@xyo-network/chain-orchestration 1.17.0 → 1.17.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json.schemastore.org/package.json",
   "name": "@xyo-network/chain-orchestration",
-  "version": "1.17.0",
+  "version": "1.17.2",
   "description": "XYO Layer One SDK Orchestration",
   "homepage": "https://xylabs.com",
   "bugs": {
@@ -40,47 +40,48 @@
   ],
   "dependencies": {
     "@opentelemetry/api": "~1.9.0",
-    "@xylabs/mongo": "~5.0.46",
-    "@xylabs/sdk-js": "~5.0.46",
-    "@xyo-network/archivist-memory": "~5.2.10",
-    "@xyo-network/archivist-model": "~5.2.10",
-    "@xyo-network/archivist-mongodb": "~5.2.10",
-    "@xyo-network/archivist-view": "~5.2.10",
+    "@xylabs/mongo": "~5.0.50",
+    "@xylabs/sdk-js": "~5.0.50",
+    "@xyo-network/archivist-memory": "~5.2.17",
+    "@xyo-network/archivist-model": "~5.2.17",
+    "@xyo-network/archivist-mongodb": "~5.2.17",
+    "@xyo-network/archivist-view": "~5.2.17",
     "@xyo-network/bios": "~7.2.0",
-    "@xyo-network/bridge-http": "~5.2.10",
-    "@xyo-network/bridge-model": "~5.2.10",
-    "@xyo-network/chain-modules": "~1.17.0",
-    "@xyo-network/chain-protocol": "~1.17.0",
-    "@xyo-network/chain-sdk": "~1.17.0",
-    "@xyo-network/chain-services": "~1.17.0",
-    "@xyo-network/chain-telemetry": "~1.17.0",
-    "@xyo-network/diviner-model": "~5.2.10",
-    "@xyo-network/manifest-wrapper": "~5.2.10",
-    "@xyo-network/module-abstract": "~5.2.10",
-    "@xyo-network/module-factory-locator": "~5.2.10",
-    "@xyo-network/module-model": "~5.2.10",
-    "@xyo-network/node-memory": "~5.2.10",
-    "@xyo-network/sentinel-memory": "~5.2.10",
-    "@xyo-network/sentinel-model": "~5.2.10",
-    "@xyo-network/typechain": "~4.0.10",
-    "@xyo-network/wallet": "~5.2.10",
-    "@xyo-network/xl1-protocol": "~1.14.15",
-    "@xyo-network/xl1-protocol-sdk": "~1.17.0",
+    "@xyo-network/bridge-http": "~5.2.17",
+    "@xyo-network/bridge-model": "~5.2.17",
+    "@xyo-network/chain-modules": "~1.17.2",
+    "@xyo-network/chain-protocol": "~1.17.2",
+    "@xyo-network/chain-sdk": "~1.17.2",
+    "@xyo-network/chain-services": "~1.17.2",
+    "@xyo-network/chain-telemetry": "~1.17.2",
+    "@xyo-network/diviner-model": "~5.2.17",
+    "@xyo-network/manifest-wrapper": "~5.2.17",
+    "@xyo-network/module-abstract": "~5.2.17",
+    "@xyo-network/module-factory-locator": "~5.2.17",
+    "@xyo-network/module-model": "~5.2.17",
+    "@xyo-network/node-memory": "~5.2.17",
+    "@xyo-network/sentinel-memory": "~5.2.17",
+    "@xyo-network/sentinel-model": "~5.2.17",
+    "@xyo-network/typechain": "~4.0.11",
+    "@xyo-network/wallet": "~5.2.17",
+    "@xyo-network/xl1-protocol": "~1.14.16",
+    "@xyo-network/xl1-protocol-sdk": "~1.17.2",
     "async-mutex": "~0.5.0",
-    "ethers": "~6.15.0"
+    "ethers": "^6.16.0"
   },
   "devDependencies": {
     "@types/node": "~24.10.1",
-    "@xylabs/sdk-js": "~5.0.46",
+    "@xylabs/sdk-js": "~5.0.50",
+    "@xylabs/telemetry": "~5.0.50",
     "@xylabs/ts-scripts-yarn3": "~7.2.8",
     "@xylabs/tsconfig": "~7.2.8",
-    "@xyo-network/account-model": "~5.2.10",
+    "@xyo-network/account-model": "~5.2.17",
     "@xyo-network/bios-model": "~7.2.0",
-    "@xyo-network/manifest-model": "~5.2.10",
-    "@xyo-network/module-model-mongodb": "~5.2.10",
-    "@xyo-network/node-model": "~5.2.10",
-    "@xyo-network/payload-model": "~5.2.10",
-    "@xyo-network/wallet-model": "~5.2.10",
+    "@xyo-network/manifest-model": "~5.2.17",
+    "@xyo-network/module-model-mongodb": "~5.2.17",
+    "@xyo-network/node-model": "~5.2.17",
+    "@xyo-network/payload-model": "~5.2.17",
+    "@xyo-network/wallet-model": "~5.2.17",
     "eslint": "^9.39.1",
     "typescript": "~5.9.3"
   },

package/src/actor/Actor.ts

@@ -0,0 +1,163 @@
+import type {
+  CreatableInstance, CreatableParams, EmptyObject,
+} from '@xylabs/sdk-js'
+import {
+  AbstractCreatable,
+  Base, creatable, delay, IdLogger,
+} from '@xylabs/sdk-js'
+import { span, spanRootAsync } from '@xylabs/telemetry'
+import type { Config } from '@xyo-network/xl1-protocol-sdk'
+import { Semaphore } from 'async-mutex'
+
+export type ActorParams<T extends EmptyObject | void = void> = CreatableParams & {
+  config: Config
+  displayName?: string
+  id: string
+} & (T extends void ? EmptyObject : T)
+
+export type ActorInstance<T extends ActorParams = ActorParams> = CreatableInstance<T> & {
+  start(): Promise<boolean>
+  stop(): Promise<boolean>
+}
+
+@creatable()
+export class Actor<TParams extends ActorParams = ActorParams> extends AbstractCreatable<TParams> {
+  protected readonly _intervals: Map<string, ReturnType<typeof setInterval>> = new Map()
+  protected readonly _semaphores: Map<string, Semaphore> = new Map()
+  protected readonly _timeouts: Map<string, ReturnType<typeof setTimeout>> = new Map()
+  private _active = false
+
+  get displayName() {
+    return this.params.displayName!
+  }
+
+  get id() {
+    return this.params.id
+  }
+
+  protected get logPrefix() {
+    return `[${this.displayName} (${this.id})] `
+  }
+
+  static override async paramsHandler<T extends ActorParams>(params?: Partial<T>) {
+    const baseParams = await super.paramsHandler(params)
+    const id = params?.id ?? baseParams.name
+    const displayName = params?.displayName ?? baseParams.name
+    return {
+      ...baseParams,
+      displayName,
+      id,
+      logger: baseParams.logger ?? new IdLogger(Base.defaultLogger ?? console, () => `[${displayName} (${id})] `),
+    }
+  }
+
+  /**
+   * The timer runs until the actor is deactivated (or you manually stop it).
+   */
+  registerTimer(timerName: string, callback: () => Promise<void>, dueTimeMs: number, periodMs: number) {
+    if (!this._active) {
+      this.logger?.warn(
+        `Cannot register timer '${timerName}' because actor is not active.`,
+      )
+      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._active || !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 > 5000) {
+                this.logger?.warn(
+                  `Timer '${this.name}:${timerName}' execution took longer (${duration}ms) than 5000ms.`,
+                )
+              }
+            })
+            .catch((error) => {
+              this.logger?.error(`Error in timer '${this.name}:${timerName}': ${error}`)
+            })
+            .finally(() => {
+              release()
+              running = false
+            })
+        }).catch((error) => {
+          this.logger?.error(`Error acquiring semaphore for timer '${this.name}:${timerName}': ${error}`)
+        })
+      }, periodMs)
+
+      // store interval so we can clear it on stop()
+      this._intervals.set(timerName, intervalId)
+    }, dueTimeMs)
+
+    // store timeout so we can clear it on stop() if interval hasn't started yet
+    this._timeouts.set(timerName, timeoutId)
+
+    this.logger?.log(
+      `Timer '${this.name}:${timerName}' registered: first call after ${dueTimeMs}ms, recurring every ${periodMs}ms.`,
+    )
+  }
+
+  /**
+   * Called by the Orchestrator when the actor is activated.
+   */
+  override async startHandler() {
+    await super.startHandler()
+    this._active = true
+    this.logger?.log('Started.')
+  }
+
+  /**
+   * Called by the Orchestrator when the actor is deactivated.
+   * Stop all running timers.
+   */
+  override async stopHandler() {
+    await super.stopHandler()
+    this._active = false
+    this.logger?.log('Stopping all timers...')
+
+    // wait for all semaphores to be free and acquire them to prevent new tasks from starting
+    await Promise.all(
+      [...this._semaphores.values()].map(async (semaphore) => {
+        // Wait for any running tasks to complete
+        while (semaphore.isLocked()) {
+          this.logger?.log('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?.log('Stopped.')
+  }
+}

package/src/actor/index.ts

@@ -0,0 +1 @@
+export * from './Actor.ts'

package/src/index.ts

@@ -1,6 +1,8 @@
+export * from './actor/index.ts'
 export * from './archivist/index.ts'
 export * from './bridge.ts'
 export * from './ConfigContext.ts'
 export * from './createDeclarationIntentBlock.ts'
 export * from './init/index.ts'
 export * from './manifest/index.ts'
+export * from './orchestrator/index.ts'

package/src/init/index.ts

@@ -1,6 +1,8 @@
 export * from './initBalanceSummaryMap.ts'
 export * from './initBridgedModule.ts'
 export * from './initChainStakeViewer.ts'
+export * from './initPendingBlockArchivist.ts'
+export * from './initPendingTransactionArchivist.ts'
 export * from './initProducerAccount.ts'
 export * from './initSeedPhrase.ts'
 export * from './initServerNode.ts'

package/src/init/initChainStakeViewer.ts

@@ -32,7 +32,7 @@ export async function initSimpleStakeViewer(config: Config, logger?: Logger): Pr
   return stakeChainViewer
 }
 
-export async function initChainStakeViewer(config: Config, logger?: Logger): Promise<StakeViewer> {
+export async function initStakeViewer(config: Config, logger?: Logger): Promise<StakeViewer> {
   if (canUseEvmProvider({ config })) {
     return await initEvmChainStakeViewer(config, logger)
   } else {

package/src/init/initPendingBlockArchivist.ts

@@ -0,0 +1,31 @@
+import { type BaseMongoSdkPrivateConfig } from '@xylabs/mongo'
+import { MemoryArchivist } from '@xyo-network/archivist-memory'
+import type { ArchivistInstance } from '@xyo-network/archivist-model'
+import { MongoDBArchivistV2 } from '@xyo-network/archivist-mongodb'
+import { hasMongoConfig } from '@xyo-network/xl1-protocol-sdk'
+
+import type { ConfigContext } from '../ConfigContext.ts'
+
+export async function initPendingBlockArchivist({ config, logger }: ConfigContext): Promise<ArchivistInstance> {
+  const mongoConfig = config.storage?.mongo
+  if (hasMongoConfig(mongoConfig)) {
+    // Create the MongoDB SDK from the configuration
+    const {
+      connectionString: dbConnectionString, database: dbName, domain: dbDomain, password: dbPassword, username: dbUserName,
+    } = mongoConfig
+    const payloadSdkConfig: BaseMongoSdkPrivateConfig = {
+      dbConnectionString, dbDomain, dbName, dbPassword, dbUserName,
+    }
+
+    return await MongoDBArchivistV2.create({
+      payloadSdkConfig: {
+        ...payloadSdkConfig,
+        collection: 'pending_block_bundles',
+      },
+      logger,
+    })
+  } else {
+    logger?.warn('[API] Mongo configuration not found. Using MemoryArchivist for TransferSummaryMap.')
+    return await MemoryArchivist.create()
+  }
+}

package/src/init/initPendingTransactionArchivist.ts

@@ -0,0 +1,31 @@
+import { type BaseMongoSdkPrivateConfig } from '@xylabs/mongo'
+import { MemoryArchivist } from '@xyo-network/archivist-memory'
+import type { ArchivistInstance } from '@xyo-network/archivist-model'
+import { MongoDBArchivistV2 } from '@xyo-network/archivist-mongodb'
+import { hasMongoConfig } from '@xyo-network/xl1-protocol-sdk'
+
+import type { ConfigContext } from '../ConfigContext.ts'
+
+export async function initPendingTransactionArchivist({ config, logger }: ConfigContext): Promise<ArchivistInstance> {
+  const mongoConfig = config.storage?.mongo
+  if (hasMongoConfig(mongoConfig)) {
+    // Create the MongoDB SDK from the configuration
+    const {
+      connectionString: dbConnectionString, database: dbName, domain: dbDomain, password: dbPassword, username: dbUserName,
+    } = mongoConfig
+    const payloadSdkConfig: BaseMongoSdkPrivateConfig = {
+      dbConnectionString, dbDomain, dbName, dbPassword, dbUserName,
+    }
+
+    return await MongoDBArchivistV2.create({
+      payloadSdkConfig: {
+        ...payloadSdkConfig,
+        collection: 'pending_transaction_bundles',
+      },
+      logger,
+    })
+  } else {
+    logger?.warn('[API] Mongo configuration not found. Using MemoryArchivist for TransferSummaryMap.')
+    return await MemoryArchivist.create()
+  }
+}

package/src/manifest/public/WithMempool/Chain.json

@@ -172,4 +172,4 @@
     }
   ],
   "schema": "network.xyo.manifest"
-}
+}

package/src/manifest/public/WithMempool/Pending.json

@@ -22,7 +22,21 @@
                 "network.xyo.storage.class": "mongodb"
               },
               "payloadSdkConfig": {
-                "collection": "pending_bundles"
+                "collection": "pending_transaction_bundles"
+              },
+              "schema": "network.xyo.archivist.config"
+            }
+          },
+          {
+            "config": {
+              "accountPath": "2/1/2",
+              "name": "PendingBlocks",
+              "getCache": {
+                "enabled": true,
+                "maxEntries": 5000
+              },
+              "payloadSdkConfig": {
+                "collection": "pending_block_bundles"
               },
               "schema": "network.xyo.archivist.config"
             }
@@ -32,4 +46,4 @@
     }
   ],
   "schema": "network.xyo.manifest"
-}
+}

package/src/manifest/public/WithoutMempool/Chain.json

@@ -94,4 +94,4 @@
     }
   ],
   "schema": "network.xyo.manifest"
-}
+}

package/src/manifest/public/WithoutMempool/Pending.json

@@ -22,7 +22,21 @@
                 "network.xyo.storage.class": "mongodb"
               },
               "payloadSdkConfig": {
-                "collection": "pending_bundles"
+                "collection": "pending_transaction_bundles"
+              },
+              "schema": "network.xyo.archivist.config"
+            }
+          },
+          {
+            "config": {
+              "accountPath": "2/1/2",
+              "name": "PendingBlocks",
+              "getCache": {
+                "enabled": true,
+                "maxEntries": 5000
+              },
+              "payloadSdkConfig": {
+                "collection": "pending_block_bundles"
               },
               "schema": "network.xyo.archivist.config"
             }
@@ -32,4 +46,4 @@
     }
   ],
   "schema": "network.xyo.manifest"
-}
+}

package/src/orchestrator/Orchestrator.ts

@@ -0,0 +1,69 @@
+import type { CreatableInstance } from '@xylabs/sdk-js'
+import { AbstractCreatable, creatable } from '@xylabs/sdk-js'
+
+import type { ActorInstance } from '../actor/index.ts'
+
+export interface OrchestratorInstance extends CreatableInstance {
+  registerActor(actor: ActorInstance): Promise<void>
+  start(): Promise<boolean>
+  stop(): Promise<boolean>
+}
+
+@creatable()
+export class Orchestrator extends AbstractCreatable implements OrchestratorInstance {
+  protected actors: ActorInstance[] = []
+  protected keepAliveHandle: NodeJS.Timeout | null = null
+  protected running = false
+
+  /**
+   * Registers an actor.
+   * (We won't activate the actor until `start()` is called.)
+   */
+  async registerActor(actor: ActorInstance) {
+    if (this.running) {
+      // If the orchestrator is already running, activate the actor immediately
+      await actor.start()
+    }
+    this.actors.push(actor)
+  }
+
+  /**
+   * Starts the orchestrator: activates all actors.
+   */
+  override async startHandler() {
+    await super.startHandler()
+    if (this.running) {
+      this.logger?.warn('[Orchestrator] Already started.')
+      return
+    }
+
+    this.logger?.log('[Orchestrator] Starting...')
+    this.running = true
+    for (const actor of this.actors) {
+      await actor.start()
+    }
+    // This interval will fire every 24.8 days (2^31 - 1 ms), effectively never finishing
+    this.keepAliveHandle = setInterval(() => {
+      // No-op
+    }, 2_147_483_647)
+  }
+
+  /**
+   * Stops the orchestrator: deactivates all actors.
+   */
+  override async stopHandler() {
+    await super.stopHandler()
+    if (!this.running) {
+      this.logger?.log('[Orchestrator] Already stopped.')
+      return
+    }
+
+    this.logger?.log('[Orchestrator] Stopping...')
+    for (const actor of this.actors) {
+      await actor.stop()
+    }
+    this.running = false
+    if (this.keepAliveHandle) clearInterval(this.keepAliveHandle)
+    this.logger?.log('[Orchestrator] Stopped...')
+  }
+}

package/src/orchestrator/index.ts

@@ -0,0 +1 @@
+export * from './Orchestrator.ts'