The function template

The SDK has no client class. It exports plain functions, and each one takes an object it acts on as its first argument. There are three such objects, and each lives for a different time.

Three objectsCopy Anchor Link

Each object is made from the one before it. The functions that take each one are grouped below.

flowchart LR
sdk(["SDK"]) --> session(["Session"])
session --> context(["Context"])
sdk -.-> wallets["Wallets and tokens: listWallets, followWallets, openWalletConnection, findMintByIdentifier"]
session -.-> reads["The private account: syncNoteStore, readBalances, readHistory, readRegistration, listReservedSpends, releaseReservedNotes"]
context -.-> flows["Payments: register, deposit, transfer, withdraw, resolvePendingDeposit, refundStrandedDeposit"]

Wallet functions need only the SDK. Reading and syncing the private account needs a session. A payment needs a context, which adds the pool and the services that payment uses.

Create a fresh context right before each payment. It is cheap, and it reads the current pool.

The call shapeCopy Anchor Link

Most functions take three arguments, always in this order:

1. The object it acts on: the SDK, a session or a context.
2. args: what the call is about. These are required.
3. options: how it behaves. Every option has a default, so you can leave any of them out.

Here is a withdrawal, with each part marked:

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

const result = await withdraw(
  // 1. The object: a withdrawal context, made for this one payment.
  context,
  // 2. args: which token, how much and to whom. All required.
  { mint: usdc, amount: 10_000_000n, recipient: bobsWallet },
  // 3. options: each one changes a default.
  { fees: "added", commitment: "finalized" },
);

Where a call needs nothing in args, it takes {}, and you may leave it out.

A few functions differ. loadNimbusSdk takes { cluster } first, since there is no SDK yet. The create…Context functions take a session and options. The sign-in store functions take options at most, and closeNimbusSession takes only a session.

NamesCopy Anchor Link

The verb at the start of a name tells you what the call does:

readBalances and readHistory read only this device and fetch nothing. readRegistration is the exception: it asks Nimbus's context service, since registration happens on Solana.

ValuesCopy Anchor Link

• Amounts are bigint, in the token's smallest unit. 25 USDC is 25_000_000n.
• Addresses are the Address type from @solana/kit.
• Lamports are always named as such, as in priorityFeeLamports.
• Results that can end more than one way have a kind to switch on.

How a function's entry readsCopy Anchor Link

Each function is documented once, in the API reference. Every entry has the same parts, in this order:

1. Summary. One or two sentences on what it does.
2. Signature. The function's TypeScript declaration.
3. Example. A short call, type-checked against the SDK when the site is built.
4. Parameters. Every argument and option, with its type and meaning.
5. Returns. What it resolves to, and what each kind means.
6. Throws. The errors it throws, and why.
7. Details. The finer points, collapsed until you open them.

See readBalances for a short entry.