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}