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.
proofrequiredProofa (64 bytes), b (128 bytes) and c (64 bytes), each base64 in groth16-solana order. See How values travel.publicInputsrequiredPublicInputstorequiredAddresslamportsrequiredPositiveU64to. Greater than zero.networkLamportsrequiredU64GET /unshield/quote, unchanged. unshield moves it from the pool vault to the relayer.memosrequired[Memo, Memo]nullifiersrequired[Field, Field]outputCommitmentsrequired[Field, Field]publicAmountrequiredFieldlamports plus networkLamports, the quote's totalLamports. See Spending: two in, two out.bindingHashrequiredFieldto, lamports, networkLamports, the relayer named by relayer in GET /config and memos. See Binding hashes.Response
signaturerequiredSignatureunshield transaction's signature.slotrequiredintegernetworkLamportsrequiredU64totalLamportsrequiredU64lamports 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:
- The relayer is ready (
PROGRAM_UNAVAILABLE). - The body: content type, JSON, then the schema.
publicInputs.publicAmountis the public amount forlamportsplusnetworkLamports, andpublicInputs.bindingHashis the binding forto,lamports,networkLamports, this relayer andmemos(PROOF_INVALID, stagesimulation).- Unless this request was already signed and has not expired:
networkLamportsequals the current network refund (QUOTE_EXPIRED, "The network refund changed. Request a fresh quote."). - The program config exists (
PROGRAM_UNAVAILABLE), its fee equals the relayer's fee rate and it lists this relayer (CONFIGURATION_REQUIRED). - Unless this request was already signed and has not expired: neither nullifier account exists (
NULLIFIER_SPENT, stagebuild). - 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_INVALIDorNULLIFIER_SPENT(never retryable) orINSUFFICIENT_BALANCE, and any other failureSIMULATION_FAILEDorCHAIN_REFUSED. - 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.
| Code | Raised when | Next |
|---|---|---|
PROGRAM_UNAVAILABLE | The relayer is not ready, or the program config account does not exist yet. Retryable. | Retry later with the same body. |
UNSUPPORTED_MEDIA_TYPE | The body is not sent as application/json. | Set the content type. |
VALIDATION_ERROR | The JSON is malformed or fails the schema; fieldErrors names the fields. | Fix the body. |
PROOF_INVALID | publicAmount 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_EXPIRED | The network refund changed since GET /unshield/quote. Retryable. | Quote again, prove for the new total, send. |
CONFIGURATION_REQUIRED | The relayer's fee rate differs from the program config's, or the program config does not list this relayer. | Try again later. |
NULLIFIER_SPENT | A nullifier account already exists, or the program refused a nullifier. | Read GET /tree, drop spent notes, prove with unspent ones. |
UNKNOWN_ROOT | The program does not accept the proof's root. | Read GET /tree, prove against its root, send again. |
INSUFFICIENT_BALANCE | The pool vault cannot cover the transfer. | Retry later. |
SIMULATION_FAILED | The transaction failed simulation for another reason. | See message and programError. |
CHAIN_REFUSED | The chain refused the transaction for another reason. | See message and programError. |
RELAYER_FAILED | The signed withdrawal is still pending. Retryable. | Send the same request again. |
Example
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
})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
GET /unshield/quote?lamports=<amount in lamports>lamportsrequiredPositiveU64No other query keys are accepted.
Response
lamportsrequiredPositiveU64networkLamportsrequiredU64totalLamportsrequiredU64lamports 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
| Code | Raised when | Next |
|---|---|---|
PROGRAM_UNAVAILABLE | The relayer is not ready. Retryable. | Retry later. |
VALIDATION_ERROR | lamports 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_FAILED | The Solana RPC did not report the rent for the network refund. Retryable. | Quote again. |
The relayer answers lamports=0 with:
{
"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
GET /unshield/quote?lamports=<amount in lamports>
Accept: application/jsonconst quote = await client.unshieldQuote({ lamports: amount })