@xyo-network/xl1-protocol-sdk 1.18.0 → 1.18.2

package/src/simple/finalization/SimpleFinalizationViewer.ts

@@ -0,0 +1,101 @@
+import {
+  assertEx,
+  Hash,
+  spanRootAsync,
+} from '@xylabs/sdk-js'
+import type { ReadArchivist } from '@xyo-network/archivist-model'
+import {
+  asSignedHydratedBlockWithStorageMeta, type SignedBlockBoundWitnessWithHashMeta, type SignedHydratedBlockWithHashMeta,
+  SignedHydratedBlockWithStorageMeta,
+  XL1BlockNumber,
+} from '@xyo-network/xl1-protocol'
+
+import { hydrateBlock } from '../../block/index.ts'
+import {
+  AbstractCreatableProvider, creatableProvider, CreatableProviderParams,
+} from '../../CreatableProvider/index.ts'
+import { ChainStoreRead } from '../../model/index.ts'
+import { findMostRecentBlock, readPayloadMapFromStore } from '../../primitives/index.ts'
+import { HydratedCache } from '../../utils/index.ts'
+import {
+  type FinalizationViewer,
+  FinalizationViewerMoniker,
+} from '../../viewers/index.ts'
+
+export interface SimpleFinalizationViewerParams extends CreatableProviderParams {
+  finalizedArchivist: ReadArchivist
+}
+
+@creatableProvider()
+export class SimpleFinalizationViewer extends AbstractCreatableProvider<SimpleFinalizationViewerParams> implements FinalizationViewer {
+  static readonly defaultMoniker = FinalizationViewerMoniker
+  static readonly dependencies = []
+  static readonly monikers = [FinalizationViewerMoniker]
+  moniker = SimpleFinalizationViewer.defaultMoniker
+
+  protected _store: ChainStoreRead | undefined
+
+  private _signedHydratedBlockCache: HydratedCache<SignedHydratedBlockWithStorageMeta> | undefined
+
+  protected get finalizedArchivist() {
+    return this.params.finalizedArchivist
+  }
+
+  protected get hydratedBlockCache(): HydratedCache<SignedHydratedBlockWithStorageMeta> {
+    if (this._signedHydratedBlockCache) return this._signedHydratedBlockCache
+    const chainMap = this.store.chainMap
+    this._signedHydratedBlockCache = new HydratedCache<SignedHydratedBlockWithStorageMeta>(chainMap, async (
+      store: ChainStoreRead,
+      hash: Hash,
+      maxDepth?: number,
+      minDepth?: number,
+    ) => {
+      const result = await hydrateBlock(store, hash, maxDepth, minDepth)
+      return asSignedHydratedBlockWithStorageMeta(result, true)
+    }, 200)
+    return this._signedHydratedBlockCache
+  }
+
+  protected get store() {
+    return this._store!
+  }
+
+  static override async paramsHandler(params: Partial<SimpleFinalizationViewerParams>) {
+    assertEx(params.finalizedArchivist, () => 'finalizedArchivist is required')
+    return { ...await super.paramsHandler(params) }
+  }
+
+  override async createHandler() {
+    await super.createHandler()
+    this._store = { chainMap: readPayloadMapFromStore(this.params.finalizedArchivist) }
+  }
+
+  async head(): Promise<SignedHydratedBlockWithHashMeta> {
+    return await spanRootAsync('head', async () => {
+      const currentHead = assertEx(await this.getCurrentHead(), () => 'Could not find most recent block [currentBlock]')
+      const cache = this.hydratedBlockCache
+      const block = await cache.get(currentHead._hash)
+      if (!block) {
+        console.log(`Could not find current block with hash ${currentHead!._hash}`)
+      }
+      return assertEx(block, () => 'Could not find current block')
+    }, this.tracer)
+  }
+
+  async headBlock(): Promise<SignedBlockBoundWitnessWithHashMeta> {
+    return (await this.head())[0]
+  }
+
+  async headHash(): Promise<Hash> {
+    return (await this.headBlock())._hash
+  }
+
+  async headNumber(): Promise<XL1BlockNumber> {
+    return (await this.headBlock()).block
+  }
+
+  protected async getCurrentHead() {
+    const chainArchivist = this.finalizedArchivist
+    return await findMostRecentBlock(chainArchivist)
+  }
+}

package/src/simple/finalization/index.ts

@@ -0,0 +1,2 @@
+export * from './SimpleFinalizationRunner.ts'
+export * from './SimpleFinalizationViewer.ts'

package/src/simple/index.ts

@@ -5,6 +5,7 @@ export * from './blockValidation/index.ts'
 export * from './chainStake/index.ts'
 export * from './client/index.ts'
 export * from './datalake/index.ts'
+export * from './finalization/index.ts'
 export * from './gateway/index.ts'
 export * from './mempool/index.ts'
 export * from './network/index.ts'
@@ -13,3 +14,4 @@ export * from './runner/index.ts'
 export * from './signer/index.ts'
 export * from './stakeEvents/index.ts'
 export * from './timesync/index.ts'
+export * from './windowedBlock/index.ts'

package/src/simple/mempool/SimpleMempoolRunner.ts

@@ -1,4 +1,4 @@
-import { type Hash } from '@xylabs/sdk-js'
+import { assertEx, type Hash } from '@xylabs/sdk-js'
 import type { ArchivistInstance } from '@xyo-network/archivist-model'
 import { PayloadBuilder } from '@xyo-network/payload-builder'
 import { type SignedHydratedBlock, type SignedHydratedTransaction } from '@xyo-network/xl1-protocol'
@@ -8,6 +8,7 @@ import {
 } from '../../CreatableProvider/index.ts'
 import { hydratedBlockToPayloadBundle, hydratedTransactionToPayloadBundle } from '../../model/index.ts'
 import { type MempoolRunner, MempoolRunnerMoniker } from '../../runners/index.ts'
+import { WindowedBlockViewerMoniker } from '../../viewers/index.ts'
 
 export interface SimpleMempoolRunnerParams extends CreatableProviderParams {
   pendingBlocksArchivist: ArchivistInstance
@@ -17,6 +18,7 @@ export interface SimpleMempoolRunnerParams extends CreatableProviderParams {
 @creatableProvider()
 export class SimpleMempoolRunner extends AbstractCreatableProvider<SimpleMempoolRunnerParams> implements MempoolRunner {
   static readonly defaultMoniker = MempoolRunnerMoniker
+  static readonly dependencies = [WindowedBlockViewerMoniker]
   static readonly monikers = [MempoolRunnerMoniker]
   moniker = SimpleMempoolRunner.defaultMoniker
 
@@ -28,6 +30,14 @@ export class SimpleMempoolRunner extends AbstractCreatableProvider<SimpleMempool
     return this.params.pendingTransactionsArchivist
   }
 
+  static override async paramsHandler(params?: Partial<SimpleMempoolRunnerParams>): Promise<SimpleMempoolRunnerParams> {
+    return {
+      ...await super.paramsHandler(params),
+      pendingBlocksArchivist: assertEx(params?.pendingBlocksArchivist, () => 'pendingBlocksArchivist is required'),
+      pendingTransactionsArchivist: assertEx(params?.pendingTransactionsArchivist, () => 'pendingTransactionsArchivist is required'),
+    }
+  }
+
   async submitBlocks(blocks: SignedHydratedBlock[]): Promise<Hash[]> {
     const bundles = await Promise.all(blocks.map(async ([bw, payloads]) => {
       return hydratedBlockToPayloadBundle([

package/src/simple/mempool/SimpleMempoolViewer.ts

@@ -1,19 +1,24 @@
 import {
-  creatable,
   exists, isDefined, isHash,
 } from '@xylabs/sdk-js'
 import type { ArchivistInstance } from '@xyo-network/archivist-model'
 import {
   isHashMeta, isPayloadBundle, type Sequence,
 } from '@xyo-network/payload-model'
-import type { SignedHydratedBlockWithHashMeta, SignedHydratedTransactionWithHashMeta } from '@xyo-network/xl1-protocol'
+import type {
+  HydratedTransactionWithHashMeta, SignedHydratedBlockWithHashMeta, SignedHydratedTransactionWithHashMeta,
+} from '@xyo-network/xl1-protocol'
 
-import { AbstractCreatableProvider, CreatableProviderParams } from '../../CreatableProvider/index.ts'
+import {
+  AbstractCreatableProvider, creatableProvider, CreatableProviderParams,
+} from '../../CreatableProvider/index.ts'
 import { bundledPayloadToHydratedBlock, bundledPayloadToHydratedTransaction } from '../../model/index.ts'
 import {
   type MempoolViewer,
   MempoolViewerMoniker,
   type PendingTransactionsOptions,
+  WindowedBlockViewer,
+  WindowedBlockViewerMoniker,
 } from '../../viewers/index.ts'
 
 export interface SimpleMempoolViewerParams extends CreatableProviderParams {
@@ -21,12 +26,15 @@ export interface SimpleMempoolViewerParams extends CreatableProviderParams {
   pendingTransactionsArchivist: ArchivistInstance
 }
 
-@creatable()
+@creatableProvider()
 export class SimpleMempoolViewer extends AbstractCreatableProvider<SimpleMempoolViewerParams> implements MempoolViewer {
   static readonly defaultMoniker = MempoolViewerMoniker
+  static readonly dependencies = [WindowedBlockViewerMoniker]
   static readonly monikers = [MempoolViewerMoniker]
   moniker = SimpleMempoolViewer.defaultMoniker
 
+  private _windowedBlockViewer?: WindowedBlockViewer
+
   protected get pendingBlocksArchivist() {
     return this.params.pendingBlocksArchivist
   }
@@ -35,6 +43,15 @@ export class SimpleMempoolViewer extends AbstractCreatableProvider<SimpleMempool
     return this.params.pendingTransactionsArchivist
   }
 
+  protected get windowedBlockViewer() {
+    return this._windowedBlockViewer!
+  }
+
+  override async createHandler() {
+    await super.createHandler()
+    this._windowedBlockViewer = await this.locator.getInstance<WindowedBlockViewer>(WindowedBlockViewerMoniker)
+  }
+
   async pendingBlocks({ cursor: providedCursor }: PendingTransactionsOptions = {}): Promise<SignedHydratedBlockWithHashMeta[]> {
     let cursor: Sequence | undefined = undefined
     if (isHash(providedCursor)) {
@@ -44,13 +61,13 @@ export class SimpleMempoolViewer extends AbstractCreatableProvider<SimpleMempool
       }
     }
     const bundles = await this.pendingBlocksArchivist.next({
-      order: 'asc', limit: 100, cursor,
+      order: 'desc', limit: 100, cursor,
     })
     const filteredBundles = bundles.filter(isPayloadBundle).filter(isHashMeta)
     return (await Promise.all(filteredBundles.map(async bundle => await bundledPayloadToHydratedBlock(bundle)))).filter(exists)
   }
 
-  async pendingTransactions({ cursor: providedCursor }: PendingTransactionsOptions = {}): Promise<SignedHydratedTransactionWithHashMeta[]> {
+  async pendingTransactions({ cursor: providedCursor, limit = 100 }: PendingTransactionsOptions = {}): Promise<SignedHydratedTransactionWithHashMeta[]> {
     let cursor: Sequence | undefined = undefined
     if (isHash(providedCursor)) {
       const [p] = await this.pendingTransactionsArchivist.get([providedCursor])
@@ -60,13 +77,29 @@ export class SimpleMempoolViewer extends AbstractCreatableProvider<SimpleMempool
     }
     this.logger?.info(`Fetching pending transactions from cursor: ${cursor}`)
     const bundles = await this.pendingTransactionsArchivist.next({
-      order: 'asc', limit: 100, cursor,
+      order: 'asc', limit, cursor,
     })
     this.logger?.info(`Fetched pending transactions: ${bundles.length} bundles`)
     const filteredBundles = bundles.filter(isPayloadBundle).filter(isHashMeta)
     this.logger?.info(`Filtered pending transactions: ${JSON.stringify(bundles, null, 2)} filteredBundles`)
     const result = (await Promise.all(filteredBundles.map(async bundle => await bundledPayloadToHydratedTransaction(bundle)))).filter(exists)
     this.logger?.info(`Converted pending transactions: ${JSON.stringify(result, null, 2)} results`)
-    return result
+    return (await Promise.all(result.map(async (tx) => {
+      const purged = await this.purgeIfInvalid(tx)
+      if (purged) {
+        this.logger?.info(`Purged completed/invalid transaction: ${tx[0]._hash}`)
+      } else {
+        return tx
+      }
+    }))).filter(exists)
+  }
+
+  private async purgeIfInvalid(tx: HydratedTransactionWithHashMeta) {
+    const existingBlock = await this.windowedBlockViewer.blockByTransactionHash(tx[0]._hash)
+    if (existingBlock) {
+      await this.pendingTransactionsArchivist.delete([tx[0]._hash])
+      return true
+    }
+    return false
   }
 }

package/src/simple/runner/SimpleXyoRunner.ts

@@ -7,7 +7,7 @@ import { PayloadBuilder } from '@xyo-network/payload-builder'
 import type { SignedHydratedTransactionWithStorageMeta } from '@xyo-network/xl1-protocol'
 
 import type { CreatableProviderParams } from '../../CreatableProvider/index.ts'
-import { AbstractCreatableProvider } from '../../CreatableProvider/index.ts'
+import { AbstractCreatableProvider, creatableProvider } from '../../CreatableProvider/index.ts'
 import { hydratedTransactionToPayloadBundle } from '../../model/index.ts'
 import { type XyoRunner, XyoRunnerMoniker } from '../../provider/index.ts'
 import { type MempoolRunner, MempoolRunnerMoniker } from '../../runners/index.ts'
@@ -16,8 +16,10 @@ export interface SimpleXyoRunnerParams extends CreatableProviderParams {
   pendingTransactionsArchivist: ArchivistInstance
 }
 
+@creatableProvider()
 export class SimpleXyoRunner extends AbstractCreatableProvider<SimpleXyoRunnerParams> implements XyoRunner {
   static readonly defaultMoniker = XyoRunnerMoniker
+  static readonly dependencies = [MempoolRunnerMoniker]
   static readonly monikers = [XyoRunnerMoniker]
   moniker = SimpleXyoRunner.defaultMoniker
 

package/src/simple/signer/SimpleXyoSigner.ts

@@ -1,4 +1,5 @@
 import type { Address, Promisable } from '@xylabs/sdk-js'
+import { Account } from '@xyo-network/account'
 import type { AccountInstance } from '@xyo-network/account-model'
 import { PayloadBuilder } from '@xyo-network/payload-builder'
 import { type Payload } from '@xyo-network/payload-model'
@@ -10,14 +11,34 @@ import type {
 } from '@xyo-network/xl1-protocol'
 import { SignedHydratedTransactionWithHashMetaZod } from '@xyo-network/xl1-protocol'
 
-import type { XyoSigner } from '../../provider/index.ts'
+import type { CreatableProviderParams } from '../../CreatableProvider/index.ts'
+import { AbstractCreatableProvider } from '../../CreatableProvider/index.ts'
+import { type XyoSigner, XyoSignerMoniker } from '../../provider/index.ts'
 import { buildTransaction, signTransaction } from '../../transaction/index.ts'
 
-export class SimpleXyoSigner implements XyoSigner {
-  protected readonly _account: AccountInstance
+export interface SimpleXyoSignerParams extends CreatableProviderParams {
+  account: AccountInstance
+}
+
+export class SimpleXyoSigner extends AbstractCreatableProvider<SimpleXyoSignerParams> implements XyoSigner {
+  static readonly defaultMoniker = XyoSignerMoniker
+  static readonly monikers = [XyoSignerMoniker]
+  moniker = SimpleXyoSigner.defaultMoniker
+  protected readonly _account!: AccountInstance
+
+  static override async paramsHandler(params?: Partial<SimpleXyoSignerParams>) {
+    let account: AccountInstance
+    if (params?.account) {
+      account = params.account
+    } else {
+      const localLogger = params?.logger ?? params?.context?.logger
+      localLogger?.warn(`No account provided to SimpleXyoSigner, generating a random account. 
+        This account will not be persisted and any transactions signed with it may be lost.
+      `)
 
-  constructor(account: AccountInstance) {
-    this._account = account
+      account = await Account.random()
+    }
+    return { ...await super.paramsHandler(params), account }
   }
 
   address(): Promisable<Address> {

package/src/simple/stakeEvents/SimpleStakeEventsViewer.ts

@@ -16,6 +16,7 @@ export interface SimpleStakeEventsParams extends CreatableProviderParams {
 @creatableProvider()
 export class SimpleStakeEventsViewer extends AbstractCreatableProvider<SimpleStakeEventsParams> implements StakeEventsViewer {
   static readonly defaultMoniker = StakeEventsViewerMoniker
+  static readonly dependencies = []
   static readonly monikers = [StakeEventsViewerMoniker]
   moniker = SimpleStakeEventsViewer.defaultMoniker
 

package/src/simple/timesync/SimpleTimeSyncViewer.ts

@@ -9,7 +9,7 @@ import {
 import type { Provider } from 'ethers'
 
 import type { CreatableProviderParams } from '../../CreatableProvider/index.ts'
-import { AbstractCreatableProvider } from '../../CreatableProvider/index.ts'
+import { AbstractCreatableProvider, creatableProvider } from '../../CreatableProvider/index.ts'
 import {
   type BlockViewer, BlockViewerMoniker, type TimeSyncViewer, TimeSyncViewerMoniker,
 } from '../../viewers/index.ts'
@@ -18,8 +18,10 @@ export interface SimpleTimeSyncViewerParams extends CreatableProviderParams {
   ethProvider?: Provider
 }
 
+@creatableProvider()
 export class SimpleTimeSyncViewer extends AbstractCreatableProvider<SimpleTimeSyncViewerParams> implements TimeSyncViewer {
   static readonly defaultMoniker = TimeSyncViewerMoniker
+  static readonly dependencies = [BlockViewerMoniker]
   static readonly monikers = [TimeSyncViewerMoniker]
   moniker = SimpleTimeSyncViewer.defaultMoniker
 

package/src/simple/windowedBlock/SimpleWindowedBlockViewer.ts

@@ -0,0 +1,208 @@
+import {
+  assertEx,
+  exists,
+  type Hash,
+  isNull,
+  type Promisable,
+} from '@xylabs/sdk-js'
+import type { Payload, WithHashMeta } from '@xyo-network/payload-model'
+import type {
+  ChainId,
+  HydratedBlockWithHashMeta,
+  SignedHydratedBlockWithHashMeta, XL1BlockNumber,
+} from '@xyo-network/xl1-protocol'
+import { asXL1BlockNumber } from '@xyo-network/xl1-protocol'
+import { Mutex } from 'async-mutex'
+
+import { transactionsFromHydratedBlock } from '../../block/index.ts'
+import {
+  AbstractCreatableProvider, creatableProvider, type CreatableProviderParams,
+} from '../../CreatableProvider/index.ts'
+import { MemoryMap } from '../../driver/index.ts'
+import type { SyncMap } from '../../map/index.ts'
+import type {
+  BlockViewer,
+  WindowedBlockViewer,
+} from '../../viewers/index.ts'
+import {
+  BlockViewerMoniker,
+  WindowedBlockViewerMoniker,
+} from '../../viewers/index.ts'
+
+export interface SimpleWindowedBlockViewerParams extends CreatableProviderParams {
+  blockViewer?: BlockViewer
+  maxWindowSize: number
+  syncInterval: number
+}
+
+@creatableProvider()
+export class SimpleWindowedBlockViewer extends AbstractCreatableProvider<SimpleWindowedBlockViewerParams> implements WindowedBlockViewer {
+  static readonly defaultMoniker = WindowedBlockViewerMoniker
+  static readonly dependencies = [BlockViewerMoniker]
+  static readonly monikers = [WindowedBlockViewerMoniker]
+  moniker = WindowedBlockViewerMoniker
+
+  private _blockHashMap!: SyncMap<Hash, SignedHydratedBlockWithHashMeta>
+  private _blockNumberMap!: SyncMap<XL1BlockNumber, SignedHydratedBlockWithHashMeta>
+  // the external BlockViewer
+  private _blockViewer!: BlockViewer
+  private _chain: SignedHydratedBlockWithHashMeta[] = []
+  private _syncMutex = new Mutex()
+  private _timerId: ReturnType<typeof setInterval> | null = null
+  private _transactionHashMap!: SyncMap<Hash, SignedHydratedBlockWithHashMeta>
+
+  protected get maxWindowSize() {
+    return this.params.maxWindowSize
+  }
+
+  protected get syncInterval() {
+    return this.params.syncInterval
+  }
+
+  static override async paramsHandler(params?: Partial<SimpleWindowedBlockViewerParams>): Promise<SimpleWindowedBlockViewerParams> {
+    return {
+      ...await super.paramsHandler(params),
+      maxWindowSize: params?.maxWindowSize ?? 1000,
+      syncInterval: params?.syncInterval ?? 10_000,
+    }
+  }
+
+  blockByHash(hash: Hash) {
+    return this._blockHashMap.get(hash) ?? null
+  }
+
+  blockByNumber(blockNumber: XL1BlockNumber) {
+    return this._blockNumberMap.get(blockNumber) ?? null
+  }
+
+  async blockByTransactionHash(hash: Hash) {
+    const [block = null] = await this.blocksByTransactionHashes([hash])
+    return block
+  }
+
+  blocksByHash(hash: Hash, limit?: number) {
+    const result: SignedHydratedBlockWithHashMeta[] = []
+    let block = this._blockHashMap.get(hash)
+    while (block && (limit === undefined || result.length < limit)) {
+      result.unshift(block)
+      const previousHash = block[0].previous
+      block = previousHash ? this._blockHashMap.get(previousHash) : undefined
+    }
+    return result
+  }
+
+  blocksByNumber(blockNumber: XL1BlockNumber, limit?: number) {
+    const result: SignedHydratedBlockWithHashMeta[] = []
+    let block = this._blockNumberMap.get(blockNumber)
+    while (block && (limit === undefined || result.length < limit)) {
+      result.unshift(block)
+      const previousBlockNumber = asXL1BlockNumber(block[0].block - 1, true)
+      block = (previousBlockNumber >= 0) ? this._blockNumberMap.get(previousBlockNumber) : undefined
+    }
+    return result
+  }
+
+  blocksByTransactionHashes(hashes: Hash[]): Promisable<HydratedBlockWithHashMeta[]> {
+    return hashes.map(hash => this._transactionHashMap.get(hash)).filter(exists)
+  }
+
+  chainId(_blockNumber?: unknown): Promisable<ChainId> {
+    throw new Error('Method not implemented.')
+  }
+
+  override async createHandler() {
+    await super.createHandler()
+
+    this._blockViewer = assertEx(
+      this.params.blockViewer ?? await this.locator.getInstance<BlockViewer>(BlockViewerMoniker),
+      () => 'BlockViewer instance is required',
+    )
+    this._blockHashMap = new MemoryMap<Hash, SignedHydratedBlockWithHashMeta>()
+    this._blockNumberMap = new MemoryMap<XL1BlockNumber, SignedHydratedBlockWithHashMeta>()
+    this._transactionHashMap = new MemoryMap<Hash, SignedHydratedBlockWithHashMeta>()
+  }
+
+  currentBlock(): Promisable<SignedHydratedBlockWithHashMeta> {
+    return assertEx(this._chain.at(-1))
+  }
+
+  currentBlockHash(): Promisable<Hash> {
+    return assertEx(this._chain.at(-1)?.[0]._hash)
+  }
+
+  currentBlockNumber(): Promisable<XL1BlockNumber> {
+    return assertEx(this._chain.at(-1)?.[0].block)
+  }
+
+  payloadByHash(_hash: Hash): Promisable<WithHashMeta<Payload> | null> {
+    throw new Error('Method not implemented.')
+  }
+
+  payloadsByHash(_hashes: Hash[]): Promisable<WithHashMeta<Payload>[]> {
+    throw new Error('Method not implemented.')
+  }
+
+  override async startHandler() {
+    await super.startHandler()
+    await this.sync()
+    this.stopPoll()
+    this.startPoll()
+  }
+
+  override async stopHandler() {
+    await super.stopHandler()
+    this.stopPoll()
+  }
+
+  private addBlock(block: SignedHydratedBlockWithHashMeta) {
+    const removedBlock = this._chain.shift()
+    if (removedBlock) {
+      this._blockHashMap.delete(removedBlock[0]._hash)
+      this._blockNumberMap.delete(removedBlock[0].block)
+      for (const tx of transactionsFromHydratedBlock(removedBlock)) {
+        this._transactionHashMap.delete(tx._hash)
+      }
+    }
+    this._chain.push(block)
+    this._blockHashMap.set(block[0]._hash, block)
+    for (const tx of transactionsFromHydratedBlock(block)) {
+      this._transactionHashMap.set(tx._hash, block)
+    }
+  }
+
+  private startPoll() {
+    this._timerId = setInterval(() => {
+      void this.sync()
+    }, this.syncInterval)
+  }
+
+  private stopPoll() {
+    if (this._timerId) {
+      clearInterval(this._timerId)
+    }
+    this._timerId = null
+  }
+
+  private async sync() {
+    if (this._syncMutex.isLocked()) {
+      return
+    }
+    return await this._syncMutex.runExclusive(async () => {
+      try {
+        let cursor: SignedHydratedBlockWithHashMeta | null = await this._blockViewer.currentBlock()
+        const previousHead = this._chain.length > 0 ? await this.currentBlockHash() : null
+        const newBlocks: SignedHydratedBlockWithHashMeta[] = []
+        while (!isNull(cursor) && cursor[0]._hash !== previousHead && newBlocks.length < this.maxWindowSize) {
+          newBlocks.unshift(cursor)
+          const previousHash = newBlocks[0][0].previous
+          cursor = isNull(previousHash) ? null : await this._blockViewer.blockByHash(previousHash)
+        }
+        for (const block of newBlocks) {
+          this.addBlock(block)
+        }
+      } catch (ex) {
+        console.error('Error during sync:', ex)
+      }
+    })
+  }
+}

package/src/simple/windowedBlock/index.ts

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

package/src/summary/model/summary.ts

@@ -5,9 +5,9 @@ import type { MapType, MapTypeRead } from '../../map/index.ts'
 import type {
   BaseContext, ChainContext, ChainContextRead,
 } from '../../model/index.ts'
-import type {
-  BalancesStepSummary, SchemasStepSummary, TransfersStepSummary,
-} from './index.ts'
+import type { BalancesStepSummary } from './BalancesStepSummary.ts'
+import type { SchemasStepSummary } from './SchemasStepSummary.ts'
+import type { TransfersStepSummary } from './TransfersSummary.ts'
 
 export interface ChainSummaryContextBase<TPayload extends Payload,
   T extends (MapTypeRead<string, TPayload>)> extends BaseContext {

package/src/summary/primitives/transfers/transfersSummary.ts

@@ -6,7 +6,7 @@ import { deepCalculateFramesFromRange } from '../../../block/index.ts'
 import type { ChainQualified, ChainQualifiedConfig } from '../../../model/index.ts'
 import { isChainQualifiedHeadConfig, isChainQualifiedRangeConfig } from '../../../model/index.ts'
 import { parseSignedBigInt } from '../../../SignedBigInt.ts'
-import type { TransfersStepSummaryContext } from '../../index.ts'
+import type { TransfersStepSummaryContext } from '../../model/index.ts'
 import { transfersStepSummaryFromRange } from './transfersStepSummaryFromRange.ts'
 
 // the summary of amount of rewards claimed from the step reward pool by addresses

package/src/utils/isZodError.ts

@@ -1,4 +1,4 @@
-import * as z from 'zod'
+import { z } from 'zod'
 
 export const isZodError = (error: unknown): error is z.ZodError => {
   return error instanceof z.ZodError

package/src/validation/schema/Mnemonic.ts

@@ -1,4 +1,4 @@
-import * as z from 'zod'
+import { z } from 'zod'
 
 /**
  * Validates a single string containing a BIP-39 mnemonic.

package/src/viewers/AccountBalance.ts

@@ -6,7 +6,7 @@ import {
   TransferZod,
 } from '@xyo-network/xl1-protocol'
 import { BlockBoundWitnessZod, TransactionBoundWitnessZod } from '@xyo-network/xl1-protocol'
-import z from 'zod'
+import { z } from 'zod'
 
 import {
   ChainQualificationZod,

package/src/viewers/Block.ts

@@ -4,7 +4,7 @@ import type {
   ChainId, SignedHydratedBlockWithHashMeta, XL1BlockNumber,
 } from '@xyo-network/xl1-protocol'
 
-import type { Provider } from '../model/index.ts'
+import type { Provider, ProviderMoniker } from '../model/index.ts'
 
 export interface BlockViewerMethods {
   blocksByHash(hash: Hash, limit?: number): Promisable<SignedHydratedBlockWithHashMeta[]>
@@ -16,7 +16,7 @@ export interface BlockViewerMethods {
 export const BlockViewerMoniker = 'BlockViewer' as const
 export type BlockViewerMoniker = typeof BlockViewerMoniker
 
-export interface BlockViewer extends BlockViewerMethods, Provider<BlockViewerMoniker> {
+export interface BlockViewer<TMoniker extends ProviderMoniker = BlockViewerMoniker> extends BlockViewerMethods, Provider<TMoniker> {
   blockByHash(hash: Hash): Promisable<SignedHydratedBlockWithHashMeta | null>
   blockByNumber(block: XL1BlockNumber): Promisable<SignedHydratedBlockWithHashMeta | null>
   chainId(): Promisable<ChainId>

package/src/viewers/BlockValidation.ts

@@ -1,7 +1,7 @@
 import { type Promisable } from '@xylabs/sdk-js'
 import { zodIsFactory } from '@xylabs/zod'
 import type { HydratedBlock, SignedHydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol'
-import z from 'zod'
+import { z } from 'zod'
 
 import {
   ChainQualificationZod, ChainQualifiedHeadConfigZod, ChainQualifiedRangeConfigZod, type Provider,

package/src/viewers/Finalization.ts

@@ -0,0 +1,19 @@
+import type { Hash } from '@xylabs/hex'
+import type {
+  SignedBlockBoundWitnessWithHashMeta, SignedHydratedBlockWithHashMeta, XL1BlockNumber,
+} from '@xyo-network/xl1-protocol'
+
+import type { Provider } from '../model/index.ts'
+
+export interface FinalizationViewerMethods {
+  head(): Promise<SignedHydratedBlockWithHashMeta>
+}
+
+export const FinalizationViewerMoniker = 'FinalizationViewer' as const
+export type FinalizationViewerMoniker = typeof FinalizationViewerMoniker
+
+export interface FinalizationViewer extends FinalizationViewerMethods, Provider<FinalizationViewerMoniker> {
+  headBlock(): Promise<SignedBlockBoundWitnessWithHashMeta>
+  headHash(): Promise<Hash>
+  headNumber(): Promise<XL1BlockNumber>
+}