@human-protocol/sdk 3.0.8 → 4.0.0

package/src/graphql/queries/operator.ts

@@ -26,22 +26,30 @@ const LEADER_FRAGMENT = gql`
 `;
 
 export const GET_LEADERS_QUERY = (filter: ILeadersFilter) => {
-  const { role } = filter;
+  const { roles, minAmountStaked } = filter;
 
   const WHERE_CLAUSE = `
     where: {
-      ${role ? `role: $role` : ''}
+      ${minAmountStaked ? `amountStaked_gte: $minAmountStaked` : ''}
+      ${roles ? `role_in: $roles` : ''}
     }
   `;
 
   return gql`
     query getLeaders(
-      $role: String
+      $minAmountStaked: Int,
+      $roles: [String!]
+      $first: Int
+      $skip: Int
+      $orderBy: String
+      $orderDirection: String
     ) {
       leaders(
         ${WHERE_CLAUSE}
-        orderBy: amountStaked,
-        orderDirection: desc,
+        first: $first
+        skip: $skip
+        orderBy: $orderBy
+        orderDirection: $orderDirection
       ) {
         ...LeaderFields
       }

package/src/interfaces.ts

@@ -35,9 +35,11 @@ export interface ILeaderSubgraph
   reputationNetworks?: { address: string }[];
 }
 
-export interface ILeadersFilter {
+export interface ILeadersFilter extends IPagination {
   chainId: ChainId;
-  role?: string;
+  roles?: string[];
+  minAmountStaked?: number;
+  orderBy?: string;
 }
 
 export interface IReputationNetwork {
@@ -154,3 +156,10 @@ export interface IPagination {
   skip?: number;
   orderDirection?: OrderDirection;
 }
+
+export interface StakerInfo {
+  stakedAmount: bigint;
+  lockedAmount: bigint;
+  lockedUntil: bigint;
+  withdrawableAmount: bigint;
+}

package/src/kvstore.ts

@@ -29,19 +29,19 @@ import { IKVStore } from './interfaces';
 /**
  * ## Introduction
  *
- * This client enables to perform actions on KVStore contract and obtain information from both the contracts and subgraph.
+ * This client enables performing actions on KVStore contract and obtaining information from both the contracts and subgraph.
  *
  * 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.
  *
  * ```ts
- * static async build(runner: ContractRunner);
+ * static async build(runner: ContractRunner): Promise<KVStoreClient>;
  * ```
  *
  * 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.
+ * - **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
  *
@@ -59,21 +59,21 @@ import { IKVStore } from './interfaces';
  *
  * ### Signer
  *
- * **Using private key(backend)**
+ * **Using private key (backend)**
  *
  * ```ts
  * import { KVStoreClient } from '@human-protocol/sdk';
  * import { Wallet, providers } from 'ethers';
  *
  * const rpcUrl = 'YOUR_RPC_URL';
- * const privateKey = 'YOUR_PRIVATE_KEY'
+ * const privateKey = 'YOUR_PRIVATE_KEY';
  *
  * const provider = new providers.JsonRpcProvider(rpcUrl);
  * const signer = new Wallet(privateKey, provider);
  * const kvstoreClient = await KVStoreClient.build(signer);
  * ```
  *
- * **Using Wagmi(frontend)**
+ * **Using Wagmi (frontend)**
  *
  * ```ts
  * import { useSigner, useChainId } from 'wagmi';
@@ -92,7 +92,7 @@ import { IKVStore } from './interfaces';
  * const rpcUrl = 'YOUR_RPC_URL';
  *
  * const provider = new providers.JsonRpcProvider(rpcUrl);
- * const kvstoreClient = await KVStoreClient.build(signer);
+ * const kvstoreClient = await KVStoreClient.build(provider);
  * ```
  */
 
@@ -123,7 +123,7 @@ export class KVStoreClient extends BaseEthersClient {
    * @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(runner: ContractRunner) {
+  public static async build(runner: ContractRunner): Promise<KVStoreClient> {
     if (!runner.provider) {
       throw ErrorProviderDoesNotExist;
     }
@@ -158,7 +158,7 @@ export class KVStoreClient extends BaseEthersClient {
    * import { KVStoreClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -199,7 +199,7 @@ export class KVStoreClient extends BaseEthersClient {
    * import { KVStoreClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -207,7 +207,7 @@ export class KVStoreClient extends BaseEthersClient {
    *
    * const keys = ['role', 'webhook_url'];
    * const values = ['RecordingOracle', 'http://localhost'];
-   * await kvstoreClient.set(keys, values);
+   * await kvstoreClient.setBulk(keys, values);
    * ```
    */
   @requiresSigner
@@ -243,14 +243,14 @@ export class KVStoreClient extends BaseEthersClient {
    * import { KVStoreClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
    * const kvstoreClient = await KVStoreClient.build(signer);
    *
    * await kvstoreClient.setFileUrlAndHash('example.com');
-   * await kvstoreClient.setFileUrlAndHash('linkedin.com/example', 'linkedin_url);
+   * await kvstoreClient.setFileUrlAndHash('linkedin.com/example', 'linkedin_url');
    * ```
    */
   @requiresSigner
@@ -309,9 +309,9 @@ export class KVStoreClient extends BaseEthersClient {
  * ```ts
  * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
  *
- * const KVStoreAddresses = new KVStoreUtils.getKVStoreData({
+ * const KVStoreAddresses = await KVStoreUtils.getKVStoreData(
  *   ChainId.POLYGON_AMOY,
- *   "0x1234567890123456789012345678901234567890",
+ *   "0x1234567890123456789012345678901234567890"
  * );
  * ```
  */

package/src/operator.ts

@@ -22,16 +22,16 @@ import {
   ErrorUnsupportedChainID,
 } from './error';
 import { getSubgraphUrl } from './utils';
-import { ChainId } from './enums';
+import { ChainId, OrderDirection } from './enums';
 import { NETWORKS } from './constants';
 
 export class OperatorUtils {
   /**
    * This function returns the leader data for the given address.
    *
+   * @param {ChainId} chainId Network in which the leader is deployed
    * @param {string} address Leader address.
-   * @returns {ILeader} Returns the leader details.
-   *
+   * @returns {Promise<ILeader>} Returns the leader details.
    *
    * **Code example**
    *
@@ -91,13 +91,12 @@ export class OperatorUtils {
    * 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.
-   *
+   * @returns {Promise<ILeader[]>} Returns an array with all the leader details.
    *
    * **Code example**
    *
    * ```ts
-   * import { OperatorUtils } from '@human-protocol/sdk';
+   * import { OperatorUtils, ChainId } from '@human-protocol/sdk';
    *
    * const filter: ILeadersFilter = {
    *  chainId: ChainId.POLYGON
@@ -108,6 +107,14 @@ export class OperatorUtils {
   public static async getLeaders(filter: ILeadersFilter): Promise<ILeader[]> {
     let leaders_data: ILeader[] = [];
 
+    const first =
+      filter.first !== undefined && filter.first > 0
+        ? Math.min(filter.first, 1000)
+        : 10;
+    const skip =
+      filter.skip !== undefined && filter.skip >= 0 ? filter.skip : 0;
+    const orderDirection = filter.orderDirection || OrderDirection.DESC;
+
     const networkData = NETWORKS[filter.chainId];
 
     if (!networkData) {
@@ -117,7 +124,12 @@ export class OperatorUtils {
     const { leaders } = await gqlFetch<{
       leaders: ILeaderSubgraph[];
     }>(getSubgraphUrl(networkData), GET_LEADERS_QUERY(filter), {
-      role: filter?.role,
+      minAmountStaked: filter?.minAmountStaked,
+      roles: filter?.roles,
+      orderBy: filter?.orderBy,
+      orderDirection: orderDirection,
+      first: first,
+      skip: skip,
     });
 
     if (!leaders) {
@@ -158,12 +170,14 @@ export class OperatorUtils {
   /**
    * Retrieves the reputation network operators of the specified address.
    *
-   * @param {string} address - Address of the reputation oracle.
+   * @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.
    * @returns {Promise<IOperator[]>} - Returns an array of operator details.
    *
-   * @example
-   * ```typescript
+   * **Code example**
+   *
+   * ```ts
    * import { OperatorUtils, ChainId } from '@human-protocol/sdk';
    *
    * const operators = await OperatorUtils.getReputationNetworkOperators(ChainId.POLYGON_AMOY, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
@@ -207,9 +221,9 @@ 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.
-   * @returns {IReward[]} Returns an array of Reward objects that contain the rewards earned by the user through slashing other users.
-   *
+   * @returns {Promise<IReward[]>} Returns an array of Reward objects that contain the rewards earned by the user through slashing other users.
    *
    * **Code example**
    *

package/src/staking.ts

@@ -23,23 +23,24 @@ import {
 } from './error';
 import { NetworkData } from './types';
 import { throwError } from './utils';
+import { StakerInfo } from './interfaces';
 
 /**
  * ## Introduction
  *
- * This client enables to perform actions on staking contracts and obtain staking information from both the contracts and subgraph.
+ * This client enables performing actions on staking contracts and obtaining staking information from both the contracts and subgraph.
  *
  * 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.
  *
  * ```ts
- * static async build(runner: ContractRunner);
+ * static async build(runner: ContractRunner): Promise<StakingClient>;
  * ```
  *
  * 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.
+ * - **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
  *
@@ -57,21 +58,21 @@ import { throwError } from './utils';
  *
  * ### Signer
  *
- * **Using private key(backend)**
+ * **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 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)**
+ * **Using Wagmi (frontend)**
  *
  * ```ts
  * import { useSigner, useChainId } from 'wagmi';
@@ -132,7 +133,7 @@ export class StakingClient extends BaseEthersClient {
    * @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(runner: ContractRunner) {
+  public static async build(runner: ContractRunner): Promise<StakingClient> {
     if (!runner.provider) {
       throw ErrorProviderDoesNotExist;
     }
@@ -171,7 +172,6 @@ export class StakingClient extends BaseEthersClient {
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
-   *
    * **Code example**
    *
    * ```ts
@@ -179,7 +179,7 @@ export class StakingClient extends BaseEthersClient {
    * import { StakingClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -225,7 +225,6 @@ export class StakingClient extends BaseEthersClient {
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
-   *
    * **Code example**
    *
    * ```ts
@@ -233,7 +232,7 @@ export class StakingClient extends BaseEthersClient {
    * import { StakingClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -241,7 +240,7 @@ export class StakingClient extends BaseEthersClient {
    *
    * 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.approveStake(amount);
+   * await stakingClient.stake(amount);
    * ```
    */
   @requiresSigner
@@ -271,7 +270,6 @@ export class StakingClient extends BaseEthersClient {
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
-   *
    * **Code example**
    *
    * ```ts
@@ -279,7 +277,7 @@ export class StakingClient extends BaseEthersClient {
    * import { StakingClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -311,14 +309,13 @@ export class StakingClient extends BaseEthersClient {
   }
 
   /**
-   * This function withdraws unstaked and non locked tokens form staking contract to the user wallet.
+   * This function withdraws unstaked and non-locked tokens from staking contract to the user wallet.
    *
    * > 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**
    *
    * ```ts
@@ -326,7 +323,7 @@ export class StakingClient extends BaseEthersClient {
    * import { StakingClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -346,16 +343,15 @@ export class StakingClient extends BaseEthersClient {
   }
 
   /**
-   * 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.
+   * 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).
-   * @param {bigint} amount Amount in WEI of tokens to unstake.
    * @returns Returns void if successful. Throws error if any.
    *
-   *
    * **Code example**
    *
    * ```ts
@@ -363,7 +359,7 @@ export class StakingClient extends BaseEthersClient {
    * import { StakingClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
-   * const privateKey = 'YOUR_PRIVATE_KEY'
+   * const privateKey = 'YOUR_PRIVATE_KEY';
    *
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const signer = new Wallet(privateKey, provider);
@@ -415,4 +411,57 @@ export class StakingClient extends BaseEthersClient {
       return throwError(e);
     }
   }
+
+  /**
+   * Retrieves comprehensive staking information for a staker.
+   *
+   * @param {string} stakerAddress - The address of the staker.
+   * @returns {Promise<StakerInfo>}
+   *
+   * **Code 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);
+   * ```
+   */
+  public async getStakerInfo(stakerAddress: string): Promise<StakerInfo> {
+    if (!ethers.isAddress(stakerAddress)) {
+      throw ErrorInvalidStakerAddressProvided;
+    }
+
+    try {
+      const stakerInfo = await this.stakingContract.stakes(stakerAddress);
+      const currentBlock = await this.runner.provider!.getBlockNumber();
+
+      const tokensWithdrawable =
+        stakerInfo.tokensLockedUntil !== 0n &&
+        currentBlock >= stakerInfo.tokensLockedUntil
+          ? stakerInfo.tokensLocked
+          : 0n;
+
+      const adjustedLockedAmount =
+        stakerInfo.tokensLockedUntil !== 0n &&
+        currentBlock >= stakerInfo.tokensLockedUntil
+          ? 0n
+          : stakerInfo.tokensLocked;
+
+      return {
+        stakedAmount: stakerInfo.tokensStaked,
+        lockedAmount: adjustedLockedAmount,
+        lockedUntil:
+          adjustedLockedAmount === 0n ? 0n : stakerInfo.tokensLockedUntil,
+        withdrawableAmount: tokensWithdrawable,
+      };
+    } catch (error) {
+      return throwError(error);
+    }
+  }
 }

package/src/statistics.ts

@@ -26,20 +26,15 @@ import { OrderDirection } from './enums';
 /**
  * ## Introduction
  *
- * This client enables to obtain statistical information from the subgraph.
+ * This client enables obtaining statistical information from the subgraph.
  *
- * Unlikely from the other SDK clients, `StatisticsClient` does not require `signer` or `provider` to be provided.
- * We just need to create client object using relevant network data.
+ * Unlike other SDK clients, `StatisticsClient` does not require `signer` or `provider` to be provided.
+ * We just need to create a client object using relevant network data.
  *
  * ```ts
  * constructor(network: NetworkData)
  * ```
  *
- * 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
@@ -77,7 +72,6 @@ export class StatisticsClient {
   /**
    * This function returns the statistical data of escrows.
    *
-   *
    * **Input parameters**
    *
    * ```ts
@@ -106,10 +100,8 @@ export class StatisticsClient {
    * };
    * ```
    *
-   *
    * @param {IStatisticsFilter} filter Statistics params with duration data
-   * @returns {EscrowStatistics} Escrow statistics data.
-   *
+   * @returns {Promise<EscrowStatistics>} Escrow statistics data.
    *
    * **Code example**
    *
@@ -169,7 +161,6 @@ export class StatisticsClient {
   /**
    * This function returns the statistical data of workers.
    *
-   *
    * **Input parameters**
    *
    * ```ts
@@ -193,10 +184,8 @@ export class StatisticsClient {
    * };
    * ```
    *
-   *
    * @param {IStatisticsFilter} filter Statistics params with duration data
-   * @returns {WorkerStatistics} Worker statistics data.
-   *
+   * @returns {Promise<WorkerStatistics>} Worker statistics data.
    *
    * **Code example**
    *
@@ -245,7 +234,6 @@ export class StatisticsClient {
   /**
    * This function returns the statistical data of payments.
    *
-   *
    * **Input parameters**
    *
    * ```ts
@@ -271,10 +259,8 @@ export class StatisticsClient {
    * };
    * ```
    *
-   *
    * @param {IStatisticsFilter} filter Statistics params with duration data
-   * @returns {PaymentStatistics} Payment statistics data.
-   *
+   * @returns {Promise<PaymentStatistics>} Payment statistics data.
    *
    * **Code example**
    *
@@ -350,7 +336,7 @@ export class StatisticsClient {
   /**
    * This function returns the statistical data of HMToken.
    *
-   *
+   * ```ts
    * type HMTStatistics = {
    *   totalTransferAmount: BigNumber;
    *   totalTransferCount: BigNumber;
@@ -358,9 +344,7 @@ export class StatisticsClient {
    * };
    * ```
    *
-   *
-   * @returns {HMTStatistics} HMToken statistics data.
-   *
+   * @returns {Promise<HMTStatistics>} HMToken statistics data.
    *
    * **Code example**
    *
@@ -401,7 +385,7 @@ export class StatisticsClient {
    * **Input parameters**
    *
    * @param {IHMTHoldersParams} params HMT Holders params with filters and ordering
-   * @returns {HMTHolder[]} List of HMToken holders.
+   * @returns {Promise<HMTHolder[]>} List of HMToken holders.
    *
    * **Code example**
    *
@@ -447,7 +431,6 @@ export class StatisticsClient {
   /**
    * This function returns the statistical data of HMToken day by day.
    *
-   *
    * **Input parameters**
    *
    * ```ts
@@ -470,10 +453,8 @@ export class StatisticsClient {
    * }
    * ```
    *
-   *
    * @param {IStatisticsFilter} filter Statistics params with duration data
-   * @returns {DailyHMTData[]} Daily HMToken statistics data.
-   *
+   * @returns {Promise<DailyHMTData[]>} Daily HMToken statistics data.
    *
    * **Code example**
    *