@cloakely/sdk 0.8.5 → 0.9.0

package/dist/private/fundsVk.d.ts

@@ -0,0 +1,13 @@
+/** Verifying key of the proof-of-funds circuit (fundsProof3), built into the SDK so no download can swap it. Generated
+ * by snarkjs (`zkey export verificationkey`); must match apps/web/public/circuits/fundsProof3_final.zkey. */
+export declare const FUNDS_VERIFYING_KEY: {
+    readonly protocol: "groth16";
+    readonly curve: "bn128";
+    readonly nPublic: 6;
+    readonly vk_alpha_1: readonly ["16428432848801857252194528405604668803277877773566238944394625302971855135431", "16846502678714586896801519656441059708016666274385668027902869494772365009666", "1"];
+    readonly vk_beta_2: readonly [readonly ["16348171800823588416173124589066524623406261996681292662100840445103873053252", "3182164110458002340215786955198810119980427837186618912744689678939861918171"], readonly ["19687132236965066906216944365591810874384658708175106803089633851114028275753", "4920802715848186258981584729175884379674325733638798907835771393452862684714"], readonly ["1", "0"]];
+    readonly vk_gamma_2: readonly [readonly ["10857046999023057135944570762232829481370756359578518086990519993285655852781", "11559732032986387107991004021392285783925812861821192530917403151452391805634"], readonly ["8495653923123431417604973247489272438418190587263600148770280649306958101930", "4082367875863433681332203403145435568316851327593401208105741076214120093531"], readonly ["1", "0"]];
+    readonly vk_delta_2: readonly [readonly ["18266226936584141102298525449969355518905231162547171843332013239103312296001", "4608830916962325122577800770047480184405870923857658614655541326829471425080"], readonly ["11249194154404412529813650344391742555988497818201018073467031259599014123168", "13914512280164755779806285822909794056855533523214639854638450175467117157204"], readonly ["1", "0"]];
+    readonly vk_alphabeta_12: readonly [readonly [readonly ["5275725312362878540782176211860327475781113689246818544623830805017503247034", "700769043921060225711174322502145319612473365595920873303028146383045646735"], readonly ["16577533945604560505206253312979863148043263406037367789711279754781525822966", "9408338099405950952721388539539775335199747835458172188116297223654842340186"], readonly ["12663399896275491035004982800573482669934131767886952660443268164480899034271", "4432711152773877173921024337047412943791122852326272337530740732443732395954"]], readonly [readonly ["13121778684901402722679281862736806628725205381360313795132945954337708567513", "9534744673358550231812045647241180985734073058548683258847806241019905135720"], readonly ["21329152369227346659770815132468371951064045353268189088026893413117512652875", "17209195434408943681049655974234541356066884378594227002358272904159790622854"], readonly ["5346467096835895366917814311591075634165750361894629082277248282132405045579", "15508364027636868967189209273443690126627947943852338696115233789046842639684"]]];
+    readonly IC: readonly [readonly ["15721865684541064263775327890593609717066197085417368299033857075295607606836", "3649085456057800705385232234652618732288045527432498449499319231402629070287", "1"], readonly ["19115754470622874327254680090376640458468168063599461561255078642455456752436", "268352908916366244976924385725787738812432620063272109979171168398146539570", "1"], readonly ["13367241374203588791127524370615543794080582178103402583137031081521492676799", "6075251114291220999136126530229192647359235168426531430677724749887555440659", "1"], readonly ["12899883044790761759445681050714971056055170420962560870231759170060523486580", "132304697271888807017055212104280482514758688081530539577784696329754230011", "1"], readonly ["5690029548563104275791293554608531345222634194836540313233716266820964228742", "932633710232186900549426475808990580341173397726821371850203234208052200421", "1"], readonly ["10335982160444207962727295113015528447870994416465641412585067601211373725633", "7876523262068583666312816278471389215143528952414879583307520358979655103139", "1"], readonly ["16609775028617948028931502278564182714321144256052088546007480321369921357581", "14747851351181528909259712851703464531252723287386778525179881822951720765189", "1"]];
+};

package/dist/private/fundsVk.js

@@ -0,0 +1,121 @@
+/** Verifying key of the proof-of-funds circuit (fundsProof3), built into the SDK so no download can swap it. Generated
+ * by snarkjs (`zkey export verificationkey`); must match apps/web/public/circuits/fundsProof3_final.zkey. */
+export const FUNDS_VERIFYING_KEY = {
+    "protocol": "groth16",
+    "curve": "bn128",
+    "nPublic": 6,
+    "vk_alpha_1": [
+        "16428432848801857252194528405604668803277877773566238944394625302971855135431",
+        "16846502678714586896801519656441059708016666274385668027902869494772365009666",
+        "1"
+    ],
+    "vk_beta_2": [
+        [
+            "16348171800823588416173124589066524623406261996681292662100840445103873053252",
+            "3182164110458002340215786955198810119980427837186618912744689678939861918171"
+        ],
+        [
+            "19687132236965066906216944365591810874384658708175106803089633851114028275753",
+            "4920802715848186258981584729175884379674325733638798907835771393452862684714"
+        ],
+        [
+            "1",
+            "0"
+        ]
+    ],
+    "vk_gamma_2": [
+        [
+            "10857046999023057135944570762232829481370756359578518086990519993285655852781",
+            "11559732032986387107991004021392285783925812861821192530917403151452391805634"
+        ],
+        [
+            "8495653923123431417604973247489272438418190587263600148770280649306958101930",
+            "4082367875863433681332203403145435568316851327593401208105741076214120093531"
+        ],
+        [
+            "1",
+            "0"
+        ]
+    ],
+    "vk_delta_2": [
+        [
+            "18266226936584141102298525449969355518905231162547171843332013239103312296001",
+            "4608830916962325122577800770047480184405870923857658614655541326829471425080"
+        ],
+        [
+            "11249194154404412529813650344391742555988497818201018073467031259599014123168",
+            "13914512280164755779806285822909794056855533523214639854638450175467117157204"
+        ],
+        [
+            "1",
+            "0"
+        ]
+    ],
+    "vk_alphabeta_12": [
+        [
+            [
+                "5275725312362878540782176211860327475781113689246818544623830805017503247034",
+                "700769043921060225711174322502145319612473365595920873303028146383045646735"
+            ],
+            [
+                "16577533945604560505206253312979863148043263406037367789711279754781525822966",
+                "9408338099405950952721388539539775335199747835458172188116297223654842340186"
+            ],
+            [
+                "12663399896275491035004982800573482669934131767886952660443268164480899034271",
+                "4432711152773877173921024337047412943791122852326272337530740732443732395954"
+            ]
+        ],
+        [
+            [
+                "13121778684901402722679281862736806628725205381360313795132945954337708567513",
+                "9534744673358550231812045647241180985734073058548683258847806241019905135720"
+            ],
+            [
+                "21329152369227346659770815132468371951064045353268189088026893413117512652875",
+                "17209195434408943681049655974234541356066884378594227002358272904159790622854"
+            ],
+            [
+                "5346467096835895366917814311591075634165750361894629082277248282132405045579",
+                "15508364027636868967189209273443690126627947943852338696115233789046842639684"
+            ]
+        ]
+    ],
+    "IC": [
+        [
+            "15721865684541064263775327890593609717066197085417368299033857075295607606836",
+            "3649085456057800705385232234652618732288045527432498449499319231402629070287",
+            "1"
+        ],
+        [
+            "19115754470622874327254680090376640458468168063599461561255078642455456752436",
+            "268352908916366244976924385725787738812432620063272109979171168398146539570",
+            "1"
+        ],
+        [
+            "13367241374203588791127524370615543794080582178103402583137031081521492676799",
+            "6075251114291220999136126530229192647359235168426531430677724749887555440659",
+            "1"
+        ],
+        [
+            "12899883044790761759445681050714971056055170420962560870231759170060523486580",
+            "132304697271888807017055212104280482514758688081530539577784696329754230011",
+            "1"
+        ],
+        [
+            "5690029548563104275791293554608531345222634194836540313233716266820964228742",
+            "932633710232186900549426475808990580341173397726821371850203234208052200421",
+            "1"
+        ],
+        [
+            "10335982160444207962727295113015528447870994416465641412585067601211373725633",
+            "7876523262068583666312816278471389215143528952414879583307520358979655103139",
+            "1"
+        ],
+        [
+            "16609775028617948028931502278564182714321144256052088546007480321369921357581",
+            "14747851351181528909259712851703464531252723287386778525179881822951720765189",
+            "1"
+        ]
+    ]
+};

package/dist/private/index.d.ts

@@ -5,3 +5,6 @@ export * from "./tx.js";
 export * from "./client.js";
 export * from "./shared.js";
 export * from "./links.js";
+export * from "./syncState.js";
+export * from "./receive.js";
+export * from "./funds.js";

package/dist/private/index.js

@@ -5,3 +5,6 @@ export * from "./tx.js";
 export * from "./client.js";
 export * from "./shared.js";
 export * from "./links.js";
+export * from "./syncState.js";
+export * from "./receive.js";
+export * from "./funds.js";

package/dist/private/prover.d.ts

@@ -55,3 +55,32 @@ export declare function loadSharedProver(baseUrl?: string | string[], opts?: {
         zkey: string;
     } | null;
 }): Promise<Prover>;
+/** SHA-256 of the proof-of-funds circuit artifacts (`fundsProof3`: up to 3 notes) this SDK version was tested with. */
+export declare const FUNDS_CIRCUIT_HASHES: {
+    readonly wasm: "28056a569b765c4ec62b43d4af005503000e5d7a797cf779f92e66411c3960ef";
+    readonly zkey: "5ae9a8b264b833b711a3bd3dfe64774c4944f363464592085cd564b7ca27e043";
+};
+/** A raw snarkjs Groth16 proof, as `snarkjs.groth16.verify` takes it. */
+export interface RawGroth16 {
+    pi_a: string[];
+    pi_b: string[][];
+    pi_c: string[];
+    protocol?: string;
+    curve?: string;
+}
+export type FundsProver = (input: Record<string, unknown>) => Promise<{
+    proof: RawGroth16;
+    publicSignals: string[];
+}>;
+/** Where the proof-of-funds circuit is served: jsDelivr pinned to the commit that added it, then Cloak's site. */
+export declare const FUNDS_CIRCUITS_CDN = "https://cdn.jsdelivr.net/gh/NECOKIZZ/Cloak@9c949fa0578ee20a78166f8fcfaf7633010b54d0/apps/web/public/circuits";
+export declare const FUNDS_CIRCUITS_SOURCES: string[];
+/** Fetch the proof-of-funds circuit (18 MB, once) and build its prover. Checked against `FUNDS_CIRCUIT_HASHES`. */
+export declare function loadFundsProver(baseUrl?: string | string[], opts?: {
+    hashes?: {
+        wasm: string;
+        zkey: string;
+    } | null;
+}): Promise<FundsProver>;
+/** The proof-of-funds prover from files you already have (Node, or your own hosting). */
+export declare function createFundsProver(wasm: Uint8Array, zkey: Uint8Array): FundsProver;

package/dist/private/prover.js

@@ -110,3 +110,25 @@ export async function loadSharedProver(baseUrl = CIRCUITS_SOURCES, opts = {}) {
     const [wasm, zkey] = await fetchCircuit(baseUrl, ["transactionMA2x2.wasm", "transactionMA2x2_final.zkey"], want, "shared-vault circuit");
     return createSharedProver(wasm, zkey);
 }
+/** SHA-256 of the proof-of-funds circuit artifacts (`fundsProof3`: up to 3 notes) this SDK version was tested with. */
+export const FUNDS_CIRCUIT_HASHES = {
+    wasm: "28056a569b765c4ec62b43d4af005503000e5d7a797cf779f92e66411c3960ef",
+    zkey: "5ae9a8b264b833b711a3bd3dfe64774c4944f363464592085cd564b7ca27e043",
+};
+/** Where the proof-of-funds circuit is served: jsDelivr pinned to the commit that added it, then Cloak's site. */
+export const FUNDS_CIRCUITS_CDN = "https://cdn.jsdelivr.net/gh/NECOKIZZ/Cloak@9c949fa0578ee20a78166f8fcfaf7633010b54d0/apps/web/public/circuits";
+export const FUNDS_CIRCUITS_SOURCES = [FUNDS_CIRCUITS_CDN, CIRCUITS_URL];
+/** Fetch the proof-of-funds circuit (18 MB, once) and build its prover. Checked against `FUNDS_CIRCUIT_HASHES`. */
+export async function loadFundsProver(baseUrl = FUNDS_CIRCUITS_SOURCES, opts = {}) {
+    const want = opts.hashes === undefined ? FUNDS_CIRCUIT_HASHES : opts.hashes;
+    const [wasm, zkey] = await fetchCircuit(baseUrl, ["fundsProof3.wasm", "fundsProof3_final.zkey"], want, "proof-of-funds circuit");
+    return createFundsProver(wasm, zkey);
+}
+/** The proof-of-funds prover from files you already have (Node, or your own hosting). */
+export function createFundsProver(wasm, zkey) {
+    return async (input) => {
+        const snarkjs = await import("snarkjs");
+        const { proof, publicSignals } = await snarkjs.groth16.fullProve(Object.fromEntries(Object.entries(input).map(([k, v]) => [k, str(v)])), wasm, zkey);
+        return { proof: proof, publicSignals: publicSignals };
+    };
+}

package/dist/private/receive.d.ts

@@ -0,0 +1,52 @@
+import { type Address, type Hex } from "viem";
+import type { CloakKeys } from "./crypto.js";
+/**
+ * Private receive addresses (CloakReceive). Each is an ordinary-looking address, derived offline from the account seed
+ * and a number n, that anyone can pay with a plain transfer: an exchange withdrawal, a bridge, any wallet. A relayer
+ * then delivers what arrived into the vault as this account's note (CloakReceive.deliver), keeping at most `maxFeeBps`.
+ * The address has no private key: only the vault (or the owner's rescue signature) can ever move what's there.
+ * Use each address once: payments to the same address are visibly linked to each other.
+ */
+export interface ReceiveParams {
+    pubKey: bigint;
+    blinding: bigint;
+    memo: Hex;
+    maxFeeBps: number;
+    rescuer: Address;
+}
+export interface ReceiveAddress {
+    n: number;
+    address: Address;
+    params: ReceiveParams;
+}
+/** The most a relayer may keep for delivering, unless the app asks for less (1%). */
+export declare const RECEIVE_MAX_FEE_BPS = 100;
+export declare function receiveSalt(p: ReceiveParams): Hex;
+/** The address CloakReceive at `factory` gives these parameters (`boxCodeHash` = CloakReceive.boxCodeHash()). */
+export declare function receiveAddressOf(factory: Address, boxCodeHash: Hex, p: ReceiveParams): Address;
+/** Receive address `n` of this account (offline: nothing goes on chain until someone pays it). */
+export declare function receiveAddress(keys: CloakKeys, factory: Address, boxCodeHash: Hex, n: number, maxFeeBps?: number): Promise<ReceiveAddress>;
+/**
+ * The owner's signature for getting something out of receive address `n` that the vaults can't take (an NFT, a token
+ * without a vault): CloakReceive.rescue(params, target, value, data, signature). `nonce` = CloakReceive.nonces(address).
+ */
+export declare function signReceiveRescue(keys: CloakKeys, n: number, o: {
+    factory: Address;
+    chainId: number;
+    box: Address;
+    target: Address;
+    value?: bigint;
+    data: Hex;
+    nonce: bigint;
+}): Promise<Hex>;
+/** Ask a Cloak relayer to watch receive addresses and deliver what arrives (`POST /receive`). */
+export declare function watchReceive(url: string, list: ReceiveAddress[]): Promise<void>;
+export interface ReceiveDelivery {
+    token: Address;
+    amount: string;
+    fee: string;
+    txHash: Hex;
+    at: number;
+}
+/** What a relayer delivered from these receive addresses (`GET /receive?addresses=`). */
+export declare function receiveDeliveries(url: string, addresses: Address[]): Promise<Record<string, ReceiveDelivery[]>>;

package/dist/private/receive.js

@@ -0,0 +1,45 @@
+import { encodeAbiParameters, getContractAddress, keccak256 } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+/** The most a relayer may keep for delivering, unless the app asks for less (1%). */
+export const RECEIVE_MAX_FEE_BPS = 100;
+export function receiveSalt(p) {
+    return keccak256(encodeAbiParameters([{ type: "uint256" }, { type: "uint256" }, { type: "bytes32" }, { type: "uint16" }, { type: "address" }], [p.pubKey, p.blinding, keccak256(p.memo), p.maxFeeBps, p.rescuer]));
+}
+/** The address CloakReceive at `factory` gives these parameters (`boxCodeHash` = CloakReceive.boxCodeHash()). */
+export function receiveAddressOf(factory, boxCodeHash, p) {
+    return getContractAddress({ opcode: "CREATE2", from: factory, salt: receiveSalt(p), bytecodeHash: boxCodeHash });
+}
+/** Receive address `n` of this account (offline: nothing goes on chain until someone pays it). */
+export async function receiveAddress(keys, factory, boxCodeHash, n, maxFeeBps = RECEIVE_MAX_FEE_BPS) {
+    const r = await keys.receive(n);
+    const params = { pubKey: r.pubKey, blinding: r.blinding, memo: r.memo, maxFeeBps, rescuer: privateKeyToAccount(r.rescueKey).address };
+    return { n, address: receiveAddressOf(factory, boxCodeHash, params), params };
+}
+/**
+ * The owner's signature for getting something out of receive address `n` that the vaults can't take (an NFT, a token
+ * without a vault): CloakReceive.rescue(params, target, value, data, signature). `nonce` = CloakReceive.nonces(address).
+ */
+export async function signReceiveRescue(keys, n, o) {
+    const { rescueKey } = await keys.receive(n);
+    return privateKeyToAccount(rescueKey).signTypedData({
+        domain: { name: "CloakReceive", chainId: o.chainId, verifyingContract: o.factory },
+        types: { Rescue: [{ name: "box", type: "address" }, { name: "target", type: "address" }, { name: "value", type: "uint256" }, { name: "data", type: "bytes32" }, { name: "nonce", type: "uint256" }] },
+        primaryType: "Rescue",
+        message: { box: o.box, target: o.target, value: o.value ?? 0n, data: keccak256(o.data), nonce: o.nonce },
+    });
+}
+const json = (v) => JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toString() : x));
+/** Ask a Cloak relayer to watch receive addresses and deliver what arrives (`POST /receive`). */
+export async function watchReceive(url, list) {
+    const res = await fetch(`${url.replace(/\/$/, "")}/receive`, { method: "POST", headers: { "content-type": "application/json" }, body: json({ addresses: list.map((x) => ({ address: x.address, params: x.params })) }), signal: AbortSignal.timeout(30_000) });
+    if (!res.ok)
+        throw new Error((await res.json().catch(() => ({}))).error ?? `watch failed (${res.status})`);
+}
+/** What a relayer delivered from these receive addresses (`GET /receive?addresses=`). */
+export async function receiveDeliveries(url, addresses) {
+    const res = await fetch(`${url.replace(/\/$/, "")}/receive?addresses=${addresses.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.deliveries ?? {};
+}

package/dist/private/shared.d.ts

@@ -1,5 +1,6 @@
 import { type Address, type Hex } from "viem";
 import { type Wallet } from "../cloak.js";
+import { type PublicLeaves } from "./syncState.js";
 import type { ProofArgs, Prover } from "./prover.js";
 import { type ExtData, type OwnedNote } from "./tx.js";
 import type { CloakPrivate, RelayQuote, Status } from "./client.js";
@@ -76,6 +77,8 @@ export declare class SharedVaultClient {
     private scannedUpTo;
     private notes;
     private nextBlock;
+    /** Started from a cache rather than the chain: a gap means rescan. */
+    private seeded;
     constructor(priv: CloakPrivate, vault: Address, router: Address, prover: () => Promise<Prover>, submit: SharedSubmitter, fromBlock?: bigint, 
     /** SharedBatcher: batch rounds that hide trade size for these tokens. */
     batcher?: Address | undefined);
@@ -88,7 +91,16 @@ export declare class SharedVaultClient {
     /** Let a settled Uniswap launch's token into the vault (anyone can; costs gas). */
     admit(wallet: Wallet, factory: Address, launchIndex: bigint): Promise<Hex>;
     /** Pull new notes, find which are ours and which token each holds, refresh spent flags. */
+    private inflight?;
+    /** One sync at a time (callers at the same moment share it), so a new note is never counted twice. */
     sync(): Promise<OwnedNote[]>;
+    private syncOnce;
+    /** Start from public leaves (a keeper's GET /leaves) if nothing is synced yet and they hash to a root the vault knows. */
+    seedLeaves(src: PublicLeaves): Promise<boolean>;
+    /** What sync has learned, to keep on this device (encrypted) and hand back to `importSync`. No spending keys inside. */
+    exportSync(): string;
+    /** Load a state from `exportSync` (ignored if anything is synced already, or if a note doesn't match this account). */
+    importSync(data: string): Promise<boolean>;
     /** Private balance of `token` in the shared vault. */
     balance(token: Address): Promise<bigint>;
     /** Every token this account holds privately in the shared vault. */

package/dist/private/shared.js

@@ -3,6 +3,7 @@ import { cloakAuctionAbi, cloakPairAbi, sharedBatcherAbi, sharedRouterAbi, share
 import { Cloak } from "../cloak.js";
 import { MAIN_KEY, encryptFullMemo, encryptRouterMemo, noteCommitment, nullifierOf, parseCloakAddress, randomField, randomKeyIndex, readMemo } from "./crypto.js";
 import { MerkleTree } from "./tree.js";
+import { fromJson, leavesRoot, toJson } from "./syncState.js";
 import { ORDER_DATA_ABI, buildTransaction, selectNotes, splitStandard } from "./tx.js";
 /**
  * The shared launch-token vault (testnet experiment): one private vault for every Cloak launch token that opens on
@@ -100,6 +101,8 @@ export class SharedVaultClient {
     scannedUpTo = 0;
     notes = [];
     nextBlock;
+    /** Started from a cache rather than the chain: a gap means rescan. */
+    seeded = false;
     constructor(priv, vault, router, prover, submit, fromBlock = 0n, 
     /** SharedBatcher: batch rounds that hide trade size for these tokens. */
     batcher) {
@@ -119,14 +122,17 @@ export class SharedVaultClient {
     async loadTokens() {
         const c = { address: this.vault, abi: sharedVaultAbi };
         const n = Number(await this.pub.readContract({ ...c, functionName: "tokensCount" }));
-        for (let i = this.tokens.length; i < n; i++) {
-            const token = await this.pub.readContract({ ...c, functionName: "tokens", args: [BigInt(i)] });
+        const from = this.tokens.length;
+        const more = await Promise.all(Array.from({ length: Math.max(0, n - from) }, async (_, j) => {
+            const token = await this.pub.readContract({ ...c, functionName: "tokens", args: [BigInt(from + j)] });
             const [market, symbol] = await Promise.all([
                 this.pub.readContract({ ...c, functionName: "marketOf", args: [token] }),
                 this.pub.readContract({ address: token, abi: ERC20, functionName: "symbol" }).catch(() => "?"),
             ]);
-            this.tokens.push({ token, market, symbol });
-        }
+            return { token, market, symbol };
+        }));
+        if (this.tokens.length === from)
+            this.tokens.push(...more); // a parallel call may have loaded them already
         return this.tokens;
     }
     /** Whether `token` is in the shared vault (reads the vault's list if it isn't known yet). */
@@ -152,7 +158,13 @@ export class SharedVaultClient {
         return h;
     }
     /** Pull new notes, find which are ours and which token each holds, refresh spent flags. */
+    inflight;
+    /** One sync at a time (callers at the same moment share it), so a new note is never counted twice. */
     async sync() {
+        this.inflight ??= this.syncOnce().finally(() => (this.inflight = undefined));
+        return this.inflight;
+    }
+    async syncOnce() {
         if (!this.tokens.length)
             await this.loadTokens();
         const latest = await this.pub.getBlockNumber({ cacheTime: 0 });
@@ -170,6 +182,15 @@ export class SharedVaultClient {
         let n = 0;
         while (n < this.leaves.length && this.leaves[n].index === n)
             n++;
+        if (n < this.leaves.length && this.seeded) {
+            // the cache stopped short of where the chain picked up: forget it and scan from the start
+            this.leaves = [];
+            this.scannedUpTo = 0;
+            this.notes = [];
+            this.nextBlock = this.fromBlock;
+            this.seeded = false;
+            return this.syncOnce();
+        }
         let reloaded = false;
         for (const l of this.leaves.slice(this.scannedUpTo, n)) {
             const m = readMemo(this.priv.keys.encPriv, l.memo);
@@ -203,6 +224,51 @@ export class SharedVaultClient {
         this.notes.forEach((x, i) => (x.spent = Boolean(flags[i])));
         return this.notes.filter((x) => !x.spent);
     }
+    /** Start from public leaves (a keeper's GET /leaves) if nothing is synced yet and they hash to a root the vault knows. */
+    async seedLeaves(src) {
+        if (this.leaves.length || this.scannedUpTo)
+            return false;
+        const root = await leavesRoot(src.leaves);
+        if (root === null)
+            return false;
+        const known = await this.pub.readContract({ address: this.vault, abi: sharedVaultAbi, functionName: "isKnownRoot", args: [root] }).catch(() => false);
+        if (!known)
+            return false;
+        this.leaves = src.leaves.map((l) => ({ ...l }));
+        this.nextBlock = src.block + 1n;
+        this.seeded = true;
+        return true;
+    }
+    /** What sync has learned, to keep on this device (encrypted) and hand back to `importSync`. No spending keys inside. */
+    exportSync() {
+        return toJson({ v: 1, leaves: this.leaves.map((l, i) => (i < this.scannedUpTo ? { ...l, memo: "0x" } : l)), scannedUpTo: this.scannedUpTo, nextBlock: this.nextBlock, notes: this.notes.map(({ privKey: _, ...n }) => n) });
+    }
+    /** Load a state from `exportSync` (ignored if anything is synced already, or if a note doesn't match this account). */
+    async importSync(data) {
+        if (this.leaves.length || this.scannedUpTo)
+            return false;
+        try {
+            const o = fromJson(data);
+            if (o.v !== 1)
+                return false;
+            const notes = [];
+            for (const n of o.notes) {
+                const key = await this.priv.keys.key(n.keyIndex);
+                if (key.pubKey !== n.pubKey)
+                    return false;
+                notes.push({ ...n, privKey: key.privKey });
+            }
+            this.leaves = o.leaves;
+            this.scannedUpTo = o.scannedUpTo;
+            this.nextBlock = o.nextBlock;
+            this.notes = notes;
+            this.seeded = true;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /** Private balance of `token` in the shared vault. */
     async balance(token) {
         const t = asNum(token);

package/dist/private/syncState.d.ts

@@ -0,0 +1,28 @@
+import type { Address, Hex } from "viem";
+/** One leaf of a vault's tree, as its NewCommitment event has it. */
+export interface Leaf {
+    index: number;
+    commitment: bigint;
+    memo: Hex;
+}
+/** A vault's public leaves up to `block` (from a keeper's GET /leaves). */
+export interface PublicLeaves {
+    pool: Address;
+    block: bigint;
+    leaves: Leaf[];
+}
+/** Leaves per tree (each vault starts a new tree, an epoch, when one fills). */
+export declare const LEAVES_PER_EPOCH: number;
+/**
+ * Every vault's public leaves from a keeper's `GET /leaves`, keyed by lowercase vault address (empty on any error, so
+ * callers just scan the chain). Nothing in the request identifies the caller's notes: it is the same for everyone.
+ */
+export declare function fetchLeaves(keeperUrl: string): Promise<Map<string, PublicLeaves>>;
+/**
+ * Whether `leaves` can stand in for scanning the chain: indexes 0, 1, 2… with no gap, all in the first tree, and
+ * hashing to `root` (the caller checks the vault knows that root). The memos aren't covered by the root: a bad memo
+ * can only hide one of your notes from the scan, never move money, and the next full rescan finds it.
+ */
+export declare function leavesRoot(leaves: Leaf[]): Promise<bigint | null>;
+export declare const toJson: (v: unknown) => string;
+export declare const fromJson: <T>(s: string) => T;

package/dist/private/syncState.js

@@ -0,0 +1,40 @@
+import { MerkleTree } from "./tree.js";
+/** Leaves per tree (each vault starts a new tree, an epoch, when one fills). */
+export const LEAVES_PER_EPOCH = 2 ** 20;
+/**
+ * Every vault's public leaves from a keeper's `GET /leaves`, keyed by lowercase vault address (empty on any error, so
+ * callers just scan the chain). Nothing in the request identifies the caller's notes: it is the same for everyone.
+ */
+export async function fetchLeaves(keeperUrl) {
+    const out = new Map();
+    try {
+        const r = await fetch(`${keeperUrl.replace(/\/$/, "")}/leaves`);
+        if (!r.ok)
+            return out;
+        const body = (await r.json());
+        for (const v of body.vaults ?? []) {
+            out.set(v.pool.toLowerCase(), { pool: v.pool, block: BigInt(v.block), leaves: v.leaves.map(([index, c, memo]) => ({ index, commitment: BigInt(c), memo })) });
+        }
+    }
+    catch { }
+    return out;
+}
+/**
+ * Whether `leaves` can stand in for scanning the chain: indexes 0, 1, 2… with no gap, all in the first tree, and
+ * hashing to `root` (the caller checks the vault knows that root). The memos aren't covered by the root: a bad memo
+ * can only hide one of your notes from the scan, never move money, and the next full rescan finds it.
+ */
+export async function leavesRoot(leaves) {
+    if (!leaves.length || leaves.length > LEAVES_PER_EPOCH)
+        return null;
+    for (let i = 0; i < leaves.length; i++)
+        if (leaves[i].index !== i)
+            return null;
+    const t = new MerkleTree();
+    t.leaves = leaves.map((l) => l.commitment);
+    return t.root();
+}
+const revive = (_k, v) => (v && typeof v === "object" && "$n" in v ? BigInt(v.$n) : v);
+const replace = (_k, v) => (typeof v === "bigint" ? { $n: v.toString() } : v);
+export const toJson = (v) => JSON.stringify(v, replace);
+export const fromJson = (s) => JSON.parse(s, revive);

package/dist/registry.d.ts

@@ -44,6 +44,8 @@ export interface CloakRegistry {
     sharedRouter?: Address;
     /** SharedBatcher: batch rounds for the shared vault's tokens. */
     sharedBatcher?: Address;
+    /** CloakReceive: private receive addresses (a plain transfer becomes the owner's note). */
+    receive?: Address;
     factory: Address;
     factoryBlock: bigint;
     /** Earlier factories of the current version (a factory added next to the first), newest first. */

package/dist/registry.js

@@ -36,6 +36,7 @@ export async function readRegistry(publicClient, config) {
         sharedBlock: newest("shared")?.startBlock,
         sharedRouter: newest("sharedRouter")?.addr,
         sharedBatcher: newest("sharedBatcher")?.addr,
+        receive: newest("receive")?.addr,
         factory: factory.addr,
         factoryBlock: factory.startBlock,
         earlierFactories: entries.filter((e) => e.kind === "factory" && e.version === factory.version && e.addr !== factory.addr).reverse().map((e) => e.addr),

package/dist/spots.js

@@ -36,7 +36,7 @@ export class CloakSpots {
         if (!partner || partner.length > 200)
             throw new Error("Name the partner collection (up to 200 characters).");
         const days = o.walletDays ?? SPOT_DEFAULT_WALLET_DAYS;
-        if (!(days > 0 && days <= SPOT_MAX_WALLET_DAYS))
+        if (!(days >= 1 && days <= SPOT_MAX_WALLET_DAYS))
             throw new Error(`Winners get 1 to ${SPOT_MAX_WALLET_DAYS} days to name wallets.`);
         const { drop, txHash } = await this.drops.create({ ...o, baseURI: o.baseURI ?? "", maxPerBid: o.maxPerBid ?? 1, spots: { partner } });
         const s = await this.drops.get(drop);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloakely/sdk",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "Cloak on Elysium: sealed-bid token launches, sealed NFT drops and WL spot sales, and private trading (shielded balances, private swaps, batch auctions, private sends) with on-device zero-knowledge proofs.",
   "keywords": [
     "cloak",