@human-protocol/sdk 3.0.0 → 3.0.2

package/src/interfaces.ts

@@ -1,5 +1,5 @@
 import { EscrowStatus } from './types';
-import { ChainId } from './enums';
+import { ChainId, OrderDirection } from './enums';
 
 export interface IAllocation {
   escrowAddress: string;
@@ -26,7 +26,7 @@ export interface ILeader {
   amountSlashed: bigint;
   reputation: bigint;
   reward: bigint;
-  amountJobsLaunched: bigint;
+  amountJobsProcessed: bigint;
   role?: string;
   fee?: bigint;
   publicKey?: string;
@@ -66,7 +66,7 @@ export interface IOperatorSubgraph extends Omit<IOperator, 'jobTypes'> {
   jobTypes?: string;
 }
 
-export interface IEscrowsFilter {
+export interface IEscrowsFilter extends IPagination {
   launcher?: string;
   reputationOracle?: string;
   recordingOracle?: string;
@@ -75,7 +75,7 @@ export interface IEscrowsFilter {
   status?: EscrowStatus;
   from?: Date;
   to?: Date;
-  networks: ChainId[];
+  chainId: ChainId;
 }
 
 export interface IEscrowConfig {
@@ -96,10 +96,13 @@ export interface IKeyPair {
   revocationCertificate?: string;
 }
 
-export interface IStatisticsParams {
+export interface IStatisticsFilter extends IPagination {
   from?: Date;
   to?: Date;
-  limit?: number;
+}
+
+export interface IHMTHoldersParams extends IPagination {
+  address?: string;
 }
 
 export interface IPayoutFilter {
@@ -116,7 +119,7 @@ export interface IKVStore {
 
 export interface ITransaction {
   block: bigint;
-  hash: string;
+  txHash: string;
   from: string;
   to: string;
   timestamp: bigint;
@@ -124,8 +127,8 @@ export interface ITransaction {
   method: string;
 }
 
-export interface ITransactionsFilter {
-  networks: ChainId[];
+export interface ITransactionsFilter extends IPagination {
+  chainId: ChainId;
   startBlock?: number;
   endBlock?: number;
   startDate?: Date;
@@ -133,3 +136,9 @@ export interface ITransactionsFilter {
   fromAddress?: string;
   toAddress?: string;
 }
+
+export interface IPagination {
+  first?: number;
+  skip?: number;
+  orderDirection?: OrderDirection;
+}

package/src/kvstore.ts

@@ -19,7 +19,10 @@ import {
 import gqlFetch from 'graphql-request';
 import { NetworkData } from './types';
 import { getSubgraphUrl, isValidUrl } from './utils';
-import { GET_KVSTORE_BY_ADDRESS_QUERY } from './graphql/queries/kvstore';
+import {
+  GET_KVSTORE_BY_ADDRESS_AND_KEY_QUERY,
+  GET_KVSTORE_BY_ADDRESS_QUERY,
+} from './graphql/queries/kvstore';
 import { KVStoreData } from './graphql';
 import { IKVStore } from './interfaces';
 /**
@@ -277,71 +280,162 @@ export class KVStoreClient extends BaseEthersClient {
         throw Error(`Failed to set URL and hash: ${e.message}`);
     }
   }
+}
+
+/**
+ * ## Introduction
+ *
+ * Utility class for KVStore-related operations.
+ *
+ * ## Installation
+ *
+ * ### npm
+ * ```bash
+ * npm install @human-protocol/sdk
+ * ```
+ *
+ * ### yarn
+ * ```bash
+ * yarn install @human-protocol/sdk
+ * ```
+ *
+ * ## Code example
+ *
+ * ### Signer
+ *
+ * **Using private key (backend)**
+ *
+ * ```ts
+ * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
+ *
+ * const KVStoreAddresses = new KVStoreUtils.getKVStoreData({
+ *   ChainId.POLYGON_AMOY,
+ *   "0x1234567890123456789012345678901234567890",
+ * );
+ * ```
+ */
+export class KVStoreUtils {
+  /**
+   * This function returns the KVStore data for a given address.
+   *
+   * @param {ChainId} chainId Network in which the KVStore is deployed
+   * @param {string} address Address of the KVStore
+   * @returns {Promise<IKVStore[]>} KVStore data
+   * @throws {ErrorUnsupportedChainID} - Thrown if the network's chainId is not supported
+   * @throws {ErrorInvalidAddress} - Thrown if the Address sent is invalid
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
+   *
+   * const kvStoreData = await KVStoreUtils.getKVStoreData(ChainId.POLYGON_AMOY, "0x1234567890123456789012345678901234567890");
+   * console.log(kvStoreData);
+   * ```
+   */
+  public static async getKVStoreData(
+    chainId: ChainId,
+    address: string
+  ): Promise<IKVStore[]> {
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    if (address && !ethers.isAddress(address)) {
+      throw ErrorInvalidAddress;
+    }
+
+    const { kvstores } = await gqlFetch<{ kvstores: KVStoreData[] }>(
+      getSubgraphUrl(networkData),
+      GET_KVSTORE_BY_ADDRESS_QUERY(),
+      { address: address.toLowerCase() }
+    );
+
+    const kvStoreData = kvstores.map((item) => ({
+      key: item.key,
+      value: item.value,
+    }));
+
+    return kvStoreData || [];
+  }
 
   /**
-   * Gets the value of a key-value pair in the contract.
+   * Gets the value of a key-value pair in the KVStore using the subgraph.
    *
+   * @param {ChainId} chainId Network in which the KVStore is deployed
    * @param {string} address Address from which to get the key value.
    * @param {string} key Key to obtain the value.
-   * @returns {string} Value of the key.
-   *
+   * @returns {Promise<string>} Value of the key.
+   * @throws {ErrorUnsupportedChainID} - Thrown if the network's chainId is not supported
+   * @throws {ErrorInvalidAddress} - Thrown if the Address sent is invalid
+   * @throws {ErrorKVStoreEmptyKey} - Thrown if the key is empty
    *
    * **Code example**
    *
-   * > Need to have available stake.
-   *
    * ```ts
-   * import { providers } from 'ethers';
-   * import { KVStoreClient } from '@human-protocol/sdk';
-   *
-   * const rpcUrl = 'YOUR_RPC_URL';
+   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
    *
-   * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const kvstoreClient = await KVStoreClient.build(provider);
+   * const chainId = ChainId.POLYGON_AMOY;
+   * const address = '0x1234567890123456789012345678901234567890';
+   * const key = 'role';
    *
-   * const value = await kvstoreClient.get('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', 'Role');
+   * const value = await KVStoreUtils.get(chainId, address, key);
+   * console.log(value);
    * ```
    */
-  public async get(address: string, key: string): Promise<string> {
+  public static async get(
+    chainId: ChainId,
+    address: string,
+    key: string
+  ): Promise<string> {
     if (key === '') throw ErrorKVStoreEmptyKey;
     if (!ethers.isAddress(address)) throw ErrorInvalidAddress;
 
-    try {
-      const result = await this.contract?.get(address, key);
-      return result;
-    } catch (e) {
-      if (e instanceof Error) throw Error(`Failed to get value: ${e.message}`);
-      return e;
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    const { kvstores } = await gqlFetch<{ kvstores: KVStoreData[] }>(
+      getSubgraphUrl(networkData),
+      GET_KVSTORE_BY_ADDRESS_AND_KEY_QUERY(),
+      { address: address.toLowerCase(), key }
+    );
+
+    if (!kvstores || kvstores.length === 0) {
+      throw new Error(`Key "${key}" not found for address ${address}`);
     }
+
+    const value = kvstores[0].value;
+
+    return value;
   }
 
   /**
-   * Gets the URL value of the given entity, and verify its hash.
+   * Gets the URL value of the given entity, and verifies its hash.
    *
+   * @param {ChainId} chainId Network in which the KVStore is deployed
    * @param {string} address Address from which to get the URL value.
-   * @param {string} urlKey  Configurable URL key. `url` by default.
-   * @returns {string} URL value for the given address if exists, and the content is valid
-   *
+   * @param {string} urlKey Configurable URL key. `url` by default.
+   * @returns {Promise<string>} URL value for the given address if it exists, and the content is valid
    *
    * **Code example**
    *
    * ```ts
-   * import { providers } from 'ethers';
-   * import { KVStoreClient } from '@human-protocol/sdk';
+   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
    *
-   * const rpcUrl = 'YOUR_RPC_URL';
+   * const chainId = ChainId.POLYGON_AMOY;
+   * const address = '0x1234567890123456789012345678901234567890';
    *
-   * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const kvstoreClient = await KVStoreClient.build(provider);
-   *
-   * const url = await kvstoreClient.getFileUrlAndVerifyHash('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
-   * const linkedinUrl = await kvstoreClient.getFileUrlAndVerifyHash(
-   *    '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    'linkedin_url'
-   * );
+   * const url = await KVStoreUtils.getFileUrlAndVerifyHash(chainId, address);
+   * console.log(url);
    * ```
    */
-  public async getFileUrlAndVerifyHash(
+  public static async getFileUrlAndVerifyHash(
+    chainId: ChainId,
     address: string,
     urlKey = 'url'
   ): Promise<string> {
@@ -352,7 +446,7 @@ export class KVStoreClient extends BaseEthersClient {
       hash = '';
 
     try {
-      url = await this.contract?.get(address, urlKey);
+      url = await this.get(chainId, address, urlKey);
     } catch (e) {
       if (e instanceof Error) throw Error(`Failed to get URL: ${e.message}`);
     }
@@ -363,7 +457,7 @@ export class KVStoreClient extends BaseEthersClient {
     }
 
     try {
-      hash = await this.contract?.get(address, hashKey);
+      hash = await this.get(chainId, address, hashKey);
     } catch (e) {
       if (e instanceof Error) throw Error(`Failed to get Hash: ${e.message}`);
     }
@@ -379,28 +473,30 @@ export class KVStoreClient extends BaseEthersClient {
   }
 
   /**
-   * Gets the public key of the given entity, and verify its hash.
+   * Gets the public key of the given entity, and verifies its hash.
    *
+   * @param {ChainId} chainId Network in which the KVStore is deployed
    * @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
-   *
+   * @returns {Promise<string>} Public key for the given address if it exists, and the content is valid
    *
    * **Code example**
    *
    * ```ts
-   * import { providers } from 'ethers';
-   * import { KVStoreClient } from '@human-protocol/sdk';
-   *
-   * const rpcUrl = 'YOUR_RPC_URL';
+   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
    *
-   * const provider = new providers.JsonRpcProvider(rpcUrl);
-   * const kvstoreClient = await KVStoreClient.build(provider);
+   * const chainId = ChainId.POLYGON_AMOY;
+   * const address = '0x1234567890123456789012345678901234567890';
    *
-   * const publicKey = await kvstoreClient.getPublicKey('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
+   * const publicKey = await KVStoreUtils.getPublicKey(chainId, address);
+   * console.log(publicKey);
    * ```
    */
-  public async getPublicKey(address: string): Promise<string> {
+  public static async getPublicKey(
+    chainId: ChainId,
+    address: string
+  ): Promise<string> {
     const publicKeyUrl = await this.getFileUrlAndVerifyHash(
+      chainId,
       address,
       KVStoreKeys.publicKey
     );
@@ -414,112 +510,3 @@ export class KVStoreClient extends BaseEthersClient {
     return publicKey;
   }
 }
-
-/**
- * ## Introduction
- *
- * Utility class for KVStore-related operations.
- *
- * ## Installation
- *
- * ### npm
- * ```bash
- * npm install @human-protocol/sdk
- * ```
- *
- * ### yarn
- * ```bash
- * yarn install @human-protocol/sdk
- * ```
- *
- * ## Code example
- *
- * ### Signer
- *
- * **Using private key (backend)**
- *
- * ```ts
- * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
- *
- * const KVStoreAddresses = new KVStoreUtils.getData({
- *   networks: [ChainId.POLYGON_AMOY]
- * });
- * ```
- */
-export class KVStoreUtils {
-  /**
-   * This function returns the KVStore data for a given address.
-   *
-   * > This uses Subgraph
-   *
-   * **Input parameters**
-   *
-   * ```ts
-   * enum ChainId {
-   *   ALL = -1,
-   *   MAINNET = 1,
-   *   RINKEBY = 4,
-   *   GOERLI = 5,
-   *   BSC_MAINNET = 56,
-   *   BSC_TESTNET = 97,
-   *   POLYGON = 137,
-   *   POLYGON_MUMBAI = 80001,
-   *   POLYGON_AMOY = 80002,
-   *   MOONBEAM = 1284,
-   *   MOONBASE_ALPHA = 1287,
-   *   AVALANCHE = 43114,
-   *   AVALANCHE_TESTNET = 43113,
-   *   CELO = 42220,
-   *   CELO_ALFAJORES = 44787,
-   *   LOCALHOST = 1338,
-   * }
-   * ```
-   *
-   * ```ts
-   * interface IKVStore {
-   *   key: string;
-   *   value: string;
-   * }
-   * ```
-   *
-   * @param {ChainId} chainId Network in which the KVStore is deployed
-   * @param {string} address Address of the KVStore
-   * @returns {Promise<IKVStore[]>} KVStore data
-   *
-   * **Code example**
-   *
-   * ```ts
-   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
-   *
-   * const kvStoreData = await KVStoreUtils.getKVStoreData(ChainId.POLYGON_AMOY, "0x1234567890123456789012345678901234567890");
-   * console.log(kvStoreData);
-   * ```
-   */
-  public static async getKVStoreData(
-    chainId: ChainId,
-    address: string
-  ): Promise<IKVStore[]> {
-    const networkData = NETWORKS[chainId];
-
-    if (!networkData) {
-      throw ErrorUnsupportedChainID;
-    }
-
-    if (address && !ethers.isAddress(address)) {
-      throw ErrorInvalidAddress;
-    }
-
-    const { kvstores } = await gqlFetch<{ kvstores: KVStoreData[] }>(
-      getSubgraphUrl(networkData),
-      GET_KVSTORE_BY_ADDRESS_QUERY(),
-      { address: address.toLowerCase() }
-    );
-
-    const kvStoreData = kvstores.map((item) => ({
-      key: item.key,
-      value: item.value,
-    }));
-
-    return kvStoreData || [];
-  }
-}

package/src/operator.ts

@@ -21,7 +21,7 @@ import {
   ErrorInvalidStakerAddressProvided,
   ErrorUnsupportedChainID,
 } from './error';
-import { getSubgraphUrl, throwError } from './utils';
+import { getSubgraphUrl } from './utils';
 import { ChainId } from './enums';
 import { NETWORKS } from './constants';
 
@@ -54,28 +54,28 @@ export class OperatorUtils {
       throw ErrorUnsupportedChainID;
     }
 
-    try {
-      const { leader } = await gqlFetch<{
-        leader: ILeaderSubgraph;
-      }>(getSubgraphUrl(networkData), GET_LEADER_QUERY, {
-        address: address.toLowerCase(),
-      });
+    const { leader } = await gqlFetch<{
+      leader: ILeaderSubgraph;
+    }>(getSubgraphUrl(networkData), GET_LEADER_QUERY, {
+      address: address.toLowerCase(),
+    });
 
-      let jobTypes: string[] = [];
+    if (!leader) {
+      return (leader as ILeader) || null;
+    }
 
-      if (typeof leader.jobTypes === 'string') {
-        jobTypes = leader.jobTypes.split(',');
-      } else if (Array.isArray(leader.jobTypes)) {
-        jobTypes = leader.jobTypes;
-      }
+    let jobTypes: string[] = [];
 
-      return {
-        ...leader,
-        jobTypes,
-      };
-    } catch (e) {
-      return throwError(e);
+    if (typeof leader.jobTypes === 'string') {
+      jobTypes = leader.jobTypes.split(',');
+    } else if (Array.isArray(leader.jobTypes)) {
+      jobTypes = leader.jobTypes;
     }
+
+    return {
+      ...leader,
+      jobTypes,
+    };
   }
 
   /**
@@ -97,45 +97,41 @@ export class OperatorUtils {
    * ```
    */
   public static async getLeaders(filter: ILeadersFilter): Promise<ILeader[]> {
-    try {
-      let leaders_data: ILeader[] = [];
+    let leaders_data: ILeader[] = [];
 
-      const networkData = NETWORKS[filter.chainId];
+    const networkData = NETWORKS[filter.chainId];
 
-      if (!networkData) {
-        throw ErrorUnsupportedChainID;
-      }
-
-      const { leaders } = await gqlFetch<{
-        leaders: ILeaderSubgraph[];
-      }>(getSubgraphUrl(networkData), GET_LEADERS_QUERY(filter), {
-        role: filter?.role,
-      });
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
 
-      if (!leaders) {
-        return [];
-      }
+    const { leaders } = await gqlFetch<{
+      leaders: ILeaderSubgraph[];
+    }>(getSubgraphUrl(networkData), GET_LEADERS_QUERY(filter), {
+      role: filter?.role,
+    });
 
-      leaders_data = leaders_data.concat(
-        leaders.map((leader) => {
-          let jobTypes: string[] = [];
-
-          if (typeof leader.jobTypes === 'string') {
-            jobTypes = leader.jobTypes.split(',');
-          } else if (Array.isArray(leader.jobTypes)) {
-            jobTypes = leader.jobTypes;
-          }
-
-          return {
-            ...leader,
-            jobTypes,
-          };
-        })
-      );
-      return leaders_data;
-    } catch (e) {
-      return throwError(e);
+    if (!leaders) {
+      return [];
     }
+
+    leaders_data = leaders_data.concat(
+      leaders.map((leader) => {
+        let jobTypes: string[] = [];
+
+        if (typeof leader.jobTypes === 'string') {
+          jobTypes = leader.jobTypes.split(',');
+        } else if (Array.isArray(leader.jobTypes)) {
+          jobTypes = leader.jobTypes;
+        }
+
+        return {
+          ...leader,
+          jobTypes,
+        };
+      })
+    );
+    return leaders_data;
   }
 
   /**
@@ -162,31 +158,27 @@ export class OperatorUtils {
     if (!networkData) {
       throw ErrorUnsupportedChainID;
     }
-    try {
-      const { reputationNetwork } = await gqlFetch<{
-        reputationNetwork: IReputationNetworkSubgraph;
-      }>(getSubgraphUrl(networkData), GET_REPUTATION_NETWORK_QUERY(role), {
-        address: address.toLowerCase(),
-        role: role,
-      });
-
-      return reputationNetwork.operators.map((operator) => {
-        let jobTypes: string[] = [];
+    const { reputationNetwork } = await gqlFetch<{
+      reputationNetwork: IReputationNetworkSubgraph;
+    }>(getSubgraphUrl(networkData), GET_REPUTATION_NETWORK_QUERY(role), {
+      address: address.toLowerCase(),
+      role: role,
+    });
+
+    return reputationNetwork.operators.map((operator) => {
+      let jobTypes: string[] = [];
 
-        if (typeof operator.jobTypes === 'string') {
-          jobTypes = operator.jobTypes.split(',');
-        } else if (Array.isArray(operator.jobTypes)) {
-          jobTypes = operator.jobTypes;
-        }
+      if (typeof operator.jobTypes === 'string') {
+        jobTypes = operator.jobTypes.split(',');
+      } else if (Array.isArray(operator.jobTypes)) {
+        jobTypes = operator.jobTypes;
+      }
 
-        return {
-          ...operator,
-          jobTypes,
-        };
-      });
-    } catch (e) {
-      return throwError(e);
-    }
+      return {
+        ...operator,
+        jobTypes,
+      };
+    });
   }
 
   /**
@@ -217,21 +209,17 @@ export class OperatorUtils {
       throw ErrorUnsupportedChainID;
     }
 
-    try {
-      const { rewardAddedEvents } = await gqlFetch<{
-        rewardAddedEvents: RewardAddedEventData[];
-      }>(getSubgraphUrl(networkData), GET_REWARD_ADDED_EVENTS_QUERY, {
-        slasherAddress: slasherAddress.toLowerCase(),
-      });
+    const { rewardAddedEvents } = await gqlFetch<{
+      rewardAddedEvents: RewardAddedEventData[];
+    }>(getSubgraphUrl(networkData), 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);
-    }
+    return rewardAddedEvents.map((reward: any) => {
+      return {
+        escrowAddress: reward.escrow,
+        amount: reward.amount,
+      };
+    });
   }
 }