From f774c09a9731310e70c53ba7ebe2841b4a5dd42b Mon Sep 17 00:00:00 2001 From: Sergio Mena Date: Fri, 14 Jan 2022 15:25:20 +0100 Subject: [PATCH] Editorial/Lint changes --- spec/README.md | 2 +- spec/abci++/README.md | 3 +- .../abci++_app_requirements_002_draft.md | 8 ++-- .../abci++/abci++_basic_concepts_002_draft.md | 4 +- spec/abci++/abci++_methods_002_draft.md | 38 +++++++++---------- 5 files changed, 28 insertions(+), 27 deletions(-) diff --git a/spec/README.md b/spec/README.md index 650376196..dfb722ef9 100644 --- a/spec/README.md +++ b/spec/README.md @@ -8,7 +8,7 @@ parent: # Tendermint Spec -This is a markdown specification of the Tendermint blockchain. +This is a Markdown specification of the Tendermint blockchain. It defines the base data structures, how they are validated, and how they are communicated over the network. diff --git a/spec/abci++/README.md b/spec/abci++/README.md index 3b9e7060e..5aecc06cf 100644 --- a/spec/abci++/README.md +++ b/spec/abci++/README.md @@ -37,7 +37,8 @@ This specification is split as follows: how the different ABCI++ methods may be called by Tendermint. This explains what the Application is to expect from Tendermint. ->**TODO** Re-read these and remove redundant in fo +>**TODO** Re-read these and remove redundant info + - [Applications](../abci/apps.md) - how to manage ABCI application state and other details about building ABCI applications - [Client and Server](../abci/client-server.md) - for those looking to implement their diff --git a/spec/abci++/abci++_app_requirements_002_draft.md b/spec/abci++/abci++_app_requirements_002_draft.md index c74317e81..1ba523d03 100644 --- a/spec/abci++/abci++_app_requirements_002_draft.md +++ b/spec/abci++/abci++_app_requirements_002_draft.md @@ -32,15 +32,15 @@ compute various hashes in the block header that will finally be part of the prop _AppHash_, _TxResults_, _ConsensusParams_, _ValidatorUpdates_. In practical terms, Requirements 1 and 2 imply that Tendermint will (a) panic if the Application is in -same-block execution mode and _does not_ provide values for +same-block execution mode and _does_ _not_ provide values for _AppHash_, _TxResults_, _ConsensusParams_, and _ValidatorUpdates_, or (b) log an error if the Application is in next-block execution mode and _does_ provide values for _AppHash_, _TxResults_, _ConsensusParams_, or _ValidatorUpdates_ (the values provided will be ignored). * Requirement 3 [`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_p$, - 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_p$). - . + `PrepareProposal` and the network is in a synchronous period while processes $p$ and $q$ are in $r_p$, 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_p$). Full execution of blocks at `PrepareProposal` time stands on Tendermint's critical path. Thus, Requirement 3 ensures the Application will set a value for _TimeoutPropose_ such that the time it takes diff --git a/spec/abci++/abci++_basic_concepts_002_draft.md b/spec/abci++/abci++_basic_concepts_002_draft.md index a5d8c9658..8fe97c9e8 100644 --- a/spec/abci++/abci++_basic_concepts_002_draft.md +++ b/spec/abci++/abci++_basic_concepts_002_draft.md @@ -348,7 +348,7 @@ provide any data in `ResponsePrepareProposal`, other than an optionally modified transaction list. In the long term, the execution model will be set in a new boolean parameter -_same_block_ in `ConsensusParams`. +*same_block* in `ConsensusParams`. It should **not** be changed once the blockchain has started, unless the Application developers _really_ know what they are doing. However, modifying `ConsensusParams` structure cannot be done lightly if we are to @@ -367,7 +367,7 @@ executing the block, the default value of _TimeoutPropose_ might not be sufficie to accomodate the long block execution time and non-proposer processes might time out and prevote `nil`, thus starting a further round unnecessarily. -The application is the best suited to provide a value for _TimeoutPropose_ so +The Application is the best suited to provide a value for _TimeoutPropose_ so that the block execution time upon `PrepareProposal` fits well in the propose timeout interval. diff --git a/spec/abci++/abci++_methods_002_draft.md b/spec/abci++/abci++_methods_002_draft.md index a8091d8c0..b2a6a0e7a 100644 --- a/spec/abci++/abci++_methods_002_draft.md +++ b/spec/abci++/abci++_methods_002_draft.md @@ -322,20 +322,20 @@ From the App's perspective, they'll probably skip ProcessProposal * In same-block execution mode, the Application must provide values for `ResponsePrepareProposal.app_hash`, `ResponsePrepareProposal.tx_result`, `ResponsePrepareProposal.validator_updates`, and `ResponsePrepareProposal.consensus_param_updates`, as a result of fully executing the block. - * 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). - * It is the responsibility of the Application to set the right value for _TimeoutPropose_ so that - the (synchronous) execution of the block does not cause other processes to prevote `nil` because - their propose timeout goes off. + * 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). + * It is the responsibility of the Application to set the right value for _TimeoutPropose_ so that + the (synchronous) execution of the block does not cause other processes to prevote `nil` because + their propose timeout goes off. * In next-block execution mode, Tendermint will ignore parameters `ResponsePrepareProposal.tx_result`, `ResponsePrepareProposal.validator_updates`, and `ResponsePrepareProposal.consensus_param_updates`. * As a result of executing the prepared proposal, the Application may produce header events or transaction events. @@ -441,7 +441,7 @@ Note that, if _p_ has a non-`nil` _validValue_, Tendermint will use it as propos * If `ResponseProcessProposal.accept` is _false_, Tendermint assumes the proposal received is not valid. * The implementation of `ProcessProposal` MUST be deterministic. Moreover, the value of - `ResponseProcessProposal.accept` MUST *exclusively* depend on the parameters passed in + `ResponseProcessProposal.accept` MUST **exclusively** depend on the parameters passed in the call to `RequestProcessProposal`, and the last committed Application state (see [Requirements](abci++_app_requirements_002_draft.md) section). * Moreover, application implementors SHOULD always set `ResponseProcessProposal.accept` to _true_, @@ -534,7 +534,7 @@ In the cases when _p_'s Tendermint is to broadcast `precommit nil` messages (eit See the [Requirements](abci++_app_requirements_002_draft.md) section to understand the potential liveness implications of this. * The implementation of `VerifyVoteExtension` MUST be deterministic. Moreover, the value of - `ResponseVerifyVoteExtension.accept` MUST *exclusively* depend on the parameters passed in + `ResponseVerifyVoteExtension.accept` MUST **exclusively** depend on the parameters passed in the call to `RequestVerifyVoteExtension`, and the last committed Application state (see [Requirements](abci++_app_requirements_002_draft.md) section). * Moreover, application implementors SHOULD always set `ResponseVerifyVoteExtension.accept` to _true_, @@ -601,9 +601,9 @@ from this condition, but not sure), and _p_ receives a Precommit message for rou 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. + - Height `H+1`: `NextValidatorsHash` includes the new `validator_updates` value. + - Height `H+2`: The validator set change takes effect and `ValidatorsHash` is updated. + - Height `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).