merkle 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bce04358fd44b062aa388fdc8bb834a33e6dc082ae522e097f7a90a777cceb7d
-  data.tar.gz: e9cdee4066043760ecd72b89bc355060cb47273ae13a4b1c379e7ecca494fb62
+  metadata.gz: eaa0d4d13ee5bd6ff5e8b81aeb50396b8932f6efea765cc64dd1ff19614ebd9e
+  data.tar.gz: aa59ca4b87da23aa28707d4434209b36c03a7942b7635af036253c2dd7161607
 SHA512:
-  metadata.gz: 7f5719c3393e13411152b2207ad1c3c109c468d0611d9c5d5c83d1430ee427dbfe914aa427145052a7bc8a55f8ebb71aaa809d45516b61243981f50a58388165
-  data.tar.gz: 7dac36c4c6aaa55107f8ca2b7c7b06efba49c59f66017e50a225c463d17f4635f13f5401b640a0735c2893ac819574589655ec9f5e5eeed0ffaf2a1704a0a7f8
+  metadata.gz: fcf1016cc2bdbc721185ca647219c036cf05f13ad4534b4775d0ebb9ef3d585a9b97f1b40aac46b8f32b4aa3071821ba32d9ba7147ba86bf6c3a49eb0550290e
+  data.tar.gz: 36aec619bb2280e91b015409933c57d050787535a6890a4ee41efd86b6380af3300f81e488e2d5871fbb617b2af955ca4c9ba2437f012107fcff6c8f94eb3ecb

data/README.md

@@ -35,7 +35,7 @@ require 'merkle'
 # Create configuration
 config = Merkle::Config.new(hash_type: :sha256)
 
-# Prepare leaves (hex strings)
+# Method 1: Using pre-hashed leaves
 leaves = [
   'a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3',
   'b3a8e0e1f9ab1bfe3a36f231f676f78bb30a519d2b21e6c530c0eee8ebb4a5d0',
@@ -58,6 +58,35 @@ puts "Proof directions: #{proof.directions}"
 puts "Proof valid: #{proof.valid?}"
 ```
 
+### Using from_elements
+
+```ruby
+# Method 2: Using from_elements to automatically hash raw data
+elements = ['hello', 'world', 'merkle', 'tree']
+
+# Create tree from raw elements
+tree = Merkle::BinaryTree.from_elements(
+  config: config, 
+  elements: elements
+)
+
+# The elements are automatically hashed before building the tree
+root = tree.compute_root
+puts "Root from elements: #{root}"
+
+# With optional leaf tag for tagged hashing (e.g., Taproot)
+taproot_config = Merkle::Config.taptree
+tagged_tree = Merkle::AdaptiveTree.from_elements(
+  config: taproot_config,
+  elements: elements,
+  leaf_tag: 'TapLeaf'  # Optional tag for leaf hashing
+)
+
+# Generate and verify proof
+proof = tree.generate_proof(0)
+puts "Proof for first element valid: #{proof.valid?}"
+```
+
 ### Adaptive Tree Example
 
 ```ruby
@@ -78,10 +107,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
 )
 ```
 

data/lib/merkle/abstract_tree.rb

@@ -11,13 +11,28 @@ module Merkle
     # @param [Merkle::Config] config Configuration for merkle tree.
     # @param [Array] leaves An array of leaves.
     # @raise [ArgumentError]
-    def initialize(config:, leaves: [])
+    def initialize(config:, leaves: )
       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
     end
 
+    # Create tree from +elements+. For each element in elements,
+    # we compute a tagged hash, which becomes the leaf value.
+    # @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: '')
+      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)
+      end
+      self.new(config: config, leaves: leaves)
+    end
+
     # Compute merkle root.
     # @return [String] merkle root (hex value). For Bitcoin, the endianness of this value must be reversed.
     # @raise [Merkle::Error] If leaves is empty.
@@ -41,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.

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.1.0"
+  VERSION = "0.3.0"
 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.1.0
+  version: 0.3.0
 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