@human-protocol/sdk 6.0.0 → 7.0.0

package/src/{escrow.ts → escrow/escrow_client.ts}

@@ -10,10 +10,10 @@ import {
   HMToken__factory,
 } from '@human-protocol/core/typechain-types';
 import { ContractRunner, EventLog, Overrides, Signer, ethers } from 'ethers';
-import { BaseEthersClient } from './base';
-import { ESCROW_BULK_PAYOUT_MAX_ITEMS, NETWORKS } from './constants';
-import { requiresSigner } from './decorators';
-import { ChainId, OrderDirection } from './enums';
+import { BaseEthersClient } from '../base';
+import { ESCROW_BULK_PAYOUT_MAX_ITEMS, NETWORKS } from '../constants';
+import { requiresSigner } from '../decorators';
+import { ChainId } from '../enums';
 import {
   ErrorAmountMustBeGreaterThanZero,
   ErrorAmountsCannotBeEmptyArray,
@@ -21,7 +21,6 @@ import {
   ErrorEscrowAddressIsNotProvidedByFactory,
   ErrorEscrowDoesNotHaveEnoughBalance,
   ErrorHashIsEmptyString,
-  ErrorInvalidAddress,
   ErrorInvalidEscrowAddressProvided,
   ErrorInvalidExchangeOracleAddressProvided,
   ErrorInvalidManifest,
@@ -35,46 +34,19 @@ import {
   ErrorRecipientCannotBeEmptyArray,
   ErrorStoreResultsVersion,
   ErrorTooManyRecipients,
-  ErrorTotalFeeMustBeLessThanHundred,
   ErrorTransferEventNotFoundInTransactionLogs,
   ErrorUnsupportedChainID,
   InvalidEthereumAddressError,
   WarnVersionMismatch,
-} from './error';
+} from '../error';
+import { IEscrowConfig, IEscrowWithdraw } from '../interfaces';
 import {
-  CancellationRefundData,
-  EscrowData,
-  GET_CANCELLATION_REFUNDS_QUERY,
-  GET_CANCELLATION_REFUND_BY_ADDRESS_QUERY,
-  GET_ESCROWS_QUERY,
-  GET_ESCROW_BY_ADDRESS_QUERY,
-  GET_PAYOUTS_QUERY,
-  GET_STATUS_UPDATES_QUERY,
-  PayoutData,
-  StatusEvent,
-} from './graphql';
-import {
-  IEscrow,
-  IEscrowConfig,
-  IEscrowsFilter,
-  IPayoutFilter,
-  IStatusEventFilter,
-  IStatusEvent,
-  ICancellationRefund,
-  ICancellationRefundFilter,
-  IPayout,
-  IEscrowWithdraw,
-  SubgraphOptions,
-} from './interfaces';
-import { EscrowStatus, NetworkData, TransactionLikeWithNonce } from './types';
-import {
-  getSubgraphUrl,
-  getUnixTimestamp,
-  customGqlFetch,
-  isValidJson,
-  isValidUrl,
-  throwError,
-} from './utils';
+  EscrowStatus,
+  NetworkData,
+  TransactionLikeWithNonce,
+  TransactionOverrides,
+} from '../types';
+import { getErrorMessage, isValidJson, isValidUrl, throwError } from '../utils';
 
 /**
  * Client to perform actions on Escrow contracts and obtain information from the contracts.
@@ -205,20 +177,22 @@ export class EscrowClient extends BaseEthersClient {
   public async createEscrow(
     tokenAddress: string,
     jobRequesterId: string,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<string> {
     if (!ethers.isAddress(tokenAddress)) {
       throw ErrorInvalidTokenAddress;
     }
 
     try {
-      const result = await (
-        await this.escrowFactoryContract.createEscrow(
-          tokenAddress,
-          jobRequesterId,
-          txOptions
-        )
-      ).wait();
+      const result = await this.sendTxAndWait(
+        (overrides) =>
+          this.escrowFactoryContract.createEscrow(
+            tokenAddress,
+            jobRequesterId,
+            overrides
+          ),
+        txOptions
+      );
 
       const event = (
         result?.logs?.find(({ topics }) =>
@@ -241,9 +215,6 @@ export class EscrowClient extends BaseEthersClient {
       recordingOracle,
       reputationOracle,
       exchangeOracle,
-      recordingOracleFee,
-      reputationOracleFee,
-      exchangeOracleFee,
       manifest,
       manifestHash,
     } = escrowConfig;
@@ -260,18 +231,6 @@ export class EscrowClient extends BaseEthersClient {
       throw ErrorInvalidExchangeOracleAddressProvided;
     }
 
-    if (
-      recordingOracleFee <= 0 ||
-      reputationOracleFee <= 0 ||
-      exchangeOracleFee <= 0
-    ) {
-      throw ErrorAmountMustBeGreaterThanZero;
-    }
-
-    if (recordingOracleFee + reputationOracleFee + exchangeOracleFee > 100) {
-      throw ErrorTotalFeeMustBeLessThanHundred;
-    }
-
     const isManifestValid = isValidUrl(manifest) || isValidJson(manifest);
     if (!isManifestValid) {
       throw ErrorInvalidManifest;
@@ -296,8 +255,6 @@ export class EscrowClient extends BaseEthersClient {
    * @throws ErrorInvalidRecordingOracleAddressProvided If the recording oracle address is invalid
    * @throws ErrorInvalidReputationOracleAddressProvided If the reputation oracle address is invalid
    * @throws ErrorInvalidExchangeOracleAddressProvided If the exchange oracle address is invalid
-   * @throws ErrorAmountMustBeGreaterThanZero If any oracle fee is less than or equal to zero
-   * @throws ErrorTotalFeeMustBeLessThanHundred If the total oracle fees exceed 100
    * @throws ErrorInvalidManifest If the manifest is not a valid URL or JSON string
    * @throws ErrorHashIsEmptyString If the manifest hash is empty
    * @throws ErrorLaunchedEventIsNotEmitted If the LaunchedV2 event is not emitted
@@ -318,9 +275,6 @@ export class EscrowClient extends BaseEthersClient {
    *   recordingOracle: '0xRecordingOracleAddress',
    *   reputationOracle: '0xReputationOracleAddress',
    *   exchangeOracle: '0xExchangeOracleAddress',
-   *   recordingOracleFee: 5n,
-   *   reputationOracleFee: 5n,
-   *   exchangeOracleFee: 5n,
    *   manifest: 'https://example.com/manifest.json',
    *   manifestHash: 'manifestHash-123',
    * };
@@ -340,7 +294,7 @@ export class EscrowClient extends BaseEthersClient {
     amount: bigint,
     jobRequesterId: string,
     escrowConfig: IEscrowConfig,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<string> {
     if (!ethers.isAddress(tokenAddress)) {
       throw ErrorInvalidTokenAddress;
@@ -352,30 +306,26 @@ export class EscrowClient extends BaseEthersClient {
       recordingOracle,
       reputationOracle,
       exchangeOracle,
-      recordingOracleFee,
-      reputationOracleFee,
-      exchangeOracleFee,
       manifest,
       manifestHash,
     } = escrowConfig;
 
     try {
-      const result = await (
-        await this.escrowFactoryContract.createFundAndSetupEscrow(
-          tokenAddress,
-          amount,
-          jobRequesterId,
-          reputationOracle,
-          recordingOracle,
-          exchangeOracle,
-          reputationOracleFee,
-          recordingOracleFee,
-          exchangeOracleFee,
-          manifest,
-          manifestHash,
-          txOptions
-        )
-      ).wait();
+      const result = await this.sendTxAndWait(
+        (overrides) =>
+          this.escrowFactoryContract.createFundAndSetupEscrow(
+            tokenAddress,
+            amount,
+            jobRequesterId,
+            reputationOracle,
+            recordingOracle,
+            exchangeOracle,
+            manifest,
+            manifestHash,
+            overrides
+          ),
+        txOptions
+      );
 
       const event = (
         result?.logs?.find(({ topics }) =>
@@ -405,8 +355,6 @@ export class EscrowClient extends BaseEthersClient {
    * @throws ErrorInvalidRecordingOracleAddressProvided If the recording oracle address is invalid
    * @throws ErrorInvalidReputationOracleAddressProvided If the reputation oracle address is invalid
    * @throws ErrorInvalidExchangeOracleAddressProvided If the exchange oracle address is invalid
-   * @throws ErrorAmountMustBeGreaterThanZero If any oracle fee is less than or equal to zero
-   * @throws ErrorTotalFeeMustBeLessThanHundred If the total oracle fees exceed 100
    * @throws ErrorInvalidManifest If the manifest is not a valid URL or JSON string
    * @throws ErrorHashIsEmptyString If the manifest hash is empty
    * @throws ErrorInvalidEscrowAddressProvided If the escrow address is invalid
@@ -420,9 +368,6 @@ export class EscrowClient extends BaseEthersClient {
    *    recordingOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
    *    reputationOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
    *    exchangeOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    recordingOracleFee: 10n,
-   *    reputationOracleFee: 10n,
-   *    exchangeOracleFee: 10n,
    *    manifest: 'http://localhost/manifest.json',
    *    manifestHash: 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079',
    * };
@@ -433,15 +378,12 @@ export class EscrowClient extends BaseEthersClient {
   async setup(
     escrowAddress: string,
     escrowConfig: IEscrowConfig,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     const {
       recordingOracle,
       reputationOracle,
       exchangeOracle,
-      recordingOracleFee,
-      reputationOracleFee,
-      exchangeOracleFee,
       manifest,
       manifestHash,
     } = escrowConfig;
@@ -459,19 +401,18 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      await (
-        await escrowContract.setup(
-          reputationOracle,
-          recordingOracle,
-          exchangeOracle,
-          reputationOracleFee,
-          recordingOracleFee,
-          exchangeOracleFee,
-          manifest,
-          manifestHash,
-          txOptions
-        )
-      ).wait();
+      await this.sendTxAndWait(
+        (overrides) =>
+          escrowContract.setup(
+            reputationOracle,
+            recordingOracle,
+            exchangeOracle,
+            manifest,
+            manifestHash,
+            overrides
+          ),
+        txOptions
+      );
 
       return;
     } catch (e) {
@@ -502,7 +443,7 @@ export class EscrowClient extends BaseEthersClient {
   async fund(
     escrowAddress: string,
     amount: bigint,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
@@ -525,9 +466,10 @@ export class EscrowClient extends BaseEthersClient {
         tokenAddress,
         this.runner
       );
-      await (
-        await tokenContract.transfer(escrowAddress, amount, txOptions)
-      ).wait();
+      await this.sendTxAndWait(
+        (overrides) => tokenContract.transfer(escrowAddress, amount, overrides),
+        txOptions
+      );
 
       return;
     } catch (e) {
@@ -564,7 +506,7 @@ export class EscrowClient extends BaseEthersClient {
     escrowAddress: string,
     url: string,
     hash: string,
-    txOptions?: Overrides
+    txOptions?: TransactionOverrides
   ): Promise<void>;
 
   /**
@@ -604,7 +546,7 @@ export class EscrowClient extends BaseEthersClient {
     url: string,
     hash: string,
     fundsToReserve: bigint,
-    txOptions?: Overrides
+    txOptions?: TransactionOverrides
   ): Promise<void>;
 
   @requiresSigner
@@ -612,14 +554,16 @@ export class EscrowClient extends BaseEthersClient {
     escrowAddress: string,
     url: string,
     hash: string,
-    a?: bigint | Overrides,
-    b?: Overrides
+    a?: bigint | TransactionOverrides,
+    b?: TransactionOverrides
   ): Promise<void> {
     const escrowContract = this.getEscrowContract(escrowAddress);
 
     const hasFundsToReserveParam = typeof a === 'bigint';
     const fundsToReserve = hasFundsToReserveParam ? (a as bigint) : null;
-    const txOptions = (hasFundsToReserveParam ? b : a) || {};
+    const txOptions = (hasFundsToReserveParam ? b : a) as
+      | TransactionOverrides
+      | undefined;
     // When fundsToReserve is provided and is 0, allow empty URL.
     // In this situation not solutions might have been provided so the escrow can be straight cancelled.
     const allowEmptyUrl = hasFundsToReserveParam && fundsToReserve === 0n;
@@ -640,24 +584,17 @@ export class EscrowClient extends BaseEthersClient {
     }
 
     try {
-      if (fundsToReserve !== null) {
-        await (
-          await escrowContract['storeResults(string,string,uint256)'](
-            url,
-            hash,
-            fundsToReserve,
-            txOptions
-          )
-        ).wait();
-      } else {
-        await (
-          await escrowContract['storeResults(string,string)'](
-            url,
-            hash,
-            txOptions
-          )
-        ).wait();
-      }
+      const txFactory = (overrides: Overrides) =>
+        fundsToReserve !== null
+          ? escrowContract['storeResults(string,string,uint256)'](
+              url,
+              hash,
+              fundsToReserve,
+              overrides
+            )
+          : escrowContract['storeResults(string,string)'](url, hash, overrides);
+
+      await this.sendTxAndWait(txFactory, txOptions);
     } catch (e) {
       if (!hasFundsToReserveParam && e.reason === 'DEPRECATED_SIGNATURE') {
         throw ErrorStoreResultsVersion;
@@ -685,7 +622,7 @@ export class EscrowClient extends BaseEthersClient {
   @requiresSigner
   async complete(
     escrowAddress: string,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
@@ -697,8 +634,10 @@ export class EscrowClient extends BaseEthersClient {
 
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
-
-      await (await escrowContract.complete(txOptions)).wait();
+      await this.sendTxAndWait(
+        (overrides) => escrowContract.complete(overrides),
+        txOptions
+      );
       return;
     } catch (e) {
       return throwError(e);
@@ -759,7 +698,7 @@ export class EscrowClient extends BaseEthersClient {
     finalResultsHash: string,
     txId: number,
     forceComplete: boolean,
-    txOptions: Overrides
+    txOptions: TransactionOverrides
   ): Promise<void>;
 
   /**
@@ -817,7 +756,7 @@ export class EscrowClient extends BaseEthersClient {
     finalResultsHash: string,
     payoutId: string,
     forceComplete: boolean,
-    txOptions: Overrides
+    txOptions: TransactionOverrides
   ): Promise<void>;
 
   @requiresSigner
@@ -829,7 +768,7 @@ export class EscrowClient extends BaseEthersClient {
     finalResultsHash: string,
     id: number | string,
     forceComplete: boolean,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     await this.ensureCorrectBulkPayoutInput(
       escrowAddress,
@@ -843,35 +782,32 @@ export class EscrowClient extends BaseEthersClient {
     const idIsString = typeof id === 'string';
 
     try {
-      if (idIsString) {
-        await (
-          await escrowContract[
-            'bulkPayOut(address[],uint256[],string,string,string,bool)'
-          ](
-            recipients,
-            amounts,
-            finalResultsUrl,
-            finalResultsHash,
-            id,
-            forceComplete,
-            txOptions
-          )
-        ).wait();
-      } else {
-        await (
-          await escrowContract[
-            'bulkPayOut(address[],uint256[],string,string,uint256,bool)'
-          ](
-            recipients,
-            amounts,
-            finalResultsUrl,
-            finalResultsHash,
-            id,
-            forceComplete,
-            txOptions
-          )
-        ).wait();
-      }
+      const txFactory = (overrides: Overrides) =>
+        idIsString
+          ? escrowContract[
+              'bulkPayOut(address[],uint256[],string,string,string,bool)'
+            ](
+              recipients,
+              amounts,
+              finalResultsUrl,
+              finalResultsHash,
+              id,
+              forceComplete,
+              overrides
+            )
+          : escrowContract[
+              'bulkPayOut(address[],uint256[],string,string,uint256,bool)'
+            ](
+              recipients,
+              amounts,
+              finalResultsUrl,
+              finalResultsHash,
+              id,
+              forceComplete,
+              overrides
+            );
+
+      await this.sendTxAndWait(txFactory, txOptions);
     } catch (e) {
       if (!idIsString && e.reason === 'DEPRECATED_SIGNATURE') {
         throw ErrorBulkPayOutVersion;
@@ -900,7 +836,7 @@ export class EscrowClient extends BaseEthersClient {
   @requiresSigner
   async cancel(
     escrowAddress: string,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
@@ -912,7 +848,10 @@ export class EscrowClient extends BaseEthersClient {
 
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
-      await (await escrowContract.cancel(txOptions)).wait();
+      await this.sendTxAndWait(
+        (overrides) => escrowContract.cancel(overrides),
+        txOptions
+      );
     } catch (e) {
       return throwError(e);
     }
@@ -936,7 +875,7 @@ export class EscrowClient extends BaseEthersClient {
   @requiresSigner
   async requestCancellation(
     escrowAddress: string,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
@@ -948,7 +887,10 @@ export class EscrowClient extends BaseEthersClient {
 
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
-      await (await escrowContract.requestCancellation(txOptions)).wait();
+      await this.sendTxAndWait(
+        (overrides) => escrowContract.requestCancellation(overrides),
+        txOptions
+      );
     } catch (e) {
       return throwError(e);
     }
@@ -981,7 +923,7 @@ export class EscrowClient extends BaseEthersClient {
   async withdraw(
     escrowAddress: string,
     tokenAddress: string,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<IEscrowWithdraw> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
@@ -997,10 +939,10 @@ export class EscrowClient extends BaseEthersClient {
 
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
-
-      const transactionReceipt = await (
-        await escrowContract.withdraw(tokenAddress, txOptions)
-      ).wait();
+      const transactionReceipt = await this.sendTxAndWait(
+        (overrides) => escrowContract.withdraw(tokenAddress, overrides),
+        txOptions
+      );
 
       let amountTransferred: bigint | undefined = undefined;
 
@@ -1342,7 +1284,34 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      return escrowContract.manifestUrl();
+      try {
+        return await escrowContract.manifest();
+      } catch (manifestError) {
+        // Fallback for legacy escrows exposing `manifestUrl()` instead of `manifest()`.
+        try {
+          const provider = this.runner.provider;
+          if (!provider) {
+            throw ErrorProviderDoesNotExist;
+          }
+
+          const manifestInterface = new ethers.Interface([
+            'function manifestUrl() view returns (string)',
+          ]);
+          const target = escrowContract.target as string;
+          const data = manifestInterface.encodeFunctionData('manifestUrl');
+          const result = await provider.call({ to: target, data });
+          return manifestInterface.decodeFunctionResult(
+            'manifestUrl',
+            result
+          )[0] as string;
+        } catch (fallbackError) {
+          throw new Error(
+            `Failed to fetch manifest using both manifest() and manifestUrl(). ` +
+              `manifest() error: ${getErrorMessage(manifestError)}. ` +
+              `manifestUrl() error: ${getErrorMessage(fallbackError)}.`
+          );
+        }
+      }
     } catch (e) {
       return throwError(e);
     }
@@ -1670,480 +1639,3 @@ export class EscrowClient extends BaseEthersClient {
     }
   }
 }
-/**
- * Utility helpers for escrow-related queries.
- *
- * @example
- * ```ts
- * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
- *
- * const escrows = await EscrowUtils.getEscrows({
- *   chainId: ChainId.POLYGON_AMOY
- * });
- * console.log('Escrows:', escrows);
- * ```
- */
-export class EscrowUtils {
-  /**
-   * This function returns an array of escrows based on the specified filter parameters.
-   *
-   * @param filter - Filter parameters.
-   * @param options - Optional configuration for subgraph requests.
-   * @returns List of escrows that match the filter.
-   * @throws ErrorInvalidAddress If any filter address is invalid
-   * @throws ErrorUnsupportedChainID If the chain ID is not supported
-   *
-   * @example
-   * ```ts
-   * import { ChainId, EscrowStatus } from '@human-protocol/sdk';
-   *
-   * const filters = {
-   *   status: EscrowStatus.Pending,
-   *   from: new Date(2023, 4, 8),
-   *   to: new Date(2023, 5, 8),
-   *   chainId: ChainId.POLYGON_AMOY
-   * };
-   * const escrows = await EscrowUtils.getEscrows(filters);
-   * console.log('Found escrows:', escrows.length);
-   * ```
-   */
-  public static async getEscrows(
-    filter: IEscrowsFilter,
-    options?: SubgraphOptions
-  ): Promise<IEscrow[]> {
-    if (filter.launcher && !ethers.isAddress(filter.launcher)) {
-      throw ErrorInvalidAddress;
-    }
-
-    if (filter.recordingOracle && !ethers.isAddress(filter.recordingOracle)) {
-      throw ErrorInvalidAddress;
-    }
-
-    if (filter.reputationOracle && !ethers.isAddress(filter.reputationOracle)) {
-      throw ErrorInvalidAddress;
-    }
-
-    if (filter.exchangeOracle && !ethers.isAddress(filter.exchangeOracle)) {
-      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 networkData = NETWORKS[filter.chainId];
-
-    if (!networkData) {
-      throw ErrorUnsupportedChainID;
-    }
-
-    let statuses;
-    if (filter.status !== undefined) {
-      statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
-      statuses = statuses.map((status) => EscrowStatus[status]);
-    }
-    const { escrows } = await customGqlFetch<{ 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: statuses,
-        from: filter.from ? getUnixTimestamp(filter.from) : undefined,
-        to: filter.to ? getUnixTimestamp(filter.to) : undefined,
-        orderDirection: orderDirection,
-        first: first,
-        skip: skip,
-      },
-      options
-    );
-    return (escrows || []).map((e) => mapEscrow(e, networkData.chainId));
-  }
-
-  /**
-   * This function returns the escrow data for a given address.
-   *
-   * > This uses Subgraph
-   *
-   * @param chainId - Network in which the escrow has been deployed
-   * @param escrowAddress - Address of the escrow
-   * @param options - Optional configuration for subgraph requests.
-   * @returns Escrow data or null if not found.
-   * @throws ErrorUnsupportedChainID If the chain ID is not supported
-   * @throws ErrorInvalidAddress If the escrow address is invalid
-   *
-   * @example
-   * ```ts
-   * import { ChainId } from '@human-protocol/sdk';
-   *
-   * const escrow = await EscrowUtils.getEscrow(
-   *   ChainId.POLYGON_AMOY,
-   *   "0x1234567890123456789012345678901234567890"
-   * );
-   * if (escrow) {
-   *   console.log('Escrow status:', escrow.status);
-   * }
-   * ```
-   */
-  public static async getEscrow(
-    chainId: ChainId,
-    escrowAddress: string,
-    options?: SubgraphOptions
-  ): Promise<IEscrow | null> {
-    const networkData = NETWORKS[chainId];
-
-    if (!networkData) {
-      throw ErrorUnsupportedChainID;
-    }
-
-    if (escrowAddress && !ethers.isAddress(escrowAddress)) {
-      throw ErrorInvalidAddress;
-    }
-
-    const { escrow } = await customGqlFetch<{ escrow: EscrowData | null }>(
-      getSubgraphUrl(networkData),
-      GET_ESCROW_BY_ADDRESS_QUERY(),
-      { escrowAddress: escrowAddress.toLowerCase() },
-      options
-    );
-    if (!escrow) return null;
-
-    return mapEscrow(escrow, networkData.chainId);
-  }
-
-  /**
-   * This function returns the status events for a given set of networks within an optional date range.
-   *
-   * > This uses Subgraph
-   *
-   * @param filter - Filter parameters.
-   * @param options - Optional configuration for subgraph requests.
-   * @returns Array of status events with their corresponding statuses.
-   * @throws ErrorInvalidAddress If the launcher address is invalid
-   * @throws ErrorUnsupportedChainID If the chain ID is not supported
-   *
-   * @example
-   * ```ts
-   * import { ChainId, EscrowStatus } from '@human-protocol/sdk';
-   *
-   * const fromDate = new Date('2023-01-01');
-   * const toDate = new Date('2023-12-31');
-   * const statusEvents = await EscrowUtils.getStatusEvents({
-   *   chainId: ChainId.POLYGON,
-   *   statuses: [EscrowStatus.Pending, EscrowStatus.Complete],
-   *   from: fromDate,
-   *   to: toDate
-   * });
-   * console.log('Status events:', statusEvents.length);
-   * ```
-   */
-  public static async getStatusEvents(
-    filter: IStatusEventFilter,
-    options?: SubgraphOptions
-  ): Promise<IStatusEvent[]> {
-    const {
-      chainId,
-      statuses,
-      from,
-      to,
-      launcher,
-      first = 10,
-      skip = 0,
-      orderDirection = OrderDirection.DESC,
-    } = filter;
-
-    if (launcher && !ethers.isAddress(launcher)) {
-      throw ErrorInvalidAddress;
-    }
-
-    const networkData = NETWORKS[chainId];
-    if (!networkData) {
-      throw ErrorUnsupportedChainID;
-    }
-
-    // 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 statusNames = effectiveStatuses.map((status) => EscrowStatus[status]);
-
-    const data = await customGqlFetch<{
-      escrowStatusEvents: StatusEvent[];
-    }>(
-      getSubgraphUrl(networkData),
-      GET_STATUS_UPDATES_QUERY(from, to, launcher),
-      {
-        status: statusNames,
-        from: from ? getUnixTimestamp(from) : undefined,
-        to: to ? getUnixTimestamp(to) : undefined,
-        launcher: launcher || undefined,
-        orderDirection,
-        first: Math.min(first, 1000),
-        skip,
-      },
-      options
-    );
-
-    if (!data || !data['escrowStatusEvents']) {
-      return [];
-    }
-
-    return data['escrowStatusEvents'].map((event) => ({
-      timestamp: Number(event.timestamp) * 1000,
-      escrowAddress: event.escrowAddress,
-      status: EscrowStatus[event.status as keyof typeof EscrowStatus],
-      chainId,
-    }));
-  }
-
-  /**
-   * This function returns the payouts for a given set of networks.
-   *
-   * > This uses Subgraph
-   *
-   * @param filter - Filter parameters.
-   * @param options - Optional configuration for subgraph requests.
-   * @returns List of payouts matching the filters.
-   * @throws ErrorUnsupportedChainID If the chain ID is not supported
-   * @throws ErrorInvalidAddress If any filter address is invalid
-   *
-   * @example
-   * ```ts
-   * import { ChainId } 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:', payouts.length);
-   * ```
-   */
-  public static async getPayouts(
-    filter: IPayoutFilter,
-    options?: SubgraphOptions
-  ): Promise<IPayout[]> {
-    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 customGqlFetch<{ payouts: PayoutData[] }>(
-      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,
-      },
-      options
-    );
-    if (!payouts) {
-      return [];
-    }
-
-    return payouts.map((payout) => ({
-      id: payout.id,
-      escrowAddress: payout.escrowAddress,
-      recipient: payout.recipient,
-      amount: BigInt(payout.amount),
-      createdAt: Number(payout.createdAt) * 1000,
-    }));
-  }
-
-  /**
-   * This function returns the cancellation refunds for a given set of networks.
-   *
-   * > This uses Subgraph
-   *
-   * @param filter - Filter parameters.
-   * @param options - Optional configuration for subgraph requests.
-   * @returns List of cancellation refunds matching the filters.
-   * @throws ErrorUnsupportedChainID If the chain ID is not supported
-   * @throws ErrorInvalidEscrowAddressProvided If the escrow address is invalid
-   * @throws ErrorInvalidAddress If the receiver address is invalid
-   *
-   * @example
-   * ```ts
-   * import { ChainId } from '@human-protocol/sdk';
-   *
-   * const cancellationRefunds = await EscrowUtils.getCancellationRefunds({
-   *    chainId: ChainId.POLYGON_AMOY,
-   *    escrowAddress: '0x1234567890123456789012345678901234567890',
-   * });
-   * console.log('Cancellation refunds:', cancellationRefunds.length);
-   * ```
-   */
-  public static async getCancellationRefunds(
-    filter: ICancellationRefundFilter,
-    options?: SubgraphOptions
-  ): Promise<ICancellationRefund[]> {
-    const networkData = NETWORKS[filter.chainId];
-    if (!networkData) throw ErrorUnsupportedChainID;
-    if (filter.escrowAddress && !ethers.isAddress(filter.escrowAddress)) {
-      throw ErrorInvalidEscrowAddressProvided;
-    }
-    if (filter.receiver && !ethers.isAddress(filter.receiver)) {
-      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 { cancellationRefundEvents } = await customGqlFetch<{
-      cancellationRefundEvents: CancellationRefundData[];
-    }>(
-      getSubgraphUrl(networkData),
-      GET_CANCELLATION_REFUNDS_QUERY(filter),
-      {
-        escrowAddress: filter.escrowAddress?.toLowerCase(),
-        receiver: filter.receiver?.toLowerCase(),
-        from: filter.from ? getUnixTimestamp(filter.from) : undefined,
-        to: filter.to ? getUnixTimestamp(filter.to) : undefined,
-        first,
-        skip,
-        orderDirection,
-      },
-      options
-    );
-
-    if (!cancellationRefundEvents || cancellationRefundEvents.length === 0) {
-      return [];
-    }
-
-    return cancellationRefundEvents.map((event) => ({
-      id: event.id,
-      escrowAddress: event.escrowAddress,
-      receiver: event.receiver,
-      amount: BigInt(event.amount),
-      block: Number(event.block),
-      timestamp: Number(event.timestamp) * 1000,
-      txHash: event.txHash,
-    }));
-  }
-
-  /**
-   * This function returns the cancellation refund for a given escrow address.
-   *
-   * > This uses Subgraph
-   *
-   * @param chainId - Network in which the escrow has been deployed
-   * @param escrowAddress - Address of the escrow
-   * @param options - Optional configuration for subgraph requests.
-   * @returns Cancellation refund data or null if not found.
-   * @throws ErrorUnsupportedChainID If the chain ID is not supported
-   * @throws ErrorInvalidEscrowAddressProvided If the escrow address is invalid
-   *
-   * @example
-   * ```ts
-   * import { ChainId } from '@human-protocol/sdk';
-   *
-   *
-   * const cancellationRefund = await EscrowUtils.getCancellationRefund(
-   *   ChainId.POLYGON_AMOY,
-   *   "0x1234567890123456789012345678901234567890"
-   * );
-   * if (cancellationRefund) {
-   *   console.log('Refund amount:', cancellationRefund.amount);
-   * }
-   * ```
-   */
-  public static async getCancellationRefund(
-    chainId: ChainId,
-    escrowAddress: string,
-    options?: SubgraphOptions
-  ): Promise<ICancellationRefund | null> {
-    const networkData = NETWORKS[chainId];
-    if (!networkData) throw ErrorUnsupportedChainID;
-
-    if (!ethers.isAddress(escrowAddress)) {
-      throw ErrorInvalidEscrowAddressProvided;
-    }
-
-    const { cancellationRefundEvents } = await customGqlFetch<{
-      cancellationRefundEvents: CancellationRefundData[];
-    }>(
-      getSubgraphUrl(networkData),
-      GET_CANCELLATION_REFUND_BY_ADDRESS_QUERY(),
-      { escrowAddress: escrowAddress.toLowerCase() },
-      options
-    );
-
-    if (!cancellationRefundEvents || cancellationRefundEvents.length === 0) {
-      return null;
-    }
-
-    return {
-      id: cancellationRefundEvents[0].id,
-      escrowAddress: cancellationRefundEvents[0].escrowAddress,
-      receiver: cancellationRefundEvents[0].receiver,
-      amount: BigInt(cancellationRefundEvents[0].amount),
-      block: Number(cancellationRefundEvents[0].block),
-      timestamp: Number(cancellationRefundEvents[0].timestamp) * 1000,
-      txHash: cancellationRefundEvents[0].txHash,
-    };
-  }
-}
-
-function mapEscrow(e: EscrowData, chainId: ChainId | number): IEscrow {
-  return {
-    id: e.id,
-    address: e.address,
-    amountPaid: BigInt(e.amountPaid),
-    balance: BigInt(e.balance),
-    count: Number(e.count),
-    factoryAddress: e.factoryAddress,
-    finalResultsUrl: e.finalResultsUrl,
-    finalResultsHash: e.finalResultsHash,
-    intermediateResultsUrl: e.intermediateResultsUrl,
-    intermediateResultsHash: e.intermediateResultsHash,
-    launcher: e.launcher,
-    jobRequesterId: e.jobRequesterId,
-    manifestHash: e.manifestHash,
-    manifest: e.manifest,
-    recordingOracle: e.recordingOracle,
-    reputationOracle: e.reputationOracle,
-    exchangeOracle: e.exchangeOracle,
-    recordingOracleFee: e.recordingOracleFee
-      ? Number(e.recordingOracleFee)
-      : null,
-    reputationOracleFee: e.reputationOracleFee
-      ? Number(e.reputationOracleFee)
-      : null,
-    exchangeOracleFee: e.exchangeOracleFee ? Number(e.exchangeOracleFee) : null,
-    status: e.status,
-    token: e.token,
-    totalFundedAmount: BigInt(e.totalFundedAmount),
-    createdAt: Number(e.createdAt) * 1000,
-    chainId: Number(chainId),
-  };
-}