Validator Configuration

This guide covers all the configuration options available for the Harmonic Salsa validator.

Core Configuration

Identity and Vote Account

`--identity` (required)

Path to the validator’s identity keypair.

--identity ~/validator-keypair.json

`--vote-account`

Public key or keypair for the vote account. Required for consensus participation.

--vote-account ~/vote-account-keypair.json

`--authorized-voter`

Additional authorized voter keypairs. Can be specified multiple times.

--authorized-voter ~/voter-1.json \
--authorized-voter ~/voter-2.json

Ledger and Storage

`--ledger`

Directory for ledger storage.

--ledger ~/validator-ledger

`--accounts`

Persistent accounts storage location. Can be specified multiple times for multiple drives.

--accounts /mnt/nvme0/accounts \
--accounts /mnt/nvme1/accounts

`--account-shrink-path`

Path for accounts shrink operations.

--account-shrink-path /mnt/nvme2/shrink

`--snapshots`

Base directory for snapshots.

--snapshots ~/validator-snapshots

`--tower`

Directory for tower storage (voting record).

--tower ~/validator-tower

Network Configuration

`--entrypoint`

Gossip entrypoint for network bootstrapping. Specify multiple for redundancy.

--entrypoint entrypoint.mainnet-beta.solana.com:8001 \
--entrypoint entrypoint2.mainnet-beta.solana.com:8001 \
--entrypoint entrypoint3.mainnet-beta.solana.com:8001

`--known-validator`

Trusted validators for snapshot and genesis verification. Specify multiple.

--known-validator 7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2 \
--known-validator GdnSyH3YtwcxFvQrVVJMm1JhTS4QVX7MFsX56uJLUfiZ

`--bind-address`

IP address to bind validator ports. Can be specified multiple times.

--bind-address 0.0.0.0

`--gossip-port`

Port for gossip protocol.

--gossip-port 8001

`--dynamic-port-range`

Range of ports for dynamically assigned services.

--dynamic-port-range 8000-8020

`--public-tpu-address`

Public TPU address to advertise in gossip.

--public-tpu-address my-validator.com:8003

`--public-rpc-address`

Public RPC address to advertise (when running RPC behind load balancer).

--public-rpc-address rpc.my-validator.com:8899

RPC Configuration

Basic RPC Settings

`--rpc-port`

Enable JSON-RPC on specified port.

--rpc-port 8899

`--rpc-bind-address`

IP address for RPC server.

--rpc-bind-address 127.0.0.1

`--private-rpc`

Do not publish RPC port in gossip.

--private-rpc

Advanced RPC Options

`--full-rpc-api`

Enable all RPC methods (use with caution).

--full-rpc-api

`--no-port-check`

Skip TCP/UDP port reachability checks at startup.

--no-port-check

Snapshot Configuration

Snapshot Intervals

`--snapshot-interval-slots`

Slots between incremental snapshots.

--snapshot-interval-slots 500

`--full-snapshot-interval-slots`

Slots between full snapshots.

--full-snapshot-interval-slots 25000

Snapshot Retention

`--maximum-full-snapshots-to-retain`

Number of full snapshots to keep.

--maximum-full-snapshots-to-retain 5

`--maximum-incremental-snapshots-to-retain`

Number of incremental snapshots to keep.

--maximum-incremental-snapshots-to-retain 10

Snapshot Archives

`--full-snapshot-archive-path`

Directory for full snapshot archives.

--full-snapshot-archive-path ~/snapshots/full

`--incremental-snapshot-archive-path`

Directory for incremental snapshot archives.

--incremental-snapshot-archive-path ~/snapshots/incremental

`--snapshot-archive-format`

Compression format for snapshots.

--snapshot-archive-format zstd

Options: bz2, gzip, zstd, lz4, tar, none

`--snapshot-version`

Snapshot version format.

--snapshot-version 1.16.0

Snapshot Behavior

`--no-snapshots`

Disable all snapshot generation.

--no-snapshots

`--maximum-local-snapshot-age`

Reuse local snapshot if less than this many slots behind.

--maximum-local-snapshot-age 1000

`--minimal-snapshot-download-speed`

Minimum download speed (bytes/second) before retrying.

--minimal-snapshot-download-speed 10485760

Performance Tuning

Accounts Database

`--accounts-db-cache-limit-mb`

Write cache size for accounts database (MB).

--accounts-db-cache-limit-mb 10000

`--accounts-index-bins`

Number of bins for accounts index (must be power of 2).

--accounts-index-bins 8192

`--enable-accounts-disk-index`

Enable disk-based accounts index to reduce memory usage.

--enable-accounts-disk-index

`--accounts-index-path`

Path for disk-based accounts index. Requires --enable-accounts-disk-index.

--accounts-index-path /mnt/nvme3/accounts-index

`--accounts-shrink-ratio`

Ratio threshold for accounts shrinking (0.0-1.0).

--accounts-shrink-ratio 0.80

Ledger Limits

`--limit-ledger-size`

Maximum ledger shreds to retain.

--limit-ledger-size 50000000

This is crucial for managing disk space. Recommended: 50-250 million shreds depending on disk size.

RocksDB Configuration

`--rocksdb-shred-compaction`

RocksDB compaction style for shreds.

--rocksdb-shred-compaction level

`--rocksdb-ledger-compression`

Compression for transaction status data.

--rocksdb-ledger-compression lz4

Options: none, lz4, snappy, zlib

TPU/QUIC Configuration

`--tpu-connection-pool-size`

TPU connection pool size per remote address.

--tpu-connection-pool-size 4

`--num-quic-endpoints`

Number of QUIC endpoints for TPU.

--num-quic-endpoints 8

Increasing this can improve throughput at the cost of higher CPU usage.

`--tpu-max-staked-connections`

Max concurrent connections from staked nodes.

--tpu-max-staked-connections 2000

`--tpu-max-unstaked-connections`

Max concurrent connections from unstaked nodes.

--tpu-max-unstaked-connections 500

Block Production and Verification

`--block-production-method`

Method for block production.

--block-production-method central-scheduler

`--block-verification-method`

Method for block verification.

--block-verification-method unified-scheduler

`--unified-scheduler-handler-threads`

Number of handler threads for unified scheduler.

--unified-scheduler-handler-threads 4

Account Indexing

`--account-index`

Enable specific account indexes.

--account-index program-id \
--account-index spl-token-owner \
--account-index spl-token-mint

Options:

program-id: Index by program owner
spl-token-owner: Index by SPL token owner
spl-token-mint: Index by SPL token mint

`--account-index-exclude-key`

Exclude specific keys from indexing.

--account-index-exclude-key 11111111111111111111111111111111

Logging

Log Configuration

`--log`

Log file path. Use - for stderr.

--log ~/validator.log

Log Filtering

Set log levels using the RUST_LOG environment variable:

RUST_LOG=solana=info,solana_runtime::message_processor=debug

Or at runtime:

agave-validator set-log-filter solana_core=debug

Advanced Options

Genesis and Fork Configuration

`--expected-genesis-hash`

Require specific genesis hash.

--expected-genesis-hash 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d

`--expected-shred-version`

Require specific shred version.

--expected-shred-version 54321

`--wait-for-supermajority`

Wait for supermajority before starting PoH (coordinated restarts).

--wait-for-supermajority 123456789 \
--expected-bank-hash ABC123... \
--expected-shred-version 54321

`--hard-fork`

Specify hard fork slots.

--hard-fork 12345678

Voting Configuration

`--no-voting`

Disable voting (run as RPC node).

--no-voting

`--vote-use-quic`

Use QUIC for sending votes.

--vote-use-quic true

Repair Configuration

`--repair-validator`

Limit repair requests to specific validators.

--repair-validator 7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2

`--gossip-validator`

Limit gossip to specific validators.

--gossip-validator 7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2

Miscellaneous

`--init-complete-file`

Create file when validator initialization completes.

--init-complete-file ~/validator-init-complete

`--skip-startup-ledger-verification`

Skip ledger verification at startup (faster but risky).

--skip-startup-ledger-verification

`--require-tower`

Refuse to start without saved tower state.

--require-tower

Harmonic-Specific Configuration

Block Engine

`--block-engine-url`

Connect to a block engine for optimized block production.

--block-engine-url https://block-engine.example.com:443

Relayer

`--relayer-url`

Connect to a relayer service.

--relayer-url https://relayer.example.com:443

Geyser Plugins

Plugin Configuration

`--geyser-plugin-config`

Load Geyser plugin configuration. Can be specified multiple times.

--geyser-plugin-config ~/plugin-config-1.json \
--geyser-plugin-config ~/plugin-config-2.json

`--geyser-plugin-always-enabled`

Enable Geyser interface even without plugin configs.

--geyser-plugin-always-enabled

Configuration File Format

You can use a configuration file instead of command-line arguments:

# validator.conf
identity=/home/sol/validator-keypair.json
vote-account=/home/sol/vote-account-keypair.json
ledger=/home/sol/validator-ledger
accounts=/mnt/nvme0/accounts
accounts=/mnt/nvme1/accounts

entrypoint=entrypoint.mainnet-beta.solana.com:8001
entrypoint=entrypoint2.mainnet-beta.solana.com:8001

known-validator=7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2
known-validator=GdnSyH3YtwcxFvQrVVJMm1JhTS4QVX7MFsX56uJLUfiZ

rpc-port=8899
private-rpc

limit-ledger-size=50000000
snapshot-interval-slots=500
full-snapshot-interval-slots=25000
maximum-full-snapshots-to-retain=5

log=/home/sol/validator.log

Load the configuration:

agave-validator --config ~/validator.conf

Best Practices

Separate Drives

Use separate NVMe drives for ledger, accounts, and snapshots for optimal I/O performance.

Limit Ledger Size

Always set --limit-ledger-size to prevent disk exhaustion.

Enable Snapshots

Generate snapshots regularly to enable faster recovery and help the network.

Monitor Resources

Use appropriate limits for QUIC connections based on your hardware capacity.

Next Steps

Operations

Learn about day-to-day operations

Monitoring

Set up comprehensive monitoring

Troubleshooting

Troubleshoot configuration issues

Get Started

Validator

CLI Tools

Architecture

​Validator Configuration

​Core Configuration

​Identity and Vote Account

​--identity (required)

​--vote-account

​--authorized-voter

​Ledger and Storage

​--ledger

​--accounts

​--account-shrink-path

​--snapshots

​--tower

​Network Configuration

​--entrypoint

​--known-validator

​--bind-address

​--gossip-port

​--dynamic-port-range

​--public-tpu-address

​--public-rpc-address

​RPC Configuration

​Basic RPC Settings

​--rpc-port

​--rpc-bind-address

​--private-rpc

​Advanced RPC Options

​--full-rpc-api

​--no-port-check

​Snapshot Configuration

​Snapshot Intervals

​--snapshot-interval-slots

​--full-snapshot-interval-slots

​Snapshot Retention

​--maximum-full-snapshots-to-retain

​--maximum-incremental-snapshots-to-retain

​Snapshot Archives

​--full-snapshot-archive-path

​--incremental-snapshot-archive-path

​--snapshot-archive-format

​--snapshot-version

​Snapshot Behavior

​--no-snapshots

​--maximum-local-snapshot-age

​--minimal-snapshot-download-speed

​Performance Tuning

​Accounts Database

​--accounts-db-cache-limit-mb

​--accounts-index-bins

​--enable-accounts-disk-index

​--accounts-index-path

​--accounts-shrink-ratio

​Ledger Limits

​--limit-ledger-size

​RocksDB Configuration

​--rocksdb-shred-compaction

​--rocksdb-ledger-compression

​TPU/QUIC Configuration

​--tpu-connection-pool-size

​--num-quic-endpoints

​--tpu-max-staked-connections

​--tpu-max-unstaked-connections

​Block Production and Verification

​--block-production-method

​--block-verification-method

​--unified-scheduler-handler-threads

​Account Indexing

​--account-index

​--account-index-exclude-key

​Logging

​Log Configuration

​--log

​Log Filtering

​Advanced Options

​Genesis and Fork Configuration

​--expected-genesis-hash

​--expected-shred-version

Validator Configuration

Core Configuration

Identity and Vote Account

`--identity` (required)

`--vote-account`

`--authorized-voter`

Ledger and Storage

`--ledger`

`--accounts`

`--account-shrink-path`

`--snapshots`

`--tower`

Network Configuration

`--entrypoint`

`--known-validator`

`--bind-address`

`--gossip-port`

`--dynamic-port-range`

`--public-tpu-address`

`--public-rpc-address`

RPC Configuration

Basic RPC Settings

`--rpc-port`

`--rpc-bind-address`

`--private-rpc`

Advanced RPC Options

`--full-rpc-api`

`--no-port-check`

Snapshot Configuration

Snapshot Intervals

`--snapshot-interval-slots`

`--full-snapshot-interval-slots`

Snapshot Retention

`--maximum-full-snapshots-to-retain`

`--maximum-incremental-snapshots-to-retain`

Snapshot Archives

`--full-snapshot-archive-path`

`--incremental-snapshot-archive-path`

`--snapshot-archive-format`

`--snapshot-version`

Snapshot Behavior

`--no-snapshots`

`--maximum-local-snapshot-age`

`--minimal-snapshot-download-speed`

Performance Tuning

Accounts Database

`--accounts-db-cache-limit-mb`

`--accounts-index-bins`

`--enable-accounts-disk-index`

`--accounts-index-path`

`--accounts-shrink-ratio`

Ledger Limits

`--limit-ledger-size`

RocksDB Configuration

`--rocksdb-shred-compaction`

`--rocksdb-ledger-compression`

TPU/QUIC Configuration

`--tpu-connection-pool-size`

`--num-quic-endpoints`

`--tpu-max-staked-connections`

`--tpu-max-unstaked-connections`

Block Production and Verification

`--block-production-method`

`--block-verification-method`

`--unified-scheduler-handler-threads`

Account Indexing

`--account-index`

`--account-index-exclude-key`

Logging

Log Configuration

`--log`

Log Filtering

Advanced Options

Genesis and Fork Configuration

`--expected-genesis-hash`

`--expected-shred-version`

`--wait-for-supermajority`

`--hard-fork`

Voting Configuration

`--no-voting`