merkle_tree 0.1.0

data/lib/merkle_tree/leaf.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class MerkleTree
+  # An object to hold one-time signature
+  # @api private
+  class Leaf
+    include Comparable
+
+    attr_reader :height
+
+    attr_accessor :value
+
+    attr_reader :left_index
+
+    attr_reader :right_index
+
+    def self.build(value, position, digest: MerkleTree.default_digest)
+      new(digest.(value), position, position)
+    end
+
+    # Create a leaf node
+    #
+    # @api private
+    def initialize(value, left_index, right_index)
+      @value = value
+      @left_index = left_index
+      @right_index = right_index
+      @height = 0
+    end
+
+    def leaf?
+      true
+    end
+
+    def include?(index)
+      (left_index..right_index).cover?(index)
+    end
+
+    def size
+      1
+    end
+
+    def <=>(other)
+      value <=> other.value &&
+        left_index <=> other.left_index &&
+        right_index <=> other.right_index
+    end
+
+    def to_h
+      { value: value }
+    end
+
+    def to_s(indent = '')
+      indent + value
+    end
+  end # Leaf
+end # MerkleTree

data/lib/merkle_tree/node.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+class MerkleTree
+  # Holds information about intermediate hashes
+  # @api private
+  class Node
+    include Comparable
+
+    UNDEFINED = Module.new
+
+    attr_reader :value
+
+    attr_accessor :left
+
+    attr_accessor :right
+
+    # The node height in the tree
+    attr_reader :height
+
+    # The sequential position in the tree
+    attr_reader :left_index
+
+    attr_reader :right_index
+
+    def self.build(left, right, digest: MerkleTree.default_digest)
+      value  = digest.(left.value + right.value)
+      height = left.height + 1
+      left_index  = left.left_index
+      right_index = right.right_index
+
+      new(value, left, right, height, left_index, right_index)
+    end
+
+    # Create a node
+    #
+    # @api private
+    def initialize(value, left, right, height, left_index, right_index)
+      @value  = value
+      @left   = left
+      @right  = right
+      @height = height
+      @left_index  = left_index
+      @right_index = right_index
+    end
+
+    def leaf?
+      false
+    end
+
+    def size
+      left.size + 1 + right.size
+    end
+
+    def include?(index)
+      (left_index..right_index).cover?(index)
+    end
+
+    def update(digest)
+      @value = digest.(left.value + right.value)
+    end
+
+    def child(index)
+      if left.include?(index)
+        left
+      else
+        right.include?(index) ? right : EMPTY
+      end
+    end
+
+    # Find sibling child node for the index
+    def sibling(index)
+      if left.include?(index)
+        [:right, right.value]
+      else
+        right.include?(index) ? [:left, left.value] : EMPTY
+      end
+    end
+
+    # Find subtree that matches the index
+    def subtree(index)
+      if left.include?(index)
+        left
+      else
+        right.include?(index) ? right : EMPTY
+      end
+    end
+
+    def <=>(other)
+      value <=> other.value &&
+        left_index <=> other.left_index &&
+        right_index <=> other.right_index
+    end
+
+    def to_h
+      { value: value, left: left.to_h, right: right.to_h }
+    end
+
+    def to_s(indent = '')
+      indent + value.to_s + $RS +
+        left.to_s(indent + '  ') + $RS +
+        right.to_s(indent + '  ')
+    end
+
+    # An empty node used as placeholder
+    # @api private
+    class EmptyNode < Node
+      def initialize
+        @value  = ''
+        @height = 0
+        @left   = UNDEFINED
+        @right  = UNDEFINED
+        @left_index = UNDEFINED
+        @right_index = UNDEFINED
+      end
+
+      def size
+        0
+      end
+
+      def sibling(*)
+        []
+      end
+
+      def subtree(*)
+        {}
+      end
+
+      def to_s; end
+
+      def to_h
+        {}
+      end
+    end # EmptyNode
+
+    EMPTY = EmptyNode.new.freeze
+  end # Node
+end # MerkleTree

data/lib/merkle_tree/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class MerkleTree
+  VERSION = '0.1.0'
+end

data/merkle_tree.gemspec

@@ -0,0 +1,33 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "merkle_tree/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "merkle_tree"
+  spec.version       = MerkleTree::VERSION
+  spec.authors       = ["Piotr Murach"]
+  spec.email         = ["me@piotrmurach.com"]
+
+  spec.summary       = %q{A binary tree of one-time signatures known as a merkle tree.}
+  spec.description   = %q{A binary tree of one-time singatures known as a merkle tree. Often used in distributed systems such as Git, Cassandra or Bitcoin for efficiently summarizing sets of data.}
+  spec.homepage      = "https://github.com/piotrmurach/merkle_tree"
+  spec.license       = "MIT"
+
+  if spec.respond_to?(:metadata)
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/piotrmurach/merkle_tree"
+    spec.metadata["changelog_uri"] = "https://github.com/piotrmurach/merkle_tree/blob/master/CHANGELOG.md"
+  end
+
+  spec.files         = Dir['{lib,spec,examples}/**/*.rb']
+  spec.files        += Dir['{bin,tasks}/*', 'merkle_tree.gemspec']
+  spec.files        += Dir['README.md', 'CHANGELOG.md', 'LICENSE.txt', 'Rakefile']
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", ">= 1.17"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec-benchmark"
+end

data/spec/perf/speed_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+RSpec.describe 'speed performance' do
+  it "creates merkle trees in linear time" do
+    messages = bench_range(8, 8 << 12).map do |n|
+      Array.new(n) { "L#{n}" }
+    end
+
+    expect { |n, i|
+      MerkleTree.new(*messages[i])
+    }.to perform_linear.in_range(8, 8 << 12)
+  end
+
+  it "checks if a message belongs in logarithmic time" do
+    trees = []
+    bench_range(8, 8 << 12).each do |n|
+      messages = []
+      n.times { |i| messages << "L#{i}" }
+      trees << MerkleTree.new(*messages)
+    end
+
+    expect { |n, i|
+      trees[i].include?("L#{n/2}", n/2)
+    }.to perform_logarithmic.in_range(8, 8 << 12).sample(100).times
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+if ENV['COVERAGE'] || ENV['TRAVIS']
+  require 'simplecov'
+  require 'coveralls'
+
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+    SimpleCov::Formatter::HTMLFormatter,
+    Coveralls::SimpleCov::Formatter
+  ]
+
+  SimpleCov.start do
+    command_name 'spec'
+    add_filter 'spec'
+  end
+end
+
+require "bundler/setup"
+require "rspec-benchmark"
+require "merkle_tree"
+
+RSpec.configure do |config|
+  config.include RSpec::Benchmark::Matchers
+
+  # Enable flags like --only-failures and --next-failure
+  # config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

data/spec/unit/add_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+RSpec.describe MerkleTree, '#add' do
+  it "adds one message" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4")
+    expanded_tree = MerkleTree.new("L1", "L2", "L3", "L4", "L5")
+
+    merkle_tree << "L5"
+
+    expect(merkle_tree.leaves.size).to eq(expanded_tree.leaves.size)
+    expect(merkle_tree.size).to eq(expanded_tree.size)
+    expect(merkle_tree.root.value).to eq(expanded_tree.root.value)
+  end
+
+  it "adds even messages" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4")
+    expanded_tree = MerkleTree.new("L1", "L2", "L3", "L4", "L5", "L6")
+
+    merkle_tree.add("L5", "L6")
+
+    expect(merkle_tree.leaves.size).to eq(expanded_tree.leaves.size)
+    expect(merkle_tree.size).to eq(expanded_tree.size)
+    expect(merkle_tree.root.value).to eq(expanded_tree.root.value)
+  end
+
+  it "adds messages double the size"  do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4")
+    expanded_tree = MerkleTree.new("L1", "L2", "L3", "L4", "L5", "L6", "L7", "L8")
+
+    merkle_tree.add("L5", "L6", "L7", "L8")
+
+    expect(merkle_tree.leaves.size).to eq(expanded_tree.leaves.size)
+    expect(merkle_tree.root.value).to eq(expanded_tree.root.value)
+    expect(merkle_tree.size).to eq(expanded_tree.size)
+  end
+end

data/spec/unit/auth_path_spec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+RSpec.describe MerkleTree, '#auth_path' do
+  it "fails to find authentication path for an index" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4")
+
+    expect(merkle_tree.auth_path(100)).to eq([MerkleTree::Node::EMPTY])
+  end
+
+  it "finds authentication path for an index" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4")
+
+    expect(merkle_tree.auth_path(2)).to eq([
+      [:left,"f2b92f33b56466fce14bc2ccf6a92f6edfcd8111446644c20221d6ae831dd67c"],
+      [:right,"4a5a97c6433c4c062457e9335709d57493e75527809d8a9586c141e591ac9f2c"]
+    ])
+  end
+end

data/spec/unit/empty_spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+RSpec.describe MerkleTree, '#empty?' do
+  it "returns true when tree has no messages" do
+    merkle_tree = MerkleTree.new
+
+    expect(merkle_tree.empty?).to eq(true)
+  end
+
+  it "returns false when tree has messages" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4", "L5", "L6", "L7", "L8")
+
+    expect(merkle_tree.empty?).to eq(false)
+  end
+end

data/spec/unit/height_spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+RSpec.describe MerkleTree, '#height' do
+  it "has no messages" do
+    merkle_tree = MerkleTree.new
+
+    expect(merkle_tree.height).to eq(0)
+  end
+
+  it "calculates tree height" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4", "L5", "L6")
+
+    expect(merkle_tree.height).to eq(3)
+  end
+end

data/spec/unit/include_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+RSpec.describe MerkleTree, '#include?' do
+  it "checks message inclusion in an empty tree" do
+    merkle_tree = MerkleTree.new
+
+    expect(merkle_tree.include?("L3", 2)).to eq(false)
+  end
+
+  it "checks valid message inclusion in 4 signatures tree" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4")
+
+    expect(merkle_tree.include?("L3", 2)).to eq(true)
+  end
+
+  it "checks valid message inclusion in 8 signatures tree" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4", "L5", "L6", "L7", "L8")
+
+    expect(merkle_tree.include?("L5", 4)).to eq(true)
+  end
+
+  it "checks invalid message inclusion in 8 signatures tree" do
+    merkle_tree = MerkleTree.new("L1", "L2", "L3", "L4", "L5", "L6", "L7", "L8")
+
+    expect(merkle_tree.include?("invalid", 4)).to eq(false)
+  end
+end

data/spec/unit/leaf/build_spec.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+RSpec.describe MerkleTree::Leaf, '::build' do
+  it "creates a leaf node" do
+    leaf_node = MerkleTree::Leaf.build("L1", 0)
+
+    expect(leaf_node.value).to eq("dffe8596427fc50e8f64654a609af134d45552f18bbecef90b31135a9e7acaa0")
+  end
+end

data/spec/unit/leaf/eql_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+RSpec.describe MerkleTree::Leaf, '#==' do
+  it "compares two different leaves with the same message" do
+    leaf_a = MerkleTree::Leaf.build("L1", 0)
+    leaf_b = MerkleTree::Leaf.build("L1", 1)
+
+    expect(leaf_a).to_not eq(leaf_b)
+  end
+
+  it "compares successfully only with the same leaf" do
+    leaf = MerkleTree::Leaf.build("L1", 0)
+
+    expect(leaf).to eq(leaf)
+  end
+end