Setup a Local Validator

Overview

A Local Validator acts as your personal node, providing a local sandbox environment for testing applications without the need to connect to a live blockchain network. It operates a fully customizable local test ledger, which is a simplified version of the Solana ledger, equipped with all native programs pre-installed and various features enabled.

Setup

To start using the local validator, you'll need to install the Solana Tools CLI using the appropriate commands for your operating system.

sh -c "$(curl -sSfL https://release.solana.com/v1.18.18/install)"

Note: The installation script references the 1.18.18 version of Solana. To install the latest version or discover different installation methods, refer to the official Solana documentation.

Usage

After installing the CLI, you can start your local validator by running a simple command.

solana-test-validator

Upon launch, the validator will be accessible at a local URL(http://127.0.0.1:8899). You'll need to establish a connection by configuring your code with this URL.

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

const umi = createUmi("http://127.0.0.1:8899")

The local validator will generate a directory named test-ledger in your user folder. This directory holds all data related to your validator, including accounts and programs.

To reset your local validator, you can either delete the test-ledger folder or use a reset command to restart the validator.

Additionally, the solana-logs feature is extremely useful for monitoring program outputs during testing.

Managing Programs and Accounts

The Local Validator doesn’t include specific programs and accounts found on mainnet. It only comes with Native Programs and the accounts you create during testing. If you need specific programs or accounts from mainnet, the Solana CLI allows you to download and load them onto your local validator.

Downloading Accounts and Programs:

You can easily download accounts or programs from a source cluster to your local validator for testing purposes. This allows you to replicate the mainnet environment.

For accounts:

solana account -u <source cluster> --output <output format> --output-file <destination file name/path> <address of account to fetch>

For Programs:

solana program dump -u <source cluster> <address of account to fetch> <destination file name/path>

Loading Accounts and Programs:

Once downloaded, these accounts and programs can be loaded into your local validator using the CLI. You can run commands to load specific accounts and programs into your local environment, ensuring they are ready for testing.

For accounts:

solana-test-validator --account <address to load the account to> <path to account file> --reset

For programs

solana-test-validator --bpf-program <address to load the program to> <path to program file> --reset

Looking at Local transaction on Explorers

Using a local validator doesn't prevent us from using the explorer since many explorers have the capability to connect to our local port and read the local ledger stored in the test-ledger folder we mentioned earlier.

There are two ways to do this:

• Create a link to the transaction signature that points to the local cluster of your favorite explorer.
• Manually change the cluster on the webpage and then paste the transaction link.

Creating a link to the transaction signature

When you send a transaction with Umi, you'll receive two key pieces of information: a signature and a result. The signature is in base58 format, so you'll need to deserialize it to make it readable for the blockchain.

You can do this with the following code:

const signature = base58.deserialize(transaction.signature)[0]

Once you have the signature, you can use it with your preferred explorer like this:

Manually changing the Cluster

As mentioned earlier, block explorers allow users to utilize a custom RPC to view transactions. To look at local validator transaction you'll need to look for an input box in the choose cluster modal and enter the following address: http://127.0.0.1:8899.

Note: The Solana Explorer automatically defaults to the local validator port when you select Custom RPC URL, so you don’t need to make any additional changes.

Creating a "Metaplex" Local Validator

With the basics of the local validator setup and management, you can create and manage personalized local validators through bash scripts.

For example, you can create a metaplex-test-validator that includes the main Metaplex programs: mpl-token-metadata, mpl-bubblegum, and mpl-core.

Setting Up Directories and Downloading Program Data

First, you'll create a directory within your path to store the necessary programs for your local validator.

mkdir ~/.local/share/metaplex-local-validator

Then, download the program data from specified addresses into this directory.

solana program dump -u m metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s ~/.local/share/metaplex-local-validator/mpl-token-metadata.so

solana program dump -u m BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY ~/.local/share/metaplex-local-validator/mpl-bubblegum.so

solana program dump -u m CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d ~/.local/share/metaplex-local-validator/mpl-core.so

Creating a Validator Script

Next, create a validator script that simplifies the process of running your local validator with all the required programs. By scripting the validator setup, you can easily start testing with your personalized environment, including all relevant Metaplex programs.

Start by opening a new script file using:

sudo nano /usr/local/bin/metaplex-local-validator

Note: If the /user/local/bin directory doesn’t exist, you can create it using sudo mkdir -p -m 775 /usr/local/bin.

Paste in the following code into the editor and save it:

#!/bin/bash

# Validator command
COMMAND="solana-test-validator -r --bpf-program metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s ~/.local/share/metaplex-local-validator/mpl-token-metadata.so --bpf-program BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY ~/.local/share/metaplex-local-validator/mpl-bubblegum.so --bpf-program CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d ~/.local/share/metaplex-local-validator/mpl-core.so"

# Append any additional arguments passed to the script
for arg in "$@"
do
    COMMAND+=" $arg"
done

# Execute the command
eval $COMMAND

Note: To exit and save, use Ctrl + X, then Y to confirm, and Enter to save.

Once your script is ready, modify its permissions so it can be executed:

sudo chmod +x /usr/local/bin/metaplex-test-validator

Finally, test your new validator within your project folder:

metaplex-test-validator