@human-protocol/sdk 4.2.0 → 5.0.0-beta.0

package/dist/escrow.js

@@ -143,7 +143,6 @@ 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 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>} Returns the address of the escrow created.
@@ -165,22 +164,16 @@ class EscrowClient extends base_1.BaseEthersClient {
      * const escrowClient = await EscrowClient.build(signer);
      *
      * const tokenAddress = '0x0376D26246Eb35FF4F9924cF13E6C05fd0bD7Fb4';
-     * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'];
      * const jobRequesterId = "job-requester-id";
-     * const escrowAddress = await escrowClient.createEscrow(tokenAddress, trustedHandlers, jobRequesterId);
+     * const escrowAddress = await escrowClient.createEscrow(tokenAddress, jobRequesterId);
      * ```
      */
-    async createEscrow(tokenAddress, trustedHandlers, jobRequesterId, txOptions = {}) {
+    async createEscrow(tokenAddress, jobRequesterId, txOptions = {}) {
         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);
-            }
-        });
         try {
-            const result = await (await this.escrowFactoryContract.createEscrow(tokenAddress, trustedHandlers, jobRequesterId, txOptions)).wait();
+            const result = await (await this.escrowFactoryContract.createEscrow(tokenAddress, jobRequesterId, txOptions)).wait();
             const event = result?.logs?.find(({ topics }) => topics.includes(ethers_1.ethers.id('LaunchedV2(address,address,string)')))?.args;
             if (!event) {
                 throw error_1.ErrorLaunchedEventIsNotEmitted;
@@ -202,7 +195,7 @@ class EscrowClient extends base_1.BaseEthersClient {
      *
      * **Code example**
      *
-     * > Only Job Launcher or a trusted handler can call it.
+     * > Only Job Launcher or admin can call it.
      *
      * ```ts
      * import { Wallet, providers } from 'ethers';
@@ -317,56 +310,40 @@ class EscrowClient extends base_1.BaseEthersClient {
             return (0, utils_1.throwError)(e);
         }
     }
-    /**
-     * This function stores the results URL and hash.
-     *
-     * @param {string} escrowAddress Address of the escrow.
-     * @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.
-     *
-     *
-     * **Code example**
-     *
-     * > Only Recording 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);
-     *
-     * await escrowClient.storeResults('0x62dD51230A30401C455c8398d06F85e4EaB6309f', 'http://localhost/results.json', 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079');
-     * ```
-     */
-    async storeResults(escrowAddress, url, hash, txOptions = {}) {
+    async storeResults(escrowAddress, url, hash, a, b) {
+        const escrowContract = this.getEscrowContract(escrowAddress);
+        const hasFundsToReserveParam = typeof a === 'bigint';
+        const fundsToReserve = hasFundsToReserveParam ? a : undefined;
+        const txOptions = (hasFundsToReserveParam ? b : a) || {};
+        // When fundsToReserve is provided and is 0, allow empty URL.
+        // In this situation not solutions might have been provided so the escrow can be straight cancelled.
+        const allowEmptyUrl = hasFundsToReserveParam && fundsToReserve === 0n;
         if (!ethers_1.ethers.isAddress(escrowAddress)) {
             throw error_1.ErrorInvalidEscrowAddressProvided;
         }
-        if (!url) {
-            throw error_1.ErrorInvalidUrl;
-        }
-        if (!(0, utils_1.isValidUrl)(url)) {
+        if (!allowEmptyUrl && !(0, utils_1.isValidUrl)(url)) {
             throw error_1.ErrorInvalidUrl;
         }
-        if (!hash) {
+        if (!hash && !allowEmptyUrl) {
             throw error_1.ErrorHashIsEmptyString;
         }
         if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
             throw error_1.ErrorEscrowAddressIsNotProvidedByFactory;
         }
         try {
-            const escrowContract = this.getEscrowContract(escrowAddress);
-            await (await escrowContract.storeResults(url, hash, txOptions)).wait();
-            return;
+            if (fundsToReserve !== undefined) {
+                await (await escrowContract['storeResults(string,string,uint256)'](url, hash, fundsToReserve, txOptions)).wait();
+            }
+            else {
+                await (await escrowContract['storeResults(string,string)'](url, hash, txOptions)).wait();
+            }
         }
         catch (e) {
+            if (!hasFundsToReserveParam && e.reason === 'DEPRECATED_SIGNATURE') {
+                throw error_1.ErrorStoreResultsVersion;
+            }
+            // eslint-disable-next-line no-console
+            console.warn(error_1.WarnVersionMismatch);
             return (0, utils_1.throwError)(e);
         }
     }
@@ -380,7 +357,7 @@ class EscrowClient extends base_1.BaseEthersClient {
      *
      * **Code example**
      *
-     * > Only Recording Oracle or a trusted handler can call it.
+     * > Only Recording Oracle or admin can call it.
      *
      * ```ts
      * import { Wallet, providers } from 'ethers';
@@ -412,57 +389,24 @@ class EscrowClient extends base_1.BaseEthersClient {
             return (0, utils_1.throwError)(e);
         }
     }
-    /**
-     * This function pays out the amounts specified to the workers and sets the URL of the final results file.
-     *
-     * @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 void if successful. Throws error if any.
-     *
-     *
-     * **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;
-     *
-     * await escrowClient.bulkPayOut('0x62dD51230A30401C455c8398d06F85e4EaB6309f', recipients, amounts, resultsUrl, resultsHash, txId);
-     * ```
-     */
-    async bulkPayOut(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash, txId, forceComplete = false, txOptions = {}) {
+    async bulkPayOut(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash, id, forceComplete, txOptions = {}) {
         await this.ensureCorrectBulkPayoutInput(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash);
+        const escrowContract = this.getEscrowContract(escrowAddress);
+        const idIsString = typeof id === 'string';
         try {
-            const escrowContract = this.getEscrowContract(escrowAddress);
-            if (forceComplete) {
-                await (await escrowContract['bulkPayOut(address[],uint256[],string,string,uint256,bool)'](recipients, amounts, finalResultsUrl, finalResultsHash, txId, forceComplete, txOptions)).wait();
+            if (idIsString) {
+                await (await escrowContract['bulkPayOut(address[],uint256[],string,string,string,bool)'](recipients, amounts, finalResultsUrl, finalResultsHash, id, forceComplete, txOptions)).wait();
             }
             else {
-                await (await escrowContract['bulkPayOut(address[],uint256[],string,string,uint256)'](recipients, amounts, finalResultsUrl, finalResultsHash, txId, txOptions)).wait();
+                await (await escrowContract['bulkPayOut(address[],uint256[],string,string,uint256,bool)'](recipients, amounts, finalResultsUrl, finalResultsHash, id, forceComplete, txOptions)).wait();
             }
-            return;
         }
         catch (e) {
+            if (!idIsString && e.reason === 'DEPRECATED_SIGNATURE') {
+                throw error_1.ErrorBulkPayOutVersion;
+            }
+            // eslint-disable-next-line no-console
+            console.warn(error_1.WarnVersionMismatch);
             return (0, utils_1.throwError)(e);
         }
     }
@@ -471,12 +415,11 @@ class EscrowClient extends base_1.BaseEthersClient {
      *
      * @param {string} escrowAddress Address of the escrow to cancel.
      * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-     * @returns {EscrowCancel} Returns the escrow cancellation data including transaction hash and refunded amount. Throws error if any.
      *
      *
      * **Code example**
      *
-     * > Only Job Launcher or a trusted handler can call it.
+     * > Only Job Launcher or admin can call it.
      *
      * ```ts
      * import { ethers, Wallet, providers } from 'ethers';
@@ -501,49 +444,22 @@ class EscrowClient extends base_1.BaseEthersClient {
         }
         try {
             const escrowContract = this.getEscrowContract(escrowAddress);
-            const transactionReceipt = await (await escrowContract.cancel(txOptions)).wait();
-            let amountTransferred = undefined;
-            const tokenAddress = await escrowContract.token();
-            const tokenContract = typechain_types_1.HMToken__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 escrowCancelData = {
-                txHash: transactionReceipt?.hash || '',
-                amountRefunded: amountTransferred,
-            };
-            return escrowCancelData;
+            await (await escrowContract.cancel(txOptions)).wait();
         }
         catch (e) {
             return (0, utils_1.throwError)(e);
         }
     }
     /**
-     * This function adds an array of addresses to the trusted handlers list.
+     * This function requests the cancellation of the specified escrow (moves status to ToCancel or finalizes if expired).
      *
-     * @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 request cancellation.
      * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
      * @returns Returns void if successful. Throws error if any.
      *
-     *
      * **Code example**
      *
-     * > Only Job Launcher or trusted handler can call it.
+     * > Only Job Launcher or admin can call it.
      *
      * ```ts
      * import { Wallet, providers } from 'ethers';
@@ -556,29 +472,19 @@ class EscrowClient extends base_1.BaseEthersClient {
      * const signer = new Wallet(privateKey, provider);
      * const escrowClient = await EscrowClient.build(signer);
      *
-     * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'];
-     * await escrowClient.addTrustedHandlers('0x62dD51230A30401C455c8398d06F85e4EaB6309f', trustedHandlers);
+     * await escrowClient.requestCancellation('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
      * ```
      */
-    async addTrustedHandlers(escrowAddress, trustedHandlers, txOptions = {}) {
+    async requestCancellation(escrowAddress, 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.addTrustedHandlers(trustedHandlers, txOptions)).wait();
-            return;
+            await (await escrowContract.requestCancellation(txOptions)).wait();
         }
         catch (e) {
             return (0, utils_1.throwError)(e);
@@ -595,7 +501,7 @@ class EscrowClient extends base_1.BaseEthersClient {
      *
      * **Code example**
      *
-     * > Only Job Launcher or a trusted handler can call it.
+     * > Only Job Launcher or admin can call it.
      *
      * ```ts
      * import { ethers, Wallet, providers } from 'ethers';
@@ -649,7 +555,7 @@ class EscrowClient extends base_1.BaseEthersClient {
             const escrowWithdrawData = {
                 txHash: transactionReceipt?.hash || '',
                 tokenAddress,
-                amountWithdrawn: amountTransferred,
+                withdrawnAmount: amountTransferred,
             };
             return escrowWithdrawData;
         }
@@ -664,14 +570,14 @@ class EscrowClient extends base_1.BaseEthersClient {
      * @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 {string} payoutId Payout ID to identify the payout.
      * @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.
+     * > Only Reputation Oracle or admin can call it.
      *
      * ```ts
      * import { ethers, Wallet, providers } from 'ethers';
@@ -688,7 +594,7 @@ class EscrowClient extends base_1.BaseEthersClient {
      * const amounts = [ethers.parseUnits(5, 'ether'), ethers.parseUnits(10, 'ether')];
      * const resultsUrl = 'http://localhost/results.json';
      * const resultsHash = 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079';
-     * const txId = 1;
+     * const payoutId = '372f6916-fe34-4711-b6e3-274f682047de';
      *
      * const rawTransaction = await escrowClient.createBulkPayoutTransaction('0x62dD51230A30401C455c8398d06F85e4EaB6309f', recipients, amounts, resultsUrl, resultsHash, txId);
      * console.log('Raw transaction:', rawTransaction);
@@ -697,12 +603,12 @@ class EscrowClient extends base_1.BaseEthersClient {
      * console.log('Tx hash:', ethers.keccak256(signedTransaction));
      * (await signer.sendTransaction(rawTransaction)).wait();
      */
-    async createBulkPayoutTransaction(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash, txId, forceComplete = false, txOptions = {}) {
+    async createBulkPayoutTransaction(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash, payoutId, 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);
+            const populatedTransaction = await escrowContract['bulkPayOut(address[],uint256[],string,string,string,bool)'].populateTransaction(recipients, amounts, finalResultsUrl, finalResultsHash, payoutId, forceComplete, txOptions);
             /**
              * Safety-belt: explicitly set the passed nonce
              * because 'populateTransaction' return value
@@ -815,6 +721,41 @@ class EscrowClient extends base_1.BaseEthersClient {
             return (0, utils_1.throwError)(e);
         }
     }
+    /**
+     * This function returns the reserved funds for a specified escrow address.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {Promise<bigint>} Reserved funds of the escrow in the token used to fund it.
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { providers } from 'ethers';
+     * import { EscrowClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const escrowClient = await EscrowClient.build(provider);
+     *
+     * const reservedFunds = await escrowClient.getReservedFunds('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
+     */
+    async getReservedFunds(escrowAddress) {
+        if (!ethers_1.ethers.isAddress(escrowAddress)) {
+            throw error_1.ErrorInvalidEscrowAddressProvided;
+        }
+        if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
+            throw error_1.ErrorEscrowAddressIsNotProvidedByFactory;
+        }
+        try {
+            const escrowContract = this.getEscrowContract(escrowAddress);
+            return await escrowContract.reservedFunds();
+        }
+        catch (e) {
+            return (0, utils_1.throwError)(e);
+        }
+    }
     /**
      * This function returns the manifest file hash.
      *
@@ -955,6 +896,41 @@ class EscrowClient extends base_1.BaseEthersClient {
             return (0, utils_1.throwError)(e);
         }
     }
+    /**
+     * This function returns the intermediate results hash.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {Promise<string>} Hash of the intermediate results file content.
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { providers } from 'ethers';
+     * import { EscrowClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const escrowClient = await EscrowClient.build(provider);
+     *
+     * const intermediateResultsHash = await escrowClient.getIntermediateResultsHash('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
+     */
+    async getIntermediateResultsHash(escrowAddress) {
+        if (!ethers_1.ethers.isAddress(escrowAddress)) {
+            throw error_1.ErrorInvalidEscrowAddressProvided;
+        }
+        if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
+            throw error_1.ErrorEscrowAddressIsNotProvidedByFactory;
+        }
+        try {
+            const escrowContract = this.getEscrowContract(escrowAddress);
+            return escrowContract.intermediateResultsHash();
+        }
+        catch (e) {
+            return (0, utils_1.throwError)(e);
+        }
+    }
     /**
      * This function returns the token address used for funding the escrow.
      *
@@ -1205,7 +1181,7 @@ exports.EscrowClient = EscrowClient;
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Array, String, Object]),
+    __metadata("design:paramtypes", [String, String, Object]),
     __metadata("design:returntype", Promise)
 ], EscrowClient.prototype, "createEscrow", null);
 __decorate([
@@ -1223,7 +1199,7 @@ __decorate([
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, String, String, Object]),
+    __metadata("design:paramtypes", [String, String, String, Object, Object]),
     __metadata("design:returntype", Promise)
 ], EscrowClient.prototype, "storeResults", null);
 __decorate([
@@ -1235,7 +1211,7 @@ __decorate([
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Array, Array, String, String, Number, Object, Object]),
+    __metadata("design:paramtypes", [String, Array, Array, String, String, Object, Boolean, Object]),
     __metadata("design:returntype", Promise)
 ], EscrowClient.prototype, "bulkPayOut", null);
 __decorate([
@@ -1247,9 +1223,9 @@ __decorate([
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Array, Object]),
+    __metadata("design:paramtypes", [String, Object]),
     __metadata("design:returntype", Promise)
-], EscrowClient.prototype, "addTrustedHandlers", null);
+], EscrowClient.prototype, "requestCancellation", null);
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
@@ -1259,7 +1235,7 @@ __decorate([
 __decorate([
     decorators_1.requiresSigner,
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Array, Array, String, String, Number, Object, Object]),
+    __metadata("design:paramtypes", [String, Array, Array, String, String, String, Object, Object]),
     __metadata("design:returntype", Promise)
 ], EscrowClient.prototype, "createBulkPayoutTransaction", null);
 /**
@@ -1647,5 +1623,132 @@ class EscrowUtils {
         });
         return payouts || [];
     }
+    /**
+     * This function returns the cancellation refunds for a given set of networks.
+     *
+     * > This uses Subgraph
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * enum ChainId {
+     *  ALL = -1,
+     *  MAINNET = 1,
+     *  SEPOLIA = 11155111,
+     *  BSC_MAINNET = 56,
+     *  BSC_TESTNET = 97,
+     *  POLYGON = 137,
+     *  POLYGON_AMOY = 80002,
+     *  LOCALHOST = 1338,
+     * }
+     * ```
+     *
+     * ```ts
+     * type CancellationRefund = {
+     *   id: string;
+     *   escrowAddress: string;
+     *   receiver: string;
+     *   amount: bigint;
+     *   block: number;
+     *   timestamp: number;
+     *   txHash: string;
+     * };
+     * ```
+     *
+     *
+     * @param {Object} filter Filter parameters.
+     * @returns {Promise<CancellationRefund[]>} List of cancellation refunds matching the filters.
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
+     *
+     * const cancellationRefunds = await EscrowUtils.getCancellationRefunds({
+     *    chainId: ChainId.POLYGON_AMOY,
+     *    escrowAddress: '0x1234567890123456789012345678901234567890',
+     * });
+     * console.log(cancellationRefunds);
+     * ```
+     */
+    static async getCancellationRefunds(filter) {
+        const networkData = constants_1.NETWORKS[filter.chainId];
+        if (!networkData)
+            throw error_1.ErrorUnsupportedChainID;
+        if (filter.escrowAddress && !ethers_1.ethers.isAddress(filter.escrowAddress)) {
+            throw error_1.ErrorInvalidEscrowAddressProvided;
+        }
+        if (filter.receiver && !ethers_1.ethers.isAddress(filter.receiver)) {
+            throw error_1.ErrorInvalidAddress;
+        }
+        const first = filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
+        const skip = filter.skip || 0;
+        const orderDirection = filter.orderDirection || enums_1.OrderDirection.DESC;
+        const { cancellationRefundEvents } = await (0, graphql_request_1.default)((0, utils_1.getSubgraphUrl)(networkData), (0, graphql_1.GET_CANCELLATION_REFUNDS_QUERY)(filter), {
+            escrowAddress: filter.escrowAddress?.toLowerCase(),
+            receiver: filter.receiver?.toLowerCase(),
+            from: filter.from ? (0, utils_1.getUnixTimestamp)(filter.from) : undefined,
+            to: filter.to ? (0, utils_1.getUnixTimestamp)(filter.to) : undefined,
+            first,
+            skip,
+            orderDirection,
+        });
+        return cancellationRefundEvents || [];
+    }
+    /**
+     * This function returns the cancellation refund for a given escrow address.
+     *
+     * > This uses Subgraph
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * enum ChainId {
+     *  ALL = -1,
+     *  MAINNET = 1,
+     *  SEPOLIA = 11155111,
+     *  BSC_MAINNET = 56,
+     *  BSC_TESTNET = 97,
+     *  POLYGON = 137,
+     *  POLYGON_AMOY = 80002,
+     *  LOCALHOST = 1338,
+     * }
+     * ```
+     *
+     * ```ts
+     * type CancellationRefund = {
+     *   id: string;
+     *   escrowAddress: string;
+     *   receiver: string;
+     *   amount: bigint;
+     *   block: number;
+     *   timestamp: number;
+     *   txHash: string;
+     * };
+     * ```
+     *
+     *
+     * @param {ChainId} chainId Network in which the escrow has been deployed
+     * @param {string} escrowAddress Address of the escrow
+     * @returns {Promise<CancellationRefund>} Cancellation refund data
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
+     *
+     * const cancellationRefund = await EscrowUtils.getCancellationRefund(ChainId.POLYGON_AMOY, "0x1234567890123456789012345678901234567890");
+     * ```
+     */
+    static async getCancellationRefund(chainId, escrowAddress) {
+        const networkData = constants_1.NETWORKS[chainId];
+        if (!networkData)
+            throw error_1.ErrorUnsupportedChainID;
+        if (!ethers_1.ethers.isAddress(escrowAddress)) {
+            throw error_1.ErrorInvalidEscrowAddressProvided;
+        }
+        const { cancellationRefundEvents } = await (0, graphql_request_1.default)((0, utils_1.getSubgraphUrl)(networkData), (0, graphql_1.GET_CANCELLATION_REFUND_BY_ADDRESS_QUERY)(), { escrowAddress: escrowAddress.toLowerCase() });
+        return cancellationRefundEvents?.[0] || null;
+    }
 }
 exports.EscrowUtils = EscrowUtils;

package/dist/graphql/queries/escrow.d.ts

@@ -1,5 +1,7 @@
-import { IEscrowsFilter } from '../../interfaces';
+import { ICancellationRefundFilter, IEscrowsFilter } from '../../interfaces';
 export declare const GET_ESCROW_BY_ADDRESS_QUERY: () => import("graphql").DocumentNode;
 export declare const GET_ESCROWS_QUERY: (filter: IEscrowsFilter) => import("graphql").DocumentNode;
 export declare const GET_STATUS_UPDATES_QUERY: (from?: Date, to?: Date, launcher?: string) => import("graphql").DocumentNode;
+export declare const GET_CANCELLATION_REFUNDS_QUERY: (filter: ICancellationRefundFilter) => import("graphql").DocumentNode;
+export declare const GET_CANCELLATION_REFUND_BY_ADDRESS_QUERY: () => import("graphql").DocumentNode;
 //# sourceMappingURL=escrow.d.ts.map

package/dist/graphql/queries/escrow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"escrow.d.ts","sourceRoot":"","sources":["../../../src/graphql/queries/escrow.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA0BlD,eAAO,MAAM,2BAA2B,sCAOvC,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,cAAc,mCAmDvD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,OAAO,IAAI,EACX,KAAK,IAAI,EACT,WAAW,MAAM,mCAiClB,CAAC"}
+{"version":3,"file":"escrow.d.ts","sourceRoot":"","sources":["../../../src/graphql/queries/escrow.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAsC7E,eAAO,MAAM,2BAA2B,sCAOvC,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,cAAc,mCAmDvD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,OAAO,IAAI,EACX,KAAK,IAAI,EACT,WAAW,MAAM,mCAiClB,CAAC;AAEF,eAAO,MAAM,8BAA8B,GACzC,QAAQ,yBAAyB,mCA2BlC,CAAC;AAEF,eAAO,MAAM,wCAAwC,sCAOpD,CAAC"}