@cloakely/sdk 0.8.5 → 0.9.0

package/dist/deployments.d.ts

@@ -54,6 +54,8 @@ export interface CloakDeployment {
     sharedRouter?: Address;
     /** SharedBatcher: batch rounds for the shared vault's tokens. */
     sharedBatcher?: Address;
+    /** CloakReceive: private receive addresses. */
+    receive?: Address;
     /** CloakDropFactory: sealed NFT drops. */
     dropFactory?: Address;
     /** Block the drop factory was deployed in: scan drop events from here. */

package/dist/deployments.js

@@ -26,6 +26,7 @@ export const deployments = {
         sharedBlock: 21426599n,
         sharedRouter: "0xe2a0769a5acbd987c1b6725247c56187a112dc7e",
         sharedBatcher: "0x11598b35fabc90fdd45d8a77ac41e2057c32ea14",
+        receive: "0x852675b2e127fcce3b5efd3ef817623db7aa44f3",
         // sealed NFT drops (Nov 3): GTD, then a sealed auction with the creator's price as the floor and a WL bid boost
         dropFactory: "0x2afb7d9a5baa02a2d72a7c761521fc66dce9d783",
         dropFactoryBlock: 22329730n,
@@ -115,6 +116,7 @@ export async function liveDeployment(publicClient, base) {
         sharedBlock: reg.sharedBlock ?? base.sharedBlock,
         sharedRouter: reg.sharedRouter ?? base.sharedRouter,
         sharedBatcher: reg.sharedBatcher ?? base.sharedBatcher,
+        receive: reg.receive ?? base.receive,
         hypePool,
         whype,
         previous: reg.previous.length

package/dist/drops.d.ts

@@ -179,7 +179,7 @@ export interface CreateDropOptions {
     };
     biddingSecs: number;
     /** Longest time after bidding closes for the keeper to open the bids (default 30 minutes). The drop settles as soon
-     * as every bid is open, so a long window only matters if the keeper is down; a bid still sealed at its end loses 10%. */
+     * as every bid is open, so a long window only matters if the keeper is down; a bid still sealed at its end loses 25% (10% on drops made before Nov 7). */
     revealSecs?: number;
     image?: string;
     /** A wide banner for the drop page (an https:, ipfs: or small data: image). */
@@ -1294,6 +1294,16 @@ export declare class CloakDrops {
             readonly internalType: "uint256";
         }];
         readonly stateMutability: "view";
+    }, {
+        readonly type: "function";
+        readonly name: "seedBlock";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{
+            readonly name: "";
+            readonly type: "uint64";
+            readonly internalType: "uint64";
+        }];
+        readonly stateMutability: "view";
     }, {
         readonly type: "function";
         readonly name: "setApprovalForAll";

package/dist/private/client.d.ts

@@ -2,6 +2,9 @@ import { type Address, type Hex, type PublicClient } from "viem";
 import { type Wallet } from "../cloak.js";
 import { CloakKeys } from "./crypto.js";
 import { MerkleTree } from "./tree.js";
+import { type PublicLeaves } from "./syncState.js";
+import { type FundsProof } from "./funds.js";
+import type { FundsProver } from "./prover.js";
 import type { ProofArgs, Prover } from "./prover.js";
 import { type ExtData, type OwnedNote } from "./tx.js";
 /** A shielded call the relayer submits so the trader's wallet never appears on-chain. */
@@ -45,6 +48,30 @@ export declare function relayerSubmitter(url: string): Submitter;
 /** Submit from a wallet directly — works, but that wallet pays gas and appears as the sender. Use for tests/relayers. */
 export declare function walletSubmitter(publicClient: PublicClient, wallet: Wallet, router: Address, batcher?: Address, migrator?: Address): Submitter;
 export type Status = (msg: string) => void;
+/** One piece of a split withdrawal: a proved relay call, and the earliest time a relayer may send it (unix seconds). */
+export interface ScheduledPiece {
+    call: RelayCall;
+    notBefore: number;
+    /** what this piece withdraws (before the vault's withdrawal fee) */
+    amount: bigint;
+    to: Address;
+}
+/**
+ * `amount` in `k` pieces of different, ordinary-looking sizes: random shares rounded to 2 significant digits, the
+ * last one taking the remainder. Every piece is above zero.
+ */
+export declare function splitAmount(amount: bigint, k: number): bigint[];
+/** Hand split-withdrawal pieces to a Cloak relayer (`POST /schedule`). Returns an id per piece, for `scheduleStatus`. */
+export declare function scheduleRelay(url: string, pieces: ScheduledPiece[]): Promise<string[]>;
+export interface ScheduledStatus {
+    id: string;
+    state: "waiting" | "sent" | "dropped" | "unknown";
+    notBefore?: number;
+    txHash?: Hex;
+    error?: string;
+}
+/** Where a relayer's scheduled pieces stand (`GET /schedule?ids=`). "unknown": it doesn't have it (re-send it). */
+export declare function scheduleStatus(url: string, ids: string[]): Promise<ScheduledStatus[]>;
 /**
  * Private trading for Cloak launch tokens on Elysium.
  *
@@ -102,8 +129,23 @@ export declare class CloakPrivate {
     /** Register a shielded pool that isn't a launch market, such as USDC (`deploymentFor(chainId).assets`). */
     addAsset(a: PrivateAsset): PrivateMarket;
     private state;
-    /** Pull new leaves from the pool's events, trial-decrypt them, and refresh spent flags. */
+    private inflight;
+    /** Pull new leaves from the pool's events, trial-decrypt them, and refresh spent flags. One sync per pool at a time
+     * (callers at the same moment share it), so a new note is never counted twice. */
     sync(pool: Address): Promise<OwnedNote[]>;
+    private syncOnce;
+    /**
+     * Start `pool` from public leaves (a keeper's GET /leaves) instead of scanning its history. Used only if nothing is
+     * synced yet and the leaves hash to a root the vault knows; returns whether they were used.
+     */
+    seedLeaves(pool: Address, src: PublicLeaves): Promise<boolean>;
+    /**
+     * What sync has learned so far, to keep on this device (encrypted: it lists your notes) and hand back to
+     * `importSync` next time, so only new blocks are scanned. Spending keys are left out and derived again on import.
+     */
+    exportSync(): string;
+    /** Load a state from `exportSync` (this account's only: notes that don't match its keys are dropped). */
+    importSync(data: string): Promise<boolean>;
     /** Every note this account has received in `pool`, spent ones included (each with `spent` and its nullifier). */
     history(pool: Address): Promise<OwnedNote[]>;
     balance(pool: Address): Promise<bigint>;
@@ -248,6 +290,38 @@ export declare class CloakPrivate {
      * `token` = a launch token, an asset such as USDC, or the WHYPE address / hypeMarket.token for HYPE.
      */
     send(token: Address, to: string, amount: bigint, onStatus?: Status): Promise<Hex>;
+    /**
+     * A withdrawal sent later in 2–4 pieces of different sizes, so the amount coming out doesn't match anything that went
+     * in. Done now, on this device:
+     *   1. private self-sends split the balance into one exact note per piece (pieces − 1 relayed sends),
+     *   2. each piece's withdrawal is proved, its recipient fixed by the proof.
+     * Hand the pieces to a relayer with `scheduleRelay`: it can only send each one (after `notBefore`) or refuse it,
+     * never change where it goes. Spending a piece's note before it's sent cancels that piece.
+     * `token` is a launch token or asset, or the WHYPE address / hypeMarket.token for HYPE.
+     */
+    planSplitWithdraw(token: Address, to: Address, amount: bigint, opts?: {
+        pieces?: number;
+        windowSecs?: number;
+        onStatus?: Status;
+    }): Promise<ScheduledPiece[]>;
+    /**
+     * Prove "I hold at least `threshold` of `token` in its vault" without revealing the balance, the notes or who you
+     * are (see funds.ts). Uses 1–3 of your notes; if the balance is spread over more, they're combined first (one
+     * relayed private send). `label` says who it's for and `expiresAt` (unix seconds) when it stops counting.
+     */
+    proveFunds(token: Address, threshold: bigint, o: {
+        label: string;
+        expiresAt: number;
+        prover: FundsProver;
+        symbol?: string;
+        decimals?: number;
+        onStatus?: Status;
+    }): Promise<FundsProof>;
+    /**
+     * Move notes into a fresh note of your own (a relayed private send to yourself), so whoever holds a proof of funds
+     * that named their nullifiers can't tell when you later spend that money.
+     */
+    refreshNotes(pool: Address, notes: OwnedNote[], onStatus?: Status): Promise<Hex>;
     /** Private tokens (a launch token, or an asset such as USDC) → any address. */
     unshieldToken(token: Address, to: Address, amount: bigint, onStatus?: Status): Promise<Hex>;
     /**

package/dist/private/client.js

@@ -4,6 +4,8 @@ import { cloakAuctionAbi, cloakConfigAbi, cloakMigratorAbi, cloakPairAbi, privat
 import { Cloak } from "../cloak.js";
 import { ACCOUNT_MESSAGE, ACCOUNT_TYPED_DATA, ROUTER_ACCOUNT_TYPED_DATA, CloakKeys, MAIN_KEY, noteCommitment, encryptFullMemo, encryptRouterMemo, formatCloakAddress, nullifierOf, parseCloakAddress, randomField, randomKeyIndex, readMemo, } from "./crypto.js";
 import { MerkleTree } from "./tree.js";
+import { fromJson, leavesRoot, toJson } from "./syncState.js";
+import { FUNDS_NOTES, fundsContext } from "./funds.js";
 import { MOVE_DATA_ABI, ORDER_DATA_ABI, SWAP_DATA_ABI, buildTransaction, selectNotes, splitStandard } from "./tx.js";
 /** Leaf positions per tree epoch (a pool starts a new tree after 2^20 leaves). */
 const EPOCH_BITS = 20;
@@ -71,6 +73,46 @@ export function walletSubmitter(publicClient, wallet, router, batcher, migrator)
         return hash;
     };
 }
+/**
+ * `amount` in `k` pieces of different, ordinary-looking sizes: random shares rounded to 2 significant digits, the
+ * last one taking the remainder. Every piece is above zero.
+ */
+export function splitAmount(amount, k) {
+    if (amount < BigInt(k) * 100n)
+        return [amount];
+    const w = Array.from({ length: k }, () => 0.6 + Math.random());
+    const sum = w.reduce((a, b) => a + b, 0);
+    const round2 = (x) => {
+        const d = x.toString().length;
+        const unit = d > 2 ? 10n ** BigInt(d - 2) : 1n;
+        return (x / unit) * unit;
+    };
+    const out = [];
+    let left = amount;
+    for (let i = 0; i < k - 1; i++) {
+        const x = round2((amount * BigInt(Math.round((w[i] / sum) * 1e6))) / 1000000n);
+        out.push(x);
+        left -= x;
+    }
+    out.push(left);
+    return out.every((x) => x > 0n) ? out : [amount];
+}
+/** Hand split-withdrawal pieces to a Cloak relayer (`POST /schedule`). Returns an id per piece, for `scheduleStatus`. */
+export async function scheduleRelay(url, pieces) {
+    const res = await fetch(`${url.replace(/\/$/, "")}/schedule`, { method: "POST", headers: { "content-type": "application/json" }, body: json({ pieces: pieces.map((p) => ({ call: p.call, notBefore: p.notBefore })) }), signal: AbortSignal.timeout(120_000) });
+    const out = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new Error(out.error ?? `scheduling failed (${res.status})`);
+    return out.ids;
+}
+/** Where a relayer's scheduled pieces stand (`GET /schedule?ids=`). "unknown": it doesn't have it (re-send it). */
+export async function scheduleStatus(url, ids) {
+    const res = await fetch(`${url.replace(/\/$/, "")}/schedule?ids=${ids.join(",")}`, { signal: AbortSignal.timeout(30_000) });
+    const out = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new Error(out.error ?? `status failed (${res.status})`);
+    return out.pieces;
+}
 /**
  * Private trading for Cloak launch tokens on Elysium.
  *
@@ -207,8 +249,19 @@ export class CloakPrivate {
         }
         return s;
     }
-    /** Pull new leaves from the pool's events, trial-decrypt them, and refresh spent flags. */
+    inflight = new Map();
+    /** Pull new leaves from the pool's events, trial-decrypt them, and refresh spent flags. One sync per pool at a time
+     * (callers at the same moment share it), so a new note is never counted twice. */
     async sync(pool) {
+        const k = pool.toLowerCase();
+        let p = this.inflight.get(k);
+        if (!p) {
+            p = this.syncOnce(pool).finally(() => this.inflight.delete(k));
+            this.inflight.set(k, p);
+        }
+        return p;
+    }
+    async syncOnce(pool) {
         const s = this.state(pool);
         const latest = await this.publicClient.getBlockNumber({ cacheTime: 0 });
         if (latest >= s.fromBlock) {
@@ -233,6 +286,11 @@ export class CloakPrivate {
         let n = 0;
         while (n < s.leaves.length && s.leaves[n].index === n)
             n++;
+        if (n < s.leaves.length && s.seeded) {
+            // the cache stopped short of where the chain picked up: forget it and scan this vault from the start
+            this.pools.delete(pool.toLowerCase());
+            return this.syncOnce(pool);
+        }
         for (const l of s.leaves.slice(s.scannedUpTo, n)) {
             const m = readMemo(this.keys.encPriv, l.memo);
             if (!m || m.amount === 0n)
@@ -249,6 +307,60 @@ export class CloakPrivate {
         s.notes.forEach((x, i) => (x.spent = Boolean(flags[i])));
         return s.notes.filter((x) => !x.spent);
     }
+    /**
+     * Start `pool` from public leaves (a keeper's GET /leaves) instead of scanning its history. Used only if nothing is
+     * synced yet and the leaves hash to a root the vault knows; returns whether they were used.
+     */
+    async seedLeaves(pool, src) {
+        const s = this.state(pool);
+        if (s.leaves.length || s.scannedUpTo)
+            return false;
+        const root = await leavesRoot(src.leaves);
+        if (root === null)
+            return false;
+        const known = await this.publicClient.readContract({ address: pool, abi: shieldedPoolAbi, functionName: "isKnownRoot", args: [root] }).catch(() => false);
+        if (!known)
+            return false;
+        s.leaves = src.leaves.map((l) => ({ ...l }));
+        s.fromBlock = src.block + 1n;
+        s.seeded = true;
+        return true;
+    }
+    /**
+     * What sync has learned so far, to keep on this device (encrypted: it lists your notes) and hand back to
+     * `importSync` next time, so only new blocks are scanned. Spending keys are left out and derived again on import.
+     */
+    exportSync() {
+        // scanned leaves keep only their commitment (the tree needs it; the memo was already read)
+        const pools = [...this.pools].map(([k, s]) => [k, { leaves: s.leaves.map((l, i) => (i < s.scannedUpTo ? { ...l, memo: "0x" } : l)), scannedUpTo: s.scannedUpTo, fromBlock: s.fromBlock, notes: s.notes.map(({ privKey: _, ...n }) => n) }]);
+        return toJson({ v: 1, pools });
+    }
+    /** Load a state from `exportSync` (this account's only: notes that don't match its keys are dropped). */
+    async importSync(data) {
+        try {
+            const o = fromJson(data);
+            if (o.v !== 1)
+                return false;
+            for (const [k, st] of o.pools) {
+                if (this.pools.has(k))
+                    continue;
+                const notes = [];
+                let ok = true;
+                for (const n of st.notes) {
+                    const key = await this.keys.key(n.keyIndex);
+                    if (key.pubKey !== n.pubKey)
+                        ok = false;
+                    notes.push({ ...n, privKey: key.privKey });
+                }
+                if (ok)
+                    this.pools.set(k, { leaves: st.leaves, scannedUpTo: st.scannedUpTo, fromBlock: st.fromBlock, notes, seeded: true });
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /** Every note this account has received in `pool`, spent ones included (each with `spent` and its nullifier). */
     async history(pool) {
         await this.sync(pool);
@@ -742,6 +854,148 @@ export class CloakPrivate {
         onStatus("Relaying private transfer…");
         return this.submit({ kind: "transact", pool, proof, extData });
     }
+    /**
+     * A withdrawal sent later in 2–4 pieces of different sizes, so the amount coming out doesn't match anything that went
+     * in. Done now, on this device:
+     *   1. private self-sends split the balance into one exact note per piece (pieces − 1 relayed sends),
+     *   2. each piece's withdrawal is proved, its recipient fixed by the proof.
+     * Hand the pieces to a relayer with `scheduleRelay`: it can only send each one (after `notBefore`) or refuse it,
+     * never change where it goes. Spending a piece's note before it's sent cancels that piece.
+     * `token` is a launch token or asset, or the WHYPE address / hypeMarket.token for HYPE.
+     */
+    async planSplitWithdraw(token, to, amount, opts = {}) {
+        const onStatus = opts.onStatus ?? (() => { });
+        const k = Math.min(4, Math.max(2, opts.pieces ?? 3));
+        const windowSecs = Math.max(600, opts.windowSecs ?? 3600);
+        const isHype = token.toLowerCase() === this.hypeMarket.token.toLowerCase();
+        const pool = isHype ? this.hypeMarket.pool : this.market(token).pool;
+        const kind = isHype ? "unshieldHype" : "transact";
+        const amounts = splitAmount(amount, k);
+        // each piece carries twice today's relayer fee, so a gas rise before it goes out doesn't get it refused
+        const q = await this.relayFee(kind, pool);
+        const pieceFee = q.fee * 2n;
+        const notes = [];
+        let rest = null;
+        for (let i = 0; i < k - 1; i++) {
+            onStatus(`Splitting your balance privately (${i + 1} of ${k - 1})…`);
+            const sq = await this.relayFee("transact", pool);
+            const remaining = amounts.slice(i).reduce((a, x) => a + x + pieceFee, 0n);
+            const inputs = rest ?? (await this.inputsFor(pool, remaining + sq.fee * BigInt(2 * (k - 1)), onStatus));
+            const total = inputs.reduce((a, x) => a + x.amount, 0n);
+            const first = amounts[i] + pieceFee;
+            const outputs = [await this.changeOutput(first), await this.changeOutput(total - sq.fee - first)];
+            onStatus("Generating zero-knowledge proof on this device…");
+            const { proof, extData } = await buildTransaction({ tree: await this.treeFor(pool, inputs), inputs, outputs, fee: sq.fee, relayer: sq.relayer, ...(await this.dummy()), prover: await this.prover() });
+            const h = await this.submit({ kind: "transact", pool, proof, extData });
+            await this.publicClient.waitForTransactionReceipt({ hash: h });
+            const [c0, c1] = proof.outputCommitments.map(BigInt);
+            let mine = [];
+            for (let t = 0; t < 10 && mine.length < 2; t++) {
+                mine = (await this.sync(pool)).filter((n) => n.commitment === c0 || n.commitment === c1);
+                if (mine.length < 2)
+                    await new Promise((r) => setTimeout(r, 1500));
+            }
+            const piece = mine.find((n) => n.commitment === c0);
+            const left = mine.find((n) => n.commitment === c1);
+            if (!piece || !left)
+                throw new Error("The split landed, but the new notes haven't shown up yet. Try again in a minute: nothing was lost.");
+            notes.push(piece);
+            rest = [left];
+        }
+        // the last piece's note is what the splits left: its amount plus anything spare, which comes back as change
+        notes.push(rest[0]);
+        const now = Math.floor(Date.now() / 1000);
+        const times = Array.from({ length: k }, () => now + 60 + Math.floor(Math.random() * (windowSecs - 60))).sort((a, b) => a - b);
+        const out = [];
+        for (let i = 0; i < k; i++) {
+            onStatus(`Proving withdrawal ${i + 1} of ${k}…`);
+            const n = notes[i];
+            const pieceAmount = amounts[i];
+            const change = n.amount - pieceAmount - pieceFee;
+            if (change < 0n)
+                throw new Error("The split came out short (the relayer's fee rose meanwhile). Your balance is intact: try again.");
+            const { proof, extData } = await buildTransaction({
+                tree: await this.treeFor(pool, [n]),
+                inputs: [n],
+                outputs: change > 0n ? [await this.changeOutput(change)] : [],
+                extAmount: -pieceAmount,
+                fee: pieceFee,
+                relayer: q.relayer,
+                recipient: isHype ? this.router : to,
+                ...(isHype ? { data: encodeAbiParameters([{ type: "address" }], [to]) } : {}),
+                ...(await this.dummy()),
+                prover: await this.prover(),
+            });
+            out.push({ call: { kind, pool, proof, extData }, notBefore: times[i], amount: pieceAmount, to });
+        }
+        return out;
+    }
+    /**
+     * Prove "I hold at least `threshold` of `token` in its vault" without revealing the balance, the notes or who you
+     * are (see funds.ts). Uses 1–3 of your notes; if the balance is spread over more, they're combined first (one
+     * relayed private send). `label` says who it's for and `expiresAt` (unix seconds) when it stops counting.
+     */
+    async proveFunds(token, threshold, o) {
+        const onStatus = o.onStatus ?? (() => { });
+        if (threshold <= 0n)
+            throw new Error("Prove an amount above zero.");
+        if (!o.label.trim() || o.label.length > 80)
+            throw new Error("Say who the proof is for, in up to 80 characters.");
+        const isHype = token.toLowerCase() === this.hypeMarket.token.toLowerCase();
+        const pool = isHype ? this.hypeMarket.pool : this.market(token).pool;
+        const notes = await this.inputsFor(pool, threshold, onStatus);
+        if (notes.length > FUNDS_NOTES)
+            throw new Error("Your balance is in too many pieces: combine it first.");
+        const tree = await this.treeFor(pool, notes);
+        const root = await tree.root();
+        const paths = await Promise.all(notes.map((n) => tree.path(n.leafIndex)));
+        const block = await this.publicClient.getBlockNumber({ cacheTime: 0 });
+        const chainId = this.publicClient.chain?.id ?? (await this.publicClient.getChainId());
+        const context = fundsContext(chainId, pool, o.label, o.expiresAt);
+        const slot = (i, f, empty) => (i < notes.length ? f(notes[i]) : empty);
+        const idx = [0, 1, 2];
+        onStatus("Generating the proof on this device…");
+        const { proof, publicSignals } = await o.prover({
+            root,
+            threshold,
+            context,
+            nullifier: idx.map((i) => slot(i, (n) => n.nullifier, 0n)),
+            used: idx.map((i) => (i < notes.length ? 1n : 0n)),
+            amount: idx.map((i) => slot(i, (n) => n.amount, 0n)),
+            privKey: idx.map((i) => slot(i, (n) => n.privKey, 1n)),
+            blinding: idx.map((i) => slot(i, (n) => n.blinding, 0n)),
+            pathIndices: idx.map((i) => slot(i, (n) => BigInt(n.leafIndex), 0n)),
+            pathElements: idx.map((i) => (i < notes.length ? paths[i].pathElements : new Array(paths[0].pathElements.length).fill(0n))),
+        });
+        return {
+            v: 1,
+            chainId,
+            pool,
+            token: isHype ? this.hypeMarket.token : token,
+            symbol: o.symbol ?? (isHype ? "HYPE" : this.market(token).symbol ?? "tokens"),
+            decimals: o.decimals ?? (isHype ? 18 : this.market(token).decimals ?? 18),
+            threshold: threshold.toString(),
+            label: o.label,
+            expiresAt: o.expiresAt,
+            block: block.toString(),
+            root: publicSignals[0],
+            context: publicSignals[2],
+            nullifiers: publicSignals.slice(3, 3 + FUNDS_NOTES),
+            proof,
+        };
+    }
+    /**
+     * Move notes into a fresh note of your own (a relayed private send to yourself), so whoever holds a proof of funds
+     * that named their nullifiers can't tell when you later spend that money.
+     */
+    async refreshNotes(pool, notes, onStatus = () => { }) {
+        const q = await this.relayFee("transact", pool);
+        const total = notes.reduce((a, x) => a + x.amount, 0n) - q.fee;
+        onStatus("Generating zero-knowledge proof on this device…");
+        const { proof, extData } = await buildTransaction({ tree: await this.treeFor(pool, notes), inputs: notes, outputs: [await this.changeOutput(total)], fee: q.fee, relayer: q.relayer, ...(await this.dummy()), prover: await this.prover() });
+        onStatus("Relaying…");
+        return this.submit({ kind: "transact", pool, proof, extData });
+    }
     /** Private tokens (a launch token, or an asset such as USDC) → any address. */
     async unshieldToken(token, to, amount, onStatus = () => { }) {
         const pool = this.market(token).pool;

package/dist/private/crypto.d.ts

@@ -4,6 +4,9 @@ export declare const LEVELS = 20;
 export declare const MAX_NOTE_AMOUNT: bigint;
 /** Key index of the main spending key; any other index is a one-time key used for a single public entry. */
 export declare const MAIN_KEY = 4294967295;
+/** One-time keys of private receive addresses: RECEIVE_KEY_BASE + n (random one-time keys stay below it in practice). */
+export declare const RECEIVE_KEY_BASE = 3221225472;
+export declare const RECEIVE_KEY_COUNT = 1073741823;
 export declare const randomField: () => bigint;
 export declare const randomKeyIndex: () => number;
 export declare function poseidon(inputs: bigint[]): Promise<bigint>;
@@ -75,6 +78,18 @@ export declare class CloakKeys {
      * bid can't be linked to the account's wallet. Derived from this account's seed, so the same signature always finds
      * it again (on any device).
      */
+    /**
+     * Everything private receive address `n` needs, derived from the seed alone, so any device that unlocks the account
+     * finds the same address again: a one-time key (index RECEIVE_KEY_BASE + n), a blinding, the memo encrypted to this
+     * account's view key (deterministic, so the address is too) and the key that may sign a rescue for it.
+     */
+    receive(n: number): Promise<{
+        keyIndex: number;
+        pubKey: bigint;
+        blinding: bigint;
+        memo: Hex;
+        rescueKey: Hex;
+    }>;
     bidWalletKey(auction: Hex, n: number): Hex;
 }
 export interface Note {

package/dist/private/crypto.js

@@ -10,9 +10,12 @@ export const LEVELS = 20;
 export const MAX_NOTE_AMOUNT = 2n ** 128n;
 /** Key index of the main spending key; any other index is a one-time key used for a single public entry. */
 export const MAIN_KEY = 0xffffffff;
+/** One-time keys of private receive addresses: RECEIVE_KEY_BASE + n (random one-time keys stay below it in practice). */
+export const RECEIVE_KEY_BASE = 0xc0000000;
+export const RECEIVE_KEY_COUNT = 0x3fffffff;
 const fieldMod = (x) => ((x % FIELD_SIZE) + FIELD_SIZE) % FIELD_SIZE;
 export const randomField = () => BigInt(toHex(randomBytes(31)));
-export const randomKeyIndex = () => Number(BigInt(toHex(randomBytes(4))) % 0xfffffffen);
+export const randomKeyIndex = () => Number(BigInt(toHex(randomBytes(4))) % 0xc0000000n); // below RECEIVE_KEY_BASE
 let _poseidon;
 export async function poseidon(inputs) {
     _poseidon ??= await (await import("circomlibjs")).buildPoseidon(); // loaded on first use
@@ -82,6 +85,21 @@ export class CloakKeys {
      * bid can't be linked to the account's wallet. Derived from this account's seed, so the same signature always finds
      * it again (on any device).
      */
+    /**
+     * Everything private receive address `n` needs, derived from the seed alone, so any device that unlocks the account
+     * finds the same address again: a one-time key (index RECEIVE_KEY_BASE + n), a blinding, the memo encrypted to this
+     * account's view key (deterministic, so the address is too) and the key that may sign a rescue for it.
+     */
+    async receive(n) {
+        if (!Number.isInteger(n) || n < 0 || n >= RECEIVE_KEY_COUNT)
+            throw new Error("receive address number out of range");
+        const tag = (t) => toBytes(keccak256(concat([toBytes(t), this.seed, toBytes(toHex(n, { size: 4 }))])));
+        const keyIndex = RECEIVE_KEY_BASE + n;
+        const k = await this.key(keyIndex);
+        const blinding = fieldMod(BigInt(toHex(tag("cloak-receive-blinding-v1"))));
+        const memo = toHex(seal(this.encPub, concat([toBytes(toHex(blinding, { size: 32 })), u32(keyIndex)]), tag("cloak-receive-eph-v1"), tag("cloak-receive-nonce-v1").slice(0, 24)));
+        return { keyIndex, pubKey: k.pubKey, blinding, memo, rescueKey: toHex(tag("cloak-receive-rescue-v1")) };
+    }
     bidWalletKey(auction, n) {
         return keccak256(concat([toBytes("cloak-bidwallet-v1"), this.seed, toBytes(auction.toLowerCase()), toBytes(toHex(n, { size: 4 }))]));
     }
@@ -97,10 +115,8 @@ export async function nullifierOf(n, leafIndex, privKey) {
 // 0x02 | amount(16) | eph(32) | nonce(24) | enc(blinding32 ‖ keyIndex4) + tag(16) — notes created by the router
 //        (the router prepends the public amount; the client only encrypts blinding + key index)
 const INFO = toBytes("cloak-note-v1");
-function seal(encPub, pt) {
-    const eph = randomBytes(32);
+function seal(encPub, pt, eph = randomBytes(32), nonce = randomBytes(24)) {
     const key = hkdf(sha256, x25519.getSharedSecret(eph, encPub), undefined, INFO, 32);
-    const nonce = randomBytes(24);
     return concat([x25519.getPublicKey(eph), nonce, xchacha20poly1305(key, nonce).encrypt(pt)]);
 }
 function open(encPriv, b) {

package/dist/private/funds.d.ts

@@ -0,0 +1,58 @@
+import { type Address, type PublicClient } from "viem";
+import type { RawGroth16 } from "./prover.js";
+import { FUNDS_VERIFYING_KEY } from "./fundsVk.js";
+export { FUNDS_VERIFYING_KEY };
+/**
+ * Proof of funds: "this vault holds at least `threshold` for me, as of block `block`", from up to 3 of the prover's
+ * notes, without the balance, the notes or the owner. The proof reveals those notes' nullifiers, so the verifier can
+ * check none was spent; the flip side is that the verifier could notice when they're spent later, which is why the
+ * app offers to refresh them (a private send to yourself) after proving.
+ *
+ * `context` binds a proof to one purpose: the chain, the vault, a free-text label (who it's for) and an expiry. A proof
+ * shown with a different label or after its expiry fails.
+ */
+export declare const FUNDS_NOTES = 3;
+export interface FundsProof {
+    v: 1;
+    chainId: number;
+    pool: Address;
+    /** the vault's asset, for display (WHYPE for HYPE) */
+    token: Address;
+    symbol: string;
+    decimals: number;
+    threshold: string;
+    label: string;
+    /** unix seconds */
+    expiresAt: number;
+    /** the block the notes were checked unspent at, when proving */
+    block: string;
+    root: string;
+    context: string;
+    nullifiers: string[];
+    proof: RawGroth16;
+}
+export declare function fundsContext(chainId: number, pool: Address, label: string, expiresAt: number): bigint;
+/** Public signals in the circuit's order: root, threshold, context, nullifier[3]. */
+export declare const fundsSignals: (p: FundsProof) => string[];
+/** A proof as a short shareable string (base64url JSON), for a link like `cloak.boblabs.tech/proof#<this>`. */
+export declare function encodeFundsProof(p: FundsProof): string;
+export declare function decodeFundsProof(s: string): FundsProof;
+export interface FundsCheck {
+    ok: boolean;
+    checks: {
+        name: string;
+        ok: boolean;
+        detail: string;
+    }[];
+    /** a backing note was spent after the proof's block (the claim held when made, not now) */
+    spentSince: boolean;
+}
+/**
+ * Check a proof of funds: the zero-knowledge proof itself (against `vk`, by default the key built into the SDK), that it's bound
+ * to this chain, vault, label and expiry, that the vault is a Cloak vault and knows the root, and that no backing note
+ * was spent as of the proof's block. A note spent since is reported, not failed: the claim was true when made.
+ */
+export declare function verifyFundsProof(publicClient: PublicClient, p: FundsProof, vk?: unknown, opts?: {
+    vaults?: Address;
+    now?: number;
+}): Promise<FundsCheck>;

package/dist/private/funds.js

@@ -0,0 +1,65 @@
+import { encodeAbiParameters, keccak256 } from "viem";
+import { cloakVaultsAbi, shieldedPoolAbi } from "../abis.js";
+import { FIELD_SIZE } from "./crypto.js";
+import { FUNDS_VERIFYING_KEY } from "./fundsVk.js";
+export { FUNDS_VERIFYING_KEY };
+/**
+ * Proof of funds: "this vault holds at least `threshold` for me, as of block `block`", from up to 3 of the prover's
+ * notes, without the balance, the notes or the owner. The proof reveals those notes' nullifiers, so the verifier can
+ * check none was spent; the flip side is that the verifier could notice when they're spent later, which is why the
+ * app offers to refresh them (a private send to yourself) after proving.
+ *
+ * `context` binds a proof to one purpose: the chain, the vault, a free-text label (who it's for) and an expiry. A proof
+ * shown with a different label or after its expiry fails.
+ */
+export const FUNDS_NOTES = 3;
+export function fundsContext(chainId, pool, label, expiresAt) {
+    return BigInt(keccak256(encodeAbiParameters([{ type: "string" }, { type: "uint256" }, { type: "address" }, { type: "string" }, { type: "uint64" }], ["cloak-funds-v1", BigInt(chainId), pool, label, BigInt(expiresAt)]))) % FIELD_SIZE;
+}
+/** Public signals in the circuit's order: root, threshold, context, nullifier[3]. */
+export const fundsSignals = (p) => [p.root, p.threshold, p.context, ...p.nullifiers];
+/** A proof as a short shareable string (base64url JSON), for a link like `cloak.boblabs.tech/proof#<this>`. */
+export function encodeFundsProof(p) {
+    const b = new TextEncoder().encode(JSON.stringify(p));
+    return btoa(Array.from(b, (c) => String.fromCharCode(c)).join("")).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function decodeFundsProof(s) {
+    const b = Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));
+    const p = JSON.parse(new TextDecoder().decode(b));
+    if (p?.v !== 1 || !Array.isArray(p.nullifiers) || p.nullifiers.length !== FUNDS_NOTES)
+        throw new Error("not a Cloak proof of funds");
+    return p;
+}
+/**
+ * Check a proof of funds: the zero-knowledge proof itself (against `vk`, by default the key built into the SDK), that it's bound
+ * to this chain, vault, label and expiry, that the vault is a Cloak vault and knows the root, and that no backing note
+ * was spent as of the proof's block. A note spent since is reported, not failed: the claim was true when made.
+ */
+export async function verifyFundsProof(publicClient, p, vk = FUNDS_VERIFYING_KEY, opts = {}) {
+    const checks = [];
+    const add = (name, ok, detail) => checks.push({ name, ok, detail });
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const chainId = publicClient.chain?.id ?? (await publicClient.getChainId());
+    add("Right network", chainId === p.chainId, chainId === p.chainId ? "The proof is for this chain." : `The proof is for chain ${p.chainId}.`);
+    const ctx = fundsContext(p.chainId, p.pool, p.label, p.expiresAt).toString();
+    add("Made for this purpose", ctx === p.context, ctx === p.context ? `Label "${p.label}".` : "The label, vault or expiry was changed after proving.");
+    add("Not expired", p.expiresAt > now, p.expiresAt > now ? `Valid until ${new Date(p.expiresAt * 1000).toISOString().slice(0, 16).replace("T", " ")} UTC.` : "This proof has expired.");
+    const snarkjs = await import("snarkjs");
+    const valid = await snarkjs.groth16.verify(vk, fundsSignals(p), p.proof).catch(() => false);
+    add("Valid zero-knowledge proof", valid, valid ? "The math checks out: the notes exist and add up." : "The proof doesn't verify.");
+    if (opts.vaults) {
+        const isPool = await publicClient.readContract({ address: opts.vaults, abi: cloakVaultsAbi, functionName: "isPool", args: [p.pool] }).catch(() => false);
+        add("A Cloak vault", isPool, isPool ? "The notes are in one of Cloak's permanent vaults." : "That address isn't a Cloak vault.");
+    }
+    const rootOk = await publicClient.readContract({ address: p.pool, abi: shieldedPoolAbi, functionName: "isKnownRoot", args: [BigInt(p.root)] }).catch(() => false);
+    add("Real vault state", rootOk, rootOk ? "The vault knows the tree the notes are in." : "The vault doesn't know this tree.");
+    const live = p.nullifiers.filter((n) => n !== "0");
+    const block = BigInt(p.block);
+    const spentAt = (n, blockNumber) => publicClient.readContract({ address: p.pool, abi: shieldedPoolAbi, functionName: "isSpent", args: [BigInt(n)], ...(blockNumber ? { blockNumber } : {}) });
+    const atBlock = await Promise.all(live.map((n) => spentAt(n, block).catch(() => spentAt(n))));
+    const unspentThen = atBlock.every((x) => !x);
+    add("Unspent when proved", unspentThen && live.length > 0, unspentThen ? `None of the ${live.length} backing note${live.length > 1 ? "s" : ""} had been spent at block ${block}.` : "A backing note had already been spent when the proof was made.");
+    const nowSpent = await Promise.all(live.map((n) => spentAt(n).catch(() => false)));
+    const spentSince = nowSpent.some(Boolean);
+    return { ok: checks.every((c) => c.ok), checks, spentSince };
+}