cometbft · jmalicevic · Mar 6, 2023 · Mar 6, 2023 · Mar 6, 2023
diff --git a/spec/abci/abci++_app_requirements.md b/spec/abci/abci++_app_requirements.md
@@ -23,18 +23,18 @@ returns via `ResponsePrepareProposal` to CometBFT, also known as the prepared pr
 
 Process *p*'s prepared proposal can differ in two different rounds where *p* is the proposer.
 
-* Requirement 1 [`PrepareProposal`, timeliness]: If the network is in a synchronous period while processes 
-  *p* and *q* are in *r<sub>p</sub>*,
+* Requirement 1 [`PrepareProposal`, timeliness]: If *p*'s Application fully executes prepared blocks in
+  `PrepareProposal` and the network is in a synchronous period while processes *p* and *q* are in *r<sub>p</sub>*,
   then the value of *TimeoutPropose* at *q* must be such that *q*'s propose timer does not time out
   (which would result in *q* prevoting `nil` in *r<sub>p</sub>*).
 
-`PrepareProposal` stands on CometBFT's critical path. Thus,
+Full execution of blocks at `PrepareProposal` time stands on CometBFT's critical path. Thus,
 Requirement 1 ensures the Application or operator will set a value for `TimeoutPropose` such that the time it takes
-to fully execute `PrepareProposal` does not interfere with CometBFT's propose timer.
-Note that violation of Requirement 1 may just lead to further rounds, but will not compromise correctness.
-
-Requirement 1 is particularly important if *p*'s Application fully executes prepared blocks in `PrepareProposal`
-as a form of optimistic execution.
+to fully execute blocks in `PrepareProposal` does not interfere with CometBFT's propose timer.
+Note that the violation of Requirement 1 may lead to further rounds, but will not 
+compromise liveness because even though `TimeoutPropose` is used as the initial
+value for proposal timeouts, CometBFT will be dynamically adjust these timeouts
+such that they will eventually be enough for completing `PrepareProposal`.
 
 * Requirement 2 [`PrepareProposal`, tx-size]: When *p*'s Application calls `ResponsePrepareProposal`, the
   total size in bytes of the transactions returned does not exceed `RequestPrepareProposal.max_tx_bytes`.
@@ -113,7 +113,7 @@ extensions will be discarded.
 
 * Requirement 8 [`VerifyVoteExtension`, determinism-2]: For any two correct processes *p* and *q*,
   and any arbitrary vote extension *e*, and any arbitrary block *w*,
-  if both *p* and *q*'s CometBFT calls `RequestVerifyVoteExtension` on *e* and *w* at height *h*,
+  if *p*'s (resp. *q*'s) CometBFT calls `RequestVerifyVoteExtension` on *e* and *w* at height *h*,
   then *p*'s Application accepts *e* if and only if *q*'s Application accepts *e*.
   Note that this requirement follows from Requirement 7 and the Agreement property of consensus.
 
@@ -135,7 +135,7 @@ As a general rule, `VerifyVoteExtension` SHOULD always accept the vote extension
 and any vote extension *e* that *p* received at height *h*, the computation of
 *s<sub>p,h</sub>* does not depend on *e*.
 
-The call of correct process *p* to `RequestFinalizeBlock` at height *h*, with block *v<sub>p,h</sub>*
+The call to correct process *p*'s `RequestFinalizeBlock` at height *h*, with block *v<sub>p,h</sub>*
 passed as parameter, creates state *s<sub>p,h</sub>*.
 Additionally, *p*'s `FinalizeBlock` creates a set of transaction results *T<sub>p,h</sub>*.
 
@@ -207,34 +207,32 @@ still received in sequence.
 #### FinalizeBlock
 
 When the consensus algorithm decides on a block, CometBFT uses `FinalizeBlock` to send the
-decided block's data to the Application, which uses it to transition its state, but not persist it;
-persisting will be done during `Commit`.
+decided block's data to the Application, which uses it to transition its state, but MUST NOT persist it;
+persisting MUST be done during `Commit`.
+
+The Application must remember the latest height from which it
+has run a successful `Commit` so that it can tell CometBFT where to
+pick up from when it recovers from a crash. See information on the Handshake
+[here](#crash-recovery).
 
 #### Commit
 
-After the Application returns from `FinalizeBlock` and before invoking `Commit`, 
-CometBFT locks the mempool and flushes the mempool connection. This ensures that
+The Application should persist its state during `Commit`, before returning from it.
+
+Before invoking `Commit`, CometBFT locks the mempool and flushes the mempool connection. This ensures that
 no new messages
-will be received on the mempool connection during `Commit`, providing an opportunity to safely
+will be received on the mempool connection during this processing step, providing an opportunity to safely
 update all four
 connection states to the latest committed state at the same time.
-When `Commit` returns, CometBFT unlocks the mempool.
-
-The Application should persist its state during `Commit`, before returning from it.
-
-The Application must remember the latest height from which it
-has run a successful `Commit` so that it can tell CometBFT where to
-pick up from when it recovers from a crash. See information on the Handshake
-[here](#crash-recovery).
 
+When `Commit` returns, CometBFT unlocks the mempool.
 
-> **Warning**    
-> if the ABCI app logic processing the `Commit` message sends a
-   `/broadcast_tx_sync` or `/broadcast_tx` and waits for the response
-   before proceeding, it will deadlock. Executing `broadcast_tx` calls
-   involves acquiring the mempool lock that CometBFT holds during the `Commit` call.
-   Synchronous mempool-related calls must be avoided as part of the sequential logic of the
-   `Commit` function.
+WARNING: if the ABCI app logic processing the `Commit` message sends a
+`/broadcast_tx_sync` or `/broadcast_tx` and waits for the response
+before proceeding, it will deadlock. Executing `broadcast_tx` calls
+involves acquiring the mempool lock that CometBFT holds during the `Commit` call.
+Synchronous mempool-related calls must be avoided as part of the sequential logic of the
+`Commit` function.
 
 #### Candidate States
 
@@ -317,7 +315,7 @@ Finally, after re-checking transactions in the mempool, CometBFT will unlock
 the mempool connection. New transactions are once again able to be processed through `CheckTx`.
 
 Note that `CheckTx` is just a weak filter to keep invalid transactions out of the mempool and,
-utimately, ouf of the blockchain.
+ultimately, ouf of the blockchain.
 Since the transaction cannot be guaranteed to be checked against the exact same state as it
 will be executed as part of a (potential) decided block, `CheckTx` shouldn't check *everything*
 that affects the transaction's validity, in particular those checks whose validity may depend on
@@ -353,7 +351,7 @@ after the full block has been processed and the state committed to disk.
 
 The Snapshot Connection is used to serve state sync snapshots for other nodes
 and/or restore state sync snapshots to a local node being bootstrapped.
-Snapshop management is optional: an Application may choose not to implement it.
+Snapshot management is optional: an Application may choose not to implement it.
 
 For more information, see Section [State Sync](#state-sync).
 
@@ -362,7 +360,7 @@ For more information, see Section [State Sync](#state-sync).
 The Application is expected to return a list of
 [`ExecTxResult`](./abci%2B%2B_methods.md#exectxresult) in
 [`ResponseFinalizeBlock`](./abci%2B%2B_methods.md#finalizeblock). The list of transaction
-results must respect the same order as the list of transactions delivered via
+results MUST respect the same order as the list of transactions delivered via
 [`RequestFinalizeBlock`](./abci%2B%2B_methods.md#finalizeblock).
 This section discusses the fields inside this structure, along with the fields in
 [`ResponseCheckTx`](./abci%2B%2B_methods.md#checktx),
@@ -643,7 +641,7 @@ parameter.
 
 The `Vote` timeout does not begin until a quorum of votes has been received.
 Once a quorum of votes has been seen and this timeout elapses, Tendermint will
-procced to the next step of the consensus algorithm. If Tendermint receives
+proceed to the next step of the consensus algorithm. If Tendermint receives
 all of the remaining votes before the end of the timeout, it will proceed
 to the next step immediately.
 
@@ -682,7 +680,7 @@ include the vote extensions from height `H`. For all heights after `H`
 
 * vote extensions cannot be disabled,
 * they are mandatory: all precommit messages sent MUST have an extension
-  attached. Nevetheless, the application MAY provide 0-length
+  attached. Nevertheless, the application MAY provide 0-length
   extensions.
 
 Must always be set to a future height. Once set to a value different from
@@ -812,9 +810,9 @@ implementation of
 
 On startup, CometBFT calls the `Info` method on the Info Connection to get the latest
 committed state of the app. The app MUST return information consistent with the
-last block it succesfully completed Commit for.
+last block it successfully completed Commit for.
 
-If the app succesfully committed block H, then `last_block_height = H` and `last_block_app_hash = <hash returned by Commit for block H>`. If the app
+If the app successfully committed block H, then `last_block_height = H` and `last_block_app_hash = <hash returned by Commit for block H>`. If the app
 failed during the Commit of block H, then `last_block_height = H-1` and
 `last_block_app_hash = <hash returned by Commit for block H-1, which is the hash in the header of block H>`.
 
@@ -825,7 +823,7 @@ the app.
 storeBlockHeight = height of the last block CometBFT saw a commit for
 stateBlockHeight = height of the last block for which CometBFT completed all
     block processing and saved all ABCI results to disk
-appBlockHeight = height of the last block for which ABCI app succesfully
+appBlockHeight = height of the last block for which ABCI app successfully
     completed Commit
 
 ```
@@ -869,7 +867,7 @@ If `appBlockHeight == stateBlockHeight`,
 This happens if we crashed before the app finished Commit
 
 If `appBlockHeight == storeBlockHeight`
-    update the state using the saved ABCI responses but dont run the block against the real app.
+    update the state using the saved ABCI responses but don't run the block against the real app.
 This happens if we crashed after the app finished Commit but before CometBFT saved the state.
 
 ### State Sync

diff --git a/spec/abci/abci++_basic_concepts.md b/spec/abci/abci++_basic_concepts.md
@@ -29,7 +29,7 @@ title: Overview and basic concepts
 [&#8593; Back to Outline](#outline)
 
 The Application's main role is to execute blocks decided (a.k.a. finalized) by consensus. The
-decided blocks are the consensus's main ouput to the (replicated) Application. With ABCI, the
+decided blocks are the consensus's main output to the (replicated) Application. With ABCI, the
 application only interacts with consensus at *decision* time. This restricted mode of interaction
 prevents numerous features for the Application, including many scalability improvements that are
 now better understood than when ABCI was first written. For example, many ideas proposed to improve
@@ -41,14 +41,14 @@ finalized blocks. This includes features such as threshold cryptography, and gua
 connection attempts.
 
 ABCI++ addresses these limitations by allowing the application to intervene at three key places of
-consensus execution: (a) at the moment a new proposal is to be created and (b) at the moment a
+consensus execution: (a) at the moment a new proposal is to be created, (b) at the moment a
 proposal is to be validated, and (c) at the moment a (precommit) vote is sent/received. 
 The new interface allows block proposers to perform application-dependent
 work in a block through the `PrepareProposal` method (a); and validators to perform application-dependent work
 and checks in a proposed block through the `ProcessProposal` method (b); and applications to require their validators 
-do more than just validate blocks through the `ExtendVote` and `VerifyVoteExtensions` methods (c). 
+to do more than just validate blocks through the `ExtendVote` and `VerifyVoteExtensions` methods (c). 
 
-Furthermore, ABCI++ coalesces {`BeginBlock`, [`DeliverTx`], `EndBlock`} into `FinalizeBlock`, as a
+Furthermore, ABCI 2.0 coalesces {`BeginBlock`, [`DeliverTx`], `EndBlock`} into `FinalizeBlock`, as a
 simplified, efficient way to deliver a decided block to the Application.
 
 ## Method overview
@@ -125,7 +125,7 @@ call sequences of these methods.
 
 - [**Commit:**](./abci++_methods.md#commit) Instructs the Application to persist its
   state. It is a fundamental part of CometBFT's crash-recovery mechanism that ensures the
-  synchronization between CometBFT and the Applicatin upon recovery. CometBFT calls it just after
+  synchronization between CometBFT and the Application upon recovery. CometBFT calls it just after
   having persisted the data returned by calls to `ResponseFinalizeBlock`. The Application can now discard
   any state or data except the one resulting from executing the transactions in the decided block.
 

diff --git a/spec/abci/abci++_comet_expected_behavior.md b/spec/abci/abci++_comet_expected_behavior.md
@@ -56,7 +56,7 @@ consensus-exec      = (inf)consensus-height
 consensus-height    = *consensus-round decide commit
 consensus-round     = proposer / non-proposer
 
-proposer            = *got-vote prepare-proposal *got-vote process-proposal [extend]
+proposer            = *got-vote [prepare-proposal process-proposal] [extend]
 extend              = *got-vote extend-vote *got-vote
 non-proposer        = *got-vote [process-proposal] [extend]
 
@@ -127,7 +127,7 @@ Let us now examine the grammar line by line, providing further details.
 >```
 
 * In recovery mode, CometBFT first calls `Info` to know from which height it needs to replay decisions
-  to the Application. After this, CometBFT enters normal consensus execution .
+  to the Application. After this, CometBFT enters normal consensus execution.
 
 >```abnf
 >recovery            = info consensus-exec
@@ -162,7 +162,7 @@ also delivers to itself.
   of this height.
 
 >```abnf
->proposer            = *got-vote prepare-proposal *got-vote process-proposal [extend]
+>proposer            = *got-vote [prepare-proposal process-proposal] [extend]
 >extend              = *got-vote extend-vote *got-vote
 >```
 
@@ -200,7 +200,7 @@ with as minimal changes as possible. In this case, of course, ABCI++ will not pr
 to the existing implementation, but will keep the same guarantees already provided by ABCI.
 Here is how ABCI++ methods should be implemented.
 
-First of all, all the methods that did not change from ABCI to ABCI++, namely `Echo`, `Flush`, `Info`, `InitChain`,
+First of all, all the methods that did not change from ABCI 0.17.0 to ABCI 2.0, namely `Echo`, `Flush`, `Info`, `InitChain`,
 `Query`, `CheckTx`, `ListSnapshots`, `LoadSnapshotChunk`, `OfferSnapshot`, and `ApplySnapshotChunk`, do not need
 to undergo any changes in their implementation.
 

diff --git a/spec/abci/abci++_methods.md b/spec/abci/abci++_methods.md
@@ -176,7 +176,7 @@ title: Methods
       Application is expected to persist its state at the end of this call, before calling `ResponseCommit`.
     * Use `ResponseCommit.retain_height` with caution! If all nodes in the network remove historical
       blocks then this data is permanently lost, and no new nodes will be able to join the network and
-      bootstrap. Historical blocks may also be required for other purposes, e.g. auditing, replay of
+      bootstrap, unless state sync is enabled on the chain. Historical blocks may also be required for other purposes, e.g. auditing, replay of
       non-persisted heights, light client verification, and so on.
 
 ### ListSnapshots
@@ -210,9 +210,9 @@ title: Methods
 
 * **Response**:
 
-    | Name  | Type  | Description                                                                                                                                            | Field Number |
-    |-------|-------|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
-    | chunk | bytes | The binary chunk contents, in an arbitrary format. Chunk messages cannot be larger than 16 MB _including metadata_, so 10 MB is a good starting point. | 1            |
+    | Name  | Type  | Description                                                                                                                                           | Field Number |
+    |-------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
+    | chunk | bytes | The binary chunk contents, in an arbitray format. Chunk messages cannot be larger than 16 MB _including metadata_, so 10 MB is a good starting point. | 1            |
 
 * **Usage**:
     * Used during state sync to retrieve snapshot chunks from peers.
@@ -349,10 +349,10 @@ title: Methods
             transaction `t1` into a second transaction `t2`, i.e., the Application asks CometBFT
             to remove `t1` from the block and add `t2` to the block. If a client wants to eventually check what
             happened to `t1`, it will discover that `t1` is not in a
-            committed block (assuming a _re-CheckTx_ evited it from the mempool), getting the wrong idea that `t1` did not make it into a block. Note
+            committed block (assuming a _re-CheckTx_ evicted it from the mempool), getting the wrong idea that `t1` did not make it into a block. Note
             that `t2` _will be_ in a committed block, but unless the Application tracks this
             information, no component will be aware of it. Thus, if the Application wants
-            traceability, it is its responsability to support it. For instance, the Application
+            traceability, it is its responsibility's to support it. For instance, the Application
             could attach to a transformed transaction a list with the hashes of the transactions it
             derives from.
     * CometBFT MAY include a list of transactions in `RequestPrepareProposal.txs` whose total
@@ -364,9 +364,6 @@ title: Methods
     * As a result of executing the prepared proposal, the Application may produce block events or transaction events.
       The Application must keep those events until a block is decided and then pass them on to CometBFT via
       `ResponseFinalizeBlock`.
-<!--
- TODO CHECK THIS 
--->
     * CometBFT does NOT provide any additional validity checks (such as checking for duplicate
       transactions).
       <!--
@@ -692,7 +689,8 @@ Most of the data structures used in ABCI are shared [common data structures](../
 
 * **Usage**:
     * Validator identified by address
-    * Used as part of VoteInfo within CommitInfo <!-- TODO Check where exactly is commitinfo used, seems to be only Prepare/Process proposal -->
+    * Used as part of VoteInfo within `CommitInfo` (used in `ProcessProposal` and `FinalizeBlock`), 
+      and `ExtendedCommitInfo` (used in `PrepareProposal`).
     * Does not include PubKey to avoid sending potentially large quantum pubkeys
     over the ABCI