merkle 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaa0d4d13ee5bd6ff5e8b81aeb50396b8932f6efea765cc64dd1ff19614ebd9e
-  data.tar.gz: aa59ca4b87da23aa28707d4434209b36c03a7942b7635af036253c2dd7161607
+  metadata.gz: 900af6789d1eda0ed4bf1c4d8b3575a3b7c5789d4e5a84abe43304c49122a92b
+  data.tar.gz: d250d0b1ed630a82d8aa4fe66347319172d200b1416e95260a51a54135e539fc
 SHA512:
-  metadata.gz: fcf1016cc2bdbc721185ca647219c036cf05f13ad4534b4775d0ebb9ef3d585a9b97f1b40aac46b8f32b4aa3071821ba32d9ba7147ba86bf6c3a49eb0550290e
-  data.tar.gz: 36aec619bb2280e91b015409933c57d050787535a6890a4ee41efd86b6380af3300f81e488e2d5871fbb617b2af955ca4c9ba2437f012107fcff6c8f94eb3ecb
+  metadata.gz: 2bd898709716daecc0b73f006e8d3367ad8a01d9e2a40fae32a1819cc62d85229ff671f38d217dd1ffef2f548be56ca485c42b097348ed95d382fde51fdc7743
+  data.tar.gz: 3b95465023c7edb109836caa261ef4a0bdd376ab042742392f7381204d715111ce0f8fab01d6fb94d7917862341d9cec7d4b14d8f55dcb34f7af755dec6ef2ad

data/.ruby-version

@@ -1 +1 @@
-ruby-3.4.5
+ruby-4.0.0

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
@@ -120,6 +146,7 @@ non_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

@@ -20,6 +20,7 @@ module Merkle
 
     # Create tree from +elements+. For each element in elements,
     # we compute a tagged hash, which becomes the leaf value.
+    # The resulting leaves are hex strings, the same representation as leaves passed to #initialize.
     # @param [Merkle::Config] config Configuration for merkle tree.
     # @param [Array] elements An array of element that will be hashed to become leaves.
     # @param [String] leaf_tag An optional tag to use when computing the leaf hash.
@@ -28,7 +29,7 @@ module Merkle
       raise ArgumentError, 'elements must be Array' unless elements.is_a?(Array)
       raise ArgumentError, 'leaf_tag must be string' unless leaf_tag.is_a?(String)
       leaves = elements.map do |element|
-        config.tagged_hash(element, leaf_tag)
+        config.tagged_hash(element, leaf_tag).unpack1('H*')
       end
       self.new(config: config, leaves: leaves)
     end

data/lib/merkle/config.rb

@@ -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

@@ -129,77 +129,49 @@ module Merkle
     
     # 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
-      
+      collect_path(@leaves, leaf_index, siblings, directions)
       [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
+
+    # Walk down the structure toward the leaf at +index+ (counted within +node+), collecting the
+    # sibling hash and its direction at each branch. Siblings are collected deepest first, the
+    # order Proof#valid? folds them in.
+    # The descent is driven by the index rather than by the leaf value, so duplicate leaf hashes
+    # still yield the proof for the requested position.
+    # @param [Object] node A subtree (nested Array) or a leaf hash.
+    # @param [Integer] index The leaf index within +node+.
+    # @param [Array] siblings Collected sibling hashes(binary format).
+    # @param [Array] directions Collected directions(0: left, 1: right).
+    def collect_path(node, index, siblings, directions)
+      return unless node.is_a?(Array)
+
+      if node.length == 1
+        # Single child contributes no sibling, its hash is passed through unchanged.
+        return collect_path(node[0], index, siblings, directions)
       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
+      left, right = node
+      left_leaves = leaf_count(left)
+      if index < left_leaves
+        collect_path(left, index, siblings, directions)
+        siblings << compute_node_hash(right)
+        directions << 1 # sibling is on the right
       else
-        # This is a leaf
-        if node == target_leaf
-          current_index[0]
-        else
-          current_index[0] += 1
-          nil
-        end
+        collect_path(right, index - left_leaves, siblings, directions)
+        siblings << compute_node_hash(left)
+        directions << 0 # sibling is on the left
       end
     end
 
+    # Count the leaves under +node+.
+    # @param [Object] node A subtree (nested Array) or a leaf hash.
+    # @return [Integer] Number of leaves.
+    def leaf_count(node)
+      node.is_a?(Array) ? node.sum { |child| leaf_count(child) } : 1
+    end
+
     # Not used in custom tree - structure is determined by nested array
     def build_next_level(nodes)
       raise NotImplementedError, "CustomTree uses structure-based computation"

data/lib/merkle/proof.rb

@@ -2,21 +2,36 @@ module Merkle
   class Proof
     include Util
 
+    # Upper bound on the number of siblings, i.e. the depth of the tree the proof came from.
+    # A proof longer than this cannot correspond to any realistic tree, so it is rejected
+    # rather than hashed.
+    MAX_SIBLINGS = 64
+
     attr_reader :config, :root, :leaf, :siblings, :directions
 
     # Constructor.
     # @param [Merkle::Config] config
     # @param [String] root
     # @param [String] leaf
-    # @param [Array] siblings
+    # @param [Array] siblings An array of sibling hashes(64-character hex strings).
     # @param [Array] directions Array of positions at each level(0: left, 1: right),
     # only required if sort_hashes is false in config.
     def initialize(config:, root:, leaf:, siblings:, directions: [])
       raise ArgumentError, 'config must be a Merkle::Config' unless config.is_a?(Merkle::Config)
       raise ArgumentError, 'root must be string' unless root.is_a?(String)
       raise ArgumentError, 'leaf must be string' unless leaf.is_a?(String)
+      raise ArgumentError, 'siblings must be an Array' unless siblings.is_a?(Array)
+      raise ArgumentError, "siblings must not exceed #{MAX_SIBLINGS} elements" if siblings.length > MAX_SIBLINGS
+      siblings.each do |sibling|
+        raise ArgumentError, 'sibling must be string' unless sibling.is_a?(String)
+        raise ArgumentError, 'sibling must be a 64-character hex string' unless sibling.match?(/\A[0-9a-fA-F]{64}\z/)
+      end
       raise ArgumentError, 'directions must be an Array' unless directions.is_a?(Array)
       raise ArgumentError, 'No directions are required because sorted_hash is enabled' if config.sort_hashes && !directions.empty?
+      unless config.sort_hashes
+        raise ArgumentError, 'directions must have the same length as siblings' unless directions.length == siblings.length
+        raise ArgumentError, 'direction must be 0 or 1' unless directions.all? { |direction| direction == 0 || direction == 1 }
+      end
       @config = config
       @root = root
       @leaf = leaf

data/lib/merkle/util.rb

@@ -2,12 +2,15 @@ module Merkle
   module Util
 
     # Check whether +data+ is hex string or not.
+    # An odd-length string is not a hex string. Treating it as one would let
+    # +pack('H*')+ pad the missing nibble with zero, so 'abc' and 'abc0' would
+    # collide.
     # @param [String] data
     # @return [Boolean]
     # @raise [ArgumentError]
     def hex_string?(data)
       raise ArgumentError, 'data must be string' unless data.is_a?(String)
-      data.match?(/\A[0-9a-fA-F]+\z/)
+      data.length.even? && data.match?(/\A[0-9a-fA-F]+\z/)
     end
 
     # Convert hex string +data+ to binary.

data/lib/merkle/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: merkle
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - azuchi
@@ -54,7 +54,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A Ruby library for Merkle trees
 test_files: []