@xyo-network/xl1-protocol-lib 1.26.1

package/src/validation/block/HydratedBlockValidationFunction.ts

@@ -0,0 +1,21 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type {
+  BaseContext, ChainId, HydratedBlockWithHashMeta, XL1BlockNumber,
+} from '@xyo-network/xl1-protocol-model'
+
+import type { HydratedBlockValidationError } from './error.ts'
+
+/** Context for HydratedBlockValidationFunction operations. */
+export interface HydratedBlockValidationFunctionContext extends BaseContext {}
+
+/**
+ * A function that validates a hydrated block.
+ * @param hydratedBlock The hydrated block to validate.
+ * @param chainIdAtBlockNumber A function to get the chain ID at a specific block number.
+ * @returns An array of errors if the block is invalid, or an empty array if it is valid.
+ */
+export type HydratedBlockValidationFunction = (
+  context: HydratedBlockValidationFunctionContext,
+  hydratedBlock: HydratedBlockWithHashMeta,
+  chainIdAtBlockNumber?: (blockNumber: XL1BlockNumber) => Promisable<ChainId>,
+) => Promisable<HydratedBlockValidationError[]>

package/src/validation/block/error.ts

@@ -0,0 +1,51 @@
+import type { Hash } from '@xylabs/sdk-js'
+import type {
+  BlockBoundWitness, ChainId, HydratedBlock,
+} from '@xyo-network/xl1-protocol-model'
+
+import { isValidationError, ValidationError } from '../error.ts'
+
+/** Error thrown during Blockvalidation  operations. */
+export class BlockValidationError extends ValidationError<BlockBoundWitness> {}
+
+/** Type guard that checks if a value is a valid BlockValidationError. */
+export const isBlockValidationError = (
+  error: unknown,
+): error is BlockValidationError => {
+  if (!isValidationError(error)) return false
+  return (
+    error.name === BlockValidationError.constructor.name
+  )
+}
+
+/** Error thrown during HydratedBlockvalidation  operations. */
+export class HydratedBlockValidationError extends ValidationError<HydratedBlock> {}
+
+/** Type guard that checks if a value is a valid HydratedBlockValidationError. */
+export const isHydratedBlockValidationError = (
+  error: unknown,
+): error is HydratedBlockValidationError => {
+  if (!isValidationError(error)) return false
+  return (
+    error.name === HydratedBlockValidationError.constructor.name
+  )
+}
+
+/** Error thrown during HydratedBlockStatevalidation  operations. */
+export class HydratedBlockStateValidationError extends ValidationError<HydratedBlock> {
+  chainId: ChainId
+  constructor(hash: Hash, chainId: ChainId, value: HydratedBlock, message?: string, cause?: unknown) {
+    super(hash, value, message, cause)
+    this.chainId = chainId
+  }
+}
+
+/** Type guard that checks if a value is a valid HydratedBlockStateValidationError. */
+export const isHydratedBlockStateValidationError = (
+  error: unknown,
+): error is HydratedBlockStateValidationError => {
+  if (!isValidationError(error)) return false
+  return (
+    error.name === HydratedBlockStateValidationError.constructor.name
+  )
+}

package/src/validation/block/index.ts

@@ -0,0 +1,4 @@
+export * from './BlockValidationFunction.ts'
+export * from './error.ts'
+export * from './HydratedBlockStateValidationFunction.ts'
+export * from './HydratedBlockValidationFunction.ts'

package/src/validation/boundwitness/BoundWitnessValidationFunction.ts

@@ -0,0 +1,9 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type { BoundWitness } from '@xyo-network/sdk-js'
+
+import type { BoundWitnessValidationError } from './error.ts'
+
+/** Function type for BoundWitnessValidation operations. */
+export type BoundWitnessValidationFunction<T extends BoundWitness = BoundWitness> = (
+  bw: T,
+) => Promisable<BoundWitnessValidationError[]>

package/src/validation/boundwitness/HydratedBoundWitnessValidationFunction.ts

@@ -0,0 +1,15 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type {
+  BoundWitness, Payload, WithHashMeta,
+} from '@xyo-network/sdk-js'
+
+import type { HydratedBoundWitnessValidationError } from './error.ts'
+
+/** Type representing a hydrated BoundWitnessWithHashMeta with resolved payloads. */
+export type HydratedBoundWitnessWithHashMeta<T extends BoundWitness = BoundWitness, P extends Payload = Payload>
+  = [WithHashMeta<T>, WithHashMeta<P>[]]
+
+/** Type representing a hydrated BoundWitnessValidationFunction with resolved payloads. */
+export type HydratedBoundWitnessValidationFunction<T extends BoundWitness = BoundWitness> = (
+  bw: HydratedBoundWitnessWithHashMeta<T>,
+) => Promisable<HydratedBoundWitnessValidationError[]>

package/src/validation/boundwitness/error.ts

@@ -0,0 +1,29 @@
+import type { BoundWitness, HydratedBoundWitness } from '@xyo-network/sdk-js'
+
+import { isValidationError, ValidationError } from '../error.ts'
+
+/** Error thrown during BoundWitnessvalidation  operations. */
+export class BoundWitnessValidationError extends ValidationError<BoundWitness> {}
+
+/** Type guard that checks if a value is a valid BoundWitnessValidationError. */
+export const isBoundWitnessValidationError = (
+  error: unknown,
+): error is BoundWitnessValidationError => {
+  if (!isValidationError(error)) return false
+  return (
+    error.name === BoundWitnessValidationError.constructor.name
+  )
+}
+
+/** Error thrown during HydratedBoundWitnessvalidation  operations. */
+export class HydratedBoundWitnessValidationError extends ValidationError<HydratedBoundWitness> {}
+
+/** Type guard that checks if a value is a valid HydratedBoundWitnessValidationError. */
+export const isHydratedBoundWitnessValidationError = (
+  error: unknown,
+): error is HydratedBoundWitnessValidationError => {
+  if (!isValidationError(error)) return false
+  return (
+    error.name === HydratedBoundWitnessValidationError.constructor.name
+  )
+}

package/src/validation/boundwitness/index.ts

@@ -0,0 +1,3 @@
+export * from './BoundWitnessValidationFunction.ts'
+export * from './error.ts'
+export * from './HydratedBoundWitnessValidationFunction.ts'

package/src/validation/error.ts

@@ -0,0 +1,25 @@
+import { type Hash, isHash } from '@xylabs/sdk-js'
+import { isError } from '@xylabs/sdk-js'
+import type { Payload } from '@xyo-network/sdk-js'
+
+/** Error thrown during validation  operations. */
+export class ValidationError<TValue = Payload> extends Error {
+  hash: Hash
+  value: TValue
+  constructor(hash: Hash, value: TValue, message?: string, cause?: unknown) {
+    super(message)
+    this.hash = hash
+    this.name = this.constructor.name
+    this.value = value
+    this.cause = cause
+  }
+}
+
+/** Type guard that checks if a value is a valid ValidationError. */
+export const isValidationError = <TValue = Payload>(
+  error: unknown,
+): error is ValidationError<TValue> => {
+  return (
+    isError(error) && isHash((error as ValidationError<TValue>)?.hash) && (error as ValidationError<TValue>)?.value !== undefined
+  )
+}

package/src/validation/index.ts

@@ -0,0 +1,5 @@
+export * from './block/index.ts'
+export * from './boundwitness/index.ts'
+export * from './error.ts'
+export * from './payload/index.ts'
+export * from './transaction/index.ts'

package/src/validation/payload/InBlockPayloadValidationFunction.ts

@@ -0,0 +1,16 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type { Payload, WithHashMeta } from '@xyo-network/sdk-js'
+import type { BaseContext, HydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol-model'
+
+import type { InBlockPayloadValidationError } from './error.ts'
+
+/** Context for InBlockPayloadValidationFunction operations. */
+export interface InBlockPayloadValidationFunctionContext extends BaseContext {
+
+}
+
+/** Function type for InBlockPayloadValidation operations. */
+export type InBlockPayloadValidationFunction = (
+  context: InBlockPayloadValidationFunctionContext,
+  payload: WithHashMeta<Payload>, block: HydratedBlockWithHashMeta,
+) => Promisable<InBlockPayloadValidationError[]>

package/src/validation/payload/error.ts

@@ -0,0 +1,24 @@
+import type { Hash } from '@xylabs/sdk-js'
+import { type Payload } from '@xyo-network/sdk-js'
+import type { HydratedBlock } from '@xyo-network/xl1-protocol-model'
+
+import { isValidationError, ValidationError } from '../error.ts'
+
+/** Error thrown during InBlockPayloadvalidation  operations. */
+export class InBlockPayloadValidationError extends ValidationError<Payload> {
+  block: HydratedBlock
+  constructor(hash: Hash, block: HydratedBlock, value: Payload, message?: string, cause?: unknown) {
+    super(hash, value, message, cause)
+    this.block = block
+  }
+}
+
+/** Type guard that checks if a value is a valid InBlockPayloadValidationError. */
+export const isInBlockPayloadValidationError = (
+  error: unknown,
+): error is InBlockPayloadValidationError => {
+  if (!isValidationError(error)) return false
+  return (
+    error.name === InBlockPayloadValidationError.constructor.name
+  )
+}

package/src/validation/payload/index.ts

@@ -0,0 +1,2 @@
+export * from './error.ts'
+export * from './InBlockPayloadValidationFunction.ts'

package/src/validation/transaction/HydratedTransactionStateValidationFunction.ts

@@ -0,0 +1,27 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type {
+  AccountBalanceViewer,
+  BaseContext, ChainId,
+  HydratedTransactionWithHashMeta,
+} from '@xyo-network/xl1-protocol-model'
+
+import type { BlockViewer } from '../../viewers/index.ts'
+import type { HydratedTransactionValidationError } from './error.ts'
+
+/** Context for HydratedTransactionStateValidationFunction operations. */
+export interface HydratedTransactionStateValidationFunctionContext extends BaseContext {
+  accountBalanceViewer: AccountBalanceViewer
+  blockViewer: BlockViewer
+  chainId: ChainId
+}
+
+/**
+ * A function that validates a hydrated transaction against chain state.
+ * @param context The context to use for validation.
+ * @param hydratedTransaction The hydrated transaction to validate.
+ * @returns An array of errors if the transaction is invalid, or an empty array if it is valid.
+ */
+export type HydratedTransactionStateValidationFunction = (
+  context: HydratedTransactionStateValidationFunctionContext,
+  hydratedTransaction: HydratedTransactionWithHashMeta,
+) => Promisable<HydratedTransactionValidationError[]>

package/src/validation/transaction/HydratedTransactionValidationFunction.ts

@@ -0,0 +1,23 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type {
+  BaseContext, ChainId, HydratedTransactionWithHashMeta, StepIdentity,
+} from '@xyo-network/xl1-protocol-model'
+
+import type { HydratedTransactionValidationError } from './error.ts'
+
+/** Context for HydratedTransactionValidationFunction operations. */
+export interface HydratedTransactionValidationFunctionContext extends BaseContext {
+  chainId: ChainId
+  step?: StepIdentity
+}
+
+/**
+ * A function that validates a hydrated transaction.
+ * @param bw The hydrated transaction to validate.
+ * @param context The context to use for validation.
+ * @returns An array of errors if the transaction is invalid, or an empty array if it is valid.
+ */
+export type HydratedTransactionValidationFunction<TContext extends HydratedTransactionValidationFunctionContext = HydratedTransactionValidationFunctionContext> = (
+  context: TContext,
+  hydratedTransaction: HydratedTransactionWithHashMeta,
+) => Promisable<HydratedTransactionValidationError[]>

package/src/validation/transaction/error.ts

@@ -0,0 +1,16 @@
+import type { HydratedTransaction } from '@xyo-network/xl1-protocol-model'
+
+import { isValidationError, ValidationError } from '../error.ts'
+
+/** Error thrown during HydratedTransactionvalidation  operations. */
+export class HydratedTransactionValidationError extends ValidationError<HydratedTransaction> {}
+
+/** Type guard that checks if a value is a valid HydratedTransactionValidationError. */
+export const isHydratedTransactionValidationError = (
+  error: unknown,
+): error is HydratedTransactionValidationError => {
+  if (!isValidationError(error)) return false
+  return (
+    error.name === HydratedTransactionValidationError.constructor.name
+  )
+}

package/src/validation/transaction/index.ts

@@ -0,0 +1,3 @@
+export * from './error.ts'
+export * from './HydratedTransactionStateValidationFunction.ts'
+export * from './HydratedTransactionValidationFunction.ts'

package/src/viewers/Block.ts

@@ -0,0 +1,40 @@
+import type { Hash, Promisable } from '@xylabs/sdk-js'
+import type { Payload, WithHashMeta } from '@xyo-network/sdk-js'
+import type {
+  BlockRate, ChainId,
+  Provider, ProviderMoniker, SignedHydratedBlockWithHashMeta, SingleTimeConfig, TimeDurations, XL1BlockNumber, XL1BlockRange,
+} from '@xyo-network/xl1-protocol-model'
+
+/** BlockViewerMethods interface. */
+export interface BlockViewerMethods {
+  blocksByHash(hash: Hash, limit?: number): Promisable<SignedHydratedBlockWithHashMeta[]>
+  blocksByNumber(block: XL1BlockNumber, limit?: number): Promisable<SignedHydratedBlockWithHashMeta[]>
+  currentBlock(): Promisable<SignedHydratedBlockWithHashMeta>
+  payloadsByHash(hashes: Hash[]): Promisable<WithHashMeta<Payload>[]>
+}
+
+/** Moniker identifier for the BlockViewer provider. */
+export const BlockViewerMoniker = 'BlockViewer' as const
+/** Type literal for the BlockViewer provider moniker. */
+export type BlockViewerMoniker = typeof BlockViewerMoniker
+
+/** Viewer interface for reading Block data. */
+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>
+  chainId(blockNumber: XL1BlockNumber): Promisable<ChainId>
+  chainId(blockNumber: 'latest'): Promisable<ChainId>
+  currentBlockHash(): Promisable<Hash>
+  currentBlockNumber(): Promisable<XL1BlockNumber>
+  payloadByHash(hash: Hash): Promisable<WithHashMeta<Payload> | null>
+  rate(range: XL1BlockRange, timeUnit?: keyof TimeDurations): Promisable<BlockRate>
+  stepSizeRate(start: XL1BlockNumber, stepIndex: number, count?: number, timeUnit?: keyof TimeDurations): Promisable<BlockRate>
+  timeDurationRate(
+    timeConfig: SingleTimeConfig,
+    startBlockNumber?: XL1BlockNumber,
+    timeUnit?: keyof TimeDurations,
+    toleranceMs?: number,
+    maxAttempts?: number,
+  ): Promisable<BlockRate>
+}

package/src/viewers/BlockInvalidation.ts

@@ -0,0 +1,81 @@
+import { type Promisable } from '@xylabs/sdk-js'
+import { zodIsFactory } from '@xylabs/sdk-js'
+import type {
+  Provider, SignedHydratedBlock, SignedHydratedBlockWithHashMeta,
+} from '@xyo-network/xl1-protocol-model'
+import {
+  ChainQualificationZod, ChainQualifiedHeadConfigZod, ChainQualifiedRangeConfigZod,
+} from '@xyo-network/xl1-protocol-model'
+import { z } from 'zod'
+
+import type { HydratedBlockValidationError } from '../validation/index.ts'
+
+/** BlockInvalidationQualificationZod constant. */
+export const BlockInvalidationQualificationZod = ChainQualificationZod
+/** BlockInvalidationQualification type. */
+export type BlockInvalidationQualification = z.infer<typeof BlockInvalidationQualificationZod>
+/** Type guard that checks if a value is a valid BlockInvalidationQualification. */
+export const isBlockInvalidationQualification = zodIsFactory(BlockInvalidationQualificationZod)
+
+/** BlockInvalidationConfigFieldsZod constant. */
+export const BlockInvalidationConfigFieldsZod = z.object({
+  state: z.boolean().optional(),
+  value: z.boolean().optional(),
+})
+
+/** BlockInvalidationConfigZod constant. */
+export const BlockInvalidationConfigZod = z.union([
+  BlockInvalidationConfigFieldsZod.extend(ChainQualifiedHeadConfigZod.shape),
+  BlockInvalidationConfigFieldsZod.extend(ChainQualifiedRangeConfigZod.shape),
+  BlockInvalidationConfigFieldsZod,
+  z.object({}),
+])
+
+/** BlockInvalidationConfig type. */
+export type BlockInvalidationConfig = z.infer<typeof BlockInvalidationConfigZod>
+/** Type guard that checks if a value is a valid BlockInvalidationConfig. */
+export const isBlockInvalidationConfig = zodIsFactory(BlockInvalidationConfigZod)
+
+/**
+ * Checks if blocks are invalid (impossible to ever become valid) according to protocol rules.
+ */
+
+export interface BlockInvalidationViewerMethods {
+  qualifiedInvalidateBlocks(
+    blocks: SignedHydratedBlock[],
+    config?: BlockInvalidationConfig
+  ): Promisable<[(HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta)[], BlockInvalidationQualification]>
+
+  qualifiedInvalidateUncle(
+    blocks: SignedHydratedBlock[],
+    config?: BlockInvalidationConfig
+  ): Promisable<[(HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta)[], BlockInvalidationQualification]>
+}
+
+/** Moniker identifier for the BlockInvalidationViewer provider. */
+export const BlockInvalidationViewerMoniker = 'BlockInvalidationViewer' as const
+/** Type literal for the BlockInvalidationViewer provider moniker. */
+export type BlockInvalidationViewerMoniker = typeof BlockInvalidationViewerMoniker
+
+/** Viewer interface for reading BlockInvalidation data. */
+export interface BlockInvalidationViewer extends BlockInvalidationViewerMethods, Provider<BlockInvalidationViewerMoniker> {
+  invalidateBlock(
+    block: SignedHydratedBlock,
+    config?: BlockInvalidationConfig
+  ): Promisable<HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta>
+
+  invalidateBlocks(
+    blocks: SignedHydratedBlock[],
+    config?: BlockInvalidationConfig
+  ): Promisable<(HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta)[]>
+
+  invalidateUncle(
+    blocks: SignedHydratedBlock[],
+    config?: BlockInvalidationConfig
+  ): Promisable<(HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta)[]>
+
+  qualifiedInvalidateBlock(
+    block: SignedHydratedBlock,
+    config?: BlockInvalidationConfig
+  ): Promisable<[HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta, BlockInvalidationQualification]>
+}

package/src/viewers/BlockReward.ts

@@ -0,0 +1,18 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type {
+  AttoXL1, Provider, XL1BlockNumber,
+} from '@xyo-network/xl1-protocol-model'
+
+/** BlockRewardViewerMethods interface. */
+export interface BlockRewardViewerMethods {
+  // The amount of xl1 to send to the producer from the block reward
+  allowedRewardForBlock(block: XL1BlockNumber): Promisable<AttoXL1>
+}
+
+/** Moniker identifier for the BlockRewardViewer provider. */
+export const BlockRewardViewerMoniker = 'BlockRewardViewer' as const
+/** Type literal for the BlockRewardViewer provider moniker. */
+export type BlockRewardViewerMoniker = typeof BlockRewardViewerMoniker
+
+/** Viewer interface for reading BlockReward data. */
+export interface BlockRewardViewer extends BlockRewardViewerMethods, Provider<BlockRewardViewerMoniker> {}

package/src/viewers/BlockValidation.ts

@@ -0,0 +1,81 @@
+import { type Promisable } from '@xylabs/sdk-js'
+import { zodIsFactory } from '@xylabs/sdk-js'
+import type {
+  Provider, SignedHydratedBlock, SignedHydratedBlockWithHashMeta,
+} from '@xyo-network/xl1-protocol-model'
+import {
+  ChainQualificationZod, ChainQualifiedHeadConfigZod, ChainQualifiedRangeConfigZod,
+} from '@xyo-network/xl1-protocol-model'
+import { z } from 'zod'
+
+import type { HydratedBlockValidationError } from '../validation/index.ts'
+
+/** BlockValidationQualificationZod constant. */
+export const BlockValidationQualificationZod = ChainQualificationZod
+/** BlockValidationQualification type. */
+export type BlockValidationQualification = z.infer<typeof BlockValidationQualificationZod>
+/** Type guard that checks if a value is a valid BlockValidationQualification. */
+export const isBlockValidationQualification = zodIsFactory(BlockValidationQualificationZod)
+
+/** BlockValidationConfigFieldsZod constant. */
+export const BlockValidationConfigFieldsZod = z.object({
+  value: z.boolean().optional(),
+  state: z.boolean().optional(),
+})
+
+/** BlockValidationConfigZod constant. */
+export const BlockValidationConfigZod = z.union([
+  BlockValidationConfigFieldsZod.extend(ChainQualifiedHeadConfigZod.shape),
+  BlockValidationConfigFieldsZod.extend(ChainQualifiedRangeConfigZod.shape),
+  BlockValidationConfigFieldsZod,
+  z.object({}),
+])
+
+/** BlockValidationConfig type. */
+export type BlockValidationConfig = z.infer<typeof BlockValidationConfigZod>
+/** Type guard that checks if a value is a valid BlockValidationConfig. */
+export const isBlockValidationConfig = zodIsFactory(BlockValidationConfigZod)
+
+/** BlockValidationViewerMethods interface. */
+export interface BlockValidationViewerMethods {
+  qualifiedValidateBlocks(
+    blocks: SignedHydratedBlock[],
+    config?: BlockValidationConfig
+  ): Promisable<[(HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta)[], BlockValidationQualification]>
+
+  qualifiedValidateUncle(
+    blocks: SignedHydratedBlock[],
+    config?: BlockValidationConfig
+  ): Promisable<[(HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta)[], BlockValidationQualification]>
+}
+
+/** Moniker identifier for the BlockValidationViewer provider. */
+export const BlockValidationViewerMoniker = 'BlockValidationViewer' as const
+/** Type literal for the BlockValidationViewer provider moniker. */
+export type BlockValidationViewerMoniker = typeof BlockValidationViewerMoniker
+
+/**
+ * Checks if blocks are valid (currently valid) according to protocol rules.  In the case that they are not valid, they may still become valid in the future.
+ */
+
+export interface BlockValidationViewer extends BlockValidationViewerMethods, Provider<BlockValidationViewerMoniker> {
+  qualifiedValidateBlock(
+    block: SignedHydratedBlock,
+    config?: BlockValidationConfig
+  ): Promisable<[HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta, BlockValidationQualification]>
+
+  validateBlock(
+    block: SignedHydratedBlock,
+    config?: BlockValidationConfig
+  ): Promisable<HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta>
+
+  validateBlocks(
+    blocks: SignedHydratedBlock[],
+    config?: BlockValidationConfig
+  ): Promisable<(HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta)[]>
+
+  validateUncle(
+    blocks: SignedHydratedBlock[],
+    config?: BlockValidationConfig
+  ): Promisable<(HydratedBlockValidationError[] | SignedHydratedBlockWithHashMeta)[]>
+}

package/src/viewers/ChainContract.ts

@@ -0,0 +1,28 @@
+import type {
+  Address, Hash, Promisable,
+} from '@xylabs/sdk-js'
+import type {
+  ChainId, Provider, XL1BlockNumber,
+} from '@xyo-network/xl1-protocol-model'
+
+/** ChainContractViewerMethods interface. */
+export interface ChainContractViewerMethods {
+  chainId(): Promisable<ChainId>
+  forkedAtBlockNumber(): Promisable<XL1BlockNumber | null>
+  forkedAtHash(): Promisable<Hash | null>
+  forkedChainId(): Promisable<ChainId | null>
+  minWithdrawalBlocks(): Promisable<number>
+  rewardsContract(): Promisable<Address>
+  stakingTokenAddress(): Promisable<Address>
+}
+
+/** Moniker identifier for the ChainContractViewer provider. */
+export const ChainContractViewerMoniker = 'ChainContractViewer' as const
+/** Type literal for the ChainContractViewer provider moniker. */
+export type ChainContractViewerMoniker = typeof ChainContractViewerMoniker
+
+/** Viewer interface for reading ChainContract data. */
+export interface ChainContractViewer extends ChainContractViewerMethods, Provider<ChainContractViewerMoniker> {
+  chainIdAtBlockNumber(blockNumber: XL1BlockNumber | 'latest'): Promisable<ChainId>
+  forkedChainContractViewer(): Promisable<ChainContractViewer | null>
+}

package/src/viewers/ChainStakeViewer.ts

@@ -0,0 +1,15 @@
+import type { Provider } from '@xyo-network/xl1-protocol-model'
+
+import type { ChainContractViewer } from './ChainContract.ts'
+import type { StakeTotalsViewer } from './StakeTotals.ts'
+
+/** Moniker identifier for the ChainStakeViewer provider. */
+export const ChainStakeViewerMoniker = 'ChainStakeViewer' as const
+/** Type literal for the ChainStakeViewer provider moniker. */
+export type ChainStakeViewerMoniker = typeof ChainStakeViewerMoniker
+
+/** Viewer interface for reading ChainStake data. */
+export interface ChainStakeViewer extends Omit<ChainContractViewer, 'moniker'>, Omit<StakeTotalsViewer, 'moniker'>,
+  Provider<ChainStakeViewerMoniker> {
+
+}

package/src/viewers/Finalization.ts

@@ -0,0 +1,22 @@
+import type { Hash, Promisable } from '@xylabs/sdk-js'
+import type {
+  ChainId, Provider, SignedBlockBoundWitnessWithHashMeta, SignedHydratedBlockWithHashMeta, XL1BlockNumber,
+} from '@xyo-network/xl1-protocol-model'
+
+/** FinalizationViewerMethods interface. */
+export interface FinalizationViewerMethods {
+  head(): Promisable<SignedHydratedBlockWithHashMeta>
+}
+
+/** Moniker identifier for the FinalizationViewer provider. */
+export const FinalizationViewerMoniker = 'FinalizationViewer' as const
+/** Type literal for the FinalizationViewer provider moniker. */
+export type FinalizationViewerMoniker = typeof FinalizationViewerMoniker
+
+/** Viewer interface for reading Finalization data. */
+export interface FinalizationViewer extends FinalizationViewerMethods, Provider<FinalizationViewerMoniker> {
+  chainId(): Promisable<ChainId>
+  headBlock(): Promisable<SignedBlockBoundWitnessWithHashMeta>
+  headHash(): Promisable<Hash>
+  headNumber(): Promisable<XL1BlockNumber>
+}

package/src/viewers/Fork.ts

@@ -0,0 +1,10 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type { ChainId } from '@xyo-network/xl1-protocol-model'
+
+/** ForkHistory type. */
+export type ForkHistory = Record<number, ChainId>
+
+/** ForkViewerMethods interface. */
+export interface ForkViewerMethods {
+  forkHistory(): Promisable<ForkHistory>
+}

package/src/viewers/Mempool.ts

@@ -0,0 +1,40 @@
+import { HashZod } from '@xylabs/sdk-js'
+import type {
+  Provider, SignedHydratedBlockWithHashMeta, SignedHydratedTransactionWithHashMeta,
+} from '@xyo-network/xl1-protocol-model'
+import { XL1BlockRangeZod } from '@xyo-network/xl1-protocol-model'
+import { z } from 'zod'
+
+/** PendingTransactionsOptionsZod constant. */
+export const PendingTransactionsOptionsZod = z.object({
+  cursor: HashZod.optional(),
+  limit: z.number().int().positive().optional(),
+  window: XL1BlockRangeZod.optional(),
+})
+
+/** PendingTransactionsOptions type. */
+export type PendingTransactionsOptions = z.infer<typeof PendingTransactionsOptionsZod>
+
+/** PendingBlocksOptionsZod constant. */
+export const PendingBlocksOptionsZod = z.object({
+  cursor: HashZod.optional(),
+  limit: z.number().int().positive().optional(),
+  window: XL1BlockRangeZod.optional(),
+})
+
+/** PendingBlocksOptions type. */
+export type PendingBlocksOptions = z.infer<typeof PendingBlocksOptionsZod>
+
+/** MempoolViewerMethods interface. */
+export interface MempoolViewerMethods {
+  pendingBlocks(options?: PendingBlocksOptions): Promise<SignedHydratedBlockWithHashMeta[]>
+  pendingTransactions(options?: PendingTransactionsOptions): Promise<SignedHydratedTransactionWithHashMeta[]>
+}
+
+/** Moniker identifier for the MempoolViewer provider. */
+export const MempoolViewerMoniker = 'MempoolViewer' as const
+/** Type literal for the MempoolViewer provider moniker. */
+export type MempoolViewerMoniker = typeof MempoolViewerMoniker
+
+/** Viewer interface for reading Mempool data. */
+export interface MempoolViewer extends MempoolViewerMethods, Provider<MempoolViewerMoniker> {}