@claviss/sdk 0.1.0

package/dist/shielded/keypair.js

@@ -0,0 +1,72 @@
+import { buildPoseidon } from "circomlibjs";
+import { x25519 } from "@noble/curves/ed25519";
+import { sha256 } from "@noble/hashes/sha256";
+// BN254 scalar field.
+export const FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+let _poseidon;
+export async function poseidon() {
+    if (!_poseidon)
+        _poseidon = await buildPoseidon();
+    return _poseidon;
+}
+export async function H(xs) {
+    const p = await poseidon();
+    return BigInt(p.F.toString(p(xs)));
+}
+const enc = new TextEncoder();
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+function bytesToField(b) {
+    let v = 0n;
+    for (const x of b)
+        v = (v << 8n) | BigInt(x);
+    return v % FIELD;
+}
+function toBytes32(v) {
+    const out = new Uint8Array(32);
+    let x = v;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+    return out;
+}
+function b64url(bytes) {
+    let s = "";
+    for (const x of bytes)
+        s += String.fromCharCode(x);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s) {
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Derive a shielded identity from a 32+ byte seed (e.g. a wallet signature). */
+export async function deriveShieldedKeypair(seed) {
+    const privateKey = bytesToField(sha256(concat(seed, enc.encode("clavis-shielded-spend"))));
+    const encPriv = sha256(concat(seed, enc.encode("clavis-shielded-enc")));
+    return {
+        privateKey,
+        publicKey: await H([privateKey]),
+        encPriv,
+        encPub: x25519.getPublicKey(encPriv),
+    };
+}
+/** Shareable shielded address = base64url(publicKey || encPub). */
+export function encodeShieldedAddress(kp) {
+    return b64url(concat(toBytes32(kp.publicKey), kp.encPub));
+}
+export function decodeShieldedAddress(s) {
+    const bytes = unb64url(s.trim());
+    if (bytes.length !== 64)
+        throw new Error("invalid shielded address");
+    return { publicKey: bytesToField(bytes.slice(0, 32)), encPub: bytes.slice(32, 64) };
+}

package/dist/shielded/note.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A shielded UTXO. `amount` and `blinding` are secret; `pubkey` is the owner's
+ * shielded publicKey. commitment = Poseidon(amount, pubkey, blinding).
+ */
+export interface Note {
+    amount: bigint;
+    pubkey: bigint;
+    blinding: bigint;
+}
+export declare function randomBlinding(): bigint;
+export declare function newNote(amount: bigint, pubkey: bigint): Note;
+export declare const commitment: (n: Note) => Promise<bigint>;
+/** nullifier = Poseidon(commitment, Poseidon(privateKey, commitment)). Needs the
+ *  owner's spending key, so only the owner can spend the note. */
+export declare function nullifier(n: Note, privateKey: bigint): Promise<bigint>;
+/** Encrypt a note's secret (amount, blinding) to a recipient's X25519 enc key. */
+export declare function encryptNoteSecret(n: Note, recipientEncPub: Uint8Array): Promise<string>;
+/** Decrypt a note secret with the owner's X25519 enc key. Throws if not ours. */
+export declare function decryptNoteSecret(blob: string, encPriv: Uint8Array): Promise<{
+    amount: bigint;
+    blinding: bigint;
+}>;

package/dist/shielded/note.js

@@ -0,0 +1,32 @@
+import { H, FIELD } from "./keypair.js";
+import { encryptNote as eciesEncrypt, decryptNote as eciesDecrypt } from "../pool/crypto.js";
+export function randomBlinding() {
+    const b = new Uint8Array(31);
+    globalThis.crypto.getRandomValues(b);
+    let v = 0n;
+    for (const x of b)
+        v = (v << 8n) | BigInt(x);
+    return v % FIELD;
+}
+export function newNote(amount, pubkey) {
+    return { amount, pubkey, blinding: randomBlinding() };
+}
+export const commitment = (n) => H([n.amount, n.pubkey, n.blinding]);
+/** nullifier = Poseidon(commitment, Poseidon(privateKey, commitment)). Needs the
+ *  owner's spending key, so only the owner can spend the note. */
+export async function nullifier(n, privateKey) {
+    const cm = await commitment(n);
+    const sig = await H([privateKey, cm]);
+    return H([cm, sig]);
+}
+// ── note-secret encryption (so a recipient can find + spend the note) ──
+/** Encrypt a note's secret (amount, blinding) to a recipient's X25519 enc key. */
+export function encryptNoteSecret(n, recipientEncPub) {
+    return eciesEncrypt(`${n.amount.toString(16)}:${n.blinding.toString(16)}`, recipientEncPub);
+}
+/** Decrypt a note secret with the owner's X25519 enc key. Throws if not ours. */
+export async function decryptNoteSecret(blob, encPriv) {
+    const s = await eciesDecrypt(blob, encPriv);
+    const [a, b] = s.split(":");
+    return { amount: BigInt("0x" + a), blinding: BigInt("0x" + b) };
+}

package/dist/shielded/prover.d.ts

@@ -0,0 +1,56 @@
+import { ShieldedKeypair } from "./keypair.js";
+import { Note } from "./note.js";
+import { type ProofCalldata } from "../zk/calldata.js";
+/**
+ * keccak256(recipient(20) ‖ relayer(20) ‖ int256 extAmount ‖ uint256 fee) with the
+ * top 3 bits cleared — MUST match ShieldedPools.transact's abi.encodePacked hash.
+ * (Deliberately different from the Solana SDK's little-endian preimage.)
+ */
+export declare function extDataHash(recipient: `0x${string}`, relayer: `0x${string}`, extAmount: bigint, fee: bigint): bigint;
+/** publicAmount = (extAmount - fee) mod p. */
+export declare function publicAmount(extAmount: bigint, fee: bigint): bigint;
+export interface TxInput {
+    note: Note;
+    pathElements: bigint[];
+    pathIndices: number[];
+}
+export interface TxOutput {
+    note: Note;
+    /** Recipient's X25519 enc key; the note secret is encrypted to it. */
+    encPub: Uint8Array;
+}
+export interface BuildTxParams {
+    /** Real notes being spent (0–2). Padded to 2 with dummies. */
+    inputs: TxInput[];
+    /** Outputs (1–2). Padded to 2 with a dummy owned by the spender. */
+    outputs: TxOutput[];
+    /** Spender — owns every input and any padding dummies. */
+    spendKeypair: ShieldedKeypair;
+    extAmount: bigint;
+    fee: bigint;
+    recipient: `0x${string}`;
+    relayer: `0x${string}`;
+    root: bigint;
+    wasmPath: string;
+    zkeyPath: string;
+}
+/** Everything needed to call ShieldedPools.transact + feed the operator. */
+export interface FormattedTx extends ProofCalldata {
+    ext: {
+        recipient: `0x${string}`;
+        relayer: `0x${string}`;
+        extAmount: bigint;
+        fee: bigint;
+        encryptedOutput1: `0x${string}`;
+        encryptedOutput2: `0x${string}`;
+    };
+    nullifiers: bigint[];
+    outputCommitments: bigint[];
+    /** Encrypted note secrets, aligned to outputCommitments — hand to the operator. */
+    encryptedSecrets: string[];
+}
+/**
+ * Build a hidden-amount transaction proof for ShieldedPools.transact.
+ * Caller must ensure Σinputs + extAmount == Σoutputs + fee.
+ */
+export declare function buildTransaction(p: BuildTxParams): Promise<FormattedTx>;

package/dist/shielded/prover.js

@@ -0,0 +1,100 @@
+import { groth16 } from "snarkjs";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { FIELD } from "./keypair.js";
+import { newNote, commitment, nullifier, encryptNoteSecret } from "./note.js";
+import { toCalldata } from "../zk/calldata.js";
+const LEVELS = 20;
+function addrBytes(addr) {
+    const hex = addr.slice(2).padStart(40, "0");
+    return Uint8Array.from(hex.match(/../g).map((b) => parseInt(b, 16)));
+}
+function be32(v) {
+    const out = new Uint8Array(32);
+    let x = BigInt.asUintN(256, v);
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+    return out;
+}
+/**
+ * keccak256(recipient(20) ‖ relayer(20) ‖ int256 extAmount ‖ uint256 fee) with the
+ * top 3 bits cleared — MUST match ShieldedPools.transact's abi.encodePacked hash.
+ * (Deliberately different from the Solana SDK's little-endian preimage.)
+ */
+export function extDataHash(recipient, relayer, extAmount, fee) {
+    const buf = new Uint8Array(104);
+    buf.set(addrBytes(recipient), 0);
+    buf.set(addrBytes(relayer), 20);
+    buf.set(be32(extAmount), 40);
+    buf.set(be32(fee), 72);
+    let v = 0n;
+    for (const b of keccak_256(buf))
+        v = (v << 8n) | BigInt(b);
+    return v & ((1n << 253n) - 1n);
+}
+/** publicAmount = (extAmount - fee) mod p. */
+export function publicAmount(extAmount, fee) {
+    let v = extAmount - fee;
+    if (v < 0n)
+        v += FIELD;
+    return v % FIELD;
+}
+const zeros = (n) => Array(n).fill("0");
+function utf8Hex(s) {
+    let out = "0x";
+    for (const b of new TextEncoder().encode(s))
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+/**
+ * Build a hidden-amount transaction proof for ShieldedPools.transact.
+ * Caller must ensure Σinputs + extAmount == Σoutputs + fee.
+ */
+export async function buildTransaction(p) {
+    const sk = p.spendKeypair;
+    const inputs = [...p.inputs];
+    while (inputs.length < 2) {
+        inputs.push({
+            note: newNote(0n, sk.publicKey),
+            pathElements: zeros(LEVELS).map(BigInt),
+            pathIndices: Array(LEVELS).fill(0),
+        });
+    }
+    const outputs = [...p.outputs];
+    while (outputs.length < 2)
+        outputs.push({ note: newNote(0n, sk.publicKey), encPub: sk.encPub });
+    const inNullifiers = await Promise.all(inputs.map((i) => nullifier(i.note, sk.privateKey)));
+    const outCommitments = await Promise.all(outputs.map((o) => commitment(o.note)));
+    const encryptedSecrets = await Promise.all(outputs.map((o) => encryptNoteSecret(o.note, o.encPub)));
+    const witness = {
+        root: p.root.toString(),
+        publicAmount: publicAmount(p.extAmount, p.fee).toString(),
+        extDataHash: extDataHash(p.recipient, p.relayer, p.extAmount, p.fee).toString(),
+        inputNullifier: inNullifiers.map(String),
+        outputCommitment: outCommitments.map(String),
+        inAmount: inputs.map((i) => i.note.amount.toString()),
+        inPrivateKey: inputs.map(() => sk.privateKey.toString()),
+        inBlinding: inputs.map((i) => i.note.blinding.toString()),
+        inPathIndices: inputs.map((i) => i.pathIndices.map(String)),
+        inPathElements: inputs.map((i) => i.pathElements.map(String)),
+        outAmount: outputs.map((o) => o.note.amount.toString()),
+        outPubkey: outputs.map((o) => o.note.pubkey.toString()),
+        outBlinding: outputs.map((o) => o.note.blinding.toString()),
+    };
+    const raw = await groth16.fullProve(witness, p.wasmPath, p.zkeyPath);
+    return {
+        ...toCalldata(raw),
+        ext: {
+            recipient: p.recipient,
+            relayer: p.relayer,
+            extAmount: p.extAmount,
+            fee: p.fee,
+            encryptedOutput1: utf8Hex(encryptedSecrets[0]),
+            encryptedOutput2: utf8Hex(encryptedSecrets[1]),
+        },
+        nullifiers: inNullifiers,
+        outputCommitments: outCommitments,
+        encryptedSecrets,
+    };
+}

package/dist/shielded/scan.d.ts

@@ -0,0 +1,21 @@
+import { ShieldedKeypair } from "./keypair.js";
+import { Note } from "./note.js";
+/** One output emitted by `transact`, paired with its encrypted secret. */
+export interface OutputRecord {
+    commitment: bigint;
+    encryptedSecret: string;
+    leafIndex: number;
+}
+export interface OwnedNote extends Note {
+    leafIndex: number;
+    nullifier: bigint;
+}
+/**
+ * Scan emitted outputs for notes owned by `kp`: decrypt each secret, and keep it
+ * if the reconstructed commitment matches and the amount is non-zero. Returns
+ * spendable UTXOs (callers should drop any whose nullifier is already spent
+ * on-chain).
+ */
+export declare function scanOutputs(records: OutputRecord[], kp: ShieldedKeypair): Promise<OwnedNote[]>;
+/** Total spendable balance from a set of owned notes. */
+export declare const balance: (notes: OwnedNote[]) => bigint;

package/dist/shielded/scan.js

@@ -0,0 +1,28 @@
+import { commitment, nullifier, decryptNoteSecret } from "./note.js";
+/**
+ * Scan emitted outputs for notes owned by `kp`: decrypt each secret, and keep it
+ * if the reconstructed commitment matches and the amount is non-zero. Returns
+ * spendable UTXOs (callers should drop any whose nullifier is already spent
+ * on-chain).
+ */
+export async function scanOutputs(records, kp) {
+    const owned = [];
+    for (const r of records) {
+        let secret;
+        try {
+            secret = await decryptNoteSecret(r.encryptedSecret, kp.encPriv);
+        }
+        catch {
+            continue; // not encrypted to us
+        }
+        const note = { amount: secret.amount, pubkey: kp.publicKey, blinding: secret.blinding };
+        if (secret.amount === 0n)
+            continue;
+        if ((await commitment(note)) !== r.commitment)
+            continue;
+        owned.push({ ...note, leafIndex: r.leafIndex, nullifier: await nullifier(note, kp.privateKey) });
+    }
+    return owned;
+}
+/** Total spendable balance from a set of owned notes. */
+export const balance = (notes) => notes.reduce((s, n) => s + n.amount, 0n);

package/dist/stealth/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./stealth.js";
+export * from "./scanner.js";

package/dist/stealth/index.js

@@ -0,0 +1,2 @@
+export * from "./stealth.js";
+export * from "./scanner.js";

package/dist/stealth/scanner.d.ts

@@ -0,0 +1,20 @@
+import { StealthKeys } from "./stealth.js";
+/** One published announcement: the sender's ephemeral key + a view tag. */
+export interface Announcement {
+    ephemeralPub: Uint8Array;
+    viewTag: number;
+    stealthPub?: Uint8Array;
+    slot?: number;
+    signature?: string;
+}
+export interface DetectedPayment {
+    stealthPub: Uint8Array;
+    stealthScalar: bigint;
+    announcement: Announcement;
+}
+/**
+ * Scan a batch of announcements for payments addressed to `keys`.
+ * The view tag lets us reject ~255/256 of non-matching announcements with a
+ * single hash before doing the full point recovery.
+ */
+export declare function scanAnnouncements(keys: StealthKeys, announcements: Announcement[]): DetectedPayment[];

package/dist/stealth/scanner.js

@@ -0,0 +1,31 @@
+import { recoverStealth } from "./stealth.js";
+/**
+ * Scan a batch of announcements for payments addressed to `keys`.
+ * The view tag lets us reject ~255/256 of non-matching announcements with a
+ * single hash before doing the full point recovery.
+ */
+export function scanAnnouncements(keys, announcements) {
+    const found = [];
+    for (const ann of announcements) {
+        const res = recoverStealth(keys, ann.ephemeralPub, ann.viewTag);
+        if (!res)
+            continue;
+        // If the registry recorded the destination, confirm it matches ours.
+        if (ann.stealthPub && !equal(ann.stealthPub, res.stealthPub))
+            continue;
+        found.push({
+            stealthPub: res.stealthPub,
+            stealthScalar: res.stealthScalar,
+            announcement: ann,
+        });
+    }
+    return found;
+}
+function equal(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}

package/dist/stealth/stealth.d.ts

@@ -0,0 +1,41 @@
+export interface MetaAddress {
+    spendPub: Uint8Array;
+    viewPub: Uint8Array;
+}
+export interface StealthKeys {
+    spendScalar: bigint;
+    viewScalar: bigint;
+    meta: MetaAddress;
+}
+export interface StealthOutput {
+    stealthPub: Uint8Array;
+    stealthAddress: `0x${string}`;
+    ephemeralPub: Uint8Array;
+    viewTag: number;
+}
+/** EVM address of a secp256k1 point: keccak256(uncompressed[1:])[12:]. */
+export declare function pubToAddress(pub: Uint8Array): `0x${string}`;
+/** The recovered stealth scalar as a 0x private key for viem's privateKeyToAccount. */
+export declare function stealthScalarToPrivateKey(scalar: bigint): `0x${string}`;
+/** Generate a recipient's stealth key material + shareable meta-address. */
+export declare function generateStealthKeys(): StealthKeys;
+/**
+ * Derive a recipient's stealth keys deterministically from a `seed` — typically
+ * the recipient's signature over a fixed message from their main wallet.
+ * Spend and view scalars are domain-separated so the view key (shareable with a
+ * scanning service) never leaks the spend key.
+ */
+export declare function deriveStealthKeys(seed: Uint8Array): StealthKeys;
+/**
+ * SENDER: derive a one-time stealth address for a recipient's meta-address.
+ * Publish `ephemeralPub` (R) and `viewTag` so the recipient can detect it.
+ */
+export declare function deriveStealthAddress(meta: MetaAddress): StealthOutput;
+/**
+ * RECIPIENT: given an announced ephemeral key R, recompute the stealth pubkey
+ * and (if it's ours) the one-time private scalar. Returns null if no match.
+ */
+export declare function recoverStealth(keys: StealthKeys, ephemeralPub: Uint8Array, expectedViewTag?: number): {
+    stealthPub: Uint8Array;
+    stealthScalar: bigint;
+} | null;

package/dist/stealth/stealth.js

@@ -0,0 +1,122 @@
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { sha512 } from "@noble/hashes/sha512";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { bytesToNumberBE, numberToBytesBE } from "@noble/curves/abstract/utils";
+/**
+ * Dual-key stealth addresses on secp256k1 (ERC-5564 style, EVM-native).
+ *
+ * A recipient publishes a META-ADDRESS made of two compressed public keys:
+ *   - spend public key  S = s*G   (controls spending)
+ *   - view public key   V = v*G   (lets the recipient scan cheaply)
+ *
+ * A sender, knowing (S, V), derives a fresh one-time stealth address per payment
+ * and publishes only an ephemeral public key R. Nobody watching the chain can
+ * link the stealth address back to the recipient's meta-address.
+ *
+ * Unlike the Solana/ed25519 version, spending needs no custom signer: the
+ * recovered `stealthScalar` IS a normal secp256k1 private key — load it with
+ * viem's privateKeyToAccount and send from the stealth address directly
+ * (the sweep transaction pays its own gas from the received funds).
+ */
+const N = secp256k1.CURVE.n; // group order
+const Point = secp256k1.ProjectivePoint;
+function concat(parts) {
+    const len = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(len);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function hashToScalar(...chunks) {
+    const h = sha512(concat(chunks));
+    return bytesToNumberBE(h) % N;
+}
+/** EVM address of a secp256k1 point: keccak256(uncompressed[1:])[12:]. */
+export function pubToAddress(pub) {
+    const uncompressed = Point.fromHex(pub).toRawBytes(false);
+    const h = keccak_256(uncompressed.slice(1));
+    let s = "0x";
+    for (const b of h.slice(12))
+        s += b.toString(16).padStart(2, "0");
+    return s;
+}
+/** The recovered stealth scalar as a 0x private key for viem's privateKeyToAccount. */
+export function stealthScalarToPrivateKey(scalar) {
+    let s = "0x";
+    for (const b of numberToBytesBE(scalar, 32))
+        s += b.toString(16).padStart(2, "0");
+    return s;
+}
+/** Generate a recipient's stealth key material + shareable meta-address. */
+export function generateStealthKeys() {
+    const s = bytesToNumberBE(secp256k1.utils.randomPrivateKey()) % N;
+    const v = bytesToNumberBE(secp256k1.utils.randomPrivateKey()) % N;
+    return {
+        spendScalar: s,
+        viewScalar: v,
+        meta: {
+            spendPub: Point.BASE.multiply(s).toRawBytes(true),
+            viewPub: Point.BASE.multiply(v).toRawBytes(true),
+        },
+    };
+}
+/**
+ * Derive a recipient's stealth keys deterministically from a `seed` — typically
+ * the recipient's signature over a fixed message from their main wallet.
+ * Spend and view scalars are domain-separated so the view key (shareable with a
+ * scanning service) never leaks the spend key.
+ */
+export function deriveStealthKeys(seed) {
+    const enc = new TextEncoder();
+    const s = hashToScalar(enc.encode("clavis:stealth:spend:v1"), seed);
+    const v = hashToScalar(enc.encode("clavis:stealth:view:v1"), seed);
+    return {
+        spendScalar: s,
+        viewScalar: v,
+        meta: {
+            spendPub: Point.BASE.multiply(s).toRawBytes(true),
+            viewPub: Point.BASE.multiply(v).toRawBytes(true),
+        },
+    };
+}
+/**
+ * SENDER: derive a one-time stealth address for a recipient's meta-address.
+ * Publish `ephemeralPub` (R) and `viewTag` so the recipient can detect it.
+ */
+export function deriveStealthAddress(meta) {
+    const r = bytesToNumberBE(secp256k1.utils.randomPrivateKey()) % N;
+    const R = Point.BASE.multiply(r).toRawBytes(true);
+    const Vpoint = Point.fromHex(meta.viewPub);
+    const shared = Vpoint.multiply(r).toRawBytes(true); // r*V = (r*v)*G
+    const tweak = hashToScalar(shared);
+    const Spoint = Point.fromHex(meta.spendPub);
+    const stealth = Spoint.add(Point.BASE.multiply(tweak)); // P = S + tweak*G
+    const stealthPub = stealth.toRawBytes(true);
+    const viewTag = keccak_256(concat([new Uint8Array([0x01]), shared]))[0];
+    return {
+        stealthPub,
+        stealthAddress: pubToAddress(stealthPub),
+        ephemeralPub: R,
+        viewTag,
+    };
+}
+/**
+ * RECIPIENT: given an announced ephemeral key R, recompute the stealth pubkey
+ * and (if it's ours) the one-time private scalar. Returns null if no match.
+ */
+export function recoverStealth(keys, ephemeralPub, expectedViewTag) {
+    const Rpoint = Point.fromHex(ephemeralPub);
+    const shared = Rpoint.multiply(keys.viewScalar).toRawBytes(true); // v*R = (r*v)*G
+    if (expectedViewTag !== undefined) {
+        const tag = keccak_256(concat([new Uint8Array([0x01]), shared]))[0];
+        if (tag !== expectedViewTag)
+            return null; // fast reject
+    }
+    const tweak = hashToScalar(shared);
+    const stealthScalar = (keys.spendScalar + tweak) % N; // p = s + tweak
+    const stealthPub = Point.BASE.multiply(stealthScalar).toRawBytes(true);
+    return { stealthPub, stealthScalar };
+}

package/dist/zk/calldata.d.ts

@@ -0,0 +1,21 @@
+/**
+ * snarkjs proof → Solidity-verifier calldata shape:
+ *   verifyProof(uint[2] pA, uint[2][2] pB, uint[2] pC, uint[N] signals)
+ * pB rows swap the c1/c0 ordering snarkjs emits (standard EVM convention);
+ * unlike the Solana verifier, A is NOT negated.
+ */
+export interface ProofCalldata {
+    pA: [bigint, bigint];
+    pB: [[bigint, bigint], [bigint, bigint]];
+    pC: [bigint, bigint];
+    signals: bigint[];
+}
+export interface RawProof {
+    proof: {
+        pi_a: string[];
+        pi_b: string[][];
+        pi_c: string[];
+    };
+    publicSignals: string[];
+}
+export declare function toCalldata({ proof, publicSignals }: RawProof): ProofCalldata;

package/dist/zk/calldata.js

@@ -0,0 +1,11 @@
+export function toCalldata({ proof, publicSignals }) {
+    return {
+        pA: [BigInt(proof.pi_a[0]), BigInt(proof.pi_a[1])],
+        pB: [
+            [BigInt(proof.pi_b[0][1]), BigInt(proof.pi_b[0][0])],
+            [BigInt(proof.pi_b[1][1]), BigInt(proof.pi_b[1][0])],
+        ],
+        pC: [BigInt(proof.pi_c[0]), BigInt(proof.pi_c[1])],
+        signals: publicSignals.map(BigInt),
+    };
+}

package/dist/zk/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./merkle.js";
+export * from "./prover.js";
+export * from "./calldata.js";

package/dist/zk/index.js

@@ -0,0 +1,3 @@
+export * from "./merkle.js";
+export * from "./prover.js";
+export * from "./calldata.js";

package/dist/zk/merkle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Poseidon Merkle tree whose hashing matches circuits/credential.circom:
+ *   parent = Poseidon(left, right)
+ *   leaf   = Poseidon(secret)   // identity commitment
+ *
+ * Fixed depth; empty slots are filled with a zero subtree so the root is
+ * stable. Keep `depth` in sync with the circuit (default 20).
+ */
+export declare class PoseidonMerkleTree {
+    private poseidon;
+    private F;
+    readonly depth: number;
+    private zeros;
+    private layers;
+    private constructor();
+    static create(depth?: number): Promise<PoseidonMerkleTree>;
+    private toBig;
+    hash1(a: bigint): bigint;
+    hash2(a: bigint, b: bigint): bigint;
+    /** identity commitment for a secret */
+    commitment(secret: bigint): bigint;
+    /** insert a leaf (already a commitment) and return its index */
+    insert(leaf: bigint): number;
+    /**
+     * Insert many leaves and rebuild once — O(n) total instead of O(n²) from
+     * calling insert() in a loop. Use this to load a tree from a commitment list.
+     */
+    insertMany(leaves: bigint[]): void;
+    private rebuild;
+    root(): bigint;
+    /** Merkle proof for the leaf at `index`, formatted for the circuit. */
+    proof(index: number): {
+        pathElements: bigint[];
+        pathIndices: number[];
+    };
+}