feat: add cli command to run the solana-test-validator with ER setup (#567)

<!-- greptile_comment -->

<h2>Greptile Overview</h2>

Updated On: 2025-10-09 15:30:44 UTC

<h3>Summary</h3>
This PR adds a new CLI command `mb-test-validator` that provides a
convenient way to run `solana-test-validator` with MagicBlock's
Ephemeral Rollup (ER) setup. The implementation includes several key
components:

**Core Functionality**: The PR introduces `mbTestValidator.ts`, which
wraps `solana-test-validator` with predefined BPF programs and accounts
necessary for MagicBlock's ER infrastructure. This eliminates the need
for users to manually specify numerous `--bpf-program` and `--account`
flags when setting up a local test environment.

**Code Refactoring**: The existing `ephemeralValidator.ts` was
refactored to extract process management logic into a reusable
`runWithForwardedExit` function. This promotes code reuse between the
ephemeral validator and the new test validator implementations,
following DRY principles while maintaining consistent process handling.

**Build Integration**: The package.json was updated to include the new
`mb-test-validator` binary and modified the build script to
automatically fetch required program binaries and account dumps from
MagicBlock's devnet RPC during compilation.

**Asset Management**: A new bash script `fetch-local-dumps.sh` was added
to handle downloading of Solana program binaries (.so files) and account
data (.json files) from MagicBlock's devnet, ensuring the test validator
has access to the correct program and account states for local
development.

This change integrates well with the existing codebase by following
established patterns from `ephemeralValidator.ts` and maintaining
consistency in CLI tool implementation. The solution addresses the
practical need for developers to quickly spin up a properly configured
test validator without manual setup of MagicBlock-specific
infrastructure components.
<h3>Important Files Changed</h3>

<details>
<summary>Changed Files</summary>

| Filename | Score | Overview |
|----------|-------|----------|
| .github/packages/npm-package/ephemeralValidator.ts | 5/5 | Refactored
to extract reusable process management logic into `runWithForwardedExit`
function |
| .github/packages/npm-package/mbTestValidator.ts | 2/5 | New CLI tool
for running solana-test-validator with ER setup, but contains duplicate
program entries and potential process handling issues |
| .github/packages/npm-package/package.json | 4/5 | Added new CLI binary
and build script modification to fetch local dumps during compilation |
| .github/packages/npm-package/scripts/fetch-local-dumps.sh | 4/5 | New
script to fetch program binaries and account data from MagicBlock devnet
with proper error handling |

</details>
<h3>Confidence score: 3/5</h3>

- This PR requires careful review due to several implementation issues
that could cause runtime problems
- Score reflects concerns about duplicate program entries, process exit
handling logic, and missing error handling in critical paths
- Pay close attention to mbTestValidator.ts which contains the most
problematic code patterns

<h3>Sequence Diagram</h3>

```mermaid
sequenceDiagram
    participant User
    participant "npm/yarn"
    participant mbTestValidator.ts
    participant "fetch-local-dumps.sh"
    participant "Solana CLI"
    participant "MagicBlock RPC"
    participant "solana-test-validator"
    participant "Local Filesystem"

    User->>npm/yarn: "npm run build" or "yarn build"
    npm/yarn->>mbTestValidator.ts: "tsc" (compile TypeScript)
    npm/yarn->>fetch-local-dumps.sh: "bash scripts/fetch-local-dumps.sh"
    
    fetch-local-dumps.sh->>Local Filesystem: "mkdir -p local-dumps"
    
    loop For each account
        fetch-local-dumps.sh->>Solana CLI: "solana account <pubkey> --output json --url <RPC_URL>"
        Solana CLI->>MagicBlock RPC: "GET account data"
        MagicBlock RPC-->>Solana CLI: "Account JSON data"
        Solana CLI-->>fetch-local-dumps.sh: "Account data"
        fetch-local-dumps.sh->>Local Filesystem: "Write <pubkey>.json"
    end
    
    loop For each program
        fetch-local-dumps.sh->>Solana CLI: "solana program dump <pubkey> <output.so> --url <RPC_URL>"
        Solana CLI->>MagicBlock RPC: "GET program binary"
        MagicBlock RPC-->>Solana CLI: "Program .so binary"
        Solana CLI-->>fetch-local-dumps.sh: "Program binary"
        fetch-local-dumps.sh->>Local Filesystem: "Write <pubkey>.so"
    end
    
    User->>npm/yarn: "mb-test-validator [args]"
    npm/yarn->>mbTestValidator.ts: "Execute mb-test-validator command"
    mbTestValidator.ts->>Local Filesystem: "Check for required .so and .json files"
    Local Filesystem-->>mbTestValidator.ts: "File existence status"
    
    alt Missing files
        mbTestValidator.ts->>User: "Warning: missing local dumps files"
    end
    
    mbTestValidator.ts->>solana-test-validator: "spawn with --bpf-program and --account flags"
    
    loop Process lifecycle management
        solana-test-validator->>mbTestValidator.ts: "Process events (exit, signals)"
        mbTestValidator.ts->>User: "Forward exit codes and signals"
    end
    
    User->>mbTestValidator.ts: "SIGINT (Ctrl+C)"
    mbTestValidator.ts->>solana-test-validator: "Kill SIGINT/SIGTERM"
```

<!-- greptile_other_comments_section -->

<!-- /greptile_comment -->

Author: GabrielePicco

.github/packages/npm-package/ephemeralValidator.ts

@@ -33,10 +33,8 @@ function getExePath(): string {
   }
 }
 
-function runEphemeralValidator(location: string): void {
-  const args = process.argv.slice(2);
-  const ephemeralValidator = spawn(location, args, { stdio: "inherit" });
-  ephemeralValidator.on("exit", (code: number | null, signal: NodeJS.Signals | null) => {
+function runWithForwardedExit(child: ReturnType<typeof spawn>): void {
+  child.on("exit", (code: number | null, signal: NodeJS.Signals | null) => {
     process.on("exit", () => {
       if (signal) {
         process.kill(process.pid, signal);
@@ -47,11 +45,17 @@ function runEphemeralValidator(location: string): void {
   });
 
   process.on("SIGINT", () => {
-    ephemeralValidator.kill("SIGINT");
-    ephemeralValidator.kill("SIGTERM");
+    child.kill("SIGINT");
+    child.kill("SIGTERM");
   });
 }
 
+function runEphemeralValidator(location: string): void {
+  const args = process.argv.slice(2);
+  const ephemeralValidator = spawn(location, args, { stdio: "inherit" });
+  runWithForwardedExit(ephemeralValidator);
+}
+
 function tryPackageEphemeralValidator(): boolean {
   try {
     const path = getExePath();
@@ -101,4 +105,6 @@ function trySystemEphemeralValidator(): void {
 
   runEphemeralValidator(absoluteBinaryPath);
 }
+
+// If the first argument is our special command, run the test validator and exit.
 tryPackageEphemeralValidator() || trySystemEphemeralValidator();

.github/packages/npm-package/mbTestValidator.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawn } from "child_process";
+import * as path from "path";
+import * as fs from "fs";
+
+function runWithForwardedExit(child: ReturnType<typeof spawn>): void {
+  child.on("exit", (code: number | null, signal: NodeJS.Signals | null) => {
+    process.on("exit", () => {
+      if (signal) {
+        process.kill(process.pid, signal);
+      } else if (code !== null) {
+        process.exit(code);
+      }
+    });
+  });
+
+  process.on("SIGINT", () => {
+    child.kill("SIGINT");
+    child.kill("SIGTERM");
+  });
+}
+
+function dumpsDir(): string {
+  // Compiled js lives in lib/, source in package root. We want <package-root>/bin/local-dumps
+  const libDir = __dirname;
+  const root = path.resolve(libDir, "..");
+  return path.join(root, "ephemeral-validator", "bin", "local-dumps");
+}
+
+function runMbTestValidator(): void {
+  const exe = "solana-test-validator";
+  const dumps = dumpsDir();
+  const p = (name: string) => path.join(dumps, name);
+
+  const args = [
+    // programs
+    "--bpf-program",
+    "DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh",
+    p("DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh.so"),
+    "--bpf-program",
+    "noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV",
+    p("noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV.so"),
+    "--bpf-program",
+    "Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz",
+    p("Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz.so"),
+    "--bpf-program",
+    "noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV",
+    p("noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV.so"),
+    // accounts
+    "--account",
+    "mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev",
+    p("mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev.json"),
+    "--account",
+    "EpJnX7ueXk7fKojBymqmVuCuwyhDQsYcLVL1XMsBbvDX",
+    p("EpJnX7ueXk7fKojBymqmVuCuwyhDQsYcLVL1XMsBbvDX.json"),
+    "--account",
+    "7JrkjmZPprHwtuvtuGTXp9hwfGYFAQLnLeFM52kqAgXg",
+    p("7JrkjmZPprHwtuvtuGTXp9hwfGYFAQLnLeFM52kqAgXg.json"),
+    "--account",
+    "Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh",
+    p("Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh.json"),
+    "--account",
+    "5hBR571xnXppuCPveTrctfTU7tJLSN94nq7kv7FRK5Tc",
+    p("5hBR571xnXppuCPveTrctfTU7tJLSN94nq7kv7FRK5Tc.json"),
+    "--account",
+    "F72HqCR8nwYsVyeVd38pgKkjXmXFzVAM8rjZZsXWbdE",
+    p("F72HqCR8nwYsVyeVd38pgKkjXmXFzVAM8rjZZsXWbdE.json"),
+  ];
+
+  const expectedFiles = [
+    "DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh.so",
+    "noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV.so",
+    "Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz.so",
+    "mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev.json",
+    "EpJnX7ueXk7fKojBymqmVuCuwyhDQsYcLVL1XMsBbvDX.json",
+    "7JrkjmZPprHwtuvtuGTXp9hwfGYFAQLnLeFM52kqAgXg.json",
+    "Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh.json",
+    "5hBR571xnXppuCPveTrctfTU7tJLSN94nq7kv7FRK5Tc.json",
+    "F72HqCR8nwYsVyeVd38pgKkjXmXFzVAM8rjZZsXWbdE.json",
+  ];
+  const missingFiles = expectedFiles
+    .map((f) => p(f))
+    .filter((full) => !fs.existsSync(full));
+  if (missingFiles.length > 0) {
+    console.warn("Warning: missing local dumps files:\n" + missingFiles.join("\n"));
+  }
+
+  const extraArgs = process.argv.slice(2);
+  const child = spawn(exe, [...args, ...extraArgs], { stdio: "inherit" });
+  runWithForwardedExit(child);
+}
+
+runMbTestValidator();

.github/packages/npm-package/package.json

@@ -12,13 +12,14 @@
   },
   "license": "Business Source License 1.1",
   "bin": {
-    "ephemeral-validator": "ephemeralValidator.js"
+    "ephemeral-validator": "ephemeralValidator.js",
+    "mb-test-validator": "mbTestValidator.js"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "lint": "prettier */*.js \"*/**/*{.js,.ts}\" --check ",
     "lint:fix": "node_modules/.bin/prettier */*.js \"*/**/*{.js,.ts}\" -w",
-    "build": "tsc",
+    "build": "tsc && bash scripts/fetch-local-dumps.sh",
     "dev": "yarn build && node lib/index.js"
   },
   "devDependencies": {

.github/packages/npm-package/scripts/fetch-local-dumps.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# This script fetches program .so binaries and account .json files into
+# <package-root>/bin/local-dumps, to be used by mb-test-validator.
+# It mirrors the list from the issue description and defaults to MagicBlock devnet RPC.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PKG_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DUMPS_DIR="$PKG_ROOT/lib/bin/local-dumps"
+RPC_URL="${SOLANA_RPC_URL:-https://rpc.magicblock.app/devnet}"
+
+mkdir -p "$DUMPS_DIR"
+
+# Dump accounts
+accounts=(
+  mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev
+  EpJnX7ueXk7fKojBymqmVuCuwyhDQsYcLVL1XMsBbvDX
+  7JrkjmZPprHwtuvtuGTXp9hwfGYFAQLnLeFM52kqAgXg
+  Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh
+  5hBR571xnXppuCPveTrctfTU7tJLSN94nq7kv7FRK5Tc
+  F72HqCR8nwYsVyeVd38pgKkjXmXFzVAM8rjZZsXWbdE
+)
+
+for acc in "${accounts[@]}"; do
+  out="$DUMPS_DIR/$acc.json"
+  echo "Dumping account $acc -> $out"
+  if ! solana account "$acc" --output json --url "$RPC_URL" > "$out"; then
+    echo "Warning: failed to dump account $acc" >&2
+  fi
+done
+
+# Dump programs
+programs=(
+  DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh
+  noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV
+  Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz
+)
+
+for prog in "${programs[@]}"; do
+  out="$DUMPS_DIR/$prog.so"
+  echo "Dumping program $prog -> $out"
+  if ! solana program dump "$prog" "$out" --url "$RPC_URL"; then
+    echo "Warning: failed to dump program $prog" >&2
+  fi
+done
+
+echo "local-dumps directory: $DUMPS_DIR"