@zerc20/wallet-sdk 0.2.0 → 0.3.0

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/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/index.ts

@@ -23,7 +23,7 @@ export {
   networkFromJson,
 } from './network.js';
 export { type Payment, PointOfSale, type PosToken, type Sale, type SaleStatus } from './pos.js';
-export { seedFromSignature } from './seed.js';
+export { accountKey, seedFromSignature } from './seed.js';
 export {
   type Activity,
   type Balance,

package/src/pos.ts

@@ -16,7 +16,7 @@ import {
   zeroAddress,
 } from 'viem';
 import { Chain, type Token } from './chain.js';
-import { core, initCore, posBurnAddress } from './core.js';
+import { burnAddress, core, initCore } from './core.js';
 import { fail } from './errors.js';
 import { type ChainConfig, type Network, checkNetwork } from './network.js';
 import { scan } from './scan.js';
@@ -346,7 +346,7 @@ export class PointOfSale {
       const laneKey = hexToBytes(c.laneKey);
       const burns = await Promise.all(
         Array.from({ length: BURN_BLOCK }, (_, i) =>
-          posBurnAddress(laneKey, token.chainId, token.tokenId, k + i, c.publicKey),
+          burnAddress(laneKey, token.chainId, token.tokenId, k + i, c.publicKey),
         ),
       );
       const block = {

package/src/rageExit.ts

@@ -4,7 +4,7 @@
 
 import { type Address, type Hex, decodeEventLog, numberToHex, parseAbi } from 'viem';
 import { depositAddressAbi, ledgerAbi, verifierAbi } from './chain.js';
-import { type ChainCtx, type Ctx, chainCtx, spendKey, walletSees } from './context.js';
+import { type ChainCtx, type Ctx, chainCtx, spendKey, walletOn, walletSees } from './context.js';
 import { core } from './core.js';
 import { fail, guard } from './errors.js';
 import { prove } from './prove.js';
@@ -85,9 +85,8 @@ export async function rageExit(ctx: Ctx, record: DepositRecord, index: number):
   const c = chainCtx(ctx, record.chainId);
   const found = record.found.find((f) => f.index === index) ?? fail('invalid', `no deposit at ${index}`);
   if (found.spent) fail('invalid', 'the deposit is already spent');
-  const wc = ctx.walletClient;
-  const account = wc.account!;
-  if ((await wc.getChainId()) !== Number(record.chainId)) await guard(wc.switchChain({ id: Number(record.chainId) }));
+  const wc = await walletOn(ctx, record.chainId);
+  const account = ctx.account;
   const hashes: Hex[] = [];
   const send: Sender = async (address, abi, functionName, args) => {
     const hash = await guard(

package/src/seed.ts

@@ -1,12 +1,24 @@
 // A seed from the wallet's own signature, so the account alone restores it. It holds only for wallets whose
 // signatures are deterministic (RFC 6979, as MetaMask's and hardware wallets' are): keep the fingerprint, and if a
 // later derivation gives another one, the wallet signs differently each time and the seed must be backed up itself.
-// Anything that gets the user to sign the same message gets the seed.
+// Anything that gets the user to sign the same message gets the seed. Or the other way round, an account from a seed:
+// for an app whose seed comes from elsewhere (a passkey), and that has no wallet of its own.
 
 import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { entropyToMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
 import { type Hex, type WalletClient, bytesToHex, hexToBytes, keccak256 } from 'viem';
+import { mnemonicToAccount } from 'viem/accounts';
 import { fail, guard } from './errors.js';
 
+/** The private key of the account a seed's own app holds its public funds in: the first account of the seed's recovery
+ * phrase (the seed as 24 BIP-39 words) by the standard derivation, BIP-44's m/44'/60'/0'/0/0. Any wallet given the
+ * phrase opens the same account, so its public funds stay reachable without this app. */
+export function accountKey(seed: Uint8Array): Hex {
+  const key = mnemonicToAccount(entropyToMnemonic(seed, wordlist)).getHdKey().privateKey;
+  return bytesToHex(key ?? fail('invalid', 'the seed derives no account key'));
+}
+
 const message = (address: Hex) =>
   [
     'zERC20 wallet seed',

package/src/spend.ts

@@ -21,7 +21,7 @@ import {
   parseAbiParameters,
 } from 'viem';
 import { UNWRAP_INTENT } from './chain.js';
-import { type Ctx, chainCtx, spendKey } from './context.js';
+import { type Ctx, chainCtx, owner, spendKey } from './context.js';
 import { core } from './core.js';
 import { fail } from './errors.js';
 import { prove } from './prove.js';
@@ -36,7 +36,7 @@ import {
   relayerFees,
   requestProof,
 } from './services.js';
-import type { NoteRecord, OperationRecord, Position, SpendOperation } from './state.js';
+import { type NoteRecord, type OperationRecord, type Position, type SpendOperation, unspent } from './state.js';
 import { commitmentsAt, noteReceipt, storageState, takeRefresh, tokenIds } from './sync.js';
 import { aspPath, aspPaths, commitmentPath, commitmentPaths } from './tree.js';
 
@@ -141,7 +141,7 @@ export function coins(ctx: Ctx, chainId: bigint, tokenId: number, rootSize: numb
   );
   // final or not: once a proved root the chain accepts covers it, a reorg that moves it takes that root back too, and
   // a JoinSplit against it then fails on chain, which frees its inputs
-  const usable = (f: { index: number; spent: boolean }) => !f.spent && f.index < rootSize && !locked.has(f.index);
+  const usable = (f: Position) => unspent(f) && f.index < rootSize && !locked.has(f.index);
   const notes = ctx.state.notes
     .filter((n) => n.chainId === chainId && n.tokenId === tokenId)
     .flatMap((n) =>
@@ -168,7 +168,7 @@ export function coins(ctx: Ctx, chainId: bigint, tokenId: number, rootSize: numb
 /** Whether any of `tokenId`'s notes or deposits is on chain but not spendable yet: not final or confirmed, not
  * screened, or not under the proved root of size `rootSize`. A note only announced does not count: it may never land. */
 export function settling(ctx: Ctx, chainId: bigint, tokenId: number, rootSize: number): boolean {
-  const waiting = (f: { index: number; spent: boolean }) => !f.spent && f.index >= rootSize;
+  const waiting = (f: Position) => unspent(f) && f.index >= rootSize;
   // a zero-value change is never spendable: it is there to carry its payment's receipt
   const notes = ctx.state.notes.filter((n) => n.chainId === chainId && n.tokenId === tokenId && n.value > 0n);
   const deposits = ctx.state.deposits.filter((d) => d.chainId === chainId);
@@ -305,7 +305,7 @@ export async function planStep(ctx: Ctx, op: SpendOperation): Promise<Step | Mer
   const all = coins(ctx, op.chainId, op.tokenId, root?.size ?? 0);
   const { relayer, publicKey: relayerKey, fees } = await relayerFees(c.config);
   const fee = fees.get(op.tokenId)?.fee ?? fail('unavailable', `the relayer does not relay token ${op.tokenId}`);
-  const self = spendKey(ctx).publicKey;
+  const self = owner(ctx)!.publicKey;
   const out = (publicKey: Hex, value: bigint, role: Output['role'], salt: Hex = fresh()): Output => ({
     publicKey,
     value,