@zerc20/wallet-sdk 0.4.0 → 0.6.0

package/src/core.ts

@@ -28,21 +28,22 @@ export interface Burn {
 
 /** The `index`-th burn address of `publicKey` on a chain and token, and its salt, from `burnKey`: the wallet's own burn
  * key, or a point of sale's (`wallet_keys::derive_burn_address`). About 2^16 hashes, spread over the device's cores
- * (Web Workers in a browser, worker threads in Node) so that the app stays responsive; `signal` stops the search. */
+ * (Web Workers in a browser, worker threads in Node) so that the app stays responsive; `signal` stops the search. One
+ * that nobody waits for, made ahead, is `urgent: false`: it gives way to those someone waits for. */
 export const burnAddress = (
   burnKey: Uint8Array,
   chainId: bigint,
   tokenId: number,
   index: number,
   publicKey: Hex,
-  signal?: AbortSignal,
-): Promise<Burn> => search({ burnKey, chainId, tokenId, index, publicKey }, signal);
+  opts: { signal?: AbortSignal; urgent?: boolean } = {},
+): Promise<Burn> => search({ burnKey, chainId, tokenId, index, publicKey }, opts.urgent ?? true, opts.signal);
 
 /** A burn address of someone else's `publicKey` (one they published to be paid), with a random salt that has the proof
  * of work: about 2^16 hashes too, searched the same way. Only who holds the salt finds it: the payer, and the owner once
  * told (`planSend` with `burn`). */
 export const burnAddressFor = (chainId: bigint, publicKey: Hex, signal?: AbortSignal): Promise<Burn> =>
-  search({ chainId, publicKey }, signal);
+  search({ chainId, publicKey }, true, signal);
 
 export type BurnSearch =
   | { burnKey: Uint8Array; chainId: bigint; tokenId: number; index: number; publicKey: Hex }
@@ -60,16 +61,27 @@ export interface BurnBlock {
 
 export type BurnAnswer = { burn: Burn | null } | { error: string };
 
-/** The address a block holds, if any. Its salts count up from a start: one the burn key derives, or for someone else's
- * key a random one below 2^253, so that every salt is a field element. */
-export function runBlock({ search: s, from, to }: BurnBlock): Burn | null {
-  let burn: unknown;
-  if ('burnKey' in s) burn = core.burnBlock(s.burnKey, s.chainId, s.tokenId, s.index, s.publicKey, from, to);
-  else {
-    const start = crypto.getRandomValues(new Uint8Array(32));
-    start[0] = start[0] & 0x1f;
-    burn = core.burnBlockFor(s.chainId, s.publicKey, bytesToHex(start), to - from + 1);
-  }
+/** What a block asks of the protocol code: `burnBlock`'s arguments, or `burnBlockFor`'s. */
+export type BurnCall =
+  | { burnKey: Uint8Array; chainId: bigint; tokenId: number; index: number; publicKey: Hex; from: number; to: number }
+  | { chainId: bigint; publicKey: Hex; start: Hex; count: number };
+
+/** A block's call. Its salts count up from a start: one the burn key derives, or for someone else's key a random one
+ * below 2^253, so that every salt is a field element. */
+export function blockCall({ search: s, from, to }: BurnBlock): BurnCall {
+  if ('burnKey' in s) return { ...s, from, to };
+  const start = crypto.getRandomValues(new Uint8Array(32));
+  start[0] = start[0] & 0x1f;
+  return { chainId: s.chainId, publicKey: s.publicKey, start: bytesToHex(start), count: to - from + 1 };
+}
+
+/** The address a block holds, if any. */
+export function runBlock(b: BurnBlock): Burn | null {
+  const c = blockCall(b);
+  const burn: unknown =
+    'burnKey' in c
+      ? core.burnBlock(c.burnKey, c.chainId, c.tokenId, c.index, c.publicKey, c.from, c.to)
+      : core.burnBlockFor(c.chainId, c.publicKey, c.start, c.count);
   return (burn as Burn | undefined) ?? null;
 }
 
@@ -155,8 +167,17 @@ type NodeWorker = new (url: URL) => {
   terminate(): Promise<number>;
 };
 
-/** Searches in progress, oldest first: blocks go to the oldest that has one to hand out. */
-const searches: Search[] = [];
+/** Searches in progress by owner (the burn key, or the key paid): those someone waits for, and those made ahead. Each
+ * owner in turn gets a block of its oldest search that has one, so that one owner's many searches hold up no other's,
+ * and each address it waits for comes as soon as its cores allow. */
+// ponytail: fair per owner, so per point of sale; a merchant opening many accounts gets many turns, so cap each
+// merchant's sales if that happens
+const queues = { urgent: new Map<string, Search[]>(), later: new Map<string, Search[]>() };
+/** One block in this many goes to the searches made ahead while some are waited for: a flood of urgent searches slows
+ * the making ahead, which keeps everyone else's sales from waiting, but does not stop it. */
+const LATER_EVERY = 4;
+/** Urgent blocks handed out in a row. */
+let urgentRun = 0;
 let threads: Thread[] | null = null;
 let starting = false;
 /** Workers do not run here (a page whose CSP forbids them, a bundler that left burnWorker.js out, tests run from
@@ -167,27 +188,51 @@ let idle: ReturnType<typeof setTimeout> | undefined;
 /** An idle pool stops after this long, freeing a wasm instance per core. */
 const IDLE_MS = 30_000;
 
-async function search(s: BurnSearch, signal?: AbortSignal): Promise<Burn> {
+async function search(s: BurnSearch, urgent: boolean, signal?: AbortSignal): Promise<Burn> {
   await initCore();
   signal?.throwIfAborted();
+  const queue = urgent ? queues.urgent : queues.later;
+  const owner = 'burnKey' in s ? bytesToHex(s.burnKey) : s.publicKey;
   return new Promise((resolve, reject) => {
     const abort = () => one.fail(signal!.reason);
     const one = new Search(s, (r) => {
       signal?.removeEventListener('abort', abort);
-      searches.splice(searches.indexOf(one), 1);
+      const mine = queue.get(owner)!;
+      mine.splice(mine.indexOf(one), 1);
+      if (!mine.length) queue.delete(owner);
       if ('burn' in r) resolve(r.burn);
       else reject(r.error);
     });
     signal?.addEventListener('abort', abort, { once: true });
-    searches.push(one);
+    const mine = queue.get(owner);
+    if (mine) mine.push(one);
+    else queue.set(owner, [one]);
     dispatch();
   });
 }
 
 function nextJob(): Job | null {
-  for (const search of searches) {
-    const block = search.take();
-    if (block !== undefined) return { search, block };
+  const order = urgentRun >= LATER_EVERY - 1 ? [queues.later, queues.urgent] : [queues.urgent, queues.later];
+  for (const queue of order) {
+    const job = takeFrom(queue);
+    if (!job) continue;
+    urgentRun = queue === queues.urgent ? urgentRun + 1 : 0;
+    return job;
+  }
+  return null;
+}
+
+/** A block of the first owner in line that has one, from its oldest search that does; that owner then goes to the back
+ * of the line. */
+function takeFrom(queue: Map<string, Search[]>): Job | null {
+  for (const [owner, mine] of queue) {
+    for (const search of mine) {
+      const block = search.take();
+      if (block === undefined) continue;
+      queue.delete(owner);
+      queue.set(owner, mine);
+      return { search, block };
+    }
   }
   return null;
 }
@@ -203,9 +248,49 @@ function deliver({ search, block }: Job, a: BurnAnswer) {
   else search.finish(block, a.burn);
 }
 
-/** Hands blocks to idle threads, starting the pool if it is not running. */
+/** Runs blocks somewhere other than this module's wasm: a server's native process, say. */
+export interface BurnRunner {
+  /** How many blocks it runs at once. */
+  slots: number;
+  run(call: BurnCall): Promise<Burn | null>;
+}
+
+let runner: BurnRunner | null = null;
+/** Blocks the runner has and has not answered. */
+const onRunner = new Set<Job>();
+
+/** Runs every block from now on on `r`, or with null in this module's wasm again. The blocks the runner had are handed
+ * out again, and what it answers for them later is dropped. */
+export function runBurnsOn(r: BurnRunner | null): void {
+  for (const job of onRunner) job.search.drop(job.block);
+  onRunner.clear();
+  runner = r;
+  dispatch();
+}
+
+function feed(r: BurnRunner) {
+  while (onRunner.size < r.slots) {
+    const job = nextJob();
+    if (!job) return;
+    onRunner.add(job);
+    void r
+      .run(blockCall(blockOf(job)))
+      .then(
+        (burn): BurnAnswer => ({ burn }),
+        (e: unknown): BurnAnswer => ({ error: e instanceof Error ? e.message : String(e) }),
+      )
+      .then((a) => {
+        if (!onRunner.delete(job)) return; // handed out again when the runner was taken away
+        deliver(job, a);
+        dispatch();
+      });
+  }
+}
+
+/** Hands blocks to the runner, or to idle threads, starting the pool if it is not running. */
 function dispatch() {
   clearTimeout(idle);
+  if (runner) return feed(runner);
   if (here) return void runHere();
   if (!threads) return void start();
   for (const t of threads) {
@@ -216,7 +301,7 @@ function dispatch() {
     t.busy(true);
     t.send(blockOf(job));
   }
-  if (!searches.length && threads.every((t) => !t.job)) {
+  if (!queues.urgent.size && !queues.later.size && threads.every((t) => !t.job)) {
     idle = setTimeout(stop, IDLE_MS);
     (idle as { unref?: () => void }).unref?.(); // a process need not stay up for it
   }
@@ -313,7 +398,8 @@ async function spawn(count: number): Promise<Thread[]> {
 }
 
 /** Runs the blocks on this thread, yielding to the event loop every ~100 ms, and no more often: each yield is a timer,
- * which costs 4 ms in a visible tab and a whole second in a hidden one. */
+ * which costs 4 ms in a visible tab and a whole second in a hidden one. A runner set meanwhile takes every block from
+ * the next on. */
 async function runHere() {
   if (!here) {
     here = true;
@@ -322,7 +408,7 @@ async function runHere() {
   if (runningHere) return;
   runningHere = true;
   let since = Date.now();
-  for (let job; (job = nextJob());) {
+  for (let job; !runner && (job = nextJob());) {
     let a: BurnAnswer;
     try {
       a = { burn: runBlock(blockOf(job)) };

package/src/errors.ts

@@ -1,6 +1,7 @@
 // What can go wrong, by code, so that an app can tell the user what to do.
 
 import { BaseError, UserRejectedRequestError } from 'viem';
+import type { CoinInfo } from './wallet.js';
 
 export type ErrorCode =
   /** Not enough value for the amount and its fees, even counting what is still settling. */
@@ -9,10 +10,14 @@ export type ErrorCode =
    * `fees({ kind: 'consolidate' })` tells how many rounds that takes. */
   | 'needs-consolidation'
   /** What is spendable now does not pay it, but notes or deposits are still settling (screening, awaiting
-   * a root, or the change of an operation in flight): pay again once `balances()` shows them spendable. */
+   * a root, or the change of an operation in flight): pay again once `balances()` shows them spendable. The error's
+   * `waitsOn` tells which coin, where that is known. */
   | 'funds-settling'
   /** The fees are above the `maxFee` the caller allowed. */
   | 'fee-too-high'
+  /** Another device of this wallet spent a note or deposit the operation was spending, first: each device locks its
+   * inputs in its own state. The operation cannot land and paid nothing: pay again. */
+  | 'spent-elsewhere'
   /** The address never registered for private payments: pay it publicly or ask for a receive code. */
   | 'recipient-not-registered'
   /** The withdrawal's recipient (or a merge's fee recipient) fails the attester's AML screening: withdraw elsewhere. */
@@ -21,8 +26,12 @@ export type ErrorCode =
   | 'unsupported-account'
   /** The user declined a signature or a transaction in their wallet. */
   | 'user-rejected'
-  /** The wallet is open in another tab or window: close it there (`close()`), then open it here. */
+  /** The operation was cancelled (`cancel()`) before anything went to the relayer: it paid nothing. */
+  | 'cancelled'
+  /** The wallet is open in another tab or window: close it there (`close()`), or open it here with `take`. */
   | 'wallet-in-use'
+  /** Another tab or window took this wallet (`taken`): open it again with `take` to take it back. */
+  | 'wallet-taken'
   /** This wallet watches its account by its view key (`Wallet.watch`): it spends and writes nothing. */
   | 'read-only'
   /** This wallet object was closed (`close()`): open the wallet again to go on. */
@@ -40,6 +49,10 @@ export class WalletError extends Error {
   constructor(
     readonly code: ErrorCode,
     message: string,
+    /** For `funds-settling`, the coin on its way whose turning spendable should let it pay: when, by its `readyBy`,
+     * and why, by its `state`. Null where it may wait on something with no estimate (a halted root, a note not
+     * confirmed yet, an operation in flight), or where what is on its way does not pay it either. */
+    readonly waitsOn: CoinInfo | null = null,
   ) {
     super(message);
     this.name = 'WalletError';

package/src/index.ts

@@ -5,14 +5,25 @@
 //   wallet.balances();                       // spendable, and what is pending and why
 //   await (await wallet.deposit({ token, amount })).wait();
 //   const q = await wallet.fees({ kind: 'send', token, amount });
-//   await (await wallet.send({ to: '0x…', token, amount, maxFee: q.fee })).wait();
+//   await (await wallet.send({ to: 'zerc20id1…', token, amount, maxFee: q.fee })).wait();
 //   const watching = await Wallet.watch({ network, viewKey: wallet.viewKey(), persist }); // elsewhere, spends nothing
 //
 // Nothing secret leaves the device unencrypted: JoinSplit proofs are made here, a merge's by the merge prover, and the
 // attester and the prover get the witness sealed to an enclave whose measurement the wallet checks. Servers are only
 // ever asked for what every wallet downloads.
 
-export { Chain, type Referrer, type Token, MAX_REFERRAL_BPS, NATIVE, UNWRAP_INTENT } from './chain.js';
+export { accountId, idAccount } from './accountId.js';
+export {
+  Chain,
+  type Referrer,
+  type Refund,
+  type Token,
+  MAX_REFERRAL_BPS,
+  NATIVE,
+  UNWRAP_INTENT,
+  rpcTransport,
+} from './chain.js';
+export { type Burn, type BurnCall, type BurnRunner, runBurnsOn } from './core.js';
 export { type ErrorCode, WalletError } from './errors.js';
 export {
   type AttesterTrust,
@@ -31,9 +42,11 @@ export {
   type Balance,
   type CoinInfo,
   type CoinState,
+  type DepositAddressInfo,
   type DepositInfo,
   type DepositStep,
   type FeeQuote,
+  type MaxAmount,
   type OpenOptions,
   type Operation,
   type OperationKind,

package/src/network.ts

@@ -24,8 +24,10 @@ export const NITRO_ROOT_SHA256 = '641a0321a3e244efe456463195d606317ed7cdcc3c1756
 
 export interface ChainConfig {
   chainId: bigint;
-  /** Used for every read and for waiting on receipts, never the wallet's own RPC. */
-  rpcUrl: string;
+  /** The chain's RPCs, in order, for every read and every wait on a receipt, never the wallet's own: a call goes on
+   * to the next one when one fails it, so one that a resolver, a firewall or an outage keeps from a device stops
+   * nothing. */
+  rpcUrls: string[];
   verifier: Address;
   depositAddressFactory: Address;
   indexer: string;
@@ -84,7 +86,8 @@ export function checkNetwork(n: Network): void {
     }
   };
   for (const c of n.chains) {
-    servers([c.rpcUrl, c.indexer, c.asp, c.attester, c.transactRelayer, c.depositRelayer]);
+    if (!c.rpcUrls.length) bad(`chain ${c.chainId} names no RPC`);
+    servers([...c.rpcUrls, c.indexer, c.asp, c.attester, c.transactRelayer, c.depositRelayer]);
     trusted([c], 'attester', c.attesterTrust);
   }
   if (n.mergeProver) {