@human-protocol/sdk 1.1.13 → 1.1.15

package/src/escrow.ts

@@ -47,6 +47,75 @@ import {
   GET_ESCROW_BY_ADDRESS_QUERY,
 } from './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);
+ * ```
+ */
 export class EscrowClient {
   private escrowFactoryContract: EscrowFactory;
   private escrowContract?: Escrow;
@@ -56,8 +125,8 @@ export 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: Signer | Provider, network: NetworkData) {
     this.escrowFactoryContract = EscrowFactory__factory.connect(
@@ -71,10 +140,10 @@ export 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
    */
   public static async build(signerOrProvider: Signer | Provider) {
     let network: Network;
@@ -99,12 +168,34 @@ export class EscrowClient {
   }
 
   /**
-   * 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);
+   * ```
    */
   @requiresSigner
   public async createEscrow(
@@ -146,12 +237,41 @@ export 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);
+   * ```
    */
   @requiresSigner
   async setup(
@@ -238,14 +358,45 @@ export 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);
+   * ```
    */
   @requiresSigner
   async createAndSetupEscrow(
@@ -270,12 +421,29 @@ export 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);
+   * ```
    */
   @requiresSigner
   async fund(escrowAddress: string, amount: BigNumber): Promise<void> {
@@ -313,14 +481,31 @@ export 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');
+   * ```
    */
   @requiresSigner
   async storeResults(
@@ -362,11 +547,29 @@ export 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');
+   * ```
    */
   @requiresSigner
   async complete(escrowAddress: string): Promise<void> {
@@ -391,15 +594,38 @@ export 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);
+   * ```
    */
   @requiresSigner
   async bulkPayOut(
@@ -478,11 +704,29 @@ export 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');
+   * ```
    */
   @requiresSigner
   async cancel(escrowAddress: string): Promise<EscrowCancel> {
@@ -538,11 +782,29 @@ export 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');
+   * ```
    */
   @requiresSigner
   async abort(escrowAddress: string): Promise<void> {
@@ -567,12 +829,31 @@ export 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);
+   * ```
    */
   @requiresSigner
   async addTrustedHandlers(
@@ -610,11 +891,24 @@ export 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: string): Promise<BigNumber> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -637,11 +931,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -664,11 +971,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -691,11 +1011,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -718,11 +1051,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -745,11 +1091,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -772,11 +1131,24 @@ export 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: string): Promise<EscrowStatus> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -799,11 +1171,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -826,11 +1211,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -853,11 +1251,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -880,11 +1291,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -907,11 +1331,24 @@ export 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: string): Promise<string> {
     if (!ethers.utils.isAddress(escrowAddress)) {
@@ -934,13 +1371,132 @@ export class 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]
+ * });
+ * ```
+ */
 export 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);
+   * ```
    */
   public static async getEscrows(
     filter: IEscrowsFilter
@@ -1007,12 +1563,70 @@ export 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");
+   * ```
    */
   public static async getEscrow(
     chainId: ChainId,