Oracle-driven escrow · Prototype guide

Lock funds now.
Settle when the chain says so.

Virtual Cabin is a bank-style payment system where every transfer is held in a virtual sub-account ("the cabin") until a real-world event — confirmed by a blockchain oracle — releases it. Either party can dispute while funds are still locked.

Try the simulator → Read the guide
The idea

A cabin holds money in trust until reality catches up.

🔒 Funds lock instantly

When you send money, it leaves your spendable balance and enters the cabin — a virtual sub-account tied to that one transaction. The receiver can see the locked guarantee but can't yet spend it.

🛰️ Oracles trigger release

Conditional payments wait for an external trigger — a ship's status changing to arrived, or a stock price crossing a target. A blockchain oracle is the source of truth.

⚖️ Disputes are reversible

While funds are still locked, the sender can raise a dispute. Admin arbitrates: approve refunds the sender, reject releases to the receiver. Every state change is atomic and idempotent.

Who does what

Three roles. Clear responsibilities.

📤

Sender

Locks funds for someone else and decides the release condition.

  • Send money (simple or conditional)
  • View their cabin (outgoing locked funds)
  • Raise a dispute while funds are still locked
📥

Receiver

Sees inbound guarantees before the funds actually arrive.

  • View the Guarantee tab (inbound locked funds)
  • See the exact condition that will release each guarantee
  • Receives credit automatically when the condition is met
🛡️

Admin

Arbitrates disputes and operates the simple-batch settlement.

  • Settle all simple (non-conditional) locked funds at once
  • Approve disputes (refund) or reject (release to receiver)
  • Deposit funds — admin balance is infinite
Lifecycle

A transaction's four possible lives.

Every transaction starts Locked. From there it can take one of four paths depending on what happens — admin settlement, oracle release, sender dispute approved, or sender dispute rejected.

1

Send → Locked

Sender picks a receiver, amount, and (optionally) a condition. Funds debit immediately and land in the cabin with status Locked.

2

Wait

For simple sends — admin presses "Settle All" eventually. For conditional sends — a background poller queries the oracle every N seconds, recording each result in the cabin.

3

Trigger

Either: admin settles (simple), the oracle confirms (conditional), or the sender raises a dispute. First trigger wins; subsequent triggers no-op.

4

Resolve

End state is one of Settled · Refunded · Dispute rejected. Money either reaches the receiver or returns to the sender. Atomic, no in-between.

Worked examples

Three flows you'll actually encounter.

Importer pays exporter on arrival

Ananya (importer) is buying ₹50,000 worth of goods from Ravi (exporter). She doesn't want to pay until the shipment actually arrives at port. With Virtual Cabin she locks the funds tied to the ship's status — the oracle releases them automatically on arrival.

Day 0 · 09:00
Ananya sends ₹50,000 to Ravi, condition Ship42 = arrived, check every 30 min. Her balance drops by ₹50,000; Ravi's Guarantee tab shows the inbound row as Locked.
Day 0 — 14
The poller queries the oracle every 30 minutes, recording Ship42=intransit each time. No money moves. The cabin row's "last check" updates.
Day 14 · 18:42
Oracle returns Ship42=arrived ✓. Transaction flips to Settled. Ravi's balance jumps by ₹50,000. Ananya gets nothing back to receive — the deal is done.
virtualcabin.app/cabin · ananya
Cabin · Outgoing
To Ravi · 🚢 Ship42 = arrived
Every 30m · last: Ship42=intransit · next check in 18m
Locked ₹50,000
To Customs Co. · 🚢 Ship42 = arrived
Every 1h · last: Ship42=arrived ✓ · settled
Settled ₹3,200

Pay a bonus when the stock crosses a target

Priya promises her co-founder Devansh a ₹25,000 bonus once their portfolio holding crosses ₹150 per share. She locks the funds tied to AAPL > ₹150; the oracle releases them the moment the price crosses the threshold.

Mon · 10:00
Priya sends ₹25,000 to Devansh, condition AAPL > ₹150, check every 60 s. Priya's balance drops; Devansh's Guarantee shows Locked.
Mon · 10:01 — Wed · 11:42
Poller logs AAPL=132.40, AAPL=147.10, AAPL=149.99… every minute. Devansh sees the live last-check value tick up in his Guarantee tab.
Wed · 11:43
Oracle returns AAPL=150.20 ✓. Auto-settle. Devansh's balance jumps by ₹25,000 within seconds of the price crossing.
virtualcabin.app/guarantee · devansh
Guarantee · Inbound
From Priya · 📈 AAPL > ₹150
Every 60s · last: AAPL=149.99 · next check in 12s
Locked ₹25,000
From Priya · 📈 TSLA < ₹200
Every 5m · last: TSLA=212.40 · next check in 3m
Locked ₹10,000

Buyer disputes a delayed shipment

Karthik sent ₹15,000 to Meera tied to Ship07 = arrived, but it's been three weeks and the ship is still intransit. He raises a dispute. Admin reviews the evidence and approves it — the funds come back to Karthik.

Day 0 · 09:00
Karthik sends ₹15,000 conditional on Ship07 = arrived. Locked in the cabin. Poller starts checking the oracle.
Day 21 · 12:30
Karthik clicks Dispute on the cabin row. Status flips Locked → Disputed. The oracle poller stops checking this row (status filter excludes it).
Day 21 · 14:15
Admin reviews: Ship07 hasn't moved in 10 days. Clicks Approve (refund). Status flips Disputed → Refunded. Karthik's ₹15,000 is back.
Counterfactual
If admin had clicked Reject instead, status would have moved to Settled and Meera would have received the ₹15,000. Same DB writes, same atomicity — just the opposite outcome.
virtualcabin.app/admin/disputes
Open disputes 1
Karthik → Meera
🚢 Ship07 = arrived · raised 21 days after send
₹15,000
Try it yourself

Simulate a transaction.

Configure a send, choose what happens, and watch the events unfold. Time is compressed — what would take 30 seconds in the real app happens in 3 here.

Sender available
₹50,000
Receiver available
₹10,000
Locked in cabin
₹0
Status
— ready —
Configure a send on the left, then click Run simulation.
Frequently asked

Things people ask in the first ten minutes.

What is a "blockchain oracle" here?
It's a service that signs and publishes off-chain data (a ship's status, a stock's price) so that a smart contract — or, in our case, the Virtual Cabin backend — can trust the value. The Cabin polls the oracle's HTTP endpoint at a configurable interval per transaction.
How fast does a conditional payment settle once the condition is met?
At most one trigger interval. If you set trigger_seconds = 30, settlement happens within 30 seconds of the oracle returning a matching value. The minimum trigger is 5 seconds (anything tighter just hammers the oracle pointlessly).
What happens if the oracle goes down?
The poller catches the error, records the reason in the cabin row's last_check_value field (e.g. "oracle timed out"), advances the next-check timestamp, and tries again next tick. Funds stay locked. No one loses money.
Can a dispute and an oracle-driven settlement collide?
Both paths use a WHERE status = 'LOCKED' guard on the database update. Whichever lands first wins. The other one's update affects zero rows and silently no-ops. There's no scenario where the same money gets sent twice or returned and delivered.
Why does only the sender raise disputes?
The sender is the one with money at risk while funds are locked. The receiver has nothing yet — they're waiting for it. If a payment never settles (oracle never confirms, ship never arrives), the sender raises a dispute to reclaim. There's no scenario where the receiver would want to dispute their own incoming money.
Is admin's "infinite money" a security problem?
It's a prototype design choice. Admin can deposit to any account, but never debits anyone — admin's role is to backstop the system, not to move user funds around. If you wanted production-grade controls you'd add admin-action audit logs and 2FA on admin actions.
Where do real funds come from?
In this prototype, balances are just numbers in a database. To turn this into a real settlement system you'd integrate with a payment rail (UPI mandate, bank ACH hold, or an actual on-chain escrow contract) so that the "cabin lock" corresponds to real money being held.