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.

Templates are the blueprint for how a settlement behaves. They define the state machine, required roles, required leg types, gates, and compliance configuration. Templates are global - they are owned by KeyStone, not individual platforms. All platforms share the same set of templates and settlement workflows. Templates are created and managed by KeyStone administrators. Platform users can browse available templates and reference them when submitting instructions via the API.
The contract does not know about templates. Templates are an off-chain convenience that packages the state machine rules, gates, and compliance configuration into a reusable definition. When a settlement is created on-chain, the template’s rules are extracted and stored directly on the SettlementCoordinator.

​
Template configuration

A template’s config object defines the complete workflow: 
{
  "states": ["INSTRUCTED", "COMPLIANCE_CHECKING", "COMPLIANCE_CLEARED",
             "AWAITING_DEPOSITS", "EXECUTING_SWAP", "FINALIZED",
             "ROLLED_BACK", "TIMED_OUT"],
  "initial_state": "INSTRUCTED",
  "terminal_states": ["FINALIZED"],
  "failure_states": ["ROLLED_BACK", "TIMED_OUT"],
  "transitions": {
    "INSTRUCTED": { "allowed_next": ["COMPLIANCE_CHECKING"] },
    "COMPLIANCE_CHECKING": { "allowed_next": ["COMPLIANCE_CLEARED", "ROLLED_BACK"] },
    "COMPLIANCE_CLEARED": { "allowed_next": ["AWAITING_DEPOSITS"] },
    "AWAITING_DEPOSITS": { "allowed_next": ["EXECUTING_SWAP", "ROLLED_BACK", "TIMED_OUT"] },
    "EXECUTING_SWAP": { "allowed_next": ["FINALIZED", "ROLLED_BACK"] }
  },
  "actions": {
    "COMPLIANCE_CHECKING": {
      "type": "compliance_check",
      "provider": "internal",
      "resolution": "immediate"
    },
    "COMPLIANCE_CLEARED": {
      "type": "noop",
      "provider": "internal",
      "resolution": "immediate"
    },
    "AWAITING_DEPOSITS": {
      "type": "noop",
      "provider": "internal",
      "resolution": "webhook"
    },
    "FINALIZED": {
      "type": "finalize",
      "provider": "internal",
      "resolution": "immediate"
    }
  },
  "compliance": {
    "entity_providers": ["lseg_worldcheck"],
    "wallet_providers": ["cipherowl"]
  },
  "required_roles": ["buyer", "seller"],
  "required_leg_types": ["asset", "payment"]
}

​
Key sections

​
States and transitions

  • states - All possible states in the workflow
  • initial_state - Where every settlement starts
  • terminal_states - Success end states (e.g. FINALIZED)
  • failure_states - Failure end states (e.g. ROLLED_BACK, TIMED_OUT)
  • transitions - Allowed state changes. The contract only permits transitions defined here.

​
Actions

Each state can have an action that the engine executes when entering that state:
FieldDescription
typeThe action handler to invoke (e.g. compliance_check, noop, finalize)
providerWhich provider handles it (internal)
resolutionHow the action completes: immediate, webhook, poll, or manual

​
Gates (derived from actions)

Gates are on-chain preconditions derived from the template’s action configuration. When a settlement is created on-chain, the relevant gates are stored on the SettlementCoordinator:
Template ActionDerived GateOn-Chain Check
compliance_check actionCOMPLIANCE_CLEARED gateComplianceRegistry.areAllPartiesCleared(settlementId)
Deposit-related stateALL_DEPOSITS_CONFIRMED gateEscrow.allLegsDeposited(settlementId)
The contract checks these gates before accepting a transition to the gated state.

​
Validation rules

  • required_roles - Every settlement must include parties covering all required roles
  • required_leg_types - Every settlement must include legs covering all required types

​
Slugs

Every template has a unique slug - a short, human-readable identifier (e.g. dvp-standard, repo-bond-usdc). Slugs provide a stable reference that does not change across template versions. When submitting an instruction, you reference a template by its slug. Slugs are particularly useful in integration code where hardcoding UUIDs is fragile.

​
Versioning

Templates are versioned. When you update a template, the version is auto-incremented. Existing settlements continue using the template version they were created with.

​
Different settlement types, same engine

The template system is generic by design. Different transaction types are just different templates:
Transaction TypeTemplate Differences
DvP2 legs (asset + payment), buyer/seller roles
Tokenised RepoTwo linked DvP settlements (opening + closing), maturity_at triggers closing leg with reversed parties. See Tokenised Repo.
Securities LendingSecurities + collateral + fee legs
NettingN legs across multiple counterparties
The settlement engine and contracts process all of them identically - they follow whatever the template defines.