Skip to content

Commit 61da5d1

Browse files
tac0turtlefacundomedica
tac0turtle
and
facundomedica
authored
docs: migrate diagrams to mermaidjs (#20503)
Co-authored-by: Facundo Medica <[email protected]>
1 parent 597fbb1 commit 61da5d1

6 files changed

+114
-179
lines changed

‎docs/learn/beginner/00-app-anatomy.md

+29-18
Original file line numberDiff line numberDiff line change
@@ -12,22 +12,31 @@ This document describes the core parts of a Cosmos SDK application, represented
1212

1313
The Daemon, or [Full-Node Client](../advanced/03-node.md), is the core process of a Cosmos SDK-based blockchain. Participants in the network run this process to initialize their state-machine, connect with other full-nodes, and update their state-machine as new blocks come in.
1414

15-
```text
16-
^ +-------------------------------+ ^
17-
| | | |
18-
| | State-machine = Application | |
19-
| | | | Built with Cosmos SDK
20-
| | ^ + | |
21-
| +----------- | ABCI | ----------+ v
22-
| | + v | ^
23-
| | | |
24-
Blockchain Node | | Consensus | |
25-
| | | |
26-
| +-------------------------------+ | CometBFT
27-
| | | |
28-
| | Networking | |
29-
| | | |
30-
v +-------------------------------+ v
15+
```mermaid
16+
flowchart TD
17+
subgraph Blockchain_Node[Blockchain Node]
18+
subgraph SM[State-machine = Application]
19+
direction TB
20+
SM1[Cosmos SDK]
21+
end
22+
subgraph ABCI[ABCI]
23+
direction TB
24+
end
25+
subgraph Consensus[Consensus]
26+
direction TB
27+
end
28+
subgraph Networking[Networking]
29+
direction TB
30+
end
31+
end
32+
33+
SM <--> ABCI
34+
ABCI <--> Consensus
35+
Consensus <--> Networking
36+
37+
Blockchain_Node -->|Includes| SM
38+
Blockchain_Node -->|Includes| Consensus
39+
Blockchain_Node -->|Includes| Networking
3140
```
3241

3342
The blockchain full-node presents itself as a binary, generally suffixed by `-d` for "daemon" (e.g. `appd` for `app` or `gaiad` for `gaia`). This binary is built by running a simple [`main.go`](../advanced/03-node.md#main-function) function placed in `./cmd/appd/`. This operation usually happens through the [Makefile](#dependencies-and-makefile).
@@ -112,13 +121,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L626-L63
112121

113122
There are two semantics around the new lifecycle method:
114123

115-
- It runs before the `BeginBlocker` of all modules
116-
- It can modify consensus parameters in storage, and signal the caller through the return value.
124+
* It runs before the `BeginBlocker` of all modules
125+
* It can modify consensus parameters in storage, and signal the caller through the return value.
117126

118127
When it returns `ConsensusParamsChanged=true`, the caller must refresh the consensus parameter in the finalize context:
128+
119129
```
120130
app.finalizeBlockState.ctx = app.finalizeBlockState.ctx.WithConsensusParams(app.GetConsensusParams())
121131
```
132+
122133
The new ctx must be passed to all the other lifecycle methods.
123134

124135
### BeginBlocker and EndBlocker

‎docs/learn/beginner/01-tx-lifecycle.md

+7-40
Original file line numberDiff line numberDiff line change
@@ -163,46 +163,13 @@ that receive a block proposal from the correct proposer execute the transactions
163163
As mentioned throughout the documentation `BeginBlock`, `ExecuteTx` and `EndBlock` are called within FinalizeBlock.
164164
Although every full-node operates individually and locally, the outcome is always consistent and unequivocal. This is because the state changes brought about by the messages are predictable, and the transactions are specifically sequenced in the proposed block.
165165

166-
```text
167-
--------------------------
168-
| Receive Block Proposal |
169-
--------------------------
170-
|
171-
v
172-
-------------------------
173-
| FinalizeBlock |
174-
-------------------------
175-
|
176-
v
177-
-------------------
178-
| BeginBlock |
179-
-------------------
180-
|
181-
v
182-
--------------------
183-
| ExecuteTx(tx0) |
184-
| ExecuteTx(tx1) |
185-
| ExecuteTx(tx2) |
186-
| ExecuteTx(tx3) |
187-
| . |
188-
| . |
189-
| . |
190-
-------------------
191-
|
192-
v
193-
--------------------
194-
| EndBlock |
195-
--------------------
196-
|
197-
v
198-
-------------------------
199-
| Consensus |
200-
-------------------------
201-
|
202-
v
203-
-------------------------
204-
| Commit |
205-
-------------------------
166+
```mermaid
167+
flowchart TD
168+
A[Receive Block Proposal] --> B[FinalizeBlock]
169+
B --> C[BeginBlock]
170+
C --> D["ExecuteTx(tx0, tx1, 1x2)"]
171+
D --> E[EndBlock]
172+
E --> F[Commit]
206173
```
207174

208175
### Transaction Execution

‎docs/learn/beginner/03-accounts.md

+15-38
Original file line numberDiff line numberDiff line change
@@ -21,44 +21,21 @@ In the Cosmos SDK, an _account_ designates a pair of _public key_ `PubKey` and _
2121

2222
For HD key derivation the Cosmos SDK uses a standard called [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki). The BIP32 allows users to create an HD wallet (as specified in [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)) - a set of accounts derived from an initial secret seed. A seed is usually created from a 12- or 24-word mnemonic. A single seed can derive any number of `PrivKey`s using a one-way cryptographic function. Then, a `PubKey` can be derived from the `PrivKey`. Naturally, the mnemonic is the most sensitive information, as private keys can always be re-generated if the mnemonic is preserved.
2323

24-
```text
25-
Account 0 Account 1 Account 2
26-
27-
+------------------+ +------------------+ +------------------+
28-
| | | | | |
29-
| Address 0 | | Address 1 | | Address 2 |
30-
| ^ | | ^ | | ^ |
31-
| | | | | | | | |
32-
| | | | | | | | |
33-
| | | | | | | | |
34-
| + | | + | | + |
35-
| Public key 0 | | Public key 1 | | Public key 2 |
36-
| ^ | | ^ | | ^ |
37-
| | | | | | | | |
38-
| | | | | | | | |
39-
| | | | | | | | |
40-
| + | | + | | + |
41-
| Private key 0 | | Private key 1 | | Private key 2 |
42-
| ^ | | ^ | | ^ |
43-
+------------------+ +------------------+ +------------------+
44-
| | |
45-
| | |
46-
| | |
47-
+--------------------------------------------------------------------+
48-
|
49-
|
50-
+---------+---------+
51-
| |
52-
| Master PrivKey |
53-
| |
54-
+-------------------+
55-
|
56-
|
57-
+---------+---------+
58-
| |
59-
| Mnemonic (Seed) |
60-
| |
61-
+-------------------+
24+
```mermaid
25+
graph BT
26+
A0A[Address 0] --> A0[Account 0]
27+
A0PK[Public key 0] --> A0A[Address 0]
28+
A0SK[Private key 0] --> A0PK[Public key 0]
29+
A1A[Address 1] --> A1[Account 1]
30+
A1PK[Public key 1] --> A1A[Address 1]
31+
A1SK[Private key 1] --> A1PK[Public key 1]
32+
A2A[Address 2] --> A2[Account 2]
33+
A2PK[Public key 2] --> A2A[Address 2]
34+
A2SK[Private key 2] --> A2PK[Public key 2]
35+
MasterPK[Master PrivKey] --> A0SK[Private key 0]
36+
MasterPK[Master PrivKey] --> A1SK[Private key 1]
37+
MasterPK[Master PrivKey] --> A2SK[Private key 2]
38+
Mnemonic["Mnemonic (Seed)"] --> MasterPK[Master PrivKey]
6239
```
6340

6441
In the Cosmos SDK, keys are stored and managed by using an object called a [`Keyring`](#keyring).

‎docs/learn/intro/01-why-app-specific.md

+22-14
Original file line numberDiff line numberDiff line change
@@ -12,20 +12,28 @@ This document explains what application-specific blockchains are, and why develo
1212

1313
Application-specific blockchains are blockchains customized to operate a single application. Instead of building a decentralized application on top of an underlying blockchain like Ethereum, developers build their own blockchain from the ground up. This means building a full-node client, a light-client, and all the necessary interfaces (CLI, REST, ...) to interact with the nodes.
1414

15-
```text
16-
^ +-------------------------------+ ^
17-
| | | | Built with Cosmos SDK
18-
| | State-machine = Application | |
19-
| | | v
20-
| +-------------------------------+
21-
| | | ^
22-
Blockchain node | | Consensus | |
23-
| | | |
24-
| +-------------------------------+ | CometBFT
25-
| | | |
26-
| | Networking | |
27-
| | | |
28-
v +-------------------------------+ v
15+
```mermaid
16+
flowchart TD
17+
subgraph Blockchain_Node[Blockchain Node]
18+
subgraph SM[State-machine]
19+
direction TB
20+
SM1[Cosmos SDK]
21+
end
22+
subgraph Consensus[Consensus]
23+
direction TB
24+
end
25+
subgraph Networking[Networking]
26+
direction TB
27+
end
28+
end
29+
30+
SM <--> Consensus
31+
Consensus <--> Networking
32+
33+
34+
Blockchain_Node -->|Includes| SM
35+
Blockchain_Node -->|Includes| Consensus
36+
Blockchain_Node -->|Includes| Networking
2937
```
3038

3139
## What are the shortcomings of Smart Contracts

‎docs/learn/intro/02-sdk-app-architecture.md

+29-26
Original file line numberDiff line numberDiff line change
@@ -12,22 +12,20 @@ A state machine is a computer science concept whereby a machine can have multipl
1212

1313
Given a state S and a transaction T, the state machine will return a new state S'.
1414

15-
```text
16-
+--------+ +--------+
17-
| | | |
18-
| S +---------------->+ S' |
19-
| | apply(T) | |
20-
+--------+ +--------+
15+
```mermaid
16+
flowchart LR
17+
A[S]
18+
B[S']
19+
A -->|"apply(T)"| B
2120
```
2221

2322
In practice, the transactions are bundled in blocks to make the process more efficient. Given a state S and a block of transactions B, the state machine will return a new state S'.
2423

25-
```text
26-
+--------+ +--------+
27-
| | | |
28-
| S +----------------------------> | S' |
29-
| | For each T in B: apply(T) | |
30-
+--------+ +--------+
24+
```mermaid
25+
flowchart LR
26+
A[S]
27+
B[S']
28+
A -->|"For each T in B: apply(T)"| B
3129
```
3230

3331
In a blockchain context, the state machine is deterministic. This means that if a node is started at a given state and replays the same sequence of transactions, it will always end up with the same final state.
@@ -38,20 +36,25 @@ The Cosmos SDK gives developers maximum flexibility to define the state of their
3836

3937
Thanks to the Cosmos SDK, developers just have to define the state machine, and [*CometBFT*](https://docs.cometbft.com/v1.0/explanation/introduction/) will handle replication over the network for them.
4038

41-
```text
42-
^ +-------------------------------+ ^
43-
| | | | Built with Cosmos SDK
44-
| | State-machine = Application | |
45-
| | | v
46-
| +-------------------------------+
47-
| | | ^
48-
Blockchain node | | Consensus | |
49-
| | | |
50-
| +-------------------------------+ | CometBFT
51-
| | | |
52-
| | Networking | |
53-
| | | |
54-
v +-------------------------------+ v
39+
```mermaid
40+
flowchart TD
41+
subgraph Blockchain_Node[Blockchain Node]
42+
subgraph SM[State-machine]
43+
direction TB
44+
SM1[Cosmos SDK]
45+
end
46+
subgraph CometBFT[CometBFT]
47+
direction TB
48+
Consensus
49+
Networking
50+
end
51+
end
52+
53+
SM <--> CometBFT
54+
55+
56+
Blockchain_Node -->|Includes| SM
57+
Blockchain_Node -->|Includes| CometBFT
5558
```
5659

5760
[CometBFT](https://docs.cometbft.com/v1.0/explanation/introduction/) is an application-agnostic engine that is responsible for handling the *networking* and *consensus* layers of a blockchain. In practice, this means that CometBFT is responsible for propagating and ordering transaction bytes. CometBFT relies on an eponymous Byzantine-Fault-Tolerant (BFT) algorithm to reach consensus on the order of transactions.

‎docs/learn/intro/03-sdk-design.md

+12-43
Original file line numberDiff line numberDiff line change
@@ -39,49 +39,18 @@ The power of the Cosmos SDK lies in its modularity. Cosmos SDK applications are
3939

4040
Here is a simplified view of how a transaction is processed by the application of each full-node when it is received in a valid block:
4141

42-
```text
43-
+
44-
|
45-
| Transaction relayed from the full-node's
46-
| CometBFT engine to the node's application
47-
| via DeliverTx
48-
|
49-
|
50-
+---------------------v--------------------------+
51-
| APPLICATION |
52-
| |
53-
| Using baseapp's methods: Decode the Tx, |
54-
| extract and route the message(s) |
55-
| |
56-
+---------------------+--------------------------+
57-
|
58-
|
59-
|
60-
+---------------------------+
61-
|
62-
|
63-
| Message routed to
64-
| the correct module
65-
| to be processed
66-
|
67-
|
68-
+----------------+ +---------------+ +----------------+ +------v----------+
69-
| | | | | | | |
70-
| AUTH MODULE | | BANK MODULE | | STAKING MODULE | | GOV MODULE |
71-
| | | | | | | |
72-
| | | | | | | Handles message,|
73-
| | | | | | | Updates state |
74-
| | | | | | | |
75-
+----------------+ +---------------+ +----------------+ +------+----------+
76-
|
77-
|
78-
|
79-
|
80-
+--------------------------+
81-
|
82-
| Return result to CometBFT
83-
| (0=Ok, 1=Err)
84-
v
42+
```mermaid
43+
flowchart TD
44+
A[Transaction relayed from the full-node's CometBFT engine to the node's application via DeliverTx] --> B[APPLICATION]
45+
B -->|"Using baseapp's methods: Decode the Tx, extract and route the message(s)"| C[Message routed to the correct module to be processed]
46+
C --> D1[AUTH MODULE]
47+
C --> D2[BANK MODULE]
48+
C --> D3[STAKING MODULE]
49+
C --> D4[GOV MODULE]
50+
D1 -->|Handle message, Update state| E["Return result to CometBFT (0=Ok, 1=Err)"]
51+
D2 -->|Handle message, Update state| E["Return result to CometBFT (0=Ok, 1=Err)"]
52+
D3 -->|Handle message, Update state| E["Return result to CometBFT (0=Ok, 1=Err)"]
53+
D4 -->|Handle message, Update state| E["Return result to CometBFT (0=Ok, 1=Err)"]
8554
```
8655

8756
Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* `messages` are extracted from `transactions` by `baseapp`). In general, each module declares its own `KVStore` in the `multistore` to persist the subset of the state it defines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos SDK is an open framework, some of the modules may be malicious, which means there is a need for security principles to reason about inter-module interactions. These principles are based on [object-capabilities](../advanced/10-ocap.md). In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called `keepers` that can be passed to other modules to grant a pre-defined set of capabilities.

0 commit comments

Comments
 (0)