@human-protocol/sdk 3.0.6 → 3.0.8

package/src/escrow.ts

@@ -1,5 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import {
+  ERC20,
+  ERC20__factory,
   Escrow,
   EscrowFactory,
   EscrowFactory__factory,
@@ -45,7 +47,12 @@ import {
   StatusEvent,
 } from './graphql';
 import { IEscrowConfig, IEscrowsFilter } from './interfaces';
-import { EscrowCancel, EscrowStatus, NetworkData } from './types';
+import {
+  EscrowCancel,
+  EscrowStatus,
+  EscrowWithdraw,
+  NetworkData,
+} from './types';
 import { getSubgraphUrl, isValidUrl, throwError } from './utils';
 
 /**
@@ -124,7 +131,7 @@ export class EscrowClient extends BaseEthersClient {
    * **EscrowClient constructor**
    *
    * @param {ContractRunner} runner The Runner object to interact with the Ethereum network
-   * @param {NetworkData} network The network information required to connect to the Escrow contract
+   * @param {NetworkData} networkData The network information required to connect to the Escrow contract
    */
   constructor(runner: ContractRunner, networkData: NetworkData) {
     super(runner, networkData);
@@ -370,69 +377,6 @@ export class EscrowClient extends BaseEthersClient {
     }
   }
 
-  /**
-   * This function creates and sets up an escrow.
-   *
-   * @param {string} tokenAddress Token address to use for pay outs.
-   * @param {string[]} trustedHandlers Array of addresses that can perform actions on the contract.
-   * @param {string} jobRequesterId Job Requester Id
-   * @param {IEscrowConfig} escrowConfig Configuration object with escrow settings.
-   * @returns {Promise<string>} Returns the address of the escrow created.
-   *
-   *
-   * **Code example**
-   *
-   * ```ts
-   * import { ethers, Wallet, providers } from 'ethers';
-   * import { EscrowClient } 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 escrowClient = await EscrowClient.build(signer);
-   *
-   * const tokenAddress = '0x0376D26246Eb35FF4F9924cF13E6C05fd0bD7Fb4';
-   * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'];
-   * const jobRequesterId = "job-requester-id";
-   *
-   * const escrowConfig = {
-   *    recordingOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    reputationOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    exchangeOracle: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-   *    recordingOracleFee: bigint.from('10'),
-   *    reputationOracleFee: bigint.from('10'),
-   *    exchangeOracleFee: bigint.from('10'),
-   *    manifestUrl: 'htttp://localhost/manifest.json',
-   *    manifestHash: 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079',
-   * };
-   *
-   * const escrowAddress = await escrowClient.createAndSetupEscrow(tokenAddress, trustedHandlers, jobRequesterId, escrowConfig);
-   * ```
-   */
-  @requiresSigner
-  async createAndSetupEscrow(
-    tokenAddress: string,
-    trustedHandlers: string[],
-    jobRequesterId: string,
-    escrowConfig: IEscrowConfig
-  ): Promise<string> {
-    try {
-      const escrowAddress = await this.createEscrow(
-        tokenAddress,
-        trustedHandlers,
-        jobRequesterId
-      );
-
-      await this.setup(escrowAddress, escrowConfig);
-
-      return escrowAddress;
-    } catch (e) {
-      return throwError(e);
-    }
-  }
-
   /**
    * This function adds funds of the chosen token to the escrow.
    *
@@ -619,6 +563,7 @@ export class EscrowClient extends BaseEthersClient {
    * @param {bigint[]} amounts Array of amounts the recipients will receive.
    * @param {string} finalResultsUrl Final results file url.
    * @param {string} finalResultsHash Final results file hash.
+   * @param {string} forceComplete Indicates if remaining balance should be transferred to the escrow creator (optional, defaults to false).
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
@@ -653,6 +598,7 @@ export class EscrowClient extends BaseEthersClient {
     amounts: bigint[],
     finalResultsUrl: string,
     finalResultsHash: string,
+    forceComplete = false,
     txOptions: Overrides = {}
   ): Promise<void> {
     if (!ethers.isAddress(escrowAddress)) {
@@ -706,17 +652,34 @@ export class EscrowClient extends BaseEthersClient {
 
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
-
-      await (
-        await escrowContract.bulkPayOut(
-          recipients,
-          amounts,
-          finalResultsUrl,
-          finalResultsHash,
-          DEFAULT_TX_ID,
-          txOptions
-        )
-      ).wait();
+      if (forceComplete) {
+        await (
+          await escrowContract[
+            'bulkPayOut(address[],uint256[],string,string,uint256,bool)'
+          ](
+            recipients,
+            amounts,
+            finalResultsUrl,
+            finalResultsHash,
+            DEFAULT_TX_ID,
+            forceComplete,
+            txOptions
+          )
+        ).wait();
+      } else {
+        await (
+          await escrowContract[
+            'bulkPayOut(address[],uint256[],string,string,uint256)'
+          ](
+            recipients,
+            amounts,
+            finalResultsUrl,
+            finalResultsHash,
+            DEFAULT_TX_ID,
+            txOptions
+          )
+        ).wait();
+      }
       return;
     } catch (e) {
       return throwError(e);
@@ -808,9 +771,10 @@ export class EscrowClient extends BaseEthersClient {
   }
 
   /**
-   * This function cancels the specified escrow, sends the balance to the canceler and selfdestructs the escrow contract.
+   * This function adds an array of addresses to the trusted handlers list.
    *
    * @param {string} escrowAddress Address of the escrow.
+   * @param {string[]} trustedHandlers Array of addresses of trusted handlers to add.
    * @param {Overrides} [txOptions] - Additional transaction parameters (optional, defaults to an empty object).
    * @returns Returns void if successful. Throws error if any.
    *
@@ -830,15 +794,30 @@ export class EscrowClient extends BaseEthersClient {
    * const signer = new Wallet(privateKey, provider);
    * const escrowClient = await EscrowClient.build(signer);
    *
-   * await escrowClient.abort('0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266']
+   * await escrowClient.addTrustedHandlers('0x62dD51230A30401C455c8398d06F85e4EaB6309f', trustedHandlers);
    * ```
    */
   @requiresSigner
-  async abort(escrowAddress: string, txOptions: Overrides = {}): Promise<void> {
+  async addTrustedHandlers(
+    escrowAddress: string,
+    trustedHandlers: string[],
+    txOptions: Overrides = {}
+  ): Promise<void> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
     }
 
+    if (trustedHandlers.length === 0) {
+      throw ErrorListOfHandlersCannotBeEmpty;
+    }
+
+    trustedHandlers.forEach((trustedHandler) => {
+      if (!ethers.isAddress(trustedHandler)) {
+        throw new InvalidEthereumAddressError(trustedHandler);
+      }
+    });
+
     if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
       throw ErrorEscrowAddressIsNotProvidedByFactory;
     }
@@ -846,7 +825,9 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      await (await escrowContract.abort(txOptions)).wait();
+      await (
+        await escrowContract.addTrustedHandlers(trustedHandlers, txOptions)
+      ).wait();
       return;
     } catch (e) {
       return throwError(e);
@@ -854,20 +835,20 @@ export class EscrowClient extends BaseEthersClient {
   }
 
   /**
-   * This function sets the status of an escrow to completed.
+   * This function withdraws additional tokens in the escrow to the canceler.
    *
-   * @param {string} escrowAddress Address of the escrow.
-   * @param {string[]} trustedHandlers Array of addresses of trusted handlers to add.
+   * @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 Returns void if successful. Throws error if any.
+   * @returns {EscrowWithdraw} Returns the escrow withdrawal data including transaction hash and withdrawal amount. Throws error if any.
    *
    *
    * **Code example**
    *
-   * > Only Job Launcher or trusted handler can call it.
+   * > Only Job Launcher or a trusted handler can call it.
    *
    * ```ts
-   * import { Wallet, providers } from 'ethers';
+   * import { ethers, Wallet, providers } from 'ethers';
    * import { EscrowClient } from '@human-protocol/sdk';
    *
    * const rpcUrl = 'YOUR_RPC_URL';
@@ -877,30 +858,26 @@ export class EscrowClient extends BaseEthersClient {
    * const signer = new Wallet(privateKey, provider);
    * const escrowClient = await EscrowClient.build(signer);
    *
-   * const trustedHandlers = ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266']
-   * await escrowClient.addTrustedHandlers('0x62dD51230A30401C455c8398d06F85e4EaB6309f', trustedHandlers);
+   * await escrowClient.withdraw(
+   *  '0x62dD51230A30401C455c8398d06F85e4EaB6309f',
+   *  '0x0376D26246Eb35FF4F9924cF13E6C05fd0bD7Fb4'
+   * );
    * ```
    */
   @requiresSigner
-  async addTrustedHandlers(
+  async withdraw(
     escrowAddress: string,
-    trustedHandlers: string[],
+    tokenAddress: string,
     txOptions: Overrides = {}
-  ): Promise<void> {
+  ): Promise<EscrowWithdraw> {
     if (!ethers.isAddress(escrowAddress)) {
       throw ErrorInvalidEscrowAddressProvided;
     }
 
-    if (trustedHandlers.length === 0) {
-      throw ErrorListOfHandlersCannotBeEmpty;
+    if (!ethers.isAddress(tokenAddress)) {
+      throw ErrorInvalidTokenAddress;
     }
 
-    trustedHandlers.forEach((trustedHandler) => {
-      if (!ethers.isAddress(trustedHandler)) {
-        throw new InvalidEthereumAddressError(trustedHandler);
-      }
-    });
-
     if (!(await this.escrowFactoryContract.hasEscrow(escrowAddress))) {
       throw ErrorEscrowAddressIsNotProvidedByFactory;
     }
@@ -908,10 +885,43 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      await (
-        await escrowContract.addTrustedHandlers(trustedHandlers, txOptions)
+      const transactionReceipt = await (
+        await escrowContract.withdraw(tokenAddress, txOptions)
       ).wait();
-      return;
+
+      let amountTransferred: bigint | undefined = undefined;
+
+      const tokenContract: ERC20 = ERC20__factory.connect(
+        tokenAddress,
+        this.runner
+      );
+      if (transactionReceipt)
+        for (const log of transactionReceipt.logs) {
+          if (log.address === tokenAddress) {
+            const parsedLog = tokenContract.interface.parseLog({
+              topics: log.topics as string[],
+              data: log.data,
+            });
+
+            const from = parsedLog?.args[0];
+            if (parsedLog?.name === 'Transfer' && from === escrowAddress) {
+              amountTransferred = parsedLog?.args[2];
+              break;
+            }
+          }
+        }
+
+      if (amountTransferred === undefined) {
+        throw ErrorTransferEventNotFoundInTransactionLogs;
+      }
+
+      const escrowWithdrawData: EscrowWithdraw = {
+        txHash: transactionReceipt?.hash || '',
+        tokenAddress,
+        amountWithdrawn: amountTransferred,
+      };
+
+      return escrowWithdrawData;
     } catch (e) {
       return throwError(e);
     }
@@ -949,7 +959,13 @@ export class EscrowClient extends BaseEthersClient {
     try {
       const escrowContract = this.getEscrowContract(escrowAddress);
 
-      return escrowContract.getBalance();
+      try {
+        return await escrowContract.remainingFunds();
+      } catch {
+        // Use getBalance() method below if remainingFunds() is not available
+      }
+
+      return await escrowContract.getBalance();
     } catch (e) {
       return throwError(e);
     }

package/src/graphql/queries/operator.ts

@@ -6,22 +6,22 @@ const LEADER_FRAGMENT = gql`
     id
     address
     amountStaked
-    amountAllocated
     amountLocked
     lockedUntilTimestamp
     amountWithdrawn
     amountSlashed
-    reputation
     reward
     amountJobsProcessed
     role
     fee
     publicKey
     webhookUrl
+    website
     url
     jobTypes
     registrationNeeded
     registrationInstructions
+    reputationNetworks
   }
 `;
 

package/src/graphql/queries/statistics.ts

@@ -15,7 +15,6 @@ const HMTOKEN_STATISTICS_FRAGMENT = gql`
 const ESCROW_STATISTICS_FRAGMENT = gql`
   fragment EscrowStatisticsFields on EscrowStatistics {
     fundEventCount
-    setupEventCount
     storeResultsEventCount
     bulkPayoutEventCount
     pendingStatusEventCount
@@ -32,7 +31,6 @@ const EVENT_DAY_DATA_FRAGMENT = gql`
   fragment EventDayDataFields on EventDayData {
     timestamp
     dailyFundEventCount
-    dailySetupEventCount
     dailyStoreResultsEventCount
     dailyBulkPayoutEventCount
     dailyPendingStatusEventCount

package/src/graphql/queries/transaction.ts

@@ -10,35 +10,45 @@ const TRANSACTION_FRAGMENT = gql`
     timestamp
     value
     method
+    receiver
+    escrow
+    token
+    internalTransactions {
+      from
+      id
+      to
+      value
+      receiver
+      escrow
+      token
+      method
+    }
   }
 `;
 
 export const GET_TRANSACTIONS_QUERY = (filter: ITransactionsFilter) => {
   const { startDate, endDate, startBlock, endBlock, fromAddress, toAddress } =
     filter;
-
   const addressCondition =
     fromAddress === toAddress
       ? `
         ${fromAddress ? `{ from: $fromAddress }` : ''}
-        ${toAddress ? `{ to: $toAddress }` : ''}
+        ${toAddress ? `{ or: [{ or: [{ to: $toAddress }, { receiver: $toAddress }] }, {internalTransactions_: { or: [{ to: $toAddress }, { receiver: $toAddress }] } }] }` : ''}
       `
       : `
-        ${fromAddress ? `from: $fromAddress` : ''}
-        ${toAddress ? `to: $toAddress` : ''}
+        ${fromAddress ? `{ from: $fromAddress }` : ''}
+        ${toAddress ? `{ or: [{ or: [{ to: $toAddress }, { receiver: $toAddress }] }, { internalTransactions_: { or: [{ to: $toAddress }, { receiver: $toAddress }] } }] }` : ''}
       `;
 
   const WHERE_CLAUSE = `
       where: {
-        ${
-          fromAddress === toAddress
-            ? `or: [ ${addressCondition} ],`
-            : addressCondition
-        }
-        ${startDate ? `timestamp_gte: $startDate,` : ''}
-        ${endDate ? `timestamp_lte: $endDate,` : ''}
-        ${startBlock ? `block_gte: $startBlock,` : ''}
-        ${endBlock ? `block_lte: $endBlock,` : ''}
+      and: [
+        ${fromAddress && fromAddress === toAddress ? `{or: [ ${addressCondition} ]},` : `${addressCondition}`}
+        ${startDate ? `{timestamp_gte: $startDate},` : ''}
+        ${endDate ? `{timestamp_lte: $endDate},` : ''}
+        ${startBlock ? `{block_gte: $startBlock},` : ''}
+        ${endBlock ? `{block_lte: $endBlock},` : ''}
+      ]
       }
     `;
 

package/src/graphql/types.ts

@@ -41,7 +41,6 @@ export type HMTStatisticsData = {
 
 export type EscrowStatisticsData = {
   fundEventCount: string;
-  setupEventCount: string;
   storeResultsEventCount: string;
   bulkPayoutEventCount: string;
   pendingStatusEventCount: string;
@@ -56,7 +55,6 @@ export type EscrowStatisticsData = {
 export type EventDayData = {
   timestamp: string;
   dailyFundEventCount: string;
-  dailySetupEventCount: string;
   dailyStoreResultsEventCount: string;
   dailyBulkPayoutEventCount: string;
   dailyPendingStatusEventCount: string;

package/src/interfaces.ts

@@ -1,14 +1,6 @@
 import { EscrowStatus } from './types';
 import { ChainId, OrderDirection } from './enums';
 
-export interface IAllocation {
-  escrowAddress: string;
-  staker: string;
-  tokens: bigint;
-  createdAt: bigint;
-  closedAt: bigint;
-}
-
 export interface IReward {
   escrowAddress: string;
   amount: bigint;
@@ -19,26 +11,28 @@ export interface ILeader {
   chainId: ChainId;
   address: string;
   amountStaked: bigint;
-  amountAllocated: bigint;
   amountLocked: bigint;
   lockedUntilTimestamp: bigint;
   amountWithdrawn: bigint;
   amountSlashed: bigint;
-  reputation: bigint;
   reward: bigint;
   amountJobsProcessed: bigint;
   role?: string;
   fee?: bigint;
   publicKey?: string;
   webhookUrl?: string;
+  website?: string;
   url?: string;
   jobTypes?: string[];
   registrationNeeded?: boolean;
   registrationInstructions?: string;
+  reputationNetworks?: string[];
 }
 
-export interface ILeaderSubgraph extends Omit<ILeader, 'jobTypes'> {
+export interface ILeaderSubgraph
+  extends Omit<ILeader, 'jobTypes' | 'reputationNetworks' | 'chainId'> {
   jobTypes?: string;
+  reputationNetworks?: { address: string }[];
 }
 
 export interface ILeadersFilter {
@@ -121,6 +115,16 @@ export interface IKVStore {
   value: string;
 }
 
+export interface InternalTransaction {
+  from: string;
+  to: string;
+  value: string;
+  method: string;
+  receiver?: string;
+  escrow?: string;
+  token?: string;
+}
+
 export interface ITransaction {
   block: bigint;
   txHash: string;
@@ -129,6 +133,10 @@ export interface ITransaction {
   timestamp: bigint;
   value: string;
   method: string;
+  receiver?: string;
+  escrow?: string;
+  token?: string;
+  internalTransactions: InternalTransaction[];
 }
 
 export interface ITransactionsFilter extends IPagination {

package/src/kvstore.ts

@@ -103,7 +103,7 @@ export class KVStoreClient extends BaseEthersClient {
    * **KVStoreClient constructor**
    *
    * @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
+   * @param {NetworkData} networkData - The network information required to connect to the KVStore contract
    */
   constructor(runner: ContractRunner, networkData: NetworkData) {
     super(runner, networkData);

package/src/operator.ts

@@ -65,6 +65,7 @@ export class OperatorUtils {
     }
 
     let jobTypes: string[] = [];
+    let reputationNetworks: string[] = [];
 
     if (typeof leader.jobTypes === 'string') {
       jobTypes = leader.jobTypes.split(',');
@@ -72,9 +73,17 @@ export class OperatorUtils {
       jobTypes = leader.jobTypes;
     }
 
+    if (leader.reputationNetworks && Array.isArray(leader.reputationNetworks)) {
+      reputationNetworks = leader.reputationNetworks.map(
+        (network) => network.address
+      );
+    }
+
     return {
       ...leader,
       jobTypes,
+      reputationNetworks,
+      chainId,
     };
   }
 
@@ -118,6 +127,7 @@ export class OperatorUtils {
     leaders_data = leaders_data.concat(
       leaders.map((leader) => {
         let jobTypes: string[] = [];
+        let reputationNetworks: string[] = [];
 
         if (typeof leader.jobTypes === 'string') {
           jobTypes = leader.jobTypes.split(',');
@@ -125,9 +135,20 @@ export class OperatorUtils {
           jobTypes = leader.jobTypes;
         }
 
+        if (
+          leader.reputationNetworks &&
+          Array.isArray(leader.reputationNetworks)
+        ) {
+          reputationNetworks = leader.reputationNetworks.map(
+            (network) => network.address
+          );
+        }
+
         return {
           ...leader,
           jobTypes,
+          reputationNetworks,
+          chainId: filter.chainId,
         };
       })
     );