diff options
| -rw-r--r-- | src/ht.erl | 36 |
1 files changed, 23 insertions, 13 deletions
@@ -17,11 +17,15 @@ -export([create/0, append/2, tree_hash/1, size/1, audit_path/2, consistency_proof/2]). +%%%%%%%%%%%%%%%%%%%% %% Public interface. + +%% @doc Return an empty tree. -spec create() -> head(). create() -> mkhead(0, undefined). +%% @doc Return the merkle tree hash of a tree. -spec tree_hash(head()) -> binary(); (tree()) -> binary(). tree_hash(#head{tree=T}) -> @@ -31,11 +35,12 @@ tree_hash(#head{tree=T}) -> #leaf{hash=H} -> H end. +%% @doc Return the size of a tree. -spec size(head()) -> non_neg_integer(). size(Head) -> tree_version(Head). -%% @doc Append Leaf to Head. +%% @doc Append a leaf to a tree. %% %% Walk down the tree in Head, stop at The Right Place and make Leaf %% the right sibling of that place. To find the right place, let d be @@ -49,7 +54,7 @@ size(Head) -> %% the way up instead of walking down the tree again. Worst case this %% is lg2(N) iterations, i.e. 24 steps for N=16e10. %% -%% Example: N=3 (011) => l=0, the rightmost leaf +%% Example: N=3 (011) => l=0, the rightmost leaf. %% Example: N=4 (100) => l=2, the root (soon not to be root). %% Example: N=5 (101) => l=0, the rightmost leaf. %% Example: N=6 (110) => l=1, the last and rightmost inner node. @@ -74,18 +79,21 @@ append(Dest, Newtree, 0) when is_record(Dest, inner) -> append(Dest, Newtree, Depth) when is_record(Dest, inner) -> mkinner(Dest#inner.child0, append(Dest#inner.child1, Newtree, Depth - 1)). -%% @doc Return an audit path, i.e a list of those hashes needed to -%% calculate the tree hash for Head given the knowledge of the nth -%% hash in the tree. Audit paths prove existance of a given leaf in a -%% given tree. +%% @doc Return an audit path. +%% +%% An audit path is a list of those hashes needed to calculate the +%% tree hash for Head given the knowledge of the nth hash in the +%% tree. Audit paths prove existance of a given leaf in a given tree. -spec audit_path(head(), non_neg_integer()) -> list(). audit_path(Head, N) -> [fixme, Head, N]. -%% @doc Return a consistency proof, i.e. the shortest list of nodes -%% required to verify that the tree built from the first n leaves of a -%% given tree is a subset of that tree. Consistency proofs prove the -%% append-only property of a tree. +%% @doc Return a consistency proof. +%% +%% A consistency proof is the shortest list of nodes required to +%% verify that the tree built from the first n leaves of a given tree +%% is a subset of that tree. Consistency proofs prove the append-only +%% property of a tree. -spec consistency_proof(head(), non_neg_integer()) -> list(). consistency_proof(Head, N) -> [fixme, Head, N]. @@ -93,9 +101,11 @@ consistency_proof(Head, N) -> %%%%%%%%%%%%%%%%%%%% %% Private functions. -%% @doc Tree version number, i.e. number of leafs in tree. Note that -%% this is set off by one (one higher) compared with the history tree -%% version as explained by Crosby and Wallach. +%% @doc Return version number of a tree. +%% +%% The version number is the number of leafs in tree. Note that this +%% is set off by one (higher) compared to the history tree version as +%% explained by Crosby and Wallach. -spec tree_version(head()) -> non_neg_integer(). tree_version(#head{version=Ver}) -> Ver. |