Relayer API

POST /unshield

How to quote a withdrawal and withdraw SOL from the pool to any address with a proof the relayer submits.

POST /unshield moves lamports out of the pool to an address. The browser proves that it spends the holder's notes for the amount plus the network refund (networkLamports), with any change as a new note, and binds the proof to the recipient, amount, network refund, memos and relayer; the relayer submits unshield with itself as fee payer, so the wallet that shielded signs nothing and the recipient can be any address. GET /unshield/quote returns the network refund to prove for. See Unshield.

Request

POST /unshield with Content-Type: application/json.

UnshieldRequest
proofrequired
Proof
The Groth16 proof: a (64 bytes), b (128 bytes) and c (64 bytes), each base64 in groth16-solana order. See How values travel.
publicInputsrequired
PublicInputs
The proof's public inputs, below.
torequired
Address
The recipient, base58.
lamportsrequired
PositiveU64
The amount sent to to. Greater than zero.
networkLamportsrequired
U64
The network refund from GET /unshield/quote, unchanged. unshield moves it from the pool vault to the relayer.
memosrequired
[Memo, Memo]
One encrypted note memo per output commitment, in the same order. Each is base64 of at most 108 characters, decoding to at most 80 bytes.
publicInputs
rootrequired
Field
The tree root the proof was built against, from GET /tree.
nullifiersrequired
[Field, Field]
The nullifiers of the two input notes, one of which may be a zero-amount dummy.
outputCommitmentsrequired
[Field, Field]
The two new notes: the change and a zero-valued second output.
publicAmountrequired
Field
The proof's public amount for lamports plus networkLamports, the quote's totalLamports. See Spending: two in, two out.
bindingHashrequired
Field
The proof's binding for to, lamports, networkLamports, the relayer named by relayer in GET /config and memos. See Binding hashes.

Response

UnshieldResponse
signaturerequired
Signature
The unshield transaction's signature.
slotrequired
integer
The slot it landed in.
networkLamportsrequired
U64
The network refund the withdrawal paid the relayer, as sent.
totalLamportsrequired
U64
lamports plus networkLamports: what left the holder's notes.

The response arrives once the transaction is confirmed and indexed, so the next GET /tree already holds the change note.

Behaviour

An unshield is idempotent per publicInputs: the relayer journals each signed transaction under them, so the same request sent again follows the transaction already signed, returns its result and moves nothing new. A retry after a lost response, or after RELAYER_FAILED, is safe.

The checks run in this order, and the first that fails answers:

  1. The relayer is ready (PROGRAM_UNAVAILABLE).
  2. The body: content type, JSON, then the schema.
  3. publicInputs.publicAmount is the public amount for lamports plus networkLamports, and publicInputs.bindingHash is the binding for to, lamports, networkLamports, this relayer and memos (PROOF_INVALID, stage simulation).
  4. Unless this request was already signed and has not expired: networkLamports equals the current network refund (QUOTE_EXPIRED, "The network refund changed. Request a fresh quote.").
  5. The program config exists (PROGRAM_UNAVAILABLE), its fee equals the relayer's fee rate and it lists this relayer (CONFIGURATION_REQUIRED).
  6. Unless this request was already signed and has not expired: neither nullifier account exists (NULLIFIER_SPENT, stage build).
  7. The transaction is built, simulated, signed by the relayer and sent. The program checks the root, the proof and the nullifiers; its refusals answer UNKNOWN_ROOT, PROOF_INVALID or NULLIFIER_SPENT (never retryable) or INSUFFICIENT_BALANCE, and any other failure SIMULATION_FAILED or CHAIN_REFUSED.
  8. The transaction confirms. Still pending, it answers RELAYER_FAILED: send the same request again.

On success the nullifiers are recorded as spent, both output commitments are appended to the tree with their memos, lamports move from the pool to to, and networkLamports move from the pool to the relayer.

Errors

Codes are explained in full under Errors.

CodeRaised whenNext
PROGRAM_UNAVAILABLEThe relayer is not ready, or the program config account does not exist yet. Retryable.Retry later with the same body.
UNSUPPORTED_MEDIA_TYPEThe body is not sent as application/json.Set the content type.
VALIDATION_ERRORThe JSON is malformed or fails the schema; fieldErrors names the fields.Fix the body.
PROOF_INVALIDpublicAmount or bindingHash does not match this request ("The proof public amount or binding does not match this instruction."), or the program refused the proof.Prove again for the to, lamports, networkLamports and memos sent.
QUOTE_EXPIREDThe network refund changed since GET /unshield/quote. Retryable.Quote again, prove for the new total, send.
CONFIGURATION_REQUIREDThe relayer's fee rate differs from the program config's, or the program config does not list this relayer.Try again later.
NULLIFIER_SPENTA nullifier account already exists, or the program refused a nullifier.Read GET /tree, drop spent notes, prove with unspent ones.
UNKNOWN_ROOTThe program does not accept the proof's root.Read GET /tree, prove against its root, send again.
INSUFFICIENT_BALANCEThe pool vault cannot cover the transfer.Retry later.
SIMULATION_FAILEDThe transaction failed simulation for another reason.See message and programError.
CHAIN_REFUSEDThe chain refused the transaction for another reason.See message and programError.
RELAYER_FAILEDThe signed withdrawal is still pending. Retryable.Send the same request again.

Example

TypeScript
const quote = await client.unshieldQuote({ lamports: amount })

const sent = await client.unshield({
  proof,          // { a, b, c } from the prover, spending quote.totalLamports
  publicInputs,   // root, nullifiers, outputCommitments, publicAmount, bindingHash
  to: recipient,
  lamports: quote.lamports,
  networkLamports: quote.networkLamports,
  memos,          // the two encrypted output memos
})
HTTP
POST /unshield
Content-Type: application/json

{
  "proof": { "a": "<base64, 64 bytes>", "b": "<base64, 128 bytes>", "c": "<base64, 64 bytes>" },
  "publicInputs": {
    "root": "0x<tree root>",
    "nullifiers": ["0x<nullifier>", "0x<second nullifier>"],
    "outputCommitments": ["0x<change commitment>", "0x<zero-value commitment>"],
    "publicAmount": "0x<public amount>",
    "bindingHash": "0x<binding for to, lamports, networkLamports, relayer and memos>"
  },
  "to": "<recipient address>",
  "lamports": "<amount in lamports>",
  "networkLamports": "<networkLamports from GET /unshield/quote>",
  "memos": ["<base64 change memo>", "<base64 zero-value memo>"]
}

GET /unshield/quote

GET /unshield/quote returns the network refund a withdrawal of lamports carries and the total the proof spends. It is called before the withdrawal is proven. Unlike a storage quote it has no id or expiry: POST /unshield checks the networkLamports it receives against the current network refund.

Request

HTTP
GET /unshield/quote?lamports=<amount in lamports>
Query
lamportsrequired
PositiveU64
The amount to send to the recipient, as a decimal string. Greater than zero.

No other query keys are accepted.

Response

UnshieldQuoteResponse
lamportsrequired
PositiveU64
The amount asked for, as sent.
networkLamportsrequired
U64
The current network refund, computed from the rent-exempt minimum the Solana RPC reports for an 8-byte account.
totalLamportsrequired
U64
lamports plus networkLamports: the amount the proof spends.

The checks run in this order: the relayer is ready (PROGRAM_UNAVAILABLE), then the query schema (VALIDATION_ERROR).

Errors

CodeRaised whenNext
PROGRAM_UNAVAILABLEThe relayer is not ready. Retryable.Retry later.
VALIDATION_ERRORlamports is missing, "0", not an unsigned integer string or above 2^64 - 1, or the query has another key. fieldErrors names the key.Fix the query.
QUOTE_FAILEDThe Solana RPC did not report the rent for the network refund. Retryable.Quote again.

The relayer answers lamports=0 with:

JSON
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Check the highlighted fields.",
    "retryable": false,
    "stage": "validation",
    "fieldErrors": { "lamports": ["Must be greater than zero."] },
    "requestId": "1874157e-756f-48db-adbf-bd19ed3b9baf"
  }
}

Example

HTTP
GET /unshield/quote?lamports=<amount in lamports>
Accept: application/json