openapi: 3.0.3

info:
  title: Umbra Relayer API
  description: |
    The Umbra relayer submits claim transactions on your behalf so your wallet
    never appears as the fee payer on-chain, preserving privacy.

    ## Response Format

    All endpoints return JSON (`application/json`).

    ## Rate Limiting

    All endpoints are subject to rate limiting. Exceeded limits return `429 Too Many Requests`.

    ## Error Format

    All error responses use this structure:
    ```json
    {
      "error": {
        "code": "ERROR_CODE",
        "message": "Human-readable description"
      }
    }
    ```
  version: 0.1.0
  contact:
    name: Umbra Protocol

servers:
  - url: https://relayer.api.umbraprivacy.com
    description: Mainnet
  - url: https://relayer.api-devnet.umbraprivacy.com
    description: Devnet

tags:
  - name: relayer
    description: Relayer identity and configuration
  - name: claims
    description: Claim submission and status polling
  - name: health
    description: Service health checks

paths:
  /v1/relayer/info:
    get:
      operationId: getRelayerInfo
      summary: Get relayer info
      description: |
        Returns the relayer's on-chain identity, supported mints, and active stealth pool indices.
        Use this to verify the relayer is operational and supports the mint you want to claim.
      tags: [relayer]
      responses:
        "200":
          description: Relayer information
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                    description: Base58-encoded Solana public key of the relayer's fee payer account.
                  supported_mints:
                    type: array
                    items:
                      type: string
                    description: Base58-encoded mint addresses the relayer accepts claims for.
                  active_stealth_pool_indices:
                    type: array
                    items:
                      type: string
                    description: Stealth pool indices the relayer monitors.
              example:
                address: "Re1ayerPubkeyHere111111111111111111111111"
                supported_mints:
                  - "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
                  - "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"
                  - "So11111111111111111111111111111111111111112"
                active_stealth_pool_indices:
                  - "0"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/claims:
    post:
      operationId: submitClaim
      summary: Submit a claim request
      description: |
        Submits a UTXO claim request to the relayer for asynchronous processing. The relayer
        validates the request, builds the on-chain transactions, and submits them.

        Returns immediately with a `request_id` for polling via `GET /v1/claims/{request_id}`.

        **Note:** This endpoint is designed to be called by the SDK, not directly. The request
        body contains cryptographic proof data that must be generated by the SDK's claim functions.
      tags: [claims]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClaimRequest"
      responses:
        "202":
          description: Claim accepted and queued for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    format: uuid
                    description: UUID for polling the claim status.
                  status:
                    type: string
                    enum: [received]
                    description: Always "received".
              example:
                request_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                status: "received"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid_body:
                  summary: Malformed JSON
                  value:
                    error:
                      code: "INVALID_REQUEST_BODY"
                      message: "Failed to parse request body"
                validation_failed:
                  summary: Validation error
                  value:
                    error:
                      code: "VALIDATION_FAILED"
                      message: "utxo_slot_data must not be empty"
        "409":
          description: Duplicate nullifier
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: "DUPLICATE_OFFSET"
                  message: "Nullifier already reserved by another claim"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/claims/{request_id}:
    get:
      operationId: getClaimStatus
      summary: Get claim status
      description: |
        Returns the current status of a previously submitted claim request.

        The SDK polls this endpoint automatically with a 3-second interval. You only
        need to call it directly if building a custom integration.

        **Terminal statuses:** `completed`, `failed`, `timed_out`
      tags: [claims]
      parameters:
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: UUID returned from `POST /v1/claims`.
      responses:
        "200":
          description: Claim status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClaimStatus"
              examples:
                in_progress:
                  summary: Claim in progress
                  value:
                    request_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    status: "awaiting_callback"
                    variant: "encrypted_balance"
                    resolved_variant: "claim_into_existing_shared_balance_v11"
                    tx_signature: "5KtP...base58..."
                    callback_signature: null
                    computation_account: "Comp...base58..."
                    failure_reason: null
                    created_at: "2026-03-31T12:00:00Z"
                    updated_at: "2026-03-31T12:00:15Z"
                completed:
                  summary: Claim completed
                  value:
                    request_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    status: "completed"
                    variant: "encrypted_balance"
                    resolved_variant: "claim_into_existing_shared_balance_v11"
                    tx_signature: "5KtP...base58..."
                    callback_signature: "7RmQ...base58..."
                    computation_account: "Comp...base58..."
                    failure_reason: null
                    created_at: "2026-03-31T12:00:00Z"
                    updated_at: "2026-03-31T12:01:30Z"
        "404":
          description: Claim not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: "NOT_FOUND"
                  message: "claim not found: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/health:
    get:
      operationId: getRelayerHealth
      summary: Relayer health check
      description: Returns a simple health status for load balancers and monitoring.
      tags: [health]
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok]
              example:
                status: "ok"

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable description.

    ClaimRequest:
      type: object
      required:
        - variant
        - user_pubkey
        - mint
        - stealth_pool_index
        - max_utxo_capacity
        - optional_data
        - proof_account_data
        - utxo_slot_data
      properties:
        variant:
          type: string
          enum: [encrypted_balance, public_balance]
          description: Claim target — encrypted token account or public ATA.
        user_pubkey:
          type: string
          description: Base58-encoded Solana public key of the claiming user.
        mint:
          type: string
          description: Base58-encoded token mint address.
        stealth_pool_index:
          type: integer
          format: int64
          description: Index of the stealth pool containing the UTXOs.
        max_utxo_capacity:
          type: integer
          minimum: 1
          description: Maximum number of UTXOs in this claim batch.
        optional_data:
          type: string
          description: Base64-encoded 32-byte metadata field.
        proof_account_data:
          $ref: "#/components/schemas/ProofAccountData"
        utxo_slot_data:
          type: array
          items:
            $ref: "#/components/schemas/UtxoSlotData"
          minItems: 1
          description: Array of UTXO slots to claim.
        fee_proof_data:
          $ref: "#/components/schemas/FeeProofData"

    ProofAccountData:
      type: object
      description: Cryptographic proof data for the claim.
      properties:
        rescue_encryption_public_key:
          type: string
          description: Base64-encoded 32-byte X25519 public key.
        encryption_nonce:
          type: string
          description: Decimal-encoded u128 Rescue cipher nonce.
        merkle_root:
          type: string
          description: Base64-encoded 32-byte Poseidon Merkle root.
        tvk_timestamp:
          type: integer
          format: int64
          description: Temporal viewing key timestamp.
        groth16_proof_a:
          type: string
          description: Base64-encoded 64-byte Groth16 proof element A.
        groth16_proof_b:
          type: string
          description: Base64-encoded 128-byte Groth16 proof element B.
        groth16_proof_c:
          type: string
          description: Base64-encoded 64-byte Groth16 proof element C.
        rescue_encryption_commitment:
          type: string
          description: Base64-encoded 32-byte encryption commitment.
        encryption_validation_polynomial:
          type: string
          description: Base64-encoded 32-byte polynomial.
        rescue_encrypted_master_viewing_key_low:
          type: string
          description: Base64-encoded encrypted MVK low half.
        rescue_encrypted_master_viewing_key_high:
          type: string
          description: Base64-encoded encrypted MVK high half.
        rescue_encrypted_blinding_factor_low:
          type: string
          description: Base64-encoded encrypted blinding factor low half.
        rescue_encrypted_blinding_factor_high:
          type: string
          description: Base64-encoded encrypted blinding factor high half.
        rescue_encrypted_total_amount:
          type: string
          description: Base64-encoded 32-byte encrypted amount (encrypted_balance only).
        rescue_encrypted_relayer_commission_fee:
          type: string
          description: Base64-encoded encrypted relayer fee (encrypted_balance only).
        rescue_encrypted_protocol_commission_fee:
          type: string
          description: Base64-encoded encrypted protocol fee (encrypted_balance only).
        total_relayer_fees:
          type: integer
          format: int64
          description: Total relayer fees in token base units (encrypted_balance only).

    UtxoSlotData:
      type: object
      description: Data for a single UTXO being claimed.
      properties:
        slot_index:
          type: integer
          format: int32
          description: Position of this UTXO in the batch.
        nullifier:
          type: string
          description: Base64-encoded 32-byte nullifier. Must be unique within the request.
        linker_encryptions:
          type: array
          items:
            type: string
          description: Base64-encoded Poseidon linker encryptions (6 for encrypted_balance, 5 for public_balance).
        linker_key_commitments:
          type: array
          items:
            type: string
          description: Base64-encoded Poseidon key commitments (6 for encrypted_balance, 5 for public_balance).

    FeeProofData:
      type: object
      description: Fee Merkle proof data. Required for public_balance variant only.
      properties:
        amount:
          type: string
          description: Claim amount.
        relayer_fixed_sol_fees:
          type: string
          description: SOL fees in lamports.
        protocol_fees_amount_lower_bound:
          type: string
        protocol_fees_amount_upper_bound:
          type: string
        protocol_fees_base_fees_in_spl:
          type: string
        protocol_fees_commission_fee_in_spl:
          type: integer
          format: int32
        protocol_fees_merkle_path:
          type: array
          items:
            type: string
          minItems: 4
          maxItems: 4
          description: Four sibling hashes for fee schedule proof.
        protocol_fees_leaf_index:
          type: integer
          format: int32
        relayer_fees_amount_lower_bound:
          type: string
        relayer_fees_amount_upper_bound:
          type: string
        relayer_fees_base_fees_in_spl:
          type: string
        relayer_fees_commission_fee_in_spl:
          type: integer
          format: int32
        relayer_fees_merkle_path:
          type: array
          items:
            type: string
          minItems: 4
          maxItems: 4
          description: Four sibling hashes for relayer fee schedule proof.
        relayer_fees_leaf_index:
          type: integer
          format: int32

    ClaimStatus:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - received
            - validating
            - offsets_reserved
            - building_tx
            - tx_built
            - submitting
            - submitted
            - awaiting_callback
            - callback_received
            - finalizing
            - completed
            - failed
            - timed_out
        variant:
          type: string
          enum: [encrypted_balance, public_balance]
        resolved_variant:
          type: string
          nullable: true
          description: Specific on-chain instruction variant selected by preflight validator.
        tx_signature:
          type: string
          nullable: true
          description: Solana transaction signature of the claim instruction.
        callback_signature:
          type: string
          nullable: true
          description: Solana transaction signature of the Arcium MPC callback.
        computation_account:
          type: string
          nullable: true
          description: Base58-encoded computation account address.
        failure_reason:
          type: string
          nullable: true
          description: Error message if status is failed.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time