@human-protocol/sdk 1.1.13 → 1.1.15

package/dist/escrow.js

@@ -22,12 +22,81 @@ const error_1 = require("./error");
 const types_1 = require("./types");
 const utils_1 = require("./utils");
 const graphql_1 = require("./graphql");
+/**
+ * ## Introduction
+ *
+ * This client enables to perform actions on Escrow contracts and obtain information from both the contracts and subgraph.
+ *
+ * Internally, the SDK will use one network or another according to the network ID of the `signerOrProvider`.
+ * To use this client, it is recommended to initialize it using the static `build` method.
+ *
+ * ```ts
+ * static async build(signerOrProvider: Signer | Provider);
+ * ```
+ *
+ * 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.
+ *
+ * ## Installation
+ *
+ * ### npm
+ * ```bash
+ * npm install @human-protocol/sdk
+ * ```
+ *
+ * ### yarn
+ * ```bash
+ * yarn install @human-protocol/sdk
+ * ```
+ *
+ * ## Code example
+ *
+ * ### Signer
+ *
+ * **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 provider = new providers.JsonRpcProvider(rpcUrl);
+ * const signer = new Wallet(privateKey, provider);
+ * const escrowClient = await EscrowClient.build(signer);
+ * ```
+ *
+ * **Using Wagmi(frontend)**
+ *
+ * ```ts
+ * import { useSigner, useChainId } from 'wagmi';
+ * import { EscrowClient } from '@human-protocol/sdk';
+ *
+ * const { data: signer } = useSigner();
+ * const escrowClient = await EscrowClient.build(signer);
+ * ```
+ *
+ * ### Provider
+ *
+ * ```ts
+ * import { EscrowClient } from '@human-protocol/sdk';
+ * import { providers } from 'ethers';
+ *
+ * const rpcUrl = 'YOUR_RPC_URL';
+ *
+ * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const escrowClient = await EscrowClient.build(provider);
+ * ```
+ */
 class EscrowClient {
     /**
      * **EscrowClient constructor**
      *
-     * @param {Signer | Provider} signerOrProvider - The Signer or Provider object to interact with the Ethereum network
-     * @param {NetworkData} network - The network information required to connect to the Escrow contract
+     * @param {Signer | Provider} signerOrProvider The Signer or Provider object to interact with the Ethereum network
+     * @param {NetworkData} network The network information required to connect to the Escrow contract
      */
     constructor(signerOrProvider, network) {
         this.escrowFactoryContract = typechain_types_1.EscrowFactory__factory.connect(network.factoryAddress, signerOrProvider);
@@ -37,10 +106,10 @@ class EscrowClient {
     /**
      * Creates an instance of EscrowClient from a Signer or Provider.
      *
-     * @param {Signer | Provider} signerOrProvider - The Signer or Provider object to interact with the Ethereum network
-     * @returns {Promise<EscrowClient>} - An instance of EscrowClient
-     * @throws {ErrorProviderDoesNotExist} - Thrown if the provider does not exist for the provided Signer
-     * @throws {ErrorUnsupportedChainID} - Thrown if the network's chainId is not supported
+     * @param {Signer | Provider} signerOrProvider The Signer or Provider object to interact with the Ethereum network
+     * @returns {Promise<EscrowClient>} An instance of EscrowClient
+     * @throws {ErrorProviderDoesNotExist} Thrown if the provider does not exist for the provided Signer
+     * @throws {ErrorUnsupportedChainID} Thrown if the network's chainId is not supported
      */
     static async build(signerOrProvider) {
         let network;
@@ -61,12 +130,34 @@ class EscrowClient {
         return new EscrowClient(signerOrProvider, networkData);
     }
     /**
-     * Creates an escrow contract that uses the token passed to pay oracle fees and reward workers.
+     * 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[]} trustedHandlers - Array of addresses that can perform actions on the contract.
-     * @returns {Promise<string>} - Return the address of the escrow created.
-     * @throws {Error} - An error object if an error occurred.
+     * @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
+     * @returns {Promise<string>} Return the address of the escrow created.
+     *
+     *
+     * **Code example**
+     *
+     * > Need to have available stake.
+     *
+     * ```ts
+     * import { 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 escrowAddress = await escrowClient.createEscrow(tokenAddress, trustedHandlers, jobRequesterId);
+     * ```
      */
     async createEscrow(tokenAddress, trustedHandlers, jobRequesterId) {
         if (!ethers_1.ethers.utils.isAddress(tokenAddress)) {
@@ -90,12 +181,41 @@ class EscrowClient {
         }
     }
     /**
-     * Sets up the parameters of the escrow.
+     * This function sets up the parameters of the escrow.
+     *
+     * @param {string} escrowAddress Address of the escrow to set up.
+     * @param {IEscrowConfig} escrowConfig Escrow configuration parameters.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
      *
-     * @param {string} escrowAddress - Address of the escrow to set up.
-     * @param {IEscrowConfig} escrowConfig - Configuration object with escrow settings.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * > Only Job Launcher or a trusted handler can call it.
+     *
+     * ```ts
+     * import { 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 escrowAddress = '0x62dD51230A30401C455c8398d06F85e4EaB6309f';
+     * const escrowConfig = {
+     *    recordingOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+     *    reputationOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+     *    exchangeOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+     *    recordingOracleFee: BigNumber.from('10'),
+     *    reputationOracleFee: BigNumber.from('10'),
+     *    exchangeOracleFee: BigNumber.from('10'),
+     *    manifestUrl: 'htttp://localhost/manifest.json',
+     *    manifestHash: 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079',
+     * };
+     * await escrowClient.setup(escrowAddress, escrowConfig);
+     * ```
      */
     async setup(escrowAddress, escrowConfig) {
         const { recordingOracle, reputationOracle, exchangeOracle, recordingOracleFee, reputationOracleFee, exchangeOracleFee, manifestUrl, manifestHash, } = escrowConfig;
@@ -141,14 +261,45 @@ class EscrowClient {
         }
     }
     /**
-     * **Creates an escrow contract that uses the token passed to pay oracle fees and reward workers.*
-     * **Sets up the parameters of the 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 {IEscrowConfig} escrowConfig - Configuration object with escrow settings.
-     * @returns {Promise<string>}
-     * @throws {Error} - An error object if an error occurred.
+     * 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: BigNumber.from('10'),
+     *    reputationOracleFee: BigNumber.from('10'),
+     *    exchangeOracleFee: BigNumber.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 {
@@ -161,12 +312,29 @@ class EscrowClient {
         }
     }
     /**
-     * **Adds funds of the chosen token to the escrow.*
+     * This function adds funds of the chosen token to the escrow.
+     *
+     * @param {string} escrowAddress Address of the escrow to fund.
+     * @param {BigNumber} amount Amount to be added as funds.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **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);
      *
-     * @param {string} escrowAddress - Address of the escrow to fund.
-     * @param {BigNumber} amount - Amount to be added as funds.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * const amount = ethers.utils.parseUnits(5, 'ether'); //convert from ETH to WEI
+     * await escrowClient.fund('0x62dD51230A30401C455c8398d06F85e4EaB6309f', amount);
+     * ```
      */
     async fund(escrowAddress, amount) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -190,14 +358,31 @@ class EscrowClient {
         }
     }
     /**
-     * **Stores the results.*
-     *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @param {string} sender - Address of the sender.
-     * @param {string} url - Results file url.
-     * @param {string} hash - Results file hash.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * 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.
+     * @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 storeResults.storeResults('0x62dD51230A30401C455c8398d06F85e4EaB6309f', 'http://localhost/results.json', 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079');
+     * ```
      */
     async storeResults(escrowAddress, url, hash) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -225,11 +410,29 @@ class EscrowClient {
         }
     }
     /**
-     * **Sets the status of an escrow to completed.*
+     * This function sets the status of an escrow to completed.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns Returns void if successful. Throws error if any.
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     *
+     * **Code example**
+     *
+     * > Only Recording Oracle or a trusted handler can call it.
+     *
+     * ```ts
+     * import { 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.complete('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async complete(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -248,15 +451,38 @@ class EscrowClient {
         }
     }
     /**
-     * Pays out the amounts specified to the workers and sets the URL of the final results file.
-     *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @param {string[]} recipients - Array of recipient addresses.
-     * @param {BigNumber[]} amounts - Array of amounts the recipients will receive.
-     * @param {string} finalResultsUrl - Final results file url.
-     * @param {string} finalResultsHash - Final results file hash.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * 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 {BigNumber[]} amounts Array of amounts the recipients will receive.
+     * @param {string} finalResultsUrl Final results file url.
+     * @param {string} finalResultsHash Final results file hash.
+     * @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.utils.parseUnits(5, 'ether'), ethers.utils.parseUnits(10, 'ether')];
+     * const resultsUrl = 'http://localhost/results.json';
+     * const resultsHash'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079';
+     *
+     * await escrowClient.bulkPayOut('0x62dD51230A30401C455c8398d06F85e4EaB6309f', recipients, amounts, resultsUrl, resultsHash);
+     * ```
      */
     async bulkPayOut(escrowAddress, recipients, amounts, finalResultsUrl, finalResultsHash) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -306,11 +532,29 @@ class EscrowClient {
         }
     }
     /**
-     * Cancels the specified escrow and sends the balance to the canceler.
+     * This function cancels the specified escrow and sends the balance to the canceler.
+     *
+     * @param {string} escrowAddress Address of the escrow to cancel.
+     * @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.
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<EscrowCancel>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```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.cancel('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async cancel(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -350,11 +594,29 @@ class EscrowClient {
         }
     }
     /**
-     * Cancels the specified escrow, sends the balance to the canceler and selfdestructs the escrow contract.
+     * This function cancels the specified escrow, sends the balance to the canceler and selfdestructs the escrow contract.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
+     *
+     * > Only Job Launcher or trusted handler can call it.
+     *
+     * ```ts
+     * import { 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);
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * await escrowClient.abort('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async abort(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -373,12 +635,31 @@ class EscrowClient {
         }
     }
     /**
-     * Adds an array of addresses to the trusted handlers list.
+     * This function sets the status of an escrow to completed.
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @param {string[]} trustedHandlers - List of trusted handler addresses.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * @param {string} escrowAddress Address of the escrow.
+     * @param {string[]} trustedHandlers Array of addresses of trusted handlers to add.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
+     *
+     * > Only Job Launcher or trusted handler can call it.
+     *
+     * ```ts
+     * import { 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 trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266']
+     * await escrowClient.addTrustedHandlers('0x62dD51230A30401C455c8398d06F85e4EaB6309f', trustedHandlers);
+     * ```
      */
     async addTrustedHandlers(escrowAddress, trustedHandlers) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -405,11 +686,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the balance for a specified escrow address.
+     * This function returns the balance for a specified escrow address.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {BigNumber} Balance of the escrow in the token used to fund it.
+     *
+     * **Code example**
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<BigNumber>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```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(signer);
+     *
+     * const balance = await escrowClient.getBalance('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getBalance(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -427,11 +721,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the manifest file hash.
+     * This function returns the manifest file hash.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {string} Hash of the manifest file content.
+     *
+     * **Code example**
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```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(signer);
+     *
+     * const manifestHash = await escrowClient.getManifestHash('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getManifestHash(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -449,11 +756,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the manifest file URL.
+     * This function returns the manifest file URL.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {string} Url of the manifest.
+     *
+     * **Code example**
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```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(signer);
+     *
+     * const manifestUrl = await escrowClient.getManifestUrl('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getManifestUrl(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -471,11 +791,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the results file URL.
+     * This function returns the results file URL.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {string} Results file url.
+     *
+     * **Code example**
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```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(signer);
+     *
+     * const resultsUrl = await escrowClient.getResultsUrl('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getResultsUrl(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -493,11 +826,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the intermediate results file URL.
+     * 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.
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * **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(signer);
+     *
+     * const intemediateResultsUrl = await escrowClient.getIntermediateResultsUrl('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getIntermediateResultsUrl(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -515,11 +861,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the value for a specified key and address
+     * 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.
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * **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(signer);
+     *
+     * const tokenAddress = await escrowClient.getTokenAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getTokenAddress(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -537,11 +896,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the current status of the escrow.
+     * This function returns the current status of the escrow.
+     *
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {EscrowStatus} Current status of the escrow.
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred.
+     * **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(signer);
+     *
+     * const status = await escrowClient.getStatus('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getStatus(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -559,11 +931,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the recording oracle address of given escrow
+     * 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.
+     *
+     * **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(signer);
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<string>} - Address of the recording oracle.
-     * @throws {Error} - An error object if an error occurred.
+     * const oracleAddress = await escrowClient.getRecordingOracleAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getRecordingOracleAddress(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -581,11 +966,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the job launcher address of given escrow
+     * This function returns the job launcher address for a given escrow.
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<string>} - Address of the job launcher.
-     * @throws {Error} - An error object if an error occurred.
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {string} Address of the Job Launcher.
+     *
+     * **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(signer);
+     *
+     * const jobLauncherAddress = await escrowClient.getJobLauncherAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getJobLauncherAddress(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -603,11 +1001,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the reputation oracle address of given escrow
+     * 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.
+     *
+     * **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(signer);
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<string>} - Address of the reputation oracle.
-     * @throws {Error} - An error object if an error occurred.
+     * const oracleAddress = await escrowClient.getReputationOracleAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getReputationOracleAddress(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -625,11 +1036,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the reputation oracle address of given escrow
+     * This function returns the exchange oracle address for a given escrow.
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<string>} - Address of the reputation oracle.
-     * @throws {Error} - An error object if an error occurred.
+     * @param {string} escrowAddress Address of the escrow.
+     * @returns {EscrowStatus} Address of the Exchange Oracle.
+     *
+     * **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(signer);
+     *
+     * const oracleAddress = await escrowClient.getExchangeOracleAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getExchangeOracleAddress(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -647,11 +1071,24 @@ class EscrowClient {
         }
     }
     /**
-     * Returns the escrow factory address of given escrow
+     * 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.
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { providers } from 'ethers';
+     * import { EscrowClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
      *
-     * @param {string} escrowAddress - Address of the escrow.
-     * @returns {Promise<string>} - Address of the escrow factory.
-     * @throws {Error} - An error object if an error occurred.
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const escrowClient = await EscrowClient.build(signer);
+     *
+     * const factoryAddress = await escrowClient.getFactoryAddress('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getFactoryAddress(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -730,13 +1167,132 @@ __decorate([
     __metadata("design:returntype", Promise)
 ], EscrowClient.prototype, "addTrustedHandlers", null);
 exports.EscrowClient = EscrowClient;
+/**
+ * ## Introduction
+ *
+ * Utility class for escrow-related operations.
+ *
+ * ## Installation
+ *
+ * ### npm
+ * ```bash
+ * npm install @human-protocol/sdk
+ * ```
+ *
+ * ### yarn
+ * ```bash
+ * yarn install @human-protocol/sdk
+ * ```
+ *
+ * ## Code example
+ *
+ * ### Signer
+ *
+ * **Using private key(backend)**
+ *
+ * ```ts
+ * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
+ *
+ * const escrowAddresses = new EscrowUtils.getEscrows({
+ *   networks: [ChainId.POLYGON_MUMBAI]
+ * });
+ * ```
+ */
 class EscrowUtils {
     /**
-     * Returns the list of escrows for given filter
+     * This function returns an array of escrows based on the specified filter parameters.
+     *
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * interface IEscrowsFilter {
+     *   networks: ChainId[];
+     *   launcher?: string;
+     *   reputationOracle?: string;
+     *   recordingOracle?: string;
+     *   exchangeOracle?: string;
+     *   jobRequesterId?: string;
+     *   status?: EscrowStatus;
+     *   from?: Date;
+     *   to?: Date;
+     * }
+     * ```
+     *
+     * ```ts
+     * enum ChainId {
+     *   ALL = -1,
+     *   MAINNET = 1,
+     *   RINKEBY = 4,
+     *   GOERLI = 5,
+     *   BSC_MAINNET = 56,
+     *   BSC_TESTNET = 97,
+     *   POLYGON = 137,
+     *   POLYGON_MUMBAI = 80001,
+     *   MOONBEAM = 1284,
+     *   MOONBASE_ALPHA = 1287,
+     *   AVALANCHE = 43114,
+     *   AVALANCHE_TESTNET = 43113,
+     *   SKALE = 1273227453,
+     *   LOCALHOST = 1338,
+     * }
+     * ```
+     *
+     * ```ts
+     * enum EscrowStatus {
+     *   Launched,
+     *   Pending,
+     *   Partial,
+     *   Paid,
+     *   Complete,
+     *   Cancelled,
+     * }
+     * ```
+     *
+     * ```ts
+     * type EscrowData = {
+     *   id: string;
+     *   address: string;
+     *   amountPaid: string;
+     *   balance: string;
+     *   count: string;
+     *   jobRequesterId: string;
+     *   factoryAddress: string;
+     *   finalResultsUrl?: string;
+     *   intermediateResultsUrl?: string;
+     *   launcher: string;
+     *   manifestHash?: string;
+     *   manifestUrl?: string;
+     *   recordingOracle?: string;
+     *   recordingOracleFee?: string;
+     *   reputationOracle?: string;
+     *   reputationOracleFee?: string;
+     *   exchangeOracle?: string;
+     *   exchangeOracleFee?: string;
+     *   status: EscrowStatus;
+     *   token: string;
+     *   totalFundedAmount: string;
+     *   createdAt: string;
+     * };
+     * ```
+     *
+     *
+     * @param {IEscrowsFilter} filter Filter parameters.
+     * @returns {EscrowData[]} List of escrows that match the filter.
+     *
+     * **Code example**
      *
-     * @param {IEscrowsFilter} filter - Filter parameters.
-     * @returns {Promise<EscrowData[]>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```ts
+     * import { ChainId, EscrowUtils, EscrowStatus } from '@human-protocol/sdk';
+     *
+     * const filters: IEscrowsFilter = {
+     *   status: EscrowStatus.Pending,
+     *   from: new Date(2023, 4, 8),
+     *   to: new Date(2023, 5, 8),
+     *   networks: [ChainId.POLYGON_MUMBAI]
+     * };
+     * const escrowDatas = await EscrowUtils.getEscrows(filters);
+     * ```
      */
     static async getEscrows(filter) {
         if (!filter?.networks?.length) {
@@ -783,12 +1339,70 @@ class EscrowUtils {
         }
     }
     /**
-     * Returns the escrow for a given address
+     * This function returns the escrow data for a given address.
+     *
+     * > This uses Subgraph
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * enum ChainId {
+     *   ALL = -1,
+     *   MAINNET = 1,
+     *   RINKEBY = 4,
+     *   GOERLI = 5,
+     *   BSC_MAINNET = 56,
+     *   BSC_TESTNET = 97,
+     *   POLYGON = 137,
+     *   POLYGON_MUMBAI = 80001,
+     *   MOONBEAM = 1284,
+     *   MOONBASE_ALPHA = 1287,
+     *   AVALANCHE = 43114,
+     *   AVALANCHE_TESTNET = 43113,
+     *   SKALE = 1273227453,
+     *   LOCALHOST = 1338,
+     * }
+     * ```
+     *
+     * ```ts
+     * type EscrowData = {
+     *   id: string;
+     *   address: string;
+     *   amountPaid: string;
+     *   balance: string;
+     *   count: string;
+     *   jobRequesterId: string;
+     *   factoryAddress: string;
+     *   finalResultsUrl?: string;
+     *   intermediateResultsUrl?: string;
+     *   launcher: string;
+     *   manifestHash?: string;
+     *   manifestUrl?: string;
+     *   recordingOracle?: string;
+     *   recordingOracleFee?: string;
+     *   reputationOracle?: string;
+     *   reputationOracleFee?: string;
+     *   exchangeOracle?: string;
+     *   exchangeOracleFee?: string;
+     *   status: EscrowStatus;
+     *   token: string;
+     *   totalFundedAmount: string;
+     *   createdAt: string;
+     * };
+     * ```
+     *
+     *
+     * @param {ChainId} chainId Network in which the escrow has been deployed
+     * @param {string} escrowAddress Address of the escrow
+     * @returns {EscrowData} Escrow data
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { ChainId, EscrowUtils } from '@human-protocol/sdk';
      *
-     * @param {string} escrowAddress - Escrow address.
-     * @param {ChainId} chainId - Chain id.
-     * @returns {Promise<EscrowData>}
-     * @throws {Error} - An error object if an error occurred.
+     * const escrowData = new EscrowUtils.getEscrow(ChainId.POLYGON_MUMBAI, "0x1234567890123456789012345678901234567890");
+     * ```
      */
     static async getEscrow(chainId, escrowAddress) {
         const networkData = constants_1.NETWORKS[chainId];