SDK
unshield
How geode.unshield withdraws shielded SOL to a Solana address with a proof, what it returns and costs, how a retry resumes, and the errors it raises.
unshield(input: { to: string; lamports: string | bigint }): Promise<UnshieldResult>unshield withdraws SOL from the holder's shielded balance to any Solana address. The payment is a Groth16 proof the relayer submits; the wallet signs no transaction.
What it does
Check the input
tomust be a base58 address of 32 bytes andlamportsa whole number above zero that fits in 64 bits. Anything else raisesVALIDATION_ERROR.Unlock the vault
On the client's first vault call, the wallet signs the key message and the manifest and notes are read, as in
recover.Quote
GET /unshield/quotewithlamports. The relayer returnslamports, the network refund (networkLamports) andtotalLamports. The client checks thatlamportsis the requested amount and thattotalLamportsequalslamports + networkLamports; a quote that fails either check raisesQUOTE_FAILED.Prove
The client reads
/tree, takes the holder's two largest unspent notes, and spends the first one, or both, that covertotalLamports. Any excess goes to a new change note. The proof is bound to the recipient, the amount, the network refund, the relayer address in/configand the memos. See Binding hashes and Spending: two in, two out.Submit
POST /unshieldwith the proof, its public inputs,to,lamports,networkLamportsand the two output memos. The relayer submits the transaction and returns its signature, its slot,networkLamportsandtotalLamports.Check the result
The returned
networkLamportsmust equal the proved one, andtotalLamportsmust equallamports + networkLamports; otherwise the call raisesRELAYER_FAILED. The nextbalancereads the change note from/tree.
unshield runs in the client's queue with store, shield and recover (see Calls run one at a time).
Arguments
torequiredstringlamportsrequiredstring | bigintbigint or a decimal string from 1 to 18446744073709551615.Return value
signaturestringslotnumbernetworkLamportsstringtotalLamportsstringlamports + networkLamports, in decimal lamports.What it costs
| Amount | Paid by |
|---|---|
lamports, sent to to | The shielded balance |
The network refund, networkLamports, sent to the relayer | The shielded balance |
| The transaction fee and the rent of two nullifier accounts | The relayer, repaid by the network refund |
The network refund repays the relayer the rent of the two nullifier accounts and the 5,000-lamport signature fee. It follows the cluster's rent, so read it from GET /unshield/quote or from the result. The two largest notes must cover lamports + networkLamports, else INSUFFICIENT_BALANCE. The recipient receives exactly lamports.
Retry
The client keeps a proved withdrawal whose submission failed, keyed by to and lamports. Calling unshield again with the same to and lamports sends the same request, with no new quote or proof. When POST /unshield answers QUOTE_EXPIRED, UNKNOWN_ROOT or NULLIFIER_SPENT, the client drops the request and the next call quotes and proves again.
Errors
| Code | Raised when |
|---|---|
VALIDATION_ERROR | to is not a 32-byte base58 address, lamports is not a positive 64-bit whole number, or a note memo that decrypts does not match its leaf |
QUOTE_FAILED | The withdrawal quote's amount or total does not match |
INSUFFICIENT_BALANCE | The two largest notes do not cover lamports + networkLamports |
CONFIGURATION_REQUIRED | /config has no relayer address, or no gateway URL is set when the manifest is read on first unlock |
UNKNOWN_ROOT | The tree leaves the relayer returned do not hash to its root |
PROOF_FAILED | No artifacts URL is configured, the artifacts cannot be downloaded, or the prover fails or yields other public signals |
RELAYER_FAILED | The confirmed withdrawal does not match the proved debit, or a relayer reply does not match the contract |
WALLET_REJECTED | The client has no wallet, or the wallet declines the key message |
WRONG_KEY, NOT_FOUND, IRYS_UNAVAILABLE, PAYLOAD_TOO_LARGE | The manifest cannot be read on first unlock |
UPSTREAM_UNAVAILABLE | A network failure or any other unrecognised error |
Codes from /unshield/quote, /unshield, /tree and /config pass through as listed at /docs/api#errors.
Sample
const { signature, networkLamports, totalLamports } = await geode.unshield({
to: '9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin',
lamports: '100000000',
})