@cloakely/sdk 0.0.0-stage → 0.2.1

package/dist/private/crypto.js

@@ -0,0 +1,135 @@
+// Private-account cryptography: Poseidon notes, x25519-encrypted memos, deterministic keys.
+import { x25519 } from "@noble/curves/ed25519";
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+import { randomBytes } from "@noble/hashes/utils";
+import { concat, keccak256, toBytes, toHex } from "viem";
+export const FIELD_SIZE = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+export const LEVELS = 20;
+export const MAX_NOTE_AMOUNT = 2n ** 128n;
+/** Key index of the main spending key; any other index is a one-time key used for a single public entry. */
+export const MAIN_KEY = 0xffffffff;
+const fieldMod = (x) => ((x % FIELD_SIZE) + FIELD_SIZE) % FIELD_SIZE;
+export const randomField = () => BigInt(toHex(randomBytes(31)));
+export const randomKeyIndex = () => Number(BigInt(toHex(randomBytes(4))) % 0xfffffffen);
+let _poseidon;
+export async function poseidon(inputs) {
+    _poseidon ??= await (await import("circomlibjs")).buildPoseidon(); // loaded on first use
+    return _poseidon.F.toObject(_poseidon(inputs.map((x) => BigInt(x))));
+}
+/** The message a wallet signs to derive its Cloak private account (deterministic for standard EOAs). */
+export 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 const ACCOUNT_TYPED_DATA = (chainId, router) => ({
+    domain: { name: "Cloak", version: "2", chainId, verifyingContract: router },
+    types: { PrivateAccount: [{ name: "purpose", type: "string" }] },
+    primaryType: "PrivateAccount",
+    message: {
+        purpose: "Derive my Cloak private trading keys. This costs nothing and moves no funds. Only sign this on cloak.boblabs.tech.",
+    },
+});
+/**
+ * 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 class CloakKeys {
+    seed;
+    encPriv;
+    encPub;
+    cache = new Map();
+    constructor(seed, encPriv, encPub) {
+        this.seed = seed;
+        this.encPriv = encPriv;
+        this.encPub = encPub;
+    }
+    static fromSeed(seed) {
+        const encPriv = toBytes(keccak256(concat([toBytes("cloak-view-v1"), seed])));
+        return new CloakKeys(seed, encPriv, x25519.getPublicKey(encPriv));
+    }
+    /** Derive from a wallet signature over ACCOUNT_MESSAGE. */
+    static fromSignature(sig) {
+        return CloakKeys.fromSeed(toBytes(keccak256(sig)));
+    }
+    async key(index) {
+        const hit = this.cache.get(index);
+        if (hit)
+            return hit;
+        const tag = index === MAIN_KEY ? toBytes("cloak-spend-v1") : concat([toBytes("cloak-otk-v1"), toBytes(toHex(index, { size: 4 }))]);
+        const privKey = fieldMod(BigInt(keccak256(concat([tag, this.seed]))));
+        const k = { index, privKey, pubKey: await poseidon([privKey]) };
+        this.cache.set(index, k);
+        return k;
+    }
+    main() {
+        return this.key(MAIN_KEY);
+    }
+}
+export const noteCommitment = (n) => poseidon([n.amount, n.pubKey, n.blinding]);
+export async function nullifierOf(n, leafIndex, privKey) {
+    const c = await noteCommitment(n);
+    const sig = await poseidon([privKey, c, BigInt(leafIndex)]);
+    return poseidon([c, BigInt(leafIndex), sig]);
+}
+// ── memos ──
+// 0x03 | eph(32) | nonce(24) | enc(amount16 ‖ blinding32 ‖ keyIndex4) + tag(16)   — notes created by a proof
+// 0x02 | amount(16) | eph(32) | nonce(24) | enc(blinding32 ‖ keyIndex4) + tag(16) — notes created by the router
+//        (the router prepends the public amount; the client only encrypts blinding + key index)
+const INFO = toBytes("cloak-note-v1");
+function seal(encPub, pt) {
+    const eph = randomBytes(32);
+    const key = hkdf(sha256, x25519.getSharedSecret(eph, encPub), undefined, INFO, 32);
+    const nonce = randomBytes(24);
+    return concat([x25519.getPublicKey(eph), nonce, xchacha20poly1305(key, nonce).encrypt(pt)]);
+}
+function open(encPriv, b) {
+    try {
+        const key = hkdf(sha256, x25519.getSharedSecret(encPriv, b.slice(0, 32)), undefined, INFO, 32);
+        return xchacha20poly1305(key, b.slice(32, 56)).decrypt(b.slice(56));
+    }
+    catch {
+        return null;
+    }
+}
+const u32 = (n) => toBytes(toHex(n, { size: 4 }));
+export function encryptFullMemo(encPub, amount, blinding, keyIndex) {
+    return toHex(concat([new Uint8Array([3]), seal(encPub, concat([toBytes(toHex(amount, { size: 16 })), toBytes(toHex(blinding, { size: 32 })), u32(keyIndex)]))]));
+}
+/** For router-created notes: the router adds `0x02 ‖ amount` in front on-chain. */
+export function encryptRouterMemo(encPub, blinding, keyIndex) {
+    return toHex(seal(encPub, concat([toBytes(toHex(blinding, { size: 32 })), u32(keyIndex)])));
+}
+export function readMemo(encPriv, memo) {
+    const b = toBytes(memo);
+    if (b.length === 1 + 32 + 24 + 52 + 16 && b[0] === 3) {
+        const pt = open(encPriv, b.slice(1));
+        if (!pt)
+            return null;
+        return { amount: BigInt(toHex(pt.slice(0, 16))), blinding: BigInt(toHex(pt.slice(16, 48))), keyIndex: Number(BigInt(toHex(pt.slice(48, 52)))) };
+    }
+    if (b.length === 1 + 16 + 32 + 24 + 36 + 16 && b[0] === 2) {
+        const pt = open(encPriv, b.slice(17));
+        if (!pt)
+            return null;
+        return { amount: BigInt(toHex(b.slice(1, 17))), blinding: BigInt(toHex(pt.slice(0, 32))), keyIndex: Number(BigInt(toHex(pt.slice(32, 36)))) };
+    }
+    return null;
+}
+// ── Cloak addresses: share one to receive private transfers ──
+// cloak:<pubKey 32 bytes><view key 32 bytes>
+export function formatCloakAddress(pubKey, encPub) {
+    return `cloak:${toHex(pubKey, { size: 32 }).slice(2)}${toHex(encPub).slice(2)}`;
+}
+export function parseCloakAddress(addr) {
+    const a = addr.trim();
+    if (!/^cloak:[0-9a-fA-F]{128}$/.test(a))
+        throw new Error("not a cloak: address");
+    const pubKey = BigInt("0x" + a.slice(6, 70));
+    if (pubKey >= FIELD_SIZE)
+        throw new Error("bad cloak: address");
+    return { pubKey, encPub: toBytes(`0x${a.slice(70)}`) };
+}

package/dist/private/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./crypto.js";
+export * from "./tree.js";
+export * from "./prover.js";
+export * from "./tx.js";
+export * from "./client.js";

package/dist/private/index.js

@@ -0,0 +1,5 @@
+export * from "./crypto.js";
+export * from "./tree.js";
+export * from "./prover.js";
+export * from "./tx.js";
+export * from "./client.js";

package/dist/private/prover.d.ts

@@ -0,0 +1,31 @@
+export interface ProofArgs {
+    a: [bigint, bigint];
+    b: [[bigint, bigint], [bigint, bigint]];
+    c: [bigint, bigint];
+    root: bigint;
+    publicAmount: bigint;
+    extDataHash: bigint;
+    inputNullifiers: [bigint, bigint];
+    outputCommitments: [bigint, bigint];
+}
+export type Prover = (input: Record<string, unknown>) => Promise<ProofArgs>;
+/** Groth16 prover for the 2-in/2-out circuit (`transaction2x2`). Runs on the user's device. */
+export declare function createProver(wasm: Uint8Array, zkey: Uint8Array): Prover;
+/** Hosted circuit artifacts. */
+export declare const CIRCUITS_URL = "https://cloak.boblabs.tech/circuits";
+/** SHA-256 of the artifacts this SDK version was built and tested against. */
+export declare const CIRCUIT_HASHES: {
+    readonly wasm: "e44f07497b34f3498352da5bfd9fd7a100c2e8cb7ebddc643f1e6e29d4dfcf6a";
+    readonly zkey: "5d64f2162ef439ae53f0e3c61f276245f7fa1b934907ef66ce3cf149056acad0";
+};
+/**
+ * Fetch the circuit artifacts (12 MB, once) and build a prover. Works in browsers and Node 18+. The files are checked
+ * against `CIRCUIT_HASHES`, so a tampered or mismatched download is refused; pass `hashes: null` to skip that when
+ * serving your own build. In Node you can also read the files yourself and call `createProver`.
+ */
+export declare function loadProver(baseUrl?: string, opts?: {
+    hashes?: {
+        wasm: string;
+        zkey: string;
+    } | null;
+}): Promise<Prover>;

package/dist/private/prover.js

@@ -0,0 +1,55 @@
+const str = (v) => (Array.isArray(v) ? v.map(str) : String(v));
+/** Groth16 prover for the 2-in/2-out circuit (`transaction2x2`). Runs on the user's device. */
+export function createProver(wasm, zkey) {
+    return async (input) => {
+        const snarkjs = await import("snarkjs"); // ~1 MB, loaded on the first proof only
+        const { proof, publicSignals } = await snarkjs.groth16.fullProve(Object.fromEntries(Object.entries(input).map(([k, v]) => [k, str(v)])), wasm, zkey);
+        const s = publicSignals.map(BigInt);
+        return {
+            a: [BigInt(proof.pi_a[0]), BigInt(proof.pi_a[1])],
+            b: [
+                [BigInt(proof.pi_b[0][1]), BigInt(proof.pi_b[0][0])],
+                [BigInt(proof.pi_b[1][1]), BigInt(proof.pi_b[1][0])],
+            ],
+            c: [BigInt(proof.pi_c[0]), BigInt(proof.pi_c[1])],
+            root: s[0],
+            publicAmount: s[1],
+            extDataHash: s[2],
+            inputNullifiers: [s[3], s[4]],
+            outputCommitments: [s[5], s[6]],
+        };
+    };
+}
+/** Hosted circuit artifacts. */
+export const CIRCUITS_URL = "https://cloak.boblabs.tech/circuits";
+/** SHA-256 of the artifacts this SDK version was built and tested against. */
+export const CIRCUIT_HASHES = {
+    wasm: "e44f07497b34f3498352da5bfd9fd7a100c2e8cb7ebddc643f1e6e29d4dfcf6a",
+    zkey: "5d64f2162ef439ae53f0e3c61f276245f7fa1b934907ef66ce3cf149056acad0",
+};
+async function sha256(bytes) {
+    const d = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+    return Array.from(d, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Fetch the circuit artifacts (12 MB, once) and build a prover. Works in browsers and Node 18+. The files are checked
+ * against `CIRCUIT_HASHES`, so a tampered or mismatched download is refused; pass `hashes: null` to skip that when
+ * serving your own build. In Node you can also read the files yourself and call `createProver`.
+ */
+export async function loadProver(baseUrl = CIRCUITS_URL, opts = {}) {
+    const base = baseUrl.replace(/\/$/, "");
+    const get = async (name) => {
+        const res = await fetch(`${base}/${name}`);
+        if (!res.ok)
+            throw new Error(`could not download ${name} from ${base} (${res.status})`);
+        return new Uint8Array(await res.arrayBuffer());
+    };
+    const [wasm, zkey] = await Promise.all([get("transaction2x2.wasm"), get("transaction2x2_final.zkey")]);
+    const want = opts.hashes === undefined ? CIRCUIT_HASHES : opts.hashes;
+    if (want) {
+        const [hw, hz] = await Promise.all([sha256(wasm), sha256(zkey)]);
+        if (hw !== want.wasm || hz !== want.zkey)
+            throw new Error("circuit files don't match this SDK version's hashes; refusing to prove with them");
+    }
+    return createProver(wasm, zkey);
+}

package/dist/private/tree.d.ts

@@ -0,0 +1,13 @@
+export declare class MerkleTree {
+    leaves: bigint[];
+    zeros: bigint[] | null;
+    layersCache: bigint[][];
+    init(): Promise<void>;
+    root(): Promise<bigint>;
+    path(index: number): Promise<{
+        pathElements: bigint[];
+        pathIndices: number;
+        root: bigint;
+    }>;
+    insert(leaf: bigint): Promise<void>;
+}

package/dist/private/tree.js

@@ -0,0 +1,52 @@
+import { poseidon, LEVELS } from "./crypto.js";
+export class MerkleTree {
+    leaves = [];
+    zeros = null;
+    layersCache = [];
+    async init() {
+        if (this.zeros)
+            return;
+        this.zeros = [0n];
+        for (let i = 0; i < LEVELS; i++)
+            this.zeros.push(await poseidon([this.zeros[i], this.zeros[i]]));
+        this.layersCache = [this.leaves.slice()];
+        for (let l = 0; l < LEVELS; l++) {
+            const cur = this.layersCache[l], next = [];
+            for (let i = 0; i < cur.length; i += 2) {
+                next.push(await poseidon([cur[i], i + 1 < cur.length ? cur[i + 1] : this.zeros[l]]));
+            }
+            this.layersCache.push(next);
+        }
+    }
+    async root() {
+        await this.init();
+        if (this.leaves.length === 0)
+            return this.zeros[LEVELS];
+        return this.layersCache[LEVELS][0] || this.zeros[LEVELS];
+    }
+    async path(index) {
+        await this.init();
+        const pathElements = [];
+        let idx = index;
+        for (let l = 0; l < LEVELS; l++) {
+            const sib = idx ^ 1;
+            pathElements.push(sib < this.layersCache[l].length ? this.layersCache[l][sib] : this.zeros[l]);
+            idx >>= 1;
+        }
+        return { pathElements, pathIndices: index, root: this.layersCache[LEVELS][0] };
+    }
+    async insert(leaf) {
+        await this.init();
+        this.leaves.push(leaf);
+        this.layersCache[0].push(leaf);
+        let idx = this.leaves.length - 1;
+        for (let l = 0; l < LEVELS; l++) {
+            const sib = idx ^ 1;
+            const left = sib > idx ? this.layersCache[l][idx] : (sib < this.layersCache[l].length ? this.layersCache[l][sib] : this.zeros[l]);
+            const right = sib > idx ? (sib < this.layersCache[l].length ? this.layersCache[l][sib] : this.zeros[l]) : this.layersCache[l][idx];
+            const p = await poseidon([left, right]);
+            idx >>= 1;
+            this.layersCache[l + 1][idx] = p;
+        }
+    }
+}

package/dist/private/tx.d.ts

@@ -0,0 +1,121 @@
+import { type Address, type Hex } from "viem";
+import type { MerkleTree } from "./tree.js";
+import type { ProofArgs, Prover } from "./prover.js";
+export interface ExtData {
+    recipient: Address;
+    extAmount: bigint;
+    relayer: Address;
+    fee: bigint;
+    encryptedOutput1: Hex;
+    encryptedOutput2: Hex;
+    data: Hex;
+}
+/** A note we can spend: leaf position + the spending key it belongs to. */
+export interface OwnedNote {
+    amount: bigint;
+    pubKey: bigint;
+    blinding: bigint;
+    leafIndex: number;
+    epoch?: number;
+    keyIndex: number;
+    privKey: bigint;
+    commitment: bigint;
+    nullifier: bigint;
+    spent: boolean;
+}
+export interface OutputNote {
+    amount: bigint;
+    pubKey: bigint;
+    blinding?: bigint;
+    memo: (blinding: bigint) => Hex;
+}
+export declare const SWAP_DATA_ABI: readonly [{
+    readonly type: "tuple";
+    readonly components: readonly [{
+        readonly name: "pair";
+        readonly type: "address";
+    }, {
+        readonly name: "poolOut";
+        readonly type: "address";
+    }, {
+        readonly name: "minOut";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outPubKey";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outBlinding";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outMemo";
+        readonly type: "bytes";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint64";
+    }];
+}];
+export declare const ORDER_DATA_ABI: readonly [{
+    readonly type: "tuple";
+    readonly components: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "outPubKey";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outBlinding";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outMemo";
+        readonly type: "bytes";
+    }];
+}];
+/** `CloakMigrator.MoveData`: where a moved balance lands in the new deployment. */
+export declare const MOVE_DATA_ABI: readonly [{
+    readonly type: "tuple";
+    readonly components: readonly [{
+        readonly name: "outPubKey";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outBlinding";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outMemo";
+        readonly type: "bytes";
+    }];
+}];
+/**
+ * Split an amount into at most `maxOrders` standard sizes (1, 2, 5 × 10ⁿ), largest first. Everyone's orders come
+ * from the same small set of sizes, so no order stands out.
+ */
+export declare function splitStandard(amount: bigint, maxOrders?: number): {
+    sizes: bigint[];
+    rest: bigint;
+};
+export declare function hashExtData(ext: ExtData): bigint;
+/**
+ * Build and prove a 2-in/2-out shielded transaction. `data` is bound into the proof through `extDataHash`, which is
+ * what lets the router act on a withdrawal without trusting whoever submits it.
+ */
+export declare function buildTransaction(p: {
+    tree: MerkleTree;
+    inputs: OwnedNote[];
+    outputs: OutputNote[];
+    extAmount?: bigint;
+    fee?: bigint;
+    recipient?: Address;
+    relayer?: Address;
+    data?: Hex;
+    dummyPubKey: bigint;
+    dummyMemo: (blinding: bigint) => Hex;
+    prover: Prover;
+}): Promise<{
+    proof: ProofArgs;
+    extData: ExtData;
+}>;
+/** Pick 1–2 notes covering `target` (smallest single note, else the tightest pair). */
+export declare function selectNotes(notes: OwnedNote[], target: bigint): {
+    inputs: OwnedNote[];
+} | {
+    merge: OwnedNote[];
+};

package/dist/private/tx.js

@@ -0,0 +1,157 @@
+import { encodeAbiParameters, keccak256, zeroAddress } from "viem";
+import { FIELD_SIZE, LEVELS, MAX_NOTE_AMOUNT, noteCommitment, nullifierOf, poseidon, randomField } from "./crypto.js";
+const EXT_DATA_ABI = [
+    {
+        type: "tuple",
+        components: [
+            { name: "recipient", type: "address" },
+            { name: "extAmount", type: "int256" },
+            { name: "relayer", type: "address" },
+            { name: "fee", type: "uint256" },
+            { name: "encryptedOutput1", type: "bytes" },
+            { name: "encryptedOutput2", type: "bytes" },
+            { name: "data", type: "bytes" },
+        ],
+    },
+];
+export const SWAP_DATA_ABI = [
+    {
+        type: "tuple",
+        components: [
+            { name: "pair", type: "address" },
+            { name: "poolOut", type: "address" },
+            { name: "minOut", type: "uint256" },
+            { name: "outPubKey", type: "uint256" },
+            { name: "outBlinding", type: "uint256" },
+            { name: "outMemo", type: "bytes" },
+            { name: "deadline", type: "uint64" },
+        ],
+    },
+];
+export const ORDER_DATA_ABI = [
+    {
+        type: "tuple",
+        components: [
+            { name: "token", type: "address" },
+            { name: "outPubKey", type: "uint256" },
+            { name: "outBlinding", type: "uint256" },
+            { name: "outMemo", type: "bytes" },
+        ],
+    },
+];
+/** `CloakMigrator.MoveData`: where a moved balance lands in the new deployment. */
+export const MOVE_DATA_ABI = [
+    {
+        type: "tuple",
+        components: [
+            { name: "outPubKey", type: "uint256" },
+            { name: "outBlinding", type: "uint256" },
+            { name: "outMemo", type: "bytes" },
+        ],
+    },
+];
+/**
+ * Split an amount into at most `maxOrders` standard sizes (1, 2, 5 × 10ⁿ), largest first. Everyone's orders come
+ * from the same small set of sizes, so no order stands out.
+ */
+export function splitStandard(amount, maxOrders = 6) {
+    const sizes = [];
+    let rest = amount;
+    while (rest > 0n && sizes.length < maxOrders) {
+        const pow = 10n ** BigInt(rest.toString().length - 1);
+        const lead = rest / pow; // 1..9
+        const d = lead >= 5n ? 5n : lead >= 2n ? 2n : 1n;
+        sizes.push(d * pow);
+        rest -= d * pow;
+    }
+    return { sizes, rest };
+}
+export function hashExtData(ext) {
+    return BigInt(keccak256(encodeAbiParameters(EXT_DATA_ABI, [ext]))) % FIELD_SIZE;
+}
+const fieldMod = (x) => ((x % FIELD_SIZE) + FIELD_SIZE) % FIELD_SIZE;
+/**
+ * Build and prove a 2-in/2-out shielded transaction. `data` is bound into the proof through `extDataHash`, which is
+ * what lets the router act on a withdrawal without trusting whoever submits it.
+ */
+export async function buildTransaction(p) {
+    const extAmount = p.extAmount ?? 0n;
+    const fee = p.fee ?? 0n;
+    if (p.inputs.length > 2 || p.outputs.length > 2)
+        throw new Error("max 2 inputs and 2 outputs");
+    const ins = [...p.inputs];
+    while (ins.length < 2) {
+        const privKey = randomField();
+        ins.push({ amount: 0n, privKey, pubKey: await poseidon([privKey]), blinding: randomField(), leafIndex: 0 });
+    }
+    const outs = p.outputs.map((o) => ({ ...o, blinding: o.blinding ?? randomField() }));
+    while (outs.length < 2)
+        outs.push({ amount: 0n, pubKey: p.dummyPubKey, blinding: randomField(), memo: p.dummyMemo });
+    for (const o of outs)
+        if (o.amount < 0n || o.amount >= MAX_NOTE_AMOUNT)
+            throw new Error("output amount out of range");
+    const sumIn = ins.reduce((s, n) => s + n.amount, 0n);
+    const sumOut = outs.reduce((s, n) => s + n.amount, 0n);
+    if (sumIn + extAmount - fee !== sumOut)
+        throw new Error("unbalanced transaction");
+    const root = await p.tree.root();
+    const inPathElements = [];
+    for (const n of ins) {
+        if (n.amount === 0n) {
+            inPathElements.push(new Array(LEVELS).fill(0n));
+            continue;
+        }
+        const path = await p.tree.path(n.leafIndex);
+        if (path.root !== root)
+            throw new Error("merkle path does not match root");
+        inPathElements.push(path.pathElements);
+    }
+    const extData = {
+        recipient: p.recipient ?? zeroAddress,
+        extAmount,
+        relayer: p.relayer ?? zeroAddress,
+        fee,
+        encryptedOutput1: outs[0].memo(outs[0].blinding),
+        encryptedOutput2: outs[1].memo(outs[1].blinding),
+        data: p.data ?? "0x",
+    };
+    const proof = await p.prover({
+        root,
+        publicAmount: fieldMod(extAmount - fee),
+        extDataHash: hashExtData(extData),
+        inputNullifier: await Promise.all(ins.map((n) => nullifierOf(n, n.leafIndex, n.privKey))),
+        outputCommitment: await Promise.all(outs.map((o) => noteCommitment(o))),
+        inAmount: ins.map((n) => n.amount),
+        inPrivateKey: ins.map((n) => n.privKey),
+        inBlinding: ins.map((n) => n.blinding),
+        inPathIndices: ins.map((n) => BigInt(n.leafIndex)),
+        inPathElements,
+        outAmount: outs.map((o) => o.amount),
+        outPubkey: outs.map((o) => o.pubKey),
+        outBlinding: outs.map((o) => o.blinding),
+    });
+    return { proof, extData };
+}
+/** Pick 1–2 notes covering `target` (smallest single note, else the tightest pair). */
+export function selectNotes(notes, target) {
+    const live = notes.filter((n) => !n.spent).sort((a, b) => (a.amount < b.amount ? -1 : 1));
+    const single = live.find((n) => n.amount >= target);
+    if (single)
+        return { inputs: [single] };
+    let best = null;
+    let bestSum = 0n;
+    for (let i = 0; i < live.length; i++)
+        for (let j = i + 1; j < live.length; j++) {
+            const s = live[i].amount + live[j].amount;
+            if (s >= target && (!best || s < bestSum)) {
+                best = [live[i], live[j]];
+                bestSum = s;
+            }
+        }
+    if (best)
+        return { inputs: best };
+    const total = live.reduce((s, n) => s + n.amount, 0n);
+    if (total < target || live.length < 2)
+        throw new Error("insufficient private balance");
+    return { merge: live.slice(-2) };
+}

package/dist/seal.d.ts

@@ -0,0 +1,17 @@
+import type { Address, Hex } from "viem";
+/** What a sealed bid hides until its drand round: everything needed to call `reveal`. */
+export interface BidPreimage {
+    auction: Address;
+    bidder: Address;
+    tick: number;
+    quantity: bigint;
+    salt: Hex;
+}
+/** First drand quicknet round that is published at or after `unixSeconds`. */
+export declare function drandRoundAt(unixSeconds: number): number;
+/** Unix time (seconds) at which a drand quicknet round is published. */
+export declare function drandRoundTime(round: number): number;
+/** Encrypt a bid preimage to a future drand round. Nobody — sequencer, DA committee, us — can open it early. */
+export declare function sealBid(p: BidPreimage, round: number): Promise<Hex>;
+/** Decrypt a sealed bid once its round is out. Throws before that (the beacon has not released the key). */
+export declare function unsealBid(sealed: Hex): Promise<BidPreimage>;

package/dist/seal.js

@@ -0,0 +1,41 @@
+import { timelockDecrypt, timelockEncrypt, mainnetClient, roundAt, defaultChainInfo, Buffer } from "tlock-js";
+import { bytesToString, stringToHex, hexToString } from "viem";
+let client;
+const drand = () => (client ??= mainnetClient()); // drand quicknet, 3 s rounds
+/** First drand quicknet round that is published at or after `unixSeconds`. */
+export function drandRoundAt(unixSeconds) {
+    return roundAt(unixSeconds * 1000, defaultChainInfo) + 1;
+}
+/** Unix time (seconds) at which a drand quicknet round is published. */
+export function drandRoundTime(round) {
+    return defaultChainInfo.genesis_time + (round - 1) * defaultChainInfo.period;
+}
+/** Encrypt a bid preimage to a future drand round. Nobody — sequencer, DA committee, us — can open it early. */
+export async function sealBid(p, round) {
+    const json = JSON.stringify({ v: 1, a: p.auction, b: p.bidder, t: p.tick, q: p.quantity.toString(), s: p.salt });
+    const armored = await timelockEncrypt(round, Buffer.from(json), drand());
+    return stringToHex(armored);
+}
+// tlock-js logs every beacon it fetches; keep keeper output readable.
+async function quiet(fn) {
+    const log = console.log;
+    console.log = (...a) => {
+        if (typeof a[0] === "string" && a[0].startsWith("beacon received"))
+            return;
+        log(...a);
+    };
+    try {
+        return await fn();
+    }
+    finally {
+        console.log = log;
+    }
+}
+/** Decrypt a sealed bid once its round is out. Throws before that (the beacon has not released the key). */
+export async function unsealBid(sealed) {
+    const plain = await quiet(() => timelockDecrypt(hexToString(sealed), drand()));
+    const j = JSON.parse(bytesToString(new Uint8Array(plain)));
+    if (j.v !== 1)
+        throw new Error("unknown sealed bid version");
+    return { auction: j.a, bidder: j.b, tick: Number(j.t), quantity: BigInt(j.q), salt: j.s };
+}