@effectstream/orchestrator 0.100.9

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@effectstream/orchestrator",
+  "version": "0.100.9",
+  "license": "MIT",
+  "homepage": "https://effectstream.github.io/docs/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PaimaStudios/paima-engine",
+    "directory": "packages/build-tools/orchestrator"
+  },
+  "bugs": {
+    "url": "https://github.com/PaimaStudios/paima-engine/issues"
+  },
+  "exports": {
+    "./config": "./src/config.ts",
+    "./resolve-package": "./scripts/resolve-package.ts",
+    "./launch-pglite": "./scripts/launch-pglite.ts",
+    "./launch-evm": "./scripts/launch-evm.ts",
+    "./launch-bitcoin": "./scripts/launch-bitcoin.ts",
+    "./launch-cardano": "./scripts/launch-cardano.ts",
+    "./launch-midnight": "./scripts/launch-midnight.ts",
+    "./launch-avail": "./scripts/launch-avail.ts",
+    "./launch-near": "./scripts/launch-near.ts",
+    "./wait-tcp": "./scripts/wait-tcp.ts",
+    "./wait-http": "./scripts/wait-http.ts"
+  },
+  "bin": {
+    "orchestrator": "src/cli.ts"
+  },
+  "scripts": {
+    "start": "bun src/cli.ts start"
+  },
+  "dependencies": {
+    "@effectstream/db": "0.100.9"
+  },
+  "description": "Multi-chain local development environment for EffectStream"
+}

package/scripts/launch-avail.ts

@@ -0,0 +1,64 @@
+import type { ProcessConfig } from "../src/config.ts";
+import { resolvePackageDir } from "./resolve-package.ts";
+
+export const AvailNames = {
+  NODE: "avail-node",
+  NODE_WAIT: "avail-node-wait",
+  LIGHT_CLIENT_DEPLOY: "avail-light-client-deploy",
+  LIGHT_CLIENT_WAIT: "avail-light-client-wait",
+} as const;
+
+const REQUIRED_SCRIPTS = {
+  "avail-node:start": "Start the Avail dev node",
+  "avail-node:wait": "Wait for the Avail node RPC to be ready",
+  "avail-light-client:deploy": "Create app key and start the Avail light client",
+  "avail-light-client:wait": "Wait for the Avail light client to be ready",
+} as const;
+
+export function launchAvail(
+  packageName: string,
+  resolveFrom: string,
+  opts?: { nodePorts?: number[]; clientPorts?: number[] },
+): ProcessConfig[] {
+  const cwd = resolvePackageDir("launchAvail", packageName, resolveFrom, REQUIRED_SCRIPTS);
+  const nodePorts = opts?.nodePorts ?? [9955, 30334];
+  const clientPorts = opts?.clientPorts ?? [7007];
+
+  return [
+    {
+      name: AvailNames.NODE,
+      description: `Start Avail dev node (${packageName} avail-node:start)`,
+      cwd,
+      stopProcessAtPort: nodePorts,
+      args: ["run", "avail-node:start"],
+      waitToExit: false,
+      critical: true,
+    },
+    {
+      name: AvailNames.NODE_WAIT,
+      description: `Wait for Avail node (${packageName} avail-node:wait)`,
+      cwd,
+      args: ["run", "avail-node:wait"],
+      waitToExit: true,
+      dependsOn: [AvailNames.NODE],
+    },
+    {
+      name: AvailNames.LIGHT_CLIENT_DEPLOY,
+      description: `Deploy Avail light client (${packageName} avail-light-client:deploy)`,
+      cwd,
+      stopProcessAtPort: clientPorts,
+      args: ["run", "avail-light-client:deploy"],
+      waitToExit: false,
+      critical: true,
+      dependsOn: [AvailNames.NODE_WAIT],
+    },
+    {
+      name: AvailNames.LIGHT_CLIENT_WAIT,
+      description: `Wait for Avail light client (${packageName} avail-light-client:wait)`,
+      cwd,
+      args: ["run", "avail-light-client:wait"],
+      waitToExit: true,
+      dependsOn: [AvailNames.LIGHT_CLIENT_DEPLOY],
+    },
+  ];
+}

package/scripts/launch-bitcoin.ts

@@ -0,0 +1,62 @@
+import type { ProcessConfig } from "../src/config.ts";
+import { resolvePackageDir } from "./resolve-package.ts";
+
+export const BitcoinNames = {
+  BITCOIN_CORE: "bitcoin-core",
+  BITCOIN_CORE_WAIT: "bitcoin-core-wait",
+  BITCOIN_MINE_BLOCKS: "bitcoin-mine-blocks",
+  BITCOIN_WAIT_FOR_BLOCK: "bitcoin-wait-for-block",
+} as const;
+
+const REQUIRED_SCRIPTS = {
+  "chain:start": "Start Bitcoin Core in regtest mode",
+  "chain:wait": "Wait for Bitcoin Core RPC to be ready",
+  "generate:blocks": "Continuously generate regtest blocks",
+  "wait-for-block": "Wait until block height exceeds a threshold (e.g. > 100)",
+} as const;
+
+export function launchBitcoin(
+  packageName: string,
+  resolveFrom: string,
+  opts?: { ports?: number[] },
+): ProcessConfig[] {
+  const cwd = resolvePackageDir("launchBitcoin", packageName, resolveFrom, REQUIRED_SCRIPTS);
+  const ports = opts?.ports ?? [18334, 18443];
+
+  return [
+    {
+      stopProcessAtPort: ports,
+      name: BitcoinNames.BITCOIN_CORE,
+      description: `Start Bitcoin Core regtest node (${packageName} chain:start)`,
+      cwd,
+      args: ["run", "chain:start"],
+      waitToExit: false,
+      critical: true,
+    },
+    {
+      name: BitcoinNames.BITCOIN_CORE_WAIT,
+      description: `Wait for Bitcoin Core RPC (${packageName} chain:wait)`,
+      cwd,
+      args: ["run", "chain:wait"],
+      waitToExit: true,
+      dependsOn: [BitcoinNames.BITCOIN_CORE],
+    },
+    {
+      name: BitcoinNames.BITCOIN_MINE_BLOCKS,
+      description: `Generate blocks continuously (${packageName} generate:blocks)`,
+      cwd,
+      args: ["run", "generate:blocks"],
+      waitToExit: false,
+      type: "system-dependency",
+      dependsOn: [BitcoinNames.BITCOIN_CORE_WAIT],
+    },
+    {
+      name: BitcoinNames.BITCOIN_WAIT_FOR_BLOCK,
+      description: `Wait for block height > 100 (${packageName} wait-for-block)`,
+      cwd,
+      args: ["run", "wait-for-block"],
+      waitToExit: true,
+      dependsOn: [BitcoinNames.BITCOIN_MINE_BLOCKS],
+    },
+  ];
+}

package/scripts/launch-cardano.ts

@@ -0,0 +1,99 @@
+import type { ProcessConfig } from "../src/config.ts";
+import { resolvePackageDir } from "./resolve-package.ts";
+
+const waitHttpScript = new URL("./wait-http.ts", import.meta.url).pathname;
+
+export const CardanoNames = {
+  YACI_DEVKIT: "yaci-devkit",
+  YACI_DEVKIT_WAIT: "yaci-devkit-wait",
+  DOLOS_FILL_TEMPLATE: "dolos-fill-template",
+  DOLOS: "dolos",
+  DOLOS_WAIT: "dolos-wait",
+  DOLOS_MINIBF_WAIT: "dolos-minibf-wait",
+  CARDANO_SUBMIT_TX: "cardano-submit-tx",
+} as const;
+
+const REQUIRED_SCRIPTS = {
+  "devkit:start": "Start YACI DevKit (Cardano local devnet)",
+  "devkit:wait": "Wait for YACI DevKit to be ready",
+  "dolos:fill-template": "Generate Dolos config from YACI DevKit state",
+  "dolos:start": "Start Dolos relay node",
+  "dolos:wait": "Wait for Dolos gRPC to be ready",
+  "cardano-submit-tx": "Submit test transactions to the devnet",
+} as const;
+
+export function launchCardano(
+  packageName: string,
+  resolveFrom: string,
+  opts?: { ports?: number[] },
+): ProcessConfig[] {
+  const cwd = resolvePackageDir("launchCardano", packageName, resolveFrom, REQUIRED_SCRIPTS);
+  const ports = opts?.ports ?? [
+    8090,  // CARDANO_SUBMIT_TX: cardano-submit-api
+    10000, // YACI_DEVKIT: admin port
+    3001,  // YACI_DEVKIT: cardano-node
+    3000,  // DOLOS: minibf (blockfrost API)
+    50051, // DOLOS: gRPC
+  ];
+
+  return [
+    {
+      stopProcessAtPort: ports,
+      name: CardanoNames.YACI_DEVKIT,
+      description: `Start YACI DevKit (${packageName} devkit:start)`,
+      cwd,
+      args: ["run", "devkit:start"],
+      waitToExit: false,
+      type: "system-dependency",
+    },
+    {
+      name: CardanoNames.YACI_DEVKIT_WAIT,
+      description: `Wait for YACI DevKit (${packageName} devkit:wait)`,
+      cwd,
+      args: ["run", "devkit:wait"],
+      waitToExit: true,
+      dependsOn: [CardanoNames.YACI_DEVKIT],
+    },
+    {
+      name: CardanoNames.DOLOS_FILL_TEMPLATE,
+      description: `Generate Dolos config (${packageName} dolos:fill-template)`,
+      cwd,
+      args: ["run", "dolos:fill-template"],
+      waitToExit: true,
+      dependsOn: [CardanoNames.YACI_DEVKIT_WAIT],
+    },
+    {
+      name: CardanoNames.DOLOS,
+      description: `Start Dolos relay node (${packageName} dolos:start)`,
+      cwd,
+      args: ["run", "dolos:start"],
+      waitToExit: false,
+      type: "system-dependency",
+      dependsOn: [CardanoNames.DOLOS_FILL_TEMPLATE],
+    },
+    {
+      name: CardanoNames.DOLOS_WAIT,
+      description: `Wait for Dolos gRPC (${packageName} dolos:wait)`,
+      cwd,
+      args: ["run", "dolos:wait"],
+      waitToExit: true,
+      dependsOn: [CardanoNames.DOLOS],
+    },
+    {
+      name: CardanoNames.DOLOS_MINIBF_WAIT,
+      description: "Wait for Dolos blockfrost API on port 3000",
+      args: [waitHttpScript, "--timeout", "60000", "http://localhost:3000/blocks/latest"],
+      waitToExit: true,
+      dependsOn: [CardanoNames.DOLOS_WAIT],
+    },
+    {
+      name: CardanoNames.CARDANO_SUBMIT_TX,
+      description: `Submit test transactions (${packageName} cardano-submit-tx)`,
+      cwd,
+      args: ["run", "cardano-submit-tx"],
+      waitToExit: true,
+      critical: true,
+      dependsOn: [CardanoNames.YACI_DEVKIT_WAIT],
+    },
+  ];
+}

package/scripts/launch-evm.ts

@@ -0,0 +1,72 @@
+import type { ProcessConfig } from "../src/config.ts";
+import { resolvePackageDir } from "./resolve-package.ts";
+
+export const EvmNames = {
+  HARDHAT: "hardhat",
+  HARDHAT_WAIT: "hardhat-wait",
+  COMPILE: "compile-evm-contracts",
+  DEPLOY: "deploy-evm-contracts",
+  GENERATE_MOD: "generate-evm-mod",
+} as const;
+
+const REQUIRED_SCRIPTS = {
+  "chain:start": "Start the Hardhat node (e.g. `bun ./node_modules/.bin/hardhat node`)",
+  "chain:wait": "Wait for the Hardhat node to be ready (e.g. `bun ./node_modules/.bin/hardhat node wait`)",
+  "build:hardhat": "Compile Solidity contracts with Hardhat (e.g. `hardhat compile`)",
+  "deploy": "Deploy compiled contracts to the running chain (e.g. via Hardhat Ignition)",
+} as const;
+
+export function launchEvm(
+  packageName: string,
+  resolveFrom: string,
+  opts?: { ports?: number[] },
+): ProcessConfig[] {
+  const cwd = resolvePackageDir("launchEvm", packageName, resolveFrom, REQUIRED_SCRIPTS);
+  const ports = opts?.ports ?? [8545, 8546];
+
+  return [
+    {
+      stopProcessAtPort: ports,
+      name: EvmNames.HARDHAT,
+      description: `Start the Hardhat node (${packageName} chain:start)`,
+      cwd,
+      args: ["run", "chain:start"],
+      waitToExit: false,
+      critical: true,
+    },
+    {
+      name: EvmNames.HARDHAT_WAIT,
+      description: `Wait for the Hardhat node to be ready (${packageName} chain:wait)`,
+      cwd,
+      args: ["run", "chain:wait"],
+      waitToExit: true,
+      dependsOn: [EvmNames.HARDHAT],
+    },
+    {
+      name: EvmNames.COMPILE,
+      description: `Compile Solidity contracts (${packageName} build:hardhat)`,
+      cwd,
+      args: ["run", "build:hardhat"],
+      waitToExit: true,
+      critical: true,
+    },
+    {
+      name: EvmNames.DEPLOY,
+      description: `Deploy contracts to the running chain (${packageName} deploy)`,
+      cwd,
+      args: ["run", "deploy"],
+      waitToExit: true,
+      critical: true,
+      dependsOn: [EvmNames.HARDHAT_WAIT, EvmNames.COMPILE],
+    },
+    {
+      name: EvmNames.GENERATE_MOD,
+      description: `Generate TypeScript bindings from deployed contracts (${packageName})`,
+      cwd,
+      args: ["-e", "const fs=await import('node:fs');await fs.promises.mkdir('./build',{recursive:true});await fs.promises.writeFile('./build/mod.ts','export {};\\n');await import('@effectstream/evm-hardhat/builder')"],
+      waitToExit: true,
+      critical: true,
+      dependsOn: [EvmNames.DEPLOY],
+    },
+  ];
+}

package/scripts/launch-midnight.ts

@@ -0,0 +1,108 @@
+import type { ProcessConfig } from "../src/config.ts";
+import { resolvePackageDir } from "./resolve-package.ts";
+
+export const MidnightNames = {
+  NODE: "midnight-node",
+  NODE_WAIT: "midnight-node-wait",
+  INDEXER: "midnight-indexer",
+  INDEXER_WAIT: "midnight-indexer-wait",
+  PROOF_SERVER: "midnight-proof-server",
+  PROOF_SERVER_WAIT: "midnight-proof-server-wait",
+  CONTRACT_DEPLOY: "midnight-contract",
+} as const;
+
+const REQUIRED_SCRIPTS = {
+  "midnight-node:start": "Start the Midnight substrate node",
+  "midnight-node:wait": "Wait for the Midnight node RPC (e.g. tcp:9944)",
+  "midnight-indexer:start": "Start the Midnight indexer",
+  "midnight-indexer:wait": "Wait for the Midnight indexer (e.g. tcp:8088)",
+  "midnight-proof-server:start": "Start the Midnight proof server",
+  "midnight-proof-server:wait": "Wait for the Midnight proof server (e.g. tcp:6300)",
+  "midnight-contract:deploy": "Deploy Midnight contracts (Compact-compiled)",
+} as const;
+
+export function launchMidnight(
+  packageName: string,
+  resolveFrom: string,
+  opts?: {
+    env?: { MIDNIGHT_STORAGE_PASSWORD?: string };
+    dependsOn?: string[];
+  },
+): ProcessConfig[] {
+  const cwd = resolvePackageDir("launchMidnight", packageName, resolveFrom, REQUIRED_SCRIPTS);
+  const deployEnv: Record<string, string> = {};
+  if (opts?.env?.MIDNIGHT_STORAGE_PASSWORD) {
+    deployEnv.MIDNIGHT_STORAGE_PASSWORD = opts.env.MIDNIGHT_STORAGE_PASSWORD;
+  }
+  const extraDeps = opts?.dependsOn ?? [];
+
+  return [
+    {
+      name: MidnightNames.NODE,
+      description: `Start Midnight node (${packageName} midnight-node:start)`,
+      cwd,
+      stopProcessAtPort: [9944, 30333],
+      args: ["run", "midnight-node:start"],
+      waitToExit: false,
+      critical: true,
+    },
+    {
+      name: MidnightNames.INDEXER,
+      description: `Start Midnight indexer (${packageName} midnight-indexer:start)`,
+      cwd,
+      stopProcessAtPort: [8088],
+      args: ["run", "midnight-indexer:start"],
+      waitToExit: false,
+      critical: true,
+      dependsOn: [MidnightNames.NODE],
+    },
+    {
+      name: MidnightNames.PROOF_SERVER,
+      description: `Start Midnight proof server (${packageName} midnight-proof-server:start)`,
+      cwd,
+      stopProcessAtPort: [6300],
+      args: ["run", "midnight-proof-server:start"],
+      waitToExit: false,
+      critical: true,
+      dependsOn: [MidnightNames.NODE],
+    },
+    {
+      name: MidnightNames.NODE_WAIT,
+      description: `Wait for Midnight node (${packageName} midnight-node:wait)`,
+      cwd,
+      args: ["run", "midnight-node:wait"],
+      waitToExit: true,
+      dependsOn: [MidnightNames.NODE],
+    },
+    {
+      name: MidnightNames.INDEXER_WAIT,
+      description: `Wait for Midnight indexer (${packageName} midnight-indexer:wait)`,
+      cwd,
+      args: ["run", "midnight-indexer:wait"],
+      waitToExit: true,
+      dependsOn: [MidnightNames.INDEXER],
+    },
+    {
+      name: MidnightNames.PROOF_SERVER_WAIT,
+      description: `Wait for Midnight proof server (${packageName} midnight-proof-server:wait)`,
+      cwd,
+      args: ["run", "midnight-proof-server:wait"],
+      waitToExit: true,
+      dependsOn: [MidnightNames.PROOF_SERVER],
+    },
+    {
+      name: MidnightNames.CONTRACT_DEPLOY,
+      description: `Deploy Midnight contracts (${packageName} midnight-contract:deploy)`,
+      cwd,
+      args: ["run", "midnight-contract:deploy"],
+      ...(Object.keys(deployEnv).length > 0 ? { env: deployEnv } : {}),
+      waitToExit: true,
+      dependsOn: [
+        MidnightNames.NODE_WAIT,
+        MidnightNames.INDEXER_WAIT,
+        MidnightNames.PROOF_SERVER_WAIT,
+        ...extraDeps,
+      ],
+    },
+  ];
+}

package/scripts/launch-near.ts

@@ -0,0 +1,41 @@
+import type { ProcessConfig } from "../src/config.ts";
+import { resolvePackageDir } from "./resolve-package.ts";
+
+export const NearNames = {
+  SANDBOX: "near-sandbox",
+  SANDBOX_WAIT: "near-sandbox-wait",
+} as const;
+
+const REQUIRED_SCRIPTS = {
+  "chain:start": "Start the NEAR sandbox node",
+  "chain:wait": "Wait for the NEAR sandbox RPC to be ready (e.g. tcp:3030)",
+} as const;
+
+export function launchNear(
+  packageName: string,
+  resolveFrom: string,
+  opts?: { ports?: number[] },
+): ProcessConfig[] {
+  const cwd = resolvePackageDir("launchNear", packageName, resolveFrom, REQUIRED_SCRIPTS);
+  const ports = opts?.ports ?? [3030];
+
+  return [
+    {
+      stopProcessAtPort: ports,
+      name: NearNames.SANDBOX,
+      description: `Start NEAR sandbox node (${packageName} chain:start)`,
+      cwd,
+      args: ["run", "chain:start"],
+      waitToExit: false,
+      critical: true,
+    },
+    {
+      name: NearNames.SANDBOX_WAIT,
+      description: `Wait for NEAR sandbox RPC (${packageName} chain:wait)`,
+      cwd,
+      args: ["run", "chain:wait"],
+      waitToExit: true,
+      dependsOn: [NearNames.SANDBOX],
+    },
+  ];
+}

package/scripts/launch-pglite.ts

@@ -0,0 +1,30 @@
+import type { ProcessConfig } from "../src/config.ts";
+
+const waitTcpScript = new URL("./wait-tcp.ts", import.meta.url).pathname;
+const startPgliteScript = import.meta.resolve("@effectstream/db/start-pglite").replace("file://", "");
+
+export const DbNames = {
+  PGLITE: "pglite",
+  PGLITE_WAIT: "pglite-wait",
+} as const;
+
+export function launchPglite(opts?: { port?: number }): ProcessConfig[] {
+  const port = opts?.port ?? 5432;
+  return [
+    {
+      name: DbNames.PGLITE,
+      description: `PGLite embedded database (port ${port})`,
+      args: [startPgliteScript, "--port", String(port)],
+      stopProcessAtPort: [port],
+      waitToExit: false,
+      critical: true,
+    },
+    {
+      name: DbNames.PGLITE_WAIT,
+      description: `Wait for PGLite on port ${port}`,
+      args: [waitTcpScript, String(port)],
+      waitToExit: true,
+      dependsOn: [DbNames.PGLITE],
+    },
+  ];
+}

package/scripts/resolve-package.ts

@@ -0,0 +1,42 @@
+import fs from "fs";
+import path from "path";
+
+function resolveEntry(packageName: string, resolveFrom: string): string {
+  try {
+    return require.resolve(packageName, { paths: [resolveFrom] });
+  } catch {
+    return require.resolve(`${packageName}/package.json`, { paths: [resolveFrom] });
+  }
+}
+
+export function resolvePackageDir(
+  launcherName: string,
+  packageName: string,
+  resolveFrom: string,
+  requiredScripts: Record<string, string>,
+): string {
+  const resolved = resolveEntry(packageName, resolveFrom);
+  let dir = path.dirname(resolved);
+  while (dir !== path.dirname(dir)) {
+    const pkgJsonPath = path.join(dir, "package.json");
+    if (!fs.existsSync(pkgJsonPath)) { dir = path.dirname(dir); continue; }
+
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+    if (pkg.name !== packageName) { dir = path.dirname(dir); continue; }
+
+    const scripts = pkg.scripts ?? {};
+    const required = Object.keys(requiredScripts);
+    const missing = required.filter((s) => !(s in scripts));
+    if (missing.length > 0) {
+      throw new Error(
+        `${launcherName}: package "${packageName}" is missing required scripts: ${missing.join(", ")}\n` +
+          `  This launcher expects the following scripts in package.json:\n` +
+          missing.map((s) => `    - ${s}: ${requiredScripts[s]}`).join("\n"),
+      );
+    }
+    return dir;
+  }
+  throw new Error(
+    `${launcherName}: could not find package.json for "${packageName}" (resolved to "${resolved}")`,
+  );
+}

package/scripts/wait-http.ts

@@ -0,0 +1,24 @@
+const url = process.argv.at(-1);
+if (!url || !url.startsWith("http")) {
+  console.error("Usage: bun wait-http.ts <url>");
+  process.exit(1);
+}
+
+const timeout = Number(process.argv.includes("--timeout")
+  ? process.argv[process.argv.indexOf("--timeout") + 1]
+  : 60000);
+
+const start = Date.now();
+
+while (Date.now() - start < timeout) {
+  try {
+    const res = await fetch(url);
+    if (res.ok) process.exit(0);
+  } catch {
+    // not ready yet
+  }
+  await Bun.sleep(500);
+}
+
+console.error(`Timed out waiting for ${url}`);
+process.exit(1);

package/scripts/wait-tcp.ts

@@ -0,0 +1,30 @@
+const port = Number(process.argv.at(-1));
+if (!port || isNaN(port)) {
+  console.error("Usage: bun wait-tcp.ts <port>");
+  process.exit(1);
+}
+
+for (let i = 0; i < 120; i++) {
+  try {
+    const connected = await new Promise<boolean>((resolve) => {
+      Bun.connect({
+        hostname: "127.0.0.1",
+        port,
+        socket: {
+          open(socket) { socket.end(); resolve(true); },
+          data() {},
+          error() { resolve(false); },
+          close() {},
+          connectError() { resolve(false); },
+        },
+      }).catch(() => resolve(false));
+    });
+    if (connected) process.exit(0);
+  } catch {
+    // fallthrough to retry
+  }
+  await Bun.sleep(500);
+}
+
+console.error(`Timed out waiting for tcp:${port}`);
+process.exit(1);