Load the SDK

loadNimbusSdk is the first call your app makes. It reads the settings the SDK ships for mainnet, checks the browser, and loads the SDK's WebAssembly. Every other function takes the NimbusSdk it returns, directly or through a session.

Load it once per page. One SDK serves any number of sessions, and it holds no keys.

Load itCopy Anchor Link

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

const sdk = await loadNimbusSdk(
  { cluster: "mainnet" },
  { assetsBaseUrl: "/nimbus/" },
);

assetsBaseUrl is the directory your app serves the SDK's files from, ending with /. Serve the SDK's files shows how to put them there.

Loading asks no wallet for anything. It fetches only the SDK's WebAssembly. Nimbus's services are first reached when a session opens or a payment runs.

The mainnet presetCopy Anchor Link

The SDK ships a preset for mainnet. It holds the programs, the tokens, every service endpoint and the proving keys, the large files each proof is built from. So your app passes only assetsBaseUrl.

These are the mainnet preset's endpoints, read from the SDK when this site was built:

primitivesWasm comes from assetsBaseUrl, so you rarely pass it yourself.

Replace an endpointCopy Anchor Link

Pass endpoints to replace any of the preset's, one at a time. The rest keep their preset values. The most common case is your own Solana RPC:

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

const sdk = await loadNimbusSdk(
  { cluster: "mainnet" },
  {
    assetsBaseUrl: "/nimbus/",
    endpoints: { rpc: "https://rpc.example.com" },
  },
);

The example app does the same when its settings name an RPC.

Endpoints shows how to point the SDK at services you run yourself.

If you replace an endpoint the gateway fronts, your replacement receives the session's gateway token. Point it only at a host you trust.

What your app reads from itCopy Anchor Link

Treat every field of the SDK as read-only. These are the ones an app usually reads:

Refuse an unpinned buildCopy Anchor Link

A packed copy of the package, the kind a registry serves, is always pinned. A copy built from source can be unpinned, and then runs its files unchecked. Refuse to go on in production if you see it:

if (sdk.settings.assetPinning !== "pinned") {
  throw new Error("This build runs the SDK's files unchecked.");
}

What it checksCopy Anchor Link

Before it returns, loadNimbusSdk makes sure the SDK can run safely on this page. Each failed check throws a NimbusSdkError:

The prover worker is checked the same way when the first proof starts. Its script, and each file it loads, must match the SHA-256 the package pins.

Turn each reason into a message your user can act on:

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

function describeLoadFailure(thrown: unknown): string {
  if (!isNimbusSdkError(thrown)) return "The private balance could not load.";
  switch (thrown.reason) {
    case "unsupported-browser":
      return "This browser cannot run private payments. Try a current Chrome, Firefox or Safari.";
    case "service-unavailable":
      return "The app's files could not be fetched. Try again.";
    case "misconfigured":
    case "dependency-nonconforming":
    case "unreadable":
      return "This app is set up wrongly. Please tell its developers.";
    case "wallet-unsupported":
    case "unauthorized":
    case "recipient-unregistered":
    case "account-unregistered":
      return "The private balance could not load.";
  }
}

Log thrown.message as well. It names the endpoint, file or browser feature at fault.

NextCopy Anchor Link