@osmura/merkletreejs 0.6.0

package/dist/UnifiedBinaryTree.d.ts

@@ -0,0 +1,454 @@
+/// <reference types="node" />
+/**
+ * Type aliases for fixed-length byte sequences used throughout the codebase.
+ * These help maintain type safety and clarify the expected byte lengths.
+ */
+export declare type Address = Buffer;
+export declare type Address32 = Buffer;
+export declare type Bytes32 = Buffer;
+/**
+ * Constants used for key derivation and tree organization.
+ * These define the structure and layout of the binary tree.
+ */
+export declare const BASIC_DATA_LEAF_KEY = 0;
+export declare const CODE_HASH_LEAF_KEY = 1;
+export declare const HEADER_STORAGE_OFFSET = 64;
+export declare const CODE_OFFSET = 128;
+export declare const STEM_SUBTREE_WIDTH = 256;
+export declare const MAIN_STORAGE_OFFSET = 256;
+export declare const pushOffset = 95;
+export declare const push1: number;
+export declare const push32: number;
+/** Function type for hash operations */
+export declare type HashFunction = (data: any) => any;
+/**
+ * Converts a 20-byte Ethereum address to a 32-byte address by left-padding with zeros.
+ *
+ * @example
+ * ```typescript
+ * const addr20 = Buffer.from('1234567890123456789012345678901234567890', 'hex')
+ * const addr32 = oldStyleAddressToAddress32(addr20)
+ * // addr32 = 0x000000000000123456789012345678901234567890 (32 bytes)
+ * ```
+ */
+export declare function oldStyleAddressToAddress32(address: Address): Address32;
+/**
+ * Applies a hash function to input data with proper buffering.
+ *
+ * @example
+ * ```typescript
+ * const input = Buffer.from('Hello World')
+ * const hashFn = (data) => blake3.hash(data)
+ * const hash = treeHash(input, hashFn)
+ * // hash = 32-byte BLAKE3 hash of 'Hello World'
+ * ```
+ */
+export declare function treeHash(input: Buffer, hashFn: HashFunction): Bytes32;
+/**
+ * Derives a tree key from an address and indices using a hash function.
+ * Used to generate unique keys for different parts of the tree structure.
+ * The resulting key is composed of a 31-byte stem (derived from address and treeIndex)
+ * and a 1-byte subIndex.
+ *
+ * @param address - A 32-byte address to derive the key from
+ * @param treeIndex - Primary index used to derive different trees for the same address
+ * @param subIndex - Secondary index used to derive different keys within the same tree
+ * @param hashFn - Hash function to use for key derivation
+ * @returns A 32-byte key that uniquely identifies this storage slot
+ * @throws Error if address is not 32 bytes
+ *
+ * @example
+ * ```typescript
+ * const addr32 = oldStyleAddressToAddress32(address)
+ * const treeKey = getTreeKey(addr32, 0, 1, blake3.hash)
+ * // Returns a unique key for this address's tree at index 0, subIndex 1
+ * ```
+ */
+export declare function getTreeKey(address: Address32, treeIndex: number, subIndex: number, hashFn: HashFunction): Address32;
+/**
+ * Derives a key for storing an account's basic data (nonce, balance, etc.).
+ *
+ * @example
+ * ```typescript
+ * const addr32 = oldStyleAddressToAddress32(address)
+ * const basicDataKey = getTreeKeyForBasicData(addr32, hashFn)
+ * tree.insert(basicDataKey, accountData)
+ * ```
+ */
+export declare function getTreeKeyForBasicData(address: Address32, hashFn: HashFunction): Address32;
+/**
+ * Derives a key for storing a contract's code hash.
+ *
+ * @example
+ * ```typescript
+ * const addr32 = oldStyleAddressToAddress32(contractAddress)
+ * const codeHashKey = getTreeKeyForCodeHash(addr32, hashFn)
+ * tree.insert(codeHashKey, codeHash)
+ * ```
+ */
+export declare function getTreeKeyForCodeHash(address: Address32, hashFn: HashFunction): Address32;
+/**
+ * Derives a tree key for a storage slot in a contract's storage.
+ * Handles two types of storage:
+ * 1. Header storage (slots 0-63): Used for contract metadata and special storage
+ * 2. Main storage (slots 256+): Used for regular contract storage
+ *
+ * The storage layout is:
+ * - Header storage: slots [0, 63] mapped to positions [64, 127]
+ * - Main storage: slots [256+] mapped to positions [384+]
+ * This creates gaps in the tree to allow for future extensions.
+ *
+ * @param address - The 32-byte contract address
+ * @param storageKey - The storage slot number to access
+ * @param hashFn - Hash function to use for key derivation
+ * @returns A 32-byte key that uniquely identifies this storage slot
+ *
+ * @example
+ * ```typescript
+ * const addr32 = oldStyleAddressToAddress32(contractAddress)
+ * // Get key for a header storage slot (0-63)
+ * const headerKey = getTreeKeyForStorageSlot(addr32, 5, blake3.hash)
+ * // Get key for a main storage slot (256+)
+ * const mainKey = getTreeKeyForStorageSlot(addr32, 300, blake3.hash)
+ * ```
+ */
+export declare function getTreeKeyForStorageSlot(address: Address32, storageKey: number, hashFn: HashFunction): Address32;
+/**
+ * Derives a key for storing a chunk of contract code.
+ * Used when contract code is split into 32-byte chunks.
+ *
+ * @example
+ * ```typescript
+ * const addr32 = oldStyleAddressToAddress32(contractAddress)
+ * const chunks = chunkifyCode(contractCode)
+ * chunks.forEach((chunk, i) => {
+ *   const key = getTreeKeyForCodeChunk(addr32, i, hashFn)
+ *   tree.insert(key, chunk)
+ * })
+ * ```
+ */
+export declare function getTreeKeyForCodeChunk(address: Address32, chunkId: number, hashFn: HashFunction): Address32;
+/**
+ * Splits EVM bytecode into 31-byte chunks with metadata.
+ * Each chunk is prefixed with a byte indicating the number of bytes
+ * that are part of PUSH data in the next chunk.
+ *
+ * @example
+ * ```typescript
+ * const code = Buffer.from('6001600201', 'hex') // PUSH1 01 PUSH1 02 ADD
+ * const chunks = chunkifyCode(code)
+ * // chunks[0] = [0x01, 0x60, 0x01, 0x60, 0x02, 0x01, 0x00...] (32 bytes)
+ * ```
+ */
+export declare function chunkifyCode(code: Buffer): Bytes32[];
+/**
+ * Node types in the binary tree.
+ * - StemNode: Leaf node containing up to 256 values
+ * - InternalNode: Internal node with left and right children
+ */
+export declare type BinaryTreeNode = StemNode | InternalNode;
+/**
+ * Leaf node in the binary tree that stores actual values.
+ * Contains a 31-byte stem and an array of 256 possible values.
+ *
+ * @example
+ * ```typescript
+ * const stem = Buffer.alloc(31, 0)
+ * const node = new StemNode(stem)
+ * node.setValue(0, Buffer.alloc(32).fill(1)) // Set value at index 0
+ * ```
+ */
+export declare class StemNode {
+    stem: Buffer;
+    values: Array<Buffer | null>;
+    nodeType: 'stem';
+    /**
+     * Creates a new StemNode with the given stem.
+     *
+     * @param stem - The 31-byte stem for this node.
+     */
+    constructor(stem: Buffer);
+    /**
+     * Sets the value at the given index.
+     *
+     * @param index - The index to set the value at.
+     * @param value - The 32-byte value to set.
+     */
+    setValue(index: number, value: Buffer): void;
+}
+/**
+ * Internal node in the binary tree with left and right children.
+ * Used to create the tree structure based on key bit patterns.
+ *
+ * @example
+ * ```typescript
+ * const node = new InternalNode()
+ * node.left = new StemNode(Buffer.alloc(31, 0))
+ * node.right = new StemNode(Buffer.alloc(31, 1))
+ * ```
+ */
+export declare class InternalNode {
+    left: BinaryTreeNode | null;
+    right: BinaryTreeNode | null;
+    nodeType: 'internal';
+}
+/**
+ * Main binary tree implementation that stores key-value pairs.
+ * Uses a configurable hash function and supports various operations.
+ *
+ * @example
+ * ```typescript
+ * const tree = new BinaryTree(blake3.hash)
+ * tree.insert(key, value)
+ * const root = tree.merkelize()
+ * const serialized = tree.serialize()
+ * ```
+ */
+export declare class UnifiedBinaryTree {
+    root: BinaryTreeNode | null;
+    hashFn: HashFunction;
+    /**
+     * Creates a new BinaryTree instance with the given hash function.
+     *
+     * @param hashFn - The hash function to use for key derivation.
+     */
+    constructor(hashFn: HashFunction);
+    /**
+     * Inserts a key-value pair into the binary tree.
+     * The key is split into two parts:
+     * - stem (first 31 bytes): Determines the path in the tree
+     * - subIndex (last byte): Determines the position within a leaf node
+     *
+     * If this is the first insertion, creates a new leaf node.
+     * Otherwise, recursively traverses or builds the tree structure.
+     *
+     * @param key - A 32-byte key that determines where to store the value
+     * @param value - A 32-byte value to store
+     * @throws Error if key or value is not exactly 32 bytes
+     *
+     * @example
+     * ```typescript
+     * const tree = new BinaryTree(hashFn)
+     * const key = getTreeKey(address, 0, 1, hashFn)
+     * const value = Buffer.alloc(32).fill(1)
+     * tree.insert(key, value)
+     * ```
+     */
+    insert(key: Buffer, value: Buffer): void;
+    /**
+     * Recursively inserts a key-value pair into the tree.
+     * This method handles three cases:
+     * 1. Empty node: Creates a new leaf node
+     * 2. Stem node: Either updates value or splits into internal node
+     * 3. Internal node: Recursively traverses left or right based on stem bits
+     *
+     * @param node - Current node in traversal (null if empty)
+     * @param stem - The 31-byte path component of the key
+     * @param subIndex - The leaf position component of the key
+     * @param value - The 32-byte value to store
+     * @param depth - Current depth in the tree (max 247 to prevent hash collisions)
+     * @returns The new or updated node
+     * @throws Error if tree depth exceeds 247 levels
+     */
+    private insertRecursive;
+    /**
+     * Converts a byte array to an array of individual bits.
+     * Each byte is converted to 8 bits, maintaining the most-significant-bit first order.
+     * Used for making path decisions in the binary tree based on stem bytes.
+     *
+     * @param data - Buffer containing bytes to convert
+     * @returns Array of bits (0s and 1s) in MSB-first order
+     *
+     * @example
+     * ```typescript
+     * const bytes = Buffer.from([0xA5]) // Binary: 10100101
+     * const bits = bytesToBits(bytes)
+     * // bits = [1,0,1,0,0,1,0,1]
+     * //         ^ MSB        LSB ^
+     * ```
+     *
+     * Process for each byte:
+     * 1. Right shift by (7-i) positions to get desired bit to LSB
+     * 2. AND with 1 to isolate that bit
+     * 3. Push result (0 or 1) to output array
+     */
+    private bytesToBits;
+    /**
+     * Converts an array of bits back into a Buffer of bytes.
+     * This is the inverse operation of bytesToBits.
+     * Processes bits in groups of 8, maintaining MSB-first order.
+     *
+     * @param bits - Array of 0s and 1s to convert to bytes
+     * @returns Buffer containing the reconstructed bytes
+     * @throws Error if the number of bits is not divisible by 8
+     *
+     * @example
+     * ```typescript
+     * const bits = [1,0,1,0,0,1,0,1] // Represents binary 10100101
+     * const bytes = bitsToBytes(bits)
+     * // bytes = Buffer.from([0xA5])
+     * ```
+     *
+     * Process for each byte:
+     * 1. Take 8 bits at a time
+     * 2. For each bit:
+     *    - Shift it left to its correct position (7-j positions)
+     *    - OR it with the accumulating byte value
+     * 3. Add completed byte to array
+     */
+    private bitsToBytes;
+    /**
+     * Applies the hash function to the given data with special handling for null values.
+     * Used primarily for Merkle tree calculations and node hashing.
+     *
+     * Special cases:
+     * - null input -> returns 32-byte zero buffer
+     * - 64-byte zero buffer -> returns 32-byte zero buffer
+     * This handling ensures consistent treatment of empty/uninitialized nodes.
+     *
+     * @param data - Buffer to hash, must be either 32 or 64 bytes, or null
+     * @returns A 32-byte hash of the data, or zero32 for empty cases
+     * @throws Error if data length is not 32 or 64 bytes
+     *
+     * @example
+     * ```typescript
+     * // Regular hashing
+     * const hash1 = hashData(nodeBuffer) // Returns hash of data
+     *
+     * // Empty cases - all return 32 zeros
+     * const hash2 = hashData(null)
+     * const hash3 = hashData(Buffer.alloc(64, 0))
+     * ```
+     */
+    private hashData;
+    /**
+     * Computes the Merkle root of the entire tree.
+     * The Merkle root is a single 32-byte hash that uniquely represents the entire tree state.
+     *
+     * The computation follows these rules:
+     * 1. For Internal nodes: hash(leftChild || rightChild)
+     * 2. For Stem nodes: hash(stem || 0x00 || merkleOfValues)
+     * 3. For empty nodes: return 32 bytes of zeros
+     *
+     * @returns A 32-byte Buffer containing the Merkle root
+     *
+     * @example
+     * ```typescript
+     * const tree = new BinaryTree(hashFn)
+     * tree.insert(key1, value1)
+     * tree.insert(key2, value2)
+     * const root = tree.merkelize()
+     * // root now contains a 32-byte hash representing the entire tree
+     * ```
+     */
+    merkelize(): Buffer;
+    /**
+     * Incrementally updates the value for an existing key.
+     * For our implementation, update is the same as insert.
+     *
+     * @param key - A 32-byte key.
+     * @param value - A 32-byte value.
+     */
+    update(key: Buffer, value: Buffer): void;
+    /**
+     * Performs a batch insertion of key-value pairs.
+     *
+     * @param entries - An array of objects with 'key' and 'value' properties.
+     */
+    insertBatch(entries: {
+        key: Buffer;
+        value: Buffer;
+    }[]): void;
+    /**
+     * Serializes the entire tree structure into a JSON Buffer.
+     * Converts the tree into a format that can be stored or transmitted,
+     * preserving the complete structure and all values.
+     *
+     * The serialized format for each node type is:
+     * 1. Stem Node:
+     *    ```json
+     *    {
+     *      "nodeType": "stem",
+     *      "stem": "hex string of 31 bytes",
+     *      "values": ["hex string or null", ...] // 256 entries
+     *    }
+     *    ```
+     * 2. Internal Node:
+     *    ```json
+     *    {
+     *      "nodeType": "internal",
+     *      "left": <node or null>,
+     *      "right": <node or null>
+     *    }
+     *    ```
+     *
+     * @returns Buffer containing the JSON string representation of the tree
+     *
+     * @example
+     * ```typescript
+     * const tree = new BinaryTree(hashFn)
+     * tree.insert(key, value)
+     * const serialized = tree.serialize()
+     * // Save to file or transmit
+     * const newTree = UnifiedBinaryTree.deserialize(serialized, hashFn)
+     * ```
+     */
+    serialize(): Buffer;
+    /**
+     * Reconstructs a BinaryTree from its serialized form.
+     * This is the inverse operation of serialize().
+     *
+     * Expected input format:
+     * ```json
+     * {
+     *   "root": {
+     *     "nodeType": "internal"|"stem",
+     *     // For stem nodes:
+     *     "stem": "hex string",
+     *     "values": ["hex string"|null, ...],
+     *     // For internal nodes:
+     *     "left": <node|null>,
+     *     "right": <node|null>
+     *   }
+     * }
+     * ```
+     *
+     * @param data - Buffer containing the JSON serialized tree
+     * @param hashFn - Hash function to use for the reconstructed tree
+     * @returns A new BinaryTree instance with the deserialized structure
+     * @throws Error if JSON parsing fails or format is invalid
+     *
+     * @example
+     * ```typescript
+     * const serialized = existingTree.serialize()
+     * const newTree = UnifiedBinaryTree.deserialize(serialized, hashFn)
+     * // newTree is now identical to existingTree
+     * ```
+     */
+    static deserialize(data: Buffer, hashFn: HashFunction): UnifiedBinaryTree;
+    /**
+     * Splits a leaf node when inserting a new key with a different stem.
+     * This method handles two cases:
+     * 1. Matching bits at current depth: Continue splitting recursively
+     * 2. Different bits at current depth: Create new internal node and arrange leaves
+     *
+     * The process ensures that keys with different stems are properly distributed
+     * in the tree based on their binary representation.
+     *
+     * @param leaf - The existing leaf node to split
+     * @param stemBits - Binary representation of the new stem
+     * @param existingStemBits - Binary representation of the existing stem
+     * @param subIndex - Position within leaf node for new value
+     * @param value - Value to store at the new position
+     * @param depth - Current depth in the tree
+     * @returns A new internal node containing both the existing and new data
+     *
+     * Example:
+     * If stems differ at bit 3:
+     * - New stem:      [1,0,1,0,...]
+     * - Existing stem: [1,0,1,1,...]
+     *                        ^ split here
+     * Creates an internal node with the leaf nodes arranged based on bit 3
+     */
+    private splitLeaf;
+}