Add ABCI domain types.

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.

tendermint/src/abci.rs

@@ -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},
+};

tendermint/src/abci/doc/request-applysnapshotchunk.md

@@ -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)

tendermint/src/abci/doc/request-beginblock.md

@@ -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)

tendermint/src/abci/doc/request-checktx.md

@@ -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)

tendermint/src/abci/doc/request-commit.md

@@ -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)

tendermint/src/abci/doc/request-delivertx.md

@@ -0,0 +1,3 @@
+Execute a transaction against the application state.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#delivertx)

tendermint/src/abci/doc/request-echo.md

@@ -0,0 +1,3 @@
+Echoes a string to test an ABCI implementation.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#echo)

tendermint/src/abci/doc/request-endblock.md

@@ -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)

tendermint/src/abci/doc/request-flush.md

@@ -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)

tendermint/src/abci/doc/request-info.md

@@ -0,0 +1,3 @@
+Requests information about the application state.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#info)

tendermint/src/abci/doc/request-initchain.md

@@ -0,0 +1,3 @@
+Called on genesis to initialize chain state.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#initchain)

tendermint/src/abci/doc/request-listsnapshots.md

@@ -0,0 +1,3 @@
+Asks the application for a list of snapshots.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#listsnapshots)

tendermint/src/abci/doc/request-loadsnapshotchunk.md

@@ -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)

tendermint/src/abci/doc/request-offersnapshot.md

@@ -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

tendermint/src/abci/doc/request-query.md

@@ -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)

tendermint/src/abci/doc/response-applysnapshotchunk.md

@@ -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)

tendermint/src/abci/doc/response-beginblock.md

@@ -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)

tendermint/src/abci/doc/response-checktx.md

@@ -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)

tendermint/src/abci/doc/response-commit.md

@@ -0,0 +1,3 @@
+Returns the result of persisting the application state.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#commit)

tendermint/src/abci/doc/response-delivertx.md

@@ -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)

tendermint/src/abci/doc/response-echo.md

@@ -0,0 +1,3 @@
+Echoes a string to test an ABCI implementation.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#echo)

tendermint/src/abci/doc/response-endblock.md

@@ -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)

tendermint/src/abci/doc/response-exception.md

@@ -0,0 +1 @@
+Returns an exception (undocumented, nondeterministic).

tendermint/src/abci/doc/response-flush.md

@@ -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)

tendermint/src/abci/doc/response-info.md

@@ -0,0 +1,3 @@
+Returns information about the application state.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#info)

tendermint/src/abci/doc/response-initchain.md

@@ -0,0 +1,3 @@
+Returned on genesis after initializing chain state.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#initchain)

tendermint/src/abci/doc/response-listsnapshots.md

@@ -0,0 +1,3 @@
+Returns a list of local state snapshots.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#listsnapshots)

tendermint/src/abci/doc/response-loadsnapshotchunk.md

@@ -0,0 +1,3 @@
+Returns a snapshot chunk from the application.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#loadsnapshotchunk)

tendermint/src/abci/doc/response-offersnapshot.md

@@ -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

tendermint/src/abci/doc/response-query.md

@@ -0,0 +1,3 @@
+Returns data queried from the application.
+
+[ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#query)