@xyo-network/xl1-protocol 1.11.0 → 1.12.0

package/src/interfaces/Block.ts

@@ -0,0 +1,14 @@
+import type { Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+import type { HydratedBlock } from '../block/index.ts'
+
+export interface BlockInterface {
+  blockByHash(hash: Hash): Promisable<HydratedBlock | null>
+  blockByNumber(blockNumber: number): Promisable<HydratedBlock | null>
+  blocksByHash(hash: Hash, limit?: number): Promisable<HydratedBlock[]>
+
+  currentBlock(): Promisable<HydratedBlock>
+  currentBlockHash(): Promisable<Hash>
+  currentBlockNumber(): Promisable<number>
+}

package/src/interfaces/Chain.ts

@@ -0,0 +1,7 @@
+import type { Promisable } from '@xylabs/promise'
+
+import type { Chain } from '../model.ts'
+
+export interface ChainInterface {
+  chainId(): Promisable<Chain>
+}

package/src/interfaces/ChainContract.ts

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

package/src/interfaces/ChainStake.ts

@@ -0,0 +1,9 @@
+export interface ChainStakeInterface {
+  active(): Promise<bigint>
+  activeByAddressStaked(address: string): Promise<bigint>
+  activeByStaker(address: string): Promise<bigint>
+  pending(): Promise<bigint>
+  pendingByStaker(staker: string): Promise<bigint>
+  withdrawn(): Promise<bigint>
+  withdrawnByStaker(staker: string): Promise<bigint>
+}

package/src/interfaces/Fork.ts

@@ -0,0 +1,9 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+export type ForkHistory = Record<number, Address>
+
+export interface ForkInterface {
+  chainIdAtBlock(blockNumber: number): Promisable<Address>
+  forkHistory(): Promisable<ForkHistory>
+}

package/src/interfaces/NetworkStakeStepReward.ts

@@ -0,0 +1,31 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+export interface NetworkStakeStepAddressReward {
+  claimedRewards(address: Address): Promisable<bigint>
+
+  // the step rewards for a specific network stakers for a given step and block
+  networkStakeStepAddressReward(address: Address, step: number, block: number): Promisable<Record<Address, bigint>>
+
+  // the step rewards for a specific network stakers for all of history
+  networkStakeStepRewardAddressHistory(address: Address): Promisable<Record<Address, bigint>>
+
+  // the shares for a specific network staker for a given step and block
+  networkStakeStepRewardAddressShare(address: Address, step: number, block: number): Promisable<[/* address shares */bigint, /* total shares */bigint]>
+
+  unclaimedRewards(address: Address): Promisable<bigint>
+}
+
+export interface NetworkStakeStepPoolReward {
+
+  // all the shares for all the network stakers for a given step and block
+  networkStakeStepPoolRewardShares(step: number, block: number): Promisable<Record<Address, bigint>>
+
+  // all the step rewards for all the network stakers for a given step and block
+  networkStakeStepPoolRewards(step: number, block: number): Promisable<Record<Address, bigint>>
+}
+
+export interface NetworkStakeStepReward extends NetworkStakeStepPoolReward, NetworkStakeStepAddressReward {
+  // the predictable random number for a given step and block
+  networkStakeStepRewardRandomizer(step: number, block: number): Promisable<bigint>
+}

package/src/interfaces/Stake.ts

@@ -0,0 +1,24 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+export type Stake = {
+  // 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: number
+  // 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
+}
+
+export interface StakeInterface {
+  stakeByAddress(address: Address, slot: number): Promisable<Stake>
+  stakeById(id: number): Promisable<Stake>
+}

package/src/interfaces/StakeTotals.ts

@@ -0,0 +1,26 @@
+import type { Address } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+export interface StakeScope {
+  staked?: Address
+  staker?: Address
+  status?: 'active' | 'pending' | 'withdrawn' | 'all'
+  type?: 'all' | 'network' | 'address'
+}
+
+export interface StakeTotalsInterface {
+  // the total amount that is staked in a given scope
+  stakeAmount(scope?: StakeScope): Promisable<[bigint /* amount */, number /* external block number */]>
+
+  // the total number of stakes in a given scope
+  stakeCount(scope?: StakeScope): Promisable<[number /* amount */, number /* external block number */]>
+
+  // the total number of unique addresses staked in a given scope
+  stakedCount(scope?: StakeScope): Promisable<[number /* amount */, number /* external block number */]>
+
+  // the total number of unique stakers in a given scope
+  stakerCount(scope?: StakeScope): Promisable<[number /* amount */, number /* external block number */]>
+
+  // the total number of unique stake positions in a given scope
+  stakes(scope?: StakeScope): Promisable<[bigint /* amount */, number /* external block number */]>
+}

package/src/interfaces/Transaction.ts

@@ -0,0 +1,10 @@
+import type { Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+import type { SignedHydratedTransaction } from '../transaction/index.ts'
+
+export interface TransactionInterface {
+  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/index.ts

@@ -0,0 +1,10 @@
+export * from './Balance.ts'
+export * from './Block.ts'
+export * from './Chain.ts'
+export * from './ChainContract.ts'
+export * from './ChainStake.ts'
+export * from './Fork.ts'
+export * from './NetworkStakeStepReward.ts'
+export * from './Stake.ts'
+export * from './StakeTotals.ts'
+export * from './Transaction.ts'

package/src/payload/elevatable/TransferPayload.ts

@@ -13,7 +13,7 @@ export type TransferSchema = typeof TransferSchema
 
 export interface TransferFields extends FromFields {
   epoch: number
-  // the amount that is being sent to another address
+  // the amount that is being sent to other addresses
   transfers: Partial<Record<Address, Hex>>
 }
 

package/src/payload/elevatable/TransferRequest.ts

@@ -0,0 +1,28 @@
+import type {
+  Address,
+  Hex,
+} from '@xylabs/hex'
+import { AsObjectFactory } from '@xylabs/object'
+import type { Payload } from '@xyo-network/payload-model'
+import { isPayloadOfSchemaType } from '@xyo-network/payload-model'
+
+import type { FromFields } from './Executable.ts'
+
+export const TransferRequestSchema = 'network.xyo.transfer.request' as const
+export type TransferRequestSchema = typeof TransferRequestSchema
+
+/* The initial use for this is for a network staker to request a transfer from the step reward account to them for the rewards they are owed */
+/* By definition, a request is valid for 1000 blocks following its inclusion in a block or until the request has been filled */
+
+export interface TransferRequestFields extends FromFields {
+  epoch: number
+  // the amount that is requested to be sent to other addresses
+  transfers: Partial<Record<Address, Hex>>
+}
+
+// if this payload is included in a boundwitness, it needs to be available for inspection to be included in block
+export type TransferRequest = Payload<TransferRequestFields, TransferRequestSchema>
+
+export const isTransferRequest = isPayloadOfSchemaType<TransferRequest>(TransferRequestSchema)
+
+export const asTransferRequest = AsObjectFactory.create(isTransferRequest)

package/src/payload/elevatable/index.ts

@@ -2,3 +2,4 @@ export * from './ChainStakeIntent.ts'
 export * from './Executable.ts'
 export * from './Hash.ts'
 export * from './TransferPayload.ts'
+export * from './TransferRequest.ts'

package/src/provider/XyoConnection.ts

@@ -6,7 +6,7 @@ import type { AllowedBlockPayload } from '../block/index.ts'
 import type { TransactionBoundWitness, TransactionFeesBigInt } from '../transaction/index.ts'
 // eslint-disable-next-line sonarjs/deprecation
 import type { TransactionSubmitter } from './TransactionSubmitter.ts'
-import type { XyoDataLakeProvider, XyoDataLakeViewer } from './XyoDataLake.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'
@@ -38,12 +38,15 @@ export interface XyoConnectionProviderDeprecated extends TransactionSubmitter {
 }
 
 // eslint-disable-next-line sonarjs/deprecation
-export interface XyoConnectionProvider extends Partial<XyoConnectionProviderDeprecated> {
+export interface XyoConnection extends Partial<XyoConnectionProviderDeprecated> {
   network?: XyoNetwork
   runner?: XyoRunner
-  storage?: XyoDataLakeProvider | XyoDataLakeViewer
+  storage?: XyoDataLake | XyoDataLakeViewer
   viewer?: XyoViewer
 }
 
 /** @deprecated use XyoConnectionProvider */
-export interface XyoProvider extends XyoConnectionProvider {}
+export interface XyoConnectionProvider extends XyoConnection {}
+
+/** @deprecated use XyoConnectionProvider */
+export interface XyoProvider extends XyoConnection {}

package/src/provider/XyoDataLake.ts

@@ -13,10 +13,14 @@ export interface XyoDataLakeViewer {
   trace(hash: Hash): Promisable<[DataLakeData | undefined, Payload[]]>
 }
 
-export interface XyoDataLakeProvider extends XyoDataLakeViewer {
+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'
@@ -30,10 +34,10 @@ export const isDataLakeViewer = (value: unknown): value is XyoDataLakeViewer =>
   )
 }
 
-export const isDataLakeProvider = (value: unknown): value is XyoDataLakeProvider => {
+export const isDataLakeProvider = (value: unknown): value is XyoDataLake => {
   return (
     isDataLakeViewer(value)
     && 'add' in value
-    && typeof (value as XyoDataLakeProvider).add === 'function'
+    && typeof (value as XyoDataLake).add === 'function'
   )
 }

package/src/provider/XyoGateway.ts

@@ -3,7 +3,7 @@ import type { Promisable } from '@xylabs/promise'
 import type { InvokerPermission, Permission } from './PermissionsProvider.ts'
 // eslint-disable-next-line sonarjs/deprecation
 import type { TransactionSubmitter } from './TransactionSubmitter.ts'
-import type { XyoConnectionProvider } from './XyoConnection.ts'
+import type { XyoConnection } from './XyoConnection.ts'
 import type { XyoGatewayHelpers } from './XyoGatewayHelpers.ts'
 import type { XyoSigner } from './XyoSigner.ts'
 
@@ -18,16 +18,16 @@ export interface XyoGatewayProviderDeprecated extends TransactionSubmitter {
   /**
    * @deprecated use `connection()` instead
    */
-  activeConnection(): Promisable<XyoConnectionProvider | undefined>
+  activeConnection(): Promisable<XyoConnection | undefined>
   /**
    * @deprecated use `connection()` instead
    */
   // eslint-disable-next-line sonarjs/deprecation
-  addConnection(config: XyoConnectionConfigDeprecated): Promisable<XyoConnectionProvider>
+  addConnection(config: XyoConnectionConfigDeprecated): Promisable<XyoConnection>
   /**
    * @deprecated use `connection()` instead
    */
-  connections(): Promisable<Record<string, XyoConnectionProvider>>
+  connections(): Promisable<Record<string, XyoConnection>>
   /**
    * @deprecated Permissions now at Client level
    */
@@ -47,7 +47,7 @@ export interface XyoGatewayProvider extends Partial<XyoGatewayHelpers>, Partial<
   /**
    * Returns the connection provider for this gateway.
    */
-  connection(): Promisable<XyoConnectionProvider>
+  connection(): Promisable<XyoConnection>
   /**
    * Returns the signer for this gateway.
    */

package/src/provider/XyoViewer.ts

@@ -1,26 +1,8 @@
-import type { Address, Hash } from '@xylabs/hex'
-import type { Promisable } from '@xylabs/promise'
-
-import type { HydratedBlock } from '../block/index.ts'
-import type { Chain } from '../model.ts'
-import type { Transfer } from '../payload/index.ts'
-import type { SignedHydratedTransaction } from '../transaction/index.ts'
-
-export interface XyoViewer {
-  accountBalance: (address: Address) => Promisable<bigint>
-  accountHistory: (address: Address) => Promisable<[Hash /* block */, Hash /* transaction */, Transfer][]>
-
-  blockByHash(hash: Hash): Promisable<HydratedBlock | null>
-  blockByNumber(blockNumber: number): Promisable<HydratedBlock | null>
-  blocksByHash(hash: Hash, limit?: number): Promisable<HydratedBlock[]>
-
-  chainId(): Promisable<Chain>
-
-  currentBlock(): Promisable<HydratedBlock>
-  currentBlockHash(): Promisable<Hash>
-  currentBlockNumber(): Promisable<number>
-
-  transactionByBlockHashAndIndex(blockHash: Hash, transactionIndex: number): Promisable<SignedHydratedTransaction | null>
-  transactionByBlockNumberAndIndex(blockNumber: number, transactionIndex: number): Promisable<SignedHydratedTransaction | null>
-  transactionByHash(transactionHash: Hash): Promisable<SignedHydratedTransaction | null>
-}
+import type {
+  BalanceInterface, BlockInterface, ChainInterface,
+  ForkInterface,
+  StakeInterface,
+  TransactionInterface,
+} from '../interfaces/index.ts'
+
+export interface XyoViewer extends BalanceInterface, ChainInterface, BlockInterface, TransactionInterface, StakeInterface, ForkInterface {}

package/src/services/AccountBalanceService.ts

@@ -4,17 +4,19 @@ import type {
 import type { Promisable } from '@xylabs/promise'
 
 import type { AttoXL1 } from '../xl1/index.ts'
-import type { Service } from './Service.ts'
+import type { ServiceInterface } from './Service.ts'
 
-export interface AccountBalanceService extends Service {
-  getBalanceValue?: (address: Address) => bigint
+export interface AccountBalanceProvider {
+  getBalanceValue: (address: Address) => bigint
+}
+
+export interface AccountBalanceService extends AccountBalanceProvider, ServiceInterface {
   getBalanceValues?: Record<Address, bigint>
 
   getBalance(address: Address): Hex
   getBalances(): Record<Address, Hex>
-  sync(head: Hash): Promise<void>
 }
 
-export interface AccountBalanceServiceV2 extends Service {
+export interface AccountBalanceServiceV2 extends ServiceInterface {
   balances(head: Hash, addresses: Address[]): Promisable<Partial<Record<Address, AttoXL1>>>
 }

package/src/services/BlockProducerService.ts

@@ -1,8 +1,8 @@
 import type { BlockBoundWitness, HydratedBlock } from '../block/index.ts'
 import type { Addressable } from '../fields/index.ts'
 import type { IterableRepository } from '../repository/index.ts'
-import type { Service } from './Service.ts'
+import type { ServiceInterface } from './Service.ts'
 
 export type NextBlockProducer = IterableRepository<BlockBoundWitness, HydratedBlock | undefined>
 
-export interface BlockProducerService extends Addressable, NextBlockProducer, Service {}
+export interface BlockProducerService extends Addressable, NextBlockProducer, ServiceInterface {}

package/src/services/BlockRewardService.ts

@@ -1,7 +1,7 @@
 import type { Promisable } from '@xylabs/promise'
 
-import type { Service } from './Service.ts'
+import type { ServiceInterface } from './Service.ts'
 
-export interface BlockRewardService extends Service {
+export interface BlockRewardService extends ServiceInterface {
   getRewardForBlock(block: bigint): Promisable<bigint>
 }

package/src/services/Chain/BaseChainService.ts

@@ -1,6 +1,6 @@
 import type { Chain } from '../../model.ts'
-import type { Service } from '../Service.ts'
+import type { ServiceInterface } from '../Service.ts'
 
-export interface BaseChainService extends Service {
+export interface BaseChainService extends ServiceInterface {
   chainId: Chain
 }

package/src/services/Chain/interfaces/ChainContractViewer.ts

@@ -1,11 +1,5 @@
-import type { Address } from '@xylabs/hex'
+import type { ChainContractInterface } from '../../../interfaces/index.ts'
+
+export interface ChainContractViewer extends ChainContractInterface {
 
-export interface ChainContractViewer {
-  active(): Promise<bigint>
-  forkedAtBlockNumber(): Promise<bigint>
-  forkedAtHash(): Promise<bigint>
-  forkedChainId(): Promise<Address>
-  minWithdrawalBlocks(): Promise<bigint>
-  rewardsContract(): Promise<string>
-  stakingTokenAddress(): Promise<string>
 }

package/src/services/Chain/interfaces/ChainStakeViewer.ts

@@ -1,10 +1,6 @@
+import type { ChainStakeInterface } from '../../../interfaces/index.ts'
 import type { ChainContractViewer } from './ChainContractViewer.ts'
 
-export interface ChainStakeViewer extends ChainContractViewer {
-  activeByAddressStaked(address: string): Promise<bigint>
-  activeByStaker(address: string): Promise<bigint>
-  pending(): Promise<bigint>
-  pendingByStaker(staker: string): Promise<bigint>
-  withdrawn(): Promise<bigint>
-  withdrawnByStaker(staker: string): Promise<bigint>
+export interface ChainStakeViewer extends ChainContractViewer, ChainStakeInterface {
+
 }

package/src/services/Election.ts

@@ -1,9 +1,9 @@
 import type { Address } from '@xylabs/hex'
 
 import type { BlockBoundWitness } from '../block/index.ts'
-import type { Service } from './Service.ts'
+import type { ServiceInterface } from './Service.ts'
 
-export interface ElectionService extends Service {
+export interface ElectionService extends ServiceInterface {
 
   /**
    * Given the current block, get the leader for the next block

package/src/services/PendingTransactionsService.ts

@@ -1,8 +1,8 @@
 import type { Hash } from '@xylabs/hex'
 
 import type { SignedHydratedTransaction } from '../transaction/index.ts'
-import type { Service } from './Service.ts'
+import type { ServiceInterface } from './Service.ts'
 
-export interface PendingTransactionsService extends Service {
+export interface PendingTransactionsService extends ServiceInterface {
   getPendingTransactions(head: Hash, limit: number, timeout?: number): Promise<SignedHydratedTransaction[]>
 }

package/src/services/Service.ts

@@ -1 +1,5 @@
-export interface Service {}
+import type { Hash } from '@xylabs/hex'
+
+export interface ServiceInterface {
+  sync(head: Hash): Promise<void>
+}

package/src/services/StakeIntentService/StakeIntentService.ts

@@ -1,9 +1,9 @@
 import type { Address } from '@xylabs/hex'
 
 import type { Intent } from '../../payload/index.ts'
-import type { Service } from '../Service.ts'
+import type { ServiceInterface } from '../Service.ts'
 
-export interface StakeIntentService extends Service {
+export interface StakeIntentService extends ServiceInterface {
 
   /**
    * Gets the declared ranges for an address based on historical on-chain data