@zerc20/wallet-sdk 0.0.0-stage → 0.1.0

package/dist/seed.d.ts

@@ -0,0 +1,8 @@
+import { type Hex, type WalletClient } from 'viem';
+/** 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 declare function seedFromSignature(walletClient: WalletClient, expectedFingerprint?: Hex): Promise<{
+    seed: Uint8Array;
+    fingerprint: Hex;
+    signature: Hex;
+}>;

package/dist/seed.js

@@ -0,0 +1,35 @@
+// 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 { bytesToHex, hexToBytes, keccak256 } from 'viem';
+import { fail, guard } from './errors.js';
+const message = (address) => [
+    '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, expectedFingerprint) {
+    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);
+    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) };
+}
+//# sourceMappingURL=seed.js.map

package/dist/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,mHAAmH;AACnH,oHAAoH;AACpH,sEAAsE;AAEtE,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAA+B,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACtF,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,OAAO,GAAG,CAAC,OAAY,EAAE,EAAE,CAC/B;IACE,oBAAoB;IACpB,mEAAmE;IACnE,gDAAgD;IAChD,YAAY,OAAO,CAAC,WAAW,EAAE,EAAE;IACnC,4BAA4B;CAC7B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEf;iFACiF;AACjF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,YAA0B,EAC1B,mBAAyB;IAEzB,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,kCAAkC,CAAC,CAAC;IAC5F,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9G,8EAA8E;IAC9E,IAAI,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;IACxE,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/C,IAAI,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;QACnB,GAAG,GAAG,IAAI,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACxE,CAAC,IAAI,CAAC,CAAC;IACT,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACtE,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,SAAS,CAC3B,IAAI,UAAU,CAAC,CAAC,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,mCAAmC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAC5F,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAQ,CAAC;IACtB,IAAI,mBAAmB,IAAI,mBAAmB,KAAK,WAAW,EAAE,CAAC;QAC/D,IAAI,CACF,SAAS,EACT,gHAAgH,CACjH,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;AACjE,CAAC"}

package/dist/servers.d.ts

@@ -0,0 +1,60 @@
+import { type Hex } from 'viem';
+export declare const PAGE = 4096;
+/** 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;
+}
+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;
+}
+export declare class Indexer {
+    readonly url: string;
+    constructor(url: string);
+    status(): Promise<IndexerStatus>;
+    /** 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>;
+    /** Page `p` of commitments: the ledger's hash chain before it (32 bytes), then 4 fields of 32 bytes each. */
+    commitments(p: number): Promise<{
+        hashChainBefore: Hex;
+        entries: Uint8Array;
+    }>;
+    pageRoots(): Promise<Uint8Array>;
+    /** Page `p` of proved roots, in the order they were proved. */
+    roots(p: number): Promise<(RootEntry & {
+        matches: boolean;
+    })[]>;
+}
+export interface AspStatus {
+    decided: number;
+    latestRoot: RootEntry | null;
+    /** How old a deposit's block must be before it is screened. */
+    delaySecs: number;
+}
+export declare class Asp {
+    readonly url: string;
+    constructor(url: string);
+    status(): Promise<AspStatus>;
+    /** 512 bytes: position `c * 4096 + j` is approved if bit `j % 8` of byte `j / 8` is set. */
+    bitmap(c: number): Promise<Uint8Array>;
+    chunkRoots(p: number): Promise<Uint8Array>;
+    pageRoots(): Promise<Uint8Array>;
+    /** The recorded root whose value is `root`, searched from the newest page back. */
+    rootEntry(root: Hex): Promise<RootEntry | null>;
+}

package/dist/servers.js

@@ -0,0 +1,117 @@
+// 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 { bytesToHex } from 'viem';
+import { fail } from './errors.js';
+export const PAGE = 4096;
+const TIMEOUT_MS = 20_000;
+async function fetchBytes(url) {
+    let res;
+    try {
+        res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    }
+    catch (e) {
+        return fail('unavailable', `${url}: ${e.message}`);
+    }
+    if (!res.ok)
+        return fail('unavailable', `${url}: HTTP ${res.status}`);
+    return new Uint8Array(await res.arrayBuffer());
+}
+async function fetchJson(url) {
+    return JSON.parse(new TextDecoder().decode(await fetchBytes(url)));
+}
+const ZERO = `0x${'0'.repeat(64)}`;
+const orNull = (h) => (h === ZERO ? null : h);
+/** Root entries back to back: size(8) ‖ root ‖ partial chunk ‖ partial page (zero: none) [‖ matches(1)]. */
+function rootEntries(bytes, width) {
+    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 class Indexer {
+    url;
+    constructor(url) {
+        this.url = url;
+    }
+    async status() {
+        const s = await fetchJson(`${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, p) {
+        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) {
+        const body = await fetchBytes(`${this.url}/commitments/${p}`);
+        return { hashChainBefore: bytesToHex(body.subarray(0, 32)), entries: body.subarray(32) };
+    }
+    pageRoots() {
+        return fetchBytes(`${this.url}/page-roots`);
+    }
+    /** Page `p` of proved roots, in the order they were proved. */
+    async roots(p) {
+        return rootEntries(await fetchBytes(`${this.url}/roots/${p}`), 105);
+    }
+}
+export class Asp {
+    url;
+    constructor(url) {
+        this.url = url;
+    }
+    async status() {
+        const s = await fetchJson(`${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) {
+        return fetchBytes(`${this.url}/bitmap/${c}`);
+    }
+    chunkRoots(p) {
+        return fetchBytes(`${this.url}/chunk-roots/${p}`);
+    }
+    pageRoots() {
+        return fetchBytes(`${this.url}/page-roots`);
+    }
+    /** The recorded root whose value is `root`, searched from the newest page back. */
+    async rootEntry(root) {
+        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;
+        }
+    }
+}
+//# sourceMappingURL=servers.js.map

package/dist/servers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"servers.js","sourceRoot":"","sources":["../src/servers.ts"],"names":[],"mappings":"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"}

package/dist/services.d.ts

@@ -0,0 +1,62 @@
+import { type Address, type Hex } from 'viem';
+import type { Chain } from './chain.js';
+import { WalletError } from './errors.js';
+import { type AttesterTrust, type ChainConfig, type Network } from './network.js';
+/** The key the attester's enclave opens witnesses with, once its attestation checks out. */
+export declare const attesterKey: (c: ChainConfig) => Promise<Uint8Array>;
+/** 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 declare function enclaveKey(c: ChainConfig, url: string, trust: AttesterTrust, what: string): Promise<Uint8Array>;
+/** 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 declare function attest(c: ChainConfig, statement: object, witness: string, inputs?: number): Promise<Hex>;
+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 declare function relayerFees(c: ChainConfig): Promise<RelayerFees>;
+export interface Relayed {
+    txHash: Hex;
+    noteIndex1: number | null;
+    noteIndex2: number | null;
+}
+/** What `relay` reports when it cannot say whether the transaction landed. */
+export declare class RelayUnknown extends WalletError {
+}
+/** Has the relayer submit `request`. A 400 means the call reverts, which includes "already landed". */
+export declare const relay: (c: ChainConfig, request: object, feeNote?: {
+    value: bigint;
+    salt: Hex;
+}) => Promise<Relayed | {
+    reverted: string;
+}>;
+/** Has the relayer submit a merge's `request`, as `relay` does a JoinSplit's. Answers the merged note's index. */
+export declare const relayMerge: (c: ChainConfig, request: object) => Promise<{
+    txHash: Hex;
+    noteIndex: number | null;
+} | {
+    reverted: string;
+}>;
+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 declare function requestProof(c: ChainConfig, p: MergeProver, statement: object, witness: string, inputs: number): Promise<void>;
+/** 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 declare function proofOf(p: MergeProver, noteHash: Hex): Promise<{
+    status: 'queued' | 'proving' | 'done' | 'failed';
+    proof?: Hex;
+    error?: string;
+} | null>;
+/** 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 declare function registerDeposit(chain: Chain, token: Address, burnAddress: Hex, refundAddress: Address): Promise<{
+    depositAddress: Address;
+    feeRecipient: Address;
+    fee: bigint;
+}>;

package/dist/services.js

@@ -0,0 +1,128 @@
+// 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 { bytesToHex, hexToBytes } from 'viem';
+import { core } from './core.js';
+import { WalletError, fail } from './errors.js';
+import { LOCAL_CHAIN_ID } 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) => JSON.stringify(v, (_, x) => (typeof x === 'bigint' ? x.toString() : x));
+async function call(url, init) {
+    let res;
+    try {
+        res = await fetch(url, { ...init, signal: AbortSignal.timeout(init?.timeoutMs ?? 30_000) });
+    }
+    catch (e) {
+        return fail('unavailable', `${url}: ${e.message}`);
+    }
+    const text = await res.text();
+    if (!res.ok)
+        return { status: res.status, body: text };
+    return { status: res.status, body: JSON.parse(text) };
+}
+const post = (url, body, timeoutMs) => call(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: json(body), timeoutMs });
+const base64 = (s) => 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) => 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, url, trust, what) {
+    const r = await call(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.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, statement, witness, inputs) {
+    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(`${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 async function relayerFees(c) {
+    const r = await call(`${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 };
+}
+/** 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, request, feeNote) => 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, request) => relayed(`${c.transactRelayer}/merge`, { request });
+async function relayed(url, body) {
+    // the relayer answers once mined, after fee bumping if need be
+    const r = await post(url, body, 15 * 60_000).catch((e) => {
+        throw new RelayUnknown('unavailable', `transact-relayer: ${e.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}`);
+}
+/** 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, p, statement, witness, inputs) {
+    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(`${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, noteHash) {
+    const r = await call(`${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, token, burnAddress, refundAddress) {
+    const r = await post(`${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 };
+}
+//# sourceMappingURL=services.js.map

package/dist/services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.js","sourceRoot":"","sources":["../src/services.ts"],"names":[],"mappings":"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"}

package/dist/spend.d.ts

@@ -0,0 +1,151 @@
+import { type Recipient } from '@zerc20/storage-sdk';
+import { type Address, type Hex } from 'viem';
+import { type Ctx } from './context.js';
+import type { OperationRecord, Position, SpendOperation } from './state.js';
+/** Something spendable. */
+export interface Coin {
+    kind: 'note' | 'burn';
+    index: number;
+    value: bigint;
+    /** For a note paid to a receive code, the code's index: the code's own key owns it. Otherwise the wallet's key does. */
+    keyIndex?: number;
+    /** A note's salt. */
+    salt?: Hex;
+    /** A deposit's burn salt and sender. */
+    burnSalt?: Hex;
+    sender?: Hex;
+}
+export interface Output {
+    publicKey: Hex;
+    value: bigint;
+    salt: Hex;
+    role: 'recipient' | 'change' | 'relayer';
+}
+/** One JoinSplit and how far it got. */
+export interface Step {
+    inputs: Coin[];
+    outputs: [Output, Output];
+    /** `unwrap` pays it out as the underlying asset rather than zERC20. */
+    withdraw: {
+        recipient: Address;
+        amount: bigint;
+        unwrap?: boolean;
+    } | null;
+    entropy: Hex;
+    stage: 'planned' | 'noted' | 'proved' | 'attested' | 'relayed';
+    witness?: string;
+    statement?: Record<string, string>;
+    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. */
+    relayedAt?: number;
+}
+/** The most inputs one merge spends: the attester takes requests up to 2 MB, at 8 KiB of sealed witness per input
+ * sent as hex, and the prover folds them in one job. */
+export declare const MAX_MERGE_INPUTS = 100;
+/** One Nova merge of a consolidation and how far it got. */
+export interface MergeStep {
+    inputs: Coin[];
+    /** The note it makes: the inputs less `fee`. */
+    output: Output;
+    /** Paid publicly to `feeRecipient`, the relayer, grossed up for the protocol's cut. */
+    fee: bigint;
+    feeRecipient: Address;
+    stage: 'planned' | 'noted' | 'attested' | 'proving' | 'proved' | 'relayed';
+    /** Only until the prover has it: it holds the inputs' openings. */
+    witness?: string;
+    /** The attester's `Merge`, and from `attested` on the `MergeRequest` short of its proof. */
+    statement?: Record<string, unknown>;
+    request?: Record<string, unknown>;
+    /** 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;
+    relayedAt?: number;
+}
+/** Where a send or withdrawal goes; `self` merges the wallet's own notes and nothing leaves. */
+export type Destination = {
+    kind: 'address';
+    recipient: Recipient;
+} | {
+    kind: 'code';
+    code: string;
+} | {
+    kind: 'public';
+    address: Address;
+    unwrap?: boolean;
+} | {
+    kind: 'self';
+};
+export interface SpendData {
+    to: Destination;
+    /** The largest total fee the caller allowed. */
+    maxFee: bigint;
+    step: Step | MergeStep | null;
+    /** Fees paid so far. */
+    paid: bigint;
+    /** A consolidation of only these notes and deposits (commitment indices). */
+    chosen?: number[];
+    /** The notes to self its steps made (a payment's change, a consolidation's merged notes), by salt. */
+    changes?: Hex[];
+    /** The transactions relayed for it. */
+    txHashes?: Hex[];
+}
+/** The notes and deposits an operation in flight spends: no other operation may take them. */
+export declare const inputsOf: (o: OperationRecord) => Coin[];
+/** Final, unspent, under the latest proved root of size `rootSize`, and not taken by another operation. */
+export declare function coins(ctx: Ctx, chainId: bigint, tokenId: number, rootSize: number): Coin[];
+/** Whether any of `tokenId`'s notes or deposits is on chain but not spendable yet: not final or confirmed, not
+ * screened, or not under the proved root of size `rootSize`. A note only announced does not count: it may never land. */
+export declare function settling(ctx: Ctx, chainId: bigint, tokenId: number, rootSize: number): boolean;
+/** The inputs of one JoinSplit worth at least `need`: one coin, or a coin plus a note (a deposit can only be the
+ * first input). The smallest total wins. O(n log n), for wallets holding many notes. */
+export declare function pick(all: Coin[], need: bigint): Coin[] | null;
+/** A consolidation's next merge: up to `MAX_MERGE_INPUTS` coins, the largest first. `null` when a merge would leave
+ * nothing better: no coin, a lone note, or no more than the relayer's `fee`.
+ * ponytail: one merge per root; merge disjoint sets in parallel if consolidations of thousands get slow. */
+export declare function mergeRound(all: Coin[], fee: bigint): Coin[] | null;
+/** How many merges consolidate `all` into one note: each spends up to `MAX_MERGE_INPUTS`, the one before's note among
+ * them. A lone deposit takes one, to become a note. */
+export declare function roundsToMerge(all: Coin[]): number;
+/** What a consolidation merges: everything, or only the chosen notes and deposits (by commitment index) and the
+ * notes its earlier rounds made of them. */
+export declare function mergePool(all: Coin[], chosen: number[] | undefined, changes?: Hex[]): Coin[];
+/** The inputs of the one JoinSplit that pays `need` (see `pick`), or why there is none: merging everything worth it
+ * into one note first would pay it, coins `onTheWay` might, or nothing will. A payment never waits or merges itself:
+ * that is the app's call. */
+export declare function payWith(all: Coin[], need: bigint, fee: bigint, onTheWay: boolean): Coin[];
+/** The smallest public withdrawal that still pays `net` after the protocol's cut. */
+export declare function grossed(ctx: Ctx, chainId: bigint, tokenId: number, net: bigint): Promise<bigint>;
+/** A payment's one public withdrawal, and the protocol's cut of it, which the payer pays on top: a withdrawal's pays
+ * its recipient `amount` (and the relayer by a note), a private payment's pays the relayer its `fee`. */
+export declare function withdrawalOf(ctx: Ctx, chainId: bigint, tokenId: number, isPublic: boolean, amount: bigint, fee: bigint): Promise<{
+    withdrawn: bigint;
+    protocol: bigint;
+}>;
+/** 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. */
+export declare function maxPayment(ctx: Ctx, chainId: bigint, tokenId: number, isPublic: boolean, all: Coin[], fee: bigint): Promise<bigint>;
+/** Plans the next step of `op`: a payment's only JoinSplit (or throws why there is none), or a consolidation's next
+ * merge. `null`: wait for the last merge's note to become spendable. `'done'`: nothing left worth merging. */
+export declare function planStep(ctx: Ctx, op: SpendOperation): Promise<Step | MergeStep | null | 'done'>;
+/** Whether any of a consolidation's chosen notes and deposits (commitment indices) is still settling: not among the
+ * spendable `all` yet. Throws for one that never merges: a deposit the ASP rejected. A quote and every merge go by
+ * this one rule. */
+export declare function chosenSettling(ctx: Ctx, chainId: bigint, chosen: number[], all: Coin[]): boolean;
+export declare const codeOf: (code: string) => import("@zerc20/storage-sdk").ReceiveCode;
+/** What `step` paid besides `op`'s amount, the relayer's fee and the protocol's cut: what its inputs hold beyond the
+ * amount and the change. */
+export declare const feeOf: (op: SpendOperation, step: Step) => bigint;
+/** 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 declare function relayedState(f: Position | undefined, relayedAt: number): 'landed' | 'dropped' | 'waiting';
+/** Whether `op`'s payment or withdrawal is on chain: done, or relayed, which the relayer answers once it is mined. Until
+ * it is final a reorg may still drop it, and the operation relays it again. */
+export declare function landed(op: SpendOperation): boolean;
+/** Takes `op` as far as it can go now, saving before each step that leaves the device. */
+export declare function advanceSpend(ctx: Ctx, op: SpendOperation): Promise<void>;