@cloakely/sdk 0.7.1 → 0.8.0

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.js

@@ -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})`);

package/package.json

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