@cloakely/sdk 0.7.0 → 0.8.0

package/dist/deployments.d.ts

@@ -48,6 +48,8 @@ export interface CloakDeployment {
     sharedBlock?: bigint;
     /** SharedRouter: private buys, sells and hidden sends for the shared vault. */
     sharedRouter?: Address;
+    /** SharedBatcher: batch rounds for the shared vault's tokens. */
+    sharedBatcher?: Address;
     hypePool: Address;
     whype: Address;
     /** Hosted relayer (POST /relay, GET /quote). */

package/dist/deployments.js

@@ -21,6 +21,7 @@ export const deployments = {
         shared: "0x0ce2ecb0195e07899377e3d7b01e927ab3f87610",
         sharedBlock: 21426599n,
         sharedRouter: "0xe2a0769a5acbd987c1b6725247c56187a112dc7e",
+        sharedBatcher: "0xdc725bdeb0fca923bf2dc65232f54463b0f80820",
         router: "0x343ab9a7aac93cee28321410510ea24417cc6386",
         routerBlock: 19485063n,
         batcher: "0xc69e4bca18020ae93bc9f17093985bfb139a3203",
@@ -103,6 +104,7 @@ export async function liveDeployment(publicClient, base) {
         shared: reg.shared ?? base.shared,
         sharedBlock: reg.sharedBlock ?? base.sharedBlock,
         sharedRouter: reg.sharedRouter ?? base.sharedRouter,
+        sharedBatcher: reg.sharedBatcher ?? base.sharedBatcher,
         hypePool,
         whype,
         previous: reg.previous.length

package/dist/private/client.d.ts

@@ -248,6 +248,20 @@ export declare class CloakPrivate {
     send(token: Address, to: string, amount: bigint, 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>;
+    /**
+     * Move everything this account holds of `token` to `to` in one relayed call, leaving no change behind: to a cloak:
+     * address (stays private) or out to a 0x address (a withdrawal; HYPE arrives as native HYPE, minus the withdrawal
+     * fee). The relayer's fee comes out of the amount. Spends the two largest notes of one tree epoch, so an account
+     * with more notes than that needs another call. Claim links use this, so a claimed link is left empty. With `one`,
+     * it moves a single note picked at random: one share of a link split into several.
+     */
+    sweep(token: Address, to: string, onStatus?: Status, opts?: {
+        one?: boolean;
+    }): Promise<{
+        txHash: Hex;
+        amount: bigint;
+        left: bigint;
+    }>;
     /**
      * 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

package/dist/private/client.js

@@ -21,14 +21,17 @@ const json = (v) => JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toStr
 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) });
+        // a relay normally answers in seconds; past two minutes the connection is dead, and saying so beats waiting forever
+        const res = await fetch(`${base}/relay`, { method: "POST", headers: { "content-type": "application/json" }, body: json(call), signal: AbortSignal.timeout(120_000) }).catch((e) => {
+            throw new Error(e?.name === "TimeoutError" ? "The relayer didn't answer. Check your balance in a minute before trying again." : `Couldn't reach the relayer: ${e?.message ?? e}`);
+        });
         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 res = await fetch(`${base}/quote?kind=${kind}&pool=${pool}`, { signal: AbortSignal.timeout(30_000) });
         const out = await res.json().catch(() => ({}));
         if (!res.ok)
             throw new Error(out.error ?? `relayer quote failed (${res.status})`);
@@ -754,6 +757,67 @@ export class CloakPrivate {
         });
         return this.submit({ kind: "transact", pool, proof, extData });
     }
+    /**
+     * Move everything this account holds of `token` to `to` in one relayed call, leaving no change behind: to a cloak:
+     * address (stays private) or out to a 0x address (a withdrawal; HYPE arrives as native HYPE, minus the withdrawal
+     * fee). The relayer's fee comes out of the amount. Spends the two largest notes of one tree epoch, so an account
+     * with more notes than that needs another call. Claim links use this, so a claimed link is left empty. With `one`,
+     * it moves a single note picked at random: one share of a link split into several.
+     */
+    async sweep(token, to, onStatus = () => { }, opts = {}) {
+        const pool = this.market(token).pool;
+        const isHype = pool.toLowerCase() === this.hypeMarket.pool.toLowerCase();
+        const out = !to.startsWith("cloak:");
+        if (out && !/^0x[0-9a-fA-F]{40}$/.test(to))
+            throw new Error("send to a cloak: address or a 0x address");
+        const kind = out && isHype ? "unshieldHype" : "transact";
+        const [live, q] = await Promise.all([this.sync(pool), this.relayFee(kind, pool)]);
+        if (!live.length)
+            throw new Error("nothing to move: this balance is empty");
+        const sorted = [...live].sort((a, b) => (a.amount > b.amount ? -1 : a.amount < b.amount ? 1 : 0));
+        // `one`: take a single note, picked at random, so people claiming shares of one link at once rarely collide
+        const worth = sorted.filter((n) => n.amount > q.fee);
+        const inputs = opts.one
+            ? worth.length ? [worth[Math.floor(Math.random() * worth.length)]] : []
+            : sorted.filter((n) => (n.epoch ?? 0) === (sorted[0].epoch ?? 0)).slice(0, 2);
+        if (!inputs.length)
+            throw new Error("this balance is smaller than the relayer's fee");
+        const sum = inputs.reduce((a, x) => a + x.amount, 0n);
+        const amount = sum - q.fee;
+        if (amount <= 0n)
+            throw new Error("this balance is smaller than the relayer's fee");
+        onStatus("Generating zero-knowledge proof on this device…");
+        let built;
+        if (out) {
+            built = await buildTransaction({
+                tree: await this.treeFor(pool, inputs),
+                inputs,
+                outputs: [],
+                extAmount: -amount,
+                fee: q.fee,
+                relayer: q.relayer,
+                recipient: isHype ? this.router : to,
+                ...(isHype ? { data: encodeAbiParameters([{ type: "address" }], [to]) } : {}),
+                ...(await this.dummy()),
+                prover: await this.prover(),
+            });
+        }
+        else {
+            const rcpt = parseCloakAddress(to);
+            built = await buildTransaction({
+                tree: await this.treeFor(pool, inputs),
+                inputs,
+                outputs: [{ amount, pubKey: rcpt.pubKey, memo: (b) => encryptFullMemo(rcpt.encPub, amount, b, MAIN_KEY) }],
+                fee: q.fee,
+                relayer: q.relayer,
+                ...(await this.dummy()),
+                prover: await this.prover(),
+            });
+        }
+        onStatus(out ? "Relaying withdrawal…" : "Relaying private transfer…");
+        const txHash = await this.submit({ kind, pool, proof: built.proof, extData: built.extData });
+        return { txHash, amount, left: live.reduce((a, x) => a + x.amount, 0n) - sum };
+    }
     // ───────────── 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

package/dist/private/index.d.ts

@@ -4,3 +4,4 @@ export * from "./prover.js";
 export * from "./tx.js";
 export * from "./client.js";
 export * from "./shared.js";
+export * from "./links.js";

package/dist/private/index.js

@@ -4,3 +4,4 @@ export * from "./prover.js";
 export * from "./tx.js";
 export * from "./client.js";
 export * from "./shared.js";
+export * from "./links.js";

package/dist/private/links.d.ts

@@ -0,0 +1,65 @@
+import { type Hex } from "viem";
+import { CloakKeys } from "./crypto.js";
+export declare const LINK_ORIGIN = "https://cloak.boblabs.tech";
+export declare const LINK_MESSAGE_MAX = 140;
+export declare const LINK_NAME_MAX = 40;
+export declare const LINK_HINT_MAX = 120;
+/** Most shares one link can be split into. Each share is its own private send, so more means a longer wait to make it. */
+export declare const LINK_SHARES_MAX = 20;
+/** Tokens a link can carry today. */
+export declare const LINK_TOKENS: readonly ["HYPE", "USDC"];
+export type LinkToken = (typeof LINK_TOKENS)[number];
+/** Unicode-safe trim to `max` characters, with control characters removed. */
+export declare function cleanLinkText(s: string | null | undefined, max: number): string;
+/** A passcode as both sides type it: case, outer spaces and repeated spaces don't matter. */
+export declare const normalizePasscode: (code: string) => string;
+/** A fresh link secret (32 random bytes). */
+export declare const newLinkSecret: () => Uint8Array;
+/**
+ * The private account a claim link opens. Without a passcode it comes from the secret alone. With one, the seed is
+ * scrypt(passcode, secret), so a copy of the link is useless without the code, and guessing codes is slow.
+ */
+export declare function linkKeys(secret: Uint8Array, passcode?: string): Promise<CloakKeys>;
+/** The cloak: address a link's money is sent to. */
+export declare function linkAddress(keys: CloakKeys): Promise<string>;
+export interface ClaimLink {
+    secret: Uint8Array;
+    /** Block the link was funded in. Shown to the claimer; scanning still starts at the vaults' first block, because
+     *  a note's Merkle proof needs every leaf before it. */
+    block: bigint;
+    /** What the sender put in (a display hint; the claim page reads the real balance). */
+    token?: LinkToken;
+    amount?: string;
+    /** A message from the sender. */
+    message?: string;
+    /** The sender's name, as they chose to give it. */
+    from?: string;
+    /** Needs a passcode. */
+    locked?: boolean;
+    /** A hint or riddle whose answer is the passcode. */
+    hint?: string;
+    /** Split into this many equal shares: each person who opens the link claims one (a red envelope). */
+    shares?: number;
+}
+export declare function buildClaimLink(l: ClaimLink, origin?: string): string;
+/** Reads a claim link (the whole URL or just its fragment). Throws on anything that isn't one. */
+export declare function parseClaimLink(link: string): ClaimLink;
+export interface PaymentRequest {
+    /** A cloak: address (paid privately) or a 0x address (paid from the payer's private balance). */
+    to: string;
+    token: LinkToken;
+    /** Whole units as a decimal ("25", "0.5"); leave out to let the payer choose. */
+    amount?: string;
+    /** What it's for: an invoice number, an order. Only the payer sees it. */
+    note?: string;
+    /** Who is asking. */
+    name?: string;
+}
+/** Checks an amount and returns it as a plain decimal, or throws a plain-language error. Empty means "payer chooses". */
+export declare function normalizeLinkAmount(input: string, decimals: number): string;
+/** Throws unless `to` is a cloak: address or a 0x address. */
+export declare function checkPayee(to: string): "cloak" | "wallet";
+export declare function buildRequestLink(r: PaymentRequest, origin?: string): string;
+/** Reads a request link (fragment first, then the query string, so hand-made `?to=…` links work too). */
+export declare function parseRequestLink(link: string): PaymentRequest;
+export type { Hex };

package/dist/private/links.js

@@ -0,0 +1,186 @@
+/**
+ * Payment links: money and requests that travel as a URL.
+ *
+ *   claim link    https://cloak.boblabs.tech/claim#k=<secret>&b=<block>&t=HYPE&m=Happy+birthday
+ *                 The link holds a whole throwaway private account. The sender funds it with a private send, and
+ *                 whoever opens the link moves that money into their own private balance, or out to any wallet. The
+ *                 relayer submits the claim and takes its fee from the link, so the claimer needs no gas and no
+ *                 Cloak account. Until someone claims it, the sender can take it back the same way.
+ *                 With a passcode (`p=1`), the account's seed also needs the code, sent another way or posed as a
+ *                 riddle (`q=`): a link posted in public that only the right person can open.
+ *                 Split into shares (`n=`), it is a red envelope: several equal notes, and each person who opens the
+ *                 link claims one, first come first served.
+ *
+ *   request link  https://cloak.boblabs.tech/pay#to=cloak:…&amount=25&token=USDC&note=Invoice+42&name=Robin
+ *                 Asks someone to pay you. `to` is a cloak: address (a private payment) or a 0x address (paid from
+ *                 the payer's private balance, so the payer's wallet never shows). Leave out the amount for a tip
+ *                 jar. Nothing about a request is on chain.
+ *
+ * Everything sits in the URL fragment (after #), which browsers never send to a server or put in a referrer, so a
+ * link stays between the people who share it.
+ */
+import { scryptAsync } from "@noble/hashes/scrypt";
+import { randomBytes } from "@noble/hashes/utils";
+import { concat, isAddress, keccak256, toBytes } from "viem";
+import { CloakKeys, formatCloakAddress, parseCloakAddress } from "./crypto.js";
+export const LINK_ORIGIN = "https://cloak.boblabs.tech";
+export const LINK_MESSAGE_MAX = 140;
+export const LINK_NAME_MAX = 40;
+export const LINK_HINT_MAX = 120;
+/** Most shares one link can be split into. Each share is its own private send, so more means a longer wait to make it. */
+export const LINK_SHARES_MAX = 20;
+/** Tokens a link can carry today. */
+export const LINK_TOKENS = ["HYPE", "USDC"];
+const b64url = (b) => btoa(String.fromCharCode(...b)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const unb64url = (s) => {
+    const t = s.replace(/-/g, "+").replace(/_/g, "/");
+    return Uint8Array.from(atob(t + "=".repeat((4 - (t.length % 4)) % 4)), (c) => c.charCodeAt(0));
+};
+/** Unicode-safe trim to `max` characters, with control characters removed. */
+export function cleanLinkText(s, max) {
+    // eslint-disable-next-line no-control-regex
+    return Array.from((s ?? "").replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim()).slice(0, max).join("");
+}
+/** A passcode as both sides type it: case, outer spaces and repeated spaces don't matter. */
+export const normalizePasscode = (code) => code.normalize("NFKC").trim().toLowerCase().replace(/\s+/g, " ");
+/** A fresh link secret (32 random bytes). */
+export const newLinkSecret = () => randomBytes(32);
+/**
+ * The private account a claim link opens. Without a passcode it comes from the secret alone. With one, the seed is
+ * scrypt(passcode, secret), so a copy of the link is useless without the code, and guessing codes is slow.
+ */
+export async function linkKeys(secret, passcode) {
+    if (secret.length !== 32)
+        throw new Error("bad link secret");
+    if (passcode === undefined)
+        return CloakKeys.fromSeed(toBytes(keccak256(concat([toBytes("cloak-link-v1"), secret]))));
+    const code = normalizePasscode(passcode);
+    if (!code)
+        throw new Error("enter the passcode");
+    const seed = await scryptAsync(toBytes(code), concat([toBytes("cloak-link-lock-v1"), secret]), { N: 2 ** 15, r: 8, p: 1, dkLen: 32 });
+    return CloakKeys.fromSeed(seed);
+}
+/** The cloak: address a link's money is sent to. */
+export async function linkAddress(keys) {
+    return formatCloakAddress((await keys.main()).pubKey, keys.encPub);
+}
+export function buildClaimLink(l, origin = LINK_ORIGIN) {
+    const p = new URLSearchParams();
+    p.set("k", b64url(l.secret));
+    p.set("b", l.block.toString());
+    if (l.token)
+        p.set("t", l.token);
+    if (l.amount)
+        p.set("a", l.amount);
+    const m = cleanLinkText(l.message, LINK_MESSAGE_MAX);
+    if (m)
+        p.set("m", m);
+    const f = cleanLinkText(l.from, LINK_NAME_MAX);
+    if (f)
+        p.set("f", f);
+    if (l.locked)
+        p.set("p", "1");
+    const q = cleanLinkText(l.hint, LINK_HINT_MAX);
+    if (l.locked && q)
+        p.set("q", q);
+    if (l.shares && l.shares > 1)
+        p.set("n", String(Math.min(Math.floor(l.shares), LINK_SHARES_MAX)));
+    return `${origin.replace(/\/+$/, "")}/claim#${p.toString()}`;
+}
+/** Reads a claim link (the whole URL or just its fragment). Throws on anything that isn't one. */
+export function parseClaimLink(link) {
+    const frag = link.includes("#") ? link.slice(link.indexOf("#") + 1) : link;
+    const p = new URLSearchParams(frag);
+    const k = p.get("k");
+    if (!k)
+        throw new Error("This isn't a Cloak claim link.");
+    let secret;
+    try {
+        secret = unb64url(k);
+    }
+    catch {
+        throw new Error("This claim link is damaged. Ask the sender to copy it again.");
+    }
+    if (secret.length !== 32)
+        throw new Error("This claim link is cut short. Ask the sender to copy it again.");
+    const b = p.get("b") ?? "0";
+    const t = p.get("t");
+    const a = p.get("a");
+    return {
+        secret,
+        block: /^\d{1,12}$/.test(b) ? BigInt(b) : 0n,
+        token: LINK_TOKENS.includes(t ?? "") ? t : undefined,
+        amount: a && /^\d{1,15}(\.\d{1,18})?$/.test(a) ? a : undefined,
+        message: cleanLinkText(p.get("m"), LINK_MESSAGE_MAX) || undefined,
+        from: cleanLinkText(p.get("f"), LINK_NAME_MAX) || undefined,
+        locked: p.get("p") === "1",
+        hint: cleanLinkText(p.get("q"), LINK_HINT_MAX) || undefined,
+        shares: /^\d{1,2}$/.test(p.get("n") ?? "") && Number(p.get("n")) > 1 ? Math.min(Number(p.get("n")), LINK_SHARES_MAX) : undefined,
+    };
+}
+/** Checks an amount and returns it as a plain decimal, or throws a plain-language error. Empty means "payer chooses". */
+export function normalizeLinkAmount(input, decimals) {
+    const s = input.trim().replace(/,/g, "");
+    if (!s)
+        return "";
+    if (!/^(\d+\.?\d*|\.\d+)$/.test(s))
+        throw new Error("Use numbers and one dot for the amount, like 25 or 0.5.");
+    const [i = "", f = ""] = s.split(".");
+    if (f.length > decimals)
+        throw new Error(`Use at most ${decimals} decimal places.`);
+    const int = i.replace(/^0+(?=\d)/, "") || "0";
+    const frac = f.replace(/0+$/, "");
+    if (int.length > 15)
+        throw new Error("That amount is too large.");
+    if (/^0*$/.test(int) && !frac)
+        throw new Error("Use an amount above zero, or leave it empty.");
+    return frac ? `${int}.${frac}` : int;
+}
+/** Throws unless `to` is a cloak: address or a 0x address. */
+export function checkPayee(to) {
+    const t = to.trim();
+    if (t.startsWith("cloak:")) {
+        parseCloakAddress(t);
+        return "cloak";
+    }
+    if (isAddress(t))
+        return "wallet";
+    throw new Error("Pay to a cloak: address or a 0x wallet address.");
+}
+export function buildRequestLink(r, origin = LINK_ORIGIN) {
+    checkPayee(r.to);
+    if (!LINK_TOKENS.includes(r.token))
+        throw new Error(`Requests take ${LINK_TOKENS.join(" or ")}.`);
+    const p = new URLSearchParams();
+    p.set("to", r.to.trim());
+    if (r.amount)
+        p.set("amount", normalizeLinkAmount(r.amount, r.token === "USDC" ? 6 : 18));
+    p.set("token", r.token);
+    const note = cleanLinkText(r.note, LINK_MESSAGE_MAX);
+    if (note)
+        p.set("note", note);
+    const name = cleanLinkText(r.name, LINK_NAME_MAX);
+    if (name)
+        p.set("name", name);
+    return `${origin.replace(/\/+$/, "")}/pay#${p.toString()}`;
+}
+/** Reads a request link (fragment first, then the query string, so hand-made `?to=…` links work too). */
+export function parseRequestLink(link) {
+    const url = new URL(link, LINK_ORIGIN);
+    const p = new URLSearchParams(url.search);
+    const frag = url.hash.replace(/^#/, "");
+    for (const [k, v] of new URLSearchParams(frag))
+        p.set(k, v);
+    const to = (p.get("to") ?? "").trim();
+    checkPayee(to);
+    const token = ((p.get("token") ?? "HYPE").toUpperCase() === "USDC" ? "USDC" : "HYPE");
+    const raw = p.get("amount") ?? "";
+    let amount;
+    try {
+        amount = normalizeLinkAmount(raw, token === "USDC" ? 6 : 18) || undefined;
+    }
+    catch {
+        amount = undefined;
+    }
+    return { to, token, amount, note: cleanLinkText(p.get("note"), LINK_MESSAGE_MAX) || undefined, name: cleanLinkText(p.get("name"), LINK_NAME_MAX) || undefined };
+}

package/dist/private/shared.d.ts

@@ -39,7 +39,7 @@ export declare const SHARED_SWAP_DATA_ABI: readonly [{
         readonly type: "uint64";
     }];
 }];
-export type SharedRelayKind = "sharedTransact" | "sharedBuy" | "sharedSell" | "sharedSend";
+export type SharedRelayKind = "sharedTransact" | "sharedBuy" | "sharedSell" | "sharedSend" | "sharedOrderBuy" | "sharedOrderSell";
 export interface SharedRelayCall {
     kind: SharedRelayKind;
     /** The shared-vault proof (or, for sharedBuy, the HYPE vault proof). */
@@ -56,7 +56,7 @@ export type SharedSubmitter = ((call: SharedRelayCall) => Promise<Hex>) & {
 /** POST shared-vault calls to a Cloak relayer (`services/keeper` serves `/relay-shared` and `/quote-shared`). */
 export declare function sharedRelayerSubmitter(url: string): SharedSubmitter;
 /** Submit shared-vault calls from a wallet (that wallet pays gas and appears as the sender). For tests and relayers. */
-export declare function sharedWalletSubmitter(priv: CloakPrivate, wallet: Wallet, vault: Address, router: Address): SharedSubmitter;
+export declare function sharedWalletSubmitter(priv: CloakPrivate, wallet: Wallet, vault: Address, router: Address, batcher?: Address): SharedSubmitter;
 export interface SharedToken {
     token: Address;
     market: Address;
@@ -69,12 +69,16 @@ export declare class SharedVaultClient {
     readonly prover: () => Promise<Prover>;
     readonly submit: SharedSubmitter;
     readonly fromBlock: bigint;
+    /** SharedBatcher: batch rounds that hide trade size for these tokens. */
+    readonly batcher?: Address | undefined;
     tokens: SharedToken[];
     private leaves;
     private scannedUpTo;
     private notes;
     private nextBlock;
-    constructor(priv: CloakPrivate, vault: Address, router: Address, prover: () => Promise<Prover>, submit: SharedSubmitter, fromBlock?: bigint);
+    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);
     private get pub();
     /** Every token admitted to the vault, with its Uniswap market. */
     loadTokens(): Promise<SharedToken[]>;
@@ -124,4 +128,27 @@ export declare class SharedVaultClient {
     send(token: Address, amount: bigint, to: string, onStatus?: Status): Promise<Hex>;
     /** Private `token` → `to` (any address). Names the token, as any withdrawal must. */
     unshield(token: Address, amount: bigint, to: Address, onStatus?: Status): Promise<Hex>;
+    roundInfo(): Promise<{
+        round: bigint;
+        endsAt: number;
+        roundSecs: number;
+    }>;
+    /**
+     * Batched private buy or sell of a shared-vault token: the amount is split into standard sizes (1, 2, 5 × 10ⁿ), each
+     * placed by the relayer into the current round. When the round ends, buys and sells cross at the pool's average price
+     * and only the net trades on Uniswap; outputs arrive as private notes. Nobody can tell how much any one trader moved.
+     * Any remainder that isn't a standard size stays in the private balance.
+     */
+    batch(token: Address, side: "buy" | "sell", amount: bigint, opts?: {
+        maxOrders?: number;
+        onStatus?: Status;
+    }): Promise<{
+        orders: {
+            id: bigint;
+            size: bigint;
+            round: bigint;
+            txHash: Hex;
+        }[];
+        rest: bigint;
+    }>;
 }

package/dist/private/shared.js

@@ -1,9 +1,9 @@
-import { encodeAbiParameters, formatEther, keccak256, zeroAddress } from "viem";
-import { cloakAuctionAbi, cloakPairAbi, sharedRouterAbi, sharedVaultAbi } from "../abis.js";
+import { encodeAbiParameters, formatEther, keccak256, parseEventLogs, zeroAddress } from "viem";
+import { cloakAuctionAbi, cloakPairAbi, sharedBatcherAbi, sharedRouterAbi, sharedVaultAbi } from "../abis.js";
 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 { buildTransaction, selectNotes } from "./tx.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
  * Uniswap from now on, next to the single-token vaults of HYPE and USDC.
@@ -36,14 +36,16 @@ const json = (v) => JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toStr
 export function sharedRelayerSubmitter(url) {
     const base = url.replace(/\/$/, "");
     const submit = async (call) => {
-        const res = await fetch(`${base}/relay-shared`, { method: "POST", headers: { "content-type": "application/json" }, body: json(call) });
+        const res = await fetch(`${base}/relay-shared`, { method: "POST", headers: { "content-type": "application/json" }, body: json(call), signal: AbortSignal.timeout(120_000) }).catch((e) => {
+            throw new Error(e?.name === "TimeoutError" ? "The relayer didn't answer. Check your balance in a minute before trying again." : `Couldn't reach the relayer: ${e?.message ?? e}`);
+        });
         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, token) => {
-        const res = await fetch(`${base}/quote-shared?kind=${kind}&token=${token}`);
+        const res = await fetch(`${base}/quote-shared?kind=${kind}&token=${token}`, { signal: AbortSignal.timeout(30_000) });
         const out = await res.json().catch(() => ({}));
         if (!res.ok)
             throw new Error(out.error ?? `relayer quote failed (${res.status})`);
@@ -52,15 +54,21 @@ export function sharedRelayerSubmitter(url) {
     return submit;
 }
 /** Submit shared-vault calls from a wallet (that wallet pays gas and appears as the sender). For tests and relayers. */
-export function sharedWalletSubmitter(priv, wallet, vault, router) {
+export function sharedWalletSubmitter(priv, wallet, vault, router, batcher) {
     return async (call) => {
-        const req = call.kind === "sharedTransact"
-            ? { address: vault, abi: sharedVaultAbi, functionName: "transact", args: [call.proof, call.extData] }
-            : call.kind === "sharedBuy"
-                ? { address: router, abi: sharedRouterAbi, functionName: "buy", args: [call.proof, call.extData] }
-                : call.kind === "sharedSell"
-                    ? { address: router, abi: sharedRouterAbi, functionName: "sell", args: [call.proof, call.extData] }
-                    : { address: router, abi: sharedRouterAbi, functionName: "send", args: [call.proof, call.extData, call.feeProof, call.feeExtData] };
+        if ((call.kind === "sharedOrderBuy" || call.kind === "sharedOrderSell") && !batcher)
+            throw new Error("no shared batcher configured");
+        const req = call.kind === "sharedOrderBuy"
+            ? { address: batcher, abi: sharedBatcherAbi, functionName: "placeBuy", args: [call.proof, call.extData] }
+            : call.kind === "sharedOrderSell"
+                ? { address: batcher, abi: sharedBatcherAbi, functionName: "placeSell", args: [call.proof, call.extData] }
+                : call.kind === "sharedTransact"
+                    ? { address: vault, abi: sharedVaultAbi, functionName: "transact", args: [call.proof, call.extData] }
+                    : call.kind === "sharedBuy"
+                        ? { address: router, abi: sharedRouterAbi, functionName: "buy", args: [call.proof, call.extData] }
+                        : call.kind === "sharedSell"
+                            ? { address: router, abi: sharedRouterAbi, functionName: "sell", args: [call.proof, call.extData] }
+                            : { address: router, abi: sharedRouterAbi, functionName: "send", args: [call.proof, call.extData, call.feeProof, call.feeExtData] };
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const est = await priv.publicClient.estimateContractGas({ ...req, account: wallet.account.address });
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -86,18 +94,22 @@ export class SharedVaultClient {
     prover;
     submit;
     fromBlock;
+    batcher;
     tokens = [];
     leaves = [];
     scannedUpTo = 0;
     notes = [];
     nextBlock;
-    constructor(priv, vault, router, prover, submit, fromBlock = 0n) {
+    constructor(priv, vault, router, prover, submit, fromBlock = 0n, 
+    /** SharedBatcher: batch rounds that hide trade size for these tokens. */
+    batcher) {
         this.priv = priv;
         this.vault = vault;
         this.router = router;
         this.prover = prover;
         this.submit = submit;
         this.fromBlock = fromBlock;
+        this.batcher = batcher;
         this.nextBlock = fromBlock;
     }
     get pub() {
@@ -456,4 +468,93 @@ export class SharedVaultClient {
         onStatus("Relaying…");
         return this.submit({ kind: "sharedTransact", proof, extData });
     }
+    // ───────────── batch rounds (hide trade size) ─────────────
+    async roundInfo() {
+        if (!this.batcher)
+            throw new Error("no shared batcher configured");
+        const c = { address: this.batcher, abi: sharedBatcherAbi };
+        const [round, roundSecs] = await Promise.all([this.pub.readContract({ ...c, functionName: "currentRound" }), this.pub.readContract({ ...c, functionName: "roundSecs" })]);
+        return { round, roundSecs: Number(roundSecs), endsAt: Number((round + 1n) * roundSecs) };
+    }
+    /**
+     * Batched private buy or sell of a shared-vault token: the amount is split into standard sizes (1, 2, 5 × 10ⁿ), each
+     * placed by the relayer into the current round. When the round ends, buys and sells cross at the pool's average price
+     * and only the net trades on Uniswap; outputs arrive as private notes. Nobody can tell how much any one trader moved.
+     * Any remainder that isn't a standard size stays in the private balance.
+     */
+    async batch(token, side, amount, opts = {}) {
+        if (!this.batcher)
+            throw new Error("no shared batcher configured");
+        if (!this.tokens.length)
+            await this.loadTokens();
+        this.info(token);
+        const onStatus = opts.onStatus ?? (() => { });
+        const asset = asNum(token);
+        const kind = side === "buy" ? "sharedOrderBuy" : "sharedOrderSell";
+        const hypePool = this.priv.hypeMarket.pool;
+        const maxOrders = opts.maxOrders ?? 6;
+        let { sizes, rest } = splitStandard(amount, maxOrders);
+        const fee = (await this.quote(kind, token)).fee;
+        if (fee > 0n) {
+            const have = side === "buy" ? await this.priv.balance(hypePool) : await this.balance(token);
+            const reserve = (n) => (fee * BigInt(n) * 5n) / 4n + fee;
+            if (sizes.reduce((a, x) => a + x, 0n) + reserve(sizes.length) > have) {
+                // every order pays its own relayer fee: use fewer orders when that's all the balance can pay for
+                let fit = false;
+                for (let n = maxOrders; n >= 1 && !fit; n--) {
+                    const budget = have - reserve(n);
+                    if (budget <= 0n)
+                        continue;
+                    ({ sizes } = splitStandard(budget < amount ? budget : amount, n));
+                    fit = sizes.length > 0;
+                }
+                if (!fit)
+                    throw new Error("insufficient private balance");
+                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.quote(kind, token);
+            let inputs;
+            try {
+                inputs = side === "buy" ? await this.priv.inputsFor(hypePool, size + q.fee, onStatus) : await this.inputsFor(token, size + q.fee, onStatus);
+            }
+            catch (e) {
+                if (!placed.length || !/insufficient private balance/.test(String(e.message)))
+                    throw e;
+                rest += sizes.slice(i).reduce((a, x) => a + x, 0n);
+                break;
+            }
+            const keyIndex = randomKeyIndex();
+            const outKey = await this.priv.keys.key(keyIndex);
+            const outBlinding = randomField();
+            const data = encodeAbiParameters(ORDER_DATA_ABI, [{ token, outPubKey: outKey.pubKey, outBlinding, outMemo: encryptRouterMemo(this.priv.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 common = {
+                inputs,
+                outputs: change > 0n ? [await this.priv.changeOutput(change)] : [],
+                extAmount: -size,
+                fee: q.fee,
+                relayer: q.relayer,
+                recipient: this.batcher,
+                data,
+                ...(await this.priv.dummy()),
+            };
+            const { proof, extData } = side === "buy"
+                ? await buildTransaction({ ...common, tree: await this.priv.treeFor(hypePool, inputs), prover: await this.priv.prover() })
+                : await buildTransaction({ ...common, tree: await this.tree(inputs[0].epoch ?? 0), asset, publicAsset: asset, prover: await this.prover() });
+            onStatus(`Order ${i + 1}/${sizes.length}: relaying…`);
+            const txHash = await this.submit({ kind, proof, extData });
+            const rc = await this.pub.waitForTransactionReceipt({ hash: txHash });
+            const ev = parseEventLogs({ abi: sharedBatcherAbi, logs: rc.logs, eventName: "OrderPlaced" })[0];
+            placed.push({ id: ev.args.id, size, round: ev.args.round, txHash });
+        }
+        return { orders: placed, rest };
+    }
 }

package/dist/registry.d.ts

@@ -42,6 +42,8 @@ export interface CloakRegistry {
     sharedBlock?: bigint;
     /** SharedRouter: private buys, sells and hidden sends for the shared vault. */
     sharedRouter?: Address;
+    /** SharedBatcher: batch rounds for the shared vault's tokens. */
+    sharedBatcher?: Address;
     factory: Address;
     factoryBlock: bigint;
     /** Earlier factories of the current version (a factory added next to the first), newest first. */