> ## 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.
# Smart Contracts
> On-chain infrastructure for autonomous, trustless settlement execution.
KeyStone's smart contracts own the settlement lifecycle on-chain. After registration and compliance attestation, the contracts handle deposits, execution, timeout, and refunds autonomously - KeyStone sends no further transactions, and platforms can verify every settlement independently by reading contract events.
## Three contracts
```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1a3a35', 'primaryTextColor': '#e0f2ef', 'primaryBorderColor': '#2DD4A8', 'lineColor': '#2DD4A8', 'secondaryColor': '#162e2a', 'tertiaryColor': '#0f2420', 'clusterBkg': '#0f2420', 'clusterBorder': '#1AAF8B', 'edgeLabelBackground': '#0c1c19', 'nodeTextColor': '#e0f2ef'}}}%%
flowchart TB
subgraph "Per chain"
K[KeystoneSettlement
Escrow + fixed lifecycle:
register, deposit, execute,
abort, timeout, refunds]
CR[ComplianceRegistry
M-of-N attestation gate]
R[KeystoneRouter
Cross-chain release/abort
coordination]
end
Operator[KeyStone backend
operator role] -->|"registerSettlement / abort"| K
Oracle[Compliance oracle
M-of-N attesters] -->|"attest (signed bundle)"| CR
Parties[Depositor wallets] -->|"depositLeg / execute /
claimTimeout / claimRefund"| K
K -->|"areAllPartiesCleared"| CR
R -->|"executeFromRouter /
abortFromRouter"| K
R <-->|"LayerZero V2 messages
to routers on other chains"| R
```
| Contract | Purpose | Deployment |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| [KeystoneSettlement](/smart-contracts/keystone-settlement) | Single contract owning escrow and the fixed settlement lifecycle: registration with bound recipients, commitment-key deposits, autonomous compliance-gated execution, operator abort, depositor-claimable timeout, pull refunds | One instance per chain |
| [ComplianceRegistry](/smart-contracts/compliance-registry) | On-chain compliance attestations authorized by an immutable M-of-N attester set; the execution gate | One instance per chain |
| [KeystoneRouter](/smart-contracts/keystone-router) | Per-chain LayerZero V2 coordinator: collects funding confirmations from every chain in a cross-chain settlement and relays one release-or-abort decision to each | One instance per chain |
The earlier SettlementCoordinator + KeystoneEscrow pair is retired. The lifecycle is now fixed in contract code - no state graphs are stored on-chain, and no transition transactions exist.
## Design principles
* **No custody by KeyStone.** Funds sit in the contract under rules bound at registration. There is no KeyStone-controlled withdrawal path - even the operator can only `abort`, which unlocks pull refunds to the recorded depositors.
* **Everything binds at registration.** Recipients per leg, deposit keys, party hashes, fees, and the timeout are fixed in one `registerSettlement` call. No later transaction can change where funds go.
* **Autonomous execution.** The last deposit executes the settlement inline when the compliance gate passes - all legs pay out atomically in one transaction, or none do. If attestations land later, any depositor (or the operator) can call `execute()`.
* **Depositor-driven recovery.** `claimTimeout` (at/after the deadline) and `claimRefund` (per leg, after abort or timeout) can be called by any depositor as well as the operator, and cannot be paused. Funds are never locked indefinitely, even if KeyStone disappears - every party with funds at stake can recover them itself.
* **Privacy-preserving deposits.** Deposit authorization uses wallet-bound commitment keys (`keccak256(abi.encode(wallet, secret))`) - depositor intent stays off-chain until the deposit transaction itself.
* **Single-chain by default, cross-chain by registration mode.** A settlement registered with `abortDeadline = 0` settles both legs on one chain and executes autonomously. A non-zero `abortDeadline` opts into the cross-chain Prepared phase, where the [KeystoneRouter](/smart-contracts/keystone-router) coordinates release or abort across chains with disjoint release/timeout windows. The hosted platform currently registers every settlement single-chain.
## What lives on-chain vs off-chain
| On-chain (trustless) | Off-chain (KeyStone service layer) |
| -------------------------------------- | -------------------------------------- |
| Settlement registration | Instruction matching |
| Deposit verification (commitment keys) | Compliance screening (LSEG, CipherOwl) |
| Compliance gate at execution | Compliance attestation submission |
| Atomic swap execution + fee collection | Webhooks and notifications |
| Abort / timeout / pull refunds | Settlement record sync (event indexer) |
| All lifecycle events | Dashboards and monitoring |
## Trust model
| Question | Answer |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Can KeyStone execute without all deposits? | No - the contract requires every leg deposited |
| Can KeyStone skip compliance? | No - execution requires every bound party hash attested Pass in the ComplianceRegistry |
| Can KeyStone redirect funds? | No - recipients are bound at registration; execution and refunds follow them mechanically |
| Can KeyStone prevent timeout? | No - any depositor can claim the timeout, and the path is not pausable |
| Can a pause trap funds? | No - abort, timeout, and refunds are exempt from pause |
| Can a cross-chain settlement both pay out and refund? | No - the router release window and the timeout window are disjoint by timestamp |
| Can an auditor verify independently? | Yes - read the lifecycle events directly from the chain |
| If KeyStone goes down? | Depositors can still execute (`execute`), expire (`claimTimeout`), and refund (`claimRefund`) their settlements themselves |
Registration, commitment deposits, autonomous execution, recovery.
M-of-N on-chain compliance attestations gating execution.
Cross-chain release/abort coordination over LayerZero V2.
Deployed contract addresses.