merkle 0.3.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce4faaabf24a85b734bd6cfe35081dfcc897bf418c5b391e68a84f8ec0aa9977
-  data.tar.gz: 944144e97463b2d0ad1ff7b2a882210548786035f52fa0090d505bbad7b9f88e
+  metadata.gz: 9b9d4e8996bfda0b7e8baa3c2324f51222503f658fc43c066819058ef028bdc7
+  data.tar.gz: 107526e231fb5925e181c7747f8130489278684ecfd37355ccc869adbcdc6d97
 SHA512:
-  metadata.gz: 49988d95199cf3e6a5e5944f69205d6b354ed4e5d811325c4e6ca8d4a868044b6c3dfc380491d1aa9c577ca7848770ea3c7e56d9212a1bb2a60cbc5c330a0060
-  data.tar.gz: 107fc3472cca81407b6fbc97a0981711f5538cdb2e657a032911d7866021fa37a4a30ac00ce5bcbebe2585849f700fc01c892c41670f619150d809c578fbb007
+  metadata.gz: 1467fc1c5715adfc418cc3ae5a44dab2c6dcad7b32f10d6fe2cd9eb264bace3d22d7f0f544cb87827048c67b6644a142c2b0754b5faaef2556966cf4493e515f
+  data.tar.gz: eb7621a6e1d771a96a219dcb283f379ace0c5528bb6ea5d8b1c08263b8e6f3f52166715848c35736aee449a1d6cbea890441a3c4f33861f7857a5ac664917c7b

data/.ruby-version

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

data/README.md

@@ -33,7 +33,12 @@ Or install it yourself as:
 require 'merkle'
 
 # Create configuration
-config = Merkle::Config.new(hash_type: :sha256)
+# element_encoding says how the elements passed to .from_elements are read:
+#   :hex    - elements are hex strings and are decoded before hashing
+#   :binary - elements are byte strings and are hashed as-is
+#   :auto   - legacy mode, see "Upgrading from 0.4.0 and earlier"
+# It has no default: guessing it silently changes the merkle root.
+config = Merkle::Config.new(element_encoding: :binary, hash_type: :sha256)
 
 # Method 1: Using pre-hashed leaves
 leaves = [
@@ -74,12 +79,12 @@ tree = Merkle::BinaryTree.from_elements(
 root = tree.compute_root
 puts "Root from elements: #{root}"
 
-# With optional leaf tag for tagged hashing (e.g., Taproot)
-taproot_config = Merkle::Config.taptree
+# Tags live on the config, so leaves and branches cannot drift apart.
+# Config.taptree carries leaf_tag: 'TapLeaf' and branch_tag: 'TapBranch'.
+taproot_config = Merkle::Config.taptree(element_encoding: :binary)
 tagged_tree = Merkle::AdaptiveTree.from_elements(
   config: taproot_config,
-  elements: elements,
-  leaf_tag: 'TapLeaf'  # Optional tag for leaf hashing
+  elements: elements
 )
 
 # Generate and verify proof
@@ -105,10 +110,11 @@ puts "Adaptive tree proof valid: #{proof.valid?}"
 # 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')
+# Leaves are always 64-character hex strings, the same form #compute_root returns.
+leaf_a = config.tagged_hash(config.encode_element('A')).unpack1('H*')
+leaf_b = config.tagged_hash(config.encode_element('B')).unpack1('H*')
+leaf_c = config.tagged_hash(config.encode_element('C')).unpack1('H*')
+leaf_d = config.tagged_hash(config.encode_element('D')).unpack1('H*')
 
 # Define structure: [[A, [B, C]], D]
 nested_leaves = [[leaf_a, [leaf_b, leaf_c]], leaf_d]
@@ -120,21 +126,24 @@ puts "Custom tree root: #{root}"
 # Valid structures:
 # - [A, B] → Simple binary node
 # - [[A, B], C] → Left subtree with right leaf
-# - [A] → Single child node
+# - [A] → A tree holding a single leaf
 # Invalid: [A, B, C] → Error (max 2 children per node)
+# Invalid: [[A, B]] → Error (a single-child node just passes its child's hash up,
+#                     so it would commit to the same root as [A, B])
 ```
 
 ### Configuration Options
 
 ```ruby
 # Bitcoin-compatible configuration with double SHA256
-bitcoin_config = Merkle::Config.new(hash_type: :double_sha256)
+bitcoin_config = Merkle::Config.new(element_encoding: :hex, hash_type: :double_sha256)
 
 # Configuration with tagged hashing (Taproot-style)
-taproot_config = Merkle::Config.taptree
+taproot_config = Merkle::Config.taptree(element_encoding: :hex)
 
 # Configuration with non-sorted hashing (directions needed in proofs)
 non_sorted_config = Merkle::Config.new(
+  element_encoding: :binary,
   hash_type: :sha256,
   sort_hashes: false
 )
@@ -162,3 +171,75 @@ The library generates compact Merkle proofs that include:
 proof = tree.generate_proof(leaf_index)
 is_valid = proof.valid? # Returns true/false
 ```
+
+`#valid?` folds `leaf` upwards through `siblings` and compares the result to `root`. It answers
+"do these hashes chain to this root", and nothing more. In particular it does not check that
+`leaf` sits at the bottom of the tree.
+
+**The verifier must derive `leaf` itself.** Hash the data you care about and build the proof
+around that value:
+
+```ruby
+leaf = config.tagged_hash(config.encode_element(my_data), config.leaf_tag).unpack1('H*')
+proof = Merkle::Proof.new(config: config, root: trusted_root, leaf: leaf,
+                          siblings: received_siblings, directions: received_directions)
+proof.valid?
+```
+
+Taking `leaf` from whoever supplied the proof defeats it: any internal node of the tree is a
+value that chains to the root, so it would be accepted as if it were a leaf.
+
+## Security considerations
+
+This library lets you build trees that are not second-preimage resistant, because Bitcoin's
+transaction merkle tree is one of them and cannot be changed. Two properties are left to the
+protocol built on top of it:
+
+- **Domain separation.** Give `leaf_tag` and `branch_tag` different values so that a leaf hash
+  can never equal an internal node hash. With both left empty, an attacker can craft an element
+  whose leaf hash equals an internal node and prove membership of something that was never in
+  the tree. `Config.taptree` sets both for you.
+- **Duplicate leaves (CVE-2012-2459).** `BinaryTree` duplicates the last node when a level holds
+  an odd number of them, exactly as Bitcoin does, so `[a, b, c]` and `[a, b, c, c]` share a root.
+  Use `AdaptiveTree` or `CustomTree` if you do not need Bitcoin compatibility.
+
+Element encoding, by contrast, is not left to guesswork: `element_encoding` is required on
+`Config`, so `'hello'` and `'68656c6c6f'` cannot silently resolve to the same leaf.
+
+### Upgrading from 0.4.0 and earlier
+
+`element_encoding` has no default, so every `Config` construction has to be updated. Pick the
+value that matches what you were already passing to `.from_elements`:
+
+| What you pass as elements | Use |
+| --- | --- |
+| Hex strings | `:hex` |
+| Raw byte strings | `:binary` |
+| A mix of both | `:auto` |
+
+`:auto` reproduces the old behaviour exactly, including its collisions: `'hello'` and
+`'68656c6c6f'` share a leaf under it, and so do `'AB'` and `'ab'`. Use it to keep verifying roots
+you already committed to, not for a new protocol. It reproduces 0.4.0; 0.3.1 and earlier also
+padded odd-length hex, so `'abc'` and `'abc0'` shared a leaf there and no mode reproduces that.
+
+`leaf_tag` moved from `.from_elements` to `Config`, next to `branch_tag`, so a protocol's tag
+spec lives in one place. Pass it to `Config.new` instead. `Config.taptree` now sets
+`leaf_tag: 'TapLeaf'` itself: if you were calling it without passing a leaf tag, your leaves were
+untagged and your roots were not BIP341 script trees. They are now, which changes those roots.
+
+Leaves are now always 64-character hex strings. If you were passing binary digests
+(`config.tagged_hash(...)`) as leaves, append `.unpack1('H*')`.
+
+**`Config#tagged_hash` is the one change that does not announce itself.** It now hashes its
+argument as bytes instead of decoding it when it looks like hex, so a direct call keeps working
+and returns a different digest:
+
+```ruby
+config.tagged_hash('deadbeef')                          # 0.4.0: hashed 4 bytes
+config.tagged_hash(config.encode_element('deadbeef'))   # 1.0.0: same 4 bytes, with :hex
+```
+
+Everything reached through `.from_elements` already goes through `encode_element`, so this only
+affects code that calls `tagged_hash` itself — typically to precompute leaves for `.new`. Audit
+those call sites: wrap the argument in `encode_element` to keep the old digest, or leave it bare
+if you were passing raw bytes all along.

data/lib/merkle/abstract_tree.rb

@@ -15,20 +15,22 @@ module Merkle
       raise ArgumentError, 'config must be Merkle::Config' unless config.is_a?(Merkle::Config)
       raise ArgumentError, 'leaves must be Array' unless leaves.is_a?(Array)
       @config = config
-      @leaves = leaves
+      # Copy, so that the array the caller keeps cannot change this tree's root behind its back.
+      @leaves = leaves.dup
+      validate_leaves!
     end
 
     # 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.
-    def self.from_elements(config:, elements:, leaf_tag: '')
+    # The tag used for the leaf hash comes from +config.leaf_tag+.
+    def self.from_elements(config:, elements:)
       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)
       leaves = elements.map do |element|
-        config.tagged_hash(element, leaf_tag)
+        config.tagged_hash(config.encode_element(element), config.leaf_tag).unpack1('H*')
       end
       self.new(config: config, leaves: leaves)
     end
@@ -38,8 +40,7 @@ module Merkle
     # @raise [Merkle::Error] If leaves is empty.
     def compute_root
       raise Error, 'leaves is empty' if leaves.empty?
-      # nodes = leaves
-      nodes = leaves.map {|leaf| hex_to_bin(leaf) }
+      nodes = leaves.map {|leaf| decode_hash(leaf) }
       while nodes.length > 1
         nodes = build_next_level(nodes)
       end
@@ -63,6 +64,12 @@ module Merkle
 
     private
 
+    # Validate the leaves this tree was built with.
+    # @raise [ArgumentError] If any leaf is not a node hash.
+    def validate_leaves!
+      leaves.each { |leaf| decode_hash(leaf) }
+    end
+
     # Gets the siblings that corresponds to +leaf_index+ and its directions (if necessary).
     # @param [Integer] leaf_index The leaf index.
     # @return [Array] An array of siblings and directions.

data/lib/merkle/adaptive_tree.rb

@@ -12,7 +12,7 @@ module Merkle
       directions = []
       
       current_index = leaf_index
-      nodes = leaves.map {|leaf| hex_to_bin(leaf) }
+      nodes = leaves.map {|leaf| decode_hash(leaf) }
       
       while nodes.length > 1
         # For adaptive tree, odd nodes are promoted to next level

data/lib/merkle/binary_tree.rb

@@ -13,7 +13,7 @@ module Merkle
       directions = []
       
       current_index = leaf_index
-      nodes = leaves.map {|leaf| hex_to_bin(leaf) }
+      nodes = leaves.map {|leaf| decode_hash(leaf) }
       
       while nodes.length > 1
         # If odd number of nodes, duplicate the last one

data/lib/merkle/config.rb

@@ -6,36 +6,79 @@ module Merkle
     # Supported Hash type.
     HASH_TYPES = [:sha256, :double_sha256]
 
-    attr_reader :hash_type, :branch_tag, :sort_hashes
+    # How the elements passed to .from_elements are turned into bytes.
+    # :hex    - each element is a hex string and is decoded before hashing.
+    # :binary - each element is already a byte string and is hashed as-is.
+    # :auto   - each element is decoded if it looks like hex, otherwise hashed as-is.
+    #
+    # :auto exists to reproduce roots computed by 0.4.0 and earlier, where this was the only
+    # behaviour. Do not choose it for a new protocol: 'hello' and '68656c6c6f' resolve to the
+    # same leaf under it, and so do 'AB' and 'ab'. Note it reproduces 0.4.0, not 0.3.1 and
+    # earlier, which also padded odd-length hex ('abc' and 'abc0' shared a leaf there).
+    ELEMENT_ENCODINGS = [:hex, :binary, :auto]
+
+    attr_reader :hash_type, :leaf_tag, :branch_tag, :sort_hashes, :element_encoding
 
     # Constructor
+    # @param [Symbol] element_encoding How elements are interpreted, :hex, :binary or :auto.
+    # This has no default on purpose. Guessing it silently changes the merkle root.
+    # See ELEMENT_ENCODINGS before reaching for :auto.
     # @param [Symbol] hash_type The hashing algorithm used to hash the internal nodes.
+    # @param [String] leaf_tag Tag to use when hashing leaves.
+    # Give this and +branch_tag+ different values so that a leaf hash can never equal an internal
+    # node hash. With both left empty the tree is not second-preimage resistant.
     # @param [String] branch_tag Tags to use when hashing internal nodes.
     # @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: true)
+    def initialize(element_encoding:, hash_type: :sha256, leaf_tag: '', branch_tag: '', sort_hashes: true)
+      raise ArgumentError, "element_encoding #{element_encoding} does not supported." unless ELEMENT_ENCODINGS.include?(element_encoding)
       raise ArgumentError, "hash_type #{hash_type} does not supported." unless HASH_TYPES.include?(hash_type)
+      raise ArgumentError, "leaf_tag must be string." unless leaf_tag.is_a?(String)
       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)
+      @element_encoding = element_encoding
       @hash_type = hash_type
-      @branch_tag = branch_tag
+      # Freeze the tags. A config is shared by every tree built with it, so mutating one in place
+      # would change the root of all of them and invalidate proofs already handed out.
+      @leaf_tag = leaf_tag.dup.freeze
+      @branch_tag = branch_tag.dup.freeze
       @sort_hashes = sort_hashes
     end
 
     # Bitcoin configuration.
+    # @param [Symbol] element_encoding How elements are interpreted, :hex, :binary or :auto.
     # @return [Merkle::Config]
-    def self.bitcoin
-      Config.new(hash_type: :double_sha256, sort_hashes: false)
+    def self.bitcoin(element_encoding:)
+      Config.new(element_encoding: element_encoding, hash_type: :double_sha256, sort_hashes: false)
     end
 
     # Taptree configuration.
+    # @param [Symbol] element_encoding How elements are interpreted, :hex, :binary or :auto.
     # @return [Merkle::Config]
-    def self.taptree
-      Config.new(branch_tag: 'TapBranch')
+    def self.taptree(element_encoding:)
+      Config.new(element_encoding: element_encoding, leaf_tag: 'TapLeaf', branch_tag: 'TapBranch')
+    end
+
+    # Convert +element+ into the byte string to be hashed, following element_encoding.
+    # @param [String] element An element as given to .from_elements.
+    # @return [String] Byte string.
+    # @raise [ArgumentError] If +element+ does not match element_encoding.
+    def encode_element(element)
+      raise ArgumentError, "element must be string." unless element.is_a?(String)
+      case element_encoding
+      when :hex
+        raise ArgumentError, "element must be a hex string." unless hex_string?(element)
+        [element].pack('H*')
+      when :binary
+        element.b
+      when :auto
+        hex_string?(element) ? [element].pack('H*') : element.b
+      end
     end
 
-    # Generate tagged hash.
+    # Generate tagged hash. +data+ is always hashed as a byte string.
+    # To hash an element written as hex, pass it through #encode_element first.
     # @param [String] data The data to be hashed.
     # @param [String] tag Tag string used tagging.
     # @return [String] Tagged hash value.
@@ -43,7 +86,7 @@ module Merkle
       raise ArgumentError, "data must be string." unless data.is_a?(String)
       raise ArgumentError, "tag must be a String." unless tag.is_a?(String)
 
-      data_bin = hex_to_bin(data).b
+      data_bin = data.b
 
       unless tag.empty?
         tag_bin = Digest::SHA256.digest(tag).b

data/lib/merkle/custom_tree.rb

@@ -9,28 +9,29 @@ module Merkle
     #                       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: '')
+    # The tag used for the leaf hash comes from +config.leaf_tag+.
+    def self.from_elements(config:, elements:)
       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)
-      
+
+      # Convert elements to hashes while preserving structure. This walks the input before the
+      # constructor gets to check it, so it has to enforce the depth limit itself.
+      hashed_structure = convert_elements_to_hashes(elements, config)
+
       self.new(config: config, leaves: hashed_structure)
     end
 
     # Compute merkle root using custom structure
     # @return [String] merkle root
     def compute_root
+      # Re-check here rather than trusting the constructor. +leaves+ is readable and its arrays
+      # are mutable, so a structure that was rejected at construction can be assembled afterwards.
+      validate_leaves!
       all_leaves = extract_leaves(@leaves)
       raise Error, 'leaves is empty' if all_leaves.empty?
       result = compute_node_hash(@leaves)
@@ -38,12 +39,13 @@ module Merkle
     end
 
     # Convert nested elements to nested hashes
-    def self.convert_elements_to_hashes(node, config, leaf_tag)
+    def self.convert_elements_to_hashes(node, config, depth = 0)
       if node.is_a?(Array)
-        node.map { |child| convert_elements_to_hashes(child, config, leaf_tag) }
+        raise ArgumentError, "Binary tree must not be deeper than #{MAX_DEPTH}" if depth >= MAX_DEPTH
+        node.map { |child| convert_elements_to_hashes(child, config, depth + 1) }
       else
         # This is a leaf element, hash it and convert to hex
-        config.tagged_hash(node, leaf_tag).unpack1('H*')
+        config.tagged_hash(config.encode_element(node), config.leaf_tag).unpack1('H*')
       end
     end
 
@@ -72,12 +74,18 @@ module Merkle
         end
       else
         # Leaf node: already a hash, convert to binary
-        hex_to_bin(node)
+        decode_hash(node)
       end
     end
 
+    private_class_method :convert_elements_to_hashes
+    private :compute_node_hash
+
     # Override generate_proof to work with nested structure
     def generate_proof(leaf_index)
+      # Walking the structure before checking it would hit the recursion limit on a structure
+      # assembled after construction, and SystemStackError escapes the caller's rescue.
+      validate_leaves!
       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
@@ -107,99 +115,85 @@ module Merkle
       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)
+    # Validate that the structure is a binary tree and that every leaf is a node hash.
+    def validate_leaves!
+      validate_binary_structure(@leaves, root: true)
+      extract_leaves(@leaves).each { |leaf| decode_hash(leaf) }
     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}"
+
+    # Validate that the structure is a binary tree (exactly 2 children per node)
+    # @param [Object] node A subtree (nested Array) or a leaf hash.
+    # @param [Boolean] root Whether +node+ is the whole tree.
+    # @param [Integer] depth How far below the root +node+ sits.
+    def validate_binary_structure(node, root: false, depth: 0)
+      return unless node.is_a?(Array)
+      # +depth+ counts the branches above this node, so a node here puts its children at
+      # depth + 1. Stopping at MAX_DEPTH keeps the deepest leaf within MAX_DEPTH branches,
+      # which is what Proof::MAX_SIBLINGS allows a proof to carry.
+      raise ArgumentError, "Binary tree must not be deeper than #{MAX_DEPTH}" if depth >= MAX_DEPTH
+
+      case node.length
+      when 0
+        raise ArgumentError, "Binary tree nodes cannot be empty"
+      when 1
+        # A node with one child contributes no branch hash, it just passes the child up.
+        # That would let [[a]] and [a, [b]] commit to the same root as [a] and [a, b].
+        # A tree holding a single leaf is the one case where there is nothing to confuse it with.
+        unless root && !node[0].is_a?(Array)
+          raise ArgumentError, "Binary tree nodes must have 2 children unless the tree is a single leaf"
         end
-        node.each { |child| validate_binary_structure(child) }
+      when 2
+        node.each { |child| validate_binary_structure(child, depth: depth + 1) }
+      else
+        raise ArgumentError, "Binary tree nodes can have at most 2 children, got #{node.length}"
       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
-      
+      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,35 +2,56 @@ 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. It matches the deepest tree the library will build, which is also the
+    # deepest a BIP341 script tree can be: a control block carries at most 128 path elements.
+    MAX_SIBLINGS = MAX_DEPTH
+
     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, "root must be a #{HASH_SIZE * 2}-character hex string" unless node_hash?(root)
       raise ArgumentError, 'leaf must be string' unless leaf.is_a?(String)
+      raise ArgumentError, "leaf must be a #{HASH_SIZE * 2}-character hex string" unless node_hash?(leaf)
+      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 #{HASH_SIZE * 2}-character hex string" unless node_hash?(sibling)
+      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
-      @siblings = siblings
-      @directions = directions
+      # Normalize and freeze. The checks above only bind if the arrays cannot grow afterwards:
+      # a caller holding the array it passed in could otherwise append past MAX_SIBLINGS, or
+      # shorten directions until #valid? reads nil and folds as if the sibling were on the right.
+      @root = normalize_hash(root)
+      @leaf = normalize_hash(leaf)
+      @siblings = siblings.map { |sibling| normalize_hash(sibling) }.freeze
+      @directions = directions.dup.freeze
     end
 
     # Verify the proof.
     # @return [Boolean] true if the proof is valid, false otherwise.
     def valid?
-      current = hex_to_bin(leaf)
+      current = decode_hash(leaf)
 
       siblings.each_with_index do |sibling, index|
-        sibling_bin = hex_to_bin(sibling)
+        sibling_bin = decode_hash(sibling)
         
         if config.sort_hashes
           # Sort lexicographically when combining
@@ -44,7 +65,9 @@ module Merkle
         current = config.tagged_hash(combined)
       end
 
-      current.unpack1('H*') == root
+      # Compare the decoded bytes. Comparing the hex would make the result depend on the case
+      # the caller happened to write +root+ in, even though both spell the same hash.
+      current == decode_hash(root)
     end
 
   end

data/lib/merkle/util.rb

@@ -1,22 +1,61 @@
 module Merkle
   module Util
 
+    # Size of a node hash in bytes. Leaves, siblings and internal nodes are all this size.
+    HASH_SIZE = 32
+
+    # Deepest tree accepted. A tree deeper than this cannot be walked without risking a
+    # SystemStackError, which is not a StandardError and so escapes a caller's rescue.
+    # 128 is also the deepest a BIP341 script tree can be.
+    MAX_DEPTH = 128
+
     # 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/)
+      # Match on the bytes. Matching the string itself raises Encoding::CompatibilityError for a
+      # UTF-16 string and ArgumentError for invalid UTF-8, neither of which the caller expects.
+      bytes = data.b
+      bytes.bytesize.even? && bytes.match?(/\A[0-9a-fA-F]+\z/)
     end
 
-    # Convert hex string +data+ to binary.
-    # @param [String] data
-    # @return [String]
+    # Check whether +hex+ is the hex representation of a node hash.
+    # @param [String] hex
+    # @return [Boolean]
+    def node_hash?(hex)
+      return false unless hex.is_a?(String)
+      # Match on the bytes. Matching the string itself raises on a value that claims to be UTF-8
+      # but holds invalid bytes, which would surface as an unrelated ArgumentError.
+      bytes = hex.b
+      bytes.bytesize == HASH_SIZE * 2 && bytes.match?(/\A[0-9a-fA-F]+\z/)
+    end
+
+    # Convert a node hash from its hex representation to binary.
+    # Node hashes are always +HASH_SIZE+ bytes written as hex, so anything else is rejected
+    # rather than guessed at. Accepting arbitrary lengths here would make the concatenation
+    # in an internal node ambiguous: ['aa', 'bbcc'] and ['aabb', 'cc'] would hash alike.
+    # @param [String] hex
+    # @return [String] Binary format hash.
     # @raise [ArgumentError]
-    def hex_to_bin(data)
-      raise ArgumentError, 'data must be string' unless data.is_a?(String)
-      hex_string?(data) ? [data].pack('H*') : data
+    def decode_hash(hex)
+      raise ArgumentError, 'hash must be string' unless hex.is_a?(String)
+      raise ArgumentError, "hash must be a #{HASH_SIZE * 2}-character hex string" unless node_hash?(hex)
+      [hex].pack('H*')
+    end
+
+    # Rewrite a node hash in the one spelling the library uses: lower case hex.
+    # Upper case names the same hash, so returning it verbatim would let a caller that matches
+    # leaves as strings miss a leaf whose proof verifies.
+    # @param [String] hex
+    # @return [String] Frozen lower case hex.
+    # @raise [ArgumentError]
+    def normalize_hash(hex)
+      bin_to_hex(decode_hash(hex)).freeze
     end
 
     # Convert binary string +data+ to hex string.
@@ -25,7 +64,7 @@ module Merkle
     # @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*')
+      data.unpack1('H*')
     end
 
     # Combine two elements(+left+ and +right+) with sort configuration.
@@ -48,4 +87,4 @@ module Merkle
     end
 
   end
-end
+end

data/lib/merkle/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: merkle
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 1.0.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: []