cnidarium_component/lib.rs
1//! Core trait definitions for components of an ABCI application using [`cnidarium`].
2//!
3//! This crate defines two traits for use by "component crates":
4//!
5//! - [`Component`], which defines the _internally driven_ behavior of a
6//! component, triggered at the beginning and end of blocks and at the ends of
7//! epochs;
8//! - [`ActionHandler`], which defines the _externally driven_ behavior of a
9//! component, triggered by actions in blockchain transactions.
10//!
11//! Component crates should be structured as follows:
12//!
13//! - Definitions of any transaction actions related to the component, and their
14//! corresponding plans and views;
15//! - a `crate::component` module, feature-gated by the `component` feature,
16//! with the `Component` implementation and `ActionHandler` implementations for
17//! any locally-defined actions, and any other code touching the chain state
18//! inside;
19//! - a `crate::state_key` module defining the component's state keys (which are
20//! a public API, like the rest of the chain state);
21//! - a `crate::event` module defining any events emitted by the component;
22//!
23//! The structure of the feature-gated `component` submodule allows reusing data
24//! structures between client and server (fullnode) code.
25//!
26//! For instance, the `penumbra_sdk_transaction` crate depends on all of the
27//! component crates without the `component` feature, so it can assemble all of
28//! the actions for each component into a top-level transaction type. This
29//! means all async code should be confined to the `component` module, so that
30//! the transaction definitions don't depend on `tokio`, `mio`, etc and can be
31//! used without problems in wasm or other non-async contexts.
32//!
33//! On the other hand, the `penumbra_sdk_app` crate depends on all of the component
34//! crates with the `component` feature enabled, so it can assemble all of the
35//! `ActionHandler` implementations into a top-level `ActionHandler`
36//! implementation and call each component's `Component` implementation at the
37//! appropriate times.
38
39#![deny(clippy::unwrap_used)]
40// Requires nightly.
41#![cfg_attr(docsrs, feature(doc_auto_cfg))]
42
43mod action_handler;
44mod component;
45
46pub use action_handler::ActionHandler;
47pub use component::Component;