Initial project setup: Add contracts, API definitions, tests, and documentation

- Add Foundry project configuration (foundry.toml, foundry.lock) - Add Solidity contracts (TokenFactory138, BridgeVault138, ComplianceRegistry, etc.) - Add API definitions (OpenAPI, GraphQL, gRPC, AsyncAPI) - Add comprehensive test suite (unit, integration, fuzz, invariants) - Add API services (REST, GraphQL, orchestrator, packet service) - Add documentation (ISO20022 mapping, runbooks, adapter guides) - Add development tools (RBC tool, Swagger UI, mock server) - Update OpenZeppelin submodules to v5.0.0
2025-12-12 10:59:41 -08:00
parent 26b5aaf932
commit 651ff4f7eb
281 changed files with 24813 additions and 2 deletions
--- a/docs/api/integration-cookbook.md
+++ b/docs/api/integration-cookbook.md
@@ -0,0 +1,246 @@
+# Integration Cookbook
+
+This document provides step-by-step guides for common integration flows.
+
+## Table of Contents
+
+1. [Deploy a Token](#deploy-a-token)
+2. [Place a Lien](#place-a-lien)
+3. [Submit ISO-20022 Message](#submit-iso-20022-message)
+4. [Generate and Dispatch Packet](#generate-and-dispatch-packet)
+5. [Bridge Lock/Unlock](#bridge-lockunlock)
+
+## Deploy a Token
+
+### REST API
+
+```bash
+POST /v1/tokens
+Authorization: Bearer <token>
+Idempotency-Key: <uuid>
+
+{
+  "name": "USD Wrapped",
+  "symbol": "USDW",
+  "decimals": 18,
+  "issuer": "0x1234...",
+  "defaultLienMode": "ENCUMBERED",
+  "bridgeOnly": false
+}
+```
+
+### GraphQL
+
+```graphql
+mutation {
+  deployToken(input: {
+    name: "USD Wrapped"
+    symbol: "USDW"
+    decimals: 18
+    issuer: "0x1234..."
+    defaultLienMode: ENCUMBERED
+  }) {
+    code
+    address
+    policy {
+      lienMode
+    }
+  }
+}
+```
+
+## Place a Lien
+
+### REST API
+
+```bash
+POST /v1/liens
+Authorization: Bearer <token>
+
+{
+  "debtor": "0xabcd...",
+  "amount": "1000000000000000000",
+  "priority": 1,
+  "reasonCode": "DEBT_ENFORCEMENT"
+}
+```
+
+### GraphQL
+
+```graphql
+mutation {
+  placeLien(input: {
+    debtor: "0xabcd..."
+    amount: "1000000000000000000"
+    priority: 1
+    reasonCode: DEBT_ENFORCEMENT
+  }) {
+    lienId
+    amount
+    active
+  }
+}
+```
+
+## Submit ISO-20022 Message
+
+### Inbound (from rail adapter)
+
+```bash
+POST /v1/iso/inbound
+Authorization: Bearer <token> (or mTLS)
+Idempotency-Key: <uuid>
+Content-Type: application/json
+
+{
+  "msgType": "pacs.008",
+  "instructionId": "0x1234...",
+  "payloadHash": "0xabcd...",
+  "payload": "<Document>...</Document>",
+  "rail": "FEDWIRE"
+}
+```
+
+### Outbound (from client)
+
+```bash
+POST /v1/iso/outbound
+Authorization: Bearer <token>
+Idempotency-Key: <uuid>
+
+{
+  "msgType": "pain.001",
+  "instructionId": "0x1234...",
+  "payloadHash": "0xabcd...",
+  "payload": "<Document>...</Document>",
+  "rail": "SEPA",
+  "token": "0x5678...",
+  "amount": "1000000000000000000",
+  "accountRefId": "0xdef0...",
+  "counterpartyRefId": "0x9876..."
+}
+```
+
+## Generate and Dispatch Packet
+
+### Step 1: Generate Packet
+
+```bash
+POST /v1/packets
+Authorization: Bearer <token>
+Idempotency-Key: <uuid>
+
+{
+  "triggerId": "abc123...",
+  "channel": "PDF"
+}
+```
+
+### Step 2: Dispatch Packet
+
+```bash
+POST /v1/packets/{packetId}/dispatch
+Authorization: Bearer <token>
+Idempotency-Key: <uuid>
+
+{
+  "channel": "EMAIL",
+  "recipient": "recipient@example.com"
+}
+```
+
+### Step 3: Record Acknowledgement
+
+```bash
+POST /v1/packets/{packetId}/ack
+Authorization: Bearer <token>
+Idempotency-Key: <uuid>
+
+{
+  "status": "ACCEPTED",
+  "ackId": "ack-123"
+}
+```
+
+## Bridge Lock/Unlock
+
+### Lock Tokens
+
+```bash
+POST /v1/bridge/lock
+Authorization: Bearer <token>
+
+{
+  "token": "0x1234...",
+  "amount": "1000000000000000000",
+  "targetChain": "0x0000...0001",
+  "targetRecipient": "0xabcd..."
+}
+```
+
+### Unlock Tokens
+
+```bash
+POST /v1/bridge/unlock
+Authorization: Bearer <token>
+Idempotency-Key: <uuid>
+
+{
+  "lockId": "lock-123",
+  "token": "0x1234...",
+  "to": "0xabcd...",
+  "amount": "1000000000000000000",
+  "sourceChain": "0x0000...0001",
+  "sourceTx": "0x5678...",
+  "proof": "0xdef0..."
+}
+```
+
+## Webhook Integration
+
+### Register Webhook
+
+```bash
+POST /v1/webhooks
+Authorization: Bearer <token>
+
+{
+  "url": "https://example.com/webhooks",
+  "events": ["triggers.created", "liens.placed"],
+  "secret": "webhook-secret"
+}
+```
+
+### Webhook Payload
+
+```json
+{
+  "eventId": "uuid",
+  "eventType": "triggers.created",
+  "occurredAt": "2024-01-01T00:00:00Z",
+  "payload": {
+    "triggerId": "abc123...",
+    "rail": "FEDWIRE"
+  },
+  "signatures": [{
+    "signer": "system",
+    "signature": "hmac-sha256-signature"
+  }]
+}
+```
+
+### Verify Webhook Signature
+
+```javascript
+const crypto = require('crypto');
+
+function verifyWebhook(payload, signature, secret) {
+  const hmac = crypto.createHmac('sha256', secret);
+  const expectedSignature = hmac.update(JSON.stringify(payload)).digest('hex');
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expectedSignature)
+  );
+}
+```
+