@zerc20/wallet-sdk 0.5.0 → 0.6.0

package/src/wallet.ts

@@ -49,9 +49,10 @@ import {
 import { burnAddressFor, core, initCore } from './core.js';
 import { type ErrorCode, WalletError, fail, guard } from './errors.js';
 import { type Network, checkNetwork } from './network.js';
+import { preload } from './prove.js';
 import { Asp, Indexer, type IndexerStatus, PAGE } from './servers.js';
 import { type Route, flushDepositAddress, rageExit, refundDepositAddress } from './rageExit.js';
-import { registerDeposit, relayerFees, rewatchDeposit } from './services.js';
+import { Relaying, registerDeposit, relayerFees, rewatchDeposit } from './services.js';
 import {
   type Destination,
   type MergeStep,
@@ -59,6 +60,7 @@ import {
   type Step,
   advanceSpend,
   bpsOf,
+  cancellable,
   chosenSettling,
   coins,
   grossed,
@@ -124,6 +126,9 @@ export interface OpenOptions {
   birthday?: bigint | Date;
   /** The app opening the wallet, when it takes a share of what reaches the deposit addresses it hands out. */
   referrer?: Referrer;
+  /** Takes the wallet from another tab or window that holds it open, whose `taken` aborts, rather than failing with
+   * `wallet-in-use`: for a user who opens it here, where the other may be a tab the browser keeps in the background. */
+  take?: boolean;
 }
 
 export interface WatchOptions extends Pick<OpenOptions, 'network' | 'persist' | 'birthday'> {
@@ -214,12 +219,33 @@ export interface CoinInfo {
   /** The deposit address of this wallet's that a deposit came through (its `from`), as `Activity.via` names it: its
    * `rageExit` goes where `to` says. */
   via: { depositAddress: Address } | null;
-  /** For a deposit in `screening`, when the ASP should decide it: an estimate, null until there is one. */
-  screenedBy: Date | null;
+  /** While `screening` or `awaiting-root`, when it should be spendable: the later of its AML check's deadline and when a
+   * root should cover it, by how long commitments on its chain usually wait for one. An estimate: null until there is
+   * one, and in other states. */
+  readyBy: Date | null;
   /** When it landed: its block's time, null until read. */
   at: Date | null;
 }
 
+/** A coin on its way to spendable by itself: screening or settling, which `readyBy` has an estimate for. */
+const onItsWay = (c: CoinInfo) => c.state === 'screening' || c.state === 'awaiting-root';
+
+const total = (coins: CoinInfo[]) => 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: CoinInfo[], need: bigint): CoinInfo | null {
+  const at = (c: CoinInfo) => 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 interface DepositInfo {
   id: string;
   /** The burn address it was sent to. */
@@ -294,8 +320,15 @@ export interface Operation {
   /** Whom a deposit pays, when `deposit({ to })` named an address; null otherwise. One to a receive code shows its code
    * as `via` in `activity()`. */
   readonly to: Address | null;
+  /** Whether `cancel()` can still end it: a send, withdrawal or consolidation that has paid nothing and has no request
+   * out to the relayer. It moves during a sync: read it while one runs. */
+  readonly cancellable: boolean;
   /** Syncs until the operation is done; throws if it fails. */
   wait(): Promise<void>;
+  /** Ends it while `cancellable`, and does nothing once it is cancelled: it paid nothing, its notes and deposits are free
+   * again, it leaves `operations()` and `activity()`, and `wait()` throws `cancelled`. Throws otherwise, and when the
+   * wallet cannot save it, which leaves it under way. */
+  cancel(): Promise<void>;
 }
 
 export class Wallet {
@@ -305,23 +338,37 @@ export class Wallet {
   #queue: Promise<unknown> = Promise.resolve();
   /** Calls running or queued. */
   #busy = 0;
-  #release = () => {};
+  readonly #lock: Hold;
   #referrer: Referrer | undefined;
   readonly #unlock: (() => Promise<Uint8Array>) | undefined;
   #readOnly = false;
   #closed = new AbortController();
 
-  private constructor(ctx: Ctx, unlock?: () => Promise<Uint8Array>) {
+  /** A wallet over `ctx`, held by `lock`: by default held nowhere, as where there are no Web Locks. */
+  private constructor(
+    ctx: Ctx,
+    unlock?: () => Promise<Uint8Array>,
+    lock: Hold = { 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(): Promise<void> {
     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(): AbortSignal {
+    return this.#lock.taken;
   }
 
   get address(): Address {
@@ -358,16 +405,16 @@ export class Wallet {
     const seed = typeof opts.seed === 'function' ? await opts.seed() : opts.seed;
     if (seed.length !== 32) fail('invalid', 'the seed is 32 bytes');
     await initCore();
-    const release = await lockWallet(account.address);
+    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: OpenOptions, seed: Uint8Array, account: Account, release: () => void): Promise<Wallet> {
+  static async #open(opts: OpenOptions, seed: Uint8Array, account: Account, hold: Hold): Promise<Wallet> {
     const address = account.address;
     const chains = chainsOf(opts.network);
     const code = await chains[0]?.chain.client.getCode({ address });
@@ -384,7 +431,7 @@ export class Wallet {
       );
     const storage = await CanisterClient.connect(opts.network.storage.host, opts.network.storage.canisterId);
     const publicKey = hexToBytes((core.spendKey(seed) as SpendKey).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 =
@@ -403,10 +450,9 @@ export class Wallet {
         view,
         chains,
       },
-      { persist: opts.persist, saved, key: stateKey(seed), from: restoring ? 0n : opts.birthday },
+      { persist: opts.persist, saved, key: stateKey(seed), from: restoring ? 0n : opts.birthday, hold },
       typeof opts.seed === 'function' ? opts.seed : undefined,
     );
-    wallet.#release = release;
     wallet.#referrer = opts.referrer;
     return wallet;
   }
@@ -419,7 +465,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
@@ -443,21 +489,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. */
+  /** 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: Omit<Ctx, 'state' | 'save' | 'lastFullRefreshMs'>,
     {
@@ -465,7 +512,14 @@ export class Wallet {
       saved,
       key,
       from,
-    }: { persist: OpenOptions['persist']; saved: Uint8Array | null | undefined; key: Uint8Array; from?: bigint | Date },
+      hold,
+    }: {
+      persist: OpenOptions['persist'];
+      saved: Uint8Array | null | undefined;
+      key: Uint8Array;
+      from?: bigint | Date;
+      hold: Hold;
+    },
     unlock?: () => Promise<Uint8Array>,
   ): Promise<Wallet> {
     const loaded = saved?.length ? openState(key, saved) : null;
@@ -479,14 +533,17 @@ 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: WalletState = loaded ?? emptyWalletState(base.address);
-    const ctx: Ctx = { ...base, state, save: () => persist.save(sealState(key, state)), lastFullRefreshMs: 0 };
+    const save = () => hold.guard(() => persist.save(sealState(key, state)));
+    const ctx: 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;
   }
 
@@ -586,6 +643,9 @@ export class Wallet {
         if (op.kind === 'deposit') await settleDeposit(this.#ctx, op);
         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.
@@ -676,6 +736,12 @@ export class Wallet {
   coins(): CoinInfo[] {
     const size = (chainId: bigint) => this.#status.get(chainId)?.latestRoot?.size ?? 0;
     const unproved = (chainId: bigint) => (this.#status.get(chainId)?.halted ? 'roots-halted' : 'awaiting-root');
+    // when a root should cover a coin that landed at `atMs`
+    const covered = (chainId: bigint, atMs: number | undefined) => {
+      const secs = this.#status.get(chainId)?.settleSecs ?? null;
+      return atMs === undefined || secs === null ? null : atMs + secs * 1000;
+    };
+    const date = (ms: number | null) => (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
@@ -703,7 +769,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),
         });
       }
@@ -723,7 +789,14 @@ 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',
@@ -732,7 +805,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),
         });
       }
@@ -1077,6 +1150,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') return;
@@ -1085,6 +1161,31 @@ export class Wallet {
           if (op.status === 'pending') 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;
+        }
+      },
     };
   }
 
@@ -1417,9 +1518,14 @@ 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(
+        // 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)));
@@ -1445,10 +1551,24 @@ export class Wallet {
     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: Token, need: bigint): CoinInfo | null {
+    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: { kind: 'send' | 'withdraw'; token: Token }): Promise<MaxAmount> {
@@ -1480,6 +1600,12 @@ export class Wallet {
     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(): Promise<void> {
+    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`,
@@ -1595,22 +1721,50 @@ const chainsOf = (network: Network): ChainCtx[] =>
     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: Address, kind: 'wallet' | 'view' = 'wallet'): Promise<() => void> {
+/** A wallet held open here (`lockWallet`): until `release`, or until another tab or window takes it, which aborts
+ * `taken`. */
+export interface Hold {
+  release: () => void;
+  taken: AbortSignal;
+  /** Runs `f`, a read or a write of the wallet's saved state, with no other tab in one, and only while this one holds the
+   * wallet: asked of the browser's lock manager, which knows of a take before this tab is told, so that a write lands
+   * either before the tab that took the wallet reads the state, or not at all. */
+  guard: <T>(f: () => Promise<T>) => Promise<T>;
+}
+
+/** 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: Address, kind: 'wallet' | 'view' = 'wallet', take = false): Promise<Hold> {
+  const taken = new AbortController();
   const locks = (globalThis as { navigator?: Navigator }).navigator?.locks;
-  if (!locks) return () => {};
+  if (!locks) 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<void>((r) => (release = r));
-  const got = await new Promise<boolean>((resolve) => {
-    void locks.request(`zerc20-${kind}:${address.toLowerCase()}`, { ifAvailable: true }, (lock) => {
-      resolve(lock !== null);
-      return lock ? held : undefined;
-    });
+  let got = false;
+  await new Promise<void>((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: unknown) => (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 = <T>(f: () => Promise<T>) =>
+    locks.request(state, async () => {
+      const holders = (await locks.query()).held ?? [];
+      const holder = (n: string) => 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