aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorpukkamustard <pukkamustard@posteo.net>2020-10-21 09:07:31 +0200
committerpukkamustard <pukkamustard@posteo.net>2020-10-21 09:07:31 +0200
commit0cdc5ad553128cb9dd7a403de5fc28e8e931f1fd (patch)
tree689fe7d2f6ce5e2a05f4956c9f991211f97807e7 /doc
parent2d05cf02bb136c742020e8c50d3717a8fb40a67f (diff)
scribble, scribble, scribble...
Diffstat (limited to 'doc')
-rw-r--r--doc/diagrams.org119
-rw-r--r--doc/eris-merkle-tree.svg417
-rw-r--r--doc/eris.adoc178
3 files changed, 714 insertions, 0 deletions
diff --git a/doc/diagrams.org b/doc/diagrams.org
new file mode 100644
index 0000000..4d372ac
--- /dev/null
+++ b/doc/diagrams.org
@@ -0,0 +1,119 @@
+#+TITLE: Diagrams
+#+PROPERTY: header-args:dot :cmdline -Nfontname=sans-serif -Tsvg :eval never-export :exports results
+
+* Merkle Tree
+
+#+BEGIN_SRC dot :file eris-merkle-tree.svg :exports results
+digraph {
+ node [shape=record] ;
+
+
+ subgraph cluster__level_0 {
+ style=dotted;
+ label="level 0 (input content)";
+ labeljust="l";
+
+ block_7 [shape=box,color=lightblue,style=filled,label="block-7"];
+ block_6 [shape=box,color=lightblue,style=filled,label="block-6"];
+ block_5 [shape=box,color=lightblue,style=filled,label="block-5"];
+ block_4 [shape=box,color=lightblue,style=filled,label="block-4"];
+ block_3 [shape=box,color=lightblue,style=filled,label="block-3"];
+ block_2 [shape=box,color=lightblue,style=filled,label="block-2"];
+ block_1 [shape=box,color=lightblue,style=filled,label="block-1"];
+ block_0 [shape=box,color=lightblue,style=filled,label="block-0"];
+
+ rk_0_7 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_0_6 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_0_5 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_0_4 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_0_3 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_0_2 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_0_1 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_0_0 [shape=record, color=yellow, style=filled, label="r | k"];
+ };
+
+ rk_0_0 -> block_0;
+ rk_0_1 -> block_1;
+ rk_0_2 -> block_2;
+ rk_0_3 -> block_3;
+ rk_0_4 -> block_4;
+ rk_0_5 -> block_5;
+ rk_0_6 -> block_6;
+ rk_0_7 -> block_7;
+
+ subgraph cluster__level_1 {
+ style=dotted;
+ label="level 1";
+ labeljust="l";
+
+ node_1_0 [shape=record, color=lightblue, style=filled, label="node"];
+ node_1_1 [shape=record, color=lightblue, style=filled, label="node"];
+ node_1_2 [shape=record, color=lightblue, style=filled, label="node"];
+ node_1_3 [shape=record, color=lightblue, style=filled, label="node"];
+
+ rk_1_3 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_1_2 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_1_1 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_1_0 [shape=record, color=yellow, style=filled, label="r | k"];
+
+ };
+
+ node_1_0 -> rk_0_0;
+ node_1_0 -> rk_0_1;
+
+ node_1_1 -> rk_0_2;
+ node_1_1 -> rk_0_3;
+
+ node_1_2 -> rk_0_4;
+ node_1_2 -> rk_0_5;
+
+ node_1_3 -> rk_0_6;
+ node_1_3 -> rk_0_7;
+
+ rk_1_0 -> node_1_0;
+ rk_1_1 -> node_1_1;
+ rk_1_2 -> node_1_2;
+ rk_1_3 -> node_1_3;
+
+ subgraph cluster__level_2 {
+ style=dotted;
+ label="level 2";
+ labeljust="l";
+
+ node_2_1 [shape=record, color=lightblue, style=filled, label="node"];
+ node_2_0 [shape=record, color=lightblue, style=filled, label="node"];
+
+ rk_2_1 [shape=record, color=yellow, style=filled, label="r | k"];
+ rk_2_0 [shape=record, color=yellow, style=filled, label="r | k"];
+
+ };
+
+ node_2_0 -> rk_1_0;
+ node_2_0 -> rk_1_1;
+
+ node_2_1 -> rk_1_2;
+ node_2_1 -> rk_1_3;
+
+ rk_2_0 -> node_2_0;
+ rk_2_1 -> node_2_1;
+
+ subgraph cluster__level_3 {
+ style=dotted;
+ label="level 3";
+ labeljust="l";
+
+ node_3_0 [shape=record, color=lightblue, style=filled, label="node"];
+
+ rk_3_0 [shape=record, color=yellow, style=filled, label="r | k"];
+
+ };
+
+ node_3_0 -> rk_2_1;
+ node_3_0 -> rk_2_0;
+
+ rk_3_0 -> node_3_0;
+}
+#+END_SRC
+
+#+RESULTS:
+[[file:eris-merkle-tree.svg]]
diff --git a/doc/eris-merkle-tree.svg b/doc/eris-merkle-tree.svg
new file mode 100644
index 0000000..3133632
--- /dev/null
+++ b/doc/eris-merkle-tree.svg
@@ -0,0 +1,417 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.42.3 (20191010.1750)
+ -->
+<!-- Title: %3 Pages: 1 -->
+<svg width="710pt" height="643pt"
+ viewBox="0.00 0.00 710.00 643.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 639)">
+<title>%3</title>
+<polygon fill="white" stroke="transparent" points="-4,4 -4,-639 706,-639 706,4 -4,4"/>
+<g id="clust1" class="cluster">
+<title>cluster__level_0</title>
+<polygon fill="none" stroke="black" stroke-dasharray="1,5" points="8,-8 8,-156 694,-156 694,-8 8,-8"/>
+<text text-anchor="middle" x="95.5" y="-140.8" font-family="Times,serif" font-size="14.00">level 0 (input content)</text>
+</g>
+<g id="clust2" class="cluster">
+<title>cluster__level_1</title>
+<polygon fill="none" stroke="black" stroke-dasharray="1,5" points="207,-164 207,-313 493,-313 493,-164 207,-164"/>
+<text text-anchor="middle" x="239" y="-297.8" font-family="Times,serif" font-size="14.00">level 1</text>
+</g>
+<g id="clust3" class="cluster">
+<title>cluster__level_2</title>
+<polygon fill="none" stroke="black" stroke-dasharray="1,5" points="279,-321 279,-470 421,-470 421,-321 279,-321"/>
+<text text-anchor="middle" x="311" y="-454.8" font-family="Times,serif" font-size="14.00">level 2</text>
+</g>
+<g id="clust4" class="cluster">
+<title>cluster__level_3</title>
+<polygon fill="none" stroke="black" stroke-dasharray="1,5" points="315,-478 315,-627 385,-627 385,-478 315,-478"/>
+<text text-anchor="middle" x="347" y="-611.8" font-family="Times,serif" font-size="14.00">level 3</text>
+</g>
+<!-- block_7 -->
+<g id="node1" class="node">
+<title>block_7</title>
+<polygon fill="lightblue" stroke="lightblue" points="686,-52 618,-52 618,-16 686,-16 686,-52"/>
+<text text-anchor="middle" x="652" y="-30.3" font-family="sans-serif" font-size="14.00">block&#45;7</text>
+</g>
+<!-- block_6 -->
+<g id="node2" class="node">
+<title>block_6</title>
+<polygon fill="lightblue" stroke="lightblue" points="600,-52 532,-52 532,-16 600,-16 600,-52"/>
+<text text-anchor="middle" x="566" y="-30.3" font-family="sans-serif" font-size="14.00">block&#45;6</text>
+</g>
+<!-- block_5 -->
+<g id="node3" class="node">
+<title>block_5</title>
+<polygon fill="lightblue" stroke="lightblue" points="514,-52 446,-52 446,-16 514,-16 514,-52"/>
+<text text-anchor="middle" x="480" y="-30.3" font-family="sans-serif" font-size="14.00">block&#45;5</text>
+</g>
+<!-- block_4 -->
+<g id="node4" class="node">
+<title>block_4</title>
+<polygon fill="lightblue" stroke="lightblue" points="428,-52 360,-52 360,-16 428,-16 428,-52"/>
+<text text-anchor="middle" x="394" y="-30.3" font-family="sans-serif" font-size="14.00">block&#45;4</text>
+</g>
+<!-- block_3 -->
+<g id="node5" class="node">
+<title>block_3</title>
+<polygon fill="lightblue" stroke="lightblue" points="342,-52 274,-52 274,-16 342,-16 342,-52"/>
+<text text-anchor="middle" x="308" y="-30.3" font-family="sans-serif" font-size="14.00">block&#45;3</text>
+</g>
+<!-- block_2 -->
+<g id="node6" class="node">
+<title>block_2</title>
+<polygon fill="lightblue" stroke="lightblue" points="256,-52 188,-52 188,-16 256,-16 256,-52"/>
+<text text-anchor="middle" x="222" y="-30.3" font-family="sans-serif" font-size="14.00">block&#45;2</text>
+</g>
+<!-- block_1 -->
+<g id="node7" class="node">
+<title>block_1</title>
+<polygon fill="lightblue" stroke="lightblue" points="170,-52 102,-52 102,-16 170,-16 170,-52"/>
+<text text-anchor="middle" x="136" y="-30.3" font-family="sans-serif" font-size="14.00">block&#45;1</text>
+</g>
+<!-- block_0 -->
+<g id="node8" class="node">
+<title>block_0</title>
+<polygon fill="lightblue" stroke="lightblue" points="84,-52 16,-52 16,-16 84,-16 84,-52"/>
+<text text-anchor="middle" x="50" y="-30.3" font-family="sans-serif" font-size="14.00">block&#45;0</text>
+</g>
+<!-- rk_0_7 -->
+<g id="node9" class="node">
+<title>rk_0_7</title>
+<polygon fill="yellow" stroke="yellow" points="614,-88.5 614,-124.5 668,-124.5 668,-88.5 614,-88.5"/>
+<text text-anchor="middle" x="627" y="-102.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="640,-88.5 640,-124.5 "/>
+<text text-anchor="middle" x="654" y="-102.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_0_7&#45;&gt;block_7 -->
+<g id="edge8" class="edge">
+<title>rk_0_7&#45;&gt;block_7</title>
+<path fill="none" stroke="black" d="M643.66,-88.43C644.87,-80.67 646.34,-71.28 647.7,-62.56"/>
+<polygon fill="black" stroke="black" points="651.2,-62.82 649.29,-52.4 644.29,-61.74 651.2,-62.82"/>
+</g>
+<!-- rk_0_6 -->
+<g id="node10" class="node">
+<title>rk_0_6</title>
+<polygon fill="yellow" stroke="yellow" points="529,-88.5 529,-124.5 583,-124.5 583,-88.5 529,-88.5"/>
+<text text-anchor="middle" x="542" y="-102.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="555,-88.5 555,-124.5 "/>
+<text text-anchor="middle" x="569" y="-102.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_0_6&#45;&gt;block_6 -->
+<g id="edge7" class="edge">
+<title>rk_0_6&#45;&gt;block_6</title>
+<path fill="none" stroke="black" d="M558.42,-88.43C559.52,-80.67 560.85,-71.28 562.09,-62.56"/>
+<polygon fill="black" stroke="black" points="565.59,-62.79 563.53,-52.4 558.66,-61.81 565.59,-62.79"/>
+</g>
+<!-- rk_0_5 -->
+<g id="node11" class="node">
+<title>rk_0_5</title>
+<polygon fill="yellow" stroke="yellow" points="445,-88.5 445,-124.5 499,-124.5 499,-88.5 445,-88.5"/>
+<text text-anchor="middle" x="458" y="-102.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="471,-88.5 471,-124.5 "/>
+<text text-anchor="middle" x="485" y="-102.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_0_5&#45;&gt;block_5 -->
+<g id="edge6" class="edge">
+<title>rk_0_5&#45;&gt;block_5</title>
+<path fill="none" stroke="black" d="M473.94,-88.43C474.82,-80.67 475.88,-71.28 476.87,-62.56"/>
+<polygon fill="black" stroke="black" points="480.38,-62.73 478.03,-52.4 473.42,-61.94 480.38,-62.73"/>
+</g>
+<!-- rk_0_4 -->
+<g id="node12" class="node">
+<title>rk_0_4</title>
+<polygon fill="yellow" stroke="yellow" points="363,-88.5 363,-124.5 417,-124.5 417,-88.5 363,-88.5"/>
+<text text-anchor="middle" x="376" y="-102.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="389,-88.5 389,-124.5 "/>
+<text text-anchor="middle" x="403" y="-102.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_0_4&#45;&gt;block_4 -->
+<g id="edge5" class="edge">
+<title>rk_0_4&#45;&gt;block_4</title>
+<path fill="none" stroke="black" d="M390.97,-88.43C391.41,-80.67 391.94,-71.28 392.44,-62.56"/>
+<polygon fill="black" stroke="black" points="395.94,-62.58 393.01,-52.4 388.95,-62.18 395.94,-62.58"/>
+</g>
+<!-- rk_0_3 -->
+<g id="node13" class="node">
+<title>rk_0_3</title>
+<polygon fill="yellow" stroke="yellow" points="284,-88.5 284,-124.5 338,-124.5 338,-88.5 284,-88.5"/>
+<text text-anchor="middle" x="297" y="-102.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="310,-88.5 310,-124.5 "/>
+<text text-anchor="middle" x="324" y="-102.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_0_3&#45;&gt;block_3 -->
+<g id="edge4" class="edge">
+<title>rk_0_3&#45;&gt;block_3</title>
+<path fill="none" stroke="black" d="M310.27,-88.43C309.94,-80.67 309.54,-71.28 309.17,-62.56"/>
+<polygon fill="black" stroke="black" points="312.66,-62.24 308.74,-52.4 305.67,-62.54 312.66,-62.24"/>
+</g>
+<!-- rk_0_2 -->
+<g id="node14" class="node">
+<title>rk_0_2</title>
+<polygon fill="yellow" stroke="yellow" points="203,-88.5 203,-124.5 257,-124.5 257,-88.5 203,-88.5"/>
+<text text-anchor="middle" x="216" y="-102.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="229,-88.5 229,-124.5 "/>
+<text text-anchor="middle" x="243" y="-102.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_0_2&#45;&gt;block_2 -->
+<g id="edge3" class="edge">
+<title>rk_0_2&#45;&gt;block_2</title>
+<path fill="none" stroke="black" d="M228.06,-88.43C227.18,-80.67 226.12,-71.28 225.13,-62.56"/>
+<polygon fill="black" stroke="black" points="228.58,-61.94 223.97,-52.4 221.62,-62.73 228.58,-61.94"/>
+</g>
+<!-- rk_0_1 -->
+<g id="node15" class="node">
+<title>rk_0_1</title>
+<polygon fill="yellow" stroke="yellow" points="120,-88.5 120,-124.5 174,-124.5 174,-88.5 120,-88.5"/>
+<text text-anchor="middle" x="133" y="-102.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="146,-88.5 146,-124.5 "/>
+<text text-anchor="middle" x="160" y="-102.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_0_1&#45;&gt;block_1 -->
+<g id="edge2" class="edge">
+<title>rk_0_1&#45;&gt;block_1</title>
+<path fill="none" stroke="black" d="M144.34,-88.43C143.13,-80.67 141.66,-71.28 140.3,-62.56"/>
+<polygon fill="black" stroke="black" points="143.71,-61.74 138.71,-52.4 136.8,-62.82 143.71,-61.74"/>
+</g>
+<!-- rk_0_0 -->
+<g id="node16" class="node">
+<title>rk_0_0</title>
+<polygon fill="yellow" stroke="yellow" points="30,-88.5 30,-124.5 84,-124.5 84,-88.5 30,-88.5"/>
+<text text-anchor="middle" x="43" y="-102.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="56,-88.5 56,-124.5 "/>
+<text text-anchor="middle" x="70" y="-102.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_0_0&#45;&gt;block_0 -->
+<g id="edge1" class="edge">
+<title>rk_0_0&#45;&gt;block_0</title>
+<path fill="none" stroke="black" d="M55.31,-88.43C54.53,-80.67 53.6,-71.28 52.74,-62.56"/>
+<polygon fill="black" stroke="black" points="56.2,-62 51.73,-52.4 49.23,-62.7 56.2,-62"/>
+</g>
+<!-- node_1_0 -->
+<g id="node17" class="node">
+<title>node_1_0</title>
+<polygon fill="lightblue" stroke="lightblue" points="215,-172.5 215,-208.5 269,-208.5 269,-172.5 215,-172.5"/>
+<text text-anchor="middle" x="242" y="-186.8" font-family="sans-serif" font-size="14.00">node</text>
+</g>
+<!-- node_1_0&#45;&gt;rk_0_1 -->
+<g id="edge10" class="edge">
+<title>node_1_0&#45;&gt;rk_0_1</title>
+<path fill="none" stroke="black" d="M215.66,-172.47C208.43,-167.44 200.73,-161.73 194,-156 185.56,-148.82 176.95,-140.33 169.44,-132.48"/>
+<polygon fill="black" stroke="black" points="171.74,-129.81 162.35,-124.91 166.63,-134.6 171.74,-129.81"/>
+</g>
+<!-- node_1_0&#45;&gt;rk_0_0 -->
+<g id="edge9" class="edge">
+<title>node_1_0&#45;&gt;rk_0_0</title>
+<path fill="none" stroke="black" d="M214.78,-186.41C187.28,-182.42 144.22,-173.77 111,-156 99.37,-149.78 88.22,-140.54 79.1,-131.78"/>
+<polygon fill="black" stroke="black" points="81.5,-129.23 71.96,-124.62 76.54,-134.17 81.5,-129.23"/>
+</g>
+<!-- node_1_1 -->
+<g id="node18" class="node">
+<title>node_1_1</title>
+<polygon fill="lightblue" stroke="lightblue" points="287,-172.5 287,-208.5 341,-208.5 341,-172.5 287,-172.5"/>
+<text text-anchor="middle" x="314" y="-186.8" font-family="sans-serif" font-size="14.00">node</text>
+</g>
+<!-- node_1_1&#45;&gt;rk_0_3 -->
+<g id="edge12" class="edge">
+<title>node_1_1&#45;&gt;rk_0_3</title>
+<path fill="none" stroke="black" d="M313.36,-172.11C312.97,-161.27 312.45,-147.1 312,-134.79"/>
+<polygon fill="black" stroke="black" points="315.49,-134.45 311.63,-124.58 308.49,-134.71 315.49,-134.45"/>
+</g>
+<!-- node_1_1&#45;&gt;rk_0_2 -->
+<g id="edge11" class="edge">
+<title>node_1_1&#45;&gt;rk_0_2</title>
+<path fill="none" stroke="black" d="M292.97,-172.19C287.04,-167.11 280.66,-161.45 275,-156 267.18,-148.47 259,-139.89 251.79,-132.07"/>
+<polygon fill="black" stroke="black" points="254.28,-129.6 244.96,-124.55 249.1,-134.31 254.28,-129.6"/>
+</g>
+<!-- node_1_2 -->
+<g id="node19" class="node">
+<title>node_1_2</title>
+<polygon fill="lightblue" stroke="lightblue" points="359,-172.5 359,-208.5 413,-208.5 413,-172.5 359,-172.5"/>
+<text text-anchor="middle" x="386" y="-186.8" font-family="sans-serif" font-size="14.00">node</text>
+</g>
+<!-- node_1_2&#45;&gt;rk_0_5 -->
+<g id="edge14" class="edge">
+<title>node_1_2&#45;&gt;rk_0_5</title>
+<path fill="none" stroke="black" d="M407.57,-172.21C413.65,-167.12 420.19,-161.46 426,-156 433.99,-148.49 442.35,-139.91 449.72,-132.08"/>
+<polygon fill="black" stroke="black" points="452.46,-134.28 456.7,-124.57 447.33,-129.51 452.46,-134.28"/>
+</g>
+<!-- node_1_2&#45;&gt;rk_0_4 -->
+<g id="edge13" class="edge">
+<title>node_1_2&#45;&gt;rk_0_4</title>
+<path fill="none" stroke="black" d="M386.85,-172.11C387.38,-161.27 388.07,-147.1 388.67,-134.79"/>
+<polygon fill="black" stroke="black" points="392.18,-134.74 389.17,-124.58 385.18,-134.4 392.18,-134.74"/>
+</g>
+<!-- node_1_3 -->
+<g id="node20" class="node">
+<title>node_1_3</title>
+<polygon fill="lightblue" stroke="lightblue" points="431,-172.5 431,-208.5 485,-208.5 485,-172.5 431,-172.5"/>
+<text text-anchor="middle" x="458" y="-186.8" font-family="sans-serif" font-size="14.00">node</text>
+</g>
+<!-- node_1_3&#45;&gt;rk_0_7 -->
+<g id="edge16" class="edge">
+<title>node_1_3&#45;&gt;rk_0_7</title>
+<path fill="none" stroke="black" d="M485.24,-186.97C513.48,-183.41 558.15,-175.05 592,-156 602.7,-149.98 612.7,-140.99 620.83,-132.39"/>
+<polygon fill="black" stroke="black" points="623.67,-134.47 627.74,-124.69 618.46,-129.79 623.67,-134.47"/>
+</g>
+<!-- node_1_3&#45;&gt;rk_0_6 -->
+<g id="edge15" class="edge">
+<title>node_1_3&#45;&gt;rk_0_6</title>
+<path fill="none" stroke="black" d="M485.18,-172.72C492.79,-167.64 500.91,-161.86 508,-156 516.77,-148.76 525.71,-140.13 533.46,-132.17"/>
+<polygon fill="black" stroke="black" points="536.4,-134.16 540.77,-124.51 531.33,-129.33 536.4,-134.16"/>
+</g>
+<!-- rk_1_3 -->
+<g id="node21" class="node">
+<title>rk_1_3</title>
+<polygon fill="yellow" stroke="yellow" points="431,-245.5 431,-281.5 485,-281.5 485,-245.5 431,-245.5"/>
+<text text-anchor="middle" x="444" y="-259.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="457,-245.5 457,-281.5 "/>
+<text text-anchor="middle" x="471" y="-259.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_1_3&#45;&gt;node_1_3 -->
+<g id="edge20" class="edge">
+<title>rk_1_3&#45;&gt;node_1_3</title>
+<path fill="none" stroke="black" d="M458,-245.31C458,-237.29 458,-227.55 458,-218.57"/>
+<polygon fill="black" stroke="black" points="461.5,-218.53 458,-208.53 454.5,-218.53 461.5,-218.53"/>
+</g>
+<!-- rk_1_2 -->
+<g id="node22" class="node">
+<title>rk_1_2</title>
+<polygon fill="yellow" stroke="yellow" points="359,-245.5 359,-281.5 413,-281.5 413,-245.5 359,-245.5"/>
+<text text-anchor="middle" x="372" y="-259.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="385,-245.5 385,-281.5 "/>
+<text text-anchor="middle" x="399" y="-259.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_1_2&#45;&gt;node_1_2 -->
+<g id="edge19" class="edge">
+<title>rk_1_2&#45;&gt;node_1_2</title>
+<path fill="none" stroke="black" d="M386,-245.31C386,-237.29 386,-227.55 386,-218.57"/>
+<polygon fill="black" stroke="black" points="389.5,-218.53 386,-208.53 382.5,-218.53 389.5,-218.53"/>
+</g>
+<!-- rk_1_1 -->
+<g id="node23" class="node">
+<title>rk_1_1</title>
+<polygon fill="yellow" stroke="yellow" points="287,-245.5 287,-281.5 341,-281.5 341,-245.5 287,-245.5"/>
+<text text-anchor="middle" x="300" y="-259.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="313,-245.5 313,-281.5 "/>
+<text text-anchor="middle" x="327" y="-259.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_1_1&#45;&gt;node_1_1 -->
+<g id="edge18" class="edge">
+<title>rk_1_1&#45;&gt;node_1_1</title>
+<path fill="none" stroke="black" d="M314,-245.31C314,-237.29 314,-227.55 314,-218.57"/>
+<polygon fill="black" stroke="black" points="317.5,-218.53 314,-208.53 310.5,-218.53 317.5,-218.53"/>
+</g>
+<!-- rk_1_0 -->
+<g id="node24" class="node">
+<title>rk_1_0</title>
+<polygon fill="yellow" stroke="yellow" points="215,-245.5 215,-281.5 269,-281.5 269,-245.5 215,-245.5"/>
+<text text-anchor="middle" x="228" y="-259.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="241,-245.5 241,-281.5 "/>
+<text text-anchor="middle" x="255" y="-259.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_1_0&#45;&gt;node_1_0 -->
+<g id="edge17" class="edge">
+<title>rk_1_0&#45;&gt;node_1_0</title>
+<path fill="none" stroke="black" d="M242,-245.31C242,-237.29 242,-227.55 242,-218.57"/>
+<polygon fill="black" stroke="black" points="245.5,-218.53 242,-208.53 238.5,-218.53 245.5,-218.53"/>
+</g>
+<!-- node_2_1 -->
+<g id="node25" class="node">
+<title>node_2_1</title>
+<polygon fill="lightblue" stroke="lightblue" points="359,-329.5 359,-365.5 413,-365.5 413,-329.5 359,-329.5"/>
+<text text-anchor="middle" x="386" y="-343.8" font-family="sans-serif" font-size="14.00">node</text>
+</g>
+<!-- node_2_1&#45;&gt;rk_1_3 -->
+<g id="edge24" class="edge">
+<title>node_2_1&#45;&gt;rk_1_3</title>
+<path fill="none" stroke="black" d="M405.69,-329.39C411.17,-324.31 416.99,-318.6 422,-313 428.33,-305.92 434.69,-297.78 440.26,-290.22"/>
+<polygon fill="black" stroke="black" points="443.39,-291.86 446.39,-281.7 437.71,-287.77 443.39,-291.86"/>
+</g>
+<!-- node_2_1&#45;&gt;rk_1_2 -->
+<g id="edge23" class="edge">
+<title>node_2_1&#45;&gt;rk_1_2</title>
+<path fill="none" stroke="black" d="M386,-329.11C386,-318.27 386,-304.1 386,-291.79"/>
+<polygon fill="black" stroke="black" points="389.5,-291.58 386,-281.58 382.5,-291.58 389.5,-291.58"/>
+</g>
+<!-- node_2_0 -->
+<g id="node26" class="node">
+<title>node_2_0</title>
+<polygon fill="lightblue" stroke="lightblue" points="287,-329.5 287,-365.5 341,-365.5 341,-329.5 287,-329.5"/>
+<text text-anchor="middle" x="314" y="-343.8" font-family="sans-serif" font-size="14.00">node</text>
+</g>
+<!-- node_2_0&#45;&gt;rk_1_1 -->
+<g id="edge22" class="edge">
+<title>node_2_0&#45;&gt;rk_1_1</title>
+<path fill="none" stroke="black" d="M314,-329.11C314,-318.27 314,-304.1 314,-291.79"/>
+<polygon fill="black" stroke="black" points="317.5,-291.58 314,-281.58 310.5,-291.58 317.5,-291.58"/>
+</g>
+<!-- node_2_0&#45;&gt;rk_1_0 -->
+<g id="edge21" class="edge">
+<title>node_2_0&#45;&gt;rk_1_0</title>
+<path fill="none" stroke="black" d="M294.31,-329.39C288.83,-324.31 283.01,-318.6 278,-313 271.67,-305.92 265.31,-297.78 259.74,-290.22"/>
+<polygon fill="black" stroke="black" points="262.29,-287.77 253.61,-281.7 256.61,-291.86 262.29,-287.77"/>
+</g>
+<!-- rk_2_1 -->
+<g id="node27" class="node">
+<title>rk_2_1</title>
+<polygon fill="yellow" stroke="yellow" points="359,-402.5 359,-438.5 413,-438.5 413,-402.5 359,-402.5"/>
+<text text-anchor="middle" x="372" y="-416.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="385,-402.5 385,-438.5 "/>
+<text text-anchor="middle" x="399" y="-416.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_2_1&#45;&gt;node_2_1 -->
+<g id="edge26" class="edge">
+<title>rk_2_1&#45;&gt;node_2_1</title>
+<path fill="none" stroke="black" d="M386,-402.31C386,-394.29 386,-384.55 386,-375.57"/>
+<polygon fill="black" stroke="black" points="389.5,-375.53 386,-365.53 382.5,-375.53 389.5,-375.53"/>
+</g>
+<!-- rk_2_0 -->
+<g id="node28" class="node">
+<title>rk_2_0</title>
+<polygon fill="yellow" stroke="yellow" points="287,-402.5 287,-438.5 341,-438.5 341,-402.5 287,-402.5"/>
+<text text-anchor="middle" x="300" y="-416.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="313,-402.5 313,-438.5 "/>
+<text text-anchor="middle" x="327" y="-416.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_2_0&#45;&gt;node_2_0 -->
+<g id="edge25" class="edge">
+<title>rk_2_0&#45;&gt;node_2_0</title>
+<path fill="none" stroke="black" d="M314,-402.31C314,-394.29 314,-384.55 314,-375.57"/>
+<polygon fill="black" stroke="black" points="317.5,-375.53 314,-365.53 310.5,-375.53 317.5,-375.53"/>
+</g>
+<!-- node_3_0 -->
+<g id="node29" class="node">
+<title>node_3_0</title>
+<polygon fill="lightblue" stroke="lightblue" points="323,-486.5 323,-522.5 377,-522.5 377,-486.5 323,-486.5"/>
+<text text-anchor="middle" x="350" y="-500.8" font-family="sans-serif" font-size="14.00">node</text>
+</g>
+<!-- node_3_0&#45;&gt;rk_2_1 -->
+<g id="edge27" class="edge">
+<title>node_3_0&#45;&gt;rk_2_1</title>
+<path fill="none" stroke="black" d="M357.63,-486.11C362.49,-475.06 368.87,-460.53 374.34,-448.05"/>
+<polygon fill="black" stroke="black" points="377.68,-449.15 378.5,-438.58 371.28,-446.33 377.68,-449.15"/>
+</g>
+<!-- node_3_0&#45;&gt;rk_2_0 -->
+<g id="edge28" class="edge">
+<title>node_3_0&#45;&gt;rk_2_0</title>
+<path fill="none" stroke="black" d="M342.37,-486.11C337.51,-475.06 331.13,-460.53 325.66,-448.05"/>
+<polygon fill="black" stroke="black" points="328.72,-446.33 321.5,-438.58 322.32,-449.15 328.72,-446.33"/>
+</g>
+<!-- rk_3_0 -->
+<g id="node30" class="node">
+<title>rk_3_0</title>
+<polygon fill="yellow" stroke="yellow" points="323,-559.5 323,-595.5 377,-595.5 377,-559.5 323,-559.5"/>
+<text text-anchor="middle" x="336" y="-573.8" font-family="sans-serif" font-size="14.00">r</text>
+<polyline fill="none" stroke="yellow" points="349,-559.5 349,-595.5 "/>
+<text text-anchor="middle" x="363" y="-573.8" font-family="sans-serif" font-size="14.00">k</text>
+</g>
+<!-- rk_3_0&#45;&gt;node_3_0 -->
+<g id="edge29" class="edge">
+<title>rk_3_0&#45;&gt;node_3_0</title>
+<path fill="none" stroke="black" d="M350,-559.31C350,-551.29 350,-541.55 350,-532.57"/>
+<polygon fill="black" stroke="black" points="353.5,-532.53 350,-522.53 346.5,-532.53 353.5,-532.53"/>
+</g>
+</g>
+</svg>
diff --git a/doc/eris.adoc b/doc/eris.adoc
new file mode 100644
index 0000000..97a3d94
--- /dev/null
+++ b/doc/eris.adoc
@@ -0,0 +1,178 @@
+= Encoding for Robust Immutable Storage (ERIS)
+pukkamustard <pukkamustard@posteo.net>
+0.2.0-draft
+:toc: left
+:stem:
+:sectnums:
+:sectanchors:
+
+[abstract]
+The Encoding for Robust Immutable Storage (ERIS) is an encoding of arbitrary content into a set of uniformly sized, encrypted and content-addressed blocks as well as a short identifier - the _read capability_. The content can be reassembled from the encrypted blocks only with the read capability. The encoding is defined independently of any storage or transport layer. Together with content-addressable storage, ERIS can be used as a building block for robust and decentralized applications.
+
+== Introduction
+
+Unavailability of content on computer networks is a major cause for reduced reliability of networked services <<Polleres2020>>.
+
+Availability can be increased by caching content on multiple peers. However most content on the Internet is identified by its location. Caching location-addressed content is complicated as the content receives a new location.
+
+An alternative to identifying content by its location is to identify content by its content itself. This is called content-addressing. The hash of some content is computed and used as an unique identifier for the content.
+
+Content-addressed content is much easier to cache as the content is completely decoupled from any physical location. It is much easier to ensure availability of content-addressed content than it is for location-addressed content.
+
+Authenticity of content is automatically ensured with content-addressing (when using a cryptographic hash) as the identifier of the content can be computed and be checked to match the requested identifier.
+
+However, naive content-addressing has certain drawbacks:
+
+- Large content is stored as a large blob. In order to optimize storage and network operations it is better to split up content into smaller uniformly sized blocks and reassemble blocks when needed.
+- Confidentiality: Content is readable by all peers involved in transporting, caching and storing content.
+
+ERIS is an encoding that addresses these issues by splitting blocks into small uniformly sized blocks and encrypting blocks.
+
+=== Objectives
+
+The objectives of ERIS are:
+
+Availability :: Content encoded with ERIS can be easily replicated and cached.
+Authenticity :: Authenticity of content can be verified efficiently.
+URN reference :: ERIS encoded content can be referrenced with a single URN.
+Storage efficiency :: ERIS can be used to encode small content (< 1Kb) as well as large content (> many Gb) with reasonable storage overhead.
+Simplicity :: The encoding should be as simple as possible in order to allow correct implementation on various platforms and in various languages.
+
+
+=== Scope
+
+ERIS describes how arbitrary content (sequence of bytes) can be encoded into a set of uniformly sized blocks and an identifier with which the content can be decoded from the set of blocks.
+
+ERIS does not prescribe how the blocks should be stored or transported over network. The only requirement is that a block can be referenced and accessed (if available) by the hash value of the contents of the block. In section <<_storage_and_transport_layers>> we show how existing technology (including IPFS) can be used to store and transport blocks.
+
+There is also no support for grouping content or mutating content. In section <<_namespaces>> we describe how such functionality can be implemented on top of ERIS.
+
+The lack of certain functionalities is intentional. ERIS is an attempt to find a minimal common basis on which higher functionality can be built. Lacking functionality in ERIS is an acknowledgment that there are many ways of implementing such functionality at a different layer that may be optimized for certain use-cases.
+
+=== Previous work
+
+ERIS is inspired and based on the encoding used in the file-sharing application of https://gnunet.org/[GNUNet] - Encoding for Censorship-Resistant Sharing (ECRS) <<ECRS>>.
+
+ERIS differs from ECRS in following points:
+
+Cryptographic primitives :: ECRS itself does not specify any cryptographic primitives but the GNUNet implementation uses the SHA-512 hash and AES cipher. ERIS uses the Blake2b-256 cryptographic hash <<RFC7693>> and the ChaCha20 stream cipher <<RFC8439>>. This improves performance, storage efficiency (as hash references are smaller) and allows a convergence secret to be used (via Blake2b keyed hashing; see section <<_convergence_secret>>).
+Block size :: ECRS uses a fixed block size of 32 Kb. This is inefficient when encoding small content. ERIS allows a block size of 1 Kb or 32 Kb, allowing efficient encoding of small and large content.
+URN :: ECRS does not specify an URN for referring to encoded content (this is specified as part of the GNUNet file-sharing application). ERIS specifies an URN for encoded content regardless of encoding application or storage and transport layer.
+Namespaces :: ECRS defines two mechanisms for grouping and discovering encoded content (SBlock and KBlock). ERIS does not specify any such mechanisms (see section <<_namespaces>>).
+
+Other related projects include Tahoe-LAFS and Freenet. The reader is referred to the ECRS paper <<ECRS>> for an in-depth explanation and comparison of related projects.
+
+=== Terminology
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 <<RFC2119>>.
+
+TODO a glossary of terms used.
+
+== Specification of ERIS
+
+=== Cryptographic Primitives
+
+The cryptographic primitives used by ERIS are:
+
+Cryptographic hash function :: Blake2b <<RFC7693>> with output size of 256 bit (32 byte).
+Symmetric Key Cipher :: ChaCha20 (IETF variant) <<RFC8439>>.
+Padding algorithm :: According to ISO/IEC 7816-4.
+
+=== Block Size
+
+=== Encoding
+
+An overview of how content (sequence of bytes) is encoded using ERIS:
+
+1. Split content into unencrypted blocks of size block size (see <<_splitting_input_content_into_blocks>>).
+2. Encrypt unencrypted block and compute reference to encrypted block. This is a fundamental operation during encoding and described in section <<_reference_key_pair>>.
+3. Build a tree of nodes containing references to blocks by (see section <<_merkle_tree>>):
+ - Collect references to encrypted blocks in a node of size block size
+ - Encrypt node and compute reference in the same way as for data blocks.
+ - Recursively collect references in nodes of higher level until there is only a single root node.
+
+The input to the encoding process is the content as sequence of bytes and an optional convergence secret (see <<_convergence_secret>>).
+
+The output of the encoding process is a sequence of encrypted blocks (of size block size) and a root reference-key pair.
+
+==== Splitting Input Content into Blocks
+
+Input content is split into blocks of size at most block size such that only the last content block may be smaller than block size.
+
+The last content block is always padded according to the padding algorithm to block size. If the size of the padded last block is larger than block size it is split into content blocks of block size.
+
+NOTE: If the length of the last content block is exactly block size, then padding will result in a padded block that is double the block size and must be split.
+
+==== Reference-Key Pair
+
+A _reference-key pair_ is a pair consisting of a reference to an encrypted block and the key to decrypt the block. Reference and key are both 32 bytes long. The concatenation of a reference-key pair is 64 bytes long (512 bits). In the following we also use the abbreviation _r-k pair_ for reference-key pair.
+
+Encrypting a block and computing the reference-key pair is a fundamental operation of the encoding process and may be implemented as following sub-process or function:
+
+1. Compute the hash of the unencrypted block. If a convergence secret is used the convergence secret MUST be used as key of the hash function. The output of the hash is the _key_.
+2. Encrypt the block using the symmetric key cipher with the key.
+3. The hash of the encrypted block is used as _reference_ to the encrypted block.
+
+The encrypted block MUST be added to the output of the encoding process. The reference-key pair is returned and used for further processing.
+
+IMPORTANT: The convergence-secret MUST NOT be used to compute the reference to the encrypted block.
+
+===== Convergence Secret
+
+TODO: some notes on convergence secret.
+
+==== Merkle Tree
+
+Reference-key pairs are collected into nodes of size block size by concatenating the concatenated reference-key pair. The node is encrypted, and a reference-key pair to the node is computed. This results in a sequence of reference-key pairs that refer nodes containing reference-key pairs at a lower level - a tree. This process is recursively applied until there is a single reference-key pair - the /root reference-key pair/. We keep track of the level of recursion.
+
+The initial input (level 0) is the sequence of reference-key pairs to the input content.
+
+The number of reference-key pairs collected into a node is called the /arity/ of the tree and depends on the block size. For block size 1Kb the arity of the tree is 16, for block size 32Kb the arity is 512.
+
+For illustration purposes we use arity 2 in example figures (every node contains two reference-key pairs).
+
+.Merkle Tree
+image::eris-merkle-tree.svg[Merkle Tree,opts=inline,width=80%]
+
+==== Read Capability
+
+=== Decoding
+
+=== URN
+
+[quote, William Shakespeare, Comedy of Errors]
+____
+The one so like the other
+
+As could not be distinguish'd but by names.
+____
+
+== Applications
+
+=== Storage and Transport Layers
+
+=== Namespaces
+
+== Acknowledgments
+
+[appendix]
+== Test Vectors
+
+[appendix]
+== Changelog
+
+[appendix]
+== Copyright
+
+This work is licensed under a http://creativecommons.org/licenses/by-sa/4.0/[Creative Commons Attribution-ShareAlike 4.0 International License].
+
+[bibliography]
+== References
+
+- [[[content-addressable-rdf]]] openEngiadina. https://openengiadina.net/papers/content-addressable-rdf.html[Content-addressable RDF]. 2020
+- [[[rdf-signify]]] openEngiadina. https://openengiadina.net/papers/rdf-signify.html[RDF Signify]. 2020
+- [[[Polleres2020]]] Polleres, Kamdar, Fernández, Javier David, Tudorache & Musen. https://epub.wu.ac.at/6371/1/IPM_workingpaper_02_2018.pdf[A more decentralized vision for Linked Data]. 2020
+- [[[ECRS]]] Grothoff, Grothoff, Horozov, & Lindgren. https://grothoff.org/christian/ecrs.pdf[An encoding for censorship-resistant sharing]. 2003
+- [[[RFC2119]]] S. Bradner. https://tools.ietf.org/html/rfc2119[Key words for use in RFCs to Indicate Requirement Levels]. 1997
+- [[[RFC7693]]] M-J. Saarinen & J-P. Aumasson. https://tools.ietf.org/html/rfc7693[The BLAKE2 Cryptographic Hash and Message Authentication Code (MAC)]. 2015
+- [[[RFC8439]]] Nir & Langley. https://tools.ietf.org/html/rfc8439[ChaCha20 and Poly1305 for IETF Protocols]. 2018