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.

TypeScript
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

  1. Check the input

    to must be a base58 address of 32 bytes and lamports a whole number above zero that fits in 64 bits. Anything else raises VALIDATION_ERROR.

  2. 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.

  3. Quote

    GET /unshield/quote with lamports. The relayer returns lamports, the network refund (networkLamports) and totalLamports. The client checks that lamports is the requested amount and that totalLamports equals lamports + networkLamports; a quote that fails either check raises QUOTE_FAILED.

  4. Prove

    The client reads /tree, takes the holder's two largest unspent notes, and spends the first one, or both, that cover totalLamports. Any excess goes to a new change note. The proof is bound to the recipient, the amount, the network refund, the relayer address in /config and the memos. See Binding hashes and Spending: two in, two out.

  5. Submit

    POST /unshield with the proof, its public inputs, to, lamports, networkLamports and the two output memos. The relayer submits the transaction and returns its signature, its slot, networkLamports and totalLamports.

  6. Check the result

    The returned networkLamports must equal the proved one, and totalLamports must equal lamports + networkLamports; otherwise the call raises RELAYER_FAILED. The next balance reads 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

unshield(input)
torequired
string
The recipient's Solana address, base58.
lamportsrequired
string | bigint
The amount the recipient receives, in lamports: a bigint or a decimal string from 1 to 18446744073709551615.

Return value

UnshieldResult
signature
string
The base58 signature of the withdrawal transaction.
slot
number
The slot it was confirmed in.
networkLamports
string
The network refund paid to the relayer, in decimal lamports.
totalLamports
string
The whole debit from the shielded balance, lamports + networkLamports, in decimal lamports.

What it costs

AmountPaid by
lamports, sent to toThe shielded balance
The network refund, networkLamports, sent to the relayerThe shielded balance
The transaction fee and the rent of two nullifier accountsThe 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

CodeRaised when
VALIDATION_ERRORto 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_FAILEDThe withdrawal quote's amount or total does not match
INSUFFICIENT_BALANCEThe 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_ROOTThe tree leaves the relayer returned do not hash to its root
PROOF_FAILEDNo artifacts URL is configured, the artifacts cannot be downloaded, or the prover fails or yields other public signals
RELAYER_FAILEDThe confirmed withdrawal does not match the proved debit, or a relayer reply does not match the contract
WALLET_REJECTEDThe client has no wallet, or the wallet declines the key message
WRONG_KEY, NOT_FOUND, IRYS_UNAVAILABLE, PAYLOAD_TOO_LARGEThe manifest cannot be read on first unlock
UPSTREAM_UNAVAILABLEA network failure or any other unrecognised error

Codes from /unshield/quote, /unshield, /tree and /config pass through as listed at /docs/api#errors.

Sample

TypeScript
const { signature, networkLamports, totalLamports } = await geode.unshield({
  to: '9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin',
  lamports: '100000000',
})