Private Send

A Private Send pays another user from the private balance. The tokens never leave the pool. They move from the sender's private balance to the recipient's.

In this guide, Alice pays Bob 10 USDC. Anyone watching the chain sees that a payment happened, but not who paid, who was paid or how much.

What's publicCopy Anchor Link

A relayer sends the transaction, so neither wallet appears on chain. Bob himself can tell the payment came from Alice. Each payment records who funded it, and Bob's keys can read that. How privacy is lost explains why.

SendCopy Anchor Link

Create a transfer context from the session, then call transfer with Bob's wallet address.

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

const usdc = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const context = await createTransferContext(session);
const result = await transfer(context, {
  mint: usdc,
  amount: 10_000_000n,
  recipient: bob,
});

• amount is in the token's smallest unit, so 10 USDC is 10_000_000n. The fees come out of it, so Bob receives a little less. Pass fees: "added" to pay them on top.
• recipient is Bob's wallet address. Bob must have registered.
• mint is the token. Alice pays from her private balance in it.

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

Follow it to the endCopy Anchor Link

By default, transfer follows the payment until it lands, then syncs the device. Two options change that:

• follow: false returns as soon as the relayer accepts the payment.
• commitment: "finalized" waits until the payment cannot be rolled back. The default is "confirmed".

A relayed result carries how following it went, in result.settlement.kind:

After failed, the funds the payment used stay reserved for a few minutes. After pending or not-followed, they stay reserved until a sync sees the payment settle. Reserved funds explains why.

Handle the resultCopy Anchor Link

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

A refused result carries a refusal, whose kind says what stopped it:

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

function describeSettlement(settlement: SpendSettlement): string {
  switch (settlement.kind) {
    case "landed":
      return "Sent.";
    case "failed":
      return `The payment did not go through (${settlement.state}).`;
    case "pending":
      return "Sent, and not settled yet. Check again in a minute.";
    case "not-followed":
      return "The relayer accepted the payment.";
  }
}

function describeRefusal(refusal: SpendRefusal): string {
  switch (refusal.kind) {
    case "insufficient":
      return `You can send at most ${refusal.available} base units, fees included.`;
    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.";
  }
}

function describeTransfer(result: TransferResult): string {
  switch (result.kind) {
    case "relayed":
      return describeSettlement(result.settlement);
    case "refused":
      return describeRefusal(result.refusal);
    case "relay-refused":
      return `The relayer refused the payment: ${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).`;
  }
}

A withdrawal returns the same type, so describeTransfer works for withdraw too.

When the balance is spread outCopy Anchor Link

Alice's private balance in a token is made of separate amounts, one for each payment she received. A single Private Send can draw on at most three of them.

If her three largest amounts cannot cover 10 USDC, but all of them together can, the SDK combines them first. Each combining step is a Private Send to herself, sent by the relayer. The SDK waits for each step to land and reach her device before the next.

That takes longer, and each step pays the relayer's fee. Each step may take up to mergeTimeout slots, 300 by default. onProgress reports each step as merge-prepared, merge-relayed and merge-settled, numbered from 1 in merge.

If a step does not finish, the result is merge-failed. The steps that finished stay combined. cause says why the next one stopped.

Show progressCopy Anchor Link

Pass onProgress to tell Alice what is happening:

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

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

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

Edge casesCopy Anchor Link

Not enough available balanceCopy Anchor Link

The result is refused with insufficient. Its available counts only what Alice can spend right now. Funds held by an unfinished payment are left out.

Funds reserved by another tabCopy Anchor Link

A payment running in another tab holds the funds it uses. This payment cannot use them, and available leaves them out. If both tabs reach for the same funds at once, one gets lease-refused. Reserved funds lists what is held and by what.

Bob is not registeredCopy Anchor Link

transfer throws a NimbusSdkError with reason recipient-unregistered, and nothing is sent. Ask Bob to open your app and register first.

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