Unverified Commit c948d2c9 authored by Sergey Pepyakin's avatar Sergey Pepyakin Committed by GitHub
Browse files

Exploration of using graphwiz (#1298)



* Experiment with graphwiz

* Convert parachain overview diagrams

* add install note for mdbook-graphviz
Co-authored-by: asynchronous rob's avatarRobert Habermeier <rphmeier@gmail.com>
parent b05bb8f6
Pipeline #98241 passed with stages
in 24 minutes and 37 seconds
......@@ -3,7 +3,7 @@
The implementers' guide is compiled from several source files with [mdBook](https://github.com/rust-lang/mdBook). To view it live, locally, from the repo root:
```sh
cargo install mdbook mdbook-linkcheck
cargo install mdbook mdbook-linkcheck mdbook-graphviz
mdbook serve roadmap/implementors-guide
open http://localhost:3000
```
......@@ -5,5 +5,8 @@ multilingual = false
src = "src"
title = "The Polkadot Parachain Host Implementers' Guide"
[preprocessor.graphviz]
command = "mdbook-graphviz"
[output.html]
[output.linkcheck]
......@@ -2,25 +2,22 @@
Our Parachain Host includes a blockchain known as the relay-chain. A blockchain is a Directed Acyclic Graph (DAG) of state transitions, where every block can be considered to be the head of a linked-list (known as a "chain" or "fork") with a cumulative state which is determined by applying the state transition of each block in turn. All paths through the DAG terminate at the Genesis Block. In fact, the blockchain is a tree, since each block can have only one parent.
```text
+----------------+ +----------------+
| Block 4 | | Block 5 |
+----------------+ +----------------+
\ /
V V
+---------------+
| Block 3 |
+---------------+
|
V
+----------------+ +----------------+
| Block 1 | | Block 2 |
+----------------+ +----------------+
\ /
V V
+----------------+
| Genesis |
+----------------+
```dot process
digraph {
node [shape=box];
genesis [label = Genesis]
b1 [label = "Block 1"]
b2 [label = "Block 2"]
b3 [label = "Block 3"]
b4 [label = "Block 4"]
b5 [label = "Block 5"]
b5 -> b3
b4 -> b3
b3 -> b1
b2 -> genesis
b1 -> genesis
}
```
A blockchain network is comprised of nodes. These nodes each have a view of many different forks of a blockchain and must decide which forks to follow and what actions to take based on the forks of the chain that they are aware of.
......@@ -34,26 +31,16 @@ The first category of questions will be addressed by the Runtime, which defines
The second category of questions addressed by Node-side behavior. Node-side behavior defines all activities that a node undertakes, given its view of the blockchain/block-DAG. Node-side behavior can take into account all or many of the forks of the blockchain, and only conditionally undertake certain activities based on which forks it is aware of, as well as the state of the head of those forks.
```text
```dot process
digraph G {
Runtime [shape=box]
"Node" [shape=box margin=0.5]
Transport [shape=rectangle width=5]
Runtime -> "Node" [dir=both label="Runtime API"]
__________________________________
/ \
| Runtime |
| |
\_________(Runtime API )___________/
| ^
V |
+----------------------------------------------+
| |
| Node |
| |
| |
+----------------------------------------------+
+ +
| |
--------------------+ +------------------------
Transport
------------------------------------------------
"Node" -> Transport [penwidth=1]
}
```
......
......@@ -60,61 +60,46 @@ Reiterating the lifecycle of a candidate:
It is also important to take note of the fact that the relay-chain is extended by BABE, which is a forkful algorithm. That means that different block authors can be chosen at the same time, and may not be building on the same block parent. Furthermore, the set of validators is not fixed, nor is the set of parachains. And even with the same set of validators and parachains, the validators' assignments to parachains is flexible. This means that the architecture proposed in the next chapters must deal with the variability and multiplicity of the network state.
```text
....... Validator Group 1 ..........
. .
. (Validator 4) .
. (Validator 1) (Validator 2) .
. (Validator 5) .
. .
..........Building on C ........... ........ Validator Group 2 ...........
+----------------------+ . .
| Relay Block C | . (Validator 7) .
+----------------------+ . ( Validator 3) (Validator 6) .
\ . .
\ ......... Building on B .............
\
+----------------------+
| Relay Block B |
+----------------------+
|
+----------------------+
| Relay Block A |
+----------------------+
```dot process
digraph {
rca [label = "Relay Block A" shape=rectangle]
rcb [label = "Relay Block B" shape=rectangle]
rcc [label = "Relay Block C" shape=rectangle]
vg1 [label =<<b>Validator Group 1</b><br/><br/><font point-size="10">(Validator 4)<br/>(Validator 1) (Validator 2)<br/>(Validator 5)</font>>]
vg2 [label =<<b>Validator Group 2</b><br/><br/><font point-size="10">(Validator 7)<br/>(Validator 3) (Validator 6)</font>>]
rcb -> rca
rcc -> rcb
vg1 -> rcc [label="Building on C" style=dashed arrowhead=none]
vg2 -> rcb [label="Building on B" style=dashed arrowhead=none]
}
```
In this example, group 1 has received block C while the others have not due to network asynchrony. Now, a validator from group 2 may be able to build another block on top of B, called C'. Assume that afterwards, some validators become aware of both C and C', while others remain only aware of one.
```text
....... Validator Group 1 .......... ........ Validator Group 2 ...........
. . . .
. (Validator 4) (Validator 1) . . (Validator 7) (Validator 6) .
. . . .
.......... Building on C .......... ......... Building on C' .............
....... Validator Group 3 ..........
. .
. (Validator 2) (Validator 3) .
. (Validator 5) .
. .
....... Building on C and C' .......
+----------------------+ +----------------------+
| Relay Block C | | Relay Block C' |
+----------------------+ +----------------------+
\ /
\ /
\ /
+----------------------+
| Relay Block B |
+----------------------+
|
+----------------------+
| Relay Block A |
+----------------------+
```dot process
digraph {
rca [label = "Relay Block A" shape=rectangle]
rcb [label = "Relay Block B" shape=rectangle]
rcc [label = "Relay Block C" shape=rectangle]
rcc_prime [label = "Relay Block C'" shape=rectangle]
vg1 [label =<<b>Validator Group 1</b><br/><br/><font point-size="10">(Validator 4) (Validator 1)</font>>]
vg2 [label =<<b>Validator Group 2</b><br/><br/><font point-size="10">(Validator 7) (Validator 6)</font>>]
vg3 [label =<<b>Validator Group 3</b><br/><br/><font point-size="10">(Validator 2) (Validator 3)<br/>(Validator 5)</font>>]
rcb -> rca
rcc -> rcb
rcc_prime -> rcb
vg1 -> rcc [style=dashed arrowhead=none]
vg2 -> rcc_prime [style=dashed arrowhead=none]
vg3 -> rcc_prime [style=dashed arrowhead=none]
vg3 -> rcc [style=dashed arrowhead=none]
}
```
Those validators that are aware of many competing heads must be aware of the work happening on each one. They may contribute to some or a full extent on both. It is possible that due to network asynchrony two forks may grow in parallel for some time, although in the absence of an adversarial network this is unlikely in the case where there are validators who are aware of both chain heads.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment