Skip to content
This repository has been archived by the owner on Nov 15, 2023. It is now read-only.

Exploration of using graphwiz #1298

Merged
merged 3 commits into from
Jun 24, 2020
Merged

Exploration of using graphwiz #1298

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
50aa4c8
Experiment with graphwiz
pepyakin Jun 20, 2020
ebe4084
Convert parachain overview diagrams
pepyakin Jun 22, 2020
8267d26
add install note for mdbook-graphviz
rphmeier Jun 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions roadmap/implementors-guide/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
book/
*.generated.svg
3 changes: 3 additions & 0 deletions roadmap/implementors-guide/book.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,8 @@ multilingual = false
src = "src"
title = "The Polkadot Parachain Host Implementers' Guide"

[preprocessor.graphviz]
command = "mdbook-graphviz"

[output.html]
[output.linkcheck]
63 changes: 25 additions & 38 deletions roadmap/implementors-guide/src/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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]
}
```

Expand Down
85 changes: 35 additions & 50 deletions roadmap/implementors-guide/src/parachains-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.