|
| 1 | +//! Engine definition trait and supporting types. |
| 2 | +
|
| 3 | +use super::tracker::FinalizationUpdate; |
| 4 | +use commonware_cryptography::PublicKey; |
| 5 | +use commonware_p2p::simulated::{self, Oracle}; |
| 6 | +use commonware_runtime::{deterministic, Handle, Quota}; |
| 7 | +use commonware_utils::channel::mpsc; |
| 8 | +use std::future::Future; |
| 9 | + |
| 10 | +/// A registered p2p channel pair (sender, receiver). |
| 11 | +pub type ChannelPair<P> = ( |
| 12 | + simulated::Sender<P, deterministic::Context>, |
| 13 | + simulated::Receiver<P>, |
| 14 | +); |
| 15 | + |
| 16 | +/// Arguments passed to [`EngineDefinition::init`]. |
| 17 | +pub struct InitContext<'a, P: PublicKey> { |
| 18 | + /// Labeled runtime context for this validator. |
| 19 | + pub context: deterministic::Context, |
| 20 | + /// Index of this validator in the participant list. |
| 21 | + pub index: usize, |
| 22 | + /// This validator's public key. |
| 23 | + pub public_key: &'a P, |
| 24 | + /// Network oracle for peer management. |
| 25 | + pub oracle: &'a Oracle<P, deterministic::Context>, |
| 26 | + /// Registered p2p channel pairs (same order as `channels()`). |
| 27 | + pub channels: Vec<ChannelPair<P>>, |
| 28 | + /// All participants in the simulation. |
| 29 | + pub participants: &'a [P], |
| 30 | + /// Channel for reporting finalization events to the harness. |
| 31 | + pub monitor: mpsc::Sender<FinalizationUpdate<P>>, |
| 32 | +} |
| 33 | + |
| 34 | +/// Defines how to construct and start one validator's service stack. |
| 35 | +/// |
| 36 | +/// The harness calls these methods for each validator in the simulation. |
| 37 | +/// The lifecycle is: |
| 38 | +/// 1. `channels()` -- declare which p2p channels are needed. |
| 39 | +/// 2. `init()` -- construct the engine (actors, archives, mailboxes). |
| 40 | +/// 3. `start()` -- start all actors, return a joinable handle. |
| 41 | +/// |
| 42 | +/// On restart after a crash, `init()` and `start()` are called again |
| 43 | +/// with the same validator identity but a fresh runtime context (storage |
| 44 | +/// state is preserved by the deterministic runtime). |
| 45 | +pub trait EngineDefinition: Clone + Send + 'static { |
| 46 | + /// The public key type used by this engine. |
| 47 | + type PublicKey: PublicKey; |
| 48 | + |
| 49 | + /// The constructed engine, passed from `init` to `start`. |
| 50 | + type Engine: Send + 'static; |
| 51 | + |
| 52 | + /// Per-validator state inspectable by property checkers. |
| 53 | + type State: Send + Sync + 'static; |
| 54 | + |
| 55 | + /// The participants for this simulation. |
| 56 | + /// |
| 57 | + /// Called once by the harness to determine the validator set. The engine |
| 58 | + /// is responsible for generating keys and any associated state (signing |
| 59 | + /// schemes, databases, etc.) during construction. |
| 60 | + fn participants(&self) -> Vec<Self::PublicKey>; |
| 61 | + |
| 62 | + /// Which p2p channels to register for each validator. |
| 63 | + /// |
| 64 | + /// Returns `(channel_id, quota)` pairs. The harness registers each |
| 65 | + /// on the simulated oracle and passes sender/receiver pairs to |
| 66 | + /// `init` in the same order. |
| 67 | + fn channels(&self) -> Vec<(u64, Quota)>; |
| 68 | + |
| 69 | + /// Construct the engine for a single validator. |
| 70 | + fn init( |
| 71 | + &self, |
| 72 | + ctx: InitContext<'_, Self::PublicKey>, |
| 73 | + ) -> impl Future<Output = (Self::Engine, Self::State)> + Send; |
| 74 | + |
| 75 | + /// Start all actors in the engine. Returns a handle the harness |
| 76 | + /// can join on (or abort on crash). |
| 77 | + fn start(engine: Self::Engine) -> Handle<()>; |
| 78 | +} |
0 commit comments