Skip to main content
Templates are the blueprint for how a settlement behaves. They define the state machine, actions, required roles, and compliance configuration. Templates are global - they are owned by KeyStone, not individual platforms. This means all platforms share the same set of templates and settlement workflows. Templates are created and managed by KeyStone administrators in the KeyStone Dashboard. Platform users can view available templates and reference them when initiating settlements via the API.

​
Template configuration

A template’s config object defines the complete workflow: 
{
  "initial_state": "INSTRUCTED",
  "terminal_states": ["FINALIZED"],
  "failure_states": ["ROLLED_BACK", "TIMED_OUT"],
  "transitions": {
    "INSTRUCTED": ["COMPLIANCE_CHECKING"],
    "COMPLIANCE_CHECKING": ["COMPLIANCE_CLEARED", "ROLLED_BACK"],
    "COMPLIANCE_CLEARED": ["REGISTERING_ESCROW"],
    "AWAITING_DEPOSITS": ["EXECUTING_SWAP", "ROLLED_BACK", "TIMED_OUT"]
  },
  "actions": {
    "INSTRUCTED": {
      "type": "compliance_check",
      "provider": "internal",
      "resolution": "immediate"
    },
    "AWAITING_DEPOSITS": {
      "type": "monitor_deposits",
      "provider": "escrow",
      "resolution": "webhook"
    }
  },
  "required_roles": ["buyer", "seller"],
  "required_leg_types": ["asset", "payment"],
  "compliance_providers": { ... },
  "payment_providers": { ... }
}

​
Key sections

​
States and transitions

  • 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 engine 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, monitor_deposits, execute_escrow)
providerWhich provider handles it (internal, escrow, fireblocks)
resolutionHow the action completes: immediate, webhook, poll, or manual

​
Resolution modes

  • immediate - Action completes synchronously. Engine advances right away.
  • webhook - Action completes when an external webhook triggers advancement (e.g. Alchemy deposit notification).
  • poll - A background worker periodically checks if the action’s condition is met.
  • manual - Requires human intervention via API call (e.g. compliance decision, counterparty confirmation).

​
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 creating a settlement, you can reference a template by its id (UUID) or 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 processes all of them identically - it follows whatever the template defines.