@human-protocol/sdk 3.0.0 → 3.0.2

package/src/escrow.ts

@@ -12,7 +12,7 @@ import gqlFetch from 'graphql-request';
 import { BaseEthersClient } from './base';
 import { DEFAULT_TX_ID, NETWORKS } from './constants';
 import { requiresSigner } from './decorators';
-import { ChainId } from './enums';
+import { ChainId, OrderDirection } from './enums';
 import {
   ErrorAmountMustBeGreaterThanZero,
   ErrorAmountsCannotBeEmptyArray,
@@ -41,6 +41,8 @@ import {
   EscrowData,
   GET_ESCROWS_QUERY,
   GET_ESCROW_BY_ADDRESS_QUERY,
+  GET_STATUS_UPDATES_QUERY,
+  StatusEvent,
 } from './graphql';
 import { IEscrowConfig, IEscrowsFilter } from './interfaces';
 import { EscrowCancel, EscrowStatus, NetworkData } from './types';
@@ -1399,7 +1401,7 @@ export class EscrowClient extends BaseEthersClient {
  * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
  *
  * const escrowAddresses = new EscrowUtils.getEscrows({
- *   networks: [ChainId.POLYGON_AMOY]
+ *   network: ChainId.POLYGON_AMOY
  * });
  * ```
  */
@@ -1412,7 +1414,7 @@ export class EscrowUtils {
    *
    * ```ts
    * interface IEscrowsFilter {
-   *   networks: ChainId[];
+   *   chainId: ChainId;
    *   launcher?: string;
    *   reputationOracle?: string;
    *   recordingOracle?: string;
@@ -1421,6 +1423,9 @@ export class EscrowUtils {
    *   status?: EscrowStatus;
    *   from?: Date;
    *   to?: Date;
+   *   first?: number;
+   *   skip?: number;
+   *   orderDirection?: OrderDirection;
    * }
    * ```
    *
@@ -1447,6 +1452,13 @@ export class EscrowUtils {
    * ```
    *
    * ```ts
+   * enum OrderDirection {
+   *   ASC = 'asc',
+   *   DESC = 'desc',
+   * }
+   * ```
+   *
+   * ```ts
    * enum EscrowStatus {
    *   Launched,
    *   Pending,
@@ -1472,11 +1484,8 @@ export class EscrowUtils {
    *   manifestHash?: string;
    *   manifestUrl?: string;
    *   recordingOracle?: string;
-   *   recordingOracleFee?: string;
    *   reputationOracle?: string;
-   *   reputationOracleFee?: string;
    *   exchangeOracle?: string;
-   *   exchangeOracleFee?: string;
    *   status: EscrowStatus;
    *   token: string;
    *   totalFundedAmount: string;
@@ -1497,7 +1506,7 @@ export class EscrowUtils {
    *   status: EscrowStatus.Pending,
    *   from: new Date(2023, 4, 8),
    *   to: new Date(2023, 5, 8),
-   *   networks: [ChainId.POLYGON_AMOY]
+   *   chainId: ChainId.POLYGON_AMOY
    * };
    * const escrowDatas = await EscrowUtils.getEscrows(filters);
    * ```
@@ -1505,9 +1514,6 @@ export class EscrowUtils {
   public static async getEscrows(
     filter: IEscrowsFilter
   ): Promise<EscrowData[]> {
-    if (!filter?.networks?.length) {
-      throw ErrorUnsupportedChainID;
-    }
     if (filter.launcher && !ethers.isAddress(filter.launcher)) {
       throw ErrorInvalidAddress;
     }
@@ -1524,42 +1530,46 @@ export class EscrowUtils {
       throw ErrorInvalidAddress;
     }
 
-    try {
-      const escrowAddresses: EscrowData[] = [];
-      for (const chainId of filter.networks) {
-        const networkData = NETWORKS[chainId];
+    const first =
+      filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+    const skip = filter.skip || 0;
+    const orderDirection = filter.orderDirection || OrderDirection.DESC;
 
-        if (!networkData) {
-          throw ErrorUnsupportedChainID;
-        }
+    const networkData = NETWORKS[filter.chainId];
 
-        const { escrows } = await gqlFetch<{ escrows: EscrowData[] }>(
-          getSubgraphUrl(networkData),
-          GET_ESCROWS_QUERY(filter),
-          {
-            ...filter,
-            launcher: filter.launcher?.toLowerCase(),
-            reputationOracle: filter.reputationOracle?.toLowerCase(),
-            recordingOracle: filter.recordingOracle?.toLowerCase(),
-            exchangeOracle: filter.exchangeOracle?.toLowerCase(),
-            status:
-              filter.status !== undefined
-                ? Object.entries(EscrowStatus).find(
-                    ([, value]) => value === filter.status
-                  )?.[0]
-                : undefined,
-            from: filter.from ? +filter.from.getTime() / 1000 : undefined,
-            to: filter.to ? +filter.to.getTime() / 1000 : undefined,
-          }
-        );
-        escrows.map((escrow) => (escrow.chainId = networkData.chainId));
-        escrowAddresses.push(...escrows);
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    const { escrows } = await gqlFetch<{ escrows: EscrowData[] }>(
+      getSubgraphUrl(networkData),
+      GET_ESCROWS_QUERY(filter),
+      {
+        ...filter,
+        launcher: filter.launcher?.toLowerCase(),
+        reputationOracle: filter.reputationOracle?.toLowerCase(),
+        recordingOracle: filter.recordingOracle?.toLowerCase(),
+        exchangeOracle: filter.exchangeOracle?.toLowerCase(),
+        status:
+          filter.status !== undefined
+            ? Object.entries(EscrowStatus).find(
+                ([, value]) => value === filter.status
+              )?.[0]
+            : undefined,
+        from: filter.from ? +filter.from.getTime() / 1000 : undefined,
+        to: filter.to ? +filter.to.getTime() / 1000 : undefined,
+        orderDirection: orderDirection,
+        first: first,
+        skip: skip,
       }
-      escrowAddresses.sort((a, b) => Number(b.createdAt) - Number(a.createdAt));
-      return escrowAddresses;
-    } catch (e: any) {
-      return throwError(e);
+    );
+    escrows.map((escrow) => (escrow.chainId = networkData.chainId));
+
+    if (!escrows) {
+      return [];
     }
+
+    return escrows;
   }
 
   /**
@@ -1605,11 +1615,8 @@ export class EscrowUtils {
    *   manifestHash?: string;
    *   manifestUrl?: string;
    *   recordingOracle?: string;
-   *   recordingOracleFee?: string;
    *   reputationOracle?: string;
-   *   reputationOracleFee?: string;
    *   exchangeOracle?: string;
-   *   exchangeOracleFee?: string;
    *   status: EscrowStatus;
    *   token: string;
    *   totalFundedAmount: string;
@@ -1644,16 +1651,152 @@ export class EscrowUtils {
       throw ErrorInvalidAddress;
     }
 
-    try {
-      const { escrow } = await gqlFetch<{ escrow: EscrowData }>(
-        getSubgraphUrl(networkData),
-        GET_ESCROW_BY_ADDRESS_QUERY(),
-        { escrowAddress: escrowAddress.toLowerCase() }
-      );
+    const { escrow } = await gqlFetch<{ escrow: EscrowData }>(
+      getSubgraphUrl(networkData),
+      GET_ESCROW_BY_ADDRESS_QUERY(),
+      { escrowAddress: escrowAddress.toLowerCase() }
+    );
 
-      return escrow || null;
-    } catch (e: any) {
-      return throwError(e);
+    return escrow || null;
+  }
+
+  /**
+   * This function returns the status events for a given set of networks within an optional date range.
+   *
+   * > This uses Subgraph
+   *
+   * **Input parameters**
+   *
+   * ```ts
+   * enum ChainId {
+   *   ALL = -1,
+   *   MAINNET = 1,
+   *   RINKEBY = 4,
+   *   GOERLI = 5,
+   *   SEPOLIA = 11155111,
+   *   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,
+   *   XLAYER_TESTNET = 195,
+   *   XLAYER = 196,
+   * }
+   * ```
+   *
+   * ```ts
+   * enum OrderDirection {
+   *   ASC = 'asc',
+   *   DESC = 'desc',
+   * }
+   * ```
+   *
+   * ```ts
+   * type Status = {
+   *   escrowAddress: string;
+   *   timestamp: string;
+   *   status: string;
+   * };
+   * ```
+   *
+   * @param {ChainId} chainId - List of network IDs to query for status events.
+   * @param {EscrowStatus[]} [statuses] - Optional array of statuses to query for. If not provided, queries for all statuses.
+   * @param {Date} [from] - Optional start date to filter events.
+   * @param {Date} [to] - Optional end date to filter events.
+   * @param {string} [launcher] - Optional launcher address to filter events. Must be a valid Ethereum address.
+   * @param {number} [first] - Optional number of transactions per page. Default is 10.
+   * @param {number} [skip] - Optional number of transactions to skip. Default is 0.
+   * @param {OrderDirection} [orderDirection] - Optional order of the results. Default is DESC.
+   * @returns {Promise<StatusEvent[]>} - Array of status events with their corresponding statuses.
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { ChainId, EscrowUtils, EscrowStatus } from '@human-protocol/sdk';
+   *
+   * (async () => {
+   *   const fromDate = new Date('2023-01-01');
+   *   const toDate = new Date('2023-12-31');
+   *   const statusEvents = await EscrowUtils.getStatusEvents(
+   *     [ChainId.POLYGON, ChainId.MAINNET],
+   *     [EscrowStatus.Pending, EscrowStatus.Complete],
+   *     fromDate,
+   *     toDate
+   *   );
+   *   console.log(statusEvents);
+   * })();
+   * ```
+   */
+
+  public static async getStatusEvents(
+    chainId: ChainId,
+    statuses?: EscrowStatus[],
+    from?: Date,
+    to?: Date,
+    launcher?: string,
+    first?: number,
+    skip?: number,
+    orderDirection?: OrderDirection
+  ): Promise<StatusEvent[]> {
+    if (launcher && !ethers.isAddress(launcher)) {
+      throw ErrorInvalidAddress;
     }
+
+    first = first !== undefined ? Math.min(first, 1000) : 10;
+    skip = skip || 0;
+    orderDirection = orderDirection || OrderDirection.DESC;
+
+    // If statuses are not provided, use all statuses except Launched
+    const effectiveStatuses = statuses ?? [
+      EscrowStatus.Launched,
+      EscrowStatus.Pending,
+      EscrowStatus.Partial,
+      EscrowStatus.Paid,
+      EscrowStatus.Complete,
+      EscrowStatus.Cancelled,
+    ];
+
+    const networkData = NETWORKS[chainId];
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    const statusNames = effectiveStatuses.map((status) => EscrowStatus[status]);
+
+    const data = await gqlFetch<{
+      escrowStatusEvents: StatusEvent[];
+    }>(
+      getSubgraphUrl(networkData),
+      GET_STATUS_UPDATES_QUERY(from, to, launcher),
+      {
+        status: statusNames,
+        from: from ? Math.floor(from.getTime() / 1000) : undefined,
+        to: to ? Math.floor(to.getTime() / 1000) : undefined,
+        launcher: launcher || undefined,
+        orderDirection: orderDirection,
+        first: first,
+        skip: skip,
+      }
+    );
+
+    if (!data || !data['escrowStatusEvents']) {
+      return [];
+    }
+
+    const statusEvents = data['escrowStatusEvents'] as StatusEvent[];
+
+    const eventsWithChainId = statusEvents.map((event) => ({
+      ...event,
+      chainId,
+    }));
+
+    return eventsWithChainId;
   }
 }

package/src/graphql/queries/escrow.ts

@@ -16,11 +16,8 @@ const ESCROW_FRAGMENT = gql`
     manifestHash
     manifestUrl
     recordingOracle
-    recordingOracleFee
     reputationOracle
-    reputationOracleFee
     exchangeOracle
-    exchangeOracleFee
     status
     token
     totalFundedAmount
@@ -51,14 +48,14 @@ export const GET_ESCROWS_QUERY = (filter: IEscrowsFilter) => {
 
   const WHERE_CLAUSE = `
     where: {
-      ${launcher ? `launcher: $launcher` : ''}
-      ${jobRequesterId ? `jobRequesterId: $jobRequesterId` : ''}
-      ${reputationOracle ? `reputationOracle: $reputationOracle` : ''}
-      ${recordingOracle ? `recordingOracle: $recordingOracle` : ''}
-      ${exchangeOracle ? `exchangeOracle: $exchangeOracle` : ''}
-      ${status !== undefined ? `status: $status` : ''}
-      ${from ? `createdAt_gte: $from` : ''}
-      ${to ? `createdAt_lte: $to` : ''}
+      ${launcher ? `launcher: $launcher,` : ''}
+      ${jobRequesterId ? `jobRequesterId: $jobRequesterId,` : ''}
+      ${reputationOracle ? `reputationOracle: $reputationOracle,` : ''}
+      ${recordingOracle ? `recordingOracle: $recordingOracle,` : ''}
+      ${exchangeOracle ? `exchangeOracle: $exchangeOracle,` : ''}
+      ${status !== undefined ? `status: $status,` : ''}
+      ${from ? `createdAt_gte: $from,` : ''}
+      ${to ? `createdAt_lte: $to,` : ''}
     }
   `;
 
@@ -72,9 +69,16 @@ export const GET_ESCROWS_QUERY = (filter: IEscrowsFilter) => {
       $status: String
       $from: Int
       $to: Int
+      $orderDirection: String
+      $first: Int
+      $skip: Int
     ) {
       escrows(
         ${WHERE_CLAUSE}
+        orderBy: createdAt,
+        orderDirection: $orderDirection,
+        first: $first,
+        skip: $skip
       ) {
         ...EscrowFields
       }
@@ -82,3 +86,41 @@ export const GET_ESCROWS_QUERY = (filter: IEscrowsFilter) => {
     ${ESCROW_FRAGMENT}
   `;
 };
+
+export const GET_STATUS_UPDATES_QUERY = (
+  from?: Date,
+  to?: Date,
+  launcher?: string
+) => {
+  const WHERE_CLAUSE = `
+    where: {
+      status_in: $status
+      ${from ? `timestamp_gte: $from` : ''}
+      ${to ? `timestamp_lte: $to` : ''}
+      ${launcher ? `launcher: $launcher` : ''}
+    }
+  `;
+  return gql`
+    query getStatus(
+      $status: [String!]!
+      $from: Int
+      $to: Int
+      $launcher: String
+      $orderDirection: String
+      $first: Int
+      $skip: Int
+    ) {
+      escrowStatusEvents(
+        ${WHERE_CLAUSE}
+        orderBy: timestamp,
+        orderDirection: $orderDirection,
+        first: $first,
+        skip: $skip
+      ) {
+        escrowAddress,
+        timestamp,
+        status,
+      }
+    }
+  `;
+};

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/kvstore.ts

@@ -21,3 +21,14 @@ export const GET_KVSTORE_BY_ADDRESS_QUERY = () => {
     ${KVSTORE_FRAGMENT}
   `;
 };
+
+export const GET_KVSTORE_BY_ADDRESS_AND_KEY_QUERY = () => {
+  return gql`
+    query getKVStoreDataByKey($address: String!, $key: String!) {
+      kvstores(where: { address: $address, key: $key }) {
+        ...KVStoreFields
+      }
+    }
+    ${KVSTORE_FRAGMENT}
+  `;
+};

package/src/graphql/queries/operator.ts

@@ -13,7 +13,7 @@ const LEADER_FRAGMENT = gql`
     amountSlashed
     reputation
     reward
-    amountJobsLaunched
+    amountJobsProcessed
     role
     fee
     publicKey

package/src/graphql/queries/statistics.ts

@@ -1,5 +1,5 @@
 import gql from 'graphql-tag';
-import { IStatisticsParams } from '../../interfaces';
+import { IStatisticsFilter } from '../../interfaces';
 
 const HMTOKEN_STATISTICS_FRAGMENT = gql`
   fragment HMTokenStatisticsFields on HMTokenStatistics {
@@ -47,6 +47,8 @@ const EVENT_DAY_DATA_FRAGMENT = gql`
     dailyPayoutAmount
     dailyHMTTransferCount
     dailyHMTTransferAmount
+    dailyUniqueSenders
+    dailyUniqueReceivers
   }
 `;
 
@@ -68,25 +70,29 @@ export const GET_ESCROW_STATISTICS_QUERY = gql`
   ${ESCROW_STATISTICS_FRAGMENT}
 `;
 
-export const GET_EVENT_DAY_DATA_QUERY = (params: IStatisticsParams) => {
-  const { from, to, limit } = params;
+export const GET_EVENT_DAY_DATA_QUERY = (params: IStatisticsFilter) => {
+  const { from, to } = params;
   const WHERE_CLAUSE = `
     where: {
       ${from !== undefined ? `timestamp_gte: $from` : ''}
       ${to !== undefined ? `timestamp_lte: $to` : ''}
     }
   `;
-  const LIMIT_CLAUSE = `
-    first: ${limit ? `$limit` : `1000`}
-  `;
 
   return gql`
-    query GetEscrowDayData($from: Int, $to: Int) {
+    query GetEscrowDayData(
+        $from: Int, 
+        $to: Int,
+        $orderDirection: String
+        $first: Int
+        $skip: Int
+    ) {
       eventDayDatas(
         ${WHERE_CLAUSE},
         orderBy: timestamp,
-        orderDirection: desc,
-        ${LIMIT_CLAUSE}
+        orderDirection: $orderDirection,
+        first: $first,
+        skip: $skip
       ) {
         ...EventDayDataFields
       }

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;
@@ -11,11 +13,8 @@ export type EscrowData = {
   manifestHash?: string;
   manifestUrl?: string;
   recordingOracle?: string;
-  recordingOracleFee?: string;
   reputationOracle?: string;
-  reputationOracleFee?: string;
   exchangeOracle?: string;
-  exchangeOracleFee?: string;
   status: string;
   token: string;
   totalFundedAmount: string;
@@ -72,6 +71,8 @@ export type EventDayData = {
   dailyPayoutAmount: string;
   dailyHMTTransferCount: string;
   dailyHMTTransferAmount: string;
+  dailyUniqueSenders: string;
+  dailyUniqueReceivers: string;
 };
 
 export type RewardAddedEventData = {
@@ -129,14 +130,14 @@ export type DailyHMTData = {
   timestamp: Date;
   totalTransactionAmount: bigint;
   totalTransactionCount: number;
+  dailyUniqueSenders: number;
+  dailyUniqueReceivers: number;
 };
 
 export type HMTStatistics = {
   totalTransferAmount: bigint;
   totalTransferCount: number;
   totalHolders: number;
-  holders: HMTHolder[];
-  dailyHMTData: DailyHMTData[];
 };
 
 export type IMDataEntity = {
@@ -156,6 +157,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

@@ -1,10 +1,11 @@
 import { StakingClient } from './staking';
 import { StorageClient } from './storage';
-import { KVStoreClient } from './kvstore';
+import { KVStoreClient, KVStoreUtils } from './kvstore';
 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';
@@ -15,10 +16,12 @@ export {
   StakingClient,
   StorageClient,
   KVStoreClient,
+  KVStoreUtils,
   EscrowClient,
   EscrowUtils,
   StatisticsClient,
   Encryption,
   EncryptionUtils,
   OperatorUtils,
+  TransactionUtils,
 };