@cloakely/sdk 0.0.0-stage → 0.2.1

package/dist/private/client.js

@@ -0,0 +1,539 @@
+import { encodeAbiParameters, parseEventLogs, zeroAddress } from "viem";
+import { cloakMigratorAbi, cloakPairAbi, privateBatcherAbi, privateRouterAbi, shieldedPoolAbi } from "../abis.js";
+import { ACCOUNT_MESSAGE, ACCOUNT_TYPED_DATA, CloakKeys, MAIN_KEY, noteCommitment, encryptFullMemo, encryptRouterMemo, formatCloakAddress, nullifierOf, parseCloakAddress, randomField, randomKeyIndex, readMemo, } from "./crypto.js";
+import { MerkleTree } from "./tree.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;
+const epochOf = (globalIndex) => Math.floor(globalIndex / 2 ** EPOCH_BITS);
+const positionOf = (globalIndex) => globalIndex % 2 ** EPOCH_BITS;
+const json = (v) => JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toString() : x));
+/** POST shielded calls to a Cloak relayer (`services/keeper` serves `/relay` and `/quote`). */
+export function relayerSubmitter(url) {
+    const base = url.replace(/\/$/, "");
+    const submit = async (call) => {
+        const res = await fetch(`${base}/relay`, { method: "POST", headers: { "content-type": "application/json" }, body: json(call) });
+        const out = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new Error(out.error ?? `relay failed (${res.status})`);
+        return out.txHash;
+    };
+    submit.quote = async (kind, pool) => {
+        const res = await fetch(`${base}/quote?kind=${kind}&pool=${pool}`);
+        const out = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new Error(out.error ?? `relayer quote failed (${res.status})`);
+        return { relayer: out.relayer, fee: BigInt(out.fee) };
+    };
+    return submit;
+}
+/** Submit from a wallet directly — works, but that wallet pays gas and appears as the sender. Use for tests/relayers. */
+export function walletSubmitter(publicClient, wallet, router, batcher, migrator) {
+    return async (call) => {
+        // viem cannot infer the nested tuple types through the union; the shapes match the ABI exactly.
+        if (call.kind === "migrate" && !migrator)
+            throw new Error("no migrator configured");
+        const req = call.kind === "migrate"
+            ? { address: migrator, abi: cloakMigratorAbi, functionName: "migrate", args: [call.pool, call.proof, call.extData] }
+            : call.kind === "placeOrder"
+                ? { address: batcher, abi: privateBatcherAbi, functionName: "placeOrder", args: [call.pool, call.proof, call.extData] }
+                : call.kind === "privateSwap"
+                    ? { address: router, abi: privateRouterAbi, functionName: "privateSwap", args: [call.pool, call.proof, call.extData] }
+                    : call.kind === "unshieldHype"
+                        ? { address: router, abi: privateRouterAbi, functionName: "unshieldHype", args: [call.proof, call.extData] }
+                        : { address: call.pool, abi: shieldedPoolAbi, functionName: "transact", args: [call.proof, call.extData] };
+        if (call.kind === "placeOrder" && !batcher)
+            throw new Error("no batcher configured");
+        // Pad the estimate: state can change between estimation and inclusion (e.g. an order landing in a new batch round
+        // writes fresh storage, ~60k more gas). Unused gas is refunded.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const est = await publicClient.estimateContractGas({ ...req, account: wallet.account });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const hash = await wallet.writeContract({ ...req, gas: (est * 13n) / 10n + 100000n });
+        const r = await publicClient.waitForTransactionReceipt({ hash });
+        if (r.status !== "success")
+            throw new Error(`shielded call reverted: ${hash}`);
+        return hash;
+    };
+}
+/**
+ * Private trading for Cloak launch tokens on Elysium.
+ *
+ *   shieldHype   public HYPE → private balance (one-time key, so deposits are unlinkable)
+ *   buy / sell   private balance → launch token / back, via the PrivateRouter and the launch's CloakPair,
+ *                proven on this device and submitted by a relayer
+ *   unshield     private HYPE → any address
+ */
+export class CloakPrivate {
+    publicClient;
+    router;
+    keys;
+    prover;
+    submit;
+    fromBlock;
+    batcher;
+    migrator;
+    pools = new Map();
+    markets = [];
+    constructor(publicClient, router, keys, prover, submit, fromBlock = 0n, batcher, migrator) {
+        this.publicClient = publicClient;
+        this.router = router;
+        this.keys = keys;
+        this.prover = prover;
+        this.submit = submit;
+        this.fromBlock = fromBlock;
+        this.batcher = batcher;
+        this.migrator = migrator;
+    }
+    /**
+     * Derive the private keys from one EIP-712 signature bound to this chain and router, so a signature asked for by any
+     * other site or contract can't reproduce them. With `verify`, the wallet signs twice and the keys are refused if the
+     * two signatures differ (some smart and MPC wallets sign differently each time, which would hide earlier notes).
+     */
+    static async keysFromWallet(wallet, opts) {
+        const req = { account: wallet.account, ...ACCOUNT_TYPED_DATA(opts.chainId, opts.router) };
+        const sig = await wallet.signTypedData(req);
+        if (opts.verify) {
+            const again = await wallet.signTypedData(req);
+            if (again.toLowerCase() !== sig.toLowerCase()) {
+                throw new Error("This wallet gives a different signature each time, so it can't hold a Cloak private account. Use a standard wallet such as MetaMask or Rabby.");
+            }
+        }
+        return CloakKeys.fromSignature(sig);
+    }
+    /** Keys of the first Cloak deployment (plain signed message). Only needed to move an old balance across. */
+    static async legacyKeysFromWallet(wallet) {
+        const sig = await wallet.signMessage({ account: wallet.account, message: ACCOUNT_MESSAGE });
+        return CloakKeys.fromSignature(sig);
+    }
+    async loadMarkets() {
+        const c = { address: this.router, abi: privateRouterAbi };
+        const n = await this.publicClient.readContract({ ...c, functionName: "tokensCount" });
+        const out = [];
+        for (let i = 0n; i < n; i++) {
+            const token = await this.publicClient.readContract({ ...c, functionName: "tokens", args: [i] });
+            const [pool, pair] = await Promise.all([
+                this.publicClient.readContract({ ...c, functionName: "poolOf", args: [token] }),
+                this.publicClient.readContract({ ...c, functionName: "pairOf", args: [token] }),
+            ]);
+            out.push({ token, pool, pair: i === 0n ? null : pair });
+        }
+        this.markets = out;
+        return out;
+    }
+    get hypeMarket() {
+        const m = this.markets[0];
+        if (!m)
+            throw new Error("call loadMarkets() first");
+        return m;
+    }
+    market(token) {
+        const m = this.markets.find((x) => x.token.toLowerCase() === token.toLowerCase());
+        if (!m)
+            throw new Error("no private market for this token (createPool after settlement)");
+        return m;
+    }
+    state(pool) {
+        let s = this.pools.get(pool.toLowerCase());
+        if (!s) {
+            s = { leaves: [], scannedUpTo: 0, fromBlock: this.fromBlock, notes: [] };
+            this.pools.set(pool.toLowerCase(), s);
+        }
+        return s;
+    }
+    /** Pull new leaves from the pool's events, trial-decrypt them, and refresh spent flags. */
+    async sync(pool) {
+        const s = this.state(pool);
+        const latest = await this.publicClient.getBlockNumber({ cacheTime: 0 });
+        if (latest >= s.fromBlock) {
+            const logs = await this.publicClient.getContractEvents({
+                address: pool,
+                abi: shieldedPoolAbi,
+                eventName: "NewCommitment",
+                fromBlock: s.fromBlock,
+                toBlock: latest,
+                strict: true,
+            });
+            const known = new Set(s.leaves.map((l) => l.index));
+            for (const l of logs) {
+                const index = Number(l.args.index);
+                if (!known.has(index))
+                    s.leaves.push({ index, commitment: l.args.commitment, memo: l.args.encryptedOutput });
+            }
+            s.leaves.sort((a, b) => a.index - b.index);
+            s.fromBlock = latest + 1n;
+        }
+        // only the contiguous prefix forms a valid tree
+        let n = 0;
+        while (n < s.leaves.length && s.leaves[n].index === n)
+            n++;
+        for (const l of s.leaves.slice(s.scannedUpTo, n)) {
+            const m = readMemo(this.keys.encPriv, l.memo);
+            if (!m || m.amount === 0n)
+                continue;
+            const k = await this.keys.key(m.keyIndex);
+            const note = { amount: m.amount, pubKey: k.pubKey, blinding: m.blinding };
+            if ((await noteCommitment(note)) !== l.commitment)
+                continue; // forged memo → ignored
+            const pos = positionOf(l.index);
+            s.notes.push({ ...note, leafIndex: pos, epoch: epochOf(l.index), keyIndex: m.keyIndex, privKey: k.privKey, commitment: l.commitment, nullifier: await nullifierOf(note, pos, k.privKey), spent: false });
+        }
+        s.scannedUpTo = n;
+        const flags = await Promise.all(s.notes.map((x) => (x.spent ? true : this.publicClient.readContract({ address: pool, abi: shieldedPoolAbi, functionName: "isSpent", args: [x.nullifier] }))));
+        s.notes.forEach((x, i) => (x.spent = Boolean(flags[i])));
+        return s.notes.filter((x) => !x.spent);
+    }
+    async balance(pool) {
+        return (await this.sync(pool)).reduce((a, x) => a + x.amount, 0n);
+    }
+    /** The most a single relayed call of this kind can move from `pool`: the balance minus the relayer's fee. */
+    async maxSpendable(pool, kind = "transact") {
+        const [bal, q] = await Promise.all([this.balance(pool), this.relayFee(kind, pool)]);
+        return bal > q.fee ? bal - q.fee : 0n;
+    }
+    /** The Merkle tree of one epoch (default: the epoch the given notes live in, else the newest). */
+    async tree(pool, epoch) {
+        const s = this.state(pool);
+        const leaves = s.leaves.slice(0, s.scannedUpTo);
+        const e = epoch ?? (leaves.length ? epochOf(leaves[leaves.length - 1].index) : 0);
+        const t = new MerkleTree();
+        for (const l of leaves)
+            if (epochOf(l.index) === e)
+                await t.insert(l.commitment);
+        return t;
+    }
+    treeFor(pool, inputs) {
+        return this.tree(pool, inputs.length ? inputs[0].epoch : undefined);
+    }
+    /** The relayer's fee for this call (0 when submitting from a wallet). */
+    async relayFee(kind, pool) {
+        return this.submit.quote ? this.submit.quote(kind, pool) : { relayer: zeroAddress, fee: 0n };
+    }
+    /** What a withdrawal of `amount` from `pool` delivers after the protocol's withdrawal fee. */
+    async afterFee(pool, amount) {
+        // pools of the first deployment have no withdrawal fee (and no afterFee)
+        return this.publicClient.readContract({ address: pool, abi: shieldedPoolAbi, functionName: "afterFee", args: [amount] }).catch(() => amount);
+    }
+    async changeOutput(amount) {
+        const main = await this.keys.main();
+        return { amount, pubKey: main.pubKey, memo: (b) => encryptFullMemo(this.keys.encPub, amount, b, MAIN_KEY) };
+    }
+    async dummy() {
+        const main = await this.keys.main();
+        return { dummyPubKey: main.pubKey, dummyMemo: (b) => encryptFullMemo(this.keys.encPub, 0n, b, MAIN_KEY) };
+    }
+    /**
+     * Get 1–2 notes (from one tree epoch) covering `target`, merging notes privately first when the balance is spread
+     * across many. Each merge is a relayed transaction and pays the relayer's fee from the merged notes.
+     */
+    async inputsFor(pool, target, onStatus) {
+        for (let round = 0; round < 6; round++) {
+            const live = await this.sync(pool);
+            const byEpoch = new Map();
+            for (const n of live)
+                byEpoch.set(n.epoch ?? 0, [...(byEpoch.get(n.epoch ?? 0) ?? []), n]);
+            const sum = (ns) => ns.reduce((a, x) => a + x.amount, 0n);
+            const groups = [...byEpoch.values()].sort((a, b) => (sum(b) > sum(a) ? 1 : -1));
+            if (!groups.length || sum(groups[0]) < target) {
+                throw new Error(sum(live) >= target ? "balance is split across tree epochs: send it in two parts" : "insufficient private balance");
+            }
+            const pick = selectNotes(groups[0], target);
+            if ("inputs" in pick)
+                return pick.inputs;
+            onStatus("Combining private notes first…");
+            const q = await this.relayFee("transact", pool);
+            const total = sum(pick.merge) - q.fee;
+            const { proof, extData } = await buildTransaction({
+                tree: await this.treeFor(pool, pick.merge),
+                inputs: pick.merge,
+                outputs: [await this.changeOutput(total)],
+                fee: q.fee,
+                relayer: q.relayer,
+                ...(await this.dummy()),
+                prover: await this.prover(),
+            });
+            const h = await this.submit({ kind: "transact", pool, proof, extData });
+            await this.publicClient.waitForTransactionReceipt({ hash: h });
+        }
+        throw new Error("too many notes to combine");
+    }
+    // ───────────── public → private ─────────────
+    /** Public HYPE → private balance. This one step is public (your wallet deposits); everything after is not. */
+    async shieldHype(wallet, amount) {
+        const keyIndex = randomKeyIndex();
+        const k = await this.keys.key(keyIndex);
+        const blinding = randomField();
+        const hash = await wallet.writeContract({
+            address: this.router,
+            abi: privateRouterAbi,
+            functionName: "shieldHype",
+            args: [k.pubKey, blinding, encryptRouterMemo(this.keys.encPub, blinding, keyIndex)],
+            value: amount,
+        });
+        const r = await this.publicClient.waitForTransactionReceipt({ hash });
+        if (r.status !== "success")
+            throw new Error("shield reverted");
+        return hash;
+    }
+    // ───────────── batch auctions (hide trade size) ─────────────
+    async roundInfo() {
+        if (!this.batcher)
+            throw new Error("no batcher configured");
+        const c = { address: this.batcher, abi: privateBatcherAbi };
+        const [round, roundSecs] = await Promise.all([
+            this.publicClient.readContract({ ...c, functionName: "currentRound" }),
+            this.publicClient.readContract({ ...c, functionName: "roundSecs" }),
+        ]);
+        return { round, roundSecs: Number(roundSecs), endsAt: Number((round + 1n) * roundSecs) };
+    }
+    /**
+     * Batched private buy/sell. The amount is split into standard-size orders (1, 2, 5 × 10ⁿ), each placed from the
+     * private balance by the relayer into the current round. When the round ends, buys and sells cross at the pool's
+     * mid-price and only the net trades through the pool; outputs arrive as private notes. Observers can't tell how
+     * much any one trader moved. Any remainder that isn't a standard size stays in your private balance.
+     */
+    async batch(token, side, amount, opts = {}) {
+        if (!this.batcher)
+            throw new Error("no batcher configured");
+        const onStatus = opts.onStatus ?? (() => { });
+        const m = this.market(token);
+        const poolIn = side === "buy" ? this.hypeMarket.pool : m.pool;
+        const maxOrders = opts.maxOrders ?? 6;
+        let { sizes, rest } = splitStandard(amount, maxOrders);
+        // each order also pays the relayer's fee from the same balance: if the orders plus their fees don't fit (say, when
+        // selling everything), shrink the orders so they do
+        const fee = (await this.relayFee("placeOrder", poolIn)).fee;
+        if (fee > 0n) {
+            const have = await this.balance(poolIn);
+            if (sizes.reduce((a, x) => a + x, 0n) + fee * BigInt(sizes.length) > have) {
+                const budget = have - fee * BigInt(maxOrders);
+                if (budget <= 0n)
+                    throw new Error("insufficient private balance");
+                ({ sizes } = splitStandard(budget < amount ? budget : amount, maxOrders));
+                rest = amount - sizes.reduce((a, x) => a + x, 0n);
+            }
+        }
+        if (sizes.length === 0)
+            throw new Error("amount too small for a standard-size order");
+        const placed = [];
+        for (let i = 0; i < sizes.length; i++) {
+            const size = sizes[i];
+            onStatus(`Order ${i + 1}/${sizes.length}: syncing…`);
+            const q = await this.relayFee("placeOrder", poolIn);
+            const inputs = await this.inputsFor(poolIn, size + q.fee, onStatus);
+            const keyIndex = randomKeyIndex();
+            const outKey = await this.keys.key(keyIndex);
+            const outBlinding = randomField();
+            const data = encodeAbiParameters(ORDER_DATA_ABI, [
+                { token, outPubKey: outKey.pubKey, outBlinding, outMemo: encryptRouterMemo(this.keys.encPub, outBlinding, keyIndex) },
+            ]);
+            const change = inputs.reduce((a, x) => a + x.amount, 0n) - size - q.fee;
+            onStatus(`Order ${i + 1}/${sizes.length}: proving on this device…`);
+            const { proof, extData } = await buildTransaction({
+                tree: await this.treeFor(poolIn, inputs),
+                inputs,
+                outputs: change > 0n ? [await this.changeOutput(change)] : [],
+                extAmount: -size,
+                fee: q.fee,
+                relayer: q.relayer,
+                recipient: this.batcher,
+                data,
+                ...(await this.dummy()),
+                prover: await this.prover(),
+            });
+            onStatus(`Order ${i + 1}/${sizes.length}: relaying…`);
+            const txHash = await this.submit({ kind: "placeOrder", pool: poolIn, proof, extData });
+            const rc = await this.publicClient.waitForTransactionReceipt({ hash: txHash });
+            const ev = parseEventLogs({ abi: privateBatcherAbi, logs: rc.logs, eventName: "OrderPlaced" })[0];
+            placed.push({ id: ev.args.id, size, round: ev.args.round, txHash });
+        }
+        return { orders: placed, rest };
+    }
+    // ───────────── private trades ─────────────
+    async quote(token, side, amountIn) {
+        const pair = this.market(token).pair;
+        const [rH, rT] = await Promise.all([
+            this.publicClient.readContract({ address: pair, abi: cloakPairAbi, functionName: "reserveHype" }),
+            this.publicClient.readContract({ address: pair, abi: cloakPairAbi, functionName: "reserveToken" }),
+        ]);
+        return this.publicClient.readContract({ address: pair, abi: cloakPairAbi, functionName: "getAmountOut", args: side === "buy" ? [amountIn, rH, rT] : [amountIn, rT, rH] });
+    }
+    /** Private buy: spend private HYPE, receive private tokens. `slippageBps` defaults to 1%. */
+    buy(token, hypeIn, opts = {}) {
+        return this.swap(token, "buy", hypeIn, opts);
+    }
+    /** Private sell: spend private tokens, receive private HYPE. */
+    sell(token, tokensIn, opts = {}) {
+        return this.swap(token, "sell", tokensIn, opts);
+    }
+    async swap(token, side, amountIn, opts) {
+        const onStatus = opts.onStatus ?? (() => { });
+        const m = this.market(token);
+        const poolIn = side === "buy" ? this.hypeMarket.pool : m.pool;
+        const poolOut = side === "buy" ? m.pool : this.hypeMarket.pool;
+        onStatus("Syncing your private balance…");
+        const q = await this.relayFee("privateSwap", poolIn);
+        const inputs = await this.inputsFor(poolIn, amountIn + q.fee, onStatus);
+        // the router trades what the pool releases after its withdrawal fee
+        const expected = await this.quote(token, side, await this.afterFee(poolIn, amountIn));
+        const minOut = (expected * BigInt(10_000 - (opts.slippageBps ?? 100))) / 10000n;
+        const keyIndex = randomKeyIndex();
+        const outKey = await this.keys.key(keyIndex);
+        const outBlinding = randomField();
+        const data = encodeAbiParameters(SWAP_DATA_ABI, [
+            {
+                pair: m.pair,
+                poolOut,
+                minOut,
+                outPubKey: outKey.pubKey,
+                outBlinding,
+                outMemo: encryptRouterMemo(this.keys.encPub, outBlinding, keyIndex),
+                deadline: BigInt(Math.floor(Date.now() / 1000) + 600),
+            },
+        ]);
+        const change = inputs.reduce((a, x) => a + x.amount, 0n) - amountIn - q.fee;
+        onStatus("Generating zero-knowledge proof on this device…");
+        const { proof, extData } = await buildTransaction({
+            tree: await this.treeFor(poolIn, inputs),
+            inputs,
+            outputs: change > 0n ? [await this.changeOutput(change)] : [],
+            extAmount: -amountIn,
+            fee: q.fee,
+            relayer: q.relayer,
+            recipient: this.router,
+            data,
+            ...(await this.dummy()),
+            prover: await this.prover(),
+        });
+        onStatus("Relaying private trade…");
+        const txHash = await this.submit({ kind: "privateSwap", pool: poolIn, proof, extData });
+        return { txHash, expectedOut: expected, minOut, relayerFee: q.fee };
+    }
+    /** Private HYPE → native HYPE at `to` (use a fresh address to stay unlinkable). */
+    async unshieldHype(to, amount, onStatus = () => { }) {
+        const pool = this.hypeMarket.pool;
+        const q = await this.relayFee("unshieldHype", pool);
+        const inputs = await this.inputsFor(pool, amount + q.fee, onStatus);
+        const change = inputs.reduce((a, x) => a + x.amount, 0n) - amount - q.fee;
+        onStatus("Generating zero-knowledge proof on this device…");
+        const { proof, extData } = await buildTransaction({
+            tree: await this.treeFor(pool, inputs),
+            inputs,
+            outputs: change > 0n ? [await this.changeOutput(change)] : [],
+            extAmount: -amount,
+            fee: q.fee,
+            relayer: q.relayer,
+            recipient: this.router,
+            data: encodeAbiParameters([{ type: "address" }], [to]),
+            ...(await this.dummy()),
+            prover: await this.prover(),
+        });
+        onStatus("Relaying withdrawal…");
+        return this.submit({ kind: "unshieldHype", pool, proof, extData });
+    }
+    /** Your receiving address for private transfers. */
+    async address() {
+        return formatCloakAddress((await this.keys.main()).pubKey, this.keys.encPub);
+    }
+    /**
+     * Private transfer inside a pool: sender, recipient and amount all stay hidden.
+     * `token` = a launch token, or the WHYPE address / hypeMarket.token for HYPE.
+     */
+    async send(token, to, amount, onStatus = () => { }) {
+        const rcpt = parseCloakAddress(to);
+        const pool = this.market(token).pool;
+        const q = await this.relayFee("transact", pool);
+        const inputs = await this.inputsFor(pool, amount + q.fee, onStatus);
+        const change = inputs.reduce((a, x) => a + x.amount, 0n) - amount - q.fee;
+        const outputs = [{ amount, pubKey: rcpt.pubKey, memo: (b) => encryptFullMemo(rcpt.encPub, amount, b, MAIN_KEY) }];
+        if (change > 0n)
+            outputs.push(await this.changeOutput(change));
+        onStatus("Generating zero-knowledge proof on this device…");
+        const { proof, extData } = await buildTransaction({
+            tree: await this.treeFor(pool, inputs),
+            inputs,
+            outputs,
+            fee: q.fee,
+            relayer: q.relayer,
+            ...(await this.dummy()),
+            prover: await this.prover(),
+        });
+        onStatus("Relaying private transfer…");
+        return this.submit({ kind: "transact", pool, proof, extData });
+    }
+    /** Private launch tokens → any address. */
+    async unshieldToken(token, to, amount, onStatus = () => { }) {
+        const pool = this.market(token).pool;
+        const q = await this.relayFee("transact", pool);
+        const inputs = await this.inputsFor(pool, amount + q.fee, onStatus);
+        const change = inputs.reduce((a, x) => a + x.amount, 0n) - amount - q.fee;
+        onStatus("Generating zero-knowledge proof on this device…");
+        const { proof, extData } = await buildTransaction({
+            tree: await this.treeFor(pool, inputs),
+            inputs,
+            outputs: change > 0n ? [await this.changeOutput(change)] : [],
+            extAmount: -amount,
+            fee: q.fee,
+            relayer: q.relayer,
+            recipient: to,
+            ...(await this.dummy()),
+            prover: await this.prover(),
+        });
+        return this.submit({ kind: "transact", pool, proof, extData });
+    }
+    // ───────────── moving a balance from an earlier deployment ─────────────
+    /**
+     * Move every private balance `legacy` (a client on the earlier router, with the earlier keys) can see into this
+     * deployment, note by note, through `CloakMigrator`. Each move is one relayed transaction: the old proof withdraws to
+     * the migrator, which deposits the same amount here as a new note for one of this account's one-time keys.
+     */
+    async migrateFrom(legacy, onStatus = () => { }) {
+        const moved = [];
+        const markets = await legacy.loadMarkets();
+        await this.loadMarkets();
+        for (const m of markets) {
+            if (!this.markets.some((x) => x.token.toLowerCase() === m.token.toLowerCase()))
+                continue; // no pool here yet
+            for (;;) {
+                const live = (await legacy.sync(m.pool)).sort((a, b) => (a.amount > b.amount ? -1 : 1));
+                if (!live.length)
+                    break;
+                const inputs = live.slice(0, 2);
+                const total = inputs.reduce((a, x) => a + x.amount, 0n);
+                const q = await legacy.relayFee("migrate", m.pool);
+                if (total <= q.fee)
+                    break; // dust that costs more to move than it's worth
+                const amount = total - q.fee;
+                const keyIndex = randomKeyIndex();
+                const outKey = await this.keys.key(keyIndex);
+                const outBlinding = randomField();
+                const data = encodeAbiParameters(MOVE_DATA_ABI, [
+                    { outPubKey: outKey.pubKey, outBlinding, outMemo: encryptRouterMemo(this.keys.encPub, outBlinding, keyIndex) },
+                ]);
+                onStatus(`Moving ${m.symbol ?? "balance"}: proving on this device…`);
+                const { proof, extData } = await buildTransaction({
+                    tree: await legacy.treeFor(m.pool, inputs),
+                    inputs,
+                    outputs: [],
+                    extAmount: -amount,
+                    fee: q.fee,
+                    relayer: q.relayer,
+                    recipient: this.migratorAddress(),
+                    data,
+                    ...(await legacy.dummy()),
+                    prover: await this.prover(),
+                });
+                onStatus(`Moving ${m.symbol ?? "balance"}: relaying…`);
+                const txHash = await this.submit({ kind: "migrate", pool: m.pool, proof, extData });
+                await this.publicClient.waitForTransactionReceipt({ hash: txHash });
+                moved.push({ token: m.token, amount, txHash });
+            }
+        }
+        return moved;
+    }
+    migratorAddress() {
+        if (!this.migrator)
+            throw new Error("no migrator configured");
+        return this.migrator;
+    }
+}

package/dist/private/crypto.d.ts

@@ -0,0 +1,75 @@
+import { type Hex } from "viem";
+export declare const FIELD_SIZE = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+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;
+export declare const randomField: () => bigint;
+export declare const randomKeyIndex: () => number;
+export declare function poseidon(inputs: bigint[]): Promise<bigint>;
+/** The message a wallet signs to derive its Cloak private account (deterministic for standard EOAs). */
+export declare const ACCOUNT_MESSAGE = "Cloak private account v1\n\nSigning this derives your private trading keys on Elysium. It costs nothing and does not move funds.";
+/**
+ * EIP-712 request whose signature derives the private keys of a Cloak v2 account. It is bound to the chain and the
+ * router, so a signature collected by another site or for another contract can't reproduce the keys.
+ */
+export declare const ACCOUNT_TYPED_DATA: (chainId: number, router: `0x${string}`) => {
+    readonly domain: {
+        readonly name: "Cloak";
+        readonly version: "2";
+        readonly chainId: number;
+        readonly verifyingContract: `0x${string}`;
+    };
+    readonly types: {
+        readonly PrivateAccount: readonly [{
+            readonly name: "purpose";
+            readonly type: "string";
+        }];
+    };
+    readonly primaryType: "PrivateAccount";
+    readonly message: {
+        readonly purpose: "Derive my Cloak private trading keys. This costs nothing and moves no funds. Only sign this on cloak.boblabs.tech.";
+    };
+};
+export interface SpendKey {
+    index: number;
+    privKey: bigint;
+    pubKey: bigint;
+}
+/**
+ * One seed → a main spending key, a view key (memo encryption) and 2³² one-time keys. One-time keys receive every note
+ * that enters the pool publicly (shielding, swap outputs), so on-chain `depositTo` calls never repeat a pubKey and
+ * cannot be linked to each other or to the main key.
+ */
+export declare class CloakKeys {
+    private seed;
+    readonly encPriv: Uint8Array;
+    readonly encPub: Uint8Array;
+    private cache;
+    private constructor();
+    static fromSeed(seed: Uint8Array): CloakKeys;
+    /** Derive from a wallet signature over ACCOUNT_MESSAGE. */
+    static fromSignature(sig: Hex): CloakKeys;
+    key(index: number): Promise<SpendKey>;
+    main(): Promise<SpendKey>;
+}
+export interface Note {
+    amount: bigint;
+    pubKey: bigint;
+    blinding: bigint;
+}
+export declare const noteCommitment: (n: Note) => Promise<bigint>;
+export declare function nullifierOf(n: Note, leafIndex: number, privKey: bigint): Promise<bigint>;
+export declare function encryptFullMemo(encPub: Uint8Array, amount: bigint, blinding: bigint, keyIndex: number): Hex;
+/** For router-created notes: the router adds `0x02 ‖ amount` in front on-chain. */
+export declare function encryptRouterMemo(encPub: Uint8Array, blinding: bigint, keyIndex: number): Hex;
+export declare function readMemo(encPriv: Uint8Array, memo: Hex): {
+    amount: bigint;
+    blinding: bigint;
+    keyIndex: number;
+} | null;
+export declare function formatCloakAddress(pubKey: bigint, encPub: Uint8Array): string;
+export declare function parseCloakAddress(addr: string): {
+    pubKey: bigint;
+    encPub: Uint8Array;
+};