@zerc20/wallet-sdk 0.3.0 → 0.5.0

package/src/rageExit.ts

@@ -1,15 +1,46 @@
 // Rage exit: a burn deposit refunded to its sender with nothing but the chain and the indexer's public pages, for
 // when the ASP, the attester or root proving stop. The ledger authenticates the deposit itself, by re-hashing the
-// commitments from it up to a checkpoint; a long way is walked back one transaction of commitments at a time.
+// commitments from it up to a checkpoint; a long way is walked back one transaction of commitments at a time. A deposit
+// address's refunds, the rage exit's and any other, go where its refund signer, a key of this wallet's, signs for; and
+// what reaches one is deposited without the deposit relayer by a flush of its own.
 
-import { type Address, type Hex, decodeEventLog, numberToHex, parseAbi } from 'viem';
-import { depositAddressAbi, ledgerAbi, verifierAbi } from './chain.js';
-import { type ChainCtx, type Ctx, chainCtx, spendKey, walletOn, walletSees } from './context.js';
+import {
+  type Address,
+  type Hex,
+  type WalletClient,
+  decodeEventLog,
+  encodeFunctionData,
+  isAddressEqual,
+  multicall3Abi,
+  numberToHex,
+  parseAbi,
+} from 'viem';
+import {
+  MULTICALL3,
+  NATIVE,
+  depositAddressAbi,
+  depositFactoryAbi,
+  erc20Abi,
+  factoryArgs,
+  ledgerAbi,
+  refundDigest,
+  verifierAbi,
+} from './chain.js';
+import {
+  type ChainCtx,
+  type Ctx,
+  chainCtx,
+  refundAccount,
+  spendKey,
+  switched,
+  walletOn,
+  walletSees,
+} from './context.js';
 import { core } from './core.js';
 import { fail, guard } from './errors.js';
 import { prove } from './prove.js';
 import { PAGE } from './servers.js';
-import type { DepositRecord } from './state.js';
+import type { DepositAddressReceipt, DepositRecord } from './state.js';
 
 /** Commitments per transaction: about a thousand fit in the 128 KB transaction size limit. */
 const SEGMENT = 900;
@@ -18,10 +49,10 @@ const checkpointEvent = parseAbi(['event CheckpointRecorded(uint64 indexed index
 
 type Fields = [bigint, bigint, bigint, bigint];
 
-/** Commitments `[from, to)` and the hash chain before `from`, from the indexer's pages. */
-async function commitments(c: ChainCtx, from: number, to: number): Promise<{ prev: Hex; list: Fields[] }> {
+/** Commitments `[from, to)`, each with the hash chain before it, from the indexer's pages. */
+async function commitments(c: ChainCtx, from: number, to: number): Promise<{ list: Fields[]; before: Hex[] }> {
   const list: Fields[] = [];
-  let prev: Hex | null = null;
+  const before: Hex[] = [];
   for (let p = Math.floor(from / PAGE); p * PAGE < to; p++) {
     const { hashChainBefore, entries } = await c.indexer.commitments(p);
     let chain = hashChainBefore;
@@ -31,21 +62,35 @@ async function commitments(c: ChainCtx, from: number, to: number): Promise<{ pre
       const fields = [0, 1, 2, 3].map((f) =>
         BigInt(`0x${hexOf(entries.subarray(j * 128 + 32 * f, j * 128 + 32 * (f + 1)))}`),
       ) as Fields;
-      if (i === from) prev = chain;
-      if (i >= from) list.push(fields);
+      if (i >= from) {
+        list.push(fields);
+        before.push(chain);
+      }
       chain = core.hashChain(
         chain,
         fields.map((x) => numberToHex(x, { size: 32 })),
       ) as Hex;
     }
   }
-  if (prev === null || list.length !== to - from)
+  if (list.length !== to - from)
     return fail('unavailable', `the indexer does not serve commitments ${from}..${to} yet`);
-  return { prev, list };
+  return { list, before };
 }
 
 const hexOf = (b: Uint8Array) => Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
 
+/** The `checkpointBefore` calls that walk back from the checkpoint at `end` to one at most a segment after `index`,
+ * the nearest the checkpoint first, and the checkpoint they end at. Each records the hash chain before its segment as
+ * the checkpoint the next one ends at. `list[k]` is the commitment at `index + k` and `before[k]` the chain before it. */
+export function walkBack(index: number, end: number, list: Fields[], before: Hex[]) {
+  const calls: [bigint, bigint, Fields[]][] = [];
+  for (; end - index > SEGMENT; end -= SEGMENT) {
+    const start = end - SEGMENT - index;
+    calls.push([BigInt(end), BigInt(before[start]), list.slice(start, end - index)]);
+  }
+  return { calls, end };
+}
+
 /** The first index after `index` the ledger has a checkpoint at: a proved root's size, else a fresh reservation. */
 async function checkpointAfter(ctx: Ctx, c: ChainCtx, index: number, send: Sender): Promise<number> {
   const ledger = await c.chain.ledger();
@@ -63,7 +108,7 @@ async function checkpointAfter(ctx: Ctx, c: ChainCtx, index: number, send: Sende
     }
     if (roots.length < PAGE) break;
   }
-  const receipt = await send(ledger, ledgerAbi, 'reserveHashChain', []);
+  const receipt = await send({ address: ledger, abi: ledgerAbi, functionName: 'reserveHashChain', args: [] });
   for (const log of receipt.logs) {
     try {
       const ev = decodeEventLog({ abi: checkpointEvent, data: log.data, topics: log.topics });
@@ -73,24 +118,29 @@ async function checkpointAfter(ctx: Ctx, c: ChainCtx, index: number, send: Sende
   return fail('unavailable', 'reserveHashChain recorded no checkpoint');
 }
 
-type Sender = (
-  address: Address,
-  abi: readonly unknown[],
-  functionName: string,
-  args: unknown[],
-) => Promise<{ logs: { data: Hex; topics: [Hex, ...Hex[]] }[]; status: string }>;
+interface Call {
+  address: Address;
+  abi: readonly unknown[];
+  functionName: string;
+  args: readonly unknown[];
+}
 
-/** Refunds the deposit at `index` of `record` to its sender, from the account's own wallet (it pays the gas). */
-export async function rageExit(ctx: Ctx, record: DepositRecord, index: number): Promise<Hex[]> {
-  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 = await walletOn(ctx, record.chainId);
-  const account = ctx.account;
-  const hashes: Hex[] = [];
-  const send: Sender = async (address, abi, functionName, args) => {
+type Sender = (call: Call) => Promise<{ logs: { data: Hex; topics: [Hex, ...Hex[]] }[]; status: string }>;
+
+/** Who sends a refund's transactions and pays their gas (null: the account's own wallet), and where a refund from one
+ * of this wallet's deposit addresses goes. */
+export interface Route {
+  from: WalletClient | null;
+  to: Address;
+}
+
+/** Sends from `from`, or from the account's own wallet, and waits for each transaction to land; `hashes` collects them. */
+async function sender(ctx: Ctx, c: ChainCtx, from: WalletClient | null, hashes: Hex[]) {
+  const wc = from ? await switched(from, c.config.chainId) : await walletOn(ctx, c.config.chainId);
+  const account = from?.account ?? ctx.account;
+  const send: Sender = async ({ address, abi, functionName, args }) => {
     const hash = await guard(
-      wc.writeContract({ account, chain: null, address, abi: abi as never, functionName: functionName, args: args }),
+      wc.writeContract({ account, chain: null, address, abi: abi as never, functionName, args }),
     );
     hashes.push(hash);
     const receipt = await c.chain.client.waitForTransactionReceipt({ hash });
@@ -98,24 +148,66 @@ export async function rageExit(ctx: Ctx, record: DepositRecord, index: number):
     await walletSees(wc, hash);
     return receipt as never;
   };
+  return { send, account };
+}
 
-  let end = await checkpointAfter(ctx, c, index, send);
-  const { prev, list } = await commitments(c, index, end);
-  const ledger = await c.chain.ledger();
-  // walk a long way back first: each step records the chain before its segment as a new checkpoint
-  while (end - index > SEGMENT) {
-    const start = end - SEGMENT;
-    const before = list.slice(0, start - index).reduce<Hex>(
-      (chain, f) =>
-        core.hashChain(
-          chain,
-          f.map((x) => numberToHex(x, { size: 32 })),
-        ) as Hex,
-      prev,
-    );
-    await send(ledger, ledgerAbi, 'checkpointBefore', [BigInt(end), BigInt(before), list.slice(start - index)]);
-    end = start;
+/** The call that sends on what `address` holds of `asset`, if it is a deposit address of `token` into `record`'s burn
+ * address, and where it goes: to `to`, signed by `record`'s refund signer, from one that names it; to its refund
+ * address, from one that names one. Null for anything else, a deposit address that names another signer included. */
+async function refundCall(
+  ctx: Ctx,
+  c: ChainCtx,
+  record: DepositRecord,
+  address: Address,
+  token: Address,
+  asset: Address,
+  to: Address,
+): Promise<{ call: Call; recipient: Address } | null> {
+  const refund = await c.chain.depositAddressRefund(address, token, record.address);
+  if (!refund) return null;
+  if ('address' in refund) {
+    return {
+      call: { address, abi: depositAddressAbi, functionName: 'refund', args: [asset] },
+      recipient: refund.address,
+    };
   }
+  // only the burn addresses of this wallet's own lane have refund signers
+  if (record.burnIndex < 0) return null;
+  const signer = refundAccount(ctx, { chainId: record.chainId, tokenId: record.tokenId, index: record.burnIndex });
+  if (signer.address.toLowerCase() !== refund.signer.toLowerCase()) return null;
+  // long enough for any wallet's confirmation; sent again before it, the signature moves only more to the same `to`
+  const deadline = BigInt(Math.floor(Date.now() / 1000) + 86_400);
+  const signature = await signer.signMessage({
+    message: { raw: refundDigest(c.config.chainId, address, asset, to, deadline) },
+  });
+  return {
+    call: { address, abi: depositAddressAbi, functionName: 'refundTo', args: [asset, to, deadline, signature] },
+    recipient: to,
+  };
+}
+
+const call3 = ({ address, abi, functionName, args }: Call) => ({
+  target: address,
+  allowFailure: false,
+  callData: encodeFunctionData({ abi, functionName, args }),
+});
+
+/** Refunds the deposit at `index` of `record` to its sender, sent by `route.from` or the account's own wallet, which
+ * pays the gas. A deposit address sends it on in the same transaction (Multicall3), so that nothing is left on it
+ * between two: one of this wallet's to `route.to`, a point of sale's to the refund address its payer named. */
+export async function rageExit(ctx: Ctx, record: DepositRecord, index: number, route: Route): Promise<Hex[]> {
+  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 hashes: Hex[] = [];
+  const { send, account } = await sender(ctx, c, route.from, hashes);
+
+  const after = await checkpointAfter(ctx, c, index, send);
+  const { list, before } = await commitments(c, index, after);
+  const prev = before[0];
+  const ledger = await c.chain.ledger();
+  const { calls, end } = walkBack(index, after, list, before);
+  for (const args of calls) await send({ address: ledger, abi: ledgerAbi, functionName: 'checkpointBefore', args });
   const segment = list.slice(0, end - index);
   // checked first, so a wrong page from the indexer costs no gas
   await c.chain.client.readContract({
@@ -134,34 +226,118 @@ export async function rageExit(ctx: Ctx, record: DepositRecord, index: number):
     auth_key_hash: key.authKeyHash,
     burn_salt: record.salt,
   });
-  const nullifier = signals[0];
-  await send(c.config.verifier, verifierAbi, 'rageExit', [
-    { checkpointIndex: BigInt(end), prevHashChain: BigInt(prev), commitments: segment, nullifier, proof },
-  ]);
-  found.spent = true;
-  // a deposit address's refund lands on the address itself; forward it to the address's refund address: this account,
-  // or for a point of sale's sale the payer's or the merchant's. A point of sale registers its deposit addresses without
-  // telling this wallet, and a record restored from storage no longer knows its own, so the sender is checked on chain.
-  const token = (await c.chain.tokens()).find((t) => t.tokenId === found.tokenId)!;
-  // the deposit's commitment, which the ledger just authenticated: `tag, sender, burn address, amount`
+  const request = {
+    checkpointIndex: BigInt(end),
+    prevHashChain: BigInt(prev),
+    commitments: segment,
+    nullifier: signals[0],
+    proof,
+  };
+  const exit: Call = { address: c.config.verifier, abi: verifierAbi, functionName: 'rageExit', args: [request] };
+  // the deposit's commitment, which the ledger just authenticated: `tag, sender, burn address, amount`. A point of sale
+  // registers its deposit addresses without telling this wallet, and a record restored from storage no longer knows
+  // its own, so whether the sender is one is read on chain.
   const [, from, , amount] = list[0];
-  const sender = numberToHex(from, { size: 20 });
-  const refundTo = await c.chain.depositAddressRefund(sender, token.address, record.address);
-  // for every device of the wallet, written by the next sync; kept now, before the forward, which may fail
+  const depositor = numberToHex(from, { size: 20 });
+  const token = (await c.chain.tokens()).find((t) => t.tokenId === found.tokenId)!;
+  const forward = await refundCall(ctx, c, record, depositor, token.address, token.address, route.to);
+  if (forward) {
+    // alone first, so that a failing rage exit says why rather than that the batch failed
+    await c.chain.client.simulateContract({
+      account,
+      address: c.config.verifier,
+      abi: verifierAbi,
+      functionName: 'rageExit',
+      args: [request],
+    });
+    await send({
+      address: MULTICALL3,
+      abi: multicall3Abi,
+      functionName: 'aggregate3',
+      args: [[call3(exit), call3(forward.call)]],
+    });
+  } else {
+    await send(exit);
+  }
+  found.spent = true;
+  // for every device of the wallet, written by the next sync
   ctx.state.receipts.push({
     kind: 'returned',
     chainId: record.chainId,
     tokenId: found.tokenId,
     burnAddress: record.address.toLowerCase() as Hex,
     index,
-    recipient: (refundTo ?? sender).toLowerCase() as Hex,
+    recipient: (forward?.recipient ?? depositor).toLowerCase() as Hex,
     amount,
     txHash: hashes.at(-1)!,
     atMs: Date.now(),
     unwritten: true,
   });
   await ctx.save();
-  if (refundTo) await send(sender, depositAddressAbi, 'refund', [token.address]);
-  await ctx.save();
   return hashes;
 }
+
+/** Sends what `record`'s deposit address `address` holds of `asset` to `route.to` (to its refund address, if it names
+ * one), sent by `route.from` or the account's own wallet. */
+export async function refundDepositAddress(
+  ctx: Ctx,
+  record: DepositRecord,
+  address: Address,
+  asset: Address,
+  route: Route,
+): Promise<Hex> {
+  const c = chainCtx(ctx, record.chainId);
+  const token = (await c.chain.tokens()).find((t) => t.tokenId === record.tokenId)!;
+  const refund =
+    (await refundCall(ctx, c, record, address, token.address, asset, route.to)) ??
+    fail(
+      'invalid',
+      `${address} is not deployed yet, or not one of this wallet's deposit addresses: it deploys on its first flush`,
+    );
+  const hashes: Hex[] = [];
+  const { send } = await sender(ctx, c, route.from, hashes);
+  await send(refund.call);
+  return hashes[0];
+}
+
+/** Deposits what deposit address `receipt.depositAddress` holds, as the deposit relayer would, by a flush with all its
+ * receipt says it was registered with, sent by `from`. */
+export async function flushDepositAddress(ctx: Ctx, receipt: DepositAddressReceipt, from: WalletClient): Promise<Hex> {
+  const { depositAddress } = receipt;
+  const registered =
+    receipt.args ??
+    fail(
+      'invalid',
+      `${depositAddress}'s receipt does not say what it was registered with: only the relayer flushes it`,
+    );
+  const c = chainCtx(ctx, receipt.chainId);
+  const token = (await c.chain.tokens()).find((t) => t.tokenId === receipt.tokenId)!;
+  const { fee, feeRecipient, refundSigner, referrer, referralBps } = registered;
+  const args = factoryArgs(
+    token.address,
+    receipt.burnAddress,
+    { signer: refundSigner },
+    feeRecipient,
+    fee,
+    referrer,
+    referralBps,
+  );
+  // the flush takes the very arguments checked here: others make another address, empty
+  if (!isAddressEqual(await c.chain.predictDepositAddress(args), depositAddress))
+    fail('invalid', `${depositAddress} is not the factory's address for what its receipt says`);
+  const held =
+    token.underlying.toLowerCase() === NATIVE.toLowerCase()
+      ? await c.chain.client.getBalance({ address: depositAddress })
+      : await c.chain.client.readContract({
+          address: token.underlying,
+          abi: erc20Abi,
+          functionName: 'balanceOf',
+          args: [depositAddress],
+        });
+  // its flush would revert: nothing reached it since, or the relayer flushed it first
+  if (held <= fee) fail('insufficient-funds', `${depositAddress} holds ${held}, not more than its fee of ${fee}`);
+  const hashes: Hex[] = [];
+  const { send } = await sender(ctx, c, from, hashes);
+  await send({ address: c.config.depositAddressFactory, abi: depositFactoryAbi, functionName: 'flush', args });
+  return hashes[0];
+}

package/src/seed.ts

@@ -7,7 +7,15 @@
 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 {
+  type Hex,
+  type WalletClient,
+  bytesToHex,
+  encodeAbiParameters,
+  hexToBytes,
+  keccak256,
+  parseAbiParameters,
+} from 'viem';
 import { mnemonicToAccount } from 'viem/accounts';
 import { fail, guard } from './errors.js';
 
@@ -19,6 +27,21 @@ export function accountKey(seed: Uint8Array): Hex {
   return bytesToHex(key ?? fail('invalid', 'the seed derives no account key'));
 }
 
+/** The private key that signs where the refunds of the deposit address handed out with burn address `index` of
+ * `tokenId` on `chainId` go (`DepositAddress.refundTo`). One per address, so that the addresses name neither one another
+ * nor the account; from the seed itself, not the view key, since whoever holds it moves those refunds. */
+export function refundKey(seed: Uint8Array, chainId: bigint, tokenId: number, index: number): Hex {
+  return keccak256(
+    encodeAbiParameters(parseAbiParameters('string, bytes32, uint64, uint32, uint32'), [
+      'zerc20/wallet/refund-signer/v1',
+      bytesToHex(seed),
+      chainId,
+      tokenId,
+      index,
+    ]),
+  );
+}
+
 const message = (address: Hex) =>
   [
     'zERC20 wallet seed',

package/src/servers.ts

@@ -62,6 +62,8 @@ export interface IndexerStatus {
   mismatch: { size: number; root: Hex } | null;
   /** The newest block whose entries cannot reorg, the one the final counts stand at. */
   finalBlock: number | null;
+  /** The last block it has indexed. Read after the counts: they may stand before it. */
+  cursor: number;
 }
 
 interface StatusJson {
@@ -77,7 +79,7 @@ interface StatusJson {
     partial_page_root: Hex | null;
   } | null;
   mismatch: { index: number; root: Hex } | null;
-  indexer: { final_block: number | null };
+  indexer: { final_block: number | null; cursor: number };
 }
 
 export class Indexer {
@@ -97,6 +99,7 @@ export class Indexer {
           : null,
       mismatch: s.mismatch ? { size: s.mismatch.index, root: s.mismatch.root } : null,
       finalBlock: s.indexer.final_block,
+      cursor: s.indexer.cursor,
     };
   }
 

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, zeroAddress } from 'viem';
-import type { Chain, Referrer } from './chain.js';
+import { type Address, type Hex, bytesToHex, getAddress, hexToBytes, zeroAddress } from 'viem';
+import { type Chain, type Referrer, type Refund, factoryArgs } 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';
@@ -101,6 +101,8 @@ export async function relayerFees(c: ChainConfig): Promise<RelayerFees> {
 
 export interface Relayed {
   txHash: Hex;
+  /** The block it was mined in. */
+  block: number;
   noteIndex1: number | null;
   noteIndex2: number | null;
 }
@@ -119,7 +121,7 @@ export const relay = (
 export const relayMerge = (
   c: ChainConfig,
   request: object,
-): Promise<{ txHash: Hex; noteIndex: number | null } | { reverted: string }> =>
+): Promise<{ txHash: Hex; block: number; noteIndex: number | null } | { reverted: string }> =>
   relayed(`${c.transactRelayer}/merge`, { request });
 
 async function relayed<T>(url: string, body: object): Promise<T | { reverted: string }> {
@@ -163,33 +165,44 @@ export async function proofOf(
   return r.body;
 }
 
+/** Has the deposit relayer watch `depositAddress` for another 7 days, at the fee it was registered with, which the
+ * address fixes: the fee the relayer names. */
+export async function rewatchDeposit(chain: Chain, depositAddress: Address): Promise<bigint> {
+  const r = await post<{ fee: Hex }>(`${chain.config.depositRelayer}/rewatch`, { depositAddress });
+  if (typeof r.body === 'string') return fail('unavailable', `deposit-relayer: ${r.body}`);
+  return BigInt(r.body.fee);
+}
+
 /** 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. */
+ * referrer's share of the rest each time; refunds go as `refund` says. 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. The address
+ * comes back checksummed, as every other address the SDK gives does: the relayer writes it in lower case. */
 export async function registerDeposit(
   chain: Chain,
   token: Address,
   burnAddress: Hex,
-  refundAddress: Address,
+  refund: Refund,
   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, referrer: referrer.address, referralBps: referrer.bps },
+    {
+      token,
+      burnAddress,
+      ...('address' in refund ? { refundAddress: refund.address } : { refundSigner: refund.signer }),
+      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);
+  // no balance exceeds such a fee, and storage holds values below 2^248 only
+  if (fee >= 1n << 248n) fail('unavailable', `deposit-relayer: a fee of ${fee}`);
   const expected = await chain.predictDepositAddress(
-    token,
-    burnAddress,
-    refundAddress,
-    feeRecipient,
-    fee,
-    referrer.address,
-    referrer.bps,
+    factoryArgs(token, burnAddress, refund, 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 };
+  return { depositAddress: getAddress(depositAddress), feeRecipient, fee };
 }