diff --git a/docs/learn/beginner/00-app-anatomy.md b/docs/learn/beginner/00-app-anatomy.md index ce14795474dc..ae5a20062053 100644 --- a/docs/learn/beginner/00-app-anatomy.md +++ b/docs/learn/beginner/00-app-anatomy.md @@ -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). @@ -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 diff --git a/docs/learn/beginner/01-tx-lifecycle.md b/docs/learn/beginner/01-tx-lifecycle.md index 133f173008d0..03f5e9767087 100644 --- a/docs/learn/beginner/01-tx-lifecycle.md +++ b/docs/learn/beginner/01-tx-lifecycle.md @@ -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 diff --git a/docs/learn/beginner/03-accounts.md b/docs/learn/beginner/03-accounts.md index 5dccbf2f7655..eb8ff47d4fa3 100644 --- a/docs/learn/beginner/03-accounts.md +++ b/docs/learn/beginner/03-accounts.md @@ -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). diff --git a/docs/learn/intro/01-why-app-specific.md b/docs/learn/intro/01-why-app-specific.md index 53042aade64e..e34bf32707f5 100644 --- a/docs/learn/intro/01-why-app-specific.md +++ b/docs/learn/intro/01-why-app-specific.md @@ -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 diff --git a/docs/learn/intro/02-sdk-app-architecture.md b/docs/learn/intro/02-sdk-app-architecture.md index 1dcd54a78e4d..cb217da6eabf 100644 --- a/docs/learn/intro/02-sdk-app-architecture.md +++ b/docs/learn/intro/02-sdk-app-architecture.md @@ -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. diff --git a/docs/learn/intro/03-sdk-design.md b/docs/learn/intro/03-sdk-design.md index f392ec9502a9..563dc11ebab8 100644 --- a/docs/learn/intro/03-sdk-design.md +++ b/docs/learn/intro/03-sdk-design.md @@ -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.