@human-protocol/sdk 5.0.0-beta.2 → 5.0.0

package/src/escrow.ts

@@ -43,6 +43,7 @@ import {
   WarnVersionMismatch,
 } from './error';
 import {
+  CancellationRefundData,
   EscrowData,
   GET_CANCELLATION_REFUNDS_QUERY,
   GET_CANCELLATION_REFUND_BY_ADDRESS_QUERY,
@@ -50,6 +51,7 @@ import {
   GET_ESCROW_BY_ADDRESS_QUERY,
   GET_PAYOUTS_QUERY,
   GET_STATUS_UPDATES_QUERY,
+  PayoutData,
   StatusEvent,
 } from './graphql';
 import {
@@ -58,15 +60,12 @@ import {
   IEscrowsFilter,
   IPayoutFilter,
   IStatusEventFilter,
+  IStatusEvent,
+  ICancellationRefund,
+  IPayout,
+  IEscrowWithdraw,
 } from './interfaces';
-import {
-  EscrowStatus,
-  EscrowWithdraw,
-  NetworkData,
-  TransactionLikeWithNonce,
-  Payout,
-  CancellationRefund,
-} from './types';
+import { EscrowStatus, NetworkData, TransactionLikeWithNonce } from './types';
 import {
   getSubgraphUrl,
   getUnixTimestamp,
@@ -204,8 +203,8 @@ export class EscrowClient extends BaseEthersClient {
   /**
    * This function creates an escrow contract that uses the token passed to pay oracle fees and reward workers.
    *
-   * @param {string} tokenAddress Token address to use for payouts.
-   * @param {string} jobRequesterId Job Requester Id
+   * @param {string} tokenAddress - The address of the token to use for escrow funding.
+   * @param {string} jobRequesterId - Identifier for the job requester.
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns {Promise<string>} Returns the address of the escrow created.
    *
@@ -264,6 +263,167 @@ export class EscrowClient extends BaseEthersClient {
       return throwError(e);
     }
   }
+  private verifySetupParameters(escrowConfig: IEscrowConfig) {
+    const {
+      recordingOracle,
+      reputationOracle,
+      exchangeOracle,
+      recordingOracleFee,
+      reputationOracleFee,
+      exchangeOracleFee,
+      manifest,
+      manifestHash,
+    } = escrowConfig;
+
+    if (!ethers.isAddress(recordingOracle)) {
+      throw ErrorInvalidRecordingOracleAddressProvided;
+    }
+
+    if (!ethers.isAddress(reputationOracle)) {
+      throw ErrorInvalidReputationOracleAddressProvided;
+    }
+
+    if (!ethers.isAddress(exchangeOracle)) {
+      throw ErrorInvalidExchangeOracleAddressProvided;
+    }
+
+    if (
+      recordingOracleFee <= 0 ||
+      reputationOracleFee <= 0 ||
+      exchangeOracleFee <= 0
+    ) {
+      throw ErrorAmountMustBeGreaterThanZero;
+    }
+
+    if (recordingOracleFee + reputationOracleFee + exchangeOracleFee > 100) {
+      throw ErrorTotalFeeMustBeLessThanHundred;
+    }
+
+    const isManifestValid = isValidUrl(manifest) || isValidJson(manifest);
+    if (!isManifestValid) {
+      throw ErrorInvalidManifest;
+    }
+
+    if (!manifestHash) {
+      throw ErrorHashIsEmptyString;
+    }
+  }
+
+  /**
+   * Creates, funds, and sets up a new escrow contract in a single transaction.
+   *
+   * @param {string} tokenAddress - The ERC-20 token address used to fund the escrow.
+   * @param {bigint} amount - The token amount to fund the escrow with.
+   * @param {string} jobRequesterId - An off-chain identifier for the job requester.
+   * @param {IEscrowConfig} escrowConfig - Configuration parameters for escrow setup:
+   *   - `recordingOracle`: Address of the recording oracle.
+   *   - `reputationOracle`: Address of the reputation oracle.
+   *   - `exchangeOracle`: Address of the exchange oracle.
+   *   - `recordingOracleFee`: Fee (in basis points or percentage * 100) for the recording oracle.
+   *   - `reputationOracleFee`: Fee for the reputation oracle.
+   *   - `exchangeOracleFee`: Fee for the exchange oracle.
+   *   - `manifest`: URL to the manifest file.
+   *   - `manifestHash`: Hash of the manifest content.
+   * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
+   *
+   * @returns {Promise<string>} Returns the address of the escrow created.
+   *
+   * @example
+   * import { Wallet, ethers } from 'ethers';
+   * import { EscrowClient, IERC20__factory } from '@human-protocol/sdk';
+   *
+   * const rpcUrl = 'YOUR_RPC_URL';
+   * const privateKey = 'YOUR_PRIVATE_KEY';
+   * const provider = new ethers.JsonRpcProvider(rpcUrl);
+   * const signer = new Wallet(privateKey, provider);
+   *
+   * const escrowClient = await EscrowClient.build(signer);
+   *
+   * const tokenAddress = '0xTokenAddress';
+   * const amount = ethers.parseUnits('1000', 18);
+   * const jobRequesterId = 'requester-123';
+   *
+   * const token = IERC20__factory.connect(tokenAddress, signer);
+   * await token.approve(escrowClient.escrowFactoryContract.target, amount);
+   *
+   * const escrowConfig = {
+   *   recordingOracle: '0xRecordingOracle',
+   *   reputationOracle: '0xReputationOracle',
+   *   exchangeOracle: '0xExchangeOracle',
+   *   recordingOracleFee: 5n,
+   *   reputationOracleFee: 5n,
+   *   exchangeOracleFee: 5n,
+   *   manifest: 'https://example.com/manifest.json',
+   *   manifestHash: 'manifestHash-123',
+   * } satisfies IEscrowConfig;
+   *
+   * const escrowAddress = await escrowClient.createFundAndSetupEscrow(
+   *   tokenAddress,
+   *   amount,
+   *   jobRequesterId,
+   *   escrowConfig
+   * );
+   *
+   * console.log('Escrow created at:', escrowAddress);
+   */
+  @requiresSigner
+  public async createFundAndSetupEscrow(
+    tokenAddress: string,
+    amount: bigint,
+    jobRequesterId: string,
+    escrowConfig: IEscrowConfig,
+    txOptions: Overrides = {}
+  ): Promise<string> {
+    if (!ethers.isAddress(tokenAddress)) {
+      throw ErrorInvalidTokenAddress;
+    }
+
+    this.verifySetupParameters(escrowConfig);
+
+    const {
+      recordingOracle,
+      reputationOracle,
+      exchangeOracle,
+      recordingOracleFee,
+      reputationOracleFee,
+      exchangeOracleFee,
+      manifest,
+      manifestHash,
+    } = escrowConfig;
+
+    try {
+      const result = await (
+        await this.escrowFactoryContract.createFundAndSetupEscrow(
+          tokenAddress,
+          amount,
+          jobRequesterId,
+          reputationOracle,
+          recordingOracle,
+          exchangeOracle,
+          reputationOracleFee,
+          recordingOracleFee,
+          exchangeOracleFee,
+          manifest,
+          manifestHash,
+          this.applyTxDefaults(txOptions)
+        )
+      ).wait();
+
+      const event = (
+        result?.logs?.find(({ topics }) =>
+          topics.includes(ethers.id('LaunchedV2(address,address,string)'))
+        ) as EventLog
+      )?.args;
+
+      if (!event) {
+        throw ErrorLaunchedEventIsNotEmitted;
+      }
+
+      return event.escrow;
+    } catch (e: any) {
+      return throwError(e);
+    }
+  }
 
   /**
    * This function sets up the parameters of the escrow.
@@ -320,43 +480,12 @@ export class EscrowClient extends BaseEthersClient {
       manifestHash,
     } = escrowConfig;
 
-    if (!ethers.isAddress(recordingOracle)) {
-      throw ErrorInvalidRecordingOracleAddressProvided;
-    }
-
-    if (!ethers.isAddress(reputationOracle)) {
-      throw ErrorInvalidReputationOracleAddressProvided;
-    }
-
-    if (!ethers.isAddress(exchangeOracle)) {
-      throw ErrorInvalidExchangeOracleAddressProvided;
-    }
+    this.verifySetupParameters(escrowConfig);
 
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
     }
 
-    if (
-      recordingOracleFee <= 0 ||
-      reputationOracleFee <= 0 ||
-      exchangeOracleFee <= 0
-    ) {
-      throw ErrorAmountMustBeGreaterThanZero;
-    }
-
-    if (recordingOracleFee + reputationOracleFee + exchangeOracleFee > 100) {
-      throw ErrorTotalFeeMustBeLessThanHundred;
-    }
-
-    const isManifestValid = isValidUrl(manifest) || isValidJson(manifest);
-    if (!isManifestValid) {
-      throw ErrorInvalidManifest;
-    }
-
-    if (!manifestHash) {
-      throw ErrorHashIsEmptyString;
-    }
-
     if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
       throw ErrorEscrowAddressIsNotProvidedByFactory;
     }
@@ -535,7 +664,7 @@ export class EscrowClient extends BaseEthersClient {
     const escrowContract = this.getEscrowContract(escrowAddress);
 
     const hasFundsToReserveParam = typeof a === 'bigint';
-    const fundsToReserve = hasFundsToReserveParam ? (a as bigint) : undefined;
+    const fundsToReserve = hasFundsToReserveParam ? (a as bigint) : null;
     const txOptions = (hasFundsToReserveParam ? b : a) || {};
     // When fundsToReserve is provided and is 0, allow empty URL.
     // In this situation not solutions might have been provided so the escrow can be straight cancelled.
@@ -557,7 +686,7 @@ export class EscrowClient extends BaseEthersClient {
     }
 
     try {
-      if (fundsToReserve !== undefined) {
+      if (fundsToReserve !== null) {
         await (
           await escrowContract['storeResults(string,string,uint256)'](
             url,
@@ -901,7 +1030,7 @@ export class EscrowClient extends BaseEthersClient {
    * @param {string} escrowAddress Address of the escrow to withdraw.
    * @param {string} tokenAddress Address of the token to withdraw.
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
-   * @returns {EscrowWithdraw} Returns the escrow withdrawal data including transaction hash and withdrawal amount. Throws error if any.
+   * @returns {IEscrowWithdraw} Returns the escrow withdrawal data including transaction hash and withdrawal amount. Throws error if any.
    *
    *
    * **Code example**
@@ -930,7 +1059,7 @@ export class EscrowClient extends BaseEthersClient {
     escrowAddress: string,
     tokenAddress: string,
     txOptions: Overrides = {}
-  ): Promise<EscrowWithdraw> {
+  ): Promise<IEscrowWithdraw> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
     }
@@ -969,7 +1098,7 @@ export class EscrowClient extends BaseEthersClient {
 
             const from = parsedLog?.args[0];
             if (parsedLog?.name === 'Transfer' && from === escrowAddress) {
-              amountTransferred = parsedLog?.args[2];
+              amountTransferred = BigInt(parsedLog?.args[2]);
               break;
             }
           }
@@ -979,13 +1108,11 @@ export class EscrowClient extends BaseEthersClient {
         throw ErrorTransferEventNotFoundInTransactionLogs;
       }
 
-      const escrowWithdrawData: EscrowWithdraw = {
+      return {
         txHash: transactionReceipt?.hash || '',
         tokenAddress,
         withdrawnAmount: amountTransferred,
       };
-
-      return escrowWithdrawData;
     } catch (e) {
       return throwError(e);
     }
@@ -1785,23 +1912,29 @@ export class EscrowUtils {
    * interface IEscrow {
    *   id: string;
    *   address: string;
-   *   amountPaid: string;
-   *   balance: string;
-   *   count: string;
-   *   jobRequesterId: string;
+   *   amountPaid: bigint;
+   *   balance: bigint;
+   *   count: bigint;
    *   factoryAddress: string;
-   *   finalResultsUrl?: string;
-   *   intermediateResultsUrl?: string;
+   *   finalResultsUrl: string | null;
+   *   finalResultsHash: string | null;
+   *   intermediateResultsUrl: string | null;
+   *   intermediateResultsHash: string | null;
    *   launcher: string;
-   *   manifestHash?: string;
-   *   manifest?: string;
-   *   recordingOracle?: string;
-   *   reputationOracle?: string;
-   *   exchangeOracle?: string;
-   *   status: EscrowStatus;
+   *   jobRequesterId: string | null;
+   *   manifestHash: string | null;
+   *   manifest: string | null;
+   *   recordingOracle: string | null;
+   *   reputationOracle: string | null;
+   *   exchangeOracle: string | null;
+   *   recordingOracleFee: number | null;
+   *   reputationOracleFee: number | null;
+   *   exchangeOracleFee: number | null;
+   *   status: string;
    *   token: string;
-   *   totalFundedAmount: string;
-   *   createdAt: string;
+   *   totalFundedAmount: bigint;
+   *   createdAt: number;
+   *   chainId: number;
    * };
    * ```
    *
@@ -1873,13 +2006,7 @@ export class EscrowUtils {
         skip: skip,
       }
     );
-    escrows.map((escrow) => (escrow.chainId = networkData.chainId));
-
-    if (!escrows) {
-      return [];
-    }
-
-    return escrows;
+    return (escrows || []).map((e) => mapEscrow(e, networkData.chainId));
   }
 
   /**
@@ -1906,23 +2033,29 @@ export class EscrowUtils {
    * interface IEscrow {
    *   id: string;
    *   address: string;
-   *   amountPaid: string;
-   *   balance: string;
-   *   count: string;
-   *   jobRequesterId: string;
+   *   amountPaid: bigint;
+   *   balance: bigint;
+   *   count: bigint;
    *   factoryAddress: string;
-   *   finalResultsUrl?: string;
-   *   intermediateResultsUrl?: string;
+   *   finalResultsUrl: string | null;
+   *   finalResultsHash: string | null;
+   *   intermediateResultsUrl: string | null;
+   *   intermediateResultsHash: string | null;
    *   launcher: string;
-   *   manifestHash?: string;
-   *   manifest?: string;
-   *   recordingOracle?: string;
-   *   reputationOracle?: string;
-   *   exchangeOracle?: string;
-   *   status: EscrowStatus;
+   *   jobRequesterId: string | null;
+   *   manifestHash: string | null;
+   *   manifest: string | null;
+   *   recordingOracle: string | null;
+   *   reputationOracle: string | null;
+   *   exchangeOracle: string | null;
+   *   recordingOracleFee: number | null;
+   *   reputationOracleFee: number | null;
+   *   exchangeOracleFee: number | null;
+   *   status: string;
    *   token: string;
-   *   totalFundedAmount: string;
-   *   createdAt: string;
+   *   totalFundedAmount: bigint;
+   *   createdAt: number;
+   *   chainId: number;
    * };
    * ```
    *
@@ -1953,13 +2086,14 @@ export class EscrowUtils {
       throw ErrorInvalidAddress;
     }
 
-    const { escrow } = await gqlFetch<{ escrow: EscrowData }>(
+    const { escrow } = await gqlFetch<{ escrow: EscrowData | null }>(
       getSubgraphUrl(networkData),
       GET_ESCROW_BY_ADDRESS_QUERY(),
       { escrowAddress: escrowAddress.toLowerCase() }
     );
+    if (!escrow) return null;
 
-    return escrow || null;
+    return mapEscrow(escrow, networkData.chainId);
   }
 
   /**
@@ -2020,7 +2154,7 @@ export class EscrowUtils {
    */
   public static async getStatusEvents(
     filter: IStatusEventFilter
-  ): Promise<StatusEvent[]> {
+  ): Promise<IStatusEvent[]> {
     const {
       chainId,
       statuses,
@@ -2073,14 +2207,12 @@ export class EscrowUtils {
       return [];
     }
 
-    const statusEvents = data['escrowStatusEvents'] as StatusEvent[];
-
-    const eventsWithChainId = statusEvents.map((event) => ({
-      ...event,
+    return data['escrowStatusEvents'].map((event) => ({
+      timestamp: Number(event.timestamp) * 1000,
+      escrowAddress: event.escrowAddress,
+      status: EscrowStatus[event.status as keyof typeof EscrowStatus],
       chainId,
     }));
-
-    return eventsWithChainId;
   }
 
   /**
@@ -2092,7 +2224,7 @@ export class EscrowUtils {
    * Fetch payouts from the subgraph.
    *
    * @param {IPayoutFilter} filter Filter parameters.
-   * @returns {Promise<Payout[]>} List of payouts matching the filters.
+   * @returns {Promise<IPayout[]>} List of payouts matching the filters.
    *
    * **Code example**
    *
@@ -2109,7 +2241,7 @@ export class EscrowUtils {
    * console.log(payouts);
    * ```
    */
-  public static async getPayouts(filter: IPayoutFilter): Promise<Payout[]> {
+  public static async getPayouts(filter: IPayoutFilter): Promise<IPayout[]> {
     const networkData = NETWORKS[filter.chainId];
     if (!networkData) {
       throw ErrorUnsupportedChainID;
@@ -2126,7 +2258,7 @@ export class EscrowUtils {
     const skip = filter.skip || 0;
     const orderDirection = filter.orderDirection || OrderDirection.DESC;
 
-    const { payouts } = await gqlFetch<{ payouts: Payout[] }>(
+    const { payouts } = await gqlFetch<{ payouts: PayoutData[] }>(
       getSubgraphUrl(networkData),
       GET_PAYOUTS_QUERY(filter),
       {
@@ -2139,8 +2271,17 @@ export class EscrowUtils {
         orderDirection,
       }
     );
+    if (!payouts) {
+      return [];
+    }
 
-    return payouts || [];
+    return payouts.map((payout) => ({
+      id: payout.id,
+      escrowAddress: payout.escrowAddress,
+      recipient: payout.recipient,
+      amount: BigInt(payout.amount),
+      createdAt: Number(payout.createdAt) * 1000,
+    }));
   }
 
   /**
@@ -2164,7 +2305,7 @@ export class EscrowUtils {
    * ```
    *
    * ```ts
-   * type CancellationRefund = {
+   * interface ICancellationRefund {
    *   id: string;
    *   escrowAddress: string;
    *   receiver: string;
@@ -2177,7 +2318,7 @@ export class EscrowUtils {
    *
    *
    * @param {Object} filter Filter parameters.
-   * @returns {Promise<CancellationRefund[]>} List of cancellation refunds matching the filters.
+   * @returns {Promise<ICancellationRefund[]>} List of cancellation refunds matching the filters.
    *
    * **Code example**
    *
@@ -2200,7 +2341,7 @@ export class EscrowUtils {
     first?: number;
     skip?: number;
     orderDirection?: OrderDirection;
-  }): Promise<CancellationRefund[]> {
+  }): Promise<ICancellationRefund[]> {
     const networkData = NETWORKS[filter.chainId];
     if (!networkData) throw ErrorUnsupportedChainID;
     if (filter.escrowAddress && !ethers.isAddress(filter.escrowAddress)) {
@@ -2216,7 +2357,7 @@ export class EscrowUtils {
     const orderDirection = filter.orderDirection || OrderDirection.DESC;
 
     const { cancellationRefundEvents } = await gqlFetch<{
-      cancellationRefundEvents: CancellationRefund[];
+      cancellationRefundEvents: CancellationRefundData[];
     }>(getSubgraphUrl(networkData), GET_CANCELLATION_REFUNDS_QUERY(filter), {
       escrowAddress: filter.escrowAddress?.toLowerCase(),
       receiver: filter.receiver?.toLowerCase(),
@@ -2227,7 +2368,19 @@ export class EscrowUtils {
       orderDirection,
     });
 
-    return cancellationRefundEvents || [];
+    if (!cancellationRefundEvents || cancellationRefundEvents.length === 0) {
+      return [];
+    }
+
+    return cancellationRefundEvents.map((event) => ({
+      id: event.id,
+      escrowAddress: event.escrowAddress,
+      receiver: event.receiver,
+      amount: BigInt(event.amount),
+      block: Number(event.block),
+      timestamp: Number(event.timestamp) * 1000,
+      txHash: event.txHash,
+    }));
   }
 
   /**
@@ -2251,7 +2404,7 @@ export class EscrowUtils {
    * ```
    *
    * ```ts
-   * type CancellationRefund = {
+   * interface ICancellationRefund {
    *   id: string;
    *   escrowAddress: string;
    *   receiver: string;
@@ -2265,7 +2418,7 @@ export class EscrowUtils {
    *
    * @param {ChainId} chainId Network in which the escrow has been deployed
    * @param {string} escrowAddress Address of the escrow
-   * @returns {Promise<CancellationRefund>} Cancellation refund data
+   * @returns {Promise<ICancellationRefund>} Cancellation refund data
    *
    * **Code example**
    *
@@ -2278,7 +2431,7 @@ export class EscrowUtils {
   public static async getCancellationRefund(
     chainId: ChainId,
     escrowAddress: string
-  ): Promise<CancellationRefund> {
+  ): Promise<ICancellationRefund | null> {
     const networkData = NETWORKS[chainId];
     if (!networkData) throw ErrorUnsupportedChainID;
 
@@ -2287,13 +2440,59 @@ export class EscrowUtils {
     }
 
     const { cancellationRefundEvents } = await gqlFetch<{
-      cancellationRefundEvents: any;
+      cancellationRefundEvents: CancellationRefundData[];
     }>(
       getSubgraphUrl(networkData),
       GET_CANCELLATION_REFUND_BY_ADDRESS_QUERY(),
       { escrowAddress: escrowAddress.toLowerCase() }
     );
 
-    return cancellationRefundEvents?.[0] || null;
+    if (!cancellationRefundEvents || cancellationRefundEvents.length === 0) {
+      return null;
+    }
+
+    return {
+      id: cancellationRefundEvents[0].id,
+      escrowAddress: cancellationRefundEvents[0].escrowAddress,
+      receiver: cancellationRefundEvents[0].receiver,
+      amount: BigInt(cancellationRefundEvents[0].amount),
+      block: Number(cancellationRefundEvents[0].block),
+      timestamp: Number(cancellationRefundEvents[0].timestamp) * 1000,
+      txHash: cancellationRefundEvents[0].txHash,
+    };
   }
 }
+
+function mapEscrow(e: EscrowData, chainId: ChainId | number): IEscrow {
+  return {
+    id: e.id,
+    address: e.address,
+    amountPaid: BigInt(e.amountPaid),
+    balance: BigInt(e.balance),
+    count: Number(e.count),
+    factoryAddress: e.factoryAddress,
+    finalResultsUrl: e.finalResultsUrl,
+    finalResultsHash: e.finalResultsHash,
+    intermediateResultsUrl: e.intermediateResultsUrl,
+    intermediateResultsHash: e.intermediateResultsHash,
+    launcher: e.launcher,
+    jobRequesterId: e.jobRequesterId,
+    manifestHash: e.manifestHash,
+    manifest: e.manifest,
+    recordingOracle: e.recordingOracle,
+    reputationOracle: e.reputationOracle,
+    exchangeOracle: e.exchangeOracle,
+    recordingOracleFee: e.recordingOracleFee
+      ? Number(e.recordingOracleFee)
+      : null,
+    reputationOracleFee: e.reputationOracleFee
+      ? Number(e.reputationOracleFee)
+      : null,
+    exchangeOracleFee: e.exchangeOracleFee ? Number(e.exchangeOracleFee) : null,
+    status: e.status,
+    token: e.token,
+    totalFundedAmount: BigInt(e.totalFundedAmount),
+    createdAt: Number(e.createdAt) * 1000,
+    chainId: Number(chainId),
+  };
+}