Skip to main content
Every settlement is driven by a deterministic state machine defined in its template. The settlement engine is the core orchestrator that advances settlements through states by executing actions and validating transitions.

​
How it works

  1. The engine enters a state
  2. If the state has an action, it executes it
  3. Based on the action’s resolution mode, it either advances immediately or waits
  4. When the next state is reached, the cycle repeats
  5. When a terminal state is reached, the settlement is complete

​
Transition rules

The engine enforces strict transition rules:
  • Only transitions explicitly defined in the template are allowed
  • No state can be skipped
  • No client can force a state jump
  • Every transition is recorded as an event with a timestamp and trigger source

​
Action handlers

The engine delegates work to registered action handlers:
Action TypeProviderWhat It Does
compliance_checkinternalScreens all parties via LSEG World-Check and CipherOwl
await_confirmationinternalPauses until all counterparties confirm participation
register_escrowescrowRegisters the settlement on the escrow smart contract
monitor_depositsescrowWatches for on-chain deposits via webhooks
execute_escrowescrowTriggers atomic swap on the escrow contract
rollback_escrowescrowReturns deposits to original owners
lock_assetsfireblocksLocks assets via Fireblocks custody
release_assetsfireblocksReleases locked assets
initiate_paymentfireblocksInitiates fiat/stablecoin payment
finalizeinternalMarks settlement as complete
noopinternalNo-op, advances immediately

​
Concurrency safety

The engine uses database-level locking (SELECT ... FOR UPDATE) to prevent race conditions:
  • Only one engine instance processes a settlement at a time
  • Concurrent webhook deliveries and poller runs are safely serialized
  • Idempotent processing means duplicate triggers are harmless

​
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. The engine can retry on the next trigger (webhook, poller, or manual)
  4. 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.

​
Events

Every state transition produces an event record: 
{
  "id": "evt-...",
  "settlement_id": "stl-...",
  "from_state": "COMPLIANCE_CHECKING",
  "to_state": "COMPLIANCE_CLEARED",
  "triggered_by": "engine:action",
  "payload": { ... },
  "created_at": "2026-03-16T12:00:00Z"
}
Events are append-only and form the complete audit trail of a settlement’s lifecycle.