@human-protocol/sdk 3.0.0 → 3.0.2

package/src/statistics.ts

@@ -15,10 +15,13 @@ import {
   PaymentStatistics,
   WorkerStatistics,
   HMTHolderData,
+  HMTHolder,
+  DailyHMTData,
 } from './graphql';
-import { IStatisticsParams } from './interfaces';
+import { IHMTHoldersParams, IStatisticsFilter } from './interfaces';
 import { NetworkData } from './types';
 import { getSubgraphUrl, throwError } from './utils';
+import { OrderDirection } from './enums';
 
 /**
  * ## Introduction
@@ -78,10 +81,12 @@ export class StatisticsClient {
    * **Input parameters**
    *
    * ```ts
-   * interface IStatisticsParams {
+   * interface IStatisticsFilter {
    *   from?: Date;
    *   to?: Date;
-   *   limit?: number;
+   *   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 ASC.
    * }
    * ```
    *
@@ -102,7 +107,7 @@ export class StatisticsClient {
    * ```
    *
    *
-   * @param {IStatisticsParams} params Statistics params with duration data
+   * @param {IStatisticsFilter} filter Statistics params with duration data
    * @returns {EscrowStatistics} Escrow statistics data.
    *
    *
@@ -121,18 +126,26 @@ export class StatisticsClient {
    * ```
    */
   async getEscrowStatistics(
-    params: IStatisticsParams = {}
+    filter: IStatisticsFilter = {}
   ): Promise<EscrowStatistics> {
     try {
+      const first =
+        filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+      const skip = filter.skip || 0;
+      const orderDirection = filter.orderDirection || OrderDirection.ASC;
+
       const { escrowStatistics } = await gqlFetch<{
         escrowStatistics: EscrowStatisticsData;
       }>(this.subgraphUrl, GET_ESCROW_STATISTICS_QUERY);
 
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
-      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
-        from: params.from ? params.from.getTime() / 1000 : undefined,
-        to: params.to ? params.to.getTime() / 1000 : undefined,
+      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(filter), {
+        from: filter.from ? filter.from.getTime() / 1000 : undefined,
+        to: filter.to ? filter.to.getTime() / 1000 : undefined,
+        orderDirection: orderDirection,
+        first: first,
+        skip: skip,
       });
 
       return {
@@ -158,10 +171,12 @@ export class StatisticsClient {
    * **Input parameters**
    *
    * ```ts
-   * interface IStatisticsParams {
+   * interface IStatisticsFilter {
    *   from?: Date;
    *   to?: Date;
-   *   limit?: number;
+   *   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 ASC.
    * }
    * ```
    *
@@ -177,7 +192,7 @@ export class StatisticsClient {
    * ```
    *
    *
-   * @param {IStatisticsParams} params Statistics params with duration data
+   * @param {IStatisticsFilter} filter Statistics params with duration data
    * @returns {WorkerStatistics} Worker statistics data.
    *
    *
@@ -196,14 +211,22 @@ export class StatisticsClient {
    * ```
    */
   async getWorkerStatistics(
-    params: IStatisticsParams = {}
+    filter: IStatisticsFilter = {}
   ): Promise<WorkerStatistics> {
     try {
+      const first =
+        filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+      const skip = filter.skip || 0;
+      const orderDirection = filter.orderDirection || OrderDirection.ASC;
+
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
-      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
-        from: params.from ? params.from.getTime() / 1000 : undefined,
-        to: params.to ? params.to.getTime() / 1000 : undefined,
+      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(filter), {
+        from: filter.from ? filter.from.getTime() / 1000 : undefined,
+        to: filter.to ? filter.to.getTime() / 1000 : undefined,
+        orderDirection: orderDirection,
+        first: first,
+        skip: skip,
       });
 
       return {
@@ -224,10 +247,12 @@ export class StatisticsClient {
    * **Input parameters**
    *
    * ```ts
-   * interface IStatisticsParams {
+   * interface IStatisticsFilter {
    *   from?: Date;
    *   to?: Date;
-   *   limit?: number;
+   *   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 ASC.
    * }
    * ```
    *
@@ -245,7 +270,7 @@ export class StatisticsClient {
    * ```
    *
    *
-   * @param {IStatisticsParams} params Statistics params with duration data
+   * @param {IStatisticsFilter} filter Statistics params with duration data
    * @returns {PaymentStatistics} Payment statistics data.
    *
    *
@@ -285,14 +310,22 @@ export class StatisticsClient {
    * ```
    */
   async getPaymentStatistics(
-    params: IStatisticsParams = {}
+    filter: IStatisticsFilter = {}
   ): Promise<PaymentStatistics> {
     try {
+      const first =
+        filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+      const skip = filter.skip || 0;
+      const orderDirection = filter.orderDirection || OrderDirection.ASC;
+
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
-      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
-        from: params.from ? params.from.getTime() / 1000 : undefined,
-        to: params.to ? params.to.getTime() / 1000 : undefined,
+      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(filter), {
+        from: filter.from ? filter.from.getTime() / 1000 : undefined,
+        to: filter.to ? filter.to.getTime() / 1000 : undefined,
+        orderDirection: orderDirection,
+        first: first,
+        skip: skip,
       });
 
       return {
@@ -316,40 +349,128 @@ export class StatisticsClient {
    * This function returns the statistical data of HMToken.
    *
    *
+   * type HMTStatistics = {
+   *   totalTransferAmount: BigNumber;
+   *   totalTransferCount: BigNumber;
+   *   totalHolders: number;
+   * };
+   * ```
+   *
+   *
+   * @returns {HMTStatistics} HMToken statistics data.
+   *
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+   *
+   * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
+   *
+   * const hmtStatistics = await statisticsClient.getHMTStatistics();
+   *
+   * console.log('HMT statistics:', {
+   *   ...hmtStatistics,
+   *   totalTransferAmount: hmtStatistics.totalTransferAmount.toString(),
+   * });
+   * ```
+   */
+  async getHMTStatistics(): Promise<HMTStatistics> {
+    try {
+      const { hmtokenStatistics } = await gqlFetch<{
+        hmtokenStatistics: HMTStatisticsData;
+      }>(this.subgraphUrl, GET_HMTOKEN_STATISTICS_QUERY);
+
+      return {
+        totalTransferAmount: ethers.toBigInt(
+          hmtokenStatistics.totalValueTransfered
+        ),
+        totalTransferCount: Number(hmtokenStatistics.totalTransferEventCount),
+        totalHolders: +hmtokenStatistics.holders,
+      };
+    } 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
-   * interface IStatisticsParams {
+   * 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);
+    }
+  }
+
+  /**
+   * This function returns the statistical data of HMToken day by day.
+   *
+   *
+   * **Input parameters**
+   *
+   * ```ts
+   * interface IStatisticsFilter {
    *   from?: Date;
    *   to?: Date;
-   *   limit?: number;
+   *   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 ASC.
    * }
    * ```
    *
    * ```ts
-   * type HMTHolder = {
-   *   address: string;
-   *   balance: BigNumber;
-   * }
-   *
    * type DailyHMTData = {
    *   timestamp: Date;
-   *   totalTransactionAmount: BigNumber;
+   *   totalTransactionAmount: bigint;
    *   totalTransactionCount: number;
-   * };
-   *
-   * type HMTStatistics = {
-   *   totalTransferAmount: BigNumber;
-   *   totalTransferCount: BigNumber;
-   *   totalHolders: number;
-   *   holders: HMTHolder[];
-   *   dailyHMTData: DailyHMTData[];
-   * };
+   *   dailyUniqueSenders: number;
+   *   dailyUniqueReceivers: number;
+   * }
    * ```
    *
    *
-   * @param {IStatisticsParams} params Statistics params with duration data
-   * @returns {HMTStatistics} HMToken statistics data.
+   * @param {IStatisticsFilter} filter Statistics params with duration data
+   * @returns {DailyHMTData[]} Daily HMToken statistics data.
    *
    *
    * **Code example**
@@ -359,77 +480,46 @@ export class StatisticsClient {
    *
    * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
    *
-   * const hmtStatistics = await statisticsClient.getHMTStatistics();
+   * const dailyHMTStats = await statisticsClient.getHMTStatistics();
    *
-   * console.log('HMT statistics:', {
-   *   ...hmtStatistics,
-   *   totalTransferAmount: hmtStatistics.totalTransferAmount.toString(),
-   *   holders: hmtStatistics.holders.map((h) => ({
-   *     ...h,
-   *     balance: h.balance.toString(),
-   *   })),
-   *   dailyHMTData: hmtStatistics.dailyHMTData.map((d) => ({
-   *     ...d,
-   *     totalTransactionAmount: d.totalTransactionAmount.toString(),
-   *   })),
-   * });
+   * console.log('Daily HMT statistics:', dailyHMTStats);
    *
    * const hmtStatisticsRange = await statisticsClient.getHMTStatistics({
    *   from: new Date(2023, 4, 8),
    *   to: new Date(2023, 5, 8),
    * });
    *
-   * console.log('HMT statistics from 5/8 - 6/8:', {
-   *   ...hmtStatisticsRange,
-   *   totalTransferAmount: hmtStatisticsRange.totalTransferAmount.toString(),
-   *   holders: hmtStatisticsRange.holders.map((h) => ({
-   *     ...h,
-   *     balance: h.balance.toString(),
-   *   })),
-   *   dailyHMTData: hmtStatisticsRange.dailyHMTData.map((d) => ({
-   *     ...d,
-   *     totalTransactionAmount: d.totalTransactionAmount.toString(),
-   *   })),
-   * });
+   * console.log('HMT statistics from 5/8 - 6/8:', hmtStatisticsRange);
    * ```
    */
-  async getHMTStatistics(
-    params: IStatisticsParams = {}
-  ): Promise<HMTStatistics> {
+  async getHMTDailyData(
+    filter: IStatisticsFilter = {}
+  ): Promise<DailyHMTData[]> {
     try {
-      const { hmtokenStatistics } = await gqlFetch<{
-        hmtokenStatistics: HMTStatisticsData;
-      }>(this.subgraphUrl, GET_HMTOKEN_STATISTICS_QUERY);
-
-      const { holders } = await gqlFetch<{
-        holders: HMTHolderData[];
-      }>(this.subgraphUrl, GET_HOLDERS_QUERY);
+      const first =
+        filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+      const skip = filter.skip || 0;
+      const orderDirection = filter.orderDirection || OrderDirection.ASC;
 
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
-      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(params), {
-        from: params.from ? params.from.getTime() / 1000 : undefined,
-        to: params.to ? params.to.getTime() / 1000 : undefined,
+      }>(this.subgraphUrl, GET_EVENT_DAY_DATA_QUERY(filter), {
+        from: filter.from ? filter.from.getTime() / 1000 : undefined,
+        to: filter.to ? filter.to.getTime() / 1000 : undefined,
+        orderDirection: orderDirection,
+        first: first,
+        skip: skip,
       });
 
-      return {
-        totalTransferAmount: ethers.toBigInt(
-          hmtokenStatistics.totalValueTransfered
+      return eventDayDatas.map((eventDayData) => ({
+        timestamp: new Date(+eventDayData.timestamp * 1000),
+        totalTransactionAmount: ethers.toBigInt(
+          eventDayData.dailyHMTTransferAmount
         ),
-        totalTransferCount: Number(hmtokenStatistics.totalTransferEventCount),
-        totalHolders: +hmtokenStatistics.holders,
-        holders: holders.map((holder) => ({
-          address: holder.address,
-          balance: ethers.toBigInt(holder.balance),
-        })),
-        dailyHMTData: eventDayDatas.map((eventDayData) => ({
-          timestamp: new Date(+eventDayData.timestamp * 1000),
-          totalTransactionAmount: ethers.toBigInt(
-            eventDayData.dailyHMTTransferAmount
-          ),
-          totalTransactionCount: +eventDayData.dailyHMTTransferCount,
-        })),
-      };
+        totalTransactionCount: +eventDayData.dailyHMTTransferCount,
+        dailyUniqueSenders: +eventDayData.dailyUniqueSenders,
+        dailyUniqueReceivers: +eventDayData.dailyUniqueReceivers,
+      }));
     } catch (e: any) {
       return throwError(e);
     }

package/src/transaction.ts

@@ -2,7 +2,7 @@
 import { ethers } from 'ethers';
 import gqlFetch from 'graphql-request';
 import { NETWORKS } from './constants';
-import { ChainId } from './enums';
+import { ChainId, OrderDirection } from './enums';
 import {
   ErrorCannotUseDateAndBlockSimultaneously,
   ErrorInvalidHahsProvided,
@@ -62,13 +62,16 @@ export class TransactionUtils {
    *
    * ```ts
    * interface ITransactionsFilter {
-   *   networks: ChainId[]; // List of chain IDs to query.
+   *   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.
    * }
    * ```
    *
@@ -90,12 +93,15 @@ export class TransactionUtils {
    * **Code example**
    *
    * ```ts
-   * import { TransactionUtils, ChainId } from '@human-protocol/sdk';
+   * import { TransactionUtils, ChainId, OrderDirection } from '@human-protocol/sdk';
    *
    * const filter: ITransactionsFilter = {
-   *   networks: [ChainId.POLYGON],
+   *   chainId: ChainId.POLYGON,
    *   startDate: new Date('2022-01-01'),
-   *   endDate: new Date('2022-12-31')
+   *   endDate: new Date('2022-12-31'),
+   *   first: 10,
+   *   skip: 0,
+   *   orderDirection: OrderDirection.DESC,
    * };
    * const transactions = await TransactionUtils.getTransactions(filter);
    * ```
@@ -110,33 +116,37 @@ export class TransactionUtils {
       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,
-      });
+    const first =
+      filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+    const skip = filter.skip || 0;
+    const orderDirection = filter.orderDirection || OrderDirection.DESC;
 
-      if (!transactions) {
-        continue;
-      }
+    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,
+    });
 
-      transactions_data.push(...transactions);
+    if (!transactions) {
+      return [];
     }
-    return transactions_data;
+
+    return transactions;
   }
 }