@zerc20/wallet-sdk 0.0.0-stage → 0.2.0

package/src/errors.ts

@@ -0,0 +1,63 @@
+// What can go wrong, by code, so that an app can tell the user what to do.
+
+import { BaseError, UserRejectedRequestError } from 'viem';
+
+export type ErrorCode =
+  /** Not enough value for the amount and its fees, even counting what is still settling. */
+  | 'insufficient-funds'
+  /** No single JoinSplit pays it, but merging the spendable notes and deposits first would: `consolidate`, then pay.
+   * `fees({ kind: 'consolidate' })` tells how many rounds that takes. */
+  | 'needs-consolidation'
+  /** What is spendable now does not pay it, but notes or deposits are still settling (screening, awaiting
+   * a root, or the change of an operation in flight): pay again once `balances()` shows them spendable. */
+  | 'funds-settling'
+  /** The fees are above the `maxFee` the caller allowed. */
+  | 'fee-too-high'
+  /** The address never registered for private payments: pay it publicly or ask for a receive code. */
+  | 'recipient-not-registered'
+  /** The withdrawal's recipient (or a merge's fee recipient) fails the attester's AML screening: withdraw elsewhere. */
+  | 'recipient-refused'
+  /** A contract account: it cannot sign the messages a wallet needs. */
+  | 'unsupported-account'
+  /** The user declined a signature or a transaction in their wallet. */
+  | 'user-rejected'
+  /** The wallet is open in another tab or window: close it there (`close()`), then open it here. */
+  | 'wallet-in-use'
+  /** This wallet object was closed (`close()`): open the wallet again to go on. */
+  | 'wallet-closed'
+  /** A server answered something that does not match the chain. */
+  | 'indexer-mismatch'
+  /** The attester's (or the merge prover's) enclave did not prove it is the published release. */
+  | 'attester-unverified'
+  /** A service did not answer, or refused. The operation can be resumed. */
+  | 'unavailable'
+  /** Bad input from the caller. */
+  | 'invalid';
+
+export class WalletError extends Error {
+  constructor(
+    readonly code: ErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'WalletError';
+  }
+}
+
+export const fail = (code: ErrorCode, message: string): never => {
+  throw new WalletError(code, message);
+};
+
+const declined = (e: unknown) =>
+  e instanceof UserRejectedRequestError || (e as { code?: number } | null)?.code === 4001;
+
+/** Maps a declined wallet prompt to `user-rejected`, also where viem wraps it (a transaction's, in an execution error). */
+export async function guard<T>(p: Promise<T>): Promise<T> {
+  try {
+    return await p;
+  } catch (e) {
+    if (declined(e) || (e instanceof BaseError && e.walk(declined)))
+      throw new WalletError('user-rejected', 'declined in the wallet');
+    throw e;
+  }
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+// @zerc20/wallet-sdk: a zERC20 wallet for browsers and Node.
+//
+//   const wallet = await Wallet.open({ network, walletClient, seed, persist });
+//   await wallet.sync();                     // or wallet.autoSync(render)
+//   wallet.balances();                       // spendable, and what is pending and why
+//   await (await wallet.deposit({ token, amount })).wait();
+//   const q = await wallet.fees({ kind: 'send', token, amount });
+//   await (await wallet.send({ to: '0x…', token, amount, maxFee: q.fee })).wait();
+//
+// Nothing secret leaves the device unencrypted: JoinSplit proofs are made here, a merge's by the merge prover, and the
+// attester and the prover get the witness sealed to an enclave whose measurement the wallet checks. Servers are only
+// ever asked for what every wallet downloads.
+
+export { Chain, type Referrer, type Token, MAX_REFERRAL_BPS, NATIVE, UNWRAP_INTENT } from './chain.js';
+export { type ErrorCode, WalletError } from './errors.js';
+export {
+  type AttesterTrust,
+  type ChainConfig,
+  type Circuit,
+  type Network,
+  NITRO_ROOT_SHA256,
+  checkNetwork,
+  networkFromJson,
+} from './network.js';
+export { type Payment, PointOfSale, type PosToken, type Sale, type SaleStatus } from './pos.js';
+export { seedFromSignature } from './seed.js';
+export {
+  type Activity,
+  type Balance,
+  type CoinInfo,
+  type CoinState,
+  type DepositInfo,
+  type DepositStep,
+  type FeeQuote,
+  type OpenOptions,
+  type Operation,
+  type OperationKind,
+  type OperationStatus,
+  type PendingReason,
+  Wallet,
+} from './wallet.js';

package/src/network.ts

@@ -0,0 +1,94 @@
+// Where a wallet finds everything: per chain, its contracts, servers and artifacts. Apps pass one of these to
+// `Wallet.open`; nothing here is secret.
+
+import type { Address } from 'viem';
+import { fail } from './errors.js';
+
+/** A proving key set: the circuit's wasm and zkey, pinned by SHA-256 (from the setup's `setup.json`). */
+export interface Circuit {
+  wasm: string;
+  zkey: string;
+  wasmSha256: string;
+  zkeySha256: string;
+}
+
+/** How to trust an enclave's key: the attester's, or the merge prover's. */
+export type AttesterTrust =
+  /** A Nitro Enclave: the document must chain to the root with this SHA-256 and measure this PCR0 (hex). */
+  | { pcr0: string; rootSha256: string }
+  /** A development attester, which has no document: its key is taken at its word. Never on a real network. */
+  | { development: true };
+
+/** The AWS Nitro Enclaves root certificate (G1), SHA-256 over its DER. */
+export const NITRO_ROOT_SHA256 = '641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b';
+
+export interface ChainConfig {
+  chainId: bigint;
+  /** Used for every read and for waiting on receipts, never the wallet's own RPC. */
+  rpcUrl: string;
+  verifier: Address;
+  depositAddressFactory: Address;
+  indexer: string;
+  asp: string;
+  attester: string;
+  attesterTrust: AttesterTrust;
+  transactRelayer: string;
+  depositRelayer: string;
+  /** The native currency, which its native zERC20 is named after; ETH if absent. For a chain an app does not know. */
+  nativeCurrency?: { name: string; symbol: string };
+}
+
+export interface Network {
+  name: string;
+  chains: ChainConfig[];
+  /** The note storage canister on the Internet Computer. */
+  storage: { host: string; canisterId: string };
+  circuits: { joinsplit: Circuit; rageexit: Circuit };
+  /** The merge prover (`backend/merge-prover`), one shared by every chain, and how to trust its enclave, which sees each
+   * merge's witness while it proves it. Without it the wallet cannot consolidate. */
+  mergeProver?: { url: string; trust: AttesterTrust };
+}
+
+/** A `Network` from JSON, where chain ids are strings (JSON has no bigints), as scripts/dev-stack.sh writes it. */
+export function networkFromJson(json: string): Network {
+  const n = JSON.parse(json) as Network & { chains: (ChainConfig & { chainId: string })[] };
+  return { ...n, chains: n.chains.map((c) => ({ ...c, chainId: BigInt(c.chainId) })) };
+}
+
+/** The local chain development settings are for. */
+export const LOCAL_CHAIN_ID = 31337n;
+
+const local = (url: string) => ['localhost', '127.0.0.1', '[::1]'].includes(new URL(url).hostname);
+
+/** Throws on settings that only a local development network may have: servers over plain HTTP (anyone on the path
+ * could swap a deposit address or a fee), a development attester or merge prover (its host would read every witness,
+ * the openings of what it spends included), or a Nitro trust that does not pin the AWS root and a real enclave. */
+export function checkNetwork(n: Network): void {
+  const bad = (what: string) => fail('invalid', `network ${n.name}: ${what}`);
+  const servers = (urls: string[]) => {
+    for (const u of urls) if (new URL(u).protocol !== 'https:' && !local(u)) bad(`${u} is not https`);
+  };
+  servers([n.storage.host]);
+  // artifacts are pinned by SHA-256, and Node reads them from disk
+  for (const c of [n.circuits.joinsplit, n.circuits.rageexit]) {
+    for (const u of [c.wasm, c.zkey]) if (!u.startsWith('file:')) servers([u]);
+  }
+  const trusted = (chains: ChainConfig[], what: string, t: AttesterTrust) => {
+    if ('development' in t) {
+      for (const c of chains) if (c.chainId !== LOCAL_CHAIN_ID) bad(`a development ${what} on chain ${c.chainId}`);
+    } else {
+      if (t.rootSha256.toLowerCase() !== NITRO_ROOT_SHA256) bad(`the ${what} trust does not pin the AWS Nitro root`);
+      // a debug enclave measures all zeros
+      const pcr0 = t.pcr0.replace(/^0x/i, '');
+      if (!/^[0-9a-f]{96}$/i.test(pcr0) || /^0+$/.test(pcr0)) bad(`PCR0 ${t.pcr0} is not a release enclave's`);
+    }
+  };
+  for (const c of n.chains) {
+    servers([c.rpcUrl, c.indexer, c.asp, c.attester, c.transactRelayer, c.depositRelayer]);
+    trusted([c], 'attester', c.attesterTrust);
+  }
+  if (n.mergeProver) {
+    servers([n.mergeProver.url]);
+    trusted(n.chains, 'merge prover', n.mergeProver.trust);
+  }
+}

package/src/pos.ts

@@ -0,0 +1,415 @@
+// A point of sale with no key: it makes burn addresses for a merchant's wallet in the lane the wallet gave it
+// (`Wallet.posKey`), records them there ahead of need, hands out one per sale, and follows what reaches each from what
+// every wallet downloads. Stolen, it gives away which addresses are the merchant's, and nothing else: the merchant's
+// wallet alone spends what they receive, merges it and withdraws it.
+
+import { BURN_BLOCK, CanisterClient, lookupRecipient, writePosBlock } from '@zerc20/storage-sdk';
+import {
+  type Address,
+  type Hex,
+  bytesToHex,
+  getAddress,
+  hexToBytes,
+  isAddress,
+  isHex,
+  numberToHex,
+  zeroAddress,
+} from 'viem';
+import { Chain, type Token } from './chain.js';
+import { core, initCore, posBurnAddress } from './core.js';
+import { fail } from './errors.js';
+import { type ChainConfig, type Network, checkNetwork } from './network.js';
+import { scan } from './scan.js';
+import { Asp, Indexer } from './servers.js';
+import { registerDeposit } from './services.js';
+import type { DepositRecord } from './state.js';
+import { applyHits, commitmentFields, commitmentTx, dropReorged, readDecisions, readTransfers } from './sync.js';
+
+/** The longest a refill waits once a token's addresses run low: a write at a random time after the sale that drew
+ * them down, not right after it, so that the write's time does not mark that sale. */
+const REFILL_WITHIN_MS = 10 * 60_000;
+
+/** What a point of sale needs of a token: where it is, and its id for the burn addresses' derivation and tags. */
+export type PosToken = Pick<Token, 'chainId' | 'tokenId' | 'address'>;
+
+export interface Sale {
+  /** Its burn address, which no other sale has. */
+  id: Address;
+  chainId: bigint;
+  tokenId: number;
+  token: Address;
+  /** Paid in the token by a transfer here. */
+  burnAddress: Address;
+  /** Paid in the underlying asset here, which the deposit relayer then wraps into the burn address: once one is
+   * registered (`registerDeposit`). */
+  depositAddress: Address | null;
+  /** What the deposit relayer takes out of each payment to `depositAddress`: ask for `amount` plus it. */
+  depositFee: bigint | null;
+  /** Where `depositAddress` sends back what it cannot wrap, and what a rage exit returns: the payer's, or the
+   * merchant's. On chain for anyone to read once the address is first flushed. */
+  refundTo: Address | null;
+  /** What was asked, if anything: the point of sale's alone, never sent anywhere. */
+  amount: bigint | null;
+  createdMs: number;
+}
+
+export interface Payment {
+  amount: bigint;
+  /** Who paid the burn address: the payer, or for a payment through `depositAddress` the deposit address itself. */
+  sender: Address;
+  /** `confirming` until final (a reorg may still drop it), then `screening` until the ASP decides. `rejected` goes back
+   * to its sender by the merchant's rage exit, or to `refundTo` from a deposit address. */
+  state: 'confirming' | 'screening' | 'approved' | 'rejected';
+  /** The transaction that paid the burn address, once the chain shows it: the payer's, or for a payment through
+   * `depositAddress` the deposit relayer's. */
+  txHash: Hex | null;
+}
+
+export interface SaleStatus {
+  sale: Sale;
+  payments: Payment[];
+  /** What is final: every payment but the confirming ones. */
+  received: bigint;
+}
+
+type Watched = Pick<DepositRecord, 'address' | 'watches' | 'found'>;
+
+interface Connection {
+  merchant: Address;
+  /** The zERC20 public key the merchant registered in storage, which its burn addresses are under. */
+  publicKey: Hex;
+  laneKey: Hex;
+  /** Per chain, the lane's first slot not known to be taken. */
+  slots: Record<string, number>;
+  /** Per `chainId:tokenId`, the next counter to derive, and the addresses recorded in the lane that no sale has had. */
+  pools: Record<string, { next: number; ready: Address[] }>;
+}
+
+interface Saved {
+  connection: Connection | null;
+  sales: Sale[];
+  /** What reached each sale's address, as a wallet's deposits keep it, by sale id. */
+  seen: Record<Address, Watched>;
+  /** Each payment's transaction, by `chainId:index`. */
+  txs: Record<string, Hex>;
+}
+
+/** JSON with bigints, which `JSON` itself has no form for. */
+const encode = (v: unknown) =>
+  new TextEncoder().encode(JSON.stringify(v, (_, x: unknown) => (typeof x === 'bigint' ? { $n: `${x}` } : x)));
+const decode = (b: Uint8Array): Saved =>
+  JSON.parse(new TextDecoder().decode(b), (_, x: { $n?: string }) =>
+    x && typeof x === 'object' && typeof x.$n === 'string' ? BigInt(x.$n) : x,
+  ) as Saved;
+
+const same = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
+const pairOf = (token: PosToken) => `${token.chainId}:${token.tokenId}`;
+
+export class PointOfSale {
+  readonly #network: Network;
+  readonly #state: Saved;
+  readonly #persist: { save(bytes: Uint8Array): Promise<void> };
+  readonly #refillWithinMs: number;
+  readonly #chains = new Map<bigint, Chain>();
+  /** The refill running for each token, and the one waiting to. */
+  readonly #fills = new Map<string, Promise<void>>();
+  readonly #timers = new Map<string, ReturnType<typeof setTimeout>>();
+  #storage: Promise<CanisterClient> | undefined;
+  #queue: Promise<unknown> = Promise.resolve();
+  #saving: Promise<unknown> = Promise.resolve();
+
+  private constructor(
+    network: Network,
+    state: Saved,
+    persist: { save(bytes: Uint8Array): Promise<void> },
+    refillWithinMs: number,
+  ) {
+    this.#network = network;
+    this.#state = state;
+    this.#persist = persist;
+    this.#refillWithinMs = refillWithinMs;
+  }
+
+  /** Opens the point of sale's saved state. It keeps which addresses it handed out: lose that, and it may hand one out
+   * twice. One state, one point of sale: two open on it would hand out the same addresses. */
+  static async open(opts: {
+    network: Network;
+    persist: { load(): Promise<Uint8Array | null | undefined>; save(bytes: Uint8Array): Promise<void> };
+    refillWithinMs?: number;
+  }): Promise<PointOfSale> {
+    checkNetwork(opts.network);
+    await initCore();
+    const saved = await opts.persist.load();
+    const state: Saved = saved?.length ? decode(saved) : { connection: null, sales: [], seen: {}, txs: {} };
+    return new PointOfSale(opts.network, state, opts.persist, opts.refillWithinMs ?? REFILL_WITHIN_MS);
+  }
+
+  get connected(): boolean {
+    return this.#state.connection !== null;
+  }
+
+  /** Takes the key `merchant`'s wallet made for it (`Wallet.posKey`), and the public key `merchant` registered in
+   * storage, which every address it makes is under: whoever hands it a key cannot point sales at a key of its own. The
+   * same key again changes nothing. Another one starts over in that lane; the sales made so far are still followed. */
+  connect(merchant: Address, laneKey: Hex): Promise<void> {
+    return this.#exclusive(async () => {
+      if (!isAddress(merchant, { strict: false })) fail('invalid', `${String(merchant)} is not an address`);
+      if (!isHex(laneKey) || laneKey.length !== 66) fail('invalid', 'the key is 32 bytes in hex');
+      const c = this.#state.connection;
+      if (c && same(c.merchant, merchant) && same(c.laneKey, laneKey)) return;
+      const recipient = await lookupRecipient(await this.#client(), hexToBytes(merchant));
+      if (!recipient) fail('invalid', `${merchant} has not registered for private payments: open its wallet once`);
+      for (const t of this.#timers.values()) clearTimeout(t);
+      this.#timers.clear();
+      this.#fills.clear();
+      this.#state.connection = {
+        merchant: getAddress(merchant),
+        publicKey: bytesToHex(recipient!.publicKey),
+        laneKey: laneKey.toLowerCase() as Hex,
+        slots: {},
+        pools: {},
+      };
+      await this.#save();
+    });
+  }
+
+  /** Readies addresses of `token` ahead of its sales: an app calls it for each token it takes, as it starts and after
+   * sales. Nothing happens while enough are ready, or a refill is under way or due. */
+  prepare(token: PosToken): void {
+    chainOf(this.#network, token.chainId);
+    this.#topUp(token);
+  }
+
+  /** How many addresses of `token` are recorded and wait for a sale. */
+  ready(token: PosToken): number {
+    return this.#state.connection?.pools[pairOf(token)]?.ready.length ?? 0;
+  }
+
+  /** A new sale of `token`, at an address no sale has had: one recorded ahead, or, when none is left, one recorded
+   * now. With `via: 'deposit'` it also registers a deposit address in front of it (`registerDeposit`). */
+  async next(opts: { via: 'burn' | 'deposit'; token: PosToken; amount?: bigint; refundTo?: Address }): Promise<Sale> {
+    const { token } = opts;
+    const c = chainOf(this.#network, token.chainId);
+    this.#connection();
+    const { commitmentsFinal: from } = await new Indexer(c.indexer).status();
+    let burnAddress: Address | undefined;
+    while (!(burnAddress = this.#connection().pools[pairOf(token)]?.ready.shift())) await this.#fill(token);
+    // saved as taken before the deposit relayer is asked: a sale that fails half-way never hands it out again
+    const sale: Sale = {
+      id: burnAddress,
+      chainId: token.chainId,
+      tokenId: token.tokenId,
+      token: token.address,
+      burnAddress,
+      depositAddress: null,
+      depositFee: null,
+      refundTo: null,
+      amount: opts.amount ?? null,
+      createdMs: Date.now(),
+    };
+    const watch = { key: tag(token.tokenId, burnAddress), from, scannedTo: from };
+    this.#state.sales.push(sale);
+    this.#state.seen[burnAddress] = { address: burnAddress, watches: [{ tokenId: token.tokenId, watch }], found: [] };
+    await this.#save();
+    this.#topUp(token);
+    return opts.via === 'deposit' ? this.#exclusive(() => this.#register(sale, opts.refundTo)) : sale;
+  }
+
+  /** Registers a deposit address in front of sale `id`, for the underlying asset; the deposit relayer watches it for 7
+   * days. What it cannot wrap (too little, another token) and a rage exit go back to `refundTo`, the merchant's
+   * account if absent: name the payer's, so that neither the merchant's account is on chain nor a payment the ASP
+   * rejects comes back to the merchant. A sale has one: asked again with the same `refundTo`, it is the same. */
+  registerDeposit(id: Address, opts: { refundTo?: Address } = {}): Promise<Sale> {
+    return this.#exclusive(() => this.#register(this.#sale(id), opts.refundTo));
+  }
+
+  async #register(sale: Sale, refundTo: Address | undefined): Promise<Sale> {
+    const to = refundTo ?? this.#connection().merchant;
+    if (!isAddress(to, { strict: false }) || same(to, zeroAddress))
+      return fail('invalid', `${to} is not an address to refund to`);
+    if (sale.depositAddress) {
+      if (same(sale.refundTo!, to)) return sale;
+      return fail('invalid', `sale ${sale.id} already has a deposit address, refunding to ${sale.refundTo}`);
+    }
+    const { depositAddress, fee } = await registerDeposit(this.#chain(sale.chainId), sale.token, sale.burnAddress, to);
+    Object.assign(sale, { depositAddress, depositFee: fee, refundTo: to });
+    await this.#save();
+    return sale;
+  }
+
+  sales(): Sale[] {
+    return [...this.#state.sales];
+  }
+
+  /** What reached each of sales `ids`: every transfer to its burn address, with where each stands. One pass per chain
+   * for them all, reading only what every wallet downloads, so no server learns which addresses it asks about. A chain
+   * that fails keeps what was read before, and its error is returned. */
+  refresh(ids: Address[]): Promise<{ sales: SaleStatus[]; errors: unknown[] }> {
+    return this.#exclusive(async () => {
+      const sales = [...new Map(ids.map((id) => [id.toLowerCase(), this.#sale(id)])).values()];
+      const errors: unknown[] = [];
+      const chains = [...new Set(sales.map((s) => s.chainId))];
+      await Promise.all(
+        chains.map((chainId) =>
+          this.#refreshChain(
+            chainId,
+            sales.filter((s) => s.chainId === chainId),
+          ).catch((e: unknown) => void errors.push(e)),
+        ),
+      );
+      await this.#save();
+      return { sales: sales.map((s) => this.#statusOf(s)), errors };
+    });
+  }
+
+  /** What reached sale `id`, and how much is final. */
+  async status(id: Address): Promise<SaleStatus> {
+    const { sales, errors } = await this.refresh([id]);
+    if (errors.length > 0) throw errors[0];
+    return sales[0];
+  }
+
+  /** What reached sale `id` as of the last `refresh`, asking no server. */
+  lastStatus(id: Address): SaleStatus {
+    return this.#statusOf(this.#sale(id));
+  }
+
+  async #refreshChain(chainId: bigint, sales: Sale[]): Promise<void> {
+    const c = chainOf(this.#network, chainId);
+    const indexer = new Indexer(c.indexer);
+    const seen = sales.map((s) => this.#state.seen[s.id]);
+    const status = await indexer.status();
+    const watches = seen.flatMap((r) => r.watches.map((w) => w.watch));
+    const hits = await scan(watches, 4, (p) => indexer.page('tags', p), status.commitmentsFinal, status.commitments);
+    applyHits([], seen, hits);
+    dropReorged(seen, status.commitmentsFinal);
+    await readTransfers(commitmentFields(indexer), seen);
+    await readDecisions(new Asp(c.asp), seen);
+    // a final payment's transaction is kept; until then it is read again, as a reorg may move what sits at a position
+    const txs = this.#state.txs;
+    await Promise.all(
+      seen
+        .flatMap((r) => r.found)
+        .map(async (f) => {
+          const at = `${chainId}:${f.index}`;
+          if (!f.tentative && txs[at]) return;
+          const tx = await commitmentTx(this.#chain(chainId), indexer, f.index).catch(() => undefined);
+          if (tx === undefined) return;
+          if (tx?.hash) txs[at] = tx.hash;
+          else delete txs[at];
+        }),
+    );
+  }
+
+  #statusOf(sale: Sale): SaleStatus {
+    const payments = this.#state.seen[sale.id].found
+      .filter((f) => f.amount !== null)
+      .map((f): Payment => ({
+        amount: f.amount!,
+        sender: f.sender as Address,
+        state: f.tentative ? 'confirming' : f.asp === null ? 'screening' : f.asp,
+        txHash: this.#state.txs[`${sale.chainId}:${f.index}`] ?? null,
+      }));
+    const received = payments.filter((p) => p.state !== 'confirming').reduce((s, p) => s + p.amount, 0n);
+    return { sale, payments, received };
+  }
+
+  /** Refills `token`'s addresses once they run low: right away when none is left, otherwise at a random time within
+   * `refillWithinMs`. */
+  #topUp(token: PosToken): void {
+    const pair = pairOf(token);
+    const left = this.#state.connection?.pools[pair]?.ready.length ?? 0;
+    if (!this.#state.connection || left >= BURN_BLOCK || this.#fills.has(pair) || this.#timers.has(pair)) return;
+    // a refill that fails is tried again by the next sale, which tells why
+    const fill = () => void this.#fill(token).catch(() => undefined);
+    if (left === 0) return fill();
+    const timer = setTimeout(() => {
+      this.#timers.delete(pair);
+      fill();
+    }, Math.random() * this.#refillWithinMs);
+    (timer as { unref?: () => void }).unref?.(); // a process need not stay up for it
+    this.#timers.set(pair, timer);
+  }
+
+  /** Makes `BURN_BLOCK` more addresses of `token`, records them in the lane, then adds them to its pool: one refill at
+   * a time per token. One that fails changes nothing. */
+  #fill(token: PosToken): Promise<void> {
+    const pair = pairOf(token);
+    const running = this.#fills.get(pair);
+    if (running) return running;
+    clearTimeout(this.#timers.get(pair));
+    this.#timers.delete(pair);
+    const run: Promise<void> = (async () => {
+      const c = this.#connection();
+      const pool = (c.pools[pair] ??= { next: 0, ready: [] });
+      const k = pool.next;
+      const laneKey = hexToBytes(c.laneKey);
+      const burns = await Promise.all(
+        Array.from({ length: BURN_BLOCK }, (_, i) =>
+          posBurnAddress(laneKey, token.chainId, token.tokenId, k + i, c.publicKey),
+        ),
+      );
+      const block = {
+        chainId: token.chainId,
+        tokenId: token.tokenId,
+        first: k,
+        salts: burns.map((b) => hexToBytes(b.salt)),
+      };
+      const chain = `${token.chainId}`;
+      const slot = await writePosBlock(await this.#client(), laneKey, block, c.slots[chain] ?? 0);
+      if (this.#state.connection !== c) return; // connected to another lane meanwhile
+      c.slots[chain] = Math.max(c.slots[chain] ?? 0, slot);
+      pool.ready.push(...burns.map((b) => b.address));
+      pool.next = k + BURN_BLOCK;
+      await this.#save();
+    })().finally(() => {
+      if (this.#fills.get(pair) === run) this.#fills.delete(pair);
+    });
+    this.#fills.set(pair, run);
+    return run;
+  }
+
+  #connection(): Connection {
+    return this.#state.connection ?? fail('invalid', "not connected: connect the merchant's wallet first");
+  }
+
+  #sale(id: Address): Sale {
+    return this.#state.sales.find((s) => same(s.id, id)) ?? fail('invalid', `no sale ${id}`);
+  }
+
+  #chain(chainId: bigint): Chain {
+    let c = this.#chains.get(chainId);
+    if (!c) this.#chains.set(chainId, (c = new Chain(chainOf(this.#network, chainId))));
+    return c;
+  }
+
+  /** Storage, connected on first use: a point of sale that only follows its sales needs none. */
+  #client(): Promise<CanisterClient> {
+    const { host, canisterId } = this.#network.storage;
+    return (this.#storage ??= CanisterClient.connect(host, canisterId).catch((e: unknown) => {
+      this.#storage = undefined;
+      throw e;
+    }));
+  }
+
+  /** Runs `f` after everything queued before it. */
+  #exclusive<T>(f: () => Promise<T>): Promise<T> {
+    const run = this.#queue.then(f);
+    this.#queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /** Saves the state as it is when the save runs, after every save asked for before: an older state never lands last,
+   * which would hand out again an address taken since. */
+  #save(): Promise<void> {
+    const run = this.#saving.then(() => this.#persist.save(encode(this.#state)));
+    this.#saving = run.catch(() => undefined);
+    return run;
+  }
+}
+
+function chainOf(network: Network, chainId: bigint): ChainConfig {
+  return network.chains.find((c) => c.chainId === chainId) ?? fail('invalid', `the network has no chain ${chainId}`);
+}
+
+const tag = (tokenId: number, address: Address) => numberToHex(core.transferTag(tokenId, address), { size: 4 });

package/src/prove.ts

@@ -0,0 +1,67 @@
+// Groth16 proofs of JoinSplit and RageExit with snarkjs, on the user's device: the witness holds the private keys.
+
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { fail } from './errors.js';
+import type { Circuit } from './network.js';
+
+/** A URL's bytes; `file:` URLs from disk, for Node. */
+export async function readUrl(url: string): Promise<Uint8Array> {
+  if (url.startsWith('file:')) {
+    const fs = 'node:fs/promises';
+    const { readFile } = (await import(/* @vite-ignore */ fs)) as { readFile: (path: URL) => Promise<Uint8Array> };
+    return readFile(new URL(url));
+  }
+  const res = await fetch(url);
+  if (!res.ok) return fail('unavailable', `${url}: HTTP ${res.status}`);
+  return new Uint8Array(await res.arrayBuffer());
+}
+
+const artifacts = new Map<string, Promise<Uint8Array>>();
+
+/** The artifact at `url`, checked against its pinned SHA-256: a swapped proving key could leak the witness. */
+function artifact(url: string, sha: string): Promise<Uint8Array> {
+  let p = artifacts.get(url);
+  if (!p) {
+    p = readUrl(url).then((bytes) => {
+      if (bytesToHex(sha256(bytes)) !== sha.toLowerCase()) fail('invalid', `${url} does not match its SHA-256`);
+      return bytes;
+    });
+    p.catch(() => artifacts.delete(url));
+    artifacts.set(url, p);
+  }
+  return p;
+}
+
+/** `Verifier.Groth16Proof`, with pB in the order the Solidity verifier takes. */
+export interface Groth16 {
+  pA: [bigint, bigint];
+  pB: [[bigint, bigint], [bigint, bigint]];
+  pC: [bigint, bigint];
+}
+
+export async function prove(circuit: Circuit, input: object): Promise<{ proof: Groth16; signals: bigint[] }> {
+  const [wasm, zkey] = await Promise.all([
+    artifact(circuit.wasm, circuit.wasmSha256),
+    artifact(circuit.zkey, circuit.zkeySha256),
+  ]);
+  // loaded on the first proof: an app that only reads balances need not carry snarkjs
+  const { groth16 } = await import('snarkjs');
+  const { proof, publicSignals } = await groth16.fullProve(
+    input,
+    { type: 'mem', data: wasm },
+    { type: 'mem', data: zkey },
+  );
+  const b = (x: string) => BigInt(x);
+  return {
+    proof: {
+      pA: [b(proof.pi_a[0]), b(proof.pi_a[1])],
+      pB: [
+        [b(proof.pi_b[0][1]), b(proof.pi_b[0][0])],
+        [b(proof.pi_b[1][1]), b(proof.pi_b[1][0])],
+      ],
+      pC: [b(proof.pi_c[0]), b(proof.pi_c[1])],
+    },
+    signals: publicSignals.map(b),
+  };
+}