forked from informalsystems/tendermint-rs
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
These types mirror the generated types in tendermint_proto, but have better naming. The documentation for each request type is adapted from the ABCI Methods and Types spec document. However, the same logical request may appear three times, as a struct with the request data, as a Request variant, and as a CategoryRequest variant. To avoid duplication, this PR uses the `#[doc = include_str!(...)]` functionality stabilized in Rust 1.54 to keep common definitions of the documentation.
- Loading branch information
1 parent
23fdab3
commit 9cb2b06
Showing
62 changed files
with
3,034 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
//! Application BlockChain Interface ([ABCI]) is the interface between Tendermint | ||
//! (a consensus engine for Byzantine-fault-tolerant replication of a state | ||
//! machine) and an application (the state machine to be replicated). | ||
//! | ||
//! Using ABCI involves writing an application driven by ABCI methods, exposing | ||
//! that application as an ABCI server, and having Tendermint connect to the | ||
//! server as an ABCI client. | ||
//! | ||
//! This module does not include an ABCI server implementation itself. Instead, | ||
//! it provides a common set of Rust domain types that model the ABCI protocol, | ||
//! which can be used by both ABCI applications and ABCI server implementations. | ||
//! | ||
//! One ABCI server implementation is provided by the [`tendermint_abci`][tmabci] | ||
//! crate. | ||
//! | ||
//! Each ABCI method corresponds to a request/response pair. ABCI requests are | ||
//! modeled by the [`Request`] enum, and responses are modeled by the | ||
//! [`Response`] enum. As described in the [methods and types][mat] page, ABCI | ||
//! methods are split into four categories. Tendermint opens one ABCI connection | ||
//! for each category of messages. These categories are modeled by the | ||
//! [`MethodKind`] enum and by per-category request and response enums: | ||
//! | ||
//! * [`ConsensusRequest`] / [`ConsensusResponse`] for [`MethodKind::Consensus`] methods; | ||
//! * [`MempoolRequest`] / [`MempoolResponse`] for [`MethodKind::Mempool`] methods; | ||
//! * [`InfoRequest`] / [`InfoResponse`] for [`MethodKind::Info`] methods; | ||
//! * [`SnapshotRequest`] / [`SnapshotResponse`] for [`MethodKind::Snapshot`] methods. | ||
//! | ||
//! The domain types in this module have conversions to and from the Protobuf | ||
//! types defined in the [`tendermint_proto`] crate. These conversions are | ||
//! required for ABCI server implementations, which use the protobufs to | ||
//! communicate with Tendermint, but should not be required for ABCI | ||
//! applications, which should use the domain types in an interface defined by | ||
//! their choice of ABCI server implementation. | ||
//! | ||
//! [ABCI]: https://docs.tendermint.com/master/spec/abci/ | ||
//! [mat]: https://docs.tendermint.com/master/spec/abci/abci.html | ||
//! [tmabci]: https://github.com/informalsystems/tendermint-rs/tree/master/abci | ||
|
||
mod event; | ||
mod kind; | ||
|
||
pub mod params; | ||
pub mod request; | ||
pub mod response; | ||
pub mod types; | ||
|
||
pub use event::{Event, EventAttribute, EventAttributeIndexExt}; | ||
|
||
#[doc(inline)] | ||
pub use self::{ | ||
kind::MethodKind, | ||
request::{ConsensusRequest, InfoRequest, MempoolRequest, Request, SnapshotRequest}, | ||
response::{ConsensusResponse, InfoResponse, MempoolResponse, Response, SnapshotResponse}, | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
Applies a snapshot chunk. | ||
|
||
The application can choose to refetch chunks and/or ban P2P peers as | ||
appropriate. Tendermint will not do this unless instructed by the | ||
application. | ||
|
||
The application may want to verify each chunk, e.g., by attaching chunk | ||
hashes in [`Snapshot::metadata`] and/or incrementally verifying contents | ||
against `app_hash`. | ||
|
||
When all chunks have been accepted, Tendermint will make an ABCI [`Info`] | ||
request to verify that `last_block_app_hash` and `last_block_height` match | ||
the expected values, and record the `app_version` in the node state. It then | ||
switches to fast sync or consensus and joins the network. | ||
|
||
If Tendermint is unable to retrieve the next chunk after some time (e.g., | ||
because no suitable peers are available), it will reject the snapshot and try | ||
a different one via `OfferSnapshot`. The application should be prepared to | ||
reset and accept it or abort as appropriate. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#applysnapshotchunk) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
Signals the beginning of a new block. | ||
|
||
Called prior to any [`DeliverTx`]s. The `header` contains the height, | ||
timestamp, and more -- it exactly matches the Tendermint block header. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#beginblock) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
Check whether a transaction should be included in the mempool. | ||
|
||
`CheckTx` is not involved in processing blocks, only in deciding whether a | ||
transaction should be included in the mempool. Every node runs `CheckTx` | ||
before adding a transaction to its local mempool. The transaction may come | ||
from an external user or another node. `CheckTx` need not execute the | ||
transaction in full, but can instead perform lightweight or statateful | ||
validation (e.g., checking signatures or account balances) instead of more | ||
expensive checks (like running code in a virtual machine). | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#checktx) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
Signals the application that it can write the queued state transitions | ||
from the block to its state. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#commit) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Execute a transaction against the application state. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#delivertx) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Echoes a string to test an ABCI implementation. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#echo) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
Signals the end of a block. | ||
|
||
Called after all transactions, and prior to each `Commit`. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#endblock) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Indicates that any pending requests should be completed and their responses flushed. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#flush) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Requests information about the application state. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#info) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Called on genesis to initialize chain state. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#initchain) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Asks the application for a list of snapshots. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#listsnapshots) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Used during state sync to retrieve snapshot chunks from peers. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#loadsnapshotchunk) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
Offers a list of snapshots to the application. | ||
|
||
`OfferSnapshot` is called when bootstrapping a node using state sync. The | ||
application may accept or reject snapshots as appropriate. Upon accepting, | ||
Tendermint will retrieve and apply snapshot chunks via | ||
[`ApplySnapshotChunk`]. The application may also choose to reject a snapshot | ||
in the chunk response, in which case it should be prepared to accept further | ||
`OfferSnapshot` calls. | ||
|
||
Only `app_hash` can be trusted, as it has been verified by the light client. | ||
Any other data can be spoofed by adversaries, so applications should employ | ||
additional verification schemes to avoid denial-of-service attacks. The | ||
verified `app_hash` is automatically checked against the restored application | ||
at the end of snapshot restoration. | ||
|
||
See also the [`Snapshot`] data type and the [ABCI state sync documentation][ssd]. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#offersnapshot) | ||
|
||
[ssd]: https://docs.tendermint.com/master/spec/abci/apps.html#state-sync |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Queries for data from the application at current or past height. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#query) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
Returns the result of applying a snapshot chunk and associated data. | ||
|
||
The application can choose to refetch chunks and/or ban P2P peers as | ||
appropriate. Tendermint will not do this unless instructed by the | ||
application. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#applysnapshotchunk) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returns events that occurred when beginning a new block. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#beginblock) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returns the result of checking a transaction for mempool inclusion. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#checktx) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returns the result of persisting the application state. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#commit) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
Returns events that occurred while executing a transaction against the | ||
application state. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#delivertx) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Echoes a string to test an ABCI implementation. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#echo) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returns validator updates that occur after the end of a block. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#endblock) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
Returns an exception (undocumented, nondeterministic). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Indicates that all pending requests have been completed with their responses flushed. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#flush) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returns information about the application state. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#info) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returned on genesis after initializing chain state. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#initchain) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returns a list of local state snapshots. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#listsnapshots) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returns a snapshot chunk from the application. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#loadsnapshotchunk) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
Returns the application's response to a snapshot offer. | ||
|
||
See also the [`Snapshot`] data type and the [ABCI state sync documentation][ssd]. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#offersnapshot) | ||
|
||
[ssd]: https://docs.tendermint.com/master/spec/abci/apps.html#state-sync |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Returns data queried from the application. | ||
|
||
[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#query) |
Oops, something went wrong.