@zerc20/wallet-sdk 0.2.0 → 0.3.0

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`