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
requestcarries one balance leaf, its path, and the opening of its owner tag. The relay checks that the path reaches the frozen root, then submitsescape_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
claimnames 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 submitsescape_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 notapplication/json.VALIDATION_ERROR:kindis neitherrequestnorclaim, 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’sEscapeStateaccount does not exist; or, for a claim, noEscapeRequestaccount sits atrequest, or a mint the claim pays has noAssetState.ESCAPE_NOT_READY: theLedgerRootrecords 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 stagesend.SHARES_PENDING: the claim’s request does not yet holdthresholdcombined 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 stagesimulation: the transaction fails simulation, as a claim whose amount or proofescape_claimrefuses does.RATE_LIMITED: more than 60POSTrequests to/v1in a minute from this client.
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) },
})
curl -X POST https://api.privium.io/v1/escape/relay \
-H 'Content-Type: application/json' \
-d @escape-request.json
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:
{
"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:addressis not a base58 address of 32 bytes.NOT_FOUND: noEscapeRequestaccount 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.
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`
curl https://api.privium.io/v1/escape/requests/2MxmZqynLPWVvtCsdsJfddHipLLGTkm1Z9Kk4kMy7Cyx
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 notapplication/json.VALIDATION_ERROR:kindis neitherrequestnorclaim,instructionsis 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 60POSTrequests to/v1in 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. |