@human-protocol/sdk 2.1.3 → 3.0.1

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,10 +41,12 @@ 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';
-import { isValidUrl, throwError } from './utils';
+import { getSubgraphUrl, isValidUrl, throwError } from './utils';
 
 /**
  * ## Introduction
@@ -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;
    * }
    * ```
    *
@@ -1441,12 +1446,19 @@ export class EscrowUtils {
    *   AVALANCHE_TESTNET = 43113,
    *   CELO = 42220,
    *   CELO_ALFAJORES = 44787,
-   *   SKALE = 1273227453,
+   *    = 1273227453,
    *   LOCALHOST = 1338,
    * }
    * ```
    *
    * ```ts
+   * enum OrderDirection {
+   *   ASC = 'asc',
+   *   DESC = 'desc',
+   * }
+   * ```
+   *
+   * ```ts
    * enum EscrowStatus {
    *   Launched,
    *   Pending,
@@ -1497,7 +1509,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 +1517,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 +1533,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[] }>(
-          networkData.subgraphUrl,
-          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;
   }
 
   /**
@@ -1586,7 +1599,6 @@ export class EscrowUtils {
    *   AVALANCHE_TESTNET = 43113,
    *   CELO = 42220,
    *   CELO_ALFAJORES = 44787,
-   *   SKALE = 1273227453,
    *   LOCALHOST = 1338,
    * }
    * ```
@@ -1645,16 +1657,152 @@ export class EscrowUtils {
       throw ErrorInvalidAddress;
     }
 
-    try {
-      const { escrow } = await gqlFetch<{ escrow: EscrowData }>(
-        networkData.subgraphUrl,
-        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

@@ -51,14 +51,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 +72,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 +89,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

@@ -0,0 +1,23 @@
+import gql from 'graphql-tag';
+
+const KVSTORE_FRAGMENT = gql`
+  fragment KVStoreFields on KVStore {
+    id
+    block
+    timestamp
+    address
+    key
+    value
+  }
+`;
+
+export const GET_KVSTORE_BY_ADDRESS_QUERY = () => {
+  return gql`
+    query getKVStoreData($address: String!) {
+      kvstores(where: { address: $address }) {
+        ...KVStoreFields
+      }
+    }
+    ${KVSTORE_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

@@ -0,0 +1,64 @@
+import gql from 'graphql-tag';
+import { ITransactionsFilter } from '../../../src/interfaces';
+
+const TRANSACTION_FRAGMENT = gql`
+  fragment TransactionFields on Transaction {
+    block
+    txHash
+    from
+    to
+    timestamp
+    value
+    method
+  }
+`;
+
+export const GET_TRANSACTIONS_QUERY = (filter: ITransactionsFilter) => {
+  const { startDate, endDate, startBlock, endBlock, fromAddress, toAddress } =
+    filter;
+
+  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,` : ''}
+    }
+  `;
+
+  return gql`
+    query getTransactions(
+        $fromAddress: String
+        $toAddress: String
+        $startDate: Int
+        $endDate: Int
+        $startBlock: Int
+        $endBlock: Int
+        $orderDirection: String
+        $first: Int
+        $skip: Int
+    ) {
+      transactions(
+        ${WHERE_CLAUSE}
+        orderBy: timestamp,
+        orderDirection: $orderDirection,
+        first: $first,
+        skip: $skip
+      ) {
+        ...TransactionFields
+      }
+    }
+    ${TRANSACTION_FRAGMENT}
+  `;
+};
+
+export const GET_TRANSACTION_QUERY = gql`
+  query getTransaction($hash: String!) {
+    transaction(id: $hash) {
+      ...TransactionFields
+    }
+  }
+  ${TRANSACTION_FRAGMENT}
+`;

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 = {
@@ -155,3 +161,19 @@ export type DailyTaskData = {
 export type TaskStatistics = {
   dailyTasksData: DailyTaskData[];
 };
+
+export type StatusEvent = {
+  timestamp: number;
+  escrowAddress: string;
+  status: string;
+  chainId: ChainId;
+};
+
+export type KVStoreData = {
+  id: string;
+  address: string;
+  key: string;
+  value: string;
+  timestamp: Date;
+  block: number;
+};

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;
@@ -40,7 +40,7 @@ export interface ILeaderSubgraph extends Omit<ILeader, 'jobTypes'> {
 }
 
 export interface ILeadersFilter {
-  networks: ChainId[];
+  chainId: ChainId;
   role?: 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,9 +102,45 @@ export interface IStatisticsParams {
   limit?: number;
 }
 
+export interface IHMTHoldersParams {
+  address?: string;
+  orderDirection?: 'asc' | 'desc';
+}
+
 export interface IPayoutFilter {
   escrowAddress?: string;
   recipient?: string;
   from?: Date;
   to?: Date;
 }
+
+export interface IKVStore {
+  key: string;
+  value: string;
+}
+
+export interface ITransaction {
+  block: bigint;
+  txHash: string;
+  from: string;
+  to: string;
+  timestamp: bigint;
+  value: string;
+  method: string;
+}
+
+export interface ITransactionsFilter extends IPagination {
+  chainId: ChainId;
+  startBlock?: number;
+  endBlock?: number;
+  startDate?: Date;
+  endDate?: Date;
+  fromAddress?: string;
+  toAddress?: string;
+}
+
+export interface IPagination {
+  first?: number;
+  skip?: number;
+  orderDirection?: OrderDirection;
+}