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

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,55 @@ 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)
+    return await factory.getInstance(resolvedParams)
+  }
+
   /**
-   * 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 +95,7 @@ export class ProviderFactoryLocator implements ProviderFactoryLocatorInstance {
         registry[moniker] = locator.registry[moniker]
       }
     }
-    return new ProviderFactoryLocator(registry)
+    return new ProviderFactoryLocator(this.context, registry)
   }
 
   /**
@@ -86,17 +120,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/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/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/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/index.ts

@@ -0,0 +1,2 @@
+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}`)
+}

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

@@ -0,0 +1,45 @@
+import { assertEx, isDefined } from '@xylabs/sdk-js'
+import type {
+  AttoXL1, StepIdentity, XL1BlockRange, XL1RangeMultipliers,
+} from '@xyo-network/xl1-protocol'
+import {
+  asAttoXL1, asXL1BlockRange, isTransfer,
+  XYO_STEP_REWARD_ADDRESS,
+} from '@xyo-network/xl1-protocol'
+
+import { type ChainContextRead, withContextCacheResponse } from '../../../model/index.ts'
+import { netTransfersForPayloads } from '../../../payloads/index.ts'
+import { stepBlockRange, stepTransferIndex } from '../../step/index.ts'
+import { stepRewardBlock } from './stepRewardBlock.ts'
+
+function stepInRange(step: StepIdentity, range: XL1BlockRange): boolean {
+  const stepRange = stepBlockRange(step)
+  return ((stepRange[0] >= range[0]) && (stepRange[1] <= range[1]))
+}
+
+export async function stepRewardTotal(context: ChainContextRead, { block, step }: StepIdentity, multipliers: XL1RangeMultipliers): Promise<AttoXL1> {
+  const cacheKey = `${block}|${step}|${isDefined(multipliers)}`
+  return await withContextCacheResponse(context, 'stepRewardTotal', cacheKey, async () => {
+    const [blockBw, payloads] = await stepRewardBlock(context, { block, step })
+    assertEx(blockBw.block === block, () => `Block Mismatch: expected ${block}, got ${blockBw.block}`)
+    const [transferIndex] = stepTransferIndex(block, step)
+    const stepTransfer = assertEx(
+      payloads.find(p => isTransfer(p) && p.from === XYO_STEP_REWARD_ADDRESS),
+      () => `No step transfer found for step ${step} at block ${block} (${blockBw._hash})`,
+    )
+    const rewards = assertEx(
+      netTransfersForPayloads([stepTransfer])[XYO_STEP_REWARD_ADDRESS],
+      () => `No rewards found for step reward address ${XYO_STEP_REWARD_ADDRESS} at block ${block} (${blockBw._hash})`,
+    )
+    const sortedTransfers = (Object.entries(rewards)).toSorted(([,a], [,b]) => a > b ? -1 : a < b ? 1 : 0)
+    let result = asAttoXL1(sortedTransfers[transferIndex][1] * -1n)
+    for (const [rangeKey, [numerator, denominator]] of Object.entries(multipliers)) {
+      const rangeParts = rangeKey.split('|').map(Number)
+      const range: XL1BlockRange = asXL1BlockRange([rangeParts[0], rangeParts[1]], { name: 'stepRewardTotal' })
+      if (stepInRange({ block, step }, range)) {
+        result = asAttoXL1(result + result * numerator / denominator)
+      }
+    }
+    return result
+  })
+}

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

@@ -0,0 +1,34 @@
+import type {
+  AttoXL1, StepIdentity, XL1BlockRange,
+  XL1RangeMultipliers,
+} from '@xyo-network/xl1-protocol'
+import { asAttoXL1, asXL1BlockRange } from '@xyo-network/xl1-protocol'
+
+import { XL1_NETWORK_STAKING_GENESIS_PERIOD_END_XL1_BLOCK } from '../../../constants.ts'
+import type { ChainContextRead } from '../../../model/index.ts'
+import { blockRangeSteps } from '../../block/index.ts'
+import { stepRewardTotal } from './stepRewardTotal.ts'
+
+export async function stepsRewardTotalGenesisPeriod(context: ChainContextRead, multipliers: XL1RangeMultipliers, stepSizes?: number[]): Promise<AttoXL1> {
+  const range = asXL1BlockRange([0, XL1_NETWORK_STAKING_GENESIS_PERIOD_END_XL1_BLOCK], { name: 'stepsRewardTotalGenesisPeriod' })
+  return await stepsRewardTotalRange(context, range, stepSizes, multipliers)
+}
+
+export async function stepsRewardTotalRange(
+  context: ChainContextRead,
+  range: XL1BlockRange,
+  stepSizes: number[] = [3, 4, 5, 6],
+  multipliers: XL1RangeMultipliers,
+): Promise<AttoXL1> {
+  const steps = blockRangeSteps(range, stepSizes)
+  return await stepsRewardTotal(context, steps, multipliers)
+}
+
+export async function stepsRewardTotal(context: ChainContextRead, steps: StepIdentity[], multipliers: XL1RangeMultipliers): Promise<AttoXL1> {
+  let totalRewards = 0n
+  for (const step of steps) {
+    const stepTotal = await stepRewardTotal(context, step, multipliers)
+    totalRewards += stepTotal
+  }
+  return asAttoXL1(totalRewards)
+}

package/src/primitives/chain/time/externalBlockNumberFromXL1BlockNumber.ts

@@ -0,0 +1,31 @@
+import { assertEx, isArray } from '@xylabs/sdk-js'
+import type { BlockNumber, XL1BlockNumber } from '@xyo-network/xl1-protocol'
+import {
+  asBlockNumber, asTimePayload, isTimePayload,
+} from '@xyo-network/xl1-protocol'
+
+import { type BaseContext, withContextCacheResponse } from '../../../model/index.ts'
+import type { BlockViewer } from '../../../viewers/index.ts'
+
+const functionName = 'externalBlockNumberFromXL1BlockNumber' as const
+
+export async function externalBlockNumberFromXL1BlockNumber(
+  context: BaseContext,
+  blockViewer: BlockViewer,
+  xl1BlockNumber: XL1BlockNumber,
+  externalTimeName: 'ethereum' | 'epoch',
+  externalGenesisTime?: BlockNumber,
+  timeBudgetMs = 2000,
+): Promise<BlockNumber> {
+  const cacheKey = `${xl1BlockNumber}-${externalTimeName}-${externalGenesisTime ?? 'default'}`
+  return await withContextCacheResponse(context, functionName, cacheKey, async () => {
+    const [, payloads = []] = await blockViewer.blockByNumber(xl1BlockNumber) ?? []
+    assertEx(isArray(payloads))
+    const timePayload = asTimePayload(payloads.find(isTimePayload))
+    // the default here is the block number we know where the xl1 chain started running (first external staking - 1)
+    return asBlockNumber(
+      timePayload?.[externalTimeName] ?? externalGenesisTime ?? 23_372_716,
+      { name: functionName },
+    ) // default is xl1 mainnet genesis time
+  }, { timeBudgetMs })
+}

package/src/primitives/chain/time/externalBlockRangeFromStep.ts

@@ -0,0 +1,19 @@
+import type { BlockRange, StepIdentity } from '@xyo-network/xl1-protocol'
+
+import { toStepIdentityString } from '../../../block/index.ts'
+import { type BaseContext, withContextCacheResponse } from '../../../model/index.ts'
+import type { BlockViewer } from '../../../viewers/index.ts'
+import { stepBlockRange } from '../../step/index.ts'
+import { externalBlockRangeFromXL1BlockRange } from './externalBlockRangeFromXL1BlockRange.ts'
+
+export async function externalBlockRangeFromStep(
+  context: BaseContext,
+  blockViewer: BlockViewer,
+  stepIdentity: StepIdentity,
+): Promise<BlockRange> {
+  const cacheKey = toStepIdentityString(stepIdentity)
+  return await withContextCacheResponse(context, 'externalBlockRangeFromStep', cacheKey, async () => {
+    const xl1BlockRange = stepBlockRange(stepIdentity)
+    return await externalBlockRangeFromXL1BlockRange(context, blockViewer, xl1BlockRange)
+  }, { timeBudgetMs: 1000 })
+}