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

package/src/block/primitives/frames/spec/calculateFramesFromRange.spec.ts

@@ -10,7 +10,7 @@ import { calculateFramesFromRange } from '../calculateFramesFromRange.ts'
 
 describe('calculateFramesFromRange', () => {
   it('handles range aligned with step size', () => {
-    const step = 1 // 105
+    const step = 1 // 31
     const range: XL1BlockRange = [XL1_BLOCK_NUMBER_ZERO, asXL1BlockNumber(stepSize(step) - 1)]
     const [fitted, remaining] = calculateFramesFromRange(range, step)
 

package/src/block/primitives/index.ts

@@ -3,4 +3,5 @@ export * from './frames/index.ts'
 export * from './hashFromBlockNumber.ts'
 export * from './model.ts'
 export * from './payloads/index.ts'
+export * from './toStepIdentityString.ts'
 export * from './transfers/index.ts'

package/src/block/primitives/toStepIdentityString.ts

@@ -0,0 +1,5 @@
+import type { StepIdentity, StepIdentityString } from '@xyo-network/xl1-protocol'
+
+export function toStepIdentityString({ block, step }: StepIdentity): StepIdentityString {
+  return `${block}|${step}` as StepIdentityString
+}

package/src/block/primitives/transfers/transfersStepSummaryFromRange.ts

@@ -16,15 +16,16 @@ import {
 import { hydrateBlock } from '../../hydrate/index.ts'
 import { deepCalculateFramesFromRange } from '../frames/index.ts'
 import { hashFromBlockNumber } from '../hashFromBlockNumber.ts'
+import { transfersSummaryKey } from './transfersSummary.ts'
 
 export async function transfersStepSummaryFromRange(
   context: TransfersStepSummaryContext,
   range: XL1BlockRange,
 ): Promise<WithStorageMeta<TransfersStepSummary>> {
-  // console.log(`transfersStepSummaryFromRange: head=${head}, range=${range[0]}-${range[1]}`)
+  // console.log(`transfersStepSummaryFromRange: head=${context.head}, range=${range[0]}-${range[1]}`)
   const frameHeadHash = await hashFromBlockNumber(context, range[1])
   const frameSize = range[1] - range[0] + 1
-  const head = await context.head()
+  const [headHash] = await context.head()
 
   let result: TransfersStepSummary | undefined = undefined
 
@@ -39,14 +40,16 @@ export async function transfersStepSummaryFromRange(
       }
     }
     result = {
-      schema: TransfersStepSummarySchema, hash: head, stepSize: -1, transfers,
+      schema: TransfersStepSummarySchema, hash: headHash, stepSize: -1, transfers,
     }
   } else {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const step = (StepSizes as any).indexOf(frameSize)
     assertEx(step !== -1, () => `Invalid step size: ${frameSize}. Must be one of ${StepSizes.join(', ')}`)
 
-    const summaryResult = await context.summaryMap.get(`${frameHeadHash}|${frameSize}`)
+    const key = transfersSummaryKey(frameHeadHash, frameSize)
+
+    const summaryResult = await context.summaryMap.get(key)
     if (isAnyPayload(summaryResult)) {
       result = summaryResult as WithStorageMeta<TransfersStepSummary>
     } else {
@@ -83,13 +86,13 @@ export async function transfersStepSummaryFromRange(
           schema: TransfersStepSummarySchema, hash: frameHeadHash, stepSize: frameSize, transfers,
         }
 
-        await context.summaryMap.set(`${frameHeadHash}|${frameSize}`, result)
+        await context.summaryMap.set(key, result)
       } finally {
         context.stepSemaphores[step].release()
       }
     }
   }
-  // console.log(`transfersStepSummaryFromRange-result: head=${head}, range=${range[0]}-${range[1]}: ${toSafeJsonString(result, 10)}`)
+  // console.log(`transfersStepSummaryFromRange-result: head=${context.head}, range=${range[0]}-${range[1]}: ${toSafeJsonString(result, 10)}`)
   const finalResult = await PayloadBuilder.addStorageMeta(result)
   return finalResult
 }

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

@@ -1,4 +1,4 @@
-import type { Address } from '@xylabs/hex'
+import type { Address, Hash } from '@xylabs/hex'
 import { asAddress } from '@xylabs/hex'
 import { spanRootAsync } from '@xylabs/telemetry'
 import { isDefined } from '@xylabs/typeof'
@@ -11,15 +11,15 @@ import { transfersStepSummaryFromRange } from './transfersStepSummaryFromRange.t
 
 // the summary of amount of rewards claimed from the step reward pool by addresses
 export async function transfersSummary(
-  context: TransfersStepSummaryContext,
+  transferContext: TransfersStepSummaryContext,
 ): Promise<Partial<Record<Address, Partial<Record<Address, bigint>>>>> {
   return await spanRootAsync('transferSummary', async () => {
-    const head = await context.head()
-    const headResult = await context.store.chainMap.get(head)
-    const headBoundWitness = asBlockBoundWitnessWithStorageMeta(headResult, () => `Head block not found for hash: ${context.head}`, { required: true })
-    const rangeStart = asXL1BlockNumber(isDefined(context.windowSize) ? Math.max(headBoundWitness.block - context.windowSize + 1, 0) : 0)
+    const [headHash] = await transferContext.head()
+    const headResult = await transferContext.store.chainMap.get(headHash)
+    const headBoundWitness = asBlockBoundWitnessWithStorageMeta(headResult, () => `Head block not found for hash: ${transferContext.head}`, { required: true })
+    const rangeStart = asXL1BlockNumber(isDefined(transferContext.windowSize) ? Math.max(headBoundWitness.block - transferContext.windowSize + 1, 0) : 0)
     const ranges = deepCalculateFramesFromRange([rangeStart, asXL1BlockNumber(headBoundWitness.block)])
-    const summaries = await Promise.all(ranges.map(range => transfersStepSummaryFromRange(context, range)))
+    const summaries = await Promise.all(ranges.map(range => transfersStepSummaryFromRange(transferContext, range)))
     const transfers: Partial<Record<Address, Partial<Record<Address, bigint>>>> = {}
     for (let summary of summaries) {
       for (const [from, toMap] of Object.entries(summary.transfers)) {
@@ -34,3 +34,7 @@ export async function transfersSummary(
     return transfers
   })
 }
+
+export function transfersSummaryKey(frameHeadHash: Hash, frameSize: number) {
+  return `${frameHeadHash}|${frameSize}`
+}

package/src/config/Config.ts

@@ -6,6 +6,7 @@ import { BridgeConfigZod } from './Bridge.ts'
 import { ChainConfigZod } from './Chain.ts'
 import { EvmConfigZod } from './Evm.ts'
 import { LogConfigZod } from './Log.ts'
+import { MempoolConfigZod } from './Mempool.ts'
 import { ProducerConfigZod } from './Producer.ts'
 import { RewardRedemptionApiConfigZod } from './RewardRedemptionApi.ts'
 import { StorageConfigZod } from './storage/index.ts'
@@ -21,6 +22,7 @@ export const ConfigZod = z.object({
   bridge: BridgeConfigZod.default(BridgeConfigZod.parse({})).describe('Configuration for the Bridge node'),
   chain: ChainConfigZod.default(ChainConfigZod.parse({})).describe('Configuration for the chain'),
   evm: EvmConfigZod.default(EvmConfigZod.parse({})).describe('Configuration for EVM-backed services'),
+  mempool: MempoolConfigZod.default(MempoolConfigZod.parse({})).describe('Configuration for the mempool'),
   producer: ProducerConfigZod.default(ProducerConfigZod.parse({})).describe('Configuration for the producer'),
   rewardRedemptionApi: RewardRedemptionApiConfigZod.default(RewardRedemptionApiConfigZod.parse({})).describe('Configuration for the rewards redemption API'),
   storage: StorageConfigZod.default(StorageConfigZod.parse({})).describe('Configuration for the storage'),

package/src/config/Mempool.ts

@@ -0,0 +1,42 @@
+import { globalRegistry } from 'zod'
+import * as z from 'zod'
+
+import { MnemonicStringZod } from '../validation/index.ts'
+
+export const MempoolConfigZod = z.object({
+  enabled: z.string().default('false').transform((val, ctx) => {
+    const normalized = val.toLowerCase().trim()
+    if (['true', '1', 'yes', 'on'].includes(normalized)) return true
+    if (['false', '0', 'no', 'off'].includes(normalized)) return false
+    ctx.addIssue({
+      code: 'invalid_type',
+      expected: 'boolean',
+      message: `Invalid boolean value: "${val}". Use true/false, 1/0, yes/no.`,
+    })
+    return z.NEVER
+  }).register(globalRegistry, {
+    default: 'false',
+    description: 'Enable the Mempool',
+    title: 'mempool.enabled',
+    type: 'boolean',
+  }),
+  host: z.string().default('localhost').register(globalRegistry, {
+    default: 'localhost',
+    description: 'Host for the Mempool',
+    title: 'mempool.host',
+    type: 'string',
+  }),
+  mnemonic: MnemonicStringZod.optional().register(globalRegistry, {
+    description: 'Mnemonic for the Mempool wallet',
+    title: 'mempool.mnemonic',
+    type: 'string',
+  }),
+  port: z.coerce.number().default(8083).register(globalRegistry, {
+    default: 8083,
+    description: 'Port for the Mempool',
+    title: 'mempool.port',
+    type: 'number',
+  }),
+})
+
+export type MempoolConfig = z.infer<typeof MempoolConfigZod>

package/src/driver/cache/LruCacheMap.ts

@@ -0,0 +1,42 @@
+import { LRUCache } from 'lru-cache'
+
+import type { SynchronousMap } from '../../map/index.ts'
+
+export class LruCacheMap<K extends {}, V extends {} | string | number | bigint, FC = () => void> implements SynchronousMap<K, V> {
+  private lruCache: LRUCache<K, V, FC>
+
+  constructor(options?: LRUCache.Options<K, V, FC>) {
+    this.lruCache = new LRUCache<K, V, FC>(options ?? { max: 5000 })
+  }
+
+  clear(): void {
+    this.lruCache.clear()
+  }
+
+  delete(id: K): boolean {
+    return this.lruCache.delete(id)
+  }
+
+  get(id: K): V | undefined {
+    return this.lruCache.get(id)
+  }
+
+  getMany(id: K[]): V[] {
+    const results: V[] = []
+    for (const key of id) {
+      const value = this.lruCache.get(key)
+      if (value !== undefined) {
+        results.push(value)
+      }
+    }
+    return results
+  }
+
+  has(id: K): boolean {
+    return this.lruCache.has(id)
+  }
+
+  set(id: K, data: V) {
+    this.lruCache.set(id, data)
+  }
+}

package/src/driver/cache/index.ts

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

package/src/driver/index.ts

@@ -0,0 +1,2 @@
+export * from './cache/index.ts'
+export * from './memory/index.ts'

package/src/driver/memory/MemoryMap.ts

@@ -0,0 +1,42 @@
+import { isDefined } from '@xylabs/typeof'
+
+import type { SynchronousMap } from '../../map/index.ts'
+
+export class MemoryMap<K extends {}, V = {}> implements SynchronousMap<K, V> {
+  private map: Map<K, V>
+
+  constructor() {
+    this.map = new Map<K, V>()
+  }
+
+  clear(): void {
+    this.map.clear()
+  }
+
+  delete(id: K): boolean {
+    return this.map.delete(id)
+  }
+
+  get(id: K): V | undefined {
+    return this.map.get(id)
+  }
+
+  getMany(ids: K[]): V[] {
+    const results: V[] = []
+    for (const id of ids) {
+      const data = this.map.get(id)
+      if (isDefined(data)) {
+        results.push(data)
+      }
+    }
+    return results
+  }
+
+  has(id: K): boolean {
+    return this.map.has(id)
+  }
+
+  set(id: K, data: V) {
+    this.map.set(id, data)
+  }
+}

package/src/driver/memory/index.ts

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

package/src/eip-712/Payloads/EIP712Data.ts

@@ -13,30 +13,11 @@ export const EIP712DataPayloadFieldsZod = z.object({
 })
 export type EIP712DataPayloadFields = z.infer<typeof EIP712DataPayloadFieldsZod>
 
-/**
- * @deprecated Use EIP712DataPayloadFields instead
- */
-export type EIP712PayloadFields = EIP712DataPayloadFields
-
 export const EIP712DataPayloadSchema = 'network.xyo.chains.ethereum.eip712.data' as const
 export type EIP712DataPayloadSchema = typeof EIP712DataPayloadSchema
 
-/**
- * @deprecated Use EIP712DataPayloadSchema instead
- */
-export const EIP712PayloadSchema = EIP712DataPayloadSchema
-/**
- * @deprecated Use EIP712DataPayloadSchema instead
- */
-export type EIP712PayloadSchema = typeof EIP712DataPayloadSchema
-
 export type EIP712DataPayload = Payload<EIP712DataPayloadFields, EIP712DataPayloadSchema>
 
-/**
- * @deprecated Use EIP712DataPayload instead
- */
-export type EIP712Payload = EIP712DataPayload
-
 export const isEIP712DataPayload = isPayloadOfZodType<EIP712DataPayload>(
   EIP712DataPayloadFieldsZod,
   EIP712DataPayloadSchema,

package/src/index.ts

@@ -1,16 +1,18 @@
 export * from './block/index.ts'
-export * from './ChainServiceCollection.ts'
 export * from './ChainServiceCollectionV2.ts'
 export * from './config/index.ts'
 export * from './constants.ts'
+export * from './driver/index.ts'
 export * from './eip-712/index.ts'
 export * from './instances/index.ts'
+export * from './interfaces/index.ts'
 export * from './map/index.ts'
 export * from './model/index.ts'
 export * from './multipliers.ts'
 export * from './payloads/index.ts'
 export * from './primitives/index.ts'
-export * from './primitives/index.ts'
+export * from './provider/index.ts'
+export * from './services/index.ts'
 export * from './SignedBigInt.ts'
 export * from './time/index.ts'
 export * from './transaction/index.ts'

package/src/instances/index.ts

@@ -6,7 +6,5 @@ export * from './Fees.ts'
 export * from './modifiers/index.ts'
 export * from './Object.ts'
 export * from './Payload.ts'
-export * from './ShiftedBigIntConfig.ts'
 export * from './Signature.ts'
 export * from './transaction/index.ts'
-export * from './XL1Amount.ts'

package/src/interfaces/index.ts

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

package/src/interfaces/viewers/AccountBalance.ts

@@ -0,0 +1,25 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { Signed } from '@xyo-network/boundwitness-model'
+import type { WithStorageMeta } from '@xyo-network/payload-model'
+import type {
+  AttoXL1,
+  BlockBoundWitness, TransactionBoundWitness, Transfer,
+  XL1BlockRange,
+} from '@xyo-network/xl1-protocol'
+
+export type AccountBalanceHistoryItem = [
+  WithStorageMeta<Signed<BlockBoundWitness>> /* block */,
+  WithStorageMeta<Signed<TransactionBoundWitness>> | null,
+  WithStorageMeta<Transfer>, /* the actual transfer payload */
+]
+
+export interface AccountBalancesViewInterface {
+  accountBalances(address: Address[]): Promisable<Partial<Record<Address, AttoXL1>>>
+  accountBalancesHistories(address: Address[]): Promisable<Partial<Record<Address, AccountBalanceHistoryItem[]>>>
+}
+
+export interface AccountBalanceViewInterface {
+  accountBalance(address: Address): Promisable<AttoXL1>
+  accountBalanceHistory(address: Address, range?: XL1BlockRange): Promisable<AccountBalanceHistoryItem[]>
+}

package/src/interfaces/viewers/Block.ts

@@ -0,0 +1,13 @@
+import type { Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { HydratedBlock } from '@xyo-network/xl1-protocol'
+
+export interface BlockViewInterface {
+  blockByHash(hash: Hash): Promisable<HydratedBlock | null>
+  blockByNumber(blockNumber: number): Promisable<HydratedBlock | null>
+  blocksByHash(hash: Hash, limit?: number): Promisable<HydratedBlock[]>
+
+  currentBlock(): Promisable<HydratedBlock>
+  currentBlockHash(): Promisable<Hash>
+  currentBlockNumber(): Promisable<number>
+}

package/src/interfaces/viewers/Chain.ts

@@ -0,0 +1,6 @@
+import type { Promisable } from '@xylabs/promise'
+import type { ChainId } from '@xyo-network/xl1-protocol'
+
+export interface ChainViewInterface {
+  chainId(): Promisable<ChainId>
+}

package/src/interfaces/viewers/ChainContract.ts

@@ -0,0 +1,10 @@
+import type { Address } from '@xylabs/hex'
+
+export interface ChainContractViewInterface {
+  forkedAtBlockNumber(): Promise<bigint>
+  forkedAtHash(): Promise<bigint>
+  forkedChainId(): Promise<Address>
+  minWithdrawalBlocks(): Promise<bigint>
+  rewardsContract(): Promise<string>
+  stakingTokenAddress(): Promise<string>
+}

package/src/interfaces/viewers/Fork.ts

@@ -0,0 +1,9 @@
+import type { Promisable } from '@xylabs/promise'
+import type { ChainId } from '@xyo-network/xl1-protocol'
+
+export type ForkHistory = Record<number, ChainId>
+
+export interface ForkViewer {
+  chainIdAtBlock(blockNumber: number): Promisable<ChainId | undefined>
+  forkHistory(): Promisable<ForkHistory>
+}

package/src/interfaces/viewers/NetworkStakeStepReward.ts

@@ -0,0 +1,69 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { StepIdentity, StepIdentityString } from '@xyo-network/xl1-protocol'
+
+export interface NetworkStakeStepAddressRewardViewInterface {
+  // the step rewards for a specific network stakers for all of history
+  networkStakeStepRewardAddressHistory(address: Address): Promisable<Record<Address, bigint>>
+
+  // the step rewards for a specific network stakers for a given step and block
+  networkStakeStepRewardAddressReward(context: StepIdentity, address: Address): Promisable<Record<Address, bigint>>
+
+  // the shares for a specific network staker for a given step and block
+  networkStakeStepRewardAddressShare(context: StepIdentity, address: Address): Promisable<[/* address shares */bigint, /* total shares */bigint]>
+
+  // estimate the current reward weight for a given address at a given step
+  networkStakeStepRewardWeightForAddress(context: StepIdentity, address: Address): Promisable<bigint>
+}
+
+export interface NetworkStakeStepPoolRewardViewInterface {
+
+  // all the step rewards for all the network stakers for a given step and block
+  networkStakeStepRewardPoolRewards(context: StepIdentity): Promisable<Record<Address, bigint>>
+
+  // all the shares for all the network stakers for a given step and block
+  networkStakeStepRewardPoolShares(context: StepIdentity): Promisable<Record<Address, bigint>>
+}
+
+export interface NetworkStakeStepRewardPositionViewInterface {
+  // estimate the current weight for a given position at a given step
+  networkStakeStepRewardPositionWeight(context: StepIdentity, position: number): Promisable<bigint>
+
+  // estimate the potential loss for removing a given position at a given step
+  networkStakeStepRewardPotentialPositionLoss(context: StepIdentity, position: number): Promisable<bigint>
+}
+
+export interface NetworkStakeStepRewardViewInterface extends
+  NetworkStakeStepPoolRewardViewInterface,
+  NetworkStakeStepAddressRewardViewInterface,
+  NetworkStakeStepRewardPositionViewInterface
+{
+  networkStakeStepRewardClaimedByAddress(address: Address): Promisable<bigint>
+
+  // the share & total rewards for a given position
+  networkStakeStepRewardForPosition(position: number, range: [number, number]): Promisable<[bigint, bigint]>
+
+  // estimate the total possible block rewards for a given step
+  networkStakeStepRewardForStep(context: StepIdentity): Promisable<bigint>
+
+  // the share & total rewards for a given step and block for a given position
+  networkStakeStepRewardForStepForPosition(context: StepIdentity, position: number): Promisable<[bigint, bigint]>
+
+  // the predictable random number for a given step and block
+  networkStakeStepRewardRandomizer(context: StepIdentity): Promisable<bigint>
+
+  // the total number of stakers for a given step and block
+  networkStakeStepRewardStakerCount(context: StepIdentity): Promisable<number>
+
+  networkStakeStepRewardUnclaimedByAddress(address: Address): Promisable<bigint>
+
+  // the share & total rewards for a given position for each step in range
+  networkStakeStepRewardsForPosition(position: number,
+    range: [number, number]): Promisable<Record<StepIdentityString, [bigint, bigint]>>
+
+  // the total rewards for a given range
+  networkStakeStepRewardsForRange(range: [number, number]): Promisable<bigint>
+
+  // the total rewards for a given range and step level
+  networkStakeStepRewardsForStepLevel(stepLevel: number, range: [number, number]): Promisable<bigint>
+}

package/src/interfaces/viewers/NetworkStakeViewer/NetworkStakeViewer.ts

@@ -0,0 +1,12 @@
+import type { Promisable } from '@xylabs/promise'
+
+import type { StepRewardsViewer } from './StepRewardsViewer.ts'
+
+export interface NetworkStakeViewerMethods {
+  /** @returns the active stake and the number of active validators [active, block] */
+  active(blockNumber?: number): Promisable<[bigint, number]>
+}
+
+export interface NetworkStakeViewer extends NetworkStakeViewerMethods {
+  stepRewards?: StepRewardsViewer
+}

package/src/interfaces/viewers/NetworkStakeViewer/RecordKeyType.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type RecordKeyType<T = keyof any> = T extends keyof any ? T : never

package/src/interfaces/viewers/NetworkStakeViewer/RewardsByIndexViewerMethodsTemplate.ts

@@ -0,0 +1,7 @@
+import type { AttoXL1 } from '@xyo-network/xl1-protocol'
+
+import type { RecordKeyType } from './RecordKeyType.ts'
+import type { RewardsViewerMethodsTemplate } from './RewardsViewerMethodsTemplate.ts'
+
+export interface RewardsByIndexViewerMethodsTemplate<TOptions, TResultIndex extends RecordKeyType>
+  extends RewardsViewerMethodsTemplate<TOptions, Record<TResultIndex, AttoXL1>> {}

package/src/interfaces/viewers/NetworkStakeViewer/RewardsByPositionViewer.ts

@@ -0,0 +1,7 @@
+import type { RewardsByIndexViewerMethodsTemplate } from './RewardsByIndexViewerMethodsTemplate.ts'
+import type { RewardsByPositionViewerOptions } from './RewardsViewerOptions.ts'
+
+// Note: Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.
+
+export interface RewardsByPositionViewerMethods extends RewardsByIndexViewerMethodsTemplate<RewardsByPositionViewerOptions, number> {}
+export interface RewardsByPositionViewer extends RewardsByPositionViewerMethods {}

package/src/interfaces/viewers/NetworkStakeViewer/RewardsByStakerViewer.ts

@@ -0,0 +1,9 @@
+import type { Address } from '@xylabs/hex'
+
+import type { RewardsByIndexViewerMethodsTemplate } from './RewardsByIndexViewerMethodsTemplate.ts'
+import type { RewardsByStakerViewerOptions } from './RewardsViewerOptions.ts'
+
+// Note: Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.
+
+export interface RewardsByStakerViewerMethods extends RewardsByIndexViewerMethodsTemplate<RewardsByStakerViewerOptions, Address> {}
+export interface RewardsByStakerViewer extends RewardsByStakerViewerMethods {}

package/src/interfaces/viewers/NetworkStakeViewer/RewardsByStepViewer.ts

@@ -0,0 +1,9 @@
+import type { StepIdentityString } from '@xyo-network/xl1-protocol'
+
+import type { RewardsByIndexViewerMethodsTemplate } from './RewardsByIndexViewerMethodsTemplate.ts'
+import type { RewardsByStepViewerOptions } from './RewardsViewerOptions.ts'
+
+// Note: Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.
+
+export interface RewardsByStepViewerMethods extends RewardsByIndexViewerMethodsTemplate<RewardsByStepViewerOptions, StepIdentityString> {}
+export interface RewardsByStepViewer extends RewardsByStepViewerMethods {}

package/src/interfaces/viewers/NetworkStakeViewer/RewardsTotalViewer.ts

@@ -0,0 +1,9 @@
+import type { AttoXL1 } from '@xyo-network/xl1-protocol'
+
+import type { RewardsViewerMethodsTemplate } from './RewardsViewerMethodsTemplate.ts'
+import type { RewardsRangeOptions } from './RewardsViewerOptions.ts'
+
+// Note: Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.
+
+export interface RewardsTotalViewerMethods extends RewardsViewerMethodsTemplate<RewardsRangeOptions, AttoXL1> {}
+export interface RewardsTotalViewer extends RewardsTotalViewerMethods {}

package/src/interfaces/viewers/NetworkStakeViewer/RewardsViewerMethodsTemplate.ts

@@ -0,0 +1,9 @@
+import type { Promisable } from '@xylabs/promise'
+
+export interface RewardsViewerMethodsTemplate<TOptions, TResult> {
+  bonus(options?: TOptions): Promisable<TResult>
+  claimed(options?: TOptions): Promisable<TResult>
+  earned(options?: TOptions): Promisable<TResult>
+  total(options?: TOptions): Promisable<TResult>
+  unclaimed(options?: TOptions): Promisable<TResult>
+}

package/src/interfaces/viewers/NetworkStakeViewer/RewardsViewerOptions.ts

@@ -0,0 +1,18 @@
+import type { Address } from '@xylabs/hex'
+import type { BlockRange, StepIdentity } from '@xyo-network/xl1-protocol'
+
+export interface RewardsRangeOptions {
+  range?: BlockRange
+}
+
+export interface RewardsByStepViewerOptions extends RewardsRangeOptions {
+  steps?: StepIdentity[]
+}
+
+export interface RewardsByStakerViewerOptions extends RewardsRangeOptions {
+  stakers?: Address[]
+}
+
+export interface RewardsByPositionViewerOptions extends RewardsRangeOptions {
+  positions?: number[]
+}

package/src/interfaces/viewers/NetworkStakeViewer/StepRewardsViewer.ts

@@ -0,0 +1,13 @@
+import type { RewardsByPositionViewer } from './RewardsByPositionViewer.ts'
+import type { RewardsByStakerViewer } from './RewardsByStakerViewer.ts'
+import type { RewardsByStepViewer } from './RewardsByStepViewer.ts'
+import type { RewardsTotalViewer } from './RewardsTotalViewer.ts'
+
+export interface StepRewardsViewerMethods {}
+
+export interface StepRewardsViewer extends StepRewardsViewerMethods {
+  position?: RewardsByPositionViewer
+  staker?: RewardsByStakerViewer
+  step?: RewardsByStepViewer
+  total?: RewardsTotalViewer
+}

package/src/interfaces/viewers/NetworkStakeViewer/StepViewer.ts

@@ -0,0 +1,42 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { PositionId, StepIdentity } from '@xyo-network/xl1-protocol'
+
+import type { Position } from '../Stake.ts'
+
+export interface PagedPositionsOptions {
+  cursor?: PositionId
+  limit?: number
+}
+
+export interface PagedStakersOptions {
+  cursor?: Address
+  limit?: number
+}
+
+export interface StepStatistics {
+  endTime: number
+  startTime: number
+}
+
+export interface StepViewerMethods {
+
+  // the total number of positions for a given step
+  positionCount(step: StepIdentity): Promisable<number>
+
+  positions(step: StepIdentity, options?: PagedPositionsOptions): Promisable<Position[]>
+
+  // the predictable random number for a given step
+  randomizer(step: StepIdentity): Promisable<bigint>
+
+  // total amount staked during a given step
+  stake(step: StepIdentity): Promisable<bigint>
+
+  // the total number of stakers for a given step
+  stakerCount(step: StepIdentity): Promisable<number>
+
+  stakers(step: StepIdentity, options?: PagedStakersOptions): Promisable<Address[]>
+
+  // total weight of all stakers during a given step
+  weight(step: StepIdentity): Promisable<bigint>
+}

package/src/interfaces/viewers/NetworkStakeViewer/index.ts

@@ -0,0 +1,13 @@
+export * from './NetworkStakeViewer.ts'
+export * from './RecordKeyType.ts'
+export * from './RewardsByIndexViewerMethodsTemplate.ts'
+export * from './RewardsByPositionViewer.ts'
+export * from './RewardsByStakerViewer.ts'
+export * from './RewardsByStepViewer.ts'
+export * from './RewardsTotalViewer.ts'
+export * from './RewardsViewerMethodsTemplate.ts'
+export * from './RewardsViewerOptions.ts'
+export * from './StepRewardsViewer.ts'
+export * from './StepViewer.ts'
+
+// Note: Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.