mirror of
https://github.com/tendermint/tendermint.git
synced 2026-01-25 22:22:04 +00:00
Compare commits
5 Commits
master
...
manuel/abc
| Author | SHA1 | Date | |
|---|---|---|---|
|
a4ecd0b87a | ||
|
|
3cfa248bb1 | ||
|
|
b0d266357e | ||
|
|
412293cc86 | ||
|
|
06d86a1408 |
@@ -306,97 +306,64 @@ title: Methods
|
||||
| consensus_param_updates | [ConsensusParams](#consensusparams) | Changes to consensus-critical gas, size, and other parameters. | 6 |
|
||||
| app_signed_updates | repeated bytes | Optional changes to the *app_signed* part of vote extensions. | 7 |
|
||||
|
||||
* **Usage**:
|
||||
* The first five parameters of `RequestPrepareProposal` are the same as `RequestProcessProposal`
|
||||
and `RequestFinalizeBlock`.
|
||||
* The header contains the height, timestamp, and more - it exactly matches the
|
||||
Tendermint block header.
|
||||
* `RequestPrepareProposal` contains a preliminary set of transactions `txs` that Tendermint considers to be a good block proposal, called _raw proposal_. The Application can modify this set via `ResponsePrepareProposal.tx_records` (see [TxRecord](#txrecord)).
|
||||
* In this case, the Application should set `ResponsePrepareProposal.modified_tx` to true.
|
||||
* The Application _can_ reorder, remove or add transactions to the raw proposal. Let `tx` be a transaction in `txs`:
|
||||
* If the Application considers that `tx` should not be proposed in this block, e.g., there are other transactions with higher priority, then it should not include it in `tx_records`. In this case, Tendermint won't remove `tx` from the mempool. The Application should be extra-careful, as abusing this feature may cause transactions to stay forever in the mempool.
|
||||
* If the Application considers that a `tx` should not be included in the proposal and removed from the mempool, then the Application should include it in `tx_records` and _mark_ it as "REMOVE". In this case, Tendermint will remove `tx` from the mempool.
|
||||
* If the Application wants to add a new transaction, then the Application should include it in `tx_records` and _mark_ it as "ADD". In this case, Tendermint will add it to the mempool.
|
||||
* The Application should be aware that removing and adding transactions may compromise _traceability_.
|
||||
> Consider the following example: the Application transforms a client-submitted transaction `t1` into a second transaction `t2`, i.e., the Application asks Tendermint to remove `t1` and add `t2` to the mempool. If a client wants to eventually check what happened to `t1`, it will discover that `t_1` is not in the mempool or in a committed block, getting the wrong idea that `t_1` did not make it into a block. Note that `t_2` _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 could attach to a transformed transaction a list with the hashes of the transactions it derives from.
|
||||
* If the Application modifies the set of transactions, the modified transactions MUST NOT exceed the configured maximum size `RequestPrepareProposal.max_tx_bytes`.
|
||||
* If the Application does not modify the preliminary set of transactions `txs`, then it sets `ResponsePrepareProposal.modified_tx` to false. In this case, Tendermint will ignore the contents of `ResponsePrepareProposal.tx_records`.
|
||||
* If the Application modifies the *app_signed* part of vote extensions via `ResponsePrepareProposal.app_signed_updates`,
|
||||
the new total size of those extensions cannot exceed their initial size.
|
||||
* The Application may choose to not modify the *app_signed* part of vote extensions by leaving parameter
|
||||
`ResponsePrepareProposal.app_signed_updates` empty.
|
||||
* 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:
|
||||
* `H`: `NextValidatorsHash` includes the new `validator_updates` value.
|
||||
* `H+1`: The validator set change takes effect and `ValidatorsHash` is updated.
|
||||
* `H+2`: `local_last_commit` now includes 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 [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_results`,
|
||||
`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.
|
||||
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.
|
||||
* A new or modified transaction is marked as "TXUNMODIFIED" or "TXREMOVED".
|
||||
* An unmodified transaction is marked as "TXADDED".
|
||||
* A transaction is marked as "TXUNKNOWN".
|
||||
* If Tendermint's sanity checks on the parameters of `ResponsePrepareProposal` fails, then it will drop the proposal
|
||||
and proceed to the next round (thus simulating a network loss/delay of the proposal).
|
||||
* **TODO**: [From discussion with William] Another possibility here is to panic. What do folks think we should do here?
|
||||
* The implementation of `PrepareProposal` can be non-deterministic.
|
||||
|
||||
#### When does Tendermint call it?
|
||||
**When does Tendermint call `RequestPrepareProposal`**
|
||||
|
||||
When a validator _p_ enters Tendermint consensus round _r_, height _h_, in which _p_ is the proposer,
|
||||
and _p_'s _validValue_ is `nil`:
|
||||
When a validator _p_ enters Tendermint consensus round _r_, height _h_, in which _p_ is the proposer, and _p_'s _validValue_ is `nil`. Note that, if _p_ has a non-`nil` _validValue_, Tendermint will use it as proposal and will not call `RequestPrepareProposal`.
|
||||
|
||||
1. _p_'s Tendermint collects outstanding transactions from the mempool
|
||||
* The transactions will be collected in order of priority
|
||||
* Let $C$ the list of currently collected transactions
|
||||
* The collection stops when any of the following conditions are met
|
||||
* the mempool is empty
|
||||
* the total size of transactions $\in C$ is greater than or equal to `consensusParams.block.max_bytes`
|
||||
* the sum of `GasWanted` field of transactions $\in C$ is greater than or equal to
|
||||
`consensusParams.block.max_gas`
|
||||
* _p_'s Tendermint creates a block header.
|
||||
2. _p_'s Tendermint calls `RequestPrepareProposal` with the newly generated block.
|
||||
* The first five parameters of `RequestPrepareProposal` are the same as `RequestProcessProposal` and `RequestFinalizeBlock`.
|
||||
* The header contains the height, timestamp, and more - it exactly matches the Tendermint block header.
|
||||
* _p_'s Tendermint collects outstanding transactions from the mempool
|
||||
* The transactions will be collected in order of priority
|
||||
* Let $C$ the list of currently collected transactions
|
||||
* The collection stops when any of the following conditions are met
|
||||
* the mempool is empty
|
||||
* the total size of transactions $\in C$ is greater than or equal to `consensusParams.block.max_bytes`
|
||||
* the sum of `GasWanted` field of transactions $\in C$ is greater than or equal to `consensusParams.block.max_gas`
|
||||
* _p_'s Tendermint creates a block header.
|
||||
* _p_'s Tendermint calls `RequestPrepareProposal` with the newly generated block.
|
||||
The call is synchronous: Tendermint's execution will block until the Application returns from the call.
|
||||
3. The Application checks the block (header, transactions, commit info, evidences). Besides,
|
||||
* in same-block execution mode, the Application can (and should) provide `ResponsePrepareProposal.app_hash`,
|
||||
`ResponsePrepareProposal.validator_updates`, or
|
||||
`ResponsePrepareProposal.consensus_param_updates`.
|
||||
* in "next-block execution" mode, _p_'s Tendermint will ignore the values for `ResponsePrepareProposal.app_hash`,
|
||||
`ResponsePrepareProposal.validator_updates`, and `ResponsePrepareProposal.consensus_param_updates`.
|
||||
* in both modes, the Application can manipulate transactions
|
||||
* leave transactions untouched - `TxAction = UNMODIFIED`
|
||||
* add new transactions (not previously in the mempool) - `TxAction = ADDED`
|
||||
* remove transactions (invalid) from the proposal and from the mempool - `TxAction = REMOVED`
|
||||
* remove transactions from the proposal but not from the mempool (effectively _delaying_ them) - the
|
||||
Application removes the transaction from the list
|
||||
* modify transactions (e.g. aggregate them) - `TxAction = ADDED` followed by `TxAction = REMOVED`. As explained above, this compromises client traceability, unless it is implemented at the Application level.
|
||||
* reorder transactions - the Application reorders transactions in the list
|
||||
4. If the block is modified, the Application sets `ResponsePrepareProposal.modified` to true,
|
||||
and includes the modified block in the return parameters (see the rules in section _Usage_).
|
||||
The Application returns from the call.
|
||||
5. _p_'s Tendermint uses the (possibly) modified block as _p_'s proposal in round _r_, height _h_.
|
||||
|
||||
Note that, if _p_ has a non-`nil` _validValue_, Tendermint will use it as proposal and will not call `RequestPrepareProposal`.
|
||||
**How the Application handles `RequestPrepareProposal`**
|
||||
|
||||
* The Application first checks the block (header, transactions, commit info, evidences).
|
||||
* `RequestPrepareProposal` contains a preliminary set of transactions `txs` that Tendermint considers to be a good block proposal, called _raw proposal_. The Application can modify this set via `ResponsePrepareProposal.tx_records` (see [TxRecord](#txrecord)).
|
||||
* In this case, the Application should set `ResponsePrepareProposal.modified_tx` to true.
|
||||
* The Application _can_ reorder, remove or add transactions to the raw proposal. Let `tx` be a transaction in `txs`:
|
||||
* If the Application wants to leave `tx` untouched, then it has to include it in `tx_records` and _mark_ it as "TXUNMODIFIED".
|
||||
* If the Application considers that `tx` should not be proposed in this block, e.g., there are other transactions with higher priority, then it should not include it in `tx_records`. In this case, Tendermint won't remove `tx` from the mempool. The Application should be extra-careful, as abusing this feature may cause transactions to stay forever in the mempool.
|
||||
* If the Application considers that a `tx` should not be included in the proposal and removed from the mempool, then the Application should include it in `tx_records` and _mark_ it as "TXREMOVED". In this case, Tendermint will remove `tx` from the mempool.
|
||||
* If the Application wants to add a new transaction, then the Application should include it in `tx_records` and _mark_ it as "TXADDED". In this case, Tendermint will add it to the mempool.
|
||||
* **TODO** shall we add transformation, i.e., remove a transaction `t1` and add second transaction `t2`, as one bullet here? Maybe we should to connect it better to the next paragraph.
|
||||
* The Application should be aware that removing and adding transactions may compromise _traceability_.
|
||||
> Consider the following example: the Application transforms a client-submitted transaction `t1` into a second transaction `t2`, i.e., the Application asks Tendermint to remove `t1` and add `t2` to the mempool. If a client wants to eventually check what happened to `t1`, it will discover that `t_1` is not in the mempool or in a committed block, getting the wrong idea that `t_1` did not make it into a block. Note that `t_2` _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 could attach to a transformed transaction a list with the hashes of the transactions it derives from.
|
||||
* If the Application modifies the set of transactions, the modified transactions MUST NOT exceed the configured maximum size `RequestPrepareProposal.max_tx_bytes`.
|
||||
* If the Application does not modified the prelimnary set of transactions `txs`, then it sets `ResponsePrepareProposal.modified_tx` to false. In this case, Tendermint will ignore the contents of `ResponsePrepareProposal.tx_records`.
|
||||
* If the Application modifies the *app_signed* part of vote extensions via `ResponsePrepareProposal.app_signed_updates`, the new total size of those extensions cannot exceed their initial size.
|
||||
* The Application may choose to not modify the *app_signed* part of vote extensions by leaving parameter `ResponsePrepareProposal.app_signed_updates` empty.
|
||||
* 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:
|
||||
* `H`: `NextValidatorsHash` includes the new `validator_updates` value.
|
||||
* `H+1`: The validator set change takes effect and `ValidatorsHash` is updated.
|
||||
* `H+2`: `local_last_commit` now includes 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 [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_results`,`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. 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`.
|
||||
* The implementation of `PrepareProposal` can be non-deterministic.
|
||||
|
||||
|
||||
**How Tendermint handles `ResponsePrepareProposal`**
|
||||
|
||||
* Tendermint first checks 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.
|
||||
* A new or modified transaction is marked as "TXUNMODIFIED" or "TXREMOVED".
|
||||
* An unmodified transaction is marked as "TXADDED".
|
||||
* A transaction is marked as "TXUNKNOWN".
|
||||
* If Tendermint's sanity checks on the parameters of `ResponsePrepareProposal` fail, then it will drop the proposal and proceed to the next round (thus simulating a network loss/delay of the proposal). **TODO**: [From discussion with William] Another possibility here is to panic. What do folks think we should do here?
|
||||
* If Tendermint's sanity checks on the parameters of `ResponsePrepareProposal` pass, p_'s Tendermint uses the (possibly) modified block as _p_'s proposal in round _r_, height _h_.
|
||||
|
||||
### ProcessProposal
|
||||
|
||||
@@ -422,60 +389,43 @@ Note that, if _p_ has a non-`nil` _validValue_, Tendermint will use it as propos
|
||||
| validator_updates | repeated [ValidatorUpdate](#validatorupdate) | Changes to validator set (set voting power to 0 to remove). | 4 |
|
||||
| consensus_param_updates | [ConsensusParams](#consensusparams) | Changes to consensus-critical gas, size, and other parameters. | 5 |
|
||||
|
||||
* **Usage**:
|
||||
* Contains a full proposed block.
|
||||
* The parameters and types of `RequestProcessProposal` are the same as `RequestPrepareProposal`
|
||||
and `RequestFinalizeBlock`.
|
||||
* The Application may fully execute the block as though it was handling `RequestFinalizeBlock`.
|
||||
However, any resulting state changes must be kept as _canditade state_,
|
||||
and the Application should be ready to backtrack/discard it in case the decided block is different.
|
||||
* The header exactly matches the Tendermint header of the proposed block.
|
||||
* In next-block execution mode, the header hashes _AppHash_, _LastResultHash_, _ValidatorHash_,
|
||||
and _ConsensusHash_ refer to the **last committed block** (data was provided by the last call to
|
||||
`ResponseFinalizeBlock`).
|
||||
* In same-block execution mode, the header hashes _AppHash_, _LastResultHash_, _ValidatorHash_,
|
||||
and _ConsensusHash_ refer to the **same** block being passed in the `Request*` call to this
|
||||
method (data was provided by the call to `ResponsePrepareProposal` at the current height that
|
||||
resulted in the block being passed in the `Request*` call to this method)
|
||||
* If `ResponseProcessProposal.accept` is _false_, 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.accept`
|
||||
was set to _true_.
|
||||
* 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 implementation of `ProcessProposal` MUST be deterministic. Moreover, the value of
|
||||
`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_,
|
||||
unless they _really_ know what the potential liveness implications of returning _false_ are.
|
||||
**When does Tendermint call it?**
|
||||
|
||||
Let _p_ be a validator that enters consensus round _r_, height _h_, in which _q_ is the proposer (possibly _p_ = _q_). Assume that _p_ receives a Proposal message and all the block parts for round _r_, height _h_ from _q_. If _p_ is not locked on a block, then Tendermint calls `RequestProcessProposal` with the full proposed block.
|
||||
|
||||
* The call is synchronous.
|
||||
|
||||
* The parameters and types of `RequestProcessProposal` are the same as `RequestPrepareProposal` and `RequestFinalizeBlock`.
|
||||
|
||||
**How the Application handles `RequestProcessProposal`**
|
||||
|
||||
* The Application checks/processes the proposed block, which is read-only, and returns true (_accept_) or false (_reject_) in `ResponseProcessProposal.accept`.
|
||||
|
||||
* The Application, depending on its needs, may call `ResponseProcessProposal`
|
||||
* either after it has completely processed the block (the simpler case),
|
||||
* or immediately (after doing some basic checks), and process the block asynchronously. In this case the Application will not be able to reject the block, or force prevote/precommit `nil` afterwards.
|
||||
|
||||
* The Application may fully execute the block as though it was handling `RequestFinalizeBlock`. However, any resulting state changes must be kept as _canditade state_, and the Application should be ready to backtrack/discard it in case the decided block is different.
|
||||
|
||||
* The header exactly matches the Tendermint header of the proposed block.
|
||||
* In next-block execution mode, the header hashes _AppHash_, _LastResultHash_, _ValidatorHash_,
|
||||
and _ConsensusHash_ refer to the **last committed block** (data was provided by the last call to `ResponseFinalizeBlock`).
|
||||
* In same-block execution mode, the header hashes _AppHash_, _LastResultHash_, _ValidatorHash_, and _ConsensusHash_ refer to the **same** block being passed in the `Request*` call to this method (data was provided by the call to `ResponsePrepareProposal` at the current height that resulted in the block being passed in the `Request*` call to this method).
|
||||
|
||||
* 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.accept` was set to _true_.
|
||||
|
||||
* 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 implementation of `ProcessProposal` MUST be deterministic. Moreover, the value of `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_, unless they _really_ know what the potential liveness implications of returning _false_ are.
|
||||
|
||||
>**TODO**: should `ResponseProcessProposal.accept` be of type `Result` rather than `bool`? (so we are able to extend the possible values in the future?)
|
||||
|
||||
#### When does Tendermint call it?
|
||||
**How Tendermint handles `ResponseProcessProposal`**
|
||||
|
||||
When a validator _p_ enters Tendermint consensus round _r_, height _h_, in which _q_ is the proposer (possibly _p_ = _q_):
|
||||
|
||||
1. _p_ sets up timer `ProposeTimeout`.
|
||||
2. If _p_ is the proposer, _p_ executes steps 1-6 in [PrepareProposal](#prepareproposal).
|
||||
3. Upon reception of Proposal message (which contains the header) for round _r_, height _h_ from _q_, _p_'s Tendermint verifies the block header.
|
||||
4. Upon reception of Proposal message, along with all the block parts, for round _r_, height _h_ from _q_, _p_'s Tendermint follows its algorithm
|
||||
to check whether it should prevote for the block just received, or `nil`
|
||||
5. If Tendermint should prevote for the block just received
|
||||
1. Tendermint calls `RequestProcessProposal` with the block. The call is synchronous.
|
||||
2. The Application checks/processes the proposed block, which is read-only, and returns true (_accept_) or false (_reject_) in `ResponseProcessProposal.accept`.
|
||||
* The Application, depending on its needs, may call `ResponseProcessProposal`
|
||||
* either after it has completely processed the block (the simpler case),
|
||||
* or immediately (after doing some basic checks), and process the block asynchronously. In this case the Application will
|
||||
not be able to reject the block, or force prevote/precommit `nil` afterwards.
|
||||
3. If the returned value is
|
||||
* _accept_, Tendermint prevotes on this proposal for round _r_, height _h_.
|
||||
* _reject_, Tendermint prevotes `nil`.
|
||||
* If `ResponseProcessProposal.accept` is _true_, then Tendermint prevotes on this proposal for round _r_, height _h_.
|
||||
* If `ResponseProcessProposal.accept` is _false_, then Tendermint assumes the proposal received is not valid and prevotes `nil`.
|
||||
|
||||
### ExtendVote
|
||||
|
||||
@@ -494,38 +444,42 @@ When a validator _p_ enters Tendermint consensus round _r_, height _h_, in which
|
||||
|-------------------|-------|-----------------------------------------------|--------------|
|
||||
| vote_extension | bytes | Optional information signed by by Tendermint. | 1 |
|
||||
|
||||
* **Usage**:
|
||||
* `ResponseExtendVote.vote_extension` is optional information that, if present, will be signed by Tendermint and
|
||||
attached to the Precommit message.
|
||||
* `RequestExtendVote.hash` corresponds to the hash of a proposed block that was made available to the application
|
||||
in a previous call to `ProcessProposal` or `PrepareProposal` for the current height.
|
||||
* `ResponseExtendVote.vote_extension` will only be attached to a non-`nil` Precommit message. If Tendermint is to
|
||||
precommit `nil`, it will not call `RequestExtendVote`.
|
||||
* The Application logic that creates the extension can be non-deterministic.
|
||||
**When does Tendermint call `RequestExtendVote`?**
|
||||
|
||||
#### When does Tendermint call it?
|
||||
|
||||
When a validator _p_ is in Tendermint consensus state _prevote_ of round _r_, height _h_, in which _q_ is the proposer; and _p_ has received
|
||||
When a validator _p_ is in Tendermint consensus state _prevote_ of round _r_, height _h_, in which _q_ is the proposer; and _p_ has received:
|
||||
|
||||
* the Proposal message _v_ for round _r_, height _h_, along with all the block parts, from _q_,
|
||||
* `Prevote` messages from _2f + 1_ validators' voting power for round _r_, height _h_, prevoting for the same block _id(v)_,
|
||||
|
||||
then _p_'s Tendermint locks _v_ and sends a Precommit message in the following way
|
||||
then _p_'s Tendermint first locks _v_: sets _lockedValue_ and _validValue_ to _v_, and sets _lockedRound_ and _validRound_ to _r_. Following, _p_'s Tendermint calls `RequestExtendVote`.
|
||||
|
||||
1. _p_'s Tendermint sets _lockedValue_ and _validValue_ to _v_, and sets _lockedRound_ and _validRound_ to _r_
|
||||
2. _p_'s Tendermint calls `RequestExtendVote` with _id(v)_ (`RequestExtendVote.hash`). The call is synchronous.
|
||||
3. The Application optionally returns an array of bytes, `ResponseExtendVote.extension`, which is not interpreted by Tendermint.
|
||||
4. _p_'s Tendermint includes `ResponseExtendVote.extension` in a field of type [CanonicalVoteExtension](#canonicalvoteextension),
|
||||
* `RequestExtendVote.hash` corresponds to the hash of a proposed block that was made available to the application in a previous call to `ProcessProposal` or `PrepareProposal` for the current height.
|
||||
|
||||
* The call is synchronous.
|
||||
|
||||
In the cases when _p_'s Tendermint is to broadcast `precommit nil` messages (either _2f+1_ `prevote nil` messages received, or _timeoutPrevote_ triggered), _p_'s Tendermint does **not** call `RequestExtendVote` and will not include
|
||||
a [CanonicalVoteExtension](#canonicalvoteextension) field in the `precommit nil` message.
|
||||
|
||||
**How the Application handles `RequestExtendVote`**
|
||||
|
||||
* `ResponseExtendVote.vote_extension` is optional information that, if present, will be signed by Tendermint and attached to the Precommit message.
|
||||
|
||||
* The Application logic that creates the extension can be non-deterministic.
|
||||
|
||||
**How Tendermint handles `ResponseExtendVote`**
|
||||
|
||||
* The Application optionally returns an array of bytes, `ResponseExtendVote.extension`, which is not interpreted by Tendermint.
|
||||
|
||||
* _p_'s Tendermint includes `ResponseExtendVote.extension` in a field of type [CanonicalVoteExtension](#canonicalvoteextension),
|
||||
it then populates the other fields in [CanonicalVoteExtension](#canonicalvoteextension), and signs the populated
|
||||
data structure.
|
||||
5. _p_'s Tendermint constructs and signs the [CanonicalVote](../core/data_structures.md#canonicalvote) structure.
|
||||
6. _p_'s Tendermint constructs the Precommit message (i.e. [Vote](../core/data_structures.md#vote) structure)
|
||||
using [CanonicalVoteExtension](#canonicalvoteextension) and [CanonicalVote](../core/data_structures.md#canonicalvote).
|
||||
7. _p_'s Tendermint broadcasts the Precommit message.
|
||||
|
||||
In the cases when _p_'s Tendermint is to broadcast `precommit nil` messages (either _2f+1_ `prevote nil` messages received,
|
||||
or _timeoutPrevote_ triggered), _p_'s Tendermint does **not** call `RequestExtendVote` and will not include
|
||||
a [CanonicalVoteExtension](#canonicalvoteextension) field in the `precommit nil` message.
|
||||
* _p_'s Tendermint constructs and signs the [CanonicalVote](../core/data_structures.md#canonicalvote) structure.
|
||||
|
||||
* _p_'s Tendermint constructs the Precommit message (i.e. [Vote](../core/data_structures.md#vote) structure)
|
||||
using [CanonicalVoteExtension](#canonicalvoteextension) and [CanonicalVote](../core/data_structures.md#canonicalvote).
|
||||
|
||||
* _p_'s Tendermint broadcasts the Precommit message.
|
||||
|
||||
### VerifyVoteExtension
|
||||
|
||||
@@ -546,29 +500,27 @@ a [CanonicalVoteExtension](#canonicalvoteextension) field in the `precommit nil`
|
||||
|--------|------|-------------------------------------------------------|--------------|
|
||||
| accept | bool | If false, Application is rejecting the vote extension | 1 |
|
||||
|
||||
* **Usage**:
|
||||
* If `ResponseVerifyVoteExtension.accept` is _false_, Tendermint will reject the whole received vote.
|
||||
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
|
||||
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_,
|
||||
unless they _really_ know what the potential liveness implications of returning _false_ are.
|
||||
|
||||
#### When does Tendermint call it?
|
||||
**When does Tendermint call `RequestVerifyVoteExtension`?**
|
||||
|
||||
When a validator _p_ is in Tendermint consensus round _r_, height _h_, state _prevote_ (**TODO** discuss: I think I must remove the state
|
||||
from this condition, but not sure), and _p_ receives a Precommit message for round _r_, height _h_ from _q_:
|
||||
from this condition, but not sure), and _p_ receives a Precommit message for round _r_, height _h_ from _q_.
|
||||
|
||||
1. _p_'s Tendermint calls `RequestVerifyVoteExtension`.
|
||||
2. The Application returns _accept_ or _reject_ via `ResponseVerifyVoteExtension.accept`.
|
||||
3. If the Application returns
|
||||
* _accept_, _p_'s Tendermint will keep the received vote, together with its corresponding
|
||||
vote extension in its internal data structures. It will be used to populate the [ExtendedCommitInfo](#extendedcommitinfo)
|
||||
**How the Application handles `RequestVerifyVoteExtension`**
|
||||
|
||||
* The Application returns _accept_ or _reject_ via `ResponseVerifyVoteExtension.accept`.
|
||||
|
||||
* The implementation of `VerifyVoteExtension` MUST be deterministic.
|
||||
|
||||
* Moreover, the value of `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).
|
||||
|
||||
* Application implementors SHOULD always set `ResponseVerifyVoteExtension.accept` to _true_, unless they _really_ know what the potential liveness implications of returning _false_ are.
|
||||
|
||||
**How Tendermint handles `ResponseVerifyVoteExtension`**
|
||||
|
||||
* If `ResponseVerifyVoteExtension.accept` is _true_, then _p_'s Tendermint will keep the received vote, together with its corresponding vote extension in its internal data structures. It will be used to populate the [ExtendedCommitInfo](#extendedcommitinfo)
|
||||
structure in calls to `RequestPrepareProposal`, in rounds of height _h + 1_ where _p_ is the proposer.
|
||||
* _reject_, _p_'s Tendermint will deem the Precommit message invalid and discard it.
|
||||
|
||||
* If `ResponseVerifyVoteExtension.accept` is _false_, then _p_'s Tendermint will deem the Precommit message invalid and discard it. See the [Requirements](abci++_app_requirements_002_draft.md) section to understand the potential liveness implications of this.
|
||||
|
||||
### FinalizeBlock
|
||||
|
||||
@@ -595,79 +547,73 @@ from this condition, but not sure), and _p_ receives a Precommit message for rou
|
||||
| app_hash | bytes | The Merkle root hash of the application state. | 5 |
|
||||
| retain_height | int64 | Blocks below this height may be removed. Defaults to `0` (retain all). | 6 |
|
||||
|
||||
* **Usage**:
|
||||
* Contains a newly decided block.
|
||||
* This method is equivalent to the call sequence `BeginBlock`, [`DeliverTx`],
|
||||
`EndBlock`, `Commit` in the previous version of ABCI.
|
||||
* The header exactly matches the Tendermint header of the proposed block.
|
||||
* The Application can use `RequestFinalizeBlock.decided_last_commit` and `RequestFinalizeBlock.byzantine_validators`
|
||||
to determine rewards and punishments for the validators.
|
||||
* The application must execute the transactions in full, in the order they appear in `RequestFinalizeBlock.txs`,
|
||||
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_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`,
|
||||
`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
|
||||
`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:
|
||||
- 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`: `decided_last_commit` now includes 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 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`.
|
||||
* Application is expected to persist its state at the end of this call, before calling `ResponseFinalizeBlock`.
|
||||
* `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` 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.
|
||||
* Later calls to `Query` can return proofs about the application state anchored
|
||||
in this Merkle root hash.
|
||||
* Use `ResponseFinalizeBlock.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
|
||||
non-persisted heights, light client verification, and so on.
|
||||
* Just as `ProcessProposal`, the implementation of `FinalizeBlock` MUST be deterministic, since it is
|
||||
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 it?
|
||||
**When does Tendermint call `RequestFinalizeBlock`?**
|
||||
|
||||
When a validator _p_ is in Tendermint consensus height _h_, and _p_ receives
|
||||
|
||||
* the Proposal message with block _v_ for a round _r_, along with all its block parts, from _q_,
|
||||
which is the proposer of round _r_, height _h_,
|
||||
* `Precommit` messages from _2f + 1_ validators' voting power for round _r_, height _h_,
|
||||
precommitting the same block _id(v)_,
|
||||
* the Proposal message with block _v_ for a round _r_, along with all its block parts, from _q_, which is the proposer of round _r_, height _h_,
|
||||
* `Precommit` messages from _2f + 1_ validators' voting power for round _r_, height _h_, precommitting the same block _id(v)_,
|
||||
|
||||
then _p_'s Tendermint decides block _v_ and finalizes consensus for height _h_ in the following way
|
||||
|
||||
1. _p_'s Tendermint persists _v_ as decision for height _h_.
|
||||
2. _p_'s Tendermint locks the mempool -- no calls to checkTx on new transactions.
|
||||
3. _p_'s Tendermint calls `RequestFinalizeBlock` with _id(v)_. The call is synchronous.
|
||||
4. _p_'s Application processes block _v_, received in a previous call to `RequestProcessProposal`.
|
||||
5. _p_'s Application commits and persists the state resulting from processing the block.
|
||||
6. _p_'s Application calculates and returns the _AppHash_, along with an array of arrays of bytes representing the output of each of the transactions
|
||||
7. _p_'s Tendermint hashes the array of transaction outputs and stores it in _ResultHash_
|
||||
8. _p_'s Tendermint persists _AppHash_ and _ResultHash_
|
||||
9. _p_'s Tendermint unlocks the mempool -- newly received transactions can now be checked.
|
||||
10. _p_'s starts consensus for a new height _h+1_, round 0
|
||||
* _p_'s Tendermint persists _v_ as decision for height _h_.
|
||||
* _p_'s Tendermint locks the mempool -- no calls to checkTx on new transactions.
|
||||
* _p_'s Tendermint calls `RequestFinalizeBlock` with _id(v)_. The call is synchronous.
|
||||
|
||||
**How the Application handles `RequestFinalizeBlock`**
|
||||
|
||||
* Contains a newly decided block.
|
||||
|
||||
* The header exactly matches the Tendermint header of the proposed block.
|
||||
|
||||
* Just as `ProcessProposal`, the implementation of `FinalizeBlock` MUST be deterministic, since it is
|
||||
making the Application's state evolve in the context of state machine replication.
|
||||
|
||||
* This method is equivalent to the call sequence `BeginBlock`, [`DeliverTx`], `EndBlock`, `Commit` in the previous version of ABCI.
|
||||
|
||||
* The application must execute the transactions in full, in the order they appear in `RequestFinalizeBlock.txs`, before returning control to Tendermint. Alternatively, it can commit the candidate state corresponding to the same block previously executed via `PrepareProposal` or `ProcessProposal`.
|
||||
|
||||
* The Application calculates and returns the _AppHash_, along with an array of arrays of bytes representing the output of each of the transactions.
|
||||
|
||||
* The Application can use `RequestFinalizeBlock.decided_last_commit` and `RequestFinalizeBlock.byzantine_validators`to determine rewards and punishments for the validators.
|
||||
|
||||
* `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` `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 `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:
|
||||
- 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`: `decided_last_commit` now includes 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 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` 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.
|
||||
|
||||
* Use `ResponseFinalizeBlock.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 non-persisted heights, light client verification, and so on.
|
||||
|
||||
* Application is expected to persist the state resulting from processing the block at the end of this call, before calling `ResponseFinalizeBlock`.
|
||||
|
||||
* Later calls to `Query` can return proofs about the application state anchored in this Merkle root hash.
|
||||
|
||||
* 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`.
|
||||
|
||||
**How Tendermint handles `ResponseFinalizeBlock`**
|
||||
|
||||
* Tendermint hashes the array of transaction outputs and stores it in _ResultHash_
|
||||
|
||||
* Tendermint persists _AppHash_ and _ResultHash_
|
||||
|
||||
* Tendermint unlocks the mempool -- newly received transactions can now be checked.
|
||||
|
||||
* The validator starts consensus for a new height _h+1_, round 0
|
||||
|
||||
## Data Types existing in ABCI
|
||||
|
||||
|
||||
Reference in New Issue
Block a user