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

package/src/CreatableProvider/ProviderFactoryLocator.ts

@@ -1,8 +1,10 @@
 import { hasAllLabels, type Labels } from '@xylabs/sdk-js'
 import { assertEx } from '@xylabs/sdk-js'
 
-import type { ProviderMoniker } from '../model/index.ts'
-import type { CreatableProviderFactory } from './CreatableProvider.ts'
+import type { Provider, ProviderMoniker } from '../model/index.ts'
+import type {
+  CreatableProviderContext, CreatableProviderFactory, CreatableProviderInstance,
+} from './CreatableProvider.ts'
 import { type CreatableProviderRegistry, registerCreatableProviderFactory } from './CreatableProviderRegistry.ts'
 import { hasLabels, type LabeledCreatableProviderFactory } from './LabeledCreatableProviderFactory.ts'
 import type { ProviderFactoryLocatorInstance } from './ProviderFactoryLocatorInstance.ts'
@@ -11,12 +13,18 @@ import type { ProviderFactoryLocatorInstance } from './ProviderFactoryLocatorIns
  * A class which encapsulates the Service Locator Pattern for Provider Factories
  */
 export class ProviderFactoryLocator implements ProviderFactoryLocatorInstance {
+  protected readonly _context: CreatableProviderContext
   protected readonly _registry: CreatableProviderRegistry
 
   private _frozen = false
 
-  constructor(registry: CreatableProviderRegistry = {}) {
+  constructor(context: Omit<CreatableProviderContext, 'locator'>, registry: CreatableProviderRegistry = {}) {
     this._registry = registry
+    this._context = { ...context, locator: this }
+  }
+
+  get context() {
+    return this._context
   }
 
   /**
@@ -26,29 +34,56 @@ export class ProviderFactoryLocator implements ProviderFactoryLocatorInstance {
     return this._registry
   }
 
-  static empty() {
-    return new ProviderFactoryLocator({})
+  static empty(context: Omit<CreatableProviderContext, 'locator'>) {
+    return new ProviderFactoryLocator(context, {})
+  }
+
+  static standard(context: Omit<CreatableProviderContext, 'locator'>) {
+    return new ProviderFactoryLocator(context, {})
   }
 
-  static standard() {
-    return new ProviderFactoryLocator({})
+  /** @deprecated use getInstance instead */
+  async create<TProvider extends Provider<ProviderMoniker>>(
+    moniker: TProvider['moniker'],
+    params?: Partial<CreatableProviderInstance<TProvider>['params']>,
+    labels?: Labels,
+  ) {
+    return await this.getInstance<TProvider>(moniker, params, labels)
   }
 
   freeze() {
     this._frozen = true
   }
 
+  async getInstance<TProvider extends Provider<ProviderMoniker>>(
+    moniker: TProvider['moniker'],
+    params?: Partial<CreatableProviderInstance<TProvider>['params']>,
+    labels?: Labels,
+  ) {
+    const resolvedParams = {
+      ...params,
+      context: {
+        ...this.context,
+        ...params?.context,
+      } as CreatableProviderInstance<TProvider>['params']['context'],
+    } as CreatableProviderInstance<TProvider>['params']
+    const factory = this.locate<TProvider>(moniker, labels)
+    const result = await factory.getInstance(resolvedParams)
+    return result
+  }
+
   /**
-   * Locates a provider factory that matches the supplied schema and labels
-   * @param schema The config schema for the provider
+   * Locates a provider factory that matches the supplied moniker and labels
+   * @param moniker The config moniker for the provider
    * @param labels The labels for the provider factory
-   * @returns A provider factory that matches the supplied schema and labels or throws if one is not found
+   * @returns A provider factory that matches the supplied moniker and labels or throws if one is not found
    */
-  locate(moniker: ProviderMoniker, labels?: Labels): CreatableProviderFactory | LabeledCreatableProviderFactory {
+  locate<TProvider extends Provider<ProviderMoniker>>(moniker: TProvider['moniker'], labels?: Labels):
+    CreatableProviderFactory<CreatableProviderInstance<TProvider>> | LabeledCreatableProviderFactory<CreatableProviderInstance<TProvider>> {
     return assertEx(
-      this.tryLocate(moniker, labels),
+      this.tryLocate<TProvider>(moniker, labels),
 
-      () => `No module factory for the supplied config schema [${moniker}]${labels ? ` & labels [${JSON.stringify(labels)}]` : ''} registered`,
+      () => `No module factory for the supplied config moniker [${moniker}]${labels ? ` & labels [${JSON.stringify(labels)}]` : ''} registered`,
     )
   }
 
@@ -61,7 +96,7 @@ export class ProviderFactoryLocator implements ProviderFactoryLocatorInstance {
         registry[moniker] = locator.registry[moniker]
       }
     }
-    return new ProviderFactoryLocator(registry)
+    return new ProviderFactoryLocator(this.context, registry)
   }
 
   /**
@@ -86,17 +121,42 @@ export class ProviderFactoryLocator implements ProviderFactoryLocatorInstance {
     return this
   }
 
+  async tryGetInstance<TProvider extends Provider<ProviderMoniker>>(
+    moniker: TProvider['moniker'],
+    params?: Partial<CreatableProviderInstance<TProvider>['params']>,
+    labels?: Labels,
+  ) {
+    try {
+      return await this.getInstance<TProvider>(moniker, params, labels)
+    } catch {
+      return
+    }
+  }
+
   /**
-   * Tries to locate a module factory that matches the supplied schema and labels
-   * @param schema The config schema for the module
+   * Tries to locate a module factory that matches the supplied moniker and labels
+   * @param moniker The config moniker for the module
    * @param labels The labels for the module factory
-   * @returns A module factory that matches the supplied schema and labels or undefined
+   * @returns A module factory that matches the supplied moniker and labels or undefined
    */
-  tryLocate(moniker: ProviderMoniker, labels?: Labels): CreatableProviderFactory | LabeledCreatableProviderFactory | undefined {
-    return labels
+  tryLocate<TProvider extends Provider<ProviderMoniker>>(moniker: TProvider['moniker'], labels?: Labels) {
+    const result = labels
       // Find the first factory that has labels and has all the labels provided
       ? (this._registry[moniker]?.filter(hasLabels).find(factory => hasAllLabels(factory?.labels, labels)) ?? this._registry[moniker]?.[0])
       // Otherwise, return the first factory
       : this._registry[moniker]?.[0]
+
+    if (result) {
+      result.defaultParams = {
+        ...result?.defaultParams,
+        context: {
+          ...this.context,
+          ...result?.defaultParams?.context,
+        },
+      }
+    }
+
+    return result as CreatableProviderFactory<CreatableProviderInstance<TProvider>>
+      | LabeledCreatableProviderFactory<CreatableProviderInstance<TProvider>> | undefined
   }
 }

package/src/CreatableProvider/ProviderFactoryLocatorInstance.ts

@@ -1,7 +1,7 @@
 import type { Labels } from '@xylabs/sdk-js'
 
-import type { ProviderMoniker } from '../model/index.ts'
-import type { CreatableProviderFactory } from './CreatableProvider.ts'
+import type { Provider, ProviderMoniker } from '../model/index.ts'
+import type { CreatableProviderFactory, CreatableProviderInstance } from './CreatableProvider.ts'
 import type { CreatableProviderRegistry } from './CreatableProviderRegistry.ts'
 import type { LabeledCreatableProviderFactory } from './LabeledCreatableProviderFactory.ts'
 
@@ -12,15 +12,31 @@ export interface ProviderFactoryLocatorInstance {
    */
   registry: Readonly<CreatableProviderRegistry>
 
+  /** @deprecated use getInstance instead */
+  create<TProvider extends Provider<ProviderMoniker>,
+    TParams extends CreatableProviderInstance<TProvider>['params'] = CreatableProviderInstance<TProvider>['params']>(
+    moniker: TProvider['moniker'],
+    params?: TParams,
+    labels?: Labels,
+  ): Promise<CreatableProviderInstance<TProvider>>
+
   freeze(): void
 
+  getInstance<TProvider extends Provider<ProviderMoniker>,
+    TParams extends CreatableProviderInstance<TProvider>['params'] = CreatableProviderInstance<TProvider>['params']>(
+    moniker: TProvider['moniker'],
+    params?: Partial<TParams>,
+    labels?: Labels,
+  ): Promise<CreatableProviderInstance<TProvider>>
+
   /**
-   * Locates a module factory that matches the supplied schema and labels
-   * @param schema The config schema for the module
+   * Locates a module factory that matches the supplied moniker and labels
+   * @param moniker The config moniker for the module
    * @param labels The labels for the module factory
-   * @returns A module factory that matches the supplied schema and labels or throws if one is not found
+   * @returns A module factory that matches the supplied moniker and labels or throws if one is not found
    */
-  locate(schema: string, labels?: Labels): CreatableProviderFactory | LabeledCreatableProviderFactory
+  locate<TProvider extends Provider<ProviderMoniker>>(moniker: ProviderMoniker, labels?: Labels):
+    CreatableProviderFactory<CreatableProviderInstance<TProvider>> | LabeledCreatableProviderFactory<CreatableProviderInstance<TProvider>> | undefined
 
   merge(locator: ProviderFactoryLocatorInstance): ProviderFactoryLocatorInstance
 
@@ -37,11 +53,18 @@ export interface ProviderFactoryLocatorInstance {
    */
   registerMany(factories: CreatableProviderFactory[]): ProviderFactoryLocatorInstance
 
+  tryGetInstance<TProvider extends Provider<ProviderMoniker>,
+    TParams extends CreatableProviderInstance<TProvider>['params'] = CreatableProviderInstance<TProvider>['params']>(
+    moniker: TProvider['moniker'],
+    params?: Partial<TParams>,
+    labels?: Labels,
+  ): Promise<CreatableProviderInstance<TProvider> | undefined>
+
   /**
-   * Tries to locate a module factory that matches the supplied schema and labels
-   * @param schema The config schema for the module
+   * Tries to locate a module factory that matches the supplied moniker and labels
+   * @param moniker The config moniker for the module
    * @param labels The labels for the module factory
-   * @returns A module factory that matches the supplied schema and labels or undefined
+   * @returns A module factory that matches the supplied moniker and labels or undefined
    */
-  tryLocate(schema: string, labels?: Labels): CreatableProviderFactory | LabeledCreatableProviderFactory | undefined
+  tryLocate(moniker: ProviderMoniker, labels?: Labels): CreatableProviderFactory | LabeledCreatableProviderFactory | undefined
 }

package/src/config/Bridge.ts

@@ -9,11 +9,12 @@ import * as z from 'zod'
 import { MnemonicStringZod } from '../validation/index.ts'
 
 const DEFAULT_FIXED_FEE = toHex(XL1(1n) * AttoXL1ConvertFactor.xl1)
-const DEFAULT_MIN_BRIDGE_AMOUNT = toHex(XL1(10n) * AttoXL1ConvertFactor.xl1)
-const DEFAULT_MAX_BRIDGE_AMOUNT = toHex(XL1(100_000n) * AttoXL1ConvertFactor.xl1)
+const DEFAULT_HARDHAT_BRIDGE_CONTRACT = toAddress('2279B7A0a67DB372996a5FaB50D91eAA73d2eBe6')
 const DEFAULT_HARDHAT_CHAIN_ID: ChainId = toHex('7A69')
+const DEFAULT_HARDHAT_REMOTE_CHAIN_WALLET_PRIVATE_KEY = toHex('0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80')
 const DEFAULT_HARDHAT_TOKEN_CONTRACT = toAddress('5FbDB2315678afecb367f032d93F642f64180aa3')
-const DEFAULT_HARDHAT_BRIDGE_CONTRACT = toAddress('2279B7A0a67DB372996a5FaB50D91eAA73d2eBe6')
+const DEFAULT_MAX_BRIDGE_AMOUNT = toHex(XL1(100_000n) * AttoXL1ConvertFactor.xl1)
+const DEFAULT_MIN_BRIDGE_AMOUNT = toHex(XL1(10n) * AttoXL1ConvertFactor.xl1)
 
 export const BasisPointsZod = z.coerce.number().int().nonnegative().max(10_000)
 export type BasisPoints = z.infer<typeof BasisPointsZod>
@@ -70,12 +71,24 @@ export const BridgeConfigZod = z.object({
     title: 'bridge.mnemonic',
     type: 'string',
   }),
-  port: z.coerce.number().default(8081).register(globalRegistry, {
+  port: z.coerce.number().int().positive().default(8081).register(globalRegistry, {
     default: 8081,
     description: 'Port for the Bridge',
     title: 'bridge.port',
     type: 'number',
   }),
+  redisHost: z.string().default('localhost').register(globalRegistry, {
+    default: 'localhost',
+    description: 'Host for the Bridge Redis instance',
+    title: 'bridge.redisHost',
+    type: 'string',
+  }),
+  redisPort: z.coerce.number().int().positive().default(6379).register(globalRegistry, {
+    default: 6379,
+    description: 'Port for the Bridge Redis instance',
+    title: 'bridge.redisPort',
+    type: 'number',
+  }),
   remoteBridgeContractAddress: AddressZod.default(DEFAULT_HARDHAT_BRIDGE_CONTRACT).register(globalRegistry, {
     default: DEFAULT_HARDHAT_BRIDGE_CONTRACT,
     description: 'Hex representation of remote token address used for bridging',
@@ -94,6 +107,11 @@ export const BridgeConfigZod = z.object({
     title: 'bridge.remoteTokenAddress',
     type: 'string',
   }),
+  remoteChainWalletPrivateKey: HexZod.default(DEFAULT_HARDHAT_REMOTE_CHAIN_WALLET_PRIVATE_KEY).register(globalRegistry, {
+    description: 'Private key for the wallet to use for the remote chain wallet',
+    title: 'bridge.remoteChainWalletPrivateKey',
+    type: 'string',
+  }),
   xl1ChainId: HexZod.optional().register(globalRegistry, {
     description: 'XL1 chain id used for bridging',
     title: 'bridge.xl1ChainId',

package/src/config/Chain.ts

@@ -1,9 +1,9 @@
-import { AddressZod } from '@xylabs/sdk-js'
+import { AddressZod, HexZod } from '@xylabs/sdk-js'
 import { globalRegistry } from 'zod'
 import * as z from 'zod'
 
 export const ChainConfigZod = z.object({
-  id: z.string().optional()
+  id: HexZod.optional()
     .register(globalRegistry, {
       description:
       'The unique identifier for the chain. Should be the staking contract address for contract-backed chains.',

package/src/config/Services.ts

@@ -2,12 +2,14 @@ import { globalRegistry } from 'zod'
 import * as z from 'zod'
 
 export const ServicesConfigZod = z.object({
-  accountBalanceViewerEndpoint: z.string().optional().register(globalRegistry, {
+  accountBalanceViewerEndpoint: z.string().default('http://localhost:8080/rpc').register(globalRegistry, {
+    default: 'http://localhost:8080/rpc',
     description: 'Endpoint of the API to use for instantiating an external AccountBalanceViewer',
     title: 'services.accountBalanceViewerEndpoint',
     type: 'string',
   }),
-  apiEndpoint: z.string().optional().register(globalRegistry, {
+  apiEndpoint: z.string().default('http://localhost:8080/rpc').register(globalRegistry, {
+    default: 'http://localhost:8080/rpc',
     description: 'Endpoint of the API to use for instantiating an external Viewers',
     title: 'services.apiEndpoint',
     type: 'string',

package/src/createDeclarationPayload.ts

@@ -0,0 +1,14 @@
+import type { Address } from '@xylabs/sdk-js'
+import { isDefined } from '@xylabs/sdk-js'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import {
+  type ChainStakeIntent, ChainStakeIntentSchema, type Intent,
+} from '@xyo-network/xl1-protocol'
+
+export const createDeclarationIntent = (address: Address, intent: Intent, nbf: number, exp?: number): ChainStakeIntent => {
+  const expiration = isDefined(exp) ? exp : nbf + 10_000
+  const redeclarationIntent = new PayloadBuilder<ChainStakeIntent>({ schema: ChainStakeIntentSchema }).fields({
+    from: address, intent, nbf, exp: expiration,
+  }).build()
+  return redeclarationIntent
+}

package/src/createTransferPayload.ts

@@ -0,0 +1,15 @@
+import type { Address, JsonObject } from '@xylabs/sdk-js'
+import { toHex } from '@xylabs/sdk-js'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import type { Transfer } from '@xyo-network/xl1-protocol'
+import { TransferSchema } from '@xyo-network/xl1-protocol'
+
+export function createTransferPayload(from: Address, transfers: Record<Address, bigint>, context?: JsonObject): Transfer {
+  return new PayloadBuilder<Transfer>({ schema: TransferSchema })
+    .fields({
+      epoch: Date.now(),
+      from,
+      transfers: Object.fromEntries(Object.entries(transfers).map(([k, v]) => [k, toHex(v)])),
+      context,
+    }).build()
+}

package/src/driver/cache/LruCacheMap.ts

@@ -1,8 +1,8 @@
 import { LRUCache } from 'lru-cache'
 
-import type { SynchronousMap } from '../../map/index.ts'
+import type { SyncMap } from '../../map/index.ts'
 
-export class LruCacheMap<K extends {}, V extends {} | string | number | bigint, FC = () => void> implements SynchronousMap<K, V> {
+export class LruCacheMap<K extends {}, V extends {} | string | number | bigint, FC = () => void> implements SyncMap<K, V> {
   private lruCache: LRUCache<K, V, FC>
 
   constructor(options?: LRUCache.Options<K, V, FC>) {

package/src/driver/memory/MemoryMap.ts

@@ -1,8 +1,8 @@
 import { isDefined } from '@xylabs/sdk-js'
 
-import type { SynchronousMap } from '../../map/index.ts'
+import type { SyncMap } from '../../map/index.ts'
 
-export class MemoryMap<K extends {}, V = {}> implements SynchronousMap<K, V> {
+export class MemoryMap<K extends {}, V = {}> implements SyncMap<K, V> {
   private map: Map<K, V>
 
   constructor() {

package/src/index.ts

@@ -3,6 +3,8 @@ export * from './ChainServiceCollectionV2.ts'
 export * from './config/index.ts'
 export * from './constants.ts'
 export * from './CreatableProvider/index.ts'
+export * from './createDeclarationPayload.ts'
+export * from './createTransferPayload.ts'
 export * from './driver/index.ts'
 export * from './eip-712/index.ts'
 export * from './instances/index.ts'
@@ -16,6 +18,7 @@ export * from './runners/index.ts'
 export * from './services/index.ts'
 export * from './SignedBigInt.ts'
 export * from './simple/index.ts'
+export * from './status/index.ts'
 export * from './summary/index.ts'
 export * from './time/index.ts'
 export * from './transaction/index.ts'

package/src/map/MapType.ts

@@ -5,11 +5,13 @@ import type {
   SyncIterableMap, SyncIterableMapRead, SyncIterableMapWrite, SyncMap, SyncMapRead, SyncMapWrite,
 } from './SyncMap.ts'
 
-export type MapTypeWrite<TId, TData> = SyncMapWrite<TId, TData> | AsyncMapWrite<TId, TData>
+export type MapType<TId, TData> = SyncMap<TId, TData> | AsyncMap<TId, TData>
 
 export type MapTypeRead<TId, TData> = SyncMapRead<TId, TData> | AsyncMapRead<TId, TData>
 
-export type MapType<TId, TData> = SyncMap<TId, TData> | AsyncMap<TId, TData>
+export type MapTypeWrite<TId, TData> = SyncMapWrite<TId, TData> | AsyncMapWrite<TId, TData>
+
+export type AsynchronousMapType<TId, TData> = AsyncMapRead<TId, TData> & AsyncMapWrite<TId, TData>
 
 export type IterableMapRead<TId, TData> = SyncIterableMapRead<TId, TData> | AsyncIterableMapRead<TId, TData>
 

package/src/model/ChainContext/ChainContext.ts

@@ -4,7 +4,6 @@ import { isDefined, isUndefined } from '@xylabs/sdk-js'
 import { LruCacheMap, MemoryMap } from '../../driver/index.ts'
 import type { MapType } from '../../map/index.ts'
 import { timeBudget } from '../../primitives/index.ts'
-import type { ChainIdentity } from '../ChainIdentity.ts'
 import type {
   ChainStakeContext, ChainStakeContextRead, ChainStakeContextWrite,
 } from './ChainStakeContext.ts'
@@ -16,6 +15,7 @@ import type {
 export interface BaseContext<TCacheValue = string | object | number | bigint> {
   caches?: Record<string, MapType<string, TCacheValue>>
   logger?: Logger
+  singletons: Record<string, unknown>
 }
 
 export function contextCache<TCacheValue>(
@@ -58,14 +58,14 @@ export async function withContextCacheResponse<T extends {} | string | number |
   return result
 }
 
-export interface ChainContextWrite extends BaseContext, ChainIdentity, ChainStateContextWrite, ChainStoreContextWrite {}
+export interface ChainContextWrite extends BaseContext, ChainStateContextWrite, ChainStoreContextWrite {}
 
 export interface StakedChainContextWrite extends BaseContext, ChainContextWrite, ChainStakeContextWrite {}
 
-export interface ChainContextRead extends BaseContext, ChainIdentity, ChainStateContextRead, ChainStoreContextRead {}
+export interface ChainContextRead extends BaseContext, ChainStateContextRead, ChainStoreContextRead {}
 
 export interface StakedChainContextRead extends BaseContext, ChainContextRead, ChainStakeContextRead {}
 
-export type ChainContext = ChainIdentity & ChainContextRead & ChainContextWrite & ChainStoreContext
+export type ChainContext = ChainContextRead & ChainContextWrite & ChainStoreContext
 
 export type StakedChainContext = ChainContext & ChainStakeContext & ChainStakeContextRead & ChainStakeContextWrite

package/src/model/ChainQualification.ts

@@ -0,0 +1,33 @@
+import { HashZod } from '@xylabs/hex'
+import { zodIsFactory } from '@xylabs/zod'
+import { XL1BlockRangeZod } from '@xyo-network/xl1-protocol'
+import z from 'zod'
+
+export const ChainQualificationZod = z.object({ head: HashZod, range: XL1BlockRangeZod })
+export type ChainQualification = z.infer<typeof ChainQualificationZod>
+export const isChainQualification = zodIsFactory(ChainQualificationZod)
+
+export const ChainQualifiedRangeConfigZod = z.object({ range: XL1BlockRangeZod })
+export type ChainQualifiedRangeConfig = z.infer<typeof ChainQualifiedRangeConfigZod>
+export const isChainQualifiedRangeConfig = zodIsFactory(ChainQualifiedRangeConfigZod)
+
+export const ChainQualifiedHeadConfigZod = z.object({ head: HashZod })
+export type ChainQualifiedHeadConfig = z.infer<typeof ChainQualifiedHeadConfigZod>
+export const isChainQualifiedHeadConfig = zodIsFactory(ChainQualifiedHeadConfigZod)
+
+export const ChainQualifiedConfigZod = z.union([ChainQualifiedRangeConfigZod, ChainQualifiedHeadConfigZod, z.object({})])
+export type ChainQualifiedConfig = z.infer<typeof ChainQualifiedConfigZod>
+export const isChainQualifiedConfig = zodIsFactory(ChainQualifiedConfigZod)
+
+export const ExtendChainQualifiedConfigZod = (<T>(zodType: z.ZodType<T>) => {
+  return z.union([
+    ChainQualifiedRangeConfigZod.extend(zodType),
+    ChainQualifiedHeadConfigZod.extend(zodType),
+    zodType,
+  ])
+}) as <T>(zodType: z.ZodType<T>) => z.ZodType<T & ChainQualifiedConfig>
+
+export type ChainQualified<T> = [T, ChainQualification]
+export const ChainQualifiedZod = <T>(zodType: z.ZodType<T>) => {
+  return z.tuple([zodType, ChainQualificationZod])
+}

package/src/model/PayloadBundle/bundledPayloadToHydratedTransaction.ts

@@ -1,10 +1,10 @@
 import { PayloadBuilder } from '@xyo-network/payload-builder'
-import type { PayloadBundle, WithHashMeta } from '@xyo-network/payload-model'
+import type { PayloadBundle } from '@xyo-network/payload-model'
 import type { SignedHydratedTransactionWithHashMeta } from '@xyo-network/xl1-protocol'
 import { asSignedTransactionBoundWitnessWithHashMeta } from '@xyo-network/xl1-protocol'
 
 export const bundledPayloadToHydratedTransaction = async (
-  payload: WithHashMeta<PayloadBundle>,
+  payload: PayloadBundle,
 ): Promise<SignedHydratedTransactionWithHashMeta | undefined> => {
   const withHashMeta = await PayloadBuilder.addHashMeta(payload.payloads)
   const tx = asSignedTransactionBoundWitnessWithHashMeta(withHashMeta.find(p => p._hash === payload.root))

package/src/model/index.ts

@@ -1,10 +1,10 @@
 export * from './ChainContext/index.ts'
 export * from './ChainFork/index.ts'
 export * from './ChainIdentity.ts'
+export * from './ChainQualification.ts'
 export * from './ChainStore.ts'
 export * from './PayloadBundle/index.ts'
 export * from './PayloadMap.ts'
 export * from './Position.ts'
 export * from './Provider.ts'
-export * from './Qualified.ts'
 export * from './RecordKeyType.ts'

package/src/primitives/block/index.ts

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

package/src/primitives/block/range/blockRangeSteps.ts

@@ -0,0 +1,22 @@
+import type {
+  StepIdentity,
+  XL1BlockRange,
+} from '@xyo-network/xl1-protocol'
+import { asXL1BlockNumber, StepSizes } from '@xyo-network/xl1-protocol'
+
+export function blockRangeSteps(range: XL1BlockRange, steps: number[]): StepIdentity[] {
+  const result: StepIdentity[] = []
+  for (const step of steps) {
+    const stepSize = StepSizes[step]
+    // we add stepSize twice to get to the start of the next full step
+    const startOfFirstStepCandidate = range[0] - (range[0] % stepSize) + stepSize
+    const startOfFirstStep = asXL1BlockNumber(
+      startOfFirstStepCandidate,
+      { name: 'blockRangeSteps' },
+    )
+    for (let block = startOfFirstStep; block <= range[1]; block = asXL1BlockNumber(block + stepSize, { name: 'blockRangeSteps' })) {
+      result.push({ step, block })
+    }
+  }
+  return result
+}

package/src/primitives/block/range/index.ts

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

package/src/primitives/chain/getWindowedChain.ts

@@ -0,0 +1,23 @@
+import type { Hash } from '@xylabs/sdk-js'
+import type { SignedHydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol'
+
+import type { BlockViewer } from '../../viewers/index.ts'
+
+export async function getWindowedChain(blockViewer: BlockViewer, maxWindowSize: number, previousChain: SignedHydratedBlockWithHashMeta[] = []) {
+  const newBlocks: SignedHydratedBlockWithHashMeta[] = []
+  let currentBlock: SignedHydratedBlockWithHashMeta | null = await blockViewer.currentBlock()
+  console.log('[getWindowedChain] Current Block:', currentBlock?.[0]._hash)
+  const head = currentBlock
+  while (currentBlock !== null && currentBlock[0].block >= head[0].block) {
+    newBlocks.unshift(currentBlock)
+    const previousBlockHash: Hash | null = currentBlock[0].previous
+    currentBlock = (previousBlockHash === null ? null : await blockViewer.blockByHash(previousBlockHash))
+  }
+  const newChain = [...previousChain, ...newBlocks].slice(-maxWindowSize)
+  while (newChain.length > 0 && newChain.length < maxWindowSize && newChain[0][0].previous !== null) {
+    const block = await blockViewer.blockByHash(newChain[0][0].previous!)
+    if (block === null) break
+    newChain.unshift(block)
+  }
+  return newChain
+}

package/src/primitives/chain/index.ts

@@ -0,0 +1,3 @@
+export * from './getWindowedChain.ts'
+export * from './step/index.ts'
+export * from './time/index.ts'

package/src/primitives/chain/step/chainStepRewardAddress.ts

@@ -0,0 +1,28 @@
+import type { Address } from '@xylabs/sdk-js'
+import {
+  assertEx, exists, toAddress,
+} from '@xylabs/sdk-js'
+import type { StepIdentity } from '@xyo-network/xl1-protocol'
+import {
+  asTransfer, isTransfer, XYO_STEP_REWARD_ADDRESS,
+} from '@xyo-network/xl1-protocol'
+
+import type { ChainContextRead } from '../../../model/index.ts'
+import { mergeTransfers } from '../../payload/index.ts'
+import { stepTransferIndex } from '../../step/index.ts'
+import { stepRewardBlock } from './stepRewardBlock.ts'
+
+export async function chainStepRewardAddress(context: ChainContextRead, { block, step }: StepIdentity): Promise<Address> {
+  const hydratedBlock = await stepRewardBlock(context, { block, step })
+  const [transferIndex, transferCount] = stepTransferIndex(block, step)
+  const [blockBw, payloads] = hydratedBlock
+
+  const transfersFromPool = payloads.filter(isTransfer).map(p => asTransfer(p)).filter(exists).filter(t => t.from === XYO_STEP_REWARD_ADDRESS)
+  const fromEntries = Object.entries(mergeTransfers(transfersFromPool)[XYO_STEP_REWARD_ADDRESS])
+  const sortedTransferAmounts = (fromEntries).toSorted(([,a], [,b]) => a > b ? -1 : a < b ? 1 : 0)
+  assertEx(
+    sortedTransferAmounts.length === transferCount,
+    () => `Step Transfers mismatch ${block} (${blockBw._hash}) [${sortedTransferAmounts.length} - ${transferCount}]`,
+  )
+  return toAddress(sortedTransferAmounts[transferIndex][0])
+}

package/src/primitives/chain/step/index.ts

@@ -0,0 +1,4 @@
+export * from './chainStepRewardAddress.ts'
+export * from './stepRewardBlock.ts'
+export * from './stepRewardTotal.ts'
+export * from './stepsRewardTotal.ts'

package/src/primitives/chain/step/stepRewardBlock.ts

@@ -0,0 +1,11 @@
+import { assertEx } from '@xylabs/sdk-js'
+import type { HydratedBlockWithHashMeta, StepIdentity } from '@xyo-network/xl1-protocol'
+import { StepSizes } from '@xyo-network/xl1-protocol'
+
+import type { ChainContextRead } from '../../../model/index.ts'
+import { hydratedBlockByNumber } from '../../state/index.ts'
+
+export async function stepRewardBlock(context: ChainContextRead, { block, step }: StepIdentity): Promise<HydratedBlockWithHashMeta> {
+  assertEx((block % StepSizes[step]) === 0, () => `Block must be the first block of the step [${StepSizes[step]}], got ${block}`)
+  return assertEx(await hydratedBlockByNumber(context, block), () => `Could not find block for block number ${block}`)
+}