@xyo-network/xl1-cli 1.6.2

package/src/orchestration/services/implementation/chain/index.ts

@@ -0,0 +1,27 @@
+import type { Promisable } from '@xylabs/promise'
+import type { BaseAccountableServiceParams } from '@xyo-network/chain-services'
+import { MemoryChainService } from '@xyo-network/chain-services'
+import type { ChainService, Initializable } from '@xyo-network/xl1-protocol'
+
+import { canUseEvmContractChainService, initEvmContractChainService } from './evm.ts'
+
+let chainStakeServiceSingleton: Promisable<ChainService> | undefined
+
+export const initChainService: Initializable<BaseAccountableServiceParams, ChainService> = ({ account }) => init({ name: 'ChainService', account })
+
+const init: Initializable<BaseAccountableServiceParams, ChainService> = ({
+  account, traceProvider, meterProvider, logger,
+}): Promisable<ChainService> => {
+  if (chainStakeServiceSingleton) return chainStakeServiceSingleton
+  chainStakeServiceSingleton = canUseEvmContractChainService()
+    ? initEvmContractChainService({
+        name: 'ChainStakeService',
+        account,
+        traceProvider,
+        meterProvider,
+        logger,
+      })
+    : MemoryChainService.create({})
+  // Create service
+  return chainStakeServiceSingleton
+}

package/src/orchestration/services/implementation/evm/index.ts

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

package/src/orchestration/services/implementation/evm/initChainId.ts

@@ -0,0 +1,18 @@
+import { assertEx } from '@xylabs/assert'
+import { hexFrom, isHex } from '@xylabs/hex'
+
+export const canUseChainId = (): boolean => {
+  return process.env.XYO_JSON_RPC_NETWORK !== undefined
+}
+
+export const getChainId = () => {
+  const chainId = assertEx(process.env.XYO_JSON_RPC_NETWORK, () => 'Missing XYO_JSON_RPC_NETWORK ENV VAR')
+  if (isHex(chainId, { prefix: true })) {
+    const hex = hexFrom(chainId)
+    const parsed = Number.parseInt(hex, 16)
+    return parsed
+  } else {
+    const parsed = Number.parseInt(chainId, 10)
+    return parsed
+  }
+}

package/src/orchestration/services/implementation/evm/initEvmProvider.ts

@@ -0,0 +1,21 @@
+import { assertEx } from '@xylabs/assert'
+import type { JsonRpcProvider } from 'ethers/providers'
+
+import { canUseJsonRpcProvider, initJsonRpcProvider } from './initGanacheProvider.ts'
+import { canUseInfuraProvider, initInfuraProvider } from './initInfuraProvider.ts'
+
+let provider: Promise<JsonRpcProvider> | undefined
+
+export const initEvmProvider = async () => {
+  if (provider) return provider
+  if (canUseInfuraProvider()) {
+    provider = initInfuraProvider()
+  } else if (canUseJsonRpcProvider()) {
+    provider = initJsonRpcProvider()
+  }
+  return assertEx(await provider, () => 'Error: No provider available')
+}
+
+export const canUseEvmProvider = () => {
+  return canUseInfuraProvider() || canUseJsonRpcProvider()
+}

package/src/orchestration/services/implementation/evm/initGanacheProvider.ts

@@ -0,0 +1,19 @@
+import { assertEx } from '@xylabs/assert'
+import { JsonRpcProvider } from 'ethers/providers'
+
+import { canUseChainId, getChainId } from './initChainId.ts'
+
+export const initJsonRpcProvider = () => {
+  const config = getJsonRpcProviderConfig()
+  return Promise.resolve(new JsonRpcProvider(...config))
+}
+
+export const canUseJsonRpcProvider = () => {
+  return canUseChainId()
+    && process.env.XYO_JSON_RPC_URL !== undefined
+}
+
+export const getJsonRpcProviderConfig = () => {
+  const jsonRpcUrl = assertEx(process.env.XYO_JSON_RPC_URL, () => 'Missing XYO_JSON_RPC_URL ENV VAR')
+  return [jsonRpcUrl, getChainId()] as const
+}

package/src/orchestration/services/implementation/evm/initInfuraProvider.ts

@@ -0,0 +1,25 @@
+import { assertEx } from '@xylabs/assert'
+import { InfuraProvider } from 'ethers/providers'
+
+import { canUseChainId, getChainId } from './initChainId.ts'
+
+let instance: Promise<InfuraProvider> | undefined
+
+export const initInfuraProvider = () => {
+  if (instance) return instance
+  const config = getInfuraProviderConfig()
+  instance = Promise.resolve(new InfuraProvider(...config))
+  return instance
+}
+
+export const canUseInfuraProvider = (): boolean => {
+  return canUseChainId()
+    && process.env.INFURA_PROJECT_ID != undefined
+    && process.env.INFURA_PROJECT_SECRET != undefined
+}
+
+export const getInfuraProviderConfig = () => {
+  const projectId = assertEx(process.env.INFURA_PROJECT_ID, () => 'Missing INFURA_PROJECT_ID ENV VAR')
+  const projectSecret = assertEx(process.env.INFURA_PROJECT_SECRET, () => 'Missing INFURA_PROJECT_SECRET ENV VAR')
+  return [getChainId(), projectId, projectSecret] as const
+}

package/src/orchestration/services/implementation/head.ts

@@ -0,0 +1,44 @@
+import { delay } from '@xylabs/delay'
+import { ZERO_ADDRESS } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { ArchivistInstance } from '@xyo-network/archivist-model'
+import { createGenesisBlock, findMostRecentBlock } from '@xyo-network/chain-protocol'
+import type { WithStorageMeta } from '@xyo-network/payload-model'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type { BlockBoundWitness, Initializable } from '@xyo-network/xl1-protocol'
+import { flattenHydratedBlock } from '@xyo-network/xl1-protocol-sdk'
+
+let headSingleton: Promisable<WithStorageMeta<BlockBoundWitness>> | undefined
+
+const createBootstrapHead = async (
+  chainSubmissionsArchivistWrite: ArchivistInstance,
+  chainArchivist: ArchivistInstance,
+  account: WalletInstance,
+): Promise<WithStorageMeta<BlockBoundWitness>> => {
+  const block = await createGenesisBlock(account, ZERO_ADDRESS, 10_000_000n, account.address)
+  const [bw] = block
+  await chainSubmissionsArchivistWrite.insert(flattenHydratedBlock(block))
+  // Wait for block to show up in finalized archivist
+  while (true) {
+    const result = await chainArchivist.get([bw._hash])
+    if (result.length > 0) break
+    await delay(1000) // Wait 1 second before retrying
+  }
+  return bw
+}
+
+export const initHead: Initializable<{
+  account: WalletInstance
+  chainArchivist: ArchivistInstance
+  chainSubmissionsArchivistWrite: ArchivistInstance
+}, WithStorageMeta<BlockBoundWitness>>
+ = async (params): Promise<WithStorageMeta<BlockBoundWitness>> => {
+   const {
+     account, chainArchivist, chainSubmissionsArchivistWrite,
+   } = params
+   if (headSingleton) return headSingleton
+   let head = await findMostRecentBlock(chainArchivist)
+   if (!head) head = await createBootstrapHead(chainSubmissionsArchivistWrite, chainArchivist, account)
+   headSingleton = head
+   return headSingleton
+ }

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

@@ -0,0 +1,10 @@
+export * from './account.ts'
+export * from './balance.ts'
+export * from './chain/index.ts'
+export * from './evm/index.ts'
+export * from './head.ts'
+export * from './iterator.ts'
+export * from './pendingTransactions.ts'
+export * from './producer.ts'
+export * from './reward.ts'
+export * from './validator.ts'

package/src/orchestration/services/implementation/iterator.ts

@@ -0,0 +1,36 @@
+import type {
+  BaseElectionServicesParams,
+  XyoChainIteratorParams,
+  XyoStakeIntentServiceParams,
+} from '@xyo-network/chain-services'
+import {
+  BaseElectionService, ChainBlockNumberIterationService,
+  XyoStakeIntentService,
+} from '@xyo-network/chain-services'
+import type {
+  ElectionService, EventingChainBlockNumberIterator, Initializable, StakeIntentService,
+} from '@xyo-network/xl1-protocol'
+
+let chainIteratorServiceSingleton: Promise<EventingChainBlockNumberIterator> | undefined
+let stakeIntentServiceSingleton: Promise<StakeIntentService> | undefined
+let electionServiceSingleton: Promise<ElectionService> | undefined
+
+export const initChainIterator: Initializable<XyoChainIteratorParams, EventingChainBlockNumberIterator> = (params) => {
+  if (chainIteratorServiceSingleton) return chainIteratorServiceSingleton
+  chainIteratorServiceSingleton = ChainBlockNumberIterationService.create(params)
+  return chainIteratorServiceSingleton
+}
+
+export const initStakeIntentService: Initializable<XyoStakeIntentServiceParams, StakeIntentService>
+= (params) => {
+  if (stakeIntentServiceSingleton) return stakeIntentServiceSingleton
+  stakeIntentServiceSingleton = XyoStakeIntentService.create(params)
+  return stakeIntentServiceSingleton
+}
+
+export const initElectionService: Initializable<BaseElectionServicesParams, ElectionService>
+= (params) => {
+  if (electionServiceSingleton) return electionServiceSingleton
+  electionServiceSingleton = BaseElectionService.create(params)
+  return electionServiceSingleton
+}

package/src/orchestration/services/implementation/pendingTransactions.ts

@@ -0,0 +1,14 @@
+import type { Promisable } from '@xylabs/promise'
+import type { BasePendingTransactionsServiceParams } from '@xyo-network/chain-services'
+import { BasePendingTransactionsService } from '@xyo-network/chain-services'
+import type { Initializable, PendingTransactionsService } from '@xyo-network/xl1-protocol'
+
+let serviceSingleton: Promisable<PendingTransactionsService> | undefined
+
+export const initPendingTransactions: Initializable<BasePendingTransactionsServiceParams, PendingTransactionsService> = async (
+  params: BasePendingTransactionsServiceParams,
+): Promise<PendingTransactionsService> => {
+  if (serviceSingleton) return serviceSingleton
+  serviceSingleton = await BasePendingTransactionsService.create(params)
+  return serviceSingleton
+}

package/src/orchestration/services/implementation/producer.ts

@@ -0,0 +1,13 @@
+import type { Promisable } from '@xylabs/promise'
+import type { BaseBlockProducerServiceParams } from '@xyo-network/chain-services'
+import { BaseBlockProducerService } from '@xyo-network/chain-services'
+import type { BlockProducerService, Initializable } from '@xyo-network/xl1-protocol'
+
+let serviceSingleton: Promisable<BlockProducerService> | undefined
+
+export const initBlockProducer: Initializable<BaseBlockProducerServiceParams, BlockProducerService>
+= async (params: BaseBlockProducerServiceParams): Promise<BlockProducerService> => {
+  if (serviceSingleton) return serviceSingleton
+  serviceSingleton = await BaseBlockProducerService.create(params)
+  return serviceSingleton
+}

package/src/orchestration/services/implementation/reward.ts

@@ -0,0 +1,37 @@
+import { assertEx } from '@xylabs/assert'
+import type { BaseBlockRewardServiceParams, EvmBlockRewardServiceParams } from '@xyo-network/chain-services'
+import { EvmBlockRewardService, MemoryBlockRewardService } from '@xyo-network/chain-services'
+import type { BlockRewardService, Initializable } from '@xyo-network/xl1-protocol'
+
+import { canUseEvmProvider, initEvmProvider } from './evm/index.ts'
+
+let rewardServiceSingleton: Promise<BlockRewardService> | undefined
+
+export const initBlockRewardService: Initializable<
+  BaseBlockRewardServiceParams | EvmBlockRewardServiceParams,
+  BlockRewardService
+> = (params): Promise<BlockRewardService> => {
+  if (rewardServiceSingleton) return rewardServiceSingleton
+  rewardServiceSingleton = canUseEvmBlockRewardService() ? initEvmBlockRewardService(params as EvmBlockRewardServiceParams) : initXyoBlockRewardService(params)
+  return rewardServiceSingleton
+}
+
+const initXyoBlockRewardService = (params: BaseBlockRewardServiceParams): Promise<BlockRewardService> => {
+  if (rewardServiceSingleton) return rewardServiceSingleton
+  rewardServiceSingleton = MemoryBlockRewardService.create(params)
+  return rewardServiceSingleton
+}
+
+const canUseEvmBlockRewardService = () => canUseEvmProvider()
+
+const initEvmBlockRewardService = async (params: EvmBlockRewardServiceParams): Promise<BlockRewardService> => {
+  if (rewardServiceSingleton) return rewardServiceSingleton
+  const { account: paramsAccount } = params
+  const account = assertEx(paramsAccount, () => 'Error: Account is required')
+  const provider = assertEx(await initEvmProvider())
+  const evmBlockRewardServiceParams: EvmBlockRewardServiceParams = {
+    ...params, provider, account,
+  }
+  rewardServiceSingleton = EvmBlockRewardService.create(evmBlockRewardServiceParams)
+  return rewardServiceSingleton
+}

package/src/orchestration/services/implementation/validator.ts

@@ -0,0 +1,14 @@
+import type { Promisable } from '@xylabs/promise'
+import type { BaseBlockProducerServiceParams } from '@xyo-network/chain-services'
+import type { BlockProducerService, Initializable } from '@xyo-network/xl1-protocol'
+
+import { initBlockProducer } from './producer.ts'
+
+let serviceSingleton: Promisable<BlockProducerService> | undefined
+
+export const initValidator: Initializable<BaseBlockProducerServiceParams, BlockProducerService>
+= (params: BaseBlockProducerServiceParams): Promisable<BlockProducerService> => {
+  if (serviceSingleton) return serviceSingleton
+  serviceSingleton = initBlockProducer(params)
+  return serviceSingleton
+}

package/src/orchestration/services/index.ts

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

package/src/orchestration/status/RuntimeStatusMonitor.ts

@@ -0,0 +1,117 @@
+import type { CreatableStatus } from '@xylabs/creatable'
+
+import { LoggerStatusReporter } from './ServiceStatus.ts'
+
+/**
+ * Enum-like record for statuses with priority allowing
+ * for determination of the aggregated status.
+ */
+const statusPriority: Record<CreatableStatus, number> = {
+  error: 0,
+  stopped: 1,
+  stopping: 2,
+  creating: 3,
+  created: 4,
+  starting: 5,
+  started: 6,
+}
+
+/**
+ * A sentinel status that represents the initial state
+ * before any statuses are reported.
+ * It is used to ensure that the monitor has a valid status
+ * even when no statuses have been reported yet and to
+ * prevent the system from showing an "error" state
+ * when no statuses are available.
+ */
+const SENTINEL_STATUS: CreatableStatus = 'starting'
+
+/**
+ * Given an array of statuses, this function reduces them
+ * to the minimum status based on the defined priority.
+ * @param statuses An array of statuses to reduce.
+ * @returns The minimum status based on priority.
+ */
+const reduceToMinimumStatus = (statuses: CreatableStatus[]): CreatableStatus => {
+  let minStatus: CreatableStatus = SENTINEL_STATUS
+  let minPriority = Infinity
+
+  for (const status of statuses) {
+    const priority = statusPriority[status]
+    if (priority < minPriority) {
+      minPriority = priority
+      minStatus = status
+    }
+  }
+  return minStatus
+}
+
+export type GlobalTransitionHandler = {
+  from?: CreatableStatus
+  handler: (from: CreatableStatus, to: CreatableStatus) => void
+  to?: CreatableStatus
+}
+export type TransitionHandler = GlobalTransitionHandler & {
+  name?: string
+}
+
+export class RuntimeStatusMonitor extends LoggerStatusReporter {
+  private globalTransitions: GlobalTransitionHandler[] = []
+  private transitions: TransitionHandler[] = []
+
+  getGlobalStatus(): CreatableStatus {
+    // If no statuses have been reported, return the sentinel status
+    if (Object.keys(this.statusMap).length === 0) return SENTINEL_STATUS
+    return reduceToMinimumStatus(Object.values(this.statusMap))
+  }
+
+  getStatus(name: string): CreatableStatus | undefined {
+    return this.statusMap[name]
+  }
+
+  onGlobalTransition(match: { from?: CreatableStatus; to?: CreatableStatus }, handler: (from: CreatableStatus, to: CreatableStatus) => void) {
+    this.globalTransitions.push({ ...match, handler })
+  }
+
+  /**
+   * Register a callback to be called on a specific transition.
+   */
+  onTransition(match: { from?: CreatableStatus; name: string; to?: CreatableStatus }, handler: (from: CreatableStatus, to: CreatableStatus) => void) {
+    this.transitions.push({ ...match, handler })
+  }
+
+  override report(name: string, status: CreatableStatus, progress?: number | Error): void {
+    // Capture the current status before updating
+    const previous = this.statusMap[name]
+    const previousGlobal = this.getGlobalStatus()
+
+    // Update the status map with the new status
+    super.report(name, status, progress)
+
+    // If the status hasn't changed, do not run handlers
+    if (previous === status) return
+    this.runTransitions(this.transitions, previous, status, name)
+
+    // If the global status hasn't changed, do not run handlers
+    const globalStatus = this.getGlobalStatus()
+    if (previousGlobal === globalStatus) return
+    this.runTransitions(this.globalTransitions, previousGlobal, globalStatus)
+  }
+
+  private runTransitions(
+    transitions: (TransitionHandler | GlobalTransitionHandler)[],
+    prev: CreatableStatus,
+    next: CreatableStatus,
+    name?: string,
+  ) {
+    for (const {
+      from, to, name: matchName, handler,
+    } of transitions as TransitionHandler[]) {
+      if ((matchName === undefined || matchName === name)
+        && (from === undefined || from === prev)
+        && (to === undefined || to === next)) {
+        handler(prev, next)
+      }
+    }
+  }
+}

package/src/orchestration/status/ServiceStatus.ts

@@ -0,0 +1,21 @@
+import type {
+  CreatableName, CreatableStatus, CreatableStatusReporter,
+} from '@xylabs/creatable'
+import type { Logger } from '@xylabs/logger'
+
+export class LoggerStatusReporter implements CreatableStatusReporter {
+  protected logger: Logger
+
+  protected statusMap: Record<CreatableName, CreatableStatus> = {}
+
+  constructor(logger: Logger) {
+    this.logger = logger
+  }
+
+  report(name: string, status: CreatableStatus, progress?: number | Error): void {
+    this.statusMap[name] = status
+    const starting = (Object.entries(this.statusMap).map(([, value]): number => value === 'starting' ? 1 : 0)).reduce((a, b) => a + b, 0)
+    const started = (Object.entries(this.statusMap).map(([, value]): number => value === 'started' ? 1 : 0)).reduce((a, b) => a + b, 0)
+    this.logger.info(`${started}/${starting + started} ${name} status: ${status}`, { progress })
+  }
+}

package/src/orchestration/status/index.ts

@@ -0,0 +1,2 @@
+export * from './RuntimeStatusMonitor.ts'
+export * from './ServiceStatus.ts'

package/src/orchestration/store/StoreKind.ts

@@ -0,0 +1 @@
+export type StoreKind = 'lmdb'

package/src/orchestration/store/getStoreDirectory.ts

@@ -0,0 +1,15 @@
+import Path from 'node:path'
+
+import type { StoreKind } from './StoreKind.ts'
+
+const STORAGE_ROOT = process.env.STORAGE_ROOT ?? Path.join(process.cwd(), '.store')
+
+/**
+ * Creates a convention-based directory path for an archivist store
+ * @param name The name of the archivist
+ * @param kind The kind of the archivist (optional)
+ * @returns The directory path for the archivist store
+ */
+export const getStoreDirectory = (name: string, kind?: StoreKind): string => {
+  return (kind === undefined) ? Path.join(STORAGE_ROOT, name) : Path.join(STORAGE_ROOT, kind, name)
+}

package/src/orchestration/store/index.ts

@@ -0,0 +1,2 @@
+export * from './getStoreDirectory.ts'
+export * from './StoreKind.ts'

package/src/runCLI.ts

@@ -0,0 +1,96 @@
+import net from 'node:net'
+
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
+
+import {
+  runApi, runProducer, runValidator,
+} from './commands/index.ts'
+import type { Orchestrator } from './orchestration/index.ts'
+
+function waitForPort(host: string, port: number): Promise<void> {
+  return new Promise((resolve) => {
+    const tryConnect = () => {
+      const socket = new net.Socket()
+
+      socket
+        .setTimeout(1000)
+        .once('error', () => {
+          socket.destroy()
+          setTimeout(tryConnect, 500) // retry after 500ms
+        })
+        .once('timeout', () => {
+          socket.destroy()
+          setTimeout(tryConnect, 500)
+        })
+        .connect(port, host, () => {
+          socket.end()
+          resolve()
+        })
+    }
+
+    tryConnect()
+  })
+}
+
+// Main entry point
+export async function runCLI(orchestrator: Orchestrator) {
+  async function validateTransaction() {
+    console.log('Validating transaction...')
+    await Promise.resolve()
+  }
+
+  async function submitTransaction() {
+    console.log('Submitting transaction...')
+    await Promise.resolve()
+  }
+
+  async function checkBalance() {
+    console.log('Checking account balance...')
+    await Promise.resolve()
+  }
+
+  // Parse command-line arguments using Yargs
+  const argv = yargs(hideBin(process.argv))
+  // .commandDir('./command/commands', opts) // Not yet supported for ESM
+  // .wrap((yargs as Argv).terminalWidth())
+    .command('validator', 'Run the XL1 validator', (yargs) => {
+      return yargs
+      // Default command is to run
+        .command('$0', 'Run as a XL1 validator node', () => {}, () => runValidator(orchestrator))
+    })
+    .command('producer', 'Run the XL1 producer', (yargs) => {
+      return yargs
+        .command('$0', 'Run as a XL1 producer node', () => {}, () => runProducer(orchestrator))
+    })
+    .command('client', 'Client-related operations', (yargs) => {
+      return yargs
+        .command('transaction', 'Transaction-related operations', (yargs) => {
+          return yargs
+            .command('validate', 'Validate a transaction', () => {}, validateTransaction)
+            .command('submit', 'Submit a transaction', () => {}, submitTransaction)
+        })
+    })
+    .command('api', 'Run as a api node', (yargs) => {
+      return yargs
+        .command('$0', 'Run as a api node', () => {}, () => runApi())
+        .command('run', 'Run as a api node', () => {}, () => runApi())
+    })
+    .command('$0', 'Run a full XL1 deployment', (yargs) => {
+      return yargs
+        .command('$0', 'Start the API and a producer', () => {}, async () => {
+          runApi()
+          await waitForPort('localhost', 8080)
+          await runProducer(orchestrator)
+        })
+    })
+    .command('account', 'Account-related operations', (yargs) => {
+      return yargs.command('balance', 'Check account balance', () => {}, checkBalance)
+    })
+    .help()
+    .alias('help', 'h')
+    .env('XL1')
+    .argv
+
+  await argv
+}