docs: migrate diagrams to mermaidjs (#20503)
Co-authored-by: Facundo Medica <14063057+facundomedica@users.noreply.github.com>
This commit is contained in:
Marko
Facundo Medica
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user