Quickstart

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

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

import { listWallets, openWalletConnection } from "@umbra-privacy/nimbus-solana-web";

const [wallet] = listWallets(sdk);
if (wallet === undefined) throw new Error("Install a Solana wallet first.");

const connection = await openWalletConnection(sdk, { wallet });
switch (connection.kind) {
  case "declined":
    throw new Error("Alice declined to connect.");
  case "no-account":
    throw new Error("The wallet has no account on Solana mainnet.");
  case "connected":
    break;
}
const { signer, transactionVersion } = connection.connected;

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

const opened = await openNimbusSession(
  sdk,
  { connectedWallet: signer },
  { gatewayToken },
);
if (opened.kind === "declined") throw new Error("Alice declined to sign.");
const { session } = opened;

import { createRegistrationContext, register } from "@umbra-privacy/nimbus-solana-web";

if (session.registration.kind === "unregistered") {
  const result = await register(
    await createRegistrationContext(session),
    {},
    { transactionVersion },
  );
  switch (result.kind) {
    case "complete":
      break;
    case "submitted":
      if (result.submission.submission.kind !== "landed") {
        throw new Error("The registration did not land. Try again.");
      }
      break;
    case "declined":
    case "store-refused":
      throw new Error("Nothing was sent. Try again.");
  }
}

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

async function waitUntilRegistered(session: NimbusSession): Promise<void> {
  for (let check = 0; check < 30; check += 1) {
    const standing = await readRegistration(session, {});
    if (standing.kind === "registered") return;
    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }
  throw new Error("Nimbus has not seen the registration yet. Try again shortly.");
}

await waitUntilRegistered(session);

import { address } from "@solana/kit";
import { createDepositContext, deposit } from "@umbra-privacy/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 },
);
if (result.kind !== "submitted") {
  throw new Error(`The deposit was not sent: ${result.kind}.`);
}

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

let outcome: string = result.submission.submission.kind;
if (outcome === "unknown") {
  const resolution = await resolvePendingDeposit(context, {
    submission: result.submission,
  });
  outcome = resolution.kind;
}
if (outcome === "unknown" || outcome === "store-refused") {
  throw new Error("The deposit is still pending. Do not deposit again yet.");
}
if (outcome !== "landed") {
  throw new Error(`The deposit did not land: ${outcome}.`);
}

import type { Balance } from "@umbra-privacy/nimbus-solana-web";
import { readBalances, syncNoteStore } from "@umbra-privacy/nimbus-solana-web";

await syncNoteStore(session, {});
const balances = await readBalances(session, {});

const usdcIn = (state: Balance["state"]): bigint =>
  balances.find((row) => row.mint === usdc && row.state === state)?.total ??
  0n;

console.log("Available:", usdcIn("available"));
console.log("Reserved:", usdcIn("reserved"));

import { readBalances, syncNoteStore } from "@umbra-privacy/nimbus-solana-web";

async function waitUntilAvailable(
  session: NimbusSession,
  mint: Address,
  amount: bigint,
): Promise<void> {
  for (let check = 0; check < 30; check += 1) {
    await syncNoteStore(session, {});
    const balances = await readBalances(session, {});
    const available = balances.find(
      (row) => row.mint === mint && row.state === "available",
    );
    if ((available?.total ?? 0n) >= amount) return;
    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }
  throw new Error("The deposit is not available yet. Try again shortly.");
}

await waitUntilAvailable(session, usdc, 10_000_000n);

import { createTransferContext, transfer } from "@umbra-privacy/nimbus-solana-web";
import type { TransferResult } from "@umbra-privacy/nimbus-solana-web";

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

function describeTransfer(result: TransferResult): string {
  switch (result.kind) {
    case "relayed":
      switch (result.settlement.kind) {
        case "landed":
          return "Bob has been paid.";
        case "failed":
          return "The payment failed on Solana. Nothing moved.";
        case "pending":
        case "not-followed":
          return "The payment is on its way.";
      }
    case "refused":
      return `Nothing was sent: ${result.refusal.kind}.`;
    case "relay-refused":
    case "unsent":
    case "merge-failed":
      return "The payment was not sent. Try again.";
  }
}
console.log(describeTransfer(result));

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

const result = await withdraw(await createWithdrawalContext(bobSession), {
  mint: usdc,
  amount: 5_000_000n,
  recipient: bobSession.walletAddress,
});
if (result.kind === "relayed" && result.settlement.kind === "landed") {
  console.log("Bob withdrew 5 USDC.");
}