@human-protocol/sdk 1.1.5 → 1.1.7

package/src/escrow.ts

@@ -1,20 +1,26 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { Provider } from '@ethersproject/abstract-provider';
+import { Network } from '@ethersproject/networks';
 import {
-  HMToken__factory,
-  HMToken,
   Escrow,
   EscrowFactory,
   EscrowFactory__factory,
   Escrow__factory,
+  HMToken,
+  HMToken__factory,
 } from '@human-protocol/core/typechain-types';
 import { BigNumber, ContractReceipt, Signer, ethers } from 'ethers';
-import { Provider } from '@ethersproject/abstract-provider';
+import { DEFAULT_TX_ID, NETWORKS } from './constants';
+import { requiresSigner } from './decorators';
+import { ChainId } from './enums';
 import {
   ErrorAmountMustBeGreaterThanZero,
   ErrorAmountsCannotBeEmptyArray,
   ErrorEscrowAddressIsNotProvidedByFactory,
   ErrorEscrowDoesNotHaveEnoughBalance,
   ErrorHashIsEmptyString,
+  ErrorProviderDoesNotExist,
+  ErrorUnsupportedChainID,
   ErrorInvalidAddress,
   ErrorInvalidEscrowAddressProvided,
   ErrorInvalidRecordingOracleAddressProvided,
@@ -29,40 +35,63 @@ import {
   ErrorUrlIsEmptyString,
   InvalidEthereumAddressError,
 } from './error';
-import {
-  IClientParams,
-  IEscrowConfig,
-  IEscrowsFilter,
-  ILauncherEscrowsResult,
-} from './interfaces';
-import { gqlFetch, isValidUrl, throwError } from './utils';
-import { DEFAULT_TX_ID } from './constants';
+import { IEscrowConfig, IEscrowsFilter } from './interfaces';
 import {
   RAW_LAUNCHED_ESCROWS_FILTERED_QUERY,
   RAW_LAUNCHED_ESCROWS_QUERY,
 } from './queries';
 import { EscrowStatus, NetworkData } from './types';
-import { requiresSigner } from './decorators';
+import { gqlFetch, isValidUrl, throwError } from './utils';
 
-export default class EscrowClient {
+export class EscrowClient {
   private escrowFactoryContract: EscrowFactory;
   private escrowContract?: Escrow;
   private signerOrProvider: Signer | Provider;
   public network: NetworkData;
 
   /**
-   * **Escrow constructor**
+   * **EscrowClient constructor**
    *
-   *   * @param {IClientParams} clientParams - Init client parameters
+   * @param {Signer | Provider} signerOrProvider - The Signer or Provider object to interact with the Ethereum network
+   * @param {NetworkData} network - The network information required to connect to the Escrow contract
    */
-  constructor(readonly clientParams: IClientParams) {
-    this.network = clientParams.network;
-
+  constructor(signerOrProvider: Signer | Provider, network: NetworkData) {
     this.escrowFactoryContract = EscrowFactory__factory.connect(
-      clientParams.network.factoryAddress,
-      clientParams.signerOrProvider
+      network.factoryAddress,
+      signerOrProvider
     );
-    this.signerOrProvider = clientParams.signerOrProvider;
+    this.network = network;
+    this.signerOrProvider = signerOrProvider;
+  }
+
+  /**
+   * Creates an instance of EscrowClient from a Signer or Provider.
+   *
+   * @param {Signer | Provider} signerOrProvider - The Signer or Provider object to interact with the Ethereum network
+   * @returns {Promise<EscrowClient>} - An instance of EscrowClient
+   * @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();
+    }
+
+    const chainId: ChainId = network.chainId;
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    return new EscrowClient(signerOrProvider, networkData);
   }
 
   /**
@@ -129,7 +158,7 @@ export default class EscrowClient {
       recordingOracleFee,
       reputationOracleFee,
       manifestUrl,
-      hash,
+      manifestHash,
     } = escrowConfig;
 
     if (!ethers.utils.isAddress(recordingOracle)) {
@@ -160,7 +189,7 @@ export default class EscrowClient {
       throw ErrorInvalidUrl;
     }
 
-    if (!hash) {
+    if (!manifestHash) {
       throw ErrorHashIsEmptyString;
     }
 
@@ -174,16 +203,16 @@ export default class EscrowClient {
         this.signerOrProvider
       );
       await this.escrowContract.setup(
-        recordingOracle,
         reputationOracle,
-        recordingOracleFee,
+        recordingOracle,
         reputationOracleFee,
+        recordingOracleFee,
         manifestUrl,
-        hash
+        manifestHash
       );
 
       return;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -213,7 +242,7 @@ export default class EscrowClient {
       await this.setup(escrowAddress, escrowConfig);
 
       return escrowAddress;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -256,7 +285,7 @@ export default class EscrowClient {
       await tokenContract.transfer(escrowAddress, amount);
 
       return;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -305,7 +334,7 @@ export default class EscrowClient {
       await this.escrowContract.storeResults(url, hash);
 
       return;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -334,7 +363,7 @@ export default class EscrowClient {
       );
       await this.escrowContract.complete();
       return;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -421,7 +450,7 @@ export default class EscrowClient {
         DEFAULT_TX_ID
       );
       return;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -450,7 +479,7 @@ export default class EscrowClient {
       );
       await this.escrowContract.cancel();
       return;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -479,7 +508,7 @@ export default class EscrowClient {
       );
       await this.escrowContract.abort();
       return;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -522,7 +551,7 @@ export default class EscrowClient {
       );
       await this.escrowContract.addTrustedHandlers(trustedHandlers);
       return;
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -549,7 +578,7 @@ export default class EscrowClient {
         this.signerOrProvider
       );
       return this.escrowContract.getBalance();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -576,7 +605,7 @@ export default class EscrowClient {
         this.signerOrProvider
       );
       return this.escrowContract.manifestUrl();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -603,6 +632,33 @@ export default class EscrowClient {
         this.signerOrProvider
       );
       return this.escrowContract.finalResultsUrl();
+    } catch (e) {
+      return throwError(e);
+    }
+  }
+
+  /**
+   * Returns the intermediate results file URL.
+   *
+   * @param {string} escrowAddress - Address of the escrow.
+   * @returns {Promise<void>}
+   * @throws {Error} - An error object if an error occurred.
+   */
+  async getIntermediateResultsUrl(escrowAddress: string): Promise<string> {
+    if (!ethers.utils.isAddress(escrowAddress)) {
+      throw ErrorInvalidEscrowAddressProvided;
+    }
+
+    if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
+      throw ErrorEscrowAddressIsNotProvidedByFactory;
+    }
+
+    try {
+      this.escrowContract = Escrow__factory.connect(
+        escrowAddress,
+        this.signerOrProvider
+      );
+      return this.escrowContract.intermediateResultsUrl();
     } catch (e: any) {
       return throwError(e);
     }
@@ -630,7 +686,7 @@ export default class EscrowClient {
         this.signerOrProvider
       );
       return this.escrowContract.token();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
@@ -657,21 +713,19 @@ export default class EscrowClient {
         this.signerOrProvider
       );
       return this.escrowContract.status();
-    } catch (e: any) {
+    } catch (e) {
       return throwError(e);
     }
   }
 
   /**
-   * Returns the current status of the escrow.
+   * Returns the escrow addresses created by a job requester.
    *
    * @param {IEscrowsFilter} requesterAddress - Address of the requester.
-   * @returns {Promise<void>}
+   * @returns {Promise<string[]>}
    * @throws {Error} - An error object if an error occurred.
    */
-  async getLaunchedEscrows(
-    requesterAddress: string
-  ): Promise<ILauncherEscrowsResult[]> {
+  async getLaunchedEscrows(requesterAddress: string): Promise<string[]> {
     if (!ethers.utils.isAddress(requesterAddress)) {
       throw ErrorInvalidAddress;
     }
@@ -679,51 +733,39 @@ export default class EscrowClient {
     try {
       const { data } = await gqlFetch(
         this.network.subgraphUrl,
-        RAW_LAUNCHED_ESCROWS_QUERY(),
-        {
-          address: requesterAddress,
-        }
+        RAW_LAUNCHED_ESCROWS_QUERY(requesterAddress)
       );
 
-      return data;
+      return data.data.launchedEscrows.map((escrow: any) => escrow.id);
     } catch (e: any) {
       return throwError(e);
     }
   }
 
   /**
-   * Returns the escrows addresses created by a job requester.
+   * Returns the escrow addresses based on a specified filter.
    *
-   * @param {string} escrowAddress - Address of the escrow.
-   * @param {IEscrowsFilter} filer - Filter parameters.
-   * @returns {Promise<void>}
+   * @param {IEscrowsFilter} filter - Filter parameters.
+   * @returns {Promise<string[]>}
    * @throws {Error} - An error object if an error occurred.
    */
-  async getEscrowsFiltered(
-    escrowAddress: string,
-    filter: IEscrowsFilter
-  ): Promise<ILauncherEscrowsResult[]> {
-    if (!ethers.utils.isAddress(escrowAddress)) {
+  async getEscrowsFiltered(filter: IEscrowsFilter): Promise<string[]> {
+    if (filter?.address && !ethers.utils.isAddress(filter?.address)) {
       throw ErrorInvalidAddress;
     }
 
-    if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
-      throw ErrorEscrowAddressIsNotProvidedByFactory;
-    }
-
     try {
       const { data } = await gqlFetch(
         this.network.subgraphUrl,
-        RAW_LAUNCHED_ESCROWS_FILTERED_QUERY(),
-        {
-          address: filter.address,
-          status: filter.status,
-          from: filter.from,
-          tro: filter.to,
-        }
+        RAW_LAUNCHED_ESCROWS_FILTERED_QUERY(
+          filter.address,
+          filter.status,
+          filter.from,
+          filter.to
+        )
       );
 
-      return data;
+      return data.data.launchedEscrows.map((escrow: any) => escrow.id);
     } catch (e: any) {
       return throwError(e);
     }
@@ -756,6 +798,33 @@ export default class EscrowClient {
     }
   }
 
+  /**
+   * Returns the job launcher address of given escrow
+   *
+   * @param {string} escrowAddress - Address of the escrow.
+   * @returns {Promise<string>} - Address of the job launcher.
+   * @throws {Error} - An error object if an error occurred.
+   */
+  async getJobLauncherAddress(escrowAddress: string): Promise<string> {
+    if (!ethers.utils.isAddress(escrowAddress)) {
+      throw ErrorInvalidEscrowAddressProvided;
+    }
+
+    if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
+      throw ErrorEscrowAddressIsNotProvidedByFactory;
+    }
+
+    try {
+      this.escrowContract = Escrow__factory.connect(
+        escrowAddress,
+        this.signerOrProvider
+      );
+      return this.escrowContract.launcher();
+    } catch (e: any) {
+      return throwError(e);
+    }
+  }
+
   /**
    * Returns the reputation oracle address of given escrow
    *
@@ -782,4 +851,31 @@ export default class EscrowClient {
       return throwError(e);
     }
   }
+
+  /**
+   * Returns the escrow factory address of given escrow
+   *
+   * @param {string} escrowAddress - Address of the escrow.
+   * @returns {Promise<string>} - Address of the escrow factory.
+   * @throws {Error} - An error object if an error occurred.
+   */
+  async getFactoryAddress(escrowAddress: string): Promise<string> {
+    if (!ethers.utils.isAddress(escrowAddress)) {
+      throw ErrorInvalidEscrowAddressProvided;
+    }
+
+    if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
+      throw ErrorEscrowAddressIsNotProvidedByFactory;
+    }
+
+    try {
+      this.escrowContract = Escrow__factory.connect(
+        escrowAddress,
+        this.signerOrProvider
+      );
+      return this.escrowContract.escrowFactory();
+    } catch (e: any) {
+      return throwError(e);
+    }
+  }
 }

package/src/index.ts

@@ -1,17 +1,11 @@
-import InitClient from './init';
-import StakingClient from './staking';
-import StorageClient from './storage';
-import KVStoreClient from './kvstore';
-import EscrowClient from './escrow';
+import { StakingClient } from './staking';
+import { StorageClient } from './storage';
+import { KVStoreClient } from './kvstore';
+import { EscrowClient } from './escrow';
 
 export * from './constants';
 export * from './types';
 export * from './enums';
+export * from './interfaces';
 
-export {
-  InitClient,
-  StakingClient,
-  StorageClient,
-  KVStoreClient,
-  EscrowClient,
-};
+export { StakingClient, StorageClient, KVStoreClient, EscrowClient };

package/src/interfaces.ts

@@ -1,11 +1,5 @@
-import { BigNumber, Signer } from 'ethers';
-import { Provider } from '@ethersproject/abstract-provider';
-import { NetworkData } from './types';
-
-export interface IClientParams {
-  signerOrProvider: Signer | Provider;
-  network: NetworkData;
-}
+import { BigNumber } from 'ethers';
+import { EscrowStatus } from './types';
 
 export interface IAllocation {
   escrowAddress: string;
@@ -21,6 +15,7 @@ export interface IReward {
 }
 
 export interface IStaker {
+  staker: string;
   tokensStaked: BigNumber;
   tokensAllocated: BigNumber;
   tokensLocked: BigNumber;
@@ -29,9 +24,9 @@ export interface IStaker {
 }
 
 export interface IEscrowsFilter {
-  address: string;
+  address?: string;
   role?: number;
-  status?: number;
+  status?: EscrowStatus;
   from?: Date;
   to?: Date;
 }
@@ -42,9 +37,12 @@ export interface IEscrowConfig {
   recordingOracleFee: BigNumber;
   reputationOracleFee: BigNumber;
   manifestUrl: string;
-  hash: string;
+  manifestHash: string;
 }
 
-export interface ILauncherEscrowsResult {
-  id: string;
+export interface IKeyPair {
+  privateKey: string;
+  publicKey: string;
+  passphrase: string;
+  revocationCertificate?: string;
 }

package/src/kvstore.ts

@@ -1,33 +1,69 @@
+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 { Provider } from '@ethersproject/abstract-provider';
+import { NETWORKS } from './constants';
+import { requiresSigner } from './decorators';
+import { ChainId } from './enums';
 import {
   ErrorInvalidAddress,
   ErrorKVStoreArrayLength,
   ErrorKVStoreEmptyKey,
+  ErrorProviderDoesNotExist,
   ErrorSigner,
+  ErrorUnsupportedChainID,
 } from './error';
-import { IClientParams } from './interfaces';
-import { requiresSigner } from './decorators';
+import { NetworkData } from './types';
 
-export default class KVStoreClient {
+export class KVStoreClient {
   private contract: KVStore;
   private signerOrProvider: Signer | Provider;
 
   /**
-   * **KVStore constructor**
+   * **KVStoreClient constructor**
    *
-   *   * @param {IClientParams} clientParams - Init client parameters
+   * @param {Signer | Provider} signerOrProvider - The Signer or Provider object to interact with the Ethereum network
+   * @param {NetworkData} network - The network information required to connect to the KVStore contract
    */
-  constructor(readonly clientParams: IClientParams) {
+  constructor(signerOrProvider: Signer | Provider, network: NetworkData) {
     this.contract = KVStore__factory.connect(
-      clientParams.network.kvstoreAddress,
-      clientParams.signerOrProvider
+      network.factoryAddress,
+      signerOrProvider
     );
-    this.signerOrProvider = clientParams.signerOrProvider;
+    this.signerOrProvider = signerOrProvider;
+  }
+
+  /**
+   * Creates an instance of KVStoreClient from a Signer or Provider.
+   *
+   * @param {Signer | Provider} signerOrProvider - The Signer or Provider 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();
+    }
+
+    const chainId: ChainId = network.chainId;
+    const networkData = NETWORKS[chainId];
+
+    if (!networkData) {
+      throw ErrorUnsupportedChainID;
+    }
+
+    return new KVStoreClient(signerOrProvider, networkData);
   }
 
   /**
@@ -39,7 +75,7 @@ export default class KVStoreClient {
    * @throws {Error} - An error object if an error occurred
    */
   @requiresSigner
-  public async set(key: string, value: string) {
+  public async set(key: string, value: string): Promise<void> {
     if (!Signer.isSigner(this.signerOrProvider)) throw ErrorSigner;
     if (key === '') throw ErrorKVStoreEmptyKey;
     try {
@@ -58,7 +94,7 @@ export default class KVStoreClient {
    * @throws {Error} - An error object if an error occurred
    */
   @requiresSigner
-  public async setBulk(keys: string[], values: string[]) {
+  public async setBulk(keys: string[], values: string[]): Promise<void> {
     if (!Signer.isSigner(this.signerOrProvider)) throw ErrorSigner;
     if (keys.length !== values.length) throw ErrorKVStoreArrayLength;
     if (keys.includes('')) throw ErrorKVStoreEmptyKey;
@@ -76,10 +112,10 @@ export default class KVStoreClient {
    *
    * @param {string} address - The Ethereum address associated with the key-value pair
    * @param {string} key - The key of the key-value pair to get
-   * @returns {string} - The value of the key-value pair if it exists
+   * @returns {Promise<string>} - The value of the key-value pair if it exists
    * @throws {Error} - An error object if an error occurred
    */
-  public async get(address: string, key: string) {
+  public async get(address: string, key: string): Promise<string> {
     if (key === '') throw ErrorKVStoreEmptyKey;
     if (!ethers.utils.isAddress(address)) throw ErrorInvalidAddress;
 
@@ -88,6 +124,7 @@ export default class KVStoreClient {
       return result;
     } catch (e) {
       if (e instanceof Error) throw Error(`Failed to get value: ${e.message}`);
+      return e;
     }
   }
 }

package/src/queries.ts

@@ -1,3 +1,5 @@
+import { EscrowStatus } from './types';
+
 export const RAW_REWARDS_QUERY = (slasherAddress: string) => `{
     rewardAddedEvents(id: "${slasherAddress}") {
       escrow,
@@ -5,14 +7,20 @@ export const RAW_REWARDS_QUERY = (slasherAddress: string) => `{
     }
   }`;
 
-export const RAW_LAUNCHED_ESCROWS_QUERY = () => `{
-    launchedEscrows(where: { from: $address }) {
+export const RAW_LAUNCHED_ESCROWS_QUERY = (requesterAddress: string) => `{
+    launchedEscrows(where: { from: ${requesterAddress} }) {
       id
     }
   }`;
 
-export const RAW_LAUNCHED_ESCROWS_FILTERED_QUERY = () => `{
-    launchedEscrows(where: { from: $address, status: $status, timestamp_gte: $from, timestamp_lte: $to }) {
-      id
-    }
-  }`;
+export const RAW_LAUNCHED_ESCROWS_FILTERED_QUERY = (
+  address?: string,
+  status?: EscrowStatus,
+  from?: Date,
+  to?: Date
+) =>
+  `{ launchedEscrows(where: { ${address ? 'from: "' + address + '", ' : ''}${
+    status ? 'status: "' + EscrowStatus[status] + '", ' : ''
+  }${from ? 'timestamp_gte: "' + from?.valueOf() + '", ' : ''}${
+    to ? 'timestamp_lte: "' + to?.valueOf() + '"' : ''
+  }}) { id }}`;