@zerc20/wallet-sdk 0.0.0-stage → 0.2.0

package/dist/wallet.js

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