@ninebix/nmt-system 1.0.0

package/dist/src/core/merkle-engine.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Merkle Engine - Tree construction and verification
+ *
+ * Extended features:
+ * - Tree diff computation
+ * - Batch proofs for multiple leaves
+ * - Range proofs for consecutive leaves
+ * - Versioned trees
+ *
+ * @module core/merkle-engine
+ */
+import type { MerkleTree, MerkleProof, SHA3Hash, MerkleRoot } from '../types/index.js';
+/**
+ * Difference between two Merkle trees
+ */
+export interface TreeDiff {
+    /** Leaves added in newTree */
+    added: SHA3Hash[];
+    /** Leaves removed from oldTree */
+    removed: SHA3Hash[];
+    /** Leaves modified (same index, different hash) */
+    modified: {
+        index: number;
+        oldHash: SHA3Hash;
+        newHash: SHA3Hash;
+    }[];
+    /** Old root */
+    oldRoot: MerkleRoot;
+    /** New root */
+    newRoot: MerkleRoot;
+}
+/**
+ * Batch proof for multiple leaves
+ */
+export interface BatchMerkleProof {
+    /** Leaves being proven */
+    leaves: {
+        index: number;
+        hash: SHA3Hash;
+    }[];
+    /** Deduplicated sibling nodes: "level:index" -> hash */
+    siblings: Record<string, SHA3Hash>;
+    /** Root hash */
+    root: MerkleRoot;
+}
+/**
+ * Range proof for consecutive leaves
+ */
+export interface RangeProof {
+    /** Start index (inclusive) */
+    startIndex: number;
+    /** End index (exclusive) */
+    endIndex: number;
+    /** Leaves in range */
+    leaves: SHA3Hash[];
+    /** Left boundary proof */
+    leftProof: MerkleProof | null;
+    /** Right boundary proof */
+    rightProof: MerkleProof | null;
+    /** Root hash */
+    root: MerkleRoot;
+}
+/**
+ * Versioned Merkle tree with parent tracking
+ */
+export interface VersionedMerkleTree extends MerkleTree {
+    /** Version number */
+    version: number;
+    /** Parent root (null for initial version) */
+    parentRoot: MerkleRoot | null;
+    /** Version timestamp */
+    timestamp: string;
+    /** Changes from parent (if any) */
+    diff?: TreeDiff;
+}
+/**
+ * MerkleEngine class for tree operations
+ */
+export declare class MerkleEngine {
+    /**
+     * Build a Merkle tree from leaf hashes
+     * @param leaves - Array of leaf hashes
+     * @returns Complete Merkle tree structure
+     */
+    buildTree(leaves: SHA3Hash[]): MerkleTree;
+    /**
+     * Build Merkle tree from raw data buffers
+     * @param data - Array of data buffers
+     * @returns Merkle tree with hashed leaves
+     */
+    buildTreeFromData(data: Buffer[]): MerkleTree;
+    /**
+     * Generate inclusion proof for a leaf
+     * @param tree - Merkle tree
+     * @param leafIndex - Index of leaf to prove
+     * @returns Merkle proof
+     */
+    generateProof(tree: MerkleTree, leafIndex: number): MerkleProof;
+    /**
+     * Verify a Merkle proof
+     * @param proof - Proof to verify
+     * @returns true if proof is valid
+     */
+    verifyProof(proof: MerkleProof): boolean;
+    /**
+     * Verify proof with explicit root and leaf
+     * @param proof - Proof structure
+     * @param root - Expected root hash
+     * @param leaf - Expected leaf hash
+     * @returns true if valid
+     */
+    verifyProofWithValues(proof: MerkleProof, root: MerkleRoot, leaf: SHA3Hash): boolean;
+    /**
+     * Compute the root hash directly from leaves
+     * @param leaves - Leaf hashes
+     * @returns Root hash
+     */
+    computeRoot(leaves: SHA3Hash[]): MerkleRoot;
+    /**
+     * Update a leaf in the tree (returns new tree)
+     * @param tree - Original tree
+     * @param index - Leaf index to update
+     * @param newLeaf - New leaf hash
+     * @returns Updated tree
+     */
+    updateLeaf(tree: MerkleTree, index: number, newLeaf: SHA3Hash): MerkleTree;
+    /**
+     * Add a new leaf to the tree
+     * @param tree - Original tree
+     * @param newLeaf - New leaf hash
+     * @returns Updated tree
+     */
+    addLeaf(tree: MerkleTree, newLeaf: SHA3Hash): MerkleTree;
+    /**
+     * Get the height of the tree
+     * @param tree - Merkle tree
+     * @returns Tree height (number of levels)
+     */
+    getHeight(tree: MerkleTree): number;
+    /**
+     * Get all nodes at a specific level
+     * @param tree - Merkle tree
+     * @param level - Level index (0 = leaves)
+     * @returns Array of hashes at that level
+     */
+    getLevel(tree: MerkleTree, level: number): SHA3Hash[];
+    /**
+     * Serialize tree to JSON-friendly format
+     */
+    serialize(tree: MerkleTree): object;
+    /**
+     * Deserialize tree from JSON
+     */
+    deserialize(data: {
+        root: MerkleRoot;
+        levels: SHA3Hash[][];
+        leafCount: number;
+        originalLeaves: SHA3Hash[];
+    }): MerkleTree;
+    /**
+     * Compute the difference between two Merkle trees
+     *
+     * @param oldTree - Original tree
+     * @param newTree - Updated tree
+     * @returns TreeDiff with added, removed, and modified leaves
+     *
+     * @example
+     * ```typescript
+     * const tree1 = engine.buildTree(['a', 'b', 'c']);
+     * const tree2 = engine.buildTree(['a', 'b', 'd']);
+     * const diff = engine.computeDiff(tree1, tree2);
+     * // diff.modified = [{ index: 2, oldHash: 'c', newHash: 'd' }]
+     * ```
+     */
+    computeDiff(oldTree: MerkleTree, newTree: MerkleTree): TreeDiff;
+    /**
+     * Check if two trees have the same content
+     */
+    treesEqual(tree1: MerkleTree, tree2: MerkleTree): boolean;
+    /**
+     * Generate a batch proof for multiple leaves at once
+     *
+     * More efficient than generating individual proofs as siblings are deduplicated.
+     *
+     * @param tree - Merkle tree
+     * @param indices - Array of leaf indices to prove
+     * @returns BatchMerkleProof with deduplicated siblings
+     *
+     * @example
+     * ```typescript
+     * const batchProof = engine.generateBatchProof(tree, [0, 2, 5]);
+     * const valid = engine.verifyBatchProof(batchProof);
+     * ```
+     */
+    generateBatchProof(tree: MerkleTree, indices: number[]): BatchMerkleProof;
+    /**
+     * Verify a batch proof
+     *
+     * @param proof - BatchMerkleProof to verify
+     * @returns true if all leaves are proven to be in the tree
+     */
+    verifyBatchProof(proof: BatchMerkleProof): boolean;
+    /**
+     * Generate a range proof for consecutive leaves
+     *
+     * Useful for proving a subset of the tree without full proofs for each leaf.
+     *
+     * @param tree - Merkle tree
+     * @param startIndex - Start index (inclusive)
+     * @param endIndex - End index (exclusive)
+     * @returns RangeProof
+     */
+    generateRangeProof(tree: MerkleTree, startIndex: number, endIndex: number): RangeProof;
+    /**
+     * Verify a range proof
+     *
+     * @param proof - RangeProof to verify
+     * @returns true if the range is valid
+     */
+    verifyRangeProof(proof: RangeProof): boolean;
+    /**
+     * Create a versioned tree from an existing tree
+     *
+     * @param tree - Source tree
+     * @param parentRoot - Parent version root (null for initial)
+     * @returns VersionedMerkleTree
+     */
+    createVersion(tree: MerkleTree, parentRoot?: MerkleRoot | null): VersionedMerkleTree;
+    /**
+     * Create a new version from changes
+     *
+     * @param currentVersion - Current versioned tree
+     * @param newTree - New tree state
+     * @returns New VersionedMerkleTree with diff
+     */
+    createNewVersion(currentVersion: VersionedMerkleTree, newTree: MerkleTree): VersionedMerkleTree;
+    /**
+     * Serialize a versioned tree
+     */
+    serializeVersioned(tree: VersionedMerkleTree): object;
+    /**
+     * Deserialize a versioned tree
+     */
+    deserializeVersioned(data: {
+        root: MerkleRoot;
+        levels: SHA3Hash[][];
+        leafCount: number;
+        originalLeaves: SHA3Hash[];
+        version: number;
+        parentRoot: MerkleRoot | null;
+        timestamp: string;
+        diff?: TreeDiff;
+    }): VersionedMerkleTree;
+    /**
+     * Check if number is power of 2
+     */
+    private isPowerOfTwo;
+}
+/**
+ * Create a MerkleEngine instance
+ */
+export declare function createMerkleEngine(): MerkleEngine;
+//# sourceMappingURL=merkle-engine.d.ts.map

package/dist/src/core/merkle-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle-engine.d.ts","sourceRoot":"","sources":["../../../src/core/merkle-engine.ts"],"names":[],"mappings":"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"}