Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Every settlement is driven by a deterministic state machine defined in its template and enforced on-chain by the SettlementCoordinator contract.

​
Two zones of control

The state machine has two distinct zones:
ZoneWho drives itStates
KeyStone-controlledSettlement engine proposes transitionsINSTRUCTED through COMPLIANCE_CLEARED
Contract-autonomousContracts handle everythingAWAITING_DEPOSITS through FINALIZED
After compliance clears, KeyStone proposes one final transition past the compliance gate. From that point, the contracts are fully autonomous.

​
How it works

​
KeyStone-controlled phase

  1. INSTRUCTED - Settlement created from matched instructions. Engine auto-advances.
  2. COMPLIANCE_CHECKING - Engine runs compliance screening via LSEG and CipherOwl. Results are attested to the ComplianceRegistry on-chain.
  3. COMPLIANCE_CLEARED - Compliance gate passed. Engine proposes transition past compliance.
  4. AWAITING_DEPOSITS - This is the handoff point. KeyStone is done.

​
Contract-autonomous phase

  1. AWAITING_DEPOSITS - Parties deposit directly to escrow contracts using their deposit_secret. The escrow contract detects when all legs are deposited and notifies the coordinator (same-chain call or LayerZero message for cross-chain).
  2. EXECUTING_SWAP - The coordinator verifies the atomicity gate (allLegsDeposited == true) and calls executeSettlement with recipient addresses (revealed only at this point) to all escrow contracts.
  3. FINALIZED - Escrow contracts release deposits to recipients. Settlement complete.

​
Gate checks

The SettlementCoordinator checks conditions (gates) before allowing certain transitions:
GateWhat it checksWhen
ComplianceComplianceRegistry.areAllPartiesCleared()Before transitioning past compliance
DepositsEscrow.allLegsDeposited()Before transitioning from AWAITING_DEPOSITS to EXECUTING_SWAP
Gates are configured per-state at settlement creation time. The contract checks the relevant gate contract before accepting the transition.

​
Transition enforcement

The SettlementCoordinator enforces strict rules:
  • Only transitions explicitly defined in the template are allowed
  • No state can be skipped
  • No client can force a state jump
  • Gate conditions must be met before gated transitions
  • Every transition is recorded as an on-chain event

​
Permissionless timeout

Anyone can call timeout() on the SettlementCoordinator after the deadline. This triggers rollback on all chains without depending on KeyStone. Funds are never locked indefinitely.

​
Events

Every state transition produces an on-chain event from the SettlementCoordinator: 
StateTransition(bytes32 settlementId, uint8 fromState, uint8 toState, bytes32 evidenceHash)
These events form the complete audit trail. Any third party can independently reconstruct the full settlement history by reading events from the chain.

​
Error handling

When an action fails:
  1. The error is logged with full context
  2. The settlement remains in its current state (no partial transitions)
  3. If timeout_at is reached, the settlement transitions to TIMED_OUT
There is no implicit error recovery. Every recovery path is an explicit state transition defined in the template. See SettlementCoordinator for full contract documentation.