Running a Local Solana Validator Network

The Solana test validator is a local emulator for the Solana blockchain, designed to provide developers with a private and controlled environment for building and testing Solana programs without the need to connect to a public testnet or mainnet. It also includes full support of the standard Solana RPC standard.

If you have the Solana CLI tool suite already installed, you can run the test validator with the following command:

mucho validator --help

npx -y mucho@latest install

Advantages #

• Ability to reset the blockchain state at any moment
• Ability to simulate different network conditions
• No RPC rate-limits
• No airdrop limits
• Direct onchain program deployment
• Ability to clone accounts and programs from a public cluster (i.e. devnet, mainnet, etc)
• Ability to load accounts and programs from files
• Configurable transaction history retention
• Configurable epoch length

Starting the Test Validator #

To start your local validator, simply run:

mucho validator

This command initializes a new ledger and starts the local validator running at http://localhost:8899, which can be used as your Solana RPC connection url.

Connecting to the Test Validator #

To connect to the local test validator with the Solana CLI:

solana config set --url localhost

This will ensure all your Solana CLI commands will be directed to your local test validator.

Checking the Status of the Test Validator #

Before interacting with the test validator, it's useful to confirm its status and ensure it is running correctly.

solana ping

This command pings the local test validator and returns the current blockhash and latency, verifying that it is active.

Deploying and Managing Programs Locally #

To deploy a compiled program (BPF) to the test validator:

solana program deploy <PROGRAM_FILE_PATH>

This uploads and deploys a program to the blockchain.

To check the details of a deployed program:

solana program show <ACCOUNT_ADDRESS>

Sending Transactions #

To transfer SOL from one account to another:

solana transfer --from /path/to/keypair.json <RECIPIENT_ADDRESS> <AMOUNT>

This sends AMOUNT of SOL from the source account to the RECIPIENT_ADDRESS.

Simulating and Confirming Transactions #

Before actually sending a transaction, you can simulate it to see if it would likely succeed:

solana transfer --from /path/to/keypair.json \
  --simulate <RECIPIENT_ADDRESS> <AMOUNT>

To confirm the details and status of a transaction:

solana confirm <TRANSACTION_SIGNATURE>

Viewing Recent Block Production #

To see information about recent block production, which can be useful for debugging performance issues:

solana block-production

Validator Logs #

For debugging, you might want more detailed logs:

solana logs

This streams log messages from the validator.

Tips for Logging #

• Increase log verbosity with the -v flag if you need more detailed output for debugging.
• Use the --rpc-port and --rpc-bind-address options to customize the RPC server settings.
• Adjust the number of CPU cores used by the validator with the --gossip-host option to simulate network conditions more realistically.

Configuration #

View all the configuration options available for the Solana test validator:

mucho validator --help

Local Ledger #

By default, the ledger data is stored in a directory named test-ledger in your current working directory.

Specifying Ledger Location #

When starting the test validator, you can specify a different directory for the ledger data using the --ledger option:

mucho validator --ledger /path/to/custom/ledger

Resetting the Ledger #

By default the validator will resume an existing ledger, if one is found. To reset the ledger, you can either manually delete the ledger directory or restart the validator with the --reset flag:

mucho validator --reset

If the ledger exists, this command will reset the ledger to genesis, which resets the state by deleting all existing accounts/programs and starting fresh.

Cloning Programs #

To add existing onchain programs to your local environment, you can clone the program with a new ledger. This is useful for testing interactions with other programs that already exist on any other cluster.

To clone an account from another cluster:

mucho validator --reset \
  --url CLUSTER_PROGRAM_IS_DEPLOYED_TO \
  --clone PROGRAM_ADDRESS

To clone an upgradeable program and its executable data from another cluster:

mucho validator --reset \
  --url CLUSTER_PROGRAM_IS_DEPLOYED_TO \
  --clone-upgradeable-program PROGRAM_ADDRESS

Cloning Accounts #

To add existing onchain accounts to your local environment, you can clone the account with a new ledger from any other network cluster.

To clone an account from the cluster when a ledger already exists:

mucho validator --reset \
  --url CLUSTER_PROGRAM_IS_DEPLOYED_TO \
  --clone ACCOUNT_ADDRESS

Reset to Specific Account Data #

To reset the state of specific accounts every time you start the validator, you can use a combination of account snapshots and the --account flag.

First, save the desired state of an account as a JSON file:

solana account ACCOUNT_ADDRESS --output json --output-file account_state.json

Then load this state each time you reset the validator:

mucho validator --reset \
  --account ACCOUNT_ADDRESS account_state.json

Runtime Features #

Solana has a feature set mechanism that allows you to enable or disable certain blockchain features when running the test validator. By default, the test validator runs with all runtime features activated.

To see all the runtime features available and their statuses:

solana feature status

To query a specific runtime feature's status:

solana feature status <ADDRESS>

To deactivate specific features in genesis:

mucho validator --reset \
  --deactivate-feature <FEATURE_PUBKEY>

To deactivate multiple features in genesis:

mucho validator --reset \
  --deactivate-feature <FEATURE_PUBKEY_1> <FEATURE_PUBKEY_2>

Changing Versions #

To check your current solana-test-validator version:

mucho validator --version

Your test validator runs on the same version as the Solana CLI installed and configured for use.

To test your programs against different versions of the Solana runtime, you can install multiple versions of the Solana CLI and switch between them using the following command:

solana-install init <VERSION>

Make sure to reset your Solana test validator's ledger after changing versions to ensure it runs a valid ledger without corruption.