From 5a2fe2890624e4b9776ac06ebe62586540dd2166 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 9 Dec 2024 12:26:05 +0000 Subject: [PATCH 1/3] chore: fix spelling errors (#22802) Co-authored-by: github-merge-queue <118344674+github-merge-queue@users.noreply.github.com> Co-authored-by: Julien Robert (cherry picked from commit 13e3e211a67d0ffd6aec78ad2d285986355e4df2) # Conflicts: # .github/.codespellignore # docs/architecture/adr-75-v2.md --- .github/.codespellignore | 8 +- CHANGELOG.md | 2 +- docs/architecture/adr-75-v2.md | 234 ++++++++++++++++++ .../building-modules/01-module-manager.md | 2 +- docs/build/building-modules/06-keeper.md | 2 +- docs/user/run-node/00-keyring.md | 2 +- docs/user/run-node/03-txs.md | 2 +- docs/user/run-node/04-rosetta.md | 4 +- docs/user/run-node/05-run-testnet.md | 2 +- docs/user/run-node/06-run-production.md | 2 +- x/accounts/defaults/lockup/TUTORIAL.md | 6 +- x/auth/CHANGELOG.md | 2 +- x/bank/README.md | 2 +- 13 files changed, 255 insertions(+), 15 deletions(-) create mode 100644 docs/architecture/adr-75-v2.md diff --git a/.github/.codespellignore b/.github/.codespellignore index e1e8758d0c30..50dedd06a557 100644 --- a/.github/.codespellignore +++ b/.github/.codespellignore @@ -4,4 +4,10 @@ keypair pastTime hasTables Nam -EyT \ No newline at end of file +<<<<<<< HEAD +EyT +======= +EyT +upTo +pullRequests +>>>>>>> 13e3e211a (chore: fix spelling errors (#22802)) diff --git a/CHANGELOG.md b/CHANGELOG.md index c74862123031..6a6f737eafe9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -135,7 +135,7 @@ Every module contains its own CHANGELOG.md. Please refer to the module you are i * (genutil) [#21701](https://github.com/cosmos/cosmos-sdk/pull/21701) Improved error messages for genesis validation. * (runtime) [#21704](https://github.com/cosmos/cosmos-sdk/pull/21704) Move `upgradetypes.StoreLoader` to runtime and alias it in upgrade for backward compatibility. * (sims)[#21613](https://github.com/cosmos/cosmos-sdk/pull/21613) Add sims2 framework and factory methods for simpler message factories in modules -* (modules) [#21963](https://github.com/cosmos/cosmos-sdk/pull/21963) Duplicatable metrics are no more collected in modules. They were unecessary overhead. +* (modules) [#21963](https://github.com/cosmos/cosmos-sdk/pull/21963) Duplicatable metrics are no more collected in modules. They were unnecessary overhead. * (crypto/ledger) [#22116](https://github.com/cosmos/cosmos-sdk/pull/22116) Improve error message when deriving paths using index >100 ### Bug Fixes diff --git a/docs/architecture/adr-75-v2.md b/docs/architecture/adr-75-v2.md new file mode 100644 index 000000000000..ebfce2de5e27 --- /dev/null +++ b/docs/architecture/adr-75-v2.md @@ -0,0 +1,234 @@ +# ADR 75: V2 Upgrades + +## Changelog + +* 2023-11-07: Initial Draft + +## Status + +DRAFT + +## Abstract + +V2 is a reset in the Cosmos SDK architecture. It is a complete rewrite of the SDK, with a focus on modularity, extensibility, and performance. The V2 SDK breaks apart the core SDK into smaller modular components allowing users to pick and choose the components they need for their specific use case. This document outlines the changes and migration path for users of the V1 SDK. + +## Context + +The Cosmos SDK began in 2016, at this time the software was written with the direct use case of the Cosmos Hub.Since then we have seen the SDK evolve and grow, with new features and improvements being added over time. The SDK today is used by over 100 different projects, with more users joining the ecosystem every day. This has led to a number of challenges, including: + +* The SDK is becoming increasingly complex, with many different components and dependencies. +* The SDK is becoming more difficult to maintain, with frequent breaking changes and compatibility issues. + +V2 is a complete rewrite of the Cosmos SDK, with a focus on modularity, extensibility, and performance. The goal is to make the Cosmos SDK easier to use for the various use cases that we have seen emerging in the ecosystem. + +```mermaid +graph TD + Z[CometBFT] --> A[Baseapp] + A[BaseApp] --> B[ABCI Methods] + A --> C[State Management] + A --> D[Transaction Processing] + A --> E[Query Handling] + + B --> B1[InitChain] + B --> B2[Info] + B --> B3[CheckTx] + B --> B4[PrepareProposal] + B --> B5[ProcessProposal] + B --> B6[FinalizeBlock] + B --> B7[Commit] + + C --> C1[Store] + C1 --> C2[Iavl] + + D --> D1[runTx] + D1 --> D2[Module] + + E --> E1[Query] + E1 --> D2[Module] +``` + +This is a high-level overview of Baseapp today. As we can see baseapp houses all the logic for the ABCI methods, state management, transaction processing, and query handling. This has led baseapp to be a very large monolith. + +## Alternatives + +The alternative to doing a rewrite is to spend more time cleaning up baseapp. This would not fix issues around forking the repository to make changes like we see today. Keeping the current codebase does not allow the project to progress and reduce the maintenance burden on the project. + + +## Decision + +The Decision is to rewrite the core components (baseapp, server, store) of the SDK into smaller modules. + +These components will be broken into separate go.mods. The modules consist of the following: + +* Consensus +* STF (State Transition Function) +* Server/v2 +* Store/v2 +* Runtime/v2 + +The flow of all the components was designed to be as simple as possible, and the flow is as follows: + +```mermaid +graph TD + subgraph Server + Mempool + E[Vote Extensions] + F[Prepare & Process Proposal] + Consensus + API[API] + end +Server <--> B["STF(State Transition Function)"] +B <--> C[Bank] +B <--> D[Auth] +B <--> G[Staking] +Server --> H[Storage] +H --> I[State Storage] +H --> J[State Commitment] +``` + +In the above diagram we do not mention runtime/v2 because it is the componend that is responsible for combining all the other components into a single application. + +### Consensus + +Consensus is the component that handles communication to the Consensus Engine (Networking & Consensus). The default implementation will be CometBFT, but other consensus engines can be used with v2. The goal of consensus is not to offer a consensus API to meet all needs, but a way to allow developers to swap out the server for a different consensus engine. An application developer should not assume that the cometbftserver will work with other consensus engines. + +Consensus is the component that controls the interaction with the consensus engine, concurrency and execution models. For context, there are three execution models we have identified: + +* **Immediate**: + * Immediate execution differs from what Cosmos SDK utilizes today. In CometBFT, consensus at height N is executed at height N+1. + * Immediate execution refers to coming to consensus at height N for the transactions in the same block. +* **Optimistic** + * Optimistic execution means different things to different applications. The way we imagine it working is that consensus may not be made on every block. Instead consensus is made after execution. This design favors a fast chain as it will not slow down for execution until the optimistic window may be exceeded. +* **Delayed** + * Delayed execution is the default execution model in CometBFT. Consensus is made after execution, but the execution may be delayed until the next block. + +The consensus server is responsible for handling the execution model of the state machine. The state machine executes transactions when it is told, it is unaware of the execution model. + +Since consensus servers can be swapped there are certain features features specific to consensus engines need to be implemented in the server. In the CometBFT server we have implemented the following features: + +* Mempool +* Prepare & Process Proposal +* Vote Extensions +* Snapshots + +If another consensus server would like to utilize the above features they can be copied or implemented in the server. + +```mermaid +graph TD + subgraph Consensus + Mempool + E[Vote Extensions] + F[Prepare & Process Proposal] + end +Consensus <-->|ABCI| A[CometBFT] +``` + +:::Note +ABCI, Vote Extensions, and Prepare & Process Proposal are primitives of cometbft, V2 is not tied to these features, teams do not have to adhere to them if they implement their own consensus engine. +::: + +### State Transition Function + +The state transition function is the component that handles the execution of transactions. It is responsible for calling the correct message handler for the transaction. The state transition function is stateless, it is handed a read only view of state and returns state changes, the changes returned can be handled by consensus in anyway needed. + +The state transition function interface is simple and meant to be as light weight as possible. This is the only interface that is required to be implemented by bespoke consensus engines. + +```mermaid +graph TD + subgraph STF[State Transition Function] + BR --> DB + subgraph DB[DeliverBlock] + PB[PreBlock] + BB[BeginBlock] + DT["Deliver Transaction(s)"] + EB[EndBlock] + end + BR[BlockRequest] + Q[Query] + S[Simulate] + VT[Validate TX] + end + C -->|Decoded Transactions| STF + DBR --> STF + STF --> |ChangeSets, Events, Transaction Results| C2 + C2 -->|Commit To DB| D + + C[Consensus] + C2[Consensus] + D[DataBase] + DBR[DataBase Reader] +``` + +State Transition function interface: + +```go +type StateTransitionFunction[T transaction.Tx] interface { + // DeliverBlock executes a block of transactions. + DeliverBlock( + ctx context.Context, + block *server.BlockRequest[T], + state store.ReaderMap, + ) (blockResult *server.BlockResponse, newState store.WriterMap, err error) + + // ValidateTx validates a transaction. + ValidateTx( + ctx context.Context, + state store.ReaderMap, + gasLimit uint64, + tx T, + ) server.TxResult + + // Simulate executes a transaction in simulation mode. + Simulate( + ctx context.Context, + state store.ReaderMap, + gasLimit uint64, + tx T, + ) (server.TxResult, store.WriterMap) + + // Query executes a query on the application. + Query( + ctx context.Context, + state store.ReaderMap, + gasLimit uint64, + req transaction.Msg, + ) (transaction.Msg, error) +} +``` + +## Consequences + +The design of the node comes with a number of tradeoffs. + +* Maintenance cost can be the same as existing Baseapp as handling many go.mods is a overhead. +* Modularity means different layers of abstractions, abstractions always have a cost. + +### Backwards Compatibility + +The state machine was made to not affect modules that are not using the state transition function. If a user would like to migrate to v2 they will need to migrate to `appmodule.Environment` from `sdk.Context`. `sdk.Context` is a struct which is a global in the state machine, this design limits the concurrency. + +V2 will have a breaking changes in regards to how CometBFT handles certain fields in ABCI. Previously, the Cosmos SDK panicked and recovered in the case of out of gas, providing an error to CometBFT which we do not return in the new design. + +V2 only works with `Store/v2`, `IAVL V1` can be used with `Store/v2`. This allows chains to continue with existing databases. There will be a migration happening to convert the database to the separation of Storage and Commitment. Once the migration is completed the state machine will query information from the rawDB unless otherwise specified. + +### Positive + +* Ability to add new features to the SDK without forking the entire repository. +* Ability to create custom node configurations. +* Reduced maintenance cost burden. +* State machine is more performant. +* Isolated components allow for easier testing. +* Allow the team to delete a lot of code in `github.com/cosmos/cosmos-sdk`. + +### Negative + +* Modularity and abstractions can be a burden. + + +## Further Discussions + +* After reducing the feature set of Cosmos SDK, we can more easily look into rewriting the core into rust. This is dependent on crosslang. + +## References + +* {reference link} diff --git a/docs/build/building-modules/01-module-manager.md b/docs/build/building-modules/01-module-manager.md index 9e6694ec3327..a0e0035f17eb 100644 --- a/docs/build/building-modules/01-module-manager.md +++ b/docs/build/building-modules/01-module-manager.md @@ -44,7 +44,7 @@ The `AppModule` interface exists to define inter-dependent module methods. Many The usage of extension interfaces allows modules to define only the functionalities they need. For example, a module that does not need an `EndBlock` does not need to define the `HasEndBlocker` interface and thus the `EndBlock` method. `AppModule` and `AppModuleGenesis` are voluntarily small interfaces, that can take advantage of the `Module` patterns without having to define many placeholder functions. :::note legacy -Prior to the introduction of the `cosmossdk.io/core` package the interfaces were defined in the `types/module` package of the Cosmos SDK. Not all interfaces have been migrated to core. Those legacy interfaces are still supported for backward compatability, but aren't described in this document and should not be used in new modules. +Prior to the introduction of the `cosmossdk.io/core` package the interfaces were defined in the `types/module` package of the Cosmos SDK. Not all interfaces have been migrated to core. Those legacy interfaces are still supported for backward compatibility, but aren't described in this document and should not be used in new modules. ::: diff --git a/docs/build/building-modules/06-keeper.md b/docs/build/building-modules/06-keeper.md index deb6727842a0..23a221fb19c0 100644 --- a/docs/build/building-modules/06-keeper.md +++ b/docs/build/building-modules/06-keeper.md @@ -82,4 +82,4 @@ State management is recommended to be done via [Collections](../packages/collect In the Cosmos SDK, it is crucial to be methodical and selective when managing state within a module, as improper state management can lead to inefficiency, security risks, and scalability issues. Not all data belongs in the on-chain state; it's important to store only essential blockchain data that needs to be verified by consensus. Storing unnecessary information, especially client-side data, can bloat the state and slow down performance. Instead, developers should focus on using an off-chain database to handle supplementary data, extending the API as needed. This approach minimizes on-chain complexity, optimizes resource usage, and keeps the blockchain state lean and efficient, ensuring scalability and smooth operations. -The Cosmos SDK leverages Protocol Buffers (protobuf) for efficient state management, providing a well-structured, binary encoding format that ensures compatibility and performance across different modules. The SDK’s recommended approach for managing state is through the [collections package](../pacakges/02-collections.md), which simplifies state handling by offering predefined data structures like maps and indexed sets, reducing the complexity of managing raw state data. While users can opt for custom encoding schemes if they need more flexibility or have specialized requirements, they should be aware that such custom implementations may not integrate seamlessly with indexers that decode state data on the fly. This could lead to challenges in data retrieval, querying, and interoperability, making protobuf a safer and more future-proof choice for most use cases. +The Cosmos SDK leverages Protocol Buffers (protobuf) for efficient state management, providing a well-structured, binary encoding format that ensures compatibility and performance across different modules. The SDK’s recommended approach for managing state is through the [collections package](../packages/02-collections.md), which simplifies state handling by offering predefined data structures like maps and indexed sets, reducing the complexity of managing raw state data. While users can opt for custom encoding schemes if they need more flexibility or have specialized requirements, they should be aware that such custom implementations may not integrate seamlessly with indexers that decode state data on the fly. This could lead to challenges in data retrieval, querying, and interoperability, making protobuf a safer and more future-proof choice for most use cases. diff --git a/docs/user/run-node/00-keyring.md b/docs/user/run-node/00-keyring.md index b4a2020068fe..f5f20daf868a 100644 --- a/docs/user/run-node/00-keyring.md +++ b/docs/user/run-node/00-keyring.md @@ -8,7 +8,7 @@ sidebar_position: 1 This document describes how to configure and use the keyring and its various backends for an [**application**](../../learn/beginner/00-app-anatomy.md). ::: -The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage. +The keyring holds the private/public key pairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage. ## Available backends for the keyring diff --git a/docs/user/run-node/03-txs.md b/docs/user/run-node/03-txs.md index 106f02e8e8e8..f459acb88014 100644 --- a/docs/user/run-node/03-txs.md +++ b/docs/user/run-node/03-txs.md @@ -269,7 +269,7 @@ func sendTx() error { ### Broadcasting a Transaction -The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the CometBFT RPC is also posible. An overview of the differences between these methods is exposed [here](../../learn/advanced/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method. +The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the CometBFT RPC is also possible. An overview of the differences between these methods is exposed [here](../../learn/advanced/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method. ```go import ( diff --git a/docs/user/run-node/04-rosetta.md b/docs/user/run-node/04-rosetta.md index de74d9898b0c..ec983f2b6fe3 100644 --- a/docs/user/run-node/04-rosetta.md +++ b/docs/user/run-node/04-rosetta.md @@ -54,7 +54,7 @@ An implementation example can be found in `simapp` package. To run Rosetta in your application CLI, use the following command: -> **Note:** if using the native approach, add your node name before any rosetta comand. +> **Note:** if using the native approach, add your node name before any rosetta command. ```shell rosetta --help @@ -74,7 +74,7 @@ rosetta ## Plugins - Multi chain connections -Rosetta will try to reflect the node types trough reflection over the node gRPC endpoints, there may be cases were this approach is not enough. It is possible to extend or implement the required types easily trough plugins. +Rosetta will try to reflect the node types through reflection over the node gRPC endpoints, there may be cases were this approach is not enough. It is possible to extend or implement the required types easily through plugins. To use Rosetta over any chain, it is required to set up prefixes and registering zone specific interfaces through plugins. diff --git a/docs/user/run-node/05-run-testnet.md b/docs/user/run-node/05-run-testnet.md index c2b5da598186..9200042e79e1 100644 --- a/docs/user/run-node/05-run-testnet.md +++ b/docs/user/run-node/05-run-testnet.md @@ -34,7 +34,7 @@ The default output directory is a relative `.testnets` directory. Let's take a l ### gentxs -The `gentxs` directory includes a genesis transaction for each validator node. Each file includes a JSON encoded genesis transaction used to register a validator node at the time of genesis. The genesis transactions are added to the `genesis.json` file within each node directory during the initilization process. +The `gentxs` directory includes a genesis transaction for each validator node. Each file includes a JSON encoded genesis transaction used to register a validator node at the time of genesis. The genesis transactions are added to the `genesis.json` file within each node directory during the initialization process. ### nodes diff --git a/docs/user/run-node/06-run-production.md b/docs/user/run-node/06-run-production.md index 807ceea56efc..f2d0dbee90a8 100644 --- a/docs/user/run-node/06-run-production.md +++ b/docs/user/run-node/06-run-production.md @@ -196,7 +196,7 @@ tmkms softsign import $HOME/tmkms/config/secrets/priv_validator_key.json $HOME/t At this point, it is necessary to delete the `priv_validator_key.json` from the validator node and the tmkms node. Since the key has been imported into tmkms (above) it is no longer necessary on the nodes. The key can be safely stored offline. -4. Modifiy the `tmkms.toml`. +4. Modify the `tmkms.toml`. ```bash vim $HOME/tmkms/config/tmkms.toml diff --git a/x/accounts/defaults/lockup/TUTORIAL.md b/x/accounts/defaults/lockup/TUTORIAL.md index f8ff4bdbee43..507679daf549 100644 --- a/x/accounts/defaults/lockup/TUTORIAL.md +++ b/x/accounts/defaults/lockup/TUTORIAL.md @@ -29,7 +29,7 @@ simd keys add owner Normally the creator must have enough token to grant to the lockup account during the lockup account init process. The owner wallet should be associated with the individual that the creator want to grant the fund to. Now, the creator can craft the lockup account init messages. This message depend on what type of lockup account the creator want to create. -For continous, delayed, permanent locking account: +For continuous, delayed, permanent locking account: ```json { @@ -40,7 +40,7 @@ For continous, delayed, permanent locking account: ``` :::info -`start_time` is only needed for continous locking account init process. For the other two, you dont have to set it in. Error will returned if `start_time` is not provided when creating continous locking account* +`start_time` is only needed for continuous locking account init process. For the other two, you dont have to set it in. Error will returned if `start_time` is not provided when creating continuous locking account* ::: For periodic locking account: @@ -215,7 +215,7 @@ simd tx accounts query $querycontents The query request type url for this query is `cosmos.accounts.defaults.lockup.QueryLockupAccountInfoRequest`. And query json file can be an empty object since `QueryLockupAccountInfoRequest` does not required an input. -Account informations including: +Account information including: * original locked amount diff --git a/x/auth/CHANGELOG.md b/x/auth/CHANGELOG.md index d0b1ca0509bb..18d99ca40859 100644 --- a/x/auth/CHANGELOG.md +++ b/x/auth/CHANGELOG.md @@ -60,7 +60,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ * [#18817](https://github.com/cosmos/cosmos-sdk/pull/18817) SigVerification, GasConsumption, IncreaseSequence ante decorators have all been joined into one SigVerification decorator. Gas consumption during TX validation flow has reduced. * [#19093](https://github.com/cosmos/cosmos-sdk/pull/19093) SetPubKeyDecorator was merged into SigVerification, gas consumption is almost halved for a simple tx. * [#19535](https://github.com/cosmos/cosmos-sdk/pull/19535) Remove vesting account creation when the chain is running. The accounts module is required for creating [#vesting accounts](../accounts/defaults/lockup/README.md) on a running chain. -* [#21688](https://github.com/cosmos/cosmos-sdk/pull/21688) Allow x/accounts to be queriable from the `AccountInfo` and `Account` gRPC endpoints +* [#21688](https://github.com/cosmos/cosmos-sdk/pull/21688) Allow x/accounts to be queryable from the `AccountInfo` and `Account` gRPC endpoints * [#21820](https://github.com/cosmos/cosmos-sdk/pull/21820) Allow x/auth `BaseAccount` to migrate to a `x/accounts` via the new `MsgMigrateAccount`. ### Bug Fixes diff --git a/x/bank/README.md b/x/bank/README.md index f6f77f1f947e..fc6c39a9183a 100644 --- a/x/bank/README.md +++ b/x/bank/README.md @@ -589,7 +589,7 @@ The bank module contains the following parameters ### SendEnabled -SendEnabled is depreacted and only kept for backward compatibility. For genesis, use the newly added send_enabled field in the genesis object. Storage, lookup, and manipulation of this information is now in the keeper. +SendEnabled is deprecated and only kept for backward compatibility. For genesis, use the newly added send_enabled field in the genesis object. Storage, lookup, and manipulation of this information is now in the keeper. ### DefaultSendEnabled From d33d157f7be822249ddc7b152355bf32dd84d72a Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Mon, 9 Dec 2024 13:57:50 +0100 Subject: [PATCH 2/3] Delete docs/architecture/adr-75-v2.md --- docs/architecture/adr-75-v2.md | 234 --------------------------------- 1 file changed, 234 deletions(-) delete mode 100644 docs/architecture/adr-75-v2.md diff --git a/docs/architecture/adr-75-v2.md b/docs/architecture/adr-75-v2.md deleted file mode 100644 index ebfce2de5e27..000000000000 --- a/docs/architecture/adr-75-v2.md +++ /dev/null @@ -1,234 +0,0 @@ -# ADR 75: V2 Upgrades - -## Changelog - -* 2023-11-07: Initial Draft - -## Status - -DRAFT - -## Abstract - -V2 is a reset in the Cosmos SDK architecture. It is a complete rewrite of the SDK, with a focus on modularity, extensibility, and performance. The V2 SDK breaks apart the core SDK into smaller modular components allowing users to pick and choose the components they need for their specific use case. This document outlines the changes and migration path for users of the V1 SDK. - -## Context - -The Cosmos SDK began in 2016, at this time the software was written with the direct use case of the Cosmos Hub.Since then we have seen the SDK evolve and grow, with new features and improvements being added over time. The SDK today is used by over 100 different projects, with more users joining the ecosystem every day. This has led to a number of challenges, including: - -* The SDK is becoming increasingly complex, with many different components and dependencies. -* The SDK is becoming more difficult to maintain, with frequent breaking changes and compatibility issues. - -V2 is a complete rewrite of the Cosmos SDK, with a focus on modularity, extensibility, and performance. The goal is to make the Cosmos SDK easier to use for the various use cases that we have seen emerging in the ecosystem. - -```mermaid -graph TD - Z[CometBFT] --> A[Baseapp] - A[BaseApp] --> B[ABCI Methods] - A --> C[State Management] - A --> D[Transaction Processing] - A --> E[Query Handling] - - B --> B1[InitChain] - B --> B2[Info] - B --> B3[CheckTx] - B --> B4[PrepareProposal] - B --> B5[ProcessProposal] - B --> B6[FinalizeBlock] - B --> B7[Commit] - - C --> C1[Store] - C1 --> C2[Iavl] - - D --> D1[runTx] - D1 --> D2[Module] - - E --> E1[Query] - E1 --> D2[Module] -``` - -This is a high-level overview of Baseapp today. As we can see baseapp houses all the logic for the ABCI methods, state management, transaction processing, and query handling. This has led baseapp to be a very large monolith. - -## Alternatives - -The alternative to doing a rewrite is to spend more time cleaning up baseapp. This would not fix issues around forking the repository to make changes like we see today. Keeping the current codebase does not allow the project to progress and reduce the maintenance burden on the project. - - -## Decision - -The Decision is to rewrite the core components (baseapp, server, store) of the SDK into smaller modules. - -These components will be broken into separate go.mods. The modules consist of the following: - -* Consensus -* STF (State Transition Function) -* Server/v2 -* Store/v2 -* Runtime/v2 - -The flow of all the components was designed to be as simple as possible, and the flow is as follows: - -```mermaid -graph TD - subgraph Server - Mempool - E[Vote Extensions] - F[Prepare & Process Proposal] - Consensus - API[API] - end -Server <--> B["STF(State Transition Function)"] -B <--> C[Bank] -B <--> D[Auth] -B <--> G[Staking] -Server --> H[Storage] -H --> I[State Storage] -H --> J[State Commitment] -``` - -In the above diagram we do not mention runtime/v2 because it is the componend that is responsible for combining all the other components into a single application. - -### Consensus - -Consensus is the component that handles communication to the Consensus Engine (Networking & Consensus). The default implementation will be CometBFT, but other consensus engines can be used with v2. The goal of consensus is not to offer a consensus API to meet all needs, but a way to allow developers to swap out the server for a different consensus engine. An application developer should not assume that the cometbftserver will work with other consensus engines. - -Consensus is the component that controls the interaction with the consensus engine, concurrency and execution models. For context, there are three execution models we have identified: - -* **Immediate**: - * Immediate execution differs from what Cosmos SDK utilizes today. In CometBFT, consensus at height N is executed at height N+1. - * Immediate execution refers to coming to consensus at height N for the transactions in the same block. -* **Optimistic** - * Optimistic execution means different things to different applications. The way we imagine it working is that consensus may not be made on every block. Instead consensus is made after execution. This design favors a fast chain as it will not slow down for execution until the optimistic window may be exceeded. -* **Delayed** - * Delayed execution is the default execution model in CometBFT. Consensus is made after execution, but the execution may be delayed until the next block. - -The consensus server is responsible for handling the execution model of the state machine. The state machine executes transactions when it is told, it is unaware of the execution model. - -Since consensus servers can be swapped there are certain features features specific to consensus engines need to be implemented in the server. In the CometBFT server we have implemented the following features: - -* Mempool -* Prepare & Process Proposal -* Vote Extensions -* Snapshots - -If another consensus server would like to utilize the above features they can be copied or implemented in the server. - -```mermaid -graph TD - subgraph Consensus - Mempool - E[Vote Extensions] - F[Prepare & Process Proposal] - end -Consensus <-->|ABCI| A[CometBFT] -``` - -:::Note -ABCI, Vote Extensions, and Prepare & Process Proposal are primitives of cometbft, V2 is not tied to these features, teams do not have to adhere to them if they implement their own consensus engine. -::: - -### State Transition Function - -The state transition function is the component that handles the execution of transactions. It is responsible for calling the correct message handler for the transaction. The state transition function is stateless, it is handed a read only view of state and returns state changes, the changes returned can be handled by consensus in anyway needed. - -The state transition function interface is simple and meant to be as light weight as possible. This is the only interface that is required to be implemented by bespoke consensus engines. - -```mermaid -graph TD - subgraph STF[State Transition Function] - BR --> DB - subgraph DB[DeliverBlock] - PB[PreBlock] - BB[BeginBlock] - DT["Deliver Transaction(s)"] - EB[EndBlock] - end - BR[BlockRequest] - Q[Query] - S[Simulate] - VT[Validate TX] - end - C -->|Decoded Transactions| STF - DBR --> STF - STF --> |ChangeSets, Events, Transaction Results| C2 - C2 -->|Commit To DB| D - - C[Consensus] - C2[Consensus] - D[DataBase] - DBR[DataBase Reader] -``` - -State Transition function interface: - -```go -type StateTransitionFunction[T transaction.Tx] interface { - // DeliverBlock executes a block of transactions. - DeliverBlock( - ctx context.Context, - block *server.BlockRequest[T], - state store.ReaderMap, - ) (blockResult *server.BlockResponse, newState store.WriterMap, err error) - - // ValidateTx validates a transaction. - ValidateTx( - ctx context.Context, - state store.ReaderMap, - gasLimit uint64, - tx T, - ) server.TxResult - - // Simulate executes a transaction in simulation mode. - Simulate( - ctx context.Context, - state store.ReaderMap, - gasLimit uint64, - tx T, - ) (server.TxResult, store.WriterMap) - - // Query executes a query on the application. - Query( - ctx context.Context, - state store.ReaderMap, - gasLimit uint64, - req transaction.Msg, - ) (transaction.Msg, error) -} -``` - -## Consequences - -The design of the node comes with a number of tradeoffs. - -* Maintenance cost can be the same as existing Baseapp as handling many go.mods is a overhead. -* Modularity means different layers of abstractions, abstractions always have a cost. - -### Backwards Compatibility - -The state machine was made to not affect modules that are not using the state transition function. If a user would like to migrate to v2 they will need to migrate to `appmodule.Environment` from `sdk.Context`. `sdk.Context` is a struct which is a global in the state machine, this design limits the concurrency. - -V2 will have a breaking changes in regards to how CometBFT handles certain fields in ABCI. Previously, the Cosmos SDK panicked and recovered in the case of out of gas, providing an error to CometBFT which we do not return in the new design. - -V2 only works with `Store/v2`, `IAVL V1` can be used with `Store/v2`. This allows chains to continue with existing databases. There will be a migration happening to convert the database to the separation of Storage and Commitment. Once the migration is completed the state machine will query information from the rawDB unless otherwise specified. - -### Positive - -* Ability to add new features to the SDK without forking the entire repository. -* Ability to create custom node configurations. -* Reduced maintenance cost burden. -* State machine is more performant. -* Isolated components allow for easier testing. -* Allow the team to delete a lot of code in `github.com/cosmos/cosmos-sdk`. - -### Negative - -* Modularity and abstractions can be a burden. - - -## Further Discussions - -* After reducing the feature set of Cosmos SDK, we can more easily look into rewriting the core into rust. This is dependent on crosslang. - -## References - -* {reference link} From 8eaba6f01fdaf342401f711ab16b570f93641942 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Mon, 9 Dec 2024 13:58:08 +0100 Subject: [PATCH 3/3] Fix merge conflict in .codespellignore file --- .github/.codespellignore | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/.codespellignore b/.github/.codespellignore index 50dedd06a557..575d88ca6955 100644 --- a/.github/.codespellignore +++ b/.github/.codespellignore @@ -4,10 +4,6 @@ keypair pastTime hasTables Nam -<<<<<<< HEAD -EyT -======= EyT upTo pullRequests ->>>>>>> 13e3e211a (chore: fix spelling errors (#22802))