@human-protocol/sdk 3.0.7 → 4.0.0

package/dist/escrow.js

@@ -28,19 +28,19 @@ const utils_1 = require("./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
  *
@@ -58,21 +58,21 @@ const utils_1 = require("./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';
@@ -99,7 +99,7 @@ class EscrowClient extends base_1.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, networkData) {
         super(runner, networkData);
@@ -142,11 +142,11 @@ class EscrowClient extends base_1.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**
@@ -158,7 +158,7 @@ class EscrowClient extends base_1.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);
@@ -209,7 +209,7 @@ class EscrowClient extends base_1.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);
@@ -220,10 +220,10 @@ class EscrowClient extends base_1.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);
@@ -272,57 +272,6 @@ class EscrowClient extends base_1.BaseEthersClient {
             return (0, utils_1.throwError)(e);
         }
     }
-    /**
-     * 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);
-     * ```
-     */
-    async createAndSetupEscrow(tokenAddress, trustedHandlers, jobRequesterId, escrowConfig) {
-        try {
-            const escrowAddress = await this.createEscrow(tokenAddress, trustedHandlers, jobRequesterId);
-            await this.setup(escrowAddress, escrowConfig);
-            return escrowAddress;
-        }
-        catch (e) {
-            return (0, utils_1.throwError)(e);
-        }
-    }
     /**
      * This function adds funds of the chosen token to the escrow.
      *
@@ -339,7 +288,7 @@ class EscrowClient extends base_1.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);
@@ -371,10 +320,10 @@ class EscrowClient extends base_1.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.
@@ -389,13 +338,13 @@ class EscrowClient extends base_1.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');
      * ```
      */
     async storeResults(escrowAddress, url, hash, txOptions = {}) {
@@ -440,7 +389,7 @@ class EscrowClient extends base_1.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);
@@ -471,8 +420,10 @@ class EscrowClient extends base_1.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.
      *
@@ -486,7 +437,7 @@ class EscrowClient extends base_1.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);
@@ -495,52 +446,22 @@ class EscrowClient extends base_1.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);
      * ```
      */
-    async bulkPayOut(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash, txOptions = {}) {
-        if (!ethers_1.ethers.isAddress(escrowAddress)) {
-            throw error_1.ErrorInvalidEscrowAddressProvided;
-        }
-        if (recipients.length === 0) {
-            throw error_1.ErrorRecipientCannotBeEmptyArray;
-        }
-        if (amounts.length === 0) {
-            throw error_1.ErrorAmountsCannotBeEmptyArray;
-        }
-        if (recipients.length !== amounts.length) {
-            throw error_1.ErrorRecipientAndAmountsMustBeSameLength;
-        }
-        recipients.forEach((recipient) => {
-            if (!ethers_1.ethers.isAddress(recipient)) {
-                throw new error_1.InvalidEthereumAddressError(recipient);
-            }
-        });
-        if (!finalResultsUrl) {
-            throw error_1.ErrorUrlIsEmptyString;
-        }
-        if (!(0, utils_1.isValidUrl)(finalResultsUrl)) {
-            throw error_1.ErrorInvalidUrl;
-        }
-        if (!finalResultsHash) {
-            throw error_1.ErrorHashIsEmptyString;
-        }
-        const balance = await this.getBalance(escrowAddress);
-        let totalAmount = 0n;
-        amounts.forEach((amount) => {
-            totalAmount = totalAmount + amount;
-        });
-        if (balance < totalAmount) {
-            throw error_1.ErrorEscrowDoesNotHaveEnoughBalance;
-        }
-        if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
-            throw error_1.ErrorEscrowAddressIsNotProvidedByFactory;
-        }
+    async bulkPayOut(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash, txId, forceComplete = false, txOptions = {}) {
+        await this.ensureCorrectBulkPayoutInput(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash);
         try {
             const escrowContract = this.getEscrowContract(escrowAddress);
-            await (await escrowContract.bulkPayOut(recipients, amounts, finalResultsUrl, finalResultsHash, constants_1.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) {
@@ -564,7 +485,7 @@ class EscrowClient extends base_1.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);
@@ -614,9 +535,10 @@ class EscrowClient extends base_1.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.
      *
@@ -630,25 +552,34 @@ class EscrowClient extends base_1.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);
      * ```
      */
-    async abort(escrowAddress, txOptions = {}) {
+    async addTrustedHandlers(escrowAddress, trustedHandlers, txOptions = {}) {
         if (!ethers_1.ethers.isAddress(escrowAddress)) {
             throw error_1.ErrorInvalidEscrowAddressProvided;
         }
+        if (trustedHandlers.length === 0) {
+            throw error_1.ErrorListOfHandlersCannotBeEmpty;
+        }
+        trustedHandlers.forEach((trustedHandler) => {
+            if (!ethers_1.ethers.isAddress(trustedHandler)) {
+                throw new error_1.InvalidEthereumAddressError(trustedHandler);
+            }
+        });
         if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
             throw error_1.ErrorEscrowAddressIsNotProvidedByFactory;
         }
         try {
             const escrowContract = this.getEscrowContract(escrowAddress);
-            await (await escrowContract.abort(txOptions)).wait();
+            await (await escrowContract.addTrustedHandlers(trustedHandlers, txOptions)).wait();
             return;
         }
         catch (e) {
@@ -656,62 +587,200 @@ class EscrowClient extends base_1.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'
+     * );
      * ```
      */
-    async addTrustedHandlers(escrowAddress, trustedHandlers, txOptions = {}) {
+    async withdraw(escrowAddress, tokenAddress, txOptions = {}) {
         if (!ethers_1.ethers.isAddress(escrowAddress)) {
             throw error_1.ErrorInvalidEscrowAddressProvided;
         }
-        if (trustedHandlers.length === 0) {
-            throw error_1.ErrorListOfHandlersCannotBeEmpty;
+        if (!ethers_1.ethers.isAddress(tokenAddress)) {
+            throw error_1.ErrorInvalidTokenAddress;
         }
-        trustedHandlers.forEach((trustedHandler) => {
-            if (!ethers_1.ethers.isAddress(trustedHandler)) {
-                throw new error_1.InvalidEthereumAddressError(trustedHandler);
-            }
-        });
         if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
             throw error_1.ErrorEscrowAddressIsNotProvidedByFactory;
         }
         try {
             const escrowContract = this.getEscrowContract(escrowAddress);
-            await (await escrowContract.addTrustedHandlers(trustedHandlers, txOptions)).wait();
-            return;
+            const transactionReceipt = await (await escrowContract.withdraw(tokenAddress, txOptions)).wait();
+            let amountTransferred = undefined;
+            const tokenContract = typechain_types_1.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,
+                            data: log.data,
+                        });
+                        const from = parsedLog?.args[0];
+                        if (parsedLog?.name === 'Transfer' && from === escrowAddress) {
+                            amountTransferred = parsedLog?.args[2];
+                            break;
+                        }
+                    }
+                }
+            if (amountTransferred === undefined) {
+                throw error_1.ErrorTransferEventNotFoundInTransactionLogs;
+            }
+            const escrowWithdrawData = {
+                txHash: transactionReceipt?.hash || '',
+                tokenAddress,
+                amountWithdrawn: amountTransferred,
+            };
+            return escrowWithdrawData;
         }
         catch (e) {
             return (0, utils_1.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();
+     */
+    async createBulkPayoutTransaction(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash, txId, forceComplete = false, txOptions = {}) {
+        await this.ensureCorrectBulkPayoutInput(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash);
+        const signer = this.runner;
+        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;
+        }
+        catch (e) {
+            return (0, utils_1.throwError)(e);
+        }
+    }
+    async ensureCorrectBulkPayoutInput(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash) {
+        if (!ethers_1.ethers.isAddress(escrowAddress)) {
+            throw error_1.ErrorInvalidEscrowAddressProvided;
+        }
+        if (recipients.length === 0) {
+            throw error_1.ErrorRecipientCannotBeEmptyArray;
+        }
+        if (recipients.length > constants_1.ESCROW_BULK_PAYOUT_MAX_ITEMS) {
+            throw error_1.ErrorTooManyRecipients;
+        }
+        if (amounts.length === 0) {
+            throw error_1.ErrorAmountsCannotBeEmptyArray;
+        }
+        if (recipients.length !== amounts.length) {
+            throw error_1.ErrorRecipientAndAmountsMustBeSameLength;
+        }
+        recipients.forEach((recipient) => {
+            if (!ethers_1.ethers.isAddress(recipient)) {
+                throw new error_1.InvalidEthereumAddressError(recipient);
+            }
+        });
+        if (!finalResultsUrl) {
+            throw error_1.ErrorUrlIsEmptyString;
+        }
+        if (!(0, utils_1.isValidUrl)(finalResultsUrl)) {
+            throw error_1.ErrorInvalidUrl;
+        }
+        if (!finalResultsHash) {
+            throw error_1.ErrorHashIsEmptyString;
+        }
+        const balance = await this.getBalance(escrowAddress);
+        let totalAmount = 0n;
+        amounts.forEach((amount) => {
+            totalAmount = totalAmount + amount;
+        });
+        if (balance < totalAmount) {
+            throw error_1.ErrorEscrowDoesNotHaveEnoughBalance;
+        }
+        if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
+            throw error_1.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**
      *
@@ -722,7 +791,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -736,7 +805,13 @@ class EscrowClient extends base_1.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 (0, utils_1.throwError)(e);
@@ -746,7 +821,7 @@ class EscrowClient extends base_1.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**
      *
@@ -757,7 +832,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -781,7 +856,7 @@ class EscrowClient extends base_1.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**
      *
@@ -792,7 +867,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -816,7 +891,7 @@ class EscrowClient extends base_1.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**
      *
@@ -827,7 +902,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -851,7 +926,7 @@ class EscrowClient extends base_1.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**
      *
@@ -862,9 +937,9 @@ class EscrowClient extends base_1.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) {
@@ -886,7 +961,7 @@ class EscrowClient extends base_1.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**
      *
@@ -897,7 +972,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -921,7 +996,7 @@ class EscrowClient extends base_1.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**
      *
@@ -932,7 +1007,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -956,7 +1031,7 @@ class EscrowClient extends base_1.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**
      *
@@ -967,7 +1042,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -991,7 +1066,7 @@ class EscrowClient extends base_1.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**
      *
@@ -1002,7 +1077,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -1026,7 +1101,7 @@ class EscrowClient extends base_1.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**
      *
@@ -1037,7 +1112,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -1061,7 +1136,7 @@ class EscrowClient extends base_1.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**
      *
@@ -1072,7 +1147,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -1096,7 +1171,7 @@ class EscrowClient extends base_1.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**
      *
@@ -1107,7 +1182,7 @@ class EscrowClient extends base_1.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');
      * ```
@@ -1141,12 +1216,6 @@ __decorate([
     __metadata("design:paramtypes", [String, Object, Object]),
     __metadata("design:returntype", Promise)
 ], EscrowClient.prototype, "setup", null);
-__decorate([
-    decorators_1.requiresSigner,
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Array, String, Object]),
-    __metadata("design:returntype", Promise)
-], EscrowClient.prototype, "createAndSetupEscrow", null);
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
@@ -1168,7 +1237,7 @@ __decorate([
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Array, Array, String, String, Object]),
+    __metadata("design:paramtypes", [String, Array, Array, String, String, Number, Object, Object]),
     __metadata("design:returntype", Promise)
 ], EscrowClient.prototype, "bulkPayOut", null);
 __decorate([
@@ -1180,15 +1249,21 @@ __decorate([
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:paramtypes", [String, Array, Object]),
     __metadata("design:returntype", Promise)
-], EscrowClient.prototype, "abort", null);
+], EscrowClient.prototype, "addTrustedHandlers", null);
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Array, Object]),
+    __metadata("design:paramtypes", [String, String, Object]),
     __metadata("design:returntype", Promise)
-], EscrowClient.prototype, "addTrustedHandlers", null);
+], EscrowClient.prototype, "withdraw", null);
+__decorate([
+    decorators_1.requiresSigner,
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Array, Array, String, String, Number, Object, Object]),
+    __metadata("design:returntype", Promise)
+], EscrowClient.prototype, "createBulkPayoutTransaction", null);
 /**
  * ## Introduction
  *
@@ -1216,7 +1291,7 @@ __decorate([
  * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
  *
  * const escrowAddresses = new EscrowUtils.getEscrows({
- *   network: ChainId.POLYGON_AMOY
+ *   chainId: ChainId.POLYGON_AMOY
  * });
  * ```
  */
@@ -1261,7 +1336,6 @@ class EscrowUtils {
      *   AVALANCHE_TESTNET = 43113,
      *   CELO = 42220,
      *   CELO_ALFAJORES = 44787,
-     *    = 1273227453,
      *   LOCALHOST = 1338,
      * }
      * ```