docs: Fix references about DeliverTx (cometbft#2330)

close: cometbft#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
fabiotudone-da · Feb 14, 2024 · a6cc64d · a6cc64d
1 parent b3e1499
commit a6cc64d
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 21 deletions.
diff --git 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
@@ -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
@@ -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