@human-protocol/sdk 3.0.7 → 4.0.0

package/src/escrow.ts

@@ -1,5 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import {
+  ERC20,
+  ERC20__factory,
   Escrow,
   EscrowFactory,
   EscrowFactory__factory,
@@ -7,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 {
@@ -31,6 +33,7 @@ import {
   ErrorProviderDoesNotExist,
   ErrorRecipientAndAmountsMustBeSameLength,
   ErrorRecipientCannotBeEmptyArray,
+  ErrorTooManyRecipients,
   ErrorTotalFeeMustBeLessThanHundred,
   ErrorTransferEventNotFoundInTransactionLogs,
   ErrorUnsupportedChainID,
@@ -45,25 +48,31 @@ import {
   StatusEvent,
 } from './graphql';
 import { IEscrowConfig, IEscrowsFilter } from './interfaces';
-import { EscrowCancel, EscrowStatus, NetworkData } from './types';
+import {
+  EscrowCancel,
+  EscrowStatus,
+  EscrowWithdraw,
+  NetworkData,
+  TransactionLikeWithNonce,
+} from './types';
 import { getSubgraphUrl, 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
  *
@@ -81,21 +90,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';
@@ -124,7 +133,7 @@ export class EscrowClient extends BaseEthersClient {
    * **EscrowClient constructor**
    *
    * @param {ContractRunner} runner The Runner object to interact with the Ethereum network
-   * @param {NetworkData} network The network information required to connect to the Escrow contract
+   * @param {NetworkData} networkData The network information required to connect to the Escrow contract
    */
   constructor(runner: ContractRunner, networkData: NetworkData) {
     super(runner, networkData);
@@ -144,7 +153,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;
     }
@@ -177,11 +186,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**
@@ -193,7 +202,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);
@@ -266,7 +275,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);
@@ -277,10 +286,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);
@@ -370,69 +379,6 @@ export class EscrowClient extends BaseEthersClient {
     }
   }
 
-  /**
-   * This function creates and sets up an escrow.
-   *
-   * @param {string} tokenAddress Token address to use for pay outs.
-   * @param {string[]} trustedHandlers Array of addresses that can perform actions on the contract.
-   * @param {string} jobRequesterId Job Requester Id
-   * @param {IEscrowConfig} escrowConfig Configuration object with escrow settings.
-   * @returns {Promise<string>} Returns the address of the escrow created.
-   *
-   *
-   * **Code example**
-   *
-   * ```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 tokenAddress = '0x0376D26246Eb35FF4F9924cF13E6C05fd0bD7Fb4';
-   * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'];
-   * const jobRequesterId = "job-requester-id";
-   *
-   * const escrowConfig = {
-   *    recordingOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    reputationOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    exchangeOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    recordingOracleFee: bigint.from('10'),
-   *    reputationOracleFee: bigint.from('10'),
-   *    exchangeOracleFee: bigint.from('10'),
-   *    manifestUrl: 'htttp://localhost/manifest.json',
-   *    manifestHash: 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079',
-   * };
-   *
-   * const escrowAddress = await escrowClient.createAndSetupEscrow(tokenAddress, trustedHandlers, jobRequesterId, escrowConfig);
-   * ```
-   */
-  @requiresSigner
-  async createAndSetupEscrow(
-    tokenAddress: string,
-    trustedHandlers: string[],
-    jobRequesterId: string,
-    escrowConfig: IEscrowConfig
-  ): Promise<string> {
-    try {
-      const escrowAddress = await this.createEscrow(
-        tokenAddress,
-        trustedHandlers,
-        jobRequesterId
-      );
-
-      await this.setup(escrowAddress, escrowConfig);
-
-      return escrowAddress;
-    } catch (e) {
-      return throwError(e);
-    }
-  }
-
   /**
    * This function adds funds of the chosen token to the escrow.
    *
@@ -449,7 +395,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);
@@ -497,10 +443,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.
@@ -515,13 +461,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
@@ -579,7 +525,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);
@@ -617,8 +563,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 {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.
    *
@@ -632,7 +580,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);
@@ -641,9 +589,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
@@ -653,70 +602,48 @@ 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);
-
-      await (
-        await escrowContract.bulkPayOut(
-          recipients,
-          amounts,
-          finalResultsUrl,
-          finalResultsHash,
-          DEFAULT_TX_ID,
-          txOptions
-        )
-      ).wait();
+      if (forceComplete) {
+        await (
+          await escrowContract[
+            'bulkPayOut(address[],uint256[],string,string,uint256,bool)'
+          ](
+            recipients,
+            amounts,
+            finalResultsUrl,
+            finalResultsHash,
+            txId,
+            forceComplete,
+            txOptions
+          )
+        ).wait();
+      } else {
+        await (
+          await escrowContract[
+            'bulkPayOut(address[],uint256[],string,string,uint256)'
+          ](
+            recipients,
+            amounts,
+            finalResultsUrl,
+            finalResultsHash,
+            txId,
+            txOptions
+          )
+        ).wait();
+      }
       return;
     } catch (e) {
       return throwError(e);
@@ -740,7 +667,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);
@@ -808,9 +735,10 @@ export class EscrowClient extends BaseEthersClient {
   }
 
   /**
-   * This function cancels the specified escrow, sends the balance to the canceler and selfdestructs the escrow contract.
+   * This function adds an array of addresses to the trusted handlers list.
    *
    * @param {string} escrowAddress Address of the escrow.
+   * @param {string[]} trustedHandlers Array of addresses of trusted handlers to add.
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
@@ -824,21 +752,36 @@ 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 escrowClient.abort('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'];
+   * await escrowClient.addTrustedHandlers('0x62dD51230A30401C455c8398d06F85e4EaB6309f', trustedHandlers);
    * ```
    */
   @requiresSigner
-  async abort(escrowAddress: string, txOptions: Overrides = {}): Promise<void> {
+  async addTrustedHandlers(
+    escrowAddress: string,
+    trustedHandlers: string[],
+    txOptions: Overrides = {}
+  ): Promise<void> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
     }
 
+    if (trustedHandlers.length === 0) {
+      throw ErrorListOfHandlersCannotBeEmpty;
+    }
+
+    trustedHandlers.forEach((trustedHandler) => {
+      if (!ethers.isAddress(trustedHandler)) {
+        throw new InvalidEthereumAddressError(trustedHandler);
+      }
+    });
+
     if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
       throw ErrorEscrowAddressIsNotProvidedByFactory;
     }
@@ -846,7 +789,9 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      await (await escrowContract.abort(txOptions)).wait();
+      await (
+        await escrowContract.addTrustedHandlers(trustedHandlers, txOptions)
+      ).wait();
       return;
     } catch (e) {
       return throwError(e);
@@ -854,53 +799,49 @@ export class EscrowClient extends BaseEthersClient {
   }
 
   /**
-   * This function sets the status of an escrow to completed.
+   * This function withdraws additional tokens in the escrow to the canceler.
    *
-   * @param {string} escrowAddress Address of the escrow.
-   * @param {string[]} trustedHandlers Array of addresses of trusted handlers to add.
+   * @param {string} escrowAddress Address of the escrow to withdraw.
+   * @param {string} tokenAddress Address of the token to withdraw.
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns Returns void if successful. Throws error if any.
+   * @returns {EscrowWithdraw} Returns the escrow withdrawal data including transaction hash and withdrawal amount. Throws error if any.
    *
    *
    * **Code example**
    *
-   * > Only Job Launcher or trusted handler can call it.
+   * > Only Job Launcher or a trusted handler can call it.
    *
    * ```ts
-   * import { Wallet, providers } from 'ethers';
+   * import { ethers, Wallet, providers } from 'ethers';
    * 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']
-   * await escrowClient.addTrustedHandlers('0x62dD51230A30401C455c8398d06F85e4EaB6309f', trustedHandlers);
+   * await escrowClient.withdraw(
+   *  '0x62dD51230A30401C455c8398d06F85e4EaB6309f',
+   *  '0x0376D26246Eb35FF4F9924cF13E6C05fd0bD7Fb4'
+   * );
    * ```
    */
   @requiresSigner
-  async addTrustedHandlers(
+  async withdraw(
     escrowAddress: string,
-    trustedHandlers: string[],
+    tokenAddress: string,
     txOptions: Overrides = {}
-  ): Promise<void> {
+  ): Promise<EscrowWithdraw> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
     }
 
-    if (trustedHandlers.length === 0) {
-      throw ErrorListOfHandlersCannotBeEmpty;
+    if (!ethers.isAddress(tokenAddress)) {
+      throw ErrorInvalidTokenAddress;
     }
 
-    trustedHandlers.forEach((trustedHandler) => {
-      if (!ethers.isAddress(trustedHandler)) {
-        throw new InvalidEthereumAddressError(trustedHandler);
-      }
-    });
-
     if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
       throw ErrorEscrowAddressIsNotProvidedByFactory;
     }
@@ -908,20 +849,219 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      await (
-        await escrowContract.addTrustedHandlers(trustedHandlers, txOptions)
+      const transactionReceipt = await (
+        await escrowContract.withdraw(tokenAddress, txOptions)
       ).wait();
-      return;
+
+      let amountTransferred: bigint | undefined = undefined;
+
+      const tokenContract: ERC20 = ERC20__factory.connect(
+        tokenAddress,
+        this.runner
+      );
+      if (transactionReceipt)
+        for (const log of transactionReceipt.logs) {
+          if (log.address === tokenAddress) {
+            const parsedLog = tokenContract.interface.parseLog({
+              topics: log.topics as string[],
+              data: log.data,
+            });
+
+            const from = parsedLog?.args[0];
+            if (parsedLog?.name === 'Transfer' && from === escrowAddress) {
+              amountTransferred = parsedLog?.args[2];
+              break;
+            }
+          }
+        }
+
+      if (amountTransferred === undefined) {
+        throw ErrorTransferEventNotFoundInTransactionLogs;
+      }
+
+      const escrowWithdrawData: EscrowWithdraw = {
+        txHash: transactionReceipt?.hash || '',
+        tokenAddress,
+        amountWithdrawn: amountTransferred,
+      };
+
+      return escrowWithdrawData;
     } catch (e) {
       return throwError(e);
     }
   }
 
+  /**
+   * 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**
    *
@@ -932,7 +1072,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');
    * ```
@@ -949,7 +1089,13 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      return escrowContract.getBalance();
+      try {
+        return await escrowContract.remainingFunds();
+      } catch {
+        // Use getBalance() method below if remainingFunds() is not available
+      }
+
+      return await escrowContract.getBalance();
     } catch (e) {
       return throwError(e);
     }
@@ -959,7 +1105,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**
    *
@@ -970,7 +1116,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');
    * ```
@@ -997,7 +1143,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**
    *
@@ -1008,7 +1154,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');
    * ```
@@ -1035,7 +1181,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**
    *
@@ -1046,7 +1192,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');
    * ```
@@ -1073,7 +1219,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**
    *
@@ -1084,9 +1230,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> {
@@ -1102,7 +1248,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.intermediateResultsUrl();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1111,7 +1257,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**
    *
@@ -1122,7 +1268,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');
    * ```
@@ -1149,7 +1295,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**
    *
@@ -1160,7 +1306,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');
    * ```
@@ -1187,7 +1333,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**
    *
@@ -1198,7 +1344,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');
    * ```
@@ -1216,7 +1362,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.recordingOracle();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1225,7 +1371,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**
    *
@@ -1236,7 +1382,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');
    * ```
@@ -1254,7 +1400,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.launcher();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1263,7 +1409,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**
    *
@@ -1274,7 +1420,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');
    * ```
@@ -1292,7 +1438,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.reputationOracle();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1301,7 +1447,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**
    *
@@ -1312,7 +1458,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');
    * ```
@@ -1330,7 +1476,7 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.exchangeOracle();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -1339,7 +1485,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**
    *
@@ -1350,7 +1496,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');
    * ```
@@ -1368,12 +1514,11 @@ export class EscrowClient extends BaseEthersClient {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
       return escrowContract.escrowFactory();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
 }
-
 /**
  * ## Introduction
  *
@@ -1401,7 +1546,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
  * });
  * ```
  */
@@ -1446,7 +1591,6 @@ export class EscrowUtils {
    *   AVALANCHE_TESTNET = 43113,
    *   CELO = 42220,
    *   CELO_ALFAJORES = 44787,
-   *    = 1273227453,
    *   LOCALHOST = 1338,
    * }
    * ```