merkletree 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 24b3c06202925e5eb62bcd41da3f8a24d6796fc3
-  data.tar.gz: ed098810fab12bda058386e887b59fec7b76f120
+  metadata.gz: 9bdd4412b5bb49cfa7d3f5d5d93d5f0254248952
+  data.tar.gz: 3759dac07a1eb87444a7264089a83a113ec62a18
 SHA512:
-  metadata.gz: ee94f77dde4f3da9e0cd3d6633e3a6658d9088549d3163614fc803611601fd41eb0b6d7eadf27e1c2d5dacdb1ebfc15125fad664c745697d03758e70b00075a6
-  data.tar.gz: 0b1c49deb2ac3d5b07fb38f65b0582186671e26c2346c1cdc9a0acd7c1fcd61f6c49abf359d5002d50c600e07b38c4a0da6eac73fc4201c81a3a7d76d0e37920
+  metadata.gz: a99eb56b3472efcca00ea11d2b9a7dedc69903dc43d33cd5d9677dd737b32288a216fd6d5f1be9bf4b6b893c311034c9c30cc7ffd0f890e65827dd730f36881f
+  data.tar.gz: a0c2465fcb59581478779ef74bd05bf74642fb5b818072d53847fa949cdb66e8f127852edc5d99ef4ab4652d3a454ab850fbcc640a75bf6e73a91b5fc3f23594

data/Manifest.txt

@@ -5,3 +5,7 @@ README.md
 Rakefile
 lib/merkletree.rb
 lib/merkletree/version.rb
+test/helper.rb
+test/test_build.rb
+test/test_readme.rb
+test/test_version.rb

data/README.md

@@ -9,6 +9,149 @@ merkletree library / gem - build your own crypto hash trees; named after Ralph M
 * rdoc  :: [rubydoc.info/gems/merkletree](http://rubydoc.info/gems/merkletree)
 
 
+## What's a Merkle Tree?
+
+> A Merkle tree or hash tree is a tree in which every leaf node is labelled with
+> the hash of a data block and every non-leaf node is labelled with the
+> cryptographic hash of the labels of its child nodes.
+> Hash trees allow efficient and secure verification of the
+> contents of large data structures. [...]
+>
+> The concept of hash trees is named after Ralph Merkle
+> who patented it in 1979.
+>
+> -- [Wikipedia](https://en.wikipedia.org/wiki/Merkle_tree)
+
+
+## Usage
+
+
+Pass along all (leaf / data block) hashes as strings or packaged in an array.
+Example:
+
+``` ruby
+merkle = MerkleTree.new(
+  'eb8ecbf6d5870763ae246e37539d82e37052cb32f88bb8c59971f9978e437743',
+  'edbd4e11e69bc399a9ccd8faaea44fb27410fe8e3023bb9462450a0a9c4caa1b',
+  '5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d' )
+
+# -or-
+
+merkle = MerkleTree.new( [
+  'eb8ecbf6d5870763ae246e37539d82e37052cb32f88bb8c59971f9978e437743',
+  'edbd4e11e69bc399a9ccd8faaea44fb27410fe8e3023bb9462450a0a9c4caa1b',
+  '5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d' ])
+
+
+puts 'merkle tree root hash:'
+puts merkle.root.value
+# => '25fd59b79d70bbdf043d66a7b0fc01409d11b990e943bb46b840fbbddd5ab895'
+
+pp merkle    ## pp (pretty print)
+```
+
+resulting in:
+
+```
+@root = #<MerkleTree::Node:0x46b55e0
+   @left = #<MerkleTree::Node:0x46b6060
+     @left = #<MerkleTree::Node:0x46b6870
+       @left  = nil,
+       @right = nil,
+       @value = "eb8ecbf6d5870763ae246e37539d82e37052cb32f88bb8c59971f9978e437743">,
+     @right = #<MerkleTree::Node:0x46b6810
+       @left  = nil,
+       @right = nil,
+       @value = "edbd4e11e69bc399a9ccd8faaea44fb27410fe8e3023bb9462450a0a9c4caa1b">,
+     @value = "c9de03ced4db3c63835807016b1efedb647c694d2db8b9a8579cbf0c5dcb5ab0">,
+   @right= #<MerkleTree::Node:0x46b5ca0
+     @left= #<MerkleTree::Node:0x46b6798
+       @left  = nil,
+       @right = nil,
+       @value = "5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d">,
+     @right = #<MerkleTree::Node:0x46b6798
+       @left  = nil,
+       @right = nil,
+       @value = "5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d">,
+     @value = "50963aa3b2047e0d58bb850fc12e5a324cf01061af55889389be72d3849e1d03">,
+   @value="25fd59b79d70bbdf043d66a7b0fc01409d11b990e943bb46b840fbbddd5ab895">>
+```
+
+
+Use `MerkleTree.compute_root` for computing the root (crypto) hash without building a
+tree. Example:
+
+``` ruby
+merkle_root_value = MerkleTree.compute_root(
+  'eb8ecbf6d5870763ae246e37539d82e37052cb32f88bb8c59971f9978e437743',
+  'edbd4e11e69bc399a9ccd8faaea44fb27410fe8e3023bb9462450a0a9c4caa1b',
+  '5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d' )
+
+# -or-
+
+merkle_root_value = MerkleTree.compute_root( [
+  'eb8ecbf6d5870763ae246e37539d82e37052cb32f88bb8c59971f9978e437743',
+  'edbd4e11e69bc399a9ccd8faaea44fb27410fe8e3023bb9462450a0a9c4caa1b',
+  '5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d' ])
+
+
+puts 'merkle tree root hash:'
+puts merkle_root_value
+# => '25fd59b79d70bbdf043d66a7b0fc01409d11b990e943bb46b840fbbddd5ab895'
+```
+
+
+### Transactions
+
+Use `MerkleTree.for` or `MerkleTree.compute_root_for` for passing along transactions.
+Will use `to_s` on every transaction and use the resulting "serialized" string
+to (auto-) calculate the (crypto) hash.
+
+Let's put the transactions from the (hyper) ledger book from [Tulips on the Blockchain!](https://github.com/openblockchains/tulips)
+on the ~~blockchain~~ merkle tree:
+
+
+| From                | To           | What                      | Qty |
+|---------------------|--------------|---------------------------|----:|
+| Bloom & Blossom (†) | Daisy        | Tulip Admiral of Admirals |   8 |
+| Vincent             | Max          | Tulip Bloemendaal Sunset  |   2 |
+| Anne                | Martijn      | Tulip Semper Augustus     |   2 |
+| Ruben               | Julia        | Tulip Admiral van Eijck   |   2 |
+
+(†): Grower Transaction - New Tulips on the Market!
+
+``` ruby
+merkle = MerkleTree.for(
+  { from: "Bloom & Blossom", to: "Daisy",   what: "Tulip Admiral of Admirals", qty: 8 },
+  { from: "Vincent",         to: "Max",     what: "Tulip Bloemendaal Sunset",  qty: 2 },
+  { from: "Anne",            to: "Martijn", what: "Tulip Semper Augustus",     qty: 2 },
+  { from: "Ruben",           to: "Julia",   what: "Tulip Admiral van Eijck",   qty: 2 } )
+
+puts 'merkle tree root hash:'
+puts merkle.root.value
+# => '703f44630117ef9b4ac20cb149ed8a0f06e4c3ed2a791e11e16a2fe7a7d0de3d'
+
+# -or-
+
+merkle_root_value = MerkleTree.compute_root_for(
+  { from: "Bloom & Blossom", to: "Daisy",   what: "Tulip Admiral of Admirals", qty: 8 },
+  { from: "Vincent",         to: "Max",     what: "Tulip Bloemendaal Sunset",  qty: 2 },
+  { from: "Anne",            to: "Martijn", what: "Tulip Semper Augustus",     qty: 2 },
+  { from: "Ruben",           to: "Julia",   what: "Tulip Admiral van Eijck",   qty: 2 } )
+
+puts 'merkle tree root hash:'
+puts merkle_root_value
+# => '703f44630117ef9b4ac20cb149ed8a0f06e4c3ed2a791e11e16a2fe7a7d0de3d'
+```
+
+
+## Install
+
+Just install the gem:
+
+```
+$ gem install merkletree
+```
 
 
 ## License

data/Rakefile

@@ -17,8 +17,8 @@ Hoe.spec 'merkletree' do
   self.readme_file  = 'README.md'
   self.history_file = 'HISTORY.md'
 
-  self.extra_deps = [
-  ]
+  ## self.extra_deps = [
+  ## ]
 
   self.licenses = ['Public Domain']
 

data/lib/merkletree.rb

@@ -3,10 +3,10 @@
 require 'digest'    # for hash checksum digest function SHA256
 require 'pp'        # for pp => pretty printer
 
-require 'date'
-require 'time'
-require 'json'
-require 'uri'
+## require 'date'
+## require 'time'
+## require 'json'
+## require 'uri'
 
 
 
@@ -14,6 +14,140 @@ require 'uri'
 require 'merkletree/version'    # note: let version always go first
 
 
+class MerkleTree
+
+  class Node
+    attr_reader :value
+    attr_reader :left
+    attr_reader :right
+
+    def initialize( value, left, right )
+       @value = value
+       @left  = left
+       @right = right
+    end
+  end # class Node
+
+
+  ## convenience helpers
+  def self.for( *args )
+     if args.size == 1 && args[0].is_a?( Array )
+        transactions = args[0]   ## "unwrap" array in array
+     else
+        transactions = args      ## use "auto-wrapped" splat array
+     end
+     ## for now use to_s for calculation hash
+     hashes = transactions.map { |tx| calc_hash( tx.to_s ) }
+     self.new( hashes )
+  end
+
+  def self.compute_root_for( *args )
+    if args.size == 1 && args[0].is_a?( Array )
+       transactions = args[0]   ## "unwrap" array in array
+    else
+       transactions = args      ## use "auto-wrapped" splat array
+    end
+
+    ## for now use to_s for calculation hash
+    hashes = transactions.map { |tx| calc_hash( tx.to_s ) }
+    self.compute_root( hashes )
+  end
+
+
+
+  attr_reader :root
+  attr_reader :leaves
+
+  def initialize( *args )
+    if args.size == 1 && args[0].is_a?( Array )
+       hashes = args[0]   ## "unwrap" array in array
+    else
+       hashes = args      ## use "auto-wrapped" splat array
+    end
+
+    @hashes = hashes
+    @root   = build_tree
+  end
+
+
+  def build_tree
+    level = @leaves = @hashes.map { |hash| Node.new( hash, nil, nil ) }
+
+    ## todo/fix: handle hashes.size == 0 case
+    ##   - throw exception - why? why not?
+    ##   -  return empty node with hash '0' - why? why not?
+
+    if @hashes.size == 1
+      level[0]
+    else
+      ## while there's more than one hash in the layer, keep looping...
+      while level.size > 1
+        ## loop through hashes two at a time
+        level = level.each_slice(2).map do |left, right|
+          ## note: handle special case
+          # if number of nodes is odd e.g. 3,5,7,etc.
+          #   last right node is nil  --  duplicate node value for hash
+          ##   todo/check - duplicate just hash? or add right node ref too - why? why not?
+          right = left   if right.nil?
+
+          Node.new( MerkleTree.calc_hash( left.value + right.value ), left, right)
+        end
+        ## debug output
+        ## puts "current merkle hash level (#{level.size} nodes):"
+        ## pp level
+      end
+      ### finally we end up with a single hash
+      level[0]
+    end
+  end  # method build tree
+
+
+
+  ### shortcut/convenience -  compute root hash w/o building tree nodes
+  def self.compute_root( *args )
+    if args.size == 1 && args[0].is_a?( Array )
+       hashes = args[0]   ## "unwrap" array in array
+    else
+       hashes = args      ## use "auto-wrapped" splat array
+    end
+
+    ## todo/fix: handle hashes.size == 0 case
+    ##   - throw exception - why? why not?
+    ##   -  return empty node with hash '0' - why? why not?
+
+    if hashes.size == 1
+      hashes[0]
+    else
+      ## while there's more than one hash in the list, keep looping...
+      while hashes.size > 1
+        # if number of hashes is odd e.g. 3,5,7,etc., duplicate last hash in list
+        hashes << hashes[-1]   if hashes.size % 2 != 0
+
+        ## loop through hashes two at a time
+        hashes = hashes.each_slice(2).map do |left,right|
+           ## join both hashes slice[0]+slice[1] together
+           hash = calc_hash( left + right )
+        end
+      end
+
+      ## debug output
+      ## puts "current merkle hashes (#{hashes.size}):"
+      ## pp hashes
+      ### finally we end up with a single hash
+      hashes[0]
+    end
+  end # method compute_root
+
+
+  def self.calc_hash( data )
+    sha = Digest::SHA256.new
+    sha.update( data )
+    sha.hexdigest
+  end
+
+
+end # class MerkleTree
+
 
 # say hello
 puts MerkleTree.banner    if defined?($RUBYLIBS_DEBUG) && $RUBYLIBS_DEBUG

data/lib/merkletree/version.rb

@@ -1,11 +1,12 @@
 # encoding: utf-8
 
 
-module MerkleTree
+class MerkleTree    ## note: use class (!) for now and NOT module
+
 
   MAJOR = 0
-  MINOR = 0
-  PATCH = 1
+  MINOR = 1
+  PATCH = 0
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 
   def self.version

data/test/helper.rb

@@ -0,0 +1,10 @@
+## $:.unshift(File.dirname(__FILE__))
+
+## minitest setup
+
+require 'minitest/autorun'
+
+
+## our own code
+
+require 'merkletree'

data/test/test_build.rb

@@ -0,0 +1,158 @@
+# encoding: utf-8
+
+###
+#  to run use
+#     ruby -I ./lib -I ./test test/test_build.rb
+
+
+require 'helper'
+
+
+class TestBuild < MiniTest::Test
+
+
+def test_example_4
+
+  hashes = [
+    '00',
+    '11',
+    '22',
+    '33',
+  ]
+
+  hash00   = '00'
+  hash11   = '11'
+  hash0011 = MerkleTree.calc_hash( hash00 + hash11 )
+
+  hash22   = '22'
+  hash33   = '33'
+  hash2233 = MerkleTree.calc_hash( hash22 + hash33 )
+
+  hash00112233 = MerkleTree.calc_hash( hash0011 + hash2233 )
+
+
+  merkle = MerkleTree.new( hashes )
+
+  puts "merkletree root hash:"
+  puts merkle.root.value
+
+  puts "merkletree:"
+  pp merkle.root
+
+  assert_equal hash00, merkle.root.left.left.value
+  assert_equal hash11, merkle.root.left.right.value
+  assert_equal hash22, merkle.root.right.left.value
+  assert_equal hash33, merkle.root.right.right.value
+
+  assert_equal hash0011, merkle.root.left.value
+  assert_equal hash2233, merkle.root.right.value
+
+  assert_equal hash00112233, merkle.root.value
+
+
+
+  merkle_root_value = MerkleTree.compute_root( hashes )
+  puts "merkletree root hash:"
+  puts merkle_root_value
+
+  assert_equal merkle.root.value, merkle_root_value
+end   # method test_example_4
+
+
+def test_example_3   ## test odd (not even hashes)
+
+  hashes = [
+    '00',
+    '11',
+    '22',
+  ]
+
+  hash00   = '00'
+  hash11   = '11'
+  hash0011 = MerkleTree.calc_hash( hash00 + hash11 )
+
+  hash22   = '22'
+  hash2222 = MerkleTree.calc_hash( hash22 + hash22 )
+
+  hash00112222 = MerkleTree.calc_hash( hash0011 + hash2222 )
+
+
+  merkle = MerkleTree.new( hashes )
+
+  puts "merkletree root hash:"
+  puts merkle.root.value
+
+  puts "merkletree:"
+  pp merkle.root
+
+  assert_equal hash00, merkle.root.left.left.value
+  assert_equal hash11, merkle.root.left.right.value
+  assert_equal hash22, merkle.root.right.left.value
+  assert_equal hash22, merkle.root.right.right.value
+
+  assert_equal hash0011, merkle.root.left.value
+  assert_equal hash2222, merkle.root.right.value
+
+  assert_equal hash00112222, merkle.root.value
+
+
+
+  merkle_root_value = MerkleTree.compute_root( hashes )
+  puts "merkletree root hash:"
+  puts merkle_root_value
+
+  assert_equal merkle.root.value, merkle_root_value
+end   # method test_example_3
+
+
+def test_example_5   ## test odd (not even hashes)
+
+  hashes = [
+    '0000',
+    '0011',
+    '0022',
+    '0033',
+    '0044',
+  ]
+
+  merkle = MerkleTree.new( hashes )
+
+  puts "merkletree root hash:"
+  puts merkle.root.value
+
+  puts "merkletree:"
+  pp merkle.root
+
+
+  merkle_root_value = MerkleTree.compute_root( hashes )
+  puts "merkletree root hash:"
+  puts merkle_root_value
+
+  assert_equal merkle.root.value, merkle_root_value
+end   # method test_example_5
+
+
+def test_tulips
+
+  merkle = MerkleTree.for(
+        { from: "Dutchgrown", to: "Vincent", what: "Tulip Bloemendaal Sunset", qty: 10 },
+        { from: "Keukenhof",  to: "Anne",    what: "Tulip Semper Augustus",    qty: 7  } )
+
+  puts "merkletree root hash:"
+  puts merkle.root.value
+
+  puts "merkletree:"
+  pp merkle.root
+
+  merkle_root_value = MerkleTree.compute_root_for(
+    { from: "Dutchgrown", to: "Vincent", what: "Tulip Bloemendaal Sunset", qty: 10 },
+    { from: "Keukenhof",  to: "Anne",    what: "Tulip Semper Augustus",    qty: 7  } )
+
+  puts "merkletree root hash:"
+  puts merkle_root_value
+
+  assert_equal merkle.root.value, merkle_root_value
+end  # method test_tulips
+
+
+end  # class TestBuild

data/test/test_readme.rb

@@ -0,0 +1,74 @@
+# encoding: utf-8
+
+###
+#  to run use
+#     ruby -I ./lib -I ./test test/test_readme.rb
+
+
+require 'helper'
+
+
+class TestReadme < MiniTest::Test
+
+
+def xxx_test_hashes
+
+  merkle1 = MerkleTree.new(
+    'eb8ecbf6d5870763ae246e37539d82e37052cb32f88bb8c59971f9978e437743',
+    'edbd4e11e69bc399a9ccd8faaea44fb27410fe8e3023bb9462450a0a9c4caa1b',
+    '5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d' )
+
+  # -or-
+
+  puts merkle1.root.value
+  pp merkle1
+
+  merkle2 = MerkleTree.new( [
+    'eb8ecbf6d5870763ae246e37539d82e37052cb32f88bb8c59971f9978e437743',
+    'edbd4e11e69bc399a9ccd8faaea44fb27410fe8e3023bb9462450a0a9c4caa1b',
+    '5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d' ])
+
+  pp merkle2
+  puts merkle2.root.value
+
+  assert_equal merkle1.root.value, merkle2.root.value
+
+
+  merkle_root_value = MerkleTree.compute_root(
+    'eb8ecbf6d5870763ae246e37539d82e37052cb32f88bb8c59971f9978e437743',
+    'edbd4e11e69bc399a9ccd8faaea44fb27410fe8e3023bb9462450a0a9c4caa1b',
+    '5ee2981606328abfe0c3b1171440f0df746c1e1f8b3b56c351727f7da7ae5d8d' )
+
+  puts merkle_root_value
+
+  assert_equal merkle1.root.value, merkle_root_value
+end # method test_hashes
+
+
+
+def test_transactions
+
+  merkle = MerkleTree.for(
+    { from: "Bloom & Blossom", to: "Daisy",   what: "Tulip Admiral of Admirals", qty: 8 },
+    { from: "Vincent",         to: "Max",     what: "Tulip Bloemendaal Sunset",  qty: 2 },
+    { from: "Anne",            to: "Martijn", what: "Tulip Semper Augustus",     qty: 2 },
+    { from: "Ruben",           to: "Julia",   what: "Tulip Admiral van Eijck",   qty: 2 } )
+
+  puts 'merkle tree root hash:'
+  puts merkle.root.value
+  pp merkle
+
+  merkle_root_value = MerkleTree.compute_root_for(
+    { from: "Bloom & Blossom", to: "Daisy",   what: "Tulip Admiral of Admirals", qty: 8 },
+    { from: "Vincent",         to: "Max",     what: "Tulip Bloemendaal Sunset",  qty: 2 },
+    { from: "Anne",            to: "Martijn", what: "Tulip Semper Augustus",     qty: 2 },
+    { from: "Ruben",           to: "Julia",   what: "Tulip Admiral van Eijck",   qty: 2 } )
+
+  puts 'merkle tree root hash:'
+  puts merkle_root_value
+
+  assert_equal merkle.root.value, merkle_root_value
+end  # method test_transactions
+
+
+end # class TestReadme

data/test/test_version.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+###
+#  to run use
+#     ruby -I ./lib -I ./test test/test_version.rb
+
+
+require 'helper'
+
+
+class TestVersion < MiniTest::Test
+
+def test_version
+   puts MerkleTree.version
+   puts MerkleTree.banner
+   puts MerkleTree.root
+
+   assert true  ## (for now) everything ok if we get here
+end
+
+end # class TestVersion

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: merkletree
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-18 00:00:00.000000000 Z
+date: 2017-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -56,6 +56,10 @@ files:
 - Rakefile
 - lib/merkletree.rb
 - lib/merkletree/version.rb
+- test/helper.rb
+- test/test_build.rb
+- test/test_readme.rb
+- test/test_version.rb
 homepage: https://github.com/openblockchains/merkletree.rb
 licenses:
 - Public Domain