From 009c120abbd257cf59f18afcc8cef68f1e3e9970 Mon Sep 17 00:00:00 2001 From: Sergio Mena Date: Mon, 20 Dec 2021 21:16:20 +0100 Subject: [PATCH] Addressed latest comments from Josef and William --- .../abci++_app_requirements_002_draft.md | 18 +++++--- .../abci++/abci++_basic_concepts_002_draft.md | 11 ++--- spec/abci++/abci++_methods_002_draft.md | 41 ++++++++++++++----- 3 files changed, 49 insertions(+), 21 deletions(-) diff --git a/spec/abci++/abci++_app_requirements_002_draft.md b/spec/abci++/abci++_app_requirements_002_draft.md index df7284dec..bd312cabc 100644 --- a/spec/abci++/abci++_app_requirements_002_draft.md +++ b/spec/abci++/abci++_app_requirements_002_draft.md @@ -20,13 +20,15 @@ Process $p$'s prepared proposal can differ in two different rounds where $p$ is * Requirement 1 [`PrepareProposal`, header-changes] When the blockchain is in same-block execution mode, $p$'s Application provides values for the following parameters in `ResponsePrepareProposal`: - _AppHash_, _TxResults_, _ConsensusParams_, _ValidatorUpdates_. + _AppHash_, _TxResults_, _ConsensusParams_, _ValidatorUpdates_. Provided values for + _ConsensusParams_ and _ValidatorUpdates_ MAY be empty to denote that the Application + wishes to keep the current values. Parameters _AppHash_, _TxResults_, _ConsensusParams_, and _ValidatorUpdates_ are used by Tendermint to compute various hashes in the block header that will finally be part of the proposal. * Requirement 2 [`PrepareProposal`, no-header-changes] When the blockchain is in next-block execution - mode, $p$'s Application does not provides values for the following parameters in `ResponsePrepareProposal`: + mode, $p$'s Application does not provide values for the following parameters in `ResponsePrepareProposal`: _AppHash_, _TxResults_, _ConsensusParams_, _ValidatorUpdates_. In practical terms, Requirement 2 implies that Tendermint will ignore those parameters in `ResponsePrepareProposal`. @@ -97,7 +99,7 @@ Requirements 7 and 8 ensure that the validation of vote extensions will be deter correct processes. Requirements 7 and 8 protect against arbitrary vote extension data from Byzantine processes similarly to Requirements 4 and 5 and proposed blocks. -Requirements 7 and 8 can be violated by a bug inducing non-determinism in `ExtendVote` or +Requirements 7 and 8 can be violated by a bug inducing non-determinism in `VerifyVoteExtension`. In this case liveness can be compromised. Extra care should be put in the implementation of `ExtendVote` and `VerifyVoteExtension` and, as a general rule, `VerifyVoteExtension` _should_ always accept the vote extension. @@ -107,12 +109,16 @@ as a general rule, `VerifyVoteExtension` _should_ always accept the vote extensi not modify $s_{p,h-1}$. * Requirement 10 [`ExtendVote`, `FinalizeBlock`, non-dependency]: for any correct process $p$, -and any vote extension $e$ that $q$ received at height $h$, the computation of -$s{p,h}$ does not depend on $e$. +and any vote extension $e$ that $p$ received at height $h$, the computation of +$s_{p,h}$ does not depend on $e$. The call to correct process $p$'s `RequestFinalizeBlock` at height $h$, with block $v_{p,h}$ passed as parameter, creates state $s_{p,h}$. -Additionally, $p$'s `FinalizeBlock` creates a set of transaction results $T_{p,h}$. +Additionally, + +* in next-block execution mode, $p$'s `FinalizeBlock` creates a set of transaction results $T_{p,h}$, +* in same-block execution mode, $p$'s `PrepareProposal` creates a set of transaction results $T_{p,h}$ + if $p$ was the proposer of $v_{p,h}$, otherwise `FinalizeBlock` creates $T_{p,h}$. >**TODO** I have left out all the "events" as they don't have any impact in safety or liveness >(same for consensus params, and validator set) diff --git a/spec/abci++/abci++_basic_concepts_002_draft.md b/spec/abci++/abci++_basic_concepts_002_draft.md index de5833814..c0f431167 100644 --- a/spec/abci++/abci++_basic_concepts_002_draft.md +++ b/spec/abci++/abci++_basic_concepts_002_draft.md @@ -212,7 +212,7 @@ in the next height, along with the vote it is extending. The vote extension data is split into two parts, one signed by Tendermint as part of the vote data structure, and the other (optionally) signed by the application. The Application may also choose not to include any vote extension. -When another process receives a precommit message with and vote extension, it calls +When another process receives a precommit message with a vote extension, it calls method `VerifyVoteExtension` so that the application can validate the data received. If the validation fails, the precommit message will be deemed invalid and ignored by Tendermint. This has negative impact on Tendermint's liveness, i.e., if repeatedly vote extensions by correct validators cannot be verified by correct validators, Tendermint may not be able to finalize a block even if sufficiently many (+2/3) of the validators send precommit votes for that block. Thus, `VerifyVoteExtension` should only be used with special care. @@ -284,12 +284,13 @@ block, resulting in an updated application state. During consensus execution of a block height, before method `FinalizeBlock` is called, methods `PrepareProposal`, `ProcessProposal`, `ExtendVote`, and `VerifyVoteExtension` may be called a number of times. -See [Application Requirements](abci++_app_requirements_002_draft.md) for -details on the possible call sequences of these methods. +See [Tendermint's expected behavior](abci++_tmint_expected_behavior_002_draft.md) +for details on the possible call sequences of these methods. Method `PrepareProposal` is called every time Tendermint is about to send -a proposal message. Tendermint gathers outstanding transactions from the mempool -(see [PrepareProposal]()#PrepareProposal), generates a block header and uses +a proposal message, but no previous proposal has been locked at Tendermint level. +Tendermint gathers outstanding transactions from the mempool +(see [PrepareProposal](#PrepareProposal)), generates a block header and uses them to create a block to propose. Then, it calls `RequestPrepareProposal` with the newly created proposal, called _raw proposal_. The Application can make changes to the raw proposal, such as modifying transactions, and returns diff --git a/spec/abci++/abci++_methods_002_draft.md b/spec/abci++/abci++_methods_002_draft.md index b86bf650d..73431108e 100644 --- a/spec/abci++/abci++_methods_002_draft.md +++ b/spec/abci++/abci++_methods_002_draft.md @@ -321,8 +321,20 @@ From the App's perspective, they'll probably skip ProcessProposal * If `ResponsePrepareProposal.modified_tx` is false, then Tendermint will ignore the contents of `ResponsePrepareProposal.tx`. * In same-block execution mode, the Application must set `ResponsePrepareProposal.same_block` to true, and, - as a result of executing the block, provide values for `ResponsePrepareProposal.tx_result`, - `ResponsePrepareProposal.validator_updates`, and `ResponsePrepareProposal.consensus_param_updates`. + as a result of executing the block, provide values for `ResponsePrepareProposal.data`, + `ResponsePrepareProposal.tx_result`, `ResponsePrepareProposal.validator_updates`, and + `ResponsePrepareProposal.consensus_param_updates`. + * The values for `ResponsePrepareProposal.validator_updates`, or + `ResponsePrepareProposal.consensus_param_updates` may be empty. In this case, Tendermint will keep + the current values. + * `ResponsePrepareProposal.validator_updates`, triggered by block `H`, affect validation + for blocks `H+1`, and `H+2`. Heights following a validator update are affected in the following way: + * `H`: `NextValidatorsHash` includes the new `validator_updates` value. + * `H+1`: The validator set change takes effect and `ValidatorsHash` is updated. + * `H+2`: `last_commit_info` is changed to include the altered validator set. + * `ResponseFinalizeBlock.consensus_param_updates` returned for block `H` apply to the consensus + params for the same block `H`. For more information on the consensus parameters, + see the [application spec entry on consensus parameters](../abci/apps.md#consensus-parameters). * In next-block execution mode, the Application must set `ResponsePrepareProposal.same_block` to false. Tendermint will ignore parameters `ResponsePrepareProposal.tx_result`, `ResponsePrepareProposal.validator_updates`, and `ResponsePrepareProposal.consensus_param_updates`. @@ -575,14 +587,23 @@ from this condition, but not sure), and _p_ receives a Precommit message for rou before returning control to Tendermint. Alternatively, it can commit the candidate state corresponding to the same block previously executed via `PrepareProposal` or `ProcessProposal`. * `ResponseFinalizeBlock.tx_result[i].Code == 0` only if the _i_-th transaction is fully valid. - * Optional `ResponseFinalizeBlock.validator_updates` triggered by block `H`. These updates affect validation - for blocks `H+1`, `H+2`, and `H+3`. Heights following a validator update are affected in the following way: - * `H+1`: `NextValidatorsHash` includes the new `validator_updates` value. - * `H+2`: The validator set change takes effect and `ValidatorsHash` is updated. - * `H+3`: `last_commit_info` is changed to include the altered validator set. - * `ResponseFinalizeBlock.consensus_param_updates` returned for block `H` apply to the consensus - params for block `H+1`. For more information on the consensus parameters, - see the [application spec entry on consensus parameters](../abci/apps.md#consensus-parameters). + * In next-block execution mode, the Application must provide values for `ResponseFinalizeBlock.app_data`, + `ResponseFinalizeBlock.tx_result`, `ResponseFinalizeBlock.validator_updates`, and + `ResponsePrepareProposal.consensus_param_updates` as a result of executing the block. + * The values for `ResponseFinalizeBlock.validator_updates`, or + `ResponseFinalizeBlock.consensus_param_updates` may be empty. In this case, Tendermint will keep + the current values. + * `ResponseFinalizeBlock.validator_updates`, triggered by block `H`, affect validation + for blocks `H+1`, `H+2`, and `H+3`. Heights following a validator update are affected in the following way: + * `H+1`: `NextValidatorsHash` includes the new `validator_updates` value. + * `H+2`: The validator set change takes effect and `ValidatorsHash` is updated. + * `H+3`: `last_commit_info` is changed to include the altered validator set. + * `ResponseFinalizeBlock.consensus_param_updates` returned for block `H` apply to the consensus + params for block `H+1`. For more information on the consensus parameters, + see the [application spec entry on consensus parameters](../abci/apps.md#consensus-parameters). + * In same-block execution mode, Tendermint will ignore values for `ResponseFinalizeBlock.app_data`, + `ResponseFinalizeBlock.tx_result`, `ResponseFinalizeBlock.validator_updates`, and + `ResponsePrepareProposal.consensus_param_updates`, as those data have been provided by `PrepareProposal`. * Application is expected to persist its state at the end of this call, before calling `ResponseFinalizeBlock`. * `ResponseFinalizeBlock.app_data` contains an (optional) Merkle root hash of the application state. * `ResponseFinalizeBlock.app_data` is included