@zerc20/wallet-sdk 0.0.0-stage → 0.1.0

package/src/wallet.ts

@@ -0,0 +1,1297 @@
+// The wallet an app works with. Amounts are bigints in a token's base units.
+
+import {
+  CanisterClient,
+  type Signer,
+  type SyncState,
+  codeKey,
+  commit,
+  decodeCode,
+  encodeCode,
+  lookupRecipient,
+  nextPosLane,
+  planDeposit,
+  planPosLane,
+  posKey,
+  registeredViewKey,
+} from '@zerc20/storage-sdk';
+import {
+  type Account,
+  type Address,
+  type Hex,
+  type WalletClient,
+  bytesToHex,
+  formatUnits,
+  hexToBytes,
+  isAddress,
+  numberToHex,
+} from 'viem';
+import { Chain, NATIVE, type Token, erc20Abi, tokenAbi } from './chain.js';
+import { type Ctx, type SpendKey, chainCtx, chainState, spendKey, walletSees } from './context.js';
+import { burnAddressFor, core, initCore } from './core.js';
+import { type ErrorCode, WalletError, fail, guard } from './errors.js';
+import { type Network, checkNetwork } from './network.js';
+import { Asp, Indexer, type IndexerStatus, PAGE } from './servers.js';
+import { rageExit } from './rageExit.js';
+import { registerDeposit, relayerFees } from './services.js';
+import {
+  type Destination,
+  type MergeStep,
+  type SpendData,
+  type Step,
+  advanceSpend,
+  chosenSettling,
+  coins,
+  grossed,
+  inputsOf,
+  landed,
+  maxPayment,
+  mergePool,
+  mergeRound,
+  payWith,
+  planStep,
+  roundsToMerge,
+  settling,
+  withdrawalOf,
+} from './spend.js';
+import {
+  type DepositOperation,
+  type OperationRecord,
+  type WalletState,
+  emptyWalletState,
+  openState,
+  sealState,
+} from './state.js';
+import {
+  WAIT_MS,
+  commitmentTx,
+  recordBurn,
+  storageState,
+  syncAll,
+  takeRefresh,
+  tokenIds,
+  topUpBurns,
+  unusedBurn,
+} from './sync.js';
+
+const DAY_MS = 86_400_000;
+/** The ledger's bound outside an emergency. */
+const NO_BOUND = 2n ** 64n - 1n;
+
+export interface OpenOptions {
+  network: Network;
+  /** The user's wallet (MetaMask, WalletConnect, ...) as a viem client with its account. */
+  walletClient: WalletClient;
+  /** The 32-byte root of every key. See `seedFromSignature`. */
+  seed: Uint8Array;
+  /** Where the encrypted state lives between sessions. */
+  persist: { load(): Promise<Uint8Array | null | undefined>; save(bytes: Uint8Array): Promise<void> };
+  /** Where a wallet with no saved state starts looking: the block its seed was first used at, or roughly when. Without
+   * it, an address registered before is looked for from the chain's start, and a new one from now on. */
+  birthday?: bigint | Date;
+}
+
+/** What a deposit, or a deposit address, waits on: for an app to show while it does. */
+export type DepositStep =
+  /** Behind another call of this wallet: a sync, or another operation. */
+  | 'queued'
+  /** Recording a fresh burn address in storage first, a proof of work then a storage write (seconds). Only when none
+   * was recorded ahead, as on a token's first deposit, or a second one before a sync has recorded the next. */
+  | 'burn-address'
+  /** The wallet is asked to approve the token to take the underlying asset; then the approval is mined (a block). */
+  | 'approve'
+  /** The wallet is asked to send the wrap into the burn address, or with `wrapped`, the transfer. */
+  | 'wrap';
+
+/** Why an amount is not spendable yet. */
+export type PendingReason =
+  /** Announced by the payer, and not yet read on chain. */
+  | 'incoming'
+  /** Waiting for a proved root that covers it (minutes). */
+  | 'awaiting-root'
+  /** Waiting for a proved root, which none will be until the protocol recovers: a forged root was proved, and the
+   * protocol is in an emergency. A deposit can be rage-exited meanwhile. */
+  | 'roots-halted'
+  /** A deposit the ASP has not decided on yet. */
+  | 'screening';
+
+export interface Balance {
+  token: Token;
+  spendable: bigint;
+  pending: { amount: bigint; reason: PendingReason }[];
+  /** Deposits the ASP rejected: only `rageExit` returns them, to their sender. */
+  blocked: bigint;
+}
+
+export interface Activity {
+  /** The same across syncs and on every device of the wallet: `kind:chainId:index` of the commitment it made or found
+   * (a payment's or withdrawal's: its change's). One shown from this device's operation has the operation's id. */
+  id: string;
+  /** `sale`: a payment to an address one of this wallet's points of sale handed out. `merged`: a consolidation folded
+   * notes and deposits into one note. `returned`: a deposit rage-exited to its sender. */
+  kind: 'received' | 'sent' | 'deposited' | 'sale' | 'withdrawn' | 'merged' | 'returned';
+  token: Token;
+  amount: bigint;
+  /** What a payment, withdrawal or merge cost besides `amount`: the relayer's fee and the protocol's cut. Null where it
+   * paid none. */
+  fee: bigint | null;
+  /** The other side, where known: a payer's claimed address (unverified), where a payment or withdrawal went, or whom a
+   * returned deposit went back to. */
+  counterparty: Address | null;
+  /** What the counterparty alone does not say: the receive code a payment went to (it has no counterparty), or the
+   * deposit address a deposit came through (its counterparty, which forwarded what was sent to it). */
+  via: { code: string } | { depositAddress: Address } | null;
+  /** The burn address of this wallet's that a deposit or a sale reached: for a sale, its id at the point of sale. */
+  burnAddress: Address | null;
+  /** When it reached the chain: its block's time. Until that is read, when storage recorded it; for a failed attempt,
+   * when it started. */
+  at: Date | null;
+  /** Its place in the commitment tree, `chainId:index`: a deposit's (also a returned one's), a note's received or
+   * merged, or a payment's or withdrawal's change. */
+  coin: string | null;
+  /** Its transaction, where the wallet keeps it: a rage exit's, or one shown from this device's operation.
+   * `transaction` finds any. */
+  txHash: Hex | null;
+  /** `done` once on chain (in a block: a reorg may still take it back until final), `failed` for a payment or
+   * withdrawal that cannot land, shown only on the device that tried it. What is not on chain yet is not activity:
+   * an operation under way is in `operations()`, a note only announced is `incoming` in `balances()`. */
+  status: 'done' | 'failed';
+}
+
+/** An unspent note or deposit on chain: what payments and consolidations spend, now or once it settles. */
+export interface CoinInfo {
+  /** Its place in the commitment tree, `chainId:index`. A deposit's is the id `rageExit` and `consolidate` take. */
+  id: string;
+  kind: 'note' | 'deposit';
+  token: Token;
+  amount: bigint;
+  /** Spendable, why not yet, `spending` (an input of an operation under way), or `blocked` (a deposit the ASP
+   * rejected: only `rageExit` returns it). */
+  state: 'spendable' | Exclude<PendingReason, 'incoming'> | 'spending' | 'blocked';
+  /** A note's payer (as claimed, unverified) or a deposit's sender, where known. */
+  from: Address | null;
+  /** For a deposit in `screening`, when the ASP should decide it: an estimate, null until there is one. */
+  screenedBy: Date | null;
+}
+
+export interface DepositInfo {
+  id: string;
+  /** The burn address it was sent to. */
+  address: Address;
+  /** Handed out by one of this wallet's points of sale (`posKey`), rather than for this wallet's own use. */
+  managed: boolean;
+  token: Token;
+  /** Unknown until its commitment is read: a sync after it lands. It is read again once final. */
+  amount: bigint | null;
+  sender: Address | null;
+  state: 'screening' | 'approved' | 'rejected' | 'spent';
+}
+
+/** A send's or withdrawal's recipient gets all of its amount, and the private balance pays `fee` on top. */
+export interface FeeQuote {
+  /** To the relayer. */
+  relayer: bigint;
+  /** The protocol's cut of the public withdrawal: a withdrawal's, or the one that pays the relayer. */
+  protocol: bigint;
+  /** `relayer + protocol`: the `maxFee` this quote passes. */
+  fee: bigint;
+  /** Transactions needed: one JoinSplit for a send or a withdrawal, a consolidation's merges (each pays the relayer's
+   * fee again). */
+  steps: number;
+}
+
+export type OperationKind = OperationRecord['kind'];
+export type OperationStatus = OperationRecord['status'];
+export type CoinState = CoinInfo['state'];
+
+export interface Operation {
+  readonly id: string;
+  readonly kind: OperationKind;
+  /** The chain it is on: its token's. */
+  readonly chainId: bigint;
+  readonly status: OperationStatus;
+  readonly error: string | undefined;
+  /** Why it failed, the code `wait()` throws. */
+  readonly errorCode: ErrorCode | undefined;
+  /** While pending, why its next step has kept failing since `since`: an error trying again may get past (a service
+   * down, a server behind the chain, or one of the wallet's own it cannot tell apart). It is tried again every sync;
+   * null once a try goes through or only waits. */
+  readonly retrying: { message: string; code: ErrorCode | undefined; since: Date } | null;
+  /** The transactions it sent so far: a deposit's, a payment's one, a consolidation's one per round. */
+  readonly txHashes: Hex[];
+  /** How far a send, withdrawal or consolidation round has come, for an app to show; null for a deposit, or between
+   * rounds. It moves during a sync: read it while one runs. */
+  readonly stage: Step['stage'] | MergeStep['stage'] | null;
+  /** Whom a deposit pays, when it goes into their burn address (`deposit({ to })`); null otherwise. */
+  readonly to: Address | null;
+  /** Syncs until the operation is done; throws if it fails. */
+  wait(): Promise<void>;
+}
+
+export class Wallet {
+  readonly #ctx: Ctx;
+  #tokens: Token[] = [];
+  #status = new Map<bigint, IndexerStatus & { halted: boolean }>();
+  #queue: Promise<unknown> = Promise.resolve();
+  /** Calls running or queued. */
+  #busy = 0;
+  #release = () => {};
+  #closed = new AbortController();
+
+  private constructor(ctx: Ctx) {
+    this.#ctx = ctx;
+  }
+
+  /** Lets this wallet open again: in another tab, or here for another account. This object is done with: what is
+   * queued fails with `wallet-closed`, a burn address search stops, and the wallet is let go once the task under way
+   * ends, so that two never write its state at once. */
+  close(): Promise<void> {
+    this.#closed.abort(new WalletError('wallet-closed', 'this wallet was closed: open it again'));
+    return this.#queue.then(() => this.#release());
+  }
+
+  get address(): Address {
+    return this.#ctx.address;
+  }
+
+  /** Opens the wallet. The first time on this address, registers it for payments: one signature. */
+  static async open(opts: OpenOptions): Promise<Wallet> {
+    await initCore();
+    checkNetwork(opts.network);
+    if (opts.seed.length !== 32) fail('invalid', 'the seed is 32 bytes');
+    const account = opts.walletClient.account ?? fail('invalid', 'the wallet client has no account');
+    const release = await lockWallet(account.address);
+    try {
+      return await Wallet.#open(opts, account, release);
+    } catch (e) {
+      release();
+      throw e;
+    }
+  }
+
+  static async #open(opts: OpenOptions, account: Account, release: () => void): Promise<Wallet> {
+    const address = account.address;
+    const chains = opts.network.chains.map((config) => ({
+      config,
+      chain: new Chain(config),
+      indexer: new Indexer(config.indexer),
+      asp: new Asp(config.asp),
+    }));
+    const code = await chains[0]?.chain.client.getCode({ address });
+    // an EIP-7702 delegated account is still an EOA that signs
+    if (code && code !== '0x' && !code.startsWith('0xef0100'))
+      fail('unsupported-account', 'contract accounts cannot sign for a wallet');
+    const signer: Signer = async (message) =>
+      hexToBytes(await guard(opts.walletClient.signMessage({ account, message })));
+    const storage = await CanisterClient.connect(opts.network.storage.host, opts.network.storage.canisterId);
+    const publicKey = hexToBytes((core.spendKey(opts.seed) as SpendKey).publicKey);
+    const saved = await opts.persist.load();
+    // registered already: used before, here or on another device, so its past is looked for
+    // ponytail: from genesis (~4 MB per million commitments); ask for a birthday once the chain has many
+    const restoring =
+      !saved?.length && opts.birthday === undefined && !!(await storage.registration(hexToBytes(address)));
+    const view = await registeredViewKey(storage, opts.seed, signer, hexToBytes(address), publicKey);
+    const loaded = saved?.length ? openState(opts.seed, saved) : null;
+    // never started over in place: the first save would overwrite what it held, operations in flight included
+    if (saved?.length && !loaded) {
+      fail(
+        'invalid',
+        'the saved state does not open with this seed (another seed, a newer version, or damaged): clear it to start over, which finds what it held again',
+      );
+    }
+    if (loaded && loaded.address.toLowerCase() !== address.toLowerCase())
+      fail('invalid', `the saved state is ${loaded.address}'s: keep one per address`);
+    const state: WalletState = loaded ?? emptyWalletState(address);
+    const ctx: Ctx = {
+      network: opts.network,
+      seed: opts.seed,
+      address,
+      walletClient: opts.walletClient,
+      storage,
+      view,
+      chains,
+      state,
+      save: () => opts.persist.save(sealState(opts.seed, state)),
+      lastFullRefreshMs: 0,
+    };
+    if (!loaded) await start(ctx, restoring ? 0n : opts.birthday);
+    const wallet = new Wallet(ctx);
+    wallet.#release = release;
+    // a saved state names its tokens by id, and its coins stand by the chains' roots: read both now, so balances, coins
+    // and history work before the first sync
+    const [tokens] = await Promise.all([Promise.all(chains.map((c) => c.chain.tokens())), wallet.#readRoots()]);
+    wallet.#tokens = tokens.flat();
+    return wallet;
+  }
+
+  /** Runs `f` after everything queued before it: one state, changed by one task at a time. */
+  #exclusive<T>(f: () => Promise<T>): Promise<T> {
+    this.#busy++;
+    const run = this.#queue
+      .then(() => {
+        this.#closed.signal.throwIfAborted();
+        return f();
+      })
+      .finally(() => this.#busy--);
+    this.#queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /** Each chain's latest proved root, which tells what is spendable, and whether the protocol is in an emergency. A
+   * chain that does not answer keeps what was read before, and its error is returned. */
+  async #readRoots(): Promise<unknown[]> {
+    const errors: unknown[] = [];
+    await Promise.all(
+      this.#ctx.chains.map(async (c) => {
+        try {
+          const [status, bound] = await Promise.all([c.indexer.status(), c.chain.bound()]);
+          // in an emergency the ledger accepts no root above its bound
+          const latestRoot = status.latestRoot && BigInt(status.latestRoot.size) <= bound ? status.latestRoot : null;
+          const halted = status.mismatch !== null || bound !== NO_BOUND;
+          this.#status.set(c.config.chainId, { ...status, latestRoot, halted });
+        } catch (e) {
+          errors.push(e);
+        }
+      }),
+    );
+    return errors;
+  }
+
+  /** Catches up: new notes, deposits, spends and roots, then advances every operation in flight. A chain or server that
+   * fails holds back only what needs it, and the first error is thrown once the rest is done. Settles before the burn
+   * addresses are topped up, which can take a phone tens of seconds. */
+  sync(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.#exclusive(async () => {
+        await this.#catchUp().then(resolve, reject);
+        // still this task's: a deposit queued meanwhile finds the one recorded ahead, rather than writing at handout
+        await topUpBurns(this.#ctx, this.#closed.signal).catch(() => {}); // tried again after the next sync
+      }).catch(reject); // closed before it ran
+    });
+  }
+
+  async #catchUp(): Promise<void> {
+    const errors = await syncAll(this.#ctx);
+    errors.push(...(await this.#readRoots()));
+    const listed = await Promise.all(
+      this.#ctx.chains.map((c) =>
+        c.chain
+          .tokens()
+          .catch((e: unknown) => (errors.push(e), this.#tokens.filter((t) => t.chainId === c.config.chainId))),
+      ),
+    );
+    this.#tokens = listed.flat();
+    for (const op of this.#ctx.state.ops.filter((o) => o.status === 'pending')) {
+      try {
+        if (op.kind === 'send' || op.kind === 'withdraw' || op.kind === 'consolidate')
+          await advanceSpend(this.#ctx, op);
+        if (op.kind === 'deposit') await settleDeposit(this.#ctx, op);
+        delete op.retrying;
+      } catch (e) {
+        // only what trying again cannot change fails an operation: a server or an RPC that does not answer (any
+        // error that is not the wallet's own), or answers what the chain does not show yet, is tried next sync. It is
+        // kept on the operation, so that one that never gets past it does not look merely slow.
+        if (!(e instanceof WalletError) || e.code === 'unavailable' || e.code === 'indexer-mismatch') {
+          const message =
+            e instanceof WalletError ? e.message : e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+          op.retrying = {
+            message,
+            code: e instanceof WalletError ? e.code : undefined,
+            sinceMs: op.retrying?.sinceMs ?? Date.now(),
+          };
+          continue;
+        }
+        delete op.retrying;
+        op.status = 'failed';
+        op.error = e.message;
+        op.errorCode = e.code;
+        await this.#ctx.save();
+      }
+    }
+    if (errors.length > 0) throw errors[0];
+  }
+
+  /** Syncs on its own: every 15 s while something is under way, every 5 min otherwise. Returns a stop function. */
+  autoSync(onChange?: () => void, onError?: (e: unknown) => void): () => void {
+    let stopped = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const tick = async () => {
+      try {
+        await this.sync();
+        onChange?.();
+      } catch (e) {
+        onError?.(e);
+      }
+      if (stopped || this.#closed.signal.aborted) return;
+      const busy = this.#ctx.state.ops.some((o) => o.status === 'pending' && Date.now() - o.createdMs < WAIT_MS * 4);
+      timer = setTimeout(tick, busy ? 15_000 : 300_000);
+    };
+    void tick();
+    return () => {
+      stopped = true;
+      clearTimeout(timer);
+    };
+  }
+
+  /** The tokens of every chain, as of opening or the last sync. */
+  tokens(): Token[] {
+    return this.#tokens;
+  }
+
+  #token(chainId: bigint, tokenId: number): Token {
+    return (
+      this.#tokens.find((t) => t.chainId === chainId && t.tokenId === tokenId) ??
+      fail('invalid', `unknown token ${tokenId} on ${chainId}`)
+    );
+  }
+
+  balances(): Balance[] {
+    const coins = this.coins();
+    return this.#tokens.map((token) => {
+      const { chainId, tokenId } = token;
+      const b: Balance = { token, spendable: 0n, pending: [], blocked: 0n };
+      // a merge that never landed (another device spent an input first) stops counting after a day; a zero-value
+      // change, there to carry its payment's receipt, never counts. A note is a coin once its commitment is read, so
+      // until then it is incoming, as a payment's change is between its relay and the next sync
+      for (const n of this.#ctx.state.notes.filter(
+        (n) => n.chainId === chainId && n.tokenId === tokenId && n.value > 0n,
+      )) {
+        const stale =
+          n.receipt?.kind === 'merged' && n.atNs !== null && Date.now() - Number(n.atNs / 1_000_000n) > DAY_MS;
+        if (!n.found.some((f) => f.confirmed) && !stale) b.pending.push({ amount: n.value, reason: 'incoming' });
+      }
+      for (const c of coins.filter((c) => c.token === token)) {
+        if (c.state === 'spendable') b.spendable += c.amount;
+        else if (c.state === 'blocked') b.blocked += c.amount;
+        else if (c.state !== 'spending') b.pending.push({ amount: c.amount, reason: c.state });
+      }
+      return b;
+    });
+  }
+
+  /** Every unspent note and deposit on chain, and where each stands, as of opening or the last sync. A note announced
+   * but not on chain yet is not one: `balances()` counts it as incoming. */
+  coins(): CoinInfo[] {
+    const size = (chainId: bigint) => this.#status.get(chainId)?.latestRoot?.size ?? 0;
+    const unproved = (chainId: bigint) => (this.#status.get(chainId)?.halted ? 'roots-halted' : 'awaiting-root');
+    const spending = new Set(this.#ctx.state.ops.flatMap((o) => inputsOf(o).map((c) => `${o.chainId}:${c.index}`)));
+    // spent by a JoinSplit in a block, which waits only to be final: gone, as activity() counts it (a reorg that drops
+    // it brings them back as spending, and the operation relays it again)
+    const landed = new Set(
+      this.#ctx.state.ops.flatMap((o) =>
+        o.kind !== 'deposit' && o.data.step?.stage === 'relayed'
+          ? inputsOf(o).map((c) => `${o.chainId}:${c.index}`)
+          : [],
+      ),
+    );
+    const out: CoinInfo[] = [];
+    // a zero-value change carries its payment's receipt, and is no coin
+    for (const n of this.#ctx.state.notes.filter((n) => n.value > 0n)) {
+      for (const f of n.found.filter((f) => !f.spent)) {
+        const id = `${n.chainId}:${f.index}`;
+        // a 4-byte tag alone matches someone else's now and then: a coin once its commitment is read
+        if (!f.confirmed || landed.has(id)) continue;
+        const state = spending.has(id) ? 'spending' : f.index >= size(n.chainId) ? unproved(n.chainId) : 'spendable';
+        out.push({
+          id,
+          kind: 'note',
+          token: this.#token(n.chainId, n.tokenId),
+          amount: n.value,
+          state,
+          from: n.peer,
+          screenedBy: null,
+        });
+      }
+    }
+    for (const d of this.#ctx.state.deposits) {
+      // a coin once its commitment is read, which names the amount
+      for (const f of d.found.filter((f) => !f.spent && f.amount !== null)) {
+        const id = `${d.chainId}:${f.index}`;
+        if (landed.has(id)) continue;
+        const state =
+          f.asp === 'rejected'
+            ? 'blocked'
+            : spending.has(id)
+              ? 'spending'
+              : f.asp === null
+                ? 'screening'
+                : f.index >= size(d.chainId)
+                  ? unproved(d.chainId)
+                  : 'spendable';
+        const screenedBy = state === 'screening' && f.decidedByMs !== undefined ? new Date(f.decidedByMs) : null;
+        out.push({
+          id,
+          kind: 'deposit',
+          token: this.#token(d.chainId, f.tokenId),
+          amount: f.amount!,
+          state,
+          from: f.sender,
+          screenedBy,
+        });
+      }
+    }
+    return out;
+  }
+
+  /** Everything this wallet received, sent, deposited, sold, withdrew, merged and returned, newest first: the same on every
+   * device of the wallet, read from storage and the chain. This device's operations add only what no other device can
+   * know: a failed attempt, and a payment in a block whose change is not found yet. */
+  activity(): Activity[] {
+    const s = this.#ctx.state;
+    const out: Activity[] = [];
+    const ms = (t: number | bigint | null | undefined) => (t === null || t === undefined ? null : new Date(Number(t)));
+    /** One on chain at `coin`, dated by its block, or else `fallbackMs`. */
+    const at = (
+      kind: Activity['kind'],
+      chainId: bigint,
+      f: { index: number; atMs?: number },
+      fallbackMs: number | null,
+    ) => ({
+      id: `${kind}:${chainId}:${f.index}`,
+      kind,
+      coin: `${chainId}:${f.index}`,
+      at: ms(f.atMs ?? fallbackMs),
+      burnAddress: null as Address | null,
+      status: 'done' as const,
+    });
+    // payments whose change shows them, by the change's salt
+    const shown = new Set<Hex>();
+    for (const n of s.notes) {
+      // on chain, and its commitment read: a 4-byte tag alone matches someone else's now and then
+      const f = n.found.find((f) => f.confirmed);
+      if (!f) continue;
+      const token = this.#token(n.chainId, n.tokenId);
+      const stored = n.atNs === null ? null : Number(n.atNs / 1_000_000n);
+      const r = n.receipt;
+      if (n.source === 'received') {
+        out.push({
+          ...at('received', n.chainId, f, stored),
+          token,
+          amount: n.value,
+          fee: null,
+          counterparty: n.peer,
+          via: null,
+          txHash: null,
+        });
+      } else if (r?.kind === 'merged') {
+        out.push({
+          ...at('merged', n.chainId, f, stored),
+          token,
+          amount: n.value,
+          fee: r.fee,
+          counterparty: null,
+          via: null,
+          txHash: null,
+        });
+      } else if (r) {
+        shown.add(n.salt);
+        const kind = r.kind === 'withdrawn' || r.kind === 'unwrapped' ? 'withdrawn' : 'sent';
+        const code = r.kind === 'sent-to-code' ? this.#paidCode(n.chainId, r.counterparty) : null;
+        const counterparty = r.kind === 'sent-to-code' ? null : r.counterparty;
+        out.push({
+          ...at(kind, n.chainId, f, stored),
+          token,
+          amount: r.amount,
+          fee: r.fee,
+          counterparty,
+          via: code ? { code } : null,
+          txHash: null,
+        });
+      }
+    }
+    for (const d of s.deposits) {
+      // registered on this device, or on another, which says so in storage
+      const registered =
+        d.depositAddress ??
+        s.receipts.flatMap((r) =>
+          r.kind === 'deposit-address' && r.chainId === d.chainId && r.burnAddress === d.address.toLowerCase()
+            ? [r.depositAddress]
+            : [],
+        )[0];
+      // on chain once found; shown once its commitment is read, which names the amount
+      for (const f of d.found.filter((f) => f.amount !== null)) {
+        const forwarded = registered && f.sender?.toLowerCase() === registered.toLowerCase();
+        // into a burn address a payer chose: theirs to this wallet, as a payment is
+        const kind = d.managed ? 'sale' : d.payer ? 'received' : 'deposited';
+        const via = forwarded ? { depositAddress: registered } : null;
+        const entry = {
+          ...at(kind, d.chainId, f, d.createdMs),
+          token: this.#token(d.chainId, f.tokenId),
+          amount: f.amount!,
+          burnAddress: d.address,
+        };
+        out.push({ ...entry, fee: null, counterparty: f.sender, via, txHash: null });
+      }
+    }
+    // a deposit that paid someone (`deposit({ to })`), once its transfer is found
+    for (const x of s.sent) {
+      for (const f of x.found.filter((f) => f.amount !== null)) {
+        out.push({
+          ...at('sent', x.chainId, f, x.createdMs),
+          token: this.#token(x.chainId, f.tokenId),
+          amount: f.amount!,
+          fee: null,
+          counterparty: x.to,
+          via: null,
+          txHash: null,
+        });
+      }
+    }
+    for (const r of s.receipts) {
+      if (r.kind !== 'returned') continue;
+      const entry = {
+        ...at('returned', r.chainId, { index: r.index }, r.atMs),
+        token: this.#token(r.chainId, r.tokenId),
+        amount: r.amount,
+      };
+      out.push({ ...entry, fee: null, counterparty: r.recipient, via: null, txHash: r.txHash });
+    }
+    for (const op of s.ops) {
+      const failed = op.status === 'failed';
+      const base = {
+        id: op.id,
+        token: this.#token(op.chainId, op.tokenId),
+        amount: op.amount,
+        at: new Date(op.createdMs),
+        coin: null,
+        burnAddress: null,
+        status: failed ? ('failed' as const) : ('done' as const),
+      };
+      if (op.kind === 'deposit') {
+        // until its transfer is found, as above
+        const found = s.sent.some(
+          (x) =>
+            x.chainId === op.chainId &&
+            x.address === op.data.burnAddress.toLowerCase() &&
+            x.found.some((f) => f.amount !== null),
+        );
+        if (!op.data.to || !op.data.txHash || op.status === 'pending' || found) continue;
+        out.push({ ...base, kind: 'sent', fee: null, counterparty: op.data.to, via: null, txHash: op.data.txHash });
+        continue;
+      }
+      // under way (in operations()), or shown by its change
+      if (op.kind === 'consolidate' || (!failed && !landed(op)) || shown.has(op.data.changes?.[0] ?? '0x')) continue;
+      const to = op.data.to;
+      out.push({
+        ...base,
+        kind: op.kind === 'send' ? 'sent' : 'withdrawn',
+        fee: op.data.paid,
+        counterparty:
+          to.kind === 'public' ? to.address : to.kind === 'address' ? bytesToHex(to.recipient.address) : null,
+        via: to.kind === 'code' ? { code: to.code } : null,
+        txHash: op.data.txHashes?.at(-1) ?? null,
+      });
+    }
+    return out.sort((a, b) => (b.at?.getTime() ?? 0) - (a.at?.getTime() ?? 0));
+  }
+
+  /** The text of a receive code this wallet paid, by its burn address, from storage's record of paying it. */
+  #paidCode(chainId: bigint, burnAddress: Hex): string | null {
+    for (const c of this.#ctx.state.storage?.outgoing.lanes ?? []) {
+      if ('code' in c.via && c.via.code.chainId === chainId && bytesToHex(c.via.code.burnAddress) === burnAddress)
+        return encodeCode(c.via.code);
+    }
+    return null;
+  }
+
+  /** `a`'s transaction and its block's time, read now: for an app to show on asking, as a sync does not read them. A
+   * coin's is the ledger's log of it, in the block the indexer names. Null while the chain does not show it. */
+  async transaction(a: Activity): Promise<{ hash: Hex; at: Date | null } | null> {
+    const c =
+      this.#ctx.chains.find((c) => c.config.chainId === a.token.chainId) ??
+      fail('invalid', `unknown chain ${a.token.chainId}`);
+    let hash = a.txHash;
+    let block: bigint | null = null;
+    if (!hash && a.coin) {
+      const tx = await commitmentTx(c.chain, c.indexer, Number(a.coin.split(':')[1]));
+      if (!tx) return null;
+      ({ hash, block } = tx);
+    }
+    if (!hash) return null;
+    block ??= (await c.chain.client.getTransactionReceipt({ hash }).catch(() => null))?.blockNumber ?? null;
+    if (block === null) return { hash, at: null }; // not mined, or not yet seen by this RPC
+    const { timestamp } = await c.chain.client.getBlock({ blockNumber: block });
+    return { hash, at: new Date(Number(timestamp) * 1000) };
+  }
+
+  /** Every deposit found, with the id `rageExit` takes. */
+  deposits(): DepositInfo[] {
+    return this.#ctx.state.deposits.flatMap((d) =>
+      d.found.map((f) => ({
+        id: `${d.chainId}:${f.index}`,
+        address: d.address,
+        managed: d.managed === true,
+        token: this.#token(d.chainId, f.tokenId),
+        amount: f.amount,
+        sender: f.sender,
+        state: f.spent ? 'spent' : f.asp === null ? 'screening' : f.asp,
+      })),
+    );
+  }
+
+  /** The payments to the burn addresses this wallet's points of sale handed out. Spent ones are, normally, in a
+   * merged note. */
+  payments(): DepositInfo[] {
+    return this.deposits().filter((d) => d.managed);
+  }
+
+  /** The key of a new point of sale (`PointOfSale.connect`): the lane where it records the payment addresses it makes
+   * for this wallet, which this wallet, every other device of it and a restore read, and `payments()` shows what reaches
+   * them. The point of sale can spend none of it. One key for one point of sale: two would hand out the same
+   * addresses. */
+  posKey(): Promise<Hex> {
+    return this.#exclusive(async () => {
+      const ctx = this.#ctx;
+      const tokens = await tokenIds(ctx);
+      let n = 0;
+      // the number is the last plan's: after `Occupied`, another device took the first one
+      const planned = (s: SyncState) => planPosLane(ctx.view, s, ctx.chains[0].config.chainId, (n = nextPosLane(s)));
+      takeRefresh(ctx, await commit(ctx.storage, ctx.view, storageState(ctx), planned), tokens);
+      await ctx.save();
+      return bytesToHex(posKey(ctx.view.seed, n));
+    });
+  }
+
+  /** Refunds deposit `id` to its sender without the ASP, the attester or a proved root: for a deposit the ASP
+   * rejected, or when those services stop. The account's wallet sends the transactions and pays their gas. */
+  rageExit(id: string): Promise<Hex[]> {
+    return this.#exclusive(async () => {
+      const [chain, index] = id.split(':');
+      const record =
+        this.#ctx.state.deposits.find((d) => `${d.chainId}` === chain && d.found.some((f) => `${f.index}` === index)) ??
+        fail('invalid', `no deposit ${id}`);
+      // an operation in flight may still land with it, and would then be taken for paid when this refund spends it
+      const op = this.#ctx.state.ops.find(
+        (o) => `${o.chainId}` === chain && inputsOf(o).some((c) => `${c.index}` === index),
+      );
+      if (op) fail('invalid', `deposit ${id} is an input of operation ${op.id}, which is in flight`);
+      return rageExit(this.#ctx, record, Number(index));
+    });
+  }
+
+  operations(): Operation[] {
+    return this.#ctx.state.ops.map((op) => this.#operation(op));
+  }
+
+  #operation(op: OperationRecord): Operation {
+    return {
+      id: op.id,
+      kind: op.kind,
+      chainId: op.chainId,
+      get status() {
+        return op.status;
+      },
+      get error() {
+        return op.error;
+      },
+      get errorCode() {
+        return op.errorCode;
+      },
+      get retrying() {
+        const r = op.retrying;
+        return r ? { message: r.message, code: r.code, since: new Date(r.sinceMs) } : null;
+      },
+      get txHashes() {
+        return op.kind === 'deposit' ? (op.data.txHash ? [op.data.txHash] : []) : (op.data.txHashes ?? []);
+      },
+      get stage() {
+        return op.kind === 'deposit' ? null : (op.data.step?.stage ?? null);
+      },
+      to: op.kind === 'deposit' ? (op.data.to ?? null) : null,
+      wait: async () => {
+        for (;;) {
+          if (op.status === 'done') return;
+          if (op.status === 'failed') throw new WalletError(op.errorCode ?? 'invalid', op.error ?? 'failed');
+          await this.sync();
+          if (op.status === 'pending') await new Promise((r) => setTimeout(r, 15_000));
+        }
+      },
+    };
+  }
+
+  #newOp<K extends OperationKind>(
+    kind: K,
+    token: Token,
+    amount: bigint,
+    data: (OperationRecord & { kind: K })['data'],
+  ): OperationRecord & { kind: K } {
+    // `data` is the kind's own, which TypeScript cannot follow through a generic
+    const op = {
+      id: bytesToHex(crypto.getRandomValues(new Uint8Array(8))),
+      kind,
+      chainId: token.chainId,
+      tokenId: token.tokenId,
+      amount,
+      createdMs: Date.now(),
+      status: 'pending',
+      data,
+    } as OperationRecord & { kind: K };
+    this.#ctx.state.ops.push(op);
+    return op;
+  }
+
+  /** A fresh burn address of `token`, recorded in storage before anything is sent to it: the one recorded ahead, or
+   * else a new one (about 2^16 hashes and a storage write), which `recording` is told of first. */
+  async #burnAddress(token: Token, depositAddress: Address | null = null, recording: () => void = () => {}) {
+    const ctx = this.#ctx;
+    // taken once recorded: a search that close() stops changes nothing
+    let record = unusedBurn(ctx, token.chainId, token.tokenId);
+    if (!record) {
+      recording();
+      record = await recordBurn(ctx, token.chainId, token.tokenId, await tokenIds(ctx), this.#closed.signal);
+    }
+    const next = chainState(ctx, token.chainId).burnNext;
+    // recording may have read another device's later ones
+    next[token.tokenId] = Math.max(next[token.tokenId] ?? 0, record.burnIndex + 1);
+    record.createdMs = Date.now();
+    record.depositAddress = depositAddress;
+    await ctx.save();
+    return record;
+  }
+
+  /** Moves `amount` of the account's public tokens into the private balance: wraps the underlying asset into a fresh
+   * burn address (approving it first if needed). The deposit is spendable once the ASP has screened it. More than the
+   * account holds fails at once (`insufficient-funds`), before anything is asked of the wallet.
+   *
+   * With `to`, an address that registered, it pays them instead, privately: into a fresh burn address of theirs,
+   * under the public key they registered, told to them in storage first as a note is (`planDeposit`). They
+   * receive it as a deposit of their own, screened like any; the burn address names no one. It shows in `activity()`
+   * as sent. Finding the address takes about 2^16 hashes (`burn-address`).
+   *
+   * With `wrapped`, it pays from the account's zERC20 itself, as a withdrawal pays out, rather than its underlying
+   * asset: a plain transfer into the burn address, with no wrap and no approval.
+   *
+   * Returns once the wrap is sent: the operation is done once it is mined, which `wait()` or the next sync finds.
+   * `onStep` hears what it waits on meanwhile, for an app to show. */
+  deposit(opts: {
+    token: Token;
+    amount: bigint;
+    to?: Address;
+    wrapped?: boolean;
+    onStep?: (step: DepositStep) => void;
+  }): Promise<Operation> {
+    const step = opts.onStep ?? (() => {});
+    if (this.#busy > 0) step('queued');
+    return this.#exclusive(async () => {
+      const { token, amount } = opts;
+      if (amount <= 0n) fail('invalid', 'the amount must be positive');
+      const wc = this.#ctx.walletClient;
+      const account = wc.account!;
+      const client = chainCtx(this.#ctx, token.chainId).chain.client;
+      const { wrapped } = opts;
+      const native = !wrapped && token.underlying.toLowerCase() === NATIVE.toLowerCase();
+      // a wrap of more would revert, and an ERC20's only after the approval it asks for first
+      const held = native
+        ? await client.getBalance({ address: account.address })
+        : await client.readContract({
+            address: wrapped ? token.address : token.underlying,
+            abi: erc20Abi,
+            functionName: 'balanceOf',
+            args: [account.address],
+          });
+      if (held < amount) {
+        const of = wrapped ? token.symbol : `${token.symbol}'s underlying asset`;
+        fail(
+          'insufficient-funds',
+          `the account holds ${formatUnits(held, token.decimals)} of ${of}, less than ${formatUnits(amount, token.decimals)}`,
+        );
+      }
+      const address = opts.to
+        ? await this.#burnFor(token, amount, opts.to, () => step('burn-address'))
+        : (await this.#burnAddress(token, null, () => step('burn-address'))).address;
+      const op = this.#newOp(
+        'deposit',
+        token,
+        amount,
+        opts.to ? { burnAddress: address, to: opts.to } : { burnAddress: address },
+      );
+      await this.#ctx.save();
+      try {
+        if ((await wc.getChainId()) !== Number(token.chainId))
+          await guard(wc.switchChain({ id: Number(token.chainId) }));
+        if (!native && !wrapped) {
+          const allowance = await client.readContract({
+            address: token.underlying,
+            abi: erc20Abi,
+            functionName: 'allowance',
+            args: [account.address, token.address],
+          });
+          if (allowance < amount) {
+            step('approve');
+            const tx = await guard(
+              wc.writeContract({
+                account,
+                chain: null,
+                address: token.underlying,
+                abi: erc20Abi,
+                functionName: 'approve',
+                args: [token.address, amount],
+              }),
+            );
+            // mined before the wrap, still holding every other call: an approval sets the allowance, so another
+            // deposit's in between would overwrite this one's
+            await client.waitForTransactionReceipt({ hash: tx });
+            await walletSees(wc, tx);
+          }
+        }
+        step('wrap');
+        const tx = await guard(
+          wrapped
+            ? wc.writeContract({
+                account,
+                chain: null,
+                address: token.address,
+                abi: erc20Abi,
+                functionName: 'transfer',
+                args: [address, amount],
+              })
+            : wc.writeContract({
+                account,
+                chain: null,
+                address: token.address,
+                abi: tokenAbi,
+                functionName: 'wrap',
+                args: [amount, address],
+                value: native ? amount : 0n,
+              }),
+        );
+        op.data.txHash = tx;
+        // its receipt is for the next sync (settleDeposit): waiting for it here would hold every other call a block
+      } catch (e) {
+        // declined, or nothing sent for another reason: over. A sent one is settled by its receipt on a later sync.
+        if (!op.data.txHash) {
+          op.status = 'failed';
+          op.error = (e as Error).message;
+          if (e instanceof WalletError) op.errorCode = e.code;
+        }
+        await this.#ctx.save();
+        throw e;
+      }
+      await this.#ctx.save();
+      return this.#operation(op);
+    });
+  }
+
+  /** A fresh burn address of `to`'s, for a deposit of `amount` that pays them, told to them in storage: a note that only
+   * shows on chain cannot be found. */
+  async #burnFor(token: Token, amount: bigint, to: Address, searching: () => void): Promise<Hex> {
+    const ctx = this.#ctx;
+    const recipient = await lookupRecipient(ctx.storage, hexToBytes(to));
+    if (!recipient)
+      fail(
+        'recipient-not-registered',
+        `${to} cannot be paid privately: withdraw to it publicly, or ask for a receive code`,
+      );
+    searching();
+    const burn = await burnAddressFor(token.chainId, bytesToHex(recipient!.publicKey), this.#closed.signal);
+    // with the address, so that every device of this wallet finds the transfer it then sends
+    const value = hexToBytes(numberToHex(amount, { size: 32 }));
+    const deposit = {
+      chainId: token.chainId,
+      tokenId: token.tokenId,
+      value,
+      burnSalt: hexToBytes(burn.salt),
+      burnAddress: hexToBytes(burn.address),
+    };
+    const result = await commit(ctx.storage, ctx.view, storageState(ctx), (s) =>
+      planDeposit(ctx.view, s, recipient!, deposit),
+    );
+    takeRefresh(ctx, result, await tokenIds(ctx));
+    return burn.address;
+  }
+
+  /** An address that takes `token`'s underlying asset from anywhere (an exchange withdrawal, another wallet) and
+   * deposits it privately, less `fee` (in the underlying's base units) to the deposit relayer each time: what arrives
+   * must exceed it. Watched for 7 days by the deposit relayer; refunds go back to this account. `onStep` hears what it
+   * waits on (`queued`, `burn-address`). */
+  depositAddress(
+    token: Token,
+    opts: { onStep?: (step: DepositStep) => void } = {},
+  ): Promise<{ address: Address; fee: bigint }> {
+    const step = opts.onStep ?? (() => {});
+    if (this.#busy > 0) step('queued');
+    return this.#exclusive(async () => {
+      const c = chainCtx(this.#ctx, token.chainId);
+      const record = await this.#burnAddress(token, null, () => step('burn-address'));
+      const { depositAddress, fee } = await registerDeposit(c.chain, token.address, record.address, this.address);
+      record.depositAddress = depositAddress;
+      // for the wallet's other devices, to show what comes through it: written by the next sync
+      const burnAddress = record.address.toLowerCase() as Hex;
+      this.#ctx.state.receipts.push({
+        kind: 'deposit-address',
+        chainId: token.chainId,
+        tokenId: token.tokenId,
+        burnAddress,
+        depositAddress,
+        atMs: Date.now(),
+        unwritten: true,
+      });
+      await this.#ctx.save();
+      return { address: depositAddress, fee };
+    });
+  }
+
+  /** A receive code for `token`, to hand to one payer: it pays any amount, as often as it likes, publicly by a transfer
+   * of the token to the code's burn address (a deposit, like a point of sale's payment addresses), or privately by
+   * `send`. It is one of this wallet's burn addresses, recorded in storage ahead of need, so handing it out writes
+   * nothing; it names neither this address nor its public key. Anyone who gets the code can pay it, and see what its
+   * other payers paid privately: give each payer its own. It is checksummed text (bech32m, `zerc201…`). */
+  receiveCode(token: Token): Promise<string> {
+    return this.#exclusive(async () => {
+      const ctx = this.#ctx;
+      const { burnIndex, address } = await this.#burnAddress(token);
+      return encodeCode({
+        chainId: token.chainId,
+        tokenId: token.tokenId,
+        burnAddress: hexToBytes(address),
+        publicKey: hexToBytes(
+          spendKey(ctx, { chainId: token.chainId, tokenId: token.tokenId, index: burnIndex }).publicKey,
+        ),
+        key: codeKey(ctx.view.seed, token.chainId, token.tokenId, burnIndex),
+      });
+    });
+  }
+
+  /** What a send or withdrawal of `amount` would cost now, or a consolidation of what the wallet holds. A send or
+   * withdrawal no single JoinSplit can pay now throws as it would (`needs-consolidation`, `funds-settling`,
+   * `insufficient-funds`). A consolidation of chosen `coins` throws `funds-settling` until all of them are spendable. */
+  async fees(opts: {
+    kind: 'send' | 'withdraw' | 'consolidate';
+    token: Token;
+    amount?: bigint;
+    coins?: string[];
+  }): Promise<FeeQuote> {
+    const { token } = opts;
+    const amount = opts.amount ?? 0n;
+    const c = chainCtx(this.#ctx, token.chainId);
+    const relayer =
+      (await relayerFees(c.config)).fees.get(token.tokenId)?.fee ??
+      fail('unavailable', 'the relayer does not relay this token');
+    const size = this.#status.get(token.chainId)?.latestRoot?.size ?? 0;
+    const all = coins(this.#ctx, token.chainId, token.tokenId, size);
+    if (opts.kind === 'consolidate') {
+      const chosen = opts.coins && this.#chosen(token, opts.coins);
+      if (chosen && chosenSettling(this.#ctx, token.chainId, chosen, all)) {
+        fail(
+          'funds-settling',
+          'a chosen note or deposit is still settling: quote again once coins() shows it spendable',
+        );
+      }
+      const steps = BigInt(roundsToMerge(mergePool(all, chosen)));
+      // a merge pays the relayer publicly, so the protocol takes its cut of that, grossed up as a payment's is
+      const cut = steps === 0n ? 0n : (await grossed(this.#ctx, token.chainId, token.tokenId, relayer)) - relayer;
+      return { relayer: relayer * steps, protocol: cut * steps, fee: (relayer + cut) * steps, steps: Number(steps) };
+    }
+    // as the payment's plan reckons it, so that `fee` is a `maxFee` it passes
+    const { protocol } = await withdrawalOf(
+      this.#ctx,
+      token.chainId,
+      token.tokenId,
+      opts.kind === 'withdraw',
+      amount,
+      relayer,
+    );
+    const onTheWay =
+      this.#ctx.state.ops.some((o) => o.status === 'pending') ||
+      settling(this.#ctx, token.chainId, token.tokenId, size);
+    payWith(all, amount + relayer + protocol, relayer, onTheWay);
+    return { relayer, protocol, fee: relayer + protocol, steps: 1 };
+  }
+
+  /** The most a send or withdrawal of `token` can pay: what is spendable, less the fees `fees` quotes on top of it, and
+   * the merges first when one JoinSplit cannot spend it all, which `fees` then asks for (`needs-consolidation`). */
+  async maxAmount(opts: { kind: 'send' | 'withdraw'; token: Token }): Promise<bigint> {
+    const { token } = opts;
+    const c = chainCtx(this.#ctx, token.chainId);
+    const relayer =
+      (await relayerFees(c.config)).fees.get(token.tokenId)?.fee ??
+      fail('unavailable', 'the relayer does not relay this token');
+    const size = this.#status.get(token.chainId)?.latestRoot?.size ?? 0;
+    return maxPayment(
+      this.#ctx,
+      token.chainId,
+      token.tokenId,
+      opts.kind === 'withdraw',
+      coins(this.#ctx, token.chainId, token.tokenId, size),
+      relayer,
+    );
+  }
+
+  /** What the next merge of a consolidation of everything would spend, as `coins()` ids: up to 100, the largest first,
+   * for `consolidate({ coins })`. Null when nothing spendable is worth merging. */
+  async nextMerge(token: Token): Promise<string[] | null> {
+    const c = chainCtx(this.#ctx, token.chainId);
+    const fee =
+      (await relayerFees(c.config)).fees.get(token.tokenId)?.fee ??
+      fail('unavailable', 'the relayer does not relay this token');
+    const size = this.#status.get(token.chainId)?.latestRoot?.size ?? 0;
+    const merge = mergeRound(coins(this.#ctx, token.chainId, token.tokenId, size), fee);
+    return merge && merge.map((m) => `${token.chainId}:${m.index}`);
+  }
+
+  /** Pays `amount` privately: to an address that has registered (any wallet that ever opened), or to a receive code
+   * (`receiveCode`). An address that never registered fails with `recipient-not-registered`. One JoinSplit from
+   * what is spendable now, or it fails here: `needs-consolidation`, `funds-settling` or `insufficient-funds`.
+   * `amount` is what the recipient gets, and `maxFee` caps what it pays on top, `fees({ kind: 'send' }).fee`: the
+   * relayer names its fee, so a quote the user saw is the cap. */
+  send(opts: { to: string; token: Token; amount: bigint; maxFee: bigint }): Promise<Operation> {
+    return this.#exclusive(async () => {
+      const { token, amount } = opts;
+      if (amount <= 0n) fail('invalid', 'the amount must be positive');
+      let to: Destination;
+      if (isAddress(opts.to)) {
+        const recipient = await lookupRecipient(this.#ctx.storage, hexToBytes(opts.to));
+        if (!recipient)
+          fail(
+            'recipient-not-registered',
+            `${opts.to} cannot be paid privately: withdraw to it publicly, or ask for a receive code`,
+          );
+        to = { kind: 'address', recipient: recipient! };
+      } else {
+        const code = decodeCode(opts.to);
+        if (!code) return fail('invalid', 'not an address or a receive code');
+        if (code.chainId !== token.chainId || code.tokenId !== token.tokenId)
+          fail('invalid', 'the receive code is for another token');
+        to = { kind: 'code', code: opts.to.trim() };
+      }
+      return this.#newPayment('send', token, amount, { to, maxFee: opts.maxFee, step: null, paid: 0n });
+    });
+  }
+
+  /** Merges `token`'s scattered notes and deposits into one note, without paying anyone: fewer, larger notes make
+   * later payments a single JoinSplit. One Nova merge spends up to 100 of them and pays the relayer's fee once; the
+   * network's merge prover proves it, seeing its witness in its enclave while it does: the openings of what it spends, but
+   * no private key, so it can prove only the merge this wallet signed. More
+   * take another merge, once a proved root is over the first one's note; `fees({ kind: 'consolidate' })` tells how
+   * many. A lone deposit becomes a note. A payment that fails with `needs-consolidation` goes through after this.
+   *
+   * With `coins` (ids from `coins()`, notes and deposits), only those are merged, into one note, and nothing else is
+   * touched; one still settling is waited for. `maxFee` caps the fees of every merge together,
+   * `fees({ kind: 'consolidate' }).fee`. */
+  consolidate(opts: { token: Token; coins?: string[]; maxFee: bigint }): Promise<Operation> {
+    return this.#exclusive(async () => {
+      if (!this.#ctx.network.mergeProver) fail('invalid', 'this network has no merge prover');
+      const to: Destination = { kind: 'self' };
+      const data: SpendData = { to, maxFee: opts.maxFee, step: null, paid: 0n };
+      if (opts.coins) data.chosen = this.#chosen(opts.token, opts.coins);
+      const op = this.#newOp('consolidate', opts.token, 0n, data);
+      await this.#ctx.save();
+      return this.#operation(op);
+    });
+  }
+
+  /** The commitment indices of coins `ids` of `token`, none blocked or already being spent. */
+  #chosen(token: Token, ids: string[]): number[] {
+    if (ids.length === 0) fail('invalid', 'choose at least one note or deposit');
+    const coins = this.coins();
+    return ids.map((id) => {
+      const c = coins.find((x) => x.id === id) ?? fail('invalid', `no unspent note or deposit ${id}`);
+      if (c.token.chainId !== token.chainId || c.token.tokenId !== token.tokenId)
+        fail('invalid', `${id} is not ${token.symbol}`);
+      if (c.state === 'blocked' || c.state === 'spending') fail('invalid', `${id} is ${c.state}`);
+      return Number(id.split(':')[1]);
+    });
+  }
+
+  /** Withdraws `amount` publicly to `to`, as zERC20 or with `unwrap` the underlying asset itself, so `to` needs no gas
+   * to unwrap. One JoinSplit, as `send`, and as there `to` gets all of `amount` and `maxFee` caps what is paid on top
+   * (`fees({ kind: 'withdraw' }).fee`). */
+  withdraw(opts: { to: Address; token: Token; amount: bigint; maxFee: bigint; unwrap?: boolean }): Promise<Operation> {
+    return this.#exclusive(async () => {
+      if (!isAddress(opts.to)) fail('invalid', `${String(opts.to)} is not an address`);
+      if (opts.amount <= 0n) fail('invalid', 'the amount must be positive');
+      const to: Destination = { kind: 'public', address: opts.to, unwrap: opts.unwrap };
+      return this.#newPayment('withdraw', opts.token, opts.amount, { to, maxFee: opts.maxFee, step: null, paid: 0n });
+    });
+  }
+
+  /** A send or withdrawal with its one JoinSplit planned now: it fails here rather than later, and its inputs are
+   * taken at once, so a payment right after it cannot count on them. */
+  async #newPayment(kind: 'send' | 'withdraw', token: Token, amount: bigint, data: SpendData): Promise<Operation> {
+    const op = this.#newOp(kind, token, amount, data);
+    try {
+      data.step = (await planStep(this.#ctx, op)) as Step; // a payment's plan is a step, or a throw
+    } catch (e) {
+      this.#ctx.state.ops.splice(this.#ctx.state.ops.indexOf(op), 1);
+      throw e;
+    }
+    await this.#ctx.save();
+    return this.#operation(op);
+  }
+}
+
+/** Holds `address`'s wallet until the returned function is called: two tabs on one wallet would each overwrite the
+ * other's state and spend the same notes. Nothing where there are no Web Locks. */
+export async function lockWallet(address: Address): Promise<() => void> {
+  const locks = (globalThis as { navigator?: Navigator }).navigator?.locks;
+  if (!locks) return () => {};
+  let release = () => {};
+  const held = new Promise<void>((r) => (release = r));
+  const got = await new Promise<boolean>((resolve) => {
+    void locks.request(`zerc20-wallet:${address.toLowerCase()}`, { ifAvailable: true }, (lock) => {
+      resolve(lock !== null);
+      return lock ? held : undefined;
+    });
+  });
+  if (!got) fail('wallet-in-use', 'this wallet is open in another tab or window: close it there first');
+  return release;
+}
+
+/** A deposit `deposit()` did not see through (a reload, a lost connection): settled by its transaction's receipt, or
+ * failed if it never sent one. Runs only between tasks, so no `deposit()` is still on its way to sending it. */
+async function settleDeposit(ctx: Ctx, op: DepositOperation): Promise<void> {
+  const hash = op.data.txHash;
+  if (hash) {
+    const receipt = await chainCtx(ctx, op.chainId)
+      .chain.client.getTransactionReceipt({ hash })
+      .catch(() => null);
+    if (!receipt) return; // not mined yet
+    op.status = receipt.status === 'success' ? 'done' : 'failed';
+    if (op.status === 'failed') op.error = 'the deposit transaction reverted';
+  } else {
+    op.status = 'failed';
+    op.error = 'the deposit was never sent';
+  }
+  await ctx.save();
+}
+
+/** A fresh state: a new wallet looks only at what comes next, a restored one from its birthday on. */
+async function start(ctx: Ctx, birthday: bigint | Date | undefined): Promise<void> {
+  for (const c of ctx.chains) {
+    const s = chainState(ctx, c.config.chainId);
+    const status = await c.indexer.status();
+    let floor = { commitments: status.commitmentsFinal, nullifiers: status.nullifiersFinal };
+    if (birthday !== undefined) floor = await floorAt(c, birthday);
+    s.samples.push({ atMs: 0, ...floor });
+  }
+  await ctx.save();
+}
+
+/** The counts before `birthday` (a block, or a date found by bisecting block times), from the indexer's marks. */
+async function floorAt(
+  c: { chain: Chain; indexer: Indexer },
+  birthday: bigint | Date,
+): Promise<{ commitments: number; nullifiers: number }> {
+  let block = typeof birthday === 'bigint' ? birthday : 0n;
+  if (birthday instanceof Date) {
+    let [lo, hi] = [0n, await c.chain.client.getBlockNumber()];
+    const target = BigInt(Math.floor(birthday.getTime() / 1000));
+    while (lo < hi) {
+      const mid = (lo + hi + 1n) / 2n;
+      if ((await c.chain.client.getBlock({ blockNumber: mid })).timestamp <= target) lo = mid;
+      else hi = mid - 1n;
+    }
+    block = lo;
+  }
+  // the last page of commitments that began before the birthday
+  let floor = { commitments: 0, nullifiers: 0 };
+  for (let p = 0; ; p++) {
+    const marks = await c.indexer.page('marks', p);
+    for (let k = 0; k < marks.length / 16; k++) {
+      const view = new DataView(marks.buffer, marks.byteOffset + k * 16, 16);
+      if (view.getBigUint64(0, false) > block) return floor;
+      floor = { commitments: (p * PAGE + k) * PAGE, nullifiers: Number(view.getBigUint64(8, false)) };
+    }
+    if (marks.length < PAGE * 16) return floor;
+  }
+}