651ff4f7eb
- 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
4.0 KiB
4.0 KiB
Integration Cookbook
This document provides step-by-step guides for common integration flows.
Table of Contents
- Deploy a Token
- Place a Lien
- Submit ISO-20022 Message
- Generate and Dispatch Packet
- Bridge Lock/Unlock
Deploy a Token
REST API
POST /v1/tokens
Authorization: Bearer <token>
Idempotency-Key: <uuid>
{
"name": "USD Wrapped",
"symbol": "USDW",
"decimals": 18,
"issuer": "0x1234...",
"defaultLienMode": "ENCUMBERED",
"bridgeOnly": false
}
GraphQL
mutation {
deployToken(input: {
name: "USD Wrapped"
symbol: "USDW"
decimals: 18
issuer: "0x1234..."
defaultLienMode: ENCUMBERED
}) {
code
address
policy {
lienMode
}
}
}
Place a Lien
REST API
POST /v1/liens
Authorization: Bearer <token>
{
"debtor": "0xabcd...",
"amount": "1000000000000000000",
"priority": 1,
"reasonCode": "DEBT_ENFORCEMENT"
}
GraphQL
mutation {
placeLien(input: {
debtor: "0xabcd..."
amount: "1000000000000000000"
priority: 1
reasonCode: DEBT_ENFORCEMENT
}) {
lienId
amount
active
}
}
Submit ISO-20022 Message
Inbound (from rail adapter)
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)
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
POST /v1/packets
Authorization: Bearer <token>
Idempotency-Key: <uuid>
{
"triggerId": "abc123...",
"channel": "PDF"
}
Step 2: Dispatch Packet
POST /v1/packets/{packetId}/dispatch
Authorization: Bearer <token>
Idempotency-Key: <uuid>
{
"channel": "EMAIL",
"recipient": "recipient@example.com"
}
Step 3: Record Acknowledgement
POST /v1/packets/{packetId}/ack
Authorization: Bearer <token>
Idempotency-Key: <uuid>
{
"status": "ACCEPTED",
"ackId": "ack-123"
}
Bridge Lock/Unlock
Lock Tokens
POST /v1/bridge/lock
Authorization: Bearer <token>
{
"token": "0x1234...",
"amount": "1000000000000000000",
"targetChain": "0x0000...0001",
"targetRecipient": "0xabcd..."
}
Unlock Tokens
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
POST /v1/webhooks
Authorization: Bearer <token>
{
"url": "https://example.com/webhooks",
"events": ["triggers.created", "liens.placed"],
"secret": "webhook-secret"
}
Webhook Payload
{
"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
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)
);
}