Skip to main content
KeyStone OS uses smart contract escrow to ensure atomic settlement. Deposits are locked until all conditions are met, then executed in a single transaction. If anything fails, deposits are returned automatically.

​
How it works

​
1. Escrow registration

When a settlement reaches REGISTERING_ESCROW, the engine registers the expected deposits on the escrow smart contract. The contract knows exactly what each party should deposit.

​
2. Deposit monitoring

At AWAITING_DEPOSITS, KeyStone monitors the escrow contract for incoming deposits using two mechanisms:
MethodLatencyRole
Alchemy webhooksSub-secondPrimary detection
Fallback poller~5 minutesSafety net for missed webhooks
When a DepositReceived event is detected on-chain, KeyStone checks if ALL expected deposits are now complete. If so, the settlement advances automatically.

​
3. Atomic execution

When all deposits are confirmed, the engine calls execute() on the escrow contract. This performs the atomic swap in a single transaction:
  • Tokens move to the buyer’s wallet
  • Payment moves to the seller’s wallet
  • The settlement transitions to SETTLED

​
4. Rollback protection

If the settlement times out or fails:
  • The engine calls rollback() on the escrow contract
  • All deposits are returned to their original owners
  • No partial execution is possible

​
Deposit flow for platforms

From your platform’s perspective:
  1. You receive a webhook: settlement.state.awaiting_deposits
  2. Instruct the settlement parties to deposit to the escrow contract address
  3. KeyStone detects the deposits automatically (no API call needed from you)
  4. You receive a webhook: settlement.state.executing_swap
  5. You receive a webhook: settlement.state.finalized
The escrow contract address is included in the settlement details once registration is complete. Query the settlement to get the contract address and expected deposit amounts.

​
Monitoring deposit status

Check deposit progress by querying the settlement: 
curl https://api.keystoneos.xyz/v1/settlements/$ID \
  -H "Authorization: Bearer $TOKEN"
The response includes the current state and leg statuses showing which deposits have been received.

​
Timeout behavior

Every settlement has a timeout_at deadline. If all deposits aren’t received by this time:
  1. Settlement transitions to TIMED_OUT
  2. Escrow contract returns any received deposits
  3. All platforms are notified via webhook
This guarantees no funds are locked indefinitely, regardless of counterparty behavior.