@human-protocol/sdk 3.0.0 → 3.0.1

package/src/graphql/queries/hmtoken.ts

@@ -7,11 +7,27 @@ const HOLDER_FRAGMENT = gql`
   }
 `;
 
-export const GET_HOLDERS_QUERY = gql`
-  query GetHolders {
-    holders {
-      ...HolderFields
+export const GET_HOLDERS_QUERY = (address?: string) => {
+  const WHERE_CLAUSE = `
+    where: {
+      ${address ? `address: $address,` : ''}
     }
-  }
-  ${HOLDER_FRAGMENT}
-`;
+  `;
+
+  return gql`
+    query GetHolders(
+      $address: String
+      $orderBy: String
+      $orderDirection: String
+    ) {
+      holders(
+        ${WHERE_CLAUSE}
+        orderBy: $orderBy,
+        orderDirection: $orderDirection
+      ) {
+        ...HolderFields
+      }
+    }
+    ${HOLDER_FRAGMENT}
+  `;
+};

package/src/graphql/queries/statistics.ts

@@ -47,6 +47,8 @@ const EVENT_DAY_DATA_FRAGMENT = gql`
     dailyPayoutAmount
     dailyHMTTransferCount
     dailyHMTTransferAmount
+    dailyUniqueSenders
+    dailyUniqueReceivers
   }
 `;
 

package/src/graphql/queries/transaction.ts

@@ -19,12 +19,12 @@ export const GET_TRANSACTIONS_QUERY = (filter: ITransactionsFilter) => {
 
   const WHERE_CLAUSE = `
     where: {
-      ${fromAddress ? `from: $fromAddress` : ''}
-      ${toAddress ? `to: $toAddress` : ''}
-      ${startDate ? `timestamp_gte: $startDate` : ''}
-      ${endDate ? `timestamp_lte: $endDate` : ''}
-      ${startBlock ? `block_gte: $startBlock` : ''}
-      ${endBlock ? `block_lte: $endBlock` : ''}
+      ${fromAddress ? `from: $fromAddress,` : ''}
+      ${toAddress ? `to: $toAddress,` : ''}
+      ${startDate ? `timestamp_gte: $startDate,` : ''}
+      ${endDate ? `timestamp_lte: $endDate,` : ''}
+      ${startBlock ? `block_gte: $startBlock,` : ''}
+      ${endBlock ? `block_lte: $endBlock,` : ''}
     }
   `;
 
@@ -36,11 +36,16 @@ export const GET_TRANSACTIONS_QUERY = (filter: ITransactionsFilter) => {
         $endDate: Int
         $startBlock: Int
         $endBlock: Int
+        $orderDirection: String
+        $first: Int
+        $skip: Int
     ) {
       transactions(
         ${WHERE_CLAUSE}
         orderBy: timestamp,
-        orderDirection: asc,
+        orderDirection: $orderDirection,
+        first: $first,
+        skip: $skip
       ) {
         ...TransactionFields
       }

package/src/graphql/types.ts

@@ -1,3 +1,5 @@
+import { ChainId } from '../enums';
+
 export type EscrowData = {
   id: string;
   address: string;
@@ -72,6 +74,8 @@ export type EventDayData = {
   dailyPayoutAmount: string;
   dailyHMTTransferCount: string;
   dailyHMTTransferAmount: string;
+  dailyUniqueSenders: string;
+  dailyUniqueReceivers: string;
 };
 
 export type RewardAddedEventData = {
@@ -129,6 +133,8 @@ export type DailyHMTData = {
   timestamp: Date;
   totalTransactionAmount: bigint;
   totalTransactionCount: number;
+  dailyUniqueSenders: number;
+  dailyUniqueReceivers: number;
 };
 
 export type HMTStatistics = {
@@ -156,6 +162,13 @@ export type TaskStatistics = {
   dailyTasksData: DailyTaskData[];
 };
 
+export type StatusEvent = {
+  timestamp: number;
+  escrowAddress: string;
+  status: string;
+  chainId: ChainId;
+};
+
 export type KVStoreData = {
   id: string;
   address: string;

package/src/index.ts

@@ -5,6 +5,7 @@ import { EscrowClient, EscrowUtils } from './escrow';
 import { StatisticsClient } from './statistics';
 import { Encryption, EncryptionUtils } from './encryption';
 import { OperatorUtils } from './operator';
+import { TransactionUtils } from './transaction';
 
 export * from './constants';
 export * from './types';
@@ -21,4 +22,5 @@ export {
   Encryption,
   EncryptionUtils,
   OperatorUtils,
+  TransactionUtils,
 };

package/src/interfaces.ts

@@ -1,5 +1,5 @@
 import { EscrowStatus } from './types';
-import { ChainId } from './enums';
+import { ChainId, OrderDirection } from './enums';
 
 export interface IAllocation {
   escrowAddress: string;
@@ -66,7 +66,7 @@ export interface IOperatorSubgraph extends Omit<IOperator, 'jobTypes'> {
   jobTypes?: string;
 }
 
-export interface IEscrowsFilter {
+export interface IEscrowsFilter extends IPagination {
   launcher?: string;
   reputationOracle?: string;
   recordingOracle?: string;
@@ -75,7 +75,7 @@ export interface IEscrowsFilter {
   status?: EscrowStatus;
   from?: Date;
   to?: Date;
-  networks: ChainId[];
+  chainId: ChainId;
 }
 
 export interface IEscrowConfig {
@@ -102,6 +102,11 @@ export interface IStatisticsParams {
   limit?: number;
 }
 
+export interface IHMTHoldersParams {
+  address?: string;
+  orderDirection?: 'asc' | 'desc';
+}
+
 export interface IPayoutFilter {
   escrowAddress?: string;
   recipient?: string;
@@ -116,7 +121,7 @@ export interface IKVStore {
 
 export interface ITransaction {
   block: bigint;
-  hash: string;
+  txHash: string;
   from: string;
   to: string;
   timestamp: bigint;
@@ -124,8 +129,8 @@ export interface ITransaction {
   method: string;
 }
 
-export interface ITransactionsFilter {
-  networks: ChainId[];
+export interface ITransactionsFilter extends IPagination {
+  chainId: ChainId;
   startBlock?: number;
   endBlock?: number;
   startDate?: Date;
@@ -133,3 +138,9 @@ export interface ITransactionsFilter {
   fromAddress?: string;
   toAddress?: string;
 }
+
+export interface IPagination {
+  first?: number;
+  skip?: number;
+  orderDirection?: OrderDirection;
+}

package/src/kvstore.ts

@@ -442,7 +442,7 @@ export class KVStoreClient extends BaseEthersClient {
  * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
  *
  * const KVStoreAddresses = new KVStoreUtils.getData({
- *   networks: [ChainId.POLYGON_AMOY]
+ *   network: ChainId.POLYGON_AMOY
  * });
  * ```
  */

package/src/operator.ts

@@ -21,7 +21,7 @@ import {
   ErrorInvalidStakerAddressProvided,
   ErrorUnsupportedChainID,
 } from './error';
-import { getSubgraphUrl, throwError } from './utils';
+import { getSubgraphUrl } from './utils';
 import { ChainId } from './enums';
 import { NETWORKS } from './constants';
 
@@ -54,28 +54,28 @@ export class OperatorUtils {
       throw ErrorUnsupportedChainID;
     }
 
-    try {
-      const { leader } = await gqlFetch<{
-        leader: ILeaderSubgraph;
-      }>(getSubgraphUrl(networkData), GET_LEADER_QUERY, {
-        address: address.toLowerCase(),
-      });
+    const { leader } = await gqlFetch<{
+      leader: ILeaderSubgraph;
+    }>(getSubgraphUrl(networkData), GET_LEADER_QUERY, {
+      address: address.toLowerCase(),
+    });
 
-      let jobTypes: string[] = [];
+    if (!leader) {
+      return (leader as ILeader) || null;
+    }
 
-      if (typeof leader.jobTypes === 'string') {
-        jobTypes = leader.jobTypes.split(',');
-      } else if (Array.isArray(leader.jobTypes)) {
-        jobTypes = leader.jobTypes;
-      }
+    let jobTypes: string[] = [];
 
-      return {
-        ...leader,
-        jobTypes,
-      };
-    } catch (e) {
-      return throwError(e);
+    if (typeof leader.jobTypes === 'string') {
+      jobTypes = leader.jobTypes.split(',');
+    } else if (Array.isArray(leader.jobTypes)) {
+      jobTypes = leader.jobTypes;
     }
+
+    return {
+      ...leader,
+      jobTypes,
+    };
   }
 
   /**
@@ -97,45 +97,41 @@ export class OperatorUtils {
    * ```
    */
   public static async getLeaders(filter: ILeadersFilter): Promise<ILeader[]> {
-    try {
-      let leaders_data: ILeader[] = [];
+    let leaders_data: ILeader[] = [];
 
-      const networkData = NETWORKS[filter.chainId];
+    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 (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
 
-      if (!leaders) {
-        return [];
-      }
+    const { leaders } = await gqlFetch<{
+      leaders: ILeaderSubgraph[];
+    }>(getSubgraphUrl(networkData), GET_LEADERS_QUERY(filter), {
+      role: filter?.role,
+    });
 
-      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);
+    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;
   }
 
   /**
@@ -162,31 +158,27 @@ export class OperatorUtils {
     if (!networkData) {
       throw ErrorUnsupportedChainID;
     }
-    try {
-      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[] = [];
+    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;
-        }
+      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);
-    }
+      return {
+        ...operator,
+        jobTypes,
+      };
+    });
   }
 
   /**
@@ -217,21 +209,17 @@ export class OperatorUtils {
       throw ErrorUnsupportedChainID;
     }
 
-    try {
-      const { rewardAddedEvents } = await gqlFetch<{
-        rewardAddedEvents: RewardAddedEventData[];
-      }>(getSubgraphUrl(networkData), 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,8 +15,9 @@ import {
   PaymentStatistics,
   WorkerStatistics,
   HMTHolderData,
+  HMTHolder,
 } from './graphql';
-import { IStatisticsParams } from './interfaces';
+import { IHMTHoldersParams, IStatisticsParams } from './interfaces';
 import { NetworkData } from './types';
 import { getSubgraphUrl, throwError } from './utils';
 
@@ -403,7 +404,7 @@ export class StatisticsClient {
 
       const { holders } = await gqlFetch<{
         holders: HMTHolderData[];
-      }>(this.subgraphUrl, GET_HOLDERS_QUERY);
+      }>(this.subgraphUrl, GET_HOLDERS_QUERY());
 
       const { eventDayDatas } = await gqlFetch<{
         eventDayDatas: EventDayData[];
@@ -428,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

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