massa_consensus_exports/
controller_trait.rs

1use crate::block_graph_export::BlockGraphExport;
2use crate::{bootstrapable_graph::BootstrapableGraph, error::ConsensusError};
3use massa_models::prehash::PreHashSet;
4use massa_models::streaming_step::StreamingStep;
5use massa_models::{
6    block::BlockGraphStatus, block_header::BlockHeader, block_id::BlockId, clique::Clique,
7    secure_share::SecureShare, slot::Slot, stats::ConsensusStats,
8};
9use massa_storage::Storage;
10
11/// Interface that communicates with the graph worker thread
12#[cfg_attr(feature = "test-exports", mockall_wrap::wrap, mockall::automock)]
13pub trait ConsensusController: Send + Sync {
14    /// Get an export of a part of the graph
15    ///
16    /// # Arguments
17    /// * `start_slot`: the slot to start the export from, if None, the export starts from the genesis
18    /// * `end_slot`: the slot to end the export at, if None, the export ends at the current slot
19    ///
20    /// # Returns
21    /// The export of the graph
22    fn get_block_graph_status(
23        &self,
24        start_slot: Option<Slot>,
25        end_slot: Option<Slot>,
26    ) -> Result<BlockGraphExport, ConsensusError>;
27
28    /// Get statuses of a list of blocks
29    ///
30    /// # Arguments
31    /// * `ids`: the list of block ids to get the status of
32    ///
33    /// # Returns
34    /// The statuses of the blocks sorted by the order of the input list
35    fn get_block_statuses(&self, ids: &[BlockId]) -> Vec<BlockGraphStatus>;
36
37    /// Get all the cliques of the graph
38    ///
39    /// # Returns
40    /// The list of cliques
41    fn get_cliques(&self) -> Vec<Clique>;
42
43    /// Get a part of the graph to send to a node for it to setup its graph.
44    /// Used for bootstrap.
45    ///
46    /// # Arguments:
47    /// * `cursor`: streaming cursor containing the current state of bootstrap and what blocks have previously been sent to the client
48    /// * `execution_cursor`: streaming cursor of the final state to ensure that last slot of the bootstrap info match the slot of the execution
49    ///
50    /// # Returns:
51    /// * A portion of the graph
52    /// * The list of outdated block ids
53    /// * The streaming step value after the current iteration to be saved to be able to use it as parameters and resume the bootstrap
54    #[allow(clippy::type_complexity)]
55    fn get_bootstrap_part(
56        &self,
57        cursor: StreamingStep<PreHashSet<BlockId>>,
58        execution_cursor: StreamingStep<Slot>,
59    ) -> Result<
60        (
61            BootstrapableGraph,
62            PreHashSet<BlockId>,
63            StreamingStep<PreHashSet<BlockId>>,
64        ),
65        ConsensusError,
66    >;
67
68    /// Get the stats of the consensus
69    ///
70    /// # Returns
71    /// The stats of the consensus
72    fn get_stats(&self) -> Result<ConsensusStats, ConsensusError>;
73
74    /// Get the best parents for the next block to be produced
75    ///
76    /// # Returns
77    /// The id of best parents for the next block to be produced along with their period
78    fn get_best_parents(&self) -> Vec<(BlockId, u64)>;
79
80    /// Get the block id of the block at a specific slot in the blockclique
81    ///
82    /// # Arguments
83    /// * `slot`: the slot to get the block id of
84    ///
85    /// # Returns
86    /// The block id of the block at the specified slot if exists
87    fn get_blockclique_block_at_slot(&self, slot: Slot) -> Option<BlockId>;
88
89    /// Get the latest block, that is in the blockclique, in the thread of the given slot and before this `slot`.
90    ///
91    /// # Arguments:
92    /// * `slot`: the slot that will give us the thread and the upper bound
93    ///
94    /// # Returns:
95    /// The block id of the latest block in the thread of the given slot and before this slot
96    fn get_latest_blockclique_block_at_slot(&self, slot: Slot) -> BlockId;
97
98    /// Register a block in the graph
99    ///
100    /// # Arguments
101    /// * `block_id`: the id of the block to register
102    /// * `slot`: the slot of the block
103    /// * `block_storage`: the storage that contains all the objects of the block
104    /// * `created`: is the block created by our node ?
105    fn register_block(&self, block_id: BlockId, slot: Slot, block_storage: Storage, created: bool);
106
107    /// Register a block header in the graph
108    ///
109    /// # Arguments
110    /// * `block_id`: the id of the block to register
111    /// * `header`: the header of the block to register
112    fn register_block_header(&self, block_id: BlockId, header: SecureShare<BlockHeader, BlockId>);
113
114    /// Mark a block as invalid in the graph
115    ///
116    /// # Arguments
117    /// * `block_id`: the id of the block to mark as invalid
118    /// * `header`: the header of the block to mark as invalid
119    fn mark_invalid_block(&self, block_id: BlockId, header: SecureShare<BlockHeader, BlockId>);
120
121    /// Returns a boxed clone of self.
122    /// Useful to allow cloning `Box<dyn ConsensusController>`.
123    fn clone_box(&self) -> Box<dyn ConsensusController>;
124}
125
126/// Allow cloning `Box<dyn ConsensusController>`
127/// Uses `ConsensusController::clone_box` internally
128impl Clone for Box<dyn ConsensusController> {
129    fn clone(&self) -> Box<dyn ConsensusController> {
130        self.clone_box()
131    }
132}
133
134/// Consensus manager used to stop the consensus thread
135pub trait ConsensusManager {
136    /// Stop the consensus thread
137    /// Note that we do not take self by value to consume it
138    /// because it is not allowed to move out of `Box<dyn ConsensusManager>`
139    /// This will improve if the `unsized_fn_params` feature stabilizes enough to be safely usable.
140    fn stop(&mut self);
141}
massa_consensus_exports/controller_trait.rs

massa_consensus_exports/
controller_trait.rs
