Skip to content

Commit ebcbe32

Browse files
nfrisbynfrisby
authored
Draft BlockBlockDiagram.md (#1420)
Since I found myself looking this up for the umpteenth time, I paused to document my mental image of the fields within a header and how they all relate to the whole block.
2 parents 43c1fef + 37a0fd5 commit ebcbe32

File tree

2 files changed

+140
-0
lines changed

2 files changed

+140
-0
lines changed

‎docs/website/contents/for-developers/BlockBlockDiagram.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Introduction
2+
3+
Many parts of the Consensus and Storage Layers' design primarily focus on points, blocks headers, and full blocks.
4+
This document visualizes their contents, as of the Conway ledger era, from the perspective of the Consensus protocol.
5+
6+
The names of the individual fields were copied directly from the corresponding Haskell code; they are merely mnemonics within this diagram/document, not necessarily recognized more broadly.
7+
Moreover, the order of the fields does not necessarily match their order within the valid CBOR encodings; see the corresponding CDDL specs for such details.
8+
9+
# Block Diagram of a Point
10+
11+
A point `(s, h)` names a (supposed) block whose `hbSlotNo` is `s` and whose serialized block header has hash `h`.
12+
13+
```mermaid
14+
block-beta
15+
block:point
16+
columns 1
17+
18+
pointSlot
19+
pointHash("pointHash (aka headerHash)")
20+
end
21+
22+
%% palette from https://davidmathlogic.com/colorblind/#%23000000-%23E69F00-%2356B4E9-%23009E73-%23F0E442-%230072B2-%23D55E00-%23CC79A7
23+
24+
style pointHash color:#E69F00
25+
```
26+
27+
The `pointHash` field has the color #E69F00 because it's a hash of the (serialization of the) fields inside that background color in the block diagram of a full block below.
28+
The same semantics of text color matching some background color is used within that diagram as well.
29+
30+
# Block Diagram of a Full Block
31+
32+
```mermaid
33+
block-beta
34+
block:fullblock
35+
columns 1
36+
37+
block:blockheader
38+
columns 1
39+
40+
headerSig("headerSig (KES)")
41+
block:headerBody
42+
columns 3
43+
44+
block:election
45+
hbSlotNo
46+
hbVk("hbVk (DSIGN)")
47+
end
48+
hbBlockNo
49+
hbPrev
50+
hbVrfVk("hbVrfVk (VRF)")
51+
hbVrfRes("hbVrfRes (VRF)")
52+
hbBodySize
53+
hbBodyHash
54+
block:ocertBody
55+
ocertVkHot("ocertVkHot (KES)"))
56+
ocertN
57+
ocertKESPeriod
58+
end
59+
ocertSigma("ocertSigma (DSIGN)")
60+
end
61+
end
62+
63+
block:blockbody
64+
columns 2
65+
66+
txSeqBodyBytes
67+
txSeqWitsBytes
68+
txSeqMetadataBytes
69+
txSeqIsValidBytes
70+
end
71+
end
72+
73+
%% palette from https://davidmathlogic.com/colorblind/#%23E69F00-%2356B4E9-%23009E73-%230072B2-%23D55E00
74+
75+
style blockheader fill:#E69F00
76+
style hbPrev color:#E69F00
77+
%% style pointHash color:#E69F00 -- find node in sibling diagram
78+
79+
style headerBody fill:#56B4E9
80+
style headerSig color:#56B4E9
81+
style ocertVkHot color:#56B4E9
82+
83+
style blockbody fill:#009E73
84+
style hbBodySize color:#009E73
85+
style hbBodyHash color:#009E73
86+
87+
style ocertBody fill:#0072B2
88+
style ocertSigma color:#0072B2
89+
style hbVk color:#0072B2
90+
91+
style election fill:#D55E00
92+
style hbVrfRes color:#D55E00
93+
style hbVrfVk color:#D55E00
94+
```
95+
96+
Some remarks.
97+
98+
- The relative sizes of the rectangles in this diagram are meaningless.
99+
We couldn't figure out a reasonable way to better control them within the Mermaid syntax.
100+
101+
- The `hbPrev` field has the same #E69F00 color as `pointHash`, but note that it is the hash of the header of the this block's predecessor.
102+
103+
# Block Diagram of a Transaction
104+
105+
There is very rich structure within the transactions themselves, but the majority of the Consensus and Storage Layer does not concern itself with that structure.
106+
The `txSeq*` items are shown within the full block are just for orientation, since the alternative would be to simply write `body`, which is much less perspicious.
107+
108+
An individual transaction, outside of a block, has the same four parts (due to [segregated witnesses](https://github.com/IntersectMBO/cardano-ledger/blob/81637a1c2250225fef47399dd56f80d87384df32/libs/cardano-ledger-core/src/Cardano/Ledger/Core.hs#L562-L579)).
109+
110+
```mermaid
111+
block-beta
112+
block:tx
113+
columns 4
114+
115+
block:txbody
116+
body
117+
end
118+
wits
119+
isValid
120+
auxiliaryData
121+
end
122+
123+
%% palette from https://davidmathlogic.com/colorblind/#%23000000-%23E69F00-%2356B4E9-%23009E73-%23F0E442-%230072B2-%23D55E00-%23CC79A7
124+
125+
style body fill:#CC79A7
126+
```
127+
128+
The transaction ID is the hash of just one of those parts of a single transaction, its body.
129+
130+
```mermaid
131+
block-beta
132+
txId("txId (aka txBodyHash)")
133+
134+
%% palette from https://davidmathlogic.com/colorblind/#%23000000-%23E69F00-%2356B4E9-%23009E73-%23F0E442-%230072B2-%23D55E00-%23CC79A7
135+
136+
style txId color:#CC79A7
137+
```
138+
139+
The `hbBodyHash` field, in contrast, hashes over all four parts of all transactions in the block body.

‎docs/website/sidebars.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ const sidebars = {
3535
'for-developers/index',
3636
'for-developers/Glossary',
3737
'for-developers/ComponentDiagram',
38+
'for-developers/BlockBlockDiagram',
3839
'for-developers/CardanoPraosBasics',
3940
'for-developers/Ticking',
4041
'for-developers/CivicTime',

0 commit comments

Comments
 (0)