From a6cc64d0712f037faa48751dd83ed070d5339763 Mon Sep 17 00:00:00 2001 From: Andy Nogueira Date: Wed, 14 Feb 2024 06:41:17 -0500 Subject: [PATCH] docs: Fix references about DeliverTx (#2330) close: #2224 Updated documentation that reference DeliverTx. Also modified a bit some content on the Introduction page. This will need to be back ported to v0.38.x and v1.x --- .../explanation/core/running-in-production.md | 17 ++++++++--------- docs/explanation/core/subscription.md | 4 ++-- docs/explanation/introduction/README.md | 19 +++++++++---------- 3 files changed, 19 insertions(+), 21 deletions(-) diff --git a/docs/explanation/core/running-in-production.md b/docs/explanation/core/running-in-production.md index 8d95ca156c4..b772084daaa 100644 --- a/docs/explanation/core/running-in-production.md +++ b/docs/explanation/core/running-in-production.md @@ -15,17 +15,16 @@ instructions](../introduction/install.md) for details. CometBFT keeps multiple distinct databases in the `$CMTHOME/data`: - `blockstore.db`: Keeps the entire blockchain - stores blocks, - block commits, and block meta data, each indexed by height. Used to sync new + block commits, and block metadata, each indexed by height. Used to sync new peers. - `evidence.db`: Stores all verified evidence of misbehavior. -- `state.db`: Stores the current blockchain state (ie. height, validators, +- `state.db`: Stores the current blockchain state (i.e. height, validators, consensus params). Only grows if consensus params or validators change. Also used to temporarily store intermediate results during block processing. -- `tx_index.db`: Indexes txs (and their results) by tx hash and by DeliverTx result events. +- `tx_index.db`: Indexes transactions and by tx hash and height. The tx results are indexed if they are added to the `FinalizeBlock` response in the application. -By default, CometBFT will only index txs by their hash and height, not by their DeliverTx -result events. See [indexing transactions](../../guides/app-dev/indexing-transactions.md) for -details. +> By default, CometBFT will only index transactions by their hash and height, if you want the result events to be indexed, see [indexing transactions](../../guides/app-dev/indexing-transactions.md#adding-events) for +for details. Applications can expose block pruning strategies to the node operator. Please read the documentation of your application to find out more details. @@ -62,12 +61,12 @@ If your `consensus.wal` is corrupted, see [below](#wal-corruption). ### Mempool WAL -The `mempool.wal` logs all incoming txs before running CheckTx, but is +The `mempool.wal` logs all incoming transactions before running CheckTx, but is otherwise not used in any programmatic way. It's just a kind of manual safe guard. Note the mempool provides no durability guarantees - a tx sent to one or many nodes may never make it into the blockchain if those nodes crash before being able to -propose it. Clients must monitor their txs by subscribing over websockets, -polling for them, or using `/broadcast_tx_commit`. In the worst case, txs can be +propose it. Clients must monitor their transactions by subscribing over websockets, +polling for them, or using `/broadcast_tx_commit`. In the worst case, transactions can be resent from the mempool WAL manually. For the above reasons, the `mempool.wal` is disabled by default. To enable, set diff --git a/docs/explanation/core/subscription.md b/docs/explanation/core/subscription.md index 99f01f8522e..33049fccbe6 100644 --- a/docs/explanation/core/subscription.md +++ b/docs/explanation/core/subscription.md @@ -36,9 +36,9 @@ method via Websocket along with a valid query. Check out [API docs](https://docs.cometbft.com/main/rpc/) for more information on query syntax and other options. -You can also use tags, given you had included them into DeliverTx +You can also use tags, given you had included them into FinalizeBlock response, to query transaction results. See [Indexing -transactions](../../guides/app-dev/indexing-transactions.md) for details. +transactions](../../guides/app-dev/indexing-transactions.md#adding-events) for details. ## Query parameter and event type restrictions diff --git a/docs/explanation/introduction/README.md b/docs/explanation/introduction/README.md index a5f11207619..b3179b50163 100644 --- a/docs/explanation/introduction/README.md +++ b/docs/explanation/introduction/README.md @@ -193,17 +193,16 @@ response messages. The messages are specified here: [ABCI Message Types](https://github.com/cometbft/cometbft/blob/main/proto/tendermint/abci/types.proto). -The **DeliverTx** message is the work horse of the application. Each -transaction in the blockchain is delivered with this message. The +The **FinalizeBlock** message is the work horse of the application. Each +transaction in the blockchain is finalized within this message. The application needs to validate each transaction received with the -**DeliverTx** message against the current state, application protocol, -and the cryptographic credentials of the transaction. A validated -transaction then needs to update the application state — by binding a -value into a key values store, or by updating the UTXO database, for -instance. - -The **CheckTx** message is similar to **DeliverTx**, but it's only for -validating transactions. CometBFT's mempool first checks the +**FinalizeBlock** message against the current state, application protocol, +and the cryptographic credentials of the transaction. FinalizeBlock only +prepares the update to be made and does not change the state of the application. +The state change is actually committed in a later stage i.e. in commit phase. + +The **CheckTx** message is used for validating transactions. +CometBFT's mempool first checks the validity of a transaction with **CheckTx**, and only relays valid transactions to its peers. For instance, an application may check an incrementing sequence number in the transaction and return an error upon