@human-protocol/sdk 5.2.0 → 6.0.0

package/dist/staking.js

@@ -20,9 +20,7 @@ const error_1 = require("./error");
 const utils_1 = require("./utils");
 const staking_1 = require("./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.
@@ -36,37 +34,25 @@ const staking_1 = require("./graphql/queries/staking");
  * - **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';
@@ -76,15 +62,15 @@ const staking_1 = require("./graphql/queries/staking");
  * 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);
  * ```
  */
@@ -92,8 +78,8 @@ class StakingClient extends base_1.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, networkData) {
         super(runner, networkData);
@@ -104,11 +90,23 @@ class StakingClient extends base_1.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);
+     * ```
      */
     static async build(runner) {
         if (!runner.provider) {
@@ -138,24 +136,17 @@ class StakingClient extends base_1.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);
      * ```
      */
@@ -177,26 +168,20 @@ class StakingClient extends base_1.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);
      * ```
@@ -219,26 +204,20 @@ class StakingClient extends base_1.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);
      * ```
      */
@@ -259,25 +238,14 @@ class StakingClient extends base_1.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();
      * ```
      */
@@ -293,28 +261,30 @@ class StakingClient extends base_1.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
+     * );
      * ```
      */
     async slash(slasher, staker, escrowAddress, amount, txOptions = {}) {
@@ -342,21 +312,14 @@ class StakingClient extends base_1.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);
      * ```
      */
     async getStakerInfo(stakerAddress) {
@@ -418,16 +381,41 @@ __decorate([
     __metadata("design:returntype", Promise)
 ], StakingClient.prototype, "slash", null);
 /**
- * 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);
+ * ```
  */
 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);
+     * ```
      */
     static async getStaker(chainId, stakerAddress, options) {
         if (!ethers_1.ethers.isAddress(stakerAddress)) {
@@ -446,9 +434,22 @@ 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);
+     * ```
      */
     static async getStakers(filter, options) {
         const first = filter.first !== undefined ? Math.min(filter.first, 1000) : 10;