@veilo/sdk-core 0.1.17 → 0.4.0

package/dist/esm/compactNote.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Compact note ciphers — the 80-byte payload carried inside the on-chain
+ * `transact` instruction (`note_ciphers: Option<NoteCiphers>`) and re-emitted in
+ * `CommitmentEvent`.
+ *
+ * This is what makes a note recoverable from chain data alone: a recipient who
+ * was never told about a deposit can still find it by scanning `view_tag` and
+ * decrypting the blob. Without it, note delivery depends on someone calling the
+ * relayer, which a third-party integrator cannot be trusted to do.
+ *
+ * ## Byte-compatibility is load-bearing
+ *
+ * Four sibling implementations already exist (relayer-server, extension ×2,
+ * wallet-app). This is the canonical one, and it MUST agree with them byte for
+ * byte in both directions:
+ *
+ *   - disagree on encrypt → new notes are invisible to every existing client
+ *   - disagree on decrypt → the entire historical note corpus becomes unreadable
+ *
+ * Three details are easy to get wrong and are individually fatal:
+ *
+ *  1. The KDF is `nacl.hash(x).slice(0, 32)` — **truncated SHA-512**, despite the
+ *     sibling helper being named `sha256ForNotes`. See `kdfSHA512_256` in utxo.ts.
+ *  2. The ephemeral key published on-chain is **Ed25519**; it is converted to
+ *     X25519 only for the Diffie-Hellman. Scanners convert it back.
+ *  3. `viewTag` is the first byte of the hash of the **raw shared secret**, not of
+ *     the derived key. A wrong view tag makes every note invisible to the scan
+ *     loop, which rejects ~255/256 candidates on this byte alone.
+ *
+ * The ECDH primitives are imported from `utxo.ts` rather than reimplemented — a
+ * fifth independent Edwards→Montgomery implementation is exactly how the current
+ * drift risk between the four siblings arose.
+ *
+ * Verified against the siblings by `tests/compact-note.test.ts` (golden vectors)
+ * and `scripts/verify-compact-cipher-parity.mjs` (differential).
+ */
+/** Size of the on-chain compact blob: nonce[24] || secretbox(40-byte plaintext)[56]. */
+export declare const COMPACT_BLOB_LENGTH = 80;
+export type CompactNoteCipher = {
+    /** Ed25519 ephemeral public key, published on-chain. */
+    ephemeralPublicKey: Uint8Array;
+    /** 80 bytes: nonce[24] || ciphertext[56]. */
+    compactBlob: Uint8Array;
+    /** 1-byte scan filter. */
+    viewTag: number;
+};
+/**
+ * Test-only determinism hook. NOT part of the public contract — it exists so
+ * golden vectors can pin exact bytes against the sibling implementations, which
+ * is the only way to prove byte-compatibility rather than assume it.
+ *
+ * @internal
+ */
+export type CompactNoteDeterminism = {
+    ephemeralSeed: Uint8Array;
+    nonce: Uint8Array;
+};
+/**
+ * Encrypt a note's secret material to a recipient's Solana wallet key.
+ *
+ * The recipient does not need to be the signer of the transaction, or to have
+ * any prior relationship with the sender — this is what makes shielding to an
+ * arbitrary owner possible.
+ *
+ * @param recipientWalletPubkey 32-byte Ed25519 Solana wallet public key
+ * @param blinding              32-byte big-endian blinding factor
+ * @param amount                note amount in base units
+ */
+export declare function createCompactNoteCipher(recipientWalletPubkey: Uint8Array, blinding: Uint8Array, amount: bigint, 
+/** @internal */ __det?: CompactNoteDeterminism): CompactNoteCipher;
+/**
+ * Recover a note's blinding and amount from an on-chain compact cipher.
+ *
+ * Returns `null` when the blob was not encrypted to this key — the expected
+ * outcome for the overwhelming majority of candidates during a scan, so callers
+ * should filter on `viewTag` first (see {@link matchesViewTag}) and only attempt
+ * decryption on the ~1/256 that survive.
+ *
+ * @param walletSecretKey 32-byte Ed25519 seed or 64-byte secret key
+ */
+export declare function decryptCompactNoteCipher(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, compactBlob: Uint8Array, precomputed?: {
+    sharedSecret?: Uint8Array;
+    x25519Private?: Uint8Array;
+}): {
+    blinding: Uint8Array;
+    amount: bigint;
+} | null;
+/**
+ * Cheap scan filter: does this on-chain cipher plausibly belong to us?
+ *
+ * Rejects ~255/256 candidates for the cost of one scalar multiplication and one
+ * hash, versus a full secretbox open. Hoist `x25519Private` across a scan loop
+ * with {@link toX25519Private}.
+ */
+export declare function matchesViewTag(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, viewTag: number, precomputed?: {
+    x25519Private?: Uint8Array;
+}): {
+    matches: boolean;
+    sharedSecret: Uint8Array;
+};
+/**
+ * Convert an Ed25519 wallet secret key to its X25519 scalar once, for reuse
+ * across a scan loop.
+ */
+export declare function toX25519Private(walletSecretKey: Uint8Array): Uint8Array;
+/** The all-zero cipher the program treats as "no note here". */
+export declare function emptyNoteCipher(): CompactNoteCipher;

package/dist/esm/compactNote.js

@@ -0,0 +1,156 @@
+import nacl from "tweetnacl";
+import { ed25519PublicKeyToX25519, ed25519SeedToX25519Private, kdfSHA512_256, } from "./utxo.js";
+import { randomBytes } from "./random.js";
+/**
+ * Compact note ciphers — the 80-byte payload carried inside the on-chain
+ * `transact` instruction (`note_ciphers: Option<NoteCiphers>`) and re-emitted in
+ * `CommitmentEvent`.
+ *
+ * This is what makes a note recoverable from chain data alone: a recipient who
+ * was never told about a deposit can still find it by scanning `view_tag` and
+ * decrypting the blob. Without it, note delivery depends on someone calling the
+ * relayer, which a third-party integrator cannot be trusted to do.
+ *
+ * ## Byte-compatibility is load-bearing
+ *
+ * Four sibling implementations already exist (relayer-server, extension ×2,
+ * wallet-app). This is the canonical one, and it MUST agree with them byte for
+ * byte in both directions:
+ *
+ *   - disagree on encrypt → new notes are invisible to every existing client
+ *   - disagree on decrypt → the entire historical note corpus becomes unreadable
+ *
+ * Three details are easy to get wrong and are individually fatal:
+ *
+ *  1. The KDF is `nacl.hash(x).slice(0, 32)` — **truncated SHA-512**, despite the
+ *     sibling helper being named `sha256ForNotes`. See `kdfSHA512_256` in utxo.ts.
+ *  2. The ephemeral key published on-chain is **Ed25519**; it is converted to
+ *     X25519 only for the Diffie-Hellman. Scanners convert it back.
+ *  3. `viewTag` is the first byte of the hash of the **raw shared secret**, not of
+ *     the derived key. A wrong view tag makes every note invisible to the scan
+ *     loop, which rejects ~255/256 candidates on this byte alone.
+ *
+ * The ECDH primitives are imported from `utxo.ts` rather than reimplemented — a
+ * fifth independent Edwards→Montgomery implementation is exactly how the current
+ * drift risk between the four siblings arose.
+ *
+ * Verified against the siblings by `tests/compact-note.test.ts` (golden vectors)
+ * and `scripts/verify-compact-cipher-parity.mjs` (differential).
+ */
+/** Size of the on-chain compact blob: nonce[24] || secretbox(40-byte plaintext)[56]. */
+export const COMPACT_BLOB_LENGTH = 80;
+/** Plaintext layout: blinding[32] || amount as little-endian u64[8]. */
+const COMPACT_PLAINTEXT_LENGTH = 40;
+const NONCE_LENGTH = 24;
+/**
+ * Encrypt a note's secret material to a recipient's Solana wallet key.
+ *
+ * The recipient does not need to be the signer of the transaction, or to have
+ * any prior relationship with the sender — this is what makes shielding to an
+ * arbitrary owner possible.
+ *
+ * @param recipientWalletPubkey 32-byte Ed25519 Solana wallet public key
+ * @param blinding              32-byte big-endian blinding factor
+ * @param amount                note amount in base units
+ */
+export function createCompactNoteCipher(recipientWalletPubkey, blinding, amount, 
+/** @internal */ __det) {
+    if (recipientWalletPubkey.length !== 32) {
+        throw new Error(`recipientWalletPubkey must be 32 bytes, got ${recipientWalletPubkey.length}`);
+    }
+    if (blinding.length < 32) {
+        throw new Error(`blinding must be at least 32 bytes, got ${blinding.length}`);
+    }
+    if (amount < 0n || amount > 0xffffffffffffffffn) {
+        throw new Error(`amount ${amount} does not fit in a u64`);
+    }
+    // Ed25519 ephemeral keypair. `nacl.sign.keyPair.fromSeed(seed)` produces the
+    // same public key as web3.js `Keypair.generate()` for the same seed, which is
+    // what the sibling implementations use — but without pulling @solana/web3.js
+    // into the crypto path.
+    const ephemeralSeed = __det?.ephemeralSeed ?? randomBytes(32);
+    const ephemeralPublicKey = nacl.sign.keyPair.fromSeed(ephemeralSeed).publicKey;
+    const sharedSecret = deriveSharedSecret(ephemeralSeed, recipientWalletPubkey);
+    const key = kdfSHA512_256(sharedSecret);
+    const plaintext = new Uint8Array(COMPACT_PLAINTEXT_LENGTH);
+    plaintext.set(blinding.slice(0, 32), 0);
+    let amt = amount;
+    for (let i = 0; i < 8; i++) {
+        plaintext[32 + i] = Number(amt & 0xffn);
+        amt >>= 8n;
+    }
+    const nonce = __det?.nonce ?? nacl.randomBytes(NONCE_LENGTH);
+    const encrypted = nacl.secretbox(plaintext, nonce, key);
+    const compactBlob = new Uint8Array(COMPACT_BLOB_LENGTH);
+    compactBlob.set(nonce, 0);
+    compactBlob.set(encrypted, NONCE_LENGTH);
+    // First byte of the hash of the RAW shared secret — not of `key`.
+    const viewTag = nacl.hash(sharedSecret)[0];
+    return { ephemeralPublicKey, compactBlob, viewTag };
+}
+/**
+ * Recover a note's blinding and amount from an on-chain compact cipher.
+ *
+ * Returns `null` when the blob was not encrypted to this key — the expected
+ * outcome for the overwhelming majority of candidates during a scan, so callers
+ * should filter on `viewTag` first (see {@link matchesViewTag}) and only attempt
+ * decryption on the ~1/256 that survive.
+ *
+ * @param walletSecretKey 32-byte Ed25519 seed or 64-byte secret key
+ */
+export function decryptCompactNoteCipher(walletSecretKey, ephemeralPublicKey, compactBlob, precomputed) {
+    if (compactBlob.length !== COMPACT_BLOB_LENGTH)
+        return null;
+    const sharedSecret = precomputed?.sharedSecret ??
+        (precomputed?.x25519Private
+            ? nacl.scalarMult(precomputed.x25519Private, ed25519PublicKeyToX25519(ephemeralPublicKey))
+            : deriveSharedSecret(walletSecretKey, ephemeralPublicKey));
+    const key = kdfSHA512_256(sharedSecret);
+    const nonce = compactBlob.slice(0, NONCE_LENGTH);
+    const encrypted = compactBlob.slice(NONCE_LENGTH);
+    const plaintext = nacl.secretbox.open(encrypted, nonce, key);
+    if (!plaintext)
+        return null;
+    const blinding = new Uint8Array(plaintext.slice(0, 32));
+    let amount = 0n;
+    for (let i = 7; i >= 0; i--) {
+        amount = (amount << 8n) | BigInt(plaintext[32 + i]);
+    }
+    return { blinding, amount };
+}
+/**
+ * Cheap scan filter: does this on-chain cipher plausibly belong to us?
+ *
+ * Rejects ~255/256 candidates for the cost of one scalar multiplication and one
+ * hash, versus a full secretbox open. Hoist `x25519Private` across a scan loop
+ * with {@link toX25519Private}.
+ */
+export function matchesViewTag(walletSecretKey, ephemeralPublicKey, viewTag, precomputed) {
+    const sharedSecret = precomputed?.x25519Private
+        ? nacl.scalarMult(precomputed.x25519Private, ed25519PublicKeyToX25519(ephemeralPublicKey))
+        : deriveSharedSecret(walletSecretKey, ephemeralPublicKey);
+    return { matches: nacl.hash(sharedSecret)[0] === viewTag, sharedSecret };
+}
+/**
+ * Convert an Ed25519 wallet secret key to its X25519 scalar once, for reuse
+ * across a scan loop.
+ */
+export function toX25519Private(walletSecretKey) {
+    return ed25519SeedToX25519Private(seedOf(walletSecretKey));
+}
+/** The all-zero cipher the program treats as "no note here". */
+export function emptyNoteCipher() {
+    return {
+        ephemeralPublicKey: new Uint8Array(32),
+        compactBlob: new Uint8Array(COMPACT_BLOB_LENGTH),
+        viewTag: 0,
+    };
+}
+// -- internal -----------------------------------------------------------------
+/** Accept either a 32-byte Ed25519 seed or a 64-byte secret key, as the siblings do. */
+function seedOf(secretKey) {
+    return secretKey.length === 64 ? secretKey.slice(0, 32) : secretKey;
+}
+function deriveSharedSecret(mySecretKey, theirEd25519PublicKey) {
+    return nacl.scalarMult(ed25519SeedToX25519Private(seedOf(mySecretKey)), ed25519PublicKeyToX25519(theirEd25519PublicKey));
+}

package/dist/esm/config.d.ts

@@ -0,0 +1,82 @@
+import { PublicKey } from "@solana/web3.js";
+/** Default relayer fee in basis points (50 = 0.5%). */
+export declare const DEFAULT_FEE_BPS = 50;
+/** Merkle tree depth - matches on-chain MerkleTreeAccount subtrees array size */
+export declare const MERKLE_TREE_DEPTH = 22;
+/** Root history size - matches on-chain MerkleTreeAccount root_history array size */
+export declare const ROOT_HISTORY_SIZE = 256;
+/** Native SOL mint address (Pubkey::default() = all zeros) */
+export declare const NATIVE_SOL_MINT: PublicKey;
+/** Convert SOL to lamports (e.g. `sol(1.5)` → `1_500_000_000n`). */
+export declare function sol(n: number): bigint;
+/** Configuration for initializing a privacy pool */
+export type PoolInitConfig = {
+    /** Fee in basis points (0-10000, where 10000 = 100%) */
+    feeBps?: number;
+    /** Token mint address (use NATIVE_SOL_MINT for SOL pools) */
+    mintAddress: PublicKey;
+    /** Minimum deposit amount in lamports/token units */
+    minDepositAmount?: bigint;
+    /** Maximum deposit amount in lamports/token units */
+    maxDepositAmount?: bigint;
+    /** Minimum withdrawal amount in lamports/token units */
+    minWithdrawAmount?: bigint;
+    /** Maximum withdrawal amount in lamports/token units */
+    maxWithdrawAmount?: bigint;
+};
+/** On-chain PrivacyConfig account structure */
+export type PrivacyConfigAccount = {
+    bump: number;
+    vaultBump: number;
+    admin: PublicKey;
+    feeBps: number;
+    feeErrorMarginBps: number;
+    minWithdrawalFee: bigint;
+    /** Minimum fee kept by relayer on swaps (in destination token base units) */
+    minSwapFee: bigint;
+    /** Fee rate applied to swap output in basis points */
+    swapFeeBps: number;
+    totalTvl: bigint;
+    mintAddress: PublicKey;
+    minDepositAmount: bigint;
+    maxDepositAmount: bigint;
+    minWithdrawAmount: bigint;
+    maxWithdrawAmount: bigint;
+    numRelayers: number;
+    relayers: PublicKey[];
+    numTrees: number;
+    nextTreeIndex: number;
+};
+/** On-chain GlobalConfig account structure */
+export type GlobalConfigAccount = {
+    bump: number;
+    admin: PublicKey;
+    relayerEnabled: boolean;
+};
+/**
+ * Compute the relayer fee for a withdrawal.
+ * Mirrors the formula in the relayer-server:
+ *   fee = max(amount * feeBps / 10_000, minWithdrawalFee)
+ *
+ * @returns fee in base token units, and the amount that reaches the recipient
+ */
+export declare function computeWithdrawalFee(amount: bigint, feeBps: number, minWithdrawalFee: bigint): {
+    fee: bigint;
+    toRecipient: bigint;
+};
+/**
+ * Compute the relayer fee for a cross-pool swap.
+ * Mirrors the formula in the relayer-server:
+ *   relayerFee = max(estimatedOutput * swapFeeBps / 10_000, minSwapFee)
+ *   destAmount  = minAmountOut - relayerFee
+ *
+ * @param estimatedOutput  Jupiter quote output amount
+ * @param swapFeeBps       From the destination pool's PrivacyConfigAccount
+ * @param minSwapFee       From the destination pool's PrivacyConfigAccount
+ * @param minAmountOut     User-agreed minimum swap output (after slippage)
+ * @returns relayerFee and the amount committed into the destination UTXO
+ */
+export declare function computeSwapFee(estimatedOutput: bigint, swapFeeBps: number, minSwapFee: bigint, minAmountOut: bigint): {
+    relayerFee: bigint;
+    destAmount: bigint;
+};

package/dist/esm/config.js

@@ -0,0 +1,51 @@
+import { LAMPORTS_PER_SOL, PublicKey } from "@solana/web3.js";
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+/** Default relayer fee in basis points (50 = 0.5%). */
+export const DEFAULT_FEE_BPS = 50;
+/** Merkle tree depth - matches on-chain MerkleTreeAccount subtrees array size */
+export const MERKLE_TREE_DEPTH = 22;
+/** Root history size - matches on-chain MerkleTreeAccount root_history array size */
+export const ROOT_HISTORY_SIZE = 256;
+/** Native SOL mint address (Pubkey::default() = all zeros) */
+export const NATIVE_SOL_MINT = PublicKey.default;
+// -----------------------------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------------------------
+/** Convert SOL to lamports (e.g. `sol(1.5)` → `1_500_000_000n`). */
+export function sol(n) {
+    return BigInt(n * LAMPORTS_PER_SOL);
+}
+// -----------------------------------------------------------------------------
+// Fee Calculation Helpers
+// -----------------------------------------------------------------------------
+/**
+ * Compute the relayer fee for a withdrawal.
+ * Mirrors the formula in the relayer-server:
+ *   fee = max(amount * feeBps / 10_000, minWithdrawalFee)
+ *
+ * @returns fee in base token units, and the amount that reaches the recipient
+ */
+export function computeWithdrawalFee(amount, feeBps, minWithdrawalFee) {
+    const computed = (amount * BigInt(feeBps)) / 10000n;
+    const fee = computed > minWithdrawalFee ? computed : minWithdrawalFee;
+    return { fee, toRecipient: amount - fee };
+}
+/**
+ * Compute the relayer fee for a cross-pool swap.
+ * Mirrors the formula in the relayer-server:
+ *   relayerFee = max(estimatedOutput * swapFeeBps / 10_000, minSwapFee)
+ *   destAmount  = minAmountOut - relayerFee
+ *
+ * @param estimatedOutput  Jupiter quote output amount
+ * @param swapFeeBps       From the destination pool's PrivacyConfigAccount
+ * @param minSwapFee       From the destination pool's PrivacyConfigAccount
+ * @param minAmountOut     User-agreed minimum swap output (after slippage)
+ * @returns relayerFee and the amount committed into the destination UTXO
+ */
+export function computeSwapFee(estimatedOutput, swapFeeBps, minSwapFee, minAmountOut) {
+    const computed = (estimatedOutput * BigInt(swapFeeBps)) / 10000n;
+    const relayerFee = computed > minSwapFee ? computed : minSwapFee;
+    return { relayerFee, destAmount: minAmountOut - relayerFee };
+}

package/dist/esm/events.d.ts

@@ -0,0 +1,77 @@
+import { PublicKey } from "@solana/web3.js";
+import { Program, Idl } from "@coral-xyz/anchor";
+import { MerkleTree } from "./merkle.js";
+/**
+ * On-chain CommitmentEvent emitted by `transact` and `transact_swap`.
+ * Mirrors the IDL CommitmentEvent struct.
+ */
+export type CommitmentEvent = {
+    commitment: Uint8Array;
+    leafIndex: number;
+    newRoot: Uint8Array;
+    timestamp: number;
+    mintAddress: PublicKey;
+    treeId: number;
+    txSignature: string;
+    slot: number;
+};
+/**
+ * On-chain NullifierSpent event emitted when a UTXO is consumed.
+ * Mirrors the IDL NullifierSpent struct.
+ */
+export type NullifierSpentEvent = {
+    nullifier: Uint8Array;
+    timestamp: number;
+    mintAddress: PublicKey;
+    treeId: number;
+    txSignature: string;
+    slot: number;
+};
+/**
+ * Fetch and parse CommitmentEvents for a program, optionally filtered by mint.
+ *
+ * @param program     - Anchor program instance
+ * @param mintAddress - Filter to a specific pool; omit to get all pools
+ * @param before      - Start paging before this signature (exclusive)
+ * @param until       - Stop paging at this signature (exclusive)
+ * @param limit       - Max signatures to fetch per page (default 1000)
+ */
+export declare function scanCommitmentEvents<T extends Idl>(params: {
+    program: Program<T>;
+    mintAddress?: PublicKey;
+    before?: string;
+    until?: string;
+    limit?: number;
+}): Promise<CommitmentEvent[]>;
+/**
+ * Fetch and parse NullifierSpent events for a program, optionally filtered by mint.
+ */
+export declare function scanNullifierEvents<T extends Idl>(params: {
+    program: Program<T>;
+    mintAddress?: PublicKey;
+    before?: string;
+    until?: string;
+    limit?: number;
+}): Promise<NullifierSpentEvent[]>;
+/**
+ * Rebuild a local MerkleTree from on-chain CommitmentEvents.
+ * Use this to get a valid inclusion proof for spending any UTXO.
+ *
+ * CommitmentEvents are sorted by (treeId, leafIndex) so the local tree
+ * matches the on-chain state exactly.
+ *
+ * @param program     - Anchor program instance
+ * @param mintAddress - Pool to reconstruct
+ * @param treeId      - Which tree to reconstruct (default 0)
+ * @param depth       - Merkle tree depth (default 22, must match on-chain)
+ */
+export declare function buildTreeFromEvents<T extends Idl>(params: {
+    program: Program<T>;
+    mintAddress: PublicKey;
+    treeId?: number;
+    depth?: number;
+}): Promise<{
+    tree: MerkleTree;
+    events: CommitmentEvent[];
+    latestSignature?: string;
+}>;

package/dist/esm/events.js

@@ -0,0 +1,129 @@
+import * as anchor from "@coral-xyz/anchor";
+import { MerkleTree } from "./merkle.js";
+// -----------------------------------------------------------------------------
+// Event Scanning
+// -----------------------------------------------------------------------------
+/**
+ * Fetch and parse CommitmentEvents for a program, optionally filtered by mint.
+ *
+ * @param program     - Anchor program instance
+ * @param mintAddress - Filter to a specific pool; omit to get all pools
+ * @param before      - Start paging before this signature (exclusive)
+ * @param until       - Stop paging at this signature (exclusive)
+ * @param limit       - Max signatures to fetch per page (default 1000)
+ */
+export async function scanCommitmentEvents(params) {
+    const { program, mintAddress, before, until, limit = 1000 } = params;
+    const out = [];
+    const eventParser = new anchor.EventParser(program.programId, new anchor.BorshCoder(program.idl));
+    const sigs = await program.provider.connection.getSignaturesForAddress(program.programId, { before, until, limit });
+    for (const sigInfo of sigs) {
+        if (sigInfo.err)
+            continue;
+        const tx = await program.provider.connection.getTransaction(sigInfo.signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
+        if (!tx)
+            continue;
+        const events = Array.from(eventParser.parseLogs(tx.meta?.logMessages ?? []));
+        for (const ev of events) {
+            if (ev.name !== "commitmentEvent")
+                continue;
+            const d = ev.data;
+            const evMint = d.mintAddress;
+            if (mintAddress && !evMint.equals(mintAddress))
+                continue;
+            out.push({
+                commitment: new Uint8Array(d.commitment),
+                leafIndex: Number(d.leafIndex),
+                newRoot: new Uint8Array(d.newRoot),
+                timestamp: Number(d.timestamp),
+                mintAddress: evMint,
+                treeId: Number(d.treeId),
+                txSignature: sigInfo.signature,
+                slot: sigInfo.slot,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Fetch and parse NullifierSpent events for a program, optionally filtered by mint.
+ */
+export async function scanNullifierEvents(params) {
+    const { program, mintAddress, before, until, limit = 1000 } = params;
+    const out = [];
+    const eventParser = new anchor.EventParser(program.programId, new anchor.BorshCoder(program.idl));
+    const sigs = await program.provider.connection.getSignaturesForAddress(program.programId, { before, until, limit });
+    for (const sigInfo of sigs) {
+        if (sigInfo.err)
+            continue;
+        const tx = await program.provider.connection.getTransaction(sigInfo.signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
+        if (!tx)
+            continue;
+        const events = Array.from(eventParser.parseLogs(tx.meta?.logMessages ?? []));
+        for (const ev of events) {
+            if (ev.name !== "nullifierSpent")
+                continue;
+            const d = ev.data;
+            const evMint = d.mintAddress;
+            if (mintAddress && !evMint.equals(mintAddress))
+                continue;
+            out.push({
+                nullifier: new Uint8Array(d.nullifier),
+                timestamp: Number(d.timestamp),
+                mintAddress: evMint,
+                treeId: Number(d.treeId),
+                txSignature: sigInfo.signature,
+                slot: sigInfo.slot,
+            });
+        }
+    }
+    return out;
+}
+// -----------------------------------------------------------------------------
+// Tree Reconstruction
+// -----------------------------------------------------------------------------
+/**
+ * Rebuild a local MerkleTree from on-chain CommitmentEvents.
+ * Use this to get a valid inclusion proof for spending any UTXO.
+ *
+ * CommitmentEvents are sorted by (treeId, leafIndex) so the local tree
+ * matches the on-chain state exactly.
+ *
+ * @param program     - Anchor program instance
+ * @param mintAddress - Pool to reconstruct
+ * @param treeId      - Which tree to reconstruct (default 0)
+ * @param depth       - Merkle tree depth (default 22, must match on-chain)
+ */
+export async function buildTreeFromEvents(params) {
+    const { program, mintAddress, treeId = 0, depth = 22 } = params;
+    // Fetch all commitment events for this pool (page until no more results).
+    // Oldest-first so we insert leaves in the correct order.
+    const allEvents = [];
+    let before;
+    while (true) {
+        const page = await scanCommitmentEvents({
+            program,
+            mintAddress,
+            before,
+            limit: 1000,
+        });
+        if (page.length === 0)
+            break;
+        allEvents.push(...page);
+        before = page[page.length - 1].txSignature;
+        if (page.length < 1000)
+            break;
+    }
+    // Keep only events for this treeId, sort by leafIndex ascending
+    const treeEvents = allEvents
+        .filter((e) => e.treeId === treeId)
+        .sort((a, b) => a.leafIndex - b.leafIndex);
+    const tree = new MerkleTree(depth);
+    for (const ev of treeEvents) {
+        tree.insert(ev.commitment);
+    }
+    const latestSignature = treeEvents.length > 0
+        ? treeEvents[treeEvents.length - 1].txSignature
+        : undefined;
+    return { tree, events: treeEvents, latestSignature };
+}

package/dist/esm/idl/privacy_pool.d.ts

@@ -0,0 +1,5 @@
+import type { Idl } from "@coral-xyz/anchor";
+declare const IDL_JSON: Idl & {
+    address: string;
+};
+export default IDL_JSON;