@human-protocol/sdk 5.0.0-beta.3 → 5.1.0

package/src/error.ts

@@ -306,6 +306,13 @@ export const ErrorBulkPayOutVersion = new Error(
   'Invalid bulkPayOut parameters for the contract version of the specified escrow address'
 );
 
+/**
+ * @constant {Error} - Retry configuration is missing required parameters.
+ */
+export const ErrorRetryParametersMissing = new Error(
+  'Retry configuration must include both maxRetries and baseDelay'
+);
+
 /**
  * @constant {Warning} - Possible version mismatch.
  */

package/src/escrow.ts

@@ -10,7 +10,6 @@ import {
   HMToken__factory,
 } from '@human-protocol/core/typechain-types';
 import { ContractRunner, EventLog, Overrides, Signer, ethers } from 'ethers';
-import gqlFetch from 'graphql-request';
 import { BaseEthersClient } from './base';
 import { ESCROW_BULK_PAYOUT_MAX_ITEMS, NETWORKS } from './constants';
 import { requiresSigner } from './decorators';
@@ -62,13 +61,16 @@ import {
   IStatusEventFilter,
   IStatusEvent,
   ICancellationRefund,
+  ICancellationRefundFilter,
   IPayout,
   IEscrowWithdraw,
+  SubgraphOptions,
 } from './interfaces';
 import { EscrowStatus, NetworkData, TransactionLikeWithNonce } from './types';
 import {
   getSubgraphUrl,
   getUnixTimestamp,
+  customGqlFetch,
   isValidJson,
   isValidUrl,
   throwError,
@@ -203,8 +205,8 @@ export class EscrowClient extends BaseEthersClient {
   /**
    * This function creates an escrow contract that uses the token passed to pay oracle fees and reward workers.
    *
-   * @param {string} tokenAddress Token address to use for payouts.
-   * @param {string} jobRequesterId Job Requester Id
+   * @param {string} tokenAddress - The address of the token to use for escrow funding.
+   * @param {string} jobRequesterId - Identifier for the job requester.
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns {Promise<string>} Returns the address of the escrow created.
    *
@@ -244,7 +246,168 @@ export class EscrowClient extends BaseEthersClient {
         await this.escrowFactoryContract.createEscrow(
           tokenAddress,
           jobRequesterId,
-          this.applyTxDefaults(txOptions)
+          txOptions
+        )
+      ).wait();
+
+      const event = (
+        result?.logs?.find(({ topics }) =>
+          topics.includes(ethers.id('LaunchedV2(address,address,string)'))
+        ) as EventLog
+      )?.args;
+
+      if (!event) {
+        throw ErrorLaunchedEventIsNotEmitted;
+      }
+
+      return event.escrow;
+    } catch (e: any) {
+      return throwError(e);
+    }
+  }
+  private verifySetupParameters(escrowConfig: IEscrowConfig) {
+    const {
+      recordingOracle,
+      reputationOracle,
+      exchangeOracle,
+      recordingOracleFee,
+      reputationOracleFee,
+      exchangeOracleFee,
+      manifest,
+      manifestHash,
+    } = escrowConfig;
+
+    if (!ethers.isAddress(recordingOracle)) {
+      throw ErrorInvalidRecordingOracleAddressProvided;
+    }
+
+    if (!ethers.isAddress(reputationOracle)) {
+      throw ErrorInvalidReputationOracleAddressProvided;
+    }
+
+    if (!ethers.isAddress(exchangeOracle)) {
+      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;
+    }
+
+    if (!manifestHash) {
+      throw ErrorHashIsEmptyString;
+    }
+  }
+
+  /**
+   * Creates, funds, and sets up a new escrow contract in a single transaction.
+   *
+   * @param {string} tokenAddress - The ERC-20 token address used to fund the escrow.
+   * @param {bigint} amount - The token amount to fund the escrow with.
+   * @param {string} jobRequesterId - An off-chain identifier for the job requester.
+   * @param {IEscrowConfig} escrowConfig - Configuration parameters for escrow setup:
+   *   - `recordingOracle`: Address of the recording oracle.
+   *   - `reputationOracle`: Address of the reputation oracle.
+   *   - `exchangeOracle`: Address of the exchange oracle.
+   *   - `recordingOracleFee`: Fee (in basis points or percentage * 100) for the recording oracle.
+   *   - `reputationOracleFee`: Fee for the reputation oracle.
+   *   - `exchangeOracleFee`: Fee for the exchange oracle.
+   *   - `manifest`: URL to the manifest file.
+   *   - `manifestHash`: Hash of the manifest content.
+   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
+   *
+   * @returns {Promise<string>} Returns the address of the escrow created.
+   *
+   * @example
+   * import { Wallet, ethers } from 'ethers';
+   * import { EscrowClient, IERC20__factory } from '@human-protocol/sdk';
+   *
+   * const rpcUrl = 'YOUR_RPC_URL';
+   * const privateKey = 'YOUR_PRIVATE_KEY';
+   * const provider = new ethers.JsonRpcProvider(rpcUrl);
+   * const signer = new Wallet(privateKey, provider);
+   *
+   * const escrowClient = await EscrowClient.build(signer);
+   *
+   * const tokenAddress = '0xTokenAddress';
+   * const amount = ethers.parseUnits('1000', 18);
+   * const jobRequesterId = 'requester-123';
+   *
+   * const token = IERC20__factory.connect(tokenAddress, signer);
+   * await token.approve(escrowClient.escrowFactoryContract.target, amount);
+   *
+   * const escrowConfig = {
+   *   recordingOracle: '0xRecordingOracle',
+   *   reputationOracle: '0xReputationOracle',
+   *   exchangeOracle: '0xExchangeOracle',
+   *   recordingOracleFee: 5n,
+   *   reputationOracleFee: 5n,
+   *   exchangeOracleFee: 5n,
+   *   manifest: 'https://example.com/manifest.json',
+   *   manifestHash: 'manifestHash-123',
+   * } satisfies IEscrowConfig;
+   *
+   * const escrowAddress = await escrowClient.createFundAndSetupEscrow(
+   *   tokenAddress,
+   *   amount,
+   *   jobRequesterId,
+   *   escrowConfig
+   * );
+   *
+   * console.log('Escrow created at:', escrowAddress);
+   */
+  @requiresSigner
+  public async createFundAndSetupEscrow(
+    tokenAddress: string,
+    amount: bigint,
+    jobRequesterId: string,
+    escrowConfig: IEscrowConfig,
+    txOptions: Overrides = {}
+  ): Promise<string> {
+    if (!ethers.isAddress(tokenAddress)) {
+      throw ErrorInvalidTokenAddress;
+    }
+
+    this.verifySetupParameters(escrowConfig);
+
+    const {
+      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();
 
@@ -319,43 +482,12 @@ export class EscrowClient extends BaseEthersClient {
       manifestHash,
     } = escrowConfig;
 
-    if (!ethers.isAddress(recordingOracle)) {
-      throw ErrorInvalidRecordingOracleAddressProvided;
-    }
-
-    if (!ethers.isAddress(reputationOracle)) {
-      throw ErrorInvalidReputationOracleAddressProvided;
-    }
-
-    if (!ethers.isAddress(exchangeOracle)) {
-      throw ErrorInvalidExchangeOracleAddressProvided;
-    }
+    this.verifySetupParameters(escrowConfig);
 
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
     }
 
-    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;
-    }
-
-    if (!manifestHash) {
-      throw ErrorHashIsEmptyString;
-    }
-
     if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
       throw ErrorEscrowAddressIsNotProvidedByFactory;
     }
@@ -373,7 +505,7 @@ export class EscrowClient extends BaseEthersClient {
           exchangeOracleFee,
           manifest,
           manifestHash,
-          this.applyTxDefaults(txOptions)
+          txOptions
         )
       ).wait();
 
@@ -437,11 +569,7 @@ export class EscrowClient extends BaseEthersClient {
         this.runner
       );
       await (
-        await tokenContract.transfer(
-          escrowAddress,
-          amount,
-          this.applyTxDefaults(txOptions)
-        )
+        await tokenContract.transfer(escrowAddress, amount, txOptions)
       ).wait();
 
       return;
@@ -562,7 +690,7 @@ export class EscrowClient extends BaseEthersClient {
             url,
             hash,
             fundsToReserve,
-            this.applyTxDefaults(txOptions)
+            txOptions
           )
         ).wait();
       } else {
@@ -570,7 +698,7 @@ export class EscrowClient extends BaseEthersClient {
           await escrowContract['storeResults(string,string)'](
             url,
             hash,
-            this.applyTxDefaults(txOptions)
+            txOptions
           )
         ).wait();
       }
@@ -626,9 +754,7 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      await (
-        await escrowContract.complete(this.applyTxDefaults(txOptions))
-      ).wait();
+      await (await escrowContract.complete(txOptions)).wait();
       return;
     } catch (e) {
       return throwError(e);
@@ -768,7 +894,7 @@ export class EscrowClient extends BaseEthersClient {
             finalResultsHash,
             id,
             forceComplete,
-            this.applyTxDefaults(txOptions)
+            txOptions
           )
         ).wait();
       } else {
@@ -782,7 +908,7 @@ export class EscrowClient extends BaseEthersClient {
             finalResultsHash,
             id,
             forceComplete,
-            this.applyTxDefaults(txOptions)
+            txOptions
           )
         ).wait();
       }
@@ -836,9 +962,7 @@ export class EscrowClient extends BaseEthersClient {
 
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
-      await (
-        await escrowContract.cancel(this.applyTxDefaults(txOptions))
-      ).wait();
+      await (await escrowContract.cancel(txOptions)).wait();
     } catch (e) {
       return throwError(e);
     }
@@ -884,11 +1008,7 @@ export class EscrowClient extends BaseEthersClient {
 
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
-      await (
-        await escrowContract.requestCancellation(
-          this.applyTxDefaults(txOptions)
-        )
-      ).wait();
+      await (await escrowContract.requestCancellation(txOptions)).wait();
     } catch (e) {
       return throwError(e);
     }
@@ -946,10 +1066,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       const transactionReceipt = await (
-        await escrowContract.withdraw(
-          tokenAddress,
-          this.applyTxDefaults(txOptions)
-        )
+        await escrowContract.withdraw(tokenAddress, txOptions)
       ).wait();
 
       let amountTransferred: bigint | undefined = undefined;
@@ -1039,7 +1156,6 @@ export class EscrowClient extends BaseEthersClient {
     forceComplete = false,
     txOptions: Overrides = {}
   ): Promise<TransactionLikeWithNonce> {
-    txOptions = this.applyTxDefaults(txOptions);
     await this.ensureCorrectBulkPayoutInput(
       escrowAddress,
       recipients,
@@ -1810,6 +1926,7 @@ export class EscrowUtils {
    *
    *
    * @param {IEscrowsFilter} filter Filter parameters.
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {IEscrow[]} List of escrows that match the filter.
    *
    * **Code example**
@@ -1826,7 +1943,10 @@ export class EscrowUtils {
    * const escrows = await EscrowUtils.getEscrows(filters);
    * ```
    */
-  public static async getEscrows(filter: IEscrowsFilter): Promise<IEscrow[]> {
+  public static async getEscrows(
+    filter: IEscrowsFilter,
+    options?: SubgraphOptions
+  ): Promise<IEscrow[]> {
     if (filter.launcher && !ethers.isAddress(filter.launcher)) {
       throw ErrorInvalidAddress;
     }
@@ -1859,7 +1979,7 @@ export class EscrowUtils {
       statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
       statuses = statuses.map((status) => EscrowStatus[status]);
     }
-    const { escrows } = await gqlFetch<{ escrows: EscrowData[] }>(
+    const { escrows } = await customGqlFetch<{ escrows: EscrowData[] }>(
       getSubgraphUrl(networkData),
       GET_ESCROWS_QUERY(filter),
       {
@@ -1874,7 +1994,8 @@ export class EscrowUtils {
         orderDirection: orderDirection,
         first: first,
         skip: skip,
-      }
+      },
+      options
     );
     return (escrows || []).map((e) => mapEscrow(e, networkData.chainId));
   }
@@ -1932,6 +2053,7 @@ export class EscrowUtils {
    *
    * @param {ChainId} chainId Network in which the escrow has been deployed
    * @param {string} escrowAddress Address of the escrow
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {Promise<IEscrow | null>} - Escrow data or null if not found.
    *
    * **Code example**
@@ -1944,7 +2066,8 @@ export class EscrowUtils {
    */
   public static async getEscrow(
     chainId: ChainId,
-    escrowAddress: string
+    escrowAddress: string,
+    options?: SubgraphOptions
   ): Promise<IEscrow | null> {
     const networkData = NETWORKS[chainId];
 
@@ -1956,10 +2079,11 @@ export class EscrowUtils {
       throw ErrorInvalidAddress;
     }
 
-    const { escrow } = await gqlFetch<{ escrow: EscrowData | null }>(
+    const { escrow } = await customGqlFetch<{ escrow: EscrowData | null }>(
       getSubgraphUrl(networkData),
       GET_ESCROW_BY_ADDRESS_QUERY(),
-      { escrowAddress: escrowAddress.toLowerCase() }
+      { escrowAddress: escrowAddress.toLowerCase() },
+      options
     );
     if (!escrow) return null;
 
@@ -2002,6 +2126,7 @@ export class EscrowUtils {
    * ```
    *
    * @param {IStatusEventFilter} filter Filter parameters.
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {Promise<StatusEvent[]>} - Array of status events with their corresponding statuses.
    *
    * **Code example**
@@ -2023,7 +2148,8 @@ export class EscrowUtils {
    * ```
    */
   public static async getStatusEvents(
-    filter: IStatusEventFilter
+    filter: IStatusEventFilter,
+    options?: SubgraphOptions
   ): Promise<IStatusEvent[]> {
     const {
       chainId,
@@ -2057,7 +2183,7 @@ export class EscrowUtils {
 
     const statusNames = effectiveStatuses.map((status) => EscrowStatus[status]);
 
-    const data = await gqlFetch<{
+    const data = await customGqlFetch<{
       escrowStatusEvents: StatusEvent[];
     }>(
       getSubgraphUrl(networkData),
@@ -2070,7 +2196,8 @@ export class EscrowUtils {
         orderDirection,
         first: Math.min(first, 1000),
         skip,
-      }
+      },
+      options
     );
 
     if (!data || !data['escrowStatusEvents']) {
@@ -2094,6 +2221,7 @@ export class EscrowUtils {
    * Fetch payouts from the subgraph.
    *
    * @param {IPayoutFilter} filter Filter parameters.
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {Promise<IPayout[]>} List of payouts matching the filters.
    *
    * **Code example**
@@ -2111,7 +2239,10 @@ export class EscrowUtils {
    * console.log(payouts);
    * ```
    */
-  public static async getPayouts(filter: IPayoutFilter): Promise<IPayout[]> {
+  public static async getPayouts(
+    filter: IPayoutFilter,
+    options?: SubgraphOptions
+  ): Promise<IPayout[]> {
     const networkData = NETWORKS[filter.chainId];
     if (!networkData) {
       throw ErrorUnsupportedChainID;
@@ -2128,7 +2259,7 @@ export class EscrowUtils {
     const skip = filter.skip || 0;
     const orderDirection = filter.orderDirection || OrderDirection.DESC;
 
-    const { payouts } = await gqlFetch<{ payouts: PayoutData[] }>(
+    const { payouts } = await customGqlFetch<{ payouts: PayoutData[] }>(
       getSubgraphUrl(networkData),
       GET_PAYOUTS_QUERY(filter),
       {
@@ -2139,7 +2270,8 @@ export class EscrowUtils {
         first: Math.min(first, 1000),
         skip,
         orderDirection,
-      }
+      },
+      options
     );
     if (!payouts) {
       return [];
@@ -2188,6 +2320,7 @@ export class EscrowUtils {
    *
    *
    * @param {Object} filter Filter parameters.
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {Promise<ICancellationRefund[]>} List of cancellation refunds matching the filters.
    *
    * **Code example**
@@ -2202,16 +2335,10 @@ export class EscrowUtils {
    * console.log(cancellationRefunds);
    * ```
    */
-  public static async getCancellationRefunds(filter: {
-    chainId: ChainId;
-    escrowAddress?: string;
-    receiver?: string;
-    from?: Date;
-    to?: Date;
-    first?: number;
-    skip?: number;
-    orderDirection?: OrderDirection;
-  }): Promise<ICancellationRefund[]> {
+  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)) {
@@ -2226,17 +2353,22 @@ export class EscrowUtils {
     const skip = filter.skip || 0;
     const orderDirection = filter.orderDirection || OrderDirection.DESC;
 
-    const { cancellationRefundEvents } = await gqlFetch<{
+    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,
-    });
+    }>(
+      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 [];
@@ -2288,6 +2420,7 @@ export class EscrowUtils {
    *
    * @param {ChainId} chainId Network in which the escrow has been deployed
    * @param {string} escrowAddress Address of the escrow
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {Promise<ICancellationRefund>} Cancellation refund data
    *
    * **Code example**
@@ -2300,7 +2433,8 @@ export class EscrowUtils {
    */
   public static async getCancellationRefund(
     chainId: ChainId,
-    escrowAddress: string
+    escrowAddress: string,
+    options?: SubgraphOptions
   ): Promise<ICancellationRefund | null> {
     const networkData = NETWORKS[chainId];
     if (!networkData) throw ErrorUnsupportedChainID;
@@ -2309,12 +2443,13 @@ export class EscrowUtils {
       throw ErrorInvalidEscrowAddressProvided;
     }
 
-    const { cancellationRefundEvents } = await gqlFetch<{
+    const { cancellationRefundEvents } = await customGqlFetch<{
       cancellationRefundEvents: CancellationRefundData[];
     }>(
       getSubgraphUrl(networkData),
       GET_CANCELLATION_REFUND_BY_ADDRESS_QUERY(),
-      { escrowAddress: escrowAddress.toLowerCase() }
+      { escrowAddress: escrowAddress.toLowerCase() },
+      options
     );
 
     if (!cancellationRefundEvents || cancellationRefundEvents.length === 0) {

package/src/interfaces.ts

@@ -312,3 +312,13 @@ export interface IEscrowWithdraw {
   tokenAddress: string;
   withdrawnAmount: bigint;
 }
+
+/**
+ * Configuration options for subgraph requests with retry logic.
+ */
+export interface SubgraphOptions {
+  /** Maximum number of retry attempts */
+  maxRetries?: number;
+  /** Base delay between retries in milliseconds */
+  baseDelay?: number;
+}