yosriady / merkle_tree

:evergreen_tree: Merkle Tree implementation in pure Elixir

MerkleTree

Merkle Tree implementation in pure Elixir.

Hex (Package Manager)

API Documentation

Installation

• Install the Elixir functional language.

• Create New Project with Mix

  mix new my_app; cd my_app

• Add merkle_tree to your list of dependencies in mix.exs.

  def deps do
    [{:merkle_tree, "~> 1.6.0"}]
  end

• Install Mix Dependencies

  mix deps.get

Usage

• Run Interactive Elixir (IEx) within context of Elixir app and dependencies injected into IEx runtime

  iex -S mix

• Try the MerkleTree Module

  iex> MerkleTree.__info__(:functions)
  [__struct__: 0, __struct__: 1, build: 2, new: 1, new: 2]
  iex> mt = MerkleTree.new ['a', 'b', 'c', 'd']
  %MerkleTree{blocks: ['a', 'b', 'c', 'd'], hash_function: &MerkleTree.Crypto.sha256/1,
        root: %MerkleTree.Node{children: [%MerkleTree.Node{children: [%MerkleTree.Node{children: [],
            value: "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb"},
            %MerkleTree.Node{children: [], value: "3e23e8160039594a33894f6564e1b1348bbd7a0088d42c4acb73eeaed59c009d"}],
          value: "62af5c3cb8da3e4f25061e829ebeea5c7513c54949115b1acc225930a90154da"},
          %MerkleTree.Node{children: [%MerkleTree.Node{children: [], value: "2e7d2c03a9507ae265ecf5b5356885a53393a2029d241394997265a1a25aefc6"},
            %MerkleTree.Node{children: [], value: "18ac3e7343f016890c510e93f935261169d9e3f565436429830faf0934f4f8e4"}],
          value: "d3a0f1c792ccf7f1708d5422696263e35755a86917ea76ef9242bd4a8cf4891a"}],
        value: "58c89d709329eb37285837b042ab6ff72c7c8f74de0446b091b6a0131c102cfd"}}
  $ mt.blocks()
  ['a', 'b', 'c', 'd']
  $ mt.hash_function()
  &MerkleTree.Crypto.sha256/1
  $ mt.root()
  ...

• Try the MerkleTree.Proof Module (requires merkle_tree >1.2.0)

  iex> MerkleTree.Proof.__info__(:functions)           
  [__struct__: 0, __struct__: 1, prove: 2, proven?: 3]
  iex> proof1 = MerkleTree.Proof.prove(mt, 1)
  iex> proven1 = MerkleTree.Proof.proven?({"b", 1}, "58c89d709329eb37285837b042ab6ff72c7c8f74de0446b091b6a0131c102cfd", proof1)
  true
  
  iex> proof3 = MerkleTree.Proof.prove(mt, 3)                                              %MerkleTree.Proof{          
    hash_function: &MerkleTree.Crypto.sha256/1,
    hashes: ["62af5c3cb8da3e4f25061e829ebeea5c7513c54949115b1acc225930a90154da",
    "2e7d2c03a9507ae265ecf5b5356885a53393a2029d241394997265a1a25aefc6"]
  }
  iex> proven3 = MerkleTree.Proof.proven?({"d", 3}, "58c89d709329eb37285837b042ab6ff72c7c8f74de0446b091b6a0131c102cfd", proof3)
  true

• Try the MerkleTree.Crypto Module

  iex> MerkleTree.Crypto.__info__(:functions)
  [hash: 2, sha256: 1]
  iex> MerkleTree.Crypto.hash("tendermint", :sha256)
  "f6c3848fc2ab9188dd2c563828019be7cee4e269f5438c19f5173f79898e9ee6"
  iex> MerkleTree.Crypto.hash("tendermint", :md5)   
  "bc93700bdf1d47ad28654ad93611941f"
  iex> MerkleTree.Crypto.sha256("tendermint")    
  "f6c3848fc2ab9188dd2c563828019be7cee4e269f5438c19f5173f79898e9ee6"

Background

A hash tree or Merkle tree is a tree in which every non-leaf node is labelled with the hash of the labels or values (in case of leaves) of its child nodes. Hash trees are useful because they allow efficient and secure verification of the contents of large data structures. Hash trees are a generalization of hash lists and hash chains.

Hash trees can be used to verify any kind of data stored, handled and transferred in and between computers. Currently the main use of hash trees is to make sure that data blocks received from other peers in a peer-to-peer network are received undamaged and unaltered, and even to check that the other peers do not lie and send fake blocks. Suggestions have been made to use hash trees in trusted computing systems. Hash trees are used in the IPFS and ZFS file systems, BitTorrent protocol, Apache Wave protocol, Git distributed revision control system, the Bitcoin peer-to-peer network, the Ethereum peer-to-peer network, and a number of NoSQL systems like Apache Cassandra and Riak.

Running Type Checker

mix dialyzer

Contributing

1. Fork it ( http://github.com/Leventhan/merkle_tree/fork )
2. Create your feature branch (git checkout -b feature/my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/my-new-feature)
5. Create a new Pull Request (Remember to squash your commits!)

Kindly report any found bugs or errors using the issue tracker.

Thanks

merkle_tree © 2016+, Yos Riady. Released under the MIT License.
Authored and maintained by Yos Riady with help from contributors (list).

yos.io  ·  GitHub @yosriady

merkle_tree's Issues

Support for k-ary tries

Number of children suggest that we could build k-ary tries (k > 2). However proofs can only work for the binary tries (2 children)

Do you think it makes sense to support k-ary merkle tries. Otherwise we can simplify the code :)

BTW: proof support for k-ary tries should be fun to implement 🤓

Getting and verifying Merkle proofs

TODO

MerkleTree Proof prove results in UndefinedFunctionError

The following steps have been followed, but result in the error, as shown:

• Added the library as a Mix dependency

  defp deps do
    [
      {:merkle_tree, "~> 1.1.1", only: [:dev, :test, :prod]}
    ]
  end

• Fetched the dependency

mix deps.get

• Run Interactively Elixir (REPL) within context of Elixir App and dependencies into IEx runtime

iex -S mix

• Used the Merkle Tree successfully
  • API Docs Reference: https://hexdocs.pm/merkle_tree/MerkleTree.html#new/2

$ MerkleTree.__info__(:functions)                                                              
[__struct__: 0, __struct__: 1, build: 2, new: 1, new: 2]
$ f = MerkleTree.new(['a', 'b', 'c', 'd'], &MerkleTree.Crypto.sha256/1)
%MerkleTree{
  blocks: ['a', 'b', 'c', 'd'],
  hash_function: &MerkleTree.Crypto.sha256/1,
  root: %MerkleTree.Node{
    children: [
...
    ],
    value: "58c89d709329eb37285837b042ab6ff72c7c8f74de0446b091b6a0131c102cfd"
  }
}
$ f.blocks()
['a', 'b', 'c', 'd'] 
$ f.hash_function()
&MerkleTree.Crypto.sha256/1
$ f.root()
...
$ f.t()
** (KeyError) key :t not found in: %MerkleTree{blocks: ['a', 'b', 'c', 'd'], hash_function: &MerkleTree.Crypto.sha256/1, root: %MerkleTree.Node{children: [%MerkleTree.Node{children: [%MerkleTree.Node{children: [], value: "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb"}, %MerkleTree.Node{children: [], value: "3e23e8160039594a33894f6564e1b1348bbd7a0088d42c4acb73eeaed59c009d"}], value: "62af5c3cb8da3e4f25061e829ebeea5c7513c54949115b1acc225930a90154da"}, %MerkleTree.Node{children: [%MerkleTree.Node{children: [], value: "2e7d2c03a9507ae265ecf5b5356885a53393a2029d241394997265a1a25aefc6"}, %MerkleTree.Node{children: [], value: "18ac3e7343f016890c510e93f935261169d9e3f565436429830faf0934f4f8e4"}], value: "d3a0f1c792ccf7f1708d5422696263e35755a86917ea76ef9242bd4a8cf4891a"}], value: "58c89d709329eb37285837b042ab6ff72c7c8f74de0446b091b6a0131c102cfd"}}

• Tried to use the Merkle Proof unsuccessfully - https://hexdocs.pm/merkle_tree/MerkleTree.Proof.html

Interactive Elixir (1.6.0) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> proof = MerkleTree.new(~w/a b c d/) |>
...(1)> MerkleTree.Proof.prove(1)
** (UndefinedFunctionError) function MerkleTree.Proof.prove/2 is undefined (module MerkleTree.Proof is not available)
    MerkleTree.Proof.prove(%MerkleTree{blocks: ["a", "b", "c", "d"], hash_function: &MerkleTree.Crypto.sha256/1, root: %MerkleTree.Node{children: [%MerkleTree.Node{children: [%MerkleTree.Node{children: [], height: 0, value: "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb"}, %MerkleTree.Node{children: [], height: 0, value: "3e23e8160039594a33894f6564e1b1348bbd7a0088d42c4acb73eeaed59c009d"}], height: 1, value: "62af5c3cb8da3e4f25061e829ebeea5c7513c54949115b1acc225930a90154da"}, %MerkleTree.Node{children: [%MerkleTree.Node{children: [], height: 0, value: "2e7d2c03a9507ae265ecf5b5356885a53393a2029d241394997265a1a25aefc6"}, %MerkleTree.Node{children: [], height: 0, value: "18ac3e7343f016890c510e93f935261169d9e3f565436429830faf0934f4f8e4"}], height: 1, value: "d3a0f1c792ccf7f1708d5422696263e35755a86917ea76ef9242bd4a8cf4891a"}], height: 2, value: "58c89d709329eb37285837b042ab6ff72c7c8f74de0446b091b6a0131c102cfd"}}, 1)

• My System:
  • macOS Sierra 10.12.6
  • Elixir and Erlang versions:

$ elixir --version
Erlang/OTP 20 [erts-9.2] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:10] [hipe] [kernel-poll:false] [dtrace]

Elixir 1.6.0 (compiled with OTP 20)

Visualization with GraphViz

I think it'd be interesting to be able to visualize and render the trees as an image using graphviz.

Noted here as a reminder.