abci/
lib.rs

1#![deny(missing_docs, unsafe_code)]
2//! A Rust crate for creating ABCI applications.
3//!
4//! # ABCI Overview
5//!
6//! ABCI is the interface between Tendermint (a state-machine replication engine) and your application (the actual state
7//! machine). It consists of a set of methods, where each method has a corresponding `Request` and `Response` message
8//! type. Tendermint calls the ABCI methods on the ABCI application by sending the `Request` messages and receiving the
9//! `Response` messages in return.
10//!
11//! ABCI methods are split across 4 separate ABCI connections:
12//!
13//! - `Consensus` Connection: `InitChain`, `BeginBlock`, `DeliverTx`, `EndBlock`, `Commit`
14//! - `Mempool` Connection: `CheckTx`
15//! - `Info` Connection: `Info`, `SetOption`, `Query`
16//! - `Snapshot` Connection: `ListSnapshots`, `LoadSnapshotChunk`, `OfferSnapshot`, `ApplySnapshotChunk`
17//!
18//! Additionally, there is a `Flush` method that is called on every connection, and an `Echo` method that is just for
19//! debugging.
20//!
21//! To know more about ABCI protocol specifications, go to official ABCI [documentation](https://tendermint.com/docs/spec/abci/).
22//!
23//! # Usage
24//!
25//! Add `abci-rs` in your `Cargo.toml`'s `dependencies` section:
26//!
27//! ```toml
28//! [dependencies]
29//! abci-rs = "0.11"
30//! ```
31//!
32//! Each ABCI application has to implement four core traits corresponding to all four ABCI connections, `Consensus`,
33//! `Mempool`, `Info` and `Snapshot`.
34//!
35//! > Note: Implementations of these traits are expected to be `Send + Sync` and methods take immutable reference of
36//! `self`. So, internal mutability must be handled using thread safe (`Arc`, `Mutex`, etc.) constructs.
37//!
38//! ## Synchronous and asynchronous APIs
39//!
40//! `abci-rs` supports both, synchronous and asynchronous APIs (using `sync-api` and `async-api` cargo features). At
41//! least one of these features should be enabled. By default, both, `sync-api` and `async-api`, features are enabled.
42//!
43//! ## Async runtimes
44//!
45//! `abci-rs` also supports multiple async runtimes. These different runtimes can be enabled by using cargo features
46//! `use-async-std`, `use-smol` or `use-tokio`. Only one runtime can be enabled at a time. Compilation will fail if more
47//! than one runtime is enabled or none of them are enabled. By default, `use-tokio` feature is enabled.
48//!
49//! ## Examples
50//!
51//! Example ABCI applications can be found in `examples/sync-counter.rs` (using `sync_api`) and `examples/async-counter.rs`
52//! (using `async_api`).
53#![cfg_attr(feature = "doc", feature(doc_cfg))]
54
55#[cfg(not(any(feature = "async-api", feature = "sync-api")))]
56compile_error!("Either feature `async-api` or `sync-api` must be enabled for this crate");
57
58#[cfg(not(any(feature = "use-async-std", feature = "use-smol", feature = "use-tokio",)))]
59compile_error!("One runtime should be enabled: `use-async-std`, `use-smol` or `use-tokio`");
60
61#[cfg(all(feature = "use-async-std", feature = "use-smol"))]
62compile_error!("Only one runtime should be enabled: `use-async-std`, `use-smol` or `use-tokio`");
63#[cfg(all(feature = "use-async-std", feature = "use-tokio"))]
64compile_error!("Only one runtime should be enabled: `use-async-std`, `use-smol` or `use-tokio`");
65#[cfg(all(feature = "use-tokio", feature = "use-smol"))]
66compile_error!("Only one runtime should be enabled: `use-async-std`, `use-smol` or `use-tokio`");
67
68mod address;
69cfg_if::cfg_if! {
70    if #[cfg(feature = "async-api")] {
71        #[cfg_attr(feature = "doc", doc(cfg(feature = "async-api")))]
72        pub mod async_api;
73    } else {
74        mod async_api;
75    }
76}
77mod handler;
78mod state;
79mod stream_split;
80#[cfg(feature = "sync-api")]
81#[cfg_attr(feature = "doc", doc(cfg(feature = "sync-api")))]
82pub mod sync_api;
83mod tasks;
84#[cfg(test)]
85mod tests;
86pub mod types;
87mod utils;
88
89#[cfg(feature = "async-api")]
90#[cfg_attr(feature = "doc", doc(cfg(feature = "async-api")))]
91pub use async_trait::async_trait;
92
93pub use self::address::Address;
abci/lib.rs

abci/
lib.rs
