merkle 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acfb1daee054131392665bdb186173e4d9facf8d8a25f0d082d3d18bdb3a9b51
-  data.tar.gz: cb94b561dc7dfbffd9a951a94c8a015710d388f7f49466808db0bdf583d1f5cb
+  metadata.gz: ce4faaabf24a85b734bd6cfe35081dfcc897bf418c5b391e68a84f8ec0aa9977
+  data.tar.gz: 944144e97463b2d0ad1ff7b2a882210548786035f52fa0090d505bbad7b9f88e
 SHA512:
-  metadata.gz: 3aae0a25fdfca015e89a4123bf7956ec3b163ae3dce0cebed93652d0eb90babd9651043fedcd12a6f346b08d15e558f2480fd9325d39294cdbcb5739594d1537
-  data.tar.gz: 1db01cd9b1de1bac9c1193d12e47dc324011dc3578f3b49620dc47bac7ed920da606227af0a954f5de0f0704775b7ebb90224da63a34757bd1ac2ed9b3cc86e9
+  metadata.gz: 49988d95199cf3e6a5e5944f69205d6b354ed4e5d811325c4e6ca8d4a868044b6c3dfc380491d1aa9c577ca7848770ea3c7e56d9212a1bb2a60cbc5c330a0060
+  data.tar.gz: 107fc3472cca81407b6fbc97a0981711f5538cdb2e657a032911d7866021fa37a4a30ac00ce5bcbebe2585849f700fc01c892c41670f619150d809c578fbb007

data/README.md

@@ -4,7 +4,7 @@ A Ruby library for Merkle tree construction and proof generation with support fo
 
 ## Features
 
-- **Multiple tree structures**: Binary Tree (Bitcoin-compatible) and Adaptive Tree implementations
+- **Multiple tree structures**: Binary Tree (Bitcoin-compatible), Adaptive Tree, and Custom Tree implementations
 - **Flexible configuration**: Support for different hash algorithms (SHA256, Double SHA256) and tagged hashing
 - **Proof generation and verification**: Generate and verify Merkle proofs for any leaf
 - **Sorted hashing support**: Optional lexicographical sorting for deterministic tree construction
@@ -98,6 +98,32 @@ proof = adaptive_tree.generate_proof(0)
 puts "Adaptive tree proof valid: #{proof.valid?}"
 ```
 
+### Custom Tree Example
+
+```ruby
+# CustomTree allows you to define your own tree structure using nested arrays
+# This gives you precise control over how leaves are grouped
+
+# Example 1: Basic usage with pre-hashed leaves
+leaf_a = config.tagged_hash('A')
+leaf_b = config.tagged_hash('B')
+leaf_c = config.tagged_hash('C')
+leaf_d = config.tagged_hash('D')
+
+# Define structure: [[A, [B, C]], D]
+nested_leaves = [[leaf_a, [leaf_b, leaf_c]], leaf_d]
+custom_tree = Merkle::CustomTree.new(config: config, leaves: nested_leaves)
+
+root = custom_tree.compute_root
+puts "Custom tree root: #{root}"
+
+# Valid structures:
+# - [A, B] → Simple binary node
+# - [[A, B], C] → Left subtree with right leaf
+# - [A] → Single child node
+# Invalid: [A, B, C] → Error (max 2 children per node)
+```
+
 ### Configuration Options
 
 ```ruby
@@ -107,10 +133,10 @@ bitcoin_config = Merkle::Config.new(hash_type: :double_sha256)
 # Configuration with tagged hashing (Taproot-style)
 taproot_config = Merkle::Config.taptree
 
-# Configuration with sorted hashing (no directions needed in proofs)
-sorted_config = Merkle::Config.new(
+# Configuration with non-sorted hashing (directions needed in proofs)
+non_sorted_config = Merkle::Config.new(
   hash_type: :sha256,
-  sort_hashes: true
+  sort_hashes: false
 )
 ```
 
@@ -120,6 +146,7 @@ sorted_config = Merkle::Config.new(
 
 - **BinaryTree**: Bitcoin-compatible merkle tree that duplicates odd nodes
 - **AdaptiveTree**: Unbalanced tree that promotes odd nodes to higher levels for optimized access patterns
+- **CustomTree**: User-defined tree structure using nested arrays for precise control over leaf grouping
 
 ### Proof System
 

data/lib/merkle/abstract_tree.rb

@@ -56,7 +56,7 @@ module Merkle
       raise ArgumentError, 'leaf_index out of range' if leaf_index < 0 || leaves.length <= leaf_index
 
       siblings, directions = siblings_with_directions(leaf_index)
-      siblings = siblings.map{|sibling| hex_string?(sibling) ? sibling : sibling.unpack1('H*')}
+      siblings = siblings.map{|sibling| bin_to_hex(sibling) }
       directions = [] if config.sort_hashes
       Proof.new(config: config, root: compute_root, leaf: leaves[leaf_index], siblings: siblings, directions: directions)
     end

data/lib/merkle/config.rb

@@ -14,7 +14,7 @@ module Merkle
     # @param [Boolean] sort_hashes Whether to sort internal nodes in lexicographical order and hash them.
     # If you enable this, Merkle::Proof's directions are not required.
     # @raise [ArgumentError]
-    def initialize(hash_type: :sha256, branch_tag: '', sort_hashes: false)
+    def initialize(hash_type: :sha256, branch_tag: '', sort_hashes: true)
       raise ArgumentError, "hash_type #{hash_type} does not supported." unless HASH_TYPES.include?(hash_type)
       raise ArgumentError, "internal_tag must be string." unless branch_tag.is_a?(String)
       raise ArgumentError, "sort_hashes must be boolean." unless sort_hashes.is_a?(TrueClass) || sort_hashes.is_a?(FalseClass)
@@ -26,13 +26,13 @@ module Merkle
     # Bitcoin configuration.
     # @return [Merkle::Config]
     def self.bitcoin
-      Config.new(hash_type: :double_sha256)
+      Config.new(hash_type: :double_sha256, sort_hashes: false)
     end
 
     # Taptree configuration.
     # @return [Merkle::Config]
     def self.taptree
-      Config.new(branch_tag: 'TapBranch', sort_hashes: true)
+      Config.new(branch_tag: 'TapBranch')
     end
 
     # Generate tagged hash.
@@ -41,19 +41,21 @@ module Merkle
     # @return [String] Tagged hash value.
     def tagged_hash(data, tag = branch_tag)
       raise ArgumentError, "data must be string." unless data.is_a?(String)
-      data = [data].pack('H*') if hex_string?(data)
+      raise ArgumentError, "tag must be a String." unless tag.is_a?(String)
+
+      data_bin = hex_to_bin(data).b
 
       unless tag.empty?
-        tag_hash = Digest::SHA256.digest(tag)
-        data = tag_hash + tag_hash + data
+        tag_bin = Digest::SHA256.digest(tag).b
+        data_bin = tag_bin + tag_bin + data_bin
       end
 
       case hash_type
       when :sha256
-        Digest::SHA256.digest(data)
+        Digest::SHA256.digest(data_bin)
       when :double_sha256
-        Digest::SHA256.digest(Digest::SHA256.digest(data))
+        Digest::SHA256.digest(Digest::SHA256.digest(data_bin))
       end
     end
   end
-end
+end

data/lib/merkle/custom_tree.rb

@@ -0,0 +1,209 @@
+module Merkle
+  # Custom Merkle tree implementation that allows specifying the tree structure
+  # Example: [leaf_A, [leaf_B, leaf_C], [leaf_D, leaf_E], leaf_F]
+  class CustomTree < AbstractTree
+
+    # Constructor
+    # @param [Merkle::Config] config Configuration for merkle tree.
+    # @param [Array] leaves A nested array representing the tree structure.
+    #                       Each element can be a leaf hash (hex string) or an array of child nodes.
+    def initialize(config:, leaves:)
+      super(config: config, leaves: leaves)
+      # Validate nested structure before calling super
+      validate_leaves!(extract_leaves(leaves))
+    end
+
+    # Create tree from elements with custom structure
+    # @param [Merkle::Config] config Configuration for merkle tree.
+    # @param [Array] elements A nested array of elements that will be hashed to become leaves.
+    # @param [String] leaf_tag An optional tag to use when computing the leaf hash.
+    def self.from_elements(config:, elements:, leaf_tag: '')
+      raise ArgumentError, 'config must be Merkle::Config' unless config.is_a?(Merkle::Config)
+      raise ArgumentError, 'elements must be Array' unless elements.is_a?(Array)
+      raise ArgumentError, 'leaf_tag must be string' unless leaf_tag.is_a?(String)
+      
+      # Convert elements to hashes while preserving structure
+      hashed_structure = convert_elements_to_hashes(elements, config, leaf_tag)
+      
+      self.new(config: config, leaves: hashed_structure)
+    end
+
+    # Compute merkle root using custom structure
+    # @return [String] merkle root
+    def compute_root
+      all_leaves = extract_leaves(@leaves)
+      raise Error, 'leaves is empty' if all_leaves.empty?
+      result = compute_node_hash(@leaves)
+      result.unpack1('H*')
+    end
+
+    # Convert nested elements to nested hashes
+    def self.convert_elements_to_hashes(node, config, leaf_tag)
+      if node.is_a?(Array)
+        node.map { |child| convert_elements_to_hashes(child, config, leaf_tag) }
+      else
+        # This is a leaf element, hash it and convert to hex
+        config.tagged_hash(node, leaf_tag).unpack1('H*')
+      end
+    end
+
+    # Compute hash for a node in the structure (binary tree only)
+    def compute_node_hash(node)
+      if node.is_a?(Array)
+        case node.length
+        when 1
+          # Single child - just return its hash
+          compute_node_hash(node[0])
+        when 2
+          # Binary node: compute hash of left and right children
+          left_hash = compute_node_hash(node[0])
+          right_hash = compute_node_hash(node[1])
+          
+          # Combine hashes according to sort_hashes config
+          combined = if config.sort_hashes
+            [left_hash, right_hash].sort.join
+          else
+            left_hash + right_hash
+          end
+          
+          config.tagged_hash(combined)
+        else
+          raise ArgumentError, "Binary tree nodes must have 1 or 2 children, got #{node.length}"
+        end
+      else
+        # Leaf node: already a hash, convert to binary
+        hex_to_bin(node)
+      end
+    end
+
+    # Override generate_proof to work with nested structure
+    def generate_proof(leaf_index)
+      all_leaves = extract_leaves(@leaves)
+      raise ArgumentError, 'leaf_index must be Integer' unless leaf_index.is_a?(Integer)
+      raise ArgumentError, 'leaf_index out of range' if leaf_index < 0 || all_leaves.length <= leaf_index
+
+      siblings, directions = siblings_with_directions(leaf_index)
+      siblings = siblings.map { |sibling| bin_to_hex(sibling) }
+      directions = [] if config.sort_hashes
+
+      Proof.new(
+        config: config,
+        root: compute_root,
+        leaf: all_leaves[leaf_index],
+        siblings: siblings,
+        directions: directions
+      )
+    end
+
+    private
+
+    # Extract all leaf hashes from the nested structure
+    def extract_leaves(node)
+      if node.is_a?(Array)
+        node.flat_map { |child| extract_leaves(child) }
+      else
+        # This is a leaf hash
+        [node]
+      end
+    end
+
+    # Validate that all leaves are valid hex strings and structure is binary
+    def validate_leaves!(leaves_to_validate)
+      leaves_to_validate.each do |leaf|
+        raise ArgumentError, "leaf hash must be string." unless leaf.is_a?(String)
+      end
+      validate_binary_structure(@leaves)
+    end
+    
+    # Validate that the structure is a binary tree (max 2 children per node)
+    def validate_binary_structure(node)
+      if node.is_a?(Array)
+        if node.length == 0
+          raise ArgumentError, "Binary tree nodes cannot be empty"
+        elsif node.length > 2
+          raise ArgumentError, "Binary tree nodes can have at most 2 children, got #{node.length}"
+        end
+        node.each { |child| validate_binary_structure(child) }
+      end
+    end
+    
+    # Override siblings_with_directions for proof generation
+    def siblings_with_directions(leaf_index)
+      all_leaves = extract_leaves(@leaves)
+      target_leaf = all_leaves[leaf_index]
+      siblings = []
+      directions = []
+      
+      # Build proof by finding the path to the target leaf
+      proof_path = build_proof_path(@leaves, target_leaf)
+      
+      proof_path.each do |level_info|
+        next if level_info[:siblings].empty?
+        
+        level_info[:siblings].each do |sibling|
+          siblings << sibling[:hash]
+          directions << sibling[:direction]
+        end
+      end
+      
+      [siblings, directions]
+    end
+    
+    # Build the proof path with siblings at each level
+    def build_proof_path(node, target_leaf, path = [])
+      if node.is_a?(Array)
+        # Find which child contains the target
+        node.each_with_index do |child, idx|
+          child_path = build_proof_path(child, target_leaf, path)
+          
+          if child_path
+            # Found the path, now collect siblings at this level
+            level_siblings = []
+            node.each_with_index do |sibling, sibling_idx|
+              next if sibling_idx == idx  # Skip the path we're on
+              
+              sibling_hash = compute_node_hash(sibling)
+              direction = sibling_idx < idx ? 0 : 1
+              level_siblings << { hash: sibling_hash, direction: direction }
+            end
+            
+            return child_path + [{ siblings: level_siblings }]
+          end
+        end
+        nil
+      else
+        # Leaf node
+        if node == target_leaf
+          []
+        else
+          nil
+        end
+      end
+    end
+
+    # Find the leaf index by searching through the tree
+    def find_leaf_index(node, target_leaf, current_index = [0])
+      if node.is_a?(Array)
+        node.each do |child|
+          result = find_leaf_index(child, target_leaf, current_index)
+          return result if result
+        end
+        nil
+      else
+        # This is a leaf
+        if node == target_leaf
+          current_index[0]
+        else
+          current_index[0] += 1
+          nil
+        end
+      end
+    end
+
+    # Not used in custom tree - structure is determined by nested array
+    def build_next_level(nodes)
+      raise NotImplementedError, "CustomTree uses structure-based computation"
+    end
+    
+  end
+end

data/lib/merkle/util.rb

@@ -2,6 +2,7 @@ module Merkle
   module Util
 
     # Check whether +data+ is hex string or not.
+    # @param [String] data
     # @return [Boolean]
     # @raise [ArgumentError]
     def hex_string?(data)
@@ -10,6 +11,7 @@ module Merkle
     end
 
     # Convert hex string +data+ to binary.
+    # @param [String] data
     # @return [String]
     # @raise [ArgumentError]
     def hex_to_bin(data)
@@ -17,6 +19,15 @@ module Merkle
       hex_string?(data) ? [data].pack('H*') : data
     end
 
+    # Convert binary string +data+ to hex string.
+    # @param [String] data
+    # @return [String]
+    # @raise [ArgumentError]
+    def bin_to_hex(data)
+      raise ArgumentError, 'data must be string' unless data.is_a?(String)
+      hex_string?(data) ? data : data.unpack1('H*')
+    end
+
     # Combine two elements(+left+ and +right+) with sort configuration.
     # @param [Merkle::Config] config
     # @param [String] left Left element(binary format).

data/lib/merkle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Merkle
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/merkle.rb

@@ -6,6 +6,7 @@ require_relative 'merkle/config'
 require_relative 'merkle/abstract_tree'
 require_relative 'merkle/binary_tree'
 require_relative 'merkle/adaptive_tree'
+require_relative 'merkle/custom_tree'
 require_relative 'merkle/proof'
 
 # Merkle tree module.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: merkle
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - azuchi
@@ -28,6 +28,7 @@ files:
 - lib/merkle/adaptive_tree.rb
 - lib/merkle/binary_tree.rb
 - lib/merkle/config.rb
+- lib/merkle/custom_tree.rb
 - lib/merkle/proof.rb
 - lib/merkle/util.rb
 - lib/merkle/version.rb