@zerc20/wallet-sdk 0.2.0 → 0.4.0

package/src/wallet.ts

@@ -10,6 +10,7 @@ import {
   encodeCode,
   lookupRecipient,
   nextPosLane,
+  notifyKey,
   planDeposit,
   planPosLane,
   posKey,
@@ -19,16 +20,29 @@ import {
   type Account,
   type Address,
   type Hex,
+  type LocalAccount,
   type WalletClient,
   bytesToHex,
   formatUnits,
+  getAddress,
   hexToBytes,
   isAddress,
   numberToHex,
   zeroAddress,
 } from 'viem';
+import { toAccount } from 'viem/accounts';
 import { Chain, MAX_REFERRAL_BPS, NATIVE, type Referrer, type Token, erc20Abi, tokenAbi } from './chain.js';
-import { type Ctx, type SpendKey, chainCtx, chainState, spendKey, walletSees } from './context.js';
+import {
+  type ChainCtx,
+  type Ctx,
+  type SpendKey,
+  chainCtx,
+  chainState,
+  owner,
+  switched,
+  walletOn,
+  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';
@@ -62,10 +76,14 @@ import {
   emptyWalletState,
   openState,
   sealState,
+  stateKey,
+  unspent,
 } from './state.js';
 import {
   WAIT_MS,
   commitmentTx,
+  keyAll,
+  nextBurn,
   recordBurn,
   storageState,
   syncAll,
@@ -74,17 +92,25 @@ import {
   topUpBurns,
   unusedBurn,
 } from './sync.js';
+import { decodeViewKey, encodeViewKey } from './viewKey.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;
+  /** The account's key, held by the app as a viem local account (a private key's, or `accountKey`'s): the wallet sends
+   * its transactions through each chain's RPC. Give this or `walletClient`. */
+  account?: LocalAccount;
+  /** The user's wallet (MetaMask, WalletConnect, ...) as a viem client with its account, which the wallet switches to
+   * each chain it sends on. */
+  walletClient?: WalletClient;
+  /** The 32-byte root of every key (see `seedFromSignature`), held while the wallet is open. Or a function that gives
+   * it, a passkey's say, to hold the seed only while it is needed: asked as the wallet opens, and again to pay,
+   * withdraw, consolidate or exit, or for a receive code past those derived ahead, each time before the call waits on
+   * anything (a browser shows a passkey prompt only in the click that asked). The seed goes at the end of a sync that
+   * nothing waits behind, once nothing in flight signs again. */
+  seed: Uint8Array | (() => Promise<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
@@ -94,6 +120,11 @@ export interface OpenOptions {
   referrer?: Referrer;
 }
 
+export interface WatchOptions extends Pick<OpenOptions, 'network' | 'persist' | 'birthday'> {
+  /** The account's view key, from its wallet's `viewKey()`. */
+  viewKey: string;
+}
+
 /** 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. */
@@ -108,7 +139,7 @@ export type DepositStep =
 
 /** Why an amount is not spendable yet. */
 export type PendingReason =
-  /** Announced by the payer, and not yet read on chain. */
+  /** A note this device's payment, withdrawal or merge under way is making, not yet read on chain. */
   | 'incoming'
   /** Waiting for a proved root that covers it (minutes). */
   | 'awaiting-root'
@@ -157,7 +188,7 @@ export interface Activity {
   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()`. */
+   * an operation under way is in `operations()`, and the note it is making `incoming` in `balances()`. */
   status: 'done' | 'failed';
 }
 
@@ -240,10 +271,13 @@ export class Wallet {
   #busy = 0;
   #release = () => {};
   #referrer: Referrer | undefined;
+  readonly #unlock: (() => Promise<Uint8Array>) | undefined;
+  #readOnly = false;
   #closed = new AbortController();
 
-  private constructor(ctx: Ctx) {
+  private constructor(ctx: Ctx, unlock?: () => Promise<Uint8Array>) {
     this.#ctx = ctx;
+    this.#unlock = unlock;
   }
 
   /** Lets this wallet open again: in another tab, or here for another account. This object is done with: what is
@@ -258,11 +292,21 @@ export class Wallet {
     return this.#ctx.address;
   }
 
+  /** The account's view key, for `watch` to follow it with on another device: whoever holds it sees what this wallet
+   * shows, except the private payments to receive codes, and can spend none of it. Checksummed text (bech32m,
+   * `zerc20view1…`). */
+  viewKey(): string {
+    return encodeViewKey(this.#ctx.view, owner(this.#ctx)!);
+  }
+
+  /** Whether this wallet only watches its account (`watch`): it shows what the account holds and spends nothing. */
+  get readOnly(): boolean {
+    return this.#readOnly;
+  }
+
   /** 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');
     // the factory refuses these, which the relayer would report as its own failure
     const r = opts.referrer;
     if (r) {
@@ -271,72 +315,179 @@ export class Wallet {
       if (!Number.isInteger(r.bps) || r.bps < 0 || r.bps > MAX_REFERRAL_BPS)
         fail('invalid', `a referrer takes 0 to ${MAX_REFERRAL_BPS} bps, not ${r.bps}`);
     }
-    const account = opts.walletClient.account ?? fail('invalid', 'the wallet client has no account');
+    if (!opts.account === !opts.walletClient) fail('invalid', 'give an account or a wallet client, one of the two');
+    const account = opts.account ?? opts.walletClient!.account ?? fail('invalid', 'the wallet client has no account');
+    // asked once the options are checked, and before anything is waited on: a browser shows a passkey prompt only in
+    // the click that opened
+    const seed = typeof opts.seed === 'function' ? await opts.seed() : opts.seed;
+    if (seed.length !== 32) fail('invalid', 'the seed is 32 bytes');
+    await initCore();
     const release = await lockWallet(account.address);
     try {
-      return await Wallet.#open(opts, account, release);
+      return await Wallet.#open(opts, seed, account, release);
     } catch (e) {
       release();
       throw e;
     }
   }
 
-  static async #open(opts: OpenOptions, account: Account, release: () => void): Promise<Wallet> {
+  static async #open(opts: OpenOptions, seed: Uint8Array, 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 chains = chainsOf(opts.network);
     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 })));
+      hexToBytes(
+        await guard(
+          account.type === 'local'
+            ? account.signMessage({ message })
+            : 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 publicKey = hexToBytes((core.spendKey(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;
+    const view = await registeredViewKey(storage, seed, signer, hexToBytes(address), publicKey);
+    const wallet = await Wallet.#begin(
+      {
+        network: opts.network,
+        seed,
+        owners: new Map(),
+        address,
+        account,
+        walletClient: opts.walletClient ?? null,
+        storage,
+        view,
+        chains,
+      },
+      { persist: opts.persist, saved, key: stateKey(seed), from: restoring ? 0n : opts.birthday },
+      typeof opts.seed === 'function' ? opts.seed : undefined,
+    );
+    wallet.#release = release;
+    wallet.#referrer = opts.referrer;
+    return wallet;
+  }
+
+  /** Opens an account to follow by its view key (`viewKey()`): its balances, coins and history as its own wallet shows
+   * them, less the private payments to its receive codes, whose keys only the seed derives. It spends and writes
+   * nothing: a call that would fails with `read-only`. The key must be the account's current one on this network. */
+  static async watch(opts: WatchOptions): Promise<Wallet> {
+    checkNetwork(opts.network);
+    await initCore();
+    const { view, owner } = decodeViewKey(opts.viewKey) ?? fail('invalid', 'not a view key');
+    const address = getAddress(bytesToHex(view.address));
+    const release = await lockWallet(address, 'view');
+    try {
+      const storage = await CanisterClient.connect(opts.network.storage.host, opts.network.storage.canisterId);
+      // what the account signed: a nullifying key that is not the account's would show spent coins as unspent
+      const r = await lookupRecipient(storage, view.address);
+      if (!r || bytesToHex(r.publicKey) !== owner.publicKey || bytesToHex(r.notifyKey) !== bytesToHex(notifyKey(view)))
+        fail('invalid', `not ${address}'s view key on ${opts.network.name}, or one it has replaced`);
+      const wallet = await Wallet.#begin(
+        {
+          network: opts.network,
+          seed: null,
+          owners: new Map([['', owner]]),
+          address,
+          // signs nothing: every call that would send is refused first
+          account: toAccount(address),
+          walletClient: null,
+          storage,
+          view,
+          chains: chainsOf(opts.network),
+        },
+        // registered, so its past is looked for
+        {
+          persist: opts.persist,
+          saved: await opts.persist.load(),
+          key: stateKey(view.seed),
+          from: opts.birthday ?? 0n,
+        },
+      );
+      wallet.#release = release;
+      wallet.#readOnly = true;
+      return wallet;
+    } catch (e) {
+      release();
+      throw e;
+    }
+  }
+
+  /** The wallet over `base`, its state opened from what `persist` saved, with `key`, or started `from` a block or date. */
+  static async #begin(
+    base: Omit<Ctx, 'state' | 'save' | 'lastFullRefreshMs'>,
+    {
+      persist,
+      saved,
+      key,
+      from,
+    }: { persist: OpenOptions['persist']; saved: Uint8Array | null | undefined; key: Uint8Array; from?: bigint | Date },
+    unlock?: () => Promise<Uint8Array>,
+  ): Promise<Wallet> {
+    const loaded = saved?.length ? openState(key, 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',
+        'the saved state does not open with this key (another seed or view key, a newer version, or damaged): clear it to start over, which finds what it held again',
       );
     }
-    if (loaded && loaded.address.toLowerCase() !== address.toLowerCase())
+    if (loaded && loaded.address.toLowerCase() !== base.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;
-    wallet.#referrer = opts.referrer;
+    const state: WalletState = loaded ?? emptyWalletState(base.address);
+    const ctx: Ctx = { ...base, state, save: () => persist.save(sealState(key, state)), lastFullRefreshMs: 0 };
+    if (!loaded) await start(ctx, from);
+    const wallet = new Wallet(ctx, unlock);
     // 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()]);
+    const [tokens] = await Promise.all([Promise.all(ctx.chains.map((c) => c.chain.tokens())), wallet.#readRoots()]);
     wallet.#tokens = tokens.flat();
+    keyAll(ctx, wallet.#tokens);
     return wallet;
   }
 
+  /** Holds `seed`, asked of `#unlock`, once it is checked to be this wallet's. */
+  #hold(seed: Uint8Array): void {
+    if ((core.spendKey(seed) as SpendKey).publicKey !== owner(this.#ctx)!.publicKey)
+      fail('invalid', "the seed given is another wallet's");
+    this.#ctx.seed = seed;
+    keyAll(this.#ctx, this.#tokens);
+  }
+
+  /** Within a task: the seed held, asked of `#unlock` if need be. */
+  async #seed(): Promise<void> {
+    if (!this.#ctx.seed) this.#hold(await this.#unlock!());
+  }
+
+  /** At the end of a sync: lets the seed go when it was opened with a function for it, nothing waits behind the sync,
+   * and no payment, withdrawal or consolidation is in flight, as each may sign again (a JoinSplit that reverts is
+   * proved again, and every merge round is signed). */
+  #dropSeed(): void {
+    if (!this.#unlock || this.#busy > 1) return;
+    if (this.#ctx.state.ops.some((o) => o.status === 'pending' && o.kind !== 'deposit')) return;
+    this.#ctx.seed = null;
+  }
+
+  /** `#exclusive` for a call that `needs` the seed: held first, asked of `#unlock` if need be before the call waits on
+   * anything else (a browser shows a passkey prompt only in the click that asked), and queued in the step that took it,
+   * so that a sync ending meanwhile does not let it go. */
+  async #seeded<T>(f: () => Promise<T>, needs = true): Promise<T> {
+    this.#writable();
+    if (needs && !this.#ctx.seed) this.#hold(await this.#unlock!());
+    return this.#exclusive(f);
+  }
+
+  /** Refuses a call that spends or writes to storage, in a wallet that watches. */
+  #writable(): void {
+    if (this.#readOnly) fail('read-only', 'this wallet watches its account by its view key: open it with its seed');
+  }
+
   /** 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++;
@@ -372,13 +523,15 @@ export class Wallet {
 
   /** 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. */
+   * addresses are topped up, which can take a phone some 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
+        // still this task's: a deposit queued meanwhile finds the one recorded ahead, rather than writing at handout;
+        // tried again after the next sync. A wallet that watches records none, as it writes nothing.
+        if (!this.#readOnly) await topUpBurns(this.#ctx, this.#closed.signal).catch(() => {});
+        this.#dropSeed();
       }).catch(reject); // closed before it ran
     });
   }
@@ -424,7 +577,7 @@ export class Wallet {
     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. */
+  /** Syncs on its own: every 3 s while something is under way, every 10 s otherwise. Returns a stop function. */
   autoSync(onChange?: () => void, onError?: (e: unknown) => void): () => void {
     let stopped = false;
     let timer: ReturnType<typeof setTimeout> | undefined;
@@ -437,7 +590,7 @@ export class Wallet {
       }
       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);
+      timer = setTimeout(tick, busy ? 3_000 : 10_000);
     };
     void tick();
     return () => {
@@ -460,18 +613,22 @@ export class Wallet {
 
   balances(): Balance[] {
     const coins = this.coins();
+    // storage says which notes to look for, not that they come: a payer writes its notes there before its JoinSplit
+    // leaves, and one that never lands leaves them behind. So a note counts once it is a coin (its commitment read);
+    // before that, only a note this device's own operation under way is making counts, as incoming. A zero-value
+    // change, there to carry its payment's receipt, never counts
+    const making = new Set(
+      this.#ctx.state.ops.flatMap((o) =>
+        o.status === 'pending' && o.kind !== 'deposit' ? (o.data.changes ?? []) : [],
+      ),
+    );
     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,
+        (n) => n.chainId === chainId && n.tokenId === tokenId && n.value > 0n && making.has(n.salt),
       )) {
-        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' });
+        if (!n.found.some((f) => f.confirmed)) 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;
@@ -483,13 +640,14 @@ export class Wallet {
   }
 
   /** 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. */
+   * but not read on chain yet is not one: `balances()` counts it as incoming if this device's operation is making it. */
   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)
+    // spent by a JoinSplit in a block, which waits only to be final: gone, as activity() counts it. Sync sees it by its
+    // nullifier (`unspent`); this device's own is gone already from its relay on (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'
@@ -500,7 +658,7 @@ export class Wallet {
     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)) {
+      for (const f of n.found.filter(unspent)) {
         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;
@@ -518,7 +676,7 @@ export class Wallet {
     }
     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)) {
+      for (const f of d.found.filter((f) => unspent(f) && f.amount !== null)) {
         const id = `${d.chainId}:${f.index}`;
         if (landed.has(id)) continue;
         const state =
@@ -754,6 +912,7 @@ export class Wallet {
    * addresses. */
   posKey(): Promise<Hex> {
     return this.#exclusive(async () => {
+      this.#writable();
       const ctx = this.#ctx;
       const tokens = await tokenIds(ctx);
       let n = 0;
@@ -768,7 +927,7 @@ export class Wallet {
   /** 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 () => {
+    return this.#seeded(async () => {
       const [chain, index] = id.split(':');
       const record =
         this.#ctx.state.deposits.find((d) => `${d.chainId}` === chain && d.found.some((f) => `${f.index}` === index)) ??
@@ -874,22 +1033,27 @@ export class Wallet {
    * 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.
    *
+   * With `from`, another wallet of the user's (a browser wallet) pays instead of the account: its balance is checked,
+   * it approves and wraps, and an exit refunds it there. The account pays nothing and signs nothing.
+   *
    * 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: {
+  async deposit(opts: {
     token: Token;
     amount: bigint;
     to?: Address;
     wrapped?: boolean;
+    from?: WalletClient;
     onStep?: (step: DepositStep) => void;
   }): Promise<Operation> {
+    this.#writable();
+    if (opts.amount <= 0n) fail('invalid', 'the amount must be positive');
+    const payer = opts.from ? (opts.from.account ?? fail('invalid', 'the wallet client has no account')) : null;
     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 account = payer ?? this.#ctx.account;
       const client = chainCtx(this.#ctx, token.chainId).chain.client;
       const { wrapped } = opts;
       const native = !wrapped && token.underlying.toLowerCase() === NATIVE.toLowerCase();
@@ -906,7 +1070,7 @@ export class Wallet {
         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)}`,
+          `${payer ? 'the wallet' : 'the account'} holds ${formatUnits(held, token.decimals)} of ${of}, less than ${formatUnits(amount, token.decimals)}`,
         );
       }
       const address = opts.to
@@ -920,8 +1084,7 @@ export class Wallet {
       );
       await this.#ctx.save();
       try {
-        if ((await wc.getChainId()) !== Number(token.chainId))
-          await guard(wc.switchChain({ id: Number(token.chainId) }));
+        const wc = opts.from ? await switched(opts.from, token.chainId) : await walletOn(this.#ctx, token.chainId);
         if (!native && !wrapped) {
           const allowance = await client.readContract({
             address: token.underlying,
@@ -1024,6 +1187,7 @@ export class Wallet {
     const step = opts.onStep ?? (() => {});
     if (this.#busy > 0) step('queued');
     return this.#exclusive(async () => {
+      this.#writable();
       const c = chainCtx(this.#ctx, token.chainId);
       const record = await this.#burnAddress(token, null, () => step('burn-address'));
       const { depositAddress, fee } = await registerDeposit(
@@ -1056,19 +1220,21 @@ export class Wallet {
    * 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 ctx = this.#ctx;
+    const code = (index: number) => ({ chainId: token.chainId, tokenId: token.tokenId, index });
+    // the seed is asked for only past the codes derived ahead
+    const derived = !!owner(ctx, code(nextBurn(ctx, token.chainId, token.tokenId)));
+    return this.#seeded(async () => {
       const { burnIndex, address } = await this.#burnAddress(token);
+      if (!owner(ctx, code(burnIndex))) await this.#seed(); // calls queued before took the next ones
       return encodeCode({
         chainId: token.chainId,
         tokenId: token.tokenId,
         burnAddress: hexToBytes(address),
-        publicKey: hexToBytes(
-          spendKey(ctx, { chainId: token.chainId, tokenId: token.tokenId, index: burnIndex }).publicKey,
-        ),
+        publicKey: hexToBytes(owner(ctx, code(burnIndex))!.publicKey),
         key: codeKey(ctx.view.seed, token.chainId, token.tokenId, burnIndex),
       });
-    });
+    }, !derived);
   }
 
   /** What a send or withdrawal of `amount` would cost now, or a consolidation of what the wallet holds. A send or
@@ -1153,10 +1319,11 @@ export class Wallet {
    * 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');
+  async send(opts: { to: string; token: Token; amount: bigint; maxFee: bigint }): Promise<Operation> {
+    const { token, amount } = opts;
+    if (amount <= 0n) fail('invalid', 'the amount must be positive');
+    // the JoinSplit is proved by a later sync, which holds the seed until the payment is done
+    return this.#seeded(async () => {
       let to: Destination;
       if (isAddress(opts.to)) {
         const recipient = await lookupRecipient(this.#ctx.storage, hexToBytes(opts.to));
@@ -1188,7 +1355,7 @@ export class Wallet {
    * 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 () => {
+    return this.#seeded(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 };
@@ -1215,10 +1382,16 @@ export class Wallet {
   /** 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');
+  async withdraw(opts: {
+    to: Address;
+    token: Token;
+    amount: bigint;
+    maxFee: bigint;
+    unwrap?: boolean;
+  }): Promise<Operation> {
+    if (!isAddress(opts.to)) fail('invalid', `${String(opts.to)} is not an address`);
+    if (opts.amount <= 0n) fail('invalid', 'the amount must be positive');
+    return this.#seeded(async () => {
       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 });
     });
@@ -1239,15 +1412,25 @@ export class Wallet {
   }
 }
 
+/** Each chain of `network`, with its servers. */
+const chainsOf = (network: Network): ChainCtx[] =>
+  network.chains.map((config) => ({
+    config,
+    chain: new Chain(config),
+    indexer: new Indexer(config.indexer),
+    asp: new Asp(config.asp),
+  }));
+
 /** 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> {
+ * other's state and spend the same notes. A wallet that watches it (`view`) is held apart, as its state is its own.
+ * Nothing where there are no Web Locks. */
+export async function lockWallet(address: Address, kind: 'wallet' | 'view' = 'wallet'): 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) => {
+    void locks.request(`zerc20-${kind}:${address.toLowerCase()}`, { ifAvailable: true }, (lock) => {
       resolve(lock !== null);
       return lock ? held : undefined;
     });