Mithril

Mithril is a Solana full node client written in Golang with the goal of serving as a "verifying full node" with lower hardware requirements than that of Solana validators and RPC nodes. This project is being developed upon the foundations of Radiance, which was built by Richard Patel (@ripatel) with contributions from @leoluk.

This project is under active development. We are completing an audit with Runtime Verification and expect a more polished, feature-rich release in early Q1 2026.

While Mithril is already functional and runs reliably for many use cases, it is not yet considered production-ready. Users should expect occasional bugs, incomplete features, and ongoing changes as development progresses. Please use with appropriate caution and follow the dev branch for the latest updates.

---

Running Mithril

The run command starts Mithril as a live verifier - it bootstraps from a Solana snapshot and continuously verifies new blocks as they are produced on mainnet-beta.

Hardware Requirements

Operating System

• Ubuntu 24.04 LTS (recommended)

CPU

• Higher core speed Ryzen series recommended, at least 3.5 GHz base clock
• The 6-core AMD Ryzen 5 7640HS performs exceptionally well in our testing
• We haven't extensively tested a wide range of hardware yet - join the #mithril-hardware channel on the Overclock Validator Discord to discuss hardware configurations

Storage

• Minimum 1 TB PCIe 4.0 NVMe SSD (more storage can be nice, espeecially to retain larger ledger size)
• Two NVMe drives preferable for optimal performance:
  • Fast NVMe: Mithril's AccountsDB (requires high IOPS)
  • Secondary NVMe: Block storage and snapshots (can be slower)
• Samsung 990 Pro has been exceptional in our testing
• Filesystem: We are still testing optimal filesystem configurations (xfs vs ext4) - more guidance coming soon

Network

• Mithril works on a home internet connections
• Slower internet speeds will result in longer snapshot download times
• The integrated snapshot finder automatically selects the fastest available snapshot source

Getting Started

Step 1: Clone the repository

git clone https://github.com/Overclock-Validator/mithril.git
cd mithril

Step 2 (Optional): Run setup scripts

We provide helper scripts for setting up your system. See the scripts documentation for a detailed walkthrough:

• Server Setup - Fresh Ubuntu install (rescue mode) or security hardening (existing Ubuntu)
• Disk Setup - Benchmark NVMe drives, format with optimal settings, reset Mithril data
• Performance Tuning - Kernel settings, CPU optimization, etc.

The scripts create the following directory structure (following Agave conventions):

/mnt/mithril-accounts/   # AccountsDB (needs higher random IOPS - use fastest drive)
/mnt/mithril-ledger/     # Blockstore and snapshots (can use slower drive)
    ├── blockstore/
    └── snapshots/

After running the disk setup script, set ownership so Mithril can write to these directories:

sudo chown -R $USER:$USER /mnt/mithril-accounts /mnt/mithril-ledger

Step 3: Install build dependencies

Mithril requires a C compiler for CGO dependencies:

sudo apt-get update && sudo apt-get install -y build-essential

Step 4: Install Go 1.25 or later

Go 1.25 introduced the "green tea" garbage collector improvements which provide better performance for memory-intensive applications like Mithril.

# Set Go version and detect architecture
GO_VERSION="1.25.0"
case $(uname -m) in
    x86_64)  GOARCH="amd64" ;;
    aarch64) GOARCH="arm64" ;;
    *) echo "Unsupported architecture"; exit 1 ;;
esac

# Download and install
wget "https://go.dev/dl/go${GO_VERSION}.linux-${GOARCH}.tar.gz"
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf "go${GO_VERSION}.linux-${GOARCH}.tar.gz"
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
go version

Step 5: Build Mithril

go build -o mithril ./cmd/mithril

Configuration

Generate a starter config with sensible defaults:

./mithril config init

This creates config.toml with all essential settings. Key options to review:

name = "mithril"

[bootstrap]
    # How Mithril initializes state:
    #   "auto"       - Use existing AccountsDB if valid, else download snapshot
    #   "snapshot"   - Always download fresh snapshot (default, good for early-stage)
    #   "accountsdb" - Require existing AccountsDB, fail if missing
    mode = "snapshot"

[storage]
    # AccountsDB path - use your fastest NVMe
    accounts = "/mnt/mithril-accounts"
    blockstore = "/mnt/mithril-ledger/blockstore"

[network]
    # Solana RPC endpoint(s) for discovering snapshots and fetching blocks
    rpc = ["https://api.mainnet-beta.solana.com"]

[replay]
    # Transaction parallelism - recommended: 2x your CPU core count
    # e.g., 192 for a 96-core machine, 24 for a 12-core machine
    txpar = 24

[rpc]
    # Mithril's RPC server (localhost only, enabled by default)
    port = 8899

See config.example.toml for all available configuration options including snapshot finder tuning and performance settings.

Running Mithril

./mithril run --config config.toml

What happens:

1. Mithril queries the Solana cluster to find reliable snapshot sources
2. The full snapshot is streamed directly into memory and processed
3. An incremental snapshot is fetched to bring the state closer to the tip
4. Mithril block execution (aka replay) is initiated and blocks are retrieved with RPC getBlock calls and verified
5. Mithril keeps up very close to the tip of the chain with recommended hardware specs

Mithril's Simple RPC Server

Mithril includes a basic RPC server implementation that exposes a subset of Solana-compatible JSON-RPC methods. This is still under active development and not yet feature-complete.

To enable it, set the port in your config:

[rpc]
    port = 8899

Once running, you can query Mithril like any Solana RPC:

# Query from the same machine
curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d '
  {"jsonrpc":"2.0","id":1,"method":"getBlockHeight"}
'

# Query from another server (replace with your Mithril host IP)
curl http://YOUR_MITHRIL_IP:8899 -X POST -H "Content-Type: application/json" -d '
  {"jsonrpc":"2.0","id":1,"method":"getAccountInfo","params":["YOUR_PUBKEY",{"encoding":"base64"}]}
'

Currently supported RPC methods:

• getAccountInfo - Get account data and lamports
• getBlockHeight - Get current block height
• getEpochInfo - Get current epoch info
• getLatestBlockhash - Get recent blockhash

We're actively expanding RPC method coverage. Upcoming methods include transaction simulation, send transaction, and get leader schedule.

Current Limitations

• Block Catchup: Mithril currently relies on getBlock RPC calls to catch up to the tip of mainnet-beta. We are actively working on adding support for direct shred replay, which will be more decentralized and performant.

Troubleshooting

Slow snapshot downloads

• The snapshot finder automatically tests many nodes and selects the fastest. If downloads are consistently slow, your network may be the bottleneck, but try increasing stage 2 parameters.
• Enable verbose = true in the [snapshot] config section to see detailed node discovery statistics.

High disk I/O

• Ensure AccountsDB is on your fastest NVMe drive
• Consider using a higher-endurance drive (Samsung 990 Pro or better recommended)

Out of memory

• Mithril streams snapshots directly to processing without requiring disk space for the full snapshot file
• Initial sync uses more RAM than steady-state replay

Updating Mithril

To update Mithril to a newer version:

# Stop Mithril (Ctrl+C or kill the process)

# Pull latest changes and rebuild
cd mithril
git pull
go build -o mithril ./cmd/mithril

# Restart
./mithril run --config config.toml

Note: With bootstrap.mode = "snapshot" (the default), each restart downloads a fresh snapshot and re-syncs from scratch. Set bootstrap.mode = "auto" to reuse an existing AccountsDB when available.

Operational Best Practices

Clean Shutdown: Always use Ctrl+C to stop Mithril cleanly rather than killing the terminal or closing the SSH session. This allows Mithril to flush data and exit gracefully.

For detailed troubleshooting tips, see docs/TROUBLESHOOTING.md.

---

Development Milestones

Milestone 1 (Completed): Reimplementation of the Solana Virtual Machine in Golang

• Completed in August 2024, read more here.
• Reimplementation of all syscalls, with a comprehensive test suite developed and exercised; bugs found as a result fixed.
• Reimplementation of all native programs, with a comprehensive test suite developed and exercised; bugs found as a result fixed.
• Implementation of the remainder of the runtime and VM, with a comprehensive test suite also developed. Any bugs found as a result of testing and review to be fixed.
• Successfully tested against Firedancer's Solana conformance suite

Milestone 2 (Completed): Block Replay and Simple RPC Interface

• Snapshot retrieval and loading.
• Full implementation of transaction (and therefore block) handling (consistently match Mainnet bankhashes).
• Incorporate the AccountsDB and Blockstore facilities that are necessary for data storage and retrieval.
• Minimal RPC interface.
• Status: Mithril can retrieve and replay current MainnetBeta blocks. There are rare bankhash mismatches that we are actively investigating.

Milestone 3 (In Progress): Alpha Release and System Optimization

• First formal audit (https://runtimeverification.com/ team is nearing end of audit). Includes development and intensive use of a robust and comprehensive 'conformance suite' for verification of compliance of the VM, interpreter, and runtime as a complete unit. Differential fuzzing will be used to detect differences versus relevant versions of the Labs client, and guided fuzzing will be used generally to uncover security and loss-of-availability issues. Any bugs identified during this phase will be remediated.
• Thorough optimization work on entire system, including on components such as the Virtual Machine and AccountsDB.
• Consensus verification implementation.
• Direct shred replay support (alternative to RPC-based block fetching and requires consensus implementation).
• Achieve multi-epoch runs without bugs (e.g. bankhash mismatches with mainnet)
• Transaction simulation and transaction sending
• Earlier testing on testnet environments.
• Target: More substantial release in early Q1 2026 following alpha release in December 2025.

Future Directions

• Implement Alpenglow consensus verification.
• Add Agave ledger-tool type features for Mithril
• gRPC interface support.
• Expanded RPC feature set.
• Implementation of 'archival node' features including historical replay compatibility.
• Ongoing performance improvements and any bug fixes.
• We welcome community suggestions - please open an issue or join our Discord to discuss ideas!

---

Community

• Discord: Join the Overclock Validator Discord for support and discussion
• Hardware Discussion: #mithril-hardware channel for hardware recommendations
• GitHub Issues: Report bugs and feature requests on the GitHub repository