@zerc20/wallet-sdk 0.2.0 → 0.4.0

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,45 @@ 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. Without it, the watch of each note whose key was derived before. */
+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);
+    const watched = watchFor(ctx, n.chainId, n.tokenId, n.value, n.salt, n.keyIndex, from);
+    if (!watched) continue; // still waits for the seed
+    Object.assign(n, watched);
+    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 +432,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 +529,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 +543,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`

package/src/viewKey.ts

@@ -0,0 +1,49 @@
+// A view key as text: what `Wallet.watch` follows an account with, spending nothing.
+
+import { bech32m } from '@scure/base';
+import type { ViewKey } from '@zerc20/storage-sdk';
+import { type Address, type Hex, bytesToHex, concat, getAddress, hexToBytes } from 'viem';
+import type { Owner } from './context.js';
+import { core } from './core.js';
+
+const PREFIX = 'zerc20view';
+
+/** `view` and the wallet's own `owner` as checksummed text (bech32m, `zerc20view1…`): `address(20) ‖ view seed(32) ‖
+ * auth key hash(32) ‖ nullifying key(32)`. The public key is left for the holder to make from the last two, so that a
+ * nullifying key that is not the account's makes a public key that is not either. */
+export function encodeViewKey(view: ViewKey, owner: Owner): string {
+  const bytes = concat([view.address, view.seed, hexToBytes(owner.authKeyHash), hexToBytes(owner.nullifyingKey)]);
+  return bech32m.encode(PREFIX, bech32m.toWords(bytes), false);
+}
+
+function bytesOf(text: string): Uint8Array | null {
+  try {
+    const { prefix, bytes } = bech32m.decodeToBytes(text.trim(), false);
+    return prefix === PREFIX && bytes.length === 116 ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The account `text` is a view key of, or `null` if it is not one: to tell a key apart before it is opened. */
+export function viewKeyAccount(text: string): Address | null {
+  const bytes = bytesOf(text);
+  return bytes && getAddress(bytesToHex(bytes.subarray(0, 20)));
+}
+
+/** The view key and owner `text` holds, or `null` for anything else. Needs `initCore`. */
+export function decodeViewKey(text: string): { view: ViewKey; owner: Owner } | null {
+  const bytes = bytesOf(text);
+  if (!bytes) return null;
+  const authKeyHash = bytesToHex(bytes.subarray(52, 84));
+  const nullifyingKey = bytesToHex(bytes.subarray(84));
+  try {
+    const publicKey = core.publicKey(authKeyHash, nullifyingKey) as Hex;
+    return {
+      view: { address: bytes.slice(0, 20), seed: bytes.slice(20, 52) },
+      owner: { authKeyHash, publicKey, nullifyingKey },
+    };
+  } catch {
+    return null; // a value that is not a field element
+  }
+}