@human-protocol/sdk 1.1.13 → 1.1.15

package/dist/staking.js

@@ -22,6 +22,75 @@ const error_1 = require("./error");
 const utils_1 = require("./utils");
 const reward_1 = require("./graphql/queries/reward");
 const staking_1 = require("./graphql/queries/staking");
+/**
+ * ## Introduction
+ *
+ * This client enables to perform actions on staking contracts and obtain staking 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 { StakingClient } 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 stakingClient = await StakingClient.build(signer);
+ * ```
+ *
+ * **Using Wagmi(frontend)**
+ *
+ * ```ts
+ * import { useSigner, useChainId } from 'wagmi';
+ * import { StakingClient } from '@human-protocol/sdk';
+ *
+ * const { data: signer } = useSigner();
+ * const stakingClient = await StakingClient.build(signer);
+ * ```
+ *
+ * ### Provider
+ *
+ * ```ts
+ * import { StakingClient } from '@human-protocol/sdk';
+ * import { providers } from 'ethers';
+ *
+ * const rpcUrl = 'YOUR_RPC_URL';
+ *
+ * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const stakingClient = await StakingClient.build(provider);
+ * ```
+ */
 class StakingClient {
     /**
      * **StakingClient constructor**
@@ -63,12 +132,28 @@ class StakingClient {
         return new StakingClient(signerOrProvider, networkData);
     }
     /**
-     * **Approves the staking contract to transfer a specified amount of tokens when the user stakes.
-     * **It increases the allowance for the staking contract.*
+     * 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 {BigNumber} amount - Amount of tokens to approve for stake
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred, void otherwise
+     * @param {BigNumber} amount Amount in WEI of tokens to approve for stake.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code 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.utils.parseUnits(5, 'ether'); //convert from ETH to WEI
+     * await stakingClient.approveStake(amount);
+     * ```
      */
     async approveStake(amount) {
         if (!ethers_1.BigNumber.isBigNumber(amount)) {
@@ -86,11 +171,31 @@ class StakingClient {
         }
     }
     /**
-     * **Stakes a specified amount of tokens on a specific network.*
+     * This function stakes a specified amount of tokens on a specific network.
+     *
+     * > `approveStake` must be called before
+     *
+     * @param {BigNumber} amount Amount in WEI of tokens to stake.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
      *
-     * @param {BigNumber} amount - Amount of tokens to stake
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred, void otherwise
+     * ```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.utils.parseUnits(5, 'ether'); //convert from ETH to WEI
+     * await stakingClient.approveStake(amount); // if it was already approved before, this is not necessary
+     * await stakingClient.approveStake(amount);
+     * ```
      */
     async stake(amount) {
         if (!ethers_1.BigNumber.isBigNumber(amount)) {
@@ -108,12 +213,30 @@ class StakingClient {
         }
     }
     /**
-     * **Unstakes tokens from staking contract.
-     * **The unstaked tokens stay locked for a period of time.*
+     * This function unstakes tokens from staking contract. The unstaked tokens stay locked for a period of time.
+     *
+     * > Must have tokens available to unstake
+     *
+     * @param {BigNumber} amount Amount in WEI of tokens to unstake.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code 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);
      *
-     * @param {BigNumber} amount - Amount of tokens to unstake
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred, void otherwise
+     * const amount = ethers.utils.parseUnits(5, 'ether'); //convert from ETH to WEI
+     * await stakingClient.unstake(amount);
+     * ```
      */
     async unstake(amount) {
         if (!ethers_1.BigNumber.isBigNumber(amount)) {
@@ -131,10 +254,28 @@ class StakingClient {
         }
     }
     /**
-     * **Withdraws unstaked and non locked tokens form staking contract to the user wallet.*
+     * This function withdraws unstaked and non locked tokens form staking contract to the user wallet.
      *
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred, void otherwise
+     * > Must have tokens available to withdraw
+     *
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code 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();
+     * ```
      */
     async withdraw() {
         try {
@@ -146,15 +287,31 @@ class StakingClient {
         }
     }
     /**
-     * **Slash the allocated amount by an 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 which allocation will be slashed
-     * @param {BigNumber} amount - Amount of tokens to slash
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred, void otherwise
+     * This function reduces the allocated amount by an 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 which allocation will be slashed
+     * @param {BigNumber} amount Amount in WEI of tokens to unstake.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code 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.utils.parseUnits(5, 'ether'); //convert from ETH to WEI
+     * await stakingClient.slash('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0x62dD51230A30401C455c8398d06F85e4EaB6309f', amount);
+     * ```
      */
     async slash(slasher, staker, escrowAddress, amount) {
         if (!ethers_1.BigNumber.isBigNumber(amount)) {
@@ -184,12 +341,31 @@ class StakingClient {
         }
     }
     /**
-     * **Allocates a portion of the staked tokens to a specific escrow.*
+     * This function allocates a portion of the staked tokens to a specific escrow.
+     *
+     * > Must have tokens staked
+     *
+     * @param {string} escrowAddress Address of the escrow contract to allocate in.
+     * @param {BigNumber} amount Amount in WEI of tokens to allocate.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { ethers, Wallet, providers } from 'ethers';
+     * import { StakingClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     * const privateKey = 'YOUR_PRIVATE_KEY'
      *
-     * @param {string} escrowAddress - Address of the escrow contract
-     * @param {BigNumber} amount - Amount of tokens to allocate
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred, void otherwise
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const signer = new Wallet(privateKey, provider);
+     * const stakingClient = await StakingClient.build(signer);
+     *
+     * const amount = ethers.utils.parseUnits(5, 'ether'); //convert from ETH to WEI
+     * await stakingClient.allocate('0x62dD51230A30401C455c8398d06F85e4EaB6309f', amount);
+     * ```
      */
     async allocate(escrowAddress, amount) {
         if (!ethers_1.BigNumber.isBigNumber(amount)) {
@@ -213,11 +389,30 @@ class StakingClient {
         }
     }
     /**
-     * **Drops the allocation from a specific escrow.*
+     * This function drops the allocation from a specific escrow.
+     *
+     * > The escrow must have allocation
+     * > The escrow must be cancelled or completed.
+     *
+     * @param {string} escrowAddress Address of the escrow contract to close allocation from.
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
      *
-     * @param {string} escrowAddress - Address of the escrow contract.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred, void otherwise
+     * ```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.closeAllocation('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async closeAllocation(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -235,11 +430,29 @@ class StakingClient {
         }
     }
     /**
-     * **Pays out rewards to the slashers for the specified escrow address.*
+     * This function drops the allocation from a specific escrow.
+     *
+     * > The escrow must have rewards added
+     *
+     * @param {string} escrowAddress Escrow address from which rewards are distributed.
+     * @returns Returns void if successful. Throws error if any.
      *
-     * @param {string} escrowAddress - Escrow address from which rewards are distributed.
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred, void otherwise
+     *
+     * **Code 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.distributeRewards('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async distributeRewards(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -258,11 +471,25 @@ class StakingClient {
         }
     }
     /**
-     * **Returns the leader details for a given address**
+     * This function returns all the leader details of the protocol.
+     *
+     * @param {ILeadersFilter} filter Filter for the leaders.
+     * @returns {ILeader[]} Returns an array with all the leader details.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StakingClient } from '@human-protocol/sdk';
+     * import { providers } from 'ethers';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
      *
-     * @param {string} address - Leader address
-     * @returns {Promise<ILeader>} - Return leader details
-     * @throws {Error} - An error object if an error occurred, result otherwise
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const stakingClient = await StakingClient.build(provider);
+     *
+     * const leaders = await stakingClient.getLeaders();
+     * ```
      */
     async getLeader(address) {
         if (!ethers_1.ethers.utils.isAddress(address)) {
@@ -279,10 +506,25 @@ class StakingClient {
         }
     }
     /**
-     * **Returns the leaders data **
+     * This function returns the leader data for the given address.
+     *
+     * @param {string} address Leader address.
+     * @returns {ILeader} Returns the leader details.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StakingClient } from '@human-protocol/sdk';
+     * import { providers } from 'ethers';
      *
-     * @returns {Promise<ILeader[]>} - Return an array with leaders data
-     * @throws {Error} - An error object if an error occurred, results otherwise
+     * const rpcUrl = 'YOUR_RPC_URL';
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const stakingClient = await StakingClient.build(provider);
+     *
+     * const leader = await stakingClient.getLeader('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getLeaders(filter = {}) {
         try {
@@ -296,11 +538,25 @@ class StakingClient {
         }
     }
     /**
-     * **Returns information about the allocation of the specified escrow.*
+     * This function returns information about the allocation of the specified escrow.
+     *
+     * @param {string} escrowAddress Escrow address from which we want to get allocation information.
+     * @returns {IAllocation} Returns allocation info if exists.
+     *
+     *
+     * **Code example**
      *
-     * @param {string} escrowAddress - The escrow address for the received allocation data
-     * @returns {Promise<IAllocation>} - Returns allocation info if exists
-     * @throws {Error} - An error object if an error occurred, result otherwise
+     * ```ts
+     * import { StakingClient } from '@human-protocol/sdk';
+     * import { providers } from 'ethers';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const stakingClient = await StakingClient.build(provider);
+     *
+     * const allocationInfo = await stakingClient.getAllocation('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getAllocation(escrowAddress) {
         if (!ethers_1.ethers.utils.isAddress(escrowAddress)) {
@@ -318,11 +574,25 @@ class StakingClient {
         }
     }
     /**
-     * **Returns information about the rewards for a given escrow address.*
+     * This function returns information about the rewards for a given slasher address.
+     *
+     * @param {string} slasherAddress Slasher address.
+     * @returns {IReward[]} Returns an array of Reward objects that contain the rewards earned by the user through slashing other users.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StakingClient } from '@human-protocol/sdk';
+     * import { providers } from 'ethers';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const stakingClient = await StakingClient.build(provider);
      *
-     * @param {string} slasherAddress - Address of the slasher
-     * @returns {Promise<IReward[]>} - Returns rewards info if exists
-     * @throws {Error} - An error object if an error occurred, results otherwise
+     * const rewards = await stakingClient.getRewards('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+     * ```
      */
     async getRewards(slasherAddress) {
         if (!ethers_1.ethers.utils.isAddress(slasherAddress)) {