docs: make description of timeout_commit more precise (cometbft#3542)

Also, added reference to the new `FinalizeBlock` return value intended
to replace the `timeout_commit` config flag.

---

#### PR checklist

- [ ] Tests written/updated
- [ ] Changelog entry added in `.changelog` (we use
[unclog](https://github.com/informalsystems/unclog) to manage our
changelog)
- [x] Updated relevant documentation (`docs/` or `spec/`) and code
comments
- [x] Title follows the [Conventional
Commits](https://www.conventionalcommits.org/en/v1.0.0/) spec

docs/explanation/core/running-in-production.md

@@ -359,6 +359,14 @@ applications, setting it to `0` is not a problem.
 
 You can try lowering it though.
 
+**Notice** that the `timeout_commit` configuration flag was deprecated in v1.0.
+It is now up to the application to return a `next_block_delay` value upon
+[`FinalizeBlock`](https://github.com/cometbft/cometbft/blob/main/spec/abci/abci%2B%2B_methods.md#finalizeblock)
+to define how long CometBFT should wait from when it has
+committed a block until it actually starts the next height.
+Notice that this delay includes the time it takes for CometBFT and the
+application to process the committed block.
+
 - `p2p.addr_book_strict`
 
 By default, CometBFT checks whenever a peer's address is routable before

docs/references/config/config.toml.md

@@ -1728,9 +1728,17 @@ The `timeout_commit` is not a required component of the consensus algorithm,
 meaning that there are no liveness implications if it is set to `0s`.
 But it may have implications in the way the application rewards validators.
 
+Notice also that the minimum interval defined with `timeout_commit` includes
+the time that both CometBFT and the application take to process the committed block.
+
 Setting `timeout_commit` to `0s` means that the node will start the next height
 as soon as it gathers all the mandatory +2/3 precommits for a block.
 
+**Notice** that the `timeout_commit` configuration flag is **deprecated** from v1.0.
+It is now up to the application to return a `next_block_delay` value upon
+[`FinalizeBlock`](https://github.com/cometbft/cometbft/blob/main/spec/abci/abci%2B%2B_methods.md#finalizeblock)
+to define how long CometBFT should wait before starting the next height.
+
 ### consensus.double_sign_check_height
 
 How many blocks to look back to check the existence of the node's consensus votes before joining consensus.
@@ -2229,3 +2237,8 @@ a proposal from another validator and prevote `nil` due to him starting
 `timeout_propose` earlier. I.e., if Bob's `timeout_commit` is too low comparing
 to other validators, then he might miss some proposals and get slashed for
 inactivity.
+
+**Notice** that the `timeout_commit` configuration flag is **deprecated** from v1.0.
+It is now up to the application to return a `next_block_delay` value upon
+[`FinalizeBlock`](https://github.com/cometbft/cometbft/blob/main/spec/abci/abci%2B%2B_methods.md#finalizeblock)
+to define how long CometBFT should wait before starting the next height.

spec/abci/abci++_methods.md

@@ -666,14 +666,17 @@ without calling `VerifyVoteExtension` to verify it.
     * When calling `FinalizeBlock` with a block, the consensus algorithm run by CometBFT guarantees
       that at least one non-byzantine validator has run `ProcessProposal` on that block.
     * `FinalizeBlockResponse.next_block_delay` - how long CometBFT waits after
-      committing a block, before starting on the new height (this gives the
-      proposer a chance to receive some more precommits, even though it
-      already has +2/3). Set to 0 if you want a proposer to make progress as
-      soon as it has all the precommits. Previously `timeout_commit` in
-      CometBFT config. **Set to constant 1s to preserve the old (v0.34 - v1.0) behavior**.
+      committing a block, before starting the next height. This includes the
+      time the application and CometBFT take for processing the committed block.
+      In CometBFT terms, this interval gives the proposer a chance to receive
+      some more precommits, even though it already has the required 2/3+.
+      - Set to 0 if you want a proposer to make progress as soon as it has all
+        the precommits and the block is processed by the application. 
+      - Previously `timeout_commit` in CometBFT config.
+        **Set to constant 1s to preserve the old (v0.34 - v1.0) behavior**.
     * `FinalizeBlockResponse.next_block_delay` is a non-deterministic field.
       This means that each node MAY provide a different value, which is
-      supposed to depend on how long things are taking at the local node. It's
+      supposed to depend on how long processing is taking at the local node. It's
       reasonable to use real --wallclock-- time and mandate for the nodes to have
       synchronized clocks (NTP, or other; PBTS also requires this) for the
       variable delay to work properly.