@effectstream/orchestrator 0.100.15 → 0.100.17

package/README.md

@@ -1,12 +1,17 @@
 # @effectstream/orchestrator
 
 A multi-chain local development environment for EffectStream. One CLI
-starts every dependency a template needs — Postgres / PgLite, Hardhat,
+starts every dependency a template needs - Postgres / PgLite, Hardhat,
 contracts, Bitcoin Core, Midnight node + indexer + proof server,
 Cardano-side services, Avail node + light client, NEAR sandbox,
-Celestia, plus the EffectStream sync + runtime + batcher — in the right
+Celestia, plus the EffectStream sync + runtime + batcher - in the right
 order, with health checks.
 
+- One CLI that starts every dependency a template needs: DB, chains, sync, runtime, batcher.
+- Dependency-graph aware: runs in parallel where it can, sequential where it must.
+- Disable any chain with `DISABLE_EVM=true`, `DISABLE_BITCOIN=true`, ...
+- Used by every template in this repo and by the E2E runner.
+
 ## Install
 
 ```bash
@@ -64,8 +69,10 @@ export const config: OrchestratorConfig = {
 
 Common chain launchers ship as subpath scripts you can compose: `./launch-pglite`,
 `./launch-evm`, `./launch-bitcoin`, `./launch-cardano`, `./launch-midnight`,
-`./launch-avail`, `./launch-near`. Each wraps a pinned binary from
-`@effectstream/binaries/*` with sensible defaults.
+`./launch-avail`, `./launch-near`. Each wraps a pinned binary from a
+package under `packages/binaries/` (e.g. `@effectstream/npm-midnight-node`,
+`@effectstream/bitcoin-core`, `@effectstream/near-sandbox`) with sensible
+defaults.
 
 > **Tip:** Disable chains you don't need with env vars: `DISABLE_EVM=true`,
 > `DISABLE_BITCOIN=true`, `DISABLE_MIDNIGHT=true`, etc. Same flags work for
@@ -90,27 +97,27 @@ Global flags:
 ## Inside EffectStream
 
 Every template under
-[`templates/`](https://github.com/PaimaStudios/paima-engine/tree/main/templates)
+[`templates/`](https://github.com/effectstream/effectstream/tree/main/templates)
 defines an `orchestrator.config.ts` (or `.json`) and starts dev with one
 command. The E2E runner at
-[`e2e/runner.ts`](https://github.com/PaimaStudios/paima-engine/blob/main/e2e/runner.ts)
+[`e2e/runner.ts`](https://github.com/effectstream/effectstream/blob/main/e2e/runner.ts)
 is the same machinery, serialised across nine chain suites.
 
 ## Key subpath exports
 
-- `@effectstream/orchestrator/config` — `OrchestratorConfig`, `ProcessConfig` types.
-- `@effectstream/orchestrator/resolve-package` — resolve a package's bin to an absolute path (used by launcher scripts).
-- `@effectstream/orchestrator/launch-pglite`, `./launch-evm`, `./launch-bitcoin`, `./launch-cardano`, `./launch-midnight`, `./launch-avail`, `./launch-near` — opinionated launcher scripts for each chain.
-- `@effectstream/orchestrator/wait-tcp`, `./wait-http` — readiness-check helpers.
+- `@effectstream/orchestrator/config` - `OrchestratorConfig`, `ProcessConfig` types.
+- `@effectstream/orchestrator/resolve-package` - resolve a package's bin to an absolute path (used by launcher scripts).
+- `@effectstream/orchestrator/launch-pglite`, `./launch-evm`, `./launch-bitcoin`, `./launch-cardano`, `./launch-midnight`, `./launch-avail`, `./launch-near` - opinionated launcher scripts for each chain.
+- `@effectstream/orchestrator/wait-tcp`, `./wait-http` - readiness-check helpers.
 
 ## Examples
 
-- Templates: every directory under [`templates/`](https://github.com/PaimaStudios/paima-engine/tree/main/templates) ships a working orchestrator config.
-- E2E: [`e2e/`](https://github.com/PaimaStudios/paima-engine/tree/main/e2e) drives the orchestrator under the hood.
+- Templates: every directory under [`templates/`](https://github.com/effectstream/effectstream/tree/main/templates) ships a working orchestrator config.
+- E2E: [`e2e/`](https://github.com/effectstream/effectstream/tree/main/e2e) drives the orchestrator under the hood.
 
 Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
 
 ## Links
 
 - Docs: https://effectstream.github.io/docs/packages/tools/orchestrator
-- Source: https://github.com/PaimaStudios/paima-engine/tree/main/packages/build-tools/orchestrator
+- Source: https://github.com/effectstream/effectstream/tree/main/packages/build-tools/orchestrator

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@effectstream/orchestrator",
-  "version": "0.100.15",
+  "version": "0.100.17",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/PaimaStudios/paima-engine",
+    "url": "https://github.com/effectstream/effectstream",
     "directory": "packages/build-tools/orchestrator"
   },
   "bugs": {
-    "url": "https://github.com/PaimaStudios/paima-engine/issues"
+    "url": "https://github.com/effectstream/effectstream/issues"
   },
   "exports": {
     "./config": "./src/config.ts",
@@ -20,6 +20,7 @@
     "./launch-cardano": "./scripts/launch-cardano.ts",
     "./launch-midnight": "./scripts/launch-midnight.ts",
     "./launch-avail": "./scripts/launch-avail.ts",
+    "./launch-celestia": "./scripts/launch-celestia.ts",
     "./launch-near": "./scripts/launch-near.ts",
     "./wait-tcp": "./scripts/wait-tcp.ts",
     "./wait-http": "./scripts/wait-http.ts"
@@ -31,7 +32,7 @@
     "start": "bun src/cli.ts start"
   },
   "dependencies": {
-    "@effectstream/db": "0.100.15"
+    "@effectstream/db": "0.100.17"
   },
   "description": "Multi-chain local development environment for EffectStream"
 }

package/scripts/launch-celestia.ts

@@ -0,0 +1,67 @@
+import type { ProcessConfig } from "../src/config.ts";
+import { resolvePackageDir, type ResolveLocation } from "./resolve-package.ts";
+
+export const CelestiaNames = {
+  CLEAN:       "celestia-clean",
+  DEVNET:      "celestia-devnet",
+  BRIDGE_WAIT: "celestia-bridge-wait",
+  FUND:        "celestia-fund-bridge",
+} as const;
+
+const REQUIRED_SCRIPTS = {
+  "celestia-bridge:start": "Start the Celestia consensus node + bridge",
+  "celestia-bridge:wait":  "Wait for the Celestia bridge RPC to be ready",
+  "celestia-fund:bridge":  "Fund the bridge node wallet with tokens",
+} as const;
+
+export function launchCelestia(
+  packageName: string,
+  location: ResolveLocation,
+  opts?: { ports?: number[]; home?: string },
+): ProcessConfig[] {
+  const cwd   = resolvePackageDir("launchCelestia", packageName, location, REQUIRED_SCRIPTS);
+  const ports = opts?.ports ?? [26657, 26658];
+  const home  = opts?.home  ?? "/tmp/celestia-home";
+
+  const cleanScript =
+    `await import('fs').then(fs => { try { fs.rmSync('${home}', { recursive: true, force: true }); } catch {} }); console.log('Celestia home cleaned');`;
+
+  return [
+    {
+      name: CelestiaNames.CLEAN,
+      description: "Remove stale Celestia devnet data",
+      args: ["-e", cleanScript],
+      waitToExit: true,
+    },
+    {
+      name: CelestiaNames.DEVNET,
+      description: `Celestia consensus node + bridge (${packageName} celestia-bridge:start)`,
+      cwd,
+      stopProcessAtPort: ports,
+      args: ["run", "celestia-bridge:start"],
+      env: { CELESTIA_HOME: home, CELESTIA_FORCE_NO_BBR: "1" },
+      waitToExit: false,
+      critical: true,
+      silent: true,
+      dependsOn: [CelestiaNames.CLEAN],
+    },
+    {
+      name: CelestiaNames.BRIDGE_WAIT,
+      description: `Wait for Celestia bridge RPC (${packageName} celestia-bridge:wait)`,
+      cwd,
+      args: ["run", "celestia-bridge:wait"],
+      waitToExit: true,
+      dependsOn: [CelestiaNames.DEVNET],
+    },
+    {
+      name: CelestiaNames.FUND,
+      description: `Fund the Celestia bridge wallet (${packageName} celestia-fund:bridge)`,
+      cwd,
+      args: ["run", "celestia-fund:bridge"],
+      env: { CELESTIA_HOME: home },
+      waitToExit: true,
+      critical: true,
+      dependsOn: [CelestiaNames.BRIDGE_WAIT],
+    },
+  ];
+}

package/scripts/launch-evm.ts

@@ -1,10 +1,35 @@
+import { spawnSync } from "node:child_process";
 import type { ProcessConfig } from "../src/config.ts";
 import { resolvePackageDir, type ResolveLocation } from "./resolve-package.ts";
 
+/**
+ * Foundry's `forge` is required to compile the EVM contracts (the mod builder
+ * derives the TypeScript bindings from the Forge artifacts). It is a system
+ * toolchain, not an npm dependency, so verify it is on PATH up front and stop
+ * with an actionable message instead of letting `build:forge` die with a
+ * cryptic "command not found" (exit 127) mid-run.
+ */
+function assertForgeInstalled(): void {
+  const found = spawnSync("forge", ["--version"], { stdio: "ignore" });
+  if (found.status === 0) return;
+  throw new Error(
+    [
+      "",
+      "Foundry's `forge` was not found on your PATH, but it is required to compile the EVM contracts.",
+      "",
+      "  Install Foundry from:  https://www.getfoundry.sh/",
+      "",
+      "  (quick install)        curl -L https://foundry.paradigm.xyz | bash && foundryup",
+      "",
+    ].join("\n"),
+  );
+}
+
 export const EvmNames = {
   HARDHAT: "hardhat",
   HARDHAT_WAIT: "hardhat-wait",
   COMPILE: "compile-evm-contracts",
+  COMPILE_FORGE: "compile-evm-contracts-forge",
   DEPLOY: "deploy-evm-contracts",
   GENERATE_MOD: "generate-evm-mod",
 } as const;
@@ -13,6 +38,7 @@ 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`)",
+  "build:forge": "Compile Solidity contracts with Forge (e.g. `forge build`) — produces the artifacts the mod builder reads",
   "deploy": "Deploy compiled contracts to the running chain (e.g. via Hardhat Ignition)",
 } as const;
 
@@ -22,6 +48,7 @@ export function launchEvm(
   opts?: { ports?: number[] },
 ): ProcessConfig[] {
   const cwd = resolvePackageDir("launchEvm", packageName, location, REQUIRED_SCRIPTS);
+  assertForgeInstalled();
   const ports = opts?.ports ?? [8545, 8546];
 
   return [
@@ -44,12 +71,25 @@ export function launchEvm(
     },
     {
       name: EvmNames.COMPILE,
-      description: `Compile Solidity contracts (${packageName} build:hardhat)`,
+      description: `Compile Solidity contracts with Hardhat (${packageName} build:hardhat)`,
       cwd,
       args: ["run", "build:hardhat"],
       waitToExit: true,
       critical: true,
     },
+    {
+      // Serialized after Hardhat: both scripts rewrite the shared remappings.txt,
+      // so running them concurrently would race. The mod builder reads only the
+      // Forge artifacts (build/artifacts/forge), so this step is required for the
+      // TypeScript bindings to be generated.
+      name: EvmNames.COMPILE_FORGE,
+      description: `Compile Solidity contracts with Forge (${packageName} build:forge)`,
+      cwd,
+      args: ["run", "build:forge"],
+      waitToExit: true,
+      critical: true,
+      dependsOn: [EvmNames.COMPILE],
+    },
     {
       name: EvmNames.DEPLOY,
       description: `Deploy contracts to the running chain (${packageName} deploy)`,
@@ -63,10 +103,10 @@ export function launchEvm(
       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')"],
+      args: ["-e", "await import('@effectstream/evm-hardhat/builder')"],
       waitToExit: true,
       critical: true,
-      dependsOn: [EvmNames.DEPLOY],
+      dependsOn: [EvmNames.DEPLOY, EvmNames.COMPILE_FORGE],
     },
   ];
 }

package/scripts/launch-midnight.ts

@@ -1,6 +1,31 @@
+import { spawnSync } from "node:child_process";
 import type { ProcessConfig } from "../src/config.ts";
 import { resolvePackageDir, type ResolveLocation } from "./resolve-package.ts";
 
+/**
+ * Midnight's `compact` compiler is required to compile the Compact contracts
+ * (the midnight-contract:deploy step). It is a system toolchain, not an npm
+ * dependency, so verify it is on PATH up front and stop with an actionable
+ * message instead of failing with a cryptic "command not found" mid-deploy.
+ * Install tips mirror .github/Dockerfile.
+ */
+function assertCompactInstalled(): void {
+  const found = spawnSync("compact", ["--version"], { stdio: "ignore" });
+  if (found.status === 0) return;
+  throw new Error(
+    [
+      "",
+      "Midnight's `compact` compiler was not found on your PATH, but it is required to compile the Midnight contracts.",
+      "",
+      "  Install Compact from:  https://github.com/midnightntwrk/compact",
+      "",
+      "  (quick install)        curl --proto '=https' --tlsv1.2 -LsSf https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh",
+      "                         compact update 0.30.0",
+      "",
+    ].join("\n"),
+  );
+}
+
 export const MidnightNames = {
   NODE: "midnight-node",
   NODE_WAIT: "midnight-node-wait",
@@ -30,6 +55,7 @@ export function launchMidnight(
   },
 ): ProcessConfig[] {
   const cwd = resolvePackageDir("launchMidnight", packageName, location, REQUIRED_SCRIPTS);
+  assertCompactInstalled();
   const deployEnv: Record<string, string> = {};
   if (opts?.env?.MIDNIGHT_STORAGE_PASSWORD) {
     deployEnv.MIDNIGHT_STORAGE_PASSWORD = opts.env.MIDNIGHT_STORAGE_PASSWORD;