@zerc20/wallet-sdk 0.3.0 → 0.5.0

package/src/wallet.ts

@@ -10,6 +10,7 @@ import {
   encodeCode,
   lookupRecipient,
   nextPosLane,
+  notifyKey,
   planDeposit,
   planPosLane,
   posKey,
@@ -23,25 +24,41 @@ import {
   type WalletClient,
   bytesToHex,
   formatUnits,
+  getAddress,
   hexToBytes,
   isAddress,
+  isAddressEqual,
   numberToHex,
   zeroAddress,
 } from 'viem';
+import { toAccount } from 'viem/accounts';
+import { idAccount } from './accountId.js';
 import { Chain, MAX_REFERRAL_BPS, NATIVE, type Referrer, type Token, erc20Abi, tokenAbi } from './chain.js';
-import { type Ctx, type SpendKey, chainCtx, chainState, owner, switched, walletOn, walletSees } from './context.js';
+import {
+  type ChainCtx,
+  type Ctx,
+  type SpendKey,
+  chainCtx,
+  chainState,
+  owner,
+  refundSigner,
+  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';
 import { Asp, Indexer, type IndexerStatus, PAGE } from './servers.js';
-import { rageExit } from './rageExit.js';
-import { registerDeposit, relayerFees } from './services.js';
+import { type Route, flushDepositAddress, rageExit, refundDepositAddress } from './rageExit.js';
+import { registerDeposit, relayerFees, rewatchDeposit } from './services.js';
 import {
   type Destination,
   type MergeStep,
   type SpendData,
   type Step,
   advanceSpend,
+  bpsOf,
   chosenSettling,
   coins,
   grossed,
@@ -57,7 +74,9 @@ import {
   withdrawalOf,
 } from './spend.js';
 import {
+  type DepositAddressReceipt,
   type DepositOperation,
+  type DepositRecord,
   type OperationRecord,
   type WalletState,
   emptyWalletState,
@@ -79,6 +98,7 @@ import {
   topUpBurns,
   unusedBurn,
 } from './sync.js';
+import { decodeViewKey, encodeViewKey } from './viewKey.js';
 
 /** The ledger's bound outside an emergency. */
 const NO_BOUND = 2n ** 64n - 1n;
@@ -106,6 +126,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. */
@@ -151,7 +176,8 @@ export interface Activity {
    * 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. */
+   * returned deposit went back to. A payment's other side, `sent`'s or that of a `received` with no `burnAddress`, is a
+   * zERC20 account, which an app shows by its zERC20 ID (`accountId`); any other is a public address. */
   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). */
@@ -185,8 +211,13 @@ export interface CoinInfo {
   state: 'spendable' | Exclude<PendingReason, 'incoming'> | 'spending' | 'blocked';
   /** A note's payer (as claimed, unverified) or a deposit's sender, where known. */
   from: Address | null;
+  /** The deposit address of this wallet's that a deposit came through (its `from`), as `Activity.via` names it: its
+   * `rageExit` goes where `to` says. */
+  via: { depositAddress: Address } | null;
   /** For a deposit in `screening`, when the ASP should decide it: an estimate, null until there is one. */
   screenedBy: Date | null;
+  /** When it landed: its block's time, null until read. */
+  at: Date | null;
 }
 
 export interface DepositInfo {
@@ -202,12 +233,25 @@ export interface DepositInfo {
   state: 'screening' | 'approved' | 'rejected' | 'spent';
 }
 
+export interface DepositAddressInfo {
+  address: Address;
+  token: Token;
+  /** What the relayer takes out of each payment through it. Null where its receipt in storage does not say what it was
+   * registered with: `flushDepositAddress` needs that, so only the relayer flushes such an address. */
+  fee: bigint | null;
+  /** When it was handed out, or watched again (`rewatchDepositAddress`), from which the deposit relayer watches it for
+   * 7 days: when storage took its receipt. */
+  at: Date;
+}
+
 /** 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;
+  /** `protocol` as a rate of that withdrawal, in basis points (35 is 0.35%): lower in tiers as the withdrawal grows. */
+  protocolBps: number;
   /** `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
@@ -215,6 +259,16 @@ export interface FeeQuote {
   steps: number;
 }
 
+/** The most a send or withdrawal can pay now, and what its fees keep back of what is spendable. */
+export interface MaxAmount {
+  /** What the recipient would get: 0 where the fees take everything. */
+  amount: bigint;
+  /** The fees: the payment's, and those of the merges it needs first. Where they take everything, what they would be. */
+  fee: bigint;
+  /** Merges first, when one JoinSplit cannot spend all of it: each pays the relayer again. */
+  merges: number;
+}
+
 export type OperationKind = OperationRecord['kind'];
 export type OperationStatus = OperationRecord['status'];
 export type CoinState = CoinInfo['state'];
@@ -237,7 +291,8 @@ export interface Operation {
   /** 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. */
+  /** Whom a deposit pays, when `deposit({ to })` named an address; null otherwise. One to a receive code shows its code
+   * as `via` in `activity()`. */
   readonly to: Address | null;
   /** Syncs until the operation is done; throws if it fails. */
   wait(): Promise<void>;
@@ -253,6 +308,7 @@ export class Wallet {
   #release = () => {};
   #referrer: Referrer | undefined;
   readonly #unlock: (() => Promise<Uint8Array>) | undefined;
+  #readOnly = false;
   #closed = new AbortController();
 
   private constructor(ctx: Ctx, unlock?: () => Promise<Uint8Array>) {
@@ -272,6 +328,18 @@ 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> {
     checkNetwork(opts.network);
@@ -301,12 +369,7 @@ export class 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'))
@@ -327,39 +390,101 @@ export class Wallet {
     const restoring =
       !saved?.length && opts.birthday === undefined && !!(await storage.registration(hexToBytes(address)));
     const view = await registeredViewKey(storage, seed, signer, hexToBytes(address), publicKey);
-    const key = stateKey(seed);
+    const wallet = await Wallet.#begin(
+      {
+        network: opts.network,
+        seed,
+        owners: new Map(),
+        refundSigners: 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]]),
+          refundSigners: new Map(),
+          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,
-      owners: new Map(),
-      address,
-      account,
-      walletClient: opts.walletClient ?? null,
-      storage,
-      view,
-      chains,
-      state,
-      save: () => opts.persist.save(sealState(key, state)),
-      lastFullRefreshMs: 0,
-    };
-    if (!loaded) await start(ctx, restoring ? 0n : opts.birthday);
-    const wallet = new Wallet(ctx, typeof opts.seed === 'function' ? opts.seed : undefined);
-    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;
@@ -391,10 +516,16 @@ export class Wallet {
    * 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++;
@@ -435,8 +566,9 @@ export class Wallet {
     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
     });
@@ -445,14 +577,8 @@ export class Wallet {
   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();
+    // as syncAll read them: a chain it could not read keeps those read before
+    this.#tokens = this.#ctx.chains.flatMap((c) => c.chain.known);
     for (const op of this.#ctx.state.ops.filter((o) => o.status === 'pending')) {
       try {
         if (op.kind === 'send' || op.kind === 'withdraw' || op.kind === 'consolidate')
@@ -576,7 +702,9 @@ export class Wallet {
           amount: n.value,
           state,
           from: n.peer,
+          via: null,
           screenedBy: null,
+          at: f.atMs === undefined ? null : new Date(f.atMs),
         });
       }
     }
@@ -603,7 +731,9 @@ export class Wallet {
           amount: f.amount!,
           state,
           from: f.sender,
+          via: this.#via(d, f.sender),
           screenedBy,
+          at: f.atMs === undefined ? null : new Date(f.atMs),
         });
       }
     }
@@ -677,27 +807,17 @@ export class Wallet {
       }
     }
     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 });
+        out.push({ ...entry, fee: null, counterparty: f.sender, via: this.#via(d, f.sender), txHash: null });
       }
     }
     // a deposit that paid someone (`deposit({ to })`), once its transfer is found
@@ -742,8 +862,16 @@ export class Wallet {
             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 });
+        const { to, code, txHash } = op.data;
+        if ((!to && !code) || !txHash || op.status === 'pending' || found) continue;
+        out.push({
+          ...base,
+          kind: 'sent',
+          fee: null,
+          counterparty: to ?? null,
+          via: code ? { code } : null,
+          txHash,
+        });
         continue;
       }
       // under way (in operations()), or shown by its change
@@ -762,6 +890,21 @@ export class Wallet {
     return out.sort((a, b) => (b.at?.getTime() ?? 0) - (a.at?.getTime() ?? 0));
   }
 
+  /** The deposit address `d` registered (here, or on another device, which says so in storage) if `sender` is it: what
+   * a deposit from `sender` came through. */
+  #via(d: DepositRecord, sender: Hex | null): { depositAddress: Address } | null {
+    const registered =
+      d.depositAddress ??
+      this.#ctx.state.receipts.flatMap((r) =>
+        r.kind === 'deposit-address' && r.chainId === d.chainId && r.burnAddress === d.address.toLowerCase()
+          ? [r.depositAddress]
+          : [],
+      )[0];
+    return registered && sender && isAddressEqual(sender, registered)
+      ? { depositAddress: getAddress(registered) }
+      : null;
+  }
+
   /** 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 ?? []) {
@@ -806,6 +949,31 @@ export class Wallet {
     );
   }
 
+  /** The deposit addresses this wallet handed out (`depositAddress`), on any of its devices, newest first: for an app to
+   * show each while what is sent to it is on its way, which `activity()` shows once deposited. Each is dated, and its
+   * fee told, by its receipt in storage, alike on every device. */
+  depositAddresses(): DepositAddressInfo[] {
+    return this.#ctx.state.receipts
+      .flatMap((r) => {
+        if (r.kind !== 'deposit-address') return [];
+        const token = this.#token(r.chainId, r.tokenId);
+        return [{ address: getAddress(r.depositAddress), token, fee: r.args?.fee ?? null, at: new Date(r.atMs) }];
+      })
+      .sort((a, b) => b.at.getTime() - a.at.getTime());
+  }
+
+  /** What `address` is to this wallet on `chainId`: one of its own burn addresses (`deposit`), one it paid someone
+   * into (`payment`, `deposit({ to })` to an address), or neither (null), as is a receive code's that it paid. On chain
+   * either is a plain transfer to an address that names no one: this tells an app listing the account's public
+   * transfers which they were. Both are recorded before the transfer is sent. */
+  burnAddressOf(chainId: bigint, address: Address): { kind: 'deposit' } | { kind: 'payment'; to: Address } | null {
+    const s = this.#ctx.state;
+    const a = address.toLowerCase();
+    if (s.deposits.some((d) => d.chainId === chainId && d.address.toLowerCase() === a)) return { kind: 'deposit' };
+    const paid = s.sent.find((x) => x.chainId === chainId && x.address.toLowerCase() === a);
+    return paid ? { kind: 'payment', to: paid.to } : null;
+  }
+
   /** The payments to the burn addresses this wallet's points of sale handed out. Spent ones are, normally, in a
    * merged note. */
   payments(): DepositInfo[] {
@@ -818,6 +986,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;
@@ -830,8 +999,12 @@ 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[]> {
+   * rejected, or when those services stop. The account's wallet sends the transactions and pays their gas, or with
+   * `from` another wallet of the user's does, as `deposit({ from })` pays. One through a deposit address of this
+   * wallet's (`CoinInfo.via`) goes to `to`, by default `from`'s account, else this account; any other goes back to its
+   * sender, and one through a point of sale's deposit address to the refund address its payer named. */
+  rageExit(id: string, opts: { from?: WalletClient; to?: Address } = {}): Promise<Hex[]> {
+    const route = this.#route(opts);
     return this.#seeded(async () => {
       const [chain, index] = id.split(':');
       const record =
@@ -842,10 +1015,39 @@ export class Wallet {
         (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));
+      return rageExit(this.#ctx, record, Number(index), route);
+    });
+  }
+
+  /** Sends what deposit address `address` of this wallet's holds of `asset` (NATIVE for the chain's own currency) to
+   * `to`: another token sent to it, which it cannot wrap. What it can wrap is wrapped instead, as a payment to it is.
+   * It deploys on its first flush, and refunds nothing before. `from` and `to` as for `rageExit`. */
+  refundDepositAddress(
+    address: Address,
+    asset: Address,
+    opts: { from?: WalletClient; to?: Address } = {},
+  ): Promise<Hex> {
+    if (!isAddress(asset, { strict: false }) || asset.toLowerCase() === zeroAddress)
+      fail('invalid', `${asset} is not an asset's address`);
+    const route = this.#route(opts);
+    return this.#seeded(async () => {
+      const record =
+        this.#ctx.state.deposits.find((d) => !d.managed && this.#via(d, address)) ??
+        fail('invalid', `${address} is not a deposit address of this wallet's`);
+      return refundDepositAddress(this.#ctx, record, getAddress(address), getAddress(asset), route);
     });
   }
 
+  /** Who sends a refund and where it goes (`rageExit`), checked before the seed is asked for. */
+  #route(opts: { from?: WalletClient; to?: Address }): Route {
+    const from = opts.from ?? null;
+    if (from && !from.account) fail('invalid', 'the wallet client has no account');
+    const to = opts.to ?? from?.account?.address ?? this.address;
+    if (!isAddress(to, { strict: false }) || to.toLowerCase() === zeroAddress)
+      fail('invalid', `${to} is not an address to refund to`);
+    return { from, to: getAddress(to) };
+  }
+
   operations(): Operation[] {
     return this.#ctx.state.ops.map((op) => this.#operation(op));
   }
@@ -915,7 +1117,9 @@ export class Wallet {
     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);
+      record = await recordBurn(ctx, token.chainId, token.tokenId, await tokenIds(ctx), {
+        signal: this.#closed.signal,
+      });
     }
     const next = chainState(ctx, token.chainId).burnNext;
     // recording may have read another device's later ones
@@ -930,10 +1134,12 @@ export class Wallet {
    * 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 `to`, an account that registered, by its address or its zERC20 ID, 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`). Or `to` is a receive
+   * code (`receiveCode`), paid into its burn address, which its owner already watches: storage is told nothing, so
+   * only this device's `activity()` shows it as sent.
    *
    * 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.
@@ -946,13 +1152,15 @@ export class Wallet {
   async deposit(opts: {
     token: Token;
     amount: bigint;
-    to?: Address;
+    to?: string;
     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 to = opts.to === undefined ? null : recipientOf(opts.to, opts.token);
     const step = opts.onStep ?? (() => {});
     if (this.#busy > 0) step('queued');
     return this.#exclusive(async () => {
@@ -977,14 +1185,21 @@ export class Wallet {
           `${payer ? 'the wallet' : '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 address =
+        to?.kind === 'code'
+          ? to.burnAddress
+          : to
+            ? await this.#burnFor(token, amount, to.address, () => 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 },
+        to?.kind === 'code'
+          ? { burnAddress: address, code: to.code }
+          : to
+            ? { burnAddress: address, to: to.address }
+            : { burnAddress: address },
       );
       await this.#ctx.save();
       try {
@@ -1057,11 +1272,7 @@ export class Wallet {
   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`,
-      );
+    if (!recipient) fail('recipient-not-registered', `${to} never opened a zERC20 wallet: 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
@@ -1083,25 +1294,35 @@ export class Wallet {
   /** 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. A wallet opened with a `referrer` also pays it its `bps` of the rest. Watched for 7 days by the
-   * deposit relayer; refunds go back to this account. `onStep` hears what it waits on (`queued`, `burn-address`). */
+   * deposit relayer. It names no account: its refunds go where a key of its own signs for (`rageExit`'s `to`,
+   * `refundDepositAddress`). `depositAddresses()` lists it. `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 ?? (() => {});
+    const ctx = this.#ctx;
+    const code = (index: number) => ({ chainId: token.chainId, tokenId: token.tokenId, index });
+    // the seed is asked for only past the refund signers derived ahead
+    const derived = !!refundSigner(ctx, code(nextBurn(ctx, token.chainId, token.tokenId)));
     if (this.#busy > 0) step('queued');
-    return this.#exclusive(async () => {
-      const c = chainCtx(this.#ctx, token.chainId);
+    return this.#seeded(async () => {
+      const c = chainCtx(ctx, token.chainId);
       const record = await this.#burnAddress(token, null, () => step('burn-address'));
-      const { depositAddress, fee } = await registerDeposit(
+      if (!refundSigner(ctx, code(record.burnIndex))) await this.#seed(); // calls queued before took the next ones
+      const signer = refundSigner(ctx, code(record.burnIndex))!;
+      const referrer = this.#referrer ?? { address: zeroAddress, bps: 0 };
+      const { depositAddress, feeRecipient, fee } = await registerDeposit(
         c.chain,
         token.address,
         record.address,
-        this.address,
-        this.#referrer,
+        { signer },
+        referrer,
       );
       record.depositAddress = depositAddress;
-      // for the wallet's other devices, to show what comes through it: written by the next sync
+      // for the wallet's other devices, to show what comes through it and what it takes, and for a flush without the
+      // relayer: written by the next sync
       const burnAddress = record.address.toLowerCase() as Hex;
       this.#ctx.state.receipts.push({
         kind: 'deposit-address',
@@ -1109,12 +1330,48 @@ export class Wallet {
         tokenId: token.tokenId,
         burnAddress,
         depositAddress,
+        args: { fee, feeRecipient, refundSigner: signer, referrer: referrer.address, referralBps: referrer.bps },
         atMs: Date.now(),
         unwritten: true,
       });
       await this.#ctx.save();
       return { address: depositAddress, fee };
-    });
+    }, !derived);
+  }
+
+  /** Has the deposit relayer watch deposit address `address` of this wallet's for another 7 days, at the fee it was
+   * handed out with: what reached it after its 7 days is deposited then, and so is what reaches it within the next.
+   * `depositAddresses()` dates it from now, on every device. */
+  rewatchDepositAddress(address: Address): Promise<{ address: Address; fee: bigint }> {
+    return this.#seeded(async () => {
+      const receipt = this.#depositReceipt(address);
+      const fee = await rewatchDeposit(chainCtx(this.#ctx, receipt.chainId).chain, getAddress(address));
+      // for every device of the wallet, written by the next sync: storage dates it anew
+      receipt.atMs = Date.now();
+      receipt.unwritten = true;
+      await this.#ctx.save();
+      return { address: getAddress(address), fee };
+    }, false);
+  }
+
+  /** Deposits what deposit address `address` of this wallet's holds, as the deposit relayer would, for when it does
+   * not: down, or no longer watching the address. Its receipt says all the address was registered with, wherever its
+   * `fee` is known (`depositAddresses()`), so no relayer is asked. `from`, another wallet of the user's, sends the
+   * flush and pays its gas, and shows on chain as the depositor: never the account's own, which the address does not
+   * name. What it holds must exceed the fee (`insufficient-funds`). It shows in `activity()` as any deposit through
+   * the address. */
+  flushDepositAddress(address: Address, opts: { from: WalletClient }): Promise<Hex> {
+    if (!opts.from.account) fail('invalid', 'the wallet client has no account');
+    return this.#seeded(() => flushDepositAddress(this.#ctx, this.#depositReceipt(address), opts.from), false);
+  }
+
+  /** The receipt of deposit address `address` of this wallet's. */
+  #depositReceipt(address: Address): DepositAddressReceipt {
+    return (
+      this.#ctx.state.receipts.find(
+        (r): r is DepositAddressReceipt => r.kind === 'deposit-address' && isAddressEqual(r.depositAddress, address),
+      ) ?? fail('invalid', `${address} is not a deposit address of this wallet's`)
+    );
   }
 
   /** A receive code for `token`, to hand to one payer: it pays any amount, as often as it likes, publicly by a transfer
@@ -1168,10 +1425,16 @@ export class Wallet {
       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) };
+      return {
+        relayer: relayer * steps,
+        protocol: cut * steps,
+        protocolBps: bpsOf(cut, relayer + cut),
+        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(
+    const { withdrawn, protocol } = await withdrawalOf(
       this.#ctx,
       token.chainId,
       token.tokenId,
@@ -1183,12 +1446,12 @@ export class Wallet {
       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 };
+    return { relayer, protocol, protocolBps: bpsOf(protocol, withdrawn), 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> {
+  async maxAmount(opts: { kind: 'send' | 'withdraw'; token: Token }): Promise<MaxAmount> {
     const { token } = opts;
     const c = chainCtx(this.#ctx, token.chainId);
     const relayer =
@@ -1217,9 +1480,10 @@ export class Wallet {
     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`.
+  /** Pays `amount` privately: to an account that has registered (any wallet that ever opened), by its address or its
+   * zERC20 ID (`accountId`), or to a receive code (`receiveCode`). An account 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. */
   async send(opts: { to: string; token: Token; amount: bigint; maxFee: bigint }): Promise<Operation> {
@@ -1227,22 +1491,14 @@ export class Wallet {
     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 () => {
+      const r = recipientOf(opts.to, token);
       let to: Destination;
-      if (isAddress(opts.to)) {
-        const recipient = await lookupRecipient(this.#ctx.storage, hexToBytes(opts.to));
+      if (r.kind === 'address') {
+        const recipient = await lookupRecipient(this.#ctx.storage, hexToBytes(r.address));
         if (!recipient)
-          fail(
-            'recipient-not-registered',
-            `${opts.to} cannot be paid privately: withdraw to it publicly, or ask for a receive code`,
-          );
+          fail('recipient-not-registered', `${opts.to.trim()} never opened a zERC20 wallet: 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() };
-      }
+      } else to = { kind: 'code', code: r.code };
       return this.#newPayment('send', token, amount, { to, maxFee: opts.maxFee, step: null, paid: 0n });
     });
   }
@@ -1315,15 +1571,40 @@ export class Wallet {
   }
 }
 
+/** Whom `to` names, as `send` and `deposit` take it: an account, by its address or its zERC20 ID, or a receive code of
+ * `token`'s. */
+function recipientOf(
+  to: string,
+  token: Token,
+): { kind: 'address'; address: Address } | { kind: 'code'; code: string; burnAddress: Hex } {
+  const address = isAddress(to) ? to : idAccount(to);
+  if (address) return { kind: 'address', address };
+  const code = decodeCode(to);
+  if (!code) return fail('invalid', 'not an address, a zERC20 ID or a receive code');
+  if (code.chainId !== token.chainId || code.tokenId !== token.tokenId)
+    fail('invalid', 'the receive code is for another token');
+  return { kind: 'code', code: to.trim(), burnAddress: bytesToHex(code.burnAddress) };
+}
+
+/** 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;
     });