Withdraw

A withdrawal moves tokens out of the private balance to a public Solana address. It can be the user's own wallet or anyone else's.

In this guide, Bob withdraws 10 USDC to his wallet. Then he sends SOL straight to another address.

What's publicCopy Anchor Link

A relayer sends the withdrawal, so no wallet of Bob's signs it. The address that receives the tokens is public, like any Solana transfer.

WithdrawCopy Anchor Link

Create a withdrawal context from the session, then call withdraw.

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

const usdc = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const context = await createWithdrawalContext(session);
const result = await withdraw(context, {
  mint: usdc,
  amount: 10_000_000n,
  recipient: session.walletAddress,
});

• amount is what leaves the private balance, in the token's smallest unit. The fees come out of it. Pass fees: "added" so the recipient receives exactly amount.
• recipient is the wallet paid. Here it is Bob's own, but any Solana address works.
• mint is the token. Bob pays from his private balance in it.

Bob's wallet signs nothing. The SDK builds the proof on his device, and a relayer sends the transaction and pays its network fee.

Where the tokens goCopy Anchor Link

A walletCopy Anchor Link

By default the tokens go to the recipient wallet's associated token account for the mint. If that account does not exist, the relayer creates it and pays its rent. The relayer charges a creation fee for that, which comes out of the withdrawal, unless it covers the cost itself.

A token accountCopy Anchor Link

To pay a different token account, pass it as recipientTokenAccount. It must already exist and hold the same token.

SOL itselfCopy Anchor Link

To send SOL rather than wrapped SOL, withdraw the wrapped SOL mint. Pass the receiving wallet's own address as recipientTokenAccount too. The SOL then lands in the wallet itself.

import { address } from "@solana/kit";
import { withdraw } from "@umbra/nimbus-solana-web";

const wrappedSol = address("So11111111111111111111111111111111111111112");

const result = await withdraw(
  context,
  { mint: wrappedSol, amount: 100_000_000n, recipient: destination },
  { recipientTokenAccount: destination },
);

A wallet that holds no SOL must receive at least 890,880 lamports, Solana's rent-exempt minimum. Without recipientTokenAccount, the SDK pays the wallet's wrapped SOL token account instead. If that account does not exist, withdraw throws.

When the destination cannot be paidCopy Anchor Link

withdraw reads the destination from Solana before it asks Nimbus for anything. When it cannot be paid, withdraw throws a NimbusSolanaFlowError with reason payout-unpayable. Some causes:

• The token account holds a different token.
• The account belongs to neither token program.
• The account does not exist, and it is not the recipient's associated token account.
• A SOL payment would leave the wallet below the rent-exempt minimum.

Nothing is sent. Choose another destination, or a larger amount.

Follow it to the endCopy Anchor Link

A withdrawal is followed the way a Private Send is. By default withdraw waits until it lands, then syncs the device. Pass follow: false to return once the relayer accepts it.

A relayed result's settlement.kind is landed, failed, pending or not-followed. Follow it to the end says what each means and what to do.

Handle the resultCopy Anchor Link

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

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

function describeWithdrawal(result: WithdrawalResult): string {
  switch (result.kind) {
    case "relayed":
      switch (result.settlement.kind) {
        case "landed":
          return "Withdrawn.";
        case "failed":
          return `The withdrawal did not go through (${result.settlement.state}).`;
        case "pending":
          return "Sent, and not settled yet. Check again in a minute.";
        case "not-followed":
          return "The relayer accepted the withdrawal.";
      }
    case "refused":
      switch (result.refusal.kind) {
        case "insufficient":
          return `You can withdraw at most ${result.refusal.available} base units.`;
        case "not-registered":
          return "Your registration is not final yet. Try again in a minute.";
        case "lease-refused":
          return "Another payment is using these funds. Try again soon.";
        case "store-refused":
        case "attempt-refused":
        case "stale-handle":
        case "store-unavailable":
          return "This browser could not use your account data. Reload and try again.";
      }
    case "relay-refused":
      return `The relayer refused the withdrawal: ${result.detail}`;
    case "unsent":
      return "Nothing was sent. Reload and try again.";
    case "merge-failed":
      return `Combining your balance stopped after ${result.mergesCompleted} step(s).`;
  }
}

Show progressCopy Anchor Link

Pass onProgress to tell Bob what is happening:

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

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

The stages are synced, then any combining steps, then prepared, proved, relayed and settled. Show progress has a message for each stage.

Edge casesCopy Anchor Link

The balance is spread outCopy Anchor Link

One withdrawal draws on at most three separate amounts in the private balance. When those cannot cover it, the SDK combines amounts first, as a Private Send does. That takes longer and costs a relayer fee per step.

A token with a transfer feeCopy Anchor Link

Some Token-2022 tokens keep a fee on every transfer. The recipient then receives less again, even with fees: "added".

Trying again after a refusalCopy Anchor Link

After relay-refused, the funds it used are free again at once, so a retry can spend them. After a failed settlement they stay reserved for a few minutes. A retry straight away may then come back insufficient. Reserved funds shows what is held.

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