SDK

shield

How geode.shield deposits SOL from the wallet into the pool as a note, what the wallet signs and pays, and the errors it raises.

TypeScript
shield(lamports: string | bigint): Promise<TransactionResult>

shield deposits SOL from the holder's wallet into the Geode pool as one new note that only the holder can spend. It is the one method that asks the wallet to sign a transaction.

  1. Seal
  2. Quote
  3. Prove
  4. Pay
  5. Store
  6. Open
Every file, from your device to Irys. Dashed: what the chain sees. Solid: what stays with you.

What it does

  1. Check the amount

    lamports must be a whole number of lamports above zero that fits in 64 bits, as a bigint or a decimal string. 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. Check the wallet

    The wallet needs signTransaction or signAndSendTransaction; with neither, the call raises WALLET_REJECTED.

  4. Prove the deposit

    The client makes a note of this amount owned by the holder's spending key, encrypts its memo under the view key, and proves the deposit: two dummy inputs, the new note and a zero-valued second output, bound to the wallet's address, the amount and the memos. The client reads /tree first, so the proof uses the current root. See Binding hashes and Spending: two in, two out.

  5. Build

    POST /shield/build with the wallet address, the amount, the proof, its public inputs and the two memos. The relayer returns an unsigned transaction whose fee payer is the wallet.

  6. Sign

    With signTransaction, the wallet signs the bytes and the client sends them to POST /shield/confirm, which submits them. Otherwise signAndSendTransaction sends the transaction and the client sends its signature to POST /shield/confirm. A wallet that throws raises WALLET_REJECTED.

  7. Confirm

    The relayer confirms the transaction and returns its signature, its slot and the two output commitments it recorded, which must equal the proved ones. The next balance reads the new note from /tree.

shield runs in the client's queue with store, unshield and recover (see Calls run one at a time).

Arguments

shield(lamports)
lamportsrequired
string | bigint
The deposit in lamports: a bigint or a decimal string, from 1 to 18446744073709551615. 1 SOL is 1000000000.

Return value

TransactionResult
signature
string
The base58 signature of the confirmed shield transaction.
slot
number
The slot it was confirmed in.

What it costs

AmountPaid by
lamports, moved into the poolThe wallet
The transaction feeThe wallet, as fee payer
The rent of two nullifier accountsThe wallet

The deposit is the transaction that carries the wallet's address. Payments from the note after it are proofs the relayer submits. See Public fields.

Errors

CodeRaised when
VALIDATION_ERRORThe amount is not a positive 64-bit whole number, or the wallet address does not decode to 32 bytes
WALLET_REJECTEDThe client has no wallet, the wallet has neither transaction method, declines the key message, or throws while signing or sending
PROOF_FAILEDNo artifacts URL is configured, the artifacts cannot be downloaded, or the prover fails or yields other public signals
UNKNOWN_ROOTThe tree leaves the relayer returned do not hash to its root
RELAYER_FAILEDThe confirmed output commitments differ from the proved ones, or a relayer reply does not match the contract
WRONG_KEY, NOT_FOUND, IRYS_UNAVAILABLE, PAYLOAD_TOO_LARGE, CONFIGURATION_REQUIREDThe manifest cannot be read on first unlock
UPSTREAM_UNAVAILABLEA network failure or any other unrecognised error

Codes from /config, /tree, /shield/build and /shield/confirm pass through as listed at /docs/api#errors.

Sample

TypeScript
// 0.25 SOL
const { signature, slot } = await geode.shield(250_000_000n)