@zerc20/wallet-sdk 0.0.0-stage → 0.1.0

package/src/rageExit.ts

@@ -0,0 +1,168 @@
+// 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.
+
+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 { 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';
+
+/** Commitments per transaction: about a thousand fit in the 128 KB transaction size limit. */
+const SEGMENT = 900;
+
+const checkpointEvent = parseAbi(['event CheckpointRecorded(uint64 indexed index, uint256 hashChain)']);
+
+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[] }> {
+  const list: Fields[] = [];
+  let prev: Hex | null = null;
+  for (let p = Math.floor(from / PAGE); p * PAGE < to; p++) {
+    const { hashChainBefore, entries } = await c.indexer.commitments(p);
+    let chain = hashChainBefore;
+    for (let j = 0; j < entries.length / 128; j++) {
+      const i = p * PAGE + j;
+      if (i >= to) break;
+      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);
+      chain = core.hashChain(
+        chain,
+        fields.map((x) => numberToHex(x, { size: 32 })),
+      ) as Hex;
+    }
+  }
+  if (prev === null || list.length !== to - from)
+    return fail('unavailable', `the indexer does not serve commitments ${from}..${to} yet`);
+  return { prev, list };
+}
+
+const hexOf = (b: Uint8Array) => Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+
+/** 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();
+  for (let p = 0; ; p++) {
+    const roots = await c.indexer.roots(p);
+    const after = roots.find((r) => r.size > index);
+    if (after) {
+      const [, exists] = await c.chain.client.readContract({
+        address: ledger,
+        abi: ledgerAbi,
+        functionName: 'hashChainAt',
+        args: [BigInt(after.size)],
+      });
+      if (exists) return after.size;
+    }
+    if (roots.length < PAGE) break;
+  }
+  const receipt = await send(ledger, ledgerAbi, 'reserveHashChain', []);
+  for (const log of receipt.logs) {
+    try {
+      const ev = decodeEventLog({ abi: checkpointEvent, data: log.data, topics: log.topics });
+      return Number(ev.args.index);
+    } catch {}
+  }
+  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 }>;
+
+/** 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 = ctx.walletClient;
+  const account = wc.account!;
+  if ((await wc.getChainId()) !== Number(record.chainId)) await guard(wc.switchChain({ id: Number(record.chainId) }));
+  const hashes: Hex[] = [];
+  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 }),
+    );
+    hashes.push(hash);
+    const receipt = await c.chain.client.waitForTransactionReceipt({ hash });
+    if (receipt.status !== 'success') fail('unavailable', `${functionName} reverted`);
+    await walletSees(wc, hash);
+    return receipt as never;
+  };
+
+  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;
+  }
+  const segment = list.slice(0, end - index);
+  // checked first, so a wrong page from the indexer costs no gas
+  await c.chain.client.readContract({
+    address: ledger,
+    abi: ledgerAbi,
+    functionName: 'verifySegment',
+    args: [BigInt(end), BigInt(prev), segment],
+  });
+
+  const key = spendKey(ctx);
+  const { proof, signals } = await prove(ctx.network.circuits.rageexit, {
+    chain_id: `${record.chainId}`,
+    commitment_index: `${index}`,
+    burn_address: BigInt(record.address).toString(),
+    private_key: key.secret,
+    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 [, 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
+  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,
+    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;
+}

package/src/scan.ts

@@ -0,0 +1,62 @@
+// Finding a wallet's own entries in the indexer's append-only lists without naming them: download pages, match
+// locally. One scanner serves both the 4-byte commitment tags and the 8-byte nullifier prefixes.
+//
+// Each watched key remembers how far it has been looked for, so a key learned late (a payment announced after
+// its commitment landed) is looked for once over the range it missed, and everything else only over new
+// entries. Pages below the final count never change, so re-reading them hits the HTTP cache or the CDN.
+
+import { bytesToHex, type Hex } from 'viem';
+import { PAGE } from './servers.js';
+
+/** A key to look for: entries at or after `from`, and not yet looked at before `scannedTo`. */
+export interface Watch {
+  key: Hex;
+  from: number;
+  /** Everything in `[from, scannedTo)` has been looked at. */
+  scannedTo: number;
+}
+
+export interface Hit {
+  key: Hex;
+  position: number;
+  /** Past the final count, so a reorg may still move or drop it. */
+  tentative: boolean;
+}
+
+/** Looks for `watches` (updated in place) in entries up to `final`, and, without recording that, in
+ * `[final, live)` too. `page(p)` returns page `p` of `width`-byte entries. */
+export async function scan(
+  watches: Watch[],
+  width: number,
+  page: (p: number) => Promise<Uint8Array>,
+  final: number,
+  live = final,
+): Promise<Hit[]> {
+  for (const w of watches) w.scannedTo = Math.max(w.scannedTo, w.from);
+  const pending = watches.filter((w) => w.scannedTo < live);
+  if (pending.length === 0) return [];
+  const byKey = new Map<string, Watch[]>();
+  for (const w of pending) byKey.set(w.key, [...(byKey.get(w.key) ?? []), w]);
+  // a loop, not Math.min(...): spreading 100k+ watches overflows the stack
+  let start = live;
+  for (const w of pending) start = Math.min(start, w.scannedTo);
+  const hits: Hit[] = [];
+  for (let p = Math.floor(start / PAGE); p * PAGE < live; p++) {
+    const bytes = await page(p);
+    const first = p * PAGE;
+    const end = Math.min(first + bytes.length / width, live);
+    for (let i = Math.max(first, start); i < end; i++) {
+      const key = bytesToHex(bytes.subarray((i - first) * width, (i - first + 1) * width));
+      for (const w of byKey.get(key) ?? []) {
+        if (i >= w.scannedTo) hits.push({ key, position: i, tentative: i >= final });
+      }
+    }
+    // a short page means the indexer has less than `live` (a stale copy): stop, and look again next time
+    if (first + bytes.length / width < Math.min(first + PAGE, live)) {
+      for (const w of pending) w.scannedTo = Math.max(w.scannedTo, Math.min(final, first + bytes.length / width));
+      return hits;
+    }
+  }
+  for (const w of pending) w.scannedTo = Math.max(w.scannedTo, final);
+  return hits;
+}

package/src/seed.ts

@@ -0,0 +1,46 @@
+// 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.
+
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { type Hex, type WalletClient, bytesToHex, hexToBytes, keccak256 } from 'viem';
+import { fail, guard } from './errors.js';
+
+const message = (address: Hex) =>
+  [
+    'zERC20 wallet seed',
+    'WARNING: signing this gives control of your private zERC20 funds.',
+    'Sign it only in an app you trust to hold them.',
+    `address: ${address.toLowerCase()}`,
+    'tag: zerc20/wallet/seed/v1',
+  ].join('\n');
+
+/** The seed, a fingerprint to check later derivations against (store it; it reveals nothing about the seed), and the
+ * canonical signature it comes from, which proves the seed is this account's. */
+export async function seedFromSignature(
+  walletClient: WalletClient,
+  expectedFingerprint?: Hex,
+): Promise<{ seed: Uint8Array; fingerprint: Hex; signature: Hex }> {
+  const account = walletClient.account ?? fail('invalid', 'the wallet client has no account');
+  const raw = hexToBytes(await guard(walletClient.signMessage({ account, message: message(account.address) })));
+  // canonical form: low s and v = 27/28, so equivalent signatures give one seed
+  let sig = secp256k1.Signature.fromBytes(raw.subarray(0, 64), 'compact');
+  let v = raw[64] >= 27 ? raw[64] - 27 : raw[64];
+  if (sig.hasHighS()) {
+    sig = new secp256k1.Signature(sig.r, secp256k1.Point.CURVE().n - sig.s);
+    v ^= 1;
+  }
+  const canonical = new Uint8Array([...sig.toBytes('compact'), 27 + v]);
+  const seed = hexToBytes(keccak256(canonical));
+  const fingerprint = keccak256(
+    new Uint8Array([...new TextEncoder().encode('zerc20/wallet/seed-fingerprint/v1'), ...seed]),
+  ).slice(0, 18) as Hex;
+  if (expectedFingerprint && expectedFingerprint !== fingerprint) {
+    fail(
+      'invalid',
+      'this wallet signs differently each time, so its signature cannot stand in for a seed: back the seed up instead',
+    );
+  }
+  return { seed, fingerprint, signature: bytesToHex(canonical) };
+}

package/src/servers.ts

@@ -0,0 +1,172 @@
+// The indexer and the ASP, read in whole pages that every wallet downloads alike: a wallet never names a
+// leaf, an address or a nullifier to a server. Layouts are in backend/indexer/README.md and backend/asp/README.md.
+
+import { type Hex, bytesToHex } from 'viem';
+import { fail } from './errors.js';
+
+export const PAGE = 4096;
+const TIMEOUT_MS = 20_000;
+
+async function fetchBytes(url: string): Promise<Uint8Array> {
+  let res: Response;
+  try {
+    res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+  } catch (e) {
+    return fail('unavailable', `${url}: ${(e as Error).message}`);
+  }
+  if (!res.ok) return fail('unavailable', `${url}: HTTP ${res.status}`);
+  return new Uint8Array(await res.arrayBuffer());
+}
+
+async function fetchJson<T>(url: string): Promise<T> {
+  return JSON.parse(new TextDecoder().decode(await fetchBytes(url))) as T;
+}
+
+/** A tree's size and root, with the roots of its partial chunk and page (null where the size ends on a
+ * boundary): what a path against that root needs besides the wallet's own chunk. */
+export interface RootEntry {
+  size: number;
+  root: Hex;
+  partialChunk: Hex | null;
+  partialPage: Hex | null;
+}
+
+const ZERO = `0x${'0'.repeat(64)}`;
+const orNull = (h: Hex): Hex | null => (h === ZERO ? null : h);
+
+/** Root entries back to back: size(8) ‖ root ‖ partial chunk ‖ partial page (zero: none) [‖ matches(1)]. */
+function rootEntries(bytes: Uint8Array, width: number): (RootEntry & { matches: boolean })[] {
+  const out = [];
+  for (let at = 0; at + width <= bytes.length; at += width) {
+    const e = bytes.subarray(at, at + width);
+    out.push({
+      size: Number(new DataView(e.buffer, e.byteOffset).getBigUint64(0, false)),
+      root: bytesToHex(e.subarray(8, 40)),
+      partialChunk: orNull(bytesToHex(e.subarray(40, 72))),
+      partialPage: orNull(bytesToHex(e.subarray(72, 104))),
+      matches: width === 104 || e[104] === 1,
+    });
+  }
+  return out;
+}
+
+export interface IndexerStatus {
+  commitments: number;
+  commitmentsFinal: number;
+  nullifiers: number;
+  nullifiersFinal: number;
+  /** The latest proved root the indexer derives itself, before any forged one: what a proof uses. */
+  latestRoot: RootEntry | null;
+  /** The first proved root since the protocol last recovered that the indexer does not derive: a forged one. No root
+   * is proved after it until the protocol recovers. */
+  mismatch: { size: number; root: Hex } | null;
+  /** The newest block whose entries cannot reorg, the one the final counts stand at. */
+  finalBlock: number | null;
+}
+
+interface StatusJson {
+  commitments: number;
+  commitments_final: number;
+  nullifiers: number;
+  nullifiers_final: number;
+  latest_root: {
+    index: number;
+    root: Hex;
+    matches: boolean;
+    partial_chunk_root: Hex | null;
+    partial_page_root: Hex | null;
+  } | null;
+  mismatch: { index: number; root: Hex } | null;
+  indexer: { final_block: number | null };
+}
+
+export class Indexer {
+  constructor(readonly url: string) {}
+
+  async status(): Promise<IndexerStatus> {
+    const s = await fetchJson<StatusJson>(`${this.url}/status`);
+    const r = s.latest_root;
+    return {
+      commitments: s.commitments,
+      commitmentsFinal: s.commitments_final,
+      nullifiers: s.nullifiers,
+      nullifiersFinal: s.nullifiers_final,
+      latestRoot:
+        r && r.matches
+          ? { size: r.index, root: r.root, partialChunk: r.partial_chunk_root, partialPage: r.partial_page_root }
+          : null,
+      mismatch: s.mismatch ? { size: s.mismatch.index, root: s.mismatch.root } : null,
+      finalBlock: s.indexer.final_block,
+    };
+  }
+
+  /** Page `p` of a list of fixed-size entries: 4096 entries, fewer while it fills. */
+  page(list: 'tags' | 'nullifiers' | 'blocks' | 'times' | 'chunk-roots' | 'marks', p: number): Promise<Uint8Array> {
+    return fetchBytes(`${this.url}/${list}/${p}`);
+  }
+
+  /** Page `p` of commitments: the ledger's hash chain before it (32 bytes), then 4 fields of 32 bytes each. */
+  async commitments(p: number): Promise<{ hashChainBefore: Hex; entries: Uint8Array }> {
+    const body = await fetchBytes(`${this.url}/commitments/${p}`);
+    return { hashChainBefore: bytesToHex(body.subarray(0, 32)), entries: body.subarray(32) };
+  }
+
+  pageRoots(): Promise<Uint8Array> {
+    return fetchBytes(`${this.url}/page-roots`);
+  }
+
+  /** Page `p` of proved roots, in the order they were proved. */
+  async roots(p: number): Promise<(RootEntry & { matches: boolean })[]> {
+    return rootEntries(await fetchBytes(`${this.url}/roots/${p}`), 105);
+  }
+}
+
+export interface AspStatus {
+  decided: number;
+  latestRoot: RootEntry | null;
+  /** How old a deposit's block must be before it is screened. */
+  delaySecs: number;
+}
+
+export class Asp {
+  constructor(readonly url: string) {}
+
+  async status(): Promise<AspStatus> {
+    const s = await fetchJson<{ decided: number; latest_root: StatusJson['latest_root']; delay_secs: number }>(
+      `${this.url}/status`,
+    );
+    const r = s.latest_root;
+    return {
+      decided: s.decided,
+      latestRoot: r
+        ? { size: r.index, root: r.root, partialChunk: r.partial_chunk_root, partialPage: r.partial_page_root }
+        : null,
+      delaySecs: s.delay_secs,
+    };
+  }
+
+  /** 512 bytes: position `c * 4096 + j` is approved if bit `j % 8` of byte `j / 8` is set. */
+  bitmap(c: number): Promise<Uint8Array> {
+    return fetchBytes(`${this.url}/bitmap/${c}`);
+  }
+
+  chunkRoots(p: number): Promise<Uint8Array> {
+    return fetchBytes(`${this.url}/chunk-roots/${p}`);
+  }
+
+  pageRoots(): Promise<Uint8Array> {
+    return fetchBytes(`${this.url}/page-roots`);
+  }
+
+  /** The recorded root whose value is `root`, searched from the newest page back. */
+  async rootEntry(root: Hex): Promise<RootEntry | null> {
+    const latest = (await this.status()).latestRoot;
+    if (latest?.root === root) return latest;
+    for (let p = 0; ; p++) {
+      const entries = rootEntries(await fetchBytes(`${this.url}/roots/${p}`), 104);
+      const hit = entries.find((e) => e.root === root);
+      if (hit) return hit;
+      if (entries.length < PAGE) return null;
+    }
+  }
+}

package/src/services.ts

@@ -0,0 +1,184 @@
+// The attester, the merge prover and the relayers. Each sees only what it must: the attester's and the prover's hosts
+// 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 { core } from './core.js';
+import { WalletError, fail } from './errors.js';
+import { type AttesterTrust, type ChainConfig, LOCAL_CHAIN_ID, type Network } from './network.js';
+
+/** A transact witness is sealed padded to this, and a merge's to `MERGE_PAD` per input, so its size does not leak the
+ * amounts' digits (`backend/attester/README.md`). */
+const WITNESS_PAD = 16 * 1024;
+const MERGE_PAD = 8 * 1024;
+
+const json = (v: unknown): string => JSON.stringify(v, (_, x: unknown) => (typeof x === 'bigint' ? x.toString() : x));
+
+async function call<T>(
+  url: string,
+  init?: RequestInit & { timeoutMs?: number },
+): Promise<{ status: number; body: T | string }> {
+  let res: Response;
+  try {
+    res = await fetch(url, { ...init, signal: AbortSignal.timeout(init?.timeoutMs ?? 30_000) });
+  } catch (e) {
+    return fail('unavailable', `${url}: ${(e as Error).message}`);
+  }
+  const text = await res.text();
+  if (!res.ok) return { status: res.status, body: text };
+  return { status: res.status, body: JSON.parse(text) as T };
+}
+
+const post = <T>(url: string, body: unknown, timeoutMs?: number) =>
+  call<T>(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: json(body), timeoutMs });
+
+const base64 = (s: string): Uint8Array => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+
+/** The key the attester's enclave opens witnesses with, once its attestation checks out. */
+export const attesterKey = (c: ChainConfig): Promise<Uint8Array> =>
+  enclaveKey(c, `${c.attester}/attestation`, c.attesterTrust, 'attester');
+
+/** The key an enclave (the attester's, the merge prover's) opens what is sealed to it with, from `url`, once its
+ * attestation document checks out against `trust`. */
+export async function enclaveKey(c: ChainConfig, url: string, trust: AttesterTrust, what: string): Promise<Uint8Array> {
+  const r = await call<{ publicKey: Hex; attestation: string | null }>(url);
+  if (typeof r.body === 'string') return fail('unavailable', `${what}: ${r.body}`);
+  if ('development' in trust) {
+    // its host would read everything sealed to it, every input's opening included: a local chain only, whatever the
+    // flag says
+    if (trust.development !== true || c.chainId !== LOCAL_CHAIN_ID)
+      return fail('attester-unverified', `a development ${what} off the local chain`);
+    return hexToBytes(r.body.publicKey);
+  }
+  if (!r.body.attestation) return fail('attester-unverified', `the ${what} sent no attestation document`);
+  try {
+    // from the document, never the `publicKey` beside it
+    return core.verifyAttestation(
+      base64(r.body.attestation),
+      trust.rootSha256,
+      trust.pcr0,
+      BigInt(Math.floor(Date.now() / 1000)),
+    );
+  } catch (e) {
+    return fail('attester-unverified', `the ${what}'s enclave does not check out: ${(e as Error).message}`);
+  }
+}
+
+/** The attester's signature over `statement`, once its enclave has checked `witness` (JSON): a JoinSplit's, or with
+ * `inputs`, a merge's of that many inputs. */
+export async function attest(c: ChainConfig, statement: object, witness: string, inputs?: number): Promise<Hex> {
+  const [path, pad] = inputs === undefined ? ['transact', WITNESS_PAD] : ['merge', MERGE_PAD * inputs];
+  for (let attempt = 0; ; attempt++) {
+    const sealed = bytesToHex(core.sealWitness(await attesterKey(c), witness, pad));
+    const r = await post<{ attestation: Hex }>(`${c.attester}/${path}`, { statement, witness: sealed }, 60_000);
+    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 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}`);
+  }
+}
+
+export interface RelayerFees {
+  relayer: Address;
+  /** The relayer's note key, which owns its fee notes whatever their token. */
+  publicKey: Hex;
+  fees: Map<number, { fee: bigint }>;
+}
+
+export async function relayerFees(c: ChainConfig): Promise<RelayerFees> {
+  const r = await call<{ relayer: Address; publicKey: Hex; fees: Record<string, { fee: Hex }> }>(
+    `${c.transactRelayer}/fee`,
+  );
+  if (typeof r.body === 'string') return fail('unavailable', `transact-relayer: ${r.body}`);
+  const fees = new Map(Object.entries(r.body.fees).map(([t, f]) => [Number(t), { fee: BigInt(f.fee) }]));
+  return { relayer: r.body.relayer, publicKey: r.body.publicKey, fees };
+}
+
+export interface Relayed {
+  txHash: Hex;
+  noteIndex1: number | null;
+  noteIndex2: number | null;
+}
+
+/** What `relay` reports when it cannot say whether the transaction landed. */
+export class RelayUnknown extends WalletError {}
+
+/** Has the relayer submit `request`. A 400 means the call reverts, which includes "already landed". */
+export const relay = (
+  c: ChainConfig,
+  request: object,
+  feeNote?: { value: bigint; salt: Hex },
+): Promise<Relayed | { reverted: string }> => relayed<Relayed>(`${c.transactRelayer}/transact`, { request, feeNote });
+
+/** Has the relayer submit a merge's `request`, as `relay` does a JoinSplit's. Answers the merged note's index. */
+export const relayMerge = (
+  c: ChainConfig,
+  request: object,
+): Promise<{ txHash: Hex; noteIndex: number | null } | { reverted: string }> =>
+  relayed(`${c.transactRelayer}/merge`, { request });
+
+async function relayed<T>(url: string, body: object): Promise<T | { reverted: string }> {
+  // the relayer answers once mined, after fee bumping if need be
+  const r = await post<T>(url, body, 15 * 60_000).catch((e: unknown) => {
+    throw new RelayUnknown('unavailable', `transact-relayer: ${(e as Error).message}`);
+  });
+  if (typeof r.body !== 'string') return r.body;
+  if (r.status === 400) return { reverted: r.body };
+  throw new RelayUnknown('unavailable', `transact-relayer: HTTP ${r.status}: ${r.body}`);
+}
+
+export type MergeProver = NonNullable<Network['mergeProver']>;
+
+/** Sends a merge's witness (JSON, of `inputs` inputs) sealed to the merge prover's enclave, to prove `statement` (the
+ * attester's `Merge`). Proving takes minutes: `proofOf` tells when it is done. */
+export async function requestProof(
+  c: ChainConfig,
+  p: MergeProver,
+  statement: object,
+  witness: string,
+  inputs: number,
+): Promise<void> {
+  const key = await enclaveKey(c, `${p.url}/enclave`, p.trust, 'merge prover');
+  const sealed = bytesToHex(core.sealMergeWitness(key, witness, MERGE_PAD * inputs));
+  const r = await post<{ status: string }>(`${p.url}/proofs`, { statement, witness: sealed }, 60_000);
+  if (typeof r.body === 'string') fail(r.status === 400 ? 'invalid' : 'unavailable', `merge prover: ${r.body}`);
+}
+
+/** Where the proof of the merge that outputs `noteHash` stands: `null` when the prover does not have it (it never
+ * did, or lost it in a restart), so it is to be sent again. `proof` is the ABI-encoded `NovaDeciderProof`. */
+export async function proofOf(
+  p: MergeProver,
+  noteHash: Hex,
+): Promise<{ status: 'queued' | 'proving' | 'done' | 'failed'; proof?: Hex; error?: string } | null> {
+  const r = await call<{ status: 'queued' | 'proving' | 'done' | 'failed'; proof?: Hex; error?: string }>(
+    `${p.url}/proofs/${noteHash}`,
+  );
+  if (r.status === 404) return null;
+  if (typeof r.body === 'string') return fail('unavailable', `merge prover: ${r.body}`);
+  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. */
+export async function registerDeposit(
+  chain: Chain,
+  token: Address,
+  burnAddress: Hex,
+  refundAddress: Address,
+): Promise<{ depositAddress: Address; feeRecipient: Address; fee: bigint }> {
+  const r = await post<{ depositAddress: Address; feeRecipient: Address; fee: Hex }>(
+    `${chain.config.depositRelayer}/register`,
+    { token, burnAddress, refundAddress },
+  );
+  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);
+  if (depositAddress.toLowerCase() !== expected.toLowerCase())
+    fail('indexer-mismatch', `the deposit relayer gave ${depositAddress}, not the factory's ${expected}`);
+  return { depositAddress, feeRecipient, fee };
+}

package/src/snarkjs.d.ts

@@ -0,0 +1,11 @@
+declare module 'snarkjs' {
+  export interface Groth16Proof {
+    pi_a: string[];
+    pi_b: string[][];
+    pi_c: string[];
+  }
+  type File = string | { type: 'mem'; data: Uint8Array };
+  export const groth16: {
+    fullProve(input: object, wasm: File, zkey: File): Promise<{ proof: Groth16Proof; publicSignals: string[] }>;
+  };
+}