@human-protocol/sdk 5.0.0 → 5.2.0

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,
@@ -244,7 +246,7 @@ export class EscrowClient extends BaseEthersClient {
         await this.escrowFactoryContract.createEscrow(
           tokenAddress,
           jobRequesterId,
-          this.applyTxDefaults(txOptions)
+          txOptions
         )
       ).wait();
 
@@ -263,6 +265,7 @@ export class EscrowClient extends BaseEthersClient {
       return throwError(e);
     }
   }
+
   private verifySetupParameters(escrowConfig: IEscrowConfig) {
     const {
       recordingOracle,
@@ -405,7 +408,7 @@ export class EscrowClient extends BaseEthersClient {
           exchangeOracleFee,
           manifest,
           manifestHash,
-          this.applyTxDefaults(txOptions)
+          txOptions
         )
       ).wait();
 
@@ -503,7 +506,7 @@ export class EscrowClient extends BaseEthersClient {
           exchangeOracleFee,
           manifest,
           manifestHash,
-          this.applyTxDefaults(txOptions)
+          txOptions
         )
       ).wait();
 
@@ -567,11 +570,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;
@@ -692,7 +691,7 @@ export class EscrowClient extends BaseEthersClient {
             url,
             hash,
             fundsToReserve,
-            this.applyTxDefaults(txOptions)
+            txOptions
           )
         ).wait();
       } else {
@@ -700,7 +699,7 @@ export class EscrowClient extends BaseEthersClient {
           await escrowContract['storeResults(string,string)'](
             url,
             hash,
-            this.applyTxDefaults(txOptions)
+            txOptions
           )
         ).wait();
       }
@@ -756,9 +755,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);
@@ -898,7 +895,7 @@ export class EscrowClient extends BaseEthersClient {
             finalResultsHash,
             id,
             forceComplete,
-            this.applyTxDefaults(txOptions)
+            txOptions
           )
         ).wait();
       } else {
@@ -912,7 +909,7 @@ export class EscrowClient extends BaseEthersClient {
             finalResultsHash,
             id,
             forceComplete,
-            this.applyTxDefaults(txOptions)
+            txOptions
           )
         ).wait();
       }
@@ -966,9 +963,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);
     }
@@ -1014,11 +1009,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);
     }
@@ -1076,10 +1067,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;
@@ -1169,7 +1157,6 @@ export class EscrowClient extends BaseEthersClient {
     forceComplete = false,
     txOptions: Overrides = {}
   ): Promise<TransactionLikeWithNonce> {
-    txOptions = this.applyTxDefaults(txOptions);
     await this.ensureCorrectBulkPayoutInput(
       escrowAddress,
       recipients,
@@ -1940,6 +1927,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**
@@ -1956,7 +1944,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;
     }
@@ -1989,7 +1980,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),
       {
@@ -2004,7 +1995,8 @@ export class EscrowUtils {
         orderDirection: orderDirection,
         first: first,
         skip: skip,
-      }
+      },
+      options
     );
     return (escrows || []).map((e) => mapEscrow(e, networkData.chainId));
   }
@@ -2062,6 +2054,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**
@@ -2074,7 +2067,8 @@ export class EscrowUtils {
    */
   public static async getEscrow(
     chainId: ChainId,
-    escrowAddress: string
+    escrowAddress: string,
+    options?: SubgraphOptions
   ): Promise<IEscrow | null> {
     const networkData = NETWORKS[chainId];
 
@@ -2086,10 +2080,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;
 
@@ -2132,6 +2127,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**
@@ -2153,7 +2149,8 @@ export class EscrowUtils {
    * ```
    */
   public static async getStatusEvents(
-    filter: IStatusEventFilter
+    filter: IStatusEventFilter,
+    options?: SubgraphOptions
   ): Promise<IStatusEvent[]> {
     const {
       chainId,
@@ -2187,7 +2184,7 @@ export class EscrowUtils {
 
     const statusNames = effectiveStatuses.map((status) => EscrowStatus[status]);
 
-    const data = await gqlFetch<{
+    const data = await customGqlFetch<{
       escrowStatusEvents: StatusEvent[];
     }>(
       getSubgraphUrl(networkData),
@@ -2200,7 +2197,8 @@ export class EscrowUtils {
         orderDirection,
         first: Math.min(first, 1000),
         skip,
-      }
+      },
+      options
     );
 
     if (!data || !data['escrowStatusEvents']) {
@@ -2224,6 +2222,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**
@@ -2241,7 +2240,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;
@@ -2258,7 +2260,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),
       {
@@ -2269,7 +2271,8 @@ export class EscrowUtils {
         first: Math.min(first, 1000),
         skip,
         orderDirection,
-      }
+      },
+      options
     );
     if (!payouts) {
       return [];
@@ -2318,6 +2321,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**
@@ -2332,16 +2336,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)) {
@@ -2356,17 +2354,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 [];
@@ -2418,6 +2421,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**
@@ -2430,7 +2434,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;
@@ -2439,12 +2444,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,18 @@ 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;
+  /**
+   * Optional indexer identifier. When provided, requests target
+   * `{gateway}/deployments/id/<DEPLOYMENT_ID>/indexers/id/<INDEXER_ID>`.
+   */
+  indexerId?: string;
+}

package/src/kvstore.ts

@@ -17,15 +17,14 @@ import {
   ErrorUnsupportedChainID,
   InvalidKeyError,
 } from './error';
-import gqlFetch from 'graphql-request';
 import { NetworkData } from './types';
-import { getSubgraphUrl, isValidUrl } from './utils';
+import { getSubgraphUrl, customGqlFetch, isValidUrl } from './utils';
 import {
   GET_KVSTORE_BY_ADDRESS_AND_KEY_QUERY,
   GET_KVSTORE_BY_ADDRESS_QUERY,
 } from './graphql/queries/kvstore';
 import { KVStoreData } from './graphql';
-import { IKVStore } from './interfaces';
+import { IKVStore, SubgraphOptions } from './interfaces';
 /**
  * ## Introduction
  *
@@ -175,9 +174,7 @@ export class KVStoreClient extends BaseEthersClient {
   ): Promise<void> {
     if (key === '') throw ErrorKVStoreEmptyKey;
     try {
-      await (
-        await this.contract.set(key, value, this.applyTxDefaults(txOptions))
-      ).wait();
+      await (await this.contract.set(key, value, txOptions)).wait();
     } catch (e) {
       if (e instanceof Error) throw Error(`Failed to set value: ${e.message}`);
     }
@@ -222,13 +219,7 @@ export class KVStoreClient extends BaseEthersClient {
     if (keys.includes('')) throw ErrorKVStoreEmptyKey;
 
     try {
-      await (
-        await this.contract.setBulk(
-          keys,
-          values,
-          this.applyTxDefaults(txOptions)
-        )
-      ).wait();
+      await (await this.contract.setBulk(keys, values, txOptions)).wait();
     } catch (e) {
       if (e instanceof Error)
         throw Error(`Failed to set bulk values: ${e.message}`);
@@ -281,7 +272,7 @@ export class KVStoreClient extends BaseEthersClient {
         await this.contract.setBulk(
           [urlKey, hashKey],
           [url, contentHash],
-          this.applyTxDefaults(txOptions)
+          txOptions
         )
       ).wait();
     } catch (e) {
@@ -294,6 +285,7 @@ export class KVStoreClient extends BaseEthersClient {
    *
    * @param {string} address Address from which to get the key value.
    * @param {string} key Key to obtain the value.
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {string} Value of the key.
    *
    *
@@ -365,6 +357,7 @@ export class KVStoreUtils {
    *
    * @param {ChainId} chainId Network in which the KVStore is deployed
    * @param {string} address Address of the KVStore
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {Promise<IKVStore[]>} KVStore data
    * @throws {ErrorUnsupportedChainID} - Thrown if the network's chainId is not supported
    * @throws {ErrorInvalidAddress} - Thrown if the Address sent is invalid
@@ -380,7 +373,8 @@ export class KVStoreUtils {
    */
   public static async getKVStoreData(
     chainId: ChainId,
-    address: string
+    address: string,
+    options?: SubgraphOptions
   ): Promise<IKVStore[]> {
     const networkData = NETWORKS[chainId];
 
@@ -392,10 +386,11 @@ export class KVStoreUtils {
       throw ErrorInvalidAddress;
     }
 
-    const { kvstores } = await gqlFetch<{ kvstores: KVStoreData[] }>(
+    const { kvstores } = await customGqlFetch<{ kvstores: KVStoreData[] }>(
       getSubgraphUrl(networkData),
       GET_KVSTORE_BY_ADDRESS_QUERY(),
-      { address: address.toLowerCase() }
+      { address: address.toLowerCase() },
+      options
     );
 
     const kvStoreData = kvstores.map((item) => ({
@@ -412,6 +407,7 @@ export class KVStoreUtils {
    * @param {ChainId} chainId Network in which the KVStore is deployed
    * @param {string} address Address from which to get the key value.
    * @param {string} key Key to obtain the value.
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {Promise<string>} Value of the key.
    * @throws {ErrorUnsupportedChainID} - Thrown if the network's chainId is not supported
    * @throws {ErrorInvalidAddress} - Thrown if the Address sent is invalid
@@ -433,7 +429,8 @@ export class KVStoreUtils {
   public static async get(
     chainId: ChainId,
     address: string,
-    key: string
+    key: string,
+    options?: SubgraphOptions
   ): Promise<string> {
     if (key === '') throw ErrorKVStoreEmptyKey;
     if (!ethers.isAddress(address)) throw ErrorInvalidAddress;
@@ -444,10 +441,11 @@ export class KVStoreUtils {
       throw ErrorUnsupportedChainID;
     }
 
-    const { kvstores } = await gqlFetch<{ kvstores: KVStoreData[] }>(
+    const { kvstores } = await customGqlFetch<{ kvstores: KVStoreData[] }>(
       getSubgraphUrl(networkData),
       GET_KVSTORE_BY_ADDRESS_AND_KEY_QUERY(),
-      { address: address.toLowerCase(), key }
+      { address: address.toLowerCase(), key },
+      options
     );
 
     if (!kvstores || kvstores.length === 0) {
@@ -463,6 +461,7 @@ export class KVStoreUtils {
    * @param {ChainId} chainId Network in which the KVStore is deployed
    * @param {string} address Address from which to get the URL value.
    * @param {string} urlKey Configurable URL key. `url` by default.
+   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
    * @returns {Promise<string>} URL value for the given address if it exists, and the content is valid
    *
    * **Code example**
@@ -480,7 +479,8 @@ export class KVStoreUtils {
   public static async getFileUrlAndVerifyHash(
     chainId: ChainId,
     address: string,
-    urlKey = 'url'
+    urlKey = 'url',
+    options?: SubgraphOptions
   ): Promise<string> {
     if (!ethers.isAddress(address)) throw ErrorInvalidAddress;
     const hashKey = urlKey + '_hash';
@@ -489,7 +489,7 @@ export class KVStoreUtils {
       hash = '';
 
     try {
-      url = await this.get(chainId, address, urlKey);
+      url = await this.get(chainId, address, urlKey, options);
     } catch (e) {
       if (e instanceof Error) throw Error(`Failed to get URL: ${e.message}`);
     }
@@ -539,12 +539,14 @@ export class KVStoreUtils {
    */
   public static async getPublicKey(
     chainId: ChainId,
-    address: string
+    address: string,
+    options?: SubgraphOptions
   ): Promise<string> {
     const publicKeyUrl = await this.getFileUrlAndVerifyHash(
       chainId,
       address,
-      KVStoreKeys.publicKey
+      KVStoreKeys.publicKey,
+      options
     );
 
     if (publicKeyUrl === '') {