You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

466 lines
18 KiB

6 years ago
  1. # Methods and Types
  2. ## Overview
  3. The ABCI message types are defined in a [protobuf
  4. file](https://github.com/tendermint/tendermint/blob/develop/abci/types/types.proto).
  5. ABCI methods are split across 3 separate ABCI *connections*:
  6. - `Consensus Connection`: `InitChain, BeginBlock, DeliverTx, EndBlock, Commit`
  7. - `Mempool Connection`: `CheckTx`
  8. - `Info Connection`: `Info, SetOption, Query`
  9. The `Consensus Connection` is driven by a consensus protocol and is responsible
  10. for block execution.
  11. The `Mempool Connection` is for validating new transactions, before they're
  12. shared or included in a block.
  13. The `Info Connection` is for initialization and for queries from the user.
  14. Additionally, there is a `Flush` method that is called on every connection,
  15. and an `Echo` method that is just for debugging.
  16. More details on managing state across connections can be found in the section on
  17. [ABCI Applications](apps.md).
  18. ## Errors
  19. Some methods (`Echo, Info, InitChain, BeginBlock, EndBlock, Commit`),
  20. don't return errors because an error would indicate a critical failure
  21. in the application and there's nothing Tendermint can do. The problem
  22. should be addressed and both Tendermint and the application restarted.
  23. All other methods (`SetOption, Query, CheckTx, DeliverTx`) return an
  24. application-specific response `Code uint32`, where only `0` is reserved
  25. for `OK`.
  26. Finally, `Query`, `CheckTx`, and `DeliverTx` include a `Codespace string`, whose
  27. intended use is to disambiguate `Code` values returned by different domains of the
  28. application. The `Codespace` is a namespace for the `Code`.
  29. ## Tags
  30. Some methods (`CheckTx, BeginBlock, DeliverTx, EndBlock`)
  31. include a `Tags` field in their `Response*`. Each tag is key-value pair denoting
  32. something about what happened during the methods execution.
  33. Tags can be used to index transactions and blocks according to what happened
  34. during their execution.
  35. Keys and values in tags must be UTF-8 encoded strings (e.g.
  36. "account.owner": "Bob", "balance": "100.0",
  37. "time": "2018-01-02T12:30:00Z")
  38. ## Determinism
  39. ABCI applications must implement deterministic finite-state machines to be
  40. securely replicated by the Tendermint consensus. This means block execution
  41. over the Consensus Connection must be strictly deterministic: given the same
  42. ordered set of requests, all nodes will compute identical responses, for all
  43. BeginBlock, DeliverTx, EndBlock, and Commit. This is critical, because the
  44. responses are included in the header of the next block, either via a Merkle root
  45. or directly, so all nodes must agree on exactly what they are.
  46. For this reason, it is recommended that applications not be exposed to any
  47. external user or process except via the ABCI connections to a consensus engine
  48. like Tendermint Core. The application must only change its state based on input
  49. from block execution (BeginBlock, DeliverTx, EndBlock, Commit), and not through
  50. any other kind of request. This is the only way to ensure all nodes see the same
  51. transactions and compute the same results.
  52. If there is some non-determinism in the state machine, consensus will eventually
  53. fail as nodes disagree over the correct values for the block header. The
  54. non-determinism must be fixed and the nodes restarted.
  55. Sources of non-determinism in applications may include:
  56. - Hardware failures
  57. - Cosmic rays, overheating, etc.
  58. - Node-dependent state
  59. - Random numbers
  60. - Time
  61. - Underspecification
  62. - Library version changes
  63. - Race conditions
  64. - Floating point numbers
  65. - JSON serialization
  66. - Iterating through hash-tables/maps/dictionaries
  67. - External Sources
  68. - Filesystem
  69. - Network calls (eg. some external REST API service)
  70. See [#56](https://github.com/tendermint/abci/issues/56) for original discussion.
  71. Note that some methods (`SetOption, Query, CheckTx, DeliverTx`) return
  72. explicitly non-deterministic data in the form of `Info` and `Log` fields. The `Log` is
  73. intended for the literal output from the application's logger, while the
  74. `Info` is any additional info that should be returned. These are the only fields
  75. that are not included in block header computations, so we don't need agreement
  76. on them. All other fields in the `Response*` must be strictly deterministic.
  77. ## Block Execution
  78. The first time a new blockchain is started, Tendermint calls
  79. `InitChain`. From then on, the follow sequence of methods is executed for each
  80. block:
  81. `BeginBlock, [DeliverTx], EndBlock, Commit`
  82. where one `DeliverTx` is called for each transaction in the block.
  83. The result is an updated application state.
  84. Cryptographic commitments to the results of DeliverTx, EndBlock, and
  85. Commit are included in the header of the next block.
  86. ## Messages
  87. ### Echo
  88. - **Request**:
  89. - `Message (string)`: A string to echo back
  90. - **Response**:
  91. - `Message (string)`: The input string
  92. - **Usage**:
  93. - Echo a string to test an abci client/server implementation
  94. ### Flush
  95. - **Usage**:
  96. - Signals that messages queued on the client should be flushed to
  97. the server. It is called periodically by the client
  98. implementation to ensure asynchronous requests are actually
  99. sent, and is called immediately to make a synchronous request,
  100. which returns when the Flush response comes back.
  101. ### Info
  102. - **Request**:
  103. - `Version (string)`: The Tendermint version
  104. - **Response**:
  105. - `Data (string)`: Some arbitrary information
  106. - `Version (Version)`: Version information
  107. - `LastBlockHeight (int64)`: Latest block for which the app has
  108. called Commit
  109. - `LastBlockAppHash ([]byte)`: Latest result of Commit
  110. - **Usage**:
  111. - Return information about the application state.
  112. - Used to sync Tendermint with the application during a handshake
  113. that happens on startup.
  114. - Tendermint expects `LastBlockAppHash` and `LastBlockHeight` to
  115. be updated during `Commit`, ensuring that `Commit` is never
  116. called twice for the same block height.
  117. ### SetOption
  118. - **Request**:
  119. - `Key (string)`: Key to set
  120. - `Value (string)`: Value to set for key
  121. - **Response**:
  122. - `Code (uint32)`: Response code
  123. - `Log (string)`: The output of the application's logger. May
  124. be non-deterministic.
  125. - `Info (string)`: Additional information. May
  126. be non-deterministic.
  127. - **Usage**:
  128. - Set non-consensus critical application specific options.
  129. - e.g. Key="min-fee", Value="100fermion" could set the minimum fee
  130. required for CheckTx (but not DeliverTx - that would be
  131. consensus critical).
  132. ### InitChain
  133. - **Request**:
  134. - `Time (google.protobuf.Timestamp)`: Genesis time.
  135. - `ChainID (string)`: ID of the blockchain.
  136. - `ConsensusParams (ConsensusParams)`: Initial consensus-critical parameters.
  137. - `Validators ([]ValidatorUpdate)`: Initial genesis validators.
  138. - `AppStateBytes ([]byte)`: Serialized initial application state. Amino-encoded JSON bytes.
  139. - **Response**:
  140. - `ConsensusParams (ConsensusParams)`: Initial
  141. consensus-critical parameters.
  142. - `Validators ([]ValidatorUpdate)`: Initial validator set (if non empty).
  143. - **Usage**:
  144. - Called once upon genesis.
  145. - If ResponseInitChain.Validators is empty, the initial validator set will be the RequestInitChain.Validators
  146. - If ResponseInitChain.Validators is not empty, the initial validator set will be the
  147. ResponseInitChain.Validators (regardless of what is in RequestInitChain.Validators).
  148. - This allows the app to decide if it wants to accept the initial validator
  149. set proposed by tendermint (ie. in the genesis file), or if it wants to use
  150. a different one (perhaps computed based on some application specific
  151. information in the genesis file).
  152. ### Query
  153. - **Request**:
  154. - `Data ([]byte)`: Raw query bytes. Can be used with or in lieu
  155. of Path.
  156. - `Path (string)`: Path of request, like an HTTP GET path. Can be
  157. used with or in liue of Data.
  158. - Apps MUST interpret '/store' as a query by key on the
  159. underlying store. The key SHOULD be specified in the Data field.
  160. - Apps SHOULD allow queries over specific types like
  161. '/accounts/...' or '/votes/...'
  162. - `Height (int64)`: The block height for which you want the query
  163. (default=0 returns data for the latest committed block). Note
  164. that this is the height of the block containing the
  165. application's Merkle root hash, which represents the state as it
  166. was after committing the block at Height-1
  167. - `Prove (bool)`: Return Merkle proof with response if possible
  168. - **Response**:
  169. - `Code (uint32)`: Response code.
  170. - `Log (string)`: The output of the application's logger. May
  171. be non-deterministic.
  172. - `Info (string)`: Additional information. May
  173. be non-deterministic.
  174. - `Index (int64)`: The index of the key in the tree.
  175. - `Key ([]byte)`: The key of the matching data.
  176. - `Value ([]byte)`: The value of the matching data.
  177. - `Proof (Proof)`: Serialized proof for the value data, if requested, to be
  178. verified against the `AppHash` for the given Height.
  179. - `Height (int64)`: The block height from which data was derived.
  180. Note that this is the height of the block containing the
  181. application's Merkle root hash, which represents the state as it
  182. was after committing the block at Height-1
  183. - `Codespace (string)`: Namespace for the `Code`.
  184. - **Usage**:
  185. - Query for data from the application at current or past height.
  186. - Optionally return Merkle proof.
  187. - Merkle proof includes self-describing `type` field to support many types
  188. of Merkle trees and encoding formats.
  189. ### BeginBlock
  190. - **Request**:
  191. - `Hash ([]byte)`: The block's hash. This can be derived from the
  192. block header.
  193. - `Header (struct{})`: The block header.
  194. - `LastCommitInfo (LastCommitInfo)`: Info about the last commit, including the
  195. round, and the list of validators and which ones signed the last block.
  196. - `ByzantineValidators ([]Evidence)`: List of evidence of
  197. validators that acted maliciously.
  198. - **Response**:
  199. - `Tags ([]cmn.KVPair)`: Key-Value tags for filtering and indexing
  200. - **Usage**:
  201. - Signals the beginning of a new block. Called prior to
  202. any DeliverTxs.
  203. - The header contains the height, timestamp, and more - it exactly matches the
  204. Tendermint block header. We may seek to generalize this in the future.
  205. - The `LastCommitInfo` and `ByzantineValidators` can be used to determine
  206. rewards and punishments for the validators. NOTE validators here do not
  207. include pubkeys.
  208. ### CheckTx
  209. - **Request**:
  210. - `Tx ([]byte)`: The request transaction bytes
  211. - **Response**:
  212. - `Code (uint32)`: Response code
  213. - `Data ([]byte)`: Result bytes, if any.
  214. - `Log (string)`: The output of the application's logger. May
  215. be non-deterministic.
  216. - `Info (string)`: Additional information. May
  217. be non-deterministic.
  218. - `GasWanted (int64)`: Amount of gas requested for transaction.
  219. - `GasUsed (int64)`: Amount of gas consumed by transaction.
  220. - `Tags ([]cmn.KVPair)`: Key-Value tags for filtering and indexing
  221. transactions (eg. by account).
  222. - `Codespace (string)`: Namespace for the `Code`.
  223. - **Usage**:
  224. - Technically optional - not involved in processing blocks.
  225. - Guardian of the mempool: every node runs CheckTx before letting a
  226. transaction into its local mempool.
  227. - The transaction may come from an external user or another node
  228. - CheckTx need not execute the transaction in full, but rather a light-weight
  229. yet stateful validation, like checking signatures and account balances, but
  230. not running code in a virtual machine.
  231. - Transactions where `ResponseCheckTx.Code != 0` will be rejected - they will not be broadcast to
  232. other nodes or included in a proposal block.
  233. - Tendermint attributes no other value to the response code
  234. ### DeliverTx
  235. - **Request**:
  236. - `Tx ([]byte)`: The request transaction bytes.
  237. - **Response**:
  238. - `Code (uint32)`: Response code.
  239. - `Data ([]byte)`: Result bytes, if any.
  240. - `Log (string)`: The output of the application's logger. May
  241. be non-deterministic.
  242. - `Info (string)`: Additional information. May
  243. be non-deterministic.
  244. - `GasWanted (int64)`: Amount of gas requested for transaction.
  245. - `GasUsed (int64)`: Amount of gas consumed by transaction.
  246. - `Tags ([]cmn.KVPair)`: Key-Value tags for filtering and indexing
  247. transactions (eg. by account).
  248. - `Codespace (string)`: Namespace for the `Code`.
  249. - **Usage**:
  250. - The workhorse of the application - non-optional.
  251. - Execute the transaction in full.
  252. - `ResponseDeliverTx.Code == 0` only if the transaction is fully valid.
  253. ### EndBlock
  254. - **Request**:
  255. - `Height (int64)`: Height of the block just executed.
  256. - **Response**:
  257. - `ValidatorUpdates ([]ValidatorUpdate)`: Changes to validator set (set
  258. voting power to 0 to remove).
  259. - `ConsensusParamUpdates (ConsensusParams)`: Changes to
  260. consensus-critical time, size, and other parameters.
  261. - `Tags ([]cmn.KVPair)`: Key-Value tags for filtering and indexing
  262. - **Usage**:
  263. - Signals the end of a block.
  264. - Called after all transactions, prior to each Commit.
  265. - Validator updates returned by block `H` impact blocks `H+1`, `H+2`, and
  266. `H+3`, but only effects changes on the validator set of `H+2`:
  267. - `H+1`: NextValidatorsHash
  268. - `H+2`: ValidatorsHash (and thus the validator set)
  269. - `H+3`: LastCommitInfo (ie. the last validator set)
  270. - Consensus params returned for block `H` apply for block `H+1`
  271. ### Commit
  272. - **Response**:
  273. - `Data ([]byte)`: The Merkle root hash of the application state
  274. - **Usage**:
  275. - Persist the application state.
  276. - Return an (optional) Merkle root hash of the application state
  277. - `ResponseCommit.Data` is included as the `Header.AppHash` in the next block
  278. - it may be empty
  279. - Later calls to `Query` can return proofs about the application state anchored
  280. in this Merkle root hash
  281. - Note developers can return whatever they want here (could be nothing, or a
  282. constant string, etc.), so long as it is deterministic - it must not be a
  283. function of anything that did not come from the
  284. BeginBlock/DeliverTx/EndBlock methods.
  285. ## Data Types
  286. ### Header
  287. - **Fields**:
  288. - `ChainID (string)`: ID of the blockchain
  289. - `Height (int64)`: Height of the block in the chain
  290. - `Time (google.protobuf.Timestamp)`: Time of the block. It is the proposer's
  291. local time when block was created.
  292. - `NumTxs (int32)`: Number of transactions in the block
  293. - `TotalTxs (int64)`: Total number of transactions in the blockchain until
  294. now
  295. - `LastBlockID (BlockID)`: Hash of the previous (parent) block
  296. - `LastCommitHash ([]byte)`: Hash of the previous block's commit
  297. - `ValidatorsHash ([]byte)`: Hash of the validator set for this block
  298. - `NextValidatorsHash ([]byte)`: Hash of the validator set for the next block
  299. - `ConsensusHash ([]byte)`: Hash of the consensus parameters for this block
  300. - `AppHash ([]byte)`: Data returned by the last call to `Commit` - typically the
  301. Merkle root of the application state after executing the previous block's
  302. transactions
  303. - `LastResultsHash ([]byte)`: Hash of the ABCI results returned by the last block
  304. - `EvidenceHash ([]byte)`: Hash of the evidence included in this block
  305. - `ProposerAddress ([]byte)`: Original proposer for the block
  306. - **Usage**:
  307. - Provided in RequestBeginBlock
  308. - Provides important context about the current state of the blockchain -
  309. especially height and time.
  310. - Provides the proposer of the current block, for use in proposer-based
  311. reward mechanisms.
  312. ### Validator
  313. - **Fields**:
  314. - `Address ([]byte)`: Address of the validator (hash of the public key)
  315. - `Power (int64)`: Voting power of the validator
  316. - **Usage**:
  317. - Validator identified by address
  318. - Used in RequestBeginBlock as part of VoteInfo
  319. - Does not include PubKey to avoid sending potentially large quantum pubkeys
  320. over the ABCI
  321. ### ValidatorUpdate
  322. - **Fields**:
  323. - `PubKey (PubKey)`: Public key of the validator
  324. - `Power (int64)`: Voting power of the validator
  325. - **Usage**:
  326. - Validator identified by PubKey
  327. - Used to tell Tendermint to update the validator set
  328. ### VoteInfo
  329. - **Fields**:
  330. - `Validator (Validator)`: A validator
  331. - `SignedLastBlock (bool)`: Indicates whether or not the validator signed
  332. the last block
  333. - **Usage**:
  334. - Indicates whether a validator signed the last block, allowing for rewards
  335. based on validator availability
  336. ### PubKey
  337. - **Fields**:
  338. - `Type (string)`: Type of the public key. A simple string like `"ed25519"`.
  339. In the future, may indicate a serialization algorithm to parse the `Data`,
  340. for instance `"amino"`.
  341. - `Data ([]byte)`: Public key data. For a simple public key, it's just the
  342. raw bytes. If the `Type` indicates an encoding algorithm, this is the
  343. encoded public key.
  344. - **Usage**:
  345. - A generic and extensible typed public key
  346. ### Evidence
  347. - **Fields**:
  348. - `Type (string)`: Type of the evidence. A hierarchical path like
  349. "duplicate/vote".
  350. - `Validator (Validator`: The offending validator
  351. - `Height (int64)`: Height when the offense was committed
  352. - `Time (google.protobuf.Timestamp)`: Time of the block at height `Height`.
  353. It is the proposer's local time when block was created.
  354. - `TotalVotingPower (int64)`: Total voting power of the validator set at
  355. height `Height`
  356. ### LastCommitInfo
  357. - **Fields**:
  358. - `Round (int32)`: Commit round.
  359. - `Votes ([]VoteInfo)`: List of validators addresses in the last validator set
  360. with their voting power and whether or not they signed a vote.
  361. ### ConsensusParams
  362. - **Fields**:
  363. - `BlockSize (BlockSize)`: Parameters limiting the size of a block.
  364. - `EvidenceParams (EvidenceParams)`: Parameters limiting the validity of
  365. evidence of byzantine behaviour.
  366. ### BlockSize
  367. - **Fields**:
  368. - `MaxBytes (int64)`: Max size of a block, in bytes.
  369. - `MaxGas (int64)`: Max sum of `GasWanted` in a proposed block.
  370. - NOTE: blocks that violate this may be committed if there are Byzantine proposers.
  371. It's the application's responsibility to handle this when processing a
  372. block!
  373. ### EvidenceParams
  374. - **Fields**:
  375. - `MaxAge (int64)`: Max age of evidence, in blocks. Evidence older than this
  376. is considered stale and ignored.
  377. - This should correspond with an app's "unbonding period" or other
  378. similar mechanism for handling Nothing-At-Stake attacks.
  379. - NOTE: this should change to time (instead of blocks)!
  380. ### Proof
  381. - **Fields**:
  382. - `Ops ([]ProofOp)`: List of chained Merkle proofs, of possibly different types
  383. - The Merkle root of one op is the value being proven in the next op.
  384. - The Merkle root of the final op should equal the ultimate root hash being
  385. verified against.
  386. ### ProofOp
  387. - **Fields**:
  388. - `Type (string)`: Type of Merkle proof and how it's encoded.
  389. - `Key ([]byte)`: Key in the Merkle tree that this proof is for.
  390. - `Data ([]byte)`: Encoded Merkle proof for the key.