@xyo-network/chain-services 1.16.26 → 1.17.1

package/src/blockViewerFromChainIteratorAndArchivist.ts

@@ -1,7 +1,8 @@
-import type { Hash } from '@xylabs/sdk-js'
+import type { Hash, Promisable } from '@xylabs/sdk-js'
 import { isDefined } from '@xylabs/sdk-js'
 import type { ReadArchivist } from '@xyo-network/archivist-model'
 import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { Payload, WithHashMeta } from '@xyo-network/payload-model'
 import type {
   SignedHydratedBlockWithHashMeta,
   XL1BlockNumber,
@@ -44,6 +45,18 @@ export function blockViewerFromChainIteratorAndArchivist(
       }
       return results
     },
+    blocksByNumber: async function (number: XL1BlockNumber, limit = 10): Promise<SignedHydratedBlockWithHashMeta[]> {
+      const results: SignedHydratedBlockWithHashMeta[] = []
+      for (let i = 0; i < limit; i++) {
+        const block = await this.blockByNumber(number)
+        if (block) {
+          results.push(block)
+        } else {
+          break
+        }
+      }
+      return results
+    },
     currentBlock: async function (): Promise<SignedHydratedBlockWithHashMeta> {
       const head = await chainIterator.head()
       return this.blockByHash(head._hash) as Promise<SignedHydratedBlockWithHashMeta>
@@ -56,6 +69,12 @@ export function blockViewerFromChainIteratorAndArchivist(
       const head = await chainIterator.head()
       return head.block
     },
+    payloadByHash: function (_hash: Hash): Promisable<WithHashMeta<Payload> | null> {
+      throw new Error('Function not implemented.')
+    },
+    payloadsByHash: function (_hashes: Hash[]): Promisable<WithHashMeta<Payload>[]> {
+      throw new Error('Function not implemented.')
+    },
   } satisfies BlockViewer
   return result
 }

package/src/implementation/accountBalance.ts

@@ -0,0 +1,29 @@
+import { isDefined, type Promisable } from '@xylabs/sdk-js'
+import type { Initializable, InitializableParams } from '@xyo-network/xl1-protocol'
+import type { AccountBalanceViewer, Config } from '@xyo-network/xl1-protocol-sdk'
+import {
+  AccountBalanceViewerRpcSchemas,
+  HttpRpcTransport,
+  JsonRpcAccountBalanceViewer,
+} from '@xyo-network/xl1-rpc'
+
+let balanceServiceSingleton: Promisable<AccountBalanceViewer> | undefined
+
+export type InitAccountBalanceServiceParams = InitializableParams<{
+  config: Config
+}>
+
+export const initAccountBalanceService: Initializable<InitAccountBalanceServiceParams, AccountBalanceViewer>
+  = (params): Promisable<AccountBalanceViewer> => {
+    const { config, logger } = params
+    if (balanceServiceSingleton) return balanceServiceSingleton
+    const endpoint = config.services?.accountBalanceViewerEndpoint ?? config.services?.apiEndpoint
+    if (isDefined(endpoint)) {
+      const transport = new HttpRpcTransport(endpoint, { ...AccountBalanceViewerRpcSchemas })
+      const viewer = new JsonRpcAccountBalanceViewer(transport)
+      logger?.log('Using AccountBalanceViewer RPC service at', endpoint)
+      return viewer
+    } else {
+      throw new Error('No AccountBalanceViewer endpoint configured')
+    }
+  }

package/src/implementation/blockViewer.ts

@@ -0,0 +1,29 @@
+import { isDefined, type Promisable } from '@xylabs/sdk-js'
+import type { Initializable, InitializableParams } from '@xyo-network/xl1-protocol'
+import type { BlockViewer, Config } from '@xyo-network/xl1-protocol-sdk'
+import {
+  BlockViewerRpcSchemas,
+  HttpRpcTransport,
+  JsonRpcBlockViewer,
+} from '@xyo-network/xl1-rpc'
+
+let blockViewerSingleton: Promisable<BlockViewer> | undefined
+
+export type InitBlockViewerParams = InitializableParams<{
+  config: Config
+}>
+
+export const initBlockViewer: Initializable<InitBlockViewerParams, BlockViewer>
+  = (params): Promisable<BlockViewer> => {
+    const { config, logger } = params
+    if (blockViewerSingleton) return blockViewerSingleton
+    const endpoint = config.services?.apiEndpoint
+    if (isDefined(endpoint)) {
+      const transport = new HttpRpcTransport(endpoint, { ...BlockViewerRpcSchemas })
+      const viewer = new JsonRpcBlockViewer(transport)
+      logger?.log('Using BlockViewer RPC service at', endpoint)
+      return viewer
+    } else {
+      throw new Error('No BlockViewer endpoint configured')
+    }
+  }

package/src/implementation/chain/evm.ts

@@ -0,0 +1,39 @@
+import type { Address, Promisable } from '@xylabs/sdk-js'
+import {
+  asAddress, assertEx, isDefined, ZERO_ADDRESS,
+} from '@xylabs/sdk-js'
+import type { Initializable } from '@xyo-network/xl1-protocol'
+import type { Config } from '@xyo-network/xl1-protocol-sdk'
+import type { ContractRunner } from 'ethers'
+import { Wallet } from 'ethers/wallet'
+
+import { EvmChainService } from '../../ChainService/index.ts'
+import type { BaseAccountableServiceParams } from '../../model/index.ts'
+import { canUseEvmProvider, initEvmProvider } from '../evm/index.ts'
+
+let chainStakeServiceSingleton: Promisable<EvmChainService> | undefined
+
+export const canUseEvmContractChainService = (config: Pick<Config, 'chain' | 'evm'>) => {
+  const { id } = config.chain
+  return isDefined(id) && id !== ZERO_ADDRESS && canUseEvmProvider({ config })
+}
+
+export const initEvmContractChainService: Initializable<BaseAccountableServiceParams<Pick<Config, 'chain' | 'evm'>>, EvmChainService> = async ({
+  account, config, traceProvider, meterProvider, logger,
+}) => {
+  if (chainStakeServiceSingleton) return chainStakeServiceSingleton
+  // Parse config
+  const emvStakingContractAddress = assertEx(config.chain.id, () => 'config.chain.id is required')
+  // Configure ContractRunner
+  const id: Address = assertEx(asAddress(emvStakingContractAddress), () => 'config.chain.id is not a valid address')
+  const provider = assertEx(await initEvmProvider({ config }))
+  const privateKey = assertEx(account.private?.hex, () => 'Account does not have a private key')
+  const runner: ContractRunner = new Wallet(privateKey, provider)
+  // Create service
+  chainStakeServiceSingleton = EvmChainService.create({
+    id, runner, traceProvider, meterProvider, logger,
+  })
+  const result = await chainStakeServiceSingleton
+  await result.start()
+  return result
+}

package/src/implementation/chain/index.ts

@@ -0,0 +1,46 @@
+import {
+  assertEx, type CreatableName, type Promisable,
+} from '@xylabs/sdk-js'
+import type { Initializable } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+import type { Config } from 'cosmiconfig'
+
+import { MemoryChainService } from '../../ChainService/index.ts'
+import type { BaseAccountableServiceParams } from '../../model/index.ts'
+import { canUseEvmContractChainService, initEvmContractChainService } from './evm.ts'
+
+let chainStakeServiceSingleton: Promisable<ChainService> | undefined
+
+export const initChainService: Initializable<BaseAccountableServiceParams<
+  Pick<Config, 'chain' | 'evm' | 'producer'>>,
+ChainService> = ({
+  account, config, logger,
+}) => {
+  logger?.log('ChainService: Initializing...')
+  const result = init({
+    config, name: 'ChainService' as CreatableName, account,
+  })
+  logger?.log('ChainService: Initialized')
+  return result
+}
+
+export const initMemoryChainService: Initializable<BaseAccountableServiceParams<
+  Pick<Config, 'producer'>>, ChainService> = async ({ config }) => {
+  const result = await MemoryChainService.create({
+    config,
+    name: 'MemoryChainService' as CreatableName,
+  })
+  assertEx(await result.start(), () => 'Failed to start MemoryChainService')
+  return result
+}
+
+const init: Initializable<BaseAccountableServiceParams<Pick<Config, 'chain' | 'evm' | 'producer'>>,
+  ChainService> = async (params): Promise<ChainService> => {
+  if (chainStakeServiceSingleton) return chainStakeServiceSingleton
+  const { config } = params
+  chainStakeServiceSingleton = canUseEvmContractChainService(config)
+    ? await initEvmContractChainService({ ...params, name: 'ChainStakeService' as CreatableName })
+    : await initMemoryChainService(params)
+  // Create service
+  return chainStakeServiceSingleton
+}

package/src/implementation/evm/index.ts

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

package/src/implementation/evm/initChainId.ts

@@ -0,0 +1,20 @@
+import {
+  assertEx, hexFrom, isDefined, isHex,
+} from '@xylabs/sdk-js'
+import type { Config } from '@xyo-network/xl1-protocol-sdk'
+
+export const canUseChainId = (config: Pick<Config, 'evm'>): boolean => {
+  return isDefined(config.evm.chainId)
+}
+
+export const getChainId = (config: Pick<Config, 'evm'>) => {
+  const chainId = assertEx(config.evm.chainId, () => 'Missing config.evm.chainId')
+  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/implementation/evm/initEvmProvider.ts

@@ -0,0 +1,24 @@
+import type { Logger } from '@xylabs/sdk-js'
+import { assertEx } from '@xylabs/sdk-js'
+import type { Config } from '@xyo-network/xl1-protocol-sdk'
+import type { Provider } from 'ethers'
+import type { JsonRpcProvider } from 'ethers/providers'
+
+import { canUseInfuraProvider, initInfuraProvider } from './initInfuraProvider.ts'
+import { canUseJsonRpcProvider, initJsonRpcProvider } from './initJsonRpcProvider.ts'
+
+let provider: Promise<JsonRpcProvider> | undefined
+
+export const initEvmProvider = async ({ config }: { config: Pick<Config, 'evm'>; logger?: Logger }): Promise<Provider> => {
+  if (provider) return provider
+  if (canUseInfuraProvider(config)) {
+    provider = initInfuraProvider(config)
+  } else if (canUseJsonRpcProvider(config)) {
+    provider = initJsonRpcProvider(config)
+  }
+  return assertEx(await provider, () => 'No provider available')
+}
+
+export const canUseEvmProvider = ({ config }: { config: Pick<Config, 'evm'> }) => {
+  return canUseInfuraProvider(config) || canUseJsonRpcProvider(config)
+}

package/src/implementation/evm/initInfuraProvider.ts

@@ -0,0 +1,26 @@
+import { assertEx, isDefined } from '@xylabs/sdk-js'
+import type { Config } from '@xyo-network/xl1-protocol-sdk'
+import { InfuraProvider } from 'ethers/providers'
+
+import { canUseChainId, getChainId } from './initChainId.ts'
+
+let instance: Promise<InfuraProvider> | undefined
+
+export const initInfuraProvider = (config: Pick<Config, 'evm'>) => {
+  if (instance) return instance
+  const providerConfig = getInfuraProviderConfig(config)
+  instance = Promise.resolve(new InfuraProvider(...providerConfig))
+  return instance
+}
+
+export const canUseInfuraProvider = (config: Pick<Config, 'evm'>): boolean => {
+  return canUseChainId(config)
+    && isDefined(config.evm?.infura?.projectId)
+    && isDefined(config.evm?.infura?.projectSecret)
+}
+
+export const getInfuraProviderConfig = (config: Pick<Config, 'evm'>) => {
+  const projectId = assertEx(config.evm?.infura?.projectId, () => 'Missing config.evm.infura.projectId')
+  const projectSecret = assertEx(config.evm?.infura?.projectSecret, () => 'Missing config.evm.infura.projectSecret')
+  return [getChainId(config), projectId, projectSecret] as const
+}

package/src/implementation/evm/initJsonRpcProvider.ts

@@ -0,0 +1,20 @@
+import { assertEx, isDefined } from '@xylabs/sdk-js'
+import type { Config } from '@xyo-network/xl1-protocol-sdk'
+import { JsonRpcProvider } from 'ethers/providers'
+
+import { canUseChainId, getChainId } from './initChainId.ts'
+
+export const initJsonRpcProvider = (config: Pick<Config, 'evm'>) => {
+  const providerConfig = getJsonRpcProviderConfig(config)
+  return Promise.resolve(new JsonRpcProvider(...providerConfig))
+}
+
+export const canUseJsonRpcProvider = (config: Pick<Config, 'evm'>) => {
+  return canUseChainId(config)
+    && isDefined(config.evm.jsonRpc?.url)
+}
+
+export const getJsonRpcProviderConfig = (config: Pick<Config, 'evm'>) => {
+  const jsonRpcUrl = assertEx(config.evm.jsonRpc?.url, () => 'Missing config.evm.jsonRpc.url')
+  return [jsonRpcUrl, getChainId(config)] as const
+}

package/src/implementation/head/createBootstrapHead.ts

@@ -0,0 +1,31 @@
+import {
+  buildNextBlock, createDeclarationIntent, createGenesisBlock,
+} from '@xyo-network/chain-protocol'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type { SignedHydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+
+export const createBootstrapHead = async (account: WalletInstance, chainService: ChainService): Promise<SignedHydratedBlockWithHashMeta[]> => {
+  const chainId = await chainService.chainId()
+  const chain: SignedHydratedBlockWithHashMeta[] = []
+
+  // Create genesis block
+  const genesisBlock = await createGenesisBlock(account, chainId, 10_000_000n, account.address)
+  chain.push(genesisBlock)
+
+  // Create producer declaration block
+  const producerDeclarationPayload = createDeclarationIntent(
+    account.address,
+    'producer',
+    genesisBlock[0].block,
+    genesisBlock[0].block + 10_000,
+  )
+  const producerDeclarationBlock = await buildNextBlock(
+    genesisBlock[0],
+    [],
+    [producerDeclarationPayload],
+    [account],
+  )
+  chain.push(producerDeclarationBlock)
+  return chain
+}

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

@@ -0,0 +1,27 @@
+import { toHex } from '@xylabs/sdk-js'
+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('0xf72aE3E0DA743033AbD7A407557D684c1aE66aed')
+const bridgeDestAddress = toHex('0x0e65b65B10C791942665030402c35023d88B14dA')
+const destConfirmation = toHex('0x950861b10523b52cdbb4a9ee52ed26601db555d2652bfec21c709e5e70d5b7d3') // 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/implementation/head/createForkedHead/config/getBridgeSourceDetails.ts

@@ -0,0 +1,19 @@
+import type { AccountInstance } from '@xyo-network/account-model'
+import type { BridgeDetailsSourceFields } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+
+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 = async (account: AccountInstance, chainService: ChainService): Promise<BridgeDetailsSourceFields> => {
+  return {
+    src: await getBridgeSrcChainId(chainService),
+    srcAddress: getBridgeSrcAddress(account),
+    srcToken: await getBridgeSrcToken(chainService),
+    srcAmount: getBridgeSrcAmount(),
+  }
+}

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

@@ -0,0 +1,10 @@
+import { type Hex, toHex } from '@xylabs/sdk-js'
+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/implementation/head/createForkedHead/config/index.ts

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

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

@@ -0,0 +1,29 @@
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type { SignedBlockBoundWitnessWithHashMeta, SignedHydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+
+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: SignedBlockBoundWitnessWithHashMeta,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<SignedHydratedBlockWithHashMeta[]> => {
+  const chain: SignedHydratedBlockWithHashMeta[] = []
+  // 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/implementation/head/createForkedHead/getBridgeDestinationObservation.ts

@@ -0,0 +1,42 @@
+import { buildNextBlock } from '@xyo-network/chain-protocol'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BridgeDestinationObservation, BridgeDestinationObservationFields,
+  HydratedBlockWithHashMeta,
+  SignedHydratedBlockWithHashMeta,
+} from '@xyo-network/xl1-protocol'
+import { BridgeDestinationObservationSchema } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+
+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: HydratedBlockWithHashMeta,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<SignedHydratedBlockWithHashMeta> => {
+  const bridgeDestinationObservationFields: BridgeDestinationObservationFields = {
+    ...await 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/implementation/head/createForkedHead/getBridgeIntent.ts

@@ -0,0 +1,51 @@
+import { buildNextBlock, createTransferPayload } from '@xyo-network/chain-protocol'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BridgeIntent, BridgeIntentFields,
+  SignedHydratedBlockWithHashMeta,
+} from '@xyo-network/xl1-protocol'
+import { BridgeIntentSchema, XYO_BRIDGE_ADDRESS } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+
+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: SignedHydratedBlockWithHashMeta,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<SignedHydratedBlockWithHashMeta> => {
+  // 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 = {
+    ...await 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/implementation/head/createForkedHead/getBridgeSourceObservation.ts

@@ -0,0 +1,46 @@
+import { buildNextBlock } from '@xyo-network/chain-protocol'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BridgeSourceObservation, BridgeSourceObservationFields,
+  SignedHydratedBlockWithHashMeta,
+} from '@xyo-network/xl1-protocol'
+import { BridgeSourceObservationSchema } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+
+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: SignedHydratedBlockWithHashMeta,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<SignedHydratedBlockWithHashMeta> => {
+  // 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 = {
+    ...await 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/implementation/head/createForkedHead/getFirstBlockForNewChain.ts

@@ -0,0 +1,41 @@
+import { buildBlock, type BuildNextBlockOptions } from '@xyo-network/chain-protocol'
+import type { WithHashMeta } from '@xyo-network/payload-model'
+import type { WalletInstance } from '@xyo-network/wallet-model'
+import type {
+  BlockBoundWitness,
+  SignedHydratedBlockWithHashMeta,
+} from '@xyo-network/xl1-protocol'
+import { AttoXL1, XYO_STEP_REWARD_ADDRESS } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+
+/**
+ * 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: WithHashMeta<BlockBoundWitness>,
+  account: WalletInstance,
+  chainService: ChainService,
+): Promise<SignedHydratedBlockWithHashMeta> => {
+  const {
+    _hash: previousBlockHash, block: previousBlockNumber, step_hashes: previousStepHashes = [], protocol,
+  } = forkBlock
+  const chainId = await chainService.chainId()
+  const options: BuildNextBlockOptions = {
+    blockPayloads: [],
+    chainId,
+    previousBlockHash,
+    previousBlockNumber,
+    previousStepHashes,
+    signers: [account],
+    txs: [],
+    protocol,
+    chainStepRewardAddress: XYO_STEP_REWARD_ADDRESS,
+    stepRewardPoolBalance: AttoXL1(0n),
+  }
+  // Can not use buildNextBlock because we need to control the chain id change here
+  return await buildBlock(options)
+}

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

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

package/src/implementation/head/getForkFromBlock.ts

@@ -0,0 +1,43 @@
+import type { Address, Hash } from '@xylabs/sdk-js'
+import {
+  asHash, hexFromBigInt, isDefined,
+} from '@xylabs/sdk-js'
+import type { ArchivistInstance } from '@xyo-network/archivist-model'
+import type { SignedBlockBoundWitnessWithHashMeta } from '@xyo-network/xl1-protocol'
+import { isSignedBlockBoundWitnessWithHashMeta } from '@xyo-network/xl1-protocol'
+import type { ChainService } from '@xyo-network/xl1-protocol-sdk'
+
+/**
+ * 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: SignedBlockBoundWitnessWithHashMeta,
+  chainService: ChainService,
+  chainArchivist: ArchivistInstance,
+): Promise<SignedBlockBoundWitnessWithHashMeta | undefined> => {
+  // If the head's chain doesn't match our chainId, we may need to fork
+  if (head.chain !== await 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 (isSignedBlockBoundWitnessWithHashMeta(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
+      }
+    }
+  }
+}