Deposit

A deposit moves tokens from your user's wallet into a private balance. It is the first payment every user makes, and the only one their wallet signs.

In this guide, Alice deposits 25 USDC into her own private balance. Then she deposits 5 USDC straight into Bob's.

What's publicCopy Anchor Link

A deposit looks like an ordinary transfer into the pool. Because Alice registered her wallet, it can be tied to her. Privacy starts once the tokens are inside.

Deposit into your user's balanceCopy Anchor Link

Create a deposit context from the session, then call deposit.

import { address } from "@solana/kit";
import { createDepositContext, deposit } from "@umbra/nimbus-solana-web";

const usdc = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const context = await createDepositContext(session);
const result = await deposit(
  context,
  { mint: usdc, amount: 25_000_000n, recipient: session.walletAddress },
  { transactionVersion },
);

• amount is in the token's smallest unit. USDC has 6 decimals, so 25 USDC is 25_000_000n. Tokens shows how to read any token's decimals.
• recipient is the wallet whose private balance receives the deposit. Here it is Alice's own.
• transactionVersion is what the wallet can sign. openWalletConnection tells you; see Connect a wallet.

Alice's wallet asks her to approve one transaction. She pays its network fee from her wallet.

The protocol feeCopy Anchor Link

The protocol fee comes out of the amount. When Alice deposits 25 USDC, her private balance grows by 25 USDC less the fee.

To charge the fee on top instead, pass fees: "added". The fee is then paid from the private balance Alice already holds in that token. If she holds too little, the deposit throws before anything is signed.

Deposit into another user's balanceCopy Anchor Link

Alice can pay Bob directly from her wallet. Pass Bob's wallet address as recipient.

import { deposit } from "@umbra/nimbus-solana-web";

const result = await deposit(context, {
  mint: usdc,
  amount: 5_000_000n,
  recipient: bob,
});

The 5 USDC arrive in Bob's private balance, not Alice's. Bob sees them the next time his device syncs.

Bob must have registered first. If he has not, deposit throws a NimbusSdkError with reason recipient-unregistered, and Alice's wallet is never asked to sign.

Handle the resultCopy Anchor Link

deposit returns a result instead of throwing for anything your user can cause. Check its kind:

A submitted result carries the transaction's fate in result.submission.submission.kind:

Here is the whole check in one function. TypeScript checks that it covers every case.

function describeDeposit(result: DepositResult): string {
  switch (result.kind) {
    case "submitted":
      switch (result.submission.submission.kind) {
        case "landed":
          return "Deposited.";
        case "failed":
          return "The deposit failed on Solana. Only the network fee was charged.";
        case "expired":
        case "refused":
          return "The deposit never reached Solana. Try again.";
        case "unknown":
          return "The deposit is still pending.";
      }
    case "declined":
      return "You declined the deposit in your wallet.";
    case "store-refused":
    case "intent-refused":
    case "attempt-refused":
      return "This browser could not record the deposit. Reload and try again.";
    case "funding-failed":
    case "funding-unknown":
    case "deposit-unsendable":
      return "See Wallets that sign only version 0.";
  }
}

The last three kinds happen only with older wallets. They are covered in Wallets that sign only version 0.

Show progressCopy Anchor Link

A deposit takes a few seconds, most of it building the proof. Pass onProgress to tell your user what is happening:

import { deposit } from "@umbra/nimbus-solana-web";

await deposit(
  context,
  { mint: usdc, amount: 25_000_000n, recipient },
  { onProgress: (event) => showStatus(event.stage) },
);

Show progress lists every stage with a message you can show as it is.

If the deposit is still pendingCopy Anchor Link

Sometimes the SDK stops waiting before Solana settles a deposit. The result is submitted, and its submission's kind is unknown. Do not deposit the same funds again yet: call resolvePendingDeposit to learn how it ended. Pending and stranded deposits shows how, including across a page reload.

Wallets that sign only version 0Copy Anchor Link

A wallet that signs only version 0 needs two transactions, and Alice approves both. The first moves the funds to her platform wallet, a second address the SDK derives for her, and the second deposits them. When they do not both go through, the result is funding-failed, funding-unknown or deposit-unsendable. Pending and stranded deposits says when to try again and when to refund.

Common errorsCopy Anchor Link

These are thrown, not returned, because your app usually cannot fix them by asking the user.

Handle errors shows one function that covers every error the SDK throws.

OptionsCopy Anchor Link

The API reference lists every option.

NextCopy Anchor Link