zolfa
/
tendermint
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 221 Wiki Activity
Browse Source

Added all ABCI++ APIs to protobufs

pull/7804/head
Sergio Mena 3 years ago
parent
5e90a98a7c
commit
1543e4122a
2 changed files with 208 additions and 126 deletions
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +104
    -41
      proto/tendermint/abci/types.proto
  2. +104
    -85
      spec/abci++/abci++_methods_002_draft.md

+ 104
- 41
proto/tendermint/abci/types.proto View File

@ -36,9 +36,10 @@ message Request {
RequestLoadSnapshotChunk load_snapshot_chunk = 13; RequestLoadSnapshotChunk load_snapshot_chunk = 13;
RequestApplySnapshotChunk apply_snapshot_chunk = 14; RequestApplySnapshotChunk apply_snapshot_chunk = 14;
RequestPrepareProposal prepare_proposal = 15; 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; 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 // Extends a vote with application-side injection
message RequestExtendVote { message RequestExtendVote {
types.Vote vote = 1;
bytes hash = 1;
int64 height = 2;
} }
// Verify the vote extension // Verify the vote extension
message RequestVerifyVoteExtension { 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 { 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]; LastCommitInfo last_commit_info = 4 [(gogoproto.nullable) = false];
repeated Evidence byzantine_validators = 5 [(gogoproto.nullable) = false]; repeated Evidence byzantine_validators = 5 [(gogoproto.nullable) = false];
} }
@ -169,9 +186,10 @@ message Response {
ResponseLoadSnapshotChunk load_snapshot_chunk = 14; ResponseLoadSnapshotChunk load_snapshot_chunk = 14;
ResponseApplySnapshotChunk apply_snapshot_chunk = 15; ResponseApplySnapshotChunk apply_snapshot_chunk = 15;
ResponsePrepareProposal prepare_proposal = 16; 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; bytes data = 2;
string log = 3; // nondeterministic string log = 3; // nondeterministic
string info = 4; // 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"]; repeated Event events = 7 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"];
string codespace = 8; string codespace = 8;
string sender = 9; 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 { 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 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. // TxResult contains results of executing the transaction.
// //
// One usage is indexing transaction results. // One usage is indexing transaction results.
@ -357,6 +401,21 @@ message TxResult {
ResponseDeliverTx result = 4 [(gogoproto.nullable) = false]; 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 // Blockchain Types
@ -375,8 +434,10 @@ message ValidatorUpdate {
// VoteInfo // VoteInfo
message 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 { enum EvidenceType {
@ -425,7 +486,9 @@ service ABCIApplication {
rpc OfferSnapshot(RequestOfferSnapshot) returns (ResponseOfferSnapshot); rpc OfferSnapshot(RequestOfferSnapshot) returns (ResponseOfferSnapshot);
rpc LoadSnapshotChunk(RequestLoadSnapshotChunk) returns (ResponseLoadSnapshotChunk); rpc LoadSnapshotChunk(RequestLoadSnapshotChunk) returns (ResponseLoadSnapshotChunk);
rpc ApplySnapshotChunk(RequestApplySnapshotChunk) returns (ResponseApplySnapshotChunk); rpc ApplySnapshotChunk(RequestApplySnapshotChunk) returns (ResponseApplySnapshotChunk);
rpc PrepareProposal(RequestPrepareProposal) returns (ResponsePrepareProposal);
rpc ProcessProposal(RequestProcessProposal) returns (ResponseProcessProposal);
rpc ExtendVote(RequestExtendVote) returns (ResponseExtendVote); rpc ExtendVote(RequestExtendVote) returns (ResponseExtendVote);
rpc VerifyVoteExtension(RequestVerifyVoteExtension) returns (ResponseVerifyVoteExtension); rpc VerifyVoteExtension(RequestVerifyVoteExtension) returns (ResponseVerifyVoteExtension);
rpc PrepareProposal(RequestPrepareProposal) returns (ResponsePrepareProposal);
rpc FinalizeBlock(RequestFinalizeBlock) returns (ResponseFinalizeBlock);
} }

+ 104
- 85
spec/abci++/abci++_methods_002_draft.md View File

@ -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 | | 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 | | 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 >**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 | | Name | Type | Description | Field Number |
|-------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------|--------------| |-------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------|--------------|
| modified_tx | bool | The Application sets it to true to denote it made changes to transactions | 1 | | 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 | | 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 | | 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 | | 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**: * **Usage**:
* Contains a preliminary block to be proposed, called _raw block_, which the Application can modify. * 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`. and `RequestFinalizeBlock`.
* The header contains the height, timestamp, and more - it exactly matches the * The header contains the height, timestamp, and more - it exactly matches the
Tendermint block header. Tendermint block header.
* The Application can modify the transactions received in `RequestPrepareProposal` before sending * The Application can modify the transactions received in `RequestPrepareProposal` before sending
them in `ResponsePrepareProposal`. In that case, `ResponsePrepareProposal.modified_tx` is set to true. 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 * 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`, * 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. `ResponsePrepareProposal.consensus_param_updates`, as a result of fully executing the block.
* The values for `ResponsePrepareProposal.validator_updates`, or * The values for `ResponsePrepareProposal.validator_updates`, or
`ResponsePrepareProposal.consensus_param_updates` may be empty. In this case, Tendermint will keep `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 * 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 the (synchronous) execution of the block does not cause other processes to prevote `nil` because
their propose timeout goes off. 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`. `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. * 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 The Application must keep those events until a block is decided and then pass them on to Tendermint via
`ResponseFinalizeBlock`. `ResponseFinalizeBlock`.
* Likewise, in next-block execution mode, the Application must keep all responses to executing transactions * Likewise, in next-block execution mode, the Application must keep all responses to executing transactions
until it can call `ResponseFinalizeBlock`. 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 * 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. "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, * 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". 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. * 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. * 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. * There is a duplicate transaction in the list.
* The `new_hashes` field contains a dangling reference to a non-existing transaction. * 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 * 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). 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? * **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**: * **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**: * **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**: * **Usage**:
* Contains a full proposed block. * 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 * If `ResponseProcessProposal.accept` is _false_, Tendermint assumes the proposal received
is not valid. is not valid.
* In same-block execution mode, the Application is required to fully execute the block and provide values * 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`, `ResponseProcessProposal.validator_updates`, and `ResponseProcessProposal.consensus_param_updates`,
so that Tendermint can then verify the hashes in the block's header are correct. 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` If the hashes mismatch, Tendermint will reject the block even if `ResponseProcessProposal.accept`
was set to _true_. was set to _true_.
* In next-block execution mode, the Application should *not* provide values for parameters * 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`. `ResponseProcessProposal.validator_updates`, and `ResponseProcessProposal.consensus_param_updates`.
* The implementation of `ProcessProposal` MUST be deterministic. Moreover, the value of * The implementation of `ProcessProposal` MUST be deterministic. Moreover, the value of
`ResponseProcessProposal.accept` MUST **exclusively** depend on the parameters passed in `ResponseProcessProposal.accept` MUST **exclusively** depend on the parameters passed in
@ -489,22 +497,25 @@ When a validator _p_ enters Tendermint consensus round _r_, height _h_, in which
* **Request**: * **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**: * **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**: * **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 * `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. * The Application logic that creates the extension can be non-deterministic.
#### When does Tendermint call it? #### When does Tendermint call it?
@ -530,12 +541,13 @@ In the cases when _p_'s Tendermint is to broadcast `precommit nil` messages (eit
* **Request**: * **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**: * **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 | | 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 | | 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**: * **Response**:
| Name | Type | Description | Field Number | | Name | Type | Description | Field Number |
|-------------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------|--------------| |-------------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------|--------------|
| block_events | repeated [Event](abci++_basic_concepts_002_draft.md#events) | Type & Key-Value events for indexing | 1 | | 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 | | 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 | | 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**: * **Usage**:
* Contains a newly decided block. * 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 header exactly matches the Tendermint header of the proposed block.
* The Application can use `RequestFinalizeBlock.last_commit_info` and `RequestFinalizeBlock.byzantine_validators` * The Application can use `RequestFinalizeBlock.last_commit_info` and `RequestFinalizeBlock.byzantine_validators`
to determine rewards and punishments for the 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 before returning control to Tendermint. Alternatively, it can commit the candidate state corresponding to the same block
previously executed via `PrepareProposal` or `ProcessProposal`. 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`, * 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. `ResponseFinalizeBlock.consensus_param_updates` as a result of executing the block.
* The values for `ResponseFinalizeBlock.validator_updates`, or * The values for `ResponseFinalizeBlock.validator_updates`, or
`ResponseFinalizeBlock.consensus_param_updates` may be empty. In this case, Tendermint will keep `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, 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). 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 * 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`. 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`. * 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` 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 * Validator identified by PubKey
* Used to tell Tendermint to update the validator set * 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 ### Evidence
* **Fields**: * **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. `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. * 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**: * **Fields**:
@ -815,21 +831,22 @@ Most of the data structures used in ABCI are shared [common data structures](../
```protobuf ```protobuf
enum TxAction { 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**: * **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. 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**: * **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 | | new_hashes | repeated bytes | List of hashes of successor transactions | 3 |
* **Usage**: * **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 * Transaction $t1$ modified into $t2$ is represented with these records
* $t2$ "ADDED" * $t2$ "ADDED"
* $t1$ "REMOVED"; `new_hashes` contains [$id(t2)$] * $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" * $t2$ "ADDED"
* $t3$ "ADDED" * $t3$ "ADDED"
* $t1$ "REMOVED"; `new_hashes` contains [$id(t2)$, $id(t3)$] * $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" * $t3$ "ADDED"
* $t1$ "REMOVED"; `new_hashes` contains [$id(t3)$] * $t1$ "REMOVED"; `new_hashes` contains [$id(t3)$]
* $t2$ "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" * $t3$ "ADDED"
* $t4$ "ADDED" * $t4$ "ADDED"
* $t1$ "REMOVED" and `new_hashes` containing [$id(t3)$, $id(t4)$] * $t1$ "REMOVED" and `new_hashes` containing [$id(t3)$, $id(t4)$]


Write Preview
Loading…
Cancel
Save