@human-protocol/sdk 5.2.0 → 6.1.0

package/src/operator.ts

@@ -26,21 +26,40 @@ import { getSubgraphUrl, customGqlFetch } from './utils';
 import { ChainId, OrderDirection } from './enums';
 import { NETWORKS } from './constants';
 
+/**
+ * Utility helpers for operator-related queries.
+ *
+ * @example
+ * ```ts
+ * import { OperatorUtils, ChainId } from '@human-protocol/sdk';
+ *
+ * const operator = await OperatorUtils.getOperator(
+ *   ChainId.POLYGON_AMOY,
+ *   '0x62dD51230A30401C455c8398d06F85e4EaB6309f'
+ * );
+ * console.log('Operator:', operator);
+ * ```
+ */
 export class OperatorUtils {
   /**
    * This function returns the operator data for the given address.
    *
-   * @param {ChainId} chainId Network in which the operator is deployed
-   * @param {string} address Operator address.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IOperator | null>} - Returns the operator details or null if not found.
-   *
-   * **Code example**
+   * @param chainId - Network in which the operator is deployed
+   * @param address - Operator address.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Returns the operator details or null if not found.
+   * @throws ErrorInvalidStakerAddressProvided If the address is invalid
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
    *
+   * @example
    * ```ts
    * import { OperatorUtils, ChainId } from '@human-protocol/sdk';
    *
-   * const operator = await OperatorUtils.getOperator(ChainId.POLYGON_AMOY, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * const operator = await OperatorUtils.getOperator(
+   *   ChainId.POLYGON_AMOY,
+   *   '0x62dD51230A30401C455c8398d06F85e4EaB6309f'
+   * );
+   * console.log('Operator:', operator);
    * ```
    */
   public static async getOperator(
@@ -74,19 +93,20 @@ export class OperatorUtils {
   /**
    * This function returns all the operator details of the protocol.
    *
-   * @param {IOperatorsFilter} filter Filter for the operators.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IOperator[]>} Returns an array with all the operator details.
-   *
-   * **Code example**
+   * @param filter - Filter for the operators.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Returns an array with all the operator details.
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
    *
+   * @example
    * ```ts
-   * import { OperatorUtils, ChainId } from '@human-protocol/sdk';
+   * import { ChainId } from '@human-protocol/sdk';
    *
-   * const filter: IOperatorsFilter = {
-   *  chainId: ChainId.POLYGON
+   * const filter = {
+   *   chainId: ChainId.POLYGON_AMOY
    * };
    * const operators = await OperatorUtils.getOperators(filter);
+   * console.log('Operators:', operators.length);
    * ```
    */
   public static async getOperators(
@@ -142,18 +162,22 @@ export class OperatorUtils {
   /**
    * Retrieves the reputation network operators of the specified address.
    *
-   * @param {ChainId} chainId Network in which the reputation network is deployed
-   * @param {string} address Address of the reputation oracle.
-   * @param {string} [role] - (Optional) Role of the operator.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IOperator[]>} - Returns an array of operator details.
-   *
-   * **Code example**
+   * @param chainId - Network in which the reputation network is deployed
+   * @param address - Address of the reputation oracle.
+   * @param role - Role of the operator (optional).
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Returns an array of operator details.
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
    *
+   * @example
    * ```ts
    * import { OperatorUtils, ChainId } from '@human-protocol/sdk';
    *
-   * const operators = await OperatorUtils.getReputationNetworkOperators(ChainId.POLYGON_AMOY, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * const operators = await OperatorUtils.getReputationNetworkOperators(
+   *   ChainId.POLYGON_AMOY,
+   *   '0x62dD51230A30401C455c8398d06F85e4EaB6309f'
+   * );
+   * console.log('Operators:', operators.length);
    * ```
    */
   public static async getReputationNetworkOperators(
@@ -189,17 +213,22 @@ export class OperatorUtils {
   /**
    * This function returns information about the rewards for a given slasher address.
    *
-   * @param {ChainId} chainId Network in which the rewards are deployed
-   * @param {string} slasherAddress Slasher address.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IReward[]>} Returns an array of Reward objects that contain the rewards earned by the user through slashing other users.
-   *
-   * **Code example**
+   * @param chainId - Network in which the rewards are deployed
+   * @param slasherAddress - Slasher address.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Returns an array of Reward objects that contain the rewards earned by the user through slashing other users.
+   * @throws ErrorInvalidSlasherAddressProvided If the slasher address is invalid
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
    *
+   * @example
    * ```ts
    * import { OperatorUtils, ChainId } from '@human-protocol/sdk';
    *
-   * const rewards = await OperatorUtils.getRewards(ChainId.POLYGON_AMOY, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * const rewards = await OperatorUtils.getRewards(
+   *   ChainId.POLYGON_AMOY,
+   *   '0x62dD51230A30401C455c8398d06F85e4EaB6309f'
+   * );
+   * console.log('Rewards:', rewards.length);
    * ```
    */
   public static async getRewards(

package/src/staking.ts

@@ -6,7 +6,7 @@ import {
   Staking,
   Staking__factory,
 } from '@human-protocol/core/typechain-types';
-import { ContractRunner, Overrides, ethers } from 'ethers';
+import { ContractRunner, ethers } from 'ethers';
 import { BaseEthersClient } from './base';
 import { NETWORKS } from './constants';
 import { requiresSigner } from './decorators';
@@ -29,7 +29,7 @@ import {
   SubgraphOptions,
 } from './interfaces';
 import { StakerData } from './graphql';
-import { NetworkData } from './types';
+import { NetworkData, TransactionOverrides } from './types';
 import { getSubgraphUrl, customGqlFetch, throwError } from './utils';
 import {
   GET_STAKER_BY_ADDRESS_QUERY,
@@ -37,9 +37,7 @@ import {
 } from './graphql/queries/staking';
 
 /**
- * ## Introduction
- *
- * This client enables performing actions on staking contracts and obtaining staking information from both the contracts and subgraph.
+ * Client for staking actions on HUMAN Protocol.
  *
  * Internally, the SDK will use one network or another according to the network ID of the `runner`.
  * To use this client, it is recommended to initialize it using the static `build` method.
@@ -53,37 +51,25 @@ import {
  * - **Signer**: when the user wants to use this model to send transactions calling the contract functions.
  * - **Provider**: when the user wants to use this model to get information from the contracts or subgraph.
  *
- * ## Installation
- *
- * ### npm
- * ```bash
- * npm install @human-protocol/sdk
- * ```
- *
- * ### yarn
- * ```bash
- * yarn install @human-protocol/sdk
- * ```
- *
- * ## Code example
+ * @example
  *
- * ### Signer
+ * ###Using Signer
  *
- * **Using private key (backend)**
+ * ####Using private key (backend)
  *
  * ```ts
  * import { StakingClient } from '@human-protocol/sdk';
- * import { Wallet, providers } from 'ethers';
+ * import { Wallet, JsonRpcProvider } from 'ethers';
  *
  * const rpcUrl = 'YOUR_RPC_URL';
  * const privateKey = 'YOUR_PRIVATE_KEY';
  *
- * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const provider = new JsonRpcProvider(rpcUrl);
  * const signer = new Wallet(privateKey, provider);
  * const stakingClient = await StakingClient.build(signer);
  * ```
  *
- * **Using Wagmi (frontend)**
+ * ####Using Wagmi (frontend)
  *
  * ```ts
  * import { useSigner, useChainId } from 'wagmi';
@@ -93,15 +79,15 @@ import {
  * const stakingClient = await StakingClient.build(signer);
  * ```
  *
- * ### Provider
+ * ###Using Provider
  *
  * ```ts
  * import { StakingClient } from '@human-protocol/sdk';
- * import { providers } from 'ethers';
+ * import { JsonRpcProvider } from 'ethers';
  *
  * const rpcUrl = 'YOUR_RPC_URL';
  *
- * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const provider = new JsonRpcProvider(rpcUrl);
  * const stakingClient = await StakingClient.build(provider);
  * ```
  */
@@ -113,8 +99,8 @@ export class StakingClient extends BaseEthersClient {
   /**
    * **StakingClient constructor**
    *
-   * @param {ContractRunner} runner - The Runner object to interact with the Ethereum network
-   * @param {NetworkData} networkData - The network information required to connect to the Staking contract
+   * @param runner - The Runner object to interact with the Ethereum network
+   * @param networkData - The network information required to connect to the Staking contract
    */
   constructor(runner: ContractRunner, networkData: NetworkData) {
     super(runner, networkData);
@@ -138,11 +124,23 @@ export class StakingClient extends BaseEthersClient {
   /**
    * Creates an instance of StakingClient from a Runner.
    *
-   * @param {ContractRunner} runner - The Runner object to interact with the Ethereum network
+   * @param runner - The Runner object to interact with the Ethereum network
+   * @returns An instance of StakingClient
+   * @throws ErrorProviderDoesNotExist If the provider does not exist for the provided Signer
+   * @throws ErrorUnsupportedChainID If the network's chainId is not supported
+   *
+   * @example
+   * ```ts
+   * import { StakingClient } from '@human-protocol/sdk';
+   * import { Wallet, JsonRpcProvider } from 'ethers';
+   *
+   * const rpcUrl = 'YOUR_RPC_URL';
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
-   * @returns {Promise<StakingClient>} - An instance of StakingClient
-   * @throws {ErrorProviderDoesNotExist} - Thrown if the provider does not exist for the provided Signer
-   * @throws {ErrorUnsupportedChainID} - Thrown if the network's chainId is not supported
+   * const provider = new JsonRpcProvider(rpcUrl);
+   * const signer = new Wallet(privateKey, provider);
+   * const stakingClient = await StakingClient.build(signer);
+   * ```
    */
   public static async build(runner: ContractRunner): Promise<StakingClient> {
     if (!runner.provider) {
@@ -179,31 +177,24 @@ export class StakingClient extends BaseEthersClient {
   /**
    * This function approves the staking contract to transfer a specified amount of tokens when the user stakes. It increases the allowance for the staking contract.
    *
-   * @param {bigint} amount Amount in WEI of tokens to approve for stake.
-   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns Returns void if successful. Throws error if any.
-   *
-   * **Code example**
+   * @param amount - Amount in WEI of tokens to approve for stake.
+   * @param txOptions - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns -
+   * @throws ErrorInvalidStakingValueType If the amount is not a bigint
+   * @throws ErrorInvalidStakingValueSign If the amount is negative
    *
+   * @example
    * ```ts
-   * import { ethers, Wallet, providers } from 'ethers';
-   * import { StakingClient } from '@human-protocol/sdk';
-   *
-   * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY';
+   * import { ethers } from 'ethers';
    *
-   * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const signer = new Wallet(privateKey, provider);
-   * const stakingClient = await StakingClient.build(signer);
-   *
-   * const amount = ethers.parseUnits(5, 'ether'); //convert from ETH to WEI
+   * const amount = ethers.parseUnits('5', 'ether'); //convert from ETH to WEI
    * await stakingClient.approveStake(amount);
    * ```
    */
   @requiresSigner
   public async approveStake(
     amount: bigint,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (typeof amount !== 'bigint') {
       throw ErrorInvalidStakingValueType;
@@ -214,13 +205,15 @@ export class StakingClient extends BaseEthersClient {
     }
 
     try {
-      await (
-        await this.tokenContract.approve(
-          await this.stakingContract.getAddress(),
-          amount,
-          txOptions
-        )
-      ).wait();
+      await this.sendTxAndWait(
+        async (overrides) =>
+          this.tokenContract.approve(
+            await this.stakingContract.getAddress(),
+            amount,
+            overrides
+          ),
+        txOptions
+      );
       return;
     } catch (e) {
       return throwError(e);
@@ -230,32 +223,29 @@ export class StakingClient extends BaseEthersClient {
   /**
    * This function stakes a specified amount of tokens on a specific network.
    *
-   * > `approveStake` must be called before
+   * !!! note
+   *     `approveStake` must be called before
    *
-   * @param {bigint} amount Amount in WEI of tokens to stake.
-   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns Returns void if successful. Throws error if any.
-   *
-   * **Code example**
+   * @param amount - Amount in WEI of tokens to stake.
+   * @param txOptions - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns -
+   * @throws ErrorInvalidStakingValueType If the amount is not a bigint
+   * @throws ErrorInvalidStakingValueSign If the amount is negative
    *
+   * @example
    * ```ts
-   * import { ethers, Wallet, providers } from 'ethers';
-   * import { StakingClient } from '@human-protocol/sdk';
+   * import { ethers } 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 stakingClient = await StakingClient.build(signer);
-   *
-   * const amount = ethers.parseUnits(5, 'ether'); //convert from ETH to WEI
+   * const amount = ethers.parseUnits('5', 'ether'); //convert from ETH to WEI
    * await stakingClient.approveStake(amount); // if it was already approved before, this is not necessary
    * await stakingClient.stake(amount);
    * ```
    */
   @requiresSigner
-  public async stake(amount: bigint, txOptions: Overrides = {}): Promise<void> {
+  public async stake(
+    amount: bigint,
+    txOptions: TransactionOverrides = {}
+  ): Promise<void> {
     if (typeof amount !== 'bigint') {
       throw ErrorInvalidStakingValueType;
     }
@@ -265,7 +255,10 @@ export class StakingClient extends BaseEthersClient {
     }
 
     try {
-      await (await this.stakingContract.stake(amount, txOptions)).wait();
+      await this.sendTxAndWait(
+        (overrides) => this.stakingContract.stake(amount, overrides),
+        txOptions
+      );
       return;
     } catch (e) {
       return throwError(e);
@@ -275,33 +268,27 @@ export class StakingClient extends BaseEthersClient {
   /**
    * This function unstakes tokens from staking contract. The unstaked tokens stay locked for a period of time.
    *
-   * > Must have tokens available to unstake
+   * !!! note
+   *     Must have tokens available to unstake
    *
-   * @param {bigint} amount Amount in WEI of tokens to unstake.
-   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns Returns void if successful. Throws error if any.
-   *
-   * **Code example**
+   * @param amount - Amount in WEI of tokens to unstake.
+   * @param txOptions - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns -
+   * @throws ErrorInvalidStakingValueType If the amount is not a bigint
+   * @throws ErrorInvalidStakingValueSign If the amount is negative
    *
+   * @example
    * ```ts
-   * import { ethers, Wallet, providers } from 'ethers';
-   * import { StakingClient } 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 stakingClient = await StakingClient.build(signer);
+   * import { ethers } from 'ethers';
    *
-   * const amount = ethers.parseUnits(5, 'ether'); //convert from ETH to WEI
+   * const amount = ethers.parseUnits('5', 'ether'); //convert from ETH to WEI
    * await stakingClient.unstake(amount);
    * ```
    */
   @requiresSigner
   public async unstake(
     amount: bigint,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (typeof amount !== 'bigint') {
       throw ErrorInvalidStakingValueType;
@@ -312,7 +299,10 @@ export class StakingClient extends BaseEthersClient {
     }
 
     try {
-      await (await this.stakingContract.unstake(amount, txOptions)).wait();
+      await this.sendTxAndWait(
+        (overrides) => this.stakingContract.unstake(amount, overrides),
+        txOptions
+      );
       return;
     } catch (e) {
       return throwError(e);
@@ -321,32 +311,24 @@ export class StakingClient extends BaseEthersClient {
 
   /**
    * This function withdraws unstaked and non-locked tokens from staking contract to the user wallet.
+   * !!! note
+   *     Must have tokens available to withdraw
    *
-   * > Must have tokens available to withdraw
-   *
-   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns Returns void if successful. Throws error if any.
-   *
-   * **Code example**
+   * @param txOptions - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns -
    *
+   * @example
    * ```ts
-   * import { Wallet, providers } from 'ethers';
-   * import { StakingClient } 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 stakingClient = await StakingClient.build(signer);
-   *
    * await stakingClient.withdraw();
    * ```
    */
   @requiresSigner
-  public async withdraw(txOptions: Overrides = {}): Promise<void> {
+  public async withdraw(txOptions: TransactionOverrides = {}): Promise<void> {
     try {
-      await (await this.stakingContract.withdraw(txOptions)).wait();
+      await this.sendTxAndWait(
+        (overrides) => this.stakingContract.withdraw(overrides),
+        txOptions
+      );
       return;
     } catch (e) {
       return throwError(e);
@@ -356,28 +338,30 @@ export class StakingClient extends BaseEthersClient {
   /**
    * This function reduces the allocated amount by a staker in an escrow and transfers those tokens to the reward pool. This allows the slasher to claim them later.
    *
-   * @param {string} slasher Wallet address from who requested the slash
-   * @param {string} staker Wallet address from who is going to be slashed
-   * @param {string} escrowAddress Address of the escrow that the slash is made
-   * @param {bigint} amount Amount in WEI of tokens to slash.
-   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns Returns void if successful. Throws error if any.
-   *
-   * **Code example**
-   *
+   * @param slasher - Wallet address from who requested the slash
+   * @param staker - Wallet address from who is going to be slashed
+   * @param escrowAddress - Address of the escrow that the slash is made
+   * @param amount - Amount in WEI of tokens to slash.
+   * @param txOptions - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns -
+   * @throws ErrorInvalidStakingValueType If the amount is not a bigint
+   * @throws ErrorInvalidStakingValueSign If the amount is negative
+   * @throws ErrorInvalidSlasherAddressProvided If the slasher address is invalid
+   * @throws ErrorInvalidStakerAddressProvided If the staker address is invalid
+   * @throws ErrorInvalidEscrowAddressProvided If the escrow address is invalid
+   * @throws ErrorEscrowAddressIsNotProvidedByFactory If the escrow is not provided by the factory
+   *
+   * @example
    * ```ts
-   * import { ethers, Wallet, providers } from 'ethers';
-   * import { StakingClient } 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 stakingClient = await StakingClient.build(signer);
-   *
-   * const amount = ethers.parseUnits(5, 'ether'); //convert from ETH to WEI
-   * await stakingClient.slash('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0x62dD51230A30401C455c8398d06F85e4EaB6309f', amount);
+   * import { ethers } from 'ethers';
+   *
+   * const amount = ethers.parseUnits('5', 'ether'); //convert from ETH to WEI
+   * await stakingClient.slash(
+   *   '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+   *   '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+   *   '0x62dD51230A30401C455c8398d06F85e4EaB6309f',
+   *   amount
+   * );
    * ```
    */
   @requiresSigner
@@ -386,7 +370,7 @@ export class StakingClient extends BaseEthersClient {
     staker: string,
     escrowAddress: string,
     amount: bigint,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (typeof amount !== 'bigint') {
       throw ErrorInvalidStakingValueType;
@@ -407,15 +391,17 @@ export class StakingClient extends BaseEthersClient {
     await this.checkValidEscrow(escrowAddress);
 
     try {
-      await (
-        await this.stakingContract.slash(
-          slasher,
-          staker,
-          escrowAddress,
-          amount,
-          txOptions
-        )
-      ).wait();
+      await this.sendTxAndWait(
+        (overrides) =>
+          this.stakingContract.slash(
+            slasher,
+            staker,
+            escrowAddress,
+            amount,
+            overrides
+          ),
+        txOptions
+      );
 
       return;
     } catch (e) {
@@ -426,21 +412,14 @@ export class StakingClient extends BaseEthersClient {
   /**
    * Retrieves comprehensive staking information for a staker.
    *
-   * @param {string} stakerAddress - The address of the staker.
-   * @returns {Promise<StakerInfo>}
-   *
-   * **Code example**
+   * @param stakerAddress - The address of the staker.
+   * @returns Staking information for the staker
+   * @throws ErrorInvalidStakerAddressProvided If the staker address is invalid
    *
+   * @example
    * ```ts
-   * import { StakingClient } from '@human-protocol/sdk';
-   *
-   * const rpcUrl = 'YOUR_RPC_URL';
-   *
-   * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const stakingClient = await StakingClient.build(provider);
-   *
    * const stakingInfo = await stakingClient.getStakerInfo('0xYourStakerAddress');
-   * console.log(stakingInfo.tokensStaked);
+   * console.log('Tokens staked:', stakingInfo.stakedAmount);
    * ```
    */
   public async getStakerInfo(stakerAddress: string): Promise<StakerInfo> {
@@ -479,16 +458,41 @@ export class StakingClient extends BaseEthersClient {
 }
 
 /**
- * Utility class for Staking-related subgraph queries.
+ * Utility helpers for Staking-related queries.
+ *
+ * @example
+ * ```ts
+ * import { StakingUtils, ChainId } from '@human-protocol/sdk';
+ *
+ * const staker = await StakingUtils.getStaker(
+ *   ChainId.POLYGON_AMOY,
+ *   '0xYourStakerAddress'
+ * );
+ * console.log('Staked amount:', staker.stakedAmount);
+ * ```
  */
 export class StakingUtils {
   /**
    * Gets staking info for a staker from the subgraph.
    *
-   * @param {ChainId} chainId Network in which the staking contract is deployed
-   * @param {string} stakerAddress Address of the staker
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IStaker>} Staker info from subgraph
+   * @param chainId - Network in which the staking contract is deployed
+   * @param stakerAddress - Address of the staker
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Staker info from subgraph
+   * @throws ErrorInvalidStakerAddressProvided If the staker address is invalid
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
+   * @throws ErrorStakerNotFound If the staker is not found
+   *
+   * @example
+   * ```ts
+   * import { StakingUtils, ChainId } from '@human-protocol/sdk';
+   *
+   * const staker = await StakingUtils.getStaker(
+   *   ChainId.POLYGON_AMOY,
+   *   '0xYourStakerAddress'
+   * );
+   * console.log('Staked amount:', staker.stakedAmount);
+   * ```
    */
   public static async getStaker(
     chainId: ChainId,
@@ -521,9 +525,22 @@ export class StakingUtils {
   /**
    * Gets all stakers from the subgraph with filters, pagination and ordering.
    *
-   * @param {IStakersFilter} filter Stakers filter with pagination and ordering
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IStaker[]>} Array of stakers
+   * @param filter - Stakers filter with pagination and ordering
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Array of stakers
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
+   *
+   * @example
+   * ```ts
+   * import { ChainId } from '@human-protocol/sdk';
+   *
+   * const filter = {
+   *   chainId: ChainId.POLYGON_AMOY,
+   *   minStakedAmount: '1000000000000000000', // 1 token in WEI
+   * };
+   * const stakers = await StakingUtils.getStakers(filter);
+   * console.log('Stakers:', stakers.length);
+   * ```
    */
   public static async getStakers(
     filter: IStakersFilter,