@human-protocol/sdk 5.2.0 → 6.1.0

package/src/graphql/queries/operator.ts

@@ -15,7 +15,9 @@ const LEADER_FRAGMENT = gql`
     jobTypes
     registrationNeeded
     registrationInstructions
-    reputationNetworks
+    reputationNetworks {
+      address
+    }
     name
     category
     staker {

package/src/graphql/types.ts

@@ -166,8 +166,10 @@ export interface IOperatorSubgraph {
   } | null;
 }
 
-export interface IReputationNetworkSubgraph
-  extends Omit<IReputationNetwork, 'operators'> {
+export interface IReputationNetworkSubgraph extends Omit<
+  IReputationNetwork,
+  'operators'
+> {
   operators: IOperatorSubgraph[];
 }
 

package/src/index.ts

@@ -1,9 +1,8 @@
 import { StakingClient, StakingUtils } from './staking';
-import { StorageClient } from './storage';
 import { KVStoreClient, KVStoreUtils } from './kvstore';
 import { EscrowClient, EscrowUtils } from './escrow';
-import { StatisticsClient } from './statistics';
-import { Encryption, EncryptionUtils } from './encryption';
+import { StatisticsUtils } from './statistics';
+import { Encryption, EncryptionUtils, MessageDataType } from './encryption';
 import { OperatorUtils } from './operator';
 import { TransactionUtils } from './transaction';
 import { WorkerUtils } from './worker';
@@ -27,16 +26,16 @@ export {
 
 export {
   StakingClient,
-  StorageClient,
   KVStoreClient,
   KVStoreUtils,
   EscrowClient,
   EscrowUtils,
-  StatisticsClient,
+  StatisticsUtils,
   Encryption,
   EncryptionUtils,
   OperatorUtils,
   TransactionUtils,
   WorkerUtils,
   StakingUtils,
+  MessageDataType,
 };

package/src/interfaces.ts

@@ -149,8 +149,8 @@ export interface ITransaction {
 
 export interface ITransactionsFilter extends IPagination {
   chainId: ChainId;
-  startBlock?: number;
-  endBlock?: number;
+  startBlock?: number | bigint;
+  endBlock?: number | bigint;
   startDate?: Date;
   endDate?: Date;
   fromAddress?: string;

package/src/kvstore.ts

@@ -2,7 +2,7 @@ import {
   KVStore,
   KVStore__factory,
 } from '@human-protocol/core/typechain-types';
-import { ContractRunner, Overrides, ethers } from 'ethers';
+import { ContractRunner, ethers } from 'ethers';
 import { BaseEthersClient } from './base';
 import { KVStoreKeys, NETWORKS } from './constants';
 import { requiresSigner } from './decorators';
@@ -17,7 +17,7 @@ import {
   ErrorUnsupportedChainID,
   InvalidKeyError,
 } from './error';
-import { NetworkData } from './types';
+import { NetworkData, TransactionOverrides } from './types';
 import { getSubgraphUrl, customGqlFetch, isValidUrl } from './utils';
 import {
   GET_KVSTORE_BY_ADDRESS_AND_KEY_QUERY,
@@ -26,12 +26,10 @@ import {
 import { KVStoreData } from './graphql';
 import { IKVStore, SubgraphOptions } from './interfaces';
 /**
- * ## Introduction
- *
- * This client enables performing actions on KVStore contract and obtaining information from both the contracts and subgraph.
+ * Client for interacting with the KVStore contract.
  *
  * 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.
+ * To use this client, it is recommended to initialize it using the static [`build`](/ts/classes/KVStoreClient/#build) method.
  *
  * ```ts
  * static async build(runner: ContractRunner): Promise<KVStoreClient>;
@@ -42,37 +40,25 @@ import { IKVStore, SubgraphOptions } from './interfaces';
  * - **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
- *
- * ### npm
- * ```bash
- * npm install @human-protocol/sdk
- * ```
- *
- * ### yarn
- * ```bash
- * yarn install @human-protocol/sdk
- * ```
- *
- * ## Code example
+ * @example
  *
- * ### Signer
+ * ###Using Signer
  *
- * **Using private key (backend)**
+ * ####Using private key (backend)
  *
  * ```ts
  * import { KVStoreClient } from '@human-protocol/sdk';
- * import { Wallet, providers } from 'ethers';
+ * import { Wallet, JsonRpcProvider } from 'ethers';
  *
  * const rpcUrl = 'YOUR_RPC_URL';
  * const privateKey = 'YOUR_PRIVATE_KEY';
  *
- * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const provider = new 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';
@@ -82,27 +68,27 @@ import { IKVStore, SubgraphOptions } from './interfaces';
  * const kvstoreClient = await KVStoreClient.build(signer);
  * ```
  *
- * ### Provider
+ * ###Using Provider
  *
  * ```ts
  * import { KVStoreClient } from '@human-protocol/sdk';
- * import { providers } from 'ethers';
+ * import { JsonRpcProvider } from 'ethers';
  *
  * const rpcUrl = 'YOUR_RPC_URL';
  *
- * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const provider = new JsonRpcProvider(rpcUrl);
  * const kvstoreClient = await KVStoreClient.build(provider);
  * ```
  */
 
 export class KVStoreClient extends BaseEthersClient {
-  private contract: KVStore;
+  public contract: KVStore;
 
   /**
    * **KVStoreClient constructor**
    *
-   * @param {ContractRunner} runner - The Runner object to interact with the Ethereum network
-   * @param {NetworkData} networkData - The network information required to connect to the KVStore contract
+   * @param runner - The Runner object to interact with the Ethereum network
+   * @param networkData - The network information required to connect to the KVStore contract
    */
   constructor(runner: ContractRunner, networkData: NetworkData) {
     super(runner, networkData);
@@ -116,11 +102,23 @@ export class KVStoreClient extends BaseEthersClient {
   /**
    * Creates an instance of KVStoreClient from a runner.
    *
-   * @param {ContractRunner} runner - The Runner object to interact with the Ethereum network
+   * @param runner - The Runner object to interact with the Ethereum network
+   * @returns An instance of KVStoreClient
+   * @throws ErrorProviderDoesNotExist If the provider does not exist for the provided Signer
+   * @throws ErrorUnsupportedChainID If the network's chainId is not supported
    *
-   * @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
+   * @example
+   * ```ts
+   * import { KVStoreClient } from '@human-protocol/sdk';
+   * import { Wallet, JsonRpcProvider } from 'ethers';
+   *
+   * const rpcUrl = 'YOUR_RPC_URL';
+   * const privateKey = 'YOUR_PRIVATE_KEY';
+   *
+   * const provider = new JsonRpcProvider(rpcUrl);
+   * const signer = new Wallet(privateKey, provider);
+   * const kvstoreClient = await KVStoreClient.build(signer);
+   * ```
    */
   public static async build(runner: ContractRunner): Promise<KVStoreClient> {
     if (!runner.provider) {
@@ -142,27 +140,15 @@ export class KVStoreClient extends BaseEthersClient {
   /**
    * This function sets a key-value pair associated with the address that submits the transaction.
    *
-   * @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.
-   *
-   *
-   * **Code example**
-   *
-   * > Need to have available stake.
+   * @param key - Key of the key-value pair
+   * @param value - Value of the key-value pair
+   * @param txOptions - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns -
+   * @throws ErrorKVStoreEmptyKey If the key is empty
+   * @throws Error If the transaction fails
    *
+   * @example
    * ```ts
-   * import { Wallet, providers } from 'ethers';
-   * import { KVStoreClient } 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 kvstoreClient = await KVStoreClient.build(signer);
-   *
    * await kvstoreClient.set('Role', 'RecordingOracle');
    * ```
    */
@@ -170,11 +156,14 @@ export class KVStoreClient extends BaseEthersClient {
   public async set(
     key: string,
     value: string,
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (key === '') throw ErrorKVStoreEmptyKey;
     try {
-      await (await this.contract.set(key, value, txOptions)).wait();
+      await this.sendTxAndWait(
+        (overrides) => this.contract.set(key, value, overrides),
+        txOptions
+      );
     } catch (e) {
       if (e instanceof Error) throw Error(`Failed to set value: ${e.message}`);
     }
@@ -183,27 +172,16 @@ export class KVStoreClient extends BaseEthersClient {
   /**
    * This function sets key-value pairs in bulk associated with the address that submits the transaction.
    *
-   * @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.
-   *
-   *
-   * **Code example**
-   *
-   * > Need to have available stake.
+   * @param keys - Array of keys (keys and value must have the same order)
+   * @param values - Array of values
+   * @param txOptions - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns -
+   * @throws ErrorKVStoreArrayLength If keys and values arrays have different lengths
+   * @throws ErrorKVStoreEmptyKey If any key is empty
+   * @throws Error If the transaction fails
    *
+   * @example
    * ```ts
-   * import { Wallet, providers } from 'ethers';
-   * import { KVStoreClient } 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 kvstoreClient = await KVStoreClient.build(signer);
-   *
    * const keys = ['role', 'webhook_url'];
    * const values = ['RecordingOracle', 'http://localhost'];
    * await kvstoreClient.setBulk(keys, values);
@@ -213,13 +191,16 @@ export class KVStoreClient extends BaseEthersClient {
   public async setBulk(
     keys: string[],
     values: string[],
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (keys.length !== values.length) throw ErrorKVStoreArrayLength;
     if (keys.includes('')) throw ErrorKVStoreEmptyKey;
 
     try {
-      await (await this.contract.setBulk(keys, values, txOptions)).wait();
+      await this.sendTxAndWait(
+        (overrides) => this.contract.setBulk(keys, values, overrides),
+        txOptions
+      );
     } catch (e) {
       if (e instanceof Error)
         throw Error(`Failed to set bulk values: ${e.message}`);
@@ -229,25 +210,15 @@ export class KVStoreClient extends BaseEthersClient {
   /**
    * 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.
-   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns Returns void if successful. Throws error if any.
-   *
-   *
-   * **Code example**
+   * @param url - URL to set
+   * @param urlKey - Configurable URL key. `url` by default.
+   * @param txOptions - Additional transaction parameters (optional, defaults to an empty object).
+   * @returns -
+   * @throws ErrorInvalidUrl If the URL is invalid
+   * @throws Error If the transaction fails
    *
+   * @example
    * ```ts
-   * import { Wallet, providers } from 'ethers';
-   * import { KVStoreClient } 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 kvstoreClient = await KVStoreClient.build(signer);
-   *
    * await kvstoreClient.setFileUrlAndHash('example.com');
    * await kvstoreClient.setFileUrlAndHash('linkedin.com/example', 'linkedin_url');
    * ```
@@ -256,7 +227,7 @@ export class KVStoreClient extends BaseEthersClient {
   public async setFileUrlAndHash(
     url: string,
     urlKey = 'url',
-    txOptions: Overrides = {}
+    txOptions: TransactionOverrides = {}
   ): Promise<void> {
     if (!isValidUrl(url)) {
       throw ErrorInvalidUrl;
@@ -268,13 +239,15 @@ export class KVStoreClient extends BaseEthersClient {
     const hashKey = urlKey + '_hash';
 
     try {
-      await (
-        await this.contract.setBulk(
-          [urlKey, hashKey],
-          [url, contentHash],
-          txOptions
-        )
-      ).wait();
+      await this.sendTxAndWait(
+        (overrides) =>
+          this.contract.setBulk(
+            [urlKey, hashKey],
+            [url, contentHash],
+            overrides
+          ),
+        txOptions
+      );
     } catch (e) {
       if (e instanceof Error)
         throw Error(`Failed to set URL and hash: ${e.message}`);
@@ -283,26 +256,17 @@ export class KVStoreClient extends BaseEthersClient {
   /**
    * 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.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {string} Value of the key.
-   *
-   *
-   * **Code example**
-   *
-   * > Need to have available stake.
+   * @param address - Address from which to get the key value.
+   * @param key - Key to obtain the value.
+   * @returns Value of the key.
+   * @throws ErrorKVStoreEmptyKey If the key is empty
+   * @throws ErrorInvalidAddress If the address is invalid
+   * @throws Error If the contract call fails
    *
+   * @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 value = await kvstoreClient.get('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', 'Role');
+   * console.log('Value:', value);
    * ```
    */
   public async get(address: string, key: string): Promise<string> {
@@ -320,55 +284,37 @@ export class KVStoreClient extends BaseEthersClient {
 }
 
 /**
- * ## 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)**
+ * Utility helpers for KVStore-related queries.
  *
+ * @example
  * ```ts
  * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
  *
- * const KVStoreAddresses = await KVStoreUtils.getKVStoreData(
+ * const kvStoreData = await KVStoreUtils.getKVStoreData(
  *   ChainId.POLYGON_AMOY,
  *   "0x1234567890123456789012345678901234567890"
  * );
+ * console.log('KVStore data:', kvStoreData);
  * ```
  */
 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
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @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**
+   * @param chainId - Network in which the KVStore is deployed
+   * @param address - Address of the KVStore
+   * @param options - Optional configuration for subgraph requests.
+   * @returns KVStore data
+   * @throws ErrorUnsupportedChainID If the network's chainId is not supported
+   * @throws ErrorInvalidAddress If the address is invalid
    *
+   * @example
    * ```ts
-   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
-   *
-   * const kvStoreData = await KVStoreUtils.getKVStoreData(ChainId.POLYGON_AMOY, "0x1234567890123456789012345678901234567890");
-   * console.log(kvStoreData);
+   * const kvStoreData = await KVStoreUtils.getKVStoreData(
+   *   ChainId.POLYGON_AMOY,
+   *   "0x1234567890123456789012345678901234567890"
+   * );
+   * console.log('KVStore data:', kvStoreData);
    * ```
    */
   public static async getKVStoreData(
@@ -404,26 +350,24 @@ export class KVStoreUtils {
   /**
    * 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.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @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**
-   *
+   * @param chainId - Network in which the KVStore is deployed
+   * @param address - Address from which to get the key value.
+   * @param key - Key to obtain the value.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Value of the key.
+   * @throws ErrorUnsupportedChainID If the network's chainId is not supported
+   * @throws ErrorInvalidAddress If the address is invalid
+   * @throws ErrorKVStoreEmptyKey If the key is empty
+   * @throws InvalidKeyError If the key is not found
+   *
+   * @example
    * ```ts
-   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
-   *
-   * const chainId = ChainId.POLYGON_AMOY;
-   * const address = '0x1234567890123456789012345678901234567890';
-   * const key = 'role';
-   *
-   * const value = await KVStoreUtils.get(chainId, address, key);
-   * console.log(value);
+   * const value = await KVStoreUtils.get(
+   *   ChainId.POLYGON_AMOY,
+   *   '0x1234567890123456789012345678901234567890',
+   *   'role'
+   * );
+   * console.log('Value:', value);
    * ```
    */
   public static async get(
@@ -458,22 +402,22 @@ export class KVStoreUtils {
   /**
    * 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.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<string>} URL value for the given address if it exists, and the content is valid
-   *
-   * **Code example**
+   * @param chainId - Network in which the KVStore is deployed
+   * @param address - Address from which to get the URL value.
+   * @param urlKey - Configurable URL key. `url` by default.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns URL value for the given address if it exists, and the content is valid
+   * @throws ErrorInvalidAddress If the address is invalid
+   * @throws ErrorInvalidHash If the hash verification fails
+   * @throws Error If fetching URL or hash fails
    *
+   * @example
    * ```ts
-   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
-   *
-   * const chainId = ChainId.POLYGON_AMOY;
-   * const address = '0x1234567890123456789012345678901234567890';
-   *
-   * const url = await KVStoreUtils.getFileUrlAndVerifyHash(chainId, address);
-   * console.log(url);
+   * const url = await KVStoreUtils.getFileUrlAndVerifyHash(
+   *   ChainId.POLYGON_AMOY,
+   *   '0x1234567890123456789012345678901234567890'
+   * );
+   * console.log('Verified URL:', url);
    * ```
    */
   public static async getFileUrlAndVerifyHash(
@@ -521,20 +465,21 @@ export class KVStoreUtils {
   /**
    * 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 {Promise<string>} Public key for the given address if it exists, and the content is valid
-   *
-   * **Code example**
+   * @param chainId - Network in which the KVStore is deployed
+   * @param address - Address from which to get the public key.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Public key for the given address if it exists, and the content is valid
+   * @throws ErrorInvalidAddress If the address is invalid
+   * @throws ErrorInvalidHash If the hash verification fails
+   * @throws Error If fetching the public key fails
    *
+   * @example
    * ```ts
-   * import { ChainId, KVStoreUtils } from '@human-protocol/sdk';
-   *
-   * const chainId = ChainId.POLYGON_AMOY;
-   * const address = '0x1234567890123456789012345678901234567890';
-   *
-   * const publicKey = await KVStoreUtils.getPublicKey(chainId, address);
-   * console.log(publicKey);
+   * const publicKey = await KVStoreUtils.getPublicKey(
+   *   ChainId.POLYGON_AMOY,
+   *   '0x1234567890123456789012345678901234567890'
+   * );
+   * console.log('Public key:', publicKey);
    * ```
    */
   public static async getPublicKey(