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

paths:
  /:
    get:
      summary: Health check endpoint
      description: Returns a simple message to verify the API is running
      operationId: root
      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
      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
          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
      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
      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"
      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'

  /reserves/issuer/{pubkey}:
    get:
      summary: Get reserves by issuer
      description: Retrieve all reserves managed by a specific issuer
      operationId: getReservesByIssuer
      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'

  /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
      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
      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'

  /proof:
    get:
      summary: Get proof for a specific note
      description: Generate and retrieve a proof for a specific IOU note against the current tracker state
      operationId: getProof
      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"
      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 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"
      responses:
        '200':
          description: Successfully generated tracker proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackerProofData'
        '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 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"
      responses:
        '200':
          description: Successfully generated reserve proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReserveProofData'
        '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 Schnorr signature from tracker for redemption.
        The tracker signs: key || totalDebt || timestamp
        where key = blake2b256(ownerKey || receiverKey)
      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/TrackerSignatureResponse'
        '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'

  /proof/redemption:
    get:
      summary: Get comprehensive redemption proof
      description: |
        Get all proofs needed for redemption in a single request.
        Includes tracker lookup proof, reserve lookup proof, and reserve insert proof.
      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
      responses:
        '200':
          description: Successfully generated redemption proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionProofResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'

components:
  schemas:
    # Request/Response Structures
    CreateNoteRequest:
      type: object
      required:
        - recipient_pubkey
        - amount
        - timestamp
        - signature
        - issuer_pubkey
      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: 1000
        timestamp:
          type: integer
          format: uint64
          description: Unix timestamp when the note was created (tracked for record-keeping, not used in signing)
          minimum: 0
          example: 1234567890
        signature:
          type: string
          description: Hex-encoded Schnorr signature (130 characters)
          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"

    SerializableIouNote:
      type: object
      description: Serializable IOU note for API responses
      properties:
        recipient_pubkey:
          type: string
          description: Hex-encoded recipient public key
          example: "020202020202020202020202020202020202020202020202020202020202020202"
        amount:
          type: integer
          format: uint64
          description: Total cumulative debt amount
          example: 1000
        timestamp:
          type: integer
          format: uint64
          description: Creation timestamp (tracked for record-keeping, not used in signing)
          example: 1234567890
        signature:
          type: string
          description: Hex-encoded Schnorr signature (signs key || totalDebt || timestamp)
          example: "0303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"

    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
          example: 2500000000
        total_debt:
          type: integer
          format: uint64
          description: Total debt issued against this reserve
          example: 1200000000
        tracker_nft_id:
          type: string
          nullable: true
          description: Optional tracker NFT ID
          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

    EventType:
      type: string
      description: Type of tracker event
      enum:
        - NoteUpdated
        - ReserveCreated
        - ReserveToppedUp
        - ReserveRedeemed
        - ReserveSpent
        - Commitment
        - CollateralAlert

    TrackerEvent:
      type: object
      description: Unified tracker event structure
      properties:
        id:
          type: integer
          format: uint64
          description: Event ID
          example: 1
        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

    KeyStatusResponse:
      type: object
      description: Key status information
      properties:
        total_debt:
          type: integer
          format: uint64
          description: Total debt issued by this key
          example: 1500000000
        collateral:
          type: integer
          format: uint64
          description: Total collateral backing the debt
          example: 3000000000
        collateralization_ratio:
          type: number
          format: float
          description: Current collateralization ratio
          example: 2.0
        note_count:
          type: integer
          description: Number of outstanding notes
          example: 5
        last_updated:
          type: integer
          format: uint64
          description: Last update timestamp
          example: 1672531200
        issuer_pubkey:
          type: string
          description: Hex-encoded issuer public key
          example: "010101010101010101010101010101010101010101010101010101010101010101"

    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
          example: 500000000
        timestamp:
          type: integer
          format: uint64
          description: Timestamp of the note being redeemed
          example: 1234567890
        reserve_box_id:
          type: string
          description: Reserve box ID (optional - server will lookup if not provided)
          example: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        tracker_box_id:
          type: string
          description: Tracker box ID (optional - server will fetch if not provided)
          example: "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        tracker_nft_id:
          type: string
          description: Tracker NFT ID (optional - server will fetch if not provided)
          example: "fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321"
        current_height:
          type: integer
          format: uint64
          description: Current blockchain height (optional - server will fetch if not provided)
          example: 1000000
        recipient_address:
          type: string
          description: Recipient address (optional - server will derive from pubkey if not provided)
          example: "9fD5TqXvN8Z3k2LmP7wR4sY6uH1jC8bA0eG9iK3oM5nQ2xV"
        change_address:
          type: string
          description: Change address (optional - server will derive from tracker 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
          description: Whether this is an emergency redemption (after 3 days tracker unavailability)
          default: false
          example: false
        tracker_signature:
          type: string
          description: Hex-encoded Schnorr signature from tracker (optional - server will generate if not provided)
          pattern: '^[0-9a-fA-F]{130}$'
          example: "0404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404"

    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

    ProofResponse:
      type: object
      description: Proof response
      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 proof data
          example: "proof_0101010101010101_0202020202020202"
        tracker_state_digest:
          type: string
          description: Tracker state digest at proof generation
          example: "mock_digest_1234567890abcdef"
        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

    # 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)

    # Tracker Signature Request/Response
    TrackerSignatureRequest:
      type: object
      description: Request for tracker signature on redemption
      required:
        - issuer_pubkey
        - recipient_pubkey
        - total_debt
      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: Total cumulative debt amount
          example: 1000000000
        emergency:
          type: boolean
          description: Whether this is an emergency redemption
          default: false
          example: false

    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)
          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
          description: Whether this was an emergency redemption
          example: false

    # Proof Data Structures
    TrackerProofData:
      type: object
      description: Tracker lookup proof data
      properties:
        key:
          type: string
          description: Hex-encoded AVL tree key
          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
          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

    RedemptionProofResponse:
      type: object
      description: Comprehensive redemption proof response
      properties:
        success:
          type: boolean
          description: Whether proof generation was successful
          example: true
        data:
          type: object
          description: Proof data
          properties:
            tracker_lookup_proof:
              type: string
              description: Hex-encoded tracker lookup proof
              example: "0102030405060708"
            reserve_lookup_proof:
              type: string
              nullable: true
              description: Hex-encoded reserve lookup proof (null for first redemption)
              example: "0102030405060708"
            reserve_insert_proof:
              type: string
              description: Hex-encoded reserve insert proof
              example: "0102030405060708"
            tracker_state_digest:
              type: string
              description: Tracker state digest
              example: "64abcdef"
            reserve_state_digest:
              type: string
              description: Reserve state digest
              example: "64fedcba"
            total_debt:
              type: integer
              format: uint64
              description: Total debt amount
              example: 1000000000
            already_redeemed:
              type: integer
              format: uint64
              description: Already redeemed amount
              example: 0
            proof_valid:
              type: boolean
              description: Whether the proof is valid
              example: true
            is_first_redemption:
              type: boolean
              description: Whether this is the first redemption
              example: true

    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"

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

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

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

    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'

  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