@xyo-network/chain-services 1.15.1 → 1.15.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json.schemastore.org/package.json",
   "name": "@xyo-network/chain-services",
-  "version": "1.15.1",
+  "version": "1.15.3",
   "description": "XYO Layer One SDK Services",
   "homepage": "https://xylabs.com",
   "bugs": {
@@ -37,51 +37,51 @@
   ],
   "dependencies": {
     "@opentelemetry/api": "~1.9.0",
-    "@xylabs/array": "~5.0.11",
-    "@xylabs/assert": "~5.0.11",
-    "@xylabs/creatable": "~5.0.11",
-    "@xylabs/decimal-precision": "~5.0.11",
-    "@xylabs/events": "~5.0.11",
-    "@xylabs/exists": "~5.0.11",
-    "@xylabs/forget": "~5.0.11",
-    "@xylabs/hex": "~5.0.11",
-    "@xylabs/promise": "~5.0.11",
-    "@xylabs/telemetry": "~5.0.11",
-    "@xylabs/typeof": "~5.0.11",
-    "@xyo-network/account-model": "~5.1.2",
-    "@xyo-network/archivist-memory": "~5.1.2",
-    "@xyo-network/archivist-model": "~5.1.2",
-    "@xyo-network/boundwitness-model": "~5.1.2",
-    "@xyo-network/boundwitness-validator": "~5.1.2",
-    "@xyo-network/boundwitness-wrapper": "~5.1.2",
-    "@xyo-network/chain-analyze": "~1.15.1",
-    "@xyo-network/chain-modules": "~1.15.1",
-    "@xyo-network/chain-protocol": "~1.15.1",
-    "@xyo-network/chain-utils": "~1.15.1",
-    "@xyo-network/payload-builder": "~5.1.2",
-    "@xyo-network/payload-model": "~5.1.2",
-    "@xyo-network/typechain": "~4.0.8",
-    "@xyo-network/xl1-protocol": "~1.12.33",
-    "@xyo-network/xl1-protocol-sdk": "~1.15.1",
-    "@xyo-network/xl1-validation": "~1.15.1",
-    "@xyo-network/xl1-wrappers": "~1.15.1",
+    "@xylabs/array": "~5.0.12",
+    "@xylabs/assert": "~5.0.12",
+    "@xylabs/creatable": "~5.0.12",
+    "@xylabs/decimal-precision": "~5.0.12",
+    "@xylabs/events": "~5.0.12",
+    "@xylabs/exists": "~5.0.12",
+    "@xylabs/forget": "~5.0.12",
+    "@xylabs/hex": "~5.0.12",
+    "@xylabs/promise": "~5.0.12",
+    "@xylabs/telemetry": "~5.0.12",
+    "@xylabs/typeof": "~5.0.12",
+    "@xyo-network/account-model": "~5.1.6",
+    "@xyo-network/archivist-memory": "~5.1.6",
+    "@xyo-network/archivist-model": "~5.1.6",
+    "@xyo-network/boundwitness-model": "~5.1.6",
+    "@xyo-network/boundwitness-validator": "~5.1.6",
+    "@xyo-network/boundwitness-wrapper": "~5.1.6",
+    "@xyo-network/chain-analyze": "~1.15.3",
+    "@xyo-network/chain-modules": "~1.15.3",
+    "@xyo-network/chain-protocol": "~1.15.3",
+    "@xyo-network/chain-utils": "~1.15.3",
+    "@xyo-network/payload-builder": "~5.1.6",
+    "@xyo-network/payload-model": "~5.1.6",
+    "@xyo-network/typechain": "~4.0.10",
+    "@xyo-network/xl1-protocol": "~1.12.66",
+    "@xyo-network/xl1-protocol-sdk": "~1.15.3",
+    "@xyo-network/xl1-validation": "~1.15.3",
+    "@xyo-network/xl1-wrappers": "~1.15.3",
     "async-mutex": "~0.5.0",
     "ethers": "6.15.0",
-    "lru-cache": "~11.2.1"
+    "lru-cache": "~11.2.2"
   },
   "devDependencies": {
-    "@types/node": "~24.5.2",
-    "@xylabs/delay": "~5.0.11",
-    "@xylabs/ts-scripts-yarn3": "~7.1.7",
-    "@xylabs/tsconfig": "~7.1.7",
-    "@xylabs/vitest-extended": "~5.0.11",
-    "@xyo-network/account": "~5.1.2",
-    "@xyo-network/account-model": "~5.1.2",
-    "@xyo-network/chain-validation": "~1.15.1",
-    "@xyo-network/wallet": "~5.1.2",
-    "eslint": "^9.36.0",
+    "@types/node": "~24.7.2",
+    "@xylabs/delay": "~5.0.12",
+    "@xylabs/ts-scripts-yarn3": "~7.1.8",
+    "@xylabs/tsconfig": "~7.1.8",
+    "@xylabs/vitest-extended": "~5.0.12",
+    "@xyo-network/account": "~5.1.6",
+    "@xyo-network/account-model": "~5.1.6",
+    "@xyo-network/chain-validation": "~1.15.3",
+    "@xyo-network/wallet": "~5.1.6",
+    "eslint": "^9.37.0",
     "tslib": "~2.8.1",
-    "typescript": "~5.9.2",
+    "typescript": "~5.9.3",
     "vitest": "~3.2.4",
     "vitest-mock-extended": "~3.1.0",
     "web3-types": "~1.10.0"

package/src/AccountBalance/BaseAccountBalanceService.ts

@@ -1,31 +1,29 @@
 import { creatable } from '@xylabs/creatable'
 import { Address, Hash } from '@xylabs/hex'
 import { spanRootAsync } from '@xylabs/telemetry'
-import { ReadArchivist } from '@xyo-network/archivist-model'
 import {
   AccountBalanceServiceV2,
-  AttoXL1, PayloadRepository,
+  AttoXL1,
 } from '@xyo-network/xl1-protocol'
 import {
-  BalancesStepSummary,
   balancesSummary,
+  BalanceStepSummaryContext,
 } from '@xyo-network/xl1-protocol-sdk'
 
 import { BaseService } from '../BaseService.ts'
 import { BaseServiceParams } from '../model/index.ts'
 
 export interface BaseAccountBalanceServiceParams extends BaseServiceParams {
-  chainArchivist: ReadArchivist
-  summaryRepository: PayloadRepository<Hash, BalancesStepSummary>
+  context: BalanceStepSummaryContext
 }
 
 @creatable()
 export class BaseAccountBalanceService extends BaseService<BaseAccountBalanceServiceParams> implements AccountBalanceServiceV2 {
   async balances(head: Hash, address: Address[]): Promise<Partial<Record<Address, AttoXL1>>> {
     return await spanRootAsync('balances', async () => {
-      const summary = await balancesSummary({
-        chainArchivist: this.params.chainArchivist, summaryRepository: this.params.summaryRepository, head,
-      })
+      const summary = await balancesSummary(
+        this.params.context,
+      )
       const result: Record<Address, AttoXL1> = {}
       for (const addr of address) {
         const summaryBalance = summary[addr] ?? 0n

package/src/AccountBalance/accountBalanceServiceFromArchivist.ts

@@ -1,45 +1,30 @@
-import { exists } from '@xylabs/exists'
-import {
-  asHash, type Hash,
-  isHash,
-} from '@xylabs/hex'
+import { ZERO_HASH } from '@xylabs/hex'
 import type { ReadArchivist } from '@xyo-network/archivist-model'
-import { PayloadBuilder } from '@xyo-network/payload-builder'
-import type { WithStorageMeta } from '@xyo-network/payload-model'
-import type { AccountBalanceServiceV2 } from '@xyo-network/xl1-protocol'
-import type { BalancesStepSummary, StepSummary } from '@xyo-network/xl1-protocol-sdk'
-import { LRUCache } from 'lru-cache'
+import { LruCacheMap } from '@xyo-network/chain-protocol'
+import type { Payload, WithStorageMeta } from '@xyo-network/payload-model'
+import type { AccountBalanceServiceV2, ChainId } from '@xyo-network/xl1-protocol'
+import { type BalancesStepSummary, readPayloadMapFromStore } from '@xyo-network/xl1-protocol-sdk'
 
 import { BaseAccountBalanceService } from './BaseAccountBalanceService.ts'
 
-export const accountBalanceServiceFromArchivist = async (archivist: ReadArchivist): Promise<AccountBalanceServiceV2> => {
-  const summaryArchivistCache = new LRUCache<Hash, WithStorageMeta<BalancesStepSummary>>({
+export const accountBalancesServiceFromArchivist = async (
+  chainId: ChainId,
+  archivist: ReadArchivist<WithStorageMeta<Payload>>,
+): Promise<AccountBalanceServiceV2> => {
+  const summaryMap = new LruCacheMap<string, BalancesStepSummary>({
     max: 100_000,
     allowStale: true,
     noDisposeOnSet: false,
     updateAgeOnGet: true,
   })
-  const summaryRepository = {
-    get: (hashes: Hash[]) => {
-      const results = hashes.map((hash) => {
-        return summaryArchivistCache.get(hash)
-      }).filter(exists)
-      return results
+  const chainMap = readPayloadMapFromStore<WithStorageMeta<Payload>>(archivist)
+  const service = await BaseAccountBalanceService.create({
+    context: {
+      chainId,
+      store: { chainMap },
+      summaryMap,
+      head: () => ZERO_HASH,
     },
-    insert: async (payloads: BalancesStepSummary[]) => {
-      const results = (await PayloadBuilder.addStorageMeta(payloads)).map((payload) => {
-        const hash = asHash((payload as WithStorageMeta<StepSummary>).hash)
-        if (isHash(hash)) {
-          summaryArchivistCache.set(hash, payload)
-          return payload
-        }
-      }).filter(exists)
-      return results
-    },
-    next: () => {
-      throw new Error('Not implemented')
-    },
-  }
-  const service = await BaseAccountBalanceService.create({ chainArchivist: archivist, summaryRepository })
+  })
   return service
 }

package/src/AccountTransfers/BaseAccountTransfersService.ts

@@ -1,14 +1,12 @@
 import { creatable } from '@xylabs/creatable'
 import { Address, Hash } from '@xylabs/hex'
-import { Promisable } from '@xylabs/promise'
 import { spanRootAsync } from '@xylabs/telemetry'
-import { ReadArchivist } from '@xyo-network/archivist-model'
 import {
   AccountTransfersService,
-  AttoXL1, PayloadRepository,
+  AttoXL1,
 } from '@xyo-network/xl1-protocol'
 import {
-  TransfersStepSummary,
+  TransfersStepSummaryContext,
   transfersSummary,
 } from '@xyo-network/xl1-protocol-sdk'
 
@@ -16,9 +14,7 @@ import { BaseService } from '../BaseService.ts'
 import { BaseServiceParams } from '../model/index.ts'
 
 export interface BaseAccountTransferServiceParams extends BaseServiceParams {
-  account: Address
-  chainArchivist: ReadArchivist
-  summaryRepository: PayloadRepository<Hash, TransfersStepSummary>
+  context: TransfersStepSummaryContext
 }
 
 @creatable()
@@ -29,12 +25,7 @@ export class BaseAccountTransfersService extends BaseService<BaseAccountTransfer
 
   async transfers(head: Hash, addresses: Address[]): Promise<Partial<Record<Address, AttoXL1>>> {
     return await spanRootAsync('transfers', async () => {
-      const {
-        chainArchivist, summaryRepository, account,
-      } = this.params
-      const summary = await transfersSummary({
-        chainArchivist, summaryRepository, head, account,
-      })
+      const summary = await transfersSummary(this.params.context)
       const result: Record<Address, AttoXL1> = {}
       for (const addr of addresses) {
         const summaryBalance = summary[addr] ?? 0n

package/src/AccountTransfers/accountTransfersServiceFromArchivist.ts

@@ -1,48 +1,31 @@
-import { exists } from '@xylabs/exists'
-import type { Address, Hash } from '@xylabs/hex'
-import {
-  asHash,
-  isHash,
-} from '@xylabs/hex'
+import { ZERO_HASH } from '@xylabs/hex'
 import type { ReadArchivist } from '@xyo-network/archivist-model'
-import { PayloadBuilder } from '@xyo-network/payload-builder'
-import type { WithStorageMeta } from '@xyo-network/payload-model'
-import type { AccountTransfersService } from '@xyo-network/xl1-protocol'
-import type { StepSummary, TransfersStepSummary } from '@xyo-network/xl1-protocol-sdk'
-import { LRUCache } from 'lru-cache'
+import { LruCacheMap } from '@xyo-network/chain-protocol'
+import type { Payload, WithStorageMeta } from '@xyo-network/payload-model'
+import type { AccountTransfersService, ChainId } from '@xyo-network/xl1-protocol'
+import type { TransfersStepSummary } from '@xyo-network/xl1-protocol-sdk'
+import { readPayloadMapFromStore } from '@xyo-network/xl1-protocol-sdk'
 
 import { BaseAccountTransfersService } from './BaseAccountTransfersService.ts'
 
-export const accountTransferServiceFromArchivist = async (archivist: ReadArchivist, account: Address): Promise<AccountTransfersService> => {
-  const summaryArchivistCache = new LRUCache<Hash, WithStorageMeta<TransfersStepSummary>>({
+export const accountTransfersServiceFromArchivist = async (
+  chainId: ChainId,
+  archivist: ReadArchivist<WithStorageMeta<Payload>>,
+): Promise<AccountTransfersService> => {
+  const summaryMap = new LruCacheMap<string, TransfersStepSummary>({
     max: 100_000,
     allowStale: true,
     noDisposeOnSet: false,
     updateAgeOnGet: true,
   })
-  const summaryRepository = {
-    get: (hashes: Hash[]) => {
-      const results = hashes.map((hash) => {
-        return summaryArchivistCache.get(hash)
-      }).filter(exists)
-      return results
-    },
-    insert: async (payloads: TransfersStepSummary[]) => {
-      const results = (await PayloadBuilder.addStorageMeta(payloads)).map((payload) => {
-        const hash = asHash((payload as WithStorageMeta<StepSummary>).hash)
-        if (isHash(hash)) {
-          summaryArchivistCache.set(hash, payload)
-          return payload
-        }
-      }).filter(exists)
-      return results
-    },
-    next: () => {
-      throw new Error('Not implemented')
-    },
-  }
+  const chainMap = readPayloadMapFromStore<WithStorageMeta<Payload>>(archivist)
   const service = await BaseAccountTransfersService.create({
-    chainArchivist: archivist, account, summaryRepository,
+    context: {
+      chainId,
+      store: { chainMap },
+      summaryMap,
+      head: () => ZERO_HASH,
+    },
   })
   return service
 }

package/src/BlockProducer/spec/BaseBlockProducerService.spec.ts

@@ -1,13 +1,15 @@
+/* eslint-disable max-statements */
 import '@xylabs/vitest-extended'
 
 import { filterAs } from '@xylabs/array'
 import { assertEx } from '@xylabs/assert'
 import type { CreatableName } from '@xylabs/creatable'
 import { delay } from '@xylabs/delay'
-import type { Address } from '@xylabs/hex'
+import type { Address, Hash } from '@xylabs/hex'
 import {
   asAddress, hexToBigInt, ZERO_HASH,
 } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
 import { Account } from '@xyo-network/account'
 import type { AccountInstance } from '@xyo-network/account-model'
 import { MemoryArchivist } from '@xyo-network/archivist-memory'
@@ -19,10 +21,11 @@ import {
 } from '@xyo-network/payload-model'
 import { HDWallet } from '@xyo-network/wallet'
 import type {
-  BlockBoundWitness, BlockRewardService, Chain, ElectionService,
+  BlockBoundWitness, BlockRewardService, ChainId, ElectionService,
   HydratedBlock,
   HydratedBlockStateValidationFunctionV2,
   StakeIntentService,
+  TimeDomain, TimePayload,
   TimeSyncViewInterfaceV2,
 } from '@xyo-network/xl1-protocol'
 import {
@@ -31,6 +34,7 @@ import {
   asTransactionBoundWitness,
   asTransfer,
   HydratedBlockStateValidationError,
+  TimeSchema,
   XYO_ZERO_ADDRESS,
 } from '@xyo-network/xl1-protocol'
 import type { Config } from '@xyo-network/xl1-protocol-sdk'
@@ -42,7 +46,7 @@ import {
 } from 'vitest'
 import { mock } from 'vitest-mock-extended'
 
-import { accountBalanceServiceFromArchivist } from '../../AccountBalance/index.ts'
+import { accountBalancesServiceFromArchivist } from '../../AccountBalance/index.ts'
 import { MemoryBlockRewardService } from '../../BlockReward/index.ts'
 import type { BasePendingTransactionsServiceParams } from '../../PendingTransactions/index.ts'
 import { BasePendingTransactionsService } from '../../PendingTransactions/index.ts'
@@ -95,9 +99,56 @@ describe('XyoBlockProducer', () => {
 
     stakeIntentService = mock<StakeIntentService>()
     stakeIntentService.getDeclaredCandidateRanges.mockResolvedValue([])
-    time = mock<TimeSyncViewInterfaceV2>()
+    time = {
+      currentTimeAndHash(domain: TimeDomain): Promisable<[number, Hash | null]> {
+        switch (domain) {
+          case 'epoch': {
+            return [Date.now(), null]
+          }
+          case 'xl1': {
+            return [1, '00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff' as Hash]
+          }
+          case 'ethereum': {
+            return [1, '00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff' as Hash]
+          }
+        // No default
+        }
+      },
+      currentTime(domain: TimeDomain): Promisable<[string, number]> {
+        switch (domain) {
+          case 'epoch': {
+            return ['epoch', Date.now()]
+          }
+          case 'xl1': {
+            return ['xl1', 1]
+          }
+          case 'ethereum': {
+            return ['ethereum', 1]
+          }
+        // No default
+        }
+      },
+      currentTimePayload(): Promisable<TimePayload> {
+        return {
+          schema: TimeSchema, epoch: Date.now(), xl1: 1,
+        }
+      },
+      /** Convert time between different domains */
+      convertTime(fromDomain: TimeDomain, toDomain: TimeDomain, from: number): Promisable<number> {
+        if (fromDomain === toDomain) {
+          return from
+        }
+        if (fromDomain === 'epoch' && toDomain === 'xl1') {
+          return 1
+        }
+        if (fromDomain === 'xl1' && toDomain === 'epoch') {
+          return Date.now()
+        }
+        return from
+      },
+    }
     rewardService = await MemoryBlockRewardService.create()
-    const balanceService = await accountBalanceServiceFromArchivist(chainArchivist)
+    const balanceService = await accountBalancesServiceFromArchivist(chainId, chainArchivist)
     const params: BaseBlockProducerServiceParams = {
       name: 'TestXyoBlockProducerParams' as CreatableName,
       account,
@@ -179,11 +230,11 @@ describe('XyoBlockProducer', () => {
           let rejectBlock = true
           const validateHydratedBlockState: HydratedBlockStateValidationFunctionV2 = async (
             hydratedBlock: HydratedBlock,
-            chainId: Chain,
+            chainId: ChainId,
           ) => {
             return rejectBlock ? [await Promise.resolve(new HydratedBlockStateValidationError(ZERO_HASH, chainId, hydratedBlock, 'Invalid block'))] : []
           }
-          const balanceService = await accountBalanceServiceFromArchivist(chainArchivist)
+          const balanceService = await accountBalancesServiceFromArchivist(chainId, chainArchivist)
           const params: BaseBlockProducerServiceParams = {
             name: 'TestXyoBlockProducerParams' as CreatableName,
             account,
@@ -234,11 +285,14 @@ describe('XyoBlockProducer', () => {
             const transfers = filterAs(assertEx(transactionsAndData), asTransfer)
             const blockRewardTransfer = transfers.find(transfer => transfer.from === XYO_ZERO_ADDRESS)
             expect(blockRewardTransfer).toBeDefined()
+            let totalTransfer = 0n
             for (const value of Object.values(blockRewardTransfer?.transfers ?? {})) {
               if (value) {
-                expect(hexToBigInt(value)).toEqual(1_500_000_000_000_000_000_000n)
+                const bigIntValue = hexToBigInt(value)
+                totalTransfer += bigIntValue
               }
             }
+            expect(totalTransfer).toEqual(3_000_000_000_000_000_000_000n)
           }
         })
       })

package/src/ChainBlockIteration/ChainBlockNumberIterationService.ts

@@ -0,0 +1,108 @@
+import { assertEx } from '@xylabs/assert'
+import type { Hex } from '@xylabs/hex'
+import {
+  isDefined, isNull, isUndefined,
+} from '@xylabs/typeof'
+import type { ArchivistInstance } from '@xyo-network/archivist-model'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { WithStorageMeta } from '@xyo-network/payload-model'
+import type {
+  BlockBoundWitness,
+  ChainIteratorServiceEventData,
+  EventingChainBlockNumberIteratorService,
+} from '@xyo-network/xl1-protocol'
+import {
+  asBlockBoundWitness,
+  asBlockBoundWitnessWithStorageMeta,
+  isBlockBoundWitness,
+} from '@xyo-network/xl1-protocol'
+import { LRUCache } from 'lru-cache'
+
+import { BaseService } from '../BaseService.ts'
+import type { XyoChainIteratorParams } from './model/index.ts'
+
+export class ChainBlockNumberIterationService extends BaseService<XyoChainIteratorParams, ChainIteratorServiceEventData>
+  implements EventingChainBlockNumberIteratorService {
+  protected _blocksByBlockNumber = new LRUCache<number, WithStorageMeta<BlockBoundWitness>>({ max: 10_000 })
+  protected _currentHead: WithStorageMeta<BlockBoundWitness> | undefined
+
+  get chainArchivist(): ArchivistInstance { return assertEx(this.params.chainArchivist) }
+
+  get chainId(): Hex { return assertEx(this._currentHead?.chain ?? this.params?.head?.chain, () => 'Current head is not set') }
+
+  async get(block: number): Promise<WithStorageMeta<BlockBoundWitness>> {
+    const head = await this.head()
+    // if(isUndefined(head)) return undefined
+    // Bail early if the block requested is newer than the current head
+    assertEx(head.block >= block, () => `Block requested is newer than the current head [${block}]`)
+    const cached = this._blocksByBlockNumber.get(block)
+    if (cached) return cached
+    // Start at the current head and traverse backwards until the requested block is found
+    const startingBlock = head
+    const currentBlockHash = await PayloadBuilder.hash(startingBlock)
+    let currentBlock = (await this.chainArchivist.get([currentBlockHash])).at(0)
+    while (isDefined(currentBlock)) {
+      assertEx(asBlockBoundWitness(currentBlock), () => `Expected hash to be a block bound witness [${currentBlock?._hash}]`)
+      if (isBlockBoundWitness(currentBlock)) {
+        this._blocksByBlockNumber.set(currentBlock.block, currentBlock)
+        if (currentBlock.block === block) {
+          return currentBlock
+        }
+        const { previous } = currentBlock
+        if (isNull(previous)) break
+        currentBlock = (await this.chainArchivist.get([previous])).at(0)
+      }
+    }
+    throw new Error(`Block not found: ${block}`)
+  }
+
+  async head(): Promise<WithStorageMeta<BlockBoundWitness>> {
+    if (isDefined(this._currentHead)) return this._currentHead
+    if (isDefined(this.params.head)) {
+      const newHead = await this.getBoundWitnessAsBlockBoundWitnessWithStorageMeta(this.params.head)
+      this._currentHead = newHead
+      return newHead
+    }
+    throw new Error('Head is not set')
+  }
+
+  async next(block: number): Promise<WithStorageMeta<BlockBoundWitness> | undefined> {
+    const currentBlock = block
+    const nextBlockNumber = currentBlock + 1
+    return await this.get(nextBlockNumber)
+  }
+
+  // TODO: Decide on inclusive/exclusive (probably need inclusive to account for chain head)
+  // and then communicate via method name and documentation
+  async previous(block: number | undefined = undefined, count: number = 1): Promise<WithStorageMeta<BlockBoundWitness>[]> {
+    const results: WithStorageMeta<BlockBoundWitness>[] = []
+    let currentBlock: WithStorageMeta<BlockBoundWitness> | undefined = isDefined(block) ? (await this.get(block)) : await this.head()
+    while (currentBlock && results.length < count) {
+      if (isBlockBoundWitness(currentBlock)) {
+        results.push(currentBlock)
+        const { previous } = currentBlock
+        if (isNull(previous)) break
+        const nextBlock = await this.chainArchivist.get([previous])
+        currentBlock = asBlockBoundWitnessWithStorageMeta(nextBlock[0])
+      } else {
+        const hash = PayloadBuilder.hash(currentBlock)
+        assertEx(asBlockBoundWitnessWithStorageMeta(currentBlock), () => `Expected hash to be a block bound witness [${hash}]`)
+      }
+    }
+    return results
+  }
+
+  async updateHead(head: BlockBoundWitness): Promise<void> {
+    const newHead = await this.getBoundWitnessAsBlockBoundWitnessWithStorageMeta(head)
+    this._currentHead = newHead
+    void this.emit('headUpdated', { blocks: [newHead] })
+  }
+
+  private async getBoundWitnessAsBlockBoundWitnessWithStorageMeta(head: BlockBoundWitness): Promise<WithStorageMeta<BlockBoundWitness>> {
+    const hash = await PayloadBuilder.hash(head)
+    const stored = (await this.chainArchivist.get([hash])).at(-1)
+    const newHead = asBlockBoundWitnessWithStorageMeta(stored)
+    if (isUndefined(newHead)) throw new Error(`Head block not found in archivist [${hash}]`)
+    return newHead
+  }
+}

package/src/ChainBlockIteration/index.ts

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

package/src/ChainBlockIteration/model/BlockNumberIteration.ts

@@ -0,0 +1,7 @@
+import type { Promisable } from '@xylabs/promise'
+import type { BlockBoundWitness, SignedHydratedTransactionWithStorageMeta } from '@xyo-network/xl1-protocol'
+
+export interface BlockNumberIteration {
+  validatePendingBlock(block: BlockBoundWitness): Promisable<Error[]>
+  validatePendingTransaction(tx: SignedHydratedTransactionWithStorageMeta): Promise<boolean>
+}

package/src/ChainBlockIteration/model/Params.ts

@@ -0,0 +1,9 @@
+import type { ArchivistInstance } from '@xyo-network/archivist-model'
+import type { BlockBoundWitness } from '@xyo-network/xl1-protocol'
+
+import type { BaseServiceParams } from '../../model/index.ts'
+
+export interface XyoChainIteratorParams extends BaseServiceParams {
+  chainArchivist: ArchivistInstance
+  head: BlockBoundWitness
+}

package/src/ChainBlockIteration/model/index.ts

@@ -0,0 +1,2 @@
+export * from './BlockNumberIteration.ts'
+export * from './Params.ts'