Running a Local Solana Validator Network

This is a beta version of the Solana Toolkit, and is still a WIP. Please post all feedback as a GitHub issue here.

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

Install the Solana Toolkit by running the following command:

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

If a ledger already exists in your working directory, you must reset the ledger to be able to clone a program or account.

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:

This must be done on a fresh ledger, so if a ledger already exists in your working directory you must add the --reset flag to reset to 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.