Skip to content

Commit e126711

Browse files
phutchinsphutchins
authored
docs: converted PUML diagrams to Mermaid (#1364)
1 parent cdae62c commit e126711

18 files changed

Lines changed: 519 additions & 521 deletions

‎docs/fendermint/diagrams/Makefile‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,25 @@
1-
PUMLS = $(shell find . -type f -name "*.puml")
2-
PNGS = $(PUMLS:.puml=.png)
3-
PUML_VER=1.2023.2
1+
MMDS = $(shell find . -type f -name "*.mmd")
2+
PNGS = $(MMDS:.mmd=.png)
3+
MERMAID_CLI_VER=10.6.1
44

55
.PHONY: all
66
all: diagrams
77

88
.PHONY: diagrams
9-
diagrams: $(PNGS)
9+
diagrams: node_modules $(PNGS)
1010

11-
plantuml.jar:
12-
wget -O $@ https://github.com/plantuml/plantuml/releases/download/v$(PUML_VER)/plantuml-$(PUML_VER).jar --no-check-certificate --quiet
11+
package.json:
12+
@echo '{"name": "diagram-builder", "version": "1.0.0", "description": "Mermaid diagram builder", "private": true}' > package.json
1313

14-
%.png: plantuml.jar %.puml
15-
@# Using pipelining to preserve file names.
16-
cat $*.puml | java -DPLANTUML_LIMIT_SIZE=8192 -jar plantuml.jar -pipe > $*.png
14+
node_modules: package.json
15+
npm cache clean --force 2>/dev/null || true
16+
npm install @mermaid-js/mermaid-cli@$(MERMAID_CLI_VER)
17+
touch node_modules
18+
19+
%.png: %.mmd node_modules
20+
npx mmdc -i $< -o $@ --theme neutral --backgroundColor transparent
21+
22+
.PHONY: clean
23+
clean:
24+
rm -f *.png
25+
rm -rf node_modules package.json package-lock.json

‎docs/fendermint/diagrams/README.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
# Diagrams
22

3-
This directory contains [PlantUML](https://plantuml.com/) diagrams which are turned into images ready to be embedded into docs.
3+
This directory contains [Mermaid](https://mermaid.js.org/) diagrams which are turned into images ready to be embedded into docs.
44

55
To render the images, run the following command:
66

77
```shell
88
make diagrams
99
```
1010

11+
## Prerequisites
12+
13+
The build process uses the Mermaid CLI tool which requires Node.js. The Makefile will automatically install the required dependencies locally.
14+
1115
## Automation
1216

1317
Adding the following script to `.git/hooks/pre-commit` automatically renders and checks in the images when we commit changes to their source diagrams. CI should also check that there are no uncommitted changes.
@@ -21,9 +25,17 @@ set -eo pipefail
2125
# Redirect output to stderr.
2226
exec 1>&2
2327

24-
if git diff --cached --name-only --diff-filter=d | grep .puml
28+
if git diff --cached --name-only --diff-filter=d | grep .mmd
2529
then
2630
make diagrams
27-
git add docs/diagrams/*.png
31+
git add docs/fendermint/diagrams/*.png
2832
fi
2933
```
34+
35+
## Cleaning Up
36+
37+
To clean up generated files and dependencies:
38+
39+
```shell
40+
make clean
41+
```

‎docs/fendermint/diagrams/checkpointing.mmd‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
sequenceDiagram
2+
participant ParentNode as Parent Node
3+
participant ParentGateway as Parent Gateway
4+
participant Validator as Validator
5+
participant IPCAgent as IPC Agent
6+
participant Relayer as Relayer
7+
participant ChildCometBFT as Child CometBFT
8+
participant ChildFendermint as Child Fendermint
9+
participant ChildSyncer as Child Syncer
10+
participant ChildGateway as Child Gateway
11+
participant ChildActors as Child Actors
12+
13+
Note over ParentNode, ParentGateway: Parent Subnet
14+
Note over ChildCometBFT, ChildActors: Child Subnet
15+
16+
%% Initialize
17+
Note over ParentNode, ChildActors: Initialize
18+
19+
Validator->>ChildCometBFT: start
20+
Validator->>ChildFendermint: start
21+
ChildFendermint->>ChildSyncer: start
22+
Validator->>IPCAgent: start
23+
IPCAgent->>ParentNode: subscribe
24+
Relayer->>ChildCometBFT: subscribe
25+
26+
%% Joining a Subnet
27+
Note over ParentNode, ChildActors: Joining a Subnet
28+
29+
Validator->>+IPCAgent: join subnet
30+
IPCAgent->>-ParentNode: TX: join subnet
31+
ParentNode->>+ParentNode: create block and<br/>execute transaction
32+
ParentNode->>+ParentGateway: join(subnet, validator)
33+
ParentGateway->>ParentGateway: new validator<br/>configuration
34+
ParentGateway-->>IPCAgent: emit new configuration event
35+
deactivate ParentGateway
36+
deactivate ParentNode
37+
38+
%% Syncing with Parent
39+
Note over ParentNode, ChildActors: Syncing with Parent
40+
Note over ChildSyncer, IPCAgent: ... syncing with the parent at regular intervals ...
41+
42+
ChildSyncer->>+IPCAgent: get latest finalized block
43+
IPCAgent->>-ChildSyncer: finalized block height
44+
45+
ChildSyncer->>+IPCAgent: get new configurations up to finalized block
46+
IPCAgent->>-ChildSyncer: configuration changes
47+
48+
Note over ChildCometBFT, ChildFendermint: ... when this validator creates a block ...
49+
50+
ChildCometBFT->>+ChildFendermint: prepare_proposal
51+
ChildFendermint->>+ChildSyncer: get finalized parent block height
52+
ChildSyncer->>-ChildFendermint: finalized block height
53+
ChildFendermint->>-ChildCometBFT: proposal(TopDownCheckpoint)
54+
ChildCometBFT-->>ChildCometBFT: broadcast proposal
55+
56+
Note over ChildCometBFT, ChildFendermint: ... for every block created in the subnet ...
57+
58+
ChildCometBFT-->>ChildCometBFT: receive proposal
59+
ChildCometBFT->>+ChildFendermint: process_proposal(TopDownCheckpoint)
60+
ChildFendermint->>+ChildSyncer: check finality of parent block height
61+
ChildSyncer->>-ChildFendermint: is known and final or not
62+
ChildFendermint->>-ChildCometBFT: accept or reject
63+
64+
ChildCometBFT-->>ChildCometBFT: receive block
65+
66+
ChildCometBFT->>+ChildFendermint: deliver_tx(TopDownCheckpoint)
67+
ChildFendermint->>+ChildSyncer: get configuration changes up to the finalized height
68+
ChildSyncer->>+IPCAgent: fetch missing configurations
69+
IPCAgent->>+ParentNode: query state
70+
ParentNode->>ParentGateway: query state
71+
ParentNode->>-IPCAgent: gateway state
72+
IPCAgent->>-ChildSyncer: new configurations
73+
ChildSyncer->>-ChildFendermint: new configurations
74+
ChildFendermint->>+ChildGateway: call GatewayRouterFacet::setMembership
75+
ChildGateway->>ChildGateway: accumulate validator changes
76+
ChildGateway->>-ChildFendermint: result
77+
ChildFendermint->>-ChildCometBFT: receipts
78+
79+
ChildCometBFT->>+ChildFendermint: deliver_tx(SignedMessage invoking the Gateway)
80+
Note left of ChildFendermint: Example of a transaction execution<br/>enqueueing a bottom-up message.
81+
ChildFendermint->>+ChildActors: invoke with Message
82+
ChildActors->>+ChildGateway: send bottom-up CrossMsg
83+
ChildGateway->>ChildGateway: accumulate CrossMsgs
84+
ChildGateway->>-ChildActors: result
85+
ChildActors->>-ChildFendermint: result
86+
ChildFendermint->>-ChildCometBFT: receipts
87+
88+
%% End of Checkpoint Period
89+
Note over ParentNode, ChildActors: End of Checkpoint Period
90+
91+
ChildCometBFT->>+ChildFendermint: end_block
92+
alt block height % bottom-up checkpoint period == 0
93+
ChildFendermint->>+ChildCometBFT: get current validator set
94+
ChildCometBFT->>-ChildFendermint: power table
95+
ChildFendermint->>ChildFendermint: create Merkle tree of power table
96+
ChildFendermint->>ChildFendermint: set validator set root hash in checkpoint
97+
98+
ChildFendermint->>+ChildGateway: call GatewayRouterFacet::update_membership
99+
ChildGateway->>ChildGateway: clear configuration accumulator
100+
ChildGateway->>-ChildFendermint: new configurations
101+
ChildFendermint->>ChildFendermint: set next configuration number in checkpoint
102+
103+
ChildFendermint->>+ChildGateway: call GatewayGetterFacet::bottom_up_messages
104+
ChildGateway->>-ChildFendermint: bottom-up CrossMsgs
105+
ChildFendermint->>ChildFendermint: set CrossMsgs hash in checkpoint
106+
107+
ChildFendermint->>+ChildGateway: call GatewayRouterFacet::create_bottom_up_checkpoint
108+
ChildGateway->>ChildGateway: store checkpoint
109+
ChildGateway->>-ChildFendermint: result
110+
111+
alt current node is a validator in the power table
112+
ChildFendermint->>+ChildFendermint: broadcast_signature
113+
ChildFendermint->>ChildFendermint: create Merkle proof of (validator, power)
114+
ChildFendermint->>ChildFendermint: hash the checkpoint
115+
ChildFendermint->>ChildFendermint: sign the checkpoint hash with validator key
116+
ChildFendermint->>ChildFendermint: create a Message to invoke GatewayRouterFacet::add_checkpoint_signature
117+
ChildFendermint->>+ChildCometBFT: query validator nonce
118+
ChildCometBFT->>-ChildFendermint: validator actor sequence
119+
ChildFendermint->>+ChildCometBFT: estimate message gas
120+
ChildCometBFT->>-ChildFendermint: simulated transaction gas limit
121+
ChildFendermint->>ChildFendermint: sign the Message with the validator key
122+
ChildFendermint->>-ChildCometBFT: broadast SignedMessage
123+
end
124+
end
125+
ChildFendermint->>-ChildCometBFT: new configurations (a.k.a. validator updates)
126+
127+
%% Signature Accumulation
128+
Note over ParentNode, ChildActors: Signature Accumulation
129+
130+
ChildCometBFT-->>ChildCometBFT: receive transaction with checkpoint signature
131+
ChildCometBFT-->>ChildCometBFT: broadcast block with signature transactions
132+
ChildCometBFT-->>ChildCometBFT: receive block with signature transactions
133+
134+
ChildCometBFT->>+ChildFendermint: deliver_tx(SignedMessage with checkpoint signature)
135+
ChildFendermint->>+ChildGateway: invoke with Message calling GatewayRouterFacet::add_checkpoint_signature
136+
ChildGateway->>ChildGateway: look up BottomUpCheckpoint at indicated height
137+
ChildGateway->>ChildGateway: validate that the signed hash matches the checkpoint
138+
ChildGateway->>ChildGateway: validate the Merkle proof with the recovered signatory
139+
ChildGateway->>ChildGateway: update the accumulated weight of total signatures
140+
alt weight over quorum threshold
141+
ChildGateway->>ChildGateway: mark checkpoint as completed
142+
ChildGateway-->>Relayer: emit checkpoint quorum event
143+
end
144+
ChildGateway->>-ChildFendermint: result
145+
ChildFendermint->>-ChildCometBFT: receipts
146+
147+
Relayer->>+Relayer: observe quorum event
148+
Relayer->>+ChildCometBFT: query checkpoint at height in quorum event
149+
ChildCometBFT->>+ChildFendermint: ABCI Call query
150+
ChildFendermint->>+ChildGateway: read-only call to GatewayGetterFacet::bottom_up_checkpoint
151+
ChildGateway->>-ChildFendermint: BottomUpCheckpoint
152+
ChildFendermint->>-ChildCometBFT: BottomUpCheckpoint
153+
ChildCometBFT->>-Relayer: BottomUpCheckpoint
154+
155+
Relayer->>+ChildCometBFT: query signatures at height in quorum event
156+
ChildCometBFT->>+ChildFendermint: ABCI Call query
157+
ChildFendermint->>+ChildGateway: read-only call to GatewayGetterFacet::get_checkpoint_signatures (TBD)
158+
ChildGateway->>-ChildFendermint: MultiSig
159+
ChildFendermint->>-ChildCometBFT: MultiSig
160+
ChildCometBFT->>-Relayer: MultiSig
161+
162+
Relayer->>+ChildCometBFT: query CrossMsgs at height in quorum event
163+
ChildCometBFT->>+ChildFendermint: ABCI Call query
164+
ChildFendermint->>+ChildGateway: read-only call to GatewayGetterFacet::bottom_up_messages (TBD)
165+
ChildGateway->>-ChildFendermint: CrossMsgs
166+
ChildFendermint->>-ChildCometBFT: CrossMsgs
167+
ChildCometBFT->>-Relayer: CrossMsgs
168+
169+
Relayer->>Relayer: create Message to invoke GatewayRouterFacet::submit_bottom_up_checkpoint (TBD)
170+
Relayer->>Relayer: sign the Message with the relayer reward key
171+
Relayer->>-ParentNode: broadcast SignedMessage
172+
173+
%% Handle Checkpoint in Parent
174+
Note over ParentNode, ChildActors: Handle Checkpoint in Parent
175+
176+
ParentNode-->>ParentNode: receive block
177+
178+
ParentNode->>+ParentGateway: call GatewayRouterFacet::submit_bottom_up_checkpoint
179+
ParentGateway->>ParentGateway: load validator set at current configuration number
180+
ParentGateway->>ParentGateway: validate signatures in the checkpoint
181+
ParentGateway->>ParentGateway: validate quroum threshold was reached
182+
ParentGateway->>ParentGateway: validate cross message hash matches the checkpoint
183+
ParentGateway->>ParentGateway: update next configuration number
184+
ParentGateway->>ParentGateway: execute cross messages
185+
ParentGateway->>-ParentNode: receipt

‎docs/fendermint/diagrams/checkpointing.png‎

-283 KB
Loading

0 commit comments

Comments
 (0)