@human-protocol/sdk 2.1.2 → 3.0.0

package/src/kvstore.ts

@@ -16,8 +16,12 @@ import {
   ErrorProviderDoesNotExist,
   ErrorUnsupportedChainID,
 } from './error';
+import gqlFetch from 'graphql-request';
 import { NetworkData } from './types';
-import { isValidUrl } from './utils';
+import { getSubgraphUrl, isValidUrl } from './utils';
+import { GET_KVSTORE_BY_ADDRESS_QUERY } from './graphql/queries/kvstore';
+import { KVStoreData } from './graphql';
+import { IKVStore } from './interfaces';
 /**
  * ## Introduction
  *
@@ -410,3 +414,112 @@ export class KVStoreClient extends BaseEthersClient {
     return publicKey;
   }
 }
+
+/**
+ * ## Introduction
+ *
+ * Utility class for KVStore-related operations.
+ *
+ * ## Installation
+ *
+ * ### npm
+ * ```bash
+ * npm install @human-protocol/sdk
+ * ```
+ *
+ * ### yarn
+ * ```bash
+ * yarn install @human-protocol/sdk
+ * ```
+ *
+ * ## Code example
+ *
+ * ### Signer
+ *
+ * **Using private key (backend)**
+ *
+ * ```ts
+ * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
+ *
+ * const KVStoreAddresses = new KVStoreUtils.getData({
+ *   networks: [ChainId.POLYGON_AMOY]
+ * });
+ * ```
+ */
+export class KVStoreUtils {
+  /**
+   * This function returns the KVStore data for a given address.
+   *
+   * > This uses Subgraph
+   *
+   * **Input parameters**
+   *
+   * ```ts
+   * enum ChainId {
+   *   ALL = -1,
+   *   MAINNET = 1,
+   *   RINKEBY = 4,
+   *   GOERLI = 5,
+   *   BSC_MAINNET = 56,
+   *   BSC_TESTNET = 97,
+   *   POLYGON = 137,
+   *   POLYGON_MUMBAI = 80001,
+   *   POLYGON_AMOY = 80002,
+   *   MOONBEAM = 1284,
+   *   MOONBASE_ALPHA = 1287,
+   *   AVALANCHE = 43114,
+   *   AVALANCHE_TESTNET = 43113,
+   *   CELO = 42220,
+   *   CELO_ALFAJORES = 44787,
+   *   LOCALHOST = 1338,
+   * }
+   * ```
+   *
+   * ```ts
+   * interface IKVStore {
+   *   key: string;
+   *   value: string;
+   * }
+   * ```
+   *
+   * @param {ChainId} chainId Network in which the KVStore is deployed
+   * @param {string} address Address of the KVStore
+   * @returns {Promise<IKVStore[]>} KVStore data
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
+   *
+   * const kvStoreData = await KVStoreUtils.getKVStoreData(ChainId.POLYGON_AMOY, "0x1234567890123456789012345678901234567890");
+   * console.log(kvStoreData);
+   * ```
+   */
+  public static async getKVStoreData(
+    chainId: ChainId,
+    address: string
+  ): Promise<IKVStore[]> {
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    if (address && !ethers.isAddress(address)) {
+      throw ErrorInvalidAddress;
+    }
+
+    const { kvstores } = await gqlFetch<{ kvstores: KVStoreData[] }>(
+      getSubgraphUrl(networkData),
+      GET_KVSTORE_BY_ADDRESS_QUERY(),
+      { address: address.toLowerCase() }
+    );
+
+    const kvStoreData = kvstores.map((item) => ({
+      key: item.key,
+      value: item.value,
+    }));
+
+    return kvStoreData || [];
+  }
+}

package/src/operator.ts

@@ -2,9 +2,10 @@
 import gqlFetch from 'graphql-request';
 import {
   ILeader,
+  ILeaderSubgraph,
   ILeadersFilter,
   IOperator,
-  IReputationNetwork,
+  IReputationNetworkSubgraph,
   IReward,
 } from './interfaces';
 import { GET_REWARD_ADDED_EVENTS_QUERY } from './graphql/queries/reward';
@@ -20,7 +21,7 @@ import {
   ErrorInvalidStakerAddressProvided,
   ErrorUnsupportedChainID,
 } from './error';
-import { throwError } from './utils';
+import { getSubgraphUrl, throwError } from './utils';
 import { ChainId } from './enums';
 import { NETWORKS } from './constants';
 
@@ -55,12 +56,23 @@ export class OperatorUtils {
 
     try {
       const { leader } = await gqlFetch<{
-        leader: ILeader;
-      }>(networkData.subgraphUrl, GET_LEADER_QUERY, {
+        leader: ILeaderSubgraph;
+      }>(getSubgraphUrl(networkData), GET_LEADER_QUERY, {
         address: address.toLowerCase(),
       });
 
-      return leader;
+      let jobTypes: string[] = [];
+
+      if (typeof leader.jobTypes === 'string') {
+        jobTypes = leader.jobTypes.split(',');
+      } else if (Array.isArray(leader.jobTypes)) {
+        jobTypes = leader.jobTypes;
+      }
+
+      return {
+        ...leader,
+        jobTypes,
+      };
     } catch (e) {
       return throwError(e);
     }
@@ -78,28 +90,48 @@ export class OperatorUtils {
    * ```ts
    * import { OperatorUtils } from '@human-protocol/sdk';
    *
-   * const leaders = await OperatorUtils.getLeaders();
+   * const filter: ILeadersFilter = {
+   *  chainId: ChainId.POLYGON
+   * };
+   * const leaders = await OperatorUtils.getLeaders(filter);
    * ```
    */
-  public static async getLeaders(
-    filter: ILeadersFilter = { networks: [ChainId.POLYGON_AMOY] }
-  ): Promise<ILeader[]> {
+  public static async getLeaders(filter: ILeadersFilter): Promise<ILeader[]> {
     try {
       let leaders_data: ILeader[] = [];
-      for (const chainId of filter.networks) {
-        const networkData = NETWORKS[chainId];
 
-        if (!networkData) {
-          throw ErrorUnsupportedChainID;
-        }
-        const { leaders } = await gqlFetch<{
-          leaders: ILeader[];
-        }>(networkData.subgraphUrl, GET_LEADERS_QUERY(filter), {
-          role: filter.role,
-        });
-        leaders_data = leaders_data.concat(leaders);
+      const networkData = NETWORKS[filter.chainId];
+
+      if (!networkData) {
+        throw ErrorUnsupportedChainID;
+      }
+
+      const { leaders } = await gqlFetch<{
+        leaders: ILeaderSubgraph[];
+      }>(getSubgraphUrl(networkData), GET_LEADERS_QUERY(filter), {
+        role: filter?.role,
+      });
+
+      if (!leaders) {
+        return [];
       }
 
+      leaders_data = leaders_data.concat(
+        leaders.map((leader) => {
+          let jobTypes: string[] = [];
+
+          if (typeof leader.jobTypes === 'string') {
+            jobTypes = leader.jobTypes.split(',');
+          } else if (Array.isArray(leader.jobTypes)) {
+            jobTypes = leader.jobTypes;
+          }
+
+          return {
+            ...leader,
+            jobTypes,
+          };
+        })
+      );
       return leaders_data;
     } catch (e) {
       return throwError(e);
@@ -132,13 +164,26 @@ export class OperatorUtils {
     }
     try {
       const { reputationNetwork } = await gqlFetch<{
-        reputationNetwork: IReputationNetwork;
-      }>(networkData.subgraphUrl, GET_REPUTATION_NETWORK_QUERY(role), {
+        reputationNetwork: IReputationNetworkSubgraph;
+      }>(getSubgraphUrl(networkData), GET_REPUTATION_NETWORK_QUERY(role), {
         address: address.toLowerCase(),
         role: role,
       });
 
-      return reputationNetwork.operators;
+      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 {
+          ...operator,
+          jobTypes,
+        };
+      });
     } catch (e) {
       return throwError(e);
     }
@@ -175,7 +220,7 @@ export class OperatorUtils {
     try {
       const { rewardAddedEvents } = await gqlFetch<{
         rewardAddedEvents: RewardAddedEventData[];
-      }>(networkData.subgraphUrl, GET_REWARD_ADDED_EVENTS_QUERY, {
+      }>(getSubgraphUrl(networkData), GET_REWARD_ADDED_EVENTS_QUERY, {
         slasherAddress: slasherAddress.toLowerCase(),
       });
 

package/src/statistics.ts

@@ -18,7 +18,7 @@ import {
 } from './graphql';
 import { IStatisticsParams } from './interfaces';
 import { NetworkData } from './types';
-import { throwError } from './utils';
+import { getSubgraphUrl, throwError } from './utils';
 
 /**
  * ## Introduction
@@ -59,6 +59,7 @@ import { throwError } from './utils';
  */
 export class StatisticsClient {
   public networkData: NetworkData;
+  public subgraphUrl: string;
 
   /**
    * **StatisticsClient constructor**
@@ -67,6 +68,7 @@ export class StatisticsClient {
    */
   constructor(networkData: NetworkData) {
     this.networkData = networkData;
+    this.subgraphUrl = getSubgraphUrl(networkData);
   }
 
   /**
@@ -124,11 +126,11 @@ export class StatisticsClient {
     try {
       const { escrowStatistics } = await gqlFetch<{
         escrowStatistics: EscrowStatisticsData;
-      }>(this.networkData.subgraphUrl, GET_ESCROW_STATISTICS_QUERY);
+      }>(this.subgraphUrl, GET_ESCROW_STATISTICS_QUERY);
 
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
-      }>(this.networkData.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
+      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
         from: params.from ? params.from.getTime() / 1000 : undefined,
         to: params.to ? params.to.getTime() / 1000 : undefined,
       });
@@ -199,7 +201,7 @@ export class StatisticsClient {
     try {
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
-      }>(this.networkData.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
+      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
         from: params.from ? params.from.getTime() / 1000 : undefined,
         to: params.to ? params.to.getTime() / 1000 : undefined,
       });
@@ -288,7 +290,7 @@ export class StatisticsClient {
     try {
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
-      }>(this.networkData.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
+      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
         from: params.from ? params.from.getTime() / 1000 : undefined,
         to: params.to ? params.to.getTime() / 1000 : undefined,
       });
@@ -397,15 +399,15 @@ export class StatisticsClient {
     try {
       const { hmtokenStatistics } = await gqlFetch<{
         hmtokenStatistics: HMTStatisticsData;
-      }>(this.networkData.subgraphUrl, GET_HMTOKEN_STATISTICS_QUERY);
+      }>(this.subgraphUrl, GET_HMTOKEN_STATISTICS_QUERY);
 
       const { holders } = await gqlFetch<{
         holders: HMTHolderData[];
-      }>(this.networkData.subgraphUrl, GET_HOLDERS_QUERY);
+      }>(this.subgraphUrl, GET_HOLDERS_QUERY);
 
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
-      }>(this.networkData.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
+      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
         from: params.from ? params.from.getTime() / 1000 : undefined,
         to: params.to ? params.to.getTime() / 1000 : undefined,
       });

package/src/transaction.ts

@@ -0,0 +1,142 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ethers } from 'ethers';
+import gqlFetch from 'graphql-request';
+import { NETWORKS } from './constants';
+import { ChainId } from './enums';
+import {
+  ErrorCannotUseDateAndBlockSimultaneously,
+  ErrorInvalidHahsProvided,
+  ErrorUnsupportedChainID,
+} from './error';
+import {
+  GET_TRANSACTIONS_QUERY,
+  GET_TRANSACTION_QUERY,
+} from './graphql/queries/transaction';
+import { ITransaction, ITransactionsFilter } from './interfaces';
+import { getSubgraphUrl } from './utils';
+
+export class TransactionUtils {
+  /**
+   * This function returns the transaction data for the given hash.
+   *
+   * @param {ChainId} chainId The chain ID.
+   * @param {string} hash The transaction hash.
+   * @returns {Promise<ITransaction>} Returns the transaction details.
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { TransactionUtils, ChainId } from '@human-protocol/sdk';
+   *
+   * const transaction = await TransactionUtils.getTransaction(ChainId.POLYGON, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * ```
+   */
+  public static async getTransaction(
+    chainId: ChainId,
+    hash: string
+  ): Promise<ITransaction> {
+    if (!ethers.isHexString(hash)) {
+      throw ErrorInvalidHahsProvided;
+    }
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    const { transaction } = await gqlFetch<{
+      transaction: ITransaction;
+    }>(getSubgraphUrl(networkData), GET_TRANSACTION_QUERY, {
+      hash: hash.toLowerCase(),
+    });
+
+    return transaction;
+  }
+
+  /**
+   * This function returns all transaction details based on the provided filter.
+   *
+   * > This uses Subgraph
+   *
+   * **Input parameters**
+   *
+   * ```ts
+   * interface ITransactionsFilter {
+   *   networks: ChainId[]; // List of chain IDs to query.
+   *   fromAddress?: string; // (Optional) The address from which transactions are sent.
+   *   toAddress?: string; // (Optional) The address to which transactions are sent.
+   *   startDate?: Date; // (Optional) The start date to filter transactions (inclusive).
+   *   endDate?: Date; // (Optional) The end date to filter transactions (inclusive).
+   *   startBlock?: number; // (Optional) The start block number to filter transactions (inclusive).
+   *   endBlock?: number; // (Optional) The end block number to filter transactions (inclusive).
+   * }
+   * ```
+   *
+   * ```ts
+   * type ITransaction = {
+   *   block: number;
+   *   txHash: string;
+   *   from: string;
+   *   to: string;
+   *   timestamp: number;
+   *   value: string;
+   *   method: string;
+   * };
+   * ```
+   *
+   * @param {ITransactionsFilter} filter Filter for the transactions.
+   * @returns {Promise<ITransaction[]>} Returns an array with all the transaction details.
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { TransactionUtils, ChainId } from '@human-protocol/sdk';
+   *
+   * const filter: ITransactionsFilter = {
+   *   networks: [ChainId.POLYGON],
+   *   startDate: new Date('2022-01-01'),
+   *   endDate: new Date('2022-12-31')
+   * };
+   * const transactions = await TransactionUtils.getTransactions(filter);
+   * ```
+   */
+  public static async getTransactions(
+    filter: ITransactionsFilter
+  ): Promise<ITransaction[]> {
+    if (
+      (!!filter.startDate || !!filter.endDate) &&
+      (!!filter.startBlock || !!filter.endBlock)
+    ) {
+      throw ErrorCannotUseDateAndBlockSimultaneously;
+    }
+
+    const transactions_data: ITransaction[] = [];
+    for (const chainId of filter.networks) {
+      const networkData = NETWORKS[chainId];
+      if (!networkData) {
+        throw ErrorUnsupportedChainID;
+      }
+      const { transactions } = await gqlFetch<{
+        transactions: ITransaction[];
+      }>(getSubgraphUrl(networkData), GET_TRANSACTIONS_QUERY(filter), {
+        fromAddress: filter?.fromAddress,
+        toAddress: filter?.toAddress,
+        startDate: filter?.startDate
+          ? Math.floor(filter?.startDate.getTime() / 1000)
+          : undefined,
+        endDate: filter.endDate
+          ? Math.floor(filter.endDate.getTime() / 1000)
+          : undefined,
+        startBlock: filter.startBlock ? filter.startBlock : undefined,
+        endBlock: filter.endBlock ? filter.endBlock : undefined,
+      });
+
+      if (!transactions) {
+        continue;
+      }
+
+      transactions_data.push(...transactions);
+    }
+    return transactions_data;
+  }
+}

package/src/types.ts

@@ -127,6 +127,10 @@ export type NetworkData = {
    * Subgraph URL
    */
   subgraphUrl: string;
+  /**
+   * Subgraph URL
+   */
+  subgraphUrlApiKey: string;
   /**
    * Old subgraph URL
    */

package/src/utils.ts

@@ -9,7 +9,10 @@ import {
   NumericFault,
   ReplacementUnderpriced,
   TransactionReplaced,
+  WarnSubgraphApiKeyNotProvided,
 } from './error';
+import { NetworkData } from './types';
+import { SUBGRAPH_API_KEY_PLACEHOLDER } from './constants';
 
 /**
  * **Handle and throw the error.*
@@ -49,3 +52,25 @@ export const isValidUrl = (url: string) => {
     return false;
   }
 };
+
+/**
+ * **Get the subgraph URL.*
+ *
+ * @param {NetworkData} networkData
+ * @param {string} apiKey
+ * @returns
+ */
+export const getSubgraphUrl = (networkData: NetworkData) => {
+  let subgraphUrl = networkData.subgraphUrl;
+  if (process.env.SUBGRAPH_API_KEY) {
+    subgraphUrl = networkData.subgraphUrlApiKey.replace(
+      SUBGRAPH_API_KEY_PLACEHOLDER,
+      process.env.SUBGRAPH_API_KEY
+    );
+  } else {
+    // eslint-disable-next-line no-console
+    console.warn(WarnSubgraphApiKeyNotProvided);
+  }
+
+  return subgraphUrl;
+};