Performance Benchmarks

Comprehensive guide to performance benchmarking and regression testing

Rivellum includes a built-in benchmarking tool (rivellum-bench) for measuring throughput, latency, and regression testing.

Quick Start

# Build release binaries
cargo build --release --bin rivellum-bench

# Run a basic transfer benchmark (2K intents)
./target/release/rivellum-bench run -s solo-transfers -t 2000 -c 100 --node-url https://rpc.rivellum.network

# Run a larger benchmark (10K intents)
./target/release/rivellum-bench run -s solo-transfers -t 10000 -c 200 --node-url https://rpc.rivellum.network

Scenarios

Scenario	Description
`solo-transfers`	Native RIVL transfers to random destinations
`same-lane-transfers`	Sender and receiver hash to the same lane
`sustained-load`	Configurable TPS injection with warmup window
`mixed-contracts`	Multi-type operations (transfers, contract calls)
`pouw-heavy`	ZK proof generation jobs
`zk-enabled`	Encrypted envelope submission (private intents)

CLI Reference

rivellum-bench run \
    --scenario <SCENARIO>          # Required: scenario name
    --node-url <URL>               # Required: node RPC endpoint
    --tx-count <N>                 # Number of intents to submit
    --concurrency <N>              # Concurrent submission tasks
    [--ci-smoke]                   # Reduced load for CI
    [--private]                    # Use encrypted envelopes
    [--seed <N>]                   # Deterministic wallet generation
    [--rate <TPS>]                 # Target TPS injection rate
    [--lanes <0,1,2,...>]          # Target specific lanes
    [--warmup <secs>]              # Warmup duration before measuring
    [--measured-duration <secs>]   # Measurement window length
    [--cross-lane]                 # Force cross-lane transfers

Regression Testing

# Compare two benchmark runs
rivellum-bench compare \
    --baseline baseline.json \
    --current current.json \
    [--tps-threshold 5]            # % drop that triggers failure
    [--p95-threshold 10]           # % latency increase threshold
    [--fail-on-regression]         # Exit code 1 on regression

# Export results
rivellum-bench export --input results.json --output report.html --format html

Metrics Collected

Each run produces:

Throughput: Transactions per second (TPS)
Latency: Average, P50, P95, P99 (milliseconds)
Success/Failure counts with error categorization
Duration: Wall clock and measured window

Pre-funded Wallets

For benchmarking, initialize the testnet with pre-funded wallets:

# Initialize testnet with 300K bench wallets
cargo run --release --bin rivellum-testnet -- init \
    --out ./testnet \
    --committees 2 \
    --validators 4 \
    --lanes 4 \
    --base-port 8080 \
    --bench-wallets 300000

# Start testnet
cargo run --release --bin rivellum-testnet -- up --dir ./testnet

Bench wallets are funded at genesis and their keys are derived deterministically from the --seed flag.

Interpreting Results

TPS scales roughly linearly with lane count for transfer workloads
P95 latency is more meaningful than average for production planning
Cross-lane transfers add latency due to CPC coordination
Run benchmarks on dedicated hardware for reproducible results