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

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/ChainContext/ChainContext.ts

@@ -1,3 +1,8 @@
+import type { Logger } from '@xylabs/logger'
+import { isDefined, isUndefined } from '@xylabs/typeof'
+
+import { LruCacheMap, MemoryMap } from '../../driver/index.ts'
+import type { MapType } from '../../map/index.ts'
 import type { ChainIdentity } from '../ChainIdentity.ts'
 import type {
   ChainStakeContext, ChainStakeContextRead, ChainStakeContextWrite,
@@ -7,13 +12,53 @@ import type {
   ChainStoreContext, ChainStoreContextRead, ChainStoreContextWrite,
 } from './ChainStoreContext.ts'
 
-export interface ChainContextWrite extends ChainIdentity, ChainStateContextWrite, ChainStoreContextWrite {}
+export interface BaseContext<TCacheValue = string | object | number | bigint> {
+  caches?: Record<string, MapType<string, TCacheValue>>
+  logger?: Logger
+}
+
+export function contextCache<TCacheValue>(
+  context: BaseContext<TCacheValue | unknown>,
+  name: string,
+  create?: () => MapType<string, TCacheValue>,
+): MapType<string, TCacheValue> {
+  if (!context.caches) {
+    context.caches = {}
+  }
+  if (isUndefined(context.caches[name])) {
+    context.caches[name] = create?.() ?? new MemoryMap<string, TCacheValue>()
+  }
+  return context.caches[name] as MapType<string, TCacheValue>
+}
+
+export async function withContextCacheResponse<T extends {} | string | number | bigint>(
+  context: BaseContext,
+  name: string,
+  key: string,
+  func: () => Promise<T extends {} | string | number | bigint ? T : never>,
+  options?: { max?: number },
+): Promise<T> {
+  const cache = contextCache<T>(
+    context,
+    name,
+    () => new LruCacheMap<string, T>({ max: options?.max ?? 10_000 }),
+  )
+  const cacheResult = await cache.get(key)
+  if (isDefined(cacheResult)) {
+    return cacheResult
+  }
+  const result = await func()
+  await cache.set(key, result)
+  return result
+}
+
+export interface ChainContextWrite extends BaseContext, ChainIdentity, ChainStateContextWrite, ChainStoreContextWrite {}
 
-export interface StakedChainContextWrite extends ChainContextWrite, ChainStakeContextWrite {}
+export interface StakedChainContextWrite extends BaseContext, ChainContextWrite, ChainStakeContextWrite {}
 
-export interface ChainContextRead extends ChainIdentity, ChainStateContextRead, ChainStoreContextRead {}
+export interface ChainContextRead extends BaseContext, ChainIdentity, ChainStateContextRead, ChainStoreContextRead {}
 
-export interface StakedChainContextRead extends ChainContextRead, ChainStakeContextRead {}
+export interface StakedChainContextRead extends BaseContext, ChainContextRead, ChainStakeContextRead {}
 
 export type ChainContext = ChainIdentity & ChainContextRead & ChainContextWrite & ChainStoreContext
 

package/src/model/ChainContext/ChainStateContext.ts

@@ -2,7 +2,7 @@ import type { Hash } from '@xylabs/hex'
 import type { Promisable } from '@xylabs/promise'
 
 export interface ChainStateContextRead {
-  head(): Promisable<Hash>
+  head(): Promisable<[Hash, number]>
 }
 
 export interface ChainStateContextWrite {}

package/src/model/ChainStake/ChainStakeRead.ts

@@ -1,17 +1,18 @@
 import type { Address } from '@xylabs/hex'
 import type { Promisable } from '@xylabs/promise'
-import type { Stake } from '@xyo-network/xl1-protocol'
+
+import type { Position } from '../../interfaces/index.ts'
 
 export interface ChainStakeRead {
-  active(): Promisable<bigint>
-  activeByAddressStaked(address: string): Promisable<bigint>
-  activeByStaker(address: string): Promisable<bigint>
-  pending(): Promisable<bigint>
-  pendingByStaker(staker: string): Promisable<bigint>
-  stakeById(id: number): Promisable<Stake>
-  stakeByStaker(staker: Address, slot: number): Promisable<Stake>
-  stakesByStaked(staked: Address, range?: [number, number | 'latest']): Promisable<Stake[]>
-  stakesByStaker(staker: Address, range?: [number, number | 'latest']): Promisable<Stake[]>
-  withdrawn(): Promisable<bigint>
-  withdrawnByStaker(staker: string): Promisable<bigint>
+  active(time?: number): Promisable<bigint>
+  activeByAddressStaked(address: string, time?: number): Promisable<bigint>
+  activeByStaker(address: string, time?: number): Promisable<bigint>
+  pending(time?: number): Promisable<bigint>
+  pendingByStaker(staker: string, time?: number): Promisable<bigint>
+  stakeById(id: number, time?: number): Promisable<Position>
+  stakeByStaker(staker: Address, slot: number, time?: number): Promisable<Position>
+  stakesByStaked(staked: Address, range?: [number, number | undefined]): Promisable<Position[]>
+  stakesByStaker(staker: Address, range?: [number, number | undefined]): Promisable<Position[]>
+  withdrawn(time?: number): Promisable<bigint>
+  withdrawnByStaker(staker: string, time?: number): Promisable<bigint>
 }

package/src/model/StakeEvents.ts

@@ -34,5 +34,6 @@ export interface StakeEvent<TName extends StakeEventName = StakeEventName> exten
 }
 
 export interface StakeEventsRead {
+  positionCount(range: [number, number | 'latest']): Promisable<number>
   stakeEvents<TName extends StakeEventName>(range: [number, number | 'latest'], filter?: StakeEventFilter<TName>): Promisable<StakeEvent<TName>[]>
 }

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/primitives/index.ts

@@ -1,4 +1,5 @@
 export * from './readPayloadMapFromStore.ts'
 export * from './step/index.ts'
 export * from './summary/index.ts'
+export * from './timeBudget.ts'
 export * from './transaction/index.ts'

package/src/primitives/summary/balances/balancesStepSummaryFromRange.ts

@@ -25,7 +25,7 @@ export async function balancesStepSummaryFromRange(
   // console.log(`balanceStepSummaryFromRange: head=${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: BalancesStepSummary | undefined = undefined
 
@@ -37,7 +37,7 @@ export async function balancesStepSummaryFromRange(
       balances[address as Address] = toSignedBigInt(balance)
     }
     result = {
-      schema: BalancesStepSummarySchema, hash: head, stepSize: -1, balances,
+      schema: BalancesStepSummarySchema, hash: headHash, stepSize: -1, balances,
     }
   } else {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/primitives/summary/balances/balancesSummary.ts

@@ -13,9 +13,9 @@ export async function balancesSummary(
   context: BalanceStepSummaryContext,
 ): Promise<Partial<Record<Address, bigint>>> {
   return await spanRootAsync('balanceSummary', 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 [headHash] = await context.head()
+    const headResult = await context.store.chainMap.get(headHash)
+    const headBoundWitness = asBlockBoundWitnessWithStorageMeta(headResult, () => `Head block not found for hash: ${headHash}`, { required: true })
     const rangeStart = asXL1BlockNumber(isDefined(context.windowSize) ? Math.max(headBoundWitness.block - context.windowSize + 1, 0) : 0)
     const ranges = deepCalculateFramesFromRange([rangeStart, asXL1BlockNumber(headBoundWitness.block)])
     const summaries = await Promise.all(ranges.map(range => balancesStepSummaryFromRange(context, range)))

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

@@ -25,7 +25,7 @@ export async function transfersStepSummaryFromRange(
   // console.log(`transfersStepSummaryFromRange: head=${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
 
@@ -40,7 +40,7 @@ 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

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

@@ -14,9 +14,9 @@ export async function transfersSummary(
   context: 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 [headHash] = await context.head()
+    const headResult = await context.store.chainMap.get(headHash)
+    const headBoundWitness = asBlockBoundWitnessWithStorageMeta(headResult, () => `Head block not found for hash: ${headHash}`, { required: true })
     const rangeStart = asXL1BlockNumber(isDefined(context.windowSize) ? Math.max(headBoundWitness.block - context.windowSize + 1, 0) : 0)
     const ranges = deepCalculateFramesFromRange([rangeStart, asXL1BlockNumber(headBoundWitness.block)])
     const summaries = await Promise.all(ranges.map(range => transfersStepSummaryFromRange(context, range)))

package/src/primitives/timeBudget.ts

@@ -0,0 +1,11 @@
+import { type Logger } from '@xylabs/logger'
+
+export async function timeBudget<TResult>(name: string, logger: Logger | undefined, func: () => Promise<TResult>, budget: number): Promise<TResult> {
+  const start = Date.now()
+  const result = await func()
+  const duration = Date.now() - start
+  if (duration > budget) {
+    logger?.warn(`Function [${name}] execution exceeded budget: ${duration}ms > ${budget}ms`)
+  }
+  return result
+}

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>
+}

package/src/provider/XyoSigner.ts

@@ -0,0 +1,29 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { Signed, UnsignedBoundWitness } from '@xyo-network/boundwitness-model'
+import type { Payload } from '@xyo-network/payload-model'
+import type {
+  AllowedBlockPayload, ChainId, TransactionBoundWitness,
+  TransactionFeesBigInt,
+} from '@xyo-network/xl1-protocol'
+
+export interface XyoSigner {
+  address(): Promisable<Address>
+  // The tx passed in must have all the payloads (on and off chain) in the payloads array
+  // Returns the signed transaction and the payloads array excluding the off-chain payloads.
+  // The return value is ready to be broadcast to block producers
+  signTransaction(tx: [UnsignedBoundWitness<TransactionBoundWitness>, Payload[]]): Promisable<[Signed<TransactionBoundWitness>, Payload[]]>
+}
+
+export interface XyoSignerDeprecated {
+  /** @deprecated use signTransaction instead */
+  createSignedTransaction(
+    chain: ChainId,
+    elevatedPayloads: AllowedBlockPayload[],
+    additionalPayloads: Payload[],
+    nbf: number,
+    exp: number,
+    fees: TransactionFeesBigInt,
+    from?: Address,
+  ): Promisable<Signed<TransactionBoundWitness>>
+}

package/src/provider/XyoViewer.ts

@@ -0,0 +1,17 @@
+import type {
+  AccountBalanceViewInterface, BlockViewInterface, ChainViewInterface,
+  ForkViewer,
+  NetworkStakeStepRewardViewInterface,
+  NetworkStakeViewer,
+  StakeViewer,
+  TransactionViewInterface, TransferBalanceViewInterface,
+} from '../interfaces/index.ts'
+
+export interface XyoViewerMethods extends AccountBalanceViewInterface, TransferBalanceViewInterface,
+  NetworkStakeStepRewardViewInterface,
+  ChainViewInterface, BlockViewInterface, TransactionViewInterface, StakeViewer, ForkViewer {
+}
+
+export interface XyoViewer extends XyoViewerMethods {
+  networkStakeViewer?: NetworkStakeViewer
+}