# CBDC settlement adapter (design)

ISO 20022 remains the **instruction layer**; token/CBDC rails provide the **settlement layer**. as4-411 does not perform settlement; it may expose routing and settlement-rail metadata so that a **settlement adapter** (outside the core directory) can choose and invoke the correct settlement channel.

---

## Model

- **Instruction layer:** ISO 20022 messages (e.g. pacs.008, pacs.009) over AS4; unchanged.
- **Settlement layer:** One of RTGS | CBDC ledger | tokenized deposit. The directory can store a **settlement rail** capability per participant or endpoint (or per routing artifact).
- **Settlement adapter:** A component (gateway-side or separate service) that receives the resolved directive plus an instruction reference, and performs or triggers settlement on the appropriate rail. It is **outside** as4-411 core.

---

## Directory extensions

- **Optional capability or metadata:** e.g. `settlement_rail` = `RTGS` | `CBDC` | `tokenized_deposit`.
- **Optional wallet/DLT endpoint:** For CBDC, the directory may store a wallet or DLT endpoint (or reference) per participant; as4-411 resolves PartyId → AS4 endpoint (unchanged) and may optionally return `settlement_rail` and `wallet_endpoint` (or equivalent) in the directive or in extended metadata for the settlement adapter to use.
- **RouteDirective extension:** See [route-directive.md](route-directive.md). Optional fields: `settlement_rail`, `wallet_endpoint` (or `settlement_endpoint`). Not required for MVP; add when CBDC/tokenized flows are in scope.

---

## Dual-track processing

```mermaid
flowchart LR
  ISO["ISO 20022 instruction"]
  AS4["AS4 transport"]
  Dir["as4-411 directory"]
  Adapter["Settlement adapter"]
  RTGS["RTGS"]
  CBDC["CBDC ledger"]
  ISO --> AS4
  Dir -->|"endpoint + settlement_rail"| Adapter
  AS4 --> Adapter
  Adapter --> RTGS
  Adapter --> CBDC
```

1. Sender resolves PartyId via as4-411 → gets AS4 endpoint and optionally settlement_rail (and wallet/DLT endpoint if stored).
2. Sender sends ISO 20022 over AS4 to receiver.
3. Receiver (or a settlement adapter) uses the instruction plus optional settlement_rail / wallet_endpoint from directory to choose: settle via RTGS or via CBDC/tokenized ledger.

---

## Settlement adapter contract (minimal)

A **settlement adapter** is a component that:

- **Input:** Resolved RouteDirective (or equivalent), instruction reference (e.g. message id, business id), and optionally payload or reference to the ISO 20022 instruction.
- **Output:** Settlement result or callback (e.g. accepted, rejected, pending). Format is out of scope of as4-411; defined by the gateway or scheme.
- **Responsibility:** Map directive + instruction to the correct rail (RTGS, CBDC, tokenized deposit) and invoke the appropriate settlement API or ledger.

as4-411 does **not** implement this interface; it only provides routing directives and, when extended, optional settlement_rail and wallet_endpoint so that an external adapter can be implemented. No full implementation of a CBDC settlement adapter is required in this add-on; a stub or placeholder may be added in packages/connectors or packages/core for tests if desired.