@xyo-network/chain-orchestration 1.20.28 → 1.21.0

package/dist/browser/index.mjs

@@ -1,78 +1,245 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
-// 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";
-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);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
+// 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 noopCounter = {
+  add: /* @__PURE__ */ __name(() => {
+  }, "add")
+};
+var noopUpDownCounter = {
+  add: /* @__PURE__ */ __name(() => {
+  }, "add")
+};
+var noopGauge = {
+  record: /* @__PURE__ */ __name(() => {
+  }, "record")
+};
+var noopHistogram = {
+  record: /* @__PURE__ */ __name(() => {
+  }, "record")
+};
+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(_ts_decorate, "_ts_decorate");
-var FinalizerActor = class extends ActorV3 {
+__name(createDeferred, "createDeferred");
+var ActorV3 = class extends AbstractCreatable {
   static {
-    __name(this, "FinalizerActor");
+    __name(this, "ActorV3");
   }
-  _blockValidationViewer;
-  _blockViewer;
-  _deadLetterQueueRunner;
-  _finalizationRunner;
-  _mempoolViewer;
-  get allowedProducers() {
-    return this.params.config.allowedProducers ?? [];
+  _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 blockValidationViewer() {
-    return this._blockValidationViewer;
+  get readyError() {
+    return this._readyError;
   }
-  get blockViewer() {
-    return this._blockViewer;
+  get readyState() {
+    return this._readyState;
   }
-  get finalizationRunner() {
-    return this._finalizationRunner;
+  get account() {
+    return this.params.account;
   }
-  get mempoolViewer() {
-    return this._mempoolViewer;
+  get context() {
+    return this.locator.context;
   }
-  get minCandidates() {
-    return this.params.config.minCandidates;
+  get locator() {
+    return this.params.locator;
   }
-  async createHandler() {
-    await super.startHandler();
-    this._blockValidationViewer = await this.locator.getInstance(BlockValidationViewerMoniker);
-    this._blockViewer = await this.locator.getInstance(BlockViewerMoniker);
-    this._finalizationRunner = await this.locator.getInstance(FinalizationRunnerMoniker);
-    this._mempoolViewer = await this.locator.getInstance(MempoolViewerMoniker);
-    this._deadLetterQueueRunner = await this.locator.tryGetInstance(DeadLetterQueueRunnerMoniker);
+  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
+    };
   }
-  async startHandler() {
-    await super.startHandler();
-    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
+  /**
+  * 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}`);
         });
-      }, {
-        ...this.context,
-        timeBudgetLimit: 1500
-      });
-    }, 2e3, 500);
+      }, 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);
+    }
+  }
+  /**
+  * Create a `Counter` instrument bound to this actor's meter, or a no-op
+  * stub if telemetry is not wired. Always returns a non-undefined value so
+  * call sites can drop the optional-chain on `.add()`.
+  *
+  * TODO: in a future pass, consider folding these single-instrument helpers
+  * into a declarative `createActorMeters({ counters: {...}, gauges: {...} })`
+  * spec API for actors with many instruments.
+  */
+  counter(name, description) {
+    return this.meter?.createCounter(name, {
+      description
+    }) ?? noopCounter;
+  }
+  /** Create a synchronous `Gauge` instrument, or a no-op stub if telemetry is not wired. */
+  gauge(name, description) {
+    return this.meter?.createGauge(name, {
+      description
+    }) ?? noopGauge;
+  }
+  /** Create a `Histogram` instrument, or a no-op stub if telemetry is not wired. */
+  histogram(name, description) {
+    return this.meter?.createHistogram(name, {
+      description
+    }) ?? noopHistogram;
+  }
+  /**
+  * 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() {
+  }
+  /** Create an `UpDownCounter` instrument, or a no-op stub if telemetry is not wired. */
+  upDownCounter(name, description) {
+    return this.meter?.createUpDownCounter(name, {
+      description
+    }) ?? noopUpDownCounter;
+  }
+};
+var Actor = class extends ActorV3 {
+  static {
+    __name(this, "Actor");
   }
 };
-FinalizerActor = _ts_decorate([
-  creatable()
-], FinalizerActor);
 
 // src/shared/buildTelemetryConfig.ts
 function buildTelemetryConfig(config, serviceName, serviceVersion, defaultMetricsScrapePort = 9464) {
@@ -96,16 +263,56 @@ __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",
     type: "boolean"
+  }),
+  /**
+  * When `true`, the API actor runs in stateless mode: it holds no local
+  * backing-store ownership, never loads the local LMDB/MongoDB node, and
+  * federates every JSON-RPC request to upstream owner-actors via `JsonRpc*`
+  * providers. Multiple stateless API instances can run behind a load
+  * balancer for horizontal scaling. Requires `remote.rpc` to point at the
+  * upstream API/Finalizer/Mempool/Indexer surfaces.
+  */
+  stateless: z2.union([
+    z2.number(),
+    z2.string(),
+    z2.boolean()
+  ]).transform((v) => v === "1" || v === "true" || v === true || v == 1).default(false).register(globalRegistry, {
+    description: "Run the API actor as a stateless federation node (availableBackings: [network])",
+    title: "api.stateless",
+    type: "boolean"
+  }),
+  /**
+  * Back-compat for the surface-aware route split. When `true`, `POST /rpc`
+  * serves the full `XyoConnection` (both node-surface and indexed-surface
+  * methods), preserving pre-Phase-7 behavior for clients that haven't yet
+  * migrated to `POST /rpc/indexed`. When `false`, `/rpc` is strictly
+  * node-surface only and indexed methods are 404 at `/rpc`.
+  *
+  * `/rpc/indexed` mounts independently of this flag whenever the locator's
+  * connection has any indexed branch.
+  *
+  * Default `true` for the first release that includes Phase 7 — flip to
+  * `false` per environment once external clients (explorers, wallets, dApps)
+  * have moved their indexed-method calls to `/rpc/indexed`.
+  */
+  legacyMixedRpc: z2.union([
+    z2.number(),
+    z2.string(),
+    z2.boolean()
+  ]).transform((v) => v !== "0" && v !== "false" && v !== false && v != 0).default(true).register(globalRegistry, {
+    description: "Serve the full XyoConnection at POST /rpc (no surface filter). Set false to enforce node-surface-only at /rpc; indexed methods always available at /rpc/indexed regardless.",
+    title: "api.legacyMixedRpc",
+    type: "boolean"
   })
 }).shape);
 var isApiConfig = zodIsFactory(ApiConfigZod);
@@ -121,7 +328,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 +337,8 @@ 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 DEFAULT_SCANNER_INTERVAL_MS = 3e4;
+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,18 +374,24 @@ 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",
     type: "number"
   }),
+  scannerIntervalMs: z3.coerce.number().int().positive().default(DEFAULT_SCANNER_INTERVAL_MS).register(globalRegistry2, {
+    default: DEFAULT_SCANNER_INTERVAL_MS,
+    description: "How often (ms) the EVM->XL1 scanner polls the remote bridge contract for new BridgedToRemote ids confirmed at depth.",
+    title: "bridge.scannerIntervalMs",
+    type: "number"
+  }),
   remoteBridgeContractAddress: AddressZod.default(DEFAULT_HARDHAT_BRIDGE_CONTRACT).register(globalRegistry2, {
     default: DEFAULT_HARDHAT_BRIDGE_CONTRACT,
     description: "Hex representation of remote token address used for bridging",
@@ -190,6 +404,14 @@ var BridgeConfigZod = HostActorConfigZod2.extend({
     title: "bridge.remoteChainId",
     type: "string"
   }),
+  remoteConfirmationDepth: z3.union([
+    z3.coerce.number().int().nonnegative(),
+    z3.literal("finalized")
+  ]).optional().register(globalRegistry2, {
+    description: "Block depth or BlockTag at which the remote (EVM) chain is read as canonical. Numeric: number of confirmations behind head. 'finalized': Casper FFG finalized block. Resolved per-chain by getRemoteConfirmationDepth when unset.",
+    title: "bridge.remoteConfirmationDepth",
+    type: "string"
+  }),
   remoteTokenAddress: HexZod.default(DEFAULT_HARDHAT_TOKEN_CONTRACT).register(globalRegistry2, {
     default: DEFAULT_HARDHAT_TOKEN_CONTRACT,
     description: "Hex representation of remote token address used for bridging",
@@ -237,10 +459,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 +481,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 +508,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 +537,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"
@@ -442,8 +663,8 @@ var ServiceLifetime = {
   Transient: "Transient"
 };
 
-// src/shared/init/initActorAccount.ts
-import { isDefined } from "@xylabs/sdk-js";
+// src/shared/init/initActorSeedPhrase.ts
+import { assertEx as assertEx2, isString } from "@xylabs/sdk-js";
 
 // src/shared/init/walletResolution.ts
 import { HDWallet } from "@xyo-network/sdk-js";
@@ -751,21 +972,7 @@ async function resolveWalletForActor(actorName, accountPath) {
 }
 __name(resolveWalletForActor, "resolveWalletForActor");
 
-// src/shared/init/initActorAccount.ts
-var actorAccountSingletons = {};
-async function initActorAccount({ config, logger }) {
-  const actorName = config.name;
-  if (isDefined(actorAccountSingletons[actorName])) return actorAccountSingletons[actorName];
-  const accountPath = typeof config.accountPath === "string" ? config.accountPath : void 0;
-  const account = await resolveWalletForActor(actorName, accountPath);
-  logger?.debug(`[${actorName}] Using wallet address ${account.address}`);
-  actorAccountSingletons[actorName] = account;
-  return actorAccountSingletons[actorName];
-}
-__name(initActorAccount, "initActorAccount");
-
 // src/shared/init/initActorSeedPhrase.ts
-import { assertEx, isString } from "@xylabs/sdk-js";
 async function initActorSeedPhrase(context, bios) {
   const { logger, config } = context;
   const walletKind = config.name;
@@ -774,12 +981,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 +995,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 +1008,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`);
@@ -828,41 +1035,65 @@ function initStatusReporter({ logger }) {
 __name(initStatusReporter, "initStatusReporter");
 
 // src/shared/init/initWallet.ts
+import { isDefined } from "@xylabs/sdk-js";
+var actorAccountSingletons = {};
 async function initActorWallet(context) {
   const actorName = context.config.name;
+  if (isDefined(actorAccountSingletons[actorName])) return actorAccountSingletons[actorName];
   const accountPath = typeof context.config.accountPath === "string" ? context.config.accountPath : void 0;
-  return await resolveWalletForActor(actorName, accountPath);
+  const account = await resolveWalletForActor(actorName, accountPath);
+  context.logger?.debug(`[${actorName}] Using wallet address ${account.address}`);
+  actorAccountSingletons[actorName] = account;
+  return actorAccountSingletons[actorName];
 }
 __name(initActorWallet, "initActorWallet");
 
 // src/shared/orchestrator/Orchestrator.ts
-import { AbstractCreatable, creatable as creatable2 } from "@xylabs/sdk-js";
-function _ts_decorate2(decorators, target, key, desc) {
+import { AbstractCreatable as AbstractCreatable2, creatable } from "@xylabs/sdk-js";
+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);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate2, "_ts_decorate");
-var Orchestrator = class extends AbstractCreatable {
+__name(_ts_decorate, "_ts_decorate");
+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 +1101,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,28 +1132,63 @@ 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 = _ts_decorate([
+  creatable()
 ], 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) {
+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);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate3, "_ts_decorate");
+__name(_ts_decorate2, "_ts_decorate");
 var RejectedTransactionsArchivistProviderMoniker = "RejectedTransactionsArchivistProvider";
 var SimpleRejectedTransactionsArchivistProvider = class _SimpleRejectedTransactionsArchivistProvider extends AbstractCreatableProvider {
   static {
@@ -927,11 +1206,11 @@ 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")
     };
   }
 };
-SimpleRejectedTransactionsArchivistProvider = _ts_decorate3([
+SimpleRejectedTransactionsArchivistProvider = _ts_decorate2([
   creatableProvider()
 ], SimpleRejectedTransactionsArchivistProvider);
 
@@ -954,18 +1233,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,
@@ -979,7 +1261,6 @@ export {
   DEFAULT_MEMPOOL_TRANSACTION_PRUNE_INTERVAL,
   DefaultServiceProvider,
   DerivationPathCollisionError,
-  FinalizerActor,
   FinalizerConfigContext,
   FinalizerConfigZod,
   GENESIS_REWARD_AMOUNT,
@@ -1023,7 +1304,6 @@ export {
   getBuiltInDevMnemonic,
   getInsecureGenesisRewardMnemonic,
   getResolvedWalletReport,
-  initActorAccount,
   initActorSeedPhrase,
   initActorWallet,
   initBridgedArchivistModule,