This repository is home of the Leios R&D project whose purpose is to define a specification of the Ouroboros Leios protocol.

This project aims to address the challenges outlined in CPS-0018, which focuses on improving transaction throughput in the Cardano network.

Checkout CONTRIBUTING.md document for possible contributions and communication channels

More documentation about Leios can be found in the web site.

• Logbook contains a detailed account of problems,successes, failures, ideas, references and is intended as a tool to help the team members stay in sync. It's updated frequently with notes about the day-to-day work, meetings, ideas, etc.
• data contains common input files, schemas, and default configurations used by both simulations
• deltaQ contains network quality analysis tools and measurements
• simulation contains experimental Haskell code to simulate the Leios protocol, including built-in visualization capabilities
• sim-rs contains experimental Rust code to simulate the Leios protocol
• ui contains the web-based visualization tool for the Rust simulation traces
• site contains the sources of the aforementioned web site

Both the Haskell and Rust simulations read in a network topology file that defines the nodes and their connections, along with a configuration file that controls various protocol parameters. The simulations then produce trace outputs that can be visualized to analyze the protocol's behavior. The Haskell simulation includes built-in visualization capabilities, while the Rust simulation generates JSONL traces that can be visualized using the web UI in the ui directory.

The Leios simulations (both Rust and Haskell) can be configured using YAML configuration files. The configuration schema is defined in data/simulation/config.d.ts and the default configuration is available in data/simulation/config.default.yaml.

Each parameter controls a specific aspect of the simulation, and some parameters are only supported by either the Rust or Haskell implementation:

For more details on each parameter, refer to the comments in the config.d.ts file and the default values in config.default.yaml.

The formal specification of the Leios protocol in Agda is refrenced from the repository: https://github.com/input-output-hk/ouroboros-leios-formal-spec

You can run both the Rust and Haskell simulations using Docker to generate simulation trace logs.

# Build the Rust simulation image
docker build --target rs -t ouroboros-leios/sim-rs:latest -f Dockerfile .

# Build the Haskell simulation image
docker build --target hs -t ouroboros-leios/sim-hs:latest -f Dockerfile .

The Rust simulation generates JSONL trace files that can be visualized using the web-based UI:

# Run with default settings
docker run -v $(pwd)/output:/output ouroboros-leios/sim-rs:latest

# Run with custom output file location
docker run -v $(pwd)/output:/output ouroboros-leios/sim-rs:latest /output/simulation.jsonl

# Mount your config directory and use custom files
docker run \
  -v $(pwd)/output:/output \
  -v $(pwd)/data/simulation:/config \
  ouroboros-leios/sim-rs:latest /config/topology-dense-52.yaml /output/simulation.jsonl -s 20 -p /config/config.default.yaml

Common arguments for Rust simulation:

• -s NUMBER: Number of slots to simulate
• -p PATH: Path to custom parameters file
• --trace-node NODE_ID: Enable tracing for specific node
• --timescale SCALE: Adjust simulation speed (e.g., 16 for 16x faster)

The Haskell simulation generates log files with simulation data:

# Run with default settings (40 seconds)
docker run -v $(pwd)/output:/output ouroboros-leios/sim-hs:latest

# Run for 120 seconds with specific output file
docker run -v $(pwd)/output:/output ouroboros-leios/sim-hs:latest \
    --output-seconds 120 \
    --output-file /output/my-simulation.log

# Run with custom topology and config files
docker run \
    -v $(pwd)/output:/output \
    -v $(pwd)/data/simulation:/config \
    ouroboros-leios/sim-hs:latest \
    --topology /config/topology-dense-52.yaml \
    --config /config/config.default.yaml \
    --output-seconds 60 \
    --seed 12345

Common arguments for Haskell simulation:

• --output-seconds NUMBER: Duration of simulation in seconds (default: 40)
• --seed NUMBER: Random seed for reproducible runs
• --topology PATH: Custom topology file
• --config PATH: Custom configuration file
• --output-file PATH: Custom output file location

The Leios CIP initially proposed in November 2022, yielded the following content. While the material there is still relevant and useful, it won't be updated in the future.

• report: the LaTeX source for the design report
• CIP: the initial version of the Leios CIP
• simulation: simulation and visualisation code for investigating Leios-like network traffic patterns.