Skip to content

Commit

Permalink
docs: migrate diagrams to mermaidjs (#20503)
Browse files Browse the repository at this point in the history 
Co-authored-by: Facundo Medica <[email protected]>
  • Loading branch information
@tac0turtle @facundomedica
tac0turtle and facundomedica authored Jun 3, 2024
1 parent 597fbb1 commit 61da5d1
Show file tree
Hide file tree
Showing 6 changed files with 114 additions and 179 deletions.
47 changes: 29 additions & 18 deletions docs/learn/beginner/00-app-anatomy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,31 @@ This document describes the core parts of a Cosmos SDK application, represented

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.

```text
^ +-------------------------------+ ^
| | | |
| | State-machine = Application | |
| | | | Built with Cosmos SDK
| | ^ + | |
| +----------- | ABCI | ----------+ v
| | + v | ^
| | | |
Blockchain Node | | Consensus | |
| | | |
| +-------------------------------+ | CometBFT
| | | |
| | Networking | |
| | | |
v +-------------------------------+ v
```mermaid
flowchart TD
subgraph Blockchain_Node[Blockchain Node]
subgraph SM[State-machine = Application]
direction TB
SM1[Cosmos SDK]
end
subgraph ABCI[ABCI]
direction TB
end
subgraph Consensus[Consensus]
direction TB
end
subgraph Networking[Networking]
direction TB
end
end
SM <--> ABCI
ABCI <--> Consensus
Consensus <--> Networking
Blockchain_Node -->|Includes| SM
Blockchain_Node -->|Includes| Consensus
Blockchain_Node -->|Includes| Networking
```

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).
Expand Down Expand Up @@ -112,13 +121,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L626-L63

There are two semantics around the new lifecycle method:

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

When it returns `ConsensusParamsChanged=true`, the caller must refresh the consensus parameter in the finalize context:

```
app.finalizeBlockState.ctx = app.finalizeBlockState.ctx.WithConsensusParams(app.GetConsensusParams())
```

The new ctx must be passed to all the other lifecycle methods.

### BeginBlocker and EndBlocker
Expand Down
47 changes: 7 additions & 40 deletions docs/learn/beginner/01-tx-lifecycle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,46 +163,13 @@ that receive a block proposal from the correct proposer execute the transactions
As mentioned throughout the documentation `BeginBlock`, `ExecuteTx` and `EndBlock` are called within FinalizeBlock.
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.

```text
--------------------------
| Receive Block Proposal |
--------------------------
|
v
-------------------------
| FinalizeBlock |
-------------------------
|
v
-------------------
| BeginBlock |
-------------------
|
v
--------------------
| ExecuteTx(tx0) |
| ExecuteTx(tx1) |
| ExecuteTx(tx2) |
| ExecuteTx(tx3) |
| . |
| . |
| . |
-------------------
|
v
--------------------
| EndBlock |
--------------------
|
v
-------------------------
| Consensus |
-------------------------
|
v
-------------------------
| Commit |
-------------------------
```mermaid
flowchart TD
A[Receive Block Proposal] --> B[FinalizeBlock]
B --> C[BeginBlock]
C --> D["ExecuteTx(tx0, tx1, 1x2)"]
D --> E[EndBlock]
E --> F[Commit]
```

### Transaction Execution
Expand Down
53 changes: 15 additions & 38 deletions docs/learn/beginner/03-accounts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,44 +21,21 @@ In the Cosmos SDK, an _account_ designates a pair of _public key_ `PubKey` and _

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.

```text
Account 0 Account 1 Account 2
+------------------+ +------------------+ +------------------+
| | | | | |
| Address 0 | | Address 1 | | Address 2 |
| ^ | | ^ | | ^ |
| | | | | | | | |
| | | | | | | | |
| | | | | | | | |
| + | | + | | + |
| Public key 0 | | Public key 1 | | Public key 2 |
| ^ | | ^ | | ^ |
| | | | | | | | |
| | | | | | | | |
| | | | | | | | |
| + | | + | | + |
| Private key 0 | | Private key 1 | | Private key 2 |
| ^ | | ^ | | ^ |
+------------------+ +------------------+ +------------------+
| | |
| | |
| | |
+--------------------------------------------------------------------+
|
|
+---------+---------+
| |
| Master PrivKey |
| |
+-------------------+
|
|
+---------+---------+
| |
| Mnemonic (Seed) |
| |
+-------------------+
```mermaid
graph BT
A0A[Address 0] --> A0[Account 0]
A0PK[Public key 0] --> A0A[Address 0]
A0SK[Private key 0] --> A0PK[Public key 0]
A1A[Address 1] --> A1[Account 1]
A1PK[Public key 1] --> A1A[Address 1]
A1SK[Private key 1] --> A1PK[Public key 1]
A2A[Address 2] --> A2[Account 2]
A2PK[Public key 2] --> A2A[Address 2]
A2SK[Private key 2] --> A2PK[Public key 2]
MasterPK[Master PrivKey] --> A0SK[Private key 0]
MasterPK[Master PrivKey] --> A1SK[Private key 1]
MasterPK[Master PrivKey] --> A2SK[Private key 2]
Mnemonic["Mnemonic (Seed)"] --> MasterPK[Master PrivKey]
```

In the Cosmos SDK, keys are stored and managed by using an object called a [`Keyring`](#keyring).
Expand Down
36 changes: 22 additions & 14 deletions docs/learn/intro/01-why-app-specific.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,28 @@ This document explains what application-specific blockchains are, and why develo

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.

```text
^ +-------------------------------+ ^
| | | | Built with Cosmos SDK
| | State-machine = Application | |
| | | v
| +-------------------------------+
| | | ^
Blockchain node | | Consensus | |
| | | |
| +-------------------------------+ | CometBFT
| | | |
| | Networking | |
| | | |
v +-------------------------------+ v
```mermaid
flowchart TD
subgraph Blockchain_Node[Blockchain Node]
subgraph SM[State-machine]
direction TB
SM1[Cosmos SDK]
end
subgraph Consensus[Consensus]
direction TB
end
subgraph Networking[Networking]
direction TB
end
end
SM <--> Consensus
Consensus <--> Networking
Blockchain_Node -->|Includes| SM
Blockchain_Node -->|Includes| Consensus
Blockchain_Node -->|Includes| Networking
```

## What are the shortcomings of Smart Contracts
Expand Down
55 changes: 29 additions & 26 deletions docs/learn/intro/02-sdk-app-architecture.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,20 @@ A state machine is a computer science concept whereby a machine can have multipl

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

```text
+--------+ +--------+
| | | |
| S +---------------->+ S' |
| | apply(T) | |
+--------+ +--------+
```mermaid
flowchart LR
A[S]
B[S']
A -->|"apply(T)"| B
```

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'.

```text
+--------+ +--------+
| | | |
| S +----------------------------> | S' |
| | For each T in B: apply(T) | |
+--------+ +--------+
```mermaid
flowchart LR
A[S]
B[S']
A -->|"For each T in B: apply(T)"| B
```

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.
Expand All @@ -38,20 +36,25 @@ The Cosmos SDK gives developers maximum flexibility to define the state of their

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.

```text
^ +-------------------------------+ ^
| | | | Built with Cosmos SDK
| | State-machine = Application | |
| | | v
| +-------------------------------+
| | | ^
Blockchain node | | Consensus | |
| | | |
| +-------------------------------+ | CometBFT
| | | |
| | Networking | |
| | | |
v +-------------------------------+ v
```mermaid
flowchart TD
subgraph Blockchain_Node[Blockchain Node]
subgraph SM[State-machine]
direction TB
SM1[Cosmos SDK]
end
subgraph CometBFT[CometBFT]
direction TB
Consensus
Networking
end
end
SM <--> CometBFT
Blockchain_Node -->|Includes| SM
Blockchain_Node -->|Includes| CometBFT
```

[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.
Expand Down
55 changes: 12 additions & 43 deletions docs/learn/intro/03-sdk-design.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,49 +39,18 @@ The power of the Cosmos SDK lies in its modularity. Cosmos SDK applications are

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:

```text
+
|
| Transaction relayed from the full-node's
| CometBFT engine to the node's application
| via DeliverTx
|
|
+---------------------v--------------------------+
| APPLICATION |
| |
| Using baseapp's methods: Decode the Tx, |
| extract and route the message(s) |
| |
+---------------------+--------------------------+
|
|
|
+---------------------------+
|
|
| Message routed to
| the correct module
| to be processed
|
|
+----------------+ +---------------+ +----------------+ +------v----------+
| | | | | | | |
| AUTH MODULE | | BANK MODULE | | STAKING MODULE | | GOV MODULE |
| | | | | | | |
| | | | | | | Handles message,|
| | | | | | | Updates state |
| | | | | | | |
+----------------+ +---------------+ +----------------+ +------+----------+
|
|
|
|
+--------------------------+
|
| Return result to CometBFT
| (0=Ok, 1=Err)
v
```mermaid
flowchart TD
A[Transaction relayed from the full-node's CometBFT engine to the node's application via DeliverTx] --> B[APPLICATION]
B -->|"Using baseapp's methods: Decode the Tx, extract and route the message(s)"| C[Message routed to the correct module to be processed]
C --> D1[AUTH MODULE]
C --> D2[BANK MODULE]
C --> D3[STAKING MODULE]
C --> D4[GOV MODULE]
D1 -->|Handle message, Update state| E["Return result to CometBFT (0=Ok, 1=Err)"]
D2 -->|Handle message, Update state| E["Return result to CometBFT (0=Ok, 1=Err)"]
D3 -->|Handle message, Update state| E["Return result to CometBFT (0=Ok, 1=Err)"]
D4 -->|Handle message, Update state| E["Return result to CometBFT (0=Ok, 1=Err)"]
```

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.
Expand Down

0 comments on commit 61da5d1

Please sign in to comment.