@zbase-protocol/core 0.1.0

package/dist/facilitatorClient.d.ts

@@ -0,0 +1,171 @@
+/**
+ * facilitatorClient.ts — the buildable-on-top-of surface for zBase as private-
+ * facilitator infrastructure (facilitator-infra-architecture-2026-06-24.md).
+ *
+ * Three primitives a builder (or a trading agent, or you dogfooding) needs to make
+ * a private payment through zBase, with NO knowledge of the internal routes:
+ *
+ *   prepareDeposit(amount)            → deposit calldata + the secrets to keep
+ *   verifyPayment({ payTo, amount })  → can this settle?
+ *   settlePrivately({ payTo, amount, deposit }) → execute the private payment
+ *
+ * This is a thin, typed HTTP client over the facilitator API. The heavy ZK work
+ * (proof generation) currently runs server-side inside /settle; a future revision
+ * can move proving client-side here (proofs.ts already generates Groth16 proofs)
+ * so the payer's secrets never leave their machine — see NOTE on settlePrivately.
+ *
+ * Chain-agnostic: pass the CAIP-2 network ("eip155:84532" Sepolia / "eip155:8453"
+ * mainnet). Zero new dependencies — fetch only.
+ */
+export type FacilitatorNetwork = "eip155:84532" | "eip155:8453";
+export interface FacilitatorClientConfig {
+    /** Base URL of the zBase deployment, e.g. "https://zbase.app" or "http://localhost:3009". */
+    baseUrl: string;
+    /** CAIP-2 network. Defaults to Base Sepolia. */
+    network?: FacilitatorNetwork;
+    /** Optional fetch override (for tests / non-browser runtimes). */
+    fetchImpl?: typeof fetch;
+}
+/** Deposit secrets the payer keeps locally; the input to every later settle. */
+export interface DepositSecrets {
+    nullifier: string;
+    secret: string;
+    value: string;
+    label: string;
+    commitment: string;
+}
+export interface PreparedDeposit {
+    /** Precommitment to pass to the pool's deposit() call. */
+    precommitment: string;
+    /** Secrets to KEEP — value+label are filled in after the deposit tx from its event. */
+    secrets: Pick<DepositSecrets, "nullifier" | "secret">;
+    /** The on-chain amount to deposit (atomic USDC). */
+    amountAtomic: string;
+}
+export interface VerifyResult {
+    valid: boolean;
+    reason?: string;
+    privacy?: {
+        method: string;
+        pool: string;
+        anonymitySet: number;
+    };
+}
+export interface SettleResult {
+    settled: boolean;
+    txHash?: string;
+    network?: string;
+    error?: string;
+    pricing?: {
+        tier: string;
+        perSettleFeeAtomic: string;
+        feeModel: string;
+    };
+    /** Present when the recipient is a registered provider (stealth routing). */
+    stealth?: {
+        ephemeralPubkey: string;
+        viewTag: string;
+    };
+    /** Change note to use for the NEXT settle, if the deposit had leftover value. */
+    nextDeposit?: DepositSecrets;
+}
+/**
+ * Plan for callPrivately: release funds from the pool DIRECTLY into a whitelisted
+ * contract call (e.g. an ERC-4626 vault deposit) from an unlinked position. The
+ * server binds (target, callData, minOut, recipient) into the withdrawal `context`
+ * so neither the relayer nor anyone else can alter the plan. Privacy = unlinkability
+ * of WHO funded the call; the call itself is public on-chain. See the zBase threat model.
+ */
+export interface CallPlan {
+    /** Whitelisted contract to call (must be on the executor's frozen whitelist). */
+    target: string;
+    /** The pool asset spent into the call (USDC). */
+    inputToken: string;
+    /** Token the call yields (vault shares / swap output). */
+    outputToken: string;
+    /** Slippage floor on the produced outputToken delta (atomic). */
+    minOut: string | bigint;
+    /** Who receives the outputToken. */
+    recipient: string;
+    /** Exact calldata for the target (0x-hex). Its selector must be whitelisted. */
+    callData: string;
+}
+export interface CallResult {
+    executed: boolean;
+    txHash?: string;
+    network?: string;
+    error?: string;
+    pricing?: {
+        tier: string;
+        perSettleFeeAtomic: string;
+        feeModel: string;
+    };
+    nextDeposit?: DepositSecrets;
+}
+export declare class FacilitatorClient {
+    private readonly base;
+    private readonly network;
+    private readonly doFetch;
+    constructor(cfg: FacilitatorClientConfig);
+    /**
+     * Step 1 (one-time): prepare a deposit. Returns the precommitment to send to the
+     * pool's on-chain deposit() and the secrets to keep. After the deposit tx mines,
+     * read its Deposited event to fill in `value` (post-fee) + `label`, producing a
+     * full DepositSecrets you pass to settlePrivately.
+     *
+     * Pure/local — no network call. Uses the same secret derivation the rest of the
+     * stack uses (account.ts), so the resulting commitment matches the circuit.
+     */
+    prepareDeposit(amountAtomic: string | bigint): PreparedDeposit;
+    /**
+     * Step 2 (per payment): can this payment settle? Mirrors POST /api/facilitator/verify.
+     */
+    verifyPayment(args: {
+        payTo: string;
+        amountAtomic: string | bigint;
+        deposit?: DepositSecrets;
+    }): Promise<VerifyResult>;
+    /**
+     * Step 3 (per payment): execute the private payment. Mirrors POST
+     * /api/facilitator/settle. The pool pays `payTo` (or a fresh stealth address if
+     * payTo is a registered provider) from the anonymity set; there is no on-chain
+     * link to the payer's wallet. Returns the tx + any change note for the next settle.
+     *
+     * NOTE (client-side proving roadmap): today the proof is generated server-side
+     * inside /settle, so the deposit secrets are sent to the facilitator. The
+     * privacy-maximal version generates the proof HERE with proofs.ts
+     * (generateWithdrawalProof) and sends only the proof + public signals, so secrets
+     * never leave the caller. That requires browser-portable wasm/zkey loading; until
+     * then this client uses the server-proving path. The API surface below does NOT
+     * change when that lands — callers keep calling settlePrivately().
+     */
+    settlePrivately(args: {
+        payTo: string;
+        amountAtomic: string | bigint;
+        deposit: DepositSecrets;
+        agentId?: string;
+    }): Promise<SettleResult>;
+    /**
+     * Private-funded DeFi access: release pool funds DIRECTLY into a whitelisted
+     * contract call from an unlinked position. Mirrors POST /api/facilitator/call.
+     *
+     * The server generates the ZK withdrawal proof, binds the ENTIRE call plan
+     * (target, callData, minOut, recipient) into the proof's `context`, and submits
+     * via the ExecutorProcessooor (NOT the plain relay path). The executor re-derives
+     * the context on-chain and reverts on any mismatch, so the relayer is trustless.
+     *
+     * Privacy note: this hides WHO funded the call, not WHAT the call does. The
+     * on-chain call (e.g. a swap or a vault deposit) is public. Do not market as
+     * "private trading" — see the threat model.
+     */
+    callPrivately(args: {
+        plan: CallPlan;
+        amountAtomic: string | bigint;
+        deposit: DepositSecrets;
+        agentId?: string;
+    }): Promise<CallResult>;
+    /** Discovery: what the facilitator accepts (networks, tokens, pricing). */
+    supported(): Promise<unknown>;
+}
+/** Convenience factory. */
+export declare function createFacilitatorClient(cfg: FacilitatorClientConfig): FacilitatorClient;

package/dist/facilitatorClient.js

@@ -0,0 +1,146 @@
+/**
+ * facilitatorClient.ts — the buildable-on-top-of surface for zBase as private-
+ * facilitator infrastructure (facilitator-infra-architecture-2026-06-24.md).
+ *
+ * Three primitives a builder (or a trading agent, or you dogfooding) needs to make
+ * a private payment through zBase, with NO knowledge of the internal routes:
+ *
+ *   prepareDeposit(amount)            → deposit calldata + the secrets to keep
+ *   verifyPayment({ payTo, amount })  → can this settle?
+ *   settlePrivately({ payTo, amount, deposit }) → execute the private payment
+ *
+ * This is a thin, typed HTTP client over the facilitator API. The heavy ZK work
+ * (proof generation) currently runs server-side inside /settle; a future revision
+ * can move proving client-side here (proofs.ts already generates Groth16 proofs)
+ * so the payer's secrets never leave their machine — see NOTE on settlePrivately.
+ *
+ * Chain-agnostic: pass the CAIP-2 network ("eip155:84532" Sepolia / "eip155:8453"
+ * mainnet). Zero new dependencies — fetch only.
+ */
+import { generateDepositSecrets, computePrecommitment } from "./account.js";
+export class FacilitatorClient {
+    base;
+    network;
+    doFetch;
+    constructor(cfg) {
+        this.base = cfg.baseUrl.replace(/\/$/, "");
+        this.network = cfg.network ?? "eip155:84532";
+        const f = cfg.fetchImpl ?? globalThis.fetch;
+        if (!f)
+            throw new Error("FacilitatorClient: no fetch available — pass fetchImpl.");
+        this.doFetch = f;
+    }
+    /**
+     * Step 1 (one-time): prepare a deposit. Returns the precommitment to send to the
+     * pool's on-chain deposit() and the secrets to keep. After the deposit tx mines,
+     * read its Deposited event to fill in `value` (post-fee) + `label`, producing a
+     * full DepositSecrets you pass to settlePrivately.
+     *
+     * Pure/local — no network call. Uses the same secret derivation the rest of the
+     * stack uses (account.ts), so the resulting commitment matches the circuit.
+     */
+    prepareDeposit(amountAtomic) {
+        // generateDepositSecrets() returns decimal strings; computePrecommitment takes
+        // + returns strings (account.ts). Keep everything as strings end-to-end.
+        const { nullifier, secret } = generateDepositSecrets();
+        const precommitment = computePrecommitment(nullifier, secret);
+        return {
+            precommitment,
+            secrets: { nullifier, secret },
+            amountAtomic: amountAtomic.toString(),
+        };
+    }
+    /**
+     * Step 2 (per payment): can this payment settle? Mirrors POST /api/facilitator/verify.
+     */
+    async verifyPayment(args) {
+        const res = await this.doFetch(`${this.base}/api/facilitator/verify`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                paymentDetails: {
+                    scheme: "exact",
+                    networkId: this.network,
+                    payTo: args.payTo,
+                    maxAmountRequired: args.amountAtomic.toString(),
+                },
+                ...(args.deposit ? { zbaseDeposit: args.deposit } : {}),
+            }),
+        });
+        return (await res.json());
+    }
+    /**
+     * Step 3 (per payment): execute the private payment. Mirrors POST
+     * /api/facilitator/settle. The pool pays `payTo` (or a fresh stealth address if
+     * payTo is a registered provider) from the anonymity set; there is no on-chain
+     * link to the payer's wallet. Returns the tx + any change note for the next settle.
+     *
+     * NOTE (client-side proving roadmap): today the proof is generated server-side
+     * inside /settle, so the deposit secrets are sent to the facilitator. The
+     * privacy-maximal version generates the proof HERE with proofs.ts
+     * (generateWithdrawalProof) and sends only the proof + public signals, so secrets
+     * never leave the caller. That requires browser-portable wasm/zkey loading; until
+     * then this client uses the server-proving path. The API surface below does NOT
+     * change when that lands — callers keep calling settlePrivately().
+     */
+    async settlePrivately(args) {
+        const res = await this.doFetch(`${this.base}/api/facilitator/settle`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                paymentDetails: {
+                    scheme: "exact",
+                    networkId: this.network,
+                    payTo: args.payTo,
+                    maxAmountRequired: args.amountAtomic.toString(),
+                },
+                zbaseDeposit: args.deposit,
+                ...(args.agentId ? { agentId: args.agentId } : {}),
+            }),
+        });
+        return (await res.json());
+    }
+    /**
+     * Private-funded DeFi access: release pool funds DIRECTLY into a whitelisted
+     * contract call from an unlinked position. Mirrors POST /api/facilitator/call.
+     *
+     * The server generates the ZK withdrawal proof, binds the ENTIRE call plan
+     * (target, callData, minOut, recipient) into the proof's `context`, and submits
+     * via the ExecutorProcessooor (NOT the plain relay path). The executor re-derives
+     * the context on-chain and reverts on any mismatch, so the relayer is trustless.
+     *
+     * Privacy note: this hides WHO funded the call, not WHAT the call does. The
+     * on-chain call (e.g. a swap or a vault deposit) is public. Do not market as
+     * "private trading" — see the threat model.
+     */
+    async callPrivately(args) {
+        const res = await this.doFetch(`${this.base}/api/facilitator/call`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                networkId: this.network,
+                amountAtomic: args.amountAtomic.toString(),
+                callPlan: {
+                    target: args.plan.target,
+                    inputToken: args.plan.inputToken,
+                    outputToken: args.plan.outputToken,
+                    minOut: args.plan.minOut.toString(),
+                    recipient: args.plan.recipient,
+                    callData: args.plan.callData,
+                },
+                zbaseDeposit: args.deposit,
+                ...(args.agentId ? { agentId: args.agentId } : {}),
+            }),
+        });
+        return (await res.json());
+    }
+    /** Discovery: what the facilitator accepts (networks, tokens, pricing). */
+    async supported() {
+        const res = await this.doFetch(`${this.base}/api/facilitator/supported`);
+        return res.json();
+    }
+}
+/** Convenience factory. */
+export function createFacilitatorClient(cfg) {
+    return new FacilitatorClient(cfg);
+}

package/dist/forwardingNotes.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @zbase-protocol/core — D3 deterministic forwarding notes (Phase 2 / forwarding rail)
+ *
+ * The forwarding rail lets a bounded relayer deposit inbound funds into the pool
+ * ON THE USER'S BEHALF, without ever being able to SPEND them. The mechanism:
+ *
+ *   - The deposit's (nullifier, secret) are DERIVED DETERMINISTICALLY from the
+ *     USER'S OWN HD seed at a per-deposit index — NOT randomly generated by the
+ *     relayer. The relayer is given only the resulting `precommitment` (a public
+ *     value) so it can call the pool's `deposit()`. It never sees, and cannot
+ *     reconstruct, the spend secret — that requires the seed, which never leaves
+ *     the user.
+ *
+ *   - Recovery is SCAN-BY-COMMITMENT (the chosen design, 2026-07-09): the user
+ *     re-derives candidate (nullifier, secret) for indices 0..N, computes each
+ *     commitment, and matches against the pool's on-chain `Deposited` events.
+ *     There is NO shared mutable index to corrupt — the relayer and the user only
+ *     ever need to agree on the SEED. Even if the relayer's own index counter
+ *     desyncs, the user still finds every note by scanning. This is the property
+ *     that makes funds UNLOSABLE to a state desync (the failure class CLAUDE.md's
+ *     "cleared localStorage = lost funds" gotcha is about).
+ *
+ * Circuit ground-truth (see account.ts / commitment.circom):
+ *     precommitment = Poseidon(2)([nullifier, secret])
+ *     commitment    = Poseidon(3)([value, label, precommitment])
+ * Any deviation breaks proof verification, so this file reuses account.ts's
+ * `computePrecommitment` / `computeCommitment` rather than re-deriving.
+ *
+ * Derivation domain: a dedicated BIP44 sub-path SEPARATE from the viewing-key
+ * path (viewingKeyHD.ts uses m/44'/60'/0'/0'/i for X25519 viewing keys). The
+ * forwarding spend-secret path is m/44'/60'/0'/1'/i so a leaked forwarding note
+ * cannot be combined with a sibling viewing key. Each index yields TWO field
+ * elements (nullifier, secret) via domain-separated hashing of the node key.
+ */
+/**
+ * BIP44 path prefix for forwarding SPEND secrets. Hardened fourth segment `1'`
+ * separates this domain from the viewing-key domain (`0'`) — a leaked forwarding
+ * note cannot be recombined with a viewing key derived from the same mnemonic.
+ *
+ *   m / 44' / 60' / 0' / 1' / index
+ */
+export declare const ZBASE_FORWARDING_PATH_PREFIX = "m/44'/60'/0'/1'";
+/** A deterministically-derived forwarding note's spend secrets + public precommitment. */
+export interface ForwardingNoteSecrets {
+    /** Per-deposit derivation index. */
+    index: number;
+    /** Spend nullifier (field element, decimal string). Derived from the seed. */
+    nullifier: string;
+    /** Spend secret (field element, decimal string). Derived from the seed. */
+    secret: string;
+    /**
+     * `precommitment = Poseidon(2)([nullifier, secret])` — the ONLY value handed to
+     * the relayer. Public; reveals nothing about the spend secret.
+     */
+    precommitment: string;
+    /** Full derivation path, e.g. "m/44'/60'/0'/1'/0". */
+    derivationPath: string;
+}
+/**
+ * Derive the forwarding note secrets for a given index from a BIP39 mnemonic.
+ *
+ * Deterministic and pure: same mnemonic + index → same (nullifier, secret,
+ * precommitment), always. This is what lets the user recover a note the relayer
+ * deposited, by re-deriving and scanning.
+ *
+ * @param mnemonic  the user's BIP39 seed phrase (NEVER leaves the client / never sent to the relayer)
+ * @param index     per-deposit index (0, 1, 2, …)
+ */
+export declare function deriveForwardingNote(mnemonic: string, index: number): ForwardingNoteSecrets;
+/**
+ * Relayer-side view: given ONLY the user's PUBLIC precommitment stream is not
+ * possible (precommitments require the seed to derive). Instead the relayer is
+ * handed a specific `precommitment` for the index it should deposit at — this
+ * helper is the USER/CLIENT producing that value to register. The relayer never
+ * calls `deriveForwardingNote` (it has no mnemonic); it only ever receives the
+ * `precommitment` field.
+ *
+ * Returned precommitment is safe to transmit to the relayer.
+ */
+export declare function precommitmentForRelayer(mnemonic: string, index: number): string;
+/**
+ * SCAN-BY-COMMITMENT recovery. Given the user's mnemonic and the set of on-chain
+ * `Deposited` events (each carrying commitment, label, value), find which
+ * derived notes actually landed on-chain and return the full recoverable notes.
+ *
+ * This is how the user reclaims funds the relayer deposited: derive candidate
+ * notes for indices [0, maxIndex], compute each commitment against the event's
+ * (value, label), and match. NO shared index state is needed — only the seed.
+ *
+ * @param mnemonic       user's seed phrase
+ * @param depositedEvents on-chain Deposited events { commitment, label, value }
+ * @param maxIndex       highest index to scan (inclusive). Scan a window past the
+ *                       last found note to tolerate gaps.
+ */
+export declare function recoverForwardingNotes(mnemonic: string, depositedEvents: Array<{
+    commitment: string;
+    label: string;
+    value: string;
+}>, maxIndex: number): Array<ForwardingNoteSecrets & {
+    value: string;
+    label: string;
+    commitment: string;
+}>;

package/dist/forwardingNotes.js

@@ -0,0 +1,149 @@
+/**
+ * @zbase-protocol/core — D3 deterministic forwarding notes (Phase 2 / forwarding rail)
+ *
+ * The forwarding rail lets a bounded relayer deposit inbound funds into the pool
+ * ON THE USER'S BEHALF, without ever being able to SPEND them. The mechanism:
+ *
+ *   - The deposit's (nullifier, secret) are DERIVED DETERMINISTICALLY from the
+ *     USER'S OWN HD seed at a per-deposit index — NOT randomly generated by the
+ *     relayer. The relayer is given only the resulting `precommitment` (a public
+ *     value) so it can call the pool's `deposit()`. It never sees, and cannot
+ *     reconstruct, the spend secret — that requires the seed, which never leaves
+ *     the user.
+ *
+ *   - Recovery is SCAN-BY-COMMITMENT (the chosen design, 2026-07-09): the user
+ *     re-derives candidate (nullifier, secret) for indices 0..N, computes each
+ *     commitment, and matches against the pool's on-chain `Deposited` events.
+ *     There is NO shared mutable index to corrupt — the relayer and the user only
+ *     ever need to agree on the SEED. Even if the relayer's own index counter
+ *     desyncs, the user still finds every note by scanning. This is the property
+ *     that makes funds UNLOSABLE to a state desync (the failure class CLAUDE.md's
+ *     "cleared localStorage = lost funds" gotcha is about).
+ *
+ * Circuit ground-truth (see account.ts / commitment.circom):
+ *     precommitment = Poseidon(2)([nullifier, secret])
+ *     commitment    = Poseidon(3)([value, label, precommitment])
+ * Any deviation breaks proof verification, so this file reuses account.ts's
+ * `computePrecommitment` / `computeCommitment` rather than re-deriving.
+ *
+ * Derivation domain: a dedicated BIP44 sub-path SEPARATE from the viewing-key
+ * path (viewingKeyHD.ts uses m/44'/60'/0'/0'/i for X25519 viewing keys). The
+ * forwarding spend-secret path is m/44'/60'/0'/1'/i so a leaked forwarding note
+ * cannot be combined with a sibling viewing key. Each index yields TWO field
+ * elements (nullifier, secret) via domain-separated hashing of the node key.
+ */
+import { HDKey } from "@scure/bip32";
+import { mnemonicToSeedSync } from "@scure/bip39";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { SNARK_SCALAR_FIELD, computePrecommitment, computeCommitment, } from "./account.js";
+/**
+ * BIP44 path prefix for forwarding SPEND secrets. Hardened fourth segment `1'`
+ * separates this domain from the viewing-key domain (`0'`) — a leaked forwarding
+ * note cannot be recombined with a viewing key derived from the same mnemonic.
+ *
+ *   m / 44' / 60' / 0' / 1' / index
+ */
+export const ZBASE_FORWARDING_PATH_PREFIX = "m/44'/60'/0'/1'";
+/**
+ * Reduce a 32-byte hash to a BN254 field element via rejection-free modular
+ * reduction with domain tagging. The bias from a single `% r` is negligible for
+ * a keccak digest domain-separated per (node, tag); we do NOT need the CSPRNG
+ * rejection sampling used for random secrets because these values are
+ * DETERMINISTIC (reproducibility is the requirement, not perfect uniformity) and
+ * keccak output is already ~uniform over 2^256. Determinism is load-bearing:
+ * the user must re-derive the EXACT same value to recover the note.
+ */
+function hashToField(nodeKey, tag) {
+    const tagBytes = new TextEncoder().encode(tag);
+    const buf = new Uint8Array(nodeKey.length + tagBytes.length);
+    buf.set(nodeKey, 0);
+    buf.set(tagBytes, nodeKey.length);
+    const h = keccak_256(buf);
+    let x = 0n;
+    for (const b of h)
+        x = (x << 8n) | BigInt(b);
+    return x % SNARK_SCALAR_FIELD;
+}
+/**
+ * Derive the forwarding note secrets for a given index from a BIP39 mnemonic.
+ *
+ * Deterministic and pure: same mnemonic + index → same (nullifier, secret,
+ * precommitment), always. This is what lets the user recover a note the relayer
+ * deposited, by re-deriving and scanning.
+ *
+ * @param mnemonic  the user's BIP39 seed phrase (NEVER leaves the client / never sent to the relayer)
+ * @param index     per-deposit index (0, 1, 2, …)
+ */
+export function deriveForwardingNote(mnemonic, index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error("deriveForwardingNote: index must be a non-negative integer");
+    }
+    const seed = mnemonicToSeedSync(mnemonic);
+    const root = HDKey.fromMasterSeed(seed);
+    const path = `${ZBASE_FORWARDING_PATH_PREFIX}/${index}`;
+    const node = root.derive(path);
+    if (!node.privateKey) {
+        throw new Error("deriveForwardingNote: derivation produced no private key");
+    }
+    // Two domain-separated field elements from the same node key.
+    const nullifier = hashToField(node.privateKey, "zbase/forwarding/nullifier");
+    const secret = hashToField(node.privateKey, "zbase/forwarding/secret");
+    const nullifierStr = nullifier.toString();
+    const secretStr = secret.toString();
+    return {
+        index,
+        nullifier: nullifierStr,
+        secret: secretStr,
+        precommitment: computePrecommitment(nullifierStr, secretStr),
+        derivationPath: path,
+    };
+}
+/**
+ * Relayer-side view: given ONLY the user's PUBLIC precommitment stream is not
+ * possible (precommitments require the seed to derive). Instead the relayer is
+ * handed a specific `precommitment` for the index it should deposit at — this
+ * helper is the USER/CLIENT producing that value to register. The relayer never
+ * calls `deriveForwardingNote` (it has no mnemonic); it only ever receives the
+ * `precommitment` field.
+ *
+ * Returned precommitment is safe to transmit to the relayer.
+ */
+export function precommitmentForRelayer(mnemonic, index) {
+    return deriveForwardingNote(mnemonic, index).precommitment;
+}
+/**
+ * SCAN-BY-COMMITMENT recovery. Given the user's mnemonic and the set of on-chain
+ * `Deposited` events (each carrying commitment, label, value), find which
+ * derived notes actually landed on-chain and return the full recoverable notes.
+ *
+ * This is how the user reclaims funds the relayer deposited: derive candidate
+ * notes for indices [0, maxIndex], compute each commitment against the event's
+ * (value, label), and match. NO shared index state is needed — only the seed.
+ *
+ * @param mnemonic       user's seed phrase
+ * @param depositedEvents on-chain Deposited events { commitment, label, value }
+ * @param maxIndex       highest index to scan (inclusive). Scan a window past the
+ *                       last found note to tolerate gaps.
+ */
+export function recoverForwardingNotes(mnemonic, depositedEvents, maxIndex) {
+    // Index on-chain commitments for O(1) lookup.
+    const byCommitment = new Map();
+    for (const ev of depositedEvents) {
+        byCommitment.set(String(ev.commitment), { label: String(ev.label), value: String(ev.value) });
+    }
+    const found = [];
+    for (let i = 0; i <= maxIndex; i++) {
+        const note = deriveForwardingNote(mnemonic, i);
+        // For each on-chain event, the commitment is Poseidon3(value, label, precommitment).
+        // We can't know (value,label) a priori, so test the note's precommitment against
+        // every event's (value,label). In practice the event set is small per user.
+        for (const [commitment, { label, value }] of byCommitment) {
+            const derivedCommitment = computeCommitment(value, label, note.precommitment);
+            if (derivedCommitment === commitment) {
+                found.push({ ...note, value, label, commitment });
+                break;
+            }
+        }
+    }
+    return found;
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @zbase-protocol/core — Chain-agnostic ZK privacy for x402 agent payments
+ *
+ * This package contains universal logic shared across all chain implementations:
+ * - ZK proof generation (Groth16 via snarkjs)
+ * - Merkle tree operations (Poseidon + lean-imt)
+ * - Account/secrets management
+ * - Privacy scanner scoring
+ * - Abstract interfaces for Pool and Facilitator
+ *
+ * Chain-specific implementations:
+ * - @zbase-protocol/evm — Base, Ethereum, Arbitrum (Solidity + Morpho yield)
+ * - @zbase-protocol/svm — Solana (Anchor + Kamino yield)
+ */
+export type { AccountSecrets, ZX402AccountData, ChainType, DepositResult, WithdrawResult, PayResult, PoolStats, ZX402Pool, VerifyRequest, VerifyResponse, SettleRequest, SettleResponse, ZX402Facilitator, AgentPermissions, AgentInfo, RegisterAgentRequest, ExposureReport, SupportedCapabilities, } from "./types.js";
+export { generateDepositSecrets, computeCommitment, computePrecommitment, computeNullifierHash, computeLabel, feToBE32, SNARK_SCALAR_FIELD, createAccount, serializeAccount, deserializeAccount, } from "./account.js";
+export type { ProofInput, Groth16Proof, ProofResult } from "./proofs.js";
+export { generateWithdrawalProof, verifyProofLocally } from "./proofs.js";
+export { buildMerkleTree, generateMerkleProof, getTreeDepth } from "./merkle.js";
+export type { FacilitatorClientConfig, FacilitatorNetwork, DepositSecrets, PreparedDeposit, VerifyResult, SettleResult, } from "./facilitatorClient.js";
+export { FacilitatorClient, createFacilitatorClient } from "./facilitatorClient.js";
+export type { BuildSwapCallPlanOpts } from "./swapPlan.js";
+export { buildSwapCallPlan, EXACT_INPUT_SINGLE_SELECTOR, } from "./swapPlan.js";
+export type { ForwardingNoteSecrets } from "./forwardingNotes.js";
+export { deriveForwardingNote, precommitmentForRelayer, recoverForwardingNotes, ZBASE_FORWARDING_PATH_PREFIX, } from "./forwardingNotes.js";
+export type { StealthMetaAddress, StealthMetaAddressWithPrivate, DerivedStealthAddress, ScanMatch, } from "./stealth.js";
+export { STEALTH_SCHEME_ID, DEFAULT_CHAIN_TAG, generateMetaAddress, parseMetaAddress, isStealthMetaAddress, deriveStealthAddress, scanForPayments, computeStealthPrivateKey, } from "./stealth.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @zbase-protocol/core — Chain-agnostic ZK privacy for x402 agent payments
+ *
+ * This package contains universal logic shared across all chain implementations:
+ * - ZK proof generation (Groth16 via snarkjs)
+ * - Merkle tree operations (Poseidon + lean-imt)
+ * - Account/secrets management
+ * - Privacy scanner scoring
+ * - Abstract interfaces for Pool and Facilitator
+ *
+ * Chain-specific implementations:
+ * - @zbase-protocol/evm — Base, Ethereum, Arbitrum (Solidity + Morpho yield)
+ * - @zbase-protocol/svm — Solana (Anchor + Kamino yield)
+ */
+// Account management
+export { generateDepositSecrets, computeCommitment, computePrecommitment, computeNullifierHash, computeLabel, feToBE32, SNARK_SCALAR_FIELD, createAccount, serializeAccount, deserializeAccount, } from "./account.js";
+export { generateWithdrawalProof, verifyProofLocally } from "./proofs.js";
+// Merkle tree
+export { buildMerkleTree, generateMerkleProof, getTreeDepth } from "./merkle.js";
+export { FacilitatorClient, createFacilitatorClient } from "./facilitatorClient.js";
+export { buildSwapCallPlan, EXACT_INPUT_SINGLE_SELECTOR, } from "./swapPlan.js";
+export { deriveForwardingNote, precommitmentForRelayer, recoverForwardingNotes, ZBASE_FORWARDING_PATH_PREFIX, } from "./forwardingNotes.js";
+export { STEALTH_SCHEME_ID, DEFAULT_CHAIN_TAG, generateMetaAddress, parseMetaAddress, isStealthMetaAddress, deriveStealthAddress, scanForPayments, computeStealthPrivateKey, } from "./stealth.js";

package/dist/merkle.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @zbase-protocol/core — Chain-agnostic Merkle tree operations
+ *
+ * Uses Lean Incremental Merkle Tree (lean-imt) with Poseidon hashing.
+ * Same tree structure works for both EVM and Solana verifiers.
+ */
+import { LeanIMT } from "@zk-kit/lean-imt";
+/**
+ * Build a Merkle tree from leaf values (commitments).
+ * The hash function (Poseidon2) is identical across chains.
+ */
+export declare function buildMerkleTree(leaves: bigint[]): LeanIMT;
+/**
+ * Generate a Merkle proof for a leaf, shaped for `note_spend.circom`'s
+ * `LeanIMTInclusionProof(levels=TREE_DEPTH)`.
+ *
+ * B3 fix (audit-sweep-2026-06-17): zk-kit's `generateProof` returns a
+ * **compacted** proof — levels where the leaf has no right sibling are DROPPED
+ * from `siblings`, and `proof.index` is **recomputed** over only the surviving
+ * path bits (it is NOT the raw `leafIndex`). The circuit walks `actualDepth`
+ * real levels, decomposing `index` into bits and pairing bit `lvl` with
+ * `siblings[lvl]` — exactly the compacted shape. The previous implementation
+ * fed the RAW `leafIndex` bits alongside the compacted-then-zero-padded
+ * siblings; for any leaf whose path crosses a dropped level the index bits and
+ * siblings misaligned, producing a wrong root and an unsatisfiable witness.
+ * (It only worked for left-spine leaves where `proof.index === leafIndex` and
+ * no level is dropped — which is why the original committed fixture passed.)
+ *
+ * Correct mapping, matching zk-kit's own `verifyProof`:
+ *   - `index`       = proof.index            (compacted path, NOT leafIndex)
+ *   - `actualDepth` = siblings.length        (number of real levels)
+ *   - `siblings`    = proof.siblings, zero-padded to TREE_DEPTH
+ *   - `pathIndices` = bits of proof.index over TREE_DEPTH levels
+ *
+ * `actualDepth` and `index` are returned alongside so the witness builder can
+ * feed the circuit's `actualDepth`/`index` inputs directly.
+ */
+export declare function generateMerkleProof(tree: LeanIMT, leafIndex: number): {
+    pathElements: bigint[];
+    pathIndices: number[];
+    index: number;
+    actualDepth: number;
+    root: bigint;
+};
+/**
+ * Get the tree depth constant.
+ */
+export declare function getTreeDepth(): number;