@xyo-network/chain-orchestration 1.20.27 → 1.20.29

package/dist/browser/index.mjs

@@ -4,7 +4,201 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 // src/shared/actor/FinalizerActor.ts
 import { creatable } from "@xylabs/sdk-js";
 import { processPendingBlocks } from "@xyo-network/chain-sdk";
-import { ActorV3, BlockValidationViewerMoniker, BlockViewerMoniker, DeadLetterQueueRunnerMoniker, FinalizationRunnerMoniker, MempoolViewerMoniker } from "@xyo-network/xl1-sdk";
+import { BlockValidationViewerMoniker, BlockViewerMoniker, DeadLetterQueueRunnerMoniker, FinalizationRunnerMoniker, MempoolViewerMoniker } from "@xyo-network/xl1-sdk";
+
+// src/shared/actor/v3/ActorV3.ts
+import { AbstractCreatable, assertEx, delay, IdLogger } from "@xylabs/sdk-js";
+import { Semaphore } from "async-mutex";
+import z from "zod";
+var CreatableNameZod = z.custom((val) => typeof val === "string" && val.length > 0);
+var StatusReporterInstanceZod = z.custom((val) => val !== null && typeof val === "object" && "report" in val);
+var AccountInstanceZod = z.custom((val) => val !== null && typeof val === "object" && "address" in val);
+var ActorParamsV3Zod = z.object({
+  account: AccountInstanceZod,
+  locator: z.unknown(),
+  name: CreatableNameZod,
+  statusReporter: StatusReporterInstanceZod.optional()
+});
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return {
+    promise,
+    resolve,
+    reject
+  };
+}
+__name(createDeferred, "createDeferred");
+var ActorV3 = class extends AbstractCreatable {
+  static {
+    __name(this, "ActorV3");
+  }
+  _intervals = /* @__PURE__ */ new Map();
+  _semaphores = /* @__PURE__ */ new Map();
+  _timeouts = /* @__PURE__ */ new Map();
+  _logger;
+  _readyDeferred = createDeferred();
+  _readyError;
+  _readyState = "pending";
+  get logger() {
+    this._logger = new IdLogger(assertEx(this.context.logger, () => `Logger is required in context for actor ${this.name}.`), () => this.name);
+    return this._logger;
+  }
+  get readyError() {
+    return this._readyError;
+  }
+  get readyState() {
+    return this._readyState;
+  }
+  get account() {
+    return this.params.account;
+  }
+  get context() {
+    return this.locator.context;
+  }
+  get locator() {
+    return this.params.locator;
+  }
+  static async paramsHandler(params) {
+    const baseParams = await super.paramsHandler({
+      ...params,
+      name: params.name ?? "UnknownActor"
+    });
+    const account = assertEx(params.account, () => `params.account is required for actor ${baseParams.name}.`);
+    const locator = assertEx(params.locator, () => `params.locator is required for actor ${baseParams.name}.`);
+    return {
+      ...baseParams,
+      account,
+      locator
+    };
+  }
+  /**
+  * The timer runs until the actor is deactivated (or you manually stop it).
+  */
+  registerTimer(timerName, callback, dueTimeMs, periodMs) {
+    if (this.status !== "starting") {
+      this.logger?.warn(`Cannot register timer '${timerName}' because actor is not starting.`);
+      return;
+    }
+    let running = false;
+    this._semaphores.set(timerName, new Semaphore(1));
+    const timeoutId = setTimeout(() => {
+      const intervalId = setInterval(() => {
+        const semaphore = this._semaphores.get(timerName);
+        if (this.status !== "started" || !this._intervals.has(timerName) || !semaphore || running) return;
+        if (semaphore.isLocked()) {
+          this.logger?.warn(`Skipping timer '${this.name}:${timerName}' execution because previous execution is still running.`);
+          return;
+        }
+        semaphore.acquire().then(([, release]) => {
+          const startTime = Date.now();
+          running = true;
+          callback().then(() => {
+            const duration = Date.now() - startTime;
+            if (duration > periodMs) {
+              this.logger?.warn(`Timer '${this.name}:${timerName}' execution took longer (${duration}ms) than the period (${periodMs}ms).`);
+            } else if (duration > 5e3) {
+              this.logger?.warn(`Timer '${this.name}:${timerName}' execution took longer (${duration}ms) than 5000ms.`);
+            }
+          }).catch((error) => {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger?.error(`Error in timer '${this.name}:${timerName}': ${err.message}`);
+            if (err.stack) this.logger?.error(err.stack);
+          }).finally(() => {
+            release();
+            running = false;
+          });
+        }).catch((error) => {
+          const err = error instanceof Error ? error : new Error(String(error));
+          this.logger?.error(`Error acquiring semaphore for timer '${this.name}:${timerName}': ${err.message}`);
+        });
+      }, periodMs);
+      this._intervals.set(timerName, intervalId);
+    }, dueTimeMs);
+    this._timeouts.set(timerName, timeoutId);
+    this.logger?.debug(`Timer '${this.name}:${timerName}' registered: first call after ${dueTimeMs}ms, recurring every ${periodMs}ms.`);
+  }
+  /**
+  * Invoked by the Orchestrator after `start()` to run the warm-pass.
+  * Idempotent: returns immediately if already invoked.
+  * Throws if `readyHandler` throws; resolves once `readyHandler` resolves.
+  */
+  async runReadyHandler() {
+    if (this._readyState !== "pending") return;
+    try {
+      await this.readyHandler();
+      this._readyState = "ready";
+      this._readyDeferred.resolve();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this._readyState = "failed";
+      this._readyError = error;
+      this._readyDeferred.reject(error);
+      throw error;
+    }
+  }
+  async stopHandler() {
+    await super.stopHandler();
+    this.logger?.debug("Stopping all timers...");
+    await Promise.all([
+      ...this._semaphores.values()
+    ].map(async (semaphore) => {
+      while (semaphore.isLocked()) {
+        this.logger?.debug("Waiting for running timer task to complete...");
+        await delay(500);
+      }
+      await semaphore.acquire();
+    }));
+    this._semaphores.clear();
+    for (const [, timeoutRef] of this._timeouts.entries()) {
+      clearTimeout(timeoutRef);
+    }
+    this._timeouts.clear();
+    for (const [, intervalRef] of this._intervals.entries()) {
+      clearInterval(intervalRef);
+    }
+    this._intervals.clear();
+    this.logger?.debug("Stopped.");
+  }
+  async whenReady(timeoutMs) {
+    if (timeoutMs === void 0) {
+      await this._readyDeferred.promise;
+      return;
+    }
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(`Actor ${this.name} did not become ready within ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+    try {
+      await Promise.race([
+        this._readyDeferred.promise,
+        timeout
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  /**
+  * Override in subclasses to prove the actor can do useful work.
+  * Default: no-op (the actor declares itself ready as soon as `start()` returns).
+  */
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  async readyHandler() {
+  }
+};
+var Actor = class extends ActorV3 {
+  static {
+    __name(this, "Actor");
+  }
+};
+
+// src/shared/actor/FinalizerActor.ts
 function _ts_decorate(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -16,6 +210,17 @@ var FinalizerActor = class extends ActorV3 {
   static {
     __name(this, "FinalizerActor");
   }
+  static needs = {
+    required: [
+      BlockValidationViewerMoniker,
+      BlockViewerMoniker,
+      FinalizationRunnerMoniker,
+      MempoolViewerMoniker
+    ],
+    optional: [
+      DeadLetterQueueRunnerMoniker
+    ]
+  };
   _blockValidationViewer;
   _blockViewer;
   _deadLetterQueueRunner;
@@ -49,25 +254,32 @@ var FinalizerActor = class extends ActorV3 {
   }
   async startHandler() {
     await super.startHandler();
+    const interval = this.params.config.finalizationCheckInterval ?? 500;
     this.registerTimer("FinalizerActor", async () => {
-      await this.spanAsync("processPendingBlocks", async () => {
-        this.logger?.debug("FinalizerActor: Processing pending blocks...");
-        await processPendingBlocks({
-          blockValidationViewer: this.blockValidationViewer,
-          context: this.context,
-          logger: this.logger,
-          mempoolViewer: this.mempoolViewer,
-          blockViewer: this.blockViewer,
-          finalizationRunner: this.finalizationRunner,
-          allowedProducers: this.allowedProducers,
-          minCandidates: this.minCandidates,
-          deadLetterQueueRunner: this._deadLetterQueueRunner
-        });
-      }, {
-        ...this.context,
-        timeBudgetLimit: 1500
+      await this.runFinalizationPass();
+    }, 2e3, interval);
+  }
+  async readyHandler() {
+    await this.runFinalizationPass();
+  }
+  async runFinalizationPass() {
+    await this.spanAsync("processPendingBlocks", async () => {
+      this.logger?.debug("FinalizerActor: Processing pending blocks...");
+      await processPendingBlocks({
+        blockValidationViewer: this.blockValidationViewer,
+        context: this.context,
+        logger: this.logger,
+        mempoolViewer: this.mempoolViewer,
+        blockViewer: this.blockViewer,
+        finalizationRunner: this.finalizationRunner,
+        allowedProducers: this.allowedProducers,
+        minCandidates: this.minCandidates,
+        deadLetterQueueRunner: this._deadLetterQueueRunner
       });
-    }, 2e3, 500);
+    }, {
+      ...this.context,
+      timeBudgetLimit: 1500
+    });
   }
 };
 FinalizerActor = _ts_decorate([
@@ -96,12 +308,12 @@ __name(buildTelemetryConfig, "buildTelemetryConfig");
 // src/shared/config/actors/Api.ts
 import { zodAsFactory, zodIsFactory, zodToFactory } from "@xylabs/sdk-js";
 import { BaseConfigContextZod, HostActorConfigZod } from "@xyo-network/xl1-sdk";
-import { globalRegistry, z } from "zod";
-var ApiConfigZod = HostActorConfigZod.extend(z.object({
-  initRewardsCache: z.union([
-    z.number(),
-    z.string(),
-    z.boolean()
+import { globalRegistry, z as z2 } from "zod";
+var ApiConfigZod = HostActorConfigZod.extend(z2.object({
+  initRewardsCache: z2.union([
+    z2.number(),
+    z2.string(),
+    z2.boolean()
   ]).transform((v) => v !== "0" && v !== "false" && v !== false && v != 0).default(true).register(globalRegistry, {
     description: "Whether to initialize the rewards cache on startup",
     title: "api.initRewardsCache",
@@ -121,7 +333,7 @@ var toApiConfigContext = zodToFactory(ApiConfigContext, "toApiConfigContext");
 // src/shared/config/actors/Bridge.ts
 import { AddressZod, HexZod, toAddress, toHex, zodAsFactory as zodAsFactory2, zodIsFactory as zodIsFactory2, zodToFactory as zodToFactory2 } from "@xylabs/sdk-js";
 import { AttoXL1ConvertFactor, BaseConfigContextZod as BaseConfigContextZod2, HostActorConfigZod as HostActorConfigZod2, XL1 } from "@xyo-network/xl1-sdk";
-import { globalRegistry as globalRegistry2, z as z2 } from "zod";
+import { globalRegistry as globalRegistry2, z as z3 } from "zod";
 var DEFAULT_FIXED_FEE = toHex(XL1(1000n) * AttoXL1ConvertFactor.xl1);
 var DEFAULT_VARIABLE_FEE_BASIS_POINTS = 300;
 var DEFAULT_HARDHAT_BRIDGE_CONTRACT = toAddress("2279B7A0a67DB372996a5FaB50D91eAA73d2eBe6");
@@ -130,7 +342,7 @@ var DEFAULT_HARDHAT_REMOTE_CHAIN_WALLET_PRIVATE_KEY = toHex("0xac0974bec39a17e36
 var DEFAULT_HARDHAT_TOKEN_CONTRACT = toAddress("5FbDB2315678afecb367f032d93F642f64180aa3");
 var DEFAULT_MAX_BRIDGE_AMOUNT = toHex(XL1(1000000n) * AttoXL1ConvertFactor.xl1);
 var DEFAULT_MIN_BRIDGE_AMOUNT = toHex(XL1(1500n) * AttoXL1ConvertFactor.xl1);
-var BasisPointsZod = z2.coerce.number().int().nonnegative().max(1e4);
+var BasisPointsZod = z3.coerce.number().int().nonnegative().max(1e4);
 var BridgeConfigZod = HostActorConfigZod2.extend({
   escrowAddress: AddressZod.optional().register(globalRegistry2, {
     description: "Address to which bridge escrow will be sent",
@@ -166,13 +378,13 @@ var BridgeConfigZod = HostActorConfigZod2.extend({
     title: "bridge.minBridgeAmount",
     type: "string"
   }),
-  redisHost: z2.string().default("localhost").register(globalRegistry2, {
+  redisHost: z3.string().default("localhost").register(globalRegistry2, {
     default: "localhost",
     description: "Host for the Bridge Redis instance",
     title: "bridge.redisHost",
     type: "string"
   }),
-  redisPort: z2.coerce.number().int().positive().default(6379).register(globalRegistry2, {
+  redisPort: z3.coerce.number().int().positive().default(6379).register(globalRegistry2, {
     default: 6379,
     description: "Port for the Bridge Redis instance",
     title: "bridge.redisPort",
@@ -237,10 +449,14 @@ var toBridgeConfigContext = zodToFactory2(BridgeConfigContext, "toBridgeConfigCo
 // src/shared/config/actors/Finalizer.ts
 import { AddressZod as AddressZod2, zodAsFactory as zodAsFactory3, zodIsFactory as zodIsFactory3, zodToFactory as zodToFactory3 } from "@xylabs/sdk-js";
 import { BaseConfigContextZod as BaseConfigContextZod3, DEFAULT_MIN_CANDIDATES, HostActorConfigZod as HostActorConfigZod3 } from "@xyo-network/xl1-sdk";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var FinalizerConfigZod = HostActorConfigZod3.extend({
-  allowedProducers: z3.array(AddressZod2).optional(),
-  minCandidates: z3.number().int().min(0).default(DEFAULT_MIN_CANDIDATES)
+  allowedProducers: z4.array(AddressZod2).optional(),
+  // Period (ms) between finalizer ticks. Default matches the historical
+  // hardcoded value in FinalizerActor; tests can lower it to drive faster
+  // block finalization.
+  finalizationCheckInterval: z4.coerce.number().default(500),
+  minCandidates: z4.number().int().min(0).default(DEFAULT_MIN_CANDIDATES)
 });
 var isFinalizerConfig = zodIsFactory3(FinalizerConfigZod);
 var asFinalizerConfig = zodAsFactory3(FinalizerConfigZod, "asFinalizerConfig");
@@ -255,13 +471,13 @@ var toFinalizerConfigContext = zodToFactory3(FinalizerConfigContext, "toFinalize
 // src/shared/config/actors/Mempool.ts
 import { zodAsFactory as zodAsFactory4, zodIsFactory as zodIsFactory4, zodToFactory as zodToFactory4 } from "@xylabs/sdk-js";
 import { BaseConfigContextZod as BaseConfigContextZod4, HostActorConfigZod as HostActorConfigZod4 } from "@xyo-network/xl1-sdk";
-import { globalRegistry as globalRegistry3, z as z4 } from "zod";
+import { globalRegistry as globalRegistry3, z as z5 } from "zod";
 var DEFAULT_MEMPOOL_BLOCK_PRUNE_INTERVAL = 1e3;
 var DEFAULT_MEMPOOL_TRANSACTION_PRUNE_INTERVAL = 1e3;
 var MempoolConfigZod = HostActorConfigZod4.extend({
-  enabled: z4.union([
-    z4.string(),
-    z4.boolean()
+  enabled: z5.union([
+    z5.string(),
+    z5.boolean()
   ]).default("false").transform((val, ctx) => {
     if (typeof val === "boolean") return val;
     const normalized = val.toLowerCase().trim();
@@ -282,19 +498,19 @@ var MempoolConfigZod = HostActorConfigZod4.extend({
       expected: "boolean",
       message: `Invalid boolean value: "${val}". Use true/false, 1/0, yes/no.`
     });
-    return z4.NEVER;
+    return z5.NEVER;
   }).register(globalRegistry3, {
     default: "false",
     description: "Enable the Mempool",
     title: "mempool.enabled",
     type: "boolean"
   }),
-  blockPruneInterval: z4.coerce.number().default(DEFAULT_MEMPOOL_BLOCK_PRUNE_INTERVAL).register(globalRegistry3, {
+  blockPruneInterval: z5.coerce.number().default(DEFAULT_MEMPOOL_BLOCK_PRUNE_INTERVAL).register(globalRegistry3, {
     description: "The interval time (in milliseconds) between pending block prune attempts",
     title: "mempool.blockPruneInterval",
     type: "number"
   }),
-  transactionPruneInterval: z4.coerce.number().default(DEFAULT_MEMPOOL_TRANSACTION_PRUNE_INTERVAL).register(globalRegistry3, {
+  transactionPruneInterval: z5.coerce.number().default(DEFAULT_MEMPOOL_TRANSACTION_PRUNE_INTERVAL).register(globalRegistry3, {
     description: "The interval time (in milliseconds) between pending transaction prune attempts",
     title: "mempool.transactionPruneInterval",
     type: "number"
@@ -311,44 +527,39 @@ var asMempoolConfigContext = zodAsFactory4(MempoolConfigContext, "asMempoolConfi
 var toMempoolConfigContext = zodToFactory4(MempoolConfigContext, "toMempoolConfigContext");
 
 // src/shared/config/actors/Producer.ts
-import { AddressZod as AddressZod3, asAddress, zodAsFactory as zodAsFactory5, zodIsFactory as zodIsFactory5, zodToFactory as zodToFactory5 } from "@xylabs/sdk-js";
+import { AddressZod as AddressZod3, zodAsFactory as zodAsFactory5, zodIsFactory as zodIsFactory5, zodToFactory as zodToFactory5 } from "@xylabs/sdk-js";
 import { ActorConfigZod, BaseConfigContextZod as BaseConfigContextZod5 } from "@xyo-network/xl1-sdk";
-import { globalRegistry as globalRegistry4, z as z5 } from "zod";
+import { globalRegistry as globalRegistry4, z as z6 } from "zod";
 var DEFAULT_BLOCK_PRODUCTION_CHECK_INTERVAL = 1e4;
-var ProducerConfigZod = ActorConfigZod.extend(z5.object({
-  allowlist: z5.preprocess((val) => {
-    if (typeof val === "string") {
-      return val.split(",").map((s) => asAddress(s.trim()));
-    }
-    return val;
-  }, z5.array(AddressZod3).optional().register(globalRegistry4, {
+var ProducerConfigZod = ActorConfigZod.extend(z6.object({
+  allowlist: z6.array(AddressZod3).optional().register(globalRegistry4, {
     description: "List of allowed producer addresses, if undefined anyone can participate",
     title: "allowlist",
     type: "array"
-  })),
-  blockProductionCheckInterval: z5.coerce.number().default(DEFAULT_BLOCK_PRODUCTION_CHECK_INTERVAL).register(globalRegistry4, {
+  }),
+  blockProductionCheckInterval: z6.coerce.number().default(DEFAULT_BLOCK_PRODUCTION_CHECK_INTERVAL).register(globalRegistry4, {
     description: "The interval time (in milliseconds) between block production attempts",
     title: "producer.blockProductionCheckInterval",
     type: "number"
   }),
-  disableIntentRedeclaration: z5.boolean().optional().register(globalRegistry4, {
+  disableIntentRedeclaration: z6.boolean().optional().register(globalRegistry4, {
     description: "Should the producer skip redeclaring their intent to continue producing blocks",
     title: "producer.disableIntentRedeclaration",
     type: "boolean"
   }),
-  heartbeatInterval: z5.coerce.number().default(36e5).register(globalRegistry4, {
+  heartbeatInterval: z6.coerce.number().default(36e5).register(globalRegistry4, {
     description: "The number of milliseconds between heartbeats if no blocks are produced",
     title: "producer.heartbeatInterval",
     type: "number"
   }),
   // TODO: BigInt schema
-  minStake: z5.coerce.number().default(1).register(globalRegistry4, {
+  minStake: z6.coerce.number().default(1).register(globalRegistry4, {
     description: "Minimum stake required to be a Producer",
     title: "producer.minStake",
     type: "number"
   }),
   // TODO: Address schema
-  rewardAddress: z5.string().optional().register(globalRegistry4, {
+  rewardAddress: z6.string().optional().register(globalRegistry4, {
     description: "Address to receive block rewards",
     title: "producer.rewardAddress",
     type: "string"
@@ -765,7 +976,7 @@ async function initActorAccount({ config, logger }) {
 __name(initActorAccount, "initActorAccount");
 
 // src/shared/init/initActorSeedPhrase.ts
-import { assertEx, isString } from "@xylabs/sdk-js";
+import { assertEx as assertEx2, isString } from "@xylabs/sdk-js";
 async function initActorSeedPhrase(context, bios) {
   const { logger, config } = context;
   const walletKind = config.name;
@@ -774,12 +985,12 @@ async function initActorSeedPhrase(context, bios) {
   if (isString(report?.root.mnemonic)) return report.root.mnemonic;
   const fallback = getBuiltInDevMnemonic();
   logger?.debug(`[${walletKind}] Falling back to built-in development mnemonic`);
-  return assertEx(fallback, () => "Unable to resolve mnemonic");
+  return assertEx2(fallback, () => "Unable to resolve mnemonic");
 }
 __name(initActorSeedPhrase, "initActorSeedPhrase");
 
 // src/shared/init/initBridgedModule.ts
-import { assertEx as assertEx2 } from "@xylabs/sdk-js";
+import { assertEx as assertEx3 } from "@xylabs/sdk-js";
 import { asAttachableArchivistInstance, asAttachableModuleInstance } from "@xyo-network/sdk-js";
 import { Mutex } from "async-mutex";
 var initMutex = new Mutex();
@@ -788,8 +999,8 @@ async function initBridgedModule({ bridge, moduleName }) {
   return await initMutex.runExclusive(async () => {
     const existing = bridgedModuleDictionary?.[bridge.address]?.[moduleName];
     if (existing) return existing;
-    const mod = assertEx2(await bridge.resolve(moduleName), () => `Could not resolve ${moduleName}`);
-    const moduleInstance = assertEx2(asAttachableModuleInstance(mod), () => `Could not convert ${moduleName} to attachable module instance`);
+    const mod = assertEx3(await bridge.resolve(moduleName), () => `Could not resolve ${moduleName}`);
+    const moduleInstance = assertEx3(asAttachableModuleInstance(mod), () => `Could not convert ${moduleName} to attachable module instance`);
     let moduleMap = bridgedModuleDictionary[bridge.address];
     if (moduleMap === void 0) {
       moduleMap = {};
@@ -801,7 +1012,7 @@ async function initBridgedModule({ bridge, moduleName }) {
 }
 __name(initBridgedModule, "initBridgedModule");
 async function initBridgedArchivistModule({ bridge, moduleName }) {
-  return assertEx2(asAttachableArchivistInstance(await initBridgedModule({
+  return assertEx3(asAttachableArchivistInstance(await initBridgedModule({
     bridge,
     moduleName
   })), () => `Could not convert ${moduleName} to attachable archivist instance`);
@@ -836,7 +1047,7 @@ async function initActorWallet(context) {
 __name(initActorWallet, "initActorWallet");
 
 // src/shared/orchestrator/Orchestrator.ts
-import { AbstractCreatable, creatable as creatable2 } from "@xylabs/sdk-js";
+import { AbstractCreatable as AbstractCreatable2, creatable as creatable2 } from "@xylabs/sdk-js";
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -844,25 +1055,43 @@ function _ts_decorate2(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate2, "_ts_decorate");
-var Orchestrator = class extends AbstractCreatable {
+var Orchestrator = class extends AbstractCreatable2 {
   static {
     __name(this, "Orchestrator");
   }
   actors = [];
-  keepAliveHandle = null;
   running = false;
+  shuttingDown = false;
+  get readyState() {
+    if (this.actors.length === 0) return "pending";
+    if (this.actors.some((a) => isLocalActor(a) && a.readyState === "failed")) return "failed";
+    if (this.actors.every((a) => isLocalActor(a) && a.readyState === "ready")) return "ready";
+    return "pending";
+  }
+  isReady() {
+    return this.readyState === "ready" && !this.shuttingDown;
+  }
+  isShuttingDown() {
+    return this.shuttingDown;
+  }
   /**
   * Registers an actor.
   * (We won't activate the actor until `start()` is called.)
   */
   async registerActor(actor) {
+    this.actors.push(actor);
     if (this.running) {
       await actor.start();
+      if (isLocalActor(actor)) {
+        actor.runReadyHandler().catch((err) => {
+          this.logger?.error(`[Orchestrator] Actor [${actor.name}] readyHandler failed: ${formatError(err)}`);
+        });
+      }
     }
-    this.actors.push(actor);
   }
   /**
-  * Starts the orchestrator: activates all actors.
+  * Starts the orchestrator: activates all actors in parallel and kicks off their warm-pass.
+  * `whenReady()` resolves once every actor's `readyHandler` has succeeded.
   */
   async startHandler() {
     await super.startHandler();
@@ -870,13 +1099,26 @@ var Orchestrator = class extends AbstractCreatable {
       this.logger?.warn("[Orchestrator] Already started.");
       return;
     }
-    this.logger?.log("[Orchestrator] Starting...");
+    this.logger?.log(`[Orchestrator] Starting ${this.actors.length} actor(s) in parallel...`);
     this.running = true;
+    const startResults = await Promise.allSettled(this.actors.map((a) => a.start()));
+    const startFailures = startResults.flatMap((r, i) => r.status === "rejected" ? [
+      {
+        actor: this.actors[i],
+        reason: r.reason
+      }
+    ] : []);
+    if (startFailures.length > 0) {
+      for (const f of startFailures) this.logger?.error(`[Orchestrator] Actor [${f.actor?.name ?? "?"}] failed to start: ${formatError(f.reason)}`);
+      throw new Error(`[Orchestrator] ${startFailures.length} actor(s) failed to start`);
+    }
     for (const actor of this.actors) {
-      await actor.start();
+      if (isLocalActor(actor)) {
+        actor.runReadyHandler().catch((err) => {
+          this.logger?.error(`[Orchestrator] Actor [${actor.name}] readyHandler failed: ${formatError(err)}`);
+        });
+      }
     }
-    this.keepAliveHandle = setInterval(() => {
-    }, 2147483647);
   }
   /**
   * Stops the orchestrator: deactivates all actors.
@@ -888,20 +1130,55 @@ var Orchestrator = class extends AbstractCreatable {
       return;
     }
     this.logger?.log("[Orchestrator] Stopping...");
-    for (const actor of this.actors) {
-      await actor.stop();
-    }
+    this.shuttingDown = true;
+    await Promise.allSettled(this.actors.map((a) => a.stop()));
     this.running = false;
-    if (this.keepAliveHandle) clearInterval(this.keepAliveHandle);
-    this.logger?.log("[Orchestrator] Stopped...");
+    this.shuttingDown = false;
+    this.logger?.log("[Orchestrator] Stopped.");
+  }
+  /**
+  * Resolves once every actor reports ready. Rejects if any actor's `readyHandler` throws,
+  * or after `timeoutMs` if provided.
+  */
+  async whenReady(timeoutMs) {
+    const localActors = this.actors.filter(isLocalActor);
+    if (localActors.length === 0) return;
+    if (timeoutMs === void 0) {
+      await Promise.all(localActors.map((a) => a.whenReady()));
+      return;
+    }
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(`[Orchestrator] Not ready within ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+    try {
+      await Promise.race([
+        Promise.all(localActors.map((a) => a.whenReady())),
+        timeout
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
   }
 };
 Orchestrator = _ts_decorate2([
   creatable2()
 ], Orchestrator);
+function isLocalActor(actor) {
+  return actor instanceof ActorV3;
+}
+__name(isLocalActor, "isLocalActor");
+function formatError(err) {
+  if (err instanceof Error) return `${err.message}${err.stack ? `
+${err.stack}` : ""}`;
+  return String(err);
+}
+__name(formatError, "formatError");
 
 // src/shared/provider/SimpleRejectedTransactionsArchivistProvider.ts
-import { assertEx as assertEx3 } from "@xylabs/sdk-js";
+import { assertEx as assertEx4 } from "@xylabs/sdk-js";
 import { AbstractCreatableProvider, creatableProvider } from "@xyo-network/xl1-sdk";
 function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -927,7 +1204,7 @@ var SimpleRejectedTransactionsArchivistProvider = class _SimpleRejectedTransacti
   static async paramsHandler(params) {
     return {
       ...await super.paramsHandler(params),
-      archivist: assertEx3(params?.archivist, () => "archivist is required")
+      archivist: assertEx4(params?.archivist, () => "archivist is required")
     };
   }
 };
@@ -954,18 +1231,21 @@ function basicRemoteViewerLocator(name, remoteConfig, dataLakeEndpoint, validato
 __name(basicRemoteViewerLocator, "basicRemoteViewerLocator");
 
 // src/neutral/config/locators/rootLocatorFromConfig.ts
-import { assertEx as assertEx4 } from "@xylabs/sdk-js";
+import { assertEx as assertEx5 } from "@xylabs/sdk-js";
 import { commonLocatorFromConfig, remoteLocatorFromConfig } from "@xyo-network/xl1-sdk";
 async function rootLocatorFromConfig(context, validateDepsOnRegister = false) {
   const { config } = context;
   await commonLocatorFromConfig(context, validateDepsOnRegister);
-  const locator = assertEx4(await (config.remote.rpc ? remoteLocatorFromConfig(context, validateDepsOnRegister) : void 0), () => "Root locator could not be created from config. No supported configuration found.");
+  const locator = assertEx5(await (config.remote.rpc ? remoteLocatorFromConfig(context, validateDepsOnRegister) : void 0), () => "Root locator could not be created from config. No supported configuration found.");
   locator.freeze();
   return locator;
 }
 __name(rootLocatorFromConfig, "rootLocatorFromConfig");
 export {
+  Actor,
   ActorMnemonicNotAllowedError,
+  ActorParamsV3Zod,
+  ActorV3,
   ApiConfigContext,
   ApiConfigZod,
   BUILT_IN_DEV_MNEMONIC,