@xyo-network/xl1-cli-lib 1.14.1 → 1.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyo-network/xl1-cli-lib",
-  "version": "1.14.1",
+  "version": "1.14.3",
   "description": "XYO Layer One CLI Library",
   "homepage": "https://xylabs.com",
   "bugs": {
@@ -52,20 +52,20 @@
     "@xylabs/promise": "~5.0.11",
     "@xylabs/telemetry": "~5.0.11",
     "@xylabs/typeof": "~5.0.11",
-    "@xyo-network/archivist-lmdb": "~5.1.0",
-    "@xyo-network/archivist-memory": "~5.1.0",
-    "@xyo-network/archivist-model": "~5.1.0",
-    "@xyo-network/chain-api": "~1.14.1",
-    "@xyo-network/chain-sdk": "~1.14.1",
-    "@xyo-network/payload-builder": "~5.1.0",
-    "@xyo-network/payload-model": "~5.1.0",
-    "@xyo-network/wallet": "~5.1.0",
-    "@xyo-network/wallet-model": "~5.1.0",
-    "@xyo-network/xl1-protocol": "~1.11.0",
-    "@xyo-network/xl1-protocol-sdk": "~1.14.1",
+    "@xyo-network/archivist-lmdb": "~5.1.2",
+    "@xyo-network/archivist-memory": "~5.1.2",
+    "@xyo-network/archivist-model": "~5.1.2",
+    "@xyo-network/chain-api": "~1.14.3",
+    "@xyo-network/chain-sdk": "~1.14.3",
+    "@xyo-network/payload-builder": "~5.1.2",
+    "@xyo-network/payload-model": "~5.1.2",
+    "@xyo-network/wallet": "~5.1.2",
+    "@xyo-network/wallet-model": "~5.1.2",
+    "@xyo-network/xl1-protocol": "~1.12.22",
+    "@xyo-network/xl1-protocol-sdk": "~1.14.3",
     "async-mutex": "~0.5.0",
     "cosmiconfig": "~9.0.0",
-    "dotenv": "~17.2.1",
+    "dotenv": "~17.2.2",
     "ethers": "~6.15.0",
     "lmdb": "~3.4.2",
     "yargs": "~18.0.0",

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

@@ -8,7 +8,7 @@ import { Mutex } from 'async-mutex'
 import { Actor } from '../model/index.ts'
 
 export type BalanceActorParams = BaseParams<
-  Pick<ChainServiceCollectionV2, 'balanceService' | 'chainIterator'>
+  Pick<ChainServiceCollectionV2, 'balance' | 'chainIterator'>
   & { config: Config }>
 
 export class BalanceActor extends Actor<BalanceActorParams> {
@@ -19,7 +19,7 @@ export class BalanceActor extends Actor<BalanceActorParams> {
   }
 
   protected get balanceService() {
-    return assertEx(this.params.balanceService, () => 'balanceService not set')
+    return assertEx(this.params.balance, () => 'balanceService not set')
   }
 
   protected get chainIterator() {

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

@@ -57,9 +57,9 @@ export class ChainHeadUpdateActor extends Actor<ChainHeadUpdateActorParams> {
     const candidateBlockNumberDisplay = `0x${toHex(candidateBlockNumber)}`
     const currentBlockNumber = currentHead?.block ?? -1
     if (candidateBlockNumber > currentBlockNumber) {
-      this.logger?.log('Found more recent head:', candidateBlockNumberDisplay)
+      this.logger?.log('Found more recent head:', candidateBlockNumber, candidateBlockNumberDisplay)
       await this.chainIterator.updateHead(candidateBlock)
-      this.logger?.log('Updated head:', candidateBlockNumberDisplay)
+      this.logger?.log('Updated head:', candidateBlockNumber, candidateBlockNumberDisplay)
     }
   }
 }

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

@@ -18,13 +18,13 @@ import { Actor } from '../model/index.ts'
 export type ProducerActorParams = BaseParams<
   Pick<ChainServiceCollectionV2,
   'account'
-  | 'balanceService'
+  | 'balance'
   | 'chainIterator'
   | 'chainStakeViewer'
   | 'chainSubmissionsArchivistWrite'
   | 'pendingBundledTransactionsArchivistWrite'
   | 'producer'
-  | 'stakeIntentService'
+  | 'stakeIntent'
   > & {
     config: Config
   }>
@@ -45,7 +45,7 @@ export class ProducerActor extends Actor<ProducerActorParams> {
   }
 
   protected get balanceService() {
-    return assertEx(this.params.balanceService, () => 'balanceService not set')
+    return assertEx(this.params.balance, () => 'balanceService not set')
   }
 
   protected get chainIterator() {
@@ -69,7 +69,7 @@ export class ProducerActor extends Actor<ProducerActorParams> {
   }
 
   protected get stakeIntentService() {
-    return assertEx(this.params.stakeIntentService, () => 'stakeIntentService not set')
+    return assertEx(this.params.stakeIntent, () => 'stakeIntentService not set')
   }
 
   static create(params: ProducerActorParams): Promisable<ProducerActor> {

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

@@ -13,12 +13,12 @@ import { Actor } from '../model/index.ts'
 export type ValidatorActorParams = BaseParams<
   Pick<ChainServiceCollectionV2,
   'account'
-  | 'balanceService'
+  | 'balance'
   | 'chainIterator'
   | 'chainStakeViewer'
   | 'chainSubmissionsArchivistWrite'
   | 'pendingBundledTransactionsArchivistWrite'
-  | 'stakeIntentService'
+  | 'stakeIntent'
   > & {
     config: Config
   }>
@@ -36,7 +36,7 @@ export class ValidatorActor extends Actor<ValidatorActorParams> {
   }
 
   protected get balanceService() {
-    return assertEx(this.params.balanceService, () => 'balanceService not set')
+    return assertEx(this.params.balance, () => 'balanceService not set')
   }
 
   protected get chainIterator() {
@@ -56,7 +56,7 @@ export class ValidatorActor extends Actor<ValidatorActorParams> {
   }
 
   protected get stakeIntentService() {
-    return assertEx(this.params.stakeIntentService, () => 'stakeIntentService not set')
+    return assertEx(this.params.stakeIntent, () => 'stakeIntentService not set')
   }
 
   // protected get validator() {

package/src/orchestration/actor/model/Actor.ts

@@ -1,7 +1,7 @@
 import type { TracerProvider } from '@opentelemetry/api'
 import { Base, type BaseParams } from '@xylabs/base'
 import { IdLogger } from '@xylabs/logger'
-import { span, spanAsync } from '@xylabs/telemetry'
+import { span, spanRootAsync } from '@xylabs/telemetry'
 import type { Config } from '@xyo-network/xl1-protocol-sdk'
 
 export interface IActor {
@@ -87,7 +87,7 @@ export class Actor<TParams extends ActorParams = ActorParams> extends Base<TPara
   }
 
   async spanAsync<T>(name: string, fn: () => Promise<T>): Promise<T> {
-    return await spanAsync(`${this.name}:${name}`, fn, this.tracer)
+    return await spanRootAsync(`${this.name}:${name}`, fn, this.tracer)
   }
 
   /**

package/src/orchestration/archivists/ChainFinalized/local.ts

@@ -12,7 +12,7 @@ export const initLocalChainFinalizedArchivist: Initializable<{ config: Config },
   return await mutex.runExclusive(async () => {
     if (singleton) return singleton
     const { root } = config.storage
-    singleton = await getLocalPersistentArchivist('chain', 'finalized', root)
+    singleton = await getLocalPersistentArchivist('local-finalized-chain', 'chain', 'finalized', root)
     return singleton
   })
 }

package/src/orchestration/archivists/StakeIntentState/local.ts

@@ -13,7 +13,7 @@ export const initLocalStakeIntentStateArchivist: Initializable<{ config: Config
   return await mutex.runExclusive(async () => {
     if (singleton) return singleton
     const { root } = config.storage
-    singleton = await getLocalPersistentArchivist('stakeIntent', 'state', root)
+    singleton = await getLocalPersistentArchivist('local-stake-intent-state', 'stakeIntent', 'state', root)
     return assertEx(singleton, () => new Error('Failed to initialize stake intent state archivist'))
   })
 }

package/src/orchestration/archivists/lib/localPersistentArchivist.ts

@@ -17,13 +17,20 @@ const DEFAULT_STORAGE_ROOT = Path.join(process.cwd(), '.store')
  * @param kind The kind of the archivist
  * @returns an archivist instance
  */
-export const getLocalPersistentArchivist = (dbName: string, storeName: string, storageRoot?: string, kind: StoreKind = 'lmdb'): Promise<ArchivistInstance> => {
+export const getLocalPersistentArchivist = (
+  name: string,
+  dbName: string,
+  storeName: string,
+  storageRoot?: string,
+  kind: StoreKind = 'lmdb',
+): Promise<ArchivistInstance> => {
   switch (kind) {
     case 'lmdb': {
       const root = storageRoot ?? DEFAULT_STORAGE_ROOT
       return LmdbArchivist.create({
         account: 'random',
         config: {
+          name,
           clearStoreOnStart: false,
           dbName,
           location: getStoreDirectory(dbName, root, 'lmdb'),

package/src/orchestration/initServices.ts

@@ -5,7 +5,7 @@ import type { Logger } from '@xylabs/logger'
 import { isDefined } from '@xylabs/typeof'
 import type { BaseBlockProducerServiceParams, XyoValidatorParams } from '@xyo-network/chain-sdk'
 import {
-  balanceSummaryRepositoryFromMap, initTelemetry, startupSpanAsync, validateHydratedBlockState,
+  balanceSummaryRepositoryFromMap, BaseTimeSyncService, initTelemetry, startupSpanAsync, validateHydratedBlockState,
 } from '@xyo-network/chain-sdk'
 import type { ChainServiceCollectionV2, Config } from '@xyo-network/xl1-protocol-sdk'
 
@@ -119,7 +119,7 @@ export const initServices = async (context: InitServicesContext): Promise<ChainS
   const chainStakeViewer = chainService
   const chainStaker = chainService
   const head = await startupSpanAsync('initHead', () => initHead({
-    ...initParams, account, chainArchivist, chainSubmissionsArchivistWrite,
+    ...initParams, account, chainArchivist, chainSubmissionsArchivistWrite, chainService,
   }))
   const [
     pendingTransactionsService,
@@ -199,6 +199,9 @@ export const initServices = async (context: InitServicesContext): Promise<ChainS
     validateHydratedBlockState,
     ...initParams,
   }
+
+  const time = await BaseTimeSyncService.create({ chainArchivist, chainIterator })
+
   const rewardAddress = isDefined(config.producer.rewardAddress)
     ? assertEx(asAddress(config.producer.rewardAddress), () => 'Invalid block reward address provided')
     : account.address
@@ -211,25 +214,26 @@ export const initServices = async (context: InitServicesContext): Promise<ChainS
     pendingTransactionsService,
     rejectedTransactionsArchivist,
     rewardAddress,
+    time,
     ...initParams,
   }
   const producer = await startupSpanAsync('Producer', () => initBlockProducer(producerParams))
   // TODO: Add to base service collection
   const result: ChainServiceCollectionV2 = {
     account,
-    balanceService,
+    balance: balanceService,
     chainArchivist,
     chainContractViewer,
     chainIterator,
     chainStaker,
     chainStakeViewer,
     chainSubmissionsArchivistWrite,
-    electionService,
+    election: electionService,
     pendingBundledTransactionsArchivistWrite,
-    pendingTransactionsService,
+    pendingTransactions: pendingTransactionsService,
     producer,
-    rewardService,
-    stakeIntentService,
+    reward: rewardService,
+    stakeIntent: stakeIntentService,
   }
 
   logger?.log('All services created. Starting...')

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

@@ -0,0 +1,8 @@
+import { ZERO_ADDRESS } from '@xylabs/hex'
+import { createGenesisBlock } from '@xyo-network/chain-sdk'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type { HydratedBlock } from '@xyo-network/xl1-protocol'
+
+export const createBootstrapHead = async (account: WalletInstance): Promise<HydratedBlock> => {
+  return await createGenesisBlock(account, ZERO_ADDRESS, 10_000_000n, account.address)
+}

package/src/orchestration/services/implementation/head/createForkedHead/config/getBridgeDestinationDetails.ts

@@ -0,0 +1,27 @@
+import { toHex } from '@xylabs/hex'
+import type { BridgeDetailsDestinationFields } from '@xyo-network/xl1-protocol'
+
+import { getForkBlockRewardHex } from './getForkDetails.ts'
+
+// const bridgeableTokenContract = toHex('0x4865Cb10d55cfB0E60DD2B4F9b888f6a49B76733')
+// const bridgeDestAddress = toHex('0xe53218d47913b5f9E58bb74F0a0eD790bbF21972')
+// const destConfirmation = toHex('0x4fa05d7e799f36f1d45c441a4866eb4570a00a753a39377f404a8d113c01a657') // Eth TX for mint
+const ethChainId = toHex('0x1')
+const bridgeableTokenContract = toHex('0x7789e11BB83b398A8Cca8E8D582B33F91499D6f5')
+const bridgeDestAddress = toHex('0xe53218d47913b5f9E58bb74F0a0eD790bbF21972')
+const destConfirmation = toHex('0x772ee028f9ad291ec692912c1a33ecd4409e71383fe06f6ebf39f7cdbb779069') // Eth TX for mint
+
+export const getBridgeDestChainId = () => ethChainId
+export const getBridgeDestToken = () => bridgeableTokenContract
+export const getBridgeDestAddress = () => bridgeDestAddress
+export const getBridgeDestAmount = () => getForkBlockRewardHex()
+export const getBridgeDestConfirmation = () => destConfirmation
+
+export const getBridgeDestinationDetails = (): BridgeDetailsDestinationFields => {
+  return {
+    dest: getBridgeDestChainId(),
+    destToken: getBridgeDestToken(),
+    destAddress: getBridgeDestAddress(),
+    destAmount: getBridgeDestAmount(),
+  }
+}

package/src/orchestration/services/implementation/head/createForkedHead/config/getBridgeSourceDetails.ts

@@ -0,0 +1,18 @@
+import type { AccountInstance } from '@xyo-network/account-model'
+import type { BridgeDetailsSourceFields, ChainService } from '@xyo-network/xl1-protocol'
+
+import { getForkBlockRewardHex } from './getForkDetails.ts'
+
+export const getBridgeSrcChainId = (chainService: ChainService) => chainService.chainId
+export const getBridgeSrcAddress = (account: AccountInstance) => account.address
+export const getBridgeSrcToken = (chainService: ChainService) => chainService.chainId
+export const getBridgeSrcAmount = () => getForkBlockRewardHex()
+
+export const getBridgeSourceDetails = (account: AccountInstance, chainService: ChainService): BridgeDetailsSourceFields => {
+  return {
+    src: getBridgeSrcChainId(chainService),
+    srcAddress: getBridgeSrcAddress(account),
+    srcToken: getBridgeSrcToken(chainService),
+    srcAmount: getBridgeSrcAmount(),
+  }
+}

package/src/orchestration/services/implementation/head/createForkedHead/config/getForkDetails.ts

@@ -0,0 +1,10 @@
+import { type Hex, toHex } from '@xylabs/hex'
+import { AttoXL1ConvertFactor } from '@xyo-network/xl1-protocol'
+
+export const getForkBlockReward = (): bigint => {
+  return 18_000_000_000n * AttoXL1ConvertFactor.xl1 // 18b XL1 in AttoXL1
+}
+
+export const getForkBlockRewardHex = (): Hex => {
+  return toHex(getForkBlockReward())
+}

package/src/orchestration/services/implementation/head/createForkedHead/config/index.ts

@@ -0,0 +1,3 @@
+export * from './getBridgeDestinationDetails.ts'
+export * from './getBridgeSourceDetails.ts'
+export * from './getForkDetails.ts'

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

@@ -0,0 +1,31 @@
+import type { WithHashStorageMeta } from '@xyo-network/payload-model'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BlockBoundWitness, ChainService, HydratedBlock,
+} from '@xyo-network/xl1-protocol'
+
+import { getBridgeDestinationObservation } from './getBridgeDestinationObservation.ts'
+import { getBridgeIntent } from './getBridgeIntent.ts'
+import { getBridgeSourceObservation } from './getBridgeSourceObservation.ts'
+import { getFirstBlockForNewChain } from './getFirstBlockForNewChain.ts'
+
+export const createForkedHead = async (
+  forkFromBlock: WithHashStorageMeta<BlockBoundWitness>,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<HydratedBlock[]> => {
+  const chain: HydratedBlock[] = []
+  // Build the first block for the new chain
+  const firstBlockForNewChain = await getFirstBlockForNewChain(forkFromBlock, account, chainService)
+  chain.push(firstBlockForNewChain)
+  // Build the bridge intent
+  const bridgeIntent = await getBridgeIntent(firstBlockForNewChain, account, chainService)
+  chain.push(bridgeIntent)
+  // Build the bridge source observation
+  const bridgeSourceObservation = await getBridgeSourceObservation(bridgeIntent, account, chainService)
+  chain.push(bridgeSourceObservation)
+  // Build the bridge destination observation
+  const bridgeDestinationObservation = await getBridgeDestinationObservation(bridgeSourceObservation, account, chainService)
+  chain.push(bridgeDestinationObservation)
+  return chain
+}

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

@@ -0,0 +1,38 @@
+import { BridgeDestinationObservationSchema, buildNextBlock } from '@xyo-network/chain-sdk'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BridgeDestinationObservation, BridgeDestinationObservationFields, ChainService, HydratedBlock,
+} from '@xyo-network/xl1-protocol'
+
+import {
+  getBridgeDestConfirmation, getBridgeDestinationDetails, getBridgeSourceDetails,
+} from './config/index.ts'
+
+/**
+ * Get the bridge destination observation for a given block.
+ * @param previousBlock The previous block to base the observation on.
+ * @param account The wallet account to use for the observation.
+ * @param chainService The chain service to use for the observation.
+ */
+export const getBridgeDestinationObservation = async (
+  previousBlock: HydratedBlock,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<HydratedBlock> => {
+  const bridgeDestinationObservationFields: BridgeDestinationObservationFields = {
+    ...getBridgeSourceDetails(account, chainService),
+    ...getBridgeDestinationDetails(),
+    destConfirmation: getBridgeDestConfirmation(),
+  }
+  const bridgeDestinationObservation = new PayloadBuilder<BridgeDestinationObservation>({ schema: BridgeDestinationObservationSchema })
+    .fields(bridgeDestinationObservationFields)
+    .build()
+
+  return await buildNextBlock(
+    previousBlock[0],
+    [],
+    [bridgeDestinationObservation],
+    [account],
+  )
+}

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

@@ -0,0 +1,50 @@
+import {
+  BridgeIntentSchema, buildNextBlock, createTransferPayload, XYO_BRIDGE_ADDRESS,
+} from '@xyo-network/chain-sdk'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BridgeIntent, BridgeIntentFields, ChainService, HydratedBlock,
+} from '@xyo-network/xl1-protocol'
+
+import {
+  getBridgeDestinationDetails, getBridgeSourceDetails, getForkBlockReward,
+} from './config/index.ts'
+
+/**
+ * Get the bridge intent for a given block.
+ * @param previousBlock The previous block to base the intent on.
+ * @param account The wallet account to use for the intent.
+ * @param chainService The chain service to use for the intent.
+ */
+export const getBridgeIntent = async (
+  previousBlock: HydratedBlock,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<HydratedBlock> => {
+  // Create transfer to bridge address
+  const transferPayload = createTransferPayload(
+    account.address,
+    { [XYO_BRIDGE_ADDRESS]: getForkBlockReward() },
+  )
+
+  // Use timestamp as nonce
+  const nonce = `${Date.now()}`
+
+  // Create Bridge Intent
+  const bridgeIntentFields: BridgeIntentFields = {
+    ...getBridgeSourceDetails(account, chainService),
+    ...getBridgeDestinationDetails(),
+    nonce,
+  }
+  const bridgeIntent = new PayloadBuilder<BridgeIntent>({ schema: BridgeIntentSchema })
+    .fields(bridgeIntentFields)
+    .build()
+
+  return await buildNextBlock(
+    previousBlock[0],
+    [],
+    [bridgeIntent, transferPayload],
+    [account],
+  )
+}

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

@@ -0,0 +1,43 @@
+import { BridgeSourceObservationSchema, buildNextBlock } from '@xyo-network/chain-sdk'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BridgeSourceObservation, BridgeSourceObservationFields, ChainService, HydratedBlock,
+} from '@xyo-network/xl1-protocol'
+
+import { getBridgeDestinationDetails, getBridgeSourceDetails } from './config/index.ts'
+
+/**
+ * Get the bridge source observation for a given block.
+ * @param previousBlock The previous block to base the observation on.
+ * @param account The wallet account to use for the observation.
+ * @param chainService The chain service to use for the observation.
+ */
+export const getBridgeSourceObservation = async (
+  previousBlock: HydratedBlock,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<HydratedBlock> => {
+  // TODO: Find actual transfer TX from previous block/source intent?
+  // This hash should contain both the source intent and the transfer to the bridge address
+  // As the block is itself both a block and a transaction, we can use its hash for now
+  const srcTxHash = previousBlock[0]._hash
+
+  const bridgeSourceObservationFields: BridgeSourceObservationFields = {
+    ...getBridgeSourceDetails(account, chainService),
+    ...getBridgeDestinationDetails(),
+    // Observation
+    srcConfirmation: srcTxHash,
+  }
+
+  const bridgeSourceObservation = new PayloadBuilder<BridgeSourceObservation>({ schema: BridgeSourceObservationSchema })
+    .fields(bridgeSourceObservationFields)
+    .build()
+
+  return await buildNextBlock(
+    previousBlock[0],
+    [],
+    [bridgeSourceObservation],
+    [account],
+  )
+}

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

@@ -0,0 +1,42 @@
+import type { BuildNextBlockOptions } from '@xyo-network/chain-sdk'
+import { buildBlock } from '@xyo-network/chain-sdk'
+import type { WithHashStorageMeta } from '@xyo-network/payload-model'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BlockBoundWitness, ChainService, HydratedBlock,
+} from '@xyo-network/xl1-protocol'
+
+import { getForkBlockReward } from './config/index.ts'
+
+/**
+ * Get the first block for the new forked chain.
+ * @param forkBlock The block to fork from
+ * @param account The wallet account to sign the block
+ * @param chainService The chain service instance
+ * @returns The first block for the new forked chain
+ */
+export const getFirstBlockForNewChain = async (
+  forkBlock: WithHashStorageMeta<BlockBoundWitness>,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<HydratedBlock> => {
+  const {
+    _hash: previousBlockHash, block: previousBlockNumber, step_hashes: previousStepHashes, protocol,
+  } = forkBlock
+  const chainId = chainService.chainId
+  const forkBlockReward = getForkBlockReward()
+  const options: BuildNextBlockOptions = {
+    blockPayloads: [],
+    chainId,
+    previousBlockHash,
+    previousBlockNumber,
+    previousStepHashes,
+    signers: [account],
+    txs: [],
+    protocol,
+    reward: forkBlockReward,
+    rewardAddress: account.address,
+  }
+  // NOTE: Can not use buildNextBlock because we need to control the chain id change here
+  return await buildBlock(options)
+}

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

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

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

@@ -0,0 +1,42 @@
+import type { Address, Hash } from '@xylabs/hex'
+import { asHash, hexFromBigInt } from '@xylabs/hex'
+import { isDefined } from '@xylabs/typeof'
+import type { ArchivistInstance } from '@xyo-network/archivist-model'
+import { isBlockBoundWitnessWithHashStorageMeta } from '@xyo-network/chain-sdk'
+import type { WithHashStorageMeta, WithStorageMeta } from '@xyo-network/payload-model'
+import type { BlockBoundWitness, ChainService } from '@xyo-network/xl1-protocol'
+
+/**
+ * Determine if the chain should fork based on the current head and chain configuration.
+ * @param head The current head block
+ * @param chainService The chain service instance
+ * @param chainArchivist The chain archivist instance
+ * @returns The block to fork from if the chain should fork, undefined otherwise
+ */
+export const getForkFromBlock = async (
+  head: WithStorageMeta<BlockBoundWitness>,
+  chainService: ChainService,
+  chainArchivist: ArchivistInstance,
+): Promise<WithHashStorageMeta<BlockBoundWitness> | undefined> => {
+  // If the head's chain doesn't match our chainId, we may need to fork
+  if (head.chain !== chainService.chainId) {
+    // Get the forked at hash from the chain service
+    const forkedAtBigInt = await chainService.forkedAtHash()
+    const forkedAtHex = hexFromBigInt(forkedAtBigInt) // Validate it's a proper hex string
+    const forkedAtHash: Hash | undefined = asHash(forkedAtHex)
+    if (isDefined(forkedAtHash)) {
+      // If we have a forkedAtHash, we need to check if the correct block exists
+      const [forkedAtBlock] = await chainArchivist.get([forkedAtHash])
+      const forkedChainId: Address = await chainService.forkedChainId()
+      const forkedAtBlockNumber: number = Number(await chainService.forkedAtBlockNumber())
+      // If we found the block hash we should fork at, check if it's a valid BlockBoundWitness
+      if (isBlockBoundWitnessWithHashStorageMeta(forkedAtBlock)
+      // And it is on the correct forked from chain
+        && forkedAtBlock.chain === forkedChainId
+        // And it is the correct forked at block number
+        && forkedAtBlock.block === forkedAtBlockNumber) {
+        return forkedAtBlock
+      }
+    }
+  }
+}

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

@@ -0,0 +1,52 @@
+import { assertEx } from '@xylabs/assert'
+import type { Promisable } from '@xylabs/promise'
+import { isDefined } from '@xylabs/typeof'
+import type { ArchivistInstance } from '@xyo-network/archivist-model'
+import { findMostRecentBlock } from '@xyo-network/chain-sdk'
+import type { WithStorageMeta } from '@xyo-network/payload-model'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BlockBoundWitness, ChainService, Initializable,
+} from '@xyo-network/xl1-protocol'
+
+import { createBootstrapHead } from './createBootstrapHead.ts'
+import { createForkedHead } from './createForkedHead/index.ts'
+import { getForkFromBlock } from './getForkFromBlock.ts'
+import { submitNewChain } from './submitNewChain.ts'
+
+let headSingleton: Promisable<WithStorageMeta<BlockBoundWitness>> | undefined
+
+export const initHead: Initializable<{
+  account: WalletInstance
+  chainArchivist: ArchivistInstance
+  chainService: ChainService
+  chainSubmissionsArchivistWrite: ArchivistInstance
+}, WithStorageMeta<BlockBoundWitness>>
+ = async (params): Promise<WithStorageMeta<BlockBoundWitness>> => {
+   const {
+     account, chainArchivist, chainSubmissionsArchivistWrite, chainService,
+   } = params
+   if (headSingleton) return headSingleton
+   let head = await findMostRecentBlock(chainArchivist)
+
+   // If there is a head
+   if (head) {
+     // If there is a head but check if it matches our chainId or we should fork from it
+     const forkFromBlock = await getForkFromBlock(head, chainService, chainArchivist)
+     // If we should fork form a block in the current chain
+     if (isDefined(forkFromBlock)) {
+       // Create a new chain from the fork from block
+       const chain = await createForkedHead(forkFromBlock, account, chainService)
+       await submitNewChain(chain, chainArchivist, chainSubmissionsArchivistWrite)
+       const newBlock = assertEx(chain.at(-1), () => new Error('Failed to get new head after forking'))
+       head = newBlock[0]
+     }
+   } else {
+     // If there is no head, create one
+     const genesisBlock = await createBootstrapHead(account)
+     await submitNewChain([genesisBlock], chainArchivist, chainSubmissionsArchivistWrite)
+     head = genesisBlock[0]
+   }
+   headSingleton = head
+   return headSingleton
+ }

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

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