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

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.

package/src/interfaces/viewers/Stake.ts

@@ -0,0 +1,22 @@
+import type { Address } from '@xylabs/hex'
+import type { PositionId } from '@xyo-network/xl1-protocol'
+
+export type Position = {
+  // the block number when the stake was added
+  addBlock: number
+  // the amount that is staked
+  amount: bigint
+  // the unique id for the stake item
+  id: PositionId
+  // the block number when the stake was removed (set to 0 if not removed)
+  removeBlock: number
+  // the address that is being staked
+  staked: Address
+  // the address that owns the stake
+  staker: Address
+  // the block number when the stake was withdrawn (set to 0 if not withdrawn)
+  withdrawBlock: number
+}
+
+/** @deprecated - use Position instead */
+export type Stake = Position

package/src/interfaces/viewers/StakeTotalsViewer.ts

@@ -0,0 +1,12 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+export interface StakeTotalsViewer {
+  active(): Promisable<bigint>
+  activeByStaked(staked: Address): Promisable<bigint>
+  activeByStaker(address: Address): Promisable<bigint>
+  pending(): Promisable<bigint>
+  pendingByStaker(staker: Address): Promisable<bigint>
+  withdrawn(): Promisable<bigint>
+  withdrawnByStaker(staker: Address): Promisable<bigint>
+}

package/src/interfaces/viewers/StakeViewer.ts

@@ -0,0 +1,13 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+import type { Position } from './Stake.ts'
+
+export interface StakeViewer {
+  stakeById(id: number): Promisable<Position>
+  stakeByStaker(staker: Address, slot: number): Promisable<Position>
+  /* @deprecated use stakesByStaker */
+  stakedByStaker(staker: Address): Promisable<Address[]>
+  stakesByStaked(staked: Address): Promisable<Position[]>
+  stakesByStaker(staker: Address): Promisable<Position[]>
+}

package/src/interfaces/viewers/StepStake.ts

@@ -0,0 +1,19 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { StepIdentity } from '@xyo-network/xl1-protocol'
+
+export interface StepStakeViewInterface {
+  // 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.
+*/

package/src/interfaces/viewers/TimeSync.ts

@@ -0,0 +1,19 @@
+import type { Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { TimeDomain, TimePayload } from '@xyo-network/xl1-protocol'
+
+export interface TimeSyncViewInterface {
+  /** 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]>
+}
+
+export interface TimeSyncViewInterfaceV2 extends TimeSyncViewInterface {
+  /** Get the current time for a given domain */
+  currentTimeAndHash(domain: TimeDomain): Promisable<[number, Hash | null]>
+
+  /** Create a TimePayload with the current time from all configured domains */
+  currentTimePayload(): Promisable<TimePayload>
+}

package/src/interfaces/viewers/Transaction.ts

@@ -0,0 +1,9 @@
+import type { Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { SignedHydratedTransaction } from '@xyo-network/xl1-protocol'
+
+export interface TransactionViewInterface {
+  transactionByBlockHashAndIndex(blockHash: Hash, transactionIndex: number): Promisable<SignedHydratedTransaction | null>
+  transactionByBlockNumberAndIndex(blockNumber: number, transactionIndex: number): Promisable<SignedHydratedTransaction | null>
+  transactionByHash(transactionHash: Hash): Promisable<SignedHydratedTransaction | null>
+}

package/src/interfaces/viewers/TransferBalance.ts

@@ -0,0 +1,29 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { Signed } from '@xyo-network/boundwitness-model'
+import type {
+  AttoXL1,
+  BlockBoundWitness, TransactionBoundWitness, Transfer,
+  XL1BlockRange,
+} from '@xyo-network/xl1-protocol'
+
+export type TransferBalanceHistoryItem = [
+  Signed<BlockBoundWitness> /* block */,
+  Signed<TransactionBoundWitness> | null,
+  Transfer, /* the actual transfer payload */
+]
+export type TransferPair = [/* from */ Address, /* to */Address]
+
+export interface TransferBalancesViewInterface {
+  transferBalances(address: Address[]): Promisable<Partial<Record<Address, Record<Address, AttoXL1>>>>
+  transferBalancesHistories(address: Address[]): Promisable<Partial<Record<Address, Record<Address, TransferBalanceHistoryItem[]>>>>
+  transferPairBalances(address: TransferPair[]): Promisable<Partial<Record<Address, Record<Address, AttoXL1>>>>
+  transferPairBalancesHistories(address: TransferPair[]): Promisable<Partial<Record<Address, Record<Address, TransferBalanceHistoryItem[]>>>>
+}
+
+export interface TransferBalanceViewInterface {
+  transferBalance(address: Address): Promisable<AttoXL1>
+  transferBalanceHistory(address: Address, range?: XL1BlockRange): Promisable<TransferBalanceHistoryItem[]>
+  transferPairBalance(address: TransferPair): Promisable<AttoXL1>
+  transferPairBalanceHistory(address: TransferPair): Promisable<TransferBalanceHistoryItem[]>
+}

package/src/interfaces/viewers/index.ts

@@ -0,0 +1,14 @@
+export * from './AccountBalance.ts'
+export * from './Block.ts'
+export * from './Chain.ts'
+export * from './ChainContract.ts'
+export * from './Fork.ts'
+export * from './NetworkStakeStepReward.ts'
+export * from './NetworkStakeViewer/index.ts'
+export * from './Stake.ts'
+export * from './StakeTotalsViewer.ts'
+export * from './StakeViewer.ts'
+export * from './StepStake.ts'
+export * from './TimeSync.ts'
+export * from './Transaction.ts'
+export * from './TransferBalance.ts'

package/src/model/ChainStake/ChainStakeRead.ts

@@ -1,6 +1,7 @@
 import type { Address } from '@xylabs/hex'
 import type { Promisable } from '@xylabs/promise'
-import type { Position } from '@xyo-network/xl1-protocol'
+
+import type { Position } from '../../interfaces/index.ts'
 
 export interface ChainStakeRead {
   active(time?: number): Promisable<bigint>

package/src/model/summary.ts

@@ -3,9 +3,10 @@ import type { Semaphore } from 'async-mutex'
 
 import type { MapTypeRead, MapTypeWrite } from '../map/index.ts'
 import type { BalancesStepSummary, TransfersStepSummary } from '../payloads/summary/index.ts'
-import type { ChainContextRead } from './index.ts'
+import type { BaseContext, ChainContextRead } from './index.ts'
 
-export interface ChainSummaryContextBase<TPayload extends Payload, T extends (MapTypeRead<string, TPayload> | MapTypeWrite<string, TPayload>)> {
+export interface ChainSummaryContextBase<TPayload extends Payload,
+  T extends (MapTypeRead<string, TPayload> | MapTypeWrite<string, TPayload>)> extends BaseContext {
   stepSemaphores: Semaphore[]
   summaryMap: T
   windowSize?: number

package/src/provider/TransactionHelper.ts

@@ -0,0 +1,14 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+import type { Payload } from '@xyo-network/payload-model'
+import type { UnsignedHydratedTransaction } from '@xyo-network/xl1-protocol'
+
+export interface TransactionHelper {
+  // build tx, sign tx, send tx
+  addPayloadsToChain(onChain: Payload[], offChain: Payload[]): void
+
+  // sign tx, send tx
+  addUnsignedTransactionToChain(tx: UnsignedHydratedTransaction): void
+
+  // send tx (primitive)
+  addSignedTransactionToChain(tx: UnsignedHydratedTransaction): void
+}

package/src/provider/TransactionSubmitter.ts

@@ -0,0 +1,26 @@
+import type { Address, Hex } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { Payload } from '@xyo-network/payload-model'
+import type {
+  AllowedBlockPayload, SignedHydratedTransaction, TransactionFeesBigInt,
+} from '@xyo-network/xl1-protocol'
+
+/** @deprecated use TransactionOptions instead */
+export interface TransactionSubmitterOptions {
+  chain?: Hex
+  exp?: number
+  fees?: TransactionFeesBigInt
+  from?: Address
+  nbf?: number
+}
+
+/** @deprecated use XyoGatewayHelpers instead */
+export interface TransactionSubmitter {
+  /** @deprecated use runner.broadcastTransaction */
+  submitTransaction(
+    elevatedPayloads: AllowedBlockPayload[],
+    additionalPayloads: Payload[],
+    // eslint-disable-next-line sonarjs/deprecation
+    options?: TransactionSubmitterOptions
+  ): Promisable<SignedHydratedTransaction>
+}

package/src/provider/XyoClient.ts

@@ -0,0 +1,21 @@
+import type { XyoPermissions } from './permissions/index.ts'
+import type { XyoGatewayProvider } from './XyoGateway.ts'
+
+export type GatewayName = string & { __gatewayName: true }
+
+export interface XyoGatewayConfig {
+  name: GatewayName
+}
+
+export interface XyoRpcGatewayConfig extends XyoGatewayConfig {
+  dataLakeEndpoint: string
+  networkEndpoint: string
+}
+
+export interface XyoClient {
+  gateways: Readonly<Record<GatewayName, XyoGatewayProvider>>
+  permissions: XyoPermissions
+
+  addGateway?(providerOrConfig: XyoGatewayConfig | XyoRpcGatewayConfig | XyoGatewayProvider): Promise<XyoGatewayProvider>
+  removeGateway?(name: GatewayName): Promise<void>
+}

package/src/provider/XyoConnection.ts

@@ -0,0 +1,55 @@
+import type { Address, Hex } from '@xylabs/hex'
+import type { Signed } from '@xyo-network/boundwitness-model'
+import type { Payload } from '@xyo-network/payload-model'
+import type {
+  AllowedBlockPayload, TransactionBoundWitness, TransactionFeesBigInt,
+} from '@xyo-network/xl1-protocol'
+
+import type { NetworkStakeViewer } from '../interfaces/index.ts'
+// eslint-disable-next-line sonarjs/deprecation
+import type { TransactionSubmitter } from './TransactionSubmitter.ts'
+import type { XyoDataLake, XyoDataLakeViewer } from './XyoDataLake.ts'
+import type { XyoNetwork } from './XyoNetwork.ts'
+import type { XyoRunner } from './XyoRunner.ts'
+import type { XyoSigner } from './XyoSigner.ts'
+import type { XyoViewer } from './XyoViewer.ts'
+// eslint-disable-next-line sonarjs/deprecation
+import type { XyoWallet } from './XyoWallet.ts'
+
+/** @deprecated use XyoConnectionProvider instead */
+// eslint-disable-next-line sonarjs/deprecation
+export interface XyoConnectionProviderDeprecated extends TransactionSubmitter {
+
+  /** @deprecated  - use from gateway instead */
+  signer: XyoSigner
+
+  /** @deprecated  - use host instead */
+  // eslint-disable-next-line sonarjs/deprecation
+  wallet: XyoWallet
+
+  /** @deprecated  - use submitTransaction instead */
+  send(
+    elevatedPayloads: AllowedBlockPayload[],
+    additionalPayloads: Payload[],
+    chain?: Hex,
+    nbf?: number,
+    exp?: number,
+    from?: Address,
+    fees?: TransactionFeesBigInt,
+  ): Promise<Signed<TransactionBoundWitness>>
+}
+
+// eslint-disable-next-line sonarjs/deprecation
+export interface XyoConnection extends Partial<XyoConnectionProviderDeprecated> {
+  network?: XyoNetwork
+  networkStake?: NetworkStakeViewer
+  runner?: XyoRunner
+  storage?: XyoDataLake | XyoDataLakeViewer
+  viewer?: XyoViewer
+}
+
+/** @deprecated use XyoConnectionProvider */
+export interface XyoConnectionProvider extends XyoConnection {}
+
+/** @deprecated use XyoConnectionProvider */
+export interface XyoProvider extends XyoConnection {}

package/src/provider/XyoDataLake.ts

@@ -0,0 +1,43 @@
+import type { Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { Payload } from '@xyo-network/payload-model'
+
+export type DataLakeData = Payload | ArrayBuffer
+
+export interface XyoDataLakeViewer {
+  // if resolves to hash payload, keep going until hitting a non-payload or maxDepth, or unable to find
+  fetch(hashes: Hash[], maxDepth?: number): Promisable<DataLakeData[]>
+  // same as fetch but never follows hash payloads
+  get(hashes: Hash[]): Promisable<DataLakeData[]>
+  // same as fetch, except returns each step in tuple containing the result and the steps
+  trace(hash: Hash): Promisable<[DataLakeData | undefined, Payload[]]>
+}
+
+export interface XyoDataLake extends XyoDataLakeViewer {
+  add(items: DataLakeData[]): Promisable<DataLakeData[]>
+}
+
+/** @deprecated use XyoDataLake instead */
+export interface XyoDataLakeProvider extends XyoDataLake {
+}
+
+export const isDataLakeViewer = (value: unknown): value is XyoDataLakeViewer => {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && 'fetch' in value
+    && typeof (value as XyoDataLakeViewer).fetch === 'function'
+    && 'get' in value
+    && typeof (value as XyoDataLakeViewer).get === 'function'
+    && 'trace' in value
+    && typeof (value as XyoDataLakeViewer).trace === 'function'
+  )
+}
+
+export const isDataLakeProvider = (value: unknown): value is XyoDataLake => {
+  return (
+    isDataLakeViewer(value)
+    && 'add' in value
+    && typeof (value as XyoDataLake).add === 'function'
+  )
+}

package/src/provider/XyoGateway.ts

@@ -0,0 +1,21 @@
+import type { Promisable } from '@xylabs/promise'
+
+import type { XyoConnection } from './XyoConnection.ts'
+import type { XyoGatewayHelpers } from './XyoGatewayHelpers.ts'
+import type { XyoSigner } from './XyoSigner.ts'
+
+/** @deprecated use XyoConnectionConfig instead */
+export interface XyoConnectionConfigDeprecated {
+  name: string
+}
+
+export interface XyoGatewayProvider extends Partial<XyoGatewayHelpers> {
+  /**
+   * Returns the connection provider for this gateway.
+   */
+  connection(): Promisable<XyoConnection>
+  /**
+   * Returns the signer for this gateway.
+   */
+  signer(): Promisable<XyoSigner>
+}

package/src/provider/XyoGatewayHelpers.ts

@@ -0,0 +1,30 @@
+import type {
+  Address, Hash, Hex,
+} from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { Payload } from '@xyo-network/payload-model'
+import type {
+  AllowedBlockPayload, TransactionBoundWitness, TransactionFeesBigInt,
+} from '@xyo-network/xl1-protocol'
+
+export interface TransactionOptions {
+  chain?: Hex
+  exp?: number
+  fees?: TransactionFeesBigInt
+  from?: Address
+  nbf?: number
+}
+
+export interface XyoGatewayHelpers {
+
+  addPayloadsToChain(
+    onChain: AllowedBlockPayload[],
+    offChain: Payload[],
+    options?: TransactionOptions
+  ): Promisable<[Hash, [TransactionBoundWitness, Payload[]]]>
+
+  addTransactionToChain(
+    tx: [TransactionBoundWitness, Payload[]],
+  ): Promisable<Hash>
+
+}

package/src/provider/XyoNetwork.ts

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

package/src/provider/XyoRunner.ts

@@ -0,0 +1,7 @@
+import type { Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { SignedHydratedTransaction } from '@xyo-network/xl1-protocol'
+
+export interface XyoRunner {
+  broadcastTransaction(transaction: SignedHydratedTransaction): Promisable<Hash>
+}