namada_node/shell/block_alloc/
states.rs

1//! All the states of the `BlockAllocator` state machine,
2//! over the extent of a Tendermint consensus round
3//! block proposal.
4//!
5//! # States
6//!
7//! The state machine moves through the following state DAG:
8//!
9//! 1. [`BuildingProtocolTxBatch`] - the initial state. In this state, we
10//!    populate a block with protocol txs.
11//! 2. [`BuildingNormalTxBatch`] - the second state. In this state, we populate
12//!    a block with non-protocol txs.
13//! 3. [`BuildingProtocolTxBatch`] - we return to this state to fill up any
14//!    remaining block space if possible.
15
16mod normal_txs;
17mod protocol_txs;
18
19use super::AllocFailure;
20
21/// The leader of the current Tendermint round is building
22/// a new batch of protocol txs.
23///
24/// This happens twice, in the first stage, we fill up to 1/2
25/// of the block. At the end of allocating user txs, we fill
26/// up any remaining space with un-allocated protocol txs.
27///
28/// For more info, read the module docs of
29/// [`crate::shell::block_alloc::states`].
30pub struct BuildingProtocolTxBatch<Mode> {
31    /// One of [`WithNormalTxs`] and [`WithoutNormalTxs`].
32    _mode: Mode,
33}
34
35/// Allow block proposals to include user submitted txs.
36///
37/// For more info, read the module docs of
38/// [`crate::shell::block_alloc::states`].
39pub enum WithNormalTxs {}
40
41/// Allow block proposals to include wrapper txs.
42///
43/// For more info, read the module docs of
44/// [`crate::shell::block_alloc::states`].
45pub enum WithoutNormalTxs {}
46
47/// The leader of the current Tendermint round is building
48/// a new batch of user submitted (non-protocol) transactions.
49///
50/// For more info, read the module docs of
51/// [`crate::shell::block_alloc::states`].
52pub struct BuildingNormalTxBatch {}
53
54/// Try to allocate a new transaction on a `BlockAllocator` state.
55///
56/// For more info, read the module docs of
57/// [`crate::shell::block_alloc::states`].
58pub trait TryAlloc {
59    type Resources<'tx>;
60
61    /// Try to allocate resources for a new transaction.
62    fn try_alloc(
63        &mut self,
64        resource_required: Self::Resources<'_>,
65    ) -> Result<(), AllocFailure>;
66}
67
68/// Represents a state transition in the `BlockAllocator` state machine.
69///
70/// This trait should not be used directly. Instead, consider using
71/// [`NextState`].
72///
73/// For more info, read the module docs of
74/// [`crate::shell::block_alloc::states`].
75pub trait NextStateImpl<Transition = ()> {
76    /// The next state in the `BlockAllocator` state machine.
77    type Next;
78
79    /// Transition to the next state in the `BlockAllocator`] state
80    /// machine.
81    fn next_state_impl(self) -> Self::Next;
82}
83
84/// Convenience extension of [`NextStateImpl`], to transition to a new
85/// state with a null transition function.
86///
87/// For more info, read the module docs of
88/// [`crate::shell::block_alloc::states`].
89pub trait NextState: NextStateImpl {
90    /// Transition to the next state in the `BlockAllocator` state,
91    /// using a null transiiton function.
92    #[inline]
93    fn next_state(self) -> Self::Next
94    where
95        Self: Sized,
96    {
97        self.next_state_impl()
98    }
99}
100
101impl<S> NextState for S where S: NextStateImpl {}
namada_node/shell/block_alloc/states.rs

namada_node/shell/block_alloc/
states.rs
