@zerc20/wallet-sdk 0.4.0 → 0.6.0

package/src/spend.ts

@@ -6,9 +6,12 @@
 // and deposits into one note to self, proved by the merge prover (a wallet cannot: its key is 6.3 GB). More take
 // another merge, once a root is over the first one's note.
 //
-// A relayed JoinSplit or merge is done once its first input's nullifier is final, as sync sees it: the relayer's
-// answer alone could be a lie, or a reorg could drop the transaction. Only one that cannot land fails, which frees its
-// inputs: one whose nullifier is nowhere on chain, after it kept reverting.
+// A relayed JoinSplit or merge is done once its change (a merge's note) is final where this wallet expects it, as sync
+// sees it: only its own transaction puts that note there, as its salt is fresh and the proof binds it to the inputs'
+// nullifiers. The relayer's answer alone could be a lie, a reorg could drop the transaction, and a spent input alone
+// could be another device's doing: each device of a wallet locks its inputs in its own state. Only one that cannot
+// land fails, which frees its inputs: one that kept reverting with no input spent, or one whose input another
+// transaction spent.
 
 import { type Receipt, type Recipient, commit, decodeCode, planPayCode, planSelf, planSend } from '@zerc20/storage-sdk';
 import {
@@ -26,16 +29,8 @@ import { core } from './core.js';
 import { fail } from './errors.js';
 import { prove } from './prove.js';
 import { scan } from './scan.js';
-import {
-  type Relayed,
-  RelayUnknown,
-  attest,
-  proofOf,
-  relay,
-  relayMerge,
-  relayerFees,
-  requestProof,
-} from './services.js';
+import type { Indexer } from './servers.js';
+import { attest, proofOf, relay, relayMerge, relayerFees, requestProof } from './services.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';
@@ -74,9 +69,16 @@ export interface Step {
   request?: object;
   /** Reverts with no sign of it on chain: proved again with the same outputs a few times, then failed. */
   attempts: number;
-  /** Once relayed: the indexer's nullifier count just after. Final nullifiers past it, and the input's still not among
-   * them, means a reorg dropped the transaction. */
+  /** Once relayed: the block the relayer saw it mined in. */
+  relayedBlock?: number;
+  /** The indexer's nullifier count once it is past that block, or just after a relay that reverted on an input spent
+   * already: that leaves the step `attested`, not relayed again until its change tells whose transaction spent it.
+   * Final nullifiers past it, and its inputs still not among them, means whatever spent them is gone: a reorg dropped
+   * it, or the relayer never sent it. */
   relayedAt?: number;
+  /** The final commitment count once an input is seen spent. Final commitments past it, and the change still not among
+   * them, means another transaction spent the input, and this step can never land. */
+  spentAt?: number;
 }
 
 /** The most inputs one merge spends: the attester takes requests up to 2 MB, at 8 KiB of sealed witness per input
@@ -100,7 +102,13 @@ export interface MergeStep {
   /** Refused by the prover, or reverting with no sign of it on chain: built again with the same output a few times,
    * then failed. */
   attempts: number;
+  /** Built again after a relay of it reverted, which counts in `attempts` beside the prover's refusals: the request
+   * out may still land, so the step is not cancelled. */
+  sent?: true;
+  /** As a JoinSplit's, with `proved` where a JoinSplit is `attested`. */
+  relayedBlock?: number;
   relayedAt?: number;
+  spentAt?: number;
 }
 
 /** Where a send or withdrawal goes; `self` merges the wallet's own notes and nothing leaves. */
@@ -249,14 +257,20 @@ export function payWith(all: Coin[], need: bigint, fee: bigint, onTheWay: boolea
   return fail('insufficient-funds', `${need} is more than the balance`);
 }
 
-/** The smallest public withdrawal that still pays `net` after the protocol's cut. */
+/** The smallest public withdrawal that still pays `net` after the protocol's cut. The cut is a rate of the whole
+ * withdrawal, rounded down, and the rate read off one withdrawal (`fee / gross`) is at most its tier's: the smallest
+ * gross that pays `net` at that rate is never more than the answer within the tier, so a read or two settles it.
+ * ponytail: where a lower tier's bound lies between two reads, that bound may already pay `net`, a little less than
+ * the gross this returns; a getter for the schedule's tiers would find it. */
 export async function grossed(ctx: Ctx, chainId: bigint, tokenId: number, net: bigint): Promise<bigint> {
   const chain = chainCtx(ctx, chainId).chain;
   let gross = net;
-  for (let i = 0; i < 8; i++) {
+  // each read moves on by a unit at least, and a few settle each tier a withdrawal crosses
+  for (let i = 0; i < 64; i++) {
     const paid = gross - (await chain.withdrawFee(tokenId, gross));
     if (paid >= net) return gross;
-    gross += net - paid;
+    if (paid <= 0n) break;
+    gross = ((net - 1n) * gross) / paid + 1n;
   }
   return fail('unavailable', 'the withdrawal fee schedule does not settle');
 }
@@ -276,10 +290,16 @@ export async function withdrawalOf(
   return { withdrawn, protocol: withdrawn - net };
 }
 
+/** The rate, in basis points, of a protocol's `cut` out of a withdrawal of `gross`. The cut is rounded down, so this is
+ * exact once `gross` is 10,000 base units or more. */
+export const bpsOf = (cut: bigint, gross: bigint): number =>
+  gross === 0n ? 0 : Number((cut * 10_000n + gross - 1n) / gross);
+
 /** The most a payment out of `all` pays its recipient, the relayer's `fee` and the protocol's cut on top
  * (`withdrawalOf`): a withdrawal of what the relayer leaves, less the cut on it, or a private payment of what the
  * relayer's grossed fee leaves. Coins one JoinSplit cannot spend together (`pick`) are merged first, each merge
- * paying the relayer's grossed fee, as a consolidation's quote does. */
+ * paying the relayer's grossed fee, as a consolidation's quote does. `fee` is all the fees take of `all`; where they
+ * take it all, what they would be with nothing left to pay. */
 export async function maxPayment(
   ctx: Ctx,
   chainId: bigint,
@@ -287,13 +307,16 @@ export async function maxPayment(
   isPublic: boolean,
   all: Coin[],
   fee: bigint,
-): Promise<bigint> {
+): Promise<{ amount: bigint; fee: bigint; merges: number }> {
   const whole = all.length < 2 || (all.length === 2 && all.some((c) => c.kind === 'note'));
-  const merges = whole ? 0n : BigInt(roundsToMerge(all)) * (await grossed(ctx, chainId, tokenId, fee));
-  const total = all.reduce((s, c) => s + c.value, 0n) - merges;
-  const left = total - (isPublic ? fee : await grossed(ctx, chainId, tokenId, fee));
-  if (left <= 0n) return 0n;
-  return isPublic ? left - (await chainCtx(ctx, chainId).chain.withdrawFee(tokenId, left)) : left;
+  const merges = whole ? 0 : roundsToMerge(all);
+  const gross = !isPublic || merges > 0 ? await grossed(ctx, chainId, tokenId, fee) : fee;
+  const fees = BigInt(merges) * gross + (isPublic ? fee : gross);
+  const total = all.reduce((s, c) => s + c.value, 0n);
+  const left = total - fees;
+  if (left <= 0n) return { amount: 0n, fee: fees, merges };
+  const amount = isPublic ? left - (await chainCtx(ctx, chainId).chain.withdrawFee(tokenId, left)) : left;
+  return { amount, fee: total - amount, merges };
 }
 
 /** Plans the next step of `op`: a payment's only JoinSplit (or throws why there is none), or a consolidation's next
@@ -628,27 +651,81 @@ const positionsAt = (ctx: Ctx, chainId: bigint, index: number): Position[] =>
 const positionOf = (ctx: Ctx, chainId: bigint, index: number): Position | undefined =>
   positionsAt(ctx, chainId, index).find((f) => !f.tentative);
 
-/** Whether the step's first input is spent on chain: among the final nullifiers (as sync last saw them), or among the
- * newer ones. Nothing but the step spends a locked input (rage exit refuses one, and a wallet is open in one tab), so
- * a spent input is the step landing. Reads the pages everyone polls, never asks about the nullifier. */
-async function inputSpent(ctx: Ctx, op: SpendOperation, step: { inputs: Coin[] }): Promise<boolean> {
-  const f = positionOf(ctx, op.chainId, step.inputs[0].index);
-  if (f?.spent) return true;
-  if (!f?.nullifier) return false;
+/** Whether any of the step's inputs is spent on chain: among the final nullifiers (as sync last saw them), or among
+ * the newer ones. Reads the pages everyone polls, never asks about a nullifier. */
+async function inputsSpent(ctx: Ctx, op: SpendOperation, step: { inputs: Coin[] }): Promise<boolean> {
+  const inputs = step.inputs.map((coin) => positionOf(ctx, op.chainId, coin.index));
+  if (inputs.some((f) => f?.spent)) return true;
+  // copies: sync alone moves the watches, over final entries
+  const watches = inputs.flatMap((f) => (f?.nullifier ? [{ ...f.nullifier }] : []));
+  if (watches.length === 0) return false;
   const c = chainCtx(ctx, op.chainId);
   const { nullifiers } = await c.indexer.status();
-  // a copy: sync alone moves the watch, over final entries
-  const watch = { ...f.nullifier };
-  const hits = await scan([watch], 8, (p) => c.indexer.page('nullifiers', p), watch.scannedTo, nullifiers);
+  const from = Math.min(...watches.map((w) => w.scannedTo));
+  const hits = await scan(watches, 8, (p) => c.indexer.page('nullifiers', p), from, nullifiers);
   return hits.length > 0;
 }
 
-/** Where a JoinSplit relayed when the indexer had `relayedAt` nullifiers stands, by its first input `f` as sync last
- * saw it: spent, or the final nullifiers passed it without its own (a reorg dropped it, or the relayer never sent it),
- * or neither yet. */
-export function relayedState(f: Position | undefined, relayedAt: number): 'landed' | 'dropped' | 'waiting' {
-  if (f?.spent) return 'landed';
-  return f?.nullifier && f.nullifier.scannedTo >= relayedAt ? 'dropped' : 'waiting';
+/** Where a relayed step stands, by its `change` (a merge's note) and its `inputs` as sync last saw them:
+ * - `landed`: the change is final where this wallet expects it;
+ * - `taken`: an input is spent and the final commitments passed `spentAt` without the change, so another transaction
+ *   spent it, and this step can never land;
+ * - `dropped`: no input is spent and the final nullifiers passed `relayedAt` without them: whatever was spending them
+ *   is gone, a reorg dropped it or the relayer never sent it;
+ * - `mined`: the change is in a block, not final yet;
+ * - `waiting`: none of these yet. */
+export function relayedState(
+  change: Pick<NoteRecord, 'found' | 'watch'> | undefined,
+  inputs: (Position | undefined)[],
+  relayedAt: number | undefined,
+  spentAt: number | undefined,
+): 'landed' | 'taken' | 'dropped' | 'mined' | 'waiting' {
+  const seen = change?.found.filter((f) => f.confirmed) ?? [];
+  if (seen.some((f) => !f.tentative)) return 'landed';
+  if (inputs.some((f) => f?.spent)) {
+    // a final position not read yet may be the change
+    const missed =
+      spentAt !== undefined &&
+      !!change?.watch &&
+      change.watch.scannedTo >= spentAt &&
+      !change.found.some((f) => !f.tentative);
+    if (missed) return 'taken';
+  } else {
+    const watches = inputs.flatMap((f) => (f?.nullifier ? [f.nullifier] : []));
+    if (relayedAt !== undefined && watches.length > 0 && watches.every((w) => w.scannedTo >= relayedAt))
+      return 'dropped';
+  }
+  return seen.length > 0 ? 'mined' : 'waiting';
+}
+
+/** `relayedState` of `step`, failing the operation once another transaction took an input. The first time an input
+ * is seen spent, short of the step landing, it notes the final commitment count: a later status counts no fewer, so
+ * once the change's watch passes it, it has looked wherever that transaction put its notes. */
+async function standing(
+  ctx: Ctx,
+  op: SpendOperation,
+  step: Step | MergeStep,
+): Promise<ReturnType<typeof relayedState>> {
+  const inputs = step.inputs.map((coin) => positionOf(ctx, op.chainId, coin.index));
+  const salt = 'output' in step ? step.output.salt : step.outputs[1].salt;
+  const change = ctx.state.notes.find((n) => n.chainId === op.chainId && n.salt === salt);
+  const now = relayedState(change, inputs, step.relayedAt, step.spentAt);
+  if (now === 'taken')
+    fail('spent-elsewhere', 'another device of this wallet spent a note or deposit of it first: it paid nothing');
+  if (now !== 'landed' && step.spentAt === undefined && inputs.some((f) => f?.spent)) {
+    step.spentAt = (await chainCtx(ctx, op.chainId).indexer.status()).commitmentsFinal;
+    await ctx.save();
+  }
+  return now;
+}
+
+/** The indexer's nullifier count once it is past `block`, so past the nullifiers of a transaction mined there unless a
+ * reorg moved them; `undefined` until then. The relayer answers once the block is mined, which may be before the
+ * indexer has read it. */
+export async function nullifiersPast(indexer: Pick<Indexer, 'status'>, block: number): Promise<number | undefined> {
+  if ((await indexer.status()).cursor < block) return undefined;
+  // a status reads its counts before its cursor, so the count comes from the next one
+  return (await indexer.status()).nullifiers;
 }
 
 /** Whether `op`'s payment or withdrawal is on chain: done, or relayed, which the relayer answers once it is mined. Until
@@ -659,6 +736,18 @@ export function landed(op: SpendOperation): boolean {
   );
 }
 
+/** Whether `op` can still be cancelled, having paid nothing: a payment, withdrawal or consolidation under way with no
+ * request out to the relayer, and no merge of it landed. A step at its relay stage has one out, as its request leaves
+ * the moment it gets there; so has one built again after a relay of it reverted, as that request may still land: a
+ * JoinSplit's `attempts` count only those, and a merge, whose `attempts` count its prover's refusals too, is `sent`. */
+export function cancellable(op: OperationRecord): boolean {
+  if (op.status !== 'pending' || op.kind === 'deposit' || op.data.paid > 0n) return false;
+  const step = op.data.step;
+  if (!step) return true;
+  if ('output' in step) return !step.sent && step.stage !== 'proved' && step.stage !== 'relayed';
+  return step.attempts === 0 && step.stage !== 'attested' && step.stage !== 'relayed';
+}
+
 function markSpent(ctx: Ctx, op: SpendOperation, step: { inputs: Coin[] }): void {
   for (const coin of step.inputs) for (const f of positionsAt(ctx, op.chainId, coin.index)) f.spent = true;
 }
@@ -671,14 +760,17 @@ function placeChange(ctx: Ctx, op: SpendOperation, salt: Hex, index: number | nu
   }
 }
 
-/** Takes `op` as far as it can go now, saving before each step that leaves the device. */
+/** Takes `op` as far as it can go now, saving before each step that leaves the device. One cancelled meanwhile
+ * (`cancel`) finishes the stage under way and starts no other: its status is looked at after each, and nothing it does
+ * later is kept, as it is out of the state. A relayer that is relaying its request already throws `Relaying`. */
 export async function advanceSpend(ctx: Ctx, op: SpendOperation): Promise<void> {
   const data = op.data;
   const c = chainCtx(ctx, op.chainId);
   for (;;) {
+    if (op.status !== 'pending') return;
     if (!data.step) {
       const step = await planStep(ctx, op);
-      if (!step) return;
+      if (!step || op.status !== 'pending') return;
       if (step === 'done') {
         op.status = 'done';
         await ctx.save();
@@ -697,6 +789,7 @@ export async function advanceSpend(ctx: Ctx, op: SpendOperation): Promise<void>
       step.stage = 'noted';
       await ctx.save();
     }
+    if (op.status !== 'pending') return;
     if (step.stage === 'noted') {
       const built = await witnessOf(ctx, op, step);
       if (!built) return;
@@ -742,6 +835,7 @@ export async function advanceSpend(ctx: Ctx, op: SpendOperation): Promise<void>
       step.stage = 'proved';
       await ctx.save();
     }
+    if (op.status !== 'pending') return;
     if (step.stage === 'proved') {
       const attestation = await attest(c.config, step.statement!, step.witness!);
       step.request = { ...step.request!, attestation };
@@ -749,21 +843,25 @@ export async function advanceSpend(ctx: Ctx, op: SpendOperation): Promise<void>
       step.stage = 'attested';
       await ctx.save();
     }
+    if (op.status !== 'pending') return;
+    if (step.stage === 'attested' && step.relayedAt !== undefined) {
+      // a relay of it reverted on an input spent already: an earlier relay of it landed, one whose answer was lost, or
+      // another transaction spent the input. Relaying it again would tell nothing more
+      const now = await standing(ctx, op, step);
+      if (now === 'waiting') return;
+      if (now === 'dropped') delete step.relayedAt;
+      else step.stage = 'relayed';
+      await ctx.save();
+    }
     if (step.stage === 'attested') {
       const relayerOut = step.outputs.find((o) => o.role === 'relayer');
-      let result: Relayed | { reverted: string };
-      try {
-        result = await relay(
-          c.config,
-          step.request!,
-          relayerOut ? { value: relayerOut.value, salt: relayerOut.salt } : undefined,
-        );
-      } catch (e) {
-        if (e instanceof RelayUnknown) return; // try the same request again next time
-        throw e;
-      }
+      const result = await relay(
+        c.config,
+        step.request!,
+        relayerOut ? { value: relayerOut.value, salt: relayerOut.salt } : undefined,
+      );
       if ('reverted' in result) {
-        if (!(await inputSpent(ctx, op, step))) {
+        if (!(await inputsSpent(ctx, op, step))) {
           // stale roots, most likely: prove again with the same outputs, next sync. A JoinSplit that keeps reverting
           // is not on chain and cannot land, so failing it frees its inputs.
           if (++step.attempts > 3)
@@ -775,20 +873,24 @@ export async function advanceSpend(ctx: Ctx, op: SpendOperation): Promise<void>
           await ctx.save();
           return;
         }
-        // an earlier relay of it landed, one whose answer was lost
-      } else {
-        placeChange(ctx, op, step.outputs[1].salt, result.noteIndex2);
-        data.txHashes = [...(data.txHashes ?? []), result.txHash];
+        // the indexer counts the nullifiers of whatever spent it already
+        step.relayedAt = (await c.indexer.status()).nullifiers;
+        await ctx.save();
+        return;
       }
-      step.relayedAt = (await c.indexer.status()).nullifiers;
+      placeChange(ctx, op, step.outputs[1].salt, result.noteIndex2);
+      data.txHashes = [...(data.txHashes ?? []), result.txHash];
+      step.relayedBlock = result.block;
       step.stage = 'relayed';
       await ctx.save();
     }
     if (step.stage === 'relayed') {
-      const now = relayedState(positionOf(ctx, op.chainId, step.inputs[0].index), step.relayedAt!);
+      step.relayedAt ??= await nullifiersPast(c.indexer, step.relayedBlock!);
+      const now = await standing(ctx, op, step);
       if (now === 'dropped') {
         // relay it again next sync; if it did land after all, that reverts and finds it
         step.stage = 'attested';
+        delete step.relayedAt;
         await ctx.save();
       }
       if (now !== 'landed') return;
@@ -821,6 +923,7 @@ async function advanceMerge(ctx: Ctx, op: SpendOperation, step: MergeStep): Prom
     step.stage = 'noted';
     await ctx.save();
   }
+  if (op.status !== 'pending') return false;
   if (step.stage === 'noted') {
     const built = await mergeWitnessOf(ctx, op, step);
     if (!built) return false;
@@ -856,6 +959,7 @@ async function advanceMerge(ctx: Ctx, op: SpendOperation, step: MergeStep): Prom
     step.stage = 'attested';
     await ctx.save();
   }
+  if (op.status !== 'pending') return false;
   if (step.stage === 'attested') {
     await requestProof(c.config, prover, step.statement!, step.witness!, step.inputs.length);
     delete step.witness; // the prover has it: the inputs' openings need not stay saved here
@@ -877,30 +981,39 @@ async function advanceMerge(ctx: Ctx, op: SpendOperation, step: MergeStep): Prom
     step.stage = 'proved';
     await ctx.save();
   }
+  if (op.status !== 'pending') return false;
+  if (step.stage === 'proved' && step.relayedAt !== undefined) {
+    // as a JoinSplit's, told apart by its note
+    const now = await standing(ctx, op, step);
+    if (now === 'waiting') return false;
+    if (now === 'dropped') delete step.relayedAt;
+    else step.stage = 'relayed';
+    await ctx.save();
+  }
   if (step.stage === 'proved') {
-    let result: Awaited<ReturnType<typeof relayMerge>>;
-    try {
-      result = await relayMerge(c.config, step.request!);
-    } catch (e) {
-      if (e instanceof RelayUnknown) return false; // try the same request again next time
-      throw e;
-    }
+    const result = await relayMerge(c.config, step.request!);
     if ('reverted' in result) {
       // stale roots, most likely: built again with the same output, next sync
-      if (!(await inputSpent(ctx, op, step))) return again(result.reverted);
-      // an earlier relay of it landed, one whose answer was lost
-    } else {
-      placeChange(ctx, op, step.output.salt, result.noteIndex);
-      data.txHashes = [...(data.txHashes ?? []), result.txHash];
+      if (!(await inputsSpent(ctx, op, step))) {
+        step.sent = true;
+        return again(result.reverted);
+      }
+      step.relayedAt = (await c.indexer.status()).nullifiers;
+      await ctx.save();
+      return false;
     }
-    step.relayedAt = (await c.indexer.status()).nullifiers;
+    placeChange(ctx, op, step.output.salt, result.noteIndex);
+    data.txHashes = [...(data.txHashes ?? []), result.txHash];
+    step.relayedBlock = result.block;
     step.stage = 'relayed';
     await ctx.save();
   }
-  const now = relayedState(positionOf(ctx, op.chainId, step.inputs[0].index), step.relayedAt!);
+  step.relayedAt ??= await nullifiersPast(c.indexer, step.relayedBlock!);
+  const now = await standing(ctx, op, step);
   if (now === 'dropped') {
     // relay it again next sync; if it did land after all, that reverts and finds it
     step.stage = 'proved';
+    delete step.relayedAt;
     await ctx.save();
   }
   if (now !== 'landed') return false;

package/src/state.ts

@@ -86,6 +86,10 @@ export interface DepositRecord {
   /** Chosen by a payer, who told it in storage (a burn), as claimed: its salt is the payer's, with no index
    * (`burnIndex` -1), and it is never handed out. */
   payer?: Hex;
+  /** Recorded by another device of the wallet, or before a restore: taken as handed out, so never handed out here. A
+   * flag of its own rather than the token's `burnNext`, which would also pass the one this device recorded ahead and
+   * still holds: with two devices open, each would then record one more ahead each sync, without end. */
+  elsewhere?: true;
   /** The transfer's tag under each token. */
   watches: { tokenId: number; watch: Watch }[];
   found: (Position & {
@@ -114,9 +118,27 @@ export interface SentRecord extends Pick<
  * `unwritten` until storage holds it: every sync tries again. */
 export type ReceiptRecord = { chainId: bigint; tokenId: number; burnAddress: Hex; atMs: number; unwritten?: true } & (
   | { kind: 'returned'; index: number; recipient: Hex; amount: bigint; txHash: Hex }
-  | { kind: 'deposit-address'; depositAddress: Hex }
+  | {
+      kind: 'deposit-address';
+      depositAddress: Hex;
+      /** From the relayer's answer, or as storage told them. Absent where storage's record does not tell them, and then
+       * only the relayer flushes it. */
+      args?: DepositAddressArgs;
+    }
 );
 
+/** What a deposit address was registered with besides its token and burn address: with those, all a flush of it takes.
+ * A wallet's refunds go where a signer of its own signs for, so its refund address is zero. */
+export interface DepositAddressArgs {
+  fee: bigint;
+  feeRecipient: Hex;
+  refundSigner: Hex;
+  referrer: Hex;
+  referralBps: number;
+}
+
+export type DepositAddressReceipt = Extract<ReceiptRecord, { kind: 'deposit-address' }>;
+
 /** A sample of the indexer's final counts, to bound where a note announced at some time can be. */
 export interface Sample {
   atMs: number;
@@ -155,6 +177,8 @@ export interface DepositOperation extends OperationBase {
     burnAddress: Hex;
     /** Whose burn address it is, when not this wallet's (`deposit({ to })`). */
     to?: Hex;
+    /** The receive code it paid, when `to` was one. */
+    code?: string;
     /** Its transaction, once sent. */
     txHash?: Hex;
   };

package/src/sync.ts

@@ -4,6 +4,7 @@
 import {
   type Deposit,
   type LaneRecord,
+  type DepositArgs,
   type NewRecord,
   type Note,
   type OwnReceipt,
@@ -18,11 +19,11 @@ import {
 } from '@zerc20/storage-sdk';
 import { type Hex, bytesToHex, hexToBytes, numberToHex, parseAbiItem } from 'viem';
 import type { Chain, Token } from './chain.js';
-import { type ChainCtx, type Ctx, chainCtx, chainState, owner } from './context.js';
+import { type ChainCtx, type Ctx, chainCtx, chainState, owner, refundSigner } 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, Position, Sample } from './state.js';
+import type { DepositAddressArgs, 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)');
@@ -95,7 +96,12 @@ async function writeReceipts(ctx: Ctx, tokens: Map<bigint, number[]>): Promise<v
             amount: hexToBytes(numberToHex(r.amount, { size: 32 })),
             txHash: hexToBytes(r.txHash),
           }
-        : { ...head, kind: r.kind, depositAddress: hexToBytes(r.depositAddress) };
+        : {
+            ...head,
+            kind: r.kind,
+            depositAddress: hexToBytes(r.depositAddress),
+            ...(r.args && { args: depositArgsBytes(r.args) }),
+          };
     takeRefresh(
       ctx,
       await commit(ctx.storage, ctx.view, storageState(ctx), (s) => planReceipt(ctx.view, s, receipt)),
@@ -106,6 +112,24 @@ async function writeReceipts(ctx: Ctx, tokens: Map<bigint, number[]>): Promise<v
   }
 }
 
+/** A deposit address's arguments as the wallet keeps them, from storage's. */
+const depositArgs = (a: DepositArgs): DepositAddressArgs => ({
+  fee: big(a.fee),
+  feeRecipient: bytesToHex(a.feeRecipient),
+  refundSigner: bytesToHex(a.refundSigner),
+  referrer: bytesToHex(a.referrer),
+  referralBps: a.referralBps,
+});
+
+/** And storage's, from the wallet's. */
+const depositArgsBytes = (a: DepositAddressArgs): DepositArgs => ({
+  fee: hexToBytes(numberToHex(a.fee, { size: 32 })),
+  feeRecipient: hexToBytes(a.feeRecipient),
+  refundSigner: hexToBytes(a.refundSigner),
+  referrer: hexToBytes(a.referrer),
+  referralBps: a.referralBps,
+});
+
 /** A storage receipt as the wallet keeps it. */
 export const noteReceipt = (r: Receipt): NoteReceipt => ({
   kind: r.kind,
@@ -182,16 +206,24 @@ function takeSent(ctx: Ctx, d: Deposit, to: Uint8Array, tokens: Map<bigint, numb
 function takeReceipt(ctx: Ctx, r: OwnReceipt & { atNs: bigint }): void {
   const burnAddress = bytesToHex(r.burnAddress);
   const atMs = Number(r.atNs / 1_000_000n);
+  // a return is told apart by its deposit, a deposit address by itself: one burn address can have more than one, each
+  // registered with arguments of its own
   const same = ctx.state.receipts.find(
     (x) =>
       x.chainId === r.chainId &&
-      x.kind === r.kind &&
       x.burnAddress === burnAddress &&
-      (x.kind !== 'returned' || (r.kind === 'returned' && x.index === r.index)),
+      (x.kind === 'returned' && r.kind === 'returned'
+        ? x.index === r.index
+        : x.kind === 'deposit-address' &&
+          r.kind === 'deposit-address' &&
+          x.depositAddress.toLowerCase() === bytesToHex(r.depositAddress)),
   );
+  // what its address was registered with, where the record tells it
+  const args = r.kind === 'deposit-address' && r.args && { args: depositArgs(r.args) };
   if (same) {
     delete same.unwritten;
     same.atMs = atMs;
+    Object.assign(same, args);
     return;
   }
   const head = { chainId: r.chainId, tokenId: r.tokenId, burnAddress, atMs };
@@ -205,7 +237,7 @@ function takeReceipt(ctx: Ctx, r: OwnReceipt & { atNs: bigint }): void {
           amount: big(r.amount),
           txHash: bytesToHex(r.txHash),
         }
-      : { ...head, kind: r.kind, depositAddress: bytesToHex(r.depositAddress) },
+      : { ...head, kind: r.kind, depositAddress: bytesToHex(r.depositAddress), ...args },
   );
 }
 
@@ -255,10 +287,6 @@ function takeBurnBlock(
     const salt = hex32(bytes);
     const address = core.burnAddressOf(b.chainId, publicKey, salt) as Hex | undefined;
     if (!address || ctx.state.deposits.some((d) => d.chainId === b.chainId && d.salt === salt)) return;
-    if (!pos) {
-      const next = chainState(ctx, b.chainId).burnNext;
-      next[b.tokenId] = Math.max(next[b.tokenId] ?? 0, b.first + i + 1);
-    }
     const watch = { key: numberToHex(core.transferTag(b.tokenId, address), { size: 4 }), from, scannedTo: from };
     const record: DepositRecord = {
       chainId: b.chainId,
@@ -272,6 +300,7 @@ function takeBurnBlock(
       found: [],
     };
     if (pos) record.managed = true;
+    else record.elsewhere = true;
     ctx.state.deposits.push(record);
   });
 }
@@ -281,7 +310,8 @@ export function unusedBurn(ctx: Ctx, chainId: bigint, tokenId: number): DepositR
   const next = chainState(ctx, chainId).burnNext[tokenId] ?? 0;
   let best: DepositRecord | undefined;
   for (const d of ctx.state.deposits) {
-    if (d.chainId !== chainId || d.tokenId !== tokenId || d.managed || d.payer || d.burnIndex < next) continue;
+    if (d.chainId !== chainId || d.tokenId !== tokenId || d.managed || d.payer || d.elsewhere || d.burnIndex < next)
+      continue;
     if (!best || d.burnIndex < best.burnIndex) best = d;
   }
   return best;
@@ -302,17 +332,18 @@ 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; needs no seed. */
+ * of the wallet, and a restore, then watches it too and never hands it out again. About 2^16 hashes, `urgent` unless
+ * it is one made ahead; needs no seed. */
 export async function recordBurn(
   ctx: Ctx,
   chainId: bigint,
   tokenId: number,
   tokens: Map<bigint, number[]>,
-  signal?: AbortSignal,
+  opts: { signal?: AbortSignal; urgent?: boolean } = {},
 ): Promise<DepositRecord> {
   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 { salt, address } = await burnAddress(key, chainId, tokenId, index, owner(ctx)!.publicKey, opts);
   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));
@@ -350,7 +381,7 @@ export async function topUpBurns(ctx: Ctx, signal?: AbortSignal): Promise<void>
   let tokens: Map<bigint, number[]> | undefined;
   for (const { chainId, tokenId } of used.values()) {
     if (!unusedBurn(ctx, chainId, tokenId))
-      await recordBurn(ctx, chainId, tokenId, (tokens ??= await tokenIds(ctx)), signal);
+      await recordBurn(ctx, chainId, tokenId, (tokens ??= await tokenIds(ctx)), { signal, urgent: false });
   }
 }
 
@@ -394,12 +425,13 @@ function upsertNote(ctx: Ctx, a: NewRecord, note: Note, tokens: Map<bigint, numb
   });
 }
 
-/** Receive codes of each token whose keys are derived while the seed is held, to hand out while it is not. */
+/** Receive codes of each token whose keys are derived while the seed is held, to hand out while it is not, and as many
+ * deposit addresses' refund signers. */
 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. */
+ * the next `CODES_AHEAD` codes' of each of `tokens` with their deposit addresses' refund signers, 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
@@ -409,7 +441,10 @@ export function keyAll(ctx: Ctx, tokens: Token[]): void {
   }
   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 (let index = next; index < next + CODES_AHEAD; index++) {
+      owner(ctx, { chainId, tokenId, index });
+      refundSigner(ctx, { chainId, tokenId, index });
+    }
   }
   for (const n of ctx.state.notes) {
     if (n.keyIndex === undefined) continue;