massa_execution_exports/
controller_traits.rs

1// Copyright (c) 2022 MASSA LABS <info@massa.net>
2
3//! This module exports generic traits representing interfaces for interacting with the Execution worker
4
5use crate::types::{
6    ExecutionBlockMetadata, ExecutionQueryRequest, ExecutionQueryResponse, ReadOnlyExecutionRequest,
7};
8
9use crate::ExecutionError;
10use crate::{ExecutionAddressInfo, ReadOnlyExecutionOutput};
11use massa_models::address::Address;
12use massa_models::amount::Amount;
13use massa_models::block_id::BlockId;
14use massa_models::denunciation::DenunciationIndex;
15use massa_models::execution::EventFilter;
16use massa_models::operation::OperationId;
17use massa_models::output_event::SCOutputEvent;
18use massa_models::prehash::PreHashMap;
19use massa_models::slot::Slot;
20use massa_models::stats::ExecutionStats;
21use std::collections::BTreeMap;
22use std::collections::HashMap;
23use std::future::Future;
24use std::pin::Pin;
25
26#[cfg(feature = "execution-trace")]
27use crate::types_trace_info::{AbiTrace, SlotAbiCallStack, Transfer};
28
29/// Future resolving to the result of a queued read-only execution
30pub type ReadOnlyExecutionFuture =
31    Pin<Box<dyn Future<Output = Result<ReadOnlyExecutionOutput, ExecutionError>> + Send>>;
32
33#[cfg_attr(feature = "test-exports", mockall::automock)]
34/// interface that communicates with the execution worker thread
35pub trait ExecutionController: Send + Sync {
36    /// Updates blockclique status by signaling newly finalized blocks and the latest blockclique.
37    ///
38    /// # Arguments
39    /// * `finalized_blocks`: newly finalized blocks indexed by slot.
40    /// * `blockclique`: new blockclique (if changed). Indexed by slot.
41    /// * `block_metadata`: storage instances and metadata for new blocks. Each storage owns refs to the block and its ops/endorsements.
42    fn update_blockclique_status(
43        &self,
44        finalized_blocks: HashMap<Slot, BlockId>,
45        new_blockclique: Option<HashMap<Slot, BlockId>>,
46        block_metadata: PreHashMap<BlockId, ExecutionBlockMetadata>,
47    );
48
49    /// Atomically query the execution state with multiple requests
50    fn query_state(&self, req: ExecutionQueryRequest) -> ExecutionQueryResponse;
51
52    /// Get execution events optionally filtered by:
53    /// * start slot
54    /// * end slot
55    /// * emitter address
56    /// * original caller address
57    /// * operation id
58    fn get_filtered_sc_output_event(&self, filter: EventFilter) -> Vec<SCOutputEvent>;
59
60    /// Get the final and active values of balance.
61    ///
62    /// # Return value
63    /// * `(final_balance, active_balance)`
64    fn get_final_and_candidate_balance(
65        &self,
66        addresses: &[Address],
67    ) -> Vec<(Option<Amount>, Option<Amount>)>;
68
69    /// Get the execution status of a batch of operations.
70    ///
71    ///  Return value: vector of
72    ///  `(Option<speculative_status>, Option<final_status>)`
73    ///  If an Option is None it means that the op execution was not found.
74    ///  Note that old op executions are forgotten.
75    /// Otherwise, the status is a boolean indicating whether the execution was successful (true) or if there was an error (false.)
76    fn get_ops_exec_status(&self, batch: &[OperationId]) -> Vec<(Option<bool>, Option<bool>)>;
77
78    /// Get a copy of a single datastore entry with its final and active values
79    ///
80    /// # Return value
81    /// * `(final_data_entry, active_data_entry)`
82    #[allow(clippy::type_complexity)]
83    fn get_final_and_active_data_entry(
84        &self,
85        input: Vec<(Address, Vec<u8>)>,
86    ) -> Vec<(Option<Vec<u8>>, Option<Vec<u8>>)>;
87
88    /// Returns for a given cycle the stakers taken into account
89    /// by the selector. That correspond to the `roll_counts` in `cycle - 3`.
90    ///
91    /// By default it returns an empty map.
92    fn get_cycle_active_rolls(&self, cycle: u64) -> BTreeMap<Address, u64>;
93
94    /// Execute read-only SC function call without causing modifications to the consensus state
95    ///
96    /// # arguments
97    /// * `req`: an instance of `ReadOnlyCallRequest` describing the parameters of the execution
98    ///
99    /// # returns
100    /// A future resolving to an instance of `ExecutionOutput` containing a summary of the
101    /// effects of the execution, or an error if the execution failed.
102    ///
103    /// The request is queued (or refused) when this is called; awaiting the future
104    /// only waits for the answer, without holding a thread. Dropping the future
105    /// abandons the request: the execution worker skips it if it has not started it yet.
106    fn execute_readonly_request_async(
107        &self,
108        req: ReadOnlyExecutionRequest,
109    ) -> ReadOnlyExecutionFuture;
110
111    /// Check if a denunciation has been executed given a `DenunciationIndex`
112    /// (speculative, final)
113    fn get_denunciation_execution_status(
114        &self,
115        denunciation_index: &DenunciationIndex,
116    ) -> (bool, bool);
117
118    /// Gets information about a batch of addresses.
119    /// `max_keys` caps the datastore keys listed per address (`None` = unbounded);
120    /// callers must pass their configured cap, never `None` on a transport path.
121    fn get_addresses_infos(
122        &self,
123        addresses: &[Address],
124        deferred_credits_max_slot: std::ops::Bound<Slot>,
125        max_keys: Option<u32>,
126    ) -> Vec<ExecutionAddressInfo>;
127
128    /// Get execution statistics
129    fn get_stats(&self) -> ExecutionStats;
130
131    /// Get the current module LRU cache size
132    fn get_module_lru_cache_memory_usage(&self) -> usize;
133
134    /// Get the number of events currently in the active history
135    fn get_active_history_total_event_len(&self) -> usize;
136
137    #[cfg(feature = "execution-trace")]
138    /// Get the abi call stack for a given operation id
139    fn get_operation_abi_call_stack(&self, operation_id: OperationId) -> Option<Vec<AbiTrace>>;
140
141    #[cfg(feature = "execution-trace")]
142    /// Get the abi call stack for a given slot
143    fn get_slot_abi_call_stack(&self, slot: Slot) -> Option<SlotAbiCallStack>;
144
145    #[cfg(feature = "execution-trace")]
146    /// Get the all transfers of MAS for a given slot
147    fn get_transfers_for_slot(&self, slot: Slot) -> Option<Vec<Transfer>>;
148
149    #[cfg(feature = "execution-trace")]
150    /// Get both the ABI call stack and the direct transfers for a given slot, read from a
151    /// single consistent snapshot of the execution trace history.
152    ///
153    /// Callers that need both datasets for a slot must use this instead of combining
154    /// `get_slot_abi_call_stack` and `get_transfers_for_slot`: those are two separate reads,
155    /// and a slot re-execution occurring between them can yield a response mixing data from
156    /// two different executions of the same slot.
157    fn get_slot_abi_call_stack_and_transfers(
158        &self,
159        slot: Slot,
160    ) -> (Option<SlotAbiCallStack>, Option<Vec<Transfer>>);
161
162    #[cfg(feature = "execution-trace")]
163    /// Get the transfer of MAS for a given operation id
164    fn get_transfer_for_op(&self, op_id: &OperationId) -> Option<Transfer>;
165
166    /// Returns a boxed clone of self.
167    /// Useful to allow cloning `Box<dyn ExecutionController>`.
168    fn clone_box(&self) -> Box<dyn ExecutionController>;
169}
170
171/// Allow cloning `Box<dyn ExecutionController>`
172/// Uses `ExecutionController::clone_box` internally
173impl Clone for Box<dyn ExecutionController> {
174    fn clone(&self) -> Box<dyn ExecutionController> {
175        self.clone_box()
176    }
177}
178
179/// Execution manager used to stop the execution thread
180pub trait ExecutionManager {
181    /// Stop the execution thread
182    /// Note that we do not take self by value to consume it
183    /// because it is not allowed to move out of `Box<dyn ExecutionManager>`
184    /// This will improve if the `unsized_fn_params` feature stabilizes enough to be safely usable.
185    fn stop(&mut self);
186}