@human-protocol/sdk 4.2.0 → 5.0.0-beta.0

package/src/graphql/queries/escrow.ts

@@ -1,5 +1,5 @@
 import gql from 'graphql-tag';
-import { IEscrowsFilter } from '../../interfaces';
+import { ICancellationRefundFilter, IEscrowsFilter } from '../../interfaces';
 
 const ESCROW_FRAGMENT = gql`
   fragment EscrowFields on Escrow {
@@ -25,6 +25,18 @@ const ESCROW_FRAGMENT = gql`
   }
 `;
 
+const CANCELLATION_REFUND_FRAGMENT = gql`
+  fragment CancellationRefundFields on CancellationRefundEvent {
+    id
+    escrowAddress
+    receiver
+    amount
+    block
+    timestamp
+    txHash
+  }
+`;
+
 export const GET_ESCROW_BY_ADDRESS_QUERY = () => gql`
   query getEscrowByAddress($escrowAddress: String!) {
     escrow(id: $escrowAddress) {
@@ -124,3 +136,42 @@ export const GET_STATUS_UPDATES_QUERY = (
     }
   `;
 };
+
+export const GET_CANCELLATION_REFUNDS_QUERY = (
+  filter: ICancellationRefundFilter
+) => gql`
+  query CancellationRefundEvents(
+    $escrowAddress: Bytes
+    $receiver: Bytes
+    $from: Int
+    $to: Int
+    $first: Int
+    $skip: Int
+    $orderDirection: OrderDirection
+  ) {
+    cancellationRefundEvents(
+      where: {
+        ${filter.escrowAddress ? 'escrowAddress: $escrowAddress' : ''}
+        ${filter.receiver ? 'receiver: $receiver' : ''}
+        ${filter.from ? 'timestamp_gte: $from' : ''}
+        ${filter.to ? 'timestamp_lte: $to' : ''}
+      }
+      first: $first
+      skip: $skip
+      orderBy: timestamp
+      orderDirection: $orderDirection
+    ) {
+      ...CancellationRefundFields
+    }
+  }
+  ${CANCELLATION_REFUND_FRAGMENT}
+`;
+
+export const GET_CANCELLATION_REFUND_BY_ADDRESS_QUERY = () => gql`
+  query getCancellationRefundByAddress($escrowAddress: String!) {
+    cancellationRefundEvents(where: { escrowAddress: $escrowAddress }) {
+      ...CancellationRefundFields
+    }
+  }
+  ${CANCELLATION_REFUND_FRAGMENT}
+`;

package/src/graphql/queries/operator.ts

@@ -5,12 +5,6 @@ const LEADER_FRAGMENT = gql`
   fragment OperatorFields on Operator {
     id
     address
-    amountStaked
-    amountLocked
-    lockedUntilTimestamp
-    amountWithdrawn
-    amountSlashed
-    reward
     amountJobsProcessed
     role
     fee
@@ -24,22 +18,30 @@ const LEADER_FRAGMENT = gql`
     reputationNetworks
     name
     category
+    staker {
+      stakedAmount
+      lockedAmount
+      withdrawnAmount
+      slashedAmount
+      lockedUntilTimestamp
+      lastDepositTimestamp
+    }
   }
 `;
 
 export const GET_LEADERS_QUERY = (filter: IOperatorsFilter) => {
-  const { roles, minAmountStaked } = filter;
+  const { roles, minStakedAmount } = filter;
 
   const WHERE_CLAUSE = `
     where: {
-      ${minAmountStaked ? `amountStaked_gte: $minAmountStaked` : ''}
+      ${minStakedAmount ? `staker_: { stakedAmount_gte: $minStakedAmount }` : ''}
       ${roles ? `role_in: $roles` : ''}
     }
   `;
 
   return gql`
     query getOperators(
-      $minAmountStaked: Int,
+      $minStakedAmount: Int,
       $roles: [String!]
       $first: Int
       $skip: Int

package/src/graphql/queries/staking.ts

@@ -0,0 +1,80 @@
+import gql from 'graphql-tag';
+import { IStakersFilter } from '../../interfaces';
+
+const STAKER_FRAGMENT = gql`
+  fragment StakerFields on Staker {
+    id
+    address
+    stakedAmount
+    lockedAmount
+    withdrawnAmount
+    slashedAmount
+    lockedUntilTimestamp
+    lastDepositTimestamp
+  }
+`;
+
+export const GET_STAKERS_QUERY = (filter: IStakersFilter) => {
+  const {
+    minStakedAmount,
+    maxStakedAmount,
+    minLockedAmount,
+    maxLockedAmount,
+    minWithdrawnAmount,
+    maxWithdrawnAmount,
+    minSlashedAmount,
+    maxSlashedAmount,
+  } = filter;
+
+  const whereFields = [
+    minStakedAmount ? `stakedAmount_gte: $minStakedAmount` : '',
+    maxStakedAmount ? `stakedAmount_lte: $maxStakedAmount` : '',
+    minLockedAmount ? `lockedAmount_gte: $minLockedAmount` : '',
+    maxLockedAmount ? `lockedAmount_lte: $maxLockedAmount` : '',
+    minWithdrawnAmount ? `withdrawnAmount_gte: $minWithdrawnAmount` : '',
+    maxWithdrawnAmount ? `withdrawnAmount_lte: $maxWithdrawnAmount` : '',
+    minSlashedAmount ? `slashedAmount_gte: $minSlashedAmount` : '',
+    maxSlashedAmount ? `slashedAmount_lte: $maxSlashedAmount` : '',
+  ].filter(Boolean);
+
+  const WHERE_CLAUSE = whereFields.length
+    ? `where: { ${whereFields.join(', ')} }`
+    : '';
+
+  return gql`
+    query getStakers(
+      $minStakedAmount: BigInt
+      $maxStakedAmount: BigInt
+      $minLockedAmount: BigInt
+      $maxLockedAmount: BigInt
+      $minWithdrawnAmount: BigInt
+      $maxWithdrawnAmount: BigInt
+      $minSlashedAmount: BigInt
+      $maxSlashedAmount: BigInt
+      $orderBy: String
+      $orderDirection: OrderDirection
+      $first: Int
+      $skip: Int
+    ) {
+      stakers(
+        ${WHERE_CLAUSE}
+        orderBy: $orderBy
+        orderDirection: $orderDirection
+        first: $first
+        skip: $skip
+      ) {
+        ...StakerFields
+      }
+    }
+    ${STAKER_FRAGMENT}
+  `;
+};
+
+export const GET_STAKER_BY_ADDRESS_QUERY = gql`
+  query getStaker($id: String!) {
+    staker(id: $id) {
+      ...StakerFields
+    }
+  }
+  ${STAKER_FRAGMENT}
+`;

package/src/index.ts

@@ -1,4 +1,4 @@
-import { StakingClient } from './staking';
+import { StakingClient, StakingUtils } from './staking';
 import { StorageClient } from './storage';
 import { KVStoreClient, KVStoreUtils } from './kvstore';
 import { EscrowClient, EscrowUtils } from './escrow';
@@ -26,4 +26,5 @@ export {
   OperatorUtils,
   TransactionUtils,
   WorkerUtils,
+  StakingUtils,
 };

package/src/interfaces.ts

@@ -10,12 +10,11 @@ export interface IOperator {
   id: string;
   chainId: ChainId;
   address: string;
-  amountStaked: bigint;
-  amountLocked: bigint;
+  stakedAmount: bigint;
+  lockedAmount: bigint;
   lockedUntilTimestamp: bigint;
-  amountWithdrawn: bigint;
-  amountSlashed: bigint;
-  reward: bigint;
+  withdrawnAmount: bigint;
+  slashedAmount: bigint;
   amountJobsProcessed: bigint;
   role?: string;
   fee?: bigint;
@@ -31,16 +30,36 @@ export interface IOperator {
   category?: string;
 }
 
-export interface IOperatorSubgraph
-  extends Omit<IOperator, 'jobTypes' | 'reputationNetworks' | 'chainId'> {
-  jobTypes?: string;
+export interface IOperatorSubgraph {
+  id: string;
+  address: string;
+  amountJobsProcessed: bigint;
+  role?: string;
+  fee?: bigint;
+  publicKey?: string;
+  webhookUrl?: string;
+  website?: string;
+  url?: string;
+  registrationNeeded?: boolean;
+  registrationInstructions?: string;
+  name?: string;
+  category?: string;
+  jobTypes?: string | string[];
   reputationNetworks?: { address: string }[];
+  staker?: {
+    stakedAmount: bigint;
+    lockedAmount: bigint;
+    lockedUntilTimestamp: bigint;
+    withdrawnAmount: bigint;
+    slashedAmount: bigint;
+    lastDepositTimestamp: bigint;
+  };
 }
 
 export interface IOperatorsFilter extends IPagination {
   chainId: ChainId;
   roles?: string[];
-  minAmountStaked?: number;
+  minStakedAmount?: number;
   orderBy?: string;
 }
 
@@ -55,15 +74,6 @@ export interface IReputationNetworkSubgraph
   operators: IOperatorSubgraph[];
 }
 
-export interface IOperator {
-  address: string;
-  role?: string;
-  url?: string;
-  jobTypes?: string[];
-  registrationNeeded?: boolean;
-  registrationInstructions?: string;
-}
-
 export interface IEscrow {
   id: string;
   address: string;
@@ -208,3 +218,38 @@ export interface IWorkersFilter extends IPagination {
   address?: string;
   orderBy?: string;
 }
+
+export interface IStaker {
+  address: string;
+  stakedAmount: bigint;
+  lockedAmount: bigint;
+  lockedUntil: bigint;
+  withdrawableAmount: bigint;
+  slashedAmount: bigint;
+  lastDepositTimestamp: bigint;
+}
+
+export interface IStakersFilter extends IPagination {
+  chainId: ChainId;
+  minStakedAmount?: string;
+  maxStakedAmount?: string;
+  minLockedAmount?: string;
+  maxLockedAmount?: string;
+  minWithdrawnAmount?: string;
+  maxWithdrawnAmount?: string;
+  minSlashedAmount?: string;
+  maxSlashedAmount?: string;
+  orderBy?:
+    | 'stakedAmount'
+    | 'lockedAmount'
+    | 'withdrawnAmount'
+    | 'slashedAmount'
+    | 'lastDepositTimestamp';
+}
+export interface ICancellationRefundFilter extends IPagination {
+  chainId: ChainId;
+  escrowAddress?: string;
+  receiver?: string;
+  from?: Date;
+  to?: Date;
+}

package/src/operator.ts

@@ -60,33 +60,10 @@ export class OperatorUtils {
     });
 
     if (!operator) {
-      return (operator as IOperator) || null;
+      return null as any;
     }
 
-    let jobTypes: string[] = [];
-    let reputationNetworks: string[] = [];
-
-    if (typeof operator.jobTypes === 'string') {
-      jobTypes = operator.jobTypes.split(',');
-    } else if (Array.isArray(operator.jobTypes)) {
-      jobTypes = operator.jobTypes;
-    }
-
-    if (
-      operator.reputationNetworks &&
-      Array.isArray(operator.reputationNetworks)
-    ) {
-      reputationNetworks = operator.reputationNetworks.map(
-        (network) => network.address
-      );
-    }
-
-    return {
-      ...operator,
-      jobTypes,
-      reputationNetworks,
-      chainId,
-    };
+    return mapOperator(operator, chainId);
   }
 
   /**
@@ -109,8 +86,6 @@ export class OperatorUtils {
   public static async getOperators(
     filter: IOperatorsFilter
   ): Promise<IOperator[]> {
-    let operators_data: IOperator[] = [];
-
     const first =
       filter.first !== undefined && filter.first > 0
         ? Math.min(filter.first, 1000)
@@ -119,6 +94,15 @@ export class OperatorUtils {
       filter.skip !== undefined && filter.skip >= 0 ? filter.skip : 0;
     const orderDirection = filter.orderDirection || OrderDirection.DESC;
 
+    let orderBy = filter.orderBy;
+    if (filter.orderBy === 'stakedAmount') orderBy = 'staker__stakedAmount';
+    else if (filter.orderBy === 'lockedAmount')
+      orderBy = 'staker__lockedAmount';
+    else if (filter.orderBy === 'withdrawnAmount')
+      orderBy = 'staker__withdrawnAmount';
+    else if (filter.orderBy === 'slashedAmount')
+      orderBy = 'staker__slashedAmount';
+
     const networkData = NETWORKS[filter.chainId];
 
     if (!networkData) {
@@ -128,9 +112,9 @@ export class OperatorUtils {
     const { operators } = await gqlFetch<{
       operators: IOperatorSubgraph[];
     }>(getSubgraphUrl(networkData), GET_LEADERS_QUERY(filter), {
-      minAmountStaked: filter?.minAmountStaked,
+      minStakedAmount: filter?.minStakedAmount,
       roles: filter?.roles,
-      orderBy: filter?.orderBy,
+      orderBy: orderBy,
       orderDirection: orderDirection,
       first: first,
       skip: skip,
@@ -140,35 +124,7 @@ export class OperatorUtils {
       return [];
     }
 
-    operators_data = operators_data.concat(
-      operators.map((operator) => {
-        let jobTypes: string[] = [];
-        let reputationNetworks: string[] = [];
-
-        if (typeof operator.jobTypes === 'string') {
-          jobTypes = operator.jobTypes.split(',');
-        } else if (Array.isArray(operator.jobTypes)) {
-          jobTypes = operator.jobTypes;
-        }
-
-        if (
-          operator.reputationNetworks &&
-          Array.isArray(operator.reputationNetworks)
-        ) {
-          reputationNetworks = operator.reputationNetworks.map(
-            (network) => network.address
-          );
-        }
-
-        return {
-          ...operator,
-          jobTypes,
-          reputationNetworks,
-          chainId: filter.chainId,
-        };
-      })
-    );
-    return operators_data;
+    return operators.map((operator) => mapOperator(operator, filter.chainId));
   }
 
   /**
@@ -206,24 +162,9 @@ export class OperatorUtils {
 
     if (!reputationNetwork) return [];
 
-    return reputationNetwork.operators.map((operator) => {
-      let jobTypes: string[] = [];
-
-      if (typeof operator.jobTypes === 'string') {
-        jobTypes = operator.jobTypes.split(',');
-      } else if (Array.isArray(operator.jobTypes)) {
-        jobTypes = operator.jobTypes;
-      }
-
-      return {
-        chainId,
-        ...operator,
-        jobTypes,
-        reputationNetworks: operator.reputationNetworks?.map(
-          (network) => network.address
-        ),
-      };
-    });
+    return reputationNetwork.operators.map((operator) =>
+      mapOperator(operator, chainId)
+    );
   }
 
   /**
@@ -270,3 +211,48 @@ export class OperatorUtils {
     });
   }
 }
+
+function mapOperator(operator: IOperatorSubgraph, chainId: ChainId): IOperator {
+  const staker = operator?.staker;
+  let jobTypes: string[] = [];
+  let reputationNetworks: string[] = [];
+
+  if (typeof operator.jobTypes === 'string') {
+    jobTypes = operator.jobTypes.split(',');
+  } else if (Array.isArray(operator.jobTypes)) {
+    jobTypes = operator.jobTypes;
+  }
+
+  if (
+    operator.reputationNetworks &&
+    Array.isArray(operator.reputationNetworks)
+  ) {
+    reputationNetworks = operator.reputationNetworks.map(
+      (network) => network.address
+    );
+  }
+
+  return {
+    id: operator.id,
+    chainId,
+    address: operator.address,
+    stakedAmount: BigInt(staker?.stakedAmount || 0),
+    lockedAmount: BigInt(staker?.lockedAmount || 0),
+    lockedUntilTimestamp: BigInt(staker?.lockedUntilTimestamp || 0),
+    withdrawnAmount: BigInt(staker?.withdrawnAmount || 0),
+    slashedAmount: BigInt(staker?.slashedAmount || 0),
+    amountJobsProcessed: BigInt(operator.amountJobsProcessed || 0),
+    role: operator.role,
+    fee: operator.fee ? BigInt(operator.fee) : undefined,
+    publicKey: operator.publicKey,
+    webhookUrl: operator.webhookUrl,
+    website: operator.website,
+    url: operator.url,
+    jobTypes,
+    registrationNeeded: operator.registrationNeeded,
+    registrationInstructions: operator.registrationInstructions,
+    reputationNetworks,
+    name: operator.name,
+    category: operator.category,
+  };
+}

package/src/staking.ts

@@ -7,10 +7,11 @@ import {
   Staking__factory,
 } from '@human-protocol/core/typechain-types';
 import { ContractRunner, Overrides, ethers } from 'ethers';
+import gqlFetch from 'graphql-request';
 import { BaseEthersClient } from './base';
 import { NETWORKS } from './constants';
 import { requiresSigner } from './decorators';
-import { ChainId } from './enums';
+import { ChainId, OrderDirection } from './enums';
 import {
   ErrorEscrowAddressIsNotProvidedByFactory,
   ErrorInvalidEscrowAddressProvided,
@@ -19,11 +20,16 @@ import {
   ErrorInvalidStakingValueSign,
   ErrorInvalidStakingValueType,
   ErrorProviderDoesNotExist,
+  ErrorStakerNotFound,
   ErrorUnsupportedChainID,
 } from './error';
+import { IStaker, IStakersFilter, StakerInfo } from './interfaces';
 import { NetworkData } from './types';
-import { throwError } from './utils';
-import { StakerInfo } from './interfaces';
+import { getSubgraphUrl, throwError } from './utils';
+import {
+  GET_STAKER_BY_ADDRESS_QUERY,
+  GET_STAKERS_QUERY,
+} from './graphql/queries/staking';
 
 /**
  * ## Introduction
@@ -439,6 +445,7 @@ export class StakingClient extends BaseEthersClient {
 
     try {
       const stakerInfo = await this.stakingContract.stakes(stakerAddress);
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       const currentBlock = await this.runner.provider!.getBlockNumber();
 
       const tokensWithdrawable =
@@ -465,3 +472,99 @@ export class StakingClient extends BaseEthersClient {
     }
   }
 }
+
+/**
+ * Utility class for Staking-related subgraph queries.
+ */
+export class StakingUtils {
+  /**
+   * Gets staking info for a staker from the subgraph.
+   *
+   * @param {ChainId} chainId Network in which the staking contract is deployed
+   * @param {string} stakerAddress Address of the staker
+   * @returns {Promise<IStaker>} Staker info from subgraph
+   */
+  public static async getStaker(
+    chainId: ChainId,
+    stakerAddress: string
+  ): Promise<IStaker> {
+    if (!ethers.isAddress(stakerAddress)) {
+      throw ErrorInvalidStakerAddressProvided;
+    }
+
+    const networkData: NetworkData | undefined = NETWORKS[chainId];
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    const { staker } = await gqlFetch<{ staker: IStaker }>(
+      getSubgraphUrl(networkData),
+      GET_STAKER_BY_ADDRESS_QUERY,
+      { id: stakerAddress.toLowerCase() }
+    );
+
+    if (!staker) {
+      throw ErrorStakerNotFound;
+    }
+
+    return staker;
+  }
+
+  /**
+   * Gets all stakers from the subgraph with filters, pagination and ordering.
+   *
+   * @returns {Promise<IStaker[]>} Array of stakers
+   */
+  public static async getStakers(filter: IStakersFilter): Promise<IStaker[]> {
+    const first =
+      filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+    const skip = filter.skip || 0;
+    const orderDirection = filter.orderDirection || OrderDirection.DESC;
+    const orderBy = filter.orderBy || 'lastDepositTimestamp';
+
+    const networkData = NETWORKS[filter.chainId];
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    const { stakers } = await gqlFetch<{ stakers: IStaker[] }>(
+      getSubgraphUrl(networkData),
+      GET_STAKERS_QUERY(filter),
+      {
+        minStakedAmount: filter.minStakedAmount
+          ? filter.minStakedAmount
+          : undefined,
+        maxStakedAmount: filter.maxStakedAmount
+          ? filter.maxStakedAmount
+          : undefined,
+        minLockedAmount: filter.minLockedAmount
+          ? filter.minLockedAmount
+          : undefined,
+        maxLockedAmount: filter.maxLockedAmount
+          ? filter.maxLockedAmount
+          : undefined,
+        minWithdrawnAmount: filter.minWithdrawnAmount
+          ? filter.minWithdrawnAmount
+          : undefined,
+        maxWithdrawnAmount: filter.maxWithdrawnAmount
+          ? filter.maxWithdrawnAmount
+          : undefined,
+        minSlashedAmount: filter.minSlashedAmount
+          ? filter.minSlashedAmount
+          : undefined,
+        maxSlashedAmount: filter.maxSlashedAmount
+          ? filter.maxSlashedAmount
+          : undefined,
+        orderBy: orderBy,
+        orderDirection: orderDirection,
+        first: first,
+        skip: skip,
+      }
+    );
+    if (!stakers) {
+      return [];
+    }
+
+    return stakers;
+  }
+}