@xyo-network/xl1-protocol-sdk 1.15.28 → 1.16.0

package/src/provider/XyoSigner.ts

@@ -0,0 +1,29 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { Signed, UnsignedBoundWitness } from '@xyo-network/boundwitness-model'
+import type { Payload } from '@xyo-network/payload-model'
+import type {
+  AllowedBlockPayload, ChainId, TransactionBoundWitness,
+  TransactionFeesBigInt,
+} from '@xyo-network/xl1-protocol'
+
+export interface XyoSigner {
+  address(): Promisable<Address>
+  // The tx passed in must have all the payloads (on and off chain) in the payloads array
+  // Returns the signed transaction and the payloads array excluding the off-chain payloads.
+  // The return value is ready to be broadcast to block producers
+  signTransaction(tx: [UnsignedBoundWitness<TransactionBoundWitness>, Payload[]]): Promisable<[Signed<TransactionBoundWitness>, Payload[]]>
+}
+
+export interface XyoSignerDeprecated {
+  /** @deprecated use signTransaction instead */
+  createSignedTransaction(
+    chain: ChainId,
+    elevatedPayloads: AllowedBlockPayload[],
+    additionalPayloads: Payload[],
+    nbf: number,
+    exp: number,
+    fees: TransactionFeesBigInt,
+    from?: Address,
+  ): Promisable<Signed<TransactionBoundWitness>>
+}

package/src/provider/XyoViewer.ts

@@ -0,0 +1,17 @@
+import type {
+  AccountBalanceViewInterface, BlockViewInterface, ChainViewInterface,
+  ForkViewer,
+  NetworkStakeStepRewardViewInterface,
+  NetworkStakeViewer,
+  StakeViewer,
+  TransactionViewInterface, TransferBalanceViewInterface,
+} from '../interfaces/index.ts'
+
+export interface XyoViewerMethods extends AccountBalanceViewInterface, TransferBalanceViewInterface,
+  NetworkStakeStepRewardViewInterface,
+  ChainViewInterface, BlockViewInterface, TransactionViewInterface, StakeViewer, ForkViewer {
+}
+
+export interface XyoViewer extends XyoViewerMethods {
+  networkStakeViewer?: NetworkStakeViewer
+}

package/src/provider/XyoWallet.ts

@@ -0,0 +1,15 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { ChainId } from '@xyo-network/xl1-protocol'
+
+/** @deprecated  - use XyoClient instead */
+export interface XyoWallet {
+  accounts(): Promisable<Address[]>
+  addChain(chain: ChainId, name?: string): Promisable<object>
+  chain(): Promisable<ChainId>
+  chains(): Promisable<object>
+  permissions(): Promisable<Record<string, object>>
+  requestPermissions(permissions: object): Promisable<object>
+  revokePermissions(permissions: object): Promisable<object>
+  switchChain(chain: ChainId): Promisable<void>
+}

package/src/provider/index.ts

@@ -0,0 +1,12 @@
+export * from './permissions/index.ts'
+export * from './TransactionSubmitter.ts'
+export * from './XyoClient.ts'
+export * from './XyoConnection.ts'
+export * from './XyoDataLake.ts'
+export * from './XyoGateway.ts'
+export * from './XyoGatewayHelpers.ts'
+export * from './XyoNetwork.ts'
+export * from './XyoRunner.ts'
+export * from './XyoSigner.ts'
+export * from './XyoViewer.ts'
+export * from './XyoWallet.ts'

package/src/provider/permissions/InvokerPermission.ts

@@ -0,0 +1,56 @@
+import type { JsonValue } from '@xylabs/object'
+
+/**
+ * Modeled after EIP-2255
+ * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+ *
+ * NOTE: In order to send multiple permission requests at once, do not send multiple parentCapability keys.
+ * Instead, send multiple PermissionRequest objects in the params array of the rpc call.
+ */
+export interface PermissionRequest {
+  [parentCapability: string]: {
+    [caveatName: string]: JsonValue
+  }
+}
+
+/**
+ * Modeled after EIP-2255
+ * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+ */
+export interface RequestedPermission {
+  /** Optional timestamp for when the permission was granted */
+  date?: number
+  /** Permission identifier (i.e. RPC method, action, etc.) */
+  parentCapability: string
+}
+
+export type CaveatTypes = 'chain' | 'expiration' | 'filteredResponse' | 'rateLimit' | 'restrictReturnedAccounts'
+
+/**
+ * Modeled after EIP-2255
+ * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+ */
+export interface Caveats {
+  /** Type of caveat */
+  type: CaveatTypes
+  /** Value for the caveat (i.e. chain id, subset of accounts, expiration, max request per minute, etc.) */
+  value: JsonValue
+}
+
+/**
+ * Modeled after EIP-2255
+ * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+ */
+export interface Permission {
+  /** Caveats for the permission, if applicable (i.e. allowed accounts, signing, etc.) */
+  caveats?: Caveats[]
+  /** Invoker for the given permission (URI, domain, webpage, address, etc.) */
+  invoker: string
+  /** Permission identifier (i.e. RPC method, action, etc.) */
+  parentCapability: string
+}
+
+export interface InvokerPermission extends Permission {
+  /** Time at which the permission was granted */
+  date?: number
+}

package/src/provider/permissions/XyoPermissions.ts

@@ -0,0 +1,40 @@
+import type {
+  InvokerPermission, PermissionRequest, RequestedPermission,
+} from './InvokerPermission.ts'
+
+/**
+ * Handles Getting Permissions
+ */
+export interface PermissionsGetHandler {
+  /**
+   * Returns the permissions that are currently granted
+   *
+   * Per the spec - "The wallet_getPermissions method is used for getting an array of current permissions
+   * (empty by default). It takes no parameters and returns an array of Permission objects."
+   *
+   * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+   */
+  getPermissions(): Promise<InvokerPermission[]>
+}
+
+/**
+ * Handles Permission Requests
+ */
+export interface PermissionRequestsHandler {
+  // Given a permissions request, attempts to request the permissions from the user
+  requestPermissions(permissions: PermissionRequest[]): Promise<RequestedPermission[]>
+  // Given a permissions request, attempts to revoke the permissions from the user
+  revokePermissions(permissions: PermissionRequest): Promise<RequestedPermission[]>
+}
+
+/**
+ * Interface for getting, requesting and revoking permissions
+ *
+ * See - https://eips.ethereum.org/EIPS/eip-2255
+ */
+export interface XyoPermissions extends PermissionsGetHandler, PermissionRequestsHandler {
+
+}
+
+// @deprecated - use XyoPermissions instead
+export interface PermissionsProvider extends XyoPermissions {}

package/src/provider/permissions/index.ts

@@ -0,0 +1,2 @@
+export * from './InvokerPermission.ts'
+export * from './XyoPermissions.ts'

package/src/services/AccountBalanceService.ts

@@ -0,0 +1,22 @@
+import type {
+  Address, Hash, Hex,
+} from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { AttoXL1 } from '@xyo-network/xl1-protocol'
+
+import type { ServiceInterface } from './Service.ts'
+
+export interface AccountBalanceProvider {
+  getBalanceValue: (address: Address) => bigint
+}
+
+export interface AccountBalanceService extends AccountBalanceProvider, ServiceInterface {
+  getBalanceValues?: Record<Address, bigint>
+
+  getBalance(address: Address): Hex
+  getBalances(): Record<Address, Hex>
+}
+
+export interface AccountBalanceServiceV2 extends ServiceInterface {
+  balances(head: Hash, addresses: Address[]): Promisable<Partial<Record<Address, AttoXL1>>>
+}

package/src/services/AccountTransfersService.ts

@@ -0,0 +1,12 @@
+import type { Address, Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { AttoXL1 } from '@xyo-network/xl1-protocol'
+
+import type { ServiceInterface } from './Service.ts'
+
+export interface AccountTransfersProvider {
+  transfer(head: Hash, account: Address): Promisable<AttoXL1>
+  transfers(head: Hash, accounts: Address[]): Promisable<Partial<Record<Address, AttoXL1>>>
+}
+
+export interface AccountTransfersService extends AccountTransfersProvider, ServiceInterface {}

package/src/services/BlockProducerService.ts

@@ -0,0 +1,10 @@
+import type {
+  Addressable,
+  BlockBoundWitness, HydratedBlock, IterableRepository,
+} from '@xyo-network/xl1-protocol'
+
+import type { ServiceInterface } from './Service.ts'
+
+export type NextBlockProducer = IterableRepository<BlockBoundWitness, HydratedBlock | undefined>
+
+export interface BlockProducerService extends Addressable, NextBlockProducer, ServiceInterface {}

package/src/services/BlockRewardService.ts

@@ -0,0 +1,8 @@
+import type { Promisable } from '@xylabs/promise'
+
+import type { ServiceInterface } from './Service.ts'
+
+export interface BlockRewardService extends ServiceInterface {
+  // The amount of xl1 to send to the producer from the block reward
+  getRewardForBlock(block: bigint): Promisable<bigint>
+}

package/src/services/BlockRewardServiceV2.ts

@@ -0,0 +1,8 @@
+import type { Promisable } from '@xylabs/promise'
+
+import type { BlockRewardService } from './BlockRewardService.ts'
+
+export interface BlockRewardServiceV2 extends BlockRewardService {
+  // The amount of xl1 to send to the step pool from the block reward
+  getRewardForStepPool(block: bigint): Promisable<bigint>
+}

package/src/services/Chain/BaseChainService.ts

@@ -0,0 +1,7 @@
+import type { ChainId } from '@xyo-network/xl1-protocol'
+
+import type { ServiceInterface } from '../Service.ts'
+
+export interface BaseChainService extends ServiceInterface {
+  chainId: ChainId
+}

package/src/services/Chain/ChainHeadService.ts

@@ -0,0 +1,7 @@
+import type { Hash } from '@xylabs/hex'
+
+import type { BaseChainService } from './BaseChainService.ts'
+
+export interface ChainHeadService extends BaseChainService {
+  head: Hash | null
+}

package/src/services/Chain/ChainService.ts

@@ -0,0 +1,6 @@
+import type { BaseChainService } from './BaseChainService.ts'
+import type {
+  ChainContractViewer, ChainStaker, ChainStakeViewer,
+} from './interfaces/index.ts'
+
+export interface ChainService extends ChainContractViewer, ChainStakeViewer, ChainStaker, BaseChainService {}

package/src/services/Chain/index.ts

@@ -0,0 +1,4 @@
+export * from './BaseChainService.ts'
+export * from './ChainHeadService.ts'
+export * from './ChainService.ts'
+export * from './interfaces/index.ts'

package/src/services/Chain/interfaces/ChainContractViewer.ts

@@ -0,0 +1,5 @@
+import type { ChainContractViewInterface } from '../../../interfaces/index.ts'
+
+export interface ChainContractViewer extends ChainContractViewInterface {
+
+}

package/src/services/Chain/interfaces/ChainStakeViewer.ts

@@ -0,0 +1,6 @@
+import type { StakeTotalsViewer } from '../../../interfaces/index.ts'
+import type { ChainContractViewer } from './ChainContractViewer.ts'
+
+export interface ChainStakeViewer extends ChainContractViewer, StakeTotalsViewer {
+
+}

package/src/services/Chain/interfaces/ChainStaker.ts

@@ -0,0 +1,5 @@
+export interface ChainStaker {
+  addStake(staked: string, amount: bigint): Promise<boolean>
+  removeStake(slot: bigint): Promise<boolean>
+  withdrawStake(slot: bigint): Promise<boolean>
+}

package/src/services/Chain/interfaces/index.ts

@@ -0,0 +1,3 @@
+export * from './ChainContractViewer.ts'
+export * from './ChainStaker.ts'
+export * from './ChainStakeViewer.ts'

package/src/services/ChainIterator/ChainIteratorService.ts

@@ -0,0 +1,45 @@
+import type { BaseParams } from '@xylabs/base'
+import type { BaseEmitter } from '@xylabs/events'
+import type { Hash } from '@xylabs/hex'
+import type { WithStorageMeta } from '@xyo-network/payload-model'
+import type {
+  BlockBoundWitness, ChainId, IterableRepository, ReadRepository,
+} from '@xyo-network/xl1-protocol'
+
+import type { ChainIteratorServiceEventData } from './ChainIteratorServiceEventData.ts'
+
+export interface ChainIteratorService<TKey>
+  extends ReadRepository<TKey, BlockBoundWitness | undefined>, IterableRepository<TKey, WithStorageMeta<BlockBoundWitness> | undefined> {
+  chainId: ChainId
+  head(): Promise<WithStorageMeta<BlockBoundWitness>>
+  previous(cursor?: TKey | undefined, limit?: number): Promise<WithStorageMeta<BlockBoundWitness>[]>
+  updateHead(head: BlockBoundWitness): Promise<void>
+}
+
+// /** @deprecated use ChainIteratorService instead */
+// export interface ChainIterator<TKey> extends ChainIteratorService<TKey> {}
+
+export interface EventingChainIteratorService<TKey> extends ChainIteratorService<TKey>, BaseEmitter<BaseParams, ChainIteratorServiceEventData> {}
+
+// /** @deprecated use EventingChainIteratorService instead */
+// export interface EventingChainIterator<TKey> extends EventingChainIteratorService<TKey> {}
+
+export interface ChainBlockNumberIteratorService extends ChainIteratorService<number> {}
+
+// /** @deprecated use ChainBlockNumberIteratorService instead */
+// export interface ChainBlockNumberIterator extends ChainBlockNumberIteratorService {}
+
+export interface EventingChainBlockNumberIteratorService extends EventingChainIteratorService<number> {}
+
+// /** @deprecated use EventingChainBlockNumberIteratorService instead */
+// export interface EventingChainBlockNumberIterator extends EventingChainBlockNumberIteratorService {}
+
+export interface ChainHashIteratorService extends ChainIteratorService<Hash> {}
+
+// /** @deprecated use ChainHashIteratorService instead */
+// export interface ChainHashIterator extends ChainHashIteratorService {}
+
+export interface EventingChainHashIteratorService extends EventingChainIteratorService<Hash> {}
+
+// /** @deprecated use EventingChainHashIteratorService instead */
+// export interface EventingChainHashIterator extends EventingChainHashIteratorService {}

package/src/services/ChainIterator/ChainIteratorServiceEventData.ts

@@ -0,0 +1,13 @@
+import type { EventData } from '@xylabs/events'
+import type { BlockBoundWitness } from '@xyo-network/xl1-protocol'
+
+export type HeadEventArgs = { blocks: [BlockBoundWitness] }
+
+export interface HeadEventData extends EventData {
+  headUpdated: HeadEventArgs
+}
+
+export interface ChainIteratorServiceEventData extends HeadEventData { }
+
+// /** @deprecated use ChainIteratorServiceEventData instead */
+// export interface ChainIteratorEventData extends ChainIteratorServiceEventData { }

package/src/services/ChainIterator/index.ts

@@ -0,0 +1,2 @@
+export * from './ChainIteratorService.ts'
+export * from './ChainIteratorServiceEventData.ts'

package/src/services/Election.ts

@@ -0,0 +1,15 @@
+import type { Address } from '@xylabs/hex'
+import type { WithHashMeta } from '@xyo-network/payload-model'
+import type { BlockBoundWitness } from '@xyo-network/xl1-protocol'
+
+import type { ServiceInterface } from './Service.ts'
+
+export interface ElectionService extends ServiceInterface {
+
+  /**
+   * Given the current block, get the leader for the next block
+   * @param current The previous block
+   */
+  getCreatorCommitteeForNextBlock(current: WithHashMeta<BlockBoundWitness>): Promise<Address[]>
+
+}

package/src/services/NetworkStakeService.ts

@@ -0,0 +1,4 @@
+import type { NetworkStakeStepRewardViewInterface } from '../interfaces/index.ts'
+import type { ServiceInterface } from './Service.ts'
+
+export interface NetworkStakeStepRewardService extends NetworkStakeStepRewardViewInterface, ServiceInterface {}

package/src/services/Params.ts

@@ -0,0 +1,11 @@
+import type { CreatableParams } from '@xylabs/creatable'
+import type { AccountInstance } from '@xyo-network/account-model'
+import type { OpenTelemetryProviders } from '@xyo-network/xl1-protocol'
+
+export interface BaseServiceParams extends CreatableParams, OpenTelemetryProviders {
+
+}
+
+export interface BaseAccountableServiceParams extends BaseServiceParams {
+  account: AccountInstance
+}

package/src/services/PendingTransactionsService.ts

@@ -0,0 +1,8 @@
+import type { Hash } from '@xylabs/hex'
+import type { SignedHydratedTransaction } from '@xyo-network/xl1-protocol'
+
+import type { ServiceInterface } from './Service.ts'
+
+export interface PendingTransactionsService extends ServiceInterface {
+  getPendingTransactions(head: Hash, limit: number, timeout?: number): Promise<SignedHydratedTransaction[]>
+}

package/src/services/Service.ts

@@ -0,0 +1,5 @@
+import type { Hash } from '@xylabs/hex'
+
+export interface ServiceInterface {
+  sync(head: Hash): Promise<void>
+}

package/src/services/StakeIntentService/ChainIndexingServiceStateSchema.ts

@@ -0,0 +1,43 @@
+import type { Hash } from '@xylabs/hex'
+import type { JsonValue } from '@xylabs/object'
+import { AsObjectFactory } from '@xylabs/object'
+import type { Payload, WithStorageMeta } from '@xyo-network/payload-model'
+import { isPayloadOfSchemaType, isStorageMeta } from '@xyo-network/payload-model'
+
+export interface ChainIndexingServiceStateFields<T extends JsonValue = JsonValue> {
+  /**
+   * The hash of the last block that this service has indexing
+   */
+  endBlockHash: Hash
+  /**
+   * The hash of the block that the service started indexing. If undefined, the service is
+   * assumed to have started indexing from the genesis block
+   */
+  startBlockHash?: Hash
+  /**
+   * The indexed state for the range
+   */
+  state: T
+}
+export const ChainIndexingServiceStateSchema = 'network.xyo.chain.indexing.service.state' as const
+export type ChainIndexingServiceStateSchema = typeof ChainIndexingServiceStateSchema
+
+/**
+ * The result of a ChainIndexingServiceState
+ */
+export type ChainIndexingServiceState<T extends JsonValue = JsonValue> = Payload<ChainIndexingServiceStateFields<T>, ChainIndexingServiceStateSchema>
+
+/**
+ * Identity functions for determining if an object is an ChainIndexingServiceState
+ */
+export const isChainIndexingServiceState = <T extends JsonValue = JsonValue>(payload?: unknown): payload is ChainIndexingServiceState<T> => {
+  return isPayloadOfSchemaType<ChainIndexingServiceState<T>>(ChainIndexingServiceStateSchema)(payload)
+}
+export const asChainIndexingServiceState = AsObjectFactory.create<ChainIndexingServiceState<JsonValue>>(isChainIndexingServiceState)
+
+export const isChainIndexingServiceStateWithStorageMeta
+  = <T extends JsonValue = JsonValue>(value: unknown): value is WithStorageMeta<ChainIndexingServiceState<T>> =>
+    isChainIndexingServiceState<T>(value) && isStorageMeta(value)
+
+export const asChainIndexingServiceStateWithStorageMeta
+  = AsObjectFactory.create<WithStorageMeta<ChainIndexingServiceState>>(isChainIndexingServiceStateWithStorageMeta)

package/src/services/StakeIntentService/StakeIntentService.ts

@@ -0,0 +1,36 @@
+import type { Address } from '@xylabs/hex'
+import type { Intent } from '@xyo-network/xl1-protocol'
+
+import type { ServiceInterface } from '../Service.ts'
+
+export interface StakeIntentService extends ServiceInterface {
+
+  /**
+   * Gets the declared ranges for an address based on historical on-chain data
+   * @param address The address to get the declared ranges for
+   * @param intent The declared intent to filter for
+   */
+  getDeclaredCandidateRanges(address: Address, intent: Intent): Promise<Readonly<Readonly<[number, number]>[]>>
+
+  /**
+   * Gets the declared candidates for a block based on historical on-chain data
+   * @param block The block number to get the declared candidates for
+   * @param intent The declared intent to filter for
+   */
+  getDeclaredCandidatesForBlock(block: number, intent: Intent): Promise<Address[]>
+
+  /**
+   * Gets the required minimum stake for a given intent
+   * @param intent The declared intent to filter for
+   * @returns The required minimum stake for the intent
+   */
+  getRequiredMinimumStakeForIntent(intent: Intent): bigint
+
+  /**
+   * Checks if the address is staked for a block for a given intent
+   * @param block The block number to check
+   * @param intent The declared intent to filter for
+   * @param address The address to check
+   */
+  isStakedForBlock(block: number, intent: Intent, address: Address): Promise<boolean>
+}

package/src/services/StakeIntentService/index.ts

@@ -0,0 +1,2 @@
+export * from './ChainIndexingServiceStateSchema.ts'
+export * from './StakeIntentService.ts'

package/src/services/StepStakeService.ts

@@ -0,0 +1,4 @@
+import type { StepStakeViewInterface } from '../interfaces/index.ts'
+import type { ServiceInterface } from './Service.ts'
+
+export interface StepStakeService extends ServiceInterface, StepStakeViewInterface {}

package/src/services/TimeSyncService.ts

@@ -0,0 +1,6 @@
+import type { TimeSyncViewInterface, TimeSyncViewInterfaceV2 } from '../interfaces/index.ts'
+import type { ServiceInterface } from './Service.ts'
+
+export interface TimeSyncService extends ServiceInterface, TimeSyncViewInterface {}
+
+export interface TimeSyncServiceV2 extends ServiceInterface, TimeSyncViewInterfaceV2 {}

package/src/services/index.ts

@@ -0,0 +1,14 @@
+export * from './AccountBalanceService.ts'
+export * from './AccountTransfersService.ts'
+export * from './BlockProducerService.ts'
+export * from './BlockRewardService.ts'
+export * from './BlockRewardServiceV2.ts'
+export * from './Chain/index.ts'
+export * from './ChainIterator/index.ts'
+export * from './Election.ts'
+export * from './NetworkStakeService.ts'
+export * from './PendingTransactionsService.ts'
+export * from './Service.ts'
+export * from './StakeIntentService/index.ts'
+export * from './StepStakeService.ts'
+export * from './TimeSyncService.ts'

package/src/transaction/confirmSubmittedTransaction.ts

@@ -3,9 +3,9 @@ import type { Logger } from '@xylabs/logger'
 import { isDefined } from '@xylabs/typeof'
 import type { Signed } from '@xyo-network/boundwitness-model'
 import { PayloadBuilder } from '@xyo-network/payload-builder'
-import type {
-  SignedHydratedTransaction, TransactionBoundWitness, XyoViewer,
-} from '@xyo-network/xl1-protocol'
+import type { SignedHydratedTransaction, TransactionBoundWitness } from '@xyo-network/xl1-protocol'
+
+import type { XyoViewer } from '../provider/index.ts'
 
 const DEFAULT_CONFIRMATION_ATTEMPTS = 20
 const DEFAULT_DELAY_BETWEEN_ATTEMPTS = 1000 // milliseconds

package/src/validation/block/BlockValidationFunction.ts

@@ -0,0 +1,9 @@
+import type { Promisable } from '@xylabs/promise'
+import type { BlockBoundWitness, ChainId } from '@xyo-network/xl1-protocol'
+
+import type { BlockValidationError } from './error.ts'
+
+export type BlockValidatorFunction = (
+  block: BlockBoundWitness,
+  chainId?: ChainId,
+) => Promisable<BlockValidationError[]>

package/src/validation/block/HydratedBlockStateValidationFunction.ts

@@ -0,0 +1,24 @@
+import type { Promisable } from '@xylabs/promise'
+import type { ChainId, HydratedBlock } from '@xyo-network/xl1-protocol'
+
+import type { AccountBalanceService, AccountBalanceServiceV2 } from '../../services/index.ts'
+import type { HydratedBlockStateValidationError } from './error.ts'
+
+/**
+ * A function that validates a hydrated block against chain state.
+ * @param hydratedBlock The hydrated block to validate.
+ * @param chainId The chain ID to use for validation.
+ * @param archivist The archivist to use for validation.
+ * @returns An array of errors if the block is invalid, or an empty array if it is valid.
+ */
+export type HydratedBlockStateValidationFunction = (
+  hydratedBlock: HydratedBlock,
+  chainId: ChainId,
+  services: { accountBalance: AccountBalanceService },
+) => Promisable<HydratedBlockStateValidationError[]>
+
+export type HydratedBlockStateValidationFunctionV2 = (
+  hydratedBlock: HydratedBlock,
+  chainId: ChainId,
+  services: { accountBalance: AccountBalanceServiceV2 },
+) => Promisable<HydratedBlockStateValidationError[]>

package/src/validation/block/HydratedBlockValidationFunction.ts

@@ -0,0 +1,15 @@
+import type { Promisable } from '@xylabs/promise'
+import type { ChainId, HydratedBlock } from '@xyo-network/xl1-protocol'
+
+import type { HydratedBlockValidationError } from './error.ts'
+
+/**
+ * A function that validates a hydrated block.
+ * @param hydratedBlock The hydrated block to validate.
+ * @param chainId The chain ID to use for validation.
+ * @returns An array of errors if the block is invalid, or an empty array if it is valid.
+ */
+export type HydratedBlockValidationFunction = (
+  hydratedBlock: HydratedBlock,
+  chainId?: ChainId,
+) => Promisable<HydratedBlockValidationError[]>

package/src/validation/block/error.spec.ts

@@ -0,0 +1,20 @@
+import type { Address, Hash } from '@xylabs/hex'
+import type { HydratedBlock } from '@xyo-network/xl1-protocol'
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { HydratedBlockStateValidationError } from './error.ts'
+
+describe('HydratedBlockStateValidationError', () => {
+  it('should be able display chainId', () => {
+    const error: HydratedBlockStateValidationError = new HydratedBlockStateValidationError(
+      '2234567890abcdef1234567890abcdef12345678' as Hash, // Mock Hash
+      '1234567890abcdef1234567890abcdef12345678' as Address, // Mock Address
+      {} as HydratedBlock, // Mock HydratedBlock
+      'Test Error',
+      [new Error('Inner error')],
+    )
+    expect(error).toBeDefined()
+  })
+})