@human-protocol/sdk 2.1.3 → 3.0.1

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({
+ *   network: 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

@@ -21,7 +21,7 @@ import {
   ErrorInvalidStakerAddressProvided,
   ErrorUnsupportedChainID,
 } from './error';
-import { throwError } from './utils';
+import { getSubgraphUrl } from './utils';
 import { ChainId } from './enums';
 import { NETWORKS } from './constants';
 
@@ -54,20 +54,28 @@ export class OperatorUtils {
       throw ErrorUnsupportedChainID;
     }
 
-    try {
-      const { leader } = await gqlFetch<{
-        leader: ILeaderSubgraph;
-      }>(networkData.subgraphUrl, GET_LEADER_QUERY, {
-        address: address.toLowerCase(),
-      });
+    const { leader } = await gqlFetch<{
+      leader: ILeaderSubgraph;
+    }>(getSubgraphUrl(networkData), GET_LEADER_QUERY, {
+      address: address.toLowerCase(),
+    });
 
-      return {
-        ...leader,
-        jobTypes: leader.jobTypes?.split(','),
-      };
-    } catch (e) {
-      return throwError(e);
+    if (!leader) {
+      return (leader as ILeader) || null;
+    }
+
+    let jobTypes: string[] = [];
+
+    if (typeof leader.jobTypes === 'string') {
+      jobTypes = leader.jobTypes.split(',');
+    } else if (Array.isArray(leader.jobTypes)) {
+      jobTypes = leader.jobTypes;
     }
+
+    return {
+      ...leader,
+      jobTypes,
+    };
   }
 
   /**
@@ -82,37 +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[]> {
-    try {
-      let leaders_data: ILeader[] = [];
-      for (const chainId of filter.networks) {
-        const networkData = NETWORKS[chainId];
-
-        if (!networkData) {
-          throw ErrorUnsupportedChainID;
-        }
-        const { leaders } = await gqlFetch<{
-          leaders: ILeaderSubgraph[];
-        }>(networkData.subgraphUrl, GET_LEADERS_QUERY(filter), {
-          role: filter.role,
-        });
-        leaders_data = leaders_data.concat(
-          leaders.map((leader) => ({
-            ...leader,
-            jobTypes: leader.jobTypes?.split(','),
-          }))
-        );
-      }
+  public static async getLeaders(filter: ILeadersFilter): Promise<ILeader[]> {
+    let leaders_data: ILeader[] = [];
 
-      return leaders_data;
-    } catch (e) {
-      return throwError(e);
+    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;
   }
 
   /**
@@ -139,21 +158,27 @@ export class OperatorUtils {
     if (!networkData) {
       throw ErrorUnsupportedChainID;
     }
-    try {
-      const { reputationNetwork } = await gqlFetch<{
-        reputationNetwork: IReputationNetworkSubgraph;
-      }>(networkData.subgraphUrl, GET_REPUTATION_NETWORK_QUERY(role), {
-        address: address.toLowerCase(),
-        role: role,
-      });
-
-      return reputationNetwork.operators.map((operator) => ({
+    const { reputationNetwork } = await gqlFetch<{
+      reputationNetwork: IReputationNetworkSubgraph;
+    }>(getSubgraphUrl(networkData), GET_REPUTATION_NETWORK_QUERY(role), {
+      address: address.toLowerCase(),
+      role: role,
+    });
+
+    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: operator.jobTypes?.split(','),
-      }));
-    } catch (e) {
-      return throwError(e);
-    }
+        jobTypes,
+      };
+    });
   }
 
   /**
@@ -184,21 +209,17 @@ export class OperatorUtils {
       throw ErrorUnsupportedChainID;
     }
 
-    try {
-      const { rewardAddedEvents } = await gqlFetch<{
-        rewardAddedEvents: RewardAddedEventData[];
-      }>(networkData.subgraphUrl, GET_REWARD_ADDED_EVENTS_QUERY, {
-        slasherAddress: slasherAddress.toLowerCase(),
-      });
+    const { rewardAddedEvents } = await gqlFetch<{
+      rewardAddedEvents: RewardAddedEventData[];
+    }>(getSubgraphUrl(networkData), GET_REWARD_ADDED_EVENTS_QUERY, {
+      slasherAddress: slasherAddress.toLowerCase(),
+    });
 
-      return rewardAddedEvents.map((reward: any) => {
-        return {
-          escrowAddress: reward.escrow,
-          amount: reward.amount,
-        };
-      });
-    } catch (e) {
-      return throwError(e);
-    }
+    return rewardAddedEvents.map((reward: any) => {
+      return {
+        escrowAddress: reward.escrow,
+        amount: reward.amount,
+      };
+    });
   }
 }

package/src/statistics.ts

@@ -15,10 +15,11 @@ import {
   PaymentStatistics,
   WorkerStatistics,
   HMTHolderData,
+  HMTHolder,
 } from './graphql';
-import { IStatisticsParams } from './interfaces';
+import { IHMTHoldersParams, IStatisticsParams } from './interfaces';
 import { NetworkData } from './types';
-import { throwError } from './utils';
+import { getSubgraphUrl, throwError } from './utils';
 
 /**
  * ## Introduction
@@ -59,6 +60,7 @@ import { throwError } from './utils';
  */
 export class StatisticsClient {
   public networkData: NetworkData;
+  public subgraphUrl: string;
 
   /**
    * **StatisticsClient constructor**
@@ -67,6 +69,7 @@ export class StatisticsClient {
    */
   constructor(networkData: NetworkData) {
     this.networkData = networkData;
+    this.subgraphUrl = getSubgraphUrl(networkData);
   }
 
   /**
@@ -124,11 +127,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 +202,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 +291,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 +400,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,
       });
@@ -426,10 +429,61 @@ export class StatisticsClient {
             eventDayData.dailyHMTTransferAmount
           ),
           totalTransactionCount: +eventDayData.dailyHMTTransferCount,
+          dailyUniqueSenders: +eventDayData.dailyUniqueSenders,
+          dailyUniqueReceivers: +eventDayData.dailyUniqueReceivers,
         })),
       };
     } catch (e: any) {
       return throwError(e);
     }
   }
+
+  /**
+   * This function returns the holders of the HMToken with optional filters and ordering.
+   *
+   * **Input parameters**
+   *
+   * @param {IHMTHoldersParams} params HMT Holders params with filters and ordering
+   * @returns {HMTHolder[]} List of HMToken holders.
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+   *
+   * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
+   *
+   * const hmtHolders = await statisticsClient.getHMTHolders({
+   *   orderDirection: 'asc',
+   * });
+   *
+   * console.log('HMT holders:', hmtHolders.map((h) => ({
+   *   ...h,
+   *   balance: h.balance.toString(),
+   * })));
+   * ```
+   */
+  async getHMTHolders(params: IHMTHoldersParams = {}): Promise<HMTHolder[]> {
+    try {
+      const { address, orderDirection } = params;
+      const query = GET_HOLDERS_QUERY(address);
+
+      const { holders } = await gqlFetch<{ holders: HMTHolderData[] }>(
+        this.subgraphUrl,
+        query,
+        {
+          address,
+          orderBy: 'balance',
+          orderDirection,
+        }
+      );
+
+      return holders.map((holder) => ({
+        address: holder.address,
+        balance: ethers.toBigInt(holder.balance),
+      }));
+    } catch (e: any) {
+      return throwError(e);
+    }
+  }
 }

package/src/transaction.ts

@@ -0,0 +1,152 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ethers } from 'ethers';
+import gqlFetch from 'graphql-request';
+import { NETWORKS } from './constants';
+import { ChainId, OrderDirection } 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 {
+   *   chainId: 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).
+   *   first?: number; // (Optional) Number of transactions per page. Default is 10.
+   *   skip?: number; // (Optional) Number of transactions to skip. Default is 0.
+   *   orderDirection?: OrderDirection; // (Optional) Order of the results. Default is DESC.
+   * }
+   * ```
+   *
+   * ```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, OrderDirection } from '@human-protocol/sdk';
+   *
+   * const filter: ITransactionsFilter = {
+   *   chainId: ChainId.POLYGON,
+   *   startDate: new Date('2022-01-01'),
+   *   endDate: new Date('2022-12-31'),
+   *   first: 10,
+   *   skip: 0,
+   *   orderDirection: OrderDirection.DESC,
+   * };
+   * 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 first =
+      filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+    const skip = filter.skip || 0;
+    const orderDirection = filter.orderDirection || OrderDirection.DESC;
+
+    const networkData = NETWORKS[filter.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,
+      orderDirection: orderDirection,
+      first: first,
+      skip: skip,
+    });
+
+    if (!transactions) {
+      return [];
+    }
+
+    return transactions;
+  }
+}

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