From 1543e4122aa4f154176982f2ea35bf76878c1994 Mon Sep 17 00:00:00 2001 From: Sergio Mena Date: Fri, 28 Jan 2022 15:03:23 +0100 Subject: [PATCH] Added all ABCI++ APIs to protobufs --- proto/tendermint/abci/types.proto | 145 +++++++++++++----- spec/abci++/abci++_methods_002_draft.md | 189 +++++++++++++----------- 2 files changed, 208 insertions(+), 126 deletions(-) diff --git a/proto/tendermint/abci/types.proto b/proto/tendermint/abci/types.proto index 0c102ebdc..1d21171fc 100644 --- a/proto/tendermint/abci/types.proto +++ b/proto/tendermint/abci/types.proto @@ -36,9 +36,10 @@ message Request { RequestLoadSnapshotChunk load_snapshot_chunk = 13; RequestApplySnapshotChunk apply_snapshot_chunk = 14; RequestPrepareProposal prepare_proposal = 15; - RequestExtendVote extend_vote = 16; - RequestVerifyVoteExtension verify_vote_extension = 17; - RequestFinalizeBlock finalize_block = 18; + RequestProcessProposal process_proposal = 16; + RequestExtendVote extend_vote = 17; + RequestVerifyVoteExtension verify_vote_extension = 18; + RequestFinalizeBlock finalize_block = 19; } } @@ -121,29 +122,45 @@ message RequestApplySnapshotChunk { string sender = 3; } +message RequestPrepareProposal { + bytes hash = 1; + tendermint.types.Header header = 2 [(gogoproto.nullable) = false]; + // txs is an array of transactions that will be included in a block, + // sent to the app for possible modifications. + repeated bytes txs = 3; + LastCommitInfo last_commit_info = 4 [(gogoproto.nullable) = false]; + repeated Evidence byzantine_validators = 5 [(gogoproto.nullable) = false]; + // the modified transactions cannot exceed this size. + int64 max_tx_bytes = 6; +} + +message RequestProcessProposal { + bytes hash = 1; + tendermint.types.Header header = 2 [(gogoproto.nullable) = false]; + repeated bytes txs = 3; + LastCommitInfo last_commit_info = 4 [(gogoproto.nullable) = false]; + repeated Evidence byzantine_validators = 5 [(gogoproto.nullable) = false]; +} + // Extends a vote with application-side injection message RequestExtendVote { - types.Vote vote = 1; + bytes hash = 1; + int64 height = 2; } // Verify the vote extension message RequestVerifyVoteExtension { - types.Vote vote = 1; -} - -message RequestPrepareProposal { - // block_data is an array of transactions that will be included in a block, - // sent to the app for possible modifications. - // applications can not exceed the size of the data passed to it. - repeated bytes block_data = 1; - // If an application decides to populate block_data with extra information, they can not exceed this value. - int64 block_data_size = 2; + bytes app_signed = 1; + bytes tendermint_signed = 2; + bytes hash = 3; + bytes validator_address = 4; + int64 height = 5; } message RequestFinalizeBlock { - repeated bytes txs = 1; - bytes hash = 2; - tendermint.types.Header header = 3 [(gogoproto.nullable) = false]; + bytes hash = 1; + tendermint.types.Header header = 2 [(gogoproto.nullable) = false]; + repeated bytes txs = 3; LastCommitInfo last_commit_info = 4 [(gogoproto.nullable) = false]; repeated Evidence byzantine_validators = 5 [(gogoproto.nullable) = false]; } @@ -169,9 +186,10 @@ message Response { ResponseLoadSnapshotChunk load_snapshot_chunk = 14; ResponseApplySnapshotChunk apply_snapshot_chunk = 15; ResponsePrepareProposal prepare_proposal = 16; - ResponseExtendVote extend_vote = 17; - ResponseVerifyVoteExtension verify_vote_extension = 18; - ResponseFinalizeBlock finalize_block = 19; + ResponseProcessProposal process_proposal = 17; + ResponseExtendVote extend_vote = 18; + ResponseVerifyVoteExtension verify_vote_extension = 19; + ResponseFinalizeBlock finalize_block = 20; } } @@ -225,8 +243,8 @@ message ResponseCheckTx { bytes data = 2; string log = 3; // nondeterministic string info = 4; // nondeterministic - int64 gas_wanted = 5 [json_name = "gas_wanted"]; - int64 gas_used = 6 [json_name = "gas_used"]; + int64 gas_wanted = 5; + int64 gas_used = 6; repeated Event events = 7 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"]; string codespace = 8; string sender = 9; @@ -298,30 +316,41 @@ message ResponseApplySnapshotChunk { } } -message ResponseExtendVote { - tendermint.types.VoteExtension vote_extension = 1; +message ResponsePrepareProposal { + bool modified_tx = 1; + repeated TxRecord tx_records = 2; + bytes app_hash = 3; + repeated ExecTxResult tx_results = 4; + repeated ValidatorUpdate validator_updates = 5; + tendermint.types.ConsensusParams consensus_param_updates = 6; + repeated bytes app_signed_updates = 7; } -message ResponseVerifyVoteExtension { - Result result = 1; +message ResponseProcessProposal { + bool accept = 1; + bytes app_hash = 2; + repeated ExecTxResult tx_results = 3; + repeated ValidatorUpdate validator_updates = 4; + tendermint.types.ConsensusParams consensus_param_updates = 5; +} - enum Result { - UNKNOWN = 0; // Unknown result, treat as ACCEPT by default - ACCEPT = 1; // Vote extension verified, include the vote - SLASH = 2; // Vote extension verification aborted, continue but slash validator - REJECT = 3; // Vote extension invalidated - } +message ResponseExtendVote { + bytes app_signed = 1; + bytes tendermint_signed = 2; } -message ResponsePrepareProposal { - repeated bytes block_data = 1; +message ResponseVerifyVoteExtension { + bool accept = 1; } message ResponseFinalizeBlock { - repeated ResponseDeliverTx txs = 1; - repeated ValidatorUpdate validator_updates = 2 [(gogoproto.nullable) = false]; - tendermint.types.ConsensusParams consensus_param_updates = 3; - repeated Event events = 4 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"]; + repeated Event block_events = 1 + [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"]; + repeated ExecTxResult tx_results = 2; + repeated ValidatorUpdate validator_updates = 3; + tendermint.types.ConsensusParams consensus_param_updates = 4; + bytes app_hash = 5; + int64 retain_height = 6; } //---------------------------------------- @@ -347,6 +376,21 @@ message EventAttribute { bool index = 3; // nondeterministic } +// ExecTxResult contains results of executing one individual transaction. +// +// * Its structure is equivalent to #ResponseDeliverTx which will be deprecated/deleted +message ExecTxResult { + uint32 code = 1; + bytes data = 2; + string log = 3; // nondeterministic + string info = 4; // nondeterministic + int64 gas_wanted = 5; + int64 gas_used = 6; + repeated Event tx_events = 7 + [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"]; // nondeterministic + string codespace = 8; +} + // TxResult contains results of executing the transaction. // // One usage is indexing transaction results. @@ -357,6 +401,21 @@ message TxResult { ResponseDeliverTx result = 4 [(gogoproto.nullable) = false]; } +message TxRecord { + TxAction action = 1; + bytes tx = 2; + repeated bytes new_hashes = 3; + + // TxAction contains App-provided information on what to do with a transaction that is part of a raw proposal + enum TxAction { + UNKNOWN = 0; // Unknown action + UNMODIFIED = 1; // The Application did not modify this transaction. Ignore new_hashes field + ADDED = 2; // The Application added this transaction. Ignore new_hashes field + REMOVED = 3; // The Application wants this transaction removed from the proposal and the mempool. + // Use #new_hashes field if the transaction was modified + } +} + //---------------------------------------- // Blockchain Types @@ -375,8 +434,10 @@ message ValidatorUpdate { // VoteInfo message VoteInfo { - Validator validator = 1 [(gogoproto.nullable) = false]; - bool signed_last_block = 2; + Validator validator = 1 [(gogoproto.nullable) = false]; + bool signed_last_block = 2; + bytes tendermint_signed_extension = 3; + bytes app_signed_extension = 4; } enum EvidenceType { @@ -425,7 +486,9 @@ service ABCIApplication { rpc OfferSnapshot(RequestOfferSnapshot) returns (ResponseOfferSnapshot); rpc LoadSnapshotChunk(RequestLoadSnapshotChunk) returns (ResponseLoadSnapshotChunk); rpc ApplySnapshotChunk(RequestApplySnapshotChunk) returns (ResponseApplySnapshotChunk); + rpc PrepareProposal(RequestPrepareProposal) returns (ResponsePrepareProposal); + rpc ProcessProposal(RequestProcessProposal) returns (ResponseProcessProposal); rpc ExtendVote(RequestExtendVote) returns (ResponseExtendVote); rpc VerifyVoteExtension(RequestVerifyVoteExtension) returns (ResponseVerifyVoteExtension); - rpc PrepareProposal(RequestPrepareProposal) returns (ResponsePrepareProposal); + rpc FinalizeBlock(RequestFinalizeBlock) returns (ResponseFinalizeBlock); } diff --git a/spec/abci++/abci++_methods_002_draft.md b/spec/abci++/abci++_methods_002_draft.md index b0fe2cb14..0d10c41e2 100644 --- a/spec/abci++/abci++_methods_002_draft.md +++ b/spec/abci++/abci++_methods_002_draft.md @@ -289,9 +289,10 @@ title: Methods |-------------------------|---------------------------------------------|------------------------------------------------------------------------------------------------------------------|--------------| | hash | bytes | The block header's hash of the block to propose. Present for convenience (can be derived from the block header). | 1 | | header | [Header](../core/data_structures.md#header) | The header of the block to propose. | 2 | - | tx | repeated bytes | Preliminary list of transactions that have been picked as part of the block to propose. | 3 | - | byzantine_validators | repeated [Evidence](#evidence) | List of evidence of validators that acted maliciously. | 4 | - | last_commit_info | [LastCommitInfo](#lastcommitinfo) | Info about the last commit, including the round, the validator list, and which ones signed the last block. | 5 | + | txs | repeated bytes | Preliminary list of transactions that have been picked as part of the block to propose. | 3 | + | last_commit_info | [LastCommitInfo](#lastcommitinfo) | Info about the last commit, including the round, the validator list, and which ones signed the last block. | 4 | + | byzantine_validators | repeated [Evidence](#evidence) | List of evidence of validators that acted maliciously. | 5 | + | max_tx_bytes | int64 | Currently configured maximum size in bytes taken by the modified transactions. | 6 | >**TODO**: Add the changes needed in LastCommitInfo for vote extensions @@ -303,24 +304,31 @@ From the App's perspective, they'll probably skip ProcessProposal | Name | Type | Description | Field Number | |-------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------|--------------| | modified_tx | bool | The Application sets it to true to denote it made changes to transactions | 1 | - | tx | repeated [TransactionRecord](#transactionrecord) | Possibly modified list of transactions that have been picked as part of the proposed block. | 2 | + | 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_result | repeated [TxResult](#txresult) | List of structures containing the data resulting from executing the transactions | 4 | + | tx_results | repeated [ExecTxResult](#txresult) | 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 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**: * Contains a preliminary block to be proposed, called _raw block_, which the Application can modify. - * The parameters and types of `RequestPrepareProposal` are the same as `RequestProcessProposal` + * 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. * The Application can modify the transactions received in `RequestPrepareProposal` before sending them in `ResponsePrepareProposal`. In that case, `ResponsePrepareProposal.modified_tx` is set to true. * If `ResponsePrepareProposal.modified_tx` is false, then Tendermint will ignore the contents of - `ResponsePrepareProposal.tx`. + `ResponsePrepareProposal.tx_records`. + * If the Application modifies the transactions, the modified transactions MUST NOT exceed the configured maximum size, + contained in `RequestPrepareProposal.max_tx_bytes`. + * 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_result`, `ResponsePrepareProposal.validator_updates`, and + `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 @@ -337,15 +345,15 @@ From the App's perspective, they'll probably skip ProcessProposal * 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`, + * 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 Application can change the transaction list via `ResponsePrepareProposal.tx`. - See [TransactionRecord](#transactionrecord) for further information on how to use it. Some notes: + * The Application can change the transaction list via `ResponsePrepareProposal.tx_records`. + See [TxRecord](#txrecord) for further information on how to use it. Some notes: * To remove a transaction from the proposed block the Application _marks_ the transaction as "REMOVE". It does not remove it from the list. The transaction will also be removed from the mempool. * Removing a transaction from the list means it is too early to propose that transaction, @@ -356,12 +364,12 @@ From the App's perspective, they'll probably skip ProcessProposal queries such as "what happened with this Tx?", by answering "it was modified into these ones". * The Application _can_ reorder the transactions in the list. * As a sanity check, Tendermint will check the returned parameters for validity if the Application modified them. - In particular, `ResponsePrepareProposal.tx` will be deemed invalid if + In particular, `ResponsePrepareProposal.tx_records` will be deemed invalid if * There is a duplicate transaction in the list. * The `new_hashes` field contains a dangling reference to a non-existing transaction. - * A new or modified transaction is marked as "UNMODIFIED" or "REMOVED". - * An unmodified transaction is marked as "ADDED". - * A transaction is marked as "UNKNOWN". + * 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? @@ -410,23 +418,23 @@ Note that, if _p_ has a non-`nil` _validValue_, Tendermint will use it as propos * **Request**: - | Name | Type | Description | Field Number | - |----------------------|---------------------------------------------|------------------------------------------------------------------------------------------------------------------|--------------| - | hash | bytes | The block header's hash of the proposed block. Present for convenience (can be derived from the block header). | 1 | - | header | [Header](../core/data_structures.md#header) | The proposed block's header. | 2 | - | tx | repeated bytes | List of transactions that have been picked as part of the proposed block. | 3 | - | byzantine_validators | repeated [Evidence](#evidence) | List of evidence of validators that acted maliciously. | 4 | - | last_commit_info | [LastCommitInfo](#lastcommitinfo) | Info about the last commit, including the round , the validator list, and which ones signed the last block. | 5 | + | Name | Type | Description | Field Number | + |----------------------|---------------------------------------------|----------------------------------------------------------------------------------------------------------------|--------------| + | hash | bytes | The block header's hash of the proposed block. Present for convenience (can be derived from the block header). | 1 | + | header | [Header](../core/data_structures.md#header) | The proposed block's header. | 2 | + | txs | repeated bytes | List of transactions that have been picked as part of the proposed block. | 3 | + | last_commit_info | [LastCommitInfo](#lastcommitinfo) | Info about the last commit, including the round , the validator list, and which ones signed the last block. | 4 | + | byzantine_validators | repeated [Evidence](#evidence) | List of evidence of validators that acted maliciously. | 5 | * **Response**: - | Name | Type | Description | Field Number | - |-------------------------|--------------------------------------------------|----------------------------------------------------------------------------------|--------------| - | accept | bool | If false, the received block failed verification | 1 | - | app_hash | bytes | The Merkle root hash of the application state. | 2 | - | tx_result | repeated [TxResult](#txresult) | 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 consensus-critical gas, size, and other parameters. | 5 | + | Name | Type | Description | Field Number | + |-------------------------|--------------------------------------------------|-----------------------------------------------------------------------------------|--------------| + | accept | bool | If false, the received block failed verification. | 1 | + | app_hash | bytes | The Merkle root hash of the application state. | 2 | + | tx_results | repeated [ExecTxResult](#txresult) | 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 consensus-critical gas, size, and other parameters. | 5 | * **Usage**: * Contains a full proposed block. @@ -446,13 +454,13 @@ 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. * In same-block execution mode, the Application is required to fully execute the block and provide values - for parameters `ResponseProcessProposal.app_hash`, `ResponseProcessProposal.tx_result`, + 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_result`, + `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 @@ -489,22 +497,25 @@ When a validator _p_ enters Tendermint consensus round _r_, height _h_, in which * **Request**: - | Name | Type | Description | Field Number | - |--------|-------|------------------------------------------------------------------------------|--------------| - | hash | bytes | The header hash of the proposed block that the vote extension is to refer to | 1 | - | height | int64 | Height of the proposed block (for sanity check). | 2 | + | Name | Type | Description | Field Number | + |--------|-------|-------------------------------------------------------------------------------|--------------| + | hash | bytes | The header hash of the proposed block that the vote extension is to refer to. | 1 | + | height | int64 | Height of the proposed block (for sanity check). | 2 | * **Response**: - | Name | Type | Description | Field Number | - |-----------|-------|---------------------------------------------------------------------|--------------| - | extension | bytes | Optional information that will be attached to the Precommit message | 1 | + | Name | Type | Description | Field Number | + |-------------------|-------|---------------------------------------------------------------------|--------------| + | app_signed | bytes | Optional information signed by the Application (not by Tendermint). | 1 | + | tendermint_signed | bytes | Optional information signed by Tendermint. | 2 | * **Usage**: + * Both `ResponseExtendVote.app_signed` and `ResponseExtendVote.tendermint_signed` are optional information that will + be 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` for the current height. - * `ResponseExtendVote.extension` will always be attached to a non-`nil` Precommit message. If Tendermint is to - precommit `nil`, it will not call `RequestExtendVote`. + in a previous call to `ProcessProposal` or `PrepareProposal` for the current height. + * `ResponseExtendVote.app_signed` and `ResponseExtendVote.tendermint_signed` will always 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 it? @@ -530,12 +541,13 @@ In the cases when _p_'s Tendermint is to broadcast `precommit nil` messages (eit * **Request**: - | Name | Type | Description | Field Number | - |-----------|-------|------------------------------------------------------------------------------------------|--------------| - | extension | bytes | Sender Application's vote extension to be validated | 1 | - | hash | bytes | The header hash of the propsed block that the vote extension refers to | 2 | - | address | bytes | [Address](../core/data_structures.md#address) of the validator that signed the extension | 3 | - | height | int64 | Height of the block (for sanity check). | 4 | + | Name | Type | Description | Field Number | + |-------------------|-------|------------------------------------------------------------------------------------------|--------------| + | app_signed | bytes | Optional information signed by the Application (not by Tendermint). | 1 | + | tendermint_signed | bytes | Optional information signed by Tendermint. | 2 | + | hash | bytes | The header hash of the propsed block that the vote extension refers to. | 3 | + | validator_address | bytes | [Address](../core/data_structures.md#address) of the validator that signed the extension | 4 | + | height | int64 | Height of the block (for sanity check). | 5 | * **Response**: @@ -580,20 +592,20 @@ from this condition, but not sure), and _p_ receives a Precommit message for rou |----------------------|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------|--------------| | hash | bytes | The block header's hash. Present for convenience (can be derived from the block header). | 1 | | header | [Header](../core/data_structures.md#header) | The block header. | 2 | - | tx | repeated bytes | List of transactions committed as part of the block. | 3 | - | byzantine_validators | repeated [Evidence](#evidence) | List of evidence of validators that acted maliciously. | 4 | - | last_commit_info | [LastCommitInfo](#lastcommitinfo) | Info about the last commit, including the round, and the list of validators and which ones signed the last block. | 5 | + | txs | repeated bytes | List of transactions committed as part of the block. | 3 | + | last_commit_info | [LastCommitInfo](#lastcommitinfo) | Info about the last commit, including the round, and the list of validators and which ones signed the last block. | 4 | + | byzantine_validators | repeated [Evidence](#evidence) | List of evidence of validators that acted maliciously. | 5 | * **Response**: | Name | Type | Description | Field Number | |-------------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------|--------------| | block_events | repeated [Event](abci++_basic_concepts_002_draft.md#events) | Type & Key-Value events for indexing | 1 | - | tx_result | repeated [TxResult](#txresult) | List of structures containing the data resulting from executing the transactions | 2 | + | tx_results | repeated [ExecTxResult](#txresult) | List of structures containing the data resulting from executing the transactions | 2 | | validator_updates | repeated [ValidatorUpdate](#validatorupdate) | Changes to validator set (set voting power to 0 to remove). | 3 | | consensus_param_updates | [ConsensusParams](#consensusparams) | Changes to consensus-critical gas, size, and other parameters. | 4 | - | app_hash | bytes | The Merkle root hash of the application state. | 6 | - | retain_height | int64 | Blocks below this height may be removed. Defaults to `0` (retain all). | 7 | + | 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. @@ -602,12 +614,12 @@ from this condition, but not sure), and _p_ receives a Precommit message for rou * The header exactly matches the Tendermint header of the proposed block. * The Application can use `RequestFinalizeBlock.last_commit_info` 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.tx`, + * 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_result[i].Code == 0` only if the _i_-th transaction is fully valid. + * `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_result`, `ResponseFinalizeBlock.validator_updates`, and + `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 @@ -621,7 +633,7 @@ from this condition, but not sure), and _p_ receives a Precommit message for rou 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_result`, `ResponseFinalizeBlock.validator_updates`, + `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. @@ -701,19 +713,6 @@ Most of the data structures used in ABCI are shared [common data structures](../ * Validator identified by PubKey * Used to tell Tendermint to update the validator set -### VoteInfo - -* **Fields**: - - | Name | Type | Description | Field Number | - |-------------------|-------------------------|--------------------------------------------------------------|--------------| - | validator | [Validator](#validator) | A validator | 1 | - | signed_last_block | bool | Indicates whether or not the validator signed the last block | 2 | - -* **Usage**: - * Indicates whether a validator signed the last block, allowing for rewards - based on validator availability - ### Evidence * **Fields**: @@ -794,9 +793,26 @@ Most of the data structures used in ABCI are shared [common data structures](../ `Metadata`). Chunks may be retrieved from all nodes that have the same snapshot. * When sent across the network, a snapshot message can be at most 4 MB. -## Data types introduced in ABCI++ +## Data types introduced or modified in ABCI++ + +### VoteInfo + +* **Fields**: + + | Name | Type | Description | Field Number | + |-----------------------------|-------------------------|---------------------------------------------------------------|--------------| + | validator | [Validator](#validator) | A validator | 1 | + | signed_last_block | bool | Indicates whether or not the validator signed the last block | 2 | + | tendermint_signed_extension | bytes | Indicates whether or not the validator signed the last block | 3 | + | app_signed_extension | bytes | Indicates whether or not the validator signed the last block | 3 | + +* **Usage**: + * Indicates whether a validator signed the last block, allowing for rewards + based on validator availability + * `tendermint_signed_extension` conveys the part of the validator's vote extension that was signed by Tendermint. + * `app_signed_extension` conveys the optional *app_signed* part of the validator's vote extension. -### TxResult +### ExecTxResult * **Fields**: @@ -815,21 +831,22 @@ Most of the data structures used in ABCI are shared [common data structures](../ ```protobuf enum TxAction { - UNKNOWN = 0; // Unknown action - UNMODIFIED = 1; // The Application did not modify this transaction. Ignore new_hashes field - ADDED = 2; // The Application added this transaction. Ignore new_hashes field - REMOVED = 3; // The Application wants this transaction removed from the proposal and the mempool. Use new_hashes field if the transaction was modified + TXUNKNOWN = 0; // Unknown action + TXUNMODIFIED = 1; // The Application did not modify this transaction. Ignore new_hashes field + TXADDED = 2; // The Application added this transaction. Ignore new_hashes field + TXREMOVED = 3; // The Application wants this transaction removed from the proposal and the mempool. + // Use new_hashes field if the transaction was modified } ``` * **Usage**: - * If `Action` is UNKNOWN, a problem happened in the Application. Tendermint will ignore this transaction. **TODO** should we panic? - * If `Action` is UNMODIFIED, Tendermint includes the transaction in the proposal. Nothing to do on the mempool. Field `new_hashes` is ignored. - * If `Action` is ADDED, Tendermint includes the transaction in the proposal. The transaction is also added to the mempool and gossipped. Field `new_hashes` is ignored. - * If `Action` is REMOVED, Tendermint excludes the transaction from the proposal. The transaction is also removed from the mempool if it exists, + * If `Action` is TXUNKNOWN, a problem happened in the Application. Tendermint will ignore this transaction. **TODO** should we panic? + * If `Action` is TXUNMODIFIED, Tendermint includes the transaction in the proposal. Nothing to do on the mempool. Field `new_hashes` is ignored. + * If `Action` is TXADDED, Tendermint includes the transaction in the proposal. The transaction is also added to the mempool and gossipped. Field `new_hashes` is ignored. + * If `Action` is TXREMOVED, Tendermint excludes the transaction from the proposal. The transaction is also removed from the mempool if it exists, similar to `CheckTx` returning _false_. Tendermint can use field `new_hashes` to help clients trace transactions that have been modified into other transactions. -### TransactionRecord +### TxRecord * **Fields**: @@ -840,19 +857,21 @@ Most of the data structures used in ABCI are shared [common data structures](../ | new_hashes | repeated bytes | List of hashes of successor transactions | 3 | * **Usage**: - * As `new_hashes` is a list, `TransactionRecord` allows to trace many-to-many modifications. Some examples: + * The hashes contained in `new_hashes` MUST follow the same algorithm used by Tendermint for hashing transactions + that are in the mempool. + * As `new_hashes` is a list, `TxRecord` allows to trace many-to-many modifications. Some examples: * Transaction $t1$ modified into $t2$ is represented with these records * $t2$ "ADDED" * $t1$ "REMOVED"; `new_hashes` contains [$id(t2)$] - * Transaction $t1$ modified into $t2$ and $t3$ is represented with these `TransactionRecord` records + * Transaction $t1$ modified into $t2$ and $t3$ is represented with these `TxRecord` records * $t2$ "ADDED" * $t3$ "ADDED" * $t1$ "REMOVED"; `new_hashes` contains [$id(t2)$, $id(t3)$] - * Transactions $t1$ and $t2$ aggregated into $t3$ is represented with these `TransactionRecord` records + * Transactions $t1$ and $t2$ aggregated into $t3$ is represented with these `TxRecord` records * $t3$ "ADDED" * $t1$ "REMOVED"; `new_hashes` contains [$id(t3)$] * $t2$ "REMOVED"; `new_hashes` contains [$id(t3)$] - * Transactions $t1$ and $t2$ combined into $t3$ and $t4$ is represented with these `TransactionRecord` records + * Transactions $t1$ and $t2$ combined into $t3$ and $t4$ is represented with these `TxRecord` records * $t3$ "ADDED" * $t4$ "ADDED" * $t1$ "REMOVED" and `new_hashes` containing [$id(t3)$, $id(t4)$]