| docs/spec.mdView |
|---|
| 1 | | -This is a simple Binary [Radix Tree](https://ipfs.io/ipns/QmdJiuMWp2FxyaerfLrtdLF6Nr1EWpL7dPAxA9oKSPYYgV/wiki/Radix_tree.html). |
| 2 | | -The default encodeing used is [cbor](http://cbor.io/) and the default hashing |
| 3 | | -algorithim used is sha2-256. |
| 1 … | +This is a simple Merkle Binary [Radix Tree](https://ipfs.io/ipns/QmdJiuMWp2FxyaerfLrtdLF6Nr1EWpL7dPAxA9oKSPYYgV/wiki/Radix_tree.html). |
| 4 | 2 … | |
| 5 | 3 … | |
| 6 | 4 … | ## Node |
| 7 | | -Each node is an variable length array containing at the most four elements |
| 8 | | -"left branch", "right branch" "extension", "value" |
| 5 … | +Each node contains at the most four elements |
| 6 … | +"extension", "left branch", "right branch" and "value". |
| 9 | 7 … | |
| 10 | 8 … | ``` |
| 11 | | -node : = [LBRANCH, RBRANCH, EXTENSION, VALUE] |
| 9 … | +node : = EXTENSION | LBRANCH | RBRANCH | VALUE |
| 12 | 10 … | ``` |
| 13 | 11 … | |
| 14 | | -If no value exists at a given node the array is truncated to |
| 12 … | +A prefix byte is used a bit field to signify which elements a node contains. |
| 13 … | +The bit field is defined a the following. The first nibble is reserved for |
| 14 … | +merkle proofs. |
| 15 | 15 … | |
| 16 | 16 … | ``` |
| 17 | | -node : = [LBRANCH, RBRANCH, EXTENSION] |
| 17 … | +PREFIX := reserved | reserved | reserved | reserved | EXTENSION | LBRANCH | RBRANCH | VALUE |
| 18 | 18 … | ``` |
| 19 | 19 … | |
| 20 | | -If no value and no extension exists at a given node the array is truncated to |
| 20 … | +For example a node that contained a left branch and a value would have a prefix byte |
| 21 … | +of 00000101 or 0x07 |
| 21 | 22 … | |
| 22 | | -``` |
| 23 | | -node : = [LBRANCH, RBRANCH] |
| 24 | | -``` |
| 23 … | +The full encoded node would then look something like. `0x07<20_bytes_for_lbranch><remaing_bytes_for_value>` |
| 25 | 24 … | |
| 26 | | -All empty values in the array are encoded as "null". |
| 27 | | -An emty tree is defined as `[null, null]` |
| 28 | 25 … | |
| 29 | 26 … | ## Branches |
| 30 | 27 … | |
| 31 | | -Each link points to the next node in the tree. |
| 28 … | +The branch elements point to the next node in the tree using a merkle link. |
| 29 … | +A merkle link is defined by the first 20 bytes of the result SHA2-256 of an encoded node. |
| 30 … | + |
| 31 … | + |
| 32 | 32 … | ``` |
| 33 | 33 … | branch : = <merkle link> |
| 34 | 34 … | ``` |
| 35 | | -Where the link is a [CID](https://github.com/ipld/cid) is encoded as a byte string. |
| 36 | | -Using CIDs allow for the flexablity to update the hashing algorithim and encoding |
| 37 | | -at a later date while being backwards compatiable. |
| 38 | 35 … | |
| 36 … | +``` |
| 37 … | +link := SHA2(encoded_node)[0..20] |
| 38 … | +``` |
| 39 … | + |
| 40 … | + |
| 39 | 41 … | ## Extensions |
| 40 | 42 … | Extensions encode shared paths. Extensions are defined as |
| 43 … | + |
| 41 | 44 … | ``` |
| 42 | | -extension := [length, extension] |
| 45 … | +extension := length | extension |
| 43 | 46 … | |
| 44 | 47 … | ``` |
| 45 | | -Where the length is an interger and the extension is a byte string padded with |
| 46 | | -0's |
| 48 … | +Where the length is the number of bits that extension repesents. This varuint32 |
| 49 … | +encoded with a leb128. And the extension is bit array padded with 0's to the nearst byte. |
| 47 | 50 … | |
| 48 | 51 … | For example if the binary keys [0, 0, 1, 1] and |
| 49 | | -[0, 0, 1, 0] have a shared path of [0, 0]. If they where the only two values in |
| 50 | | -the tree the root node would have an extension of [0, 0] |
| 52 … | +[0, 0, 1, 0] have a shared path of [0, 0, 1]. The extension node would therefor be |
| 51 | 53 … | |
| 54 … | +`0x03, 0x04` |
| 55 … | + |
| 56 … | +where 3 is the the shared path length and the `0x04` is the shared path encoded |
| 57 … | +as a little endian byte array. |
| 58 … | + |
| 59 … | +# Examples |
| 60 … | + |
| 61 … | +An empty tree is hash a merkle link of sha256(0x00) or `6e340b9cffb37a989ca544e6bb780a2c78901d3f` |
| 62 … | + |
| 63 … | + |
| 64 … | +A tree with a single key 'binary' and value of 'tree' is encoded as |
| 65 … | + |
| 52 | 66 … | ``` |
| 53 | | -root := [null, <link>, [2, 0x00]] |
| 67 … | +0x093062696e61727974726565 |
| 68 … | + |
| 69 … | +0x09 this node has an extention and value |
| 70 … | +0x30 the extention has a length of 48 bits or 6 bytes |
| 71 … | +0x62696e617279 the key 'binary' |
| 72 … | +0x4726565 the value 'tree' |
| 54 | 73 … | ``` |
| 55 | 74 … | |
| 75 … | +If an other key "bin" with the value "number" is add the tree will have two nodes |
| 56 | 76 … | |
| 77 … | +The root node will be |
| 78 … | +`0x0b1862696eaf39aa98eb0350611f230cbeb2e68dbe95ab5ecc6e756d626572` |
| 79 … | + |
| 80 … | +0xb this node has an extention, a right branch and a value |
| 81 … | +0x18 this the extention has a length of 24 bits |
| 82 … | +0x62696e the value extention "bin" |
| 83 … | +0xaf39aa98eb0350611f230cbeb2e68dbe95ab5ecc a merkle link to another node |
| 84 … | +0x6e756d626572 the value "number" |
| 85 … | + |
| 86 … | +the link 0xaf39aa98eb0350611f230cbeb2e68dbe95ab5ecc points to the node |
| 87 … | + |
| 88 … | +0x091730b93c74726565 |
| 89 … | + |
| 90 … | +0x09 this node has an extention and value |
| 91 … | +0x17 this the extention has a length of 23 bits |
| 92 … | +0x30b93c the extention 'ary' = 0x617279 that is shift left one bit. 'a' is 0x61 which |
| 93 … | +is read 100001100 (little endian) The was first bit is was used to choose the branch (right) |
| 94 … | +turns into 0x30 (110000) |