mirrors/tendermint
1
0
Fork 0
mirror of https://github.com/tendermint/tendermint.git synced 2026-09-29 19:25:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove references to "same-block execution" in ABCI++ specification and protobufs (#8937)

Browse Source 
* Changes to spec

* Changes to proto-bufs

* make proto-gen

* Remove typo
This commit is contained in:
Sergio Mena
2022-07-07 13:13:58 +02:00
committed by GitHub
parent 38b671a294
commit 1c719813ca
5 changed files with 260 additions and 910 deletions
Download Patch File Download Diff File Expand all files Collapse all files
spec/abci++/abci++_app_requirements.md
+39 -92
View File
@@ -23,74 +23,55 @@ returns via `ResponsePrepareProposal` to Tendermint, also known as the prepared
Process *p*'s prepared proposal can differ in two different rounds where *p* is the proposer.
* 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`. 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 provide values for the following parameters in `ResponsePrepareProposal`:
`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
`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
* 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>*).
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
Requirement 1 ensures the Application will set a value for `TimeoutPropose` such that the time it takes
to fully execute blocks in `PrepareProposal` does not interfere with Tendermint's propose timer.
Note that violation of Requirement 3 may just lead to further rounds, but will not compromise liveness.
Note that violation of Requirement 1 may just lead to further rounds, but will not compromise liveness.
* Requirement 4 [`PrepareProposal`, tx-size]: When *p*'s Application calls `ResponsePrepareProposal`, the
* 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`.
Busy blockchains might seek to maximize the amount of transactions included in each block. Under those conditions,
Tendermint might choose to increase the transactions passed to the Application via `RequestPrepareProposal.txs`
beyond the `RequestPrepareProposal.max_tx_bytes` limit. The idea is that, if the Application drops some of
those transactions, it can still return a transaction list whose byte size is as close to
`RequestPrepareProposal.max_tx_bytes` as possible. Thus, Requirement 4 ensures that the size in bytes of the
`RequestPrepareProposal.max_tx_bytes` as possible. Thus, Requirement 2 ensures that the size in bytes of the
transaction list returned by the application will never cause the resulting block to go beyond its byte size
limit.
* Requirement 5 [`PrepareProposal`, `ProcessProposal`, coherence]: For any two correct processes *p* and *q*,
* Requirement 3 [`PrepareProposal`, `ProcessProposal`, coherence]: For any two correct processes *p* and *q*,
if *q*'s Tendermint calls `RequestProcessProposal` on *u<sub>p</sub>*,
*q*'s Application returns Accept in `ResponseProcessProposal`.
Requirement 5 makes sure that blocks proposed by correct processes *always* pass the correct receiving process's
Requirement 3 makes sure that blocks proposed by correct processes *always* pass the correct receiving process's
`ProcessProposal` check.
On the other hand, if there is a deterministic bug in `PrepareProposal` or `ProcessProposal` (or in both),
strictly speaking, this makes all processes that hit the bug byzantine. This is a problem in practice,
as very often validators are running the Application from the same codebase, so potentially *all* would
likely hit the bug at the same time. This would result in most (or all) processes prevoting `nil`, with the
serious consequences on Tendermint's liveness that this entails. Due to its criticality, Requirement 5 is a
serious consequences on Tendermint's liveness that this entails. Due to its criticality, Requirement 3 is a
target for extensive testing and automated verification.
* Requirement 6 [`ProcessProposal`, determinism-1]: `ProcessProposal` is a (deterministic) function of the current
* Requirement 4 [`ProcessProposal`, determinism-1]: `ProcessProposal` is a (deterministic) function of the current
state and the block that is about to be applied. In other words, for any correct process *p*, and any arbitrary block *u*,
if *p*'s Tendermint calls `RequestProcessProposal` on *u* at height *h*,
then *p*'s Application's acceptance or rejection **exclusively** depends on *u* and *s<sub>p,h-1</sub>*.
* Requirement 7 [`ProcessProposal`, determinism-2]: For any two correct processes *p* and *q*, and any arbitrary
* Requirement 5 [`ProcessProposal`, determinism-2]: For any two correct processes *p* and *q*, and any arbitrary
block *u*,
if *p*'s (resp. *q*'s) Tendermint calls `RequestProcessProposal` on *u* at height *h*,
then *p*'s Application accepts *u* if and only if *q*'s Application accepts *u*.
Note that this requirement follows from Requirement 6 and the Agreement property of consensus.
Note that this requirement follows from Requirement 4 and the Agreement property of consensus.
Requirements 6 and 7 ensure that all correct processes will react in the same way to a proposed block, even
Requirements 4 and 5 ensure that all correct processes will react in the same way to a proposed block, even
if the proposer is Byzantine. However, `ProcessProposal` may contain a bug that renders the
acceptance or rejection of the block non-deterministic, and therefore prevents processes hitting
the bug from fulfilling Requirements 6 or 7 (effectively making those processes Byzantine).
the bug from fulfilling Requirements 4 or 5 (effectively making those processes Byzantine).
In such a scenario, Tendermint's liveness cannot be guaranteed.
Again, this is a problem in practice if most validators are running the same software, as they are likely
to hit the bug at the same point. There is currently no clear solution to help with this situation, so
@@ -108,64 +89,58 @@ Let *e<sup>r</sup><sub>p</sub>* be the vote extension that the Application of a
Let *w<sup>r</sup><sub>p</sub>* be the proposed block that *p*'s Tendermint passes to the Application via `RequestExtendVote`
in round *r*, height *h*.
* Requirement 8 [`ExtendVote`, `VerifyVoteExtension`, coherence]: For any two different correct
* Requirement 6 [`ExtendVote`, `VerifyVoteExtension`, coherence]: For any two different correct
processes *p* and *q*, if *q* receives *e<sup>r</sup><sub>p</sub>* from *p* in height *h*, *q*'s
Application returns Accept in `ResponseVerifyVoteExtension`.
Requirement 8 constrains the creation and handling of vote extensions in a similar way as Requirement 5
Requirement 6 constrains the creation and handling of vote extensions in a similar way as Requirement 3
constrains the creation and handling of proposed blocks.
Requirement 8 ensures that extensions created by correct processes *always* pass the `VerifyVoteExtension`
Requirement 6 ensures that extensions created by correct processes *always* pass the `VerifyVoteExtension`
checks performed by correct processes receiving those extensions.
However, if there is a (deterministic) bug in `ExtendVote` or `VerifyVoteExtension` (or in both),
we will face the same liveness issues as described for Requirement 5, as Precommit messages with invalid vote
extensions will be discarded.
* Requirement 9 [`VerifyVoteExtension`, determinism-1]: `VerifyVoteExtension` is a (deterministic) function of
* Requirement 7 [`VerifyVoteExtension`, determinism-1]: `VerifyVoteExtension` is a (deterministic) function of
the current state, the vote extension received, and the prepared proposal that the extension refers to.
In other words, for any correct process *p*, and any arbitrary vote extension *e*, and any arbitrary
block *w*, if *p*'s (resp. *q*'s) Tendermint calls `RequestVerifyVoteExtension` on *e* and *w* at height *h*,
then *p*'s Application's acceptance or rejection **exclusively** depends on *e*, *w* and *s<sub>p,h-1</sub>*.
* Requirement 10 [`VerifyVoteExtension`, determinism-2]: For any two correct processes *p* and *q*,
* 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 *p*'s (resp. *q*'s) Tendermint 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 9 and the Agreement property of consensus.
Note that this requirement follows from Requirement 7 and the Agreement property of consensus.
Requirements 9 and 10 ensure that the validation of vote extensions will be deterministic at all
Requirements 7 and 8 ensure that the validation of vote extensions will be deterministic at all
correct processes.
Requirements 9 and 10 protect against arbitrary vote extension data from Byzantine processes,
in a similar way as Requirements 6 and 7 protect against arbitrary proposed blocks.
Requirements 9 and 10 can be violated by a bug inducing non-determinism in
Requirements 7 and 8 protect against arbitrary vote extension data from Byzantine processes,
in a similar way as Requirements 4 and 5 protect against arbitrary proposed blocks.
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`.
As a general rule, `VerifyVoteExtension` SHOULD always accept the vote extension.
* Requirement 11 [*all*, no-side-effects]: *p*'s calls to `RequestPrepareProposal`,
* Requirement 9 [*all*, no-side-effects]: *p*'s calls to `RequestPrepareProposal`,
`RequestProcessProposal`, `RequestExtendVote`, and `RequestVerifyVoteExtension` at height *h* do
not modify *s<sub>p,h-1</sub>*.
* Requirement 12 [`ExtendVote`, `FinalizeBlock`, non-dependency]: for any correct process *p*,
* Requirement 10 [`ExtendVote`, `FinalizeBlock`, non-dependency]: for any correct process *p*,
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 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,
Additionally, *p*'s `FinalizeBlock` creates a set of transaction results *T<sub>p,h</sub>*.
* in next-block execution mode, *p*'s `FinalizeBlock` creates a set of transaction results *T<sub>p,h</sub>*,
* in same-block execution mode, *p*'s `PrepareProposal` creates a set of transaction results *T<sub>p,h</sub>*
if *p* was the proposer of *v<sub>p,h</sub>*. If *p* was not the proposer of *v<sub>p,h</sub>*,
`ProcessProposal` creates *T<sub>p,h</sub>*. `FinalizeBlock` MAY re-create *T<sub>p,h</sub>* if it was
removed from memory during the execution of height *h*.
* Requirement 13 [`FinalizeBlock`, determinism-1]: For any correct process *p*,
* Requirement 11 [`FinalizeBlock`, determinism-1]: For any correct process *p*,
*s<sub>p,h</sub>* exclusively depends on *s<sub>p,h-1</sub>* and *v<sub>p,h</sub>*.
* Requirement 14 [`FinalizeBlock`, determinism-2]: For any correct process *p*,
* Requirement 12 [`FinalizeBlock`, determinism-2]: For any correct process *p*,
the contents of *T<sub>p,h</sub>* exclusively depend on *s<sub>p,h-1</sub>* and *v<sub>p,h</sub>*.
Note that Requirements 13 and 14, combined with Agreement property of consensus ensure
Note that Requirements 11 and 12, combined with Agreement property of consensus ensure
state machine replication, i.e., the Application state evolves consistently at all correct processes.
Finally, notice that neither `PrepareProposal` nor `ExtendVote` have determinism-related
@@ -449,11 +424,6 @@ including the list of all its transactions synchronously to the Application.
The block delivered (and thus the transaction order) is the same at all correct nodes as guaranteed
by the Agreement property of Tendermint consensus.
In same block execution mode, field `LastResultsHash` in the block header refers to the results
of all transactions stored in that block. Therefore,
`PrepareProposal` must return `ExecTxResult` so that it can
be used to build the block to be proposed in the current height.
The `Data` field in `ExecTxResult` contains an array of bytes with the transaction result.
It must be deterministic (i.e., the same value must be returned at all nodes), but it can contain arbitrary
data. Likewise, the value of `Code` must be deterministic.
@@ -462,9 +432,7 @@ though it is still included in the block. Invalid transaction are not indexed, a
considered analogous to those that failed `CheckTx`.
Both the `Code` and `Data` are included in a structure that is hashed into the
`LastResultsHash` of the block header in the next height (next block execution mode), or the
header of the block to propose in the current height (same block execution mode, `ExecTxResult` as
part of `PrepareProposal`).
`LastResultsHash` of the block header in the next height.
`Events` include any events for the execution, which Tendermint will use to index
the transaction by. This allows transactions to be queried according to what
@@ -474,10 +442,7 @@ events took place during their execution.
The application may set the validator set during
[`InitChain`](./abci%2B%2B_methods.md#initchain), and may update it during
[`FinalizeBlock`](./abci%2B%2B_methods.md#finalizeblock)
(next block execution mode) or
[`PrepareProposal`](./abci%2B%2B_methods.md#prepareproposal)/[`ProcessProposal`](./abci%2B%2B_methods.md#processproposal)
(same block execution mode). In all cases, a structure of type
[`FinalizeBlock`](./abci%2B%2B_methods.md#finalizeblock). In both cases, a structure of type
[`ValidatorUpdate`](./abci%2B%2B_methods.md#validatorupdate) is returned.
The `InitChain` method, used to initialize the Application, can return a list of validators.
@@ -521,10 +486,7 @@ They enforce certain limits in the blockchain, like the maximum size
of blocks, amount of gas used in a block, and the maximum acceptable age of
evidence. They can be set in
[`InitChain`](./abci%2B%2B_methods.md#initchain), and updated in
[`FinalizeBlock`](./abci%2B%2B_methods.md#finalizeblock)
(next block execution mode) or
[`PrepareProposal`](./abci%2B%2B_methods.md#prepareproposal)/[`ProcessProposal`](./abci%2B%2B_methods.md#processproposal)
(same block execution model).
[`FinalizeBlock`](./abci%2B%2B_methods.md#finalizeblock).
These parameters are deterministically set and/or updated by the Application, so
all full nodes have the same value at a given height.
@@ -698,10 +660,7 @@ Must always be set to a future height. Once set to a value different from
The application may set the `ConsensusParams` during
[`InitChain`](./abci%2B%2B_methods.md#initchain),
and update them during
[`FinalizeBlock`](./abci%2B%2B_methods.md#finalizeblock)
(next block execution mode) or
[`PrepareProposal`](./abci%2B%2B_methods.md#prepareproposal)/[`ProcessProposal`](./abci%2B%2B_methods.md#processproposal)
(same block execution mode).
[`FinalizeBlock`](./abci%2B%2B_methods.md#finalizeblock).
If the `ConsensusParams` is empty, it will be ignored. Each field
that is not empty will be applied in full. For instance, if updating the
`Block.MaxBytes`, applications must also set the other `Block` fields (like
@@ -718,21 +677,13 @@ blockchain.
##### `FinalizeBlock`, `PrepareProposal`/`ProcessProposal`
In next block execution mode, `ResponseFinalizeBlock` accepts a `ConsensusParams` parameter.
`ResponseFinalizeBlock` accepts a `ConsensusParams` parameter.
If `ConsensusParams` is `nil`, Tendermint will do nothing.
If `ConsensusParams` is not `nil`, Tendermint will use it.
This way the application can update the consensus parameters over time.
Likewise, in same block execution mode, `PrepareProposal` and `ProcessProposal` include
a `ConsensusParams` parameter. `PrepareProposal` may return a `ConsensusParams` to update
the consensus parameters in the block that is about to be proposed. If it returns `nil`
the consensus parameters will not be updated. `ProcessProposal` also accepts a
`ConsensusParams` parameter, which Tendermint will use it to calculate the corresponding
hashes and sanity-check them against those of the block that triggered `ProcessProposal`
at the first place.
Note the updates returned in block `H` will take effect right away for block
`H+1` (both in next block and same block execution mode).
The updates returned in block `H` will take effect right away for block
`H+1`.
### `Query`
@@ -769,11 +720,8 @@ For such applications, the `AppHash` provides a much more efficient way to verif
ABCI applications can take advantage of more efficient light-client proofs for
their state as follows:
* in next block executon mode, return the Merkle root of the deterministic application state in
`ResponseCommit.Data`. This Merkle root will be included as the `AppHash` in the next block.
* in same block execution mode, return the Merkle root of the deterministic application state
in `ResponsePrepareProposal.AppHash`. This Merkle root will be included as the `AppHash` in
the block that is about to be proposed.
* return the Merkle root of the deterministic application state in
`ResponseFinalizeBlock.Data`. This Merkle root will be included as the `AppHash` in the next block.
* return efficient Merkle proofs about that application state in `ResponseQuery.Proof`
that can be verified using the `AppHash` of the corresponding block.
@@ -1031,8 +979,7 @@ bootstrapping the node (e.g. chain ID, consensus parameters, validator sets, and
from the genesis file and light client RPC servers. It also calls `Info` to verify the following:
* that the app hash from the snapshot it has delivered to the Application matches the apphash
stored in the next height's block (in next block execution), or the current block's height
(same block execution)
stored in the next height's block
* that the version that the Application returns in `ResponseInfo` matches the version in the
current height's block header
spec/abci++/abci++_basic_concepts.md
+2 -56
View File
@@ -11,7 +11,6 @@ title: Overview and basic concepts
- [Mempool methods](#mempool-methods)
- [Info methods](#info-methods)
- [State-sync methods](#state-sync-methods)
- [Next-block execution vs. same-block execution](#next-block-execution-vs-same-block-execution)
- [Tendermint proposal timeout](#tendermint-proposal-timeout)
- [Deterministic State-Machine Replication](#deterministic-state-machine-replication)
- [Events](#events)
@@ -32,7 +31,7 @@ now better understood than when ABCI was first written. For example, many ideas
scalability can be boiled down to "make the block proposers do work, so the network does not have
to". This includes optimizations such as transaction level signature aggregation, state transition
proofs, etc. Furthermore, many new security properties cannot be achieved in the current paradigm,
as the Application cannot require validators to do more than execute the transactions contained in
as the Application cannot require validators to do more than executing the transactions contained in
finalized blocks. This includes features such as threshold cryptography, and guaranteed IBC
connection attempts.
@@ -192,59 +191,6 @@ and an [**Echo**](./abci++_methods.md#echo) method that is used for debugging.
More details on managing state across connections can be found in the section on
[Managing Application State](./abci%2B%2B_app_requirements.md#managing-the-application-state-and-related-topics).
## Next-block execution vs. same-block execution
[&uparrow; Back to Outline](#outline)
In the original ABCI protocol, the only moment when the Application had access to a
block was after it was decided. This led to a block execution model, called *next-block
execution*, where some fields hashed in a block header refer to the execution of the
previous block, namely:
- the Merkle root of the Application's state
- the transaction results
- the consensus parameter updates
- the validator updates
With ABCI++, an Application may be configured to keep using the next-block execution model, by
executing the decided block in `FinalizeBlock`. However, the new methods introduced &mdash;
`PrepareProposal` and `ProcessProposal` &mdash; disclose the entire proposed block to the
Application, allowing for its immediate exectution. An Application implementing immediate execution
may additionally wish to store certain data resulting from the block's execution in the same block
that has just been executed. This brings about a new execution model, called
*same-block execution*. An Application implementing this execution model, upon receiving a raw
proposal via `RequestPrepareProposal` and potentially modifying its transaction list, fully
executes the resulting prepared proposal as though it was the decided block (immediate execution),
and the results of the block execution are used as follows:
- The block execution may generate a set of events. The Application should store these events and
return them back to Tendermint during the `FinalizeBlock` call if the block is finally decided.
- The Merkle root resulting from executing the prepared proposal is provided in
`ResponsePrepareProposal` and thus refers to the **current block**. Tendermint
will use it in the prepared proposal's header.
- Likewise, the transaction results from executing the prepared proposal are
provided in `ResponsePrepareProposal` and refer to the transactions in the
**current block**. Tendermint will use them to calculate the results hash
in the prepared proposal's header.
- The consensus parameter updates and validator updates are also provided in
`ResponsePrepareProposal` and reflect the result of the prepared proposal's
execution. They come into force in height H+1 (as opposed to the H+2 rule
in next-block execution model).
If the Application is configured to keep the next-block execution model, it will not
provide any data in `ResponsePrepareProposal`, other than a potentially modified
transaction list. The Application may nevertheless choose to perform immediate execution even in
next-block execution mode, however same-block execution mode *requires* immediate execution.
The long term plan is for the execution model to be set in a new boolean parameter *same_block* in
`ConsensusParams`. Once this parameter is introduced, it **must 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
preserve blockchain compatibility. Therefore we need an interim solution until
soft upgrades are specified and implemented in Tendermint. This somewhat *unsafe*
solution consists in Tendermint assuming same-block execution if the Application
fills the above mentioned fields in `ResponsePrepareProposal`.
## Tendermint proposal timeout
Immediate execution requires the Application to fully execute the prepared block
@@ -312,7 +258,7 @@ Sources of non-determinism in applications may include:
See [#56](https://github.com/tendermint/abci/issues/56) for the original discussion.
Note that some methods (`Query, CheckTx, FinalizeBlock`) return non-deterministic data in the form
Note that some methods (`Query, FinalizeBlock`) return non-deterministic data in the form
of `Info` and `Log` fields. The `Log` is intended for the literal output from the Application's
logger, while the `Info` is any additional info that should be returned. These are the only fields
that are not included in block header computations, so we don't need agreement
spec/abci++/abci++_methods.md
+9 -68
View File
@@ -323,10 +323,6 @@ title: Methods
| Name | Type | Description | Field Number |
|-------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------|--------------|
| tx_records | repeated [TxRecord](#txrecord) | Possibly modified list of transactions that have been picked as part of the proposed block. | 2 |
| app_hash | bytes | The Merkle root hash of the application state. | 3 |
| tx_results | repeated [ExecTxResult](#exectxresult) | List of structures containing the data resulting from executing the transactions | 4 |
| validator_updates | repeated [ValidatorUpdate](#validatorupdate) | Changes to validator set (set voting power to 0 to remove). | 5 |
| consensus_param_updates | [ConsensusParams](#consensusparams) | Changes to gas, size, and other consensus-related parameters. | 6 |
* **Usage**:
* `RequestPrepareProposal`'s parameters `txs`, `misbehavior`, `height`, `time`,
@@ -371,35 +367,9 @@ title: Methods
that the `RequestPrepareProposal.max_tx_bytes` limit is respected by those transaction
records returned in `ResponsePrepareProposal.tx_records` that are marked as `UNMODIFIED` or
`ADDED`.
* In same-block execution mode, the Application must provide values for
`ResponsePrepareProposal.app_hash`, `ResponsePrepareProposal.tx_results`,
`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:
* Height `H`: `NextValidatorsHash` includes the new `validator_updates` value.
* Height `H+1`: The validator set change takes effect and `ValidatorsHash` is updated.
* Height `H+2`: `*_last_commit` fields in `PrepareProposal`, `ProcessProposal`, and
`FinalizeBlock` now include the altered validator set.
* `ResponseFinalizeBlock.consensus_param_updates` returned for block `H` apply to the consensus
params for block `H+1` even if the change is agreed in block `H`.
For more information on the consensus parameters,
see the [consensus parameters](./abci%2B%2B_app_requirements.md#consensus-parameters)
section.
* It is the Application's responsibility 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.app_hash`, `ResponsePrepareProposal.tx_results`,
`ResponsePrepareProposal.validator_updates`, and `ResponsePrepareProposal.consensus_param_updates`.
* 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 Tendermint via
`ResponseFinalizeBlock`.
* Likewise, in next-block execution mode, the Application must keep all responses to executing
transactions until it can call `ResponseFinalizeBlock`.
* As a sanity check, Tendermint will check the returned parameters for validity if the Application modified them.
In particular, `ResponsePrepareProposal.tx_records` will be deemed invalid if
* There is a duplicate transaction in the list.
@@ -424,15 +394,9 @@ and _p_'s _validValue_ is `nil`:
returns from the call.
3. The Application uses the information received (transactions, commit info, misbehavior, time) to
(potentially) modify the proposal.
* in same-block execution mode, the Application fully executes the block and provides values
for `ResponsePrepareProposal.app_hash`, `ResponsePrepareProposal.tx_results`,
`ResponsePrepareProposal.validator_updates`, and
`ResponsePrepareProposal.consensus_param_updates`.
* in next-block execution mode, _p_'s Tendermint will ignore the values for
`ResponsePrepareProposal.app_hash`, `ResponsePrepareProposal.tx_results`,
`ResponsePrepareProposal.validator_updates`, and
`ResponsePrepareProposal.consensus_param_updates`.
* in both modes, the Application can manipulate transactions:
* the Application MAY fully execute the block and produce a candidate state &mdash; immediate
execution
* the Application can manipulate transactions:
* leave transactions untouched - `TxAction = UNMODIFIED`
* add new transactions (not present initially) to the proposal - `TxAction = ADDED`
* remove (invalid) transactions from the proposal and from the mempool - `TxAction = REMOVED`
@@ -471,10 +435,6 @@ proposal and will not call `RequestPrepareProposal`.
| Name | Type | Description | Field Number |
|-------------------------|--------------------------------------------------|-----------------------------------------------------------------------------------|--------------|
| status | [ProposalStatus](#proposalstatus) | `enum` that signals if the application finds the proposal valid. | 1 |
| app_hash | bytes | The Merkle root hash of the application state. | 2 |
| tx_results | repeated [ExecTxResult](#exectxresult) | List of structures containing the data resulting from executing the transactions. | 3 |
| validator_updates | repeated [ValidatorUpdate](#validatorupdate) | Changes to validator set (set voting power to 0 to remove). | 4 |
| consensus_param_updates | [ConsensusParams](#consensusparams) | Changes to gas, size, and other consensus-related parameters. | 5 |
* **Usage**:
* Contains all information on the proposed block needed to fully execute it.
@@ -489,15 +449,7 @@ proposal and will not call `RequestPrepareProposal`.
* The height and time values match the values from the header of the proposed block.
* If `ResponseProcessProposal.status` is `REJECT`, Tendermint assumes the proposal received
is not valid.
* In same-block execution mode, the Application is required to fully execute the block and provide values
for parameters `ResponseProcessProposal.app_hash`, `ResponseProcessProposal.tx_results`,
`ResponseProcessProposal.validator_updates`, and `ResponseProcessProposal.consensus_param_updates`,
so that Tendermint can then verify the hashes in the block's header are correct.
If the hashes mismatch, Tendermint will reject the block even if `ResponseProcessProposal.status`
was set to `ACCEPT`.
* In next-block execution mode, the Application should _not_ provide values for parameters
`ResponseProcessProposal.app_hash`, `ResponseProcessProposal.tx_results`,
`ResponseProcessProposal.validator_updates`, and `ResponseProcessProposal.consensus_param_updates`.
* The Application MAY fully execute the block &mdash; immediate execution
* The implementation of `ProcessProposal` MUST be deterministic. Moreover, the value of
`ResponseProcessProposal.status` MUST **exclusively** depend on the parameters passed in
the call to `RequestProcessProposal`, and the last committed Application state
@@ -669,10 +621,10 @@ message for round _r_, height _h_ from validator _q_ (_q_ &ne; _p_):
to determine rewards and punishments for the validators.
* The Application executes the transactions in `RequestFinalizeBlock.txs` deterministically,
according to the rules set up by the Application, before returning control to Tendermint.
Alternatively, it can commit the candidate state corresponding to the same block previously
Alternatively, it can apply the candidate state corresponding to the same block previously
executed via `PrepareProposal` or `ProcessProposal`.
* `ResponseFinalizeBlock.tx_results[i].Code == 0` only if the _i_-th transaction is fully valid.
* In next-block execution mode, the Application must provide values for `ResponseFinalizeBlock.app_hash`,
* The Application must provide values for `ResponseFinalizeBlock.app_hash`,
`ResponseFinalizeBlock.tx_results`, `ResponseFinalizeBlock.validator_updates`, and
`ResponseFinalizeBlock.consensus_param_updates` as a result of executing the block.
* The values for `ResponseFinalizeBlock.validator_updates`, or
@@ -688,16 +640,8 @@ message for round _r_, height _h_ from validator _q_ (_q_ &ne; _p_):
params for block `H+1`. For more information on the consensus parameters,
see the [consensus parameters](./abci%2B%2B_app_requirements.md#consensus-parameters)
section.
* In same-block execution mode, Tendermint will log an error and ignore values for
`ResponseFinalizeBlock.app_hash`, `ResponseFinalizeBlock.tx_results`, `ResponseFinalizeBlock.validator_updates`,
and `ResponsePrepareProposal.consensus_param_updates`, as those must have been provided by `PrepareProposal`.
* `ResponseFinalizeBlock.app_hash` contains an (optional) Merkle root hash of the application state.
* `ResponseFinalizeBlock.app_hash` is included
* [in next-block execution mode] as the `Header.AppHash` in the next block.
* [in same-block execution mode] as the `Header.AppHash` in the current block. In this case,
`PrepareProposal` is required to fully execute the block and set the App hash before
returning the proposed block to Tendermint.
* `ResponseFinalizeBlock.app_hash` is included as the `Header.AppHash` in the next block.
* `ResponseFinalizeBlock.app_hash` may also be empty or hard-coded, but MUST be
**deterministic** - it must not be a function of anything that did not come from the parameters
of `RequestFinalizeBlock` and the previous committed state.
@@ -707,9 +651,6 @@ message for round _r_, height _h_ from validator _q_ (_q_ &ne; _p_):
making the Application's state evolve in the context of state machine replication.
* Currently, Tendermint will fill up all fields in `RequestFinalizeBlock`, even if they were
already passed on to the Application via `RequestPrepareProposal` or `RequestProcessProposal`.
If the Application is in same-block execution mode, it applies the right candidate state here
(rather than executing the whole block). In this case the Application disregards all parameters in
`RequestFinalizeBlock` except `RequestFinalizeBlock.hash`.
#### When does Tendermint call `FinalizeBlock`?
@@ -830,8 +771,8 @@ Most of the data structures used in ABCI are shared [common data structures](../
| height | uint64 | The height at which the snapshot was taken (after commit). | 1 |
| format | uint32 | An application-specific snapshot format, allowing applications to version their snapshot data format and make backwards-incompatible changes. Tendermint does not interpret this. | 2 |
| chunks | uint32 | The number of chunks in the snapshot. Must be at least 1 (even if empty). | 3 |
| hash | bytes | TAn arbitrary snapshot hash. Must be equal only for identical snapshots across nodes. Tendermint does not interpret the hash, it only compares them. | 3 |
| metadata | bytes | Arbitrary application metadata, for example chunk hashes or other verification data. | 3 |
| hash | bytes | An arbitrary snapshot hash. Must be equal only for identical snapshots across nodes. Tendermint does not interpret the hash, it only compares them. | 4 |
| metadata | bytes | Arbitrary application metadata, for example chunk hashes or other verification data. | 5 |
* **Usage**:
* Used for state sync snapshots, see the [state sync section](../p2p/messages/state-sync.md) for details.