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.
The SettlementCoordinator is the core on-chain contract. It stores settlement state machine rules, enforces valid transitions, and operates autonomously after compliance - auto-dispatching releases when all deposits are confirmed.
Functions
createSettlement()
Registers a new settlement on-chain with its state machine rules, legs with commitment hashes, and timeout. Uses the commitment scheme - no party addresses are stored at registration time.
struct LegSpec {
address token;
uint256 amount;
bytes32 depositKey; // keccak256(depositSecret)
uint8 tokenStandard; // 0=ERC-20, 1=ERC-721, 2=ERC-1400, 3=ERC-3643
FeeSpec[] fees; // Fee recipients and amounts
}
struct FeeSpec {
address recipient;
uint256 amount;
}
function createSettlement(CreateParams params) external
| Parameter | Description |
|---|
settlementId | UUID converted to bytes32 (16 bytes UUID + 16 bytes zero padding) |
initialState | Index of the initial state in the template’s states list |
transitions | Array of allowed (fromState, allowedTargets[]) rules |
gates | Array of (state, gateType) pairs defining preconditions |
partyHashes | Keccak256 hashes of party identifiers |
legs | Array of LegSpec structs with deposit keys and fee specs |
timeoutAt | Unix timestamp deadline for the settlement |
autonomous | Whether the coordinator auto-executes after all deposits |
terminalStates | Array of terminal state indices |
depositKey is the keccak256 hash of a random secret. The party who knows the secret can deposit on that leg. No addresses are registered - this preserves pre-execution privacy on public chains.
Emits: SettlementCreated(bytes32 settlementId)
transition()
Proposes a state transition. The contract validates the proposal against the registered rules and gate checks before accepting. Used by the KeyStone engine for compliance-phase transitions only.
function transition(
bytes32 settlementId,
uint8 targetState,
bytes32 evidenceHash
) external
| Parameter | Description |
|---|
settlementId | The settlement to transition |
targetState | Index of the target state |
evidenceHash | SHA-256 of "fromState:toState:triggeredBy" for audit |
- Settlement exists and is not in a terminal state
(currentState, targetState) is in the registered transitions list- If the target state has a gate, the gate condition is met
- Caller is authorized (coordinator role)
Emits: StateTransition(bytes32 settlementId, uint8 fromState, uint8 toState, bytes32 evidenceHash)
notifyDepositsComplete()
Called externally by the API (event indexer) when an AllDepositsComplete event is detected from the escrow contract, or received via LayerZero (cross-chain) when all legs for a settlement have been deposited. This triggers the coordinator to auto-advance the settlement.
The coordinator:
- Verifies
allLegsDeposited == true via the escrow contract
- Transitions from
AWAITING_DEPOSITS to EXECUTING_SWAP
- Dispatches release instructions to all escrow contracts (via LayerZero for cross-chain)
- Settlement auto-finalizes
This is the key to autonomous post-compliance execution. No KeyStone involvement is needed.
_lzReceive()
Receives cross-chain lock confirmations from escrow contracts via LayerZero. When all chains have confirmed their deposits, the coordinator auto-advances to execution and calls executeSettlement with recipient addresses to trigger releases.
timeout()
Triggers a timeout for an expired settlement. This call is permissionless - anyone can call it after the deadline. No dependency on KeyStone.
function timeout(bytes32 settlementId) external
- Settlement exists and is not in a terminal state
block.timestamp >= timeoutAt
When triggered, the coordinator dispatches rollback instructions to all escrow contracts (via LayerZero for cross-chain), returning deposits to their original owners.
Emits: SettlementTimedOut(bytes32 settlementId, uint8 fromState)
View functions
function getSettlement(bytes32 settlementId) external view returns (Settlement)
function getState(bytes32 settlementId) external view returns (uint8)
Events
| Event | When | Purpose |
|---|
SettlementCreated(bytes32 settlementId) | New settlement registered | Audit trail, indexer trigger |
StateTransition(bytes32 settlementId, uint8 fromState, uint8 toState, bytes32 evidenceHash) | Any state change | Immutable transition record |
SettlementTimedOut(bytes32 settlementId, uint8 fromState) | Timeout triggered | Audit trail, triggers rollback |
Gate types
Gates are preconditions checked before a transition is accepted:
| Gate Type | Contract Checked | Function Called |
|---|
COMPLIANCE_CLEARED | ComplianceRegistry | areAllPartiesCleared(settlementId) |
ALL_DEPOSITS_CONFIRMED | KeystoneEscrow | allLegsDeposited(settlementId) |
Access control
| Function | Who Can Call |
|---|
createSettlement() | Anyone (permissionless) |
transition() | Coordinator role only (KeyStone engine) |
notifyDepositsComplete() | Coordinator role (called by API after AllDepositsComplete event) |
_lzReceive() | LayerZero endpoint only |
timeout() | Anyone (permissionless, after deadline) |
getSettlement() / getState() | Anyone (view) |
Data conversion
| Source | Target | Method |
|---|
| UUID (16 bytes) | bytes32 | Right-pad with 16 zero bytes |
| State name (string) | uint8 | Index in template’s states list |
| Evidence | bytes32 | SHA-256 of "from_state:to_state:triggered_by" |
| Party identity | bytes32 | keccak256(abi.encode(participantId_bytes32, walletAddress)) |
