Local Development Setup

Set up a local Ephemeral Rollup validator for development and testing

Overview

Running a local Ephemeral Rollup validator allows you to develop and test your programs without relying on remote endpoints. This guide covers installing the validator, configuring your environment, and running tests locally.

For comprehensive local development guidance, see the MagicBlock Local Development Guide.

Prerequisites

Before setting up your local environment, ensure you have:

• Node.js v24.10.0 or later
• Solana CLI v2.3.13 or later
• Anchor Framework v0.32.1 or later
• Rust v1.85.0 or later

Installation

1. Install the Ephemeral Validator

   Install the @magicblock-labs/ephemeral-validator package globally:

   npm install -g @magicblock-labs/ephemeral-validator
   

   Verify the installation:

   ephemeral-validator --version
   
2. Install mb-test-validator

   The mb-test-validator is a wrapper around Solana’s test validator that pre-configures required accounts for MagicBlock.

   npm install -g @magicblock-labs/solana-test-validator
   

   The test scripts in the examples use mb-test-validator which clones necessary MagicBlock program accounts automatically.

3. Configure Solana CLI

   Set your Solana CLI to use localhost:

   solana config set --url localhost
   

   Create a keypair if you don’t have one:

   solana-keygen new --no-bip39-passphrase --outfile ~/.config/solana/id.json
   

Starting Local Validators

Starting mb-test-validator

The mb-test-validator runs on port 8899 and provides the base layer:

mb-test-validator --reset

This command:

• Resets the ledger state
• Clones required MagicBlock program accounts from devnet
• Starts listening on http://localhost:8899

Logs are written to /tmp/mb-test-validator.log when using the automated test scripts.

Starting ephemeral-validator

The ephemeral validator runs on port 7799 and connects to your local base layer:

RUST_LOG=info ephemeral-validator \
  --remotes "http://127.0.0.1:8899" \
  --remotes "ws://127.0.0.1:8900" \
  -l "127.0.0.1:7799" \
  --reset

Local Development

RUST_LOG=info ephemeral-validator \
  --remotes "http://127.0.0.1:8899" \
  --remotes "ws://127.0.0.1:8900" \
  -l "127.0.0.1:7799" \
  --reset

The ephemeral validator:

• Listens on http://localhost:7799 (RPC)
• Provides WebSocket on ws://localhost:7800
• Connects to the base layer at http://127.0.0.1:8899

Environment Variables

Configure your environment for local testing:

export EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799
export EPHEMERAL_WS_ENDPOINT=ws://localhost:7800
export ANCHOR_PROVIDER_URL=http://127.0.0.1:8899
export ANCHOR_WALLET="${HOME}/.config/solana/id.json"

Localnet

.env

EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799
EPHEMERAL_WS_ENDPOINT=ws://localhost:7800
PROVIDER_ENDPOINT=http://localhost:8899
WS_ENDPOINT=ws://localhost:8900
ANCHOR_PROVIDER_URL=http://127.0.0.1:8899
ANCHOR_WALLET=~/.config/solana/id.json

Devnet

.env

EPHEMERAL_PROVIDER_ENDPOINT=https://devnet-as.magicblock.app/
EPHEMERAL_WS_ENDPOINT=wss://devnet-as.magicblock.app/
PROVIDER_ENDPOINT=https://api.devnet.solana.com
ANCHOR_PROVIDER_URL=https://api.devnet.solana.com
ANCHOR_WALLET=~/.config/solana/id.json

Anchor.toml Configuration

Configure your Anchor.toml to support multiple clusters:

Anchor.toml

[toolchain]
anchor_version = "0.32.1"

[programs.localnet]
your_program = "YourProgramID111111111111111111111111111"

[programs.devnet]
your_program = "YourProgramID111111111111111111111111111"

[provider]
cluster = "localnet"  # Change to "devnet" for devnet testing
wallet = "~/.config/solana/id.json"

[scripts]
test = "./fullstack-test.sh"

The fullstack-test.sh script automatically detects the cluster from Anchor.toml and configures validators accordingly.

Automated Local Testing

The examples include a fullstack-test.sh script that automates the entire local testing process:

1. Script automatically starts validators

   The script checks if validators are already running on ports 8899 and 7799. If not, it starts them:

   # Auto-detected from Anchor.toml
   anchor test
   
2. Builds and deploys programs

   anchor build
   anchor deploy --provider.cluster localnet
   
3. Runs tests with proper configuration

   yarn ts-mocha --colors -p ./tsconfig.json -t 1000000 --exit tests/**/*.ts \
     --provider.cluster localnet \
     --skip-local-validator \
     --skip-build \
     --skip-deploy
   
4. Cleans up after tests

   The script automatically stops validators and cleans up test ledgers when tests complete.

Manual Testing Workflow

For manual control over the testing process:

1. Start validators in separate terminals

   Terminal 1 - Base Layer:

   mb-test-validator --reset
   

   Terminal 2 - Ephemeral Rollup:

   RUST_LOG=info ephemeral-validator \
     --remotes "http://127.0.0.1:8899" \
     --remotes "ws://127.0.0.1:8900" \
     -l "127.0.0.1:7799" \
     --reset
   
2. Set environment variables

   export EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799
   export EPHEMERAL_WS_ENDPOINT=ws://localhost:7800
   export PROVIDER_ENDPOINT=http://localhost:8899
   export WS_ENDPOINT=ws://localhost:8900
   
3. Build and deploy

   anchor build
   anchor deploy --provider.cluster localnet
   
4. Run tests

   anchor test --skip-local-validator --skip-build --skip-deploy
   

Using —skip-local-validator

When you have validators already running, use the --skip-local-validator flag to avoid starting new instances:

anchor test --skip-local-validator --skip-build --skip-deploy

This is useful when:

• You want to keep validators running between test runs
• You’re manually managing validator lifecycles
• You’re debugging and need to inspect validator logs

Make sure validators are actually running before using --skip-local-validator, or tests will fail with connection errors.

Airdropping SOL

For local testing, airdrop SOL to your wallet:

solana airdrop 100 --url http://localhost:8899

The automated test script does this automatically:

solana airdrop 100 $(solana address) --url http://127.0.0.1:8899

Checking Validator Health

Base Layer (8899)

curl http://127.0.0.1:8899/health

solana cluster-version --url http://localhost:8899

Ephemeral Rollup (7799)

curl http://127.0.0.1:7799/health

Troubleshooting

Validators won’t start

Check if ports are already in use:

lsof -i :8899
lsof -i :7799

Kill existing processes:

pkill -f "solana-test-validator"
pkill -f "mb-test-validator"
pkill -f "ephemeral-validator"

Clean ledger state

rm -rf test-ledger test-ledger-magicblock magicblock-test-storage

Check logs

View validator logs:

tail -f /tmp/mb-test-validator.log
tail -f /tmp/ephemeral-validator.log

Next Steps

• Learn about Testing Patterns
• Explore Troubleshooting Common Issues
• Try running the Anchor Counter Example