API reference

import {
	createUmbrClient,
	verifyProof,
	networks,
	fileStore,
	UmbrError,
} from "@umbr/sdk";

import type { Proof, VerifyResult, Note, PayrollLine, ClientOptions, NoteStore } from "@umbr/sdk";

function createUmbrClient(options: ClientOptions): UmbrClient;

const umbr = createUmbrClient({
	network: networks.tempoModerato,
	wallet,                                    // browser
	relayer: "default",
	limits: { perPayment: "2.00", perDay: "50.00" },
});

umbr.address; // "umbr1qexample...you"

const networks: {
	tempoModerato: Network;     // Tempo testnet, chain id 42431
	robinhoodTestnet: Network;  // Robinhood Chain testnet, chain id 46630
	tempo: Network;             // chain id 4217, usable only once configured
	robinhood: Network;         // chain id 4663, usable only once configured
};

const { chainId, assets, configured } = networks.robinhoodTestnet;
// 46630, ["USDG"], true when NEXT_PUBLIC_UMBR_POOL_46630 and its start block are set

umbr.shield(args: { asset: string; amount: string }): Promise<{ txHash: `0x${string}`; notes: Note[] }>;

const { txHash, notes } = await umbr.shield({ asset: "pathUSD", amount: "250.00" });

umbr.send(args: {
	to: string;        // "umbr1q..."
	asset: string;
	amount: string;
	memo?: string;
}): Promise<{ txHash: `0x${string}`; paymentId: string }>;

const { paymentId } = await umbr.send({
	to: "umbr1qexample...ana",
	asset: "pathUSD",
	amount: "40.00",
	memo: "Invoice 0192",
});

umbr.links.create(args: { asset: string; amount: string; expiresIn: "1d" | "7d" | "30d" }): Promise<{ url: string; id: string }>;
umbr.links.claim(url: string): Promise<{ txHash: `0x${string}` }>;
umbr.links.revoke(id: string): Promise<{ txHash: `0x${string}` }>;

umbr.unshield(args: { asset: string; amount: string; to: `0x${string}` }): Promise<{ txHash: `0x${string}` }>;

await umbr.unshield({ asset: "pathUSD", amount: "60.00", to: "0xYourPublicWallet" });

umbr.balance(asset: string): Promise<string>;
umbr.balances(): Promise<Record<string, string>>;

await umbr.balance("pathUSD"); // "210.00"
await umbr.balances();         // { pathUSD: "210.00", AlphaUSD: "0.00" }

umbr.notes.sync(): Promise<void>;
umbr.notes.list(filter?: { asset?: string }): Promise<Note[]>;
umbr.on(event: "payment", handler: (p: IncomingPayment) => void): () => void;

const off = umbr.on("payment", (p) => console.log(p.amount, p.asset, p.memo));
await umbr.notes.sync();
const notes = await umbr.notes.list({ asset: "pathUSD" });
off(); // stop listening

umbr.payroll.run(args: { asset: string; lines: PayrollLine[] }): Promise<{
	id: string;
	txHashes: `0x${string}`[];
	lines: (PayrollLine & { status: "settled" | "failed" })[];
}>;
umbr.payroll.parseCsv(text: string): PayrollLine[];
umbr.payroll.schedule(args: {
	asset: string;
	lines: PayrollLine[];
	every: "week" | "month";
	startAt: string | Date;
}): Promise<{ id: string }>;

const lines = umbr.payroll.parseCsv(`address,amount,label
umbr1qexample...ana,4200.00,Design
umbr1qexample...ben,3850.00,Support`);

const run = await umbr.payroll.run({ asset: "USDG", lines });

umbr.prove(args: {
	claim: "balance-exact" | "balance-at-least" | "payment" | "payroll-total";
	asset?: string;
	amount?: string;
	payment?: string;               // paymentId, for claim "payment"
	run?: string;                   // run id, for claim "payroll-total"
	reveal?: "exact" | "at-least";  // for claim "payment"
	audience: string;
	expiresIn: "1d" | "7d" | "30d";
}): Promise<Proof>;

const proof = await umbr.prove({
	claim: "payment",
	payment: paymentId,
	reveal: "at-least",
	amount: "300.00",
	audience: "Northwind Leasing",
	expiresIn: "7d",
});
proof.link; // a /verify link you can share

function verifyProof(input: Proof | string, options?: { network?: Network }): Promise<VerifyResult>;

const result = await verifyProof(pastedJsonOrLink);
if (!result.valid || result.expired) reject();
else accept(result.statement, result.audience);

import { UmbrError } from "@umbr/sdk";

try {
	await umbr.send({ to, asset: "pathUSD", amount: "75.00" });
} catch (err) {
	if (!(err instanceof UmbrError)) throw err;
	switch (err.code) {
		case "INSUFFICIENT_PRIVATE_BALANCE": return askToShield();
		case "RELAYER_REJECTED": return retryWithoutRelayer();
		default: throw err;
	}
}

type Proof = {
	format: "umbr.disclosure/1";
	claim: "balance-exact" | "balance-at-least" | "payment" | "payroll-total";
	json: string;   // the full proof (format "umbr.disclosure/1"), safe to send to the reader
	text: string;   // the same proof as one line: "umbrproof1:" + base64url(json)
	link: string;   // https://umbr.trade/verify#... with the proof embedded
};

type VerifyResult = {
	valid: boolean;
	claim: Proof["claim"];
	statement: string;   // e.g. "Holds at least 1,000.00 pathUSD"
	audience: string;
	expiresAt: Date;
	expired: boolean;
};

type Note = {
	commitment: `0x${string}`;
	asset: string;
	amount: string;
	spent: boolean;
	createdAt: Date;
};

type PayrollLine = {
	to: string;      // "umbr1q..."
	amount: string;
	label?: string;  // stays on your device
};

type ClientOptions = {
	network: Network;
	wallet?: WalletClient;          // viem, for browsers
	signer?: `0x${string}`;        // private key, for servers and agents only
	relayer?: "default" | string | false;
	limits?: { perPayment?: string; perDay?: string };
	storage?: NoteStore;
};

interface NoteStore {
	get(key: string): Promise<string | undefined>;
	set(key: string, value: string): Promise<void>;
	delete(key: string): Promise<void>;
	keys(prefix?: string): Promise<string[]>;
}