hyperscale-rs

Warning: Work in progress. Do not use.

Rust implementation of Hyperscale consensus protocol.

What's different:

• Pure consensus layer — no I/O, no locks, no async
• Created with deterministic simulation testing in mind
• Faster two-chain commit consensus based on HotStuff-2
• Optimistic pipelining — proposers propose immediately after QC formation
• Improved cross-shard livelock prevention
• Real Radix Engine integration

Crates

Crate	Purpose
hyperscale-types	Core types: hashes, blocks, votes, QCs, keys, transactions, topology
hyperscale-core	The StateMachine and SubStateMachine traits that everything implements
hyperscale-messages	Network message serialization (SBOR encoding)
hyperscale-bft	BFT consensus: block proposal, voting, QC formation, view changes
hyperscale-execution	Transaction execution with cross-shard 2PC coordination
hyperscale-mempool	Transaction pool management
hyperscale-livelock	Cross-shard deadlock detection and prevention
hyperscale-node	Composes all sub-state machines into the main NodeStateMachine
hyperscale-provisions	Centralized provision coordination for cross-shard transactions
hyperscale-engine	Radix Engine integration for smart contract execution
hyperscale-simulation	Deterministic simulator with configurable network conditions
hyperscale-simulator	CLI tool for running simulations with metrics
hyperscale-production	Production runner: libp2p networking, RocksDB storage, thread pools
hyperscale-spammer	Transaction spammer CLI and library for load testing
hyperscale-parallel	Parallel (non-deterministic) simulation for multi-core performance testing
hyperscale-test-helpers	Test helpers providing properly-signed fixtures for crypto testing

Installation

Binaries

Pre-built binaries for Linux (x86_64) and macOS (ARM64) are available on the Releases page.

Docker Image

You can pull the latest Docker image from the GitHub Container Registry:

docker pull ghcr.io/flightofthefox/hyperscale-rs:latest

Prerequisites

1. Install Rust

Install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Install Build Dependencies

You will need clang, lld, protobuf, and openssl.

macOS

brew install llvm protobuf openssl pkg-config

Linux (Ubuntu/Debian)

sudo apt-get update && sudo apt-get install -y \
    clang \
    lld \
    pkg-config \
    protobuf-compiler \
    git \
    build-essential \
    libssl-dev \
    libc6-dev

Windows

1. Install Rust.
2. Install LLVM.
3. Install Protoc.
4. Ensure clang and protoc are in your PATH.

3. Install Docker (Optional)

Required only if you plan to run the launch-docker-compose.sh script or use the provided Dockerfile.

macOS & Windows

Recommended: Docker Desktop or Rancher Desktop.

Linux

Install the Docker Engine and Docker Compose plugin: Install on Ubuntu | Install on Debian | Install on Fedora

Ensure your user is in the docker group to run commands without sudo:

sudo usermod -aG docker $USER
newgrp docker

Cloning with Submodules

This repository uses git submodules for vendor dependencies. When cloning, use:

git clone --recurse-submodules https://github.com/flightofthefox/hyperscale-rs.git

If you've already cloned the repository without submodules, initialize them with:

git submodule update --init --recursive

Building

cargo build --release

Running the Simulator

cargo run --release --bin hyperscale-sim

Running Tests

cargo test

Running a Local Cluster

For development and testing, you can launch a local cluster using the provided scripts.

Process-based Cluster

The launch-cluster.sh script launches a cluster of validator nodes as background processes on your host machine. This is faster and easier for quick iteration.

./scripts/launch-cluster.sh

Options:

• --shards <N>: Number of shards (default: 2)
• --validators-per-shard <M>: Validators per shard (default: 4)
• --clean: Clean data directories before starting
• --monitoring: Start Prometheus and Grafana for metrics

Docker-based Cluster

The launch-docker-compose.sh script launches a full cluster inside Docker containers using Docker Compose. This more closely mimics a production environment.

Important

Memory Requirement: Please ensure your Docker VM/Desktop is configured with at least 8-10GB of RAM. The validator nodes require significant memory for the high-throughput consensus simulation.

./scripts/launch-docker-compose.sh

Options:

• --build <true|false>: Whether to build the docker image (default: true). Set to false to use existing image for much faster startup.
• --use-ghcr-image: Use the latest pre-built image from GHCR instead of building locally.
• --shards <N>: Number of shards (default: 1)
• --validators-per-shard <M>: Validators per shard (default: 8)
• --memory <limit>: Memory limit per validator (e.g. 1g, 512m)
• --cpus <limit>: CPU limit per validator (e.g. 0.5)
• --latency <ms>: Artificial network latency per validator
• --latency-nodes <N>: Number of nodes to apply latency to (default: 1)

Stopping the Cluster

To stop the Docker cluster and remove volumes:

./scripts/stop-docker-compose.sh

Running Load Tests (Spammer)

To run load tests against your local cluster, use the hyperscale-spammer binary.

Important

Check Ports: You MUST use the ports outputted by the launch script at the end of its execution. These ports may vary depending on the number of validators and sharding configuration.

Example command (adjust ports as needed):

./target/release/hyperscale-spammer run \
  --endpoints "http://localhost:8080,http://localhost:8081" \
  --num-shards 2 \
  --validators-per-shard 4 \
  --tps 100 \
  --duration 30s

Troubleshooting

Windows: "Path too long" Error

If you encounter "path too long" errors during cargo build on Windows (often due to deep dependency trees), you need to enable Long Paths in Windows.

1. Open PowerShell as Administrator.
2. Run the following command to enable long paths in the registry:

   New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

3. Restart your computer (or sign out and back in).
4. Run this git command to ensure git uses long paths:

   git config --system core.longpaths true

Windows: "Can't find clang.dll" or "libclang.dll"

If you see errors about missing clang.dll or libclang.dll during build (usually from rocksdb or bindgen), you need to set the LIBCLANG_PATH environment variable.

1. Ensure LLVM is installed (choco install llvm).
2. Ensure protobuf is installed (choco install protobuf).
3. Set the environment variable to your LLVM bin directory:

   $env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"

   (Or add it permanently to your System Environment Variables).