@xyo-network/xl1-cli-lib 1.7.4

package/src/orchestration/host/implementation/DefaultServiceCollection.ts

@@ -0,0 +1,60 @@
+import type {
+  ServiceCollection, ServiceDescriptor, ServiceProvider,
+} from '../model/index.ts'
+import { ServiceLifetime } from '../model/index.ts'
+import { DefaultServiceProvider } from './DefaultServiceProvider.ts'
+
+/**
+ * A collection of service descriptors, allowing adding/removing services before building.
+ */
+export class DefaultServiceCollection implements ServiceCollection {
+  private readonly descriptors: ServiceDescriptor[] = []
+
+  /**
+   * Register a service as Singleton: a single instance is created and shared.
+   */
+  addSingleton<T>(
+    identifier: string | symbol,
+    implementationFactory: () => T,
+  ): void {
+    this.descriptors.push({
+      identifier,
+      lifetime: ServiceLifetime.Singleton,
+      implementationFactory,
+    })
+  }
+
+  /**
+   * Register a service as Transient: a new instance is created on each request.
+   */
+  addTransient<T>(
+    _identifier: string | symbol,
+    _implementationFactory: () => T,
+  ): void {
+    throw new Error('Not implemented')
+  }
+
+  /**
+   * Build a concrete, immutable service provider from the current descriptors.
+   */
+  build(): ServiceProvider {
+    const services: Record<string, unknown> = {}
+    for (const descriptor of this.descriptors) {
+      if (descriptor.lifetime === ServiceLifetime.Singleton) {
+        services[descriptor.identifier.toString()] = descriptor.implementationFactory()
+      }
+    }
+    return new DefaultServiceProvider(services)
+  }
+
+  /**
+   * Removes all registrations matching the given identifier.
+   */
+  remove(identifier: string | symbol): void {
+    for (let i = this.descriptors.length - 1; i >= 0; i--) {
+      if (this.descriptors[i].identifier === identifier) {
+        this.descriptors.splice(i, 1)
+      }
+    }
+  }
+}

package/src/orchestration/host/implementation/DefaultServiceProvider.ts

@@ -0,0 +1,12 @@
+import type { ServiceProvider } from '../model/index.ts'
+
+export class DefaultServiceProvider implements ServiceProvider {
+  protected _services: Record<string, unknown>
+  constructor(services: Record<string, unknown>) {
+    this._services = services
+  }
+
+  getService<T>(serviceIdentifier: string): T | undefined {
+    return this._services[serviceIdentifier] as T
+  }
+}

package/src/orchestration/host/implementation/index.ts

@@ -0,0 +1,2 @@
+export * from './DefaultHost.ts'
+export * from './DefaultServiceProvider.ts'

package/src/orchestration/host/index.ts

@@ -0,0 +1,2 @@
+export * from './implementation/index.ts'
+export * from './model/index.ts'

package/src/orchestration/host/model/Host.ts

@@ -0,0 +1,21 @@
+import type { ServiceProvider } from './ServiceProvider.ts'
+
+/**
+ * Represents the host for an application.
+ */
+export interface Host {
+  /**
+   * Provides access to the application's services (for dependency injection).
+   */
+  services: ServiceProvider
+
+  /**
+   * Starts the host and any underlying services (e.g., background tasks).
+   */
+  start(): Promise<void>
+
+  /**
+   * Stops the host and attempts to gracefully shut down services.
+   */
+  stop(): Promise<void>
+}

package/src/orchestration/host/model/ServiceCollection.ts

@@ -0,0 +1,22 @@
+import type { ServiceProvider } from './ServiceProvider.ts'
+
+export interface ServiceCollection {
+  build(): ServiceProvider
+}
+
+/**
+ * Represents the lifetime of a service
+ */
+export const ServiceLifetime = {
+  Singleton: 'Singleton',
+  Transient: 'Transient',
+} as const
+
+/**
+ * Describes a single service registration
+ */
+export interface ServiceDescriptor<T = unknown> {
+  identifier: string | symbol
+  implementationFactory: () => T
+  lifetime: keyof typeof ServiceLifetime
+}

package/src/orchestration/host/model/ServiceProvider.ts

@@ -0,0 +1,3 @@
+export interface ServiceProvider {
+  getService<T = unknown>(serviceIdentifier: string): T | undefined
+}

package/src/orchestration/host/model/index.ts

@@ -0,0 +1,3 @@
+export * from './Host.ts'
+export * from './ServiceCollection.ts'
+export * from './ServiceProvider.ts'

package/src/orchestration/index.ts

@@ -0,0 +1,5 @@
+export * from './actor/index.ts'
+export * from './health/index.ts'
+export * from './initServices.ts'
+export * from './services/index.ts'
+export * from './status/index.ts'

package/src/orchestration/initServices.ts

@@ -0,0 +1,240 @@
+import { assertEx } from '@xylabs/assert'
+import { asAddress } from '@xylabs/hex'
+import type { Logger } from '@xylabs/logger'
+import { isDefined } from '@xylabs/typeof'
+import { balanceSummaryRepositoryFromMap } from '@xyo-network/chain-modules'
+import type { BaseBlockProducerServiceParams, XyoValidatorParams } from '@xyo-network/chain-services'
+import { initTelemetry } from '@xyo-network/chain-telemetry'
+import { startupSpanAsync } from '@xyo-network/chain-utils'
+import { validateHydratedBlockState } from '@xyo-network/chain-validation'
+import type { ChainServiceCollectionV2, Config } from '@xyo-network/xl1-protocol-sdk'
+
+import {
+  initChainFinalizedArchivist, initChainSubmissionsArchivist, initPendingBundledTransactionsArchivist, initRejectedTransactionsArchivist,
+  initStakeIntentStateArchivist,
+} from './archivists/index.ts'
+import type { ChainInitializableParams } from './ChainInitializableParams.ts'
+import { initHealthEndpoints } from './health/index.ts'
+import { initBalanceSummaryMap } from './map/index.ts'
+import {
+  initAccount, initBalanceService, initBlockProducer, initBlockRewardService, initChainIterator, initChainService, initElectionService, initHead,
+  initPendingTransactions, initStakeIntentService,
+} from './services/index.ts'
+import { RuntimeStatusMonitor } from './status/index.ts'
+
+const telemetryConfig = {
+  attributes: {
+    serviceName: 'xl1-producer',
+    serviceVersion: '1.0.0',
+  },
+  metricsConfig: {
+    endpoint: '/metrics',
+    port: 9464,
+  },
+}
+
+interface Startable {
+  start: () => Promise<void>
+}
+
+const isStartable = (value: unknown): value is Startable => {
+  return isDefined((value as Startable).start) && typeof (value as Startable).start === 'function'
+}
+
+interface InitServicesContext {
+  config: Config
+  logger: Logger
+}
+
+export const initServices = async (context: InitServicesContext): Promise<ChainServiceCollectionV2> => {
+  const { config, logger } = context
+  const statusReporter = new RuntimeStatusMonitor(logger)
+  statusReporter.onGlobalTransition({ to: 'started' }, () => {
+    logger.log('All services started.')
+  })
+  statusReporter.onGlobalTransition({ to: 'error' }, () => {
+    logger.error('Producer encountered an unhandled error!')
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(1)
+  })
+
+  await startupSpanAsync('initHealthEndpoints', () => initHealthEndpoints({ ...context, statusReporter }))
+
+  const [
+    { traceProvider, meterProvider },
+    account,
+  ] = await Promise.all([
+    startupSpanAsync('initTelemetry', () => initTelemetry(telemetryConfig)),
+    startupSpanAsync('initAccount', () => initAccount(context)),
+  ])
+
+  const initParams: ChainInitializableParams = {
+    config, logger, meterProvider, statusReporter, traceProvider,
+  }
+
+  // Archivists
+  const [
+    chainArchivist,
+    [pendingBundledTransactionsArchivist, pendingBundledTransactionsArchivistWrite],
+    rejectedTransactionsArchivist,
+    chainSubmissionsArchivistWrite,
+    stakeIntentStateArchivist,
+    chainService,
+    balanceSummaryMap,
+  ] = await Promise.all([
+    startupSpanAsync(
+      'ChainFinalizedArchivist',
+      () => initChainFinalizedArchivist(initParams),
+    ),
+    startupSpanAsync(
+      'PendingBundledTransactionsArchivist',
+      () => initPendingBundledTransactionsArchivist(initParams),
+    ),
+    startupSpanAsync(
+      'RejectedTransactionsArchivist',
+      () => initRejectedTransactionsArchivist(initParams),
+    ),
+    startupSpanAsync(
+      'ChainSubmissionsArchivist',
+      () => initChainSubmissionsArchivist(initParams),
+    ),
+    startupSpanAsync(
+      'StakeIntentStateArchivist',
+      () => initStakeIntentStateArchivist(initParams),
+    ),
+    startupSpanAsync(
+      'ChainService',
+      () => initChainService({
+        ...initParams, account, name: 'ChainService',
+      }),
+    ),
+    startupSpanAsync(
+      'BalanceSummaryMap',
+      () => initBalanceSummaryMap(initParams),
+    ),
+  ])
+
+  const chainId = chainService.chainId
+  const chainContractViewer = chainService
+  const chainStakeViewer = chainService
+  const chainStaker = chainService
+  const head = await startupSpanAsync('initHead', () => initHead({
+    ...initParams, account, chainArchivist, chainSubmissionsArchivistWrite,
+  }))
+  const [
+    pendingTransactionsService,
+    rewardService,
+    chainIterator,
+    balanceService,
+  ] = await Promise.all([
+    startupSpanAsync('PendingTransactions', () => initPendingTransactions({
+      name: 'PendingTransactionsService',
+      chainArchivist,
+      chainId,
+      pendingBundledTransactionsArchivist,
+      rejectedTransactionsArchivist,
+      ...initParams,
+    })),
+    startupSpanAsync(
+      'RewardService',
+      () => initBlockRewardService({
+        name: 'RewardService',
+        account,
+        chainService,
+        ...initParams,
+      }),
+    ),
+    startupSpanAsync(
+      'ChainIterator',
+      () => initChainIterator({
+        name: 'ChainIterator',
+        chainArchivist,
+        head,
+        ...initParams,
+      }),
+    ),
+    startupSpanAsync(
+      'BalanceService',
+      () => initBalanceService({
+        name: 'BalanceService',
+        chainArchivist,
+        summaryRepository: balanceSummaryRepositoryFromMap(balanceSummaryMap),
+        ...initParams,
+      }),
+    ),
+  ])
+
+  const stakeIntentService = await startupSpanAsync(
+    'StakeIntentService',
+    () => initStakeIntentService({
+      name: 'StakeIntentService',
+      chainArchivist,
+      chainIterator,
+      chainStakeViewer,
+      stakeIntentStateArchivist,
+      ...initParams,
+    }),
+  )
+
+  const electionService = await startupSpanAsync(
+    'ElectionService',
+    () => initElectionService({
+      name: 'ElectionService',
+      chainIterator,
+      chainStakeViewer,
+      stakeIntentService,
+      ...initParams,
+    }),
+  )
+
+  const validatorParams: XyoValidatorParams = {
+    name: 'Validator',
+    account,
+    chainId,
+    pendingBundledTransactionsArchivist,
+    chainArchivist,
+    electionService,
+    rewardService,
+    stakeIntentService,
+    validateHydratedBlockState,
+    ...initParams,
+  }
+  const rewardAddress = isDefined(config.producer.rewardAddress)
+    ? assertEx(asAddress(config.producer.rewardAddress), () => 'Invalid block reward address provided')
+    : account.address
+  const producerParams: BaseBlockProducerServiceParams = {
+    ...validatorParams,
+    name: 'Producer',
+    balanceService,
+    chainArchivist,
+    pendingBundledTransactionsArchivist,
+    pendingTransactionsService,
+    rejectedTransactionsArchivist,
+    rewardAddress,
+    ...initParams,
+  }
+  const producer = await startupSpanAsync('Producer', () => initBlockProducer(producerParams))
+  // TODO: Add to base service collection
+  const result: ChainServiceCollectionV2 = {
+    account,
+    balanceService,
+    chainArchivist,
+    chainContractViewer,
+    chainIterator,
+    chainStaker,
+    chainStakeViewer,
+    chainSubmissionsArchivistWrite,
+    electionService,
+    pendingBundledTransactionsArchivistWrite,
+    pendingTransactionsService,
+    producer,
+    rewardService,
+    stakeIntentService,
+  }
+
+  logger?.log('All services created. Starting...')
+  const startableServices = [balanceSummaryMap, ...Object.values(result)].filter(isStartable)
+  // Start all services that have a start method
+  await Promise.all(startableServices.map(service => service.start()))
+  return result
+}

package/src/orchestration/map/BalanceSummary/index.ts

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

package/src/orchestration/map/BalanceSummary/initBalanceSummaryMap.ts

@@ -0,0 +1,22 @@
+import type { Hash } from '@xylabs/hex'
+import { isDefined } from '@xylabs/typeof'
+import type { MapType } from '@xyo-network/chain-protocol'
+import { startupSpanAsync } from '@xyo-network/chain-utils'
+import type { WithStorageMeta } from '@xyo-network/payload-model'
+import type { BalancesStepSummary } from '@xyo-network/xl1-protocol-sdk'
+import { Mutex } from 'async-mutex'
+
+import type { ChainInitializableParams } from '../../ChainInitializableParams.ts'
+import { initLocalBalanceSummaryMap } from './local.ts'
+
+const mutex = new Mutex()
+let singleton: MapType<Hash, WithStorageMeta<BalancesStepSummary>> | undefined
+
+export async function initBalanceSummaryMap(params: ChainInitializableParams): Promise<MapType<Hash, WithStorageMeta<BalancesStepSummary>>> {
+  return await mutex.runExclusive(async () => {
+    if (isDefined(singleton)) return singleton
+    const local = await startupSpanAsync('BalanceSummaryMap:initLocal', () => initLocalBalanceSummaryMap(params))
+    singleton = local
+    return singleton
+  })
+}

package/src/orchestration/map/BalanceSummary/local.ts

@@ -0,0 +1,21 @@
+import type { Hash } from '@xylabs/hex'
+import { isDefined } from '@xylabs/typeof'
+import type { MapType } from '@xyo-network/chain-protocol'
+import type { WithStorageMeta } from '@xyo-network/payload-model'
+import type { BalancesStepSummary } from '@xyo-network/xl1-protocol-sdk'
+import { Mutex } from 'async-mutex'
+
+import type { ChainInitializableParams } from '../../ChainInitializableParams.ts'
+import { getLocalPersistentMap } from '../localPersistentMap.ts'
+
+const mutex = new Mutex()
+let singleton: MapType<Hash, WithStorageMeta<BalancesStepSummary>> | undefined
+
+export const initLocalBalanceSummaryMap = async (params: ChainInitializableParams): Promise<MapType<Hash, WithStorageMeta<BalancesStepSummary>>> => {
+  return await mutex.runExclusive(async () => {
+    if (isDefined(singleton)) return singleton
+    const { root } = params.config.storage
+    singleton = await getLocalPersistentMap<Hash, WithStorageMeta<BalancesStepSummary>>('balance', 'summary', root)
+    return singleton
+  })
+}

package/src/orchestration/map/driver/index.ts

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

package/src/orchestration/map/driver/lmdb/Params.ts

@@ -0,0 +1,7 @@
+import type { CreatableParams } from '@xylabs/creatable'
+
+export interface LmdbMapParams extends CreatableParams {
+  dbName: string
+  location: string
+  storeName: string
+}

package/src/orchestration/map/driver/lmdb/SynchronousLmdbMap.ts

@@ -0,0 +1,66 @@
+import { AbstractCreatable, creatable } from '@xylabs/creatable'
+import { SynchronousMap } from '@xyo-network/chain-protocol'
+import {
+  Database, Key, open, RootDatabase,
+} from 'lmdb'
+
+import { LmdbMapParams } from './Params.ts'
+
+// TODO: Abstract creatable instead of service?
+/**
+ * A synchronous LMDB-backed Map implementation.
+ * This class provides a synchronous interface to an LMDB database, allowing for key-value storage.
+ * It allows for multi-tenancy within a single LMDB environment by using a root database (located
+ * at this.folderPath) and a specific DB within the environment (specified by this.params.storeName).
+ * @template K - The type of keys in the map.
+ * @template V - The type of values in the map.
+ */
+@creatable()
+export class SynchronousLmdbMap<K extends Key, V> extends AbstractCreatable<LmdbMapParams> implements SynchronousMap<K, V> {
+  protected db!: Database<V, K>
+  protected rootDatabase!: RootDatabase
+
+  /**
+   * The path to the LMDB folder where the database is stored.
+   * This is constructed from the location and dbName parameters
+   * allowing for multiple DBs within the root (by specifying a
+   * different storeName).
+   * @returns The folder path for the LMDB database.
+   */
+  get folderPath() {
+    return `${this.params.location}/${this.params.dbName}`
+  }
+
+  all(): V[] {
+    return [...this.db.getRange({})].map(entry => entry.value)
+  }
+
+  clear(): void {
+    this.db.clearSync()
+  }
+
+  delete(id: K): boolean {
+    return this.db.removeSync(id)
+  }
+
+  get(id: K): V | undefined {
+    return this.db.get(id)
+  }
+
+  has(id: K): boolean {
+    return this.db.doesExist(id)
+  }
+
+  set(id: K, data: V): this {
+    this.db.putSync(id, data)
+    return this
+  }
+
+  override async startHandler(): Promise<void> {
+    await super.startHandler()
+    // Initialize the DB Environment (opens the default LMDB database)
+    this.rootDatabase = open({ path: this.folderPath })
+    // Open the desired DB (using the store name)
+    this.db = this.rootDatabase.openDB<V, K>({ name: this.params.storeName })
+  }
+}

package/src/orchestration/map/driver/lmdb/index.ts

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

package/src/orchestration/map/driver/lmdb/spec/SynchronousLmdbMap.spec.ts

@@ -0,0 +1,97 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import {
+  afterEach, beforeEach, describe, expect, it,
+} from 'vitest'
+
+import type { LmdbMapParams } from '../Params.ts'
+import { SynchronousLmdbMap } from '../SynchronousLmdbMap.ts'
+
+type TestKey = string
+type TestValue = { age: number; name: string }
+
+describe('SynchronousLmdbMap', () => {
+  let map: SynchronousLmdbMap<TestKey, TestValue>
+  let tempDir: string
+
+  const params: LmdbMapParams = {
+    dbName: 'test-db',
+    storeName: 'test-store',
+    location: '', // Will be set to temp dir
+  }
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(path.join(tmpdir(), 'lmdb-test-'))
+    params.location = tempDir
+    map = await SynchronousLmdbMap.create<SynchronousLmdbMap<TestKey, TestValue>>(params)
+    await map.start()
+  })
+
+  afterEach(async () => {
+    map.clear()
+    await map.stop()
+    rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  it('should set and get a value', () => {
+    const key = 'user-1'
+    const value = { name: 'Alice', age: 30 }
+    map.set(key, value)
+    const result = map.get(key)
+    expect(result).toEqual(value)
+  })
+
+  it('should return true for has() if key exists', () => {
+    const key = 'user-2'
+    const value = { name: 'Bob', age: 25 }
+    map.set(key, value)
+    expect(map.has(key)).toBe(true)
+  })
+
+  it('should return false for has() if key does not exist', () => {
+    expect(map.has('nonexistent')).toBe(false)
+  })
+
+  it('should delete a key and return true', () => {
+    const key = 'user-3'
+    const value = { name: 'Charlie', age: 40 }
+    map.set(key, value)
+    const deleted = map.delete(key)
+    expect(deleted).toBe(true)
+    expect(map.has(key)).toBe(false)
+    expect(map.get(key)).toBeUndefined()
+  })
+
+  it('should return false for delete() if key does not exist', () => {
+    const deleted = map.delete('missing')
+    expect(deleted).toBe(false)
+  })
+
+  it('should clear all data', () => {
+    const key1 = 'user-4'
+    const value1 = { name: 'Dana', age: 22 }
+    const key2 = 'user-5'
+    const value2 = { name: 'Eve', age: 28 }
+    map.set(key1, value1)
+    map.set(key2, value2)
+    map.clear()
+    expect(map.has(key1)).toBe(false)
+    expect(map.has(key2)).toBe(false)
+    expect(map.all()).toEqual([])
+  })
+
+  it('should return all values', () => {
+    const key1 = 'a'
+    const value1 = { name: 'Anna', age: 33 }
+    const key2 = 'b'
+    const value2 = { name: 'Ben', age: 44 }
+    map.set(key1, value1)
+    map.set(key2, value2)
+    const values = map.all()
+    expect(values).toContainEqual(value1)
+    expect(values).toContainEqual(value2)
+    expect(values.length).toBe(2)
+  })
+})

package/src/orchestration/map/index.ts

@@ -0,0 +1,2 @@
+export * from './BalanceSummary/index.ts'
+export * from './driver/index.ts'

package/src/orchestration/map/localPersistentMap.ts

@@ -0,0 +1,52 @@
+import { rm } from 'node:fs/promises'
+import Path from 'node:path'
+
+import type { MapType } from '@xyo-network/chain-protocol'
+
+import type { StoreKind } from '../store/index.ts'
+import { getStoreDirectory } from '../store/index.ts'
+import { SynchronousLmdbMap } from './driver/index.ts'
+
+const DEFAULT_STORAGE_ROOT = Path.join(process.cwd(), '.store')
+
+/**
+ * Returns a local persistent map
+ * @param dbName The name of the database
+ * @param storeName The name of the store
+ * @param storageRoot The root directory for storage (default is '.store' in the current working directory)
+ * @param kind The kind of the map
+ * @returns a map
+ */
+export const getLocalPersistentMap = async <TId, TData>(
+  dbName: string,
+  storeName: string,
+  storageRoot?: string,
+  kind: StoreKind = 'lmdb'): Promise<MapType<TId, TData>> => {
+  switch (kind) {
+    case 'lmdb': {
+      const root = storageRoot ?? DEFAULT_STORAGE_ROOT
+      const location = getStoreDirectory(dbName, root, 'lmdb')
+      const store = await SynchronousLmdbMap.create({
+        location, dbName, storeName,
+      })
+      return store as unknown as MapType<TId, TData>
+    }
+  }
+}
+
+export const deleteLocalPersistentMap = async (
+  dbName: string,
+  storageRoot?: string,
+  kind: StoreKind = 'lmdb',
+): Promise<void> => {
+  await Promise.resolve()
+  let location = ''
+  switch (kind) {
+    case 'lmdb': {
+      const root = storageRoot ?? DEFAULT_STORAGE_ROOT
+      location = getStoreDirectory(dbName, root, 'lmdb')
+      break
+    }
+  }
+  await rm(location, { recursive: true, force: true })
+}

package/src/orchestration/repository/index.ts

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

package/src/orchestration/repository/lib/index.ts

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