@ariestools/chain-serve-local-s3 0.1.15

package/README.md

@@ -0,0 +1,83 @@
+# @ariestools/chain-serve-local-s3
+
+> **Dev/test only.** Boots an ephemeral local XL1 environment for integration
+> and e2e tests. Not for production.
+
+One function call starts:
+
+1. **`@ariestools/aries-chain-serve`** — S3-compatible published-chain layout
+   (`/blocks`, `/state`, `/indexes`) via s3rver
+2. **`@xyo-network/xl1-cli`** — `api` + `producer` + `finalizer` + `mempool` +
+   `indexer`, publishing finalized blocks and index into that layout
+
+## Install
+
+```sh
+pnpm add -D @ariestools/chain-serve-local-s3
+```
+
+Pulls in `@ariestools/aries-chain-serve`, `@xyo-network/xl1-cli`, and
+`@xyo-network/xl1-sdk` as runtime dependencies.
+
+## Single-call usage
+
+```ts
+import { startLocalS3Chain } from '@ariestools/chain-serve-local-s3'
+
+const chain = await startLocalS3Chain()
+
+// chain.rpcUrl              http://127.0.0.1:<port>/rpc
+// chain.apiPort
+// chain.chainId
+// chain.blockProducerWallet // path 0 of the insecure test mnemonic
+// chain.s3Endpoint          s3rver origin
+// chain.s3ReadUrls          { finalized, chainState, index }
+
+await chain.stop()
+```
+
+## Vitest setupFile (lifehash-style globals)
+
+```ts
+// test/setup/api-local-s3.ts
+import { afterAll, beforeAll } from 'vitest'
+import { registerLocalS3Chain } from '@ariestools/chain-serve-local-s3'
+
+registerLocalS3Chain(
+  { beforeAll, afterAll },
+  { assignGlobals: true },
+)
+```
+
+With `assignGlobals: true`, specs can read:
+
+| Global               | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `apiPort`            | XL1 API port                                     |
+| `rpcUrl`             | `http://127.0.0.1:<port>/rpc`                    |
+| `chainId`            | Local chain id                                   |
+| `blockProducerWallet`| Genesis / producer path-0 account                |
+| `s3ReadUrls`         | `{ finalized, chainState, index }` read base URLs|
+| `s3Endpoint`         | s3rver base URL                                  |
+
+## Options
+
+| Option            | Default                                      |
+| ----------------- | -------------------------------------------- |
+| `apiPort`         | `8080 + VITEST_WORKER_ID` (or free fallback) |
+| `chainId`         | local-dev fixture id                         |
+| `mnemonic`        | insecure `test test … junk` phrase           |
+| `healthTimeoutMs` | `120_000`                                    |
+| `assignGlobals`   | `false`                                      |
+| `silent`          | `true` (s3rver)                              |
+| `logXl1`          | `true` (child logs → stderr)                 |
+
+## Notes
+
+- The local API serves `/rpc` only (no REST datalake). Writers typically run in
+  inline mode; body resolution on the read side is up to the test.
+- S3 credentials accepted by the layout: `S3RVER` / `S3RVER` (exported as
+  `S3_CREDENTIALS`).
+- Parallel vitest workers get distinct preferred API ports via
+  `VITEST_WORKER_ID`; Prometheus and health-check ports are disabled in the
+  child config to avoid clashes.

package/dist/node/assignGlobals.d.ts

@@ -0,0 +1,10 @@
+import type { LocalS3Chain } from './types.ts';
+/**
+ * Keys written to `globalThis` when `assignGlobals: true`.
+ * Matches the lifehash / chain-test vitest setupFile convention.
+ */
+export declare const LOCAL_S3_CHAIN_GLOBAL_KEYS: readonly ["apiPort", "rpcUrl", "chainId", "blockProducerWallet", "s3ReadUrls", "s3Endpoint"];
+export type LocalS3ChainGlobalKey = typeof LOCAL_S3_CHAIN_GLOBAL_KEYS[number];
+/** Assign chain harness fields onto `globalThis` for vitest e2e specs. */
+export declare function assignLocalS3ChainGlobals(chain: LocalS3Chain): void;
+//# sourceMappingURL=assignGlobals.d.ts.map

package/dist/node/assignGlobals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignGlobals.d.ts","sourceRoot":"","sources":["../../src/assignGlobals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAQ9C;;;GAGG;AACH,eAAO,MAAM,0BAA0B,8FAO7B,CAAA;AAEV,MAAM,MAAM,qBAAqB,GAAG,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAA;AAE7E,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAOnE"}

package/dist/node/buildXl1Config.d.ts

@@ -0,0 +1,15 @@
+export interface BuildXl1ConfigOptions {
+    apiPort: number;
+    baseUrl: string;
+    chainId: string;
+    genesisRewardAddress: string;
+    /** Port 0 disables Prometheus scrape (avoids default 9465 clashes). */
+    metricsPort?: number;
+    s3Endpoint: string;
+}
+/**
+ * Memory authority store + S3 publish targets for the published REST layout.
+ * Section key is `xl1` (xl1-cli config file shape).
+ */
+export declare function buildXl1Config(options: BuildXl1ConfigOptions): Record<string, unknown>;
+//# sourceMappingURL=buildXl1Config.d.ts.map

package/dist/node/buildXl1Config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildXl1Config.d.ts","sourceRoot":"","sources":["../../src/buildXl1Config.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,oBAAoB,EAAE,MAAM,CAAA;IAC5B,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwEtF"}

package/dist/node/constants.d.ts

@@ -0,0 +1,24 @@
+/** Built-in insecure genesis mnemonic — same phrase xl1-cli uses for the
+ *  genesis reward wallet when no production mnemonic is configured. */
+export declare const GENESIS_MNEMONIC = "test test test test test test test test test test test junk";
+/** Default local-dev chain id (matches xl1/aries fixtures). */
+export declare const DEFAULT_CHAIN_ID = "1111111111111111111111111111111111111111";
+/** Credentials s3rver accepts for any signed S3 API call. */
+export declare const S3_CREDENTIALS: {
+    readonly accessKeyId: "S3RVER";
+    readonly accountId: "test";
+    readonly secretAccessKey: "S3RVER";
+};
+/**
+ * aries-chain-serve bucket names (path-style: /blocks, /state, /indexes),
+ * mapped to the connection roles used in the xl1-cli config.
+ */
+export declare const CHAIN_BUCKETS: {
+    readonly chainState: "state";
+    readonly finalized: "blocks";
+    readonly index: "indexes";
+};
+export declare const DEFAULT_HEALTH_TIMEOUT_MS = 120000;
+export declare const DEFAULT_HEALTH_POLL_MS = 500;
+export declare const DEFAULT_API_PORT_BASE = 8080;
+//# sourceMappingURL=constants.d.ts.map

package/dist/node/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;uEACuE;AACvE,eAAO,MAAM,gBAAgB,gEAAgE,CAAA;AAE7F,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,6CAA6C,CAAA;AAE1E,6DAA6D;AAC7D,eAAO,MAAM,cAAc;;;;CAIjB,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAA;AAEV,eAAO,MAAM,yBAAyB,SAAU,CAAA;AAChD,eAAO,MAAM,sBAAsB,MAAM,CAAA;AACzC,eAAO,MAAM,qBAAqB,OAAO,CAAA"}

package/dist/node/index.d.ts

@@ -0,0 +1,12 @@
+export type { LocalS3ChainGlobalKey } from './assignGlobals.ts';
+export { assignLocalS3ChainGlobals, LOCAL_S3_CHAIN_GLOBAL_KEYS } from './assignGlobals.ts';
+export type { BuildXl1ConfigOptions } from './buildXl1Config.ts';
+export { buildXl1Config } from './buildXl1Config.ts';
+export { CHAIN_BUCKETS, DEFAULT_API_PORT_BASE, DEFAULT_CHAIN_ID, DEFAULT_HEALTH_POLL_MS, DEFAULT_HEALTH_TIMEOUT_MS, GENESIS_MNEMONIC, S3_CREDENTIALS, } from './constants.ts';
+export { findAvailablePort } from './ports.ts';
+export type { RegisterLocalS3ChainOptions, TestLifecycleHooks } from './registerLocalS3Chain.ts';
+export { registerLocalS3Chain } from './registerLocalS3Chain.ts';
+export { resolveXl1Bin } from './resolveXl1Bin.ts';
+export type { LocalS3Chain, S3ReadUrls, StartLocalS3ChainOptions, } from './startLocalS3Chain.ts';
+export { startLocalS3Chain } from './startLocalS3Chain.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC/D,OAAO,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAA;AAC1F,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,sBAAsB,EACtB,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9C,YAAY,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAChG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EACV,YAAY,EAAE,UAAU,EAAE,wBAAwB,GACnD,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/node/index.mjs

@@ -0,0 +1,439 @@
+// src/assignGlobals.ts
+function assignGlobal(key, value) {
+  Object.defineProperty(globalThis, key, {
+    configurable: true,
+    enumerable: true,
+    value,
+    writable: true
+  });
+}
+var LOCAL_S3_CHAIN_GLOBAL_KEYS = [
+  "apiPort",
+  "rpcUrl",
+  "chainId",
+  "blockProducerWallet",
+  "s3ReadUrls",
+  "s3Endpoint"
+];
+function assignLocalS3ChainGlobals(chain) {
+  assignGlobal("apiPort", chain.apiPort);
+  assignGlobal("rpcUrl", chain.rpcUrl);
+  assignGlobal("chainId", chain.chainId);
+  assignGlobal("blockProducerWallet", chain.blockProducerWallet);
+  assignGlobal("s3ReadUrls", chain.s3ReadUrls);
+  assignGlobal("s3Endpoint", chain.s3Endpoint);
+}
+
+// src/constants.ts
+var GENESIS_MNEMONIC = "test test test test test test test test test test test junk";
+var DEFAULT_CHAIN_ID = "1111111111111111111111111111111111111111";
+var S3_CREDENTIALS = {
+  accessKeyId: "S3RVER",
+  accountId: "test",
+  secretAccessKey: "S3RVER"
+};
+var CHAIN_BUCKETS = {
+  chainState: "state",
+  finalized: "blocks",
+  index: "indexes"
+};
+var DEFAULT_HEALTH_TIMEOUT_MS = 12e4;
+var DEFAULT_HEALTH_POLL_MS = 500;
+var DEFAULT_API_PORT_BASE = 8080;
+
+// src/buildXl1Config.ts
+function buildS3Connection(endpoint, bucket, readUrl) {
+  return {
+    type: "s3",
+    accessKeyId: S3_CREDENTIALS.accessKeyId,
+    accountId: S3_CREDENTIALS.accountId,
+    secretAccessKey: S3_CREDENTIALS.secretAccessKey,
+    bucket,
+    endpoint,
+    readUrl
+  };
+}
+function buildXl1Config(options) {
+  const metricsPort = options.metricsPort ?? 0;
+  const {
+    apiPort,
+    baseUrl,
+    chainId,
+    genesisRewardAddress,
+    s3Endpoint
+  } = options;
+  return {
+    xl1: {
+      chain: { id: chainId, genesisRewardAddress },
+      // Port 0 disables the HTTP system-status publisher (default 9099) so
+      // parallel vitest files / leftover nodes cannot collide on it.
+      healthCheckPort: 0,
+      // Explicit free metrics scrape port (port 0 disables Prometheus entirely
+      // in xl1 telemetry). Avoids the default 9465 clash when multiple xl1
+      // children start together.
+      telemetry: { metrics: { scrape: { port: metricsPort } } },
+      connections: {
+        "local-store": { type: "memory" },
+        "s3-finalized": buildS3Connection(s3Endpoint, CHAIN_BUCKETS.finalized, `${baseUrl}/${CHAIN_BUCKETS.finalized}`),
+        "s3-chain-state": buildS3Connection(s3Endpoint, CHAIN_BUCKETS.chainState, `${baseUrl}/${CHAIN_BUCKETS.chainState}`),
+        "s3-index": buildS3Connection(s3Endpoint, CHAIN_BUCKETS.index, `${baseUrl}/${CHAIN_BUCKETS.index}`)
+      },
+      providerBindings: {
+        // Authority / write path — in-memory single process.
+        BlockRunner: { connection: "local-store" },
+        BlockValidationViewer: { connection: "local-store" },
+        BlockViewer: { connection: "local-store" },
+        DeadLetterQueueRunner: { connection: "local-store" },
+        DeadLetterQueueViewer: { connection: "local-store" },
+        FinalizationRunner: { connection: "local-store" },
+        FinalizationViewer: { connection: "local-store" },
+        MempoolRunner: { connection: "local-store" },
+        MempoolViewer: { connection: "local-store" },
+        TransactionValidationViewer: { connection: "local-store" },
+        WindowedBlockViewer: { connection: "local-store" },
+        XyoRunner: { connection: "local-store" },
+        // Published REST layout writers + chain-state gate for the indexer.
+        BlockPublishRunner: { connection: "s3-finalized" },
+        ChainStatePublishRunner: { connection: "s3-chain-state" },
+        IndexPublishRunner: { connection: "s3-index" },
+        ChainStateViewer: { connection: "s3-chain-state" },
+        // Dev placeholder — no real EVM staking contract in this harness.
+        ChainContractViewer: { provider: "SimpleChainContractViewer" }
+      },
+      actors: [
+        {
+          name: "api",
+          host: "127.0.0.1",
+          port: apiPort
+        },
+        {
+          name: "producer",
+          accountPath: "0",
+          // Keep production under s3rver publish catch-up capacity.
+          blockProductionCheckInterval: 250,
+          heartbeatInterval: 1e3
+        },
+        {
+          name: "finalizer",
+          accountPath: "5",
+          finalizationCheckInterval: 100,
+          minCandidates: 1,
+          publishOnFinalize: true,
+          publishContentEncoding: "none"
+        },
+        { name: "mempool" },
+        {
+          name: "indexer",
+          accountPath: "6",
+          publishSyncInterval: 250,
+          publishContentEncoding: "none"
+        }
+      ]
+    }
+  };
+}
+
+// src/ports.ts
+import net from "node:net";
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.listen(port, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+async function getFreePort() {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (address === null || typeof address === "string") {
+        server.close(() => reject(new Error("getFreePort: no address")));
+        return;
+      }
+      const { port } = address;
+      server.close((error) => error ? reject(error) : resolve(port));
+    });
+  });
+}
+async function findAvailablePort(preferred) {
+  if (await isPortAvailable(preferred)) return preferred;
+  return await getFreePort();
+}
+
+// src/startLocalS3Chain.ts
+import { createMemoryBacking, startChainServer } from "@ariestools/aries-chain-serve";
+import { generateXyoBaseWalletFromPhrase } from "@xyo-network/xl1-sdk/protocol-sdk";
+
+// src/startXl1.ts
+import { spawn } from "node:child_process";
+import FS from "node:fs/promises";
+import OS from "node:os";
+import PATH2 from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+// src/resolveXl1Bin.ts
+import { createRequire } from "node:module";
+import PATH from "node:path";
+import xl1CliPkg from "@xyo-network/xl1-cli/package.json" with { type: "json" };
+function binFromPkg(pkgPath, pkg) {
+  const binEntry = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.xl1;
+  if (!binEntry) throw new Error('@xyo-network/xl1-cli does not declare a "xl1" bin');
+  return PATH.resolve(PATH.dirname(pkgPath), binEntry);
+}
+function resolveXl1Bin() {
+  if (xl1CliPkg.name !== "@xyo-network/xl1-cli") {
+    throw new Error("@ariestools/chain-serve-local-s3: unexpected @xyo-network/xl1-cli package name");
+  }
+  const localRequire = createRequire(import.meta.url);
+  try {
+    const pkgPath = localRequire.resolve("@xyo-network/xl1-cli/package.json");
+    const pkg = localRequire("@xyo-network/xl1-cli/package.json");
+    return binFromPkg(pkgPath, pkg);
+  } catch {
+  }
+  const cwdPkg = PATH.join(process.cwd(), "package.json");
+  const cwdRequire = createRequire(cwdPkg);
+  try {
+    const pkgPath = cwdRequire.resolve("@xyo-network/xl1-cli/package.json");
+    const pkg = cwdRequire("@xyo-network/xl1-cli/package.json");
+    return binFromPkg(pkgPath, pkg);
+  } catch (error) {
+    throw new Error(
+      "@ariestools/chain-serve-local-s3: @xyo-network/xl1-cli is not installed. It is a runtime dependency of this package \u2014 reinstall node_modules.",
+      { cause: error }
+    );
+  }
+}
+
+// src/startXl1.ts
+async function waitForApi(rpcUrl, child, healthTimeoutMs, healthPollMs) {
+  const deadline = Date.now() + healthTimeoutMs;
+  const healthUrl = rpcUrl.replace(/\/rpc$/, "/");
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(
+        `@ariestools/chain-serve-local-s3: xl1 exited early (code=${child.exitCode}) before API became reachable on ${rpcUrl}`
+      );
+    }
+    try {
+      const response = await fetch(healthUrl, { method: "GET" });
+      if (response.status > 0) return;
+    } catch {
+    }
+    await delay(healthPollMs);
+  }
+  throw new Error(
+    `@ariestools/chain-serve-local-s3: xl1 API did not become reachable on ${rpcUrl} within ${healthTimeoutMs}ms`
+  );
+}
+async function startXl1(options) {
+  const {
+    apiPort,
+    chainId,
+    genesisRewardAddress,
+    healthPollMs = DEFAULT_HEALTH_POLL_MS,
+    healthTimeoutMs = DEFAULT_HEALTH_TIMEOUT_MS,
+    logXl1 = true,
+    mnemonic = GENESIS_MNEMONIC,
+    s3
+  } = options;
+  const rpcUrl = `http://127.0.0.1:${apiPort}/rpc`;
+  const metricsPort = 0;
+  const configDir = await FS.mkdtemp(PATH2.join(OS.tmpdir(), "chain-serve-local-s3-"));
+  const configPath = PATH2.join(configDir, "xyo.json");
+  await FS.writeFile(
+    configPath,
+    `${JSON.stringify(buildXl1Config({
+      apiPort,
+      baseUrl: s3.baseUrl,
+      chainId,
+      genesisRewardAddress,
+      metricsPort,
+      s3Endpoint: s3.baseUrl
+    }), null, 2)}
+`,
+    "utf8"
+  );
+  const xl1Bin = resolveXl1Bin();
+  const child = spawn(
+    process.execPath,
+    [
+      xl1Bin,
+      "start",
+      "api",
+      "producer",
+      "finalizer",
+      "mempool",
+      "indexer",
+      "-c",
+      configPath,
+      "--skip-insecure-confirm"
+    ],
+    {
+      env: {
+        ...process.env,
+        // Seed the shared root mnemonic so producer path 0 == genesis reward.
+        XL1_MNEMONIC: mnemonic
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    }
+  );
+  if (logXl1) {
+    child.stdout?.on("data", (chunk) => {
+      process.stderr.write(`[xl1] ${chunk.toString("utf8")}`);
+    });
+    child.stderr?.on("data", (chunk) => {
+      process.stderr.write(`[xl1!] ${chunk.toString("utf8")}`);
+    });
+    child.on("exit", (code, signal) => {
+      process.stderr.write(`[xl1] exited code=${code} signal=${signal}
+`);
+    });
+  }
+  try {
+    await waitForApi(rpcUrl, child, healthTimeoutMs, healthPollMs);
+  } catch (error) {
+    if (child.exitCode === null) child.kill("SIGTERM");
+    try {
+      await FS.rm(configDir, { recursive: true, force: true });
+    } catch {
+    }
+    throw error;
+  }
+  return {
+    apiPort,
+    chainId,
+    child,
+    configDir,
+    rpcUrl
+  };
+}
+async function stopXl1(result) {
+  if (!result) return;
+  const cleanup = async () => {
+    try {
+      await FS.rm(result.configDir, { recursive: true, force: true });
+    } catch {
+    }
+  };
+  if (result.child.exitCode !== null) {
+    await cleanup();
+    return;
+  }
+  const stopped = new Promise((resolve) => {
+    result.child.once("exit", () => resolve());
+  });
+  result.child.kill("SIGTERM");
+  await Promise.race([
+    stopped,
+    delay(1e4).then(() => {
+      if (result.child.exitCode === null) result.child.kill("SIGKILL");
+    })
+  ]);
+  await cleanup();
+}
+
+// src/startLocalS3Chain.ts
+async function startLocalS3Chain(options = {}) {
+  const {
+    assignGlobals = false,
+    chainId = DEFAULT_CHAIN_ID,
+    healthTimeoutMs = DEFAULT_HEALTH_TIMEOUT_MS,
+    logXl1 = true,
+    mnemonic = GENESIS_MNEMONIC,
+    silent = true
+  } = options;
+  const s3 = await startChainServer({
+    backing: createMemoryBacking(),
+    port: 0,
+    silent
+  });
+  let xl1;
+  try {
+    const preferredApi = options.apiPort ?? DEFAULT_API_PORT_BASE + Number(process.env.VITEST_WORKER_ID ?? 0);
+    const apiPort = await findAvailablePort(preferredApi);
+    const genesisRoot = await generateXyoBaseWalletFromPhrase(mnemonic);
+    const genesisWallet = await genesisRoot.derivePath("0");
+    xl1 = await startXl1({
+      apiPort,
+      chainId,
+      genesisRewardAddress: genesisWallet.address,
+      healthTimeoutMs,
+      logXl1,
+      mnemonic,
+      s3
+    });
+    const s3ReadUrls = {
+      chainState: `${s3.baseUrl}/${CHAIN_BUCKETS.chainState}`,
+      finalized: `${s3.baseUrl}/${CHAIN_BUCKETS.finalized}`,
+      index: `${s3.baseUrl}/${CHAIN_BUCKETS.index}`
+    };
+    const chain = {
+      apiPort,
+      blockProducerWallet: genesisWallet,
+      chainId: xl1.chainId,
+      rpcUrl: xl1.rpcUrl,
+      s3Endpoint: s3.baseUrl,
+      s3ReadUrls,
+      stop: async () => {
+        await stopXl1(xl1);
+        xl1 = void 0;
+        await s3.close();
+      }
+    };
+    if (assignGlobals) assignLocalS3ChainGlobals(chain);
+    if (logXl1) {
+      process.stderr.write(
+        `chain-serve-local-s3: XL1 on ${chain.rpcUrl}, published layout on ${chain.s3Endpoint}, chain ${chain.chainId}
+`
+      );
+    }
+    return chain;
+  } catch (error) {
+    await stopXl1(xl1);
+    await s3.close();
+    throw error;
+  }
+}
+
+// src/registerLocalS3Chain.ts
+function registerLocalS3Chain(hooks, options = {}) {
+  const {
+    afterAllTimeoutMs = 6e4,
+    beforeAllTimeoutMs,
+    healthTimeoutMs = DEFAULT_HEALTH_TIMEOUT_MS,
+    ...startOptions
+  } = options;
+  let chain;
+  hooks.beforeAll(async () => {
+    chain = await startLocalS3Chain({
+      healthTimeoutMs,
+      ...startOptions
+    });
+  }, beforeAllTimeoutMs ?? healthTimeoutMs + 6e4);
+  hooks.afterAll(async () => {
+    await chain?.stop();
+    chain = void 0;
+  }, afterAllTimeoutMs);
+}
+export {
+  CHAIN_BUCKETS,
+  DEFAULT_API_PORT_BASE,
+  DEFAULT_CHAIN_ID,
+  DEFAULT_HEALTH_POLL_MS,
+  DEFAULT_HEALTH_TIMEOUT_MS,
+  GENESIS_MNEMONIC,
+  LOCAL_S3_CHAIN_GLOBAL_KEYS,
+  S3_CREDENTIALS,
+  assignLocalS3ChainGlobals,
+  buildXl1Config,
+  findAvailablePort,
+  registerLocalS3Chain,
+  resolveXl1Bin,
+  startLocalS3Chain
+};
+//# sourceMappingURL=index.mjs.map

package/dist/node/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/assignGlobals.ts", "../../src/constants.ts", "../../src/buildXl1Config.ts", "../../src/ports.ts", "../../src/startLocalS3Chain.ts", "../../src/startXl1.ts", "../../src/resolveXl1Bin.ts", "../../src/registerLocalS3Chain.ts"],
+  "sourcesContent": ["import type { LocalS3Chain } from './types.ts'\n\nfunction assignGlobal(key: string, value: unknown): void {\n  Object.defineProperty(globalThis, key, {\n    configurable: true, enumerable: true, value, writable: true,\n  })\n}\n\n/**\n * Keys written to `globalThis` when `assignGlobals: true`.\n * Matches the lifehash / chain-test vitest setupFile convention.\n */\nexport const LOCAL_S3_CHAIN_GLOBAL_KEYS = [\n  'apiPort',\n  'rpcUrl',\n  'chainId',\n  'blockProducerWallet',\n  's3ReadUrls',\n  's3Endpoint',\n] as const\n\nexport type LocalS3ChainGlobalKey = typeof LOCAL_S3_CHAIN_GLOBAL_KEYS[number]\n\n/** Assign chain harness fields onto `globalThis` for vitest e2e specs. */\nexport function assignLocalS3ChainGlobals(chain: LocalS3Chain): void {\n  assignGlobal('apiPort', chain.apiPort)\n  assignGlobal('rpcUrl', chain.rpcUrl)\n  assignGlobal('chainId', chain.chainId)\n  assignGlobal('blockProducerWallet', chain.blockProducerWallet)\n  assignGlobal('s3ReadUrls', chain.s3ReadUrls)\n  assignGlobal('s3Endpoint', chain.s3Endpoint)\n}\n", "/** Built-in insecure genesis mnemonic \u2014 same phrase xl1-cli uses for the\n *  genesis reward wallet when no production mnemonic is configured. */\nexport const GENESIS_MNEMONIC = 'test test test test test test test test test test test junk'\n\n/** Default local-dev chain id (matches xl1/aries fixtures). */\nexport const DEFAULT_CHAIN_ID = '1111111111111111111111111111111111111111'\n\n/** Credentials s3rver accepts for any signed S3 API call. */\nexport const S3_CREDENTIALS = {\n  accessKeyId: 'S3RVER',\n  accountId: 'test',\n  secretAccessKey: 'S3RVER',\n} as const\n\n/**\n * aries-chain-serve bucket names (path-style: /blocks, /state, /indexes),\n * mapped to the connection roles used in the xl1-cli config.\n */\nexport const CHAIN_BUCKETS = {\n  chainState: 'state',\n  finalized: 'blocks',\n  index: 'indexes',\n} as const\n\nexport const DEFAULT_HEALTH_TIMEOUT_MS = 120_000\nexport const DEFAULT_HEALTH_POLL_MS = 500\nexport const DEFAULT_API_PORT_BASE = 8080\n", "import { CHAIN_BUCKETS, S3_CREDENTIALS } from './constants.ts'\n\nfunction buildS3Connection(endpoint: string, bucket: string, readUrl: string): Record<string, unknown> {\n  return {\n    type: 's3',\n    accessKeyId: S3_CREDENTIALS.accessKeyId,\n    accountId: S3_CREDENTIALS.accountId,\n    secretAccessKey: S3_CREDENTIALS.secretAccessKey,\n    bucket,\n    endpoint,\n    readUrl,\n  }\n}\n\nexport interface BuildXl1ConfigOptions {\n  apiPort: number\n  baseUrl: string\n  chainId: string\n  genesisRewardAddress: string\n  /** Port 0 disables Prometheus scrape (avoids default 9465 clashes). */\n  metricsPort?: number\n  s3Endpoint: string\n}\n\n/**\n * Memory authority store + S3 publish targets for the published REST layout.\n * Section key is `xl1` (xl1-cli config file shape).\n */\nexport function buildXl1Config(options: BuildXl1ConfigOptions): Record<string, unknown> {\n  const metricsPort = options.metricsPort ?? 0\n  const {\n    apiPort, baseUrl, chainId, genesisRewardAddress, s3Endpoint,\n  } = options\n  return {\n    xl1: {\n      chain: { id: chainId, genesisRewardAddress },\n      // Port 0 disables the HTTP system-status publisher (default 9099) so\n      // parallel vitest files / leftover nodes cannot collide on it.\n      healthCheckPort: 0,\n      // Explicit free metrics scrape port (port 0 disables Prometheus entirely\n      // in xl1 telemetry). Avoids the default 9465 clash when multiple xl1\n      // children start together.\n      telemetry: { metrics: { scrape: { port: metricsPort } } },\n      connections: {\n        'local-store': { type: 'memory' },\n        's3-finalized': buildS3Connection(s3Endpoint, CHAIN_BUCKETS.finalized, `${baseUrl}/${CHAIN_BUCKETS.finalized}`),\n        's3-chain-state': buildS3Connection(s3Endpoint, CHAIN_BUCKETS.chainState, `${baseUrl}/${CHAIN_BUCKETS.chainState}`),\n        's3-index': buildS3Connection(s3Endpoint, CHAIN_BUCKETS.index, `${baseUrl}/${CHAIN_BUCKETS.index}`),\n      },\n      providerBindings: {\n        // Authority / write path \u2014 in-memory single process.\n        BlockRunner: { connection: 'local-store' },\n        BlockValidationViewer: { connection: 'local-store' },\n        BlockViewer: { connection: 'local-store' },\n        DeadLetterQueueRunner: { connection: 'local-store' },\n        DeadLetterQueueViewer: { connection: 'local-store' },\n        FinalizationRunner: { connection: 'local-store' },\n        FinalizationViewer: { connection: 'local-store' },\n        MempoolRunner: { connection: 'local-store' },\n        MempoolViewer: { connection: 'local-store' },\n        TransactionValidationViewer: { connection: 'local-store' },\n        WindowedBlockViewer: { connection: 'local-store' },\n        XyoRunner: { connection: 'local-store' },\n        // Published REST layout writers + chain-state gate for the indexer.\n        BlockPublishRunner: { connection: 's3-finalized' },\n        ChainStatePublishRunner: { connection: 's3-chain-state' },\n        IndexPublishRunner: { connection: 's3-index' },\n        ChainStateViewer: { connection: 's3-chain-state' },\n        // Dev placeholder \u2014 no real EVM staking contract in this harness.\n        ChainContractViewer: { provider: 'SimpleChainContractViewer' },\n      },\n      actors: [\n        {\n          name: 'api', host: '127.0.0.1', port: apiPort,\n        },\n        {\n          name: 'producer',\n          accountPath: '0',\n          // Keep production under s3rver publish catch-up capacity.\n          blockProductionCheckInterval: 250,\n          heartbeatInterval: 1000,\n        },\n        {\n          name: 'finalizer',\n          accountPath: '5',\n          finalizationCheckInterval: 100,\n          minCandidates: 1,\n          publishOnFinalize: true,\n          publishContentEncoding: 'none',\n        },\n        { name: 'mempool' },\n        {\n          name: 'indexer',\n          accountPath: '6',\n          publishSyncInterval: 250,\n          publishContentEncoding: 'none',\n        },\n      ],\n    },\n  }\n}\n", "import net from 'node:net'\n\nfunction isPortAvailable(port: number): Promise<boolean> {\n  return new Promise((resolve) => {\n    const server = net.createServer()\n    server.once('error', () => resolve(false))\n    server.listen(port, () => {\n      server.close(() => resolve(true))\n    })\n  })\n}\n\nasync function getFreePort(): Promise<number> {\n  return await new Promise((resolve, reject) => {\n    const server = net.createServer()\n    server.once('error', reject)\n    server.listen(0, '127.0.0.1', () => {\n      const address = server.address()\n      if (address === null || typeof address === 'string') {\n        server.close(() => reject(new Error('getFreePort: no address')))\n        return\n      }\n      const { port } = address\n      server.close(error => (error ? reject(error) : resolve(port)))\n    })\n  })\n}\n\n/** Prefer `preferred` when free on every interface; otherwise an ephemeral port. */\nexport async function findAvailablePort(preferred: number): Promise<number> {\n  if (await isPortAvailable(preferred)) return preferred\n  return await getFreePort()\n}\n", "import { createMemoryBacking, startChainServer } from '@ariestools/aries-chain-serve'\nimport { generateXyoBaseWalletFromPhrase } from '@xyo-network/xl1-sdk/protocol-sdk'\n\nimport { assignLocalS3ChainGlobals } from './assignGlobals.ts'\nimport {\n  CHAIN_BUCKETS,\n  DEFAULT_API_PORT_BASE,\n  DEFAULT_CHAIN_ID,\n  DEFAULT_HEALTH_TIMEOUT_MS,\n  GENESIS_MNEMONIC,\n} from './constants.ts'\nimport { findAvailablePort } from './ports.ts'\nimport type { RunningXl1 } from './startXl1.ts'\nimport { startXl1, stopXl1 } from './startXl1.ts'\nimport type { LocalS3Chain, S3ReadUrls } from './types.ts'\n\nexport type { LocalS3Chain, S3ReadUrls } from './types.ts'\n\nexport interface StartLocalS3ChainOptions {\n  /**\n   * Preferred API port. Defaults to `8080 + Number(process.env.VITEST_WORKER_ID ?? 0)`.\n   * Falls back to an ephemeral port when the preferred port is busy.\n   */\n  apiPort?: number\n  /**\n   * When true, also assign `apiPort`, `rpcUrl`, `chainId`, `blockProducerWallet`,\n   * `s3ReadUrls`, and `s3Endpoint` on `globalThis` (lifehash-style vitest globals).\n   */\n  assignGlobals?: boolean\n  /** Chain id hex string. Default: {@link DEFAULT_CHAIN_ID}. */\n  chainId?: string\n  /** API readiness timeout in ms. Default: 120_000. */\n  healthTimeoutMs?: number\n  /** Pipe xl1 child stdout/stderr to process.stderr. Default: true. */\n  logXl1?: boolean\n  /**\n   * Root mnemonic for xl1 actors and the genesis reward address.\n   * Default: insecure test phrase ({@link GENESIS_MNEMONIC}).\n   */\n  mnemonic?: string\n  /** Silence the embedded s3rver logs. Default: true. */\n  silent?: boolean\n}\n\n/**\n * Boots a local XL1 test environment in one call:\n *\n * 1. `@ariestools/aries-chain-serve` \u2014 S3-compatible published-chain layout\n *    (`/blocks`, `/state`, `/indexes`)\n * 2. `@xyo-network/xl1-cli` \u2014 api + producer + finalizer + mempool + indexer,\n *    publishing finalized blocks and index into that layout\n *\n * @example\n * ```ts\n * const chain = await startLocalS3Chain()\n * // chain.rpcUrl, chain.s3ReadUrls, chain.blockProducerWallet, ...\n * await chain.stop()\n * ```\n */\nexport async function startLocalS3Chain(\n  options: StartLocalS3ChainOptions = {},\n): Promise<LocalS3Chain> {\n  const {\n    assignGlobals = false,\n    chainId = DEFAULT_CHAIN_ID,\n    healthTimeoutMs = DEFAULT_HEALTH_TIMEOUT_MS,\n    logXl1 = true,\n    mnemonic = GENESIS_MNEMONIC,\n    silent = true,\n  } = options\n\n  const s3 = await startChainServer({\n    backing: createMemoryBacking(), port: 0, silent,\n  })\n\n  let xl1: RunningXl1 | undefined\n  try {\n    const preferredApi = options.apiPort\n      ?? (DEFAULT_API_PORT_BASE + Number(process.env.VITEST_WORKER_ID ?? 0))\n    const apiPort = await findAvailablePort(preferredApi)\n\n    // Genesis reward wallet = path 0 of the mnemonic (producer path 0).\n    const genesisRoot = await generateXyoBaseWalletFromPhrase(mnemonic)\n    const genesisWallet = await genesisRoot.derivePath('0')\n\n    xl1 = await startXl1({\n      apiPort,\n      chainId,\n      genesisRewardAddress: genesisWallet.address,\n      healthTimeoutMs,\n      logXl1,\n      mnemonic,\n      s3,\n    })\n\n    const s3ReadUrls: S3ReadUrls = {\n      chainState: `${s3.baseUrl}/${CHAIN_BUCKETS.chainState}`,\n      finalized: `${s3.baseUrl}/${CHAIN_BUCKETS.finalized}`,\n      index: `${s3.baseUrl}/${CHAIN_BUCKETS.index}`,\n    }\n\n    const chain: LocalS3Chain = {\n      apiPort,\n      blockProducerWallet: genesisWallet,\n      chainId: xl1.chainId,\n      rpcUrl: xl1.rpcUrl,\n      s3Endpoint: s3.baseUrl,\n      s3ReadUrls,\n      stop: async (): Promise<void> => {\n        await stopXl1(xl1)\n        xl1 = undefined\n        await s3.close()\n      },\n    }\n\n    if (assignGlobals) assignLocalS3ChainGlobals(chain)\n\n    if (logXl1) {\n      process.stderr.write(\n        `chain-serve-local-s3: XL1 on ${chain.rpcUrl}, published layout on ${chain.s3Endpoint}, chain ${chain.chainId}\\n`,\n      )\n    }\n\n    return chain\n  } catch (error) {\n    await stopXl1(xl1)\n    await s3.close()\n    throw error\n  }\n}\n", "import type { ChildProcess } from 'node:child_process'\nimport { spawn } from 'node:child_process'\nimport FS from 'node:fs/promises'\nimport OS from 'node:os'\nimport PATH from 'node:path'\nimport { setTimeout as delay } from 'node:timers/promises'\n\nimport type { RunningChainServer } from '@ariestools/aries-chain-serve'\n\nimport { buildXl1Config } from './buildXl1Config.ts'\nimport {\n  DEFAULT_HEALTH_POLL_MS, DEFAULT_HEALTH_TIMEOUT_MS, GENESIS_MNEMONIC,\n} from './constants.ts'\nimport { resolveXl1Bin } from './resolveXl1Bin.ts'\n\nexport interface RunningXl1 {\n  apiPort: number\n  chainId: string\n  child: ChildProcess\n  configDir: string\n  rpcUrl: string\n}\n\nexport interface StartXl1Options {\n  apiPort: number\n  chainId: string\n  genesisRewardAddress: string\n  healthPollMs?: number\n  healthTimeoutMs?: number\n  logXl1?: boolean\n  mnemonic?: string\n  s3: RunningChainServer\n}\n\nasync function waitForApi(\n  rpcUrl: string,\n  child: ChildProcess,\n  healthTimeoutMs: number,\n  healthPollMs: number,\n): Promise<void> {\n  const deadline = Date.now() + healthTimeoutMs\n  const healthUrl = rpcUrl.replace(/\\/rpc$/, '/')\n  while (Date.now() < deadline) {\n    if (child.exitCode !== null) {\n      throw new Error(\n        `@ariestools/chain-serve-local-s3: xl1 exited early (code=${child.exitCode}) before API became reachable on ${rpcUrl}`,\n      )\n    }\n    try {\n      const response = await fetch(healthUrl, { method: 'GET' })\n      if (response.status > 0) return\n    } catch {\n      // not ready\n    }\n    await delay(healthPollMs)\n  }\n  throw new Error(\n    `@ariestools/chain-serve-local-s3: xl1 API did not become reachable on ${rpcUrl} within ${healthTimeoutMs}ms`,\n  )\n}\n\nexport async function startXl1(options: StartXl1Options): Promise<RunningXl1> {\n  const {\n    apiPort,\n    chainId,\n    genesisRewardAddress,\n    healthPollMs = DEFAULT_HEALTH_POLL_MS,\n    healthTimeoutMs = DEFAULT_HEALTH_TIMEOUT_MS,\n    logXl1 = true,\n    mnemonic = GENESIS_MNEMONIC,\n    s3,\n  } = options\n\n  // Prefer 127.0.0.1 over localhost \u2014 Node may resolve localhost to ::1 while\n  // the API binds IPv4-only (UND_ERR_SOCKET on RPC writes).\n  const rpcUrl = `http://127.0.0.1:${apiPort}/rpc`\n  // Port 0 = disable Prometheus scrape (see initTelemetryNode). Avoids the\n  // default 9465 clash across concurrent vitest setupFiles.\n  const metricsPort = 0\n  const configDir = await FS.mkdtemp(PATH.join(OS.tmpdir(), 'chain-serve-local-s3-'))\n  const configPath = PATH.join(configDir, 'xyo.json')\n  await FS.writeFile(\n    configPath,\n    `${JSON.stringify(buildXl1Config({\n      apiPort,\n      baseUrl: s3.baseUrl,\n      chainId,\n      genesisRewardAddress,\n      metricsPort,\n      s3Endpoint: s3.baseUrl,\n    }), null, 2)}\\n`,\n    'utf8',\n  )\n\n  const xl1Bin = resolveXl1Bin()\n  const child = spawn(\n    process.execPath,\n    [\n      xl1Bin,\n      'start',\n      'api',\n      'producer',\n      'finalizer',\n      'mempool',\n      'indexer',\n      '-c',\n      configPath,\n      '--skip-insecure-confirm',\n    ],\n    {\n      env: {\n        ...process.env,\n        // Seed the shared root mnemonic so producer path 0 == genesis reward.\n        XL1_MNEMONIC: mnemonic,\n      },\n      stdio: ['ignore', 'pipe', 'pipe'],\n    },\n  )\n\n  if (logXl1) {\n    child.stdout?.on('data', (chunk: Buffer) => {\n      process.stderr.write(`[xl1] ${chunk.toString('utf8')}`)\n    })\n    child.stderr?.on('data', (chunk: Buffer) => {\n      process.stderr.write(`[xl1!] ${chunk.toString('utf8')}`)\n    })\n    child.on('exit', (code, signal) => {\n      process.stderr.write(`[xl1] exited code=${code} signal=${signal}\\n`)\n    })\n  }\n\n  try {\n    await waitForApi(rpcUrl, child, healthTimeoutMs, healthPollMs)\n  } catch (error) {\n    if (child.exitCode === null) child.kill('SIGTERM')\n    try {\n      await FS.rm(configDir, { recursive: true, force: true })\n    } catch {\n      // best-effort cleanup after failed start\n    }\n    throw error\n  }\n\n  return {\n    apiPort, chainId, child, configDir, rpcUrl,\n  }\n}\n\nexport async function stopXl1(result: RunningXl1 | undefined): Promise<void> {\n  if (!result) return\n  const cleanup = async (): Promise<void> => {\n    try {\n      await FS.rm(result.configDir, { recursive: true, force: true })\n    } catch {\n      // best-effort\n    }\n  }\n  if (result.child.exitCode !== null) {\n    await cleanup()\n    return\n  }\n  const stopped = new Promise<void>((resolve) => {\n    result.child.once('exit', () => resolve())\n  })\n  result.child.kill('SIGTERM')\n  await Promise.race([\n    stopped,\n    delay(10_000).then(() => {\n      if (result.child.exitCode === null) result.child.kill('SIGKILL')\n    }),\n  ])\n  await cleanup()\n}\n", "import { createRequire } from 'node:module'\nimport PATH from 'node:path'\n\n// Static import so deplint / package managers treat @xyo-network/xl1-cli as a\n// used runtime dependency. The bin path is still resolved via createRequire\n// below (the package's main entry is not the CLI binary).\nimport xl1CliPkg from '@xyo-network/xl1-cli/package.json' with { type: 'json' }\n\ninterface Xl1Pkg {\n  bin?: Record<string, string> | string\n  name?: string\n}\n\nfunction binFromPkg(pkgPath: string, pkg: Xl1Pkg): string {\n  const binEntry = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.xl1\n  if (!binEntry) throw new Error('@xyo-network/xl1-cli does not declare a \"xl1\" bin')\n  return PATH.resolve(PATH.dirname(pkgPath), binEntry)\n}\n\n/**\n * Resolve the `xl1` bin from `@xyo-network/xl1-cli`. Tries this package's\n * dependency tree first, then the consumer project's cwd.\n */\nexport function resolveXl1Bin(): string {\n  // Touch the static import so tree-shakers keep the package installed.\n  if (xl1CliPkg.name !== '@xyo-network/xl1-cli') {\n    throw new Error('@ariestools/chain-serve-local-s3: unexpected @xyo-network/xl1-cli package name')\n  }\n\n  const localRequire = createRequire(import.meta.url)\n  try {\n    const pkgPath = localRequire.resolve('@xyo-network/xl1-cli/package.json')\n    const pkg = localRequire('@xyo-network/xl1-cli/package.json') as Xl1Pkg\n    return binFromPkg(pkgPath, pkg)\n  } catch {\n    // fall through\n  }\n  const cwdPkg = PATH.join(process.cwd(), 'package.json')\n  const cwdRequire = createRequire(cwdPkg)\n  try {\n    const pkgPath = cwdRequire.resolve('@xyo-network/xl1-cli/package.json')\n    const pkg = cwdRequire('@xyo-network/xl1-cli/package.json') as Xl1Pkg\n    return binFromPkg(pkgPath, pkg)\n  } catch (error) {\n    throw new Error(\n      '@ariestools/chain-serve-local-s3: @xyo-network/xl1-cli is not installed. '\n      + 'It is a runtime dependency of this package \u2014 reinstall node_modules.',\n      { cause: error },\n    )\n  }\n}\n", "import { DEFAULT_HEALTH_TIMEOUT_MS } from './constants.ts'\nimport type { StartLocalS3ChainOptions } from './startLocalS3Chain.ts'\nimport { startLocalS3Chain } from './startLocalS3Chain.ts'\nimport type { LocalS3Chain } from './types.ts'\n\n/** Minimal vitest (or jest) hook surface \u2014 avoids a hard vitest dependency. */\nexport interface TestLifecycleHooks {\n  afterAll: (fn: () => Promise<void> | void, timeout?: number) => void\n  beforeAll: (fn: () => Promise<void> | void, timeout?: number) => void\n}\n\nexport interface RegisterLocalS3ChainOptions extends StartLocalS3ChainOptions {\n  /** afterAll timeout ms. Default: 60_000. */\n  afterAllTimeoutMs?: number\n  /** beforeAll timeout ms. Default: healthTimeoutMs + 60_000. */\n  beforeAllTimeoutMs?: number\n}\n\n/**\n * Wire `startLocalS3Chain` into vitest (or any beforeAll/afterAll host).\n *\n * @example\n * ```ts\n * // vitest setupFile\n * import { afterAll, beforeAll } from 'vitest'\n * import { registerLocalS3Chain } from '@ariestools/chain-serve-local-s3'\n *\n * registerLocalS3Chain({ beforeAll, afterAll }, { assignGlobals: true })\n * ```\n */\nexport function registerLocalS3Chain(\n  hooks: TestLifecycleHooks,\n  options: RegisterLocalS3ChainOptions = {},\n): void {\n  const {\n    afterAllTimeoutMs = 60_000,\n    beforeAllTimeoutMs,\n    healthTimeoutMs = DEFAULT_HEALTH_TIMEOUT_MS,\n    ...startOptions\n  } = options\n\n  let chain: LocalS3Chain | undefined\n\n  hooks.beforeAll(async () => {\n    chain = await startLocalS3Chain({\n      healthTimeoutMs,\n      ...startOptions,\n    })\n  }, beforeAllTimeoutMs ?? healthTimeoutMs + 60_000)\n\n  hooks.afterAll(async () => {\n    await chain?.stop()\n    chain = undefined\n  }, afterAllTimeoutMs)\n}\n"],
+  "mappings": "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",
+  "names": ["PATH", "PATH"]
+}

package/dist/node/ports.d.ts

@@ -0,0 +1,3 @@
+/** Prefer `preferred` when free on every interface; otherwise an ephemeral port. */
+export declare function findAvailablePort(preferred: number): Promise<number>;
+//# sourceMappingURL=ports.d.ts.map

package/dist/node/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/ports.ts"],"names":[],"mappings":"AA4BA,oFAAoF;AACpF,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1E"}

package/dist/node/registerLocalS3Chain.d.ts

@@ -0,0 +1,26 @@
+import type { StartLocalS3ChainOptions } from './startLocalS3Chain.ts';
+/** Minimal vitest (or jest) hook surface — avoids a hard vitest dependency. */
+export interface TestLifecycleHooks {
+    afterAll: (fn: () => Promise<void> | void, timeout?: number) => void;
+    beforeAll: (fn: () => Promise<void> | void, timeout?: number) => void;
+}
+export interface RegisterLocalS3ChainOptions extends StartLocalS3ChainOptions {
+    /** afterAll timeout ms. Default: 60_000. */
+    afterAllTimeoutMs?: number;
+    /** beforeAll timeout ms. Default: healthTimeoutMs + 60_000. */
+    beforeAllTimeoutMs?: number;
+}
+/**
+ * Wire `startLocalS3Chain` into vitest (or any beforeAll/afterAll host).
+ *
+ * @example
+ * ```ts
+ * // vitest setupFile
+ * import { afterAll, beforeAll } from 'vitest'
+ * import { registerLocalS3Chain } from '@ariestools/chain-serve-local-s3'
+ *
+ * registerLocalS3Chain({ beforeAll, afterAll }, { assignGlobals: true })
+ * ```
+ */
+export declare function registerLocalS3Chain(hooks: TestLifecycleHooks, options?: RegisterLocalS3ChainOptions): void;
+//# sourceMappingURL=registerLocalS3Chain.d.ts.map

package/dist/node/registerLocalS3Chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerLocalS3Chain.d.ts","sourceRoot":"","sources":["../../src/registerLocalS3Chain.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAItE,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACpE,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACtE;AAED,MAAM,WAAW,2BAA4B,SAAQ,wBAAwB;IAC3E,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,2BAAgC,GACxC,IAAI,CAqBN"}

package/dist/node/resolveXl1Bin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve the `xl1` bin from `@xyo-network/xl1-cli`. Tries this package's
+ * dependency tree first, then the consumer project's cwd.
+ */
+export declare function resolveXl1Bin(): string;
+//# sourceMappingURL=resolveXl1Bin.d.ts.map

package/dist/node/resolveXl1Bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveXl1Bin.d.ts","sourceRoot":"","sources":["../../src/resolveXl1Bin.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CA2BtC"}

package/dist/node/startLocalS3Chain.d.ts

@@ -0,0 +1,44 @@
+import type { LocalS3Chain } from './types.ts';
+export type { LocalS3Chain, S3ReadUrls } from './types.ts';
+export interface StartLocalS3ChainOptions {
+    /**
+     * Preferred API port. Defaults to `8080 + Number(process.env.VITEST_WORKER_ID ?? 0)`.
+     * Falls back to an ephemeral port when the preferred port is busy.
+     */
+    apiPort?: number;
+    /**
+     * When true, also assign `apiPort`, `rpcUrl`, `chainId`, `blockProducerWallet`,
+     * `s3ReadUrls`, and `s3Endpoint` on `globalThis` (lifehash-style vitest globals).
+     */
+    assignGlobals?: boolean;
+    /** Chain id hex string. Default: {@link DEFAULT_CHAIN_ID}. */
+    chainId?: string;
+    /** API readiness timeout in ms. Default: 120_000. */
+    healthTimeoutMs?: number;
+    /** Pipe xl1 child stdout/stderr to process.stderr. Default: true. */
+    logXl1?: boolean;
+    /**
+     * Root mnemonic for xl1 actors and the genesis reward address.
+     * Default: insecure test phrase ({@link GENESIS_MNEMONIC}).
+     */
+    mnemonic?: string;
+    /** Silence the embedded s3rver logs. Default: true. */
+    silent?: boolean;
+}
+/**
+ * Boots a local XL1 test environment in one call:
+ *
+ * 1. `@ariestools/aries-chain-serve` — S3-compatible published-chain layout
+ *    (`/blocks`, `/state`, `/indexes`)
+ * 2. `@xyo-network/xl1-cli` — api + producer + finalizer + mempool + indexer,
+ *    publishing finalized blocks and index into that layout
+ *
+ * @example
+ * ```ts
+ * const chain = await startLocalS3Chain()
+ * // chain.rpcUrl, chain.s3ReadUrls, chain.blockProducerWallet, ...
+ * await chain.stop()
+ * ```
+ */
+export declare function startLocalS3Chain(options?: StartLocalS3ChainOptions): Promise<LocalS3Chain>;
+//# sourceMappingURL=startLocalS3Chain.d.ts.map

package/dist/node/startLocalS3Chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startLocalS3Chain.d.ts","sourceRoot":"","sources":["../../src/startLocalS3Chain.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,YAAY,CAAA;AAE1D,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE1D,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,YAAY,CAAC,CAoEvB"}

package/dist/node/startXl1.d.ts

@@ -0,0 +1,22 @@
+import type { ChildProcess } from 'node:child_process';
+import type { RunningChainServer } from '@ariestools/aries-chain-serve';
+export interface RunningXl1 {
+    apiPort: number;
+    chainId: string;
+    child: ChildProcess;
+    configDir: string;
+    rpcUrl: string;
+}
+export interface StartXl1Options {
+    apiPort: number;
+    chainId: string;
+    genesisRewardAddress: string;
+    healthPollMs?: number;
+    healthTimeoutMs?: number;
+    logXl1?: boolean;
+    mnemonic?: string;
+    s3: RunningChainServer;
+}
+export declare function startXl1(options: StartXl1Options): Promise<RunningXl1>;
+export declare function stopXl1(result: RunningXl1 | undefined): Promise<void>;
+//# sourceMappingURL=startXl1.d.ts.map

package/dist/node/startXl1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startXl1.d.ts","sourceRoot":"","sources":["../../src/startXl1.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAOtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAQvE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,YAAY,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,oBAAoB,EAAE,MAAM,CAAA;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,EAAE,EAAE,kBAAkB,CAAA;CACvB;AA6BD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAqF5E;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3E"}

package/dist/node/types.d.ts

@@ -0,0 +1,22 @@
+import type { AccountInstance } from '@xyo-network/sdk';
+export interface S3ReadUrls {
+    chainState: string;
+    finalized: string;
+    index: string;
+}
+/**
+ * Running local XL1 + published-chain S3 layout. Call `stop()` in teardown.
+ *
+ * DEV/TEST ONLY — accepts any S3 credentials, memory authority store, no auth.
+ */
+export interface LocalS3Chain {
+    apiPort: number;
+    /** Genesis reward / producer path-0 account (same mnemonic as the xl1 child). */
+    blockProducerWallet: AccountInstance;
+    chainId: string;
+    rpcUrl: string;
+    s3Endpoint: string;
+    s3ReadUrls: S3ReadUrls;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/node/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEvD,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,iFAAiF;IACjF,mBAAmB,EAAE,eAAe,CAAA;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,UAAU,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@ariestools/chain-serve-local-s3",
+  "version": "0.1.15",
+  "description": "One-call local XL1 test harness: published-chain S3 layout (s3rver) + xl1-cli (api/producer/finalizer/mempool/indexer)",
+  "keywords": [
+    "ariestools",
+    "xl1",
+    "xyo",
+    "chain",
+    "s3",
+    "s3rver",
+    "test",
+    "e2e",
+    "typescript"
+  ],
+  "homepage": "https://ariestools.ai",
+  "license": "LGPL-3.0-only",
+  "author": {
+    "name": "Arie Trouw",
+    "email": "support@ariestools.ai",
+    "url": "https://ariestools.ai"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@xyo-network/sdk": "~7.2.1",
+    "@xyo-network/xl1-cli": "~4.5.2",
+    "@xyo-network/xl1-sdk": "~4.6.0",
+    "@ariestools/aries-chain-serve": "~0.1.15"
+  },
+  "devDependencies": {
+    "@ariestools/sdk": "~8.1.4",
+    "@ariestools/tsconfig": "~8.7.23",
+    "@opentelemetry/api": "~1.9.1",
+    "@types/node": "~26.1.1",
+    "@xyo-network/sdk-protocol": "~7.2.2",
+    "async-mutex": "~0.5.0",
+    "ethers": "~6.17.0",
+    "typescript": "~6.0.3",
+    "vite": "~8.1.5",
+    "vitest": "~4.1.10",
+    "zod": "~4.4.3"
+  },
+  "engines": {
+    "node": ">=18.17.1"
+  },
+  "engineStrict": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "package-compile": "package-compile-only"
+  }
+}