@human-protocol/sdk 4.0.3 → 4.1.2

package/src/escrow.ts

@@ -44,16 +44,24 @@ import {
   EscrowData,
   GET_ESCROWS_QUERY,
   GET_ESCROW_BY_ADDRESS_QUERY,
+  GET_PAYOUTS_QUERY,
   GET_STATUS_UPDATES_QUERY,
   StatusEvent,
 } from './graphql';
-import { IEscrowConfig, IEscrowsFilter } from './interfaces';
+import {
+  IEscrow,
+  IEscrowConfig,
+  IEscrowsFilter,
+  IPayoutFilter,
+  IStatusEventFilter,
+} from './interfaces';
 import {
   EscrowCancel,
   EscrowStatus,
   EscrowWithdraw,
   NetworkData,
   TransactionLikeWithNonce,
+  Payout,
 } from './types';
 import {
   getSubgraphUrl,
@@ -1611,7 +1619,7 @@ export class EscrowUtils {
    * ```
    *
    * ```ts
-   * type EscrowData = {
+   * interface IEscrow {
    *   id: string;
    *   address: string;
    *   amountPaid: string;
@@ -1636,7 +1644,7 @@ export class EscrowUtils {
    *
    *
    * @param {IEscrowsFilter} filter Filter parameters.
-   * @returns {EscrowData[]} List of escrows that match the filter.
+   * @returns {IEscrow[]} List of escrows that match the filter.
    *
    * **Code example**
    *
@@ -1649,12 +1657,10 @@ export class EscrowUtils {
    *   to: new Date(2023, 5, 8),
    *   chainId: ChainId.POLYGON_AMOY
    * };
-   * const escrowDatas = await EscrowUtils.getEscrows(filters);
+   * const escrows = await EscrowUtils.getEscrows(filters);
    * ```
    */
-  public static async getEscrows(
-    filter: IEscrowsFilter
-  ): Promise<EscrowData[]> {
+  public static async getEscrows(filter: IEscrowsFilter): Promise<IEscrow[]> {
     if (filter.launcher && !ethers.isAddress(filter.launcher)) {
       throw ErrorInvalidAddress;
     }
@@ -1734,7 +1740,7 @@ export class EscrowUtils {
    * ```
    *
    * ```ts
-   * type EscrowData = {
+   * interface IEscrow {
    *   id: string;
    *   address: string;
    *   amountPaid: string;
@@ -1760,20 +1766,20 @@ export class EscrowUtils {
    *
    * @param {ChainId} chainId Network in which the escrow has been deployed
    * @param {string} escrowAddress Address of the escrow
-   * @returns {EscrowData} Escrow data
+   * @returns {IEscrow} Escrow data
    *
    * **Code example**
    *
    * ```ts
    * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
    *
-   * const escrowData = new EscrowUtils.getEscrow(ChainId.POLYGON_AMOY, "0x1234567890123456789012345678901234567890");
+   * const escrow = new EscrowUtils.getEscrow(ChainId.POLYGON_AMOY, "0x1234567890123456789012345678901234567890");
    * ```
    */
   public static async getEscrow(
     chainId: ChainId,
     escrowAddress: string
-  ): Promise<EscrowData> {
+  ): Promise<IEscrow> {
     const networkData = NETWORKS[chainId];
 
     if (!networkData) {
@@ -1828,14 +1834,7 @@ export class EscrowUtils {
    * };
    * ```
    *
-   * @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.
+   * @param {IStatusEventFilter} filter Filter parameters.
    * @returns {Promise<StatusEvent[]>} - Array of status events with their corresponding statuses.
    *
    * **Code example**
@@ -1846,34 +1845,38 @@ export class EscrowUtils {
    * (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
-   *   );
+   *   const statusEvents = await EscrowUtils.getStatusEvents({
+   *     chainId: ChainId.POLYGON,
+   *     statuses: [EscrowStatus.Pending, EscrowStatus.Complete],
+   *     from: fromDate,
+   *     to: toDate
+   *   });
    *   console.log(statusEvents);
    * })();
    * ```
    */
-
   public static async getStatusEvents(
-    chainId: ChainId,
-    statuses?: EscrowStatus[],
-    from?: Date,
-    to?: Date,
-    launcher?: string,
-    first?: number,
-    skip?: number,
-    orderDirection?: OrderDirection
+    filter: IStatusEventFilter
   ): Promise<StatusEvent[]> {
+    const {
+      chainId,
+      statuses,
+      from,
+      to,
+      launcher,
+      first = 10,
+      skip = 0,
+      orderDirection = OrderDirection.DESC,
+    } = filter;
+
     if (launcher && !ethers.isAddress(launcher)) {
       throw ErrorInvalidAddress;
     }
 
-    first = first !== undefined ? Math.min(first, 1000) : 10;
-    skip = skip || 0;
-    orderDirection = orderDirection || OrderDirection.DESC;
+    const networkData = NETWORKS[chainId];
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
 
     // If statuses are not provided, use all statuses except Launched
     const effectiveStatuses = statuses ?? [
@@ -1885,11 +1888,6 @@ export class EscrowUtils {
       EscrowStatus.Cancelled,
     ];
 
-    const networkData = NETWORKS[chainId];
-    if (!networkData) {
-      throw ErrorUnsupportedChainID;
-    }
-
     const statusNames = effectiveStatuses.map((status) => EscrowStatus[status]);
 
     const data = await gqlFetch<{
@@ -1902,9 +1900,9 @@ export class EscrowUtils {
         from: from ? getUnixTimestamp(from) : undefined,
         to: to ? getUnixTimestamp(to) : undefined,
         launcher: launcher || undefined,
-        orderDirection: orderDirection,
-        first: first,
-        skip: skip,
+        orderDirection,
+        first: Math.min(first, 1000),
+        skip,
       }
     );
 
@@ -1921,4 +1919,64 @@ export class EscrowUtils {
 
     return eventsWithChainId;
   }
+
+  /**
+   * This function returns the payouts for a given set of networks.
+   *
+   * > This uses Subgraph
+   *
+   * **Input parameters**
+   * Fetch payouts from the subgraph.
+   *
+   * @param {IPayoutFilter} filter Filter parameters.
+   * @returns {Promise<Payout[]>} List of payouts matching the filters.
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
+   *
+   * const payouts = await EscrowUtils.getPayouts({
+   *   chainId: ChainId.POLYGON,
+   *   escrowAddress: '0x1234567890123456789012345678901234567890',
+   *   recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef',
+   *   from: new Date('2023-01-01'),
+   *   to: new Date('2023-12-31')
+   * });
+   * console.log(payouts);
+   * ```
+   */
+  public static async getPayouts(filter: IPayoutFilter): Promise<Payout[]> {
+    const networkData = NETWORKS[filter.chainId];
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+    if (filter.escrowAddress && !ethers.isAddress(filter.escrowAddress)) {
+      throw ErrorInvalidAddress;
+    }
+    if (filter.recipient && !ethers.isAddress(filter.recipient)) {
+      throw ErrorInvalidAddress;
+    }
+
+    const first =
+      filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+    const skip = filter.skip || 0;
+    const orderDirection = filter.orderDirection || OrderDirection.DESC;
+
+    const { payouts } = await gqlFetch<{ payouts: Payout[] }>(
+      getSubgraphUrl(networkData),
+      GET_PAYOUTS_QUERY(filter),
+      {
+        escrowAddress: filter.escrowAddress?.toLowerCase(),
+        recipient: filter.recipient?.toLowerCase(),
+        from: filter.from ? getUnixTimestamp(filter.from) : undefined,
+        to: filter.to ? getUnixTimestamp(filter.to) : undefined,
+        first: Math.min(first, 1000),
+        skip,
+        orderDirection,
+      }
+    );
+
+    return payouts || [];
+  }
 }

package/src/graphql/queries/payout.ts

@@ -1,5 +1,5 @@
 import gql from 'graphql-tag';
-import { IPayoutFilter } from '../../interfaces';
+import { IPayoutFilter } from 'src/interfaces';
 
 const PAYOUT_FRAGMENT = gql`
   fragment PayoutFields on Payout {
@@ -22,9 +22,6 @@ export const GET_PAYOUTS_QUERY = (filter: IPayoutFilter) => {
       ${to ? `createdAt_lt: $to` : ''}
     }
   `;
-  const LIMIT_CLAUSE = `
-    first: 1000
-  `;
 
   return gql`
     query getPayouts(
@@ -32,12 +29,16 @@ export const GET_PAYOUTS_QUERY = (filter: IPayoutFilter) => {
       $recipient: String
       $from: Int
       $to: Int
+      $first: Int
+      $skip: Int
+      $orderDirection: String
     ) {
       payouts(
         ${WHERE_CLAUSE}
         orderBy: createdAt,
-        orderDirection: desc,
-        ${LIMIT_CLAUSE}
+        orderDirection: $orderDirection,
+        first: $first,
+        skip: $skip
       ) {
         ...PayoutFields
       }

package/src/graphql/queries/statistics.ts

@@ -42,7 +42,7 @@ const EVENT_DAY_DATA_FRAGMENT = gql`
     dailyEscrowCount
     dailyWorkerCount
     dailyPayoutCount
-    dailyPayoutAmount
+    dailyHMTPayoutAmount
     dailyHMTTransferCount
     dailyHMTTransferAmount
     dailyUniqueSenders

package/src/graphql/queries/transaction.ts

@@ -27,8 +27,17 @@ const TRANSACTION_FRAGMENT = gql`
 `;
 
 export const GET_TRANSACTIONS_QUERY = (filter: ITransactionsFilter) => {
-  const { startDate, endDate, startBlock, endBlock, fromAddress, toAddress } =
-    filter;
+  const {
+    startDate,
+    endDate,
+    startBlock,
+    endBlock,
+    fromAddress,
+    toAddress,
+    method,
+    escrow,
+    token,
+  } = filter;
   const addressCondition =
     fromAddress === toAddress
       ? `
@@ -48,6 +57,9 @@ export const GET_TRANSACTIONS_QUERY = (filter: ITransactionsFilter) => {
         ${endDate ? `{timestamp_lte: $endDate},` : ''}
         ${startBlock ? `{block_gte: $startBlock},` : ''}
         ${endBlock ? `{block_lte: $endBlock},` : ''}
+        ${method ? `{ method: $method },` : ''}
+        ${escrow ? `{ escrow: $escrow },` : ''}
+        ${token ? `{ token: $token },` : ''}
       ]
       }
     `;
@@ -60,6 +72,9 @@ export const GET_TRANSACTIONS_QUERY = (filter: ITransactionsFilter) => {
         $endDate: Int
         $startBlock: Int
         $endBlock: Int
+        $method: String
+        $escrow: String
+        $token: String
         $orderDirection: String
         $first: Int
         $skip: Int

package/src/graphql/queries/worker.ts

@@ -0,0 +1,41 @@
+import gql from 'graphql-tag';
+import { IWorkersFilter } from '../../interfaces';
+
+export const GET_WORKER_QUERY = gql`
+  query GetWorker($address: String!) {
+    worker(id: $address) {
+      id
+      address
+      totalHMTAmountReceived
+      payoutCount
+    }
+  }
+`;
+
+export const GET_WORKERS_QUERY = (filter: IWorkersFilter) => {
+  const { address } = filter;
+
+  return gql`
+  query GetWorkers(
+    $address: String
+    $first: Int
+    $skip: Int
+    $orderBy: String
+    $orderDirection: String
+  ) {
+    workers(
+      where: {
+        ${address ? 'address: $address,' : ''}
+      }
+      first: $first
+      skip: $skip
+      orderBy: $orderBy
+      orderDirection: $orderDirection
+    ) {
+      id
+      address
+      totalHMTAmountReceived
+      payoutCount
+    }
+  }`;
+};

package/src/graphql/types.ts

@@ -22,14 +22,6 @@ export type EscrowData = {
   chainId: number;
 };
 
-export type PayoutData = {
-  id: string;
-  escrowAddress: string;
-  recipient: string;
-  amount: string;
-  createdAt: string;
-};
-
 export type HMTStatisticsData = {
   totalTransferEventCount: string;
   totalBulkTransferEventCount: string;
@@ -66,7 +58,7 @@ export type EventDayData = {
   dailyEscrowCount: string;
   dailyWorkerCount: string;
   dailyPayoutCount: string;
-  dailyPayoutAmount: string;
+  dailyHMTPayoutAmount: string;
   dailyHMTTransferCount: string;
   dailyHMTTransferAmount: string;
   dailyUniqueSenders: string;

package/src/index.ts

@@ -6,6 +6,7 @@ import { StatisticsClient } from './statistics';
 import { Encryption, EncryptionUtils } from './encryption';
 import { OperatorUtils } from './operator';
 import { TransactionUtils } from './transaction';
+import { WorkerUtils } from './worker';
 
 export * from './constants';
 export * from './types';
@@ -24,4 +25,5 @@ export {
   EncryptionUtils,
   OperatorUtils,
   TransactionUtils,
+  WorkerUtils,
 };

package/src/interfaces.ts

@@ -64,6 +64,28 @@ export interface IOperator {
   registrationInstructions?: string;
 }
 
+export interface IEscrow {
+  id: string;
+  address: string;
+  amountPaid: string;
+  balance: string;
+  count: string;
+  factoryAddress: string;
+  finalResultsUrl?: string;
+  intermediateResultsUrl?: string;
+  launcher: string;
+  manifestHash?: string;
+  manifestUrl?: string;
+  recordingOracle?: string;
+  reputationOracle?: string;
+  exchangeOracle?: string;
+  status: string;
+  token: string;
+  totalFundedAmount: string;
+  createdAt: string;
+  chainId: number;
+}
+
 export interface IEscrowsFilter extends IPagination {
   launcher?: string;
   reputationOracle?: string;
@@ -103,7 +125,8 @@ export interface IHMTHoldersParams extends IPagination {
   address?: string;
 }
 
-export interface IPayoutFilter {
+export interface IPayoutFilter extends IPagination {
+  chainId: ChainId;
   escrowAddress?: string;
   recipient?: string;
   from?: Date;
@@ -147,6 +170,9 @@ export interface ITransactionsFilter extends IPagination {
   endDate?: Date;
   fromAddress?: string;
   toAddress?: string;
+  method?: string;
+  escrow?: string;
+  token?: string;
 }
 
 export interface IPagination {
@@ -161,3 +187,24 @@ export interface StakerInfo {
   lockedUntil: bigint;
   withdrawableAmount: bigint;
 }
+
+export interface IStatusEventFilter extends IPagination {
+  chainId: ChainId;
+  statuses?: EscrowStatus[];
+  from?: Date;
+  to?: Date;
+  launcher?: string;
+}
+
+export interface IWorker {
+  id: string;
+  address: string;
+  totalHMTAmountReceived: number;
+  payoutCount: number;
+}
+
+export interface IWorkersFilter extends IPagination {
+  chainId: ChainId;
+  address?: string;
+  orderBy?: string;
+}

package/src/statistics.ts

@@ -319,12 +319,12 @@ export class StatisticsClient {
       return {
         dailyPaymentsData: eventDayDatas.map((eventDayData) => ({
           timestamp: new Date(+eventDayData.timestamp * 1000),
-          totalAmountPaid: ethers.toBigInt(eventDayData.dailyPayoutAmount),
+          totalAmountPaid: ethers.toBigInt(eventDayData.dailyHMTPayoutAmount),
           totalCount: +eventDayData.dailyPayoutCount,
           averageAmountPerWorker:
             eventDayData.dailyWorkerCount === '0'
               ? ethers.toBigInt(0)
-              : ethers.toBigInt(eventDayData.dailyPayoutAmount) /
+              : ethers.toBigInt(eventDayData.dailyHMTPayoutAmount) /
                 ethers.toBigInt(eventDayData.dailyWorkerCount),
         })),
       };

package/src/transaction.ts

@@ -19,6 +19,22 @@ export class TransactionUtils {
   /**
    * This function returns the transaction data for the given hash.
    *
+   * ```ts
+   * type ITransaction = {
+   *   block: bigint;
+   *   txHash: string;
+   *   from: string;
+   *   to: string;
+   *   timestamp: bigint;
+   *   value: string;
+   *   method: string;
+   *   receiver?: string;
+   *   escrow?: string;
+   *   token?: string;
+   *   internalTransactions: InternalTransaction[];
+   * };
+   * ```
+   *
    * @param {ChainId} chainId The chain ID.
    * @param {string} hash The transaction hash.
    * @returns {Promise<ITransaction>} Returns the transaction details.
@@ -65,6 +81,9 @@ export class TransactionUtils {
    *   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.
+   *   method?: string; // (Optional) The method of the transaction to filter by.
+   *   escrow?: string; // (Optional) The escrow address to filter transactions.
+   *   token?: string; // (Optional) The token address to filter transactions.
    *   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).
@@ -77,13 +96,17 @@ export class TransactionUtils {
    *
    * ```ts
    * type ITransaction = {
-   *   block: number;
+   *   block: bigint;
    *   txHash: string;
    *   from: string;
    *   to: string;
-   *   timestamp: number;
+   *   timestamp: bigint;
    *   value: string;
    *   method: string;
+   *   receiver?: string;
+   *   escrow?: string;
+   *   token?: string;
+   *   internalTransactions: InternalTransaction[];
    * };
    * ```
    *
@@ -137,6 +160,9 @@ export class TransactionUtils {
       endDate: filter.endDate ? getUnixTimestamp(filter.endDate) : undefined,
       startBlock: filter.startBlock ? filter.startBlock : undefined,
       endBlock: filter.endBlock ? filter.endBlock : undefined,
+      method: filter.method ? filter.method : undefined,
+      escrow: filter.escrow ? filter.escrow : undefined,
+      token: filter.token ? filter.token : undefined,
       orderDirection: orderDirection,
       first: first,
       skip: skip,

package/src/types.ts

@@ -171,4 +171,30 @@ export type EscrowWithdraw = {
   amountWithdrawn: bigint;
 };
 
+/**
+ * Represents a payout from an escrow.
+ */
+export type Payout = {
+  /**
+   * Unique identifier of the payout.
+   */
+  id: string;
+  /**
+   * The address of the escrow associated with the payout.
+   */
+  escrowAddress: string;
+  /**
+   * The address of the recipient who received the payout.
+   */
+  recipient: string;
+  /**
+   * The amount paid to the recipient.
+   */
+  amount: bigint;
+  /**
+   * The timestamp when the payout was created (in UNIX format).
+   */
+  createdAt: number;
+};
+
 export type TransactionLikeWithNonce = TransactionLike & { nonce: number };

package/src/utils.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { ethers } from 'ethers';
 
+import { ChainId } from './enums';
 import {
   ContractExecutionError,
   EthereumError,
@@ -66,7 +67,7 @@ export const getSubgraphUrl = (networkData: NetworkData) => {
       SUBGRAPH_API_KEY_PLACEHOLDER,
       process.env.SUBGRAPH_API_KEY
     );
-  } else {
+  } else if (networkData.chainId !== ChainId.LOCALHOST) {
     // eslint-disable-next-line no-console
     console.warn(WarnSubgraphApiKeyNotProvided);
   }