Solana Test Validator Guide
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. If you have the Solana CLI tool suite already installed, you can run the test validator with the following command:
solana-test-validator
Advantagesβ
- Ability to reset the blockchain state at any moment
- Ability to simulate different network conditions
- No RPC rate-limits
- No airdrop limits
- Direct on-chain program deployment
- Ability to clone accounts from a public cluster
- Ability to load accounts from files
- Configurable transaction history retention
- Configurable epoch length
Installationβ
Since the solana-test-validator
is part of the Solana CLI tool suite, ensure
you have Solana's command-line tools installed. You can install them using the
following command:
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
You can replace stable
with the release tag matching the software version of
your desired release (i.e. v1.18.12
), or use one of the three symbolic channel
names: stable
, beta
, or edge
.
For more detailed instructions, checkout this guide on setting up your local environment for Solana development. It includes installing the Solana CLI, Anchor, getting a local keypair, and more.
Starting the Test Validatorβ
To start your local validator, simply run:
solana-test-validator
This command initializes a new ledger and starts the validator.
Interacting with a Running Test Validatorβ
Once you have the solana-test-validator
up and running, you can interact with
it using various Solana CLI (Command Line Interface) commands. These commands
let you deploy programs, manage
accounts, send
transactions, and much more. Hereβs a detailed
guide on the key commands you will use.
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.
Account Managementβ
To create a new keypair (account), use:
solana-keygen new
This command creates a new keypair and saves it to the specified file.
To add SOL to your account:
solana airdrop 10 <ACCOUNT_ADDRESS>
To retrieve details about an account, such as its balance and owner:
solana account <ACCOUNT_ADDRESS>
You must first airdrop funds to the account for the account to exist.
This command sends 10 SOL to the specified account address.
Deploying and Managing Programsβ
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 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
Creating Token Accountsβ
Adjusting Logsβ
For debugging, you might want more detailed logs:
solana logs
This streams log messages from the validator.
Useful Tips 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β
Check CLI Tool Suite configuration:
solana genesis-hash
View all the configuration options available for the Solana test validator:
solana-test-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:
solana-test-validator --ledger /path/to/custom/ledger
Resetting the Ledgerβ
By default the validator will resume an existing ledger. To reset the ledger,
you can either manually delete the ledger directory or restart the validator
with the --reset
flag:
solana-test-validator --reset
If the ledger exists, this command will reset the ledger to genesis, which resets the state by deleting all existing data and starting fresh.
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 query the runtime feature status:
solana feature status <ADDRESS>
ADDRESS
is the feature status to query [default: all known features]
To activate a specific feature:
solana feature activate <FEATURE_KEYPAIR> <CLUSTER>
FEATURE_KEYPAIR
is the signer for the feature to activateCLUSTER
is the cluster to activate the feature on
To deactivate specific features in genesis:
solana-test-validator --deactivate-feature <FEATURE_PUBKEY> --reset
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.
Changing Versionsβ
To check your current solana-test-validator
version:
solana-test-validator --version
Your solana-test-validator
runs on the same version as the Solana CLI version.
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 solana-install set command:
solana-install init <VERSION>
VERSION
is the desired CLI version to install
Make sure to restart your Solana test validator after changing versions to ensure it runs the correct version.
Cloning Programsβ
To add existing onchain programs to your local environment, you can clone the program with a new ledger.
To clone an account from the cluster:
solana-test-validator --clone PROGRAM_ADDRESS --url CLUSTER_PROGRAM_IS_DEPLOYED_TO
This is useful for testing interactions with standard programs.
If a ledger already exists in your working directory, you must reset the ledger to be able to clone a program.
To clone an account from the cluster when a ledger already exists:
solana-test-validator --clone PROGRAM_ADDRESS --url CLUSTER_PROGRAM_IS_DEPLOYED_TO --reset
To clone an upgradeable program and its executable data from the cluster:
solana-test-validator --clone-upgradeable-program PROGRAM_ADDRESS --url CLUSTER_PROGRAM_IS_DEPLOYED_TO
Resetting State on Accounts at Startupβ
By default the validator will resume an existing ledger (if present). But during startup, you can reset the ledger either to genesis or to specific account state that you provide.
Reset to Genesisβ
To reset the ledger to the genesis state:
solana-test-validator --reset
Reset to Specific Accountsβ
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 PROGRAM_ADDRESS --output json > account_state.json
Then load this state each time you reset the validator:
solana-test-validator --reset --account PROGRAM_ADDRESS account_state.json
Solana CLI Commandsβ
To view all CLI commands and see other ways to interact with the test validator:
solana --help
This command list all flags, options, and subcommands available.
Example Use Caseβ
Create a USDC Token Account on your localnet
- Clone the USDC mint address to your local validator
solana-test-validator --clone EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --url mainnet-beta --reset
- Create a token account
spl-token create-account EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --url localhost