Local Validator Setup

Run and test your Native Rust or Anchor programs with a fully local Ephemeral Rollup stack, Surfpool, or a local VRF oracle.

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

Fully local

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

   Rust Native

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

   Anchor

   anchor build && anchor deploy \
     --provider.cluster localnet
   
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.

   Rust Native

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

   Anchor

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

Surfpool

1. Install Surfpool

   curl -sL https://run.surfpool.run/ | bash
   
2. Install the Ephemeral Validator CLI

   npm install -g @magicblock-labs/ephemeral-validator@latest
   
3. 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.

4. 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
   
5. Send a test transaction to the rollup

   solana transfer <your address> 0 -u "http://localhost:7799"
   
6. 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.

Devnet

1. Deploy or upgrade your program on Devnet

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

   Rust Native

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

   Anchor

   anchor build && anchor deploy \
     --provider.cluster devnet
   
2. 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
   
3. Run tests against the local rollup

   Rust Native

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

   Anchor

   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.

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.