@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/commitment-tree.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Commitment Tree Client
+ *
+ * Implements an incremental Merkle tree matching the on-chain logic exactly.
+ * Uses frontier array + pre-computed zero hashes (Tornado Cash/Semaphore pattern).
+ *
+ * The tree supports up to 2^20 (~1M) leaf commitments.
+ * Standard Merkle path proofs compatible with ZK circuits.
+ */
+import { initPoseidon } from "./poseidon";
+export { initPoseidon };
+export declare const TREE_DEPTH = 16;
+export declare const ROOT_HISTORY_SIZE = 100;
+export declare const MAX_LEAVES: bigint;
+export declare const COMMITMENT_TREE_DISCRIMINATOR = 5;
+/**
+ * Pre-computed zero hashes for each level of the tree
+ * ZERO[0] = 0 (empty leaf)
+ * ZERO[i] = Poseidon(ZERO[i-1], ZERO[i-1])
+ *
+ * These values MUST match the contract's ZERO_HASHES exactly!
+ * Using Circom-compatible Poseidon (matches Solana's sol_poseidon).
+ */
+export declare const ZERO_HASHES: bigint[];
+/**
+ * On-chain commitment tree state
+ */
+export interface CommitmentTreeState {
+    discriminator: number;
+    bump: number;
+    currentRoot: Uint8Array;
+    nextIndex: bigint;
+    frontier: Uint8Array[];
+    rootHistory: Uint8Array[];
+    rootHistoryIndex: number;
+}
+/**
+ * Parse commitment tree account data
+ *
+ * On-chain layout:
+ * - discriminator: 1 byte
+ * - bump: 1 byte
+ * - padding: 6 bytes
+ * - current_root: 32 bytes
+ * - next_index: 8 bytes
+ * - frontier: 20 * 32 = 640 bytes
+ * - root_history: 100 * 32 = 3200 bytes
+ * - root_history_index: 4 bytes
+ * - reserved: 60 bytes
+ */
+export declare function parseCommitmentTreeData(data: Uint8Array): CommitmentTreeState;
+/**
+ * Check if a root is valid (current or in history)
+ */
+export declare function isValidRoot(state: CommitmentTreeState, root: Uint8Array): boolean;
+/**
+ * Local Commitment Tree Index (Incremental Merkle Tree)
+ *
+ * Uses the same algorithm as the on-chain contract:
+ * - Frontier array to track rightmost filled nodes at each level
+ * - Pre-computed zero hashes for empty subtrees
+ *
+ * This produces the same root as the on-chain tree.
+ */
+export declare class CommitmentTreeIndex {
+    private commitments;
+    private leaves;
+    private frontier;
+    private currentRoot;
+    private nextIndex;
+    constructor();
+    /**
+     * Add a commitment to the index
+     * Uses the same algorithm as on-chain insert_leaf()
+     */
+    addCommitment(commitment: bigint, amount: bigint): bigint;
+    /**
+     * Get merkle proof for a commitment
+     *
+     * Returns siblings and path indices for ZK circuit verification.
+     */
+    getMerkleProof(commitment: bigint): {
+        siblings: bigint[];
+        indices: number[];
+        leafIndex: bigint;
+        root: bigint;
+    } | null;
+    /**
+     * Compute merkle proof for a leaf at given index
+     * Optimized: only computes nodes needed for the proof path
+     */
+    private computeMerkleProof;
+    /**
+     * Get commitment info by hex string
+     */
+    getCommitment(commitmentHex: string): {
+        index: bigint;
+        amount: bigint;
+    } | null;
+    /**
+     * Get current merkle root
+     */
+    getRoot(): bigint;
+    /**
+     * Get root as bytes for comparison with on-chain
+     */
+    getRootBytes(): Uint8Array;
+    /**
+     * Get number of commitments
+     */
+    size(): number;
+    /**
+     * Get next leaf index
+     */
+    getNextIndex(): bigint;
+    /**
+     * Get tree status (for API compatibility)
+     */
+    getStatus(): {
+        root: string;
+        nextIndex: number;
+        size: number;
+    };
+    /**
+     * Get path (merkle proof) for a commitment by hex string
+     * Convenience wrapper around getMerkleProof for API compatibility
+     */
+    getPath(commitmentHex: string): {
+        siblings: string[];
+        indices: number[];
+        leafIndex: string;
+        root: string;
+    } | null;
+    /**
+     * Export index for persistence
+     */
+    export(): {
+        commitments: [string, {
+            index: string;
+            amount: string;
+        }][];
+    };
+    /**
+     * Import index from persistence
+     */
+    import(data: {
+        commitments: [string, {
+            index: string;
+            amount: string;
+        }][];
+    }): void;
+    /**
+     * Import from on-chain state
+     * Reconstructs tree state from on-chain frontier and root
+     */
+    importFromOnChainState(state: CommitmentTreeState): void;
+}
+/**
+ * Fetch commitment tree state from Solana
+ */
+export declare function fetchCommitmentTree(connection: {
+    getAccountInfo: (pubkey: unknown) => Promise<{
+        data: Uint8Array;
+    } | null>;
+}, commitmentTreePDA: unknown): Promise<CommitmentTreeState | null>;
+/**
+ * Get or create the global commitment index
+ */
+export declare function getCommitmentIndex(): CommitmentTreeIndex;
+/**
+ * Save the global commitment index to localStorage
+ */
+export declare function saveCommitmentIndex(): void;
+/**
+ * RPC client interface for on-chain queries
+ * Compatible with @solana/web3.js Connection and Helius enhanced RPC
+ */
+export interface RpcClient {
+    getProgramAccounts(programId: string, config?: {
+        filters?: Array<{
+            memcmp: {
+                offset: number;
+                bytes: string;
+            };
+        } | {
+            dataSize: number;
+        }>;
+        encoding?: string;
+    }): Promise<Array<{
+        pubkey: string;
+        account: {
+            data: Uint8Array | string;
+        };
+    }>>;
+}
+/**
+ * On-chain merkle proof format
+ */
+export interface OnChainMerkleProof {
+    siblings: bigint[];
+    indices: number[];
+    leafIndex: number;
+    root: bigint;
+    commitment: bigint;
+}
+/**
+ * Build commitment tree from indexed commitment data.
+ *
+ * Stealth announcements are now emitted as events, not stored as PDAs.
+ * This function accepts a commitments map (leafIndex → commitment bigint)
+ * from the event indexer and builds the local Merkle tree.
+ *
+ * @param _rpc - RPC client (unused, kept for API compatibility)
+ * @param _programId - UTXOpia program ID (unused)
+ * @param options - commitments map from indexer
+ */
+export declare function buildCommitmentTreeFromChain(_rpc: RpcClient, _programId: string, options?: {
+    maxLeafIndex?: number;
+    commitments?: Map<number, bigint>;
+}): Promise<CommitmentTreeIndex>;
+/**
+ * Get leaf index for a commitment.
+ *
+ * Commitments are emitted as sol_log_data events (not stored in PDAs).
+ * Use scanUnifiedNotes() to get leafIndex for your notes, or query the indexer API.
+ * This function builds the full tree from provided commitments to find the index.
+ *
+ * @param rpc - RPC client
+ * @param programId - UTXOpia program ID
+ * @param commitment - Commitment to find
+ * @returns Leaf index or -1 if not found
+ */
+export declare function fetchLeafIndexForCommitment(rpc: RpcClient, programId: string, commitment: bigint): Promise<number>;
+/**
+ * Fetch merkle proof for a commitment from on-chain data
+ *
+ * Builds tree from chain and computes merkle proof for the given commitment.
+ * For better performance with multiple proofs, use buildCommitmentTreeFromChain
+ * once and call getMerkleProof on the resulting tree.
+ *
+ * @param rpc - RPC client
+ * @param programId - UTXOpia program ID
+ * @param commitment - Commitment to get proof for
+ * @returns Merkle proof or null if commitment not found
+ *
+ * @example
+ * ```typescript
+ * const proof = await fetchMerkleProofForCommitment(connection, programId, myCommitment);
+ * if (proof) {
+ *   // Use proof for ZK circuit
+ *   const claimInputs = {
+ *     merkleRoot: proof.root,
+ *     merkleProof: { siblings: proof.siblings, indices: proof.indices },
+ *     leafIndex: BigInt(proof.leafIndex),
+ *     // ...
+ *   };
+ * }
+ * ```
+ */
+export declare function fetchMerkleProofForCommitment(rpc: RpcClient, programId: string, commitment: bigint): Promise<OnChainMerkleProof | null>;
+/**
+ * Fetch merkle proof using cached tree (more efficient for multiple lookups)
+ *
+ * @param tree - Pre-built commitment tree from buildCommitmentTreeFromChain
+ * @param commitment - Commitment to get proof for
+ * @returns Merkle proof or null if not found
+ */
+export declare function getMerkleProofFromTree(tree: CommitmentTreeIndex, commitment: bigint): OnChainMerkleProof | null;