@zerc20/wallet-sdk 0.1.0 → 0.3.0

package/src/index.ts

@@ -11,7 +11,7 @@
 // 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 Token, NATIVE, UNWRAP_INTENT } from './chain.js';
+export { Chain, type Referrer, type Token, MAX_REFERRAL_BPS, NATIVE, UNWRAP_INTENT } from './chain.js';
 export { type ErrorCode, WalletError } from './errors.js';
 export {
   type AttesterTrust,
@@ -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/services.ts

@@ -2,8 +2,8 @@
 // see the public statement and a witness sealed to their enclave, the transact-relayer a finished request, the
 // deposit-relayer a burn address.
 
-import { type Address, type Hex, bytesToHex, hexToBytes } from 'viem';
-import type { Chain } from './chain.js';
+import { type Address, type Hex, bytesToHex, hexToBytes, zeroAddress } from 'viem';
+import type { Chain, Referrer } from './chain.js';
 import { core } from './core.js';
 import { WalletError, fail } from './errors.js';
 import { type AttesterTrust, type ChainConfig, LOCAL_CHAIN_ID, type Network } from './network.js';
@@ -75,6 +75,8 @@ export async function attest(c: ChainConfig, statement: object, witness: string,
     if (typeof r.body !== 'string') return r.body.attestation;
     // the enclave restarted with a new key between the fetch and the request
     if (r.body.includes('fetch /attestation again') && attempt === 0) continue;
+    // a screening's verdict: asking again gets the same, and spends the notes' screenings for nothing
+    if (r.status === 403) return fail('recipient-refused', `attester: ${r.body}`);
     // a root its indexer has not derived yet is a 400 too, but one that passes
     const later = r.status !== 400 || r.body.includes('retry once');
     return fail(later ? 'unavailable' : 'invalid', `attester: ${r.body}`);
@@ -161,23 +163,32 @@ export async function proofOf(
   return r.body;
 }
 
-/** A deposit address that flushes whatever reaches it into `burnAddress`, less `fee` paid to `feeRecipient` each time;
- * refunds go to `refundAddress`. What the relayer says is checked against the factory: an address of its own would take
- * the funds, and the fee it names is the one the address takes. */
+/** A deposit address that flushes whatever reaches it into `burnAddress`, less `fee` paid to `feeRecipient` and the
+ * referrer's share of the rest each time; refunds go to `refundAddress`. What the relayer says is checked against the
+ * factory: an address of its own would take the funds, and the fee it names is the one the address takes. */
 export async function registerDeposit(
   chain: Chain,
   token: Address,
   burnAddress: Hex,
   refundAddress: Address,
+  referrer: Referrer = { address: zeroAddress, bps: 0 },
 ): Promise<{ depositAddress: Address; feeRecipient: Address; fee: bigint }> {
   const r = await post<{ depositAddress: Address; feeRecipient: Address; fee: Hex }>(
     `${chain.config.depositRelayer}/register`,
-    { token, burnAddress, refundAddress },
+    { token, burnAddress, refundAddress, referrer: referrer.address, referralBps: referrer.bps },
   );
   if (typeof r.body === 'string') return fail('unavailable', `deposit-relayer: ${r.body}`);
   const { depositAddress, feeRecipient } = r.body;
   const fee = BigInt(r.body.fee);
-  const expected = await chain.predictDepositAddress(token, burnAddress, refundAddress, feeRecipient, fee);
+  const expected = await chain.predictDepositAddress(
+    token,
+    burnAddress,
+    refundAddress,
+    feeRecipient,
+    fee,
+    referrer.address,
+    referrer.bps,
+  );
   if (depositAddress.toLowerCase() !== expected.toLowerCase())
     fail('indexer-mismatch', `the deposit relayer gave ${depositAddress}, not the factory's ${expected}`);
   return { depositAddress, feeRecipient, fee };

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);

package/src/sync.ts

@@ -9,6 +9,7 @@ import {
   type OwnReceipt,
   type Receipt,
   type SyncState,
+  burnKey,
   commit,
   emptyState,
   planBurnBlock,
@@ -16,12 +17,12 @@ import {
   refresh,
 } from '@zerc20/storage-sdk';
 import { type Hex, bytesToHex, hexToBytes, numberToHex, parseAbiItem } from 'viem';
-import type { Chain } from './chain.js';
-import { type ChainCtx, type Ctx, chainCtx, chainState, spendKey } from './context.js';
+import type { Chain, Token } from './chain.js';
+import { type ChainCtx, type Ctx, chainCtx, chainState, owner } from './context.js';
 import { burnAddress, core } from './core.js';
 import { type Hit, type Watch, scan } from './scan.js';
 import { type Asp, type AspStatus, type Indexer, PAGE } from './servers.js';
-import type { DepositRecord, NoteReceipt, NoteRecord, Sample } from './state.js';
+import type { DepositRecord, NoteReceipt, NoteRecord, Position, Sample } from './state.js';
 
 /** The ledger's log of each commitment, found by its index (`contracts/src/CommitmentLedger.sol`). */
 const committedEvent = parseAbiItem('event Committed(uint64 indexed index, uint256[4] fields)');
@@ -47,7 +48,7 @@ export function commitmentsAt(samples: Sample[], atMs: number): number {
 }
 
 /** A note's hash under the key that owns it (the wallet's, or with `keyIndex` a receive code's), and the watch for its
- * tag. */
+ * tag. Null while that key's owner is not derived. */
 function watchFor(
   ctx: Ctx,
   chainId: bigint,
@@ -57,8 +58,9 @@ function watchFor(
   keyIndex: number | undefined,
   from: number,
 ) {
-  const { publicKey } = spendKey(ctx, keyIndex === undefined ? undefined : { chainId, tokenId, index: keyIndex });
-  const noteHash = core.noteHash(chainId, publicKey, `0x${value.toString(16)}`, tokenId, salt) as Hex;
+  const key = owner(ctx, keyIndex === undefined ? undefined : { chainId, tokenId, index: keyIndex });
+  if (!key) return null;
+  const noteHash = core.noteHash(chainId, key.publicKey, `0x${value.toString(16)}`, tokenId, salt) as Hex;
   return { noteHash, watch: { key: numberToHex(core.noteTag(tokenId, noteHash), { size: 4 }), from, scannedTo: from } };
 }
 
@@ -214,7 +216,7 @@ export function takeDeposit(ctx: Ctx, deposit: Deposit, payer: Uint8Array, token
   if (!tokens.get(chainId)?.includes(tokenId)) return;
   const salt = hex32(deposit.burnSalt);
   if (ctx.state.deposits.some((d) => d.chainId === chainId && d.salt === salt)) return;
-  const address = core.burnAddressOf(chainId, spendKey(ctx).publicKey, salt) as Hex | undefined;
+  const address = core.burnAddressOf(chainId, owner(ctx)!.publicKey, salt) as Hex | undefined;
   if (!address) return;
   const atMs = Number(deposit.atNs / 1_000_000n);
   // storage held it before the payer's transfer; a day of margin covers clock skew
@@ -246,7 +248,7 @@ function takeBurnBlock(
   tokens: Map<bigint, number[]>,
 ): void {
   if (!tokens.has(b.chainId)) return;
-  const { publicKey } = spendKey(ctx);
+  const { publicKey } = owner(ctx)!;
   const atMs = Number(b.atNs / 1_000_000n);
   const from = commitmentsAt(chainState(ctx, b.chainId).samples, atMs - DAY_MS);
   b.salts.forEach((bytes, i) => {
@@ -285,8 +287,22 @@ export function unusedBurn(ctx: Ctx, chainId: bigint, tokenId: number): DepositR
   return best;
 }
 
+/** The index of the next burn address of a token to record: past every one recorded, here or by another device. */
+function toRecord(ctx: Ctx, chainId: bigint, tokenId: number): number {
+  let index = chainState(ctx, chainId).burnNext[tokenId] ?? 0;
+  for (const d of ctx.state.deposits) {
+    if (d.chainId === chainId && d.tokenId === tokenId && !d.managed) index = Math.max(index, d.burnIndex + 1);
+  }
+  return index;
+}
+
+/** The index of the burn address of a token that is handed out next, and so of the receive code: the one recorded
+ * ahead, or else the next to record. */
+export const nextBurn = (ctx: Ctx, chainId: bigint, tokenId: number): number =>
+  unusedBurn(ctx, chainId, tokenId)?.burnIndex ?? toRecord(ctx, chainId, tokenId);
+
 /** Records this wallet's next burn address of a token in storage (a burn block of one), then watches it. Every device
- * of the wallet, and a restore, then watches it too and never hands it out again. About 2^16 hashes. */
+ * of the wallet, and a restore, then watches it too and never hands it out again. About 2^16 hashes; needs no seed. */
 export async function recordBurn(
   ctx: Ctx,
   chainId: bigint,
@@ -294,11 +310,9 @@ export async function recordBurn(
   tokens: Map<bigint, number[]>,
   signal?: AbortSignal,
 ): Promise<DepositRecord> {
-  let index = chainState(ctx, chainId).burnNext[tokenId] ?? 0;
-  for (const d of ctx.state.deposits) {
-    if (d.chainId === chainId && d.tokenId === tokenId && !d.managed) index = Math.max(index, d.burnIndex + 1);
-  }
-  const { salt, address } = await burnAddress(ctx.seed, chainId, tokenId, index, signal);
+  const index = toRecord(ctx, chainId, tokenId);
+  const key = burnKey(ctx.view.seed);
+  const { salt, address } = await burnAddress(key, chainId, tokenId, index, owner(ctx)!.publicKey, signal);
   const { commitmentsFinal: from } = await chainCtx(ctx, chainId).indexer.status();
   const block = { chainId, tokenId, first: index, salts: [hexToBytes(salt)] };
   const result = await commit(ctx.storage, ctx.view, storageState(ctx), (s) => planBurnBlock(ctx.view, s, block));
@@ -370,11 +384,43 @@ function upsertNote(ctx: Ctx, a: NewRecord, note: Note, tokens: Map<bigint, numb
     peer,
     atNs,
     ...(keyIndex === undefined ? {} : { keyIndex }),
-    ...watchFor(ctx, chainId, tokenId, big(value), salt, keyIndex, from),
+    // storage tells of a note once: one whose key waits for the seed is kept, not dropped
+    ...(watchFor(ctx, chainId, tokenId, big(value), salt, keyIndex, from) ?? {
+      unkeyed: true,
+      noteHash: '0x',
+      watch: null,
+    }),
     found: [],
   });
 }
 
+/** Receive codes of each token whose keys are derived while the seed is held, to hand out while it is not. */
+export const CODES_AHEAD = 4;
+
+/** With the seed held, each owner not derived yet: the wallet's own, each of its burn addresses' (a receive code each),
+ * the next `CODES_AHEAD` codes' of each of `tokens`, and each note's key's; and the watch of each note that waited for
+ * its key. */
+export function keyAll(ctx: Ctx, tokens: Token[]): void {
+  owner(ctx);
+  // ponytail: one derivation per own burn address as the wallet opens; keep owners in the saved state if wallets grow
+  // to thousands of them
+  for (const d of ctx.state.deposits) {
+    if (d.burnIndex >= 0 && !d.managed) owner(ctx, { chainId: d.chainId, tokenId: d.tokenId, index: d.burnIndex });
+  }
+  for (const { chainId, tokenId } of tokens) {
+    const next = nextBurn(ctx, chainId, tokenId);
+    for (let index = next; index < next + CODES_AHEAD; index++) owner(ctx, { chainId, tokenId, index });
+  }
+  for (const n of ctx.state.notes) {
+    if (n.keyIndex === undefined) continue;
+    owner(ctx, { chainId: n.chainId, tokenId: n.tokenId, index: n.keyIndex });
+    if (!n.unkeyed) continue;
+    const from = commitmentsAt(chainState(ctx, n.chainId).samples, Number((n.atNs ?? 0n) / 1_000_000n) - DAY_MS);
+    Object.assign(n, watchFor(ctx, n.chainId, n.tokenId, n.value, n.salt, n.keyIndex, from));
+    delete n.unkeyed;
+  }
+}
+
 /** Whether something was started or announced recently enough to look past the final count for it. */
 function waiting(ctx: Ctx, chainId: bigint, now: number): boolean {
   const recent = (ms: number | null) => ms !== null && now - ms < WAIT_MS;
@@ -384,7 +430,12 @@ function waiting(ctx: Ctx, chainId: bigint, now: number): boolean {
       (d) => d.chainId === chainId && d.found.length === 0 && recent(d.createdMs),
     ) ||
     ctx.state.notes.some(
-      (n) => n.chainId === chainId && n.found.length === 0 && n.atNs !== null && recent(Number(n.atNs / 1_000_000n)),
+      (n) =>
+        n.chainId === chainId &&
+        !n.unkeyed &&
+        n.found.length === 0 &&
+        n.atNs !== null &&
+        recent(Number(n.atNs / 1_000_000n)),
     )
   );
 }
@@ -476,12 +527,13 @@ async function syncChain(ctx: Ctx, c: ChainCtx, tokens: number[]): Promise<void>
     ...deposits.flatMap((d) => d.found.map((f) => ({ f, code: undefined }))),
   ].filter(({ f }) => !f.tentative && !f.spent);
   for (const { f, code } of owned) {
-    if (f.nullifier) continue;
-    const nullifier = core.nullifier(chainId, BigInt(f.index), spendKey(ctx, code).nullifyingKey);
+    const key = owner(ctx, code);
+    if (f.nullifier || !key) continue; // without its owner: looked for once the seed is held
+    const nullifier = core.nullifier(chainId, BigInt(f.index), key.nullifyingKey);
     const from = await nullifierFrom(f.index);
     f.nullifier = { key: nullifier.slice(0, 18) as Hex, from, scannedTo: from };
   }
-  const nullifierWatches = owned.map(({ f }) => f.nullifier!);
+  const nullifierWatches = owned.flatMap(({ f }) => (f.nullifier ? [f.nullifier] : []));
   const spent = await scan(
     nullifierWatches,
     8,
@@ -489,13 +541,32 @@ async function syncChain(ctx: Ctx, c: ChainCtx, tokens: number[]): Promise<void>
     status.nullifiersFinal,
     live === status.commitments ? status.nullifiers : status.nullifiersFinal,
   );
-  const byNullifier = new Map(owned.map(({ f }) => [f.nullifier!.key, f]));
-  for (const hit of spent) {
+  applySpends(
+    [...notes, ...deposits].flatMap((r): Position[] => r.found),
+    spent,
+  );
+}
+
+/** Records nullifier hits on the positions they spend: a final one spends it, one past the final count marks it
+ * `nullifiedAt`, until the final nullifiers pass that place without it (a reorg dropped that JoinSplit, which shows up
+ * again where it went). Every device sees an input gone once its JoinSplit is in a block, as the one that sent it does. */
+export function applySpends(positions: Position[], hits: Hit[]): void {
+  const byNullifier = new Map(positions.filter((f) => f.nullifier).map((f) => [f.nullifier!.key, f]));
+  for (const hit of hits) {
     const f = byNullifier.get(hit.key);
-    if (f && !hit.tentative) f.spent = true;
+    if (!f) continue;
+    if (hit.tentative) f.nullifiedAt = hit.position;
+    else f.spent = true;
+  }
+  for (const f of positions) {
+    // a spent position needs no more watching
+    if (f.spent) {
+      delete f.nullifier;
+      delete f.nullifiedAt;
+    } else if (f.nullifier && f.nullifiedAt !== undefined && f.nullifiedAt < f.nullifier.scannedTo) {
+      delete f.nullifiedAt;
+    }
   }
-  // a spent position needs no more watching
-  for (const r of [...notes, ...deposits]) for (const f of r.found) if (f.spent) delete f.nullifier;
 }
 
 /** The four fields of the commitment at an index, read from its page of commitments, each page once per reader: `null`