Struct Cluster 

pub struct Cluster {

    pub config: ClusterConfig,
    scenario: ClusterScenarioRun,
    available_ports: Box<dyn Iterator<Item = u16> + Send>,
    account_sec_keys: BTreeMap<AccountPublicKey, AccountSecretKey>,
    nodes: Vec<Node>,
    ocaml_nodes: Vec<Option<OcamlNode>>,
    initial_time: Option<Timestamp>,
    rpc_counter: usize,
    ocaml_libp2p_keypair_i: usize,
    verifier_srs: Arc<VerifierSRS>,
    block_verifier_index: BlockVerifier,
    work_verifier_index: TransactionVerifier,
    debugger: Option<Debugger>,
    invariants_state: Arc<Mutex<InvariantsState>>,
}

Manages a cluster of Mina nodes for testing scenarios.

The Cluster struct coordinates multiple node instances, handling resource allocation, configuration, and lifecycle management. It supports both Rust and OCaml node implementations for comprehensive testing.

Default Behaviors

• Port allocation: Automatically assigns available ports from the configured range, testing availability before assignment
• Keypair management: Uses deterministic keypairs for Rust nodes and rotates through predefined keypairs for OCaml nodes
• Resource isolation: Each node gets isolated temporary directories
• Verifier indices: Shared verifier SRS and indices across all nodes
• Network debugging: Optional debugger integration for CI environments

Node Addition

The cluster provides specialized methods for adding different node types:

• Rust nodes via add_rust_node
• OCaml nodes via add_ocaml_node

Fields

config: ClusterConfig

Cluster-wide configuration settings

scenario: ClusterScenarioRun

Current scenario execution state

available_ports: Box<dyn Iterator<Item = u16> + Send>

Iterator over available ports for node allocation

account_sec_keys: BTreeMap<AccountPublicKey, AccountSecretKey>

Registry of account secret keys for deterministic testing

nodes: Vec<Node>

Collection of active Rust nodes

ocaml_nodes: Vec<Option<OcamlNode>>

Collection of active OCaml nodes (Option for lifecycle management)

initial_time: Option<Timestamp>

Genesis timestamp for deterministic time progression

rpc_counter: usize

Counter for generating unique RPC request IDs

ocaml_libp2p_keypair_i: usize

Index for rotating OCaml LibP2P keypairs

verifier_srs: Arc<VerifierSRS>

Shared verifier SRS for proof verification

block_verifier_index: BlockVerifier

Block verifier index for consensus validation

work_verifier_index: TransactionVerifier

Transaction verifier index for transaction validation

debugger: Option<Debugger>

Optional network traffic debugger

invariants_state: Arc<Mutex<InvariantsState>>

Shared state for invariant checking across nodes

Implementations

impl Cluster

pub fn new(config: ClusterConfig) -> Self

pub fn available_port(&mut self) -> Option<u16>

pub fn add_account_sec_key(&mut self, sec_key: AccountSecretKey)

pub fn get_account_sec_key( &self, pub_key: &AccountPublicKey, ) -> Option<&AccountSecretKey>

pub fn set_initial_time(&mut self, initial_time: Timestamp)

pub fn get_initial_time(&self) -> Option<Timestamp>

pub fn add_rust_node( &mut self, testing_config: RustNodeTestingConfig, ) -> ClusterNodeId

Add a new Rust implementation node to the cluster.

Creates and configures a Rust Mina node with the specified testing configuration. This method handles all aspects of node initialization including port allocation, key generation, service setup, and state initialization.

Default Behaviors

• Port allocation: HTTP and LibP2P ports automatically assigned from available port range
• Peer identity: Deterministic LibP2P keypair based on node index
• Work directory: Isolated temporary directory per node
• Invariants: Automatic invariant checking enabled
• HTTP server: Spawned on separate thread for API access
• Proof verification: Shared verifier indices and SRS

Configuration Options

• peer_id: Deterministic or custom LibP2P identity
• libp2p_port: Custom P2P port (auto-assigned if None)
• initial_peers: Peer connection targets (supports node references)
• block_producer: Optional block production configuration
• genesis: Genesis ledger and protocol constants
• snark_worker: SNARK work generation settings

Returns

Returns a ClusterNodeId that can be used to reference this node in scenarios and for inter-node connections.

Panics

Panics if:

• No available ports in the configured range
• Node service initialization fails
• Invalid genesis configuration

pub fn add_ocaml_node( &mut self, testing_config: OcamlNodeTestingConfig, ) -> ClusterOcamlNodeId

Add a new OCaml implementation node to the cluster.

Creates and spawns an OCaml Mina daemon process with the specified configuration. This method handles process spawning, port allocation, directory setup, and daemon configuration.

Default Behaviors

• Executable selection: Automatically detects local binary or falls back to default Docker image
• Port allocation: LibP2P, GraphQL, and client ports automatically assigned from available range
• Keypair rotation: Uses predefined LibP2P keypairs, rotating through the set for each new node
• Process management: Spawns daemon with proper environment variables and argument configuration
• Logging: Stdout/stderr forwarded with port-based prefixes
• Docker support: Automatic container management when using Docker

Configuration Options

• initial_peers: List of peer connection targets
• daemon_json: Genesis configuration (file path or in-memory JSON)
• block_producer: Optional block production key

Docker vs Local Execution

The method automatically determines execution mode:

1. Attempts to use locally installed mina binary
2. Falls back to Docker with default image if binary not found
3. Custom Docker images supported via configuration

Returns

Returns a ClusterOcamlNodeId for referencing this OCaml node in scenarios and peer connections.

Panics

Panics if:

• No available ports in the configured range
• Temporary directory creation fails
• OCaml daemon process spawn fails

pub async fn start(&mut self, scenario: Scenario) -> Result<(), Error>

pub async fn reload_scenarios(&mut self) -> Result<(), Error>

pub fn next_scenario_and_step(&self) -> Option<(&ScenarioId, usize)>

pub fn target_scenario(&self) -> Option<&ScenarioId>

pub fn nodes_iter(&self) -> impl Iterator<Item = (ClusterNodeId, &Node)>

pub fn ocaml_nodes_iter( &self, ) -> impl Iterator<Item = (ClusterOcamlNodeId, &OcamlNode)>

pub fn node(&self, node_id: ClusterNodeId) -> Option<&Node>

pub fn node_by_peer_id(&self, peer_id: PeerId) -> Option<&Node>

pub fn node_mut(&mut self, node_id: ClusterNodeId) -> Option<&mut Node>

pub fn ocaml_node(&self, node_id: ClusterOcamlNodeId) -> Option<&OcamlNode>

pub fn ocaml_node_by_peer_id(&self, peer_id: PeerId) -> Option<&OcamlNode>

pub fn pending_events( &mut self, poll: bool, ) -> impl Iterator<Item = (ClusterNodeId, &State, impl Iterator<Item = (PendingEventId, &Event)>)>

pub fn node_pending_events( &mut self, node_id: ClusterNodeId, poll: bool, ) -> Result<(&State, impl Iterator<Item = (PendingEventId, &Event)>), Error>

pub async fn wait_for_pending_events(&mut self)

pub async fn wait_for_pending_events_with_timeout( &mut self, timeout: Duration, ) -> bool

pub async fn wait_for_pending_event( &mut self, node_id: ClusterNodeId, event_pattern: &str, ) -> Result<PendingEventId>

pub async fn wait_for_event_and_dispatch( &mut self, node_id: ClusterNodeId, event_pattern: &str, ) -> Result<bool>

pub async fn add_steps_and_save( &mut self, steps: impl IntoIterator<Item = ScenarioStep>, )

pub async fn exec_to_end(&mut self) -> Result<(), Error>

pub async fn exec_until( &mut self, target_scenario: ScenarioId, step_i: Option<usize>, ) -> Result<(), Error>

pub async fn exec_next(&mut self) -> Result<bool, Error>

pub async fn exec_step(&mut self, step: ScenarioStep) -> Result<bool>

pub fn debugger(&self) -> Option<&Debugger>