@human-protocol/sdk 3.0.8 → 4.0.1

package/src/escrow.ts

@@ -9,10 +9,10 @@ import {
   HMToken,
   HMToken__factory,
 } from '@human-protocol/core/typechain-types';
-import { ContractRunner, EventLog, Overrides, ethers } from 'ethers';
+import { ContractRunner, EventLog, Overrides, Signer, ethers } from 'ethers';
 import gqlFetch from 'graphql-request';
 import { BaseEthersClient } from './base';
-import { DEFAULT_TX_ID, NETWORKS } from './constants';
+import { ESCROW_BULK_PAYOUT_MAX_ITEMS, NETWORKS } from './constants';
 import { requiresSigner } from './decorators';
 import { ChainId, OrderDirection } from './enums';
 import {
@@ -33,6 +33,7 @@ import {
   ErrorProviderDoesNotExist,
   ErrorRecipientAndAmountsMustBeSameLength,
   ErrorRecipientCannotBeEmptyArray,
+  ErrorTooManyRecipients,
   ErrorTotalFeeMustBeLessThanHundred,
   ErrorTransferEventNotFoundInTransactionLogs,
   ErrorUnsupportedChainID,
@@ -52,25 +53,31 @@ import {
   EscrowStatus,
   EscrowWithdraw,
   NetworkData,
+  TransactionLikeWithNonce,
 } from './types';
-import { getSubgraphUrl, isValidUrl, throwError } from './utils';
+import {
+  getSubgraphUrl,
+  getUnixTimestamp,
+  isValidUrl,
+  throwError,
+} from './utils';
 
 /**
  * ## Introduction
  *
- * This client enables to perform actions on Escrow contracts and obtain information from both the contracts and subgraph.
+ * This client enables performing actions on Escrow contracts and obtaining information from both the contracts and subgraph.
  *
  * Internally, the SDK will use one network or another according to the network ID of the `runner`.
  * To use this client, it is recommended to initialize it using the static `build` method.
  *
  * ```ts
- * static async build(runner: ContractRunner);
+ * static async build(runner: ContractRunner): Promise<EscrowClient>;
  * ```
  *
  * A `Signer` or a `Provider` should be passed depending on the use case of this module:
  *
- * - **Signer**: when the user wants to use this model in order to send transactions caling the contract functions.
- * - **Provider**: when the user wants to use this model in order to get information from the contracts or subgraph.
+ * - **Signer**: when the user wants to use this model to send transactions calling the contract functions.
+ * - **Provider**: when the user wants to use this model to get information from the contracts or subgraph.
  *
  * ## Installation
  *
@@ -88,21 +95,21 @@ import { getSubgraphUrl, isValidUrl, throwError } from './utils';
  *
  * ### Signer
  *
- * **Using private key(backend)**
+ * **Using private key (backend)**
  *
  * ```ts
  * import { EscrowClient } from '@human-protocol/sdk';
  * import { Wallet, providers } from 'ethers';
  *
  * const rpcUrl = 'YOUR_RPC_URL';
- * const privateKey = 'YOUR_PRIVATE_KEY'
+ * const privateKey = 'YOUR_PRIVATE_KEY';
  *
  * const provider = new providers.JsonRpcProvider(rpcUrl);
  * const signer = new Wallet(privateKey, provider);
  * const escrowClient = await EscrowClient.build(signer);
  * ```
  *
- * **Using Wagmi(frontend)**
+ * **Using Wagmi (frontend)**
  *
  * ```ts
  * import { useSigner, useChainId } from 'wagmi';
@@ -151,7 +158,7 @@ export class EscrowClient extends BaseEthersClient {
    * @throws {ErrorProviderDoesNotExist} Thrown if the provider does not exist for the provided Signer
    * @throws {ErrorUnsupportedChainID} Thrown if the network's chainId is not supported
    */
-  public static async build(runner: ContractRunner) {
+  public static async build(runner: ContractRunner): Promise<EscrowClient> {
     if (!runner.provider) {
       throw ErrorProviderDoesNotExist;
     }
@@ -184,11 +191,11 @@ 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 pay outs.
+   * @param {string} tokenAddress Token address to use for payouts.
    * @param {string[]} trustedHandlers Array of addresses that can perform actions on the contract.
    * @param {string} jobRequesterId Job Requester Id
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns {Promise<string>} Return the address of the escrow created.
+   * @returns {Promise<string>} Returns the address of the escrow created.
    *
    *
    * **Code example**
@@ -200,7 +207,7 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -273,7 +280,7 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -284,10 +291,10 @@ export class EscrowClient extends BaseEthersClient {
    *    recordingOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
    *    reputationOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
    *    exchangeOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    recordingOracleFee: bigint.from('10'),
-   *    reputationOracleFee: bigint.from('10'),
-   *    exchangeOracleFee: bigint.from('10'),
-   *    manifestUrl: 'htttp://localhost/manifest.json',
+   *    recordingOracleFee: BigInt('10'),
+   *    reputationOracleFee: BigInt('10'),
+   *    exchangeOracleFee: BigInt('10'),
+   *    manifestUrl: 'http://localhost/manifest.json',
    *    manifestHash: 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079',
    * };
    * await escrowClient.setup(escrowAddress, escrowConfig);
@@ -393,7 +400,7 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -441,10 +448,10 @@ export class EscrowClient extends BaseEthersClient {
   }
 
   /**
-   * This function stores the results url and hash.
+   * This function stores the results URL and hash.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @param {string} url Results file url.
+   * @param {string} url Results file URL.
    * @param {string} hash Results file hash.
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
@@ -459,13 +466,13 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
    * const escrowClient = await EscrowClient.build(signer);
    *
-   * await storeResults.storeResults('0x62dD51230A30401C455c8398d06F85e4EaB6309f', 'http://localhost/results.json', 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079');
+   * await escrowClient.storeResults('0x62dD51230A30401C455c8398d06F85e4EaB6309f', 'http://localhost/results.json', 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079');
    * ```
    */
   @requiresSigner
@@ -523,7 +530,7 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -561,9 +568,10 @@ export class EscrowClient extends BaseEthersClient {
    * @param {string} escrowAddress Escrow address to payout.
    * @param {string[]} recipients Array of recipient addresses.
    * @param {bigint[]} amounts Array of amounts the recipients will receive.
-   * @param {string} finalResultsUrl Final results file url.
+   * @param {string} finalResultsUrl Final results file URL.
    * @param {string} finalResultsHash Final results file hash.
-   * @param {string} forceComplete Indicates if remaining balance should be transferred to the escrow creator (optional, defaults to false).
+   * @param {number} txId Transaction ID.
+   * @param {boolean} forceComplete Indicates if remaining balance should be transferred to the escrow creator (optional, defaults to false).
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
@@ -577,7 +585,7 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -586,9 +594,10 @@ export class EscrowClient extends BaseEthersClient {
    * const recipients = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'];
    * const amounts = [ethers.parseUnits(5, 'ether'), ethers.parseUnits(10, 'ether')];
    * const resultsUrl = 'http://localhost/results.json';
-   * const resultsHash'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079';
+   * const resultsHash = 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079';
+   * const txId = 1;
    *
-   * await escrowClient.bulkPayOut('0x62dD51230A30401C455c8398d06F85e4EaB6309f', recipients, amounts, resultsUrl, resultsHash);
+   * await escrowClient.bulkPayOut('0x62dD51230A30401C455c8398d06F85e4EaB6309f', recipients, amounts, resultsUrl, resultsHash, txId);
    * ```
    */
   @requiresSigner
@@ -598,57 +607,17 @@ export class EscrowClient extends BaseEthersClient {
     amounts: bigint[],
     finalResultsUrl: string,
     finalResultsHash: string,
+    txId: number,
     forceComplete = false,
     txOptions: Overrides = {}
   ): Promise<void> {
-    if (!ethers.isAddress(escrowAddress)) {
-      throw ErrorInvalidEscrowAddressProvided;
-    }
-
-    if (recipients.length === 0) {
-      throw ErrorRecipientCannotBeEmptyArray;
-    }
-
-    if (amounts.length === 0) {
-      throw ErrorAmountsCannotBeEmptyArray;
-    }
-
-    if (recipients.length !== amounts.length) {
-      throw ErrorRecipientAndAmountsMustBeSameLength;
-    }
-
-    recipients.forEach((recipient) => {
-      if (!ethers.isAddress(recipient)) {
-        throw new InvalidEthereumAddressError(recipient);
-      }
-    });
-
-    if (!finalResultsUrl) {
-      throw ErrorUrlIsEmptyString;
-    }
-
-    if (!isValidUrl(finalResultsUrl)) {
-      throw ErrorInvalidUrl;
-    }
-
-    if (!finalResultsHash) {
-      throw ErrorHashIsEmptyString;
-    }
-
-    const balance = await this.getBalance(escrowAddress);
-
-    let totalAmount = 0n;
-    amounts.forEach((amount) => {
-      totalAmount = totalAmount + amount;
-    });
-
-    if (balance < totalAmount) {
-      throw ErrorEscrowDoesNotHaveEnoughBalance;
-    }
-
-    if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
-      throw ErrorEscrowAddressIsNotProvidedByFactory;
-    }
+    await this.ensureCorrectBulkPayoutInput(
+      escrowAddress,
+      recipients,
+      amounts,
+      finalResultsUrl,
+      finalResultsHash
+    );
 
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
@@ -661,7 +630,7 @@ export class EscrowClient extends BaseEthersClient {
             amounts,
             finalResultsUrl,
             finalResultsHash,
-            DEFAULT_TX_ID,
+            txId,
             forceComplete,
             txOptions
           )
@@ -675,7 +644,7 @@ export class EscrowClient extends BaseEthersClient {
             amounts,
             finalResultsUrl,
             finalResultsHash,
-            DEFAULT_TX_ID,
+            txId,
             txOptions
           )
         ).wait();
@@ -703,7 +672,7 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -788,13 +757,13 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
    * const escrowClient = await EscrowClient.build(signer);
    *
-   * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266']
+   * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'];
    * await escrowClient.addTrustedHandlers('0x62dD51230A30401C455c8398d06F85e4EaB6309f', trustedHandlers);
    * ```
    */
@@ -852,7 +821,7 @@ export class EscrowClient extends BaseEthersClient {
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -927,11 +896,177 @@ export class EscrowClient extends BaseEthersClient {
     }
   }
 
+  /**
+   * Creates a prepared transaction for bulk payout without immediately sending it.
+   * @param {string} escrowAddress Escrow address to payout.
+   * @param {string[]} recipients Array of recipient addresses.
+   * @param {bigint[]} amounts Array of amounts the recipients will receive.
+   * @param {string} finalResultsUrl Final results file URL.
+   * @param {string} finalResultsHash Final results file hash.
+   * @param {number} txId Transaction ID.
+   * @param {boolean} forceComplete Indicates if remaining balance should be transferred to the escrow creator (optional, defaults to false).
+   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns Returns object with raw transaction and signed transaction hash
+   *
+   * **Code example**
+   *
+   * > Only Reputation Oracle or a trusted handler can call it.
+   *
+   * ```ts
+   * import { ethers, Wallet, providers } from 'ethers';
+   * import { EscrowClient } from '@human-protocol/sdk';
+   *
+   * const rpcUrl = 'YOUR_RPC_URL';
+   * const privateKey = 'YOUR_PRIVATE_KEY'
+   *
+   * const provider = new providers.JsonRpcProvider(rpcUrl);
+   * const signer = new Wallet(privateKey, provider);
+   * const escrowClient = await EscrowClient.build(signer);
+   *
+   * const recipients = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'];
+   * const amounts = [ethers.parseUnits(5, 'ether'), ethers.parseUnits(10, 'ether')];
+   * const resultsUrl = 'http://localhost/results.json';
+   * const resultsHash = 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079';
+   * const txId = 1;
+   *
+   * const rawTransaction = await escrowClient.createBulkPayoutTransaction('0x62dD51230A30401C455c8398d06F85e4EaB6309f', recipients, amounts, resultsUrl, resultsHash, txId);
+   * console.log('Raw transaction:', rawTransaction);
+   *
+   * const signedTransaction = await signer.signTransaction(rawTransaction);
+   * console.log('Tx hash:', ethers.keccak256(signedTransaction));
+   * (await signer.sendTransaction(rawTransaction)).wait();
+   */
+  @requiresSigner
+  async createBulkPayoutTransaction(
+    escrowAddress: string,
+    recipients: string[],
+    amounts: bigint[],
+    finalResultsUrl: string,
+    finalResultsHash: string,
+    txId: number,
+    forceComplete = false,
+    txOptions: Overrides = {}
+  ): Promise<TransactionLikeWithNonce> {
+    await this.ensureCorrectBulkPayoutInput(
+      escrowAddress,
+      recipients,
+      amounts,
+      finalResultsUrl,
+      finalResultsHash
+    );
+
+    const signer = this.runner as Signer;
+    try {
+      const escrowContract = this.getEscrowContract(escrowAddress);
+
+      const populatedTransaction = await escrowContract[
+        'bulkPayOut(address[],uint256[],string,string,uint256,bool)'
+      ].populateTransaction(
+        recipients,
+        amounts,
+        finalResultsUrl,
+        finalResultsHash,
+        txId,
+        forceComplete,
+        txOptions
+      );
+
+      /**
+       * Safety-belt: explicitly set the passed nonce
+       * because 'populateTransaction' return value
+       * doesn't mention it even in library docs,
+       * even though it includes if from txOptions.
+       */
+      if (typeof txOptions.nonce === 'number') {
+        populatedTransaction.nonce = txOptions.nonce;
+      } else {
+        populatedTransaction.nonce = await signer.getNonce();
+      }
+      /**
+       * It's needed to get all necessary info for tx object
+       * before signing it, e.g.:
+       * - type
+       * - chainId
+       * - fees params
+       * - etc.
+       *
+       * All information is needed in order to get proper hash value
+       */
+      const preparedTransaction =
+        await signer.populateTransaction(populatedTransaction);
+
+      return preparedTransaction as TransactionLikeWithNonce;
+    } catch (e) {
+      return throwError(e);
+    }
+  }
+
+  private async ensureCorrectBulkPayoutInput(
+    escrowAddress: string,
+    recipients: string[],
+    amounts: bigint[],
+    finalResultsUrl: string,
+    finalResultsHash: string
+  ): Promise<void> {
+    if (!ethers.isAddress(escrowAddress)) {
+      throw ErrorInvalidEscrowAddressProvided;
+    }
+
+    if (recipients.length === 0) {
+      throw ErrorRecipientCannotBeEmptyArray;
+    }
+
+    if (recipients.length > ESCROW_BULK_PAYOUT_MAX_ITEMS) {
+      throw ErrorTooManyRecipients;
+    }
+
+    if (amounts.length === 0) {
+      throw ErrorAmountsCannotBeEmptyArray;
+    }
+
+    if (recipients.length !== amounts.length) {
+      throw ErrorRecipientAndAmountsMustBeSameLength;
+    }
+
+    recipients.forEach((recipient) => {
+      if (!ethers.isAddress(recipient)) {
+        throw new InvalidEthereumAddressError(recipient);
+      }
+    });
+
+    if (!finalResultsUrl) {
+      throw ErrorUrlIsEmptyString;
+    }
+
+    if (!isValidUrl(finalResultsUrl)) {
+      throw ErrorInvalidUrl;
+    }
+
+    if (!finalResultsHash) {
+      throw ErrorHashIsEmptyString;
+    }
+
+    const balance = await this.getBalance(escrowAddress);
+
+    let totalAmount = 0n;
+    amounts.forEach((amount) => {
+      totalAmount = totalAmount + amount;
+    });
+
+    if (balance < totalAmount) {
+      throw ErrorEscrowDoesNotHaveEnoughBalance;
+    }
+
+    if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
+      throw ErrorEscrowAddressIsNotProvidedByFactory;
+    }
+  }
+
   /**
    * This function returns the balance for a specified escrow address.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {bigint} Balance of the escrow in the token used to fund it.
+   * @returns {Promise<bigint>} Balance of the escrow in the token used to fund it.
    *
    * **Code example**
    *
@@ -942,7 +1077,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const balance = await escrowClient.getBalance('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -975,7 +1110,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the manifest file hash.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {string} Hash of the manifest file content.
+   * @returns {Promise<string>} Hash of the manifest file content.
    *
    * **Code example**
    *
@@ -986,7 +1121,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const manifestHash = await escrowClient.getManifestHash('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1013,7 +1148,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the manifest file URL.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {string} Url of the manifest.
+   * @returns {Promise<string>} Url of the manifest.
    *
    * **Code example**
    *
@@ -1024,7 +1159,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const manifestUrl = await escrowClient.getManifestUrl('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1051,7 +1186,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the results file URL.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {string} Results file url.
+   * @returns {Promise<string>} Results file url.
    *
    * **Code example**
    *
@@ -1062,7 +1197,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const resultsUrl = await escrowClient.getResultsUrl('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1089,7 +1224,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the intermediate results file URL.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {string} Url of the file that store results from Recording Oracle.
+   * @returns {Promise<string>} Url of the file that store results from Recording Oracle.
    *
    * **Code example**
    *
@@ -1100,9 +1235,9 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
-   * const intemediateResultsUrl = await escrowClient.getIntermediateResultsUrl('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * const intermediateResultsUrl = await escrowClient.getIntermediateResultsUrl('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
    */
   async getIntermediateResultsUrl(escrowAddress: string): Promise<string> {
@@ -1118,7 +1253,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.intermediateResultsUrl();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1127,7 +1262,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the token address used for funding the escrow.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {string} Address of the token used to fund the escrow.
+   * @returns {Promise<string>} Address of the token used to fund the escrow.
    *
    * **Code example**
    *
@@ -1138,7 +1273,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const tokenAddress = await escrowClient.getTokenAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1165,7 +1300,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the current status of the escrow.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {EscrowStatus} Current status of the escrow.
+   * @returns {Promise<EscrowStatus>} Current status of the escrow.
    *
    * **Code example**
    *
@@ -1176,7 +1311,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const status = await escrowClient.getStatus('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1203,7 +1338,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the recording oracle address for a given escrow.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {string} Address of the Recording Oracle.
+   * @returns {Promise<string>} Address of the Recording Oracle.
    *
    * **Code example**
    *
@@ -1214,7 +1349,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const oracleAddress = await escrowClient.getRecordingOracleAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1232,7 +1367,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.recordingOracle();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1241,7 +1376,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the job launcher address for a given escrow.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {string} Address of the Job Launcher.
+   * @returns {Promise<string>} Address of the Job Launcher.
    *
    * **Code example**
    *
@@ -1252,7 +1387,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const jobLauncherAddress = await escrowClient.getJobLauncherAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1270,7 +1405,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.launcher();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1279,7 +1414,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the reputation oracle address for a given escrow.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {EscrowStatus} Address of the Reputation Oracle.
+   * @returns {Promise<string>} Address of the Reputation Oracle.
    *
    * **Code example**
    *
@@ -1290,7 +1425,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const oracleAddress = await escrowClient.getReputationOracleAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1308,7 +1443,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.reputationOracle();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1317,7 +1452,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the exchange oracle address for a given escrow.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {EscrowStatus} Address of the Exchange Oracle.
+   * @returns {Promise<string>} Address of the Exchange Oracle.
    *
    * **Code example**
    *
@@ -1328,7 +1463,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const oracleAddress = await escrowClient.getExchangeOracleAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1346,7 +1481,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.exchangeOracle();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1355,7 +1490,7 @@ export class EscrowClient extends BaseEthersClient {
    * This function returns the escrow factory address for a given escrow.
    *
    * @param {string} escrowAddress Address of the escrow.
-   * @returns {EscrowStatus} Address of the escrow factory.
+   * @returns {Promise<string>} Address of the escrow factory.
    *
    * **Code example**
    *
@@ -1366,7 +1501,7 @@ export class EscrowClient extends BaseEthersClient {
    * const rpcUrl = 'YOUR_RPC_URL';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const escrowClient = await EscrowClient.build(signer);
+   * const escrowClient = await EscrowClient.build(provider);
    *
    * const factoryAddress = await escrowClient.getFactoryAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
    * ```
@@ -1384,12 +1519,11 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.escrowFactory();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
 }
-
 /**
  * ## Introduction
  *
@@ -1417,7 +1551,7 @@ export class EscrowClient extends BaseEthersClient {
  * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
  *
  * const escrowAddresses = new EscrowUtils.getEscrows({
- *   network: ChainId.POLYGON_AMOY
+ *   chainId: ChainId.POLYGON_AMOY
  * });
  * ```
  */
@@ -1449,20 +1583,11 @@ export class EscrowUtils {
    * enum ChainId {
    *   ALL = -1,
    *   MAINNET = 1,
-   *   RINKEBY = 4,
-   *   GOERLI = 5,
+   *   SEPOLIA = 11155111,
    *   BSC_MAINNET = 56,
    *   BSC_TESTNET = 97,
    *   POLYGON = 137,
-   *   POLYGON_MUMBAI = 80001,
    *   POLYGON_AMOY=80002,
-   *   MOONBEAM = 1284,
-   *   MOONBASE_ALPHA = 1287,
-   *   AVALANCHE = 43114,
-   *   AVALANCHE_TESTNET = 43113,
-   *   CELO = 42220,
-   *   CELO_ALFAJORES = 44787,
-   *    = 1273227453,
    *   LOCALHOST = 1338,
    * }
    * ```
@@ -1572,8 +1697,8 @@ export class EscrowUtils {
                 ([, value]) => value === filter.status
               )?.[0]
             : undefined,
-        from: filter.from ? +filter.from.getTime() / 1000 : undefined,
-        to: filter.to ? +filter.to.getTime() / 1000 : undefined,
+        from: filter.from ? getUnixTimestamp(filter.from) : undefined,
+        to: filter.to ? getUnixTimestamp(filter.to) : undefined,
         orderDirection: orderDirection,
         first: first,
         skip: skip,
@@ -1599,19 +1724,11 @@ export class EscrowUtils {
    * enum ChainId {
    *   ALL = -1,
    *   MAINNET = 1,
-   *   RINKEBY = 4,
-   *   GOERLI = 5,
+   *   SEPOLIA = 11155111,
    *   BSC_MAINNET = 56,
    *   BSC_TESTNET = 97,
    *   POLYGON = 137,
-   *   POLYGON_MUMBAI = 80001,
    *   POLYGON_AMOY = 80002,
-   *   MOONBEAM = 1284,
-   *   MOONBASE_ALPHA = 1287,
-   *   AVALANCHE = 43114,
-   *   AVALANCHE_TESTNET = 43113,
-   *   CELO = 42220,
-   *   CELO_ALFAJORES = 44787,
    *   LOCALHOST = 1338,
    * }
    * ```
@@ -1687,23 +1804,12 @@ export class EscrowUtils {
    * enum ChainId {
    *   ALL = -1,
    *   MAINNET = 1,
-   *   RINKEBY = 4,
-   *   GOERLI = 5,
    *   SEPOLIA = 11155111,
    *   BSC_MAINNET = 56,
    *   BSC_TESTNET = 97,
    *   POLYGON = 137,
-   *   POLYGON_MUMBAI = 80001,
    *   POLYGON_AMOY = 80002,
-   *   MOONBEAM = 1284,
-   *   MOONBASE_ALPHA = 1287,
-   *   AVALANCHE = 43114,
-   *   AVALANCHE_TESTNET = 43113,
-   *   CELO = 42220,
-   *   CELO_ALFAJORES = 44787,
    *   LOCALHOST = 1338,
-   *   XLAYER_TESTNET = 195,
-   *   XLAYER = 196,
    * }
    * ```
    *
@@ -1793,8 +1899,8 @@ export class EscrowUtils {
       GET_STATUS_UPDATES_QUERY(from, to, launcher),
       {
         status: statusNames,
-        from: from ? Math.floor(from.getTime() / 1000) : undefined,
-        to: to ? Math.floor(to.getTime() / 1000) : undefined,
+        from: from ? getUnixTimestamp(from) : undefined,
+        to: to ? getUnixTimestamp(to) : undefined,
         launcher: launcher || undefined,
         orderDirection: orderDirection,
         first: first,