@provablehq/veil-aleo-devnode 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Provable Inc.
+
+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,90 @@
+# @provablehq/veil-aleo-devnode
+
+Runs and drives a local Aleo development node from TypeScript. Reach for it in
+tests, CI, and local development when you need a real node to broadcast against
+without touching testnet — start one, mine blocks on demand, and tear it down.
+
+The node is seeded with a well-known genesis account (`DEVNODE_PRIVATE_KEY`)
+that holds credits, so you have a funded key to pay fees from the moment it
+boots.
+
+## Installation
+
+```sh
+pnpm add @provablehq/veil-aleo-devnode @provablehq/veil-core
+```
+
+`@provablehq/veil-aleo-devnode` drives the `aleo-devnode` binary as a subprocess — it does not
+bundle a node. The binary MUST be installed and resolvable on `PATH` (override
+its location per call with `devnodePath`). Every function throws with an
+install-and-PATH hint if it cannot find or run the binary.
+
+## Usage
+
+`startDevnode` spawns the node and resolves once its REST API answers, so the
+returned instance is ready to receive transactions. Call `stop` to terminate it
+(SIGTERM); starting again on the same socket shuts down any node already there
+first.
+
+```ts
+import { startDevnode, advanceDevnode, DEVNODE_ADDR } from '@provablehq/veil-aleo-devnode'
+
+const devnode = await startDevnode({
+  socketAddr: DEVNODE_ADDR, // '127.0.0.1:3030'
+  storagePath: '',          // '' → default ./devnode dir; omit for in-memory
+})
+
+// ... broadcast transactions against http://127.0.0.1:3030 ...
+
+await advanceDevnode({ numBlocks: 1 }) // mine a block so a broadcast finalizes
+
+await devnode.stop()
+```
+
+`advanceDevnode` mines blocks on a running node — pair it with
+`manualBlockCreation` on `startDevnode` when you want deterministic block
+timing instead of automatic creation. `restoreDevnode` reloads ledger state
+from a named snapshot, optionally restarting the node afterward.
+
+Taking a snapshot is a live REST call against the running node, not a binary
+subcommand, so it lives on the `@provablehq/veil-core` test client as `snapshot` (with
+`listSnapshots` to enumerate them) rather than in this package. Capture state
+with `client.snapshot(...)` and reload it here with `restoreDevnode` — the node
+must have been started with `storagePath`, since an in-memory node has nothing
+to snapshot.
+
+### As test-client actions
+
+`devnodeActions` folds the process-lifecycle functions onto a `@provablehq/veil-core` test
+client via `.extend`, so a single client drives the node (start/advance/restore)
+and, through the core test actions, snapshots it.
+
+```ts
+import { createTestClient, http } from '@provablehq/veil-core'
+import { devnodeActions } from '@provablehq/veil-aleo-devnode'
+
+const client = createTestClient({
+  transport: http('http://127.0.0.1:3030', { network: 'testnet' }),
+}).extend(devnodeActions)
+
+const devnode = await client.startDevnode({ storagePath: '' })
+await client.advanceDevnode({ numBlocks: 1 })
+const { name } = await client.snapshot({ name: 'before-deploy' }) // core test action
+// ...run something you may want to undo...
+await client.restoreDevnode({ snapshot: name, restart: true })
+await devnode.stop()
+```
+
+## Exports
+
+- `startDevnode(options?)` — spawn a node; resolves to a `DevnodeInstance` once
+  the REST API is ready.
+- `advanceDevnode(options?)` — mine one or more blocks on a running node.
+- `restoreDevnode(options)` — restore ledger state from a snapshot.
+- `devnodeActions` — `.extend` decorator that adds the above to a client.
+- `DEVNODE_PRIVATE_KEY` — the seeded, funded genesis account key.
+- `DEVNODE_ADDR` — the default socket address, `127.0.0.1:3030`.
+
+See the JSDoc on `DevnodeStartOptions`, `DevnodeAdvanceOptions`, and
+`DevnodeRestoreOptions` for every flag, its default, and the CLI switch it maps
+to.

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+import { Client } from '@provablehq/veil-core';
+
+/** The well-known seeded private key used by Aleo Devnode */
+declare const DEVNODE_PRIVATE_KEY = "APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH";
+/** Default local devnode socket address */
+declare const DEVNODE_ADDR = "127.0.0.1:3030";
+/**
+ * Options for {@link startDevnode}.
+ *
+ * Most fields map to flags of the `aleo-devnode start` subcommand.
+ */
+type DevnodeStartOptions = {
+    /** Private key for block creation. Defaults to `DEVNODE_PRIVATE_KEY`. */
+    privateKey?: string;
+    /** `-a, --socket-addr`. REST API bind address. Defaults to `DEVNODE_ADDR`. */
+    socketAddr?: string;
+    /** `-v, --verbosity` (0–2). Defaults to 2. */
+    verbosity?: 0 | 1 | 2;
+    /** `-g, --genesis-path`. Path to a custom genesis block file. */
+    genesisPath?: string;
+    /**
+     * `-s, --storage [DIR]`. Directory for persistent ledger storage.
+     * - Omit for in-memory (ephemeral).
+     * - Pass an empty string to use the default "./devnode" directory.
+     * - Pass a path string for a custom directory.
+     */
+    storagePath?: string;
+    /** `-c, --clear-storage`. Clear the storage directory before starting. Requires `storagePath`. */
+    clearStorage?: boolean;
+    /** `-m, --manual-block-creation`. Disable automatic block creation after broadcast. */
+    manualBlockCreation?: boolean;
+    /** Milliseconds to wait for the REST API to become ready. Defaults to 30000. */
+    readyTimeout?: number;
+    /** Path to the aleo-devnode binary. Defaults to `'aleo-devnode'` (resolved on PATH). */
+    devnodePath?: string;
+    /** Write devnode stdout/stderr to devnode-<port>.log in the current directory. Defaults to false. */
+    verbose?: boolean;
+};
+/**
+ * Options for {@link advanceDevnode}.
+ *
+ * Fields map to the `aleo-devnode advance` subcommand.
+ */
+type DevnodeAdvanceOptions = {
+    /** Number of blocks to advance. Defaults to 1. */
+    numBlocks?: number;
+    /** `--socket-addr`. Target devnode socket. Defaults to `DEVNODE_ADDR`. */
+    socketAddr?: string;
+    /** Path to the aleo-devnode binary. Defaults to `'aleo-devnode'` (resolved on PATH). */
+    devnodePath?: string;
+};
+/**
+ * Options for {@link restoreDevnode}.
+ *
+ * Fields map to flags of the `aleo-devnode restore` subcommand. Restoring
+ * requires persistent storage, so the snapshot must have been taken from a
+ * devnode started with `storagePath`.
+ */
+type DevnodeRestoreOptions = {
+    /** `--snapshot`. Name of the snapshot to restore. Required. */
+    snapshot: string;
+    /** `--storage`. Ledger storage directory to restore into. Defaults to `'devnode'`. */
+    storage?: string;
+    /** `--restart`. Restart the devnode after restoring. */
+    restart?: boolean;
+    /** `--private-key`. Required when `restart` is true (or set via `$PRIVATE_KEY`). */
+    privateKey?: string;
+    /** `-a, --socket-addr`. Forwarded to `start` when `restart` is true. */
+    socketAddr?: string;
+    /** `-v, --verbosity`. Forwarded to `start` when `restart` is true. */
+    verbosity?: 0 | 1 | 2;
+    /** `-m, --manual-block-creation`. Forwarded to `start` when `restart` is true. */
+    manualBlockCreation?: boolean;
+    /** Path to the aleo-devnode binary. Defaults to `'aleo-devnode'` (resolved on PATH). */
+    devnodePath?: string;
+};
+/**
+ * Handle to a running devnode process returned by {@link startDevnode}.
+ *
+ * Hold on to it for the lifetime of the node and call `stop()` when done —
+ * the child process is not stopped automatically when the parent exits.
+ */
+type DevnodeInstance = {
+    /** Socket address the devnode is listening on. */
+    socketAddr: string;
+    /** Terminates the devnode process gracefully (SIGTERM). */
+    stop: () => Promise<void>;
+};
+/**
+ * Starts a local Aleo devnode and waits until its REST API answers.
+ *
+ * Spawns the `aleo-devnode` binary as a child process, so it MUST be
+ * installed and on PATH (or located via `devnodePath`). If a devnode is
+ * already listening on the target socket, it is asked to shut down first so
+ * the new instance can bind. Resolves once the node serves block height, or
+ * rejects after `readyTimeout`.
+ *
+ * By default the node binds `127.0.0.1:3030`, keeps its ledger in memory
+ * (lost on stop), creates blocks automatically, and produces blocks with the
+ * well-known seeded key {@link DEVNODE_PRIVATE_KEY}.
+ *
+ * @param options Overrides for the defaults above; omit for an ephemeral
+ *   node on port 3030.
+ * @returns A {@link DevnodeInstance} — keep it and call `stop()` to terminate
+ *   the process.
+ * @throws If the binary is missing, the process exits during startup, or the
+ *   REST API is not ready within `readyTimeout` (default 30000 ms).
+ *
+ * @example
+ * import { startDevnode } from '@provablehq/veil-aleo-devnode'
+ *
+ * const devnode = await startDevnode()
+ * // ...run tests against http://127.0.0.1:3030...
+ * await devnode.stop()
+ */
+declare function startDevnode(options?: DevnodeStartOptions): Promise<DevnodeInstance>;
+/**
+ * Advances a running devnode by one or more empty blocks.
+ *
+ * Spawns `aleo-devnode advance` as a child process (requires the binary on
+ * PATH) and resolves when it exits. Use it to move the chain forward when the
+ * node runs with `manualBlockCreation`, or when a test needs height to pass.
+ *
+ * @param options.numBlocks Blocks to produce. Defaults to 1.
+ * @param options.socketAddr Devnode to target. Defaults to `127.0.0.1:3030`.
+ * @throws If the binary is missing or no devnode answers on the socket.
+ */
+declare function advanceDevnode(options?: DevnodeAdvanceOptions): Promise<void>;
+/**
+ * Restores a devnode ledger from a named snapshot.
+ *
+ * Spawns `aleo-devnode restore` as a child process (requires the binary on
+ * PATH). With `restart: true` the devnode is relaunched on the restored
+ * ledger; otherwise only the storage directory is rewritten and the caller
+ * starts the node separately.
+ *
+ * @param options Snapshot name, target storage directory, and optional
+ *   restart parameters.
+ * @throws If the binary is missing, the snapshot does not exist, or the
+ *   command exits non-zero.
+ */
+declare function restoreDevnode(options: DevnodeRestoreOptions): Promise<void>;
+/**
+ * Devnode management actions added to a test client by {@link devnodeActions}.
+ *
+ * Each action delegates to the standalone function of the same name and
+ * spawns the `aleo-devnode` binary.
+ *
+ * @property startDevnode Starts a devnode; see {@link startDevnode}.
+ * @property advanceDevnode Produces blocks on a running devnode; see {@link advanceDevnode}.
+ * @property restoreDevnode Restores a ledger snapshot; see {@link restoreDevnode}.
+ */
+type DevnodeClientActions = {
+    startDevnode: (options?: DevnodeStartOptions) => Promise<DevnodeInstance>;
+    advanceDevnode: (options?: DevnodeAdvanceOptions) => Promise<void>;
+    restoreDevnode: (options: DevnodeRestoreOptions) => Promise<void>;
+};
+/**
+ * Adds devnode management actions to a test client via `.extend`.
+ *
+ * @example
+ * ```ts
+ * import { createTestClient, http } from '@provablehq/veil-core'
+ * import { devnodeActions } from '@provablehq/veil-aleo-devnode'
+ *
+ * const client = createTestClient({ transport: http('http://127.0.0.1:3030', { network: 'testnet' }) })
+ *   .extend(devnodeActions)
+ *
+ * const devnode = await client.startDevnode()
+ * await client.advanceDevnode({ numBlocks: 1 })
+ * await devnode.stop()
+ * ```
+ */
+declare function devnodeActions(_client: Client): DevnodeClientActions;
+
+export { DEVNODE_ADDR, DEVNODE_PRIVATE_KEY, type DevnodeAdvanceOptions, type DevnodeClientActions, type DevnodeInstance, type DevnodeRestoreOptions, type DevnodeStartOptions, advanceDevnode, devnodeActions, restoreDevnode, startDevnode };

package/dist/index.js

@@ -0,0 +1,170 @@
+// src/index.ts
+import { spawn } from "child_process";
+import { createWriteStream } from "fs";
+import { join } from "path";
+var DEVNODE_PRIVATE_KEY = "APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH";
+var DEVNODE_ADDR = "127.0.0.1:3030";
+var HEALTH_CHECK_PATH = "/testnet/block/height/latest";
+var HEALTH_CHECK_INTERVAL_MS = 250;
+var HEALTH_CHECK_REQUEST_TIMEOUT_MS = 1e3;
+async function startDevnode(options) {
+  const privateKey = options?.privateKey ?? DEVNODE_PRIVATE_KEY;
+  const socketAddr = options?.socketAddr ?? DEVNODE_ADDR;
+  const verbosity = options?.verbosity ?? 2;
+  const readyTimeout = options?.readyTimeout ?? 3e4;
+  const devnodePath = options?.devnodePath ?? "aleo-devnode";
+  const verbose = options?.verbose ?? false;
+  await tryShutdownExisting(socketAddr);
+  const args = [
+    "start",
+    "--private-key",
+    privateKey,
+    "--socket-addr",
+    socketAddr,
+    "--verbosity",
+    String(verbosity)
+  ];
+  if (options?.genesisPath !== void 0) args.push("--genesis-path", options.genesisPath);
+  if (options?.storagePath !== void 0) {
+    args.push(options.storagePath === "" ? "--storage" : `--storage=${options.storagePath}`);
+  }
+  if (options?.clearStorage) args.push("--clear-storage");
+  if (options?.manualBlockCreation) args.push("--manual-block-creation");
+  return spawnDevnode(devnodePath, args, socketAddr, readyTimeout, verbose);
+}
+async function advanceDevnode(options) {
+  const devnodePath = options?.devnodePath ?? "aleo-devnode";
+  const args = ["advance"];
+  if (options?.numBlocks !== void 0) args.push(String(options.numBlocks));
+  if (options?.socketAddr) args.push("--socket-addr", options.socketAddr);
+  await runDevnode(devnodePath, args);
+}
+async function restoreDevnode(options) {
+  const devnodePath = options.devnodePath ?? "aleo-devnode";
+  const args = ["restore", "--snapshot", options.snapshot];
+  if (options.storage) args.push("--storage", options.storage);
+  if (options.restart) {
+    args.push("--restart");
+    if (options.privateKey) args.push("--private-key", options.privateKey);
+    if (options.socketAddr) args.push("--socket-addr", options.socketAddr);
+    if (options.verbosity !== void 0) args.push("--verbosity", String(options.verbosity));
+    if (options.manualBlockCreation) args.push("--manual-block-creation");
+  }
+  await runDevnode(devnodePath, args);
+}
+async function tryShutdownExisting(socketAddr) {
+  const baseUrl = `http://${socketAddr}`;
+  try {
+    const res = await fetch(`${baseUrl}/testnet/shutdown`, {
+      method: "POST",
+      signal: AbortSignal.timeout(2e3)
+    });
+    if (!res.ok) return;
+    const deadline = Date.now() + 5e3;
+    while (Date.now() < deadline) {
+      try {
+        await fetch(`${baseUrl}${HEALTH_CHECK_PATH}`, { signal: AbortSignal.timeout(500) });
+        await new Promise((r) => setTimeout(r, 200));
+      } catch {
+        return;
+      }
+    }
+  } catch {
+  }
+}
+function runDevnode(devnodePath, args) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(devnodePath, args, { stdio: "inherit" });
+    proc.on(
+      "error",
+      (err) => reject(
+        new Error(
+          `Failed to run ${devnodePath}: ${err.message}. Ensure aleo-devnode is installed and on PATH.`
+        )
+      )
+    );
+    proc.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${devnodePath} ${args[0]} exited with code ${code}`));
+    });
+  });
+}
+async function spawnDevnode(devnodePath, args, socketAddr, readyTimeout, verbose = false) {
+  const proc = spawn(devnodePath, args, {
+    stdio: "pipe",
+    // MUST mirror DEVNODE_CONSENSUS_HEIGHTS in @provablehq/veil-aleo-sdk so the
+    // transaction builder and the node agree on active consensus versions.
+    env: { ...process.env, CONSENSUS_VERSION_HEIGHTS: process.env.CONSENSUS_VERSION_HEIGHTS || "0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16" }
+  });
+  if (verbose) {
+    const port = socketAddr.split(":")[1] ?? socketAddr.replace(/\./g, "-");
+    const logFile = join(process.cwd(), `devnode-${port}.log`);
+    const logStream = createWriteStream(logFile, { flags: "w" });
+    proc.stdout?.pipe(logStream);
+    proc.stderr?.pipe(logStream);
+    console.log(`[devnode] logs \u2192 ${logFile}`);
+  } else {
+    proc.stdout?.resume();
+    proc.stderr?.resume();
+  }
+  let startError;
+  proc.on("error", (err) => {
+    startError = new Error(
+      `Failed to start ${devnodePath}: ${err.message}. Ensure aleo-devnode is installed and on PATH.`
+    );
+  });
+  proc.on("exit", (code, signal) => {
+    if (signal === "SIGTERM" || signal === "SIGINT") return;
+    if (code !== 0 && code !== null) {
+      startError = startError ?? new Error(`${devnodePath} exited unexpectedly with code ${code}`);
+    }
+  });
+  try {
+    await waitForReady(`http://${socketAddr}`, readyTimeout, () => startError);
+  } catch (err) {
+    proc.kill("SIGTERM");
+    throw err;
+  }
+  return {
+    socketAddr,
+    stop: () => new Promise((resolve) => {
+      proc.kill("SIGTERM");
+      proc.once("exit", () => resolve());
+    })
+  };
+}
+function devnodeActions(_client) {
+  return {
+    startDevnode: (options) => startDevnode(options),
+    advanceDevnode: (options) => advanceDevnode(options),
+    restoreDevnode: (options) => restoreDevnode(options)
+  };
+}
+async function waitForReady(baseUrl, timeout, getError) {
+  const deadline = Date.now() + timeout;
+  const healthUrl = `${baseUrl}${HEALTH_CHECK_PATH}`;
+  while (Date.now() < deadline) {
+    const err = getError();
+    if (err) throw err;
+    try {
+      const response = await fetch(healthUrl, {
+        signal: AbortSignal.timeout(HEALTH_CHECK_REQUEST_TIMEOUT_MS)
+      });
+      if (response.ok) return;
+    } catch {
+    }
+    await new Promise((resolve) => setTimeout(resolve, HEALTH_CHECK_INTERVAL_MS));
+  }
+  throw new Error(
+    `Devnode at ${baseUrl} did not become ready within ${timeout}ms. Try increasing readyTimeout or check that aleo-devnode is installed and working.`
+  );
+}
+export {
+  DEVNODE_ADDR,
+  DEVNODE_PRIVATE_KEY,
+  advanceDevnode,
+  devnodeActions,
+  restoreDevnode,
+  startDevnode
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { spawn } from 'node:child_process'\nimport { createWriteStream } from 'node:fs'\nimport { join } from 'node:path'\nimport type { Client } from '@provablehq/veil-core'\n\n/** The well-known seeded private key used by Aleo Devnode */\nexport const DEVNODE_PRIVATE_KEY = 'APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH'\n\n/** Default local devnode socket address */\nexport const DEVNODE_ADDR = '127.0.0.1:3030'\n\nconst HEALTH_CHECK_PATH = '/testnet/block/height/latest'\nconst HEALTH_CHECK_INTERVAL_MS = 250\nconst HEALTH_CHECK_REQUEST_TIMEOUT_MS = 1_000\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Options for {@link startDevnode}.\n *\n * Most fields map to flags of the `aleo-devnode start` subcommand.\n */\nexport type DevnodeStartOptions = {\n  /** Private key for block creation. Defaults to `DEVNODE_PRIVATE_KEY`. */\n  privateKey?: string\n  /** `-a, --socket-addr`. REST API bind address. Defaults to `DEVNODE_ADDR`. */\n  socketAddr?: string\n  /** `-v, --verbosity` (0–2). Defaults to 2. */\n  verbosity?: 0 | 1 | 2\n  /** `-g, --genesis-path`. Path to a custom genesis block file. */\n  genesisPath?: string\n  /**\n   * `-s, --storage [DIR]`. Directory for persistent ledger storage.\n   * - Omit for in-memory (ephemeral).\n   * - Pass an empty string to use the default \"./devnode\" directory.\n   * - Pass a path string for a custom directory.\n   */\n  storagePath?: string\n  /** `-c, --clear-storage`. Clear the storage directory before starting. Requires `storagePath`. */\n  clearStorage?: boolean\n  /** `-m, --manual-block-creation`. Disable automatic block creation after broadcast. */\n  manualBlockCreation?: boolean\n  /** Milliseconds to wait for the REST API to become ready. Defaults to 30000. */\n  readyTimeout?: number\n  /** Path to the aleo-devnode binary. Defaults to `'aleo-devnode'` (resolved on PATH). */\n  devnodePath?: string\n  /** Write devnode stdout/stderr to devnode-<port>.log in the current directory. Defaults to false. */\n  verbose?: boolean\n}\n\n/**\n * Options for {@link advanceDevnode}.\n *\n * Fields map to the `aleo-devnode advance` subcommand.\n */\nexport type DevnodeAdvanceOptions = {\n  /** Number of blocks to advance. Defaults to 1. */\n  numBlocks?: number\n  /** `--socket-addr`. Target devnode socket. Defaults to `DEVNODE_ADDR`. */\n  socketAddr?: string\n  /** Path to the aleo-devnode binary. Defaults to `'aleo-devnode'` (resolved on PATH). */\n  devnodePath?: string\n}\n\n/**\n * Options for {@link restoreDevnode}.\n *\n * Fields map to flags of the `aleo-devnode restore` subcommand. Restoring\n * requires persistent storage, so the snapshot must have been taken from a\n * devnode started with `storagePath`.\n */\nexport type DevnodeRestoreOptions = {\n  /** `--snapshot`. Name of the snapshot to restore. Required. */\n  snapshot: string\n  /** `--storage`. Ledger storage directory to restore into. Defaults to `'devnode'`. */\n  storage?: string\n  /** `--restart`. Restart the devnode after restoring. */\n  restart?: boolean\n  /** `--private-key`. Required when `restart` is true (or set via `$PRIVATE_KEY`). */\n  privateKey?: string\n  /** `-a, --socket-addr`. Forwarded to `start` when `restart` is true. */\n  socketAddr?: string\n  /** `-v, --verbosity`. Forwarded to `start` when `restart` is true. */\n  verbosity?: 0 | 1 | 2\n  /** `-m, --manual-block-creation`. Forwarded to `start` when `restart` is true. */\n  manualBlockCreation?: boolean\n  /** Path to the aleo-devnode binary. Defaults to `'aleo-devnode'` (resolved on PATH). */\n  devnodePath?: string\n}\n\n/**\n * Handle to a running devnode process returned by {@link startDevnode}.\n *\n * Hold on to it for the lifetime of the node and call `stop()` when done —\n * the child process is not stopped automatically when the parent exits.\n */\nexport type DevnodeInstance = {\n  /** Socket address the devnode is listening on. */\n  socketAddr: string\n  /** Terminates the devnode process gracefully (SIGTERM). */\n  stop: () => Promise<void>\n}\n\n// =============================================================================\n// Public API\n// =============================================================================\n\n/**\n * Starts a local Aleo devnode and waits until its REST API answers.\n *\n * Spawns the `aleo-devnode` binary as a child process, so it MUST be\n * installed and on PATH (or located via `devnodePath`). If a devnode is\n * already listening on the target socket, it is asked to shut down first so\n * the new instance can bind. Resolves once the node serves block height, or\n * rejects after `readyTimeout`.\n *\n * By default the node binds `127.0.0.1:3030`, keeps its ledger in memory\n * (lost on stop), creates blocks automatically, and produces blocks with the\n * well-known seeded key {@link DEVNODE_PRIVATE_KEY}.\n *\n * @param options Overrides for the defaults above; omit for an ephemeral\n *   node on port 3030.\n * @returns A {@link DevnodeInstance} — keep it and call `stop()` to terminate\n *   the process.\n * @throws If the binary is missing, the process exits during startup, or the\n *   REST API is not ready within `readyTimeout` (default 30000 ms).\n *\n * @example\n * import { startDevnode } from '@provablehq/veil-aleo-devnode'\n *\n * const devnode = await startDevnode()\n * // ...run tests against http://127.0.0.1:3030...\n * await devnode.stop()\n */\nexport async function startDevnode(options?: DevnodeStartOptions): Promise<DevnodeInstance> {\n  const privateKey = options?.privateKey ?? DEVNODE_PRIVATE_KEY\n  const socketAddr = options?.socketAddr ?? DEVNODE_ADDR\n  const verbosity = options?.verbosity ?? 2\n  const readyTimeout = options?.readyTimeout ?? 30_000\n  const devnodePath = options?.devnodePath ?? 'aleo-devnode'\n  const verbose = options?.verbose ?? false\n\n  await tryShutdownExisting(socketAddr)\n\n  const args = [\n    'start',\n    '--private-key', privateKey,\n    '--socket-addr', socketAddr,\n    '--verbosity', String(verbosity),\n  ]\n\n  if (options?.genesisPath !== undefined) args.push('--genesis-path', options.genesisPath)\n  if (options?.storagePath !== undefined) {\n    args.push(options.storagePath === '' ? '--storage' : `--storage=${options.storagePath}`)\n  }\n  if (options?.clearStorage) args.push('--clear-storage')\n  if (options?.manualBlockCreation) args.push('--manual-block-creation')\n\n  return spawnDevnode(devnodePath, args, socketAddr, readyTimeout, verbose)\n}\n\n/**\n * Advances a running devnode by one or more empty blocks.\n *\n * Spawns `aleo-devnode advance` as a child process (requires the binary on\n * PATH) and resolves when it exits. Use it to move the chain forward when the\n * node runs with `manualBlockCreation`, or when a test needs height to pass.\n *\n * @param options.numBlocks Blocks to produce. Defaults to 1.\n * @param options.socketAddr Devnode to target. Defaults to `127.0.0.1:3030`.\n * @throws If the binary is missing or no devnode answers on the socket.\n */\nexport async function advanceDevnode(options?: DevnodeAdvanceOptions): Promise<void> {\n  const devnodePath = options?.devnodePath ?? 'aleo-devnode'\n  const args = ['advance']\n  if (options?.numBlocks !== undefined) args.push(String(options.numBlocks))\n  if (options?.socketAddr) args.push('--socket-addr', options.socketAddr)\n  await runDevnode(devnodePath, args)\n}\n\n/**\n * Restores a devnode ledger from a named snapshot.\n *\n * Spawns `aleo-devnode restore` as a child process (requires the binary on\n * PATH). With `restart: true` the devnode is relaunched on the restored\n * ledger; otherwise only the storage directory is rewritten and the caller\n * starts the node separately.\n *\n * @param options Snapshot name, target storage directory, and optional\n *   restart parameters.\n * @throws If the binary is missing, the snapshot does not exist, or the\n *   command exits non-zero.\n */\nexport async function restoreDevnode(options: DevnodeRestoreOptions): Promise<void> {\n  const devnodePath = options.devnodePath ?? 'aleo-devnode'\n  const args = ['restore', '--snapshot', options.snapshot]\n  if (options.storage) args.push('--storage', options.storage)\n  if (options.restart) {\n    args.push('--restart')\n    if (options.privateKey) args.push('--private-key', options.privateKey)\n    if (options.socketAddr) args.push('--socket-addr', options.socketAddr)\n    if (options.verbosity !== undefined) args.push('--verbosity', String(options.verbosity))\n    if (options.manualBlockCreation) args.push('--manual-block-creation')\n  }\n  await runDevnode(devnodePath, args)\n}\n\n// =============================================================================\n// Subprocess helpers\n// =============================================================================\n\nasync function tryShutdownExisting(socketAddr: string): Promise<void> {\n  const baseUrl = `http://${socketAddr}`\n  try {\n    const res = await fetch(`${baseUrl}/testnet/shutdown`, {\n      method: 'POST',\n      signal: AbortSignal.timeout(2_000),\n    })\n    if (!res.ok) return\n    // Wait up to 5s for the old process to stop responding\n    const deadline = Date.now() + 5_000\n    while (Date.now() < deadline) {\n      try {\n        await fetch(`${baseUrl}${HEALTH_CHECK_PATH}`, { signal: AbortSignal.timeout(500) })\n        await new Promise<void>(r => setTimeout(r, 200))\n      } catch {\n        return // port no longer responding — old devnode is gone\n      }\n    }\n  } catch {\n    // nothing was listening on the port — proceed normally\n  }\n}\n\nfunction runDevnode(devnodePath: string, args: string[]): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const proc = spawn(devnodePath, args, { stdio: 'inherit' })\n    proc.on('error', (err) =>\n      reject(\n        new Error(\n          `Failed to run ${devnodePath}: ${err.message}. Ensure aleo-devnode is installed and on PATH.`,\n        ),\n      ),\n    )\n    proc.on('exit', (code) => {\n      if (code === 0) resolve()\n      else reject(new Error(`${devnodePath} ${args[0]} exited with code ${code}`))\n    })\n  })\n}\n\nasync function spawnDevnode(\n  devnodePath: string,\n  args: string[],\n  socketAddr: string,\n  readyTimeout: number,\n  verbose: boolean = false,\n): Promise<DevnodeInstance> {\n  const proc = spawn(devnodePath, args, {\n    stdio: 'pipe',\n    // MUST mirror DEVNODE_CONSENSUS_HEIGHTS in @provablehq/veil-aleo-sdk so the\n    // transaction builder and the node agree on active consensus versions.\n    env: { ...process.env, CONSENSUS_VERSION_HEIGHTS: process.env.CONSENSUS_VERSION_HEIGHTS || '0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16' },\n  })\n\n  if (verbose) {\n    const port = socketAddr.split(':')[1] ?? socketAddr.replace(/\\./g, '-')\n    const logFile = join(process.cwd(), `devnode-${port}.log`)\n    const logStream = createWriteStream(logFile, { flags: 'w' })\n    proc.stdout?.pipe(logStream)\n    proc.stderr?.pipe(logStream)\n    console.log(`[devnode] logs → ${logFile}`)\n  } else {\n    proc.stdout?.resume()\n    proc.stderr?.resume()\n  }\n\n  let startError: Error | undefined\n  proc.on('error', (err) => {\n    startError = new Error(\n      `Failed to start ${devnodePath}: ${err.message}. Ensure aleo-devnode is installed and on PATH.`,\n    )\n  })\n  proc.on('exit', (code, signal) => {\n    if (signal === 'SIGTERM' || signal === 'SIGINT') return\n    if (code !== 0 && code !== null) {\n      startError = startError ?? new Error(`${devnodePath} exited unexpectedly with code ${code}`)\n    }\n  })\n\n  try {\n    await waitForReady(`http://${socketAddr}`, readyTimeout, () => startError)\n  } catch (err) {\n    proc.kill('SIGTERM')\n    throw err\n  }\n\n  return {\n    socketAddr,\n    stop: () =>\n      new Promise<void>((resolve) => {\n        proc.kill('SIGTERM')\n        proc.once('exit', () => resolve())\n      }),\n  }\n}\n\n// =============================================================================\n// Test client decorator\n// =============================================================================\n\n/**\n * Devnode management actions added to a test client by {@link devnodeActions}.\n *\n * Each action delegates to the standalone function of the same name and\n * spawns the `aleo-devnode` binary.\n *\n * @property startDevnode Starts a devnode; see {@link startDevnode}.\n * @property advanceDevnode Produces blocks on a running devnode; see {@link advanceDevnode}.\n * @property restoreDevnode Restores a ledger snapshot; see {@link restoreDevnode}.\n */\nexport type DevnodeClientActions = {\n  startDevnode: (options?: DevnodeStartOptions) => Promise<DevnodeInstance>\n  advanceDevnode: (options?: DevnodeAdvanceOptions) => Promise<void>\n  restoreDevnode: (options: DevnodeRestoreOptions) => Promise<void>\n}\n\n/**\n * Adds devnode management actions to a test client via `.extend`.\n *\n * @example\n * ```ts\n * import { createTestClient, http } from '@provablehq/veil-core'\n * import { devnodeActions } from '@provablehq/veil-aleo-devnode'\n *\n * const client = createTestClient({ transport: http('http://127.0.0.1:3030', { network: 'testnet' }) })\n *   .extend(devnodeActions)\n *\n * const devnode = await client.startDevnode()\n * await client.advanceDevnode({ numBlocks: 1 })\n * await devnode.stop()\n * ```\n */\nexport function devnodeActions(_client: Client): DevnodeClientActions {\n  return {\n    startDevnode: (options) => startDevnode(options),\n    advanceDevnode: (options) => advanceDevnode(options),\n    restoreDevnode: (options) => restoreDevnode(options),\n  }\n}\n\nasync function waitForReady(\n  baseUrl: string,\n  timeout: number,\n  getError: () => Error | undefined,\n): Promise<void> {\n  const deadline = Date.now() + timeout\n  const healthUrl = `${baseUrl}${HEALTH_CHECK_PATH}`\n\n  while (Date.now() < deadline) {\n    const err = getError()\n    if (err) throw err\n\n    try {\n      const response = await fetch(healthUrl, {\n        signal: AbortSignal.timeout(HEALTH_CHECK_REQUEST_TIMEOUT_MS),\n      })\n      if (response.ok) return\n    } catch {\n      // not ready yet — keep polling\n    }\n\n    await new Promise<void>((resolve) => setTimeout(resolve, HEALTH_CHECK_INTERVAL_MS))\n  }\n\n  throw new Error(\n    `Devnode at ${baseUrl} did not become ready within ${timeout}ms. ` +\n    'Try increasing readyTimeout or check that aleo-devnode is installed and working.',\n  )\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@provablehq/veil-aleo-devnode",
+  "version": "0.4.0",
+  "description": "TypeScript interface for orchestrating local Aleo test networks for testing & developing Aleo programs.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ProvableHQ/veil.git",
+    "directory": "packages/devnode"
+  },
+  "homepage": "https://github.com/ProvableHQ/veil#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@provablehq/veil-core": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}