diff --git a/abci/types/types.pb.go b/abci/types/types.pb.go index 7ed1b1a00e..9d6b484742 100644 --- a/abci/types/types.pb.go +++ b/abci/types/types.pb.go @@ -3073,6 +3073,8 @@ type ExtendVoteExtension struct { // The Tenderdash supports only THRESHOLD_RECOVER and THRESHOLD_RECOVER_RAW at this moment. Type types1.VoteExtensionType `protobuf:"varint,1,opt,name=type,proto3,enum=tendermint.types.VoteExtensionType" json:"type,omitempty"` // Deterministic or (Non-Deterministic) extension provided by the sending validator's Application. + // + // For THRESHOLD_RECOVER_RAW, it MUST be 32 bytes. Extension []byte `protobuf:"bytes,2,opt,name=extension,proto3" json:"extension,omitempty"` // Types that are valid to be assigned to XSignRequestId: // diff --git a/spec/abci++/api.md b/spec/abci++/api.md index 6c8579af66..19b0f4945f 100644 --- a/spec/abci++/api.md +++ b/spec/abci++/api.md @@ -1,78 +1,70 @@ # Protocol Documentation - ## Table of Contents -1. [Table of Contents](#table-of-contents) -2. [tendermint/abci/types.proto](#tendermintabcitypesproto) - 1. [CommitInfo](#commitinfo) - 2. [Event](#event) - 3. [EventAttribute](#eventattribute) - 4. [ExecTxResult](#exectxresult) - 5. [ExtendVoteExtension](#extendvoteextension) - 6. [ExtendedVoteInfo](#extendedvoteinfo) - 7. [Misbehavior](#misbehavior) - 8. [QuorumHashUpdate](#quorumhashupdate) - 9. [Request](#request) - 10. [RequestApplySnapshotChunk](#requestapplysnapshotchunk) - 11. [RequestCheckTx](#requestchecktx) - 12. [RequestEcho](#requestecho) - 13. [RequestExtendVote](#requestextendvote) - 1. [Usage](#usage) - 2. [When does Tenderdash call it?](#when-does-tenderdash-call-it) - 14. [RequestFinalizeBlock](#requestfinalizeblock) - 1. [Usage](#usage-1) - 15. [RequestFlush](#requestflush) - 16. [RequestInfo](#requestinfo) - 17. [RequestInitChain](#requestinitchain) - 18. [RequestListSnapshots](#requestlistsnapshots) - 19. [RequestLoadSnapshotChunk](#requestloadsnapshotchunk) - 20. [RequestOfferSnapshot](#requestoffersnapshot) - 21. [RequestPrepareProposal](#requestprepareproposal) - 1. [Usage](#usage-2) - 2. [When does Tenderdash call it?](#when-does-tenderdash-call-it-1) - 22. [RequestProcessProposal](#requestprocessproposal) - 1. [Usage](#usage-3) - 2. [When does Tenderdash call it?](#when-does-tenderdash-call-it-2) - 23. [RequestQuery](#requestquery) - 24. [RequestVerifyVoteExtension](#requestverifyvoteextension) - 1. [Usage](#usage-4) - 2. [When does Tenderdash call it?](#when-does-tenderdash-call-it-3) - 25. [Response](#response) - 26. [ResponseApplySnapshotChunk](#responseapplysnapshotchunk) - 27. [ResponseCheckTx](#responsechecktx) - 28. [ResponseEcho](#responseecho) - 29. [ResponseException](#responseexception) - 30. [ResponseExtendVote](#responseextendvote) - 31. [ResponseFinalizeBlock](#responsefinalizeblock) - 32. [ResponseFlush](#responseflush) - 33. [ResponseInfo](#responseinfo) - 34. [ResponseInitChain](#responseinitchain) - 35. [ResponseListSnapshots](#responselistsnapshots) - 36. [ResponseLoadSnapshotChunk](#responseloadsnapshotchunk) - 37. [ResponseOfferSnapshot](#responseoffersnapshot) - 38. [ResponsePrepareProposal](#responseprepareproposal) - 39. [ResponseProcessProposal](#responseprocessproposal) - 40. [ResponseQuery](#responsequery) - 41. [ResponseVerifyVoteExtension](#responseverifyvoteextension) - 42. [Snapshot](#snapshot) - 43. [ThresholdPublicKeyUpdate](#thresholdpublickeyupdate) - 44. [TxRecord](#txrecord) - 45. [TxResult](#txresult) - 46. [Validator](#validator) - 47. [ValidatorSetUpdate](#validatorsetupdate) - 48. [ValidatorUpdate](#validatorupdate) - 49. [VoteInfo](#voteinfo) - 50. [CheckTxType](#checktxtype) - 51. [MisbehaviorType](#misbehaviortype) - 52. [ResponseApplySnapshotChunk.Result](#responseapplysnapshotchunkresult) - 53. [ResponseOfferSnapshot.Result](#responseoffersnapshotresult) - 54. [ResponseProcessProposal.ProposalStatus](#responseprocessproposalproposalstatus) - 55. [ResponseVerifyVoteExtension.VerifyStatus](#responseverifyvoteextensionverifystatus) - 56. [TxRecord.TxAction](#txrecordtxaction) - 57. [ABCIApplication](#abciapplication) -3. [Scalar Value Types](#scalar-value-types) +- [tendermint/abci/types.proto](#tendermint_abci_types-proto) + - [CommitInfo](#tendermint-abci-CommitInfo) + - [Event](#tendermint-abci-Event) + - [EventAttribute](#tendermint-abci-EventAttribute) + - [ExecTxResult](#tendermint-abci-ExecTxResult) + - [ExtendVoteExtension](#tendermint-abci-ExtendVoteExtension) + - [ExtendedVoteInfo](#tendermint-abci-ExtendedVoteInfo) + - [Misbehavior](#tendermint-abci-Misbehavior) + - [QuorumHashUpdate](#tendermint-abci-QuorumHashUpdate) + - [Request](#tendermint-abci-Request) + - [RequestApplySnapshotChunk](#tendermint-abci-RequestApplySnapshotChunk) + - [RequestCheckTx](#tendermint-abci-RequestCheckTx) + - [RequestEcho](#tendermint-abci-RequestEcho) + - [RequestExtendVote](#tendermint-abci-RequestExtendVote) + - [RequestFinalizeBlock](#tendermint-abci-RequestFinalizeBlock) + - [RequestFlush](#tendermint-abci-RequestFlush) + - [RequestInfo](#tendermint-abci-RequestInfo) + - [RequestInitChain](#tendermint-abci-RequestInitChain) + - [RequestListSnapshots](#tendermint-abci-RequestListSnapshots) + - [RequestLoadSnapshotChunk](#tendermint-abci-RequestLoadSnapshotChunk) + - [RequestOfferSnapshot](#tendermint-abci-RequestOfferSnapshot) + - [RequestPrepareProposal](#tendermint-abci-RequestPrepareProposal) + - [RequestProcessProposal](#tendermint-abci-RequestProcessProposal) + - [RequestQuery](#tendermint-abci-RequestQuery) + - [RequestVerifyVoteExtension](#tendermint-abci-RequestVerifyVoteExtension) + - [Response](#tendermint-abci-Response) + - [ResponseApplySnapshotChunk](#tendermint-abci-ResponseApplySnapshotChunk) + - [ResponseCheckTx](#tendermint-abci-ResponseCheckTx) + - [ResponseEcho](#tendermint-abci-ResponseEcho) + - [ResponseException](#tendermint-abci-ResponseException) + - [ResponseExtendVote](#tendermint-abci-ResponseExtendVote) + - [ResponseFinalizeBlock](#tendermint-abci-ResponseFinalizeBlock) + - [ResponseFlush](#tendermint-abci-ResponseFlush) + - [ResponseInfo](#tendermint-abci-ResponseInfo) + - [ResponseInitChain](#tendermint-abci-ResponseInitChain) + - [ResponseListSnapshots](#tendermint-abci-ResponseListSnapshots) + - [ResponseLoadSnapshotChunk](#tendermint-abci-ResponseLoadSnapshotChunk) + - [ResponseOfferSnapshot](#tendermint-abci-ResponseOfferSnapshot) + - [ResponsePrepareProposal](#tendermint-abci-ResponsePrepareProposal) + - [ResponseProcessProposal](#tendermint-abci-ResponseProcessProposal) + - [ResponseQuery](#tendermint-abci-ResponseQuery) + - [ResponseVerifyVoteExtension](#tendermint-abci-ResponseVerifyVoteExtension) + - [Snapshot](#tendermint-abci-Snapshot) + - [ThresholdPublicKeyUpdate](#tendermint-abci-ThresholdPublicKeyUpdate) + - [TxRecord](#tendermint-abci-TxRecord) + - [TxResult](#tendermint-abci-TxResult) + - [Validator](#tendermint-abci-Validator) + - [ValidatorSetUpdate](#tendermint-abci-ValidatorSetUpdate) + - [ValidatorUpdate](#tendermint-abci-ValidatorUpdate) + - [VoteInfo](#tendermint-abci-VoteInfo) + + - [CheckTxType](#tendermint-abci-CheckTxType) + - [MisbehaviorType](#tendermint-abci-MisbehaviorType) + - [ResponseApplySnapshotChunk.Result](#tendermint-abci-ResponseApplySnapshotChunk-Result) + - [ResponseOfferSnapshot.Result](#tendermint-abci-ResponseOfferSnapshot-Result) + - [ResponseProcessProposal.ProposalStatus](#tendermint-abci-ResponseProcessProposal-ProposalStatus) + - [ResponseVerifyVoteExtension.VerifyStatus](#tendermint-abci-ResponseVerifyVoteExtension-VerifyStatus) + - [TxRecord.TxAction](#tendermint-abci-TxRecord-TxAction) + + - [ABCIApplication](#tendermint-abci-ABCIApplication) + +- [Scalar Value Types](#scalar-value-types) @@ -104,7 +96,6 @@ ### Event - Event allows application developers to attach additional information to ResponseCheckTx, ResponsePrepareProposal, ResponseProcessProposal and ResponseFinalizeBlock. @@ -125,7 +116,6 @@ Later, transactions may be queried using these events. ### EventAttribute - EventAttribute is a single key-value pair, associated with an event. @@ -143,7 +133,6 @@ EventAttribute is a single key-value pair, associated with an event. ### ExecTxResult - ExecTxResult contains results of executing one individual transaction. @@ -166,7 +155,6 @@ ExecTxResult contains results of executing one individual transaction. ### ExtendVoteExtension - Provides a vote extension for signing. `type` and `extension` fields are mandatory for filling @@ -175,12 +163,14 @@ Provides a vote extension for signing. `type` and `extension` fields are mandato | type | [tendermint.types.VoteExtensionType](#tendermint-types-VoteExtensionType) | | Vote extension type can be either DEFAULT, THRESHOLD_RECOVER or THRESHOLD_RECOVER_RAW. The Tenderdash supports only THRESHOLD_RECOVER and THRESHOLD_RECOVER_RAW at this moment. | | extension | [bytes](#bytes) | | Deterministic or (Non-Deterministic) extension provided by the sending validator's Application. +For THRESHOLD_RECOVER_RAW, it MUST be 32 bytes. + Sign request ID that will be used to sign the vote extensions. Only applicable for THRESHOLD_RECOVER_RAW vote extension type. Tenderdash will use SHA256 checksum of `sign_request_id` when generating quorum signatures of THRESHOLD_RECOVER_RAW vote extensions. It MUST NOT be set for any other vote extension types. | | sign_request_id | [bytes](#bytes) | optional | If not set, Tenderdash will generate it based on height and round. -If set, it SHOULD be unique per voting round, and it MUST start with `\x06dpevote` or `plwdtx` string. +If set, it SHOULD be unique per voting round, and it MUST start with `dpevote` or `\x06plwdtx` prefix. Use with caution - it can have severe security consequences. | @@ -192,7 +182,6 @@ Use with caution - it can have severe security consequences. | ### ExtendedVoteInfo - ExtendedVoteInfo @@ -219,7 +208,7 @@ ExtendedVoteInfo | validator | [Validator](#tendermint-abci-Validator) | | The offending validator | | height | [int64](#int64) | | The height when the offense occurred | | time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | The corresponding time where the offense occurred | -| total_voting_power | [int64](#int64) | | Total voting power of the validator set in case the ABCI application does not store historical validators. | +| total_voting_power | [int64](#int64) | | Total voting power of the validator set in case the ABCI application does not store historical validators. https://github.com/tendermint/tendermint/issues/4581 | @@ -244,7 +233,6 @@ ExtendedVoteInfo ### Request - Request types @@ -274,7 +262,6 @@ Request types ### RequestApplySnapshotChunk - Applies a snapshot chunk. - The application can choose to refetch chunks and/or ban P2P peers as appropriate. @@ -303,7 +290,6 @@ Applies a snapshot chunk. ### RequestCheckTx - Check if transaction is valid. - Technically optional - not involved in processing blocks. @@ -329,7 +315,6 @@ Check if transaction is valid. ### RequestEcho - Echo a string to test an abci client/server implementation @@ -345,7 +330,6 @@ Echo a string to test an abci client/server implementation ### RequestExtendVote - Extends a vote with application-side injection #### Usage @@ -397,7 +381,6 @@ a [CanonicalVoteExtension](#canonicalvoteextension) field in the `precommit nil` ### RequestFinalizeBlock - Finalize newly decided block. #### Usage @@ -444,7 +427,6 @@ Finalize newly decided block. ### RequestFlush - Signals that messages queued on the client should be flushed to the server. It is called periodically by the client implementation to ensure asynchronous requests are actually sent, and is called immediately to make a synchronous request, @@ -458,7 +440,6 @@ which returns when the Flush response comes back. ### RequestInfo - Return information about the application state. Used to sync Tenderdash with the application during a handshake that happens on startup. @@ -482,7 +463,6 @@ ensuring that Commit is never called twice for the same block height. ### RequestInitChain - Called once upon genesis. - If ResponseInitChain.Validators is empty, the initial validator set will be the RequestInitChain.Validators @@ -511,7 +491,6 @@ Called once upon genesis. ### RequestListSnapshots - Lists available snapshots - Used during state sync to discover available snapshots on peers. @@ -525,7 +504,6 @@ Lists available snapshots ### RequestLoadSnapshotChunk - Used during state sync to retrieve snapshot chunks from peers. @@ -543,7 +521,6 @@ Used during state sync to retrieve snapshot chunks from peers. ### RequestOfferSnapshot - Offers a snapshot to the application. - OfferSnapshot is called when bootstrapping a node using state sync. The application may accept or reject snapshots @@ -569,7 +546,6 @@ Offers a snapshot to the application. ### RequestPrepareProposal - Prepare new block proposal, potentially altering list of transactions. #### Usage @@ -678,7 +654,6 @@ Note that, if _p_ has a non-`nil` _validValue_, Tenderdash will use it as propos ### RequestProcessProposal - Process prepared proposal. #### Usage @@ -749,7 +724,6 @@ When a validator _p_ enters Tenderdash consensus round _r_, height _h_, in which ### RequestQuery - Query for data from the application at current or past height. - Optionally return Merkle proof. @@ -771,7 +745,6 @@ Query for data from the application at current or past height. ### RequestVerifyVoteExtension - Verify the vote extension #### Usage @@ -795,17 +768,14 @@ When a validator _p_ is in Tenderdash consensus round _r_, height _h_, state _pr from this condition, but not sure), and _p_ receives a Precommit message for round _r_, height _h_ from _q_: 1. If the Precommit message does not contain a vote extensions with a valid signature, Tenderdash discards the message as invalid. - -- a 0-length vote extensions is valid as long as its accompanying signature is also valid. - + - a 0-length vote extensions is valid as long as its accompanying signature is also valid. 2. Else, _p_'s Tenderdash calls `RequestVerifyVoteExtension`. 3. The Application returns _accept_ or _reject_ via `ResponseVerifyVoteExtension.status`. 4. If the Application returns - -- _accept_, _p_'s Tenderdash will keep the received vote, together with its corresponding + - _accept_, _p_'s Tenderdash 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 Tenderdash will deem the Precommit message invalid and discard it. + - _reject_, _p_'s Tenderdash will deem the Precommit message invalid and discard it. | Field | Type | Label | Description | @@ -908,7 +878,6 @@ from this condition, but not sure), and _p_ receives a Precommit message for rou ### ResponseException - nondeterministic @@ -1174,7 +1143,6 @@ nondeterministic ### TxResult - TxResult contains results of executing the transaction. One usage is indexing transaction results. @@ -1195,7 +1163,6 @@ One usage is indexing transaction results. ### Validator - Validator @@ -1229,7 +1196,6 @@ Validator ### ValidatorUpdate - ValidatorUpdate @@ -1248,7 +1214,6 @@ ValidatorUpdate ### VoteInfo - VoteInfo @@ -1261,13 +1226,12 @@ VoteInfo - + ### CheckTxType - Type of transaction check | Name | Number | Description | @@ -1352,7 +1316,6 @@ Type of transaction check ### TxRecord.TxAction - TxAction contains App-provided information on what to do with a transaction that is part of a raw proposal | Name | Number | Description | @@ -1364,9 +1327,9 @@ TxAction contains App-provided information on what to do with a transaction that | DELAYED | 4 | The Application wants this transaction removed from the proposal but not the mempool. | + - - + @@ -1392,7 +1355,7 @@ TxAction contains App-provided information on what to do with a transaction that | VerifyVoteExtension | [RequestVerifyVoteExtension](#tendermint-abci-RequestVerifyVoteExtension) | [ResponseVerifyVoteExtension](#tendermint-abci-ResponseVerifyVoteExtension) | | | FinalizeBlock | [RequestFinalizeBlock](#tendermint-abci-RequestFinalizeBlock) | [ResponseFinalizeBlock](#tendermint-abci-ResponseFinalizeBlock) | | - +