@human-protocol/sdk 1.1.19 → 2.1.0

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,12 +1,10 @@
-import { Provider } from '@ethersproject/abstract-provider';
-import { Network } from '@ethersproject/networks';
 import {
   KVStore,
   KVStore__factory,
 } from '@human-protocol/core/typechain-types';
-import { Overrides, Signer, ethers } from 'ethers';
+import { ContractRunner, Overrides, ethers } from 'ethers';
 import { BaseEthersClient } from './base';
-import { NETWORKS } from './constants';
+import { KVStoreKeys, NETWORKS } from './constants';
 import { requiresSigner } from './decorators';
 import { ChainId } from './enums';
 import {
@@ -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,47 +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
    */
-  constructor(signerOrProvider: Signer | Provider, networkData: NetworkData) {
-    super(signerOrProvider, networkData);
+  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 {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) {
-    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);
+    return new KVStoreClient(runner, networkData);
   }
 
   /**
@@ -173,7 +165,6 @@ export class KVStoreClient extends BaseEthersClient {
     value: string,
     txOptions: Overrides = {}
   ): Promise<void> {
-    if (!Signer.isSigner(this.signerOrProvider)) throw ErrorSigner;
     if (key === '') throw ErrorKVStoreEmptyKey;
     try {
       await (await this.contract.set(key, value, txOptions)).wait();
@@ -206,7 +197,7 @@ export class KVStoreClient extends BaseEthersClient {
    * const signer = new Wallet(privateKey, provider);
    * const kvstoreClient = await KVStoreClient.build(signer);
    *
-   * const keys = ['role', 'webhookUrl'];
+   * const keys = ['role', 'webhook_url'];
    * const values = ['RecordingOracle', 'http://localhost'];
    * await kvstoreClient.set(keys, values);
    * ```
@@ -217,7 +208,6 @@ export class KVStoreClient extends BaseEthersClient {
     values: string[],
     txOptions: Overrides = {}
   ): Promise<void> {
-    if (!Signer.isSigner(this.signerOrProvider)) throw ErrorSigner;
     if (keys.length !== values.length) throw ErrorKVStoreArrayLength;
     if (keys.includes('')) throw ErrorKVStoreEmptyKey;
 
@@ -230,7 +220,7 @@ export class KVStoreClient extends BaseEthersClient {
   }
 
   /**
-   * This function sets a URL value for the address that submits the transaction.
+   * Sets a URL value for the address that submits the transaction, and its hash.
    *
    * @param {string} url URL to set
    * @param {string | undefined} urlKey Configurable URL key. `url` by default.
@@ -251,30 +241,24 @@ export class KVStoreClient extends BaseEthersClient {
    * const signer = new Wallet(privateKey, provider);
    * const kvstoreClient = await KVStoreClient.build(signer);
    *
-   * await kvstoreClient.setURL('example.com');
-   * await kvstoreClient.setURL('linkedin.com/example', 'linkedinUrl);
+   * await kvstoreClient.setFileUrlAndHash('example.com');
+   * await kvstoreClient.setFileUrlAndHash('linkedin.com/example', 'linkedin_url);
    * ```
    */
   @requiresSigner
-  public async setURL(
+  public async setFileUrlAndHash(
     url: string,
     urlKey = 'url',
     txOptions: Overrides = {}
   ): Promise<void> {
-    if (!Signer.isSigner(this.signerOrProvider)) {
-      throw ErrorSigner;
-    }
-
     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';
+    const hashKey = urlKey + '_hash';
 
     try {
       await (
@@ -291,7 +275,7 @@ export class KVStoreClient extends BaseEthersClient {
   }
 
   /**
-   * This function returns the value for a specified key and address.
+   * Gets the value of a key-value pair in the contract.
    *
    * @param {string} address Address from which to get the key value.
    * @param {string} key Key to obtain the value.
@@ -316,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);
@@ -328,7 +312,7 @@ export class KVStoreClient extends BaseEthersClient {
   }
 
   /**
-   * This function returns the URL value for the given entity.
+   * Gets the URL value of the given entity, and verify its hash.
    *
    * @param {string} address Address from which to get the URL value.
    * @param {string} urlKey  Configurable URL key. `url` by default.
@@ -346,16 +330,19 @@ export class KVStoreClient extends BaseEthersClient {
    * const provider = new providers.JsonRpcProvider(rpcUrl);
    * const kvstoreClient = await KVStoreClient.build(provider);
    *
-   * const url = await kvstoreClient.getURL('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
-   * const linkedinUrl = await kvstoreClient.getURL(
+   * const url = await kvstoreClient.getFileUrlAndVerifyHash('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
+   * const linkedinUrl = await kvstoreClient.getFileUrlAndVerifyHash(
    *    '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    'linkedinUrl'
+   *    'linkedin_url'
    * );
    * ```
    */
-  public async getURL(address: string, urlKey = 'url'): Promise<string> {
-    if (!ethers.utils.isAddress(address)) throw ErrorInvalidAddress;
-    const hashKey = urlKey + 'Hash';
+  public async getFileUrlAndVerifyHash(
+    address: string,
+    urlKey = 'url'
+  ): Promise<string> {
+    if (!ethers.isAddress(address)) throw ErrorInvalidAddress;
+    const hashKey = urlKey + '_hash';
 
     let url = '',
       hash = '';
@@ -378,9 +365,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;
@@ -388,4 +373,40 @@ export class KVStoreClient extends BaseEthersClient {
 
     return url;
   }
+
+  /**
+   * Gets the public key of the given entity, and verify its hash.
+   *
+   * @param {string} address Address from which to get the public key.
+   * @returns {string} Public key for the given address if exists, and the content is valid
+   *
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { providers } from 'ethers';
+   * import { KVStoreClient } from '@human-protocol/sdk';
+   *
+   * const rpcUrl = 'YOUR_RPC_URL';
+   *
+   * const provider = new providers.JsonRpcProvider(rpcUrl);
+   * const kvstoreClient = await KVStoreClient.build(provider);
+   *
+   * const publicKey = await kvstoreClient.getPublicKey('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
+   * ```
+   */
+  public async getPublicKey(address: string): Promise<string> {
+    const publicKeyUrl = await this.getFileUrlAndVerifyHash(
+      address,
+      KVStoreKeys.publicKey
+    );
+
+    if (publicKeyUrl === '') {
+      return '';
+    }
+
+    const publicKey = await fetch(publicKeyUrl).then((res) => res.text());
+
+    return publicKey;
+  }
 }

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);
+    }
+  }
+}