sim-rs

Leios Simulation

This directory contains a Rust simulation of the Leios protocol. It produces a stream of events which can be used to visualize or analyze the behavior of Leios.

For more information about the simulation, see ./IMPLEMENTATION.md.

Running the project

cargo run --release input_path [output_path] [-s slots] [--trace-node <node id>]

# for example...
cargo run --release ./test_data/realistic.yaml output/out.jsonl

The input_path is a YAML file which describes the network topology. Input files for predefined scenarios are in the test_data directory.

The default parameters for the simulation are defined in data/simulation/config.default.yaml in the root of this repository, which is symlinked to parameters/config.default.yaml here. To override parameters, pass -p <path-to-parameters-file> (you can pass this flag as many times as you'd like). Some predefined overrides are in the parameters directory.

While the simulation is running, it will log what's going on to the console. You can stop it at any time with ctrl+c, and when you do it will save the stream of events to output_path. To only simulate e.g. 50 slots, pass -s 50.

The simulation runs in virtual time and completes as fast as your machine allows.

Engine and shard selection

The simulator supports two execution engines, selected via the engine parameter:

Engine	Description	Deterministic	Attacker support
actor (default)	Tokio-based async actor system with virtual clock coordination	No	Yes
sequential	Discrete event simulation with strict timestamp ordering	Yes	No

Both engines support sharding: partitioning nodes into independent groups that run in parallel. The sequential engine additionally uses rayon to parallelise simultaneous events across nodes within each timestep. Cross-shard communication uses conservative message blocking (CMB) based on minimum inter-shard latencies. Configure with:

• shard-count — number of shards (default: 1)
• shard-strategy — node assignment strategy:
  • round-robin — simple round-robin by node ID
  • zero-latency-clusters — keeps zero-latency-connected nodes together (recommended)
  • geographic — k-means clustering by geographic coordinates
  • min-latency-clusters — agglomerative clustering by link latency
  • min-cut — recursive bisection with Kernighan-Lin refinement

For fast runs, a convenience preset is provided:

cargo run --release topology.yaml output.jsonl -s 500 -p parameters/turbo.yaml

This uses the sequential engine with 6 shards and zero-latency-clusters, typically giving ~5x speedup over the default actor engine.

Note

For instructions on running the simulation using Docker, please refer to the Docker Simulation section in the root README.md.

Using traces in model comparisons

Transaction diffusion

Assuming an output file simplified.json:

./txn_diffusion.sh simplified.json

This will output a ΔQ expression for use with the delta_q web tool corresponding to the probabilistic choice between all diffusion traces contained in the JSON file.