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

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/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,13 @@
+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 './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/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/model/index.ts

@@ -4,5 +4,6 @@ export * from './ChainIdentity.ts'
 export * from './ChainStake/index.ts'
 export * from './ChainStore.ts'
 export * from './PayloadMap.ts'
+export * from './RecordKeyType.ts'
 export * from './StakeEvents.ts'
 export * from './summary.ts'

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

@@ -0,0 +1,14 @@
+import type { Hash } from '@xylabs/hex'
+import type { Payload } from '@xyo-network/payload-model'
+
+import type { MapType } from '../map/index.ts'
+
+export type DataLakeData = Payload | ArrayBuffer
+
+export type DataLakeViewerMethods = Pick<MapType<Hash, DataLakeData>, 'get' | 'getMany' | 'has'>
+
+export interface DataLakeViewer extends DataLakeViewerMethods {}
+
+export type DataLakeRunnerMethods = Pick<MapType<Hash, DataLakeData>, 'set' | 'delete' | 'clear'>
+
+export interface DataLakeRunner extends DataLakeViewerMethods, DataLakeRunnerMethods {}

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,54 @@
+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 { DataLakeRunner, DataLakeViewer } from './DataLake.ts'
+// eslint-disable-next-line sonarjs/deprecation
+import type { TransactionSubmitter } from './TransactionSubmitter.ts'
+import type { NetworkStakeViewer, XyoViewer } from './viewer/index.ts'
+import type { XyoNetwork } from './XyoNetwork.ts'
+import type { XyoRunner } from './XyoRunner.ts'
+import type { XyoSigner } from './XyoSigner.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?: DataLakeRunner | DataLakeViewer | (DataLakeRunner & DataLakeViewer)
+  viewer?: XyoViewer
+}
+
+/** @deprecated use XyoConnectionProvider */
+export interface XyoConnectionProvider extends XyoConnection {}
+
+/** @deprecated use XyoConnectionProvider */
+export interface XyoProvider extends XyoConnection {}

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

@@ -0,0 +1,15 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+import type { ChainId } from '@xyo-network/xl1-protocol'
+
+/** @deprecated  - use XyoClient instead */
+export interface XyoWallet {
+  accounts(): Promisable<Address[]>
+  addChain(chain: ChainId, name?: string): Promisable<object>
+  chain(): Promisable<ChainId>
+  chains(): Promisable<object>
+  permissions(): Promisable<Record<string, object>>
+  requestPermissions(permissions: object): Promisable<object>
+  revokePermissions(permissions: object): Promisable<object>
+  switchChain(chain: ChainId): Promisable<void>
+}

package/src/provider/index.ts

@@ -0,0 +1,12 @@
+export * from './DataLake.ts'
+export * from './permissions/index.ts'
+export * from './TransactionSubmitter.ts'
+export * from './viewer/index.ts'
+export * from './XyoClient.ts'
+export * from './XyoConnection.ts'
+export * from './XyoGateway.ts'
+export * from './XyoGatewayHelpers.ts'
+export * from './XyoNetwork.ts'
+export * from './XyoRunner.ts'
+export * from './XyoSigner.ts'
+export * from './XyoWallet.ts'

package/src/provider/permissions/InvokerPermission.ts

@@ -0,0 +1,56 @@
+import type { JsonValue } from '@xylabs/object'
+
+/**
+ * Modeled after EIP-2255
+ * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+ *
+ * NOTE: In order to send multiple permission requests at once, do not send multiple parentCapability keys.
+ * Instead, send multiple PermissionRequest objects in the params array of the rpc call.
+ */
+export interface PermissionRequest {
+  [parentCapability: string]: {
+    [caveatName: string]: JsonValue
+  }
+}
+
+/**
+ * Modeled after EIP-2255
+ * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+ */
+export interface RequestedPermission {
+  /** Optional timestamp for when the permission was granted */
+  date?: number
+  /** Permission identifier (i.e. RPC method, action, etc.) */
+  parentCapability: string
+}
+
+export type CaveatTypes = 'chain' | 'expiration' | 'filteredResponse' | 'rateLimit' | 'restrictReturnedAccounts'
+
+/**
+ * Modeled after EIP-2255
+ * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+ */
+export interface Caveats {
+  /** Type of caveat */
+  type: CaveatTypes
+  /** Value for the caveat (i.e. chain id, subset of accounts, expiration, max request per minute, etc.) */
+  value: JsonValue
+}
+
+/**
+ * Modeled after EIP-2255
+ * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+ */
+export interface Permission {
+  /** Caveats for the permission, if applicable (i.e. allowed accounts, signing, etc.) */
+  caveats?: Caveats[]
+  /** Invoker for the given permission (URI, domain, webpage, address, etc.) */
+  invoker: string
+  /** Permission identifier (i.e. RPC method, action, etc.) */
+  parentCapability: string
+}
+
+export interface InvokerPermission extends Permission {
+  /** Time at which the permission was granted */
+  date?: number
+}

package/src/provider/permissions/XyoPermissions.ts

@@ -0,0 +1,40 @@
+import type {
+  InvokerPermission, PermissionRequest, RequestedPermission,
+} from './InvokerPermission.ts'
+
+/**
+ * Handles Getting Permissions
+ */
+export interface PermissionsGetHandler {
+  /**
+   * Returns the permissions that are currently granted
+   *
+   * Per the spec - "The wallet_getPermissions method is used for getting an array of current permissions
+   * (empty by default). It takes no parameters and returns an array of Permission objects."
+   *
+   * See - https://eips.ethereum.org/EIPS/eip-2255#specification
+   */
+  getPermissions(): Promise<InvokerPermission[]>
+}
+
+/**
+ * Handles Permission Requests
+ */
+export interface PermissionRequestsHandler {
+  // Given a permissions request, attempts to request the permissions from the user
+  requestPermissions(permissions: PermissionRequest[]): Promise<RequestedPermission[]>
+  // Given a permissions request, attempts to revoke the permissions from the user
+  revokePermissions(permissions: PermissionRequest): Promise<RequestedPermission[]>
+}
+
+/**
+ * Interface for getting, requesting and revoking permissions
+ *
+ * See - https://eips.ethereum.org/EIPS/eip-2255
+ */
+export interface XyoPermissions extends PermissionsGetHandler, PermissionRequestsHandler {
+
+}
+
+// @deprecated - use XyoPermissions instead
+export interface PermissionsProvider extends XyoPermissions {}

package/src/provider/permissions/index.ts

@@ -0,0 +1,2 @@
+export * from './InvokerPermission.ts'
+export * from './XyoPermissions.ts'