openapi.yaml

openapi: 3.0.3
info:
  title: Basis Tracker API
  description: |
    HTTP API for Basis Tracker - a decentralized system for offchain IOU notes backed by on-chain reserves.
    
    Basis enables efficient offchain cash systems for micropayments and community currencies, allowing:
    - Credit-based payments (unbacked IOU money)
    - On-chain collateral management via Ergo reserves
    - Real-time tracking of debt relationships
    - Secure redemption processes with Schnorr signatures
    
    The system uses secp256k1 cryptography with 33-byte compressed public keys and 65-byte Schnorr signatures.
    Trackers maintain offchain ledgers while reserves provide on-chain collateral backing.
  version: 1.0.0
  contact:
    name: Basis Tracker Team
    url: https://github.com/bml/basis-tracker
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3048
    description: Local development server (plaintext)
  - url: https://localhost:3048
    description: Local development server (TLS)

security:
  - ApiKeyAuth: []
  - SignatureAuth: []

paths:
  /:
    get:
      summary: Health check endpoint
      description: Returns a simple message to verify the API is running.
      operationId: root
      tags:
        - Health
      security: []
      responses:
        '200':
          description: Successful response
          content:
            text/plain:
              schema:
                type: string
                example: "Hello, Basis Tracker API!"

  /notes:
    post:
      summary: Create a new IOU note
      description: Creates a new IOU note with the specified parameters. The note must be signed by the issuer.
      operationId: createNote
      tags:
        - Notes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNoteRequest'
      responses:
        '201':
          description: Note created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEmpty'
        '400':
          description: Bad request - invalid input parameters (including malformed tracker_nft_id hex or wrong length)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '409':
          description: Conflict - note's tracker_nft_id does not match this tracker's configured tracker NFT ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
    get:
      summary: Get all IOU notes
      description: Retrieve all IOU notes tracked by the server, including the age of each note in seconds.
      operationId: getAllNotes
      tags:
        - Notes
      responses:
        '200':
          description: Successfully retrieved notes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseNotesWithAge'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /notes/exchange:
    post:
      summary: Exchange debt between denominations (two-phase off-chain novation)
      description: >-
        Moves cumulative debt between two denominations of one (issuer, recipient)
        pair in two phases (issue #17). Phase 1, applied immediately: the
        from-denomination edge decreases by from_amount. Phase 2, staged: the
        to-denomination edge increases by to_amount, but only applies once the
        from-edge decrease is committed on-chain AND the issuer's tracked
        from-denomination reserve box is verified unchanged (still unspent with
        an R5 digest matching the tracker's reserve tree). This prevents the
        creditor from redeeming the old from-edge note AND collecting the staged
        to-edge increase. Both parties sign both edges' new states; the
        recipient's signatures are the creditor consent required for a debt
        decrease (S3 rule). The acceptance policy is evaluated in the target
        denomination against the pre-mutation state, atomically with the
        mutation. The request fails with 409 when the issuer has zero or
        multiple tracked reserves in the from denomination. Track progress via
        GET /exchanges/pending.
      operationId: exchangeNotes
      tags:
        - Notes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeNotesRequest'
      responses:
        '200':
          description: >-
            From-edge decrease applied; to-edge increase staged
            (to_edge_status "pending")
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseExchangeNotes'
        '400':
          description: Invalid request, unserved denomination, missing creditor consent, or acceptance-policy rejection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '409':
          description: The issuer has no tracked reserve or multiple tracked reserves in the from denomination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
  /exchanges/pending:
    get:
      summary: List staged and cancelled cross-denomination exchanges
      description: >-
        Returns the persisted two-phase exchange records (issue #17) for the
        tracker, optionally filtered by issuer and/or recipient public key.
        Staged records await the from-edge decrease being committed and the
        from-denomination reserve box being verified unchanged; cancelled
        records carry the reason the exchange was abandoned (the from-edge
        decrease stays applied). Applied records are removed once the to-edge
        increase is applied. Cancelled records older than 30 days are pruned
        on access.
      operationId: listPendingExchanges
      tags:
        - Notes
      parameters:
        - name: issuer_pubkey
          in: query
          required: false
          description: Hex-encoded issuer public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
        - name: recipient_pubkey
          in: query
          required: false
          description: Hex-encoded recipient public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
      responses:
        '200':
          description: Pending exchange records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponsePendingExchanges'
        '400':
          description: Invalid public key filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
  /notes/issuer/{pubkey}:
    get:
      summary: Get notes by issuer
      description: Retrieve all IOU notes issued by a specific public key.
      operationId: getNotesByIssuer
      tags:
        - Notes
      parameters:
        - name: pubkey
          in: path
          required: true
          description: Hex-encoded issuer public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "010101010101010101010101010101010101010101010101010101010101010101"
      responses:
        '200':
          description: Successfully retrieved notes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseNotes'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /notes/issuer/{issuer_pubkey}/recipient/{recipient_pubkey}:
    get:
      summary: Get specific note by issuer and recipient
      description: Retrieve a specific IOU note between an issuer and recipient.
      operationId: getNoteByIssuerAndRecipient
      tags:
        - Notes
      parameters:
        - name: issuer_pubkey
          in: path
          required: true
          description: Hex-encoded issuer public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "010101010101010101010101010101010101010101010101010101010101010101"
        - name: recipient_pubkey
          in: path
          required: true
          description: Hex-encoded recipient public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "020202020202020202020202020202020202020202020202020202020202020202"
        - name: denomination
          in: query
          required: false
          schema:
            type: string
          description: "Denomination of the note: erg or token:<64-hex>. Defaults to the pair's existing note denomination when unambiguous, else erg."

      responses:
        '200':
          description: Successfully retrieved note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseNote'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEmpty'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /notes/recipient/{pubkey}:
    get:
      summary: Get notes by recipient
      description: Retrieve all IOU notes where the specified public key is the recipient.
      operationId: getNotesByRecipient
      tags:
        - Notes
      parameters:
        - name: pubkey
          in: path
          required: true
          description: Hex-encoded recipient public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "020202020202020202020202020202020202020202020202020202020202020202"
      responses:
        '200':
          description: Successfully retrieved notes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseNotes'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /notes/state:
    post:
      summary: Get confirmation state for a single note
      description: Retrieve local, confirmed, and pending total debt for a specific note, along with redeemable information.
      operationId: getNoteState
      tags:
        - Notes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteStateRequest'
      responses:
        '200':
          description: Successfully retrieved note state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseNoteState'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /reserves:
    get:
      summary: Get all reserves
      description: Retrieve all on-chain reserves tracked by the server regardless of issuer.
      operationId: getAllReserves
      tags:
        - Reserves
      responses:
        '200':
          description: Successfully retrieved reserves
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReserves'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /reserves/{box_id}:
    get:
      summary: Get reserve by box ID
      description: Retrieve a specific reserve by its box ID.
      operationId: getReserveByBoxId
      tags:
        - Reserves
      parameters:
        - name: box_id
          in: path
          required: true
          description: Hex-encoded reserve box ID
          schema:
            type: string
            example: "f1e2d3c4b5a697887766554433221100ffeeddccbbaa99887766554433221100"
      responses:
        '200':
          description: Successfully retrieved reserve
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReserve'
        '404':
          description: Reserve not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEmpty'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /reserves/issuer/{pubkey}:
    get:
      summary: Get reserves by issuer
      description: Retrieve all reserves managed by a specific issuer public key.
      operationId: getReservesByIssuer
      tags:
        - Reserves
      parameters:
        - name: pubkey
          in: path
          required: true
          description: Hex-encoded issuer public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "010101010101010101010101010101010101010101010101010101010101010101"
      responses:
        '200':
          description: Successfully retrieved reserves
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReserves'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /reserves/quarantined:
    get:
      summary: Get quarantined reserve boxes
      description: >-
        Retrieve reserve contract boxes rejected by admission control
        (issue #19): duplicates that do not descend from the tracked reserve
        for their (owner, denomination), or roots that failed setup validation.
        Quarantined boxes are never tracked, so they cannot block an issuer.
      operationId: getQuarantinedReserves
      tags:
        - Reserves
      responses:
        '200':
          description: Successfully retrieved quarantined reserve boxes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseQuarantinedReserves'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /reserves/create:
    post:
      summary: Create reserve transaction payload
      description: |
        Build a reserve creation transaction formatted for the Ergo node's
        /wallet/payment/send API. The tracker never broadcasts it: the reserve
        owner submits the returned `requests` array to their own node's
        `/wallet/payment/send`, so the tracker's wallet is never involved. The
        owner's wallet must hold the reserve NFT and enough ERG for the reserve
        value plus fee. The `nft_id` must not be the tracker's own NFT, and the
        amounts are bounded by `server.reserve_creation_max_*` config caps.
        The tracker only tracks a reserve whose creating transaction spends a
        P2PK input of the R4 owner key (see specs/ergo/reserve_admission.md);
        `basis-cli reserve create --submit` guarantees that (pinning inputs, or
        a pre-deployment 0.001 ERG UTXO when the wallet has no owner P2PK box),
        while a manual /wallet/payment/send submission is only safe when every
        wallet box belongs to the owner key.
      operationId: createReservePayload
      tags:
        - Reserves
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReserveRequest'
      responses:
        '200':
          description: Reserve payload created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReserveCreation'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /events:
    get:
      summary: Get recent tracker events
      description: Retrieve the 50 most recent tracker events including note updates, reserve changes, and system events.
      operationId: getEvents
      tags:
        - Events
      responses:
        '200':
          description: Successfully retrieved events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEvents'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /events/paginated:
    get:
      summary: Get paginated tracker events
      description: Retrieve paginated tracker events including note updates, reserve changes, and system events.
      operationId: getEventsPaginated
      tags:
        - Events
      parameters:
        - name: page
          in: query
          required: false
          description: Page number (0-indexed)
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: page_size
          in: query
          required: false
          description: Number of items per page (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Successfully retrieved events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEvents'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /key-status/{pubkey}:
    get:
      summary: Get key status information
      description: Retrieve comprehensive status information for a specific public key including debt, collateral, and collateralization ratio.
      operationId: getKeyStatus
      tags:
        - Status
      parameters:
        - name: pubkey
          in: path
          required: true
          description: Hex-encoded public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "010101010101010101010101010101010101010101010101010101010101010101"
      responses:
        '200':
          description: Successfully retrieved key status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseKeyStatus'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /redeem:
    post:
      summary: Initiate redemption process
      description: Initiate the redemption of an IOU note from a reserve.
      operationId: initiateRedemption
      tags:
        - Redemption
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemRequest'
      responses:
        '200':
          description: Redemption initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseRedeem'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /redeem/complete:
    post:
      summary: Complete a redemption
      description: |
        Mark a redemption as completed and update the note's redeemed amount.
        The server validates the amounts against the stored note state before
        applying the update: `redeemed_amount` must be positive and within the
        note's outstanding debt, and when `new_already_redeemed` is supplied it
        must equal the note's cumulative redeemed amount plus `redeemed_amount`.
        A mismatch is rejected with 400.
      operationId: completeRedemption
      tags:
        - Redemption
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteRedemptionRequest'
      responses:
        '200':
          description: Redemption completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEmpty'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /proof/redemption:
    get:
      summary: Get redemption proof
      description: Generate and retrieve a single AVL proof for a specific IOU note against the current tracker state.
      operationId: getRedemptionProof
      tags:
        - Proofs
      parameters:
        - name: issuer_pubkey
          in: query
          required: true
          description: Hex-encoded issuer public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "010101010101010101010101010101010101010101010101010101010101010101"
        - name: recipient_pubkey
          in: query
          required: true
          description: Hex-encoded recipient public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "020202020202020202020202020202020202020202020202020202020202020202"
        - name: amount
          in: query
          required: false
          description: Redemption amount (optional)
          schema:
            type: integer
            format: uint64
            example: 500000000
        - name: denomination
          in: query
          required: false
          schema:
            type: string
          description: "Denomination of the note: erg or token:<64-hex>. Defaults to the pair's existing note denomination when unambiguous, else erg."

      responses:
        '200':
          description: Successfully generated proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseProof'
        '400':
          description: Bad request - invalid public key format or missing parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /tracker/proof:
    get:
      summary: Get tracker lookup proof
      description: |
        Get AVL proof for totalDebt from the tracker's AVL tree.
        Returns proof for context extension variable #8 in redemption transactions.
      operationId: getTrackerProof
      tags:
        - Proofs
      parameters:
        - name: issuer_pubkey
          in: query
          required: true
          description: Hex-encoded issuer public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "010101010101010101010101010101010101010101010101010101010101010101"
        - name: recipient_pubkey
          in: query
          required: true
          description: Hex-encoded recipient public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "020202020202020202020202020202020202020202020202020202020202020202"
        - name: denomination
          in: query
          required: false
          schema:
            type: string
          description: "Denomination of the note: erg or token:<64-hex>. Defaults to the pair's existing note denomination when unambiguous, else erg."

      responses:
        '200':
          description: Successfully generated tracker proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseTrackerProof'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /reserve/proof:
    get:
      summary: Get reserve lookup proof
      description: |
        Get AVL proof for already_redeemed from the reserve's AVL tree.
        Returns proof for context extension variable #7 in redemption transactions.
        For first redemptions, returns proof: null (no lookup proof needed).
      operationId: getReserveProof
      tags:
        - Proofs
      parameters:
        - name: issuer_pubkey
          in: query
          required: true
          description: Hex-encoded issuer public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "010101010101010101010101010101010101010101010101010101010101010101"
        - name: recipient_pubkey
          in: query
          required: true
          description: Hex-encoded recipient public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "020202020202020202020202020202020202020202020202020202020202020202"
        - name: denomination
          in: query
          required: false
          schema:
            type: string
          description: "Denomination of the note: erg or token:<64-hex>. Defaults to the pair's existing note denomination when unambiguous, else erg."

      responses:
        '200':
          description: Successfully generated reserve proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReserveProof'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /tracker/signature:
    post:
      summary: Request tracker signature for redemption
      description: |
        Request a Schnorr signature from the tracker for redemption.
        The tracker signs: key || totalDebt || timestamp
        where key = blake2b256(ownerKey || receiverKey).

        The signed `totalDebt` and `timestamp` always come from the tracker's
        stored note for the given issuer/recipient pair; the `total_debt` and
        `timestamp` request fields must match the stored note (mismatches are
        rejected with 409). The acceptance policy is enforced for non-emergency
        requests before signing, evaluated against the issuer's tracked reserve
        for the note's denomination: 409 when the issuer has more than one
        tracked reserve in that denomination, or none — a reserve of another
        currency is never consulted in its place. Returns 404 when no note is
        stored for the pair.
      operationId: requestTrackerSignature
      tags:
        - Redemption
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackerSignatureRequest'
      responses:
        '200':
          description: Successfully generated tracker signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseTrackerSignature'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '404':
          description: Note not found for the issuer/recipient pair
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '409':
          description: >-
            Request values do not match the stored note, or the issuer's tracked
            reserve for the note's denomination is missing or not unique
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /tracker/state:
    get:
      summary: Get tracker state
      description: Retrieve the current tracker AVL tree state, including local, confirmed, and pending digests.
      operationId: getTrackerState
      tags:
        - Tracker
      responses:
        '200':
          description: Successfully retrieved tracker state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseTrackerState'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /tracker/pending-tx:
    get:
      summary: Get pending tracker update transaction
      description: Retrieve information about a pending tracker update transaction, if any.
      operationId: getPendingTx
      tags:
        - Tracker
      responses:
        '200':
          description: Successfully retrieved pending transaction information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponsePendingTx'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /tracker/latest-box-id:
    get:
      summary: Get latest tracker box ID
      description: Retrieve the latest confirmed tracker box ID, timestamp, and blockchain height.
      operationId: getLatestTrackerBoxId
      tags:
        - Tracker
      responses:
        '200':
          description: Successfully retrieved latest tracker box ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseTrackerBoxId'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /redemption/prepare:
    post:
      summary: Prepare a redemption
      description: |
        Prepare a redemption by generating AVL proofs and tracker signature.
        Returns the legacy preparation response containing a single combined AVL proof.

        The note for the issuer/recipient pair must exist in the tracker state;
        otherwise the request is rejected with 404. The tracker signature always
        covers the stored note's cumulative debt and payment timestamp — the
        `timestamp` request field must match the stored note — and `amount` is
        used only for the acceptance-policy check (skipped for emergency
        requests). That check is evaluated against the issuer's tracked reserve
        for the note's denomination; 409 when that reserve is missing or not
        unique — a reserve of another currency is never consulted in its place.
      operationId: prepareRedemption
      tags:
        - Redemption
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedemptionPreparationRequest'
      responses:
        '200':
          description: Redemption prepared successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseRedemptionPreparation'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '409':
          description: The issuer's tracked reserve for the note's denomination is missing or not unique
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /redemption/build:
    post:
      summary: Build a redemption transaction
      description: |
        Build an unsigned redemption transaction and a fee-signed partial transaction.
        The client must add the reserve input's proveDlog proof and submit the signed result.

        The tracker AVL proof is generated against the last on-chain-confirmed
        tracker state digest (not the live local tree), so the proof verifies
        against the digest stored in the tracker box. If no tracker state has
        been confirmed on-chain yet, or the note is not part of the confirmed
        state, the request is rejected with 400.
      operationId: buildRedemption
      tags:
        - Redemption
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedemptionBuildRequest'
      responses:
        '200':
          description: Redemption transaction built successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseRedemptionBuild'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /redemption/submit:
    post:
      summary: Submit a signed redemption transaction
      description: |
        Broadcast a fully signed redemption transaction to the Ergo network.
        Before broadcasting, the server validates the note key and redemption
        amounts against the stored note state; a mismatch is rejected with 400
        and nothing is broadcast.
      operationId: submitRedemption
      tags:
        - Redemption
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedemptionSubmitRequest'
      responses:
        '200':
          description: Redemption transaction submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseRedemptionSubmit'
        '400':
          description: Bad request - invalid transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /acceptance/check:
    post:
      summary: Check note acceptance
      description: >
        Check whether a note from the given issuer and total debt is acceptable
        under current policies. Collateralization is evaluated per
        denomination: against the issuer's tracked reserve of the candidate
        note's denomination, with the issuer's gross debt restricted to that
        same currency.
      operationId: checkAcceptance
      tags:
        - Acceptance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckAcceptanceRequest'
      responses:
        '200':
          description: Acceptance check completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCheckAcceptance'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /acceptance/policy:
    post:
      summary: Upload acceptance policy
      description: Upload or update a recipient's acceptance policy JSON, signed by the recipient.
      operationId: uploadPolicy
      tags:
        - Acceptance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadPolicyRequest'
      responses:
        '200':
          description: Policy uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseUploadPolicy'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /acceptance/policy/{pubkey}:
    get:
      summary: Get acceptance policy by recipient
      description: Retrieve the uploaded acceptance policy for a specific recipient public key.
      operationId: getPolicyByRecipient
      tags:
        - Acceptance
      parameters:
        - name: pubkey
          in: path
          required: true
          description: Hex-encoded recipient public key (66 characters)
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{66}$'
            example: "020202020202020202020202020202020202020202020202020202020202020202"
      responses:
        '200':
          description: Successfully retrieved policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseGetPolicy'
        '404':
          description: Policy not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEmpty'
        '400':
          description: Bad request - invalid public key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /config/reserve-contract-p2s:
    get:
      summary: Get reserve contract P2S address
      description: Retrieve the configured Basis reserve contract P2S address.
      operationId: getBasisReserveContractP2s
      tags:
        - Config
      responses:
        '200':
          description: Successfully retrieved reserve contract P2S address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseString'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /config/reserve-token:
    get:
      summary: Get reserve token configuration
      description: Retrieve reserve token configuration including token ID, decimals, and token-backed reserve contract P2S address.
      operationId: getReserveTokenConfig
      tags:
        - Config
      responses:
        '200':
          description: Successfully retrieved reserve token configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReserveTokenConfig'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

  /config/reserve-collateral:
    get:
      summary: Get reserve collateral configuration
      description: >-
        Returns the reserve contract addresses (ERG and token) plus the table of
        tokens this tracker serves as reserve collateral, and the full list of
        denominations available for notes and reserves
        (specs/ergo/multi_collateral_reserves.md).
      operationId: getReserveCollateralConfig
      tags:
        - Config
      responses:
        '200':
          description: Successfully retrieved reserve collateral configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReserveCollateralConfig'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Shared API key sent as `X-API-Key: <key>` or
        `Authorization: Bearer <key>`. Grants `Admin` access.
    SignatureAuth:
      type: apiKey
      in: header
      name: X-Signature
      description: |
        Per-request secp256k1 Schnorr signature. Requires companion headers
        `X-Signature-Pubkey`, `X-Signature-Timestamp`, and `X-Signature-Nonce`.

  schemas:
    ExchangeNotesRequest:
      type: object
      description: >-
        Cross-denomination debt exchange request. All four signatures are over the
        respective edge's standard 80-byte note message (debtKey ‖ totalDebt ‖
        timestamp ‖ trackerNftId) at the NEW cumulative total and timestamp.
      required:
        - issuer_pubkey
        - recipient_pubkey
        - from_denomination
        - from_amount
        - to_denomination
        - to_amount
        - timestamp
        - issuer_from_signature
        - recipient_from_signature
        - issuer_to_signature
        - recipient_to_signature
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
        from_denomination:
          type: string
          description: Denomination of the edge being decreased ("erg" or "token:<64-hex>")
          example: "erg"
        from_amount:
          type: integer
          format: uint64
          description: Amount by which the from-edge's cumulative debt decreases
        to_denomination:
          type: string
          description: Denomination of the edge being increased
          example: "token:a55b8735ed1a99e46c2c89f8994aacdf4b1109bdcf682f1e5b34479c6e392669"
        to_amount:
          type: integer
          format: uint64
          description: Amount by which the to-edge's cumulative debt increases
        timestamp:
          type: integer
          format: uint64
          description: New timestamp for both edges (must be newer than both current ones)
        issuer_from_signature:
          type: string
          description: Issuer signature over the from-edge's new message (hex, 130 chars)
        recipient_from_signature:
          type: string
          description: Recipient signature over the from-edge's new message (creditor consent)
        issuer_to_signature:
          type: string
          description: Issuer signature over the to-edge's new message
        recipient_to_signature:
          type: string
          description: Recipient signature over the to-edge's new message (creditor acceptance)

    ExchangeNotesResponse:
      type: object
      properties:
        exchanged:
          type: boolean
          example: true
        from_denomination:
          type: string
          example: "erg"
        to_denomination:
          type: string
          example: "token:a55b8735ed1a99e46c2c89f8994aacdf4b1109bdcf682f1e5b34479c6e392669"
        from_new_total:
          type: integer
          format: uint64
        to_new_total:
          type: integer
          format: uint64
          description: The to-edge total once the staged increase applies (not yet effective).
        timestamp:
          type: integer
          format: uint64
        to_edge_status:
          type: string
          enum:
            - pending
          description: >-
            Always "pending": the to-edge increase is staged until the
            from-edge decrease is committed and the from-denomination reserve
            box is verified unchanged (issue #17 two-phase exchange).

    PendingExchangeView:
      type: object
      properties:
        issuer_pubkey:
          type: string
        recipient_pubkey:
          type: string
        from_denomination:
          type: string
          example: "erg"
        from_old_total:
          type: integer
          format: uint64
          description: The from-edge's collected total before the exchange decrease.
        from_new_total:
          type: integer
          format: uint64
          description: The from-edge's collected total after the decrease (applied immediately).
        to_denomination:
          type: string
          example: "token:a55b8735ed1a99e46c2c89f8994aacdf4b1109bdcf682f1e5b34479c6e392669"
        to_amount:
          type: integer
          format: uint64
          description: The to-edge increase amount.
        to_new_total:
          type: integer
          format: uint64
          description: The to-edge's total once the staged increase is applied.
        status:
          type: string
          enum:
            - staged
            - cancelled
        cancel_reason:
          type: string
          nullable: true
          description: Why the exchange was abandoned (cancelled records only).
        created_at:
          type: integer
          format: uint64
          description: Unix timestamp (millis) when the exchange was staged.

    ApiResponsePendingExchanges:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/PendingExchangeView'
        error:
          type: string
          nullable: true

    ApiResponseExchangeNotes:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/ExchangeNotesResponse'
        error:
          type: string
          nullable: true

    ServedTokenInfo:
      type: object
      properties:
        token_id:
          type: string
          description: Token ID (64 hex chars)
          example: "a55b8735ed1a99e46c2c89f8994aacdf4b1109bdcf682f1e5b34479c6e392669"
        symbol:
          type: string
          example: "USE"
        decimals:
          type: integer
          example: 3
        min_collateralization_ratio:
          type: number
          format: float
          nullable: true
          example: 1.1

    ServedDenomination:
      type: object
      properties:
        id:
          type: string
          description: '"erg" or "token:<64-hex>"'
          example: "erg"
        symbol:
          type: string
          example: "ERG"
        decimals:
          type: integer
          example: 9

    ReserveCollateralConfigResponse:
      type: object
      properties:
        erg_contract_p2s:
          type: string
          description: ERG reserve contract P2S address
        token_contract_p2s:
          type: string
          description: Token reserve contract P2S address (serves every served token)
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/ServedTokenInfo'
        denominations:
          type: array
          items:
            $ref: '#/components/schemas/ServedDenomination'

    ApiResponseReserveCollateralConfig:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/ReserveCollateralConfigResponse'
        error:
          type: string
          nullable: true

    # API Response Wrappers
    ApiResponse:
      type: object
      description: Standard API response format
      properties:
        success:
          type: boolean
          description: Whether the request was successful
        data:
          type: object
          nullable: true
          description: Response data (null for error responses)
        error:
          type: string
          nullable: true
          description: Error message (null for successful responses)

    ApiResponseEmpty:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: object
              nullable: true
              example: null

    ApiResponseError:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            success:
              type: boolean
              example: false
            data:
              type: object
              nullable: true
              example: null
            error:
              type: string
              example: "Invalid signature"

    ApiResponseString:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: string
              description: String response data

    # Note Schemas
    SerializableIouNote:
      type: object
      description: Serializable IOU note for API responses
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        amount_collected:
          type: integer
          format: uint64
          description: Total cumulative debt amount collected on this note
          example: 1000000000
        amount_redeemed:
          type: integer
          format: uint64
          description: Total amount already redeemed from this note
          example: 250000000
        timestamp:
          type: integer
          format: uint64
          description: Note creation timestamp (tracked for record-keeping, not used in signing)
          example: 1234567890
        signature:
          type: string
          description: Hex-encoded Schnorr signature (signs key || totalDebt || timestamp || trackerNftId)
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"
        tracker_nft_id:
          type: string
          description: Hex-encoded tracker NFT ID (64 characters = 32 bytes) this note is bound to; part of the signed message
          pattern: '^[0-9a-fA-F]{64}$'
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"
        denomination:
          type: string
          description: "Denomination of the debt: erg or token:<64-hex>."
          example: "erg"

        confirmation:
          $ref: '#/components/schemas/NoteConfirmationSummary'

    SerializableIouNoteWithAge:
      type: object
      description: Serializable IOU note for API responses, including age
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        amount_collected:
          type: integer
          format: uint64
          description: Total cumulative debt amount collected on this note
          example: 1000000000
        amount_redeemed:
          type: integer
          format: uint64
          description: Total amount already redeemed from this note
          example: 250000000
        timestamp:
          type: integer
          format: uint64
          description: Note creation timestamp
          example: 1234567890
        signature:
          type: string
          description: Hex-encoded Schnorr signature (130 characters)
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"
        tracker_nft_id:
          type: string
          description: Hex-encoded tracker NFT ID (64 characters = 32 bytes) this note is bound to; part of the signed message
          pattern: '^[0-9a-fA-F]{64}$'
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"
        denomination:
          type: string
          description: "Denomination of the debt: erg or token:<64-hex>."
          example: "erg"

        age_seconds:
          type: integer
          format: uint64
          description: Age of the note in seconds
          example: 3600
        confirmation:
          $ref: '#/components/schemas/NoteConfirmationSummary'

    NoteConfirmationSummary:
      type: object
      description: Confirmation summary attached to note responses
      properties:
        status:
          type: string
          description: Confirmation status (local_only, pending, confirmed)
          example: "confirmed"
        confirmed_total_debt:
          type: integer
          format: uint64
          nullable: true
          description: Confirmed total debt amount
          example: 1000000000
        pending_total_debt:
          type: integer
          format: uint64
          nullable: true
          description: Pending total debt amount
          example: 1000000000
        confirmed_box_id:
          type: string
          nullable: true
          description: Box ID where the note was confirmed
          example: "f1e2d3c4b5a697887766554433221100ffeeddccbbaa99887766554433221100"
        confirmed_height:
          type: integer
          format: uint64
          nullable: true
          description: Blockchain height at which the note was confirmed
          example: 1250
        pending_tx_id:
          type: string
          nullable: true
          description: Transaction ID of the pending confirmation
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"
        redeemable:
          type: boolean
          description: Whether the note is currently redeemable
          example: true
        redeemable_amount:
          type: integer
          format: uint64
          description: Amount currently redeemable
          example: 750000000

    CreateNoteRequest:
      type: object
      description: Request body for creating a new IOU note
      required:
        - recipient_pubkey
        - amount
        - timestamp
        - signature
        - issuer_pubkey
        - tracker_nft_id
      properties:
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        amount:
          type: integer
          format: uint64
          description: Total cumulative debt amount (used in signing message)
          minimum: 0
          example: 1000000000
        timestamp:
          type: integer
          format: uint64
          description: Unix timestamp when the note was created
          minimum: 0
          example: 1234567890
        signature:
          type: string
          description: Hex-encoded Schnorr signature (130 characters = 65 bytes)
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        tracker_nft_id:
          type: string
          description: >-
            Hex-encoded tracker NFT ID (64 characters = 32 bytes) the note is bound to.
            Part of the signed message (appended after key || totalDebt || timestamp), so the
            signature is valid only for this tracker. Must match this tracker's configured
            ergo.tracker_nft_id.
          pattern: '^[0-9a-fA-F]{64}$'
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"
        denomination:
          type: string
          description: >-
            Denomination of the note: "erg" or "token:<64-hex>". When omitted, the server
            resolves to the pair's existing note's denomination when unambiguous, else "erg".
          example: "erg"

    NoteStateRequest:
      type: object
      description: Request body for retrieving a single note's confirmation state
      required:
        - issuer_pubkey
        - recipient_pubkey
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"


        denomination:
          type: string
          description: >-
            Denomination of the note: "erg" or "token:<64-hex>". When omitted, the server
            resolves to the pair's existing note's denomination when unambiguous, else "erg".
          example: "erg"
    NoteStateResponse:
      type: object
      description: Response for a single note's confirmation state
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        local:
          type: integer
          format: uint64
          description: Local total debt amount
          example: 1000000000
        confirmed:
          type: integer
          format: uint64
          nullable: true
          description: Confirmed total debt amount
          example: 1000000000
        pending:
          type: integer
          format: uint64
          nullable: true
          description: Pending total debt amount
          example: 1000000000
        already_redeemed:
          type: integer
          format: uint64
          description: Amount already redeemed
          example: 250000000
        redeemable:
          type: boolean
          description: Whether the note is redeemable
          example: true
        redeemable_amount:
          type: integer
          format: uint64
          description: Amount currently redeemable
          example: 750000000
        status:
          type: string
          description: Overall note status
          example: "confirmed"

    # Reserve Schemas
    SerializableReserveInfo:
      type: object
      description: Serializable reserve information
      properties:
        box_id:
          type: string
          description: Hex-encoded reserve box ID
          example: "f1e2d3c4b5a697887766554433221100ffeeddccbbaa99887766554433221100"
        owner_pubkey:
          type: string
          description: Hex-encoded owner public key
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        collateral_amount:
          type: integer
          format: uint64
          description: Amount of collateral in nanoERG or raw token units
          example: 2500000000
        total_debt:
          type: integer
          format: uint64
          description: Total debt issued against this reserve
          example: 1200000000
        tracker_nft_id:
          type: string
          description: Tracker NFT ID (hex-encoded)
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"
        last_updated_height:
          type: integer
          format: uint64
          description: Last blockchain height when reserve was updated
          example: 1250
        last_updated_timestamp:
          type: integer
          format: uint64
          description: Last update timestamp
          example: 1672531200
        collateralization_ratio:
          type: number
          format: float
          description: Current collateralization ratio
          example: 2.08
        refund_initiation_height:
          type: integer
          format: uint64
          description: Blockchain height at which refund was initiated (0 if not initiated)
          example: 0

    CreateReserveRequest:
      type: object
      description: Request body for creating a reserve
      required:
        - nft_id
        - owner_pubkey
        - erg_amount
      properties:
        nft_id:
          type: string
          description: Hex-encoded reserve NFT ID
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"
        owner_pubkey:
          type: string
          description: Hex-encoded owner public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        erg_amount:
          type: integer
          format: uint64
          description: ERG value for the reserve box in nanoERG
          example: 2500000000
        token_amount:
          type: integer
          format: uint64
          default: 0
          description: Amount of reserve token to lock in the reserve (raw token units)
          example: 1000000000
        token_id:
          type: string
          default: ""
          description: Reserve token ID (hex-encoded, 32 bytes) for token-backed reserves
          example: "b1c2d3e4f5061728394051627384950617283940516273849506172839405162"

    ReserveCreationResponse:
      type: object
      description: Response for reserve creation formatted for Ergo node's /wallet/payment/send API
      properties:
        requests:
          type: array
          description: Payment requests for the reserve creation transaction
          items:
            $ref: '#/components/schemas/ReservePaymentRequest'
        fee:
          type: integer
          format: uint64
          description: Transaction fee in nanoERG
          example: 1100000
        change_address:
          type: string
          description: Owner's change address (derived from the owner pubkey). Submit the `requests` array to the owner's own Ergo node `/wallet/payment/send`.
          example: "9fD5TqXvN8Z3k2LmP7wR4sY6uH1jC8bA0eG9iK3oM5nQ2xV"

    ReservePaymentRequest:
      type: object
      description: Individual payment request for reserve creation
      properties:
        address:
          type: string
          description: Target P2S address for the reserve box
          example: "2Z4YBkDsDvQj8BX7xiySF9jLUCuYUHjbkY78Zn7aQGjftGPKvUvtbNE7"
        value:
          type: integer
          format: uint64
          description: Box value in nanoERG
          example: 2500000000
        assets:
          type: array
          description: Assets to include in the reserve box
          items:
            $ref: '#/components/schemas/Asset'
        registers:
          type: object
          additionalProperties:
            type: string
          description: Register values for the reserve box
          example:
            R4: "010101010101010101010101010101010101010101010101010101010101010101"
            R5: "64abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"

    Asset:
      type: object
      description: Asset in a reserve payment request
      properties:
        token_id:
          type: string
          description: Hex-encoded token ID
          example: "b1c2d3e4f5061728394051627384950617283940516273849506172839405162"
        amount:
          type: integer
          format: uint64
          description: Token amount in raw units
          example: 1000000000

    # Redemption Schemas
    RedeemRequest:
      type: object
      description: Redemption request
      required:
        - issuer_pubkey
        - recipient_pubkey
        - amount
        - timestamp
        - issuer_signature
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        amount:
          type: integer
          format: uint64
          description: Amount to redeem in nanoERG
          example: 500000000
        timestamp:
          type: integer
          format: uint64
          description: Timestamp of the note being redeemed
          example: 1234567890
        reserve_box_id:
          type: string
          default: ""
          description: Reserve box ID (optional - server will lookup if not provided)
          example: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        recipient_address:
          type: string
          default: ""
          description: Recipient address for redemption output (optional - server will derive from pubkey if not provided)
          example: "9fD5TqXvN8Z3k2LmP7wR4sY6uH1jC8bA0eG9iK3oM5nQ2xV"
        issuer_signature:
          type: string
          description: Hex-encoded Schnorr signature from issuer (130 characters = 65 bytes)
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"
        emergency:
          type: boolean
          default: false
          description: Whether this is an emergency redemption
          example: false


        denomination:
          type: string
          description: >-
            Denomination of the note: "erg" or "token:<64-hex>". When omitted, the server
            resolves to the pair's existing note's denomination when unambiguous, else "erg".
          example: "erg"
    CompleteRedemptionRequest:
      type: object
      description: Request body for completing a redemption
      required:
        - redemption_id
        - issuer_pubkey
        - recipient_pubkey
        - redeemed_amount
      properties:
        redemption_id:
          type: string
          description: Unique redemption identifier
          example: "redeem_0101010101010101_0202020202020202"
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        redeemed_amount:
          type: integer
          format: uint64
          description: Amount redeemed in this transaction
          example: 500000000
        new_already_redeemed:
          type: integer
          format: uint64
          nullable: true
          description: Optional explicit cumulative reserve-tree value
          example: 500000000


        denomination:
          type: string
          description: >-
            Denomination of the note: "erg" or "token:<64-hex>". When omitted, the server
            resolves to the pair's existing note's denomination when unambiguous, else "erg".
          example: "erg"
    RedeemResponse:
      type: object
      description: Redemption response
      properties:
        redemption_id:
          type: string
          description: Unique redemption identifier
          example: "redeem_0101010101010101_0202020202020202"
        amount:
          type: integer
          format: uint64
          description: Amount being redeemed
          example: 500000000
        timestamp:
          type: integer
          format: uint64
          description: Redemption timestamp
          example: 1672531200
        proof_available:
          type: boolean
          description: Whether proof is available
          example: true
        transaction_pending:
          type: boolean
          description: Whether redemption transaction is pending
          example: false
        transaction_data:
          $ref: '#/components/schemas/TransactionData'
        transaction_bytes:
          type: string
          nullable: true
          description: Raw Ergo transaction JSON (hex encoded) that can be signed and submitted
          example: "a1b2c3d4e5f6"

    TransactionData:
      type: object
      description: Transaction data that can be submitted to an Ergo node
      properties:
        address:
          type: string
          description: Target address for the transaction
          example: "9fD5TqXvN8Z3k2LmP7wR4sY6uH1jC8bA0eG9iK3oM5nQ2xV"
        value:
          type: integer
          format: uint64
          description: Value in nanoERG
          example: 500000000
        registers:
          type: object
          additionalProperties:
            type: string
          description: Register values
          example:
            R4: "010101010101010101010101010101010101010101010101010101010101010101"
        assets:
          type: array
          description: Assets to include in transaction
          items:
            $ref: '#/components/schemas/TokenData'
        fee:
          type: integer
          format: uint64
          description: Transaction fee
          example: 1100000

    TokenData:
      type: object
      description: Token/asset data for a transaction
      properties:
        token_id:
          type: string
          description: Hex-encoded token ID
          example: "b1c2d3e4f5061728394051627384950617283940516273849506172839405162"
        amount:
          type: integer
          format: uint64
          description: Token amount in raw units
          example: 1000000000

    # Tracker Signature Schemas
    TrackerSignatureRequest:
      type: object
      description: Request for tracker signature on redemption
      required:
        - issuer_pubkey
        - recipient_pubkey
        - total_debt
        - timestamp
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        total_debt:
          type: integer
          format: uint64
          description: Must equal the stored note's total debt; mismatches are rejected with 409
          example: 1000000000
        timestamp:
          type: integer
          format: uint64
          description: Must equal the stored note's payment timestamp; mismatches are rejected with 409
          example: 1234567890000
        emergency:
          type: boolean
          default: false
          description: Whether this is an emergency redemption
          example: false


        denomination:
          type: string
          description: >-
            Denomination of the note: "erg" or "token:<64-hex>". When omitted, the server
            resolves to the pair's existing note's denomination when unambiguous, else "erg".
          example: "erg"
    TrackerSignatureResponse:
      type: object
      description: Tracker signature response
      properties:
        success:
          type: boolean
          description: Whether signature generation was successful
          example: true
        tracker_signature:
          type: string
          description: Hex-encoded Schnorr signature (130 characters)
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404"
        tracker_pubkey:
          type: string
          description: Hex-encoded tracker public key
          example: "030303030303030303030303030303030303030303030303030303030303030303"
        message_signed:
          type: string
          description: Hex-encoded message that was signed
          example: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        is_emergency:
          type: boolean
          nullable: true
          description: Whether this was an emergency redemption
          example: false

    # Proof Schemas
    ProofResponse:
      type: object
      description: Proof response for a specific IOU note
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        proof_data:
          type: string
          description: Hex-encoded AVL proof data
          example: "0102030405060708"
        tracker_state_digest:
          type: string
          description: Tracker state digest at proof generation
          example: "64abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        block_height:
          type: integer
          format: uint64
          description: Blockchain height when proof was generated
          example: 1500
        timestamp:
          type: integer
          format: uint64
          description: Proof generation timestamp
          example: 1672531200

    TrackerProofData:
      type: object
      description: Tracker lookup proof data
      properties:
        key:
          type: string
          description: Hex-encoded AVL tree key (blake2b256(ownerKey || receiverKey))
          example: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        value:
          type: string
          description: 'Hex-encoded value: totalDebt as 8-byte big-endian'
          example: "000000003b9aca00"
        proof:
          type: string
          description: Hex-encoded AVL proof bytes
          example: "0102030405060708"
        total_debt:
          type: integer
          format: uint64
          description: Total debt as integer
          example: 1000000000
        tracker_state_digest:
          type: string
          description: Current tracker state digest (R5 register value)
          example: "64abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"

    ReserveProofData:
      type: object
      description: Reserve lookup proof data
      properties:
        key:
          type: string
          description: Hex-encoded AVL tree key (blake2b256(ownerKey || receiverKey))
          example: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        value:
          type: string
          description: 'Hex-encoded value: already_redeemed as 8-byte big-endian'
          example: "000000003b9aca00"
        proof:
          type: string
          nullable: true
          description: Hex-encoded AVL proof bytes (null for first redemption)
          example: "0102030405060708"
        already_redeemed:
          type: integer
          format: uint64
          description: Already redeemed amount as integer
          example: 500000000
        is_first_redemption:
          type: boolean
          description: Whether this is the first redemption (no lookup proof needed)
          example: false
        insert_proof:
          type: string
          description: Hex-encoded AVL insert proof for the new already_redeemed amount
          example: "0807060504030201"
        new_reserve_state_digest:
          type: string
          description: Updated reserve state digest after the insert operation (R5 register value)
          example: "64fedcba0123456789abcdef0123456789abcdef0123456789abcdef0123456789"

    RedemptionPreparationRequest:
      type: object
      description: Request for redemption preparation
      required:
        - issuer_pubkey
        - recipient_pubkey
        - amount
        - timestamp
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        amount:
          type: integer
          format: uint64
          description: Intended redemption amount in nanoERG. Used only for the acceptance-policy check; the signed message always covers the stored note's cumulative debt
          example: 500000000
        timestamp:
          type: integer
          format: uint64
          description: Must equal the stored note's payment timestamp; mismatches are rejected with 409
          example: 1234567890000
        emergency:
          type: boolean
          default: false
          description: Whether this is an emergency redemption (exempt from the acceptance-policy check)
          example: false


        denomination:
          type: string
          description: >-
            Denomination of the note: "erg" or "token:<64-hex>". When omitted, the server
            resolves to the pair's existing note's denomination when unambiguous, else "erg".
          example: "erg"
    RedemptionPreparationResponse:
      type: object
      description: Legacy redemption preparation response
      properties:
        redemption_id:
          type: string
          description: Unique redemption identifier
          example: "redeem_0101010101010101_0202020202020202"
        avl_proof:
          type: string
          description: Hex-encoded combined AVL proof
          example: "0102030405060708"
        tracker_signature:
          type: string
          description: Hex-encoded tracker Schnorr signature
          example: "0404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404"
        tracker_pubkey:
          type: string
          description: Hex-encoded tracker public key
          example: "030303030303030303030303030303030303030303030303030303030303030303"
        tracker_state_digest:
          type: string
          description: Tracker state digest
          example: "64abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        block_height:
          type: integer
          format: uint64
          description: Current blockchain height
          example: 1500

    RedemptionBuildRequest:
      type: object
      description: Request to build a redemption transaction
      required:
        - issuer_pubkey
        - recipient_pubkey
        - amount
        - timestamp
        - issuer_signature
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer (reserve owner) public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient (creditor) public key (66 characters)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        amount:
          type: integer
          format: uint64
          description: Amount to redeem in nanoERG
          example: 500000000
        timestamp:
          type: integer
          format: uint64
          description: Legacy field, ignored by the server — the stored note's payment timestamp is used for the signature, context extension, and reserve tree value
          example: 1234567890000
        issuer_signature:
          type: string
          description: Hex-encoded issuer's 65-byte Schnorr signature
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"
        emergency:
          type: boolean
          default: false
          description: Whether this is an emergency redemption
          example: false
        tracker_box_id:
          type: string
          nullable: true
          description: Optional tracker box id; fetched from storage if omitted
          example: "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        change_address:
          type: string
          nullable: true
          description: Deprecated and ignored. Change always goes to the owner of the tracker's selected fee box (falling back to the configured change address); a caller-supplied address is never used.
          example: "9fD5TqXvN8Z3k2LmP7wR4sY6uH1jC8bA0eG9iK3oM5nQ2xV"


        denomination:
          type: string
          description: "Denomination of the debt: erg or token:<64-hex>."
          example: "erg"
    RedemptionBuildResponse:
      type: object
      description: Response for a built redemption transaction
      properties:
        unsigned_tx:
          type: object
          description: Node-canonical unsigned transaction JSON
        partial_tx:
          type: object
          description: Fee-signed transaction JSON (reserve input proof empty)
        input_box_binaries:
          type: array
          description: Sigma-serialized input boxes (hex), in transaction-input order
          items:
            type: string
          example: ["a1b2c3d4", "e5f60718"]
        data_box_binaries:
          type: array
          description: Sigma-serialized data-input boxes (hex)
          items:
            type: string
          example: ["91a2b3c4"]
        headers:
          type: array
          description: Last 10 block headers for deriving PreHeader and ErgoStateContext
          items:
            type: object
        reserve_box_id:
          type: string
          description: Reserve box ID used as input
          example: "f1e2d3c4b5a697887766554433221100ffeeddccbbaa99887766554433221100"
        tracker_box_id:
          type: string
          description: Tracker box ID used as data input
          example: "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        reserve_output_value:
          type: integer
          format: uint64
          description: Value of the reserve output box after redemption
          example: 2000000000
        recipient_output_value:
          type: integer
          format: uint64
          description: Value sent to the recipient output
          example: 500000000
        total_debt:
          type: integer
          format: uint64
          description: Total debt for the note
          example: 1000000000
        change_amount:
          type: integer
          format: uint64
          description: Change amount returned to the tracker
          example: 123900000
        change_address:
          type: string
          description: Address receiving change (always derived from the tracker's own wallet)
          example: "9fD5TqXvN8Z3k2LmP7wR4sY6uH1jC8bA0eG9iK3oM5nQ2xV"
        recipient_address:
          type: string
          description: Recipient address for the redemption output
          example: "9fD5TqXvN8Z3k2LmP7wR4sY6uH1jC8bA0eG9iK3oM5nQ2xV"
        is_first_redemption:
          type: boolean
          description: Whether this is the first redemption for this note
          example: false
        fee:
          type: integer
          format: uint64
          description: Transaction fee
          example: 1100000
        new_already_redeemed:
          type: integer
          format: uint64
          description: Cumulative already_redeemed value this redemption inserts into the reserve tree
          example: 500000000

    RedemptionSubmitRequest:
      type: object
      description: Request to submit a fully signed redemption transaction
      required:
        - signed_tx
        - issuer_pubkey
        - recipient_pubkey
        - redeemed_amount
        - new_already_redeemed
      properties:
        signed_tx:
          type: object
          description: Fully signed transaction JSON
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        redeemed_amount:
          type: integer
          format: uint64
          description: Amount redeemed by this transaction in nanoERG
          example: 500000000
        new_already_redeemed:
          type: integer
          format: uint64
          description: Cumulative reserve-tree already_redeemed value from the build response
          example: 500000000

    RedemptionSubmitResponse:
      type: object
      description: Response for a submitted redemption transaction
      properties:
        tx_id:
          type: string
          description: Transaction ID of the broadcast redemption transaction
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"

    # Status / Tracker Schemas
    KeyStatusDenomination:
      type: object
      description: Per-denomination debt/collateral status (never summed across denominations)
      properties:
        denomination:
          type: string
          description: '"erg" or "token:<64-hex>"'
          example: "erg"
        symbol:
          type: string
          example: "ERG"
        decimals:
          type: integer
          example: 9
        total_debt:
          type: integer
          format: uint64
          description: Outstanding debt in this denomination (raw units)
          example: 1500000000
        collateral:
          type: integer
          format: uint64
          description: Collateral backing this denomination (raw units)
          example: 3000000000
        collateralization_ratio:
          type: number
          format: float
          example: 2.0
        note_count:
          type: integer
          example: 5
        reserve_box_id:
          type: string
          nullable: true
          example: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        has_pending_refund:
          type: boolean
          example: false

    KeyStatusResponse:
      type: object
      description: >-
        Key status information, broken down per denomination. Debt and collateral
        are never summed across denominations (specs/ergo/multi_collateral_reserves.md).
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        note_count:
          type: integer
          description: Total number of notes across all denominations
          example: 5
        last_updated:
          type: integer
          format: uint64
          example: 1672531200
        has_pending_refund:
          type: boolean
          example: false
        denominations:
          type: array
          items:
            $ref: '#/components/schemas/KeyStatusDenomination'
    TrackerBoxIdResponse:
      type: object
      description: Latest confirmed tracker box ID
      properties:
        tracker_box_id:
          type: string
          description: Latest tracker box ID
          example: "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        timestamp:
          type: integer
          format: uint64
          description: Timestamp when the box was confirmed
          example: 1672531200
        height:
          type: integer
          format: uint64
          description: Blockchain height when the box was confirmed
          example: 1500

    TrackerStateResponse:
      type: object
      description: Tracker state response showing local, confirmed, and pending digests
      properties:
        local_digest:
          type: string
          description: Local tracker AVL tree digest
          example: "64abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        confirmed_digest:
          type: string
          nullable: true
          description: Confirmed tracker AVL tree digest
          example: "64abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        confirmed_box_id:
          type: string
          nullable: true
          description: Box ID of the confirmed tracker box
          example: "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        confirmed_height:
          type: integer
          format: uint64
          nullable: true
          description: Blockchain height at which the tracker box was confirmed
          example: 1500
        pending_digest:
          type: string
          nullable: true
          description: Pending tracker AVL tree digest
          example: "64fedcba0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        pending_tx_id:
          type: string
          nullable: true
          description: Transaction ID of the pending tracker update
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"
        pending_submitted_height:
          type: integer
          format: uint64
          nullable: true
          description: Height at which the pending transaction was submitted
          example: 1501
        tracker_box_id:
          type: string
          nullable: true
          description: Latest tracker box ID
          example: "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

    PendingTxResponse:
      type: object
      description: Pending tracker update transaction response
      properties:
        pending_tx_id:
          type: string
          nullable: true
          description: Pending transaction ID
          example: "a1b2c3d4e5f67788990011223344556677889900112233445566778899001122"
        pending_digest:
          type: string
          nullable: true
          description: Pending tracker digest
          example: "64fedcba0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        submitted_height:
          type: integer
          format: uint64
          nullable: true
          description: Height at which the pending transaction was submitted
          example: 1501

    # Acceptance Schemas
    CheckAcceptanceRequest:
      type: object
      description: Request for checking note acceptance
      required:
        - issuer_pubkey
        - total_debt
      properties:
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key (33 bytes)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        total_debt:
          type: integer
          format: uint64
          description: Total cumulative debt amount
          example: 1000000000
        recipient_pubkey:
          type: string
          nullable: true
          description: Optional hex-encoded recipient public key for per-recipient policy lookup
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"


        denomination:
          type: string
          description: >-
            Denomination of the note: "erg" or "token:<64-hex>". When omitted, the server
            resolves to the pair's existing note's denomination when unambiguous, else "erg".
          example: "erg"
    CheckAcceptanceResponse:
      type: object
      description: Response for checking note acceptance
      properties:
        acceptable:
          type: boolean
          description: Whether the note is acceptable
          example: true
        reason:
          type: string
          nullable: true
          description: Optional reason for rejection
          example: "Collateralization ratio below threshold"

    UploadPolicyRequest:
      type: object
      description: Request for uploading an acceptance policy
      required:
        - recipient_pubkey
        - policy_json
        - signature
      properties:
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key (33 bytes)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        policy_json:
          type: string
          description: Policy JSON string (serialized AcceptanceConfig)
          example: '{"max_debt_per_issuer": 10000000000, "min_collateralization_ratio": 1.5}'
        signature:
          type: string
          description: Schnorr signature over policy_json (65 bytes, hex encoded)
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"

    UploadPolicyResponse:
      type: object
      description: Response for uploading an acceptance policy
      properties:
        uploaded_at:
          type: integer
          format: uint64
          description: Unix timestamp when the policy was uploaded
          example: 1672531200
        policy_hash:
          type: string
          description: Hash of the policy for verification
          example: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"

    GetPolicyResponse:
      type: object
      description: Response for getting a recipient's acceptance policy
      properties:
        recipient_pubkey:
          type: string
          description: Recipient public key (hex encoded)
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        policy_json:
          type: string
          description: Policy JSON string
          example: '{"max_debt_per_issuer": 10000000000, "min_collateralization_ratio": 1.5}'
        signature:
          type: string
          description: Hex-encoded Schnorr signature (130 characters = 65 bytes)
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"
        uploaded_at:
          type: integer
          format: uint64
          description: Unix timestamp when the policy was uploaded
          example: 1672531200

    # Event Schemas
    EventType:
      oneOf:
        - type: object
          description: Generic tracker event type
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - NoteUpdated
                - ReserveCreated
                - ReserveToppedUp
                - ReserveRedeemed
                - ReserveSpent
                - Commitment
              example: "NoteUpdated"
        - type: object
          description: Collateral alert event with ratio
          required:
            - type
            - ratio
          properties:
            type:
              type: string
              enum:
                - CollateralAlert
              example: "CollateralAlert"
            ratio:
              type: number
              format: float
              description: Collateralization ratio that triggered the alert
              example: 0.8
      description: Tagged enum representing the type of tracker event

    TrackerEvent:
      type: object
      description: Unified tracker event structure
      properties:
        id:
          type: integer
          format: uint64
          description: Event ID
          example: 1
        event_type:
          $ref: '#/components/schemas/EventType'
        timestamp:
          type: integer
          format: uint64
          description: Event timestamp
          example: 1234567890
        issuer_pubkey:
          type: string
          nullable: true
          description: Hex-encoded issuer public key
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        recipient_pubkey:
          type: string
          nullable: true
          description: Hex-encoded recipient public key
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        amount:
          type: integer
          format: uint64
          nullable: true
          description: Amount involved in the event
          example: 1000
        reserve_box_id:
          type: string
          nullable: true
          description: Reserve box ID for reserve events
          example: "box1234567890abcdef"
        collateral_amount:
          type: integer
          format: uint64
          nullable: true
          description: Collateral amount for reserve events
          example: 1000000000
        redeemed_amount:
          type: integer
          format: uint64
          nullable: true
          description: Redeemed amount for redemption events
          example: 500000000
        height:
          type: integer
          format: uint64
          nullable: true
          description: Blockchain height when event occurred
          example: 1000

    # Config Schemas
    ReserveTokenConfigResponse:
      type: object
      description: Reserve token configuration response
      properties:
        reserve_token_id:
          type: string
          nullable: true
          description: Reserve token ID (hex-encoded) if configured
          example: "b1c2d3e4f5061728394051627384950617283940516273849506172839405162"
        reserve_token_decimals:
          type: integer
          description: Number of decimals for the reserve token
          example: 6
        basis_token_reserve_contract_p2s:
          type: string
          description: P2S address for the token-backed reserve contract
          example: "2Z4YBkDsDvQj8BX7xiySF9jLUCuYUHjbkY78Zn7aQGjftGPKvUvtbNE7"

    # Response Wrappers
    ApiResponseNotes:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/SerializableIouNote'

    ApiResponseNotesWithAge:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/SerializableIouNoteWithAge'

    ApiResponseNote:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SerializableIouNote'

    ApiResponseNoteState:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/NoteStateResponse'

    ApiResponseReserves:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/SerializableReserveInfo'

    ApiResponseQuarantinedReserves:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/SerializableQuarantinedReserve'

    SerializableQuarantinedReserve:
      type: object
      description: >-
        A reserve contract box rejected by scanner admission control
        (issue #19). Quarantined boxes are never tracked.
      properties:
        box_id:
          type: string
          description: Hex-encoded box ID
          example: "f1e2d3c4b5a697887766554433221100ffeeddccbbaa99887766554433221100"
        owner_pubkey:
          type: string
          description: Owner public key from R4 (hex, 66 characters)
          example: "010101010101010101010101010101010101010101010101010101010101010101"
        denomination:
          type: string
          description: '"ERG" or the hex-encoded collateral token id'
          example: "ERG"
        reason:
          type: string
          description: Why the box was quarantined
        quarantined_at:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when the box was quarantined
          example: 1762041600000

    ApiResponseReserve:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SerializableReserveInfo'

    ApiResponseReserveCreation:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/ReserveCreationResponse'

    ApiResponseEvents:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/TrackerEvent'

    ApiResponseKeyStatus:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/KeyStatusResponse'

    ApiResponseRedeem:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/RedeemResponse'

    ApiResponseProof:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/ProofResponse'

    ApiResponseTrackerProof:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/TrackerProofData'

    ApiResponseReserveProof:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/ReserveProofData'

    ApiResponseTrackerSignature:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/TrackerSignatureResponse'

    ApiResponseRedemptionPreparation:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/RedemptionPreparationResponse'

    ApiResponseRedemptionBuild:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/RedemptionBuildResponse'

    ApiResponseRedemptionSubmit:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/RedemptionSubmitResponse'

    ApiResponseTrackerState:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/TrackerStateResponse'

    ApiResponsePendingTx:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/PendingTxResponse'

    ApiResponseTrackerBoxId:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/TrackerBoxIdResponse'

    ApiResponseCheckAcceptance:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/CheckAcceptanceResponse'

    ApiResponseUploadPolicy:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/UploadPolicyResponse'

    ApiResponseGetPolicy:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/GetPolicyResponse'

    ApiResponseReserveTokenConfig:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/ReserveTokenConfigResponse'

  responses:
    BadRequest:
      description: Bad request - invalid input parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseError'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseEmpty'

tags:
  - name: Health
    description: Health check endpoints
  - name: Notes
    description: IOU note management
  - name: Reserves
    description: Reserve tracking and management
  - name: Events
    description: Tracker event monitoring
  - name: Status
    description: System status and monitoring
  - name: Redemption
    description: Note redemption operations
  - name: Proofs
    description: Proof generation and verification
  - name: Acceptance
    description: Acceptance policy management
  - name: Tracker
    description: Tracker state and operations
  - name: Config
    description: Server configuration