@zerc20/wallet-sdk 0.1.0 → 0.3.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@zerc20/wallet-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A zERC20 wallet for browsers and Node: deposits, private payments, withdrawals and rage exits.",
   "type": "module",
   "license": "Unlicense",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kbizikav/zerc20-v2-new.git",
+    "url": "git+https://github.com/zerc20io/zERC20v2.git",
     "directory": "wallet/sdk"
   },
   "main": "dist/index.js",
@@ -35,7 +35,8 @@
     "@noble/ciphers": "^2.3.0",
     "@noble/curves": "^2.3.0",
     "@noble/hashes": "^2.3.0",
-    "@zerc20/storage-sdk": "^0.1.0",
+    "@scure/bip39": "^2.4.0",
+    "@zerc20/storage-sdk": "^0.3.0",
     "snarkjs": "0.7.6"
   },
   "peerDependencies": {

package/src/burnWorker.ts

@@ -1,25 +1,24 @@
-// Searches a burn address off the main thread: core.ts starts one per search, a Web Worker in a browser and a worker
-// thread in Node.
+// Runs blocks of burn address searches off the main thread, one at a time: core.ts keeps a pool of these, Web Workers
+// in a browser and worker threads in Node.
 
-import { type BurnAnswer, type BurnSearch, initCore, searchHere } from './core.js';
+import { type BurnAnswer, type BurnBlock, initCore, runBlock } from './core.js';
 
-async function answer(s: BurnSearch): Promise<BurnAnswer> {
+async function answer(b: BurnBlock): Promise<BurnAnswer> {
   try {
     await initCore();
-    return { burn: searchHere(s) };
+    return { burn: runBlock(b) };
   } catch (e) {
     return { error: e instanceof Error ? e.message : String(e) };
   }
 }
 
 if (typeof self !== 'undefined') {
-  self.onmessage = async ({ data }: MessageEvent<BurnSearch>) => postMessage(await answer(data));
+  self.onmessage = async ({ data }: MessageEvent<BurnBlock>) => postMessage(await answer(data));
 } else {
   // a variable, so that bundlers for the browser leave Node's module alone
   const threads = 'node:worker_threads';
-  type Port = { postMessage(a: BurnAnswer): void };
-  void import(/* @vite-ignore */ threads).then(
-    async ({ parentPort, workerData }: { parentPort: Port; workerData: BurnSearch }) =>
-      parentPort.postMessage(await answer(workerData)),
+  type Port = { on(event: 'message', f: (b: BurnBlock) => void): void; postMessage(a: BurnAnswer): void };
+  void import(/* @vite-ignore */ threads).then(({ parentPort }: { parentPort: Port }) =>
+    parentPort.on('message', (b) => void answer(b).then((a) => parentPort.postMessage(a))),
   );
 }

package/src/chain.ts

@@ -57,9 +57,19 @@ export const erc20Abi = parseAbi([
 ]);
 
 export const depositFactoryAbi = parseAbi([
-  'function predict(address token, address burnAddress, address refundAddress, address feeRecipient, uint256 fee) view returns (address)',
+  'function predict(address token, address burnAddress, address refundAddress, address feeRecipient, uint256 fee, address referrer, uint16 referralBps) view returns (address)',
 ]);
 
+/** The factory's `MAX_REFERRAL_BPS`: the most of a deposit, after the relayer's fee, that a referrer can take. */
+export const MAX_REFERRAL_BPS = 300;
+
+/** An app that hands out deposit addresses and takes `bps` of each payment to them, of what is left after the relayer's
+ * fee. `address` is paid, and also names the app on chain. */
+export interface Referrer {
+  address: Address;
+  bps: number;
+}
+
 export const depositAddressAbi = parseAbi(['function refund(address asset)']);
 
 /** The native asset's stand-in for `underlyingAsset`. */
@@ -106,35 +116,48 @@ export class Chain {
   }
 
   /** The deposit address the factory deploys for `token`, `burnAddress` and `refundAddress`, whose flush pays `fee`
-   * to `feeRecipient`. */
+   * to `feeRecipient` and `referralBps` of the rest to `referrer`. */
   predictDepositAddress(
     token: Address,
     burnAddress: Hex,
     refundAddress: Address,
     feeRecipient: Address,
     fee: bigint,
+    referrer: Address,
+    referralBps: number,
   ): Promise<Address> {
     return this.client.readContract({
       address: this.config.depositAddressFactory,
       abi: depositFactoryAbi,
       functionName: 'predict',
-      args: [token, burnAddress, refundAddress, feeRecipient, fee],
+      args: [token, burnAddress, refundAddress, feeRecipient, fee, referrer, referralBps],
     });
   }
 
   /** The refund address of `address` if it is a deployed deposit address for `token` and `burnAddress`, whatever its
-   * refund address and fee; null if it is not one. A clone's code ends with its immutable args, `abi.encode(token,
-   * burnAddress, refundAddress, feeRecipient, fee)`; the factory's address for them confirms it, so code made to look
-   * like one does not pass. */
+   * refund address, fee and referral; null if it is not one. A clone's code ends with its immutable args,
+   * `abi.encode(token, burnAddress, refundAddress, feeRecipient, fee, referrer, referralBps)`; the factory's address
+   * for them confirms it, so code made to look like one does not pass. */
   async depositAddressRefund(address: Address, token: Address, burnAddress: Hex): Promise<Address | null> {
     const code = await this.client.getCode({ address });
-    if (!code || size(code) < 160) return null;
-    const [refundAddress, feeRecipient, fee] = decodeAbiParameters(
-      [{ type: 'address' }, { type: 'address' }, { type: 'uint256' }],
-      slice(code, size(code) - 96),
+    if (!code || size(code) < 224) return null;
+    // the uint16 read as a whole word, so code made to look like a clone cannot make the decoding throw
+    const [refundAddress, feeRecipient, fee, referrer, referralBps] = decodeAbiParameters(
+      [{ type: 'address' }, { type: 'address' }, { type: 'uint256' }, { type: 'address' }, { type: 'uint256' }],
+      slice(code, size(code) - 160),
+    );
+    // predict would revert
+    if (refundAddress === zeroAddress || feeRecipient === zeroAddress) return null;
+    if (referralBps > MAX_REFERRAL_BPS || (referrer === zeroAddress && referralBps !== 0n)) return null;
+    const expected = await this.predictDepositAddress(
+      token,
+      burnAddress,
+      refundAddress,
+      feeRecipient,
+      fee,
+      referrer,
+      Number(referralBps),
     );
-    if (refundAddress === zeroAddress || feeRecipient === zeroAddress) return null; // predict would revert
-    const expected = await this.predictDepositAddress(token, burnAddress, refundAddress, feeRecipient, fee);
     return expected.toLowerCase() === address.toLowerCase() ? refundAddress : null;
   }
 

package/src/context.ts

@@ -1,9 +1,10 @@
 // Everything an open wallet works with, shared by sync and the operations.
 
 import type { CanisterClient, ViewKey } from '@zerc20/storage-sdk';
-import { type Hex, type WalletClient, publicActions } from 'viem';
+import { type Account, type Hex, type WalletClient, createWalletClient, http, publicActions } from 'viem';
 import type { Chain } from './chain.js';
 import { core } from './core.js';
+import { guard } from './errors.js';
 import type { ChainConfig, Network } from './network.js';
 import type { Asp, Indexer } from './servers.js';
 import type { ChainState, WalletState } from './state.js';
@@ -24,11 +25,21 @@ export interface SpendKey {
   nullifyingKey: Hex;
 }
 
+/** What a sync needs of a key: its public key and nullifying key, which find and follow what it owns but spend none of
+ * it. */
+export type Owner = Pick<SpendKey, 'publicKey' | 'nullifyingKey'>;
+
 export interface Ctx {
   network: Network;
-  seed: Uint8Array;
+  /** The root of every key. Opened with a function for it, held only while something needs it; otherwise always. */
+  seed: Uint8Array | null;
+  /** The owners derived while the seed was held, by key: the wallet's own (`''`) and each receive code's. */
+  owners: Map<string, Owner>;
   address: Hex;
-  walletClient: WalletClient;
+  /** The account that holds the public funds, and signs for them. */
+  account: Account;
+  /** The user's wallet, when it is what signs and sends rather than an account of the app's own (`walletOn`). */
+  walletClient: WalletClient | null;
   storage: CanisterClient;
   view: ViewKey;
   chains: ChainCtx[];
@@ -47,20 +58,36 @@ export interface CodeId {
   index: number;
 }
 
+const idOf = (code?: CodeId) => (code ? `${code.chainId}:${code.tokenId}:${code.index}` : '');
+
+/** The seed, which the wallet holds whenever it does what needs it. */
+export function seedOf(ctx: Ctx): Uint8Array {
+  if (!ctx.seed) throw new Error('the wallet does not hold its seed now');
+  return ctx.seed;
+}
+
 /** The key that owns this seed's notes and deposits on every chain and token, or with `code`, the notes paid to that
- * receive code. */
+ * receive code. Its owner is kept for when the seed is not held. */
 export function spendKey(ctx: Ctx, code?: CodeId): SpendKey {
-  let bySeed = keys.get(ctx.seed);
-  if (!bySeed) keys.set(ctx.seed, (bySeed = new Map<string, SpendKey>()));
-  const id = code ? `${code.chainId}:${code.tokenId}:${code.index}` : '';
+  const seed = seedOf(ctx);
+  let bySeed = keys.get(seed);
+  if (!bySeed) keys.set(seed, (bySeed = new Map<string, SpendKey>()));
+  const id = idOf(code);
   let key = bySeed.get(id);
   if (!key) {
-    key = (code ? core.codeKey(ctx.seed, code.chainId, code.tokenId, code.index) : core.spendKey(ctx.seed)) as SpendKey;
+    key = (code ? core.codeSpendKey(seed, code.chainId, code.tokenId, code.index) : core.spendKey(seed)) as SpendKey;
     bySeed.set(id, key);
   }
+  if (!ctx.owners.has(id)) ctx.owners.set(id, { publicKey: key.publicKey, nullifyingKey: key.nullifyingKey });
   return key;
 }
 
+/** `spendKey`'s owner: derived before, or now if the seed is held; null if neither. The wallet's own is derived as it
+ * opens. */
+export function owner(ctx: Ctx, code?: CodeId): Owner | null {
+  return ctx.owners.get(idOf(code)) ?? (ctx.seed ? spendKey(ctx, code) : null);
+}
+
 export function chainCtx(ctx: Ctx, chainId: bigint): ChainCtx {
   const c = ctx.chains.find((c) => c.config.chainId === chainId);
   if (!c) throw new Error(`chain ${chainId} is not in this network`);
@@ -73,6 +100,19 @@ export function chainState(ctx: Ctx, chainId: bigint): ChainState {
   return s;
 }
 
+/** `wc` on `chainId`, switched there first: a browser wallet is on one chain at a time. */
+export async function switched(wc: WalletClient, chainId: bigint): Promise<WalletClient> {
+  if ((await wc.getChainId()) !== Number(chainId)) await guard(wc.switchChain({ id: Number(chainId) }));
+  return wc;
+}
+
+/** The client that sends the account's transactions on `chainId`: the user's wallet, switched to the chain, or the
+ * app's own account, through the chain's RPC. */
+export async function walletOn(ctx: Ctx, chainId: bigint): Promise<WalletClient> {
+  if (ctx.walletClient) return switched(ctx.walletClient, chainId);
+  return createWalletClient({ account: ctx.account, transport: http(chainCtx(ctx, chainId).config.rpcUrl) });
+}
+
 /** Waits until the wallet's own node has a transaction mined on ours too: the wallet simulates the next one there, and
  * where blocks are fast that node lags ours now and then, so the next one would show as reverting. A wallet that does
  * not answer is not waited on. */

package/src/core.ts

@@ -26,27 +26,17 @@ export interface Burn {
   address: Address;
 }
 
-/** A seed's `index`-th burn address of a token, with its salt: about 2^16 hashes, up to tens of seconds on a phone.
- * Searched off the main thread (a Web Worker in a browser, a worker thread in Node), so that the app stays
- * responsive; `signal` stops the search. */
+/** 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. */
 export const burnAddress = (
-  seed: Uint8Array,
+  burnKey: Uint8Array,
   chainId: bigint,
   tokenId: number,
   index: number,
-  signal?: AbortSignal,
-): Promise<Burn> => search({ seed, chainId, tokenId, index }, signal);
-
-/** The `k`-th burn address a point of sale holding `laneKey` makes for its owner's `publicKey` on a chain and token
- * (`keys::pos_burn`), with its salt: about 2^16 hashes too, searched the same way. */
-export const posBurnAddress = (
-  laneKey: Uint8Array,
-  chainId: bigint,
-  tokenId: number,
-  k: number,
   publicKey: Hex,
   signal?: AbortSignal,
-): Promise<Burn> => search({ laneKey, chainId, tokenId, k, publicKey }, signal);
+): Promise<Burn> => search({ burnKey, chainId, tokenId, index, publicKey }, 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
@@ -55,93 +45,295 @@ export const burnAddressFor = (chainId: bigint, publicKey: Hex, signal?: AbortSi
   search({ chainId, publicKey }, signal);
 
 export type BurnSearch =
-  | { seed: Uint8Array; chainId: bigint; tokenId: number; index: number }
-  | { laneKey: Uint8Array; chainId: bigint; tokenId: number; k: number; publicKey: Hex }
+  | { burnKey: Uint8Array; chainId: bigint; tokenId: number; index: number; publicKey: Hex }
   | { chainId: bigint; publicKey: Hex };
 
-/** A search, where it runs: a seed's index, or a point of sale's counter, derives its salts; someone else's key takes
- * random ones. */
-export function searchHere(s: BurnSearch): Burn {
-  if ('seed' in s) return core.burnAddress(s.seed, s.chainId, s.tokenId, s.index) as Burn;
-  if ('laneKey' in s) return core.posBurnAddress(s.laneKey, s.chainId, s.tokenId, s.k, s.publicKey) as Burn;
-  for (;;) {
-    const bytes = crypto.getRandomValues(new Uint8Array(32));
-    bytes[0] = bytes[0] & 0x1f; // below 2^253: a canonical field element
-    const salt = bytesToHex(bytes);
-    const address = core.burnAddressOf(s.chainId, s.publicKey, salt) as Address | undefined;
-    if (address) return { salt, address };
+/** Counters per block: about 20 ms of hashing on a laptop, a few times that on a phone. */
+const BLOCK = 512;
+
+/** A block of a search: its salt counters `from..=to`, or as many random salts for someone else's key. */
+export interface BurnBlock {
+  search: BurnSearch;
+  from: number;
+  to: number;
+}
+
+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);
+  }
+  return (burn as Burn | undefined) ?? null;
+}
+
+type Outcome = { burn: Burn } | { error: unknown };
+
+/** A search in progress, in blocks `0, 1, …` of `BLOCK` counters. From a burn key, the address is the first block's
+ * hit, so that every device derives the same one; for someone else's key, it is the first found. */
+export class Search {
+  readonly s: BurnSearch;
+  readonly #settle: (r: Outcome) => void;
+  /** From a burn key: the address is the first block's hit, not the first found. */
+  readonly #derived: boolean;
+  #settled = false;
+  #next = 0;
+  /** Blocks a worker took and died with, handed out again before any other. */
+  #dropped: number[] = [];
+  /** What the finished blocks from `#checked` on hold: every block below it holds none. */
+  #found = new Map<number, Burn | null>();
+  #checked = 0;
+  /** The lowest block known to hold an address: no block above it is needed. */
+  #lowest = Infinity;
+
+  constructor(s: BurnSearch, settle: (r: Outcome) => void) {
+    this.s = s;
+    this.#settle = settle;
+    this.#derived = 'burnKey' in s;
+  }
+
+  take(): number | undefined {
+    if (this.#settled) return undefined;
+    if (this.#dropped.length) return this.#dropped.shift();
+    return this.#next < this.#lowest ? this.#next++ : undefined;
+  }
+
+  drop(block: number) {
+    this.#dropped.unshift(block);
+  }
+
+  finish(block: number, burn: Burn | null) {
+    if (this.#settled) return;
+    if (!this.#derived) {
+      if (burn) this.#end({ burn });
+      return;
+    }
+    this.#found.set(block, burn);
+    if (burn) this.#lowest = Math.min(this.#lowest, block);
+    for (let found; (found = this.#found.get(this.#checked)) !== undefined; this.#checked++) {
+      if (found) return this.#end({ burn: found });
+      this.#found.delete(this.#checked);
+    }
+  }
+
+  fail(error: unknown) {
+    if (!this.#settled) this.#end({ error });
+  }
+
+  #end(r: Outcome) {
+    this.#settled = true;
+    this.#settle(r);
   }
 }
 
-export type BurnAnswer = { burn: Burn } | { error: string };
+/** A worker running one block at a time. */
+interface Thread {
+  job: Job | null;
+  /** Whether it ever answered: one that dies before it does never ran. */
+  answered: boolean;
+  send(b: BurnBlock): void;
+  stop(): void;
+  /** In Node, a thread keeps the process up while it works, and only then. */
+  busy(working: boolean): void;
+}
+
+type Job = { search: Search; block: number };
 
 /** What this module takes from Node's worker threads, typed here so that the package needs no Node types. */
-type NodeThread = new (
-  url: URL,
-  opts: { workerData: BurnSearch },
-) => {
-  once(event: 'message', f: (a: BurnAnswer) => void): void;
-  once(event: 'error', f: () => void): void;
+type NodeWorker = new (url: URL) => {
+  on(event: 'message', f: (a: BurnAnswer) => void): void;
+  on(event: 'error' | 'exit' | 'messageerror', f: () => void): void;
+  postMessage(b: BurnBlock): void;
+  ref(): void;
+  unref(): void;
   terminate(): Promise<number>;
 };
 
-/** Starts `s` in a worker, which hands `done` its answer, or null if it did not run; returns how to stop it, or null
- * where no worker starts. */
-// ponytail: a worker per search, each compiling the wasm; a pool of availableParallelism() workers if a server makes many
-async function spawn(s: BurnSearch, done: (a: BurnAnswer | null) => void): Promise<(() => void) | null> {
-  if (typeof Worker !== 'undefined') {
-    const worker = new Worker(new URL('./burnWorker.js', import.meta.url), { type: 'module' });
-    worker.onmessage = ({ data }: MessageEvent<BurnAnswer>) => done(data);
-    // a worker that does not start (a bundler that left it out) costs responsiveness only
-    worker.onerror = (e) => {
-      e.preventDefault();
-      done(null);
-    };
-    worker.postMessage(s);
-    return () => worker.terminate();
-  }
-  // variables, so that bundlers for the browser leave Node's module and a second copy of the worker alone
-  const [threads, file] = ['node:worker_threads', './burnWorker.js'];
-  const { Worker: Thread } = (await import(/* @vite-ignore */ threads).catch(() => ({}))) as { Worker?: NodeThread };
-  if (!Thread) return null;
-  const thread = new Thread(new URL(file, import.meta.url), { workerData: s });
-  thread.once('message', done);
-  thread.once('error', () => done(null)); // run from source, as tests are, there is no burnWorker.js
-  return () => void thread.terminate();
-}
+/** Searches in progress, oldest first: blocks go to the oldest that has one to hand out. */
+const searches: Search[] = [];
+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
+ * source): blocks run on this thread instead. */
+let here = false;
+let runningHere = false;
+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> {
-  signal?.throwIfAborted();
   await initCore();
+  signal?.throwIfAborted();
   return new Promise((resolve, reject) => {
-    let stop: (() => void) | null = null;
-    let settled = false;
-    const settle = (f: () => void) => {
-      if (settled) return;
-      settled = true;
-      stop?.();
+    const abort = () => one.fail(signal!.reason);
+    const one = new Search(s, (r) => {
       signal?.removeEventListener('abort', abort);
-      f();
-    };
-    const here = () =>
-      settle(() => {
-        try {
-          resolve(searchHere(s));
-        } catch (err) {
-          reject(err);
-        }
-      });
-    const abort = () => settle(() => reject(signal!.reason));
+      searches.splice(searches.indexOf(one), 1);
+      if ('burn' in r) resolve(r.burn);
+      else reject(r.error);
+    });
     signal?.addEventListener('abort', abort, { once: true });
-    spawn(s, (a) =>
-      a === null ? here() : settle(() => ('burn' in a ? resolve(a.burn) : reject(new Error(a.error)))),
-    ).then(
-      (stopIt) => {
-        if (!stopIt) here();
-        else if (settled) stopIt();
-        else stop = stopIt;
-      },
-      here, // a page whose CSP forbids workers
-    );
+    searches.push(one);
+    dispatch();
+  });
+}
+
+function nextJob(): Job | null {
+  for (const search of searches) {
+    const block = search.take();
+    if (block !== undefined) return { search, block };
+  }
+  return null;
+}
+
+const blockOf = ({ search, block }: Job): BurnBlock => ({
+  search: search.s,
+  from: block * BLOCK,
+  to: block * BLOCK + BLOCK - 1,
+});
+
+function deliver({ search, block }: Job, a: BurnAnswer) {
+  if ('error' in a) search.fail(new Error(a.error));
+  else search.finish(block, a.burn);
+}
+
+/** Hands blocks to idle threads, starting the pool if it is not running. */
+function dispatch() {
+  clearTimeout(idle);
+  if (here) return void runHere();
+  if (!threads) return void start();
+  for (const t of threads) {
+    if (t.job) continue;
+    const job = nextJob();
+    if (!job) break;
+    t.job = job;
+    t.busy(true);
+    t.send(blockOf(job));
+  }
+  if (!searches.length && threads.every((t) => !t.job)) {
+    idle = setTimeout(stop, IDLE_MS);
+    (idle as { unref?: () => void }).unref?.(); // a process need not stay up for it
+  }
+}
+
+async function start() {
+  if (starting) return;
+  starting = true;
+  const cores = globalThis.navigator?.hardwareConcurrency ?? 1;
+  // Node leaves a core to its event loop: a point of sale's server answers while it searches
+  const count = Math.max(1, Math.min(16, typeof Worker !== 'undefined' ? cores : cores - 1));
+  threads = await spawn(count).catch(() => []);
+  starting = false;
+  if (!threads.length) {
+    threads = null;
+    void runHere();
+  }
+  dispatch();
+}
+
+function stop() {
+  const stopped = threads ?? [];
+  threads = null;
+  for (const t of stopped) t.stop();
+}
+
+function answered(t: Thread, a: BurnAnswer) {
+  t.answered = true;
+  const job = t.job!;
+  t.job = null;
+  t.busy(false);
+  deliver(job, a);
+  dispatch();
+}
+
+function died(t: Thread) {
+  if (!threads?.includes(t)) return; // stopped, or already counted
+  threads = threads.filter((other) => other !== t);
+  if (t.job) t.job.search.drop(t.job.block);
+  if (!t.answered) {
+    // it never ran: neither will the others
+    for (const other of threads) if (other.job) other.job.search.drop(other.job.block);
+    stop();
+    void runHere();
+    return;
+  }
+  if (!threads.length) threads = null; // started again on the next dispatch
+  dispatch();
+}
+
+/** Starts `count` workers; none where there are no workers. */
+async function spawn(count: number): Promise<Thread[]> {
+  if (typeof Worker !== 'undefined') {
+    return Array.from({ length: count }, () => {
+      // this exact form is what bundlers (Vite, webpack) look for to emit the worker
+      const worker = new Worker(new URL('./burnWorker.js', import.meta.url), { type: 'module' });
+      const t: Thread = {
+        job: null,
+        answered: false,
+        send: (b) => worker.postMessage(b),
+        stop: () => worker.terminate(),
+        busy: () => {},
+      };
+      worker.onmessage = ({ data }: MessageEvent<BurnAnswer>) => answered(t, data);
+      worker.onerror = (e) => {
+        e.preventDefault();
+        died(t);
+      };
+      worker.onmessageerror = () => died(t);
+      return t;
+    });
+  }
+  // variables, so that bundlers for the browser leave Node's module and a second copy of the worker alone
+  const [threadsModule, file] = ['node:worker_threads', './burnWorker.js'];
+  const { Worker: ThreadWorker } = (await import(/* @vite-ignore */ threadsModule).catch(() => ({}))) as {
+    Worker?: NodeWorker;
+  };
+  if (!ThreadWorker) return [];
+  return Array.from({ length: count }, () => {
+    const worker = new ThreadWorker(new URL(file, import.meta.url));
+    worker.unref();
+    const t: Thread = {
+      job: null,
+      answered: false,
+      send: (b) => worker.postMessage(b),
+      stop: () => void worker.terminate(),
+      busy: (working) => (working ? worker.ref() : worker.unref()),
+    };
+    worker.on('message', (a) => answered(t, a));
+    // run from source, as tests are, there is no burnWorker.js: the thread exits before it answers
+    for (const event of ['error', 'exit', 'messageerror'] as const) worker.on(event, () => died(t));
+    return t;
   });
 }
+
+/** 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. */
+async function runHere() {
+  if (!here) {
+    here = true;
+    console.warn('zerc20: burn addresses are searched on the main thread, slower: no worker starts here');
+  }
+  if (runningHere) return;
+  runningHere = true;
+  let since = Date.now();
+  for (let job; (job = nextJob());) {
+    let a: BurnAnswer;
+    try {
+      a = { burn: runBlock(blockOf(job)) };
+    } catch (e) {
+      a = { error: e instanceof Error ? e.message : String(e) };
+    }
+    deliver(job, a);
+    if (Date.now() - since >= 100) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      since = Date.now();
+    }
+  }
+  runningHere = false;
+}

package/src/errors.ts

@@ -15,6 +15,8 @@ export type ErrorCode =
   | 'fee-too-high'
   /** 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. */
+  | 'recipient-refused'
   /** A contract account: it cannot sign the messages a wallet needs. */
   | 'unsupported-account'
   /** The user declined a signature or a transaction in their wallet. */