openapi.yaml

openapi: 3.0.0
info:
  title: SwiftRemit API Service
  version: 1.0.0
  description: |
    API service for SwiftRemit currency configuration and anchor management
    
    ## Rate Limiting
    
    All API endpoints are subject to rate limiting to ensure fair usage and system stability.
    The API implements RFC 6585-compliant rate limiting with the following tiers:
    
    ### Rate Limit Tiers
    
    | Tier      | Limit                | Window    | Applies To                          |
    |-----------|----------------------|-----------|-------------------------------------|
    | **Global**   | 100 requests         | 15 minutes| All unauthenticated requests        |
    | **Per-Key**  | 200 requests         | 1 minute  | Authenticated API key requests      |
    | **Admin**    | 500 requests         | 1 minute  | Admin operations (x-api-key header) |
    | **Webhook**  | 1000 requests        | 1 minute  | Webhook endpoints                   |
    
    ### Rate Limit Headers
    
    Every response includes the following RFC 6585-compliant headers:
    
    - `RateLimit-Limit`: Maximum number of requests allowed in the current window
    - `RateLimit-Remaining`: Number of requests remaining in the current window
    - `RateLimit-Reset`: ISO 8601 timestamp when the rate limit window resets
    
    When the rate limit is exceeded, the API returns:
    
    - HTTP Status: `429 Too Many Requests`
    - `Retry-After` header: Number of seconds to wait before retrying
    - Response body includes `retryAfter` (seconds) and `resetAt` (ISO 8601 timestamp)
    
    ### Example Response Headers
    
    **Successful Request (200 OK):**
    ```
    RateLimit-Limit: 100
    RateLimit-Remaining: 87
    RateLimit-Reset: 2026-07-30T12:30:00.000Z
    ```
    
    **Rate Limit Exceeded (429 Too Many Requests):**
    ```
    RateLimit-Limit: 100
    RateLimit-Remaining: 0
    RateLimit-Reset: 2026-07-30T12:30:00.000Z
    Retry-After: 120
    ```
    
    ### Best Practices
    
    1. **Monitor Headers**: Check `RateLimit-Remaining` before making additional requests
    2. **Honor Retry-After**: When receiving a 429 response, wait at least `Retry-After` seconds
    3. **Implement Exponential Backoff**: For transient errors, use exponential backoff with jitter
    4. **Use API Keys**: Authenticate with `x-api-key` header for higher rate limits
    
  contact:
    name: SwiftRemit Team

servers:
  - url: http://localhost:3000
    description: Development server
  - url: https://api.swiftremit.com
    description: Production server

tags:
  - name: Health
    description: Health check endpoints
  - name: Currencies
    description: Currency configuration endpoints
  - name: Anchors
    description: Anchor provider management endpoints
  - name: Remittances
    description: Remittance query endpoints
  - name: Admin
    description: Admin utility endpoints
  - name: Agents
    description: Agent registration and management endpoints
  - name: Auth
    description: JWT authentication endpoints

paths:
  /health:
    get:
      tags:
        - Health
      summary: Health check endpoint
      operationId: getHealth
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /api/currencies:
    get:
      tags:
        - Currencies
      summary: Get all supported currencies
      description: Returns all supported currencies with their formatting rules
      operationId: getCurrencies
      responses:
        '200':
          description: List of currencies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/currencies/{code}:
    get:
      tags:
        - Currencies
      summary: Get currency by code
      description: Returns a specific currency by its code
      operationId: getCurrencyByCode
      parameters:
        - name: code
          in: path
          required: true
          description: Currency code (e.g., USD, EUR)
          schema:
            type: string
            minLength: 1
            maxLength: 12
            example: USD
      responses:
        '200':
          description: Currency details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyResponse'
        '400':
          description: Invalid currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Currency not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/anchors:
    get:
      tags:
        - Anchors
      summary: Get all anchor providers
      description: Returns all available anchor providers with optional filtering
      operationId: getAnchors
      parameters:
        - name: status
          in: query
          description: Filter by anchor status
          schema:
            type: string
            enum: [active, inactive, maintenance]
        - name: currency
          in: query
          description: Filter by supported currency
          schema:
            type: string
            maxLength: 12
      responses:
        '200':
          description: List of anchor providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnchorListResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/anchors/{id}:
    get:
      tags:
        - Anchors
      summary: Get anchor by ID
      description: Returns a specific anchor provider by ID
      operationId: getAnchorById
      parameters:
        - name: id
          in: path
          required: true
          description: Anchor ID
          schema:
            type: string
      responses:
        '200':
          description: Anchor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnchorDetailResponse'
        '404':
          description: Anchor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/anchors/admin:
    post:
      tags:
        - Anchors
      summary: Create new anchor (Admin)
      description: Creates a new anchor provider. Requires admin API key.
      operationId: createAnchor
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnchorProvider'
      responses:
        '201':
          description: Anchor created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnchorDetailResponse'
        '400':
          description: Invalid anchor payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/remittances:
    get:
      tags:
        - Remittances
      summary: Query remittances with cursor pagination and filters
      description: >
        Returns a cursor-paginated list of remittances with optional filtering
        by status, date range, corridor, and amount range (Issue #882).
      operationId: getRemittances
      parameters:
        - name: agent
          in: query
          required: false
          description: Stellar address of the agent
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by remittance status
          schema:
            type: string
            enum: [Pending, Processing, Completed, Cancelled, Failed, Disputed]
        - name: from_date
          in: query
          required: false
          description: ISO 8601 lower bound for created_at
          schema:
            type: string
            format: date-time
        - name: to_date
          in: query
          required: false
          description: ISO 8601 upper bound for created_at
          schema:
            type: string
            format: date-time
        - name: corridor
          in: query
          required: false
          description: Corridor filter, e.g. "USD-NG"
          schema:
            type: string
        - name: min_amount
          in: query
          required: false
          description: Minimum amount in stroops
          schema:
            type: integer
            minimum: 0
        - name: max_amount
          in: query
          required: false
          description: Maximum amount in stroops
          schema:
            type: integer
            minimum: 0
        - name: cursor
          in: query
          required: false
          description: Opaque pagination cursor from previous response
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Items per page (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Cursor-paginated list of remittances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemittanceCursorResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/agents:
    post:
      tags:
        - Agents
      summary: Register a new agent (Issue #880)
      description: >
        Creates an agent profile with status 'pending'. Requires admin API key.
        The on-chain register_agent call should be triggered separately.
      operationId: registerAgent
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRegistrationRequest'
      responses:
        '201':
          description: Agent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Agent already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/agents/{id}:
    get:
      tags:
        - Agents
      summary: Get agent profile (Issue #880)
      operationId: getAgent
      parameters:
        - name: id
          in: path
          required: true
          description: Agent stellar_address
          schema:
            type: string
      responses:
        '200':
          description: Agent profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/agents/{id}/payout-address:
    put:
      tags:
        - Agents
      summary: Update agent payout address (Issue #880)
      operationId: updateAgentPayoutAddress
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Agent stellar_address
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - payout_address
              properties:
                payout_address:
                  type: string
      responses:
        '200':
          description: Updated agent profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/auth/login:
    post:
      tags:
        - Auth
      summary: Login and receive access + refresh tokens (Issue #883)
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - userId
                - password
              properties:
                userId:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Access token issued; refresh token set in HttpOnly cookie
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/auth/refresh:
    post:
      tags:
        - Auth
      summary: Rotate refresh token and issue new access token (Issue #883)
      operationId: refreshToken
      responses:
        '200':
          description: New access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Missing or invalid refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/auth/logout:
    post:
      tags:
        - Auth
      summary: Revoke refresh token (Issue #883)
      operationId: logout
      responses:
        '200':
          description: Logged out, cookie cleared
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  timestamp:
                    type: string

  /api/admin/simulate-upgrade:
    post:
      tags:
        - Admin
      summary: Simulate a contract upgrade (strictly read-only)
      description: >
        Returns a structured preview of the storage migrations, CPU/ledger resource estimates,
        and operator warnings that would arise if the supplied WASM hash were used in a real
        upgrade proposal. No on-chain state, no database state, and no transaction is ever
        modified or submitted (simulation_only is always true in the response).

        Requires both an admin API key (x-api-key header) and a valid second-admin
        confirmation token obtained via POST /api/admin/actions followed by
        POST /api/admin/actions/{id}/confirm.

        Rate-limited to 5 requests per 15 minutes per IP. Every invocation —
        including rejected ones — is written to the admin_audit_log table.
        Resolves issue SR-059.
      operationId: simulateUpgrade
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateUpgradeRequest'
            examples:
              valid:
                summary: Typical valid request
                value:
                  wasm_hash: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
                  confirmation_token: "3f6e2a1b-0000-4abc-8def-1234567890ab"
      responses:
        '200':
          description: Read-only simulation report
          headers:
            X-Simulation-Only:
              description: Always "true" — confirms no state was mutated
              schema:
                type: string
                example: "true"
            Cache-Control:
              description: no-store — response must not be cached
              schema:
                type: string
                example: "no-store"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateUpgradeResponse'
        '400':
          description: >
            Invalid wasm_hash format, hash not on allowlist, extra fields present,
            missing confirmation_token, or payload exceeds 1 KB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidHash:
                  value:
                    success: false
                    error:
                      message: "wasm_hash must be a 64-character hex string (32 bytes)"
                      code: "INVALID_WASM_HASH"
                    timestamp: "2026-07-29T12:00:00.000Z"
                notAllowlisted:
                  value:
                    success: false
                    error:
                      message: "wasm_hash is not in the permitted allowlist"
                      code: "WASM_HASH_NOT_ALLOWLISTED"
                    timestamp: "2026-07-29T12:00:00.000Z"
                extraFields:
                  value:
                    success: false
                    error:
                      message: "Unexpected field(s): evil_field"
                      code: "EXTRA_FIELDS"
                    timestamp: "2026-07-29T12:00:00.000Z"
                payloadTooLarge:
                  value:
                    success: false
                    error:
                      message: "Request body must not exceed 1024 bytes"
                      code: "PAYLOAD_TOO_LARGE"
                    timestamp: "2026-07-29T12:00:00.000Z"
        '401':
          description: Admin API key missing/invalid or confirmation token invalid/expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded — 5 requests per 15 minutes per IP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Database not configured (required for confirmation token verification)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/admin/fees:
    get:
      tags:
        - Admin
      summary: Get accumulated fee breakdown
      description: >
        Returns total accumulated platform fees, per-integrator breakdown,
        daily/weekly/monthly time-series, and pending withdrawal amount.
        Requires admin authentication. Resolves issue #473.
      operationId: getAdminFees
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Fee breakdown data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeBreakdownResponse'
        '401':
          description: Unauthorized — admin API key required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Admin API key for protected endpoints

  schemas:
    HealthResponse:
      type: object
      required:
        - status
        - timestamp
        - uptime
      properties:
        status:
          type: string
          example: ok
        timestamp:
          type: string
          format: date-time
        uptime:
          type: number
          description: Server uptime in seconds

    Currency:
      type: object
      required:
        - code
        - symbol
        - decimal_precision
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 12
          example: USD
        symbol:
          type: string
          example: $
        decimal_precision:
          type: integer
          minimum: 0
          maximum: 18
          example: 2
        name:
          type: string
          example: US Dollar

    CurrencyResponse:
      type: object
      required:
        - success
        - data
        - count
        - timestamp
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Currency'
        count:
          type: integer
        timestamp:
          type: string
          format: date-time

    ErrorResponse:
      type: object
      required:
        - success
        - error
        - timestamp
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
            code:
              type: string
        timestamp:
          type: string
          format: date-time

    AnchorFees:
      type: object
      required:
        - deposit_fee_percent
        - withdrawal_fee_percent
      properties:
        deposit_fee_percent:
          type: number
          format: float
        deposit_fee_fixed:
          type: number
          format: float
        withdrawal_fee_percent:
          type: number
          format: float
        withdrawal_fee_fixed:
          type: number
          format: float
        min_fee:
          type: number
          format: float
        max_fee:
          type: number
          format: float

    AnchorLimits:
      type: object
      required:
        - min_amount
        - max_amount
      properties:
        min_amount:
          type: number
          format: float
        max_amount:
          type: number
          format: float
        daily_limit:
          type: number
          format: float
        monthly_limit:
          type: number
          format: float

    AnchorCompliance:
      type: object
      required:
        - kyc_required
        - kyc_level
        - supported_countries
        - restricted_countries
        - documents_required
      properties:
        kyc_required:
          type: boolean
        kyc_level:
          type: string
          enum: [basic, intermediate, advanced]
        supported_countries:
          type: array
          items:
            type: string
        restricted_countries:
          type: array
          items:
            type: string
        documents_required:
          type: array
          items:
            type: string

    AnchorProvider:
      type: object
      required:
        - id
        - name
        - domain
        - description
        - status
        - fees
        - limits
        - compliance
        - supported_currencies
        - processing_time
        - verified
      properties:
        id:
          type: string
          example: anchor-1
        name:
          type: string
          example: Example Anchor
        domain:
          type: string
          example: anchor.example.com
        logo_url:
          type: string
          format: uri
        description:
          type: string
        status:
          type: string
          enum: [active, inactive, maintenance]
        fees:
          $ref: '#/components/schemas/AnchorFees'
        limits:
          $ref: '#/components/schemas/AnchorLimits'
        compliance:
          $ref: '#/components/schemas/AnchorCompliance'
        supported_currencies:
          type: array
          items:
            type: string
        processing_time:
          type: string
          example: 1-2 business days
        rating:
          type: number
          format: float
          minimum: 0
          maximum: 5
        total_transactions:
          type: integer
        verified:
          type: boolean

    AnchorListResponse:
      type: object
      required:
        - success
        - data
        - count
        - timestamp
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnchorProvider'
        count:
          type: integer
        timestamp:
          type: string
          format: date-time

    AnchorDetailResponse:
      type: object
      required:
        - success
        - data
        - timestamp
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/AnchorProvider'
        timestamp:
          type: string
          format: date-time

    Remittance:
      type: object
      required:
        - id
        - sender
        - agent
        - amount
        - fee
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: integer
          example: 1
        sender:
          type: string
          description: Stellar address of the sender
        agent:
          type: string
          description: Stellar address of the agent
        amount:
          type: integer
          description: Amount in stroops
        fee:
          type: integer
          description: Platform fee in stroops
        status:
          type: string
          enum: [Pending, Processing, Completed, Cancelled, Failed, Disputed]
        token:
          type: string
          description: Stellar token address used for this remittance
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Pagination:
      type: object
      required:
        - page
        - limit
        - total
        - total_pages
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer

    RemittanceListResponse:
      type: object
      required:
        - success
        - data
        - pagination
        - timestamp
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Remittance'
        pagination:
          $ref: '#/components/schemas/Pagination'
        timestamp:
          type: string
          format: date-time

    IntegratorFeeEntry:
      type: object
      required:
        - integrator
        - accumulated_fees
      properties:
        integrator:
          type: string
          description: Stellar address of the integrator
        accumulated_fees:
          type: integer
          description: Accumulated fees in stroops

    FeeTimeSeries:
      type: object
      required:
        - period
        - label
        - amount
      properties:
        period:
          type: string
          enum: [daily, weekly, monthly]
        label:
          type: string
          description: Human-readable period label (e.g. "2026-04-27")
        amount:
          type: integer
          description: Fees collected in this period (stroops)

    FeeBreakdownResponse:
      type: object
      required:
        - success
        - data
        - timestamp
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          required:
            - total_accumulated_fees
            - pending_withdrawal
            - integrator_breakdown
            - time_series
          properties:
            total_accumulated_fees:
              type: integer
              description: Total platform fees accumulated (stroops)
            pending_withdrawal:
              type: integer
              description: Fees not yet withdrawn (stroops)
            integrator_breakdown:
              type: array
              items:
                $ref: '#/components/schemas/IntegratorFeeEntry'
            time_series:
              type: array
              items:
                $ref: '#/components/schemas/FeeTimeSeries'
        timestamp:
          type: string
          format: date-time

    Agent:
      type: object
      required:
        - id
        - stellar_address
        - payout_address
        - name
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
        stellar_address:
          type: string
          description: Stellar public key (G...)
        payout_address:
          type: string
          description: Off-chain payout destination address
        name:
          type: string
        status:
          type: string
          enum: [pending, active, suspended]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AgentRegistrationRequest:
      type: object
      required:
        - stellar_address
        - payout_address
        - name
      properties:
        stellar_address:
          type: string
          description: Agent Stellar public key
        payout_address:
          type: string
        name:
          type: string

    AgentResponse:
      type: object
      required:
        - success
        - data
        - timestamp
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Agent'
        timestamp:
          type: string
          format: date-time

    TokenResponse:
      type: object
      required:
        - success
        - data
        - timestamp
      properties:
        success:
          type: boolean
        data:
          type: object
          required:
            - access_token
            - token_type
            - expires_in
          properties:
            access_token:
              type: string
            token_type:
              type: string
              example: Bearer
            expires_in:
              type: integer
              description: Seconds until access token expires
              example: 900
        timestamp:
          type: string
          format: date-time

    RemittanceCursorResponse:
      type: object
      required:
        - success
        - data
        - next_cursor
        - has_more
        - timestamp
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Remittance'
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
        timestamp:
          type: string
          format: date-time

    SimulateUpgradeRequest:
      type: object
      required:
        - wasm_hash
        - confirmation_token
      additionalProperties: false
      properties:
        wasm_hash:
          type: string
          description: >
            64-character lowercase hex-encoded SHA-256 hash of the candidate WASM blob (32 bytes).
            Must match a value in WASM_HASH_ALLOWLIST when that environment variable is configured.
          pattern: '^[0-9a-fA-F]{64}$'
          minLength: 64
          maxLength: 64
          example: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
        confirmation_token:
          type: string
          description: >
            UUID token issued by a second admin via POST /api/admin/actions/{id}/confirm.
            The token must be confirmed and not expired.
          example: "3f6e2a1b-0000-4abc-8def-1234567890ab"

    SimulateUpgradeReport:
      type: object
      required:
        - current_schema_version
        - new_schema_version
        - schema_version_delta
        - estimated_migration_steps
        - affected_storage_keys
        - requires_migration
        - estimated_cpu_instructions
        - estimated_ledger_bytes
        - warnings
        - input_hash_fingerprint
        - simulation_only
      properties:
        current_schema_version:
          type: integer
          description: Schema version currently deployed on-chain
          example: 2
        new_schema_version:
          type: integer
          description: Projected schema version if this WASM were applied
          example: 4
        schema_version_delta:
          type: integer
          description: Signed delta (new − current)
          example: 2
        estimated_migration_steps:
          type: integer
          description: Number of discrete migration steps estimated
          example: 2
        affected_storage_keys:
          type: array
          items:
            type: string
          description: Ledger storage keys that would be touched during migration
          example: ["schema_v", "UpgradeKey::NextId"]
        requires_migration:
          type: boolean
          description: Whether any migration work would be required
          example: true
        estimated_cpu_instructions:
          type: integer
          description: Conservative upper-bound CPU instruction budget estimate
          example: 700000
        estimated_ledger_bytes:
          type: integer
          description: Conservative upper-bound ledger-entry bytes written estimate
          example: 256
        warnings:
          type: array
          items:
            type: string
          description: Human-readable operator warnings (e.g. large version jump, budget pressure)
          example: ["Large schema version jump detected. Verify migration scripts cover all intermediate versions."]
        input_hash_fingerprint:
          type: string
          description: First 16 hex chars of SHA-256(wasm_hash) — for audit-trail correlation
          example: "d4e8f1a2b3c09571"
        simulation_only:
          type: boolean
          enum: [true]
          description: Always true — confirms no on-chain or database state was mutated
          example: true

    SimulateUpgradeResponse:
      type: object
      required:
        - success
        - data
        - timestamp
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/SimulateUpgradeReport'
        timestamp:
          type: string
          format: date-time