Local Development

Quick Access

Explore private program and test scripts for Anchor, Native Rust, and Pinocchio:

Anchor Private Counter

Anchor implementation with permissions.

Pinocchio Private Counter

Pinocchio implementation with magic permission accounts.

Why a Local PER Setup Is Different

In production a Private Ephemeral Rollup runs the Ephemeral Rollup inside a Trusted Execution Environment (TEE) on Intel TDX. Clients don’t reach the ER directly — they connect through a token-gated TEE endpoint that enforces privacy and compliance (IP geofencing, OFAC screening, and per-account permission filtering) at ingress, before any transaction is accepted or executed. You can’t run real TDX hardware locally. Instead, the TEE ingress is emulated by a dedicated process — the Query Filtering Service (QFS) — which replicates the same token-auth and permission-filtering logic without hardware attestation, and fronts an ordinary local ephemeral validator. That is the only structural difference from a plain Ephemeral Rollup local setup: you run the QFS in front of the ER and point your client at the QFS instead of the ER directly.

Topology

Four processes, each fronting the next:

Process	RPC / WS	Role
`mb-test-validator`	8899 / 8900	Base layer. Wraps `solana-test-validator` and pre-clones the MagicBlock delegation + permission programs.
`ephemeral-validator`	7799 / 7800	The Ephemeral Rollup itself.
`query-filtering-service`	6699 / 6700	PER-specific. Emulates the TEE ingress — token auth + permission filtering.
`vrf-oracle` (optional)	—	Only needed if the program under test uses VRF.

Point your client at the QFS (6699) to test privacy features. Point it at the ER (7799) directly when you don’t need the privacy layer.

Quickstart with mb-stack

mb-stack is a single CLI that wraps mb-test-validator, ephemeral-validator, and query-filtering-service, and handles the startup ordering between them for you, in a single command. It ships in the same package as ephemeral-validator.

Install

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

Bring up the full stack

mb-stack --reset

This starts mb-test-validator (8899 / 8900), ephemeral-validator (7799 / 7800), and query-filtering-service (6699 / 6700) together, on the same default ports used throughout this guide.

Deploy your program

Once the stack is up, deploy against the base layer as usual:

Anchor
Native / Pinocchio

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

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

Per-Service Setup

Install the binaries

mb-stack, ephemeral-validator, query-filtering-service, and mb-test-validator ship together:

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

Start the base validator (port 8899)

mb-test-validator --reset

Deploy or preload your program

Anchor
Native / Pinocchio
Preload at startup

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

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

Alternatively, inject the program when the base validator boots so it is on-chain at its declared address from slot 0:

mb-test-validator --reset \
  --upgradeable-program <program-keypair.json> <program.so> <upgrade-authority-pubkey>

Start the ephemeral validator (port 7799)

ephemeral-validator \
  --lifecycle ephemeral \
  --remotes http://127.0.0.1:8899 \
  --remotes ws://127.0.0.1:8900 \
  --listen 127.0.0.1:7799 \
  --reset

Start the Query Filtering Service (port 6699)

This is the process that makes it a private rollup. It points upstream at the ER and exposes the client-facing endpoint:

RUST_LOG=info query-filtering-service \
  --listen-addr 127.0.0.1:6699 \
  --listen-addr-ws 127.0.0.1:6700 \
  --ephemeral-url http://127.0.0.1:7799 \
  --ephemeral-url-ws ws://127.0.0.1:7800 \
  --token-expiry-days 180 \
  --add-cors-headers

--add-cors-headers is required if you test from a browser app. Wait for port 6699 to accept a connection before firing any request.

(Optional) Start the VRF oracle

If your program requests randomness, run one oracle against the base layer and one against the ER:

# Base-layer VRF requests
VRF_ORACLE_SKIP_PREFLIGHT=true RPC_URL=http://localhost:8899 \
  WEBSOCKET_URL=ws://localhost:8900 RUST_LOG=info vrf-oracle &

# ER VRF requests
VRF_ORACLE_SKIP_PREFLIGHT=true RPC_URL=http://localhost:7799 \
  WEBSOCKET_URL=ws://localhost:7800 RUST_LOG=info vrf-oracle &

Connect Your Client Through the QFS

Your client treats the QFS endpoint as the TEE endpoint: point TEE_PROVIDER_ENDPOINT at http://localhost:6699 and reuse the same authorization flow from the quickstart — fetch a token by signing a challenge, then open the connection with ?token=... attached. When a PDA is set to private via its EphemeralPermission, the QFS blocks any wallet not in the member list — exactly as the TEE would on devnet.

import { getAuthToken } from "@magicblock-labs/ephemeral-rollups-sdk";
import nacl from "tweetnacl";

// Locally, TEE_PROVIDER_ENDPOINT = http://localhost:6699 (the QFS).
const teeUrl =
  process.env.TEE_PROVIDER_ENDPOINT || "https://devnet-tee.magicblock.app";
const teeWsUrl =
  process.env.TEE_WS_ENDPOINT || "wss://devnet-tee.magicblock.app";

const token = await getAuthToken(
  teeUrl,
  payer.publicKey,
  (message: Uint8Array) =>
    Promise.resolve(nacl.sign.detached(message, payer.secretKey)),
);

const erProvider = new anchor.AnchorProvider(
  new anchor.web3.Connection(`${teeUrl}?token=${token.token}`, {
    wsEndpoint: `${teeWsUrl}?token=${token.token}`,
    commitment: "confirmed",
  }),
  anchor.Wallet.local(),
);

verifyTeeRpcIntegrity checks a real TDX attestation and is meant for the devnet/mainnet TEE endpoints. The local QFS has no hardware attestation, so skip that check when running fully local.

Delegate to the Local Validator Identity

When delegating your PDA in a local test, delegate to the localnet ER identity — not a devnet/mainnet one — so commits and undelegations settle correctly:

mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev

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

Endpoint Environment Variables

Centralize the endpoints so tests hit the local cluster instead of silently falling back to devnet. The PER-relevant variables:

export PROVIDER_ENDPOINT=http://localhost:8899            # base layer
export WS_ENDPOINT=ws://localhost:8900
export EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799  # ER direct
export EPHEMERAL_WS_ENDPOINT=ws://localhost:7800
export QFS_ENDPOINT=http://localhost:6699                 # QFS
export QFS_WS_ENDPOINT=ws://localhost:6700
export TEE_PROVIDER_ENDPOINT=$QFS_ENDPOINT                # private tests read this
export TEE_WS_ENDPOINT=$QFS_WS_ENDPOINT
export VALIDATOR=mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev

How-to-Guide

Reference Material

Private Payments API

Quick Access

Anchor Private Counter

Pinocchio Private Counter

Why a Local PER Setup Is Different

Topology

Quickstart with mb-stack

Per-Service Setup

Connect Your Client Through the QFS

Delegate to the Local Validator Identity

Endpoint Environment Variables

​Quick Access

Anchor Private Counter

Pinocchio Private Counter

​Why a Local PER Setup Is Different

​Topology

​Quickstart with mb-stack

​Per-Service Setup

​Connect Your Client Through the QFS

​Delegate to the Local Validator Identity

​Endpoint Environment Variables

Quick Access

Why a Local PER Setup Is Different

Topology

Quickstart with mb-stack

Per-Service Setup

Connect Your Client Through the QFS

Delegate to the Local Validator Identity

Endpoint Environment Variables