feat: CBDC Interoperability & Sandbox Bridge (Issue #499)

[Jokay1997]

Summary

Implements Issue #499 - Central Bank Digital Currency (CBDC) Interoperability & Sandbox Integration for the Aframp platform. Establishes secure API integrations, zero-trust network protocols, and translation layers that allow white-label tenants to swap on-chain cNGN tokens for official digital fiat assets.

Changes

1. Data Model & CBDC Network Gateway Schemas (4 migration files)

• \cbdc_gateways: permissioned node endpoints, mTLS footprints, DLT system types (Besu/Corda/Quorum), health tracking
• \cbdc_swap_records: immutable audit trail mapping Stellar tx hashes to CBDC block IDs with 2PC state, AML results, multi-sig approvals
• \cryptographic_signatory_vault: multi-sig approval states with regional data residency partitioning for sovereign compliance
• \cbdc_2pc_locks: durable 2PC lock persistence for crash recovery

2. Enterprise DLT Gateway Integration (\src/cbdc/gateway.rs)

• Async RPC client for Hyperledger Besu, Corda, Quorum, and Hyperledger Fabric
• JSON-RPC (eth_blockNumber, eth_sendRawTransaction, eth_getTransactionReceipt)
• mTLS-ready transport with configurable timeouts and retries
• Confirmation-wait loop with polling

3. HSM Signing Client (\src/cbdc/hsm.rs)

• PKCS#11 protocol client for institutional bank key signing
• Supports ECDSA-P256, ECDSA-P384, ED25519, RSA-2048, PKCS11-HSM
• Signature verification and public key retrieval

4. Two-Phase Commit (2PC) Lock Manager (\src/cbdc/two_pc.rs)

• Redis-backed distributed lock with NX/PX atomic acquire
• Full prepare → commit / rollback state machine
• Heartbeat mechanism for long-running locks
• Stale lock recovery and fail-secure \HELD_FOR_RECONCILIATION\ state

5. Cross-Rail Liquidity Bridge & Settlement (\src/cbdc/settlement.rs)

• Tokio-based background worker processing pending swaps
• Pipeline: AML validation → 2PC lock → CBDC gateway submission → confirmation wait → 2PC commit
• Distributed locking via Redis to prevent duplicate processing

6. Transaction Reversal Engine (\src/cbdc/reversal.rs)

• Auto-recovery for failed swaps and stale 2PC locks
• Configurable retry with max-attempts cap
• Multiple reversal strategies (pre-submission / CBDC / Stellar)

7. AML/Compliance Payload Validator (\src/cbdc/validator.rs)

• Amount bounds, jurisdiction restrictions, required fields
• Optional external AML screening service integration
• Compliance metadata tagging (purpose, source_of_funds)

8. Observability & Metrics (\src/cbdc/metrics.rs)

• \cbdc_rpc_latency_seconds, \cross_rail_swap_volume_total\
• \dlt_confirmation_blocks, \ wo_phase_commit_failures_total\
• \cbdc_gateway_health_status, \cbdc_hsm_operations_total\
• \ racing\ structured logging across all operations

9. REST API (\src/cbdc/handlers.rs, \src/cbdc/routes.rs)

• \POST /api/v1/cbdc/swaps\ - initiate swap
• \GET /api/v1/cbdc/swaps\ - list swaps (with status filter)
• \GET /api/v1/cbdc/swaps/{id}\ - swap status
• \GET /api/v1/cbdc/swaps/{id}/signatories\ - multi-sig signatories
• \POST /api/admin/cbdc/gateways\ - register gateway
• \GET /api/admin/cbdc/gateways\ - list gateways
• \GET /api/admin/cbdc/gateways/{id}\ - gateway details

Acceptance Criteria Met

• CBDC gateway client parses enterprise ledger logs, verifies signatures, dispatches settlement instructions
• 2PC manager fail-secure: drops to \HELD_FOR_RECONCILIATION\ on communication failure
• mTLS-ready connection routines (TLS 1.3)
• Prometheus metrics for all key operations
• Unit tests for validator, model serde, 2PC state machine

Closes #499

[drips-wave]

@Jokay1997 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits