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