@zerc20/wallet-sdk 0.2.0 → 0.4.0

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

@@ -23,6 +23,8 @@ export type ErrorCode =
   | 'user-rejected'
   /** The wallet is open in another tab or window: close it there (`close()`), then open it here. */
   | 'wallet-in-use'
+  /** 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. */
   | 'wallet-closed'
   /** A server answered something that does not match the chain. */

package/src/index.ts

@@ -6,6 +6,7 @@
 //   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();
+//   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
@@ -23,7 +24,8 @@ 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 { viewKeyAccount } from './viewKey.js';
 export {
   type Activity,
   type Balance,
@@ -38,4 +40,5 @@ export {
   type OperationStatus,
   type PendingReason,
   Wallet,
+  type WatchOptions,
 } from './wallet.js';

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,

package/src/state.ts

@@ -21,10 +21,16 @@ export interface Position {
   spent: boolean;
   /** Looking for its nullifier, once final. */
   nullifier?: Watch;
+  /** Where among the nullifiers its own was seen past the final count: spent by a JoinSplit in a block, which a reorg
+   * may still drop. */
+  nullifiedAt?: number;
   /** Its block's time (ms), read with its commitment: the same on every device. Unset until read. */
   atMs?: number;
 }
 
+/** Neither spent nor spent by a JoinSplit in a block: one waits only to be final, so it is gone already. */
+export const unspent = (f: Position): boolean => !f.spent && f.nullifiedAt === undefined;
+
 /** What a payment, withdrawal or merge was, kept on its change or merged note in storage (the storage SDK's
  * `Receipt`): every device of the wallet shows it once that note lands. */
 export interface NoteReceipt {
@@ -51,6 +57,9 @@ export interface NoteRecord {
   atNs: bigint | null;
   /** For a note paid to a receive code, the code's index: the code's own key owns it. Otherwise the wallet's key does. */
   keyIndex?: number;
+  /** Paid to a receive code whose key was not derived when storage told of it (another device's code, while the seed
+   * was not held): its hash and watch wait for the seed, and nothing counts it until then. */
+  unkeyed?: true;
   /** Its hash under the key that owns it. */
   noteHash: Hex;
   /** Its tag, watched until it is found where no reorg moves it. */
@@ -183,22 +192,23 @@ export const emptyWalletState = (address: Hex): WalletState => ({
 });
 
 const TAG = new TextEncoder().encode('zerc20/wallet/state/v1');
-const keyOf = (seed: Uint8Array) => hkdf(sha256, seed, TAG, new TextEncoder().encode('wallet-state'), 32);
+/** The key the state is sealed under: the seed's, kept while the seed is not, so that a sync saves without it. */
+export const stateKey = (seed: Uint8Array) => hkdf(sha256, seed, TAG, new TextEncoder().encode('wallet-state'), 32);
 
-/** `state` as bytes only the seed opens: `nonce(12) ‖ ChaCha20-Poly1305(JSON)`. */
-export function sealState(seed: Uint8Array, state: WalletState): Uint8Array {
+/** `state` as bytes only the seed's `stateKey` opens: `nonce(12) ‖ ChaCha20-Poly1305(JSON)`. */
+export function sealState(key: Uint8Array, state: WalletState): Uint8Array {
   const json = JSON.stringify(state, (_, v: unknown) =>
     typeof v === 'bigint' ? { $n: v.toString() } : v instanceof Uint8Array ? { $b: bytesToHex(v) } : v,
   );
   const nonce = randomBytes(12);
-  const sealed = chacha20poly1305(keyOf(seed), nonce, TAG).encrypt(new TextEncoder().encode(json));
+  const sealed = chacha20poly1305(key, nonce, TAG).encrypt(new TextEncoder().encode(json));
   return new Uint8Array([...nonce, ...sealed]);
 }
 
-/** The state `sealState` wrote, or `null` if `bytes` is not one this seed opens. */
-export function openState(seed: Uint8Array, bytes: Uint8Array): WalletState | null {
+/** The state `sealState` wrote, or `null` if `bytes` is not one `key` opens. */
+export function openState(key: Uint8Array, bytes: Uint8Array): WalletState | null {
   try {
-    const plain = chacha20poly1305(keyOf(seed), bytes.subarray(0, 12), TAG).decrypt(bytes.subarray(12));
+    const plain = chacha20poly1305(key, bytes.subarray(0, 12), TAG).decrypt(bytes.subarray(12));
     const state = JSON.parse(new TextDecoder().decode(plain), (_, v: unknown) => {
       if (typeof v === 'object' && v !== null && '$n' in v) return BigInt(v.$n as string);
       if (typeof v === 'object' && v !== null && '$b' in v) return hexToBytes(v.$b as string);