Zach
7 years ago
committed by
GitHub
GitHub
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 251 additions and 0 deletions
Unified View
Diff Options
-
+249 -0specification.md
-
+2 -0specification.rst
+ 249
- 0
specification.md
View File
| @ -0,0 +1,249 @@ | |||||
| # ABCI Specification | |||||
| ## Message Types | |||||
| ABCI requests/responses are defined as simple Protobuf messages in [this | |||||
| schema file](https://github.com/tendermint/abci/blob/master/types/types.proto). | |||||
| TendermintCore sends the requests, and the ABCI application sends the | |||||
| responses. Here, we provide an overview of the messages types and how | |||||
| they are used by Tendermint. Then we describe each request-response pair | |||||
| as a function with arguments and return values, and add some notes on | |||||
| usage. | |||||
| Some messages (`Echo, Info, InitChain, BeginBlock, EndBlock, Commit`), | |||||
| don't return errors because an error would indicate a critical failure | |||||
| in the application and there's nothing Tendermint can do. The problem | |||||
| should be addressed and both Tendermint and the application restarted. | |||||
| All other messages (`SetOption, Query, CheckTx, DeliverTx`) return an | |||||
| application-specific response `Code uint32`, where only `0` is reserved | |||||
| for `OK`. | |||||
| Some messages (`SetOption, Query, CheckTx, DeliverTx`) return | |||||
| non-deterministic data in the form of `Info` and `Log`. The `Log` is | |||||
| intended for the literal output from the application's logger, while the | |||||
| `Info` is any additional info that should be returned. | |||||
| The first time a new blockchain is started, Tendermint calls | |||||
| `InitChain`. From then on, the Block Execution Sequence that causes the | |||||
| committed state to be updated is as follows: | |||||
| `BeginBlock, [DeliverTx], EndBlock, Commit` | |||||
| where one `DeliverTx` is called for each transaction in the block. | |||||
| Cryptographic commitments to the results of DeliverTx, EndBlock, and | |||||
| Commit are included in the header of the next block. | |||||
| Tendermint opens three connections to the application to handle the | |||||
| different message types: | |||||
| - `Consensus Connection - InitChain, BeginBlock, DeliverTx, EndBlock, Commit` | |||||
| - `Mempool Connection - CheckTx` | |||||
| - `Info Connection - Info, SetOption, Query` | |||||
| The `Flush` message is used on every connection, and the `Echo` message | |||||
| is only used for debugging. | |||||
| Note that messages may be sent concurrently across all connections -a | |||||
| typical application will thus maintain a distinct state for each | |||||
| connection. They may be referred to as the `DeliverTx state`, the | |||||
| `CheckTx state`, and the `Commit state` respectively. | |||||
| See below for more details on the message types and how they are used. | |||||
| ### Echo | |||||
| - **Arguments**: | |||||
| - `Message (string)`: A string to echo back | |||||
| - **Returns**: | |||||
| - `Message (string)`: The input string | |||||
| - **Usage**: | |||||
| - Echo a string to test an abci client/server implementation | |||||
| ### Flush | |||||
| - **Usage**: | |||||
| - 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, | |||||
| which returns when the Flush response comes back. | |||||
| ### Info | |||||
| - **Arguments**: | |||||
| - `Version (string)`: The Tendermint version | |||||
| - **Returns**: | |||||
| - `Data (string)`: Some arbitrary information | |||||
| - `Version (Version)`: Version information | |||||
| - `LastBlockHeight (int64)`: Latest block for which the app has | |||||
| called Commit | |||||
| - `LastBlockAppHash ([]byte)`: Latest result of Commit | |||||
| - **Usage**: | |||||
| - Return information about the application state. | |||||
| - Used to sync Tendermint with the application during a handshake | |||||
| that happens on startup. | |||||
| - Tendermint expects `LastBlockAppHash` and `LastBlockHeight` to | |||||
| be updated during `Commit`, ensuring that `Commit` is never | |||||
| called twice for the same block height. | |||||
| ### SetOption | |||||
| - **Arguments**: | |||||
| - `Key (string)`: Key to set | |||||
| - `Value (string)`: Value to set for key | |||||
| - **Returns**: | |||||
| - `Code (uint32)`: Response code | |||||
| - `Log (string)`: The output of the application's logger. May | |||||
| be non-deterministic. | |||||
| - `Info (string)`: Additional information. May | |||||
| be non-deterministic. | |||||
| - **Usage**: | |||||
| - Set non-consensus critical application specific options. | |||||
| - e.g. Key="min-fee", Value="100fermion" could set the minimum fee | |||||
| required for CheckTx (but not DeliverTx - that would be | |||||
| consensus critical). | |||||
| ### InitChain | |||||
| - **Arguments**: | |||||
| - `Validators ([]Validator)`: Initial genesis validators | |||||
| - `AppStateBytes ([]byte)`: Serialized initial application state | |||||
| - **Usage**: | |||||
| - Called once upon genesis. | |||||
| ### Query | |||||
| - **Arguments**: | |||||
| - `Data ([]byte)`: Raw query bytes. Can be used with or in lieu | |||||
| of Path. | |||||
| - `Path (string)`: Path of request, like an HTTP GET path. Can be | |||||
| used with or in liue of Data. | |||||
| - Apps MUST interpret '/store' as a query by key on the | |||||
| underlying store. The key SHOULD be specified in the Data field. | |||||
| - Apps SHOULD allow queries over specific types like | |||||
| '/accounts/...' or '/votes/...' | |||||
| - `Height (int64)`: The block height for which you want the query | |||||
| (default=0 returns data for the latest committed block). Note | |||||
| that this is the height of the block containing the | |||||
| application's Merkle root hash, which represents the state as it | |||||
| was after committing the block at Height-1 | |||||
| - `Prove (bool)`: Return Merkle proof with response if possible | |||||
| - **Returns**: | |||||
| - `Code (uint32)`: Response code. | |||||
| - `Log (string)`: The output of the application's logger. May | |||||
| be non-deterministic. | |||||
| - `Info (string)`: Additional information. May | |||||
| be non-deterministic. | |||||
| - `Index (int64)`: The index of the key in the tree. | |||||
| - `Key ([]byte)`: The key of the matching data. | |||||
| - `Value ([]byte)`: The value of the matching data. | |||||
| - `Proof ([]byte)`: Proof for the data, if requested. | |||||
| - `Height (int64)`: The block height from which data was derived. | |||||
| Note that this is the height of the block containing the | |||||
| application's Merkle root hash, which represents the state as it | |||||
| was after committing the block at Height-1 | |||||
| - **Usage**: | |||||
| - Query for data from the application at current or past height. | |||||
| - Optionally return Merkle proof. | |||||
| ### BeginBlock | |||||
| - **Arguments**: | |||||
| - `Hash ([]byte)`: The block's hash. This can be derived from the | |||||
| block header. | |||||
| - `Header (struct{})`: The block header | |||||
| - `AbsentValidators ([]int32)`: List of indices of validators not | |||||
| included in the LastCommit | |||||
| - `ByzantineValidators ([]Evidence)`: List of evidence of | |||||
| validators that acted maliciously | |||||
| - **Usage**: | |||||
| - Signals the beginning of a new block. Called prior to | |||||
| any DeliverTxs. | |||||
| - The header is expected to at least contain the Height. | |||||
| - The `AbsentValidators` and `ByzantineValidators` can be used to | |||||
| determine rewards and punishments for the validators. | |||||
| ### CheckTx | |||||
| - **Arguments**: | |||||
| - `Tx ([]byte)`: The request transaction bytes | |||||
| - **Returns**: | |||||
| - `Code (uint32)`: Response code | |||||
| - `Data ([]byte)`: Result bytes, if any. | |||||
| - `Log (string)`: The output of the application's logger. May | |||||
| be non-deterministic. | |||||
| - `Info (string)`: Additional information. May | |||||
| be non-deterministic. | |||||
| - `GasWanted (int64)`: Amount of gas request for transaction. | |||||
| - `GasUsed (int64)`: Amount of gas consumed by transaction. | |||||
| - `Tags ([]cmn.KVPair)`: Key-Value tags for filtering and indexing | |||||
| transactions (eg. by account). | |||||
| - `Fee (cmn.KI64Pair)`: Fee paid for the transaction. | |||||
| - **Usage**: Validate a mempool transaction, prior to broadcasting | |||||
| or proposing. CheckTx should perform stateful but light-weight | |||||
| checks of the validity of the transaction (like checking signatures | |||||
| and account balances), but need not execute in full (like running a | |||||
| smart contract). | |||||
| Tendermint runs CheckTx and DeliverTx concurrently with eachother, | |||||
| though on distinct ABCI connections - the mempool connection and the | |||||
| consensus connection, respectively. | |||||
| The application should maintain a separate state to support CheckTx. | |||||
| This state can be reset to the latest committed state during | |||||
| `Commit`, where Tendermint ensures the mempool is locked and not | |||||
| sending new `CheckTx`. After `Commit`, the mempool will rerun | |||||
| CheckTx on all remaining transactions, throwing out any that are no | |||||
| longer valid. | |||||
| Keys and values in Tags must be UTF-8 encoded strings (e.g. | |||||
| "account.owner": "Bob", "balance": "100.0", "date": "2018-01-02") | |||||
| ### DeliverTx | |||||
| - **Arguments**: | |||||
| - `Tx ([]byte)`: The request transaction bytes. | |||||
| - **Returns**: | |||||
| - `Code (uint32)`: Response code. | |||||
| - `Data ([]byte)`: Result bytes, if any. | |||||
| - `Log (string)`: The output of the application's logger. May | |||||
| be non-deterministic. | |||||
| - `Info (string)`: Additional information. May | |||||
| be non-deterministic. | |||||
| - `GasWanted (int64)`: Amount of gas requested for transaction. | |||||
| - `GasUsed (int64)`: Amount of gas consumed by transaction. | |||||
| - `Tags ([]cmn.KVPair)`: Key-Value tags for filtering and indexing | |||||
| transactions (eg. by account). | |||||
| - `Fee (cmn.KI64Pair)`: Fee paid for the transaction. | |||||
| - **Usage**: | |||||
| - Deliver a transaction to be executed in full by the application. | |||||
| If the transaction is valid, returns CodeType.OK. | |||||
| - Keys and values in Tags must be UTF-8 encoded strings (e.g. | |||||
| "account.owner": "Bob", "balance": "100.0", | |||||
| "time": "2018-01-02T12:30:00Z") | |||||
| ### EndBlock | |||||
| - **Arguments**: | |||||
| - `Height (int64)`: Height of the block just executed. | |||||
| - **Returns**: | |||||
| - `ValidatorUpdates ([]Validator)`: Changes to validator set (set | |||||
| voting power to 0 to remove). | |||||
| - `ConsensusParamUpdates (ConsensusParams)`: Changes to | |||||
| consensus-critical time, size, and other parameters. | |||||
| - **Usage**: | |||||
| - Signals the end of a block. | |||||
| - Called prior to each Commit, after all transactions. | |||||
| - Validator set and consensus params are updated with the result. | |||||
| - Validator pubkeys are expected to be go-wire encoded. | |||||
| ### Commit | |||||
| - **Returns**: | |||||
| - `Data ([]byte)`: The Merkle root hash | |||||
| - **Usage**: | |||||
| - Persist the application state. | |||||
| - Return a Merkle root hash of the application state. | |||||
| - It's critical that all application instances return the | |||||
| same hash. If not, they will not be able to agree on the next | |||||
| block, because the hash is included in the next block! | |||||