• Reading the docs…
Start trading

API reference

Escape requests and claims

The routes an owner’s Escape runs through: the relay that submits a request and a claim with the API paying, the public progress of a request toward the Council’s threshold, and the Escape build route.

Routes#

POST /v1/escape/relay#

Submits an owner’s Escape request or claim as the program’s fixed instruction, with the API as fee payer, so the owner spends no SOL and signs nothing with the wallet. requestEscape and claimEscape build the body from the account’s keys and the public diffs, and the Account page’s Escape panel runs through them (Claiming a balance). The body carries proofs, never instructions, and a claim’s proof binds its destination, so no relayer can redirect the payout.

The body is EscapeRelayRequest, by kind. Returns EscapeSubmission.

  • A request carries one balance leaf, its path, and the opening of its owner tag. The relay checks that the path reaches the frozen root, then submits escape_request, which checks the leaf’s asset and owner tag (escape_request). When the request account already exists for that leaf, mint and owner key, the answer is its transaction, requested.
  • A claim names an existing request of the same mint whose Council shares are combined, with the amount and the proof. The relay creates the destination’s token account for each mint the claim pays, or a temporary wrapped SOL account for native SOL, and submits escape_claim (escape_claim). A request already claimed answers with the claim’s transaction, paid.

Each request and each claim is one journaled transaction. The relay simulates it, sends it and follows it for up to 10 seconds, then answers; one still unconfirmed by then is pending, with its signature. Follow it with getSignatureStatuses through the RPC relay, or send the same body again, which follows the same journaled transaction and builds a new one only once that one’s blockhash has expired unseen. The shares and the claim show on GET /v1/escape/requests/{address}.

Errors

  • CONFIGURATION_REQUIRED: this API instance has no fee payer for the relay.
  • UNSUPPORTED_MEDIA_TYPE: the body is not application/json.
  • VALIDATION_ERROR: kind is neither request nor claim, a field fails its type (an address, base64 of 32 bytes, a path of exactly 32 hashes, a leaf index above 4,294,967,295, an amount that is not a positive 64-bit integer), or the body carries another key.
  • NOT_FOUND: no Escape has been triggered, so the Pool’s EscapeState account does not exist; or, for a claim, no EscapeRequest account sits at request, or a mint the claim pays has no AssetState.
  • ESCAPE_NOT_READY: the LedgerRoot records no active Escape.
  • MERKLE_PROOF_INVALID: a request’s leaf and path do not reach the frozen root.
  • CHAIN_REFUSED: the account at the request address is not the program’s, or is the request of another leaf, mint or owner key; a claim’s mint is not its request’s; or the chain refused the transaction, at stage send.
  • SHARES_PENDING: the claim’s request does not yet hold threshold combined shares; retryable.
  • INDEXER_UNAVAILABLE: the request or the claim is on chain and the indexer has not recorded its transaction yet; retryable.
  • SIMULATION_FAILED, at stage simulation: the transaction fails simulation, as a claim whose amount or proof escape_claim refuses does.
  • RATE_LIMITED: more than 60 POST requests to /v1 in a minute from this client.
TypeScript
import { b64, type EscapeClaimProof } from '@privium/sdk'

// A claim's parts, as claimEscape gathers them.
declare const request: string
declare const mint: string
declare const destination: string
declare const amount: bigint
declare const proof: EscapeClaimProof

const submission = await api.relayEscape({
  kind: 'claim',
  request,
  mint,
  destination,
  amount: amount.toString(),
  proof: { r1: b64(proof.r1), r2: b64(proof.r2), z: b64(proof.z) },
})

escape-request.json holds a request body as requestEscape builds it: the mint, the leaf’s position, its 225 bytes, its 32 siblings, the escape public key and the owner salt. The answer’s fields are in EscapeSubmission. While no Escape has been triggered, the relay answers with HTTP 404:

Response
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The EscapeState account was not found.",
    "retryable": false,
    "stage": "read"
  }
}

GET /v1/escape/requests/{address}#

An Escape request’s public progress: the frozen root, the Council shares posted against the threshold, and the claim. It is keyed by the EscapeRequest account’s address, the program address of the seeds escape-req, the leaf’s position as a little-endian u32 and the mint, so each frozen balance leaf has one request; escapeRequestAddress computes it. The address names a public account, never a wallet or an account identity. watchEscape polls it, and so does the Account page’s Escape panel while the Escape is active. Claim once state is claimable (Claiming a balance).

Parameter Type In Meaning
address Address path The EscapeRequest account's address: the program address derived from the leaf and the mint.

Returns EscapeRequest.

Errors

  • VALIDATION_ERROR: address is not a base58 address of 32 bytes.
  • NOT_FOUND: no EscapeRequest account exists at this address.
  • INDEXER_UNAVAILABLE: the indexer has not verified the latest Commit yet, or its root disagrees with the chain; retryable.
  • PROGRAM_UNAVAILABLE: the Pool is not indexed yet, or no enclave registration covers the current slot; retryable.
TypeScript
import { escapeRequestAddress } from '@privium/sdk'

const { balances } = await privium.readBalances()
const { asset, position } = balances[0]

const request = await api.escapeRequest(escapeRequestAddress(privium.config.programId, position, asset.mint))
const progress = `${request.shares.length} of ${request.threshold} shares`

The address in the request is the EscapeRequest account of the USDC leaf at position 28,971,320; the answer’s fields are in EscapeRequest.

POST /v1/escape/build#

Takes an EscapeBuildRequest and, once the body validates, answers NOT_IMPLEMENTED at stage build. Requests and claims go through POST /v1/escape/relay, which forms the program’s instruction itself from the owner’s proofs.

Errors

  • UNSUPPORTED_MEDIA_TYPE: the body is not application/json.
  • VALIDATION_ERROR: kind is neither request nor claim, instructions is not base64 or is outside 1 to 16,384 characters, or the body carries another key.
  • NOT_IMPLEMENTED: every valid body.
  • RATE_LIMITED: more than 60 POST requests to /v1 in a minute from this client.

Types#

EscapeRelayRequest#

A request:

Field Type Meaning
request.kind "request" request: open an EscapeRequest for one balance leaf under the frozen root.
request.mint Address The leaf's mint.
request.leafIndex integer The leaf's Ledger position, 0 to 4,294,967,295.
request.leaf Base64 The leaf's 225 bytes as the frozen root commits them, base64.
request.path Hash[] The leaf's 32 Merkle siblings to the frozen root, leaf level first.
request.ownerKey Hash The owner's escape public key Y: with salt, the opening of the leaf's owner tag.
request.salt Hash The owner salt.

A claim:

Field Type Meaning
claim.kind "claim" claim: pay a combined request's balance to destination.
claim.request Address The EscapeRequest account's address.
claim.mint Address The request's mint.
claim.destination Address The address the claim pays, bound into the proof.
claim.amount PositiveU64 The leaf's committed balance in base units: the amount the proof is made for.
claim.proof object The claim proof, made with the owner's escape secret.
claim.proof.r1 Hash The nonce commitment R1 = r·G.
claim.proof.r2 Hash The nonce commitment R2 = r·A.
claim.proof.z Hash The response z = r + e·y, a canonical little-endian scalar.

EscapeSubmission#

Field Type Meaning
request Address The EscapeRequest account's address; for a request, the program address of the leaf position and the mint.
transaction Signature The signature of the escape_request or escape_claim transaction, its fee paid by the API.
state "pending", "requested", "paid" pending while that transaction is sent and not yet confirmed, requested once the request is on chain, paid once the claim is.

EscapeRequest#

Field Type Meaning
address Address The EscapeRequest account's address, derived from the leaf and the mint.
state "requested", "collecting", "claimable", "paid" requested once the request is open, collecting while Council shares arrive, claimable once threshold shares are in, paid after the claim.
frozenRoot Hash The Ledger root the Escape froze.
frozenSlot U64 The slot of that root's Commit.
threshold integer t, the shares the request needs.
shares object[] The Council shares posted so far.
shares[].member integer The member's index.
shares[].transaction Signature The escape_share transaction's signature.
claimTransaction Signature or null The escape_claim transaction's signature; null until paid.

EscapeBuildRequest#

Field Type Meaning
kind "request", "claim" request builds escape_request, claim builds escape_claim.
instructions string The instruction bytes the client built, proofs included, base64, up to 16,384 characters.