@effectstream/solana-node 0.102.0

package/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024-2026 Midnight Foundation
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Midnight Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @effectstream/solana-node
+
+NPM wrapper around [`solana-test-validator`](https://docs.anza.xyz/cli/examples/test-validator)
+from an [Agave](https://github.com/anza-xyz/agave) release - a single-node Solana
+cluster for local development. Downloads a pinned build into
+`vendor/bin/solana-test-validator` on first use so the orchestrator can boot it
+without each developer installing the Solana CLI.
+
+- Pinned Agave release, verified by SHA-256 before it is ever executed.
+- Exposes a `solana-node` bin plus a programmatic `run()`.
+- Consumed by `@effectstream/sync`'s `SolanaFetcher` via JSON-RPC on `:8899`.
+- Used by the orchestrator's `launchSolana` step for end-to-end local testing.
+- The same archive also provides `cargo-build-sbf`, which the `solana-starter`
+  template uses to compile its Rust program.
+
+## Install
+
+```bash
+bun add @effectstream/solana-node
+```
+
+The pinned archive is downloaded on first run (not at install time) for the
+current OS/arch.
+
+## Standalone usage
+
+```bash
+bun ./node_modules/.bin/solana-node            # boot the validator
+bun ./node_modules/.bin/solana-node --verbose  # stream validator output
+```
+
+Programmatically:
+
+```ts
+import { run } from "@effectstream/solana-node";
+
+const validator = await run({
+  rpcPort: 8899,
+  faucetPort: 9900,
+  reset: true,
+  // bindAddress: "127.0.0.1",
+  // dataDir: "/tmp/my-ledger",
+  // verbose: false,
+});
+
+// … use http://127.0.0.1:8899 …
+validator.stop();
+```
+
+On non-zero exit the wrapper prints the last 40 lines of the validator's output.
+That matters because the validator reports most startup failures on **stdout**,
+and deeper detail goes only to `<ledger>/validator.log`.
+
+## Integrity
+
+`bin-wrapper` has no checksum support and discards the archive after extracting,
+so this package hashes the **extracted binary** and refuses to run anything that
+isn't one of the pinned official builds. Set `SOLANA_NODE_SKIP_CHECKSUM=1` to
+bypass when deliberately testing a locally-built validator.
+
+Regenerate the digests whenever the pinned version changes:
+
+```bash
+shasum -a 256 packages/binaries/solana-node/vendor/bin/solana-test-validator
+```
+
+## Networking
+
+RPC and gossip bind `127.0.0.1` by default — the validator has no
+authentication, so exposing it broadly is a hazard on a shared network.
+Override with `SOLANA_BIND_ADDRESS` (or the `bindAddress` option) for container
+setups that need external reachability.
+
+The **faucet ignores this** and always listens on all interfaces; Agave offers no
+flag to restrict it, only the `--faucet-per-request-sol-cap` /
+`--faucet-per-time-sol-cap` rate limits. It hands out worthless localnet SOL, but
+don't run this on an untrusted network.
+
+## Platform support
+
+| Platform | Supported |
+| :--- | :---: |
+| linux x64 | ✅ |
+| darwin x64 | ✅ |
+| darwin arm64 | ✅ |
+| linux arm64 | ❌ |
+
+Upstream publishes no `aarch64-unknown-linux-gnu` build, so ARM64 Linux has no
+binary to download.
+
+## ⚠️ Version pin: do not bump past Agave 3.0.x
+
+Pinned to **3.0.14** deliberately. Agave ≥ 3.1 hard-asserts io_uring support on
+Linux and panics during init where it is unavailable:
+
+```
+[INFO agave_io_uring] io_uring NOT supported: Function not implemented (os error 38)
+thread 'main' panicked at fs/src/dirs.rs:27:9:
+assertion failed: io_uring_supported()
+```
+
+Docker's default seccomp profile blocks the io_uring syscalls, and the whole e2e
+suite runs containerized — so 3.1+ cannot start in CI as configured. macOS builds
+don't compile the assert in at all, which means a newer version looks fine
+locally and then fails in CI.
+
+Verified: `4.1.2` ✗ · `4.0.3` ✗ · `3.1.14` ✗ · `3.0.14` ✓ · `2.3.13` ✓
+
+This is a CI-configuration constraint, not an upstream dead end — on a kernel
+that supports io_uring the block is purely seccomp. See the note in `index.js`
+for the path to running a current release.

package/index.js

@@ -0,0 +1,249 @@
+import BinWrapper from '@xhmikosr/bin-wrapper';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Agave is the maintained continuation of solana-labs/solana; the old org
+// publishes nothing past 1.18.x, which is EOL.
+//
+// ⚠️ DO NOT BUMP PAST 3.0.x WITHOUT READING THIS.
+// Agave >= 3.1 hard-asserts io_uring support on Linux and panics during init
+// where it is unavailable:
+//
+//   [INFO agave_io_uring] io_uring NOT supported: Function not implemented (os error 38)
+//   thread 'main' panicked at fs/src/dirs.rs:27:9:
+//   assertion failed: io_uring_supported()
+//     3: solana_accounts_db::utils::create_accounts_run_and_snapshot_dirs
+//     4: solana_test_validator::TestValidator::start
+//
+// The entire e2e suite runs inside Docker (.github/Dockerfile), and Docker's
+// DEFAULT SECCOMP PROFILE blocks the io_uring syscalls, so 3.1+ cannot start in
+// CI as configured. macOS builds are unaffected (io_uring is Linux-only, so the
+// assert isn't compiled in) — which is exactly why 4.x passes every local check
+// and dies in CI.
+//
+// Verified: 4.1.2 ✗  4.0.3 ✗  3.1.14 ✗  3.0.14 ✓  2.3.13 ✓
+//
+// This pin is a CI-configuration constraint, NOT an upstream dead end. On a
+// kernel that supports io_uring, the block is purely seccomp:
+//   default profile      -> io_uring_setup errno=1  (EPERM)
+//   seccomp=unconfined   -> io_uring_setup OK
+// So 3.1+/4.x becomes viable by relaxing seccomp for the e2e container —
+// preferably a minimal custom profile allowing only io_uring_setup/enter/
+// register, rather than blanket `unconfined`. Docker dropped io_uring from its
+// default allowlist over a run of kernel LPE bugs, so that is a deliberate
+// trade-off to make explicitly, not a rubber stamp. See PR #815 discussion.
+// (Docker-on-Apple-Silicon is a separate matter: emulated amd64 has no io_uring
+// at all, and no seccomp setting helps there.)
+const version = '3.0.14';
+const base = `https://github.com/anza-xyz/agave/releases/download/v${version}`;
+const dest = path.join(__dirname, 'vendor');
+
+// NOTE: upstream ships NO aarch64-unknown-linux-gnu build — only the three
+// targets below (plus Windows, which this repo doesn't support). Adding a
+// linux/arm64 entry produces a 404 at download time, not a clean error.
+const bin = new BinWrapper()
+  .src(`${base}/solana-release-x86_64-unknown-linux-gnu.tar.bz2`, 'linux', 'x64')
+  .src(`${base}/solana-release-x86_64-apple-darwin.tar.bz2`, 'darwin', 'x64')
+  .src(`${base}/solana-release-aarch64-apple-darwin.tar.bz2`, 'darwin', 'arm64')
+  .dest(dest)
+  .use('bin/solana-test-validator');
+
+export default bin;
+
+/**
+ * SHA-256 of the extracted `solana-test-validator` in each published v3.0.14
+ * asset. bin-wrapper has no integrity support and discards the archive after
+ * extracting, so this verifies the binary we are about to execute rather than
+ * the tarball. Regenerate on every `version` bump with:
+ *
+ *   shasum -a 256 packages/binaries/solana-node/vendor/bin/solana-test-validator
+ *
+ * Deliberately matched as a SET rather than by `os.arch()`. Asset selection goes
+ * through bin-wrapper -> os-filter-obj -> arch, and the reported architecture
+ * has not always agreed with `os.arch()`: arch@2.x had no notion of arm64 at all
+ * (`darwin` was hardcoded to 'x64'), which is why every Mac used to download the
+ * x86_64 build and run it under Rosetta. The root `overrides` now force arch@3,
+ * so selection is correct today — but membership in the pinned set is immune to
+ * that class of mismatch (including deliberate emulation) while still proving
+ * the binary is one of the three official builds, which is the property that
+ * matters here.
+ */
+const CHECKSUMS = {
+  'linux-x64': '80f3bc0e3fa6a3090e69bafbfe00b249eaa655c5874ac83aebb6acdb157140ab',
+  'darwin-x64': '2a4a5ad21f7cd50021fa55948710ee2f3559d9cccf95f7a31094e45c27023b52',
+  'darwin-arm64': 'ab00c9a189341ef61402efce1a27713bb1b0ffb941715cea56ed5aa133992fe1',
+};
+
+/**
+ * Fail closed if the downloaded validator isn't one of the builds we pinned.
+ * Set SOLANA_NODE_SKIP_CHECKSUM=1 to bypass when intentionally testing a
+ * locally-built validator.
+ */
+function verifyChecksum(binaryPath) {
+  if (process.env.SOLANA_NODE_SKIP_CHECKSUM === '1') {
+    console.warn('[solana-node] checksum verification skipped (SOLANA_NODE_SKIP_CHECKSUM=1)');
+    return;
+  }
+  const actual = crypto
+    .createHash('sha256')
+    .update(fs.readFileSync(binaryPath))
+    .digest('hex');
+
+  const match = Object.entries(CHECKSUMS).find(([, digest]) => digest === actual);
+  if (!match) {
+    throw new Error(
+      `[solana-node] checksum mismatch for ${binaryPath}\n` +
+      `  got      ${actual}\n` +
+      `  expected one of:\n` +
+      Object.entries(CHECKSUMS)
+        .map(([platform, digest]) => `    ${digest}  (${platform})`)
+        .join('\n') +
+      `\nThis is not a pinned v${version} build. Refusing to run it.`,
+    );
+  }
+  return match[0];
+}
+
+export async function run(options = {}) {
+  const {
+    config,
+    dataDir,
+    verbose = false,
+    reset = true,
+    rpcPort = 8899,
+    faucetPort = 9900,
+    // The test validator has no authentication, so binding 0.0.0.0 exposed the
+    // RPC to the whole network. Default to loopback; override for container
+    // setups that genuinely need to reach it from outside.
+    //
+    // CAVEAT: this only covers the RPC and gossip/TPU. The FAUCET ignores
+    // --bind-address and always listens on 0.0.0.0 — there is no flag to
+    // change that in Agave 4.1.2 (only the --faucet-per-request-sol-cap /
+    // --faucet-per-time-sol-cap rate limits). It hands out worthless localnet
+    // SOL, but anyone on the LAN can still reach it, so don't run this on an
+    // untrusted network.
+    bindAddress = process.env.SOLANA_BIND_ADDRESS ?? '127.0.0.1',
+    // Programs to preload into the genesis ledger, as
+    // `[{ address, soPath }, …]` -> `--bpf-program <address> <soPath>`. Callers
+    // used to spawn the binary themselves to pass this, which duplicated all the
+    // ledger/reset handling below AND skipped the checksum verification above.
+    bpfPrograms = [],
+  } = options;
+
+  // Download (if needed) and verify BEFORE executing anything. `bin.run()`
+  // would execute the binary to check its version first, which defeats the
+  // point of verifying it.
+  if (!fs.existsSync(bin.path())) {
+    await bin.download();
+  }
+  const flavour = verifyChecksum(bin.path());
+  if (verbose) {
+    console.log(`[solana-node] verified solana-test-validator v${version} (${flavour})`);
+  }
+
+  const dataDirPath = dataDir || fs.mkdtempSync(path.join(os.tmpdir(), 'solana-test-validator-'));
+
+  if (!fs.existsSync(dataDirPath)) {
+    fs.mkdirSync(dataDirPath, { recursive: true });
+  }
+
+  const ledgerDir = path.join(dataDirPath, 'ledger');
+  if (!fs.existsSync(ledgerDir)) {
+    fs.mkdirSync(ledgerDir, { recursive: true });
+  }
+
+  const args = [
+    '--ledger', ledgerDir,
+    '--rpc-port', String(rpcPort),
+    '--faucet-port', String(faucetPort),
+    '--bind-address', bindAddress,
+  ];
+
+  for (const { address, soPath } of bpfPrograms) {
+    if (!address || !soPath) {
+      throw new Error(
+        `[solana-node] bpfPrograms entries need both 'address' and 'soPath'; got ${JSON.stringify({ address, soPath })}`,
+      );
+    }
+    if (!fs.existsSync(soPath)) {
+      throw new Error(
+        `[solana-node] program binary not found at ${soPath} (for ${address}). Build it before starting the validator.`,
+      );
+    }
+    args.push('--bpf-program', address, soPath);
+  }
+
+  if (reset) {
+    args.push('--reset');
+  }
+
+  // COPYFILE_DISABLE prevents macOS from materializing AppleDouble (`._`)
+  // companion files when the validator archives/unarchives genesis, which
+  // otherwise aborts ledger creation with
+  // "Archive error: extra entry found: ._genesis.bin". No-op on Linux.
+  const child = spawn(bin.path(), args, {
+    env: { ...process.env, COPYFILE_DISABLE: "1" },
+  });
+
+  // Keep a rolling tail of output even when quiet. The validator reports most
+  // startup failures on STDOUT, which used to be discarded unless `verbose` —
+  // so a failure surfaced as a bare "exited with code 1" with nothing to
+  // diagnose from, in CI least of all.
+  const TAIL_LINES = 40;
+  const tail = [];
+  const record = (stream) => (data) => {
+    const text = String(data);
+    if (verbose) {
+      const log = stream === 'stderr' ? console.error : console.log;
+      log(`solana-test-validator ${stream}: ${text}`);
+    }
+    for (const line of text.split('\n')) {
+      if (line.trim() === '') continue;
+      tail.push(`  [${stream}] ${line}`);
+      if (tail.length > TAIL_LINES) tail.shift();
+    }
+  };
+
+  child.stdout.on('data', record('stdout'));
+  child.stderr.on('data', record('stderr'));
+
+  child.on('close', (code) => {
+    if (code === 0) return;
+    console.error(
+      `solana-test-validator exited with code ${code}.` +
+      (verbose
+        ? ''
+        : ` Last output:\n${tail.length > 0 ? tail.join('\n') : '  (no output captured)'}`),
+    );
+  });
+
+  return {
+    child,
+    dataDir: dataDirPath,
+    ledgerDir,
+    rpcPort,
+    faucetPort,
+    stop: () => child.kill(),
+  };
+}
+
+if (import.meta.main) {
+  const cliArgs = process.argv.slice(2);
+  const verbose = cliArgs.includes("--verbose");
+
+  (async () => {
+    try {
+      console.log("Starting Solana test validator...");
+      await run({ verbose });
+    } catch (error) {
+      console.error("Failed to start Solana test validator:", error);
+      process.exit(1);
+    }
+  })();
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@effectstream/solana-node",
+  "version": "0.102.0",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "solana-node": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@xhmikosr/bin-wrapper": "^5.0.0"
+  },
+  "homepage": "https://effectstream.github.io/docs/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/effectstream/effectstream",
+    "directory": "packages/binaries/solana-node"
+  },
+  "bugs": {
+    "url": "https://github.com/effectstream/effectstream/issues"
+  },
+  "description": "Solana test validator binary wrapper for EffectStream"
+}