@human-protocol/sdk 5.2.0 → 6.0.0

package/src/staking.ts

@@ -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
    *
-   * @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
+   * @example
+   * ```ts
+   * import { StakingClient } from '@human-protocol/sdk';
+   * import { Wallet, JsonRpcProvider } from 'ethers';
+   *
+   * const rpcUrl = 'YOUR_RPC_URL';
+   * const privateKey = 'YOUR_PRIVATE_KEY';
+   *
+   * 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,24 +177,17 @@ 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);
    * ```
    */
@@ -230,26 +221,20 @@ export class StakingClient extends BaseEthersClient {
   /**
    * This function stakes a specified amount of tokens on a specific network.
    *
-   * > `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.
+   * !!! note
+   *     `approveStake` must be called before
    *
-   * **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);
    * ```
@@ -275,26 +260,20 @@ 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
-   *
-   * @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.
+   * !!! note
+   *     Must have tokens available to unstake
    *
-   * **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);
    * ```
    */
@@ -321,25 +300,14 @@ 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();
    * ```
    */
@@ -356,28 +324,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
@@ -426,21 +396,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 +442,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 +509,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,