Skip to main content

​
Why Use a Local Setup?

When testing delegations and real-time behavior of your Solana programs, fast feedback loops are critical. Running a Local Ephemeral Rollup Validator allows you to:
  • Test delegations and behaviors quickly without network latency or rate limits.
  • Simulate Solana runtime transactions locally.
  • Customize your validator setup for your own needs.

​
Quickstart: Local Ephemeral Validator

Explore delegation and test scripts for both Anchor and Native Rust:

Anchor

Integrate with an Anchor program

Native Rust

Integrate with a Native Rust program

​
Local Setup Options

You can run Ephemeral Rollups locally in three ways:
  • A fully local stack with mb-test-validator as the base layer and a local ephemeral-validator.
  • A local Surfpool instance as the base layer alternative, while still running the rollup locally.
  • A local ephemeral-validator connected directly to a public base layer such as Devnet.
Use the fully local path when you want everything on your machine. Use Surfpool when you want to keep the Surfpool workflow while testing against a local Ephemeral Rollup. Use the Devnet option when you want a local rollup process without running a local Solana validator.

​
Important: upgrade your program with the correct validator identity

When using a local ER validator, connect it to the base layer where the accounts are delegated. If you delegate your PDA to a specific ER validator identity, update the delegation config in your program so commits and undelegations can complete correctly on the base layer.

These public validators are supported for development. Make sure to add the specific ER validator in your delegation instruction:

Mainnet
  • Asia (as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
  • EU (eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
  • US (us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
  • TEE (mainnet-tee.magicblock.app): MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo
Devnet
  • Asia (devnet-as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
  • EU (devnet-eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
  • US (devnet-us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
  • TEE (tee.magicblock.app): FnE6VJT5QNZdedZPnCoLsARgBwoE6DeJNjBs2H1gySXA
Localnet
  • Local ER (localhost:7799): mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev
1

Install the Ephemeral Validator CLI

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

Start the local Solana base layer

mb-test-validator starts a local Solana validator you can use as the base layer for a fully local setup.
mb-test-validator --reset
This setup uses http://localhost:8899 for RPC and ws://localhost:8900 for WebSocket connections.
3

Deploy or upgrade your program on localhost

cargo build-sbf
solana config set --url localhost
solana program deploy YOUR_PROGRAM_PATH
4

Start the local ephemeral validator

Connect the local Ephemeral Rollup to the local Solana validator:
ephemeral-validator --remotes "http://localhost:8899" --remotes "ws://localhost:8900" -l "7799" --lifecycle ephemeral
5

Run tests against the local rollup

The local rollup is exposed on http://localhost:7799 for RPC and ws://localhost:7800 for WebSocket connections.
EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799 \
EPHEMERAL_WS_ENDPOINT=ws://localhost:7800 \
PROVIDER_ENDPOINT=http://localhost:8899 \
WS_ENDPOINT=ws://localhost:8900 \
yarn test

​
Run the VRF Oracle Locally

If you also need to test VRF end to end, run a local vrf-oracle against a local test queue.
1

Install the latest Ephemeral Validator CLI

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

Start the local Solana validator

mb-test-validator --reset
3

Start the ephemeral validator

ephemeral-validator --remote-url "http://localhost:8899" --rpc-port 7799 --lifecycle ephemeral
4

Start the local VRF oracle

This oracle adds requests to the local test queue:
VRF_ORACLE_SKIP_PREFLIGHT="true" RPC_URL="http://localhost:8899" WEBSOCKET_URL="ws://localhost:8999" RUST_LOG=info vrf-oracle
If your local validator exposes a different WebSocket port, update WEBSOCKET_URL accordingly.