# §48.16 Settlement Platform Sub-Registry — Operator Guide

> **Admission ceremony script:** Platform admission is **founder-authorized** (SEC-A2-11). The platform
> operator runs the N-CB witness signing ceremony via `tsx platform/scripts/admit-settlement-platform.ts
> --help`; the script reads each CB's Ed25519 key file, collects all CB witness signatures, assembles the
> §48.16 fields, and **founder-signs the §6.13a Cluster A admission envelope** (founder key from
> `~/.setix/keys/founder.sec`) before submitting `thread.admit_settlement_platform`. Use `--dry-run` to
> inspect the envelope without submitting. See ADR-2026-0129 + SEC-A2-11.

## What this is

The Settlement Platform Sub-Registry (§48.16) registers mBridge-class multi-CB consortium platforms on
the Setix network. A Settlement Platform aggregates multiple §48.10 Settlement Venues and provides
native atomic PvP (Payment-versus-Payment) guarantees for Cross-Ledger Escrows with
`atomicity_mode=1`. Once admitted, eligible BANKER agents with the `MBRIDGE_PARTICIPANT (0x8000)`
service bit can route Cross-Ledger Escrows through the platform for atomic cross-CBDC settlement.

## Tools

| Tool | Who calls it | What it does |
|---|---|---|
| `thread.admit_settlement_platform` | Platform operator (multi-CB consortium lead) | Register a new platform |
| `thread.query_settlement_platform` | Any agent | Fetch a platform by id |
| `thread.list_settlement_platforms` | Any agent | List platforms, optionally filtered |

## Admission flow

1. **Prepare participating venues.** Each Central Bank involved in the platform must already have its
   venue admitted in §48.10 (via `thread.admit_settlement_venue`). Collect the `venue_id` for each.

2. **Collect CB witness attestation refs.** Unlike §48.10's fixed P21 dual-anchor (2 refs),
   §48.16 requires **one witness attestation ref per participating Central Bank** (N refs for N CBs).
   Each ref attests the CB's identity and consent to join the platform.

3. **Collect nation_state_ref_ids.** Each participating CB maps to a `cb_nation_state_ref_id`
   (§48.21 nation-state registry reference). Provide one per CB, in the same order as the
   witness attestation refs.

4. **Call `thread.admit_settlement_platform`** with a single `founder_signed_envelope_hex`
   (SEC-A2-11). Admission is **FOUNDER-AUTHORIZED ONLY** — an active platform feeds the §13.5 PvP
   authorization chain, so it cannot be self-asserted. The envelope is a §6.13a Cluster A COSE_Sign1,
   signed by the **Setix founder key**, over a canonical CBOR map: field 1 = `created_slot`,
   field 2 = `effective_slot` (≥ `created_slot` + `EFFECTIVE_LEAD_SLOTS_MIN`), fields 3–15 = the §48.16
   record (in CDDL order):
   - 3 `platform_name` — human-readable name (e.g. `"mbridge"`, `"project-dunbar"`)
   - 4 `platform_operator_model` — 0–3 (see below)
   - 5 `platform_operator_agent_id` — 32 bytes; **read from the founder-signed payload, not derived from a caller secret**
   - 6 `participating_venue_ids` — array of §48.10 venue IDs (each admitted first)
   - 7 `cb_witness_attestation_refs` — array of CB witness refs, one per CB
   - 8 `cb_nation_state_refs` — array of nation-state ref IDs, one per CB (parallel to field 7; each unique)
   - 9 `atomicity_mechanism` — 0–3 (see below; `1=native_pvp` for mBridge)
   - 10 `platform_finality_semantics` — 0–3
   - 11 `platform_finality_confirmation_depth` — 0 if finality is instant or deterministic_at_block
   - 12 `participation_agreement_hash` — 32-byte SHA-256 of the platform participation agreement
   - 13 `participation_agreement_uri` — where the agreement lives
   - 14 `platform_settlement_attestation_pubkey` — 32-byte Ed25519 pubkey for Platform Settlement Attestations
   - 15 `platform_attestation_cadence_slots` — max slots between Platform Attestations (e.g. `216000` ≈ 24 h)

   The ceremony script (`admit-settlement-platform.ts`) builds + founder-signs this envelope for you —
   it collects the CB witness signatures and assembles fields 3–15 from your CLI flags. Rejections:
   `0x1180 VERSION_STAMP_SIGNER_INVALID` (not the founder key), `0x1181 VERSION_STAMP_LEAD_TIME_INSUFFICIENT`
   (lead too short), or a validator message (`venue_not_found`, `cb_witness_count_mismatch`, malformed field).

5. **On success**, the bridge returns `{ platform_id, platform_operator_agent_id_hex, platform_name, status: "admitted" }`.
   `admitted_slot` is the founder-declared `effective_slot`. The dual transparency-log proofs (CDDL 14–15)
   start as `null` and are populated by the platform root counter-sign ceremony.

## Operator model codes

| Code | Name | Description |
|---|---|---|
| 0 | `bis_incubated` | BIS Innovation Hub incubated (e.g. mBridge MVP) |
| 1 | `multi_cb_consortium` | Direct multi-CB consortium without BIS hub sponsorship |
| 2 | `single_cb_hosted` | Single CB hosts infrastructure for other CBs |
| 3 | `commercial_utility` | Commercial utility with CB oversight |

## Atomicity mechanism codes

| Code | Name | Description |
|---|---|---|
| 0 | `none` | No atomicity guarantee |
| 1 | `native_pvp` | mBridge-native Payment-versus-Payment (both legs atomic at platform level) |
| 2 | `htlc_bridge` | HTLC-based atomic bridge |
| 3 | `hybrid` | Hybrid (platform-level PvP + HTLC fallback) |

## Querying platforms

```
thread.query_settlement_platform  { "platform_id": 1 }
```

Returns the full platform record including `platform_state`, `participating_venues` (list of
`{ venue_id, added_slot }`), and `cb_witnesses` (list of `{ position, cb_witness_attestation_ref_hex, cb_nation_state_ref_id }`).

## Listing platforms

```
thread.list_settlement_platforms  {}                                    // all
thread.list_settlement_platforms  { "platform_state": 0 }              // active only
thread.list_settlement_platforms  { "platform_operator_model": 0 }     // BIS-incubated
```

## Platform lifecycle

| State | Value | Meaning |
|---|---|---|
| active | 0 | New `atomicity_mode=1` Cross-Ledger Escrows accepted; Platform Attestations current |
| quarantined | 1 | Platform Attestation lapsed; new escrows with `atomicity_mode=1` reject; existing complete under pre-quarantine rules |
| retired | 2 | Terminal; no new Cross-Ledger Escrows admitted |

Quarantine triggers automatically when
`platform_attestation_cadence_slots × MBRIDGE_ATTESTATION_MISS_MULTIPLIER` passes without a fresh
Platform Settlement Attestation. Retired state is irreversible.

## Error catalog

| Error substring | Cause |
|---|---|
| `platform_not_found` | No platform with that platform_id |
| `venue_not_found` | A `participating_venue_ids` entry does not exist in §48.10 settlement_venues |
| `cb_witness_count_mismatch` | `cb_witness_attestation_ref_hexes` and `cb_nation_state_ref_ids` have different lengths, or a CB nation-state ref appears more than once |
| `platform_finality_confirmation_depth` error | Depth must be 0 for instant or deterministic_at_block finality semantics |
| `SETTLEMENT_PLATFORM_UNKNOWN` | platform_id not in §48.16 (Cross-Ledger Escrow context) |
| `SETTLEMENT_PLATFORM_QUARANTINED` | Platform is quarantined; no new `atomicity_mode=1` escrows |
| `SETTLEMENT_PLATFORM_RETIRED` | Platform retired |
| `SETTLEMENT_PLATFORM_ATTESTATION_STALE` | Platform attestation past expires_slot |
| `MBRIDGE_VENUE_PAIR_NOT_PARTICIPANT` | Escrow venue pair not both members of the declared platform |

## Integration smoke (v0.2.91)

```
REGION_A_URL=http://127.0.0.1:9401 \
REGION_B_URL=http://127.0.0.1:9411 \
REGION_C_URL=http://127.0.0.1:9421 \
npx tsx scripts/smoke-platform-registry-e2e.ts
```

Exercises: admission ceremony script → query → cross-region replication → list/filter/pagination → error semantics.

## Cross-references

- §48.10 Settlement Venue Sub-Registry — each §48.16 platform member venue must be pre-admitted here
- §48.21 Nation-State Sub-Registry — `cb_nation_state_ref_ids` reference entries here (FK enforcement deferred until §48.21 is implemented)
- Cross-Ledger Escrow `atomicity_mode=1` — routes through a §48.16 platform for native PvP settlement
- Platform Settlement Attestation (c10) — the liveness signal that keeps platforms from quarantining
- §48.1 Dual Transparency Log — platform root counter-sign populates fields 14–15 after admission