@human-protocol/sdk 1.1.18 → 2.0.0

package/src/graphql/queries/{staking.ts → operator.ts}

@@ -47,6 +47,30 @@ export const GET_LEADERS_QUERY = (filter: ILeadersFilter) => {
   `;
 };
 
+export const GET_REPUTATION_NETWORK_QUERY = (role?: string) => {
+  const WHERE_CLAUSE = `
+    where: {
+      ${role ? `role: $role` : ''}
+    }
+  `;
+
+  return gql`
+    query getReputationNetwork(
+      $address: String,
+      $role: String
+    ) {
+      reputationNetwork(id: $address) {
+        operators(
+          ${WHERE_CLAUSE}
+        ) {
+          address,
+          role
+        }
+      }
+    }
+  `;
+};
+
 export const GET_LEADER_QUERY = gql`
   query getLeader($address: String!) {
     leader(id: $address) {

package/src/graphql/types.ts

@@ -1,5 +1,3 @@
-import { BigNumber } from 'ethers';
-
 export type EscrowData = {
   id: string;
   address: string;
@@ -108,9 +106,9 @@ export type WorkerStatistics = {
 
 export type DailyPaymentData = {
   timestamp: Date;
-  totalAmountPaid: BigNumber;
+  totalAmountPaid: bigint;
   totalCount: number;
-  averageAmountPerWorker: BigNumber;
+  averageAmountPerWorker: bigint;
 };
 
 export type PaymentStatistics = {
@@ -124,17 +122,17 @@ export type HMTHolderData = {
 
 export type HMTHolder = {
   address: string;
-  balance: BigNumber;
+  balance: bigint;
 };
 
 export type DailyHMTData = {
   timestamp: Date;
-  totalTransactionAmount: BigNumber;
+  totalTransactionAmount: bigint;
   totalTransactionCount: number;
 };
 
 export type HMTStatistics = {
-  totalTransferAmount: BigNumber;
+  totalTransferAmount: bigint;
   totalTransferCount: number;
   totalHolders: number;
   holders: HMTHolder[];

package/src/index.ts

@@ -4,6 +4,7 @@ import { KVStoreClient } from './kvstore';
 import { EscrowClient, EscrowUtils } from './escrow';
 import { StatisticsClient } from './statistics';
 import { Encryption, EncryptionUtils } from './encryption';
+import { OperatorUtils } from './operator';
 
 export * from './constants';
 export * from './types';
@@ -19,4 +20,5 @@ export {
   StatisticsClient,
   Encryption,
   EncryptionUtils,
+  OperatorUtils,
 };

package/src/interfaces.ts

@@ -1,40 +1,52 @@
-import { BigNumber } from 'ethers';
 import { EscrowStatus } from './types';
 import { ChainId } from './enums';
 
 export interface IAllocation {
   escrowAddress: string;
   staker: string;
-  tokens: BigNumber;
-  createdAt: BigNumber;
-  closedAt: BigNumber;
+  tokens: bigint;
+  createdAt: bigint;
+  closedAt: bigint;
 }
 
 export interface IReward {
   escrowAddress: string;
-  amount: BigNumber;
+  amount: bigint;
 }
 
 export interface ILeader {
   id: string;
+  chainId: ChainId;
   address: string;
-  amountStaked: BigNumber;
-  amountAllocated: BigNumber;
-  amountLocked: BigNumber;
-  lockedUntilTimestamp: BigNumber;
-  amountWithdrawn: BigNumber;
-  amountSlashed: BigNumber;
-  reputation: BigNumber;
-  reward: BigNumber;
-  amountJobsLaunched: BigNumber;
+  amountStaked: bigint;
+  amountAllocated: bigint;
+  amountLocked: bigint;
+  lockedUntilTimestamp: bigint;
+  amountWithdrawn: bigint;
+  amountSlashed: bigint;
+  reputation: bigint;
+  reward: bigint;
+  amountJobsLaunched: bigint;
   role?: string;
-  fee?: BigNumber;
+  fee?: bigint;
   publicKey?: string;
   webhookUrl?: string;
   url?: string;
 }
 
 export interface ILeadersFilter {
+  networks: ChainId[];
+  role?: string;
+}
+
+export interface IReputationNetwork {
+  id: string;
+  address: string;
+  operators: IOperator[];
+}
+
+export interface IOperator {
+  address: string;
   role?: string;
 }
 
@@ -54,9 +66,9 @@ export interface IEscrowConfig {
   recordingOracle: string;
   reputationOracle: string;
   exchangeOracle: string;
-  recordingOracleFee: BigNumber;
-  reputationOracleFee: BigNumber;
-  exchangeOracleFee: BigNumber;
+  recordingOracleFee: bigint;
+  reputationOracleFee: bigint;
+  exchangeOracleFee: bigint;
   manifestUrl: string;
   manifestHash: string;
 }

package/src/kvstore.ts

@@ -1,10 +1,8 @@
-import { Provider } from '@ethersproject/abstract-provider';
-import { Network } from '@ethersproject/networks';
 import {
   KVStore,
   KVStore__factory,
 } from '@human-protocol/core/typechain-types';
-import { Signer, ethers } from 'ethers';
+import { ContractRunner, Overrides, ethers } from 'ethers';
 import { BaseEthersClient } from './base';
 import { NETWORKS } from './constants';
 import { requiresSigner } from './decorators';
@@ -16,7 +14,6 @@ import {
   ErrorKVStoreArrayLength,
   ErrorKVStoreEmptyKey,
   ErrorProviderDoesNotExist,
-  ErrorSigner,
   ErrorUnsupportedChainID,
 } from './error';
 import { NetworkData } from './types';
@@ -27,11 +24,11 @@ import { isValidUrl } from './utils';
  *
  * This client enables to perform actions on KVStore contract and obtain information from both the contracts and subgraph.
  *
- * Internally, the SDK will use one network or another according to the network ID of the `signerOrProvider`.
+ * 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(signerOrProvider: Signer | Provider);
+ * static async build(runner: ContractRunner);
  * ```
  *
  * A `Signer` or a `Provider` should be passed depending on the use case of this module:
@@ -97,56 +94,42 @@ export class KVStoreClient extends BaseEthersClient {
   /**
    * **KVStoreClient constructor**
    *
-   * @param {Signer | Provider} signerOrProvider - The Signer or Provider object to interact with the Ethereum network
+   * @param {ContractRunner} runner - The Runner object to interact with the Ethereum network
    * @param {NetworkData} network - The network information required to connect to the KVStore contract
-   * @param {number | undefined} gasPriceMultiplier - The multiplier to apply to the gas price
    */
-  constructor(
-    signerOrProvider: Signer | Provider,
-    networkData: NetworkData,
-    gasPriceMultiplier?: number
-  ) {
-    super(signerOrProvider, networkData, gasPriceMultiplier);
+  constructor(runner: ContractRunner, networkData: NetworkData) {
+    super(runner, networkData);
 
     this.contract = KVStore__factory.connect(
       networkData.kvstoreAddress,
-      signerOrProvider
+      runner
     );
   }
 
   /**
-   * Creates an instance of KVStoreClient from a Signer or Provider.
+   * Creates an instance of KVStoreClient from a runner.
    *
-   * @param {Signer | Provider} signerOrProvider - The Signer or Provider object to interact with the Ethereum network
-   * @param {number | undefined} gasPriceMultiplier - The multiplier to apply to the gas price
+   * @param {ContractRunner} runner - The Runner object to interact with the Ethereum network
    *
    * @returns {Promise<KVStoreClient>} - An instance of KVStoreClient
    * @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(
-    signerOrProvider: Signer | Provider,
-    gasPriceMultiplier?: number
-  ) {
-    let network: Network;
-    if (Signer.isSigner(signerOrProvider)) {
-      if (!signerOrProvider.provider) {
-        throw ErrorProviderDoesNotExist;
-      }
-
-      network = await signerOrProvider.provider.getNetwork();
-    } else {
-      network = await signerOrProvider.getNetwork();
+  public static async build(runner: ContractRunner) {
+    if (!runner.provider) {
+      throw ErrorProviderDoesNotExist;
     }
 
-    const chainId: ChainId = network.chainId;
+    const network = await runner.provider?.getNetwork();
+
+    const chainId: ChainId = Number(network?.chainId);
     const networkData = NETWORKS[chainId];
 
     if (!networkData) {
       throw ErrorUnsupportedChainID;
     }
 
-    return new KVStoreClient(signerOrProvider, networkData, gasPriceMultiplier);
+    return new KVStoreClient(runner, networkData);
   }
 
   /**
@@ -154,6 +137,7 @@ export class KVStoreClient extends BaseEthersClient {
    *
    * @param {string} key Key of the key-value pair
    * @param {string} value Value of the key-value pair
+   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
    *
@@ -176,13 +160,14 @@ export class KVStoreClient extends BaseEthersClient {
    * ```
    */
   @requiresSigner
-  public async set(key: string, value: string): Promise<void> {
-    if (!Signer.isSigner(this.signerOrProvider)) throw ErrorSigner;
+  public async set(
+    key: string,
+    value: string,
+    txOptions: Overrides = {}
+  ): Promise<void> {
     if (key === '') throw ErrorKVStoreEmptyKey;
     try {
-      await this.contract?.set(key, value, {
-        ...(await this.gasPriceOptions()),
-      });
+      await (await this.contract.set(key, value, txOptions)).wait();
     } catch (e) {
       if (e instanceof Error) throw Error(`Failed to set value: ${e.message}`);
     }
@@ -193,6 +178,7 @@ export class KVStoreClient extends BaseEthersClient {
    *
    * @param {string[]} keys Array of keys (keys and value must have the same order)
    * @param {string[]} values Array of values
+   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
    *
@@ -217,15 +203,16 @@ export class KVStoreClient extends BaseEthersClient {
    * ```
    */
   @requiresSigner
-  public async setBulk(keys: string[], values: string[]): Promise<void> {
-    if (!Signer.isSigner(this.signerOrProvider)) throw ErrorSigner;
+  public async setBulk(
+    keys: string[],
+    values: string[],
+    txOptions: Overrides = {}
+  ): Promise<void> {
     if (keys.length !== values.length) throw ErrorKVStoreArrayLength;
     if (keys.includes('')) throw ErrorKVStoreEmptyKey;
 
     try {
-      await this.contract?.setBulk(keys, values, {
-        ...(await this.gasPriceOptions()),
-      });
+      await (await this.contract.setBulk(keys, values, txOptions)).wait();
     } catch (e) {
       if (e instanceof Error)
         throw Error(`Failed to set bulk values: ${e.message}`);
@@ -237,6 +224,7 @@ export class KVStoreClient extends BaseEthersClient {
    *
    * @param {string} url URL to set
    * @param {string | undefined} urlKey Configurable URL key. `url` by default.
+   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
    *
@@ -258,26 +246,28 @@ export class KVStoreClient extends BaseEthersClient {
    * ```
    */
   @requiresSigner
-  public async setURL(url: string, urlKey = 'url'): Promise<void> {
-    if (!Signer.isSigner(this.signerOrProvider)) {
-      throw ErrorSigner;
-    }
-
+  public async setURL(
+    url: string,
+    urlKey = 'url',
+    txOptions: Overrides = {}
+  ): Promise<void> {
     if (!isValidUrl(url)) {
       throw ErrorInvalidUrl;
     }
 
     const content = await fetch(url).then((res) => res.text());
-    const contentHash = ethers.utils.keccak256(
-      ethers.utils.toUtf8Bytes(content)
-    );
+    const contentHash = ethers.keccak256(ethers.toUtf8Bytes(content));
 
     const hashKey = urlKey + 'Hash';
 
     try {
-      await this.contract.setBulk([urlKey, hashKey], [url, contentHash], {
-        ...(await this.gasPriceOptions()),
-      });
+      await (
+        await this.contract.setBulk(
+          [urlKey, hashKey],
+          [url, contentHash],
+          txOptions
+        )
+      ).wait();
     } catch (e) {
       if (e instanceof Error)
         throw Error(`Failed to set URL and hash: ${e.message}`);
@@ -310,7 +300,7 @@ export class KVStoreClient extends BaseEthersClient {
    */
   public async get(address: string, key: string): Promise<string> {
     if (key === '') throw ErrorKVStoreEmptyKey;
-    if (!ethers.utils.isAddress(address)) throw ErrorInvalidAddress;
+    if (!ethers.isAddress(address)) throw ErrorInvalidAddress;
 
     try {
       const result = await this.contract?.get(address, key);
@@ -348,7 +338,7 @@ export class KVStoreClient extends BaseEthersClient {
    * ```
    */
   public async getURL(address: string, urlKey = 'url'): Promise<string> {
-    if (!ethers.utils.isAddress(address)) throw ErrorInvalidAddress;
+    if (!ethers.isAddress(address)) throw ErrorInvalidAddress;
     const hashKey = urlKey + 'Hash';
 
     let url = '',
@@ -372,9 +362,7 @@ export class KVStoreClient extends BaseEthersClient {
     }
 
     const content = await fetch(url).then((res) => res.text());
-    const contentHash = ethers.utils.keccak256(
-      ethers.utils.toUtf8Bytes(content)
-    );
+    const contentHash = ethers.keccak256(ethers.toUtf8Bytes(content));
 
     if (hash !== contentHash) {
       throw ErrorInvalidHash;

package/src/operator.ts

@@ -0,0 +1,192 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import gqlFetch from 'graphql-request';
+import {
+  ILeader,
+  ILeadersFilter,
+  IOperator,
+  IReputationNetwork,
+  IReward,
+} from './interfaces';
+import { GET_REWARD_ADDED_EVENTS_QUERY } from './graphql/queries/reward';
+import { RewardAddedEventData } from './graphql';
+import {
+  GET_LEADER_QUERY,
+  GET_LEADERS_QUERY,
+  GET_REPUTATION_NETWORK_QUERY,
+} from './graphql/queries/operator';
+import { ethers } from 'ethers';
+import {
+  ErrorInvalidSlasherAddressProvided,
+  ErrorInvalidStakerAddressProvided,
+  ErrorUnsupportedChainID,
+} from './error';
+import { throwError } from './utils';
+import { ChainId } from './enums';
+import { NETWORKS } from './constants';
+
+export class OperatorUtils {
+  /**
+   * 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 { OperatorUtils, ChainId } from '@human-protocol/sdk';
+   *
+   * const leader = await OperatorUtils.getLeader(ChainId.POLYGON_MUMBAI, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * ```
+   */
+  public static async getLeader(
+    chainId: ChainId,
+    address: string
+  ): Promise<ILeader> {
+    if (!ethers.isAddress(address)) {
+      throw ErrorInvalidStakerAddressProvided;
+    }
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    try {
+      const { leader } = await gqlFetch<{
+        leader: ILeader;
+      }>(networkData.subgraphUrl, GET_LEADER_QUERY, {
+        address: address.toLowerCase(),
+      });
+
+      return leader;
+    } catch (e) {
+      return throwError(e);
+    }
+  }
+
+  /**
+   * 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 { OperatorUtils } from '@human-protocol/sdk';
+   *
+   * const leaders = await OperatorUtils.getLeaders();
+   * ```
+   */
+  public static async getLeaders(
+    filter: ILeadersFilter = { networks: [ChainId.POLYGON_MUMBAI] }
+  ): Promise<ILeader[]> {
+    try {
+      let leaders_data: ILeader[] = [];
+      for (const chainId of filter.networks) {
+        const networkData = NETWORKS[chainId];
+
+        if (!networkData) {
+          throw ErrorUnsupportedChainID;
+        }
+        const { leaders } = await gqlFetch<{
+          leaders: ILeader[];
+        }>(networkData.subgraphUrl, GET_LEADERS_QUERY(filter), {
+          role: filter.role,
+        });
+        leaders_data = leaders_data.concat(leaders);
+      }
+
+      return leaders_data;
+    } catch (e) {
+      return throwError(e);
+    }
+  }
+
+  /**
+   * Retrieves the reputation network operators of the specified address.
+   *
+   * @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
+   * import { OperatorUtils, ChainId } from '@human-protocol/sdk';
+   *
+   * const operators = await OperatorUtils.getReputationNetworkOperators(ChainId.POLYGON_MUMBAI, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * ```
+   */
+  public static async getReputationNetworkOperators(
+    chainId: ChainId,
+    address: string,
+    role?: string
+  ): Promise<IOperator[]> {
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+    try {
+      const { reputationNetwork } = await gqlFetch<{
+        reputationNetwork: IReputationNetwork;
+      }>(networkData.subgraphUrl, GET_REPUTATION_NETWORK_QUERY(role), {
+        address: address,
+        role: role,
+      });
+
+      return reputationNetwork.operators;
+    } catch (e) {
+      return throwError(e);
+    }
+  }
+
+  /**
+   * 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 { OperatorUtils, ChainId } from '@human-protocol/sdk';
+   *
+   * const rewards = await OperatorUtils.getRewards(ChainId.POLYGON_MUMBAI, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * ```
+   */
+  public static async getRewards(
+    chainId: ChainId,
+    slasherAddress: string
+  ): Promise<IReward[]> {
+    if (!ethers.isAddress(slasherAddress)) {
+      throw ErrorInvalidSlasherAddressProvided;
+    }
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    try {
+      const { rewardAddedEvents } = await gqlFetch<{
+        rewardAddedEvents: RewardAddedEventData[];
+      }>(networkData.subgraphUrl, GET_REWARD_ADDED_EVENTS_QUERY, {
+        slasherAddress: slasherAddress.toLowerCase(),
+      });
+
+      return rewardAddedEvents.map((reward: any) => {
+        return {
+          escrowAddress: reward.escrow,
+          amount: reward.amount,
+        };
+      });
+    } catch (e) {
+      return throwError(e);
+    }
+  }
+}