@zerc20/wallet-sdk 0.3.0 → 0.5.0

package/dist/wallet.js

@@ -1,17 +1,20 @@
 // The wallet an app works with. Amounts are bigints in a token's base units.
-import { CanisterClient, codeKey, commit, decodeCode, encodeCode, lookupRecipient, nextPosLane, planDeposit, planPosLane, posKey, registeredViewKey, } from '@zerc20/storage-sdk';
-import { bytesToHex, formatUnits, hexToBytes, isAddress, numberToHex, zeroAddress, } from 'viem';
+import { CanisterClient, codeKey, commit, decodeCode, encodeCode, lookupRecipient, nextPosLane, notifyKey, planDeposit, planPosLane, posKey, registeredViewKey, } from '@zerc20/storage-sdk';
+import { 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, erc20Abi, tokenAbi } from './chain.js';
-import { chainCtx, chainState, owner, switched, walletOn, walletSees } from './context.js';
+import { chainCtx, chainState, owner, refundSigner, switched, walletOn, walletSees, } from './context.js';
 import { burnAddressFor, core, initCore } from './core.js';
 import { WalletError, fail, guard } from './errors.js';
 import { checkNetwork } from './network.js';
 import { Asp, Indexer, PAGE } from './servers.js';
-import { rageExit } from './rageExit.js';
-import { registerDeposit, relayerFees } from './services.js';
-import { advanceSpend, chosenSettling, coins, grossed, inputsOf, landed, maxPayment, mergePool, mergeRound, payWith, planStep, roundsToMerge, settling, withdrawalOf, } from './spend.js';
+import { flushDepositAddress, rageExit, refundDepositAddress } from './rageExit.js';
+import { registerDeposit, relayerFees, rewatchDeposit } from './services.js';
+import { advanceSpend, bpsOf, chosenSettling, coins, grossed, inputsOf, landed, maxPayment, mergePool, mergeRound, payWith, planStep, roundsToMerge, settling, withdrawalOf, } from './spend.js';
 import { emptyWalletState, openState, sealState, stateKey, unspent, } from './state.js';
 import { WAIT_MS, commitmentTx, keyAll, nextBurn, recordBurn, storageState, syncAll, takeRefresh, tokenIds, topUpBurns, unusedBurn, } from './sync.js';
+import { decodeViewKey, encodeViewKey } from './viewKey.js';
 /** The ledger's bound outside an emergency. */
 const NO_BOUND = 2n ** 64n - 1n;
 export class Wallet {
@@ -24,6 +27,7 @@ export class Wallet {
     #release = () => { };
     #referrer;
     #unlock;
+    #readOnly = false;
     #closed = new AbortController();
     constructor(ctx, unlock) {
         this.#ctx = ctx;
@@ -39,6 +43,16 @@ export class Wallet {
     get address() {
         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() {
+        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() {
+        return this.#readOnly;
+    }
     /** Opens the wallet. The first time on this address, registers it for payments: one signature. */
     static async open(opts) {
         checkNetwork(opts.network);
@@ -70,12 +84,7 @@ export class Wallet {
     }
     static async #open(opts, seed, account, release) {
         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'))
@@ -90,37 +99,83 @@ export class Wallet {
         // 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, seed, signer, hexToBytes(address), publicKey);
-        const key = stateKey(seed);
-        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');
-        }
-        if (loaded && loaded.address.toLowerCase() !== address.toLowerCase())
-            fail('invalid', `the saved state is ${loaded.address}'s: keep one per address`);
-        const state = loaded ?? emptyWalletState(address);
-        const ctx = {
+        const wallet = await Wallet.#begin({
             network: opts.network,
             seed,
             owners: new Map(),
+            refundSigners: 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);
+        }, { 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) {
+        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, { persist, saved, key, from, }, unlock) {
+        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 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() !== base.address.toLowerCase())
+            fail('invalid', `the saved state is ${loaded.address}'s: keep one per address`);
+        const state = loaded ?? emptyWalletState(base.address);
+        const 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;
@@ -151,10 +206,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(f, needs = true) {
+        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() {
+        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(f) {
         this.#busy++;
@@ -192,8 +253,10 @@ 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
         });
@@ -201,10 +264,8 @@ export class Wallet {
     async #catchUp() {
         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) => (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')
@@ -320,7 +381,9 @@ export class Wallet {
                     amount: n.value,
                     state,
                     from: n.peer,
+                    via: null,
                     screenedBy: null,
+                    at: f.atMs === undefined ? null : new Date(f.atMs),
                 });
             }
         }
@@ -347,7 +410,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),
                 });
             }
         }
@@ -418,24 +483,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
@@ -478,9 +536,17 @@ export class Wallet {
                 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)
+                const { to, code, txHash } = op.data;
+                if ((!to && !code) || !txHash || op.status === 'pending' || found)
                     continue;
-                out.push({ ...base, kind: 'sent', fee: null, counterparty: op.data.to, via: null, txHash: op.data.txHash });
+                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
@@ -498,6 +564,17 @@ 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, sender) {
+        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, burnAddress) {
         for (const c of this.#ctx.state.storage?.outgoing.lanes ?? []) {
@@ -539,6 +616,31 @@ export class Wallet {
             state: f.spent ? 'spent' : f.asp === null ? 'screening' : f.asp,
         })));
     }
+    /** 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() {
+        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, address) {
+        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() {
@@ -550,6 +652,7 @@ export class Wallet {
      * addresses. */
     posKey() {
         return this.#exclusive(async () => {
+            this.#writable();
             const ctx = this.#ctx;
             const tokens = await tokenIds(ctx);
             let n = 0;
@@ -561,8 +664,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) {
+     * 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, opts = {}) {
+        const route = this.#route(opts);
         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)) ??
@@ -571,9 +678,32 @@ export class Wallet {
             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));
+            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, asset, opts = {}) {
+        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) {
+        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() {
         return this.#ctx.state.ops.map((op) => this.#operation(op));
     }
@@ -638,7 +768,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
@@ -652,10 +784,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.
@@ -666,9 +800,11 @@ export class Wallet {
      * 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. */
     async deposit(opts) {
+        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');
@@ -691,10 +827,16 @@ export class Wallet {
                 const of = wrapped ? token.symbol : `${token.symbol}'s underlying asset`;
                 fail('insufficient-funds', `${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 op = this.#newOp('deposit', token, amount, opts.to ? { burnAddress: address, to: opts.to } : { burnAddress: 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, to?.kind === 'code'
+                ? { burnAddress: address, code: to.code }
+                : to
+                    ? { burnAddress: address, to: to.address }
+                    : { burnAddress: address });
             await this.#ctx.save();
             try {
                 const wc = opts.from ? await switched(opts.from, token.chainId) : await walletOn(this.#ctx, token.chainId);
@@ -764,7 +906,7 @@ export class Wallet {
         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`);
+            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
@@ -783,17 +925,28 @@ 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, opts = {}) {
         const step = opts.onStep ?? (() => { });
+        const ctx = this.#ctx;
+        const code = (index) => ({ 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(c.chain, token.address, record.address, this.address, this.#referrer);
+            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, { 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();
             this.#ctx.state.receipts.push({
                 kind: 'deposit-address',
@@ -801,12 +954,42 @@ 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) {
+        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, opts) {
+        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) {
+        return (this.#ctx.state.receipts.find((r) => 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
      * of the token to the code's burn address (a deposit, like a point of sale's payment addresses), or privately by
@@ -850,14 +1033,20 @@ 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(this.#ctx, token.chainId, token.tokenId, opts.kind === 'withdraw', amount, relayer);
+        const { withdrawn, 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 };
+        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`). */
@@ -879,9 +1068,10 @@ export class Wallet {
         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`.
+    /** 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) {
@@ -890,21 +1080,16 @@ export class Wallet {
             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;
-            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 });
         });
     }
@@ -973,16 +1158,37 @@ export class Wallet {
         return this.#operation(op);
     }
 }
+/** 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, token) {
+    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.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) {
+ * 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, kind = 'wallet') {
     const locks = globalThis.navigator?.locks;
     if (!locks)
         return () => { };
     let release = () => { };
     const held = new Promise((r) => (release = r));
     const got = await new Promise((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;
         });