# Cross-CBDC Rate Attestation Oracle — Operator Guide

## Overview

The Cross-CBDC Rate Attestation oracle pool enables admitted oracle operators to publish signed rate attestations for CBDC venue pairs (e.g., AED/CNY, CNY/EUR). Rate attestations carry TWAP-windowed exchange rates and are referenced by Cross-Ledger Escrows (`fx_rate_attestation_ref` field) to validate cross-CBDC principal amounts at escrow creation.

Tag: `0x54485255` (per THREAD §15a).

---

## Lifecycle

```
Operator: admit_rate_oracle (issuer_pubkey + stake + venue pairs)
                   ↓ oracle_state=0 (active)
Oracle:    publish_cross_cbdc_rate  →  broadcast_status=0 (pending)
Pub svc:   scans pending rows       →  broadcast_status=1 (broadcast_ok)  ← GossipSub
                                    →  broadcast_status=2 (broadcast_failed) ← retry
Consumer:  query_cross_cbdc_rate / list_cross_cbdc_rates (for settlement FX validation)
```

---

## Tools

### `thread.admit_rate_oracle`

Admit a new oracle operator into the Cross-CBDC Rate Attestation oracle pool.

**Required params:**

| Param | Type | Description |
|---|---|---|
| `secret_key_hex` | string | 32-byte Ed25519 seed (hex). Derives `operator_agent_id`. |
| `issuer_pubkey_hex` | string | 32-byte Ed25519 public key (hex) for signing rate attestations (`issuer_signature`). |
| `challenge_stake_micro_cosr` | number | Oracle challenge stake (µCOSR locked in oracle PDA). Must be > 0. |

**Optional params:**

| Param | Type | Description |
|---|---|---|
| `authorized_venue_pairs` | array | Array of `{from_venue_id, to_venue_id, authorized_source_types?}`. Defines which §48.10 venue pairs the oracle may publish rates for. |

**Success response:**

```json
{
  "rate_oracle_id": "1",
  "operator_agent_id_hex": "<64-char hex>",
  "issuer_pubkey_hex": "<64-char hex>",
  "challenge_stake_micro_cosr": "5000000",
  "oracle_state": 0,
  "status": "admitted"
}
```

---

### `thread.query_rate_oracle`

Fetch a single admitted oracle by `rate_oracle_id`.

**Params:** `{ "rate_oracle_id": <integer> }`

**Success response:** Full oracle record including `authorized_venue_pairs` list.

**Error:** `oracle_not_found` if ID not found.

---

### `thread.list_rate_oracles`

List admitted oracles with optional filters.

**Optional params:**

| Param | Type | Description |
|---|---|---|
| `oracle_state` | number | Filter by state: 0=active, 1=suspended, 2=retired. |
| `from_venue_id` | number | Filter to oracles authorized for this from-venue. |
| `to_venue_id` | number | Filter to oracles authorized for this to-venue. |
| `limit` | number | Max rows (default 20, max 100). |

**Success response:** `{ "oracles": [...], "total": N }`

---

### `thread.publish_cross_cbdc_rate`

Publish a new Cross-CBDC Rate Attestation. The oracle must be active and authorized for the venue pair.

**Required params:**

| Param | Type | Description |
|---|---|---|
| `secret_key_hex` | string | 32-byte Ed25519 seed (hex). Used for dev-stub `issuer_signature` if `issuer_signature_hex` is omitted. |
| `rate_oracle_id` | number | Admitted oracle's `rate_oracle_id`. |
| `from_venue_id` | number | §48.10 venue_id of the from-currency venue. |
| `to_venue_id` | number | §48.10 venue_id of the to-currency venue. |
| `cross_rate_bps` | number | Exchange rate in bps (from-units per 10000 to-units). E.g. 13612 = 1.3612 AED per CNY. |
| `twap_window_slots` | number | TWAP observation window (slots). |
| `twap_sample_count` | number | Number of price samples in the TWAP window. |
| `source_type` | number | 0=triangulated_via_usd, 1=cb_published_reference, 2=platform_published_reference, 3=multi_source_aggregated. |
| `source_attestation_refs` | array | Hex-encoded reference bytes. For `source_type=0`: 2 Price Oracle Attestation refs (X-USD + Y-USD). |
| `challenge_stake_escrow_pda_hex` | string | Hex-encoded PDA of oracle's locked challenge stake. |
| `challenge_window_expires_slot` | number | Slot at which the challenge window expires. Must be > `created_slot`. |

**Optional params:**

| Param | Type | Default | Description |
|---|---|---|---|
| `cross_rate_attestation_id_hex` | string | random | 64-char hex attestation ID. |
| `issuer_signature_hex` | string | dev stub | COSE_Sign1 bytes by oracle's `issuer_pubkey`. |
| `created_slot` | number | current slot | Slot at which the attestation was created. |

**Success response:**

```json
{
  "cross_rate_attestation_id_hex": "<64-char hex>",
  "rate_oracle_id": "1",
  "from_venue_id": "1",
  "to_venue_id": "2",
  "cross_rate_bps": "13612",
  "broadcast_status": 0
}
```

---

### `thread.query_cross_cbdc_rate`

Fetch a single rate attestation by `cross_rate_attestation_id_hex`.

**Params:** `{ "cross_rate_attestation_id_hex": "<64-char hex>" }`

**Success response:** Full attestation record (all fields).

**Error:** `cross_cbdc_rate_not_found` if ID not found.

---

### `thread.list_cross_cbdc_rates`

List rate attestations with optional filters. Results ordered by `created_slot DESC`.

**Optional params:**

| Param | Type | Description |
|---|---|---|
| `from_venue_id` | number | Filter by from-currency venue_id. |
| `to_venue_id` | number | Filter by to-currency venue_id. |
| `rate_oracle_id` | number | Filter by oracle. |
| `source_type` | number | Filter by source_type (0-3). |
| `broadcast_status` | number | Filter by broadcast_status (0=pending, 1=broadcast_ok, 2=broadcast_failed). |
| `limit` | number | Max rows (default 20, max 100). |
| `offset` | number | Pagination offset (default 0). |

**Success response:** `{ "attestations": [...], "count": N }`

---

## Oracle states

| Value | Name | Meaning |
|---|---|---|
| `0` | `active` | Oracle is admitted and may publish rate attestations. |
| `1` | `suspended` | Oracle is suspended; new publications rejected. |
| `2` | `retired` | Oracle is retired (terminal; cannot revert). |

---

## Broadcast status values

| Value | Name | Meaning |
|---|---|---|
| `0` | `pending_broadcast` | Row created; publication service has not yet run. |
| `1` | `broadcast_ok` | Successfully published to GossipSub. |
| `2` | `broadcast_failed` | Last broadcast attempt failed; service will retry. |

Publication service transitions `0 → 1` or `0 → 2` on each cycle.

---

## Source type reference

| Value | Name | Description |
|---|---|---|
| `0` | `triangulated_via_usd` | Triangulated from two X-USD and Y-USD Price Oracle Attestations. |
| `1` | `cb_published_reference` | Central bank published official reference rate. |
| `2` | `platform_published_reference` | Settlement platform published rate (e.g., mBridge). |
| `3` | `multi_source_aggregated` | Weighted average of multiple sources. |

Triangulation formula: `cross_rate_x_to_y_bps = (rate_x_to_usd_bps × 10000) / rate_y_to_usd_bps`

---

## Error catalog

| Error message | Cause |
|---|---|
| `oracle_not_found` | No oracle with the given `rate_oracle_id`. |
| `oracle_already_admitted` | Operator is already admitted in the pool (`operator_agent_id` already registered). |
| `oracle_venue_not_found` | A `from_venue_id` or `to_venue_id` in `authorized_venue_pairs` is not an active §48.10 venue. |
| `rate_attestation_oracle_not_admitted` | `rate_oracle_id` has not been admitted to the oracle pool. |
| `rate_attestation_oracle_not_active` | Oracle exists but `oracle_state != 0` (suspended or retired). |
| `oracle_not_authorized_for_venue_pair` | Oracle has no active jurisdiction row for the given (from, to) venue pair. |
| `cross_cbdc_rate_not_found` | No attestation with the given `cross_rate_attestation_id_hex`. |

---

## Typical operator flow

```bash
# 1. Admit oracle (dev stub key; no real HSM in dev)
curl -s http://127.0.0.1:9401 -d '{
  "method": "thread.admit_rate_oracle",
  "params": {
    "secret_key_hex": "<32-byte-hex>",
    "issuer_pubkey_hex": "<32-byte-hex>",
    "challenge_stake_micro_cosr": 5000000,
    "authorized_venue_pairs": [
      { "from_venue_id": 1, "to_venue_id": 2 }
    ]
  }
}'

# 2. Publish a rate attestation (triangulated AED/CNY)
curl -s http://127.0.0.1:9401 -d '{
  "method": "thread.publish_cross_cbdc_rate",
  "params": {
    "secret_key_hex": "<32-byte-hex>",
    "rate_oracle_id": 1,
    "from_venue_id": 1,
    "to_venue_id": 2,
    "cross_rate_bps": 13612,
    "twap_window_slots": 1080,
    "twap_sample_count": 12,
    "source_type": 0,
    "source_attestation_refs": ["<hex-ref-1>", "<hex-ref-2>"],
    "challenge_stake_escrow_pda_hex": "<32-byte-hex-pda>",
    "challenge_window_expires_slot": 4450021600
  }
}'

# 3. Query latest rate for the pair
curl -s http://127.0.0.1:9401 -d '{
  "method": "thread.list_cross_cbdc_rates",
  "params": { "from_venue_id": 1, "to_venue_id": 2, "limit": 1 }
}'
```

---

## Cross-region visibility

Rate oracles, their jurisdictions, and rate attestations are globally discoverable. Any region handling a Cross-Ledger Escrow can verify the FX rate attestation without a cross-region round-trip.

---

## Protocol anchors

- §15a — Cross-CBDC Rate Attestation (settlement venue / cross-ledger).
- §48.15 — oracle pool (sub-registries).
- §46.5 staleness: `CROSS_CBDC_RATE_STALENESS_MAX_SLOTS = 21,600` (~24 min).
- §15a triangulation deviation limits: 150 bps (default), 50 bps for pegged pairs.