> ## 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

> Settlement product parameter packs on top of the fixed machine.

Templates are settlement product **parameter packs**. The state machine itself is not configurable - it is fixed in code (`dvp/v1`) and pinned on every settlement at creation. A template configures policy on top of the machine: the default timeout, compliance providers, required party roles, and what the engine does in each state.

Templates are **global** - they are owned by KeyStone, not individual platforms. All platforms share the same set of templates. Templates are created and managed by KeyStone administrators; platform users browse available templates and reference them when submitting instructions via the API.

<Note>
  The contract does not know about templates. Nothing from the template is encoded on-chain - the KeystoneSettlement contract implements the chain-owned part of the machine natively, and registration carries only legs (with bound recipients and deposit keys), party hashes, and the timeout.
</Note>

## Template configuration

A template's `config` object is the full parameter pack:

```json theme={null}
{
  "machine": "dvp/v1",
  "timeout_seconds": 3600,
  "required_roles": ["seller", "buyer"],
  "compliance": {
    "entity_providers": ["lseg_worldcheck"],
    "wallet_providers": ["cipherowl"],
    "recheck_at_states": []
  },
  "actions": {
    "COMPLIANCE_CHECKING": {
      "type": "compliance_check",
      "provider": "internal",
      "resolution": "immediate",
      "timeout_seconds": 300
    }
  }
}
```

The schema is strict: state-graph keys (`states`, `transitions`, `initial_state`, ...) are rejected. States and transitions live in the machine, not the template.

## Key sections

### Machine

`machine` selects which code-fixed machine settlements created from this template run (currently `dvp/v1`). The value is pinned on the settlement as `machine_version` at creation - in-flight settlements never change machines, and breaking machine changes ship as a new version rather than mutating `dvp/v1`.

### Timeout

`timeout_seconds` is the default settlement deadline (`now + timeout_seconds`) when the caller does not pass an explicit `timeout_at`. After on-chain registration the deadline is enforced by the contract itself: deposits and execution are only accepted strictly before it, and `claimTimeout` (operator or any depositor, not pausable) takes over at and after it.

### Actions

Each machine state can have an action the engine executes when a settlement enters that state:

| Field             | Description                                                                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`            | The action handler to invoke (e.g. `compliance_check`, `noop`)                                                                                                    |
| `provider`        | Which provider handles it (any registered handler pair is valid)                                                                                                  |
| `resolution`      | How the action completes: `immediate` runs inline during the engine walk; `webhook`, `poll`, and `manual` park the settlement until an external party resolves it |
| `timeout_seconds` | Action-level policy timeout                                                                                                                                       |

Action keys must be `dvp/v1` state names. Bindings only matter on engine-owned states - the engine never acts in chain-owned or admin-owned states.

### Compliance

`compliance.entity_providers` and `compliance.wallet_providers` list the screening providers the compliance action runs (`lseg_worldcheck` for entities, `cipherowl` for wallets). Empty lists mean zero checks.

### Roles

`required_roles` drives party validation: exactly one party per role at creation, one instruction per role when matching bilaterally.

## Slugs

Every template has a unique `slug` - a short, human-readable identifier (e.g. `cross_platform_dvp`, `repo_open_tri_party`). Slugs provide a stable reference that does not change across template versions. When submitting an instruction, you reference a template by its `slug`.

## Versioning

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

## Different settlement products, same machine

Different products are different parameter packs over the same machine:

| Product                             | Template Differences                                                                                                                                                                                                    |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cross-platform DvP**              | 2 legs (asset + payment), `seller`/`buyer` roles                                                                                                                                                                        |
| **Tri-party tokenised repo (open)** | 1 collateral leg + 2 cash legs, `lender`/`borrower_1`/`borrower_2` roles                                                                                                                                                |
| **Tokenised repo lifecycle**        | Two linked settlements (opening + closing); the derived maturity (`repo_terms.tenor_days` after the opening is created) triggers the closing leg with reversed parties. See [Tokenised Repo](/concepts/tokenised-repo). |

The settlement engine and the contract process all of them identically - same states, same transitions, same ownership rules.