@zerc20/wallet-sdk 0.5.0 → 0.6.0

package/dist/wallet.js

@@ -8,15 +8,33 @@ import { chainCtx, chainState, owner, refundSigner, switched, walletOn, walletSe
 import { burnAddressFor, core, initCore } from './core.js';
 import { WalletError, fail, guard } from './errors.js';
 import { checkNetwork } from './network.js';
+import { preload } from './prove.js';
 import { Asp, Indexer, PAGE } from './servers.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 { Relaying, registerDeposit, relayerFees, rewatchDeposit } from './services.js';
+import { advanceSpend, bpsOf, cancellable, 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;
+/** A coin on its way to spendable by itself: screening or settling, which `readyBy` has an estimate for. */
+const onItsWay = (c) => c.state === 'screening' || c.state === 'awaiting-root';
+const total = (coins) => coins.reduce((s, c) => s + c.amount, 0n);
+/** Of `coins`, the one whose turning spendable makes them `need`, the soonest first; null where they never do, or the
+ * one it takes has no estimate. */
+export function waitsOn(coins, need) {
+    const at = (c) => c.readyBy?.getTime() ?? Infinity;
+    // two coins with no estimate compare as equal, not as NaN
+    const soonest = [...coins].sort((a, b) => Math.sign(at(a) - at(b)) || 0);
+    let left = need;
+    for (const c of soonest) {
+        left -= c.amount;
+        if (left <= 0n)
+            return c.readyBy ? c : null;
+    }
+    return null;
+}
 export class Wallet {
     #ctx;
     #tokens = [];
@@ -24,21 +42,30 @@ export class Wallet {
     #queue = Promise.resolve();
     /** Calls running or queued. */
     #busy = 0;
-    #release = () => { };
+    #lock;
     #referrer;
     #unlock;
     #readOnly = false;
     #closed = new AbortController();
-    constructor(ctx, unlock) {
+    /** A wallet over `ctx`, held by `lock`: by default held nowhere, as where there are no Web Locks. */
+    constructor(ctx, unlock, lock = { release: () => { }, taken: new AbortController().signal, guard: (f) => f() }) {
         this.#ctx = ctx;
         this.#unlock = unlock;
+        this.#lock = lock;
+        lock.taken.addEventListener('abort', () => this.#closed.abort(lock.taken.reason));
     }
-    /** Lets this wallet open again: in another tab, or here for another account. This object is done with: what is
+    /** Lets this wallet go, for another tab or another account here. 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());
+        return this.#queue.then(() => this.#lock.release());
+    }
+    /** Aborts once another tab or window takes this wallet (`take`), which closes it here: what is queued fails with
+     * `wallet-taken`, a burn address search stops, and the task under way saves nothing more, as the other tab reads the
+     * state and writes it now. */
+    get taken() {
+        return this.#lock.taken;
     }
     get address() {
         return this.#ctx.address;
@@ -73,16 +100,16 @@ export class Wallet {
         if (seed.length !== 32)
             fail('invalid', 'the seed is 32 bytes');
         await initCore();
-        const release = await lockWallet(account.address);
+        const hold = await lockWallet(account.address, 'wallet', opts.take);
         try {
-            return await Wallet.#open(opts, seed, account, release);
+            return await Wallet.#open(opts, seed, account, hold);
         }
         catch (e) {
-            release();
+            hold.release();
             throw e;
         }
     }
-    static async #open(opts, seed, account, release) {
+    static async #open(opts, seed, account, hold) {
         const address = account.address;
         const chains = chainsOf(opts.network);
         const code = await chains[0]?.chain.client.getCode({ address });
@@ -94,7 +121,7 @@ export class Wallet {
             : opts.walletClient.signMessage({ account, message })));
         const storage = await CanisterClient.connect(opts.network.storage.host, opts.network.storage.canisterId);
         const publicKey = hexToBytes(core.spendKey(seed).publicKey);
-        const saved = await opts.persist.load();
+        const saved = await hold.guard(() => 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)));
@@ -110,8 +137,7 @@ export class Wallet {
             storage,
             view,
             chains,
-        }, { persist: opts.persist, saved, key: stateKey(seed), from: restoring ? 0n : opts.birthday }, typeof opts.seed === 'function' ? opts.seed : undefined);
-        wallet.#release = release;
+        }, { persist: opts.persist, saved, key: stateKey(seed), from: restoring ? 0n : opts.birthday, hold }, typeof opts.seed === 'function' ? opts.seed : undefined);
         wallet.#referrer = opts.referrer;
         return wallet;
     }
@@ -123,7 +149,7 @@ export class Wallet {
         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');
+        const hold = 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
@@ -146,21 +172,22 @@ export class Wallet {
             // registered, so its past is looked for
             {
                 persist: opts.persist,
-                saved: await opts.persist.load(),
+                saved: await hold.guard(() => opts.persist.load()),
                 key: stateKey(view.seed),
                 from: opts.birthday ?? 0n,
+                hold,
             });
-            wallet.#release = release;
             wallet.#readOnly = true;
             return wallet;
         }
         catch (e) {
-            release();
+            hold.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) {
+    /** The wallet over `base`, its state opened from what `persist` saved, with `key`, or started `from` a block or date,
+     * as long as `hold` holds it. */
+    static async #begin(base, { persist, saved, key, from, hold, }, 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) {
@@ -169,15 +196,18 @@ export class Wallet {
         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 };
+        const save = () => hold.guard(() => persist.save(sealState(key, state)));
+        const ctx = { ...base, state, save, lastFullRefreshMs: 0 };
         if (!loaded)
             await start(ctx, from);
-        const wallet = new Wallet(ctx, unlock);
+        const wallet = new Wallet(ctx, unlock, hold);
         // 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(ctx.chains.map((c) => c.chain.tokens())), wallet.#readRoots()]);
         wallet.#tokens = tokens.flat();
         keyAll(ctx, wallet.#tokens);
+        // taken while it opened, before it listened
+        hold.taken.throwIfAborted();
         return wallet;
     }
     /** Holds `seed`, asked of `#unlock`, once it is checked to be this wallet's. */
@@ -275,6 +305,10 @@ export class Wallet {
                 delete op.retrying;
             }
             catch (e) {
+                // cancelled while it ran: it stays so. And a relayer relaying its request already answers the request that
+                // started it, so whether a service keeps failing stays as the tries before found it.
+                if (op.status !== 'pending' || e instanceof Relaying)
+                    continue;
                 // 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.
@@ -358,6 +392,12 @@ export class Wallet {
     coins() {
         const size = (chainId) => this.#status.get(chainId)?.latestRoot?.size ?? 0;
         const unproved = (chainId) => (this.#status.get(chainId)?.halted ? 'roots-halted' : 'awaiting-root');
+        // when a root should cover a coin that landed at `atMs`
+        const covered = (chainId, atMs) => {
+            const secs = this.#status.get(chainId)?.settleSecs ?? null;
+            return atMs === undefined || secs === null ? null : atMs + secs * 1000;
+        };
+        const date = (ms) => (ms === null ? null : new Date(ms));
         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. Sync sees it by its
         // nullifier (`unspent`); this device's own is gone already from its relay on (a reorg that drops it brings them
@@ -382,7 +422,7 @@ export class Wallet {
                     state,
                     from: n.peer,
                     via: null,
-                    screenedBy: null,
+                    readyBy: state === 'awaiting-root' ? date(covered(n.chainId, f.atMs)) : null,
                     at: f.atMs === undefined ? null : new Date(f.atMs),
                 });
             }
@@ -402,7 +442,13 @@ export class Wallet {
                             : f.index >= size(d.chainId)
                                 ? unproved(d.chainId)
                                 : 'spendable';
-                const screenedBy = state === 'screening' && f.decidedByMs !== undefined ? new Date(f.decidedByMs) : null;
+                // a root covers a deposit while it is screened, most often before its check ends
+                const settles = covered(d.chainId, f.atMs);
+                const readyBy = state === 'screening'
+                    ? date(f.decidedByMs === undefined ? null : Math.max(f.decidedByMs, settles ?? 0))
+                    : state === 'awaiting-root'
+                        ? date(settles)
+                        : null;
                 out.push({
                     id,
                     kind: 'deposit',
@@ -411,7 +457,7 @@ export class Wallet {
                     state,
                     from: f.sender,
                     via: this.#via(d, f.sender),
-                    screenedBy,
+                    readyBy,
                     at: f.atMs === undefined ? null : new Date(f.atMs),
                 });
             }
@@ -732,6 +778,9 @@ export class Wallet {
                 return op.kind === 'deposit' ? null : (op.data.step?.stage ?? null);
             },
             to: op.kind === 'deposit' ? (op.data.to ?? null) : null,
+            get cancellable() {
+                return cancellable(op);
+            },
             wait: async () => {
                 for (;;) {
                     if (op.status === 'done')
@@ -743,6 +792,31 @@ export class Wallet {
                         await new Promise((r) => setTimeout(r, 15_000));
                 }
             },
+            // at once, outside the queue: a sync under way may wait long on a service that does not answer, and a page closed
+            // before a queued save would find the operation pending and relay it. That sync starts no further stage of it.
+            cancel: async () => {
+                if (op.errorCode === 'cancelled')
+                    return;
+                if (!cancellable(op))
+                    fail('invalid', op.status === 'pending'
+                        ? 'it has a request out to the relayer, or has paid: it finishes or fails on its own'
+                        : `it is ${op.status}`);
+                const ops = this.#ctx.state.ops;
+                const at = ops.indexOf(op);
+                if (at < 0)
+                    fail('invalid', 'this wallet no longer holds it');
+                ops.splice(at, 1);
+                Object.assign(op, { status: 'failed', errorCode: 'cancelled', error: 'cancelled' });
+                try {
+                    await this.#ctx.save();
+                }
+                catch (e) {
+                    // not saved, so not cancelled: the saved state would resume it
+                    Object.assign(op, { status: 'pending', errorCode: undefined, error: undefined });
+                    ops.splice(at, 0, op);
+                    throw e;
+                }
+            },
         };
     }
     #newOp(kind, token, amount, data) {
@@ -1028,7 +1102,11 @@ export class Wallet {
         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');
+                // all of them must be spendable: the last one on its way, where each is a coin with an estimate
+                const ids = new Set(opts.coins);
+                const picked = this.coins().filter((c) => ids.has(c.id));
+                const waiting = picked.filter((c) => c.state !== 'spendable');
+                throw new WalletError('funds-settling', 'a chosen note or deposit is still settling: quote again once coins() shows it spendable', picked.length === ids.size && waiting.every(onItsWay) ? waitsOn(waiting, total(waiting)) : null);
             }
             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
@@ -1045,9 +1123,25 @@ export class Wallet {
         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);
+        const need = amount + relayer + protocol;
+        try {
+            payWith(all, need, relayer, onTheWay);
+        }
+        catch (e) {
+            if (!(e instanceof WalletError) || e.code !== 'funds-settling')
+                throw e;
+            throw new WalletError(e.code, e.message, this.#waitsFor(token, need));
+        }
         return { relayer, protocol, protocolBps: bpsOf(protocol, withdrawn), fee: relayer + protocol, steps: 1 };
     }
+    /** Of `token`'s coins on their way, the one whose turning spendable lets a payment of `need` go, as
+     * `WalletError.waitsOn` tells. None while an operation is in flight, as its change is not a coin yet. */
+    #waitsFor(token, need) {
+        if (this.#ctx.state.ops.some((o) => o.status === 'pending'))
+            return null;
+        const mine = this.coins().filter((c) => c.token.chainId === token.chainId && c.token.tokenId === token.tokenId);
+        return waitsOn(mine.filter(onItsWay), need - total(mine.filter((c) => c.state === 'spendable')));
+    }
     /** 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) {
@@ -1068,6 +1162,11 @@ export class Wallet {
         const merge = mergeRound(coins(this.#ctx, token.chainId, token.tokenId, size), fee);
         return merge && merge.map((m) => `${token.chainId}:${m.index}`);
     }
+    /** Fetches what a send or withdrawal proves with, some 25 MB, once a page: an app calls it as a payment form opens,
+     * so that the payment's proof does not wait for the download. Outside the queue of calls: a sync goes on meanwhile. */
+    preloadProver() {
+        return preload(this.#ctx.network.circuits.joinsplit);
+    }
     /** 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`,
@@ -1178,24 +1277,41 @@ const chainsOf = (network) => network.chains.map((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. 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') {
+/** Holds `address`'s wallet: two tabs on one wallet would each overwrite the other's state and spend the same notes. It
+ * fails with `wallet-in-use` while another tab or window holds it, unless it `take`s it from that one. A wallet that
+ * watches it (`view`) is held apart, as its state is its own. Neither where there are no Web Locks. */
+export async function lockWallet(address, kind = 'wallet', take = false) {
+    const taken = new AbortController();
     const locks = globalThis.navigator?.locks;
     if (!locks)
-        return () => { };
+        return { release: () => { }, taken: taken.signal, guard: (f) => f() };
+    const name = `zerc20-${kind}:${address.toLowerCase()}`;
+    const lose = () => taken.abort(new WalletError('wallet-taken', 'this wallet was opened in another tab or window'));
     let release = () => { };
     const held = new Promise((r) => (release = r));
-    const got = await new Promise((resolve) => {
-        void locks.request(`zerc20-${kind}:${address.toLowerCase()}`, { ifAvailable: true }, (lock) => {
-            resolve(lock !== null);
-            return lock ? held : undefined;
-        });
+    let got = false;
+    await new Promise((resolve, reject) => {
+        locks
+            .request(name, take ? { steal: true } : { ifAvailable: true }, (lock) => {
+            got = lock !== null;
+            resolve();
+            return got ? held : undefined;
+        })
+            // a held lock's request rejects as another takes it
+            .catch((e) => (got ? lose() : reject(e)));
     });
     if (!got)
         fail('wallet-in-use', 'this wallet is open in another tab or window: close it there first');
-    return release;
+    const state = `${name}/state`;
+    const guard = (f) => locks.request(state, async () => {
+        const holders = (await locks.query()).held ?? [];
+        const holder = (n) => holders.find((l) => l.name === n)?.clientId;
+        if (holder(name) !== holder(state))
+            lose();
+        taken.signal.throwIfAborted();
+        return f();
+    });
+    return { release, taken: taken.signal, guard };
 }
 /** 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. */