> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.umbraprivacy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit Burn
> Submit a Stealth Pool Note burn request to the relayer for processing. The wire path is /v1/claims (legacy).
This endpoint is designed to be called by the SDK's burner factories, not directly.
The request body contains cryptographic proof data that must be generated correctly
by the ZK prover. Use `getSelfBurnableStealthPoolNoteIntoETABurnerFunction`,
`getReceiverBurnableStealthPoolNoteIntoETABurnerFunction`, or
`getSelfBurnableStealthPoolNoteIntoATABurnerFunction`
from `@umbra-privacy/sdk/burn` instead.
The relayer validates the request, builds the on-chain transactions, and submits them asynchronously. Poll `GET /v1/claims/{request_id}` with the returned UUID to track progress.
The wire path retains the legacy `/v1/claims` segment. In V18 SDK code you call it via the relayer client's `submitClaim` method (or its `submitBurn` alias when plugged into a burner factory's `relayer` dep).
## Burn variants
* `encrypted_balance` — burn into an `EncryptedTokenAccount`. Requires additional Rescue-encrypted fee fields in `proof_account_data`. Each note slot has 6 linker encryptions and 6 key commitments.
* `public_balance` — burn into an `AssociatedTokenAccount`. Requires `fee_proof_data` with the client's expected basis-points rates (`protocol_fee_basis_points`, `relayer_fee_basis_points`) and allowed-address PDA slots — the relayer verifies these against the on-chain `FeeSchedule` / `RelayerFeeSchedule` PDAs before submission, catching stale client config without wasting a transaction. Each note slot has 5 linker encryptions and 5 key commitments.
## Validation rules
* All base58 pubkeys must decode to exactly 32 bytes.
* All nullifiers within a request must be unique (duplicates return `409 DUPLICATE_OFFSET`).
* `max_utxo_capacity` must be greater than 0.
* `fee_proof_data` is required for `public_balance` variant only.
## Idempotency / `DUPLICATE_OFFSET`
If a burn callback drops and you re-submit with the same `request_id` while the nullifier is still reserved upstream, the relayer returns **HTTP 409 with code `DUPLICATE_OFFSET`**. Wait, re-check on-chain that the nullifier has not landed, and retry only if still unspent. The SDK's burner factories handle this internally.
## OpenAPI
````yaml openapi-relayer.yaml POST /v1/claims
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
security: []
tags:
- name: relayer
description: Relayer identity and configuration
- name: claims
description: Claim submission and status polling
- name: health
description: Service health checks
paths:
/v1/claims:
post:
tags:
- claims
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.
operationId: submitClaim
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'
components:
schemas:
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'
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Machine-readable error code.
message:
type: string
description: Human-readable description.
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
````