@xyo-network/xl1-cli-lib 1.7.4

package/src/initLogger.ts

@@ -0,0 +1,23 @@
+import { Base } from '@xylabs/base'
+import type { Logger, LogLevelValue } from '@xylabs/logger'
+import {
+  ConsoleLogger, LogLevel, SilentLogger,
+} from '@xylabs/logger'
+import { isDefined } from '@xylabs/typeof'
+import type { Config } from '@xyo-network/xl1-protocol-sdk'
+
+export const initLogger = (config: Config): Logger => {
+  let logger: Logger
+  if (config.silent) {
+    logger = new SilentLogger()
+  } else {
+    let level: LogLevelValue | undefined
+    if (isDefined(config.logLevel)) {
+      const parsed = LogLevel[config.logLevel.toLowerCase() as keyof typeof LogLevel]
+      if (isDefined(parsed)) level = parsed
+    }
+    logger = new ConsoleLogger(level)
+  }
+  Base.defaultLogger = logger
+  return logger
+}

package/src/optionsFromZodSchema.ts

@@ -0,0 +1,69 @@
+import type { Options } from 'yargs'
+import type { ZodTypeAny } from 'zod'
+import {
+  ZodBoolean, ZodDefault, ZodEnum, ZodNumber, ZodObject, ZodOptional,
+} from 'zod'
+
+const collectOptions = (
+  zodType: ZodTypeAny,
+  path: string[] = [],
+  out: Record<string, Options> = {},
+): Record<string, Options> => {
+  // Handle objects by descending into their shape
+  if (zodType instanceof ZodObject) {
+    const shape = (zodType as ZodObject<{}>).shape
+    for (const [k, v] of Object.entries(shape)) {
+      collectOptions(v as ZodTypeAny, [...path, k], out)
+    }
+    return out
+  }
+
+  // Handle defaults and optionals by descending into the inner type
+  // TODO: Less brittle
+  const def = zodType._def
+  if (def?.innerType instanceof ZodObject) {
+    const shape = def.innerType.shape
+    for (const [k, v] of Object.entries(shape)) {
+      collectOptions(v as ZodTypeAny, [...path, k], out)
+    }
+    return out
+  }
+
+  // Construct the Yargs Options
+  const options: Options = {}
+
+  // Assign the description
+  options.describe = def.description
+
+  // Assign the default value
+  options.default = typeof def.defaultValue === 'function'
+    ? def.defaultValue()
+    : def.defaultValue
+
+  // Assign the type
+  let type: 'string' | 'number' | 'boolean' = 'string'
+  const typeName = def.typeName === ZodDefault.name || def.typeName === ZodOptional.name
+    ? def.innerType._def.typeName
+    : def.typeName
+  if (typeName === ZodBoolean.name) type = 'boolean'
+  if (typeName === ZodNumber.name || def.coerce) type = 'number'
+  if (typeName === ZodEnum.name) {
+    options.choices = Object.values(def.innerType.enum)
+  }
+  options.type = type
+
+  // Build argument path e.g. "db.host" or "producer.port"
+  const key = path.join('.')
+  out[key] = options
+  return out
+}
+
+export const optionsFromZodSchema = (
+  schema: Record<string, ZodTypeAny>,
+): Record<string, Options> => {
+  const opts: Record<string, Options> = {}
+  for (const [rootKey, zodType] of Object.entries(schema)) {
+    collectOptions(zodType, [rootKey], opts)
+  }
+  return opts
+}

package/src/orchestration/ChainInitializableParams.ts

@@ -0,0 +1,12 @@
+import type { MeterProvider, TracerProvider } from '@opentelemetry/api'
+import type { InitializableParams } from '@xyo-network/xl1-protocol'
+import type { Config } from '@xyo-network/xl1-protocol-sdk'
+
+import type { RuntimeStatusMonitor } from './status/index.ts'
+
+export type ChainInitializableParams = InitializableParams<{
+  config: Config
+  meterProvider: MeterProvider
+  statusReporter: RuntimeStatusMonitor
+  traceProvider: TracerProvider
+}>

package/src/orchestration/actor/implementation/BalanceActor.ts

@@ -0,0 +1,50 @@
+import { assertEx } from '@xylabs/assert'
+import type { BaseParams } from '@xylabs/base'
+import type { Promisable } from '@xylabs/promise'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { ChainServiceCollectionV2, Config } from '@xyo-network/xl1-protocol-sdk'
+import { Mutex } from 'async-mutex'
+
+import { Actor } from '../model/index.ts'
+
+export type BalanceActorParams = BaseParams<
+  Pick<ChainServiceCollectionV2, 'balanceService' | 'chainIterator'>
+  & { config: Config }>
+
+export class BalanceActor extends Actor<BalanceActorParams> {
+  protected _updateMutex = new Mutex()
+
+  protected constructor(params: BalanceActorParams) {
+    super('BalanceActor', 'Balance', params)
+  }
+
+  protected get balanceService() {
+    return assertEx(this.params.balanceService, () => 'balanceService not set')
+  }
+
+  protected get chainIterator() {
+    return assertEx(this.params.chainIterator, () => 'chainIterator not set')
+  }
+
+  static create(params: BalanceActorParams): Promisable<BalanceActor> {
+    return new BalanceActor(params)
+  }
+
+  override async start(): Promise<void> {
+    await super.start()
+    this.chainIterator.on('headUpdate', async () => {
+      await this.updateBalance()
+    })
+    this.registerTimer('BalanceTimer', async () => {
+      await this.updateBalance()
+    }, 1000, 1000)
+  }
+
+  protected async updateBalance(): Promise<void> {
+    if (this._updateMutex.isLocked()) return
+    await this._updateMutex.runExclusive(async () => {
+      const head = await PayloadBuilder.hash(await this.chainIterator.head())
+      await this.balanceService.balances(head, [])
+    })
+  }
+}

package/src/orchestration/actor/implementation/ChainHeadUpdateActor.ts

@@ -0,0 +1,65 @@
+import { filterAs } from '@xylabs/array'
+import { assertEx } from '@xylabs/assert'
+import type { BaseParams } from '@xylabs/base'
+import { toHex } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import { findMostRecentBlock, sortBlocks } from '@xyo-network/chain-protocol'
+import type { Payload } from '@xyo-network/payload-model'
+import type { BlockBoundWitness } from '@xyo-network/xl1-protocol'
+import { asBlockBoundWitness } from '@xyo-network/xl1-protocol'
+import type { ChainServiceCollectionV2, Config } from '@xyo-network/xl1-protocol-sdk'
+
+import { Actor } from '../model/index.ts'
+
+export type ChainHeadUpdateActorParams = BaseParams<Pick<ChainServiceCollectionV2, 'chainIterator' | 'chainArchivist'> & { config: Config }>
+
+export class ChainHeadUpdateActor extends Actor<ChainHeadUpdateActorParams> {
+  protected constructor(params: ChainHeadUpdateActorParams) {
+    super('ChainHeadUpdate', 'ChainHeadUpdate', params)
+  }
+
+  protected get chainFinalizedArchivist() {
+    return assertEx(this.params.chainArchivist, () => 'ChainArchivist not set')
+  }
+
+  protected get chainIterator() {
+    return assertEx(this.params.chainIterator, () => 'chainIterator not set')
+  }
+
+  static create(params: ChainHeadUpdateActorParams): Promisable<ChainHeadUpdateActor> {
+    return new ChainHeadUpdateActor(params)
+  }
+
+  override async start(): Promise<void> {
+    await super.start()
+    // Register event handler on all insert event to check for new head
+    this.chainFinalizedArchivist.on('inserted', async (data: { payloads: Payload[] }) => {
+      await this.checkInsertedForNewHead(data)
+    })
+    // Poll in case we missed an event
+    this.registerTimer('ChainHeadUpdateTimer', async () => await this.pollForNewHead(), 0, 250)
+  }
+
+  private async checkInsertedForNewHead(data: { payloads: Payload[] }) {
+    const candidateBlock = sortBlocks(filterAs(data.payloads, asBlockBoundWitness)).at(-1)
+    await this.updateHeadIfNewer(candidateBlock)
+  }
+
+  private async pollForNewHead() {
+    const candidateBlock = await findMostRecentBlock(this.chainFinalizedArchivist)
+    await this.updateHeadIfNewer(candidateBlock)
+  }
+
+  private async updateHeadIfNewer(candidateBlock?: BlockBoundWitness) {
+    if (!candidateBlock) return
+    const currentHead = await this.chainIterator.head()
+    const candidateBlockNumber = candidateBlock.block
+    const candidateBlockNumberDisplay = `0x${toHex(candidateBlockNumber)}`
+    const currentBlockNumber = currentHead?.block ?? -1
+    if (candidateBlockNumber > currentBlockNumber) {
+      this.logger?.log('Found more recent head:', candidateBlockNumberDisplay)
+      await this.chainIterator.updateHead(candidateBlock)
+      this.logger?.log('Updated head:', candidateBlockNumberDisplay)
+    }
+  }
+}

package/src/orchestration/actor/implementation/ProducerActor.ts

@@ -0,0 +1,244 @@
+import { assertEx } from '@xylabs/assert'
+import type { BaseParams } from '@xylabs/base'
+import { toHex } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import { isDefined, isUndefined } from '@xylabs/typeof'
+import { createDeclarationIntent } from '@xyo-network/chain-protocol'
+import { BaseBlockProducerService } from '@xyo-network/chain-services'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { PayloadBundle } from '@xyo-network/payload-model'
+import { PayloadBundleSchema } from '@xyo-network/payload-model'
+import type { ChainStakeIntent, HydratedBlock } from '@xyo-network/xl1-protocol'
+import type { ChainServiceCollectionV2, Config } from '@xyo-network/xl1-protocol-sdk'
+import {
+  buildTransaction, flattenHydratedBlock, flattenHydratedTransaction,
+} from '@xyo-network/xl1-protocol-sdk'
+
+import { Actor } from '../model/index.ts'
+
+export type ProducerActorParams = BaseParams<
+  Pick<ChainServiceCollectionV2,
+  'account'
+  | 'balanceService'
+  | 'chainIterator'
+  | 'chainStakeViewer'
+  | 'chainSubmissionsArchivistWrite'
+  | 'pendingBundledTransactionsArchivistWrite'
+  | 'producer'
+  | 'stakeIntentService'
+  > & {
+    config: Config
+  }>
+
+const SHOULD_REGISTER_REDECLARATION_INTENT_TIMER = true
+const TEN_MINUTES = 10 * 60 * 1000 // 10 minutes in milliseconds
+
+export class ProducerActor extends Actor<ProducerActorParams> {
+  protected _lastProducedBlock: HydratedBlock | undefined
+  protected _lastRedeclarationIntent: ChainStakeIntent | undefined
+
+  protected constructor(params: ProducerActorParams) {
+    super(params.producer.address, 'Producer', params)
+  }
+
+  protected get account() {
+    return assertEx(this.params.account, () => 'account not set')
+  }
+
+  protected get balanceService() {
+    return assertEx(this.params.balanceService, () => 'balanceService not set')
+  }
+
+  protected get chainIterator() {
+    return assertEx(this.params.chainIterator, () => 'chainIterator not set')
+  }
+
+  protected get chainStakeViewer() {
+    return assertEx(this.params.chainStakeViewer, () => 'chainStakeViewer not set')
+  }
+
+  protected get chainSubmissionsArchivistWrite() {
+    return assertEx(this.params.chainSubmissionsArchivistWrite, () => 'chainSubmissionsArchivistWrite not set')
+  }
+
+  protected get pendingBundledTransactionsArchivistWrite() {
+    return assertEx(this.params.pendingBundledTransactionsArchivistWrite, () => 'pendingBundledTransactionsArchivistWrite not set')
+  }
+
+  protected get producer() {
+    return assertEx(this.params.producer, () => 'producer not set')
+  }
+
+  protected get stakeIntentService() {
+    return assertEx(this.params.stakeIntentService, () => 'stakeIntentService not set')
+  }
+
+  static create(params: ProducerActorParams): Promisable<ProducerActor> {
+    return new ProducerActor(params)
+  }
+
+  override async start(): Promise<void> {
+    await super.start()
+    // Register a timer to check if we should produce a block
+    this.registerTimer('BlockProductionTimer', async () => {
+      await this.spanAsync('produceBlock', async () => {
+        // Get the updated head
+        const head = await this.chainIterator.head()
+        // Check if we've already produced the next block for this head
+        const headHash = await PayloadBuilder.hash(head)
+        // If our last produced block was the next block for the current head, we do not
+        // need to produce another. This prevents duplicate blocks from being produced
+        if (this._lastProducedBlock && this._lastProducedBlock[0].previous === headHash) {
+          this.logger?.log('Block already produced:', `0x${toHex(this._lastProducedBlock[0].block)}`)
+        } else {
+          // Produce the next block
+          const nextBlock = await this.producer.next(head)
+          // If it was produced
+          if (nextBlock) {
+            const displayBlockNumber = `0x${toHex(nextBlock[0].block)}`
+            this.logger?.log('Produced block:', displayBlockNumber)
+            // Insert the block into the chain
+            await this.chainSubmissionsArchivistWrite.insert(flattenHydratedBlock(nextBlock))
+            this.logger?.log('Published block:', displayBlockNumber)
+            // Record that we have produced a block so we do not produce it again
+            this._lastProducedBlock = nextBlock
+          }
+        }
+      })
+    }, 100, 500)
+
+    if (SHOULD_REGISTER_REDECLARATION_INTENT_TIMER) {
+      // Register a timer to check if we should redeclare the producer
+      this.registerTimer('ProducerRedeclarationTimer', async () => {
+        await this.spanAsync('producerRedeclarationTimer', async () => {
+          // Decide if we should redeclare intent
+          if (this.params.config.producer.disableIntentRedeclaration) return
+
+          // Get the current block
+          const head = await this.chainIterator.head()
+          if (isUndefined(head)) return
+          const currentBlock = head.block
+
+          // Calculate the time until the producer's declaration expires
+          const blocksUntilExpiration = await this.calculateBlocksUntilProducerDeclarationExpiration(currentBlock)
+
+          // Allow the producer time to redeclare itself via block production
+          // (for free) before submitting a redeclaration intent transaction.
+          if (blocksUntilExpiration > BaseBlockProducerService.RedeclarationWindow * 0.1) {
+            // Clear any previous redeclaration intent
+            this._lastRedeclarationIntent = undefined
+            // No need to redeclare yet
+            return
+          }
+
+          // If we already have a valid redeclaration intent, do not create another
+          // unless it has expired.
+          if (this._lastRedeclarationIntent) {
+            // Check if the last redeclaration intent is still valid
+            if (this._lastRedeclarationIntent.exp > currentBlock) return
+            // If it has expired, clear the last redeclaration intent
+            this._lastRedeclarationIntent = undefined
+          }
+
+          // Check if we have a valid balance before declaring intent
+          if (!await this.validateCurrentBalance()) {
+            this.logger?.error(
+              `Add balance to address ${this.account.address} for the producer to declare it's intent.`,
+            )
+            return
+          }
+
+          // Check if we have a valid stake before declaring intent
+          if (!(await this.validateCurrentStake())) {
+            this.logger?.error(
+              `Add stake to contract address ${this.params.config.chain.id}`
+              + ' for the producer to declare it\'s intent.',
+            )
+            return
+          }
+
+          // Create a redeclaration intent
+          this.logger?.log('Creating redeclaration intent for producer:', this.account.address)
+          const redeclarationIntent = createDeclarationIntent(
+            this.account.address,
+            'producer',
+            currentBlock,
+            currentBlock + BaseBlockProducerService.RedeclarationDuration,
+          )
+
+          // Submit the redeclaration intent
+          await this.submitRedeclarationIntent(currentBlock, redeclarationIntent)
+
+          // On successful submission, save the redeclaration intent
+          this._lastRedeclarationIntent = redeclarationIntent
+        })
+      }, 10_000, TEN_MINUTES)
+    }
+  }
+
+  protected async calculateBlocksUntilProducerDeclarationExpiration(currentBlock: number): Promise<number> {
+    // Decide if we need to redeclare intent
+    const ranges = await this.stakeIntentService.getDeclaredCandidateRanges(this.account.address, 'producer')
+    // TODO: This doesn't handle the case where the producer had declared a range for the future
+    // but we're in a range that's not the future
+    // Sort in ascending order based on ending range to get range with highest ending block
+    const lastRange = ranges.toSorted((a, b) => a[1] > b[1] ? 1 : -1).at(-1)
+
+    // Use the most recent range's end block as the current declaration end OR
+    const [, currentDeclarationEnd] = lastRange
+    // If we have no ranges, we need to declare intent, so use the current block
+      || [undefined, currentBlock]
+
+    // Calculate the time until the producer's declaration expires
+    const timeToProducerExpiration = currentDeclarationEnd - currentBlock
+    return timeToProducerExpiration
+  }
+
+  protected async submitRedeclarationIntent(currentBlock: number, redeclarationIntent: ChainStakeIntent): Promise<void> {
+    this.logger?.log('Submitting redeclaration intent for producer:', this.account.address)
+    // Create a transaction to submit the redeclaration intent
+    const tx = await buildTransaction(
+      this.chainIterator.chainId,
+      [redeclarationIntent],
+      [],
+      this.account,
+      currentBlock,
+      currentBlock + 1000,
+    )
+    const payloads = flattenHydratedTransaction(tx)
+    const root = tx[0]._hash
+    const payloadBundle = new PayloadBuilder<PayloadBundle>({ schema: PayloadBundleSchema }).fields({ payloads, root }).build()
+
+    // Submit the redeclaration intent
+    await this.pendingBundledTransactionsArchivistWrite.insert([payloadBundle])
+
+    this.logger?.log('Submitted redeclaration intent for producer:', this.account.address)
+  }
+
+  protected async validateCurrentBalance(): Promise<boolean> {
+    // Check if we have a valid balance before declaring intent
+    const head = this._lastProducedBlock?.[0]._hash
+    if (isDefined(head)) {
+      const balances = await this.balanceService.balances(head, [this.account.address])
+      const currentBalance = balances[this.account.address] ?? 0n
+      if (currentBalance <= 0n) {
+        this.logger?.error(`Producer ${this.account.address} has no balance.`)
+        return false
+      }
+      return true
+    }
+    return true
+  }
+
+  protected async validateCurrentStake(): Promise<boolean> {
+    // Use StakeIntentService to get the required minimum stake
+    const requiredMinimumStake = this.stakeIntentService.getRequiredMinimumStakeForIntent('producer')
+    // Check if we have a valid stake before declaring intent
+    const currentStake = await this.chainStakeViewer.activeByAddressStaked(this.account.address)
+    if (currentStake < requiredMinimumStake) {
+      this.logger?.error(`Producer ${this.account.address} has insufficient stake.`)
+      return false
+    }
+    return true
+  }
+}

package/src/orchestration/actor/implementation/ValidatorActor.ts

@@ -0,0 +1,113 @@
+import { assertEx } from '@xylabs/assert'
+import type { BaseParams } from '@xylabs/base'
+import type { Hash } from '@xylabs/hex'
+import { toHex } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import { isDefined, isUndefined } from '@xylabs/typeof'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { BlockBoundWitness } from '@xyo-network/xl1-protocol'
+import type { ChainServiceCollectionV2, Config } from '@xyo-network/xl1-protocol-sdk'
+
+import { Actor } from '../model/index.ts'
+
+export type ValidatorActorParams = BaseParams<
+  Pick<ChainServiceCollectionV2,
+  'account'
+  | 'balanceService'
+  | 'chainIterator'
+  | 'chainStakeViewer'
+  | 'chainSubmissionsArchivistWrite'
+  | 'pendingBundledTransactionsArchivistWrite'
+  | 'stakeIntentService'
+  > & {
+    config: Config
+  }>
+
+export class ValidatorActor extends Actor<ValidatorActorParams> {
+  protected _lastValidatedBlock: BlockBoundWitness | undefined
+  protected _lastValidatedBlockHash: Hash | undefined
+
+  protected constructor(params: ValidatorActorParams) {
+    super('Validator', 'Validator', params)
+  }
+
+  protected get account() {
+    return assertEx(this.params.account, () => 'account not set')
+  }
+
+  protected get balanceService() {
+    return assertEx(this.params.balanceService, () => 'balanceService not set')
+  }
+
+  protected get chainIterator() {
+    return assertEx(this.params.chainIterator, () => 'chainIterator not set')
+  }
+
+  protected get chainStakeViewer() {
+    return assertEx(this.params.chainStakeViewer, () => 'chainStakeViewer not set')
+  }
+
+  protected get chainSubmissionsArchivistWrite() {
+    return assertEx(this.params.chainSubmissionsArchivistWrite, () => 'chainSubmissionsArchivistWrite not set')
+  }
+
+  protected get pendingBundledTransactionsArchivistWrite() {
+    return assertEx(this.params.pendingBundledTransactionsArchivistWrite, () => 'pendingBundledTransactionsArchivistWrite not set')
+  }
+
+  protected get stakeIntentService() {
+    return assertEx(this.params.stakeIntentService, () => 'stakeIntentService not set')
+  }
+
+  // protected get validator() {
+  //   return assertEx(this.params.validator, () => 'validator not set')
+  // }
+
+  static create(params: ValidatorActorParams): Promisable<ValidatorActor> {
+    return new ValidatorActor(params)
+  }
+
+  override async start(): Promise<void> {
+    await super.start()
+    // Register a timer to check if we should produce a block
+    this.registerTimer('BlockProductionTimer', async () => {
+      await this.spanAsync('produceBlock', async () => {
+        // Get the updated head
+        const block = await this.chainIterator.head()
+        if (isUndefined(block)) return
+        // Check if we've already validated this head
+        const hash = await PayloadBuilder.hash(block)
+        // If our last validated block was this head, skip validation
+        if (isDefined(this._lastValidatedBlock) && this._lastValidatedBlockHash === hash) {
+          this.logger?.log('Block already validated:', `0x${toHex(block.block)}`)
+        } else {
+          this.logger?.log('Validating block:', `0x${toHex(block.block)}`)
+          const valid = await this.validateBlock(block)
+          if (valid) {
+            this.logger?.log('Validated block:', `0x${toHex(block.block)}`)
+          } else {
+            this.logger?.log('Invalid block:', `0x${toHex(block.block)}`)
+            await this.slashInvalidBlock(block)
+          }
+        }
+      })
+    }, 100, 500)
+  }
+
+  protected async slashInvalidBlock(_block: BlockBoundWitness): Promise<boolean> {
+    // TODO: Handle slashing logic
+    const slashed = await Promise.resolve(true)
+    return slashed
+  }
+
+  protected async validateBlock(block: BlockBoundWitness): Promise<boolean> {
+    // TODO: Validate using validation logic
+    const valid = await Promise.resolve(true)
+    // Store the last validated block and its hash
+    this._lastValidatedBlock = block
+    this._lastValidatedBlockHash = await PayloadBuilder.hash(block)
+
+    // Return the validation result
+    return valid
+  }
+}

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

@@ -0,0 +1,4 @@
+export * from './BalanceActor.ts'
+export * from './ChainHeadUpdateActor.ts'
+export * from './ProducerActor.ts'
+export * from './ValidatorActor.ts'

package/src/orchestration/actor/index.ts

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