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.
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.
- Seal
- Quote
- Prove
- Pay
- Store
- Open
What it does
Check the amount
lamportsmust be a whole number of lamports above zero that fits in 64 bits, as abigintor a decimal string. 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.Check the wallet
The wallet needs
signTransactionorsignAndSendTransaction; with neither, the call raisesWALLET_REJECTED.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
/treefirst, so the proof uses the current root. See Binding hashes and Spending: two in, two out.Build
POST /shield/buildwith 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.Sign
With
signTransaction, the wallet signs the bytes and the client sends them toPOST /shield/confirm, which submits them. OtherwisesignAndSendTransactionsends the transaction and the client sends its signature toPOST /shield/confirm. A wallet that throws raisesWALLET_REJECTED.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
balancereads 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
lamportsrequiredstring | bigintbigint or a decimal string, from 1 to 18446744073709551615. 1 SOL is 1000000000.Return value
signaturestringshield transaction.slotnumberWhat it costs
| Amount | Paid by |
|---|---|
lamports, moved into the pool | The wallet |
| The transaction fee | The wallet, as fee payer |
| The rent of two nullifier accounts | The 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
| Code | Raised when |
|---|---|
VALIDATION_ERROR | The amount is not a positive 64-bit whole number, or the wallet address does not decode to 32 bytes |
WALLET_REJECTED | The client has no wallet, the wallet has neither transaction method, declines the key message, or throws while signing or sending |
PROOF_FAILED | No artifacts URL is configured, the artifacts cannot be downloaded, or the prover fails or yields other public signals |
UNKNOWN_ROOT | The tree leaves the relayer returned do not hash to its root |
RELAYER_FAILED | The 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_REQUIRED | The manifest cannot be read on first unlock |
UPSTREAM_UNAVAILABLE | A 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
// 0.25 SOL
const { signature, slot } = await geode.shield(250_000_000n)