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

api/packages/openapi/v1/components/parameters.yaml

@@ -0,0 +1,67 @@
+components:
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: Idempotency key for ensuring request is only processed once
+      schema:
+        type: string
+        format: uuid
+    TokenCode:
+      name: code
+      in: path
+      required: true
+      description: Token code (e.g., USDW)
+      schema:
+        type: string
+        pattern: '^[A-Z0-9]{1,10}$'
+    LienId:
+      name: lienId
+      in: path
+      required: true
+      description: Lien identifier
+      schema:
+        type: string
+        pattern: '^[0-9]+$'
+    AccountRefId:
+      name: accountRefId
+      in: path
+      required: true
+      description: Hashed account reference identifier
+      schema:
+        type: string
+        pattern: '^0x[a-fA-F0-9]{64}$'
+    WalletRefId:
+      name: walletRefId
+      in: path
+      required: true
+      description: Hashed wallet reference identifier
+      schema:
+        type: string
+        pattern: '^0x[a-fA-F0-9]{64}$'
+    TriggerId:
+      name: triggerId
+      in: path
+      required: true
+      description: Trigger identifier
+      schema:
+        type: string
+        pattern: '^[a-fA-F0-9]{64}$'
+    PacketId:
+      name: packetId
+      in: path
+      required: true
+      description: Packet identifier
+      schema:
+        type: string
+        pattern: '^[a-fA-F0-9]{64}$'
+    LockId:
+      name: lockId
+      in: path
+      required: true
+      description: Bridge lock identifier
+      schema:
+        type: string
+        pattern: '^[a-fA-F0-9]{64}$'
+

api/packages/openapi/v1/components/schemas.yaml

@@ -0,0 +1,635 @@
+components:
+  schemas:
+    # Core domain models (reference JSON Schema registry)
+    Token:
+      type: object
+      required:
+        - code
+        - address
+        - name
+        - symbol
+        - decimals
+        - issuer
+      properties:
+        code:
+          type: string
+          pattern: '^[A-Z0-9]{1,10}$'
+        address:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        name:
+          type: string
+        symbol:
+          type: string
+        decimals:
+          type: integer
+          minimum: 0
+          maximum: 255
+        issuer:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        policy:
+          $ref: '#/components/schemas/TokenPolicy'
+        createdAt:
+          type: string
+          format: date-time
+    
+    TokenPolicy:
+      type: object
+      properties:
+        paused:
+          type: boolean
+        bridgeOnly:
+          type: boolean
+        bridge:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        lienMode:
+          type: string
+          enum: ["OFF", "HARD_FREEZE", "ENCUMBERED"]
+        forceTransferMode:
+          type: boolean
+        routes:
+          type: array
+          items:
+            $ref: '#/components/schemas/Rail'
+    
+    Lien:
+      type: object
+      required:
+        - lienId
+        - debtor
+        - amount
+        - active
+      properties:
+        lienId:
+          type: string
+        debtor:
+          type: string
+        amount:
+          type: string
+        expiry:
+          type: integer
+        priority:
+          type: integer
+        authority:
+          type: string
+        reasonCode:
+          $ref: '#/components/schemas/ReasonCode'
+        active:
+          type: boolean
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+    
+    ComplianceProfile:
+      type: object
+      required:
+        - refId
+        - allowed
+        - frozen
+      properties:
+        refId:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{64}$'
+        allowed:
+          type: boolean
+        frozen:
+          type: boolean
+        riskTier:
+          type: integer
+          minimum: 0
+          maximum: 255
+        jurisdictionHash:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{64}$'
+        updatedAt:
+          type: string
+          format: date-time
+    
+    Trigger:
+      type: object
+      required:
+        - triggerId
+        - rail
+        - msgType
+        - state
+        - instructionId
+      properties:
+        triggerId:
+          type: string
+        rail:
+          $ref: '#/components/schemas/Rail'
+        msgType:
+          type: string
+        state:
+          $ref: '#/components/schemas/TriggerState'
+        instructionId:
+          type: string
+        endToEndId:
+          type: string
+        payloadHash:
+          type: string
+        amount:
+          type: string
+        token:
+          type: string
+        accountRefId:
+          type: string
+        counterpartyRefId:
+          type: string
+        railTxRef:
+          type: string
+          nullable: true
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+    
+    Packet:
+      type: object
+      required:
+        - packetId
+        - payloadHash
+        - channel
+        - status
+      properties:
+        packetId:
+          type: string
+        triggerId:
+          type: string
+        instructionId:
+          type: string
+        payloadHash:
+          type: string
+        channel:
+          type: string
+          enum: ["PDF", "AS4", "EMAIL", "PORTAL"]
+        messageRef:
+          type: string
+          nullable: true
+        status:
+          type: string
+          enum: ["GENERATED", "DISPATCHED", "DELIVERED", "ACKNOWLEDGED", "FAILED"]
+        acknowledgements:
+          type: array
+          items:
+            type: object
+            properties:
+              ackId:
+                type: string
+              receivedAt:
+                type: string
+                format: date-time
+              status:
+                type: string
+                enum: ["RECEIVED", "ACCEPTED", "REJECTED"]
+        createdAt:
+          type: string
+          format: date-time
+        dispatchedAt:
+          type: string
+          format: date-time
+          nullable: true
+    
+    BridgeLock:
+      type: object
+      required:
+        - lockId
+        - token
+        - amount
+        - status
+      properties:
+        lockId:
+          type: string
+        token:
+          type: string
+        amount:
+          type: string
+        from:
+          type: string
+        targetChain:
+          type: string
+        targetRecipient:
+          type: string
+        status:
+          type: string
+          enum: ["LOCKED", "UNLOCKED", "PENDING"]
+        sourceChain:
+          type: string
+          nullable: true
+        sourceTx:
+          type: string
+          nullable: true
+        proof:
+          type: string
+          nullable: true
+        createdAt:
+          type: string
+          format: date-time
+        unlockedAt:
+          type: string
+          format: date-time
+          nullable: true
+    
+    AccountRef:
+      type: object
+      required:
+        - refId
+      properties:
+        refId:
+          type: string
+        provider:
+          type: string
+          enum: ["BANK", "FINTECH", "CUSTODIAN", "OTHER"]
+        metadata:
+          type: object
+        createdAt:
+          type: string
+          format: date-time
+    
+    WalletRef:
+      type: object
+      required:
+        - refId
+      properties:
+        refId:
+          type: string
+        provider:
+          type: string
+          enum: ["WALLETCONNECT", "FIREBLOCKS", "METAMASK", "OTHER"]
+        address:
+          type: string
+        metadata:
+          type: object
+        createdAt:
+          type: string
+          format: date-time
+    
+    # Enums
+    ReasonCode:
+      type: string
+      enum:
+        - OK
+        - PAUSED
+        - FROM_FROZEN
+        - TO_FROZEN
+        - FROM_NOT_COMPLIANT
+        - TO_NOT_COMPLIANT
+        - LIEN_BLOCK
+        - INSUFF_FREE_BAL
+        - BRIDGE_ONLY
+        - NOT_ALLOWED_ROUTE
+        - UNAUTHORIZED
+        - CONFIG_ERROR
+    
+    TriggerState:
+      type: string
+      enum:
+        - CREATED
+        - VALIDATED
+        - SUBMITTED_TO_RAIL
+        - PENDING
+        - SETTLED
+        - REJECTED
+        - CANCELLED
+        - RECALLED
+    
+    Rail:
+      type: string
+      enum:
+        - FEDWIRE
+        - SWIFT
+        - SEPA
+        - RTGS
+    
+    # Request/Response models
+    DeployTokenRequest:
+      type: object
+      required:
+        - name
+        - symbol
+        - decimals
+        - issuer
+      properties:
+        name:
+          type: string
+        symbol:
+          type: string
+          pattern: '^[A-Z0-9]{1,10}$'
+        decimals:
+          type: integer
+          minimum: 0
+          maximum: 255
+        issuer:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        defaultLienMode:
+          type: string
+          enum: ["OFF", "HARD_FREEZE", "ENCUMBERED"]
+          default: "ENCUMBERED"
+        bridgeOnly:
+          type: boolean
+          default: false
+        bridge:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+    
+    UpdatePolicyRequest:
+      type: object
+      properties:
+        paused:
+          type: boolean
+        bridgeOnly:
+          type: boolean
+        bridge:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        lienMode:
+          type: string
+          enum: ["OFF", "HARD_FREEZE", "ENCUMBERED"]
+        forceTransferMode:
+          type: boolean
+        routes:
+          type: array
+          items:
+            $ref: '#/components/schemas/Rail'
+    
+    MintRequest:
+      type: object
+      required:
+        - to
+        - amount
+      properties:
+        to:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        amount:
+          type: string
+        reasonCode:
+          $ref: '#/components/schemas/ReasonCode'
+    
+    BurnRequest:
+      type: object
+      required:
+        - from
+        - amount
+      properties:
+        from:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        amount:
+          type: string
+        reasonCode:
+          $ref: '#/components/schemas/ReasonCode'
+    
+    ClawbackRequest:
+      type: object
+      required:
+        - from
+        - to
+        - amount
+      properties:
+        from:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        to:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        amount:
+          type: string
+        reasonCode:
+          $ref: '#/components/schemas/ReasonCode'
+    
+    ForceTransferRequest:
+      type: object
+      required:
+        - from
+        - to
+        - amount
+      properties:
+        from:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        to:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        amount:
+          type: string
+        reasonCode:
+          $ref: '#/components/schemas/ReasonCode'
+    
+    PlaceLienRequest:
+      type: object
+      required:
+        - debtor
+        - amount
+      properties:
+        debtor:
+          type: string
+        amount:
+          type: string
+        expiry:
+          type: integer
+          minimum: 0
+        priority:
+          type: integer
+          minimum: 0
+          maximum: 255
+        reasonCode:
+          $ref: '#/components/schemas/ReasonCode'
+    
+    ReduceLienRequest:
+      type: object
+      required:
+        - reduceBy
+      properties:
+        reduceBy:
+          type: string
+          description: Amount to reduce by
+    
+    SetComplianceRequest:
+      type: object
+      required:
+        - allowed
+      properties:
+        allowed:
+          type: boolean
+        riskTier:
+          type: integer
+          minimum: 0
+          maximum: 255
+        jurisdictionHash:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{64}$'
+    
+    LinkAccountWalletRequest:
+      type: object
+      required:
+        - accountRefId
+        - walletRefId
+      properties:
+        accountRefId:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{64}$'
+        walletRefId:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{64}$'
+    
+    SubmitInboundMessageRequest:
+      type: object
+      required:
+        - msgType
+        - instructionId
+        - payloadHash
+        - payload
+      properties:
+        msgType:
+          type: string
+          pattern: '^[a-z]+\\.[0-9]{3}$'
+        instructionId:
+          type: string
+        endToEndId:
+          type: string
+        payloadHash:
+          type: string
+        payload:
+          type: string
+          description: ISO-20022 XML payload
+        rail:
+          $ref: '#/components/schemas/Rail'
+    
+    SubmitOutboundMessageRequest:
+      type: object
+      required:
+        - msgType
+        - instructionId
+        - payloadHash
+        - payload
+        - token
+        - amount
+        - accountRefId
+        - counterpartyRefId
+      properties:
+        msgType:
+          type: string
+          pattern: '^[a-z]+\\.[0-9]{3}$'
+        instructionId:
+          type: string
+        endToEndId:
+          type: string
+        payloadHash:
+          type: string
+        payload:
+          type: string
+          description: ISO-20022 XML payload
+        rail:
+          $ref: '#/components/schemas/Rail'
+        token:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        amount:
+          type: string
+        accountRefId:
+          type: string
+        counterpartyRefId:
+          type: string
+    
+    GeneratePacketRequest:
+      type: object
+      required:
+        - triggerId
+        - channel
+      properties:
+        triggerId:
+          type: string
+        channel:
+          type: string
+          enum: ["PDF", "AS4", "EMAIL", "PORTAL"]
+        options:
+          type: object
+          description: Channel-specific options
+    
+    BridgeLockRequest:
+      type: object
+      required:
+        - token
+        - amount
+        - targetChain
+        - targetRecipient
+      properties:
+        token:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        amount:
+          type: string
+        targetChain:
+          type: string
+        targetRecipient:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+    
+    BridgeUnlockRequest:
+      type: object
+      required:
+        - lockId
+        - token
+        - to
+        - amount
+        - sourceChain
+        - sourceTx
+        - proof
+      properties:
+        lockId:
+          type: string
+        token:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        to:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{40}$'
+        amount:
+          type: string
+        sourceChain:
+          type: string
+        sourceTx:
+          type: string
+        proof:
+          type: string
+          description: Light client proof
+    
+    TransactionResponse:
+      type: object
+      properties:
+        txHash:
+          type: string
+          pattern: '^0x[a-fA-F0-9]{64}$'
+        status:
+          type: string
+          enum: ["PENDING", "SUCCESS", "FAILED"]
+        blockNumber:
+          type: integer
+          nullable: true
+    
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+        reasonCode:
+          $ref: '#/components/schemas/ReasonCode'
+        details:
+          type: object
+        requestId:
+          type: string
+

api/packages/openapi/v1/examples/tokens.yaml

@@ -0,0 +1,12 @@
+components:
+  examples:
+    DeployUSDW:
+      summary: Deploy USDW token
+      value:
+        name: "USD Wrapped"
+        symbol: "USDW"
+        decimals: 18
+        issuer: "0x1234567890123456789012345678901234567890"
+        defaultLienMode: "ENCUMBERED"
+        bridgeOnly: false
+

api/packages/openapi/v1/openapi.yaml

@@ -0,0 +1,290 @@
+openapi: 3.1.0
+info:
+  title: eMoney Token Factory API
+  version: 1.0.0
+  description: |
+    Comprehensive API for ChainID 138 eMoney Token Factory system.
+    
+    Features:
+    - Token deployment and management
+    - Lien enforcement (hard freeze and encumbered modes)
+    - Compliance registry
+    - Account ↔ Wallet mapping
+    - ISO-20022 message routing
+    - Payment rail triggers
+    - Packet generation and dispatch
+    - Bridge operations
+    
+  contact:
+    name: API Support
+  license:
+    name: MIT
+
+servers:
+  - url: https://api.emoney.example.com/v1
+    description: Production server
+  - url: https://api-staging.emoney.example.com/v1
+    description: Staging server
+  - url: http://localhost:3000/v1
+    description: Local development server
+
+tags:
+  - name: Tokens
+    description: Token deployment and policy management
+  - name: Liens
+    description: Lien (encumbrance) management
+  - name: Compliance
+    description: Compliance registry operations
+  - name: Mappings
+    description: Account ↔ Wallet mapping
+  - name: Triggers
+    description: Payment rail trigger management
+  - name: ISO
+    description: ISO-20022 message submission
+  - name: Packets
+    description: Non-scheme integration packets
+  - name: Bridge
+    description: Bridge lock/unlock operations
+
+paths:
+  /tokens:
+    $ref: './paths/tokens.yaml#/paths/~1tokens'
+  /tokens/{code}:
+    $ref: './paths/tokens.yaml#/paths/~1tokens~1{code}'
+  /tokens/{code}/policy:
+    $ref: './paths/tokens.yaml#/paths/~1tokens~1{code}~1policy'
+  /tokens/{code}/mint:
+    $ref: './paths/tokens.yaml#/paths/~1tokens~1{code}~1mint'
+  /tokens/{code}/burn:
+    $ref: './paths/tokens.yaml#/paths/~1tokens~1{code}~1burn'
+  /tokens/{code}/clawback:
+    $ref: './paths/tokens.yaml#/paths/~1tokens~1{code}~1clawback'
+  /tokens/{code}/force-transfer:
+    $ref: './paths/tokens.yaml#/paths/~1tokens~1{code}~1force-transfer'
+  /liens:
+    $ref: './paths/liens.yaml#/paths/~1liens'
+  /liens/{lienId}:
+    $ref: './paths/liens.yaml#/paths/~1liens~1{lienId}'
+  /accounts/{accountRefId}/liens:
+    $ref: './paths/liens.yaml#/paths/~1accounts~1{accountRefId}~1liens'
+  /accounts/{accountRefId}/encumbrance:
+    $ref: './paths/liens.yaml#/paths/~1accounts~1{accountRefId}~1encumbrance'
+  /compliance/accounts/{accountRefId}:
+    $ref: './paths/compliance.yaml#/paths/~1compliance~1accounts~1{accountRefId}'
+  /compliance/wallets/{walletRefId}:
+    $ref: './paths/compliance.yaml#/paths/~1compliance~1wallets~1{walletRefId}'
+  /compliance/{refId}/freeze:
+    $ref: './paths/compliance.yaml#/paths/~1compliance~1{refId}~1freeze'
+  /compliance/{refId}:
+    $ref: './paths/compliance.yaml#/paths/~1compliance~1{refId}'
+  /mappings/account-wallet/link:
+    $ref: './paths/mappings.yaml#/paths/~1mappings~1account-wallet~1link'
+  /mappings/account-wallet/unlink:
+    $ref: './paths/mappings.yaml#/paths/~1mappings~1account-wallet~1unlink'
+  /mappings/accounts/{accountRefId}/wallets:
+    $ref: './paths/mappings.yaml#/paths/~1mappings~1accounts~1{accountRefId}~1wallets'
+  /mappings/wallets/{walletRefId}/accounts:
+    $ref: './paths/mappings.yaml#/paths/~1mappings~1wallets~1{walletRefId}~1accounts'
+  /triggers:
+    $ref: './paths/triggers.yaml#/paths/~1triggers'
+  /triggers/{triggerId}:
+    $ref: './paths/triggers.yaml#/paths/~1triggers~1{triggerId}'
+  /triggers/{triggerId}/validate-and-lock:
+    $ref: './paths/triggers.yaml#/paths/~1triggers~1{triggerId}~1validate-and-lock'
+  /triggers/{triggerId}/mark-submitted:
+    $ref: './paths/triggers.yaml#/paths/~1triggers~1{triggerId}~1mark-submitted'
+  /triggers/{triggerId}/confirm-settled:
+    $ref: './paths/triggers.yaml#/paths/~1triggers~1{triggerId}~1confirm-settled'
+  /triggers/{triggerId}/confirm-rejected:
+    $ref: './paths/triggers.yaml#/paths/~1triggers~1{triggerId}~1confirm-rejected'
+  /iso/inbound:
+    $ref: './paths/iso.yaml#/paths/~1iso~1inbound'
+  /iso/outbound:
+    $ref: './paths/iso.yaml#/paths/~1iso~1outbound'
+  /packets:
+    $ref: './paths/packets.yaml#/paths/~1packets'
+  /packets/{packetId}:
+    $ref: './paths/packets.yaml#/paths/~1packets~1{packetId}'
+  /packets/{packetId}/download:
+    $ref: './paths/packets.yaml#/paths/~1packets~1{packetId}~1download'
+  /packets/{packetId}/dispatch:
+    $ref: './paths/packets.yaml#/paths/~1packets~1{packetId}~1dispatch'
+  /packets/{packetId}/ack:
+    $ref: './paths/packets.yaml#/paths/~1packets~1{packetId}~1ack'
+  /bridge/lock:
+    $ref: './paths/bridge.yaml#/paths/~1bridge~1lock'
+  /bridge/unlock:
+    $ref: './paths/bridge.yaml#/paths/~1bridge~1unlock'
+  /bridge/locks/{lockId}:
+    $ref: './paths/bridge.yaml#/paths/~1bridge~1locks~1{lockId}'
+  /bridge/corridors:
+    $ref: './paths/bridge.yaml#/paths/~1bridge~1corridors'
+
+components:
+  securitySchemes:
+    oauth2:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: /oauth/token
+          scopes:
+            tokens:read: Read token information
+            tokens:write: Deploy and manage tokens
+            liens:read: Read lien information
+            liens:write: Manage liens
+            compliance:read: Read compliance information
+            compliance:write: Manage compliance
+            mappings:read: Read account-wallet mappings
+            mappings:write: Manage mappings
+            triggers:read: Read trigger information
+            triggers:write: Manage triggers
+            packets:read: Read packet information
+            packets:write: Manage packets
+            bridge:read: Read bridge information
+            bridge:write: Manage bridge operations
+    mtls:
+      type: mutualTLS
+      description: Mutual TLS authentication for high-trust adapters
+    apiKey:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key for internal services (optional)
+  
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: Idempotency key for ensuring request is only processed once
+      schema:
+        type: string
+        format: uuid
+    TokenCode:
+      name: code
+      in: path
+      required: true
+      description: Token code (e.g., USDW)
+      schema:
+        type: string
+        pattern: '^[A-Z0-9]{1,10}$'
+    LienId:
+      name: lienId
+      in: path
+      required: true
+      description: Lien identifier
+      schema:
+        type: string
+        pattern: '^[0-9]+$'
+    AccountRefId:
+      name: accountRefId
+      in: path
+      required: true
+      description: Hashed account reference identifier
+      schema:
+        type: string
+        pattern: '^0x[a-fA-F0-9]{64}$'
+    WalletRefId:
+      name: walletRefId
+      in: path
+      required: true
+      description: Hashed wallet reference identifier
+      schema:
+        type: string
+        pattern: '^0x[a-fA-F0-9]{64}$'
+    TriggerId:
+      name: triggerId
+      in: path
+      required: true
+      description: Trigger identifier
+      schema:
+        type: string
+        pattern: '^[a-fA-F0-9]{64}$'
+    PacketId:
+      name: packetId
+      in: path
+      required: true
+      description: Packet identifier
+      schema:
+        type: string
+        pattern: '^[a-fA-F0-9]{64}$'
+    LockId:
+      name: lockId
+      in: path
+      required: true
+      description: Bridge lock identifier
+      schema:
+        type: string
+        pattern: '^[a-fA-F0-9]{64}$'
+  
+  schemas:
+    $ref: './components/schemas.yaml'
+  
+  responses:
+    BadRequest:
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            $ref: './components/schemas.yaml#/components/schemas/Error'
+    Unauthorized:
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: './components/schemas.yaml#/components/schemas/Error'
+    Forbidden:
+      description: Forbidden - insufficient permissions
+      content:
+        application/json:
+          schema:
+            $ref: './components/schemas.yaml#/components/schemas/Error'
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: './components/schemas.yaml#/components/schemas/Error'
+    Conflict:
+      description: Conflict - resource already exists or state conflict
+      content:
+        application/json:
+          schema:
+            $ref: './components/schemas.yaml#/components/schemas/Error'
+    UnprocessableEntity:
+      description: Unprocessable entity - validation error
+      content:
+        application/json:
+          schema:
+            $ref: './components/schemas.yaml#/components/schemas/Error'
+    InternalServerError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: './components/schemas.yaml#/components/schemas/Error'
+
+security:
+  - oauth2: []
+
+x-roles:
+  ISSUER: "Token issuer operations"
+  ENFORCEMENT: "Enforcement operations (clawback, force transfer)"
+  DEBT_AUTHORITY: "Lien management"
+  COMPLIANCE: "Compliance registry management"
+  POLICY_OPERATOR: "Policy configuration"
+  BRIDGE_OPERATOR: "Bridge operations"
+
+x-idempotency:
+  - POST /tokens
+  - POST /tokens/{code}/mint
+  - POST /tokens/{code}/burn
+  - POST /iso/inbound
+  - POST /iso/outbound
+  - POST /triggers/{triggerId}/confirm-settled
+  - POST /triggers/{triggerId}/confirm-rejected
+  - POST /packets
+  - POST /packets/{packetId}/dispatch
+  - POST /packets/{packetId}/ack
+  - POST /bridge/unlock
+

api/packages/openapi/v1/paths/bridge.yaml

@@ -0,0 +1,113 @@
+paths:
+  /bridge/lock:
+    post:
+      summary: Lock tokens for bridge
+      description: Lock tokens in bridge vault for cross-chain transfer
+      operationId: bridgeLock
+      tags:
+        - Bridge
+      security:
+        - oauth2:
+            - bridge:write
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/BridgeLockRequest'
+      responses:
+        '201':
+          description: Tokens locked
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/BridgeLock'
+        '400':
+          $ref: '../openapi.yaml#/components/responses/BadRequest'
+
+  /bridge/unlock:
+    post:
+      summary: Unlock tokens from bridge
+      description: Unlock tokens from bridge vault (requires proof)
+      operationId: bridgeUnlock
+      tags:
+        - Bridge
+      security:
+        - oauth2:
+            - bridge:write
+      x-roles:
+        - BRIDGE_OPERATOR
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/BridgeUnlockRequest'
+      responses:
+        '200':
+          description: Tokens unlocked
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/BridgeLock'
+        '400':
+          $ref: '../openapi.yaml#/components/responses/BadRequest'
+
+  /bridge/locks/{lockId}:
+    get:
+      summary: Get bridge lock status
+      description: Get bridge lock status by ID
+      operationId: getBridgeLock
+      tags:
+        - Bridge
+      security:
+        - oauth2:
+            - bridge:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/LockId'
+      responses:
+        '200':
+          description: Bridge lock details
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/BridgeLock'
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+
+  /bridge/corridors:
+    get:
+      summary: Get supported corridors
+      description: Get list of supported bridge corridors and verification modes
+      operationId: getBridgeCorridors
+      tags:
+        - Bridge
+      security:
+        - oauth2:
+            - bridge:read
+      responses:
+        '200':
+          description: Supported corridors
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  corridors:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        targetChain:
+                          type: string
+                        chainId:
+                          type: string
+                        verificationMode:
+                          type: string
+                          enum: ["LIGHT_CLIENT", "MULTISIG", "ORACLE"]
+                        enabled:
+                          type: boolean
+

api/packages/openapi/v1/paths/compliance.yaml

@@ -0,0 +1,167 @@
+paths:
+  /compliance/accounts/{accountRefId}:
+    put:
+      summary: Set account compliance
+      description: Set compliance status for an account
+      operationId: setAccountCompliance
+      tags:
+        - Compliance
+      security:
+        - oauth2:
+            - compliance:write
+      x-roles:
+        - COMPLIANCE
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/AccountRefId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/SetComplianceRequest'
+      responses:
+        '200':
+          description: Compliance updated
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/ComplianceProfile'
+    
+    get:
+      summary: Get account compliance
+      description: Get compliance profile for an account
+      operationId: getAccountCompliance
+      tags:
+        - Compliance
+      security:
+        - oauth2:
+            - compliance:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/AccountRefId'
+      responses:
+        '200':
+          description: Compliance profile
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/ComplianceProfile'
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+
+  /compliance/wallets/{walletRefId}:
+    put:
+      summary: Set wallet compliance
+      description: Set compliance status for a wallet
+      operationId: setWalletCompliance
+      tags:
+        - Compliance
+      security:
+        - oauth2:
+            - compliance:write
+      x-roles:
+        - COMPLIANCE
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/WalletRefId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/SetComplianceRequest'
+      responses:
+        '200':
+          description: Compliance updated
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/ComplianceProfile'
+    
+    get:
+      summary: Get wallet compliance
+      description: Get compliance profile for a wallet
+      operationId: getWalletCompliance
+      tags:
+        - Compliance
+      security:
+        - oauth2:
+            - compliance:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/WalletRefId'
+      responses:
+        '200':
+          description: Compliance profile
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/ComplianceProfile'
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+
+  /compliance/{refId}/freeze:
+    put:
+      summary: Freeze or unfreeze
+      description: Freeze or unfreeze an account or wallet
+      operationId: setFreeze
+      tags:
+        - Compliance
+      security:
+        - oauth2:
+            - compliance:write
+      x-roles:
+        - COMPLIANCE
+      parameters:
+        - name: refId
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: '^0x[a-fA-F0-9]{64}$'
+          description: Account or wallet reference identifier
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - frozen
+              properties:
+                frozen:
+                  type: boolean
+                  description: true to freeze, false to unfreeze
+      responses:
+        '200':
+          description: Freeze status updated
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/ComplianceProfile'
+
+  /compliance/{refId}:
+    get:
+      summary: Get compliance profile
+      description: Get compliance profile by reference ID (account or wallet)
+      operationId: getCompliance
+      tags:
+        - Compliance
+      security:
+        - oauth2:
+            - compliance:read
+      parameters:
+        - name: refId
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: '^0x[a-fA-F0-9]{64}$'
+          description: Account or wallet reference identifier
+      responses:
+        '200':
+          description: Compliance profile
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/ComplianceProfile'
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+

api/packages/openapi/v1/paths/iso.yaml

@@ -0,0 +1,74 @@
+paths:
+  /iso/inbound:
+    post:
+      summary: Submit inbound ISO-20022 message
+      description: Submit an inbound ISO-20022 message (from rail adapter)
+      operationId: submitInboundMessage
+      tags:
+        - ISO
+      security:
+        - mtls: []
+        - oauth2:
+            - triggers:write
+      x-roles:
+        - POLICY_OPERATOR
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/SubmitInboundMessageRequest'
+          application/xml:
+            schema:
+              type: string
+              description: ISO-20022 XML payload
+      responses:
+        '201':
+          description: Message submitted and trigger created
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
+        '400':
+          $ref: '../openapi.yaml#/components/responses/BadRequest'
+        '409':
+          $ref: '../openapi.yaml#/components/responses/Conflict'
+
+  /iso/outbound:
+    post:
+      summary: Submit outbound ISO-20022 message
+      description: Submit an outbound ISO-20022 message (from ops/client)
+      operationId: submitOutboundMessage
+      tags:
+        - ISO
+      security:
+        - oauth2:
+            - triggers:write
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/SubmitOutboundMessageRequest'
+          application/xml:
+            schema:
+              type: string
+              description: ISO-20022 XML payload
+      responses:
+        '201':
+          description: Message submitted and trigger created
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
+        '400':
+          $ref: '../openapi.yaml#/components/responses/BadRequest'
+        '409':
+          $ref: '../openapi.yaml#/components/responses/Conflict'
+

api/packages/openapi/v1/paths/liens.yaml

@@ -0,0 +1,238 @@
+paths:
+  /liens:
+    post:
+      summary: Place a lien
+      description: Place a lien (encumbrance) on an account
+      operationId: placeLien
+      tags:
+        - Liens
+      security:
+        - oauth2:
+            - liens:write
+      x-roles:
+        - DEBT_AUTHORITY
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/PlaceLienRequest'
+      responses:
+        '201':
+          description: Lien placed successfully
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Lien'
+        '400':
+          $ref: '../openapi.yaml#/components/responses/BadRequest'
+        '403':
+          $ref: '../openapi.yaml#/components/responses/Forbidden'
+    
+    get:
+      summary: List liens
+      description: List liens with optional filtering
+      operationId: listLiens
+      tags:
+        - Liens
+      security:
+        - oauth2:
+            - liens:read
+      parameters:
+        - name: debtor
+          in: query
+          schema:
+            type: string
+            pattern: '^(0x[a-fA-F0-9]{40}|0x[a-fA-F0-9]{64})$'
+          description: Filter by debtor address or account reference
+        - name: active
+          in: query
+          schema:
+            type: boolean
+          description: Filter by active status
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        '200':
+          description: List of liens
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '../components/schemas.yaml#/components/schemas/Lien'
+                  total:
+                    type: integer
+                  limit:
+                    type: integer
+                  offset:
+                    type: integer
+
+  /liens/{lienId}:
+    get:
+      summary: Get lien
+      description: Get lien details by ID
+      operationId: getLien
+      tags:
+        - Liens
+      security:
+        - oauth2:
+            - liens:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/LienId'
+      responses:
+        '200':
+          description: Lien details
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Lien'
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+    
+    patch:
+      summary: Reduce lien
+      description: Reduce lien amount
+      operationId: reduceLien
+      tags:
+        - Liens
+      security:
+        - oauth2:
+            - liens:write
+      x-roles:
+        - DEBT_AUTHORITY
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/LienId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/ReduceLienRequest'
+      responses:
+        '200':
+          description: Lien reduced
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Lien'
+    
+    delete:
+      summary: Release lien
+      description: Release (remove) a lien
+      operationId: releaseLien
+      tags:
+        - Liens
+      security:
+        - oauth2:
+            - liens:write
+      x-roles:
+        - DEBT_AUTHORITY
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/LienId'
+      responses:
+        '200':
+          description: Lien released
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  lienId:
+                    type: string
+                  released:
+                    type: boolean
+
+  /accounts/{accountRefId}/liens:
+    get:
+      summary: List liens for account
+      description: Get all liens for a specific account
+      operationId: getAccountLiens
+      tags:
+        - Liens
+      security:
+        - oauth2:
+            - liens:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/AccountRefId'
+        - name: active
+          in: query
+          schema:
+            type: boolean
+          description: Filter by active status
+      responses:
+        '200':
+          description: List of liens
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accountRefId:
+                    type: string
+                  liens:
+                    type: array
+                    items:
+                      $ref: '../components/schemas.yaml#/components/schemas/Lien'
+                  activeEncumbrance:
+                    type: string
+                    description: Total active encumbrance amount
+
+  /accounts/{accountRefId}/encumbrance:
+    get:
+      summary: Get encumbrance summary
+      description: Get active encumbrance and free balance for an account by token
+      operationId: getEncumbrance
+      tags:
+        - Liens
+      security:
+        - oauth2:
+            - liens:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/AccountRefId'
+        - name: token
+          in: query
+          schema:
+            type: string
+            pattern: '^0x[a-fA-F0-9]{40}$'
+          description: Token address (optional, returns for all tokens if omitted)
+      responses:
+        '200':
+          description: Encumbrance summary
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accountRefId:
+                    type: string
+                  encumbrances:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        token:
+                          type: string
+                        tokenCode:
+                          type: string
+                        balance:
+                          type: string
+                        activeEncumbrance:
+                          type: string
+                        freeBalance:
+                          type: string
+

api/packages/openapi/v1/paths/mappings.yaml

@@ -0,0 +1,130 @@
+paths:
+  /mappings/account-wallet/link:
+    post:
+      summary: Link account to wallet
+      description: Create a mapping between an account reference and a wallet reference
+      operationId: linkAccountWallet
+      tags:
+        - Mappings
+      security:
+        - oauth2:
+            - mappings:write
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/LinkAccountWalletRequest'
+      responses:
+        '201':
+          description: Mapping created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accountRefId:
+                    type: string
+                  walletRefId:
+                    type: string
+                  linked:
+                    type: boolean
+                  createdAt:
+                    type: string
+                    format: date-time
+
+  /mappings/account-wallet/unlink:
+    post:
+      summary: Unlink account from wallet
+      description: Remove a mapping between an account reference and a wallet reference
+      operationId: unlinkAccountWallet
+      tags:
+        - Mappings
+      security:
+        - oauth2:
+            - mappings:write
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - accountRefId
+                - walletRefId
+              properties:
+                accountRefId:
+                  type: string
+                  pattern: '^0x[a-fA-F0-9]{64}$'
+                walletRefId:
+                  type: string
+                  pattern: '^0x[a-fA-F0-9]{64}$'
+      responses:
+        '200':
+          description: Mapping removed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accountRefId:
+                    type: string
+                  walletRefId:
+                    type: string
+                  unlinked:
+                    type: boolean
+
+  /mappings/accounts/{accountRefId}/wallets:
+    get:
+      summary: Get wallets for account
+      description: Get all wallet references linked to an account reference
+      operationId: getAccountWallets
+      tags:
+        - Mappings
+      security:
+        - oauth2:
+            - mappings:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/AccountRefId'
+      responses:
+        '200':
+          description: List of wallet references
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accountRefId:
+                    type: string
+                  wallets:
+                    type: array
+                    items:
+                      $ref: '../components/schemas.yaml#/components/schemas/WalletRef'
+
+  /mappings/wallets/{walletRefId}/accounts:
+    get:
+      summary: Get accounts for wallet
+      description: Get all account references linked to a wallet reference
+      operationId: getWalletAccounts
+      tags:
+        - Mappings
+      security:
+        - oauth2:
+            - mappings:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/WalletRefId'
+      responses:
+        '200':
+          description: List of account references
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  walletRefId:
+                    type: string
+                  accounts:
+                    type: array
+                    items:
+                      $ref: '../components/schemas.yaml#/components/schemas/AccountRef'
+

api/packages/openapi/v1/paths/packets.yaml

@@ -0,0 +1,206 @@
+paths:
+  /packets:
+    post:
+      summary: Generate packet
+      description: Generate a non-scheme integration packet (PDF + sidecars)
+      operationId: generatePacket
+      tags:
+        - Packets
+      security:
+        - oauth2:
+            - packets:write
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/GeneratePacketRequest'
+      responses:
+        '201':
+          description: Packet generated
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Packet'
+    
+    get:
+      summary: List packets
+      description: List packets with optional filtering
+      operationId: listPackets
+      tags:
+        - Packets
+      security:
+        - oauth2:
+            - packets:read
+      parameters:
+        - name: triggerId
+          in: query
+          schema:
+            type: string
+            pattern: '^[a-fA-F0-9]{64}$'
+          description: Filter by trigger ID
+        - name: instructionId
+          in: query
+          schema:
+            type: string
+            pattern: '^[a-fA-F0-9]{64}$'
+          description: Filter by instruction ID
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: ["GENERATED", "DISPATCHED", "DELIVERED", "ACKNOWLEDGED", "FAILED"]
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        '200':
+          description: List of packets
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '../components/schemas.yaml#/components/schemas/Packet'
+                  total:
+                    type: integer
+                  limit:
+                    type: integer
+                  offset:
+                    type: integer
+
+  /packets/{packetId}:
+    get:
+      summary: Get packet
+      description: Get packet metadata and hashes
+      operationId: getPacket
+      tags:
+        - Packets
+      security:
+        - oauth2:
+            - packets:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/PacketId'
+      responses:
+        '200':
+          description: Packet metadata
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Packet'
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+
+  /packets/{packetId}/download:
+    get:
+      summary: Download packet
+      description: Download packet file (PDF, etc.) - auth controlled
+      operationId: downloadPacket
+      tags:
+        - Packets
+      security:
+        - oauth2:
+            - packets:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/PacketId'
+      responses:
+        '200':
+          description: Packet file
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+
+  /packets/{packetId}/dispatch:
+    post:
+      summary: Dispatch packet
+      description: Dispatch packet via email/AS4/portal
+      operationId: dispatchPacket
+      tags:
+        - Packets
+      security:
+        - oauth2:
+            - packets:write
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/PacketId'
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - channel
+              properties:
+                channel:
+                  type: string
+                  enum: ["EMAIL", "AS4", "PORTAL"]
+                recipient:
+                  type: string
+                  description: Recipient address/identifier
+      responses:
+        '200':
+          description: Packet dispatched
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Packet'
+
+  /packets/{packetId}/ack:
+    post:
+      summary: Record packet acknowledgement
+      description: Record an acknowledgement/receipt for a packet
+      operationId: acknowledgePacket
+      tags:
+        - Packets
+      security:
+        - oauth2:
+            - packets:write
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/PacketId'
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - status
+              properties:
+                status:
+                  type: string
+                  enum: ["RECEIVED", "ACCEPTED", "REJECTED"]
+                ackId:
+                  type: string
+                  description: Acknowledgement identifier
+      responses:
+        '200':
+          description: Acknowledgement recorded
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Packet'
+

api/packages/openapi/v1/paths/tokens.yaml

@@ -0,0 +1,266 @@
+paths:
+  /tokens:
+    post:
+      summary: Deploy a new token
+      description: Deploy a new eMoney token on ChainID 138
+      operationId: deployToken
+      tags:
+        - Tokens
+      security:
+        - oauth2:
+            - tokens:write
+      x-roles:
+        - TOKEN_DEPLOYER
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/DeployTokenRequest'
+            examples:
+              usdw:
+                $ref: '../examples/tokens.yaml#/components/examples/DeployUSDW'
+      responses:
+        '201':
+          description: Token deployed successfully
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Token'
+        '400':
+          $ref: '../openapi.yaml#/components/responses/BadRequest'
+        '401':
+          $ref: '../openapi.yaml#/components/responses/Unauthorized'
+        '403':
+          $ref: '../openapi.yaml#/components/responses/Forbidden'
+        '409':
+          $ref: '../openapi.yaml#/components/responses/Conflict'
+    
+    get:
+      summary: List tokens
+      description: List all deployed tokens with optional filtering
+      operationId: listTokens
+      tags:
+        - Tokens
+      security:
+        - oauth2:
+            - tokens:read
+      parameters:
+        - name: code
+          in: query
+          schema:
+            type: string
+            pattern: '^[A-Z0-9]{1,10}$'
+          description: Filter by token code
+        - name: issuer
+          in: query
+          schema:
+            type: string
+            pattern: '^0x[a-fA-F0-9]{40}$'
+          description: Filter by issuer address
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+          description: Pagination offset
+      responses:
+        '200':
+          description: List of tokens
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '../components/schemas.yaml#/components/schemas/Token'
+                  total:
+                    type: integer
+                  limit:
+                    type: integer
+                  offset:
+                    type: integer
+
+  /tokens/{code}:
+    get:
+      summary: Get token metadata
+      description: Get token metadata and configuration by code
+      operationId: getToken
+      tags:
+        - Tokens
+      security:
+        - oauth2:
+            - tokens:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
+      responses:
+        '200':
+          description: Token metadata
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Token'
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+
+    patch:
+      summary: Update token policy
+      description: Update token policy configuration (pause, lienMode, bridgeOnly, etc.)
+      operationId: updateTokenPolicy
+      tags:
+        - Tokens
+      security:
+        - oauth2:
+            - tokens:write
+      x-roles:
+        - POLICY_OPERATOR
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/UpdatePolicyRequest'
+      responses:
+        '200':
+          description: Policy updated
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Token'
+
+  /tokens/{code}/mint:
+    post:
+      summary: Mint tokens
+      description: Mint new tokens to an address (requires ISSUER_ROLE)
+      operationId: mintTokens
+      tags:
+        - Tokens
+      security:
+        - oauth2:
+            - tokens:write
+      x-roles:
+        - ISSUER
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/MintRequest'
+      responses:
+        '200':
+          description: Tokens minted
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/TransactionResponse'
+
+  /tokens/{code}/burn:
+    post:
+      summary: Burn tokens
+      description: Burn tokens from an address (requires ISSUER_ROLE)
+      operationId: burnTokens
+      tags:
+        - Tokens
+      security:
+        - oauth2:
+            - tokens:write
+      x-roles:
+        - ISSUER
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/BurnRequest'
+      responses:
+        '200':
+          description: Tokens burned
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/TransactionResponse'
+
+  /tokens/{code}/clawback:
+    post:
+      summary: Clawback tokens
+      description: Clawback tokens from an address (requires ENFORCEMENT_ROLE)
+      operationId: clawbackTokens
+      tags:
+        - Tokens
+      security:
+        - oauth2:
+            - tokens:write
+      x-roles:
+        - ENFORCEMENT
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/ClawbackRequest'
+      responses:
+        '200':
+          description: Tokens clawed back
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/TransactionResponse'
+
+  /tokens/{code}/force-transfer:
+    post:
+      summary: Force transfer tokens
+      description: Force transfer tokens between addresses (requires ENFORCEMENT_ROLE and forceTransferMode)
+      operationId: forceTransferTokens
+      tags:
+        - Tokens
+      security:
+        - oauth2:
+            - tokens:write
+      x-roles:
+        - ENFORCEMENT
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas.yaml#/components/schemas/ForceTransferRequest'
+      responses:
+        '200':
+          description: Tokens force transferred
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/TransactionResponse'
+

api/packages/openapi/v1/paths/triggers.yaml

@@ -0,0 +1,206 @@
+paths:
+  /triggers:
+    get:
+      summary: List triggers
+      description: List payment rail triggers with filtering
+      operationId: listTriggers
+      tags:
+        - Triggers
+      security:
+        - oauth2:
+            - triggers:read
+      parameters:
+        - name: state
+          in: query
+          schema:
+            $ref: '../components/schemas.yaml#/components/schemas/TriggerState'
+          description: Filter by trigger state
+        - name: rail
+          in: query
+          schema:
+            $ref: '../components/schemas.yaml#/components/schemas/Rail'
+          description: Filter by payment rail
+        - name: msgType
+          in: query
+          schema:
+            type: string
+            pattern: '^[a-z]+\\.[0-9]{3}$'
+          description: Filter by ISO-20022 message type
+        - name: instructionId
+          in: query
+          schema:
+            type: string
+            pattern: '^[a-fA-F0-9]{64}$'
+          description: Filter by instruction ID
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        '200':
+          description: List of triggers
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '../components/schemas.yaml#/components/schemas/Trigger'
+                  total:
+                    type: integer
+                  limit:
+                    type: integer
+                  offset:
+                    type: integer
+
+  /triggers/{triggerId}:
+    get:
+      summary: Get trigger
+      description: Get trigger details by ID
+      operationId: getTrigger
+      tags:
+        - Triggers
+      security:
+        - oauth2:
+            - triggers:read
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
+      responses:
+        '200':
+          description: Trigger details
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
+        '404':
+          $ref: '../openapi.yaml#/components/responses/NotFound'
+
+  /triggers/{triggerId}/validate-and-lock:
+    post:
+      summary: Validate and lock trigger
+      description: Orchestrator step - validate trigger and lock funds
+      operationId: validateAndLockTrigger
+      tags:
+        - Triggers
+      security:
+        - oauth2:
+            - triggers:write
+      x-roles:
+        - POLICY_OPERATOR
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
+      responses:
+        '200':
+          description: Trigger validated and locked
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
+        '400':
+          $ref: '../openapi.yaml#/components/responses/BadRequest'
+        '409':
+          $ref: '../openapi.yaml#/components/responses/Conflict'
+
+  /triggers/{triggerId}/mark-submitted:
+    post:
+      summary: Mark trigger as submitted
+      description: Mark trigger as submitted to rail (includes railTxRef)
+      operationId: markTriggerSubmitted
+      tags:
+        - Triggers
+      security:
+        - oauth2:
+            - triggers:write
+      x-roles:
+        - POLICY_OPERATOR
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - railTxRef
+              properties:
+                railTxRef:
+                  type: string
+                  description: Rail transaction reference
+      responses:
+        '200':
+          description: Trigger marked as submitted
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
+
+  /triggers/{triggerId}/confirm-settled:
+    post:
+      summary: Confirm trigger settled
+      description: Confirm trigger has settled on the rail
+      operationId: confirmTriggerSettled
+      tags:
+        - Triggers
+      security:
+        - oauth2:
+            - triggers:write
+      x-roles:
+        - POLICY_OPERATOR
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      responses:
+        '200':
+          description: Trigger confirmed as settled
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
+
+  /triggers/{triggerId}/confirm-rejected:
+    post:
+      summary: Confirm trigger rejected
+      description: Confirm trigger was rejected on the rail
+      operationId: confirmTriggerRejected
+      tags:
+        - Triggers
+      security:
+        - oauth2:
+            - triggers:write
+      x-roles:
+        - POLICY_OPERATOR
+      x-idempotency: true
+      parameters:
+        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
+        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+                  description: Rejection reason
+      responses:
+        '200':
+          description: Trigger confirmed as rejected
+          content:
+            application/json:
+              schema:
+                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
+