@xyo-network/xl1-protocol-lib 1.26.1

package/src/viewers/NetworkStake/NetworkStakeViewer.ts

@@ -0,0 +1,20 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type { Provider } from '@xyo-network/xl1-protocol-model'
+
+import type { NetworkStakeStepRewardsViewer } from './Rewards/index.ts'
+
+/** NetworkStakeViewerMethods interface. */
+export interface NetworkStakeViewerMethods {
+  /** @returns the active stake and the number of active validators [active, block] */
+  active(blockNumber?: number): Promisable<[bigint, number]>
+}
+
+/** Moniker identifier for the NetworkStakeViewer provider. */
+export const NetworkStakeViewerMoniker = 'NetworkStakeViewer' as const
+/** Type literal for the NetworkStakeViewer provider moniker. */
+export type NetworkStakeViewerMoniker = typeof NetworkStakeViewerMoniker
+
+/** Viewer interface for reading NetworkStake data. */
+export interface NetworkStakeViewer extends NetworkStakeViewerMethods, Provider<NetworkStakeViewerMoniker> {
+  stepRewards?: NetworkStakeStepRewardsViewer
+}

package/src/viewers/NetworkStake/Rewards/ByPositionViewer.ts

@@ -0,0 +1,19 @@
+import type { Provider } from '@xyo-network/xl1-protocol-model'
+
+import type { NetworkStakeStepRewardsByPositionViewerOptions } from './Options.ts'
+import type { NetworkStakeStepRewardsByIndexViewerMethodsTemplate } from './templates/index.ts'
+
+// Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.
+
+/** NetworkStakeStepRewardsByPositionViewerMethods interface. */
+export interface NetworkStakeStepRewardsByPositionViewerMethods extends
+  NetworkStakeStepRewardsByIndexViewerMethodsTemplate<NetworkStakeStepRewardsByPositionViewerOptions, number> {}
+
+/** Moniker identifier for the NetworkStakeStepRewardsByPositionViewer provider. */
+export const NetworkStakeStepRewardsByPositionViewerMoniker = 'NetworkStakeStepRewardsByPositionViewer' as const
+/** Type literal for the NetworkStakeStepRewardsByPositionViewer provider moniker. */
+export type NetworkStakeStepRewardsByPositionViewerMoniker = typeof NetworkStakeStepRewardsByPositionViewerMoniker
+
+/** Viewer interface for reading NetworkStakeStepRewardsByPosition data. */
+export interface NetworkStakeStepRewardsByPositionViewer extends NetworkStakeStepRewardsByPositionViewerMethods,
+  Provider<NetworkStakeStepRewardsByPositionViewerMoniker> {}

package/src/viewers/NetworkStake/Rewards/ByStakerViewer.ts

@@ -0,0 +1,20 @@
+import type { Address } from '@xylabs/sdk-js'
+import type { Provider } from '@xyo-network/xl1-protocol-model'
+
+import type { NetworkStakeStepRewardsByStakerViewerOptions } from './Options.ts'
+import type { NetworkStakeStepRewardsByIndexViewerMethodsTemplate } from './templates/index.ts'
+
+// Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.
+
+/** NetworkStakeStepRewardsByStakerViewerMethods interface. */
+export interface NetworkStakeStepRewardsByStakerViewerMethods
+  extends NetworkStakeStepRewardsByIndexViewerMethodsTemplate<NetworkStakeStepRewardsByStakerViewerOptions, Address> {}
+
+/** Moniker identifier for the NetworkStakeStepRewardsByStakerViewer provider. */
+export const NetworkStakeStepRewardsByStakerViewerMoniker = 'NetworkStakeStepRewardsByStakerViewer' as const
+/** Type literal for the NetworkStakeStepRewardsByStakerViewer provider moniker. */
+export type NetworkStakeStepRewardsByStakerViewerMoniker = typeof NetworkStakeStepRewardsByStakerViewerMoniker
+
+/** Viewer interface for reading NetworkStakeStepRewardsByStaker data. */
+export interface NetworkStakeStepRewardsByStakerViewer extends NetworkStakeStepRewardsByStakerViewerMethods,
+  Provider<NetworkStakeStepRewardsByStakerViewerMoniker> {}

package/src/viewers/NetworkStake/Rewards/ByStepViewer.ts

@@ -0,0 +1,18 @@
+import type { Provider, StepIdentityString } from '@xyo-network/xl1-protocol-model'
+
+import type { NetworkStakeStepRewardsByStepViewerOptions } from './Options.ts'
+import type { NetworkStakeStepRewardsByIndexViewerMethodsTemplate } from './templates/index.ts'
+
+// Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.
+
+/** NetworkStakeStepRewardsByStepViewerMethods interface. */
+export interface NetworkStakeStepRewardsByStepViewerMethods extends
+  NetworkStakeStepRewardsByIndexViewerMethodsTemplate<NetworkStakeStepRewardsByStepViewerOptions, StepIdentityString> {}
+
+/** Moniker identifier for the NetworkStakeStepRewardsByStepViewer provider. */
+export const NetworkStakeStepRewardsByStepViewerMoniker = 'NetworkStakeStepRewardsByStepViewer' as const
+/** Type literal for the NetworkStakeStepRewardsByStepViewer provider moniker. */
+export type NetworkStakeStepRewardsByStepViewerMoniker = typeof NetworkStakeStepRewardsByStepViewerMoniker
+
+/** Viewer interface for reading NetworkStakeStepRewardsByStep data. */
+export interface NetworkStakeStepRewardsByStepViewer extends NetworkStakeStepRewardsByStepViewerMethods, Provider<NetworkStakeStepRewardsByStepViewerMoniker> {}

package/src/viewers/NetworkStake/Rewards/Options.ts

@@ -0,0 +1,22 @@
+import type { Address } from '@xylabs/sdk-js'
+import type { BlockRange, StepIdentity } from '@xyo-network/xl1-protocol-model'
+
+/** Options for NetworkStakeStepRewardsRange. */
+export interface NetworkStakeStepRewardsRangeOptions {
+  range?: BlockRange
+}
+
+/** Options for NetworkStakeStepRewardsByStepViewer. */
+export interface NetworkStakeStepRewardsByStepViewerOptions extends NetworkStakeStepRewardsRangeOptions {
+  steps?: StepIdentity[]
+}
+
+/** Options for NetworkStakeStepRewardsByStakerViewer. */
+export interface NetworkStakeStepRewardsByStakerViewerOptions extends NetworkStakeStepRewardsRangeOptions {
+  stakers?: Address[]
+}
+
+/** Options for NetworkStakeStepRewardsByPositionViewer. */
+export interface NetworkStakeStepRewardsByPositionViewerOptions extends NetworkStakeStepRewardsRangeOptions {
+  positions?: number[]
+}

package/src/viewers/NetworkStake/Rewards/TotalViewer.ts

@@ -0,0 +1,17 @@
+import type { AttoXL1, Provider } from '@xyo-network/xl1-protocol-model'
+
+import type { NetworkStakeStepRewardsRangeOptions } from './Options.ts'
+import type { NetworkStakeStepRewardsViewerMethodsTemplate } from './templates/index.ts'
+
+// Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.
+
+/** NetworkStakeStepRewardsTotalViewerMethods interface. */
+export interface NetworkStakeStepRewardsTotalViewerMethods extends NetworkStakeStepRewardsViewerMethodsTemplate<NetworkStakeStepRewardsRangeOptions, AttoXL1> {}
+
+/** Moniker identifier for the NetworkStakeStepRewardsTotalViewer provider. */
+export const NetworkStakeStepRewardsTotalViewerMoniker = 'NetworkStakeStepRewardsTotalViewer' as const
+/** Type literal for the NetworkStakeStepRewardsTotalViewer provider moniker. */
+export type NetworkStakeStepRewardsTotalViewerMoniker = typeof NetworkStakeStepRewardsTotalViewerMoniker
+
+/** Viewer interface for reading NetworkStakeStepRewardsTotal data. */
+export interface NetworkStakeStepRewardsTotalViewer extends NetworkStakeStepRewardsTotalViewerMethods, Provider<NetworkStakeStepRewardsTotalViewerMoniker> {}

package/src/viewers/NetworkStake/Rewards/Viewer.ts

@@ -0,0 +1,22 @@
+import type { Provider } from '@xyo-network/xl1-protocol-model'
+
+import type { NetworkStakeStepRewardsByPositionViewer } from './ByPositionViewer.ts'
+import type { NetworkStakeStepRewardsByStakerViewer } from './ByStakerViewer.ts'
+import type { NetworkStakeStepRewardsByStepViewer } from './ByStepViewer.ts'
+import type { NetworkStakeStepRewardsTotalViewer } from './TotalViewer.ts'
+
+/** NetworkStakeStepRewardsViewerMethods interface. */
+export interface NetworkStakeStepRewardsViewerMethods {}
+
+/** Moniker identifier for the NetworkStakeStepRewardsViewer provider. */
+export const NetworkStakeStepRewardsViewerMoniker = 'NetworkStakeStepRewardsViewer' as const
+/** Type literal for the NetworkStakeStepRewardsViewer provider moniker. */
+export type NetworkStakeStepRewardsViewerMoniker = typeof NetworkStakeStepRewardsViewerMoniker
+
+/** Viewer interface for reading NetworkStakeStepRewards data. */
+export interface NetworkStakeStepRewardsViewer extends NetworkStakeStepRewardsViewerMethods, Provider<NetworkStakeStepRewardsViewerMoniker> {
+  position?: NetworkStakeStepRewardsByPositionViewer
+  staker?: NetworkStakeStepRewardsByStakerViewer
+  step?: NetworkStakeStepRewardsByStepViewer
+  total?: NetworkStakeStepRewardsTotalViewer
+}

package/src/viewers/NetworkStake/Rewards/index.ts

@@ -0,0 +1,7 @@
+export * from './ByPositionViewer.ts'
+export * from './ByStakerViewer.ts'
+export * from './ByStepViewer.ts'
+export * from './Options.ts'
+export * from './templates/index.ts'
+export * from './TotalViewer.ts'
+export * from './Viewer.ts'

package/src/viewers/NetworkStake/Rewards/templates/ByIndexMethodsTemplate.ts

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

package/src/viewers/NetworkStake/Rewards/templates/MethodsTemplate.ts

@@ -0,0 +1,10 @@
+import type { Promisable } from '@xylabs/sdk-js'
+
+/** NetworkStakeStepRewardsViewerMethodsTemplate interface. */
+export interface NetworkStakeStepRewardsViewerMethodsTemplate<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/viewers/NetworkStake/Rewards/templates/index.ts

@@ -0,0 +1,2 @@
+export * from './ByIndexMethodsTemplate.ts'
+export * from './MethodsTemplate.ts'

package/src/viewers/NetworkStake/index.ts

@@ -0,0 +1,4 @@
+export * from './NetworkStakeViewer.ts'
+export * from './Rewards/index.ts'
+
+// Viewers are client objects that can nest other viewers and ViewerMethods objects consist only of methods that return data.

package/src/viewers/NetworkStakeStepReward.ts

@@ -0,0 +1,82 @@
+import type { Address, Promisable } from '@xylabs/sdk-js'
+import type {
+  AttoXL1, Provider, StepIdentity, StepIdentityString,
+} from '@xyo-network/xl1-protocol-model'
+
+/** NetworkStakeStepAddressRewardViewerMethods interface. */
+export interface NetworkStakeStepAddressRewardViewerMethods {
+  // the step rewards for a specific network stakers for all of history
+  networkStakeStepRewardAddressHistory(address: Address): Promisable<Record<Address, AttoXL1>>
+
+  // the step rewards for a specific network stakers for a given step and block
+  networkStakeStepRewardAddressReward(context: StepIdentity, address: Address): Promisable<Record<Address, AttoXL1>>
+
+  // 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>
+}
+
+/** NetworkStakeStepPoolRewardViewerMethods interface. */
+export interface NetworkStakeStepPoolRewardViewerMethods {
+
+  // all the step rewards for all the network stakers for a given step and block
+  networkStakeStepRewardPoolRewards(context: StepIdentity): Promisable<Record<Address, AttoXL1>>
+
+  // all the shares for all the network stakers for a given step and block
+  networkStakeStepRewardPoolShares(context: StepIdentity): Promisable<Record<Address, bigint>>
+}
+
+/** NetworkStakeStepRewardPositionViewerMethods interface. */
+export interface NetworkStakeStepRewardPositionViewerMethods {
+  // 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<AttoXL1>
+}
+
+/** NetworkStakeStepRewardViewerMethods interface. */
+export interface NetworkStakeStepRewardViewerMethods extends
+  NetworkStakeStepPoolRewardViewerMethods,
+  NetworkStakeStepAddressRewardViewerMethods,
+  NetworkStakeStepRewardPositionViewerMethods
+{
+  networkStakeStepRewardClaimedByAddress(address: Address): Promisable<AttoXL1>
+
+  // the share & total rewards for a given position
+  networkStakeStepRewardForPosition(position: number, range: [number, number]): Promisable<[AttoXL1, AttoXL1]>
+
+  // estimate the total possible block rewards for a given step
+  networkStakeStepRewardForStep(context: StepIdentity): Promisable<AttoXL1>
+
+  // the share & total rewards for a given step and block for a given position
+  networkStakeStepRewardForStepForPosition(context: StepIdentity, position: number): Promisable<[AttoXL1, AttoXL1]>
+
+  // the predictable random number for a given step and block
+  networkStakeStepRewardRandomizer(context: StepIdentity): Promisable<AttoXL1>
+
+  // the total number of stakers for a given step and block
+  networkStakeStepRewardStakerCount(context: StepIdentity): Promisable<number>
+
+  networkStakeStepRewardUnclaimedByAddress(address: Address): Promisable<AttoXL1>
+
+  // the share & total rewards for a given position for each step in range
+  networkStakeStepRewardsForPosition(position: number,
+    range: [number, number]): Promisable<Record<StepIdentityString, [AttoXL1, AttoXL1]>>
+
+  // the total rewards for a given range
+  networkStakeStepRewardsForRange(range: [number, number]): Promisable<AttoXL1>
+
+  // the total rewards for a given range and step level
+  networkStakeStepRewardsForStepLevel(stepLevel: number, range: [number, number]): Promisable<AttoXL1>
+}
+
+/** Moniker identifier for the NetworkStakeStepRewardViewer provider. */
+export const NetworkStakeStepRewardViewerMoniker = 'NetworkStakeStepRewardViewer' as const
+/** Type literal for the NetworkStakeStepRewardViewer provider moniker. */
+export type NetworkStakeStepRewardViewerMoniker = typeof NetworkStakeStepRewardViewerMoniker
+
+/** Viewer interface for reading NetworkStakeStepReward data. */
+export interface NetworkStakeStepRewardViewer extends NetworkStakeStepRewardViewerMethods, Provider<NetworkStakeStepRewardViewerMoniker> {}

package/src/viewers/Stake.ts

@@ -0,0 +1,44 @@
+import type { Address, Promisable } from '@xylabs/sdk-js'
+import type { Position, Provider } from '@xyo-network/xl1-protocol-model'
+
+import type { StakeEventsViewer } from './StakeEvents.ts'
+
+/** StakeViewerProperties interface. */
+export interface StakeViewerProperties {
+  stakeEvents: StakeEventsViewer
+}
+
+/** StakeViewerMethods interface. */
+export interface StakeViewerMethods {
+  minWithdrawalBlocks(): Promisable<number>
+  rewardsContract(): Promisable<Address>
+  stakeById(id: number): Promisable<Position>
+  stakeByStaker(staker: Address, slot: number): Promisable<Position>
+  stakesByStaked(staked: Address): Promisable<Position[]>
+  stakesByStaker(staker: Address): Promisable<Position[]>
+  stakingTokenAddress(): Promisable<Address>
+}
+
+/** Moniker identifier for the StakeViewer provider. */
+export const StakeViewerMoniker = 'StakeViewer' as const
+/** Type literal for the StakeViewer provider moniker. */
+export type StakeViewerMoniker = typeof StakeViewerMoniker
+
+/** Viewer interface for reading Stake data. */
+export interface StakeViewer extends StakeViewerMethods, StakeViewerProperties, Provider<StakeViewerMoniker> {
+  activeStakes(): Promisable<Position[]>
+  removedStakes(): Promisable<Position[]>
+  withdrawnStakes(): Promisable<Position[]>
+}
+
+/** Moniker identifier for the StakeRunner provider. */
+export const StakeRunnerMoniker = 'StakeRunner' as const
+/** Type literal for the StakeRunner provider moniker. */
+export type StakeRunnerMoniker = typeof StakeRunnerMoniker
+
+/** Runner interface for executing Stake operations. */
+export interface StakeRunner extends Provider<StakeRunnerMoniker> {
+  addStake(staked: string, amount: bigint): Promise<boolean>
+  removeStake(slot: bigint): Promise<boolean>
+  withdrawStake(slot: bigint): Promise<boolean>
+}

package/src/viewers/StakeEvents.ts

@@ -0,0 +1,54 @@
+import type {
+  Address, JsonObject, Promisable,
+} from '@xylabs/sdk-js'
+import type { Provider } from '@xyo-network/xl1-protocol-model'
+
+/** StakeEventNames constant. */
+export const StakeEventNames = ['StakeAdded', 'StakeRemoved', 'StakeWithdrawn'] as const
+/** StakeEventName type. */
+export type StakeEventName = typeof StakeEventNames[number]
+
+/** ExternalEvent interface. */
+export interface ExternalEvent<TName extends string = string, TArgs extends JsonObject = {}> {
+  args: TArgs
+  name: TName
+  time: number // usually block number
+}
+
+/** EventFilter interface. */
+export interface EventFilter<TName extends string = string> {
+  name?: TName
+  time?: [number, number]
+}
+
+/** StakeEventArgs interface. */
+export interface StakeEventArgs {
+  amount: bigint
+  id: number
+  staked: Address
+  staker: Address
+}
+
+/** StakeEventFilterArgs type. */
+export type StakeEventFilterArgs = Partial<Pick<StakeEventArgs, 'staker' | 'staked' | 'id'>>
+
+/** StakeEventFilter interface. */
+export interface StakeEventFilter<TName extends StakeEventName = StakeEventName> extends EventFilter<TName> {
+  args?: StakeEventFilterArgs
+}
+
+/** StakeEvent interface. */
+export interface StakeEvent<TName extends StakeEventName = StakeEventName> extends ExternalEvent<TName> {
+  args: StakeEventArgs
+}
+
+/** Moniker identifier for the StakeEventsViewer provider. */
+export const StakeEventsViewerMoniker = 'StakeEventsViewer' as const
+/** Type literal for the StakeEventsViewer provider moniker. */
+export type StakeEventsViewerMoniker = typeof StakeEventsViewerMoniker
+
+/** Viewer interface for reading StakeEvents data. */
+export interface StakeEventsViewer extends Provider<StakeEventsViewerMoniker> {
+  positionCount(range: [number, number | 'latest']): Promisable<number>
+  stakeEvents<TName extends StakeEventName>(range: [number, number | 'latest'], filter?: StakeEventFilter<TName>): Promisable<StakeEvent<TName>[]>
+}

package/src/viewers/StakeIntent.ts

@@ -0,0 +1,21 @@
+import type {
+  Address, Hash, Promisable,
+} from '@xylabs/sdk-js'
+import type {
+  ChainQualified, ChainStakeIntent, Provider, XL1BlockRange,
+} from '@xyo-network/xl1-protocol-model'
+
+/** StakeIntentViewerMethods interface. */
+export interface StakeIntentViewerMethods {
+  qualifiedIntentByAddress(address: Address, headOrRange?: Hash | XL1BlockRange): Promisable<ChainQualified<ChainStakeIntent | null>>
+}
+
+/** Moniker identifier for the StakeIntentViewer provider. */
+export const StakeIntentViewerMoniker = 'StakeIntentViewer' as const
+/** Type literal for the StakeIntentViewer provider moniker. */
+export type StakeIntentViewerMoniker = typeof StakeIntentViewerMoniker
+
+/** Viewer interface for reading StakeIntent data. */
+export interface StakeIntentViewer extends StakeIntentViewerMethods, Provider<StakeIntentViewerMoniker> {
+  intentByAddress(address: Address, headOrRange?: Hash | XL1BlockRange): Promisable<ChainStakeIntent | null>
+}

package/src/viewers/StakeTotals.ts

@@ -0,0 +1,21 @@
+import type { Address, Promisable } from '@xylabs/sdk-js'
+import type { Provider } from '@xyo-network/xl1-protocol-model'
+
+/** StakeTotalsViewerMethods interface. */
+export interface StakeTotalsViewerMethods {
+  active(time?: number): Promisable<bigint>
+  activeByStaked(staked: Address, time?: number): Promisable<bigint>
+  activeByStaker(address: Address, time?: number): Promisable<bigint>
+  pending(time?: number): Promisable<bigint>
+  pendingByStaker(staker: Address, time?: number): Promisable<bigint>
+  withdrawn(time?: number): Promisable<bigint>
+  withdrawnByStaker(staker: Address, time?: number): Promisable<bigint>
+}
+
+/** Moniker identifier for the StakeTotalsViewer provider. */
+export const StakeTotalsViewerMoniker = 'StakeTotalsViewer' as const
+/** Type literal for the StakeTotalsViewer provider moniker. */
+export type StakeTotalsViewerMoniker = typeof StakeTotalsViewerMoniker
+
+/** Viewer interface for reading StakeTotals data. */
+export interface StakeTotalsViewer extends StakeTotalsViewerMethods, Provider<StakeTotalsViewerMoniker> {}

package/src/viewers/StepStake.ts

@@ -0,0 +1,26 @@
+import type { Address, Promisable } from '@xylabs/sdk-js'
+import type { Provider, StepIdentity } from '@xyo-network/xl1-protocol-model'
+
+/** StepStakeViewerMethods interface. */
+export interface StepStakeViewerMethods {
+  // this is the prorated stake for all addresses in the step
+  stepStake: (step: StepIdentity) => Promisable<Record<Address, bigint>>
+
+  // this is the prorated stake for a specific address in the step
+  stepStakeForAddress: (address: Address, step: StepIdentity) => Promisable<bigint>
+}
+
+/* Prorated stake is the amount of stake that is allocated to a specific step
+   based on the total stake and the number of steps. This is used to ensure
+   that the stake is distributed fairly among all steps.
+
+   The simplest way to calculate it is to enumerate every XL1 block in the step add the current stake at that point to a counter.
+   For example, if an Address had a stake of 100 for the entire time, then the prorated stake would be 100 * number of blocks in the step.
+*/
+
+export const StepStakeViewerMoniker = 'StepStakeViewer' as const
+/** Type literal for the StepStakeViewer provider moniker. */
+export type StepStakeViewerMoniker = typeof StepStakeViewerMoniker
+
+/** Viewer interface for reading StepStake data. */
+export interface StepStakeViewer extends StepStakeViewerMethods, Provider<StepStakeViewerMoniker> {}

package/src/viewers/StepViewer.ts

@@ -0,0 +1,57 @@
+import type { Address, Promisable } from '@xylabs/sdk-js'
+import type {
+  Position, PositionId, Provider, StepIdentity,
+} from '@xyo-network/xl1-protocol-model'
+
+import type { NetworkStakeStepRewardsViewer } from './NetworkStake/index.ts'
+
+/** Options for PagedPositions. */
+export interface PagedPositionsOptions {
+  cursor?: PositionId
+  limit?: number
+}
+
+/** Options for PagedStakers. */
+export interface PagedStakersOptions {
+  cursor?: Address
+  limit?: number
+}
+
+/** StepStatistics interface. */
+export interface StepStatistics {
+  endTime: number
+  startTime: number
+}
+
+/** StepViewerMethods interface. */
+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[]>
+
+  // if no positionId is supplied, returns the total stake weight for the step
+  weight(step: StepIdentity, positionId?: PositionId): Promisable<bigint>
+}
+
+/** Moniker identifier for the StepViewer provider. */
+export const StepViewerMoniker = 'StepViewer' as const
+/** Type literal for the StepViewer provider moniker. */
+export type StepViewerMoniker = typeof StepViewerMoniker
+
+/** Viewer interface for reading Step data. */
+export interface StepViewer extends StepViewerMethods, Provider<StepViewerMoniker> {
+  rewards?: NetworkStakeStepRewardsViewer
+}

package/src/viewers/TimeSync.ts

@@ -0,0 +1,27 @@
+import type { Promisable } from '@xylabs/sdk-js'
+import type {
+  Provider, TimeDomain, TimePayload,
+} from '@xyo-network/xl1-protocol-model'
+
+/** TimeSyncViewerMethods interface. */
+export interface TimeSyncViewerMethods {
+  /** Convert time between different domains */
+  convertTime(fromDomain: TimeDomain, toDomain: TimeDomain, from: number): Promisable<number>
+
+  /** Get the current time for a given domain */
+  currentTime(domain: TimeDomain): Promisable<[string, number]>
+
+  /** Get the current time for a given domain */
+  currentTimeAndHash(domain: TimeDomain): Promisable<[number, string | null]>
+
+  /** Create a TimePayload with the current time from all configured domains */
+  currentTimePayload(): Promisable<TimePayload>
+}
+
+/** Moniker identifier for the TimeSyncViewer provider. */
+export const TimeSyncViewerMoniker = 'TimeSyncViewer' as const
+/** Type literal for the TimeSyncViewer provider moniker. */
+export type TimeSyncViewerMoniker = typeof TimeSyncViewerMoniker
+
+/** Viewer interface for reading TimeSync data. */
+export interface TimeSyncViewer extends TimeSyncViewerMethods, Provider<TimeSyncViewerMoniker> {}

package/src/viewers/Transaction.ts

@@ -0,0 +1,27 @@
+import type { Hash, Promisable } from '@xylabs/sdk-js'
+import type {
+  Provider, ProviderMoniker, SignedHydratedTransaction, SignedHydratedTransactionWithHashMeta,
+} from '@xyo-network/xl1-protocol-model'
+
+/** TransactionViewerMethods interface. */
+export interface TransactionViewerMethods {
+  byHash(transactionHash: Hash): Promisable<SignedHydratedTransactionWithHashMeta | null>
+
+  /** @deprecated use .byBlockHashAndIndex instead */
+  transactionByBlockHashAndIndex(blockHash: Hash, transactionIndex: number): Promisable<SignedHydratedTransaction | null>
+  /** @deprecated use .byBlockNumberAndIndex instead */
+  transactionByBlockNumberAndIndex(blockNumber: number, transactionIndex: number): Promisable<SignedHydratedTransaction | null>
+  /** @deprecated use .byHash instead */
+  transactionByHash(transactionHash: Hash): Promisable<SignedHydratedTransaction | null>
+}
+
+/** Moniker identifier for the TransactionViewer provider. */
+export const TransactionViewerMoniker = 'TransactionViewer' as const
+/** Type literal for the TransactionViewer provider moniker. */
+export type TransactionViewerMoniker = typeof TransactionViewerMoniker
+
+/** Viewer interface for reading Transaction data. */
+export interface TransactionViewer<TMoniker extends ProviderMoniker = TransactionViewerMoniker> extends TransactionViewerMethods, Provider<TMoniker> {
+  byBlockHashAndIndex(blockHash: Hash, transactionIndex: number): Promisable<SignedHydratedTransactionWithHashMeta | null>
+  byBlockNumberAndIndex(blockNumber: number, transactionIndex: number): Promisable<SignedHydratedTransactionWithHashMeta | null>
+}

package/src/viewers/TransactionInvalidation.ts

@@ -0,0 +1,71 @@
+import { type Promisable } from '@xylabs/sdk-js'
+import { zodIsFactory } from '@xylabs/sdk-js'
+import type {
+  Provider, SignedHydratedTransaction, SignedHydratedTransactionWithHashMeta,
+} from '@xyo-network/xl1-protocol-model'
+import {
+  ChainQualificationZod, ChainQualifiedHeadConfigZod, ChainQualifiedRangeConfigZod,
+} from '@xyo-network/xl1-protocol-model'
+import { z } from 'zod'
+
+import type { HydratedTransactionValidationError } from '../validation/index.ts'
+
+/** TransactionInvalidationQualificationZod constant. */
+export const TransactionInvalidationQualificationZod = ChainQualificationZod
+/** TransactionInvalidationQualification type. */
+export type TransactionInvalidationQualification = z.infer<typeof TransactionInvalidationQualificationZod>
+/** Type guard that checks if a value is a valid TransactionInvalidationQualification. */
+export const isTransactionInvalidationQualification = zodIsFactory(TransactionInvalidationQualificationZod)
+
+/** TransactionInvalidationConfigFieldsZod constant. */
+export const TransactionInvalidationConfigFieldsZod = z.object({
+  state: z.boolean().optional(),
+  value: z.boolean().optional(),
+})
+
+/** TransactionInvalidationConfigZod constant. */
+export const TransactionInvalidationConfigZod = z.union([
+  TransactionInvalidationConfigFieldsZod.extend(ChainQualifiedHeadConfigZod.shape),
+  TransactionInvalidationConfigFieldsZod.extend(ChainQualifiedRangeConfigZod.shape),
+  TransactionInvalidationConfigFieldsZod,
+  z.object({}),
+])
+
+/** TransactionInvalidationConfig type. */
+export type TransactionInvalidationConfig = z.infer<typeof TransactionInvalidationConfigZod>
+/** Type guard that checks if a value is a valid TransactionInvalidationConfig. */
+export const isTransactionInvalidationConfig = zodIsFactory(TransactionInvalidationConfigZod)
+
+/**
+ * Checks if transactions are invalid (impossible to ever become valid) according to protocol rules.
+ */
+
+export interface TransactionInvalidationViewerMethods {
+  qualifiedInvalidateTransactions(
+    blocks: SignedHydratedTransaction[],
+    config?: TransactionInvalidationConfig
+  ): Promisable<[(HydratedTransactionValidationError[] | SignedHydratedTransactionWithHashMeta)[], TransactionInvalidationQualification]>
+}
+
+/** Moniker identifier for the TransactionInvalidationViewer provider. */
+export const TransactionInvalidationViewerMoniker = 'TransactionInvalidationViewer' as const
+/** Type literal for the TransactionInvalidationViewer provider moniker. */
+export type TransactionInvalidationViewerMoniker = typeof TransactionInvalidationViewerMoniker
+
+/** Viewer interface for reading TransactionInvalidation data. */
+export interface TransactionInvalidationViewer extends TransactionInvalidationViewerMethods, Provider<TransactionInvalidationViewerMoniker> {
+  invalidateTransaction(
+    block: SignedHydratedTransaction,
+    config?: TransactionInvalidationConfig
+  ): Promisable<HydratedTransactionValidationError[] | SignedHydratedTransactionWithHashMeta>
+
+  invalidateTransactions(
+    blocks: SignedHydratedTransaction[],
+    config?: TransactionInvalidationConfig
+  ): Promisable<(HydratedTransactionValidationError[] | SignedHydratedTransactionWithHashMeta)[]>
+
+  qualifiedInvalidateTransaction(
+    block: SignedHydratedTransaction,
+    config?: TransactionInvalidationConfig
+  ): Promisable<[HydratedTransactionValidationError[] | SignedHydratedTransactionWithHashMeta, TransactionInvalidationQualification]>
+}