> For AI agents: the documentation index is at https://sdk.nimbusprivacy.xyz/llms.txt, and every page is available as Markdown at its URL with .md appended. # Deposit (/reference/deposit) A deposit runs in a context made from the session. [Deposit](https://sdk.nimbusprivacy.xyz/deposit) walks through the flow, and [Pending and stranded deposits](https://sdk.nimbusprivacy.xyz/deposit/pending) covers what can be left over. ## createDepositContext Create one from the session before you deposit. `resolvePendingDeposit` and `refundStrandedDeposit` take the same kind of context. ```ts function createDepositContext( session: NimbusSession, options?: NimbusContextOptions, ): Promise; ``` Creates the context a session deposits, refunds a stranded deposit and resolves a pending deposit in. Without `options.poolIndex` the pools' accounts are read from the RPC once, and the highest open pool is chosen; the nodes and guardian cluster default to the cluster's preset. **Parameters** | Parameter | Type | Description | | ---------- | ---------------------- | ------------------------------------------------------------------------- | | `session` | `NimbusSession` | The opened session. | | `options?` | `NimbusContextOptions` | The pool, the screener and data endorser nodes, and the guardian cluster. | **Returns** `Promise` The context. **Throws** [`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"misconfigured"` when an option is out of range or no pool is open; `"service-unavailable"` or `"unreadable"` when the RPC cannot be read. **Example** ```ts import { createDepositContext } from "@umbra/nimbus-solana-web"; import type { NimbusSession } from "@umbra/nimbus-solana-web"; declare const session: NimbusSession; const context = await createDepositContext(session, { screenerNodeIndex: 1 }); ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/contexts.ts`. ## deposit Use it to move tokens from the connected wallet into a private balance, the user's own or another registered user's. ```ts function deposit( context: DepositContext, args: { readonly mint: Address; readonly amount: bigint; readonly recipient: Address; }, options?: DepositOptions, ): Promise; ``` Deposits `amount` of `mint` from the connected wallet into the context's pool, as a note for `recipient`, a registered identity's wallet address: the session's own, or another's. First syncs the note store until it is caught up, unless `sync: false`. The context API resolves the recipient to its identity and the key the note is sealed to. The committee endorses, the deposit is proved, the wallet signs once (twice at version 0) and the transaction is sent and followed to `commitment`. **Parameters** | Parameter | Type | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `context` | `DepositContext` | The deposit context. | | `args` | ``{ /** The mint deposited, which the connected wallet holds. */ readonly mint: Address; /** * What leaves the connected wallet, in base units of the mint, before any transfer fee the mint * withholds; at least 1 and below 2^64. Under `fees: "deducted"` the protocol fee comes out of * it; under `added` the note holds it and the fee is paid from the session's notes. */ readonly amount: bigint; /** * A registered identity's wallet address, whose identity the note is sealed to: the session's * own, or another's. */ readonly recipient: Address; }`` | The mint, the amount in its base units, and the recipient's wallet address. | | `options?` | `DepositOptions` | The progress hook, which also sees `synced`; whether to sync first; who pays the fee, the submitter's fee and its mint, the zone, the priority fee, the transaction version and the commitment. | **Returns** `Promise` `submitted` with how the deposit was funded and where its transaction ended up, which [`resolvePendingDeposit`](https://sdk.nimbusprivacy.xyz/reference/deposit#resolvependingdeposit) follows when that is `unknown`; `declined` when the wallet declined to sign; `store-refused`, `intent-refused` or `attempt-refused` when the note store would not take the deposit; and, at version 0 only, `funding-failed`, `funding-unknown` or `deposit-unsendable` when the funding transaction did not land or the deposit could not follow it. Nothing was deposited unless a `submitted` result's transaction `landed`. **Throws** [`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"misconfigured"` when an address is not base58 or no prover worker or committee endpoint was configured; `"service-unavailable"` or `"unreadable"` when a service or the RPC cannot answer, and `"unreadable"` too when the note store cannot be synced before it starts; `"unauthorized"` when a gateway service refuses the session's gateway token or the session has none; `"dependency-nonconforming"` when a proving key or the prover breaks its contract; `"wallet-unsupported"` when the wallet fails; `"recipient-unregistered"` when the context API answers that `recipient` has no registration in the pool, and `"account-unregistered"` when it answers that the session's identity has none, each before the wallet is asked to sign; [`NimbusSolanaFlowError`](https://sdk.nimbusprivacy.xyz/reference/types#nimbussolanaflowerror) when the protocol refuses the deposit, with reason `"fee-payer-unfunded"` when the connected wallet has no account or too few lamports for the transaction it pays for (at version 0, the funding): its fee, the SOL it moves, the rent of the token account it creates and its own rent-exempt minimum, raised before any proving key is downloaded or the committee is asked. **Example** ```ts import { createDepositContext, deposit } from "@umbra/nimbus-solana-web"; import type { NimbusSession } from "@umbra/nimbus-solana-web"; import type { Address } from "@solana/kit"; declare const session: NimbusSession; declare const mint: Address; const result = await deposit(await createDepositContext(session), { amount: 1_000_000n, mint, recipient: session.walletAddress, }); ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/flows.ts`. ## resolvePendingDeposit Use it when a deposit's submission came back `unknown`, to learn whether it landed. ```ts function resolvePendingDeposit( context: DepositContext, args: { readonly submission: DepositSubmission }, _options?: Readonly>, ): Promise; ``` Waits for a deposit whose outcome was `unknown` to land, fail or expire at the note store's finality, `confirmed`, and tells the note store, which releases a failed or expired deposit's notes. **Parameters** | Parameter | Type | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | `context` | `DepositContext` | The deposit context the deposit ran in. | | `args` | ``{ /** The `submitted` deposit result's `submission`, whose transaction's outcome was `unknown`. */ readonly submission: DepositSubmission; }`` | The deposit's submission, from a `submitted` deposit result whose transaction's outcome was `unknown`. | | `_options?` | `Readonly>` | Unused; kept so every function takes the same arguments. | **Returns** `Promise` `landed` with its slot; `failed` or `expired`, nothing deposited, with the store's answers to the failure and to abandoning the deposit's intent; `unknown` when the wait ended first, its notes still held; or `store-refused` when the note store would not open. **Throws** [`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"misconfigured"` when the submission's outcome was not `unknown`, before anything is fetched: one that landed, failed, expired or was refused is settled already; `"service-unavailable"` or `"unreadable"` when the RPC or the store cannot answer. **Example** ```ts import { resolvePendingDeposit } from "@umbra/nimbus-solana-web"; import type { DepositContext, DepositResult } from "@umbra/nimbus-solana-web"; declare const context: DepositContext; declare const result: DepositResult; if (result.kind === "submitted" && result.submission.submission.kind === "unknown") { await resolvePendingDeposit(context, { submission: result.submission }); } ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/flows.ts`. ## refundStrandedDeposit Use it to return funds a version 0 deposit left halfway, once every deposit of that token has settled. ```ts function refundStrandedDeposit( context: DepositContext, args: { readonly mint: Address }, options?: StrandedDepositRefundOptions, ): Promise; ``` Returns what the session's platform wallet holds of `mint` to the connected wallet: value a version 0 deposit's funding left there when the deposit did not land. Run it only once every deposit of the mint has settled: it returns what the platform wallet holds when it is prepared. The connected wallet signs and pays; the platform wallet signs as the owner of what moves. **Parameters** | Parameter | Type | Description | | ---------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `context` | `DepositContext` | The deposit context. | | `args` | `{ /** The mint whose stranded value is returned. */ readonly mint: Address; }` | The mint. | | `options?` | `StrandedDepositRefundOptions` | The progress hook, whether to close the emptied token account, the priority fee, the transaction version and the commitment. | **Returns** `Promise` `nothing-held` when the platform wallet holds nothing of the mint and no lamports; `declined` when the wallet declined to sign; or `submitted` with where the transaction ended up, which returned the value only when it `landed`. **Throws** [`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"misconfigured"` when the mint is not base58; `"service-unavailable"` or `"unreadable"` when the RPC cannot answer; `"wallet-unsupported"` when the wallet fails; [`NimbusSolanaFlowError`](https://sdk.nimbusprivacy.xyz/reference/types#nimbussolanaflowerror) with reason `"mint-unsupported"` when the mint is not one, `"fee-payer-unfunded"` when the connected wallet has no account or too few lamports to pay the refund's fee, before the wallet is asked to sign, or `"transaction-unsendable"` or `"transaction-altered"` when the refund cannot be sent or the wallet alters it. **Example** ```ts import { createDepositContext, refundStrandedDeposit } from "@umbra/nimbus-solana-web"; import type { NimbusSession } from "@umbra/nimbus-solana-web"; import type { Address } from "@solana/kit"; declare const session: NimbusSession; declare const mint: Address; const result = await refundStrandedDeposit(await createDepositContext(session), { mint }); ``` Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/flows.ts`. Last updated 21 October 2026