@xyo-network/chain-orchestration 1.20.29 → 1.21.0

package/dist/browser/index.mjs

@@ -1,15 +1,26 @@
 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 { 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 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);
@@ -185,12 +196,44 @@ var ActorV3 = class extends AbstractCreatable {
     }
   }
   /**
+  * 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 {
@@ -198,94 +241,6 @@ var Actor = class extends ActorV3 {
   }
 };
 
-// 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);
-  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_decorate, "_ts_decorate");
-var FinalizerActor = class extends ActorV3 {
-  static {
-    __name(this, "FinalizerActor");
-  }
-  static needs = {
-    required: [
-      BlockValidationViewerMoniker,
-      BlockViewerMoniker,
-      FinalizationRunnerMoniker,
-      MempoolViewerMoniker
-    ],
-    optional: [
-      DeadLetterQueueRunnerMoniker
-    ]
-  };
-  _blockValidationViewer;
-  _blockViewer;
-  _deadLetterQueueRunner;
-  _finalizationRunner;
-  _mempoolViewer;
-  get allowedProducers() {
-    return this.params.config.allowedProducers ?? [];
-  }
-  get blockValidationViewer() {
-    return this._blockValidationViewer;
-  }
-  get blockViewer() {
-    return this._blockViewer;
-  }
-  get finalizationRunner() {
-    return this._finalizationRunner;
-  }
-  get mempoolViewer() {
-    return this._mempoolViewer;
-  }
-  get minCandidates() {
-    return this.params.config.minCandidates;
-  }
-  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);
-  }
-  async startHandler() {
-    await super.startHandler();
-    const interval = this.params.config.finalizationCheckInterval ?? 500;
-    this.registerTimer("FinalizerActor", async () => {
-      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
-      });
-    }, {
-      ...this.context,
-      timeBudgetLimit: 1500
-    });
-  }
-};
-FinalizerActor = _ts_decorate([
-  creatable()
-], FinalizerActor);
-
 // src/shared/buildTelemetryConfig.ts
 function buildTelemetryConfig(config, serviceName, serviceVersion, defaultMetricsScrapePort = 9464) {
   const { otlpEndpoint } = config.telemetry?.otel ?? {};
@@ -318,6 +273,46 @@ var ApiConfigZod = HostActorConfigZod.extend(z2.object({
     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);
@@ -342,6 +337,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 DEFAULT_SCANNER_INTERVAL_MS = 3e4;
 var BasisPointsZod = z3.coerce.number().int().nonnegative().max(1e4);
 var BridgeConfigZod = HostActorConfigZod2.extend({
   escrowAddress: AddressZod.optional().register(globalRegistry2, {
@@ -390,6 +386,12 @@ var BridgeConfigZod = HostActorConfigZod2.extend({
     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",
@@ -402,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",
@@ -653,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";
@@ -962,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 as assertEx2, isString } from "@xylabs/sdk-js";
 async function initActorSeedPhrase(context, bios) {
   const { logger, config } = context;
   const walletKind = config.name;
@@ -1039,22 +1035,28 @@ 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 as AbstractCreatable2, 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");
+__name(_ts_decorate, "_ts_decorate");
 var Orchestrator = class extends AbstractCreatable2 {
   static {
     __name(this, "Orchestrator");
@@ -1163,8 +1165,8 @@ var Orchestrator = class extends AbstractCreatable2 {
     }
   }
 };
-Orchestrator = _ts_decorate2([
-  creatable2()
+Orchestrator = _ts_decorate([
+  creatable()
 ], Orchestrator);
 function isLocalActor(actor) {
   return actor instanceof ActorV3;
@@ -1180,13 +1182,13 @@ __name(formatError, "formatError");
 // src/shared/provider/SimpleRejectedTransactionsArchivistProvider.ts
 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 {
@@ -1208,7 +1210,7 @@ var SimpleRejectedTransactionsArchivistProvider = class _SimpleRejectedTransacti
     };
   }
 };
-SimpleRejectedTransactionsArchivistProvider = _ts_decorate3([
+SimpleRejectedTransactionsArchivistProvider = _ts_decorate2([
   creatableProvider()
 ], SimpleRejectedTransactionsArchivistProvider);
 
@@ -1259,7 +1261,6 @@ export {
   DEFAULT_MEMPOOL_TRANSACTION_PRUNE_INTERVAL,
   DefaultServiceProvider,
   DerivationPathCollisionError,
-  FinalizerActor,
   FinalizerConfigContext,
   FinalizerConfigZod,
   GENESIS_REWARD_AMOUNT,
@@ -1303,7 +1304,6 @@ export {
   getBuiltInDevMnemonic,
   getInsecureGenesisRewardMnemonic,
   getResolvedWalletReport,
-  initActorAccount,
   initActorSeedPhrase,
   initActorWallet,
   initBridgedArchivistModule,