Local Development

Quick Access

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

GitHub

Anchor Implementation

GitHub

Native Rust Implementation

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 (devnet-tee.magicblock.app): MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo

Localnet

Local ER (localhost:7799): mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev

Fully local
Surfpool
Devnet

Install the Ephemeral Validator CLI

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

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.

Deploy or upgrade your program on localhost

Rust Native
Anchor

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

anchor build && anchor deploy \
  --provider.cluster localnet

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

Run tests against the local rollup

The local rollup is exposed on http://localhost:7799 for RPC and ws://localhost:7800 for WebSocket connections.

Rust Native
Anchor

EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799 \
EPHEMERAL_WS_ENDPOINT=ws://localhost:7800 \
PROVIDER_ENDPOINT=http://localhost:8899 \
WS_ENDPOINT=ws://localhost:8900 \
yarn test

EPHEMERAL_PROVIDER_ENDPOINT="http://localhost:7799" \
EPHEMERAL_WS_ENDPOINT="ws://localhost:7800" \
anchor test \
  --provider.cluster localnet \
  --skip-local-validator \
  --skip-build \
  --skip-deploy

Install Surfpool

curl -sL https://run.surfpool.run/ | bash

Install the Ephemeral Validator CLI

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

Start Surfpool

This example keeps Surfpool local while using Solana Devnet as the upstream base layer:

surfpool start --rpc-url https://api.devnet.solana.com

Surfpool exposes the local RPC and WebSocket endpoints that the ephemeral validator connects to.

Start the ephemeral validator

Point the validator to Surfpool’s local RPC and WebSocket endpoints:

ephemeral-validator --remotes "http://localhost:8899" --remotes "ws://localhost:8900" -l "7799" --lifecycle ephemeral

Send a test transaction to the rollup

solana transfer <your address> 0 -u "http://localhost:7799"

Inspect the transaction

The transaction should appear in the ER TUI, where you can inspect it and open it in the explorer.This flow is based on Running Ephemeral Rollups locally with Surfpool.

Deploy or upgrade your program on Devnet

Upgrade your program with MagicBlock delegation and deploy it to Devnet:

Rust Native
Anchor

cargo build-sbf
solana config set --url devnet
solana program deploy YOUR_PROGRAM_PATH

anchor build && anchor deploy \
  --provider.cluster devnet

Install and run the local ephemeral validator

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

RUST_LOG=info ephemeral-validator \
  --lifecycle ephemeral \
  --remote-url "https://rpc.magicblock.app/devnet" \
  --rpc-port 7799

Run tests against the local rollup

Rust Native
Anchor

EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799 \
EPHEMERAL_WS_ENDPOINT=ws://localhost:7800 \
yarn test

EPHEMERAL_PROVIDER_ENDPOINT="http://localhost:7799" \
EPHEMERAL_WS_ENDPOINT="ws://localhost:7800" \
anchor test \
  --provider.cluster devnet \
  --skip-local-validator \
  --skip-build \
  --skip-deploy

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.

Install the latest Ephemeral Validator CLI

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

Start the local Solana validator

mb-test-validator --reset

Start the ephemeral validator

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

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.

How-to-Guide

Reference Material

ROUTER API

RPC API

Quick Access

GitHub

GitHub

Local Setup Options

Important: upgrade your program with the correct validator identity

Run the VRF Oracle Locally

​Quick Access

GitHub

GitHub

​Local Setup Options

​Important: upgrade your program with the correct validator identity

​Run the VRF Oracle Locally

Quick Access

Local Setup Options

Important: upgrade your program with the correct validator identity

Run the VRF Oracle Locally