Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/magicblock-labs/magicblock-engine-examples/llms.txt

Use this file to discover all available pages before exploring further.

​
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

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"
.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

​
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

curl http://127.0.0.1:8899/health

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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us