solana-validator-optimizer 2.3.0

Optimized Solana validator tool with snapshot prefetching, RPC caching, and Prometheus metrics.
Documentation

solana-validator-optimizer

Crates.io Release Docs.rs

A production-grade Rust toolkit for Solana infrastructure diagnostics, validator optimization, RPC health checks, caching, metrics, and production-readiness workflows.

Overview

solana-validator-optimizer is a modular enhancement suite for Solana validator infrastructure. It helps operators by:

  • Running validator preflight readiness checks before deployment or restart
  • Validating RPC health, cluster genesis hash, current slot, and blockhash availability
  • Checking host CPU, memory, and disk readiness
  • Prefetching ledger snapshots from trusted mirrors
  • Validating snapshot integrity via SHA-256
  • Auto-tuning validator configuration based on hardware resources
  • Adding an in-memory LRU cache for frequently used RPC calls
  • Exposing Prometheus metrics via a /metrics endpoint

Compatibility

The project currently builds against the Solana 3.x Rust crate line.

  • Solana crate line: 3.x
  • RPC diagnostics have been exercised against Mainnet-Beta RPC endpoints reporting Agave/Solana 4.x
  • Tested against:

RPC-level interoperability with a newer Agave endpoint does not imply full build-time compatibility with the Agave 4.x Rust crate line.

Ideal For

  • Solana Validator Operators
  • RPC Infrastructure Maintainers
  • Performance-Focused Mainnet/Devnet Deployments

Core Features

Feature Description
Validator Preflight Aggregates RPC, cluster identity, CPU, memory, disk, and readiness checks into PASS/WARN/FAIL results
Genesis Validation Retrieves the cluster genesis hash and optionally validates it against an operator-supplied expected hash
Snapshot Prefetching Downloads or copies snapshots locally with optional SHA-256 validation
RPC LRU Cache Reduces redundant RPC calls like getBalance, getEpochInfo, etc.
Prometheus Metrics /metrics endpoint for cache hits, misses, request counts, and latency
Config Auto-Tuner Adjusts validator configuration based on CPU, RAM, disk, and network
RPC Health Checker Checks RPC health, Solana/Agave version, genesis hash, current slot, latest blockhash availability, and RPC latency

Architecture

Architecture Overview

Getting Started

1. Clone the Repository

git clone https://github.com/0rlych1kk4/solana-validator-optimizer.git
cd solana-validator-optimizer

2. Configuration

Create a Config.toml file in the project root:

# Config.toml

# Snapshot settings
snapshot_url   = ""    # e.g. "https://snapshots.myvalidator.com/latest.tar.zst"
snapshot_sha256 = ""   # optional SHA-256 checksum for validation

# RPC and Metrics
rpc_url      = "https://api.mainnet-beta.solana.com"
metrics_port = 9090    # Prometheus scrapes at http://<host>:9090/metrics

# Cache settings
cache_size = 128       # Number of entries in the RPC LRU cache

Usage – CLI Mode

Run all modules (snapshot, RPC cache, auto-tuner, metrics):

cargo run -p solana-validator-optimizer-cli --release

Usage – As a Library

Add this to your Cargo.toml:

[dependencies]
solana-validator-optimizer = "2.3.0"
tokio = { version = "1", features = ["full"] }
anyhow = "1"

Example usage:

use solana_validator_optimizer::{
    config::AppConfig,
    snapshot_prefetcher,
    rpc_cache_layer,
    metrics,
    config_autotuner,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load configuration from Config.toml and/or OPTIMIZER_* env vars
    let cfg = AppConfig::load()?;

    // Prefetch snapshot (no-op if snapshot_url is empty)
    snapshot_prefetcher::run(&cfg).await?;

    // Auto-tune configuration (currently informational)
    config_autotuner::autotune_config(&cfg).await?;

    // Start background RPC cache workers
    rpc_cache_layer::start_rpc_cache(&cfg).await?;

    // Start Prometheus metrics server (blocks)
    metrics::start_metrics_server(&cfg).await?;

    Ok(())
}

Usage – RPC Health Checker

Check the configured Solana RPC endpoint from Config.toml:

cargo run -p solana-validator-optimizer-cli -- rpc-health

Example output:

Solana RPC Health Report
Endpoint: https://api.mainnet-beta.solana.com
Healthy: true
Health Status: ok
Solana Version: 4.2.0-rc.1
Genesis Hash: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d
Current Slot: 438204077
Latest Blockhash: 77L8S6DcWGDsAVQJr1S4n4n7EPn7wP365DgHiMNFJbMc
getHealth Latency: 956 ms
getVersion Latency: 328 ms
getGenesisHash Latency: 308 ms
getSlot Latency: 295 ms
getLatestBlockhash Latency: 626 ms

Use a custom endpoint:

cargo run -p solana-validator-optimizer-cli -- rpc-health --endpoint https://api.mainnet-beta.solana.com

Output as JSON:

cargo run -p solana-validator-optimizer-cli -- rpc-health --json

The RPC Health Checker helps Solana infrastructure teams validate endpoint health, cluster identity, blockhash availability, and latency before transaction submission or production deployment.

Usage – Validator Preflight

Run production-readiness checks using the RPC endpoint configured in Config.toml:

cargo run -p solana-validator-optimizer-cli -- preflight

The preflight command evaluates:

  • RPC health
  • Solana/Agave version
  • Cluster genesis hash
  • Current slot
  • Latest blockhash availability
  • RPC latency
  • Logical CPU count
  • Total memory
  • Available memory
  • Available disk space

Example output:

Solana Validator Preflight
Endpoint: https://api.mainnet-beta.solana.com

[PASS] rpc_health           RPC health status: ok
[PASS] solana_version       Detected Solana/Agave version: 4.2.0-rc.1
[PASS] genesis_hash         Genesis hash: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d
[PASS] current_slot         Current slot: 438203915
[PASS] latest_blockhash     Latest blockhash available
[PASS] rpc_latency          RPC latency is within the 1000 ms threshold
[PASS] cpu                  Logical CPU count: 8
[WARN] memory_total         Total memory: 8.0 GiB
[WARN] memory_available     Available memory: 0.34 GiB
[PASS] disk_available       Disk space: 57.8 GiB available / 228.3 GiB total

Overall readiness: READY

Validate an Expected Genesis Hash

Use an expected genesis hash to detect a wrong-cluster configuration:

cargo run -p solana-validator-optimizer-cli -- preflight --expected-genesis-hash 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d

A matching hash produces:

[PASS] genesis_hash         Genesis hash matches expected value: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d
Overall readiness: READY

A mismatch is treated as a hard readiness failure:

[FAIL] genesis_hash         Genesis hash mismatch: expected 11111111111111111111111111111111, observed 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d
Overall readiness: NOT READY

Warnings such as elevated RPC latency or limited available memory do not automatically fail readiness. Hard failures such as an unhealthy RPC endpoint, missing required cluster data, or a genesis-hash mismatch result in NOT READY.

Machine-readable output is also available:

cargo run -p solana-validator-optimizer-cli -- preflight --json

Environment Variables

Any Config.toml value can be overridden using the OPTIMIZER_ prefix.

Config Key Environment Variable
snapshot_url OPTIMIZER_SNAPSHOT_URL
snapshot_sha256 OPTIMIZER_SNAPSHOT_SHA256
rpc_url OPTIMIZER_RPC_URL
metrics_port OPTIMIZER_METRICS_PORT
cache_size OPTIMIZER_CACHE_SIZE

Example:

OPTIMIZER_RPC_URL=https://api.mainnet-beta.solana.com \
OPTIMIZER_CACHE_SIZE=256 \
cargo run --release

Operational Metrics

Prometheus endpoint:

http://<host>:<metrics_port>/metrics

Exposed Metrics

  • rpc_requests_total
  • rpc_cache_hits_total
  • rpc_cache_misses_total

Metrics

Enable Prometheus metrics endpoint:

cargo run -p solana-validator-optimizer-cli --release --features metrics -- --config Config.toml run
curl -s http://127.0.0.1:9090/metrics | grep rpc_

Contributing

Contributions are welcome!
Feel free to open issues, feature requests, or pull requests.

License

Licensed under the MIT License.