@xyo-network/xl1-protocol-sdk 1.18.0-rc.1 → 1.18.0

package/src/simple/accountBalance/SimpleAccountBalanceViewer.ts

@@ -2,6 +2,7 @@ import type { Address, Hash } from '@xylabs/sdk-js'
 import {
   asHash,
   assertEx, exists, isDefined, spanRootAsync,
+  ZERO_ADDRESS,
 } from '@xylabs/sdk-js'
 import type { WithHashMeta, WithStorageMeta } from '@xyo-network/payload-model'
 import type {
@@ -16,7 +17,9 @@ import {
 import { deepCalculateFramesFromRange } from '../../block/index.ts'
 import type { CreatableProviderParams } from '../../CreatableProvider/index.ts'
 import { AbstractCreatableProvider, creatableProvider } from '../../CreatableProvider/index.ts'
-import type { Qualified } from '../../model/index.ts'
+import {
+  ChainQualification, type ChainQualified, isChainQualifiedHeadConfig, isChainQualifiedRangeConfig,
+} from '../../model/index.ts'
 import type {
   BalanceStepSummaryContext,
   TransfersStepSummary,
@@ -27,6 +30,7 @@ import {
   transfersStepSummaryFromRange,
 } from '../../summary/index.ts'
 import {
+  AccountBalanceConfig,
   type AccountBalanceHistoryItem, type AccountBalanceViewer, AccountBalanceViewerMoniker,
   type BlockViewer,
   BlockViewerMoniker,
@@ -64,17 +68,17 @@ export class SimpleAccountBalanceViewer extends AbstractCreatableProvider<Simple
     return await super.paramsHandler({ ...params })
   }
 
-  async accountBalance(address: Address, headOrRange?: XL1BlockRange | Hash): Promise<AttoXL1> {
-    const balances = await this.accountBalances([address], headOrRange)
+  async accountBalance(address: Address, config?: AccountBalanceConfig) {
+    const balances = await this.accountBalances([address], config)
     return balances[address] ?? AttoXL1(0n)
   }
 
-  accountBalanceHistories(_addresses: Address[], _rangeOrHash?: XL1BlockRange | Hash): Promise<Record<Address, AccountBalanceHistoryItem[]>> {
-    throw new Error('Method [accountBalanceHistories] not implemented.')
+  async accountBalanceHistories(addresses: Address[], config: AccountBalanceConfig = {}) {
+    return (await this.qualifiedAccountBalanceHistories(addresses, config))[0]
   }
 
-  async accountBalanceHistory(address: Address, headOrRange?: XL1BlockRange | Hash): Promise<AccountBalanceHistoryItem[]> {
-    const range = asRange(headOrRange)
+  async accountBalanceHistory(address: Address, config?: AccountBalanceConfig) {
+    const range = isChainQualifiedRangeConfig(config) ? config.range : undefined
     const startingRange = asXL1BlockRange(range ?? [0, await this.blockViewer.currentBlockNumber()], true)
     const blockNumbers = await this.distillTransferHistory(address, startingRange)
     const blocks = (await Promise.all(blockNumbers.map(async bn => await this.blockViewer.blockByNumber(bn)))).filter(exists)
@@ -101,8 +105,8 @@ export class SimpleAccountBalanceViewer extends AbstractCreatableProvider<Simple
     return result
   }
 
-  async accountBalances(address: Address[], _headOrRange?: XL1BlockRange | Hash): Promise<Record<Address, AttoXL1>> {
-    const [result] = (await this.qualifiedAccountBalances(address, _headOrRange))
+  async accountBalances(address: Address[], config?: AccountBalanceConfig) {
+    const [result] = (await this.qualifiedAccountBalances(address, config ?? {}))
     return result
   }
 
@@ -113,57 +117,69 @@ export class SimpleAccountBalanceViewer extends AbstractCreatableProvider<Simple
 
   async qualifiedAccountBalanceHistories(
     addresses: Address[],
-    headOrRange?: Hash | XL1BlockRange,
-  ): Promise<Qualified<Record<Address, AccountBalanceHistoryItem[]>>> {
-    const head = asHash(headOrRange) ?? await this.blockViewer.currentBlockHash()
-    const range = asXL1BlockRange(headOrRange) ?? asXL1BlockRange([0,
-      assertEx(
-        await this.blockViewer.blockByHash(head),
-        () => `Error: Could not find block with hash ${head}`,
-      )[0].block])
-    const qualifiedEntries: [Address, Qualified<AccountBalanceHistoryItem[]>][] = await Promise.all(addresses.map(async address => ([
+    config: AccountBalanceConfig,
+  ) {
+    const head = isChainQualifiedHeadConfig(config) ? config.head : await this.blockViewer.currentBlockHash()
+    const range = isChainQualifiedRangeConfig(config)
+      ? config.range
+      : asXL1BlockRange([0,
+          assertEx(
+            await this.blockViewer.blockByHash(head),
+            () => `Error: Could not find block with hash ${head}`,
+          )[0].block])
+    const qualifiedEntries = await Promise.all(addresses.map(async address => ([
       address,
       await this.qualifiedAccountBalanceHistory(address, range),
-    ])))
+    ]))) satisfies [Address, ChainQualified<AccountBalanceHistoryItem[]>][]
 
     const entries = qualifiedEntries.map(([address, [history]]) => {
       return [address, history]
     })
-    const qualifiedRange = qualifiedEntries[0][1][1]
-    const qualifiedHeadHash = qualifiedEntries[0][1][2]
+    const qualifiedRange = qualifiedEntries[0][1][1].range
+    const qualifiedHeadHash = qualifiedEntries[0][1][1].head
 
     // check for drift
-    for (const [_, [__, range, headHash]] of qualifiedEntries) {
+    for (const [_, [__, { range, head }]] of qualifiedEntries) {
       assertEx(
         range[0] === qualifiedRange[0] && range[1] === qualifiedRange[1],
         () => 'Inconsistent ranges in qualifiedAccountBalanceHistories',
       )
       assertEx(
-        headHash === qualifiedHeadHash,
+        head === qualifiedHeadHash,
         () => 'Inconsistent head hashes in qualifiedAccountBalanceHistories',
       )
     }
 
-    return [Object.fromEntries(entries), qualifiedRange, qualifiedHeadHash]
+    return [Object.fromEntries(entries), { range: qualifiedRange, head: qualifiedHeadHash }] satisfies
+      [Record<Address, AccountBalanceHistoryItem[]>, ChainQualification]
   }
 
   async qualifiedAccountBalances(
     address: Address[],
-    _headOrRange?: Hash | XL1BlockRange,
-  ): Promise<Qualified<Record<Address, AttoXL1>>> {
+    config: AccountBalanceConfig,
+  ): Promise<ChainQualified<Record<Address, AttoXL1>>> {
     return await spanRootAsync('qualifiedAccountsBalances', async () => {
       const qualifiedSummary = await balancesSummary(
-        this.balanceSummaryContext,
+        { ...this.balanceSummaryContext },
+        config,
       )
       const result: Record<Address, AttoXL1> = {}
       for (const addr of address) {
         const summaryBalance = qualifiedSummary[0][addr] ?? 0n
         result[addr] = AttoXL1(summaryBalance < 0n ? 0n : summaryBalance)
       }
-      return [result, qualifiedSummary[1], qualifiedSummary[2]]
+      return [result, qualifiedSummary[1]]
     })
   }
 
+  override async startHandler() {
+    await super.startHandler()
+    await Promise.all([
+      this.accountBalance(ZERO_ADDRESS),
+      this.accountBalanceHistory(ZERO_ADDRESS),
+    ])
+  }
+
   private async distillTransferHistory(address: Address, range: XL1BlockRange, max: number = 50): Promise<XL1BlockNumber[]> {
     if ((range[1] - range[0]) <= StepSizes[0] || max <= 1) {
       return Array.from({ length: range[1] - range[0] + 1 }, (_, i) => range[1] - i).slice(0, max).map(n => asXL1BlockNumber(n, true))
@@ -205,7 +221,7 @@ export class SimpleAccountBalanceViewer extends AbstractCreatableProvider<Simple
   private async qualifiedAccountBalanceHistory(
     address: Address,
     headOrRange?: Hash | XL1BlockRange,
-  ): Promise<Qualified<AccountBalanceHistoryItem[]>> {
+  ): Promise<ChainQualified<AccountBalanceHistoryItem[]>> {
     const range = asRange(headOrRange)
     const headHash = asHash(headOrRange)
     const [head] = assertEx(isDefined(headHash)
@@ -234,6 +250,6 @@ export class SimpleAccountBalanceViewer extends AbstractCreatableProvider<Simple
         null,
         transfer] satisfies AccountBalanceHistoryItem))
     }
-    return [result, startingRange, head._hash]
+    return [result, { range: startingRange, head: head._hash }]
   }
 }

package/src/simple/blockValidation/SimpleBlockValidationViewer.ts

@@ -0,0 +1,126 @@
+import { exists } from '@xylabs/sdk-js'
+import {
+  asXL1BlockRange,
+  ChainId,
+  type SignedHydratedBlockWithHashMeta,
+} from '@xyo-network/xl1-protocol'
+
+import type { CreatableProviderParams } from '../../CreatableProvider/index.ts'
+import { AbstractCreatableProvider, creatableProvider } from '../../CreatableProvider/index.ts'
+import { findUncles, getWindowedChain } from '../../primitives/index.ts'
+import type {
+  HydratedBlockStateValidationFunction, HydratedBlockValidationError, HydratedBlockValidationFunction,
+} from '../../validation/index.ts'
+import type {
+  AccountBalanceViewer,
+  BlockValidationConfig,
+  BlockValidationQualification,
+  BlockValidationViewer,
+} from '../../viewers/index.ts'
+import {
+  AccountBalanceViewerMoniker,
+  BlockValidationViewerMoniker, BlockViewer, BlockViewerMoniker,
+} from '../../viewers/index.ts'
+
+export interface SimpleBlockValidationViewerParams extends CreatableProviderParams {
+  maxUncleWindowSize: number
+  state?: HydratedBlockStateValidationFunction
+  value?: HydratedBlockValidationFunction
+}
+
+@creatableProvider()
+export class SimpleBlockValidationViewer extends AbstractCreatableProvider<SimpleBlockValidationViewerParams> implements BlockValidationViewer {
+  static readonly defaultMoniker = BlockValidationViewerMoniker
+  static readonly monikers = [BlockValidationViewerMoniker]
+  moniker = SimpleBlockValidationViewer.defaultMoniker
+
+  private _accountBalanceViewer!: AccountBalanceViewer
+  private _blockViewer!: BlockViewer
+  private _uncleWindowedChainCache: SignedHydratedBlockWithHashMeta[] | null = null
+
+  protected get blockViewer() {
+    return this._blockViewer
+  }
+
+  protected get maxUncleWindowSize() {
+    return this.params.maxUncleWindowSize
+  }
+
+  static override async paramsHandler(params: Partial<SimpleBlockValidationViewerParams>): Promise<SimpleBlockValidationViewerParams> {
+    return {
+      ...await super.paramsHandler(params),
+      maxUncleWindowSize: params.maxUncleWindowSize ?? 100,
+    } satisfies SimpleBlockValidationViewerParams
+  }
+
+  override async createHandler() {
+    await super.createHandler()
+    this._accountBalanceViewer = await this.locator.getInstance<AccountBalanceViewer>(AccountBalanceViewerMoniker)
+    this._blockViewer = await this.locator.getInstance<BlockViewer>(BlockViewerMoniker)
+  }
+
+  async qualifiedValidateBlock(
+    block: SignedHydratedBlockWithHashMeta,
+    config?: BlockValidationConfig,
+  ): Promise<[HydratedBlockValidationError[], BlockValidationQualification]> {
+    return (await this.qualifiedValidateBlocks([block], config))
+  }
+
+  async qualifiedValidateBlocks(
+    blocks: SignedHydratedBlockWithHashMeta[],
+    config?: BlockValidationConfig,
+  ): Promise<[HydratedBlockValidationError[], BlockValidationQualification]> {
+    const { value, state } = config ?? {
+      shape: true, links: true, state: true,
+    }
+
+    const [headBlock] = await this.blockViewer.currentBlock()
+    const chainId = headBlock.chain
+
+    const validateValue = value ? this.doValidateValue.bind(this) : undefined
+    const validateState = state ? this.doValidateState.bind(this) : undefined
+
+    return [(await Promise.all([
+      validateValue?.(blocks, chainId), validateState?.(blocks, chainId),
+    ].filter(exists))).flat(), { head: headBlock._hash, range: asXL1BlockRange([0, headBlock.block], true) }]
+  }
+
+  async validateBlock(block: SignedHydratedBlockWithHashMeta, config?: BlockValidationConfig): Promise<HydratedBlockValidationError[]> {
+    return (await this.validateBlocks([block], config))
+  }
+
+  async validateBlocks(blocks: SignedHydratedBlockWithHashMeta[], config?: BlockValidationConfig): Promise<HydratedBlockValidationError[]> {
+    return (await this.qualifiedValidateBlocks(blocks, config))[0]
+  }
+
+  private async doValidateState(blocks: SignedHydratedBlockWithHashMeta[], chainId: ChainId): Promise<HydratedBlockValidationError[]> {
+    const windowedUncleChain = await this.updateWindowedChainCache()
+
+    const uncles = findUncles(this.context, windowedUncleChain, blocks)
+
+    if (uncles.length !== 1) {
+      throw new Error(`No uncles or greater than one uncle found in block validation, which is not supported [${uncles.length}]`)
+    }
+    return (await Promise.all(uncles[0].map(async (block) => {
+      return await this.params.state!(
+        block,
+        chainId,
+        { accountBalance: this._accountBalanceViewer },
+      )
+    }))).flat()
+  }
+
+  private async doValidateValue(blocks: SignedHydratedBlockWithHashMeta[], chainId: ChainId): Promise<HydratedBlockValidationError[]> {
+    return (await Promise.all(blocks.map(async (block) => {
+      return await this.params.value!(
+        block,
+        chainId,
+      )
+    }))).flat()
+  }
+
+  private async updateWindowedChainCache() {
+    this._uncleWindowedChainCache = await getWindowedChain(this.blockViewer, this.maxUncleWindowSize, this._uncleWindowedChainCache ?? [])
+    return [...this._uncleWindowedChainCache]
+  }
+}

package/src/simple/blockValidation/index.ts

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

package/src/simple/datalake/AbstractSimpleDataLake.ts

@@ -14,7 +14,8 @@ MapTypeRead<Hash, DataLakeData> = MapTypeRead<Hash, DataLakeData>> extends
   map: TMap
 }
 
-export class AbstractSimpleDataLake<TParams extends AbstractSimpleDataLakeParams = AbstractSimpleDataLakeParams> extends AbstractCreatableProvider<TParams> {
+export abstract class AbstractSimpleDataLake<TParams extends AbstractSimpleDataLakeParams = AbstractSimpleDataLakeParams> extends
+  AbstractCreatableProvider<TParams> {
   get allowedSchemas(): Schema[] | undefined {
     return this.params.allowedSchemas
   }

package/src/simple/datalake/SimpleDataLakeViewer.ts

@@ -1,5 +1,4 @@
 import type { Hash } from '@xylabs/sdk-js'
-import { isAnyPayload } from '@xyo-network/payload-model'
 
 import { creatableProvider } from '../../CreatableProvider/index.ts'
 import type { MapTypeRead } from '../../map/index.ts'

package/src/simple/index.ts

@@ -1,6 +1,7 @@
 export * from './accountBalance/index.ts'
 export * from './block/index.ts'
 export * from './blockReward/index.ts'
+export * from './blockValidation/index.ts'
 export * from './chainStake/index.ts'
 export * from './client/index.ts'
 export * from './datalake/index.ts'

package/src/simple/timesync/SimpleTimeSyncViewer.ts

@@ -1,4 +1,4 @@
-import type { Hash, Promisable } from '@xylabs/sdk-js'
+import type { Hash } from '@xylabs/sdk-js'
 import {
   asHash, assertEx, isDefined,
 } from '@xylabs/sdk-js'

package/src/summary/model/summary.ts

@@ -13,7 +13,6 @@ export interface ChainSummaryContextBase<TPayload extends Payload,
   T extends (MapTypeRead<string, TPayload>)> extends BaseContext {
   stepSemaphores: Semaphore[]
   summaryMap: T
-  windowSize?: number
 }
 
 export interface ChainSummaryContextRead<T extends Payload> extends ChainSummaryContextBase<T, MapTypeRead<string, T>>, ChainContextRead {}

package/src/summary/primitives/balances/balancesSummary.ts

@@ -1,27 +1,27 @@
 import type { Address } from '@xylabs/sdk-js'
-import {
-  asAddress, isDefined, spanRootAsync,
-} from '@xylabs/sdk-js'
-import {
-  asBlockBoundWitnessWithStorageMeta, asXL1BlockNumber, asXL1BlockRange,
-} from '@xyo-network/xl1-protocol'
+import { asAddress, spanRootAsync } from '@xylabs/sdk-js'
+import { asBlockBoundWitnessWithStorageMeta, asXL1BlockRange } from '@xyo-network/xl1-protocol'
 
 import { deepCalculateFramesFromRange } from '../../../block/index.ts'
-import type { Qualified } from '../../../model/index.ts'
+import {
+  type ChainQualified, type ChainQualifiedConfig, isChainQualifiedHeadConfig,
+  isChainQualifiedRangeConfig,
+} from '../../../model/index.ts'
 import { parseSignedBigInt } from '../../../SignedBigInt.ts'
 import type { BalanceStepSummaryContext } from '../../model/index.ts'
 import { balancesStepSummaryFromRange } from './balancesStepSummaryFromRange.ts'
 
 export async function balancesSummary(
   context: BalanceStepSummaryContext,
-): Promise<Qualified<Record<Address, bigint>>> {
+  config?: ChainQualifiedConfig,
+): Promise<ChainQualified<Record<Address, bigint>>> {
   return await spanRootAsync('balancesSummary', async () => {
-    const [headHash] = await context.head()
+    const [headHash] = isChainQualifiedHeadConfig(config) ? [config.head] : await context.head()
     const headResult = await context.store.chainMap.get(headHash)
     const headBoundWitness = asBlockBoundWitnessWithStorageMeta(headResult, () => `Head block not found for hash: ${headHash}`)
-    const rangeStart = asXL1BlockNumber(isDefined(context.windowSize) ? Math.max(headBoundWitness.block - context.windowSize + 1, 0) : 0, true)
+    const range = isChainQualifiedRangeConfig(config) ? config.range : asXL1BlockRange([0, headBoundWitness.block], true)
     const ranges = deepCalculateFramesFromRange(asXL1BlockRange(
-      [rangeStart, headBoundWitness.block],
+      range,
       { name: 'balancesSummary' },
     ))
     const summaries = await Promise.all(ranges.map(range => balancesStepSummaryFromRange(context, range)))
@@ -32,6 +32,6 @@ export async function balancesSummary(
         balances[validAddress] = (balances[validAddress] ?? 0n) + parseSignedBigInt(balance)
       }
     }
-    return [balances, [rangeStart, headBoundWitness.block], headHash]
+    return [balances, { range, head: headHash }]
   })
 }

package/src/summary/primitives/schemas/schemasSummary.ts

@@ -1,24 +1,26 @@
-import { isDefined, spanRootAsync } from '@xylabs/sdk-js'
+import { spanRootAsync } from '@xylabs/sdk-js'
 import type { Schema } from '@xyo-network/payload-model'
-import {
-  asBlockBoundWitnessWithStorageMeta, asXL1BlockNumber, asXL1BlockRange,
-} from '@xyo-network/xl1-protocol'
+import { asBlockBoundWitnessWithStorageMeta, asXL1BlockRange } from '@xyo-network/xl1-protocol'
 
 import { deepCalculateFramesFromRange } from '../../../block/index.ts'
-import type { Qualified } from '../../../model/index.ts'
+import {
+  type ChainQualified, type ChainQualifiedConfig, isChainQualifiedHeadConfig,
+  isChainQualifiedRangeConfig,
+} from '../../../model/index.ts'
 import type { SchemasStepSummaryContext } from '../../model/index.ts'
 import { schemasStepSummaryFromRange } from './schemasStepSummaryFromRange.ts'
 
 export async function schemasSummary(
   context: SchemasStepSummaryContext,
-): Promise<Qualified<Record<Schema, number>>> {
+  config?: ChainQualifiedConfig,
+): Promise<ChainQualified<Record<Schema, number>>> {
   return await spanRootAsync('schemasSummary', async () => {
-    const [headHash] = await context.head()
+    const [headHash] = isChainQualifiedHeadConfig(config) ? [config.head] : await context.head()
     const headResult = await context.store.chainMap.get(headHash)
     const headBoundWitness = asBlockBoundWitnessWithStorageMeta(headResult, () => `Head block not found for hash: ${headHash}`)
-    const rangeStart = asXL1BlockNumber(isDefined(context.windowSize) ? Math.max(headBoundWitness.block - context.windowSize + 1, 0) : 0, true)
+    const range = isChainQualifiedRangeConfig(config) ? config.range : asXL1BlockRange([0, headBoundWitness.block], true)
     const ranges = deepCalculateFramesFromRange(asXL1BlockRange(
-      [rangeStart, headBoundWitness.block],
+      range,
       { name: 'schemasSummary' },
     ))
     const summaries = await Promise.all(ranges.map(range => schemasStepSummaryFromRange(context, range)))
@@ -28,6 +30,6 @@ export async function schemasSummary(
         results[schema] = (results[schema] ?? 0) + count
       }
     }
-    return [results, [rangeStart, headBoundWitness.block], headHash]
+    return [results, { range, head: headHash }]
   })
 }

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

@@ -1,31 +1,29 @@
 import type { Address, Hash } from '@xylabs/sdk-js'
-import {
-  asAddress, isDefined, spanRootAsync,
-} from '@xylabs/sdk-js'
-import {
-  asBlockBoundWitnessWithStorageMeta, asXL1BlockNumber, asXL1BlockRange,
-} from '@xyo-network/xl1-protocol'
+import { asAddress, spanRootAsync } from '@xylabs/sdk-js'
+import { asBlockBoundWitnessWithStorageMeta, asXL1BlockRange } from '@xyo-network/xl1-protocol'
 
 import { deepCalculateFramesFromRange } from '../../../block/index.ts'
-import type { Qualified } from '../../../model/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 { transfersStepSummaryFromRange } from './transfersStepSummaryFromRange.ts'
 
 // the summary of amount of rewards claimed from the step reward pool by addresses
 export async function transfersSummary(
-  transferContext: TransfersStepSummaryContext,
-): Promise<Qualified<Record<Address, Record<Address, bigint>>>> {
+  context: TransfersStepSummaryContext,
+  config?: ChainQualifiedConfig,
+): Promise<ChainQualified<Record<Address, Record<Address, bigint>>>> {
   return await spanRootAsync('transferSummary', async () => {
-    const [headHash] = await transferContext.head()
-    const headResult = await transferContext.store.chainMap.get(headHash)
-    const headBoundWitness = asBlockBoundWitnessWithStorageMeta(headResult, () => `Head block not found for hash: ${transferContext.head}`)
-    const rangeStart = asXL1BlockNumber(isDefined(transferContext.windowSize) ? Math.max(headBoundWitness.block - transferContext.windowSize + 1, 0) : 0, true)
+    const [headHash] = isChainQualifiedHeadConfig(config) ? [config.head] : await context.head()
+    const headResult = await context.store.chainMap.get(headHash)
+    const headBoundWitness = asBlockBoundWitnessWithStorageMeta(headResult, () => `Head block not found for hash: ${headHash}`)
+    const range = isChainQualifiedRangeConfig(config) ? config.range : asXL1BlockRange([0, headBoundWitness.block], true)
     const ranges = deepCalculateFramesFromRange(asXL1BlockRange(
-      [rangeStart, headBoundWitness.block],
+      range,
       { name: 'transfersSummary' },
     ))
-    const summaries = await Promise.all(ranges.map(range => transfersStepSummaryFromRange(transferContext, range)))
+    const summaries = await Promise.all(ranges.map(range => transfersStepSummaryFromRange(context, range)))
     const transfers: Record<Address, Record<Address, bigint>> = {}
     for (let summary of summaries) {
       for (const [from, toMap] of Object.entries(summary.transfers)) {
@@ -37,7 +35,7 @@ export async function transfersSummary(
         }
       }
     }
-    return [transfers, [rangeStart, headBoundWitness.block], headHash]
+    return [transfers, { range, head: headHash }]
   })
 }
 

package/src/viewers/AccountBalance.ts

@@ -1,18 +1,18 @@
-import type {
-  Address, Hash, Promisable,
-} from '@xylabs/sdk-js'
+import { type Address, type Promisable } from '@xylabs/sdk-js'
+import { zodIsFactory } from '@xylabs/zod'
 import { WithHashMetaZod } from '@xyo-network/payload-model'
 import {
   type AttoXL1,
   TransferZod,
-  type XL1BlockRange,
 } from '@xyo-network/xl1-protocol'
 import { BlockBoundWitnessZod, TransactionBoundWitnessZod } from '@xyo-network/xl1-protocol'
 import z from 'zod'
 
-import type {
-  Provider,
-  Qualified,
+import {
+  ChainQualificationZod,
+  type ChainQualified,
+  ChainQualifiedConfigZod,
+  type Provider,
 } from '../model/index.ts'
 
 export const AccountBalanceHistoryItemZod = z.tuple([
@@ -23,19 +23,27 @@ export const AccountBalanceHistoryItemZod = z.tuple([
 
 export type AccountBalanceHistoryItem = z.infer<typeof AccountBalanceHistoryItemZod>
 
+export const AccountBalanceQualificationZod = ChainQualificationZod
+export type AccountBalanceQualification = z.infer<typeof AccountBalanceQualificationZod>
+export const isAccountBalanceQualification = zodIsFactory(AccountBalanceQualificationZod)
+
+export const AccountBalanceConfigZod = ChainQualifiedConfigZod
+export type AccountBalanceConfig = z.infer<typeof AccountBalanceConfigZod>
+export const isAccountBalanceCOnfig = zodIsFactory(AccountBalanceConfigZod)
+
 export interface AccountBalanceViewerMethods {
   qualifiedAccountBalanceHistories(
     address: Address[],
-    headOrRange?: Hash | XL1BlockRange
-  ): Promisable<Qualified<Record<Address, AccountBalanceHistoryItem[]>>>
-  qualifiedAccountBalances(address: Address[], headOrRange?: Hash | XL1BlockRange): Promisable<Qualified<Record<Address, AttoXL1>>>
+    config: AccountBalanceConfig
+  ): Promisable<ChainQualified<Record<Address, AccountBalanceHistoryItem[]>>>
+  qualifiedAccountBalances(address: Address[], config: AccountBalanceConfig): Promisable<ChainQualified<Record<Address, AttoXL1>>>
 }
 
 export interface AccountBalanceViewer extends AccountBalanceViewerMethods, Provider<AccountBalanceViewerMoniker> {
-  accountBalance(address: Address, headOrRange?: Hash | XL1BlockRange): Promisable<AttoXL1>
-  accountBalanceHistories(address: Address[], headOrRange?: Hash | XL1BlockRange): Promisable<Record<Address, AccountBalanceHistoryItem[]>>
-  accountBalanceHistory(address: Address, headOrRange?: Hash | XL1BlockRange): Promisable<AccountBalanceHistoryItem[]>
-  accountBalances(address: Address[], headOrRange?: Hash | XL1BlockRange): Promisable<Record<Address, AttoXL1>>
+  accountBalance(address: Address, config?: AccountBalanceConfig): Promisable<AttoXL1>
+  accountBalanceHistories(address: Address[], config?: AccountBalanceConfig): Promisable<Record<Address, AccountBalanceHistoryItem[]>>
+  accountBalanceHistory(address: Address, config?: AccountBalanceConfig): Promisable<AccountBalanceHistoryItem[]>
+  accountBalances(address: Address[], config?: AccountBalanceConfig): Promisable<Record<Address, AttoXL1>>
 }
 
 export const AccountBalanceViewerMoniker = 'AccountBalanceViewer' as const

package/src/viewers/BlockValidation.ts

@@ -0,0 +1,47 @@
+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 {
+  ChainQualificationZod, ChainQualifiedHeadConfigZod, ChainQualifiedRangeConfigZod, type Provider,
+} from '../model/index.ts'
+import type { HydratedBlockValidationError } from '../validation/index.ts'
+
+export const BlockValidationQualificationZod = ChainQualificationZod
+export type BlockValidationQualification = z.infer<typeof BlockValidationQualificationZod>
+export const isBlockValidationQualification = zodIsFactory(BlockValidationQualificationZod)
+
+export const BlockValidationConfigFieldsZod = z.object({
+  value: z.boolean().optional(),
+  state: z.boolean().optional(),
+})
+
+export const BlockValidationConfigZod = z.union([
+  BlockValidationConfigFieldsZod.extend(ChainQualifiedHeadConfigZod.shape),
+  BlockValidationConfigFieldsZod.extend(ChainQualifiedRangeConfigZod.shape),
+  BlockValidationConfigFieldsZod,
+  z.object({}),
+])
+
+export type BlockValidationConfig = z.infer<typeof BlockValidationConfigZod>
+export const isBlockValidationConfig = zodIsFactory(BlockValidationConfigZod)
+
+export interface BlockValidationViewerMethods {
+  qualifiedValidateBlocks(
+    blocks: HydratedBlock[],
+    config?: BlockValidationConfig
+  ): Promisable<[HydratedBlockValidationError[], BlockValidationQualification]>
+}
+
+export const BlockValidationViewerMoniker = 'BlockValidationViewer' as const
+export type BlockValidationViewerMoniker = typeof BlockValidationViewerMoniker
+
+export interface BlockValidationViewer extends BlockValidationViewerMethods, Provider<BlockValidationViewerMoniker> {
+  qualifiedValidateBlock(
+    block: SignedHydratedBlockWithHashMeta,
+    config?: BlockValidationConfig
+  ): Promisable<[HydratedBlockValidationError[], BlockValidationQualification]>
+  validateBlock(block: SignedHydratedBlockWithHashMeta, config?: BlockValidationConfig): Promisable<HydratedBlockValidationError[]>
+  validateBlocks(blocks: SignedHydratedBlockWithHashMeta[], config?: BlockValidationConfig): Promisable<HydratedBlockValidationError[]>
+}

package/src/viewers/StakeIntent.ts

@@ -3,10 +3,10 @@ import type {
 } from '@xylabs/sdk-js'
 import type { ChainStakeIntent, XL1BlockRange } from '@xyo-network/xl1-protocol'
 
-import type { Provider, Qualified } from '../model/index.ts'
+import type { ChainQualified, Provider } from '../model/index.ts'
 
 export interface StakeIntentViewerMethods {
-  qualifiedIntentByAddress(address: Address, headOrRange?: Hash | XL1BlockRange): Promisable<Qualified<ChainStakeIntent | null>>
+  qualifiedIntentByAddress(address: Address, headOrRange?: Hash | XL1BlockRange): Promisable<ChainQualified<ChainStakeIntent | null>>
 }
 
 export const StakeIntentViewerMoniker = 'StakeIntentViewer' as const

package/src/viewers/TransactionValidation.ts

@@ -0,0 +1,35 @@
+import { type Promisable } from '@xylabs/sdk-js'
+import { zodIsFactory } from '@xylabs/zod'
+import { type HydratedTransaction, type ValidationError } from '@xyo-network/xl1-protocol'
+import type z from 'zod'
+
+import {
+  ChainQualificationZod, ChainQualifiedConfigZod, type Provider,
+} from '../model/index.ts'
+
+export const TransactionValidationQualificationZod = ChainQualificationZod
+export type TransactionValidationQualification = z.infer<typeof TransactionValidationQualificationZod>
+export const isTransactionValidationQualification = zodIsFactory(TransactionValidationQualificationZod)
+
+export const TransactionValidationConfigZod = ChainQualifiedConfigZod
+export type TransactionValidationConfig = z.infer<typeof TransactionValidationConfigZod>
+export const isTransactionValidationConfig = zodIsFactory(TransactionValidationConfigZod)
+
+export interface TransactionValidationViewerMethods {
+  qualifiedValidateTransactions(
+    transactions: HydratedTransaction[],
+    config?: TransactionValidationConfig
+  ): Promisable<[ValidationError[][], TransactionValidationQualification]>
+}
+
+export const TransactionValidationViewerMoniker = 'TransactionValidationViewer' as const
+export type TransactionValidationViewerMoniker = typeof TransactionValidationViewerMoniker
+
+export interface TransactionValidationViewer extends TransactionValidationViewerMethods, Provider<TransactionValidationViewerMoniker> {
+  qualifiedValidateTransaction(
+    transaction: HydratedTransaction,
+    config?: TransactionValidationConfig
+  ): Promisable<[ValidationError[], TransactionValidationQualification]>
+  validateTransaction(transaction: HydratedTransaction[], config?: TransactionValidationConfig): Promisable<ValidationError[]>
+  validateTransactions(transactions: HydratedTransaction[], config?: TransactionValidationConfig): Promisable<ValidationError[][]>
+}