@nomicfoundation/hardhat-ethers-chai-matchers 3.0.0-next.0

package/src/internal/matchers/changeEtherBalance.ts

@@ -0,0 +1,138 @@
+import type { BalanceChangeOptions } from "../utils/balance.js";
+import type { Addressable } from "ethers/address";
+import type { TransactionResponse } from "ethers/providers";
+import type { BigNumberish } from "ethers/utils";
+import type { EthereumProvider } from "hardhat/types/providers";
+
+import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
+import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
+import { toBigInt } from "ethers/utils";
+
+import { CHANGE_ETHER_BALANCE_MATCHER } from "../constants.js";
+import { getAddressOf } from "../utils/account.js";
+import {
+  assertCanBeConvertedToBigint,
+  assertIsNotNull,
+} from "../utils/asserts.js";
+import { buildAssert } from "../utils/build-assert.js";
+import { preventAsyncMatcherChaining } from "../utils/prevent-chaining.js";
+
+export function supportChangeEtherBalance(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(
+    CHANGE_ETHER_BALANCE_MATCHER,
+    function (
+      this: any,
+      provider: EthereumProvider,
+      account: Addressable | string,
+      balanceChange: BigNumberish | ((change: bigint) => boolean),
+      options?: BalanceChangeOptions,
+    ) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+      const subject = this._obj;
+
+      preventAsyncMatcherChaining(
+        this,
+        CHANGE_ETHER_BALANCE_MATCHER,
+        chaiUtils,
+      );
+
+      const checkBalanceChange = ([actualChange, address]: [
+        bigint,
+        string,
+      ]) => {
+        const assert = buildAssert(negated, checkBalanceChange);
+
+        if (typeof balanceChange === "function") {
+          assert(
+            balanceChange(actualChange),
+            `Expected the ether balance change of "${address}" to satisfy the predicate, but it didn't (balance change: ${actualChange.toString()} wei)`,
+            `Expected the ether balance change of "${address}" to NOT satisfy the predicate, but it did (balance change: ${actualChange.toString()} wei)`,
+          );
+        } else {
+          const expectedChange = toBigInt(balanceChange);
+          assert(
+            actualChange === expectedChange,
+            `Expected the ether balance of "${address}" to change by ${balanceChange.toString()} wei, but it changed by ${actualChange.toString()} wei`,
+            `Expected the ether balance of "${address}" NOT to change by ${balanceChange.toString()} wei, but it did`,
+          );
+        }
+      };
+
+      const derivedPromise = Promise.all([
+        getBalanceChange(provider, subject, account, options),
+        getAddressOf(account),
+      ]).then(checkBalanceChange);
+      this.then = derivedPromise.then.bind(derivedPromise);
+      this.catch = derivedPromise.catch.bind(derivedPromise);
+      this.promise = derivedPromise;
+      return this;
+    },
+  );
+}
+
+export async function getBalanceChange(
+  provider: EthereumProvider,
+  transaction:
+    | TransactionResponse
+    | Promise<TransactionResponse>
+    | (() => Promise<TransactionResponse> | TransactionResponse),
+  account: Addressable | string,
+  options?: BalanceChangeOptions,
+): Promise<bigint> {
+  let txResponse: TransactionResponse;
+
+  if (typeof transaction === "function") {
+    txResponse = await transaction();
+  } else {
+    txResponse = await transaction;
+  }
+
+  const txReceipt = await txResponse.wait();
+  assertIsNotNull(txReceipt, "txReceipt");
+  const txBlockNumber = txReceipt.blockNumber;
+
+  const block = await provider.request({
+    method: "eth_getBlockByHash",
+    params: [txReceipt.blockHash, false],
+  });
+
+  assertHardhatInvariant(
+    isObject(block) &&
+      Array.isArray(block.transactions) &&
+      block.transactions.length === 1,
+    "There should be only 1 transaction in the block",
+  );
+
+  const address = await getAddressOf(account);
+
+  const balanceAfterHex = await provider.request({
+    method: "eth_getBalance",
+    params: [address, numberToHexString(txBlockNumber)],
+  });
+
+  const balanceBeforeHex = await provider.request({
+    method: "eth_getBalance",
+    params: [address, numberToHexString(txBlockNumber - 1)],
+  });
+
+  assertCanBeConvertedToBigint(balanceAfterHex);
+  assertCanBeConvertedToBigint(balanceBeforeHex);
+
+  const balanceAfter = BigInt(balanceAfterHex);
+  const balanceBefore = BigInt(balanceBeforeHex);
+
+  if (options?.includeFee !== true && address === txResponse.from) {
+    const gasPrice = txReceipt.gasPrice;
+    const gasUsed = txReceipt.gasUsed;
+    const txFee = gasPrice * gasUsed;
+
+    return balanceAfter + txFee - balanceBefore;
+  } else {
+    return balanceAfter - balanceBefore;
+  }
+}

package/src/internal/matchers/changeEtherBalances.ts

@@ -0,0 +1,188 @@
+import type { BalanceChangeOptions } from "../utils/balance.js";
+import type { Addressable } from "ethers/address";
+import type { TransactionResponse } from "ethers/providers";
+import type { EthereumProvider } from "hardhat/types/providers";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { toBigInt } from "ethers/utils";
+
+import { CHANGE_ETHER_BALANCES_MATCHER } from "../constants.js";
+import { getAddressOf } from "../utils/account.js";
+import { assertIsNotNull } from "../utils/asserts.js";
+import { getAddresses, getBalances } from "../utils/balance.js";
+import { buildAssert } from "../utils/build-assert.js";
+import { ordinal } from "../utils/ordinal.js";
+import { preventAsyncMatcherChaining } from "../utils/prevent-chaining.js";
+
+export function supportChangeEtherBalances(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(
+    CHANGE_ETHER_BALANCES_MATCHER,
+    function (
+      this: any,
+      provider: EthereumProvider,
+      accounts: Array<Addressable | string>,
+      balanceChanges: bigint[] | ((changes: bigint[]) => boolean),
+      options?: BalanceChangeOptions,
+    ) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+
+      let subject = this._obj;
+      if (typeof subject === "function") {
+        subject = subject();
+      }
+
+      preventAsyncMatcherChaining(
+        this,
+        CHANGE_ETHER_BALANCES_MATCHER,
+        chaiUtils,
+      );
+
+      validateInput(this._obj, accounts, balanceChanges);
+
+      const checkBalanceChanges = ([actualChanges, accountAddresses]: [
+        bigint[],
+        string[],
+      ]) => {
+        const assert = buildAssert(negated, checkBalanceChanges);
+
+        if (typeof balanceChanges === "function") {
+          assert(
+            balanceChanges(actualChanges),
+            "Expected the balance changes of the accounts to satisfy the predicate, but they didn't",
+            "Expected the balance changes of the accounts to NOT satisfy the predicate, but they did",
+          );
+        } else {
+          assert(
+            actualChanges.every(
+              (change, ind) => change === toBigInt(balanceChanges[ind]),
+            ),
+            () => {
+              const lines: string[] = [];
+              actualChanges.forEach((change: bigint, i) => {
+                if (change !== toBigInt(balanceChanges[i])) {
+                  lines.push(
+                    `Expected the ether balance of ${
+                      accountAddresses[i]
+                    } (the ${ordinal(
+                      i + 1,
+                    )} address in the list) to change by ${balanceChanges[
+                      i
+                    ].toString()} wei, but it changed by ${change.toString()} wei`,
+                  );
+                }
+              });
+              return lines.join("\n");
+            },
+            () => {
+              const lines: string[] = [];
+              actualChanges.forEach((change: bigint, i) => {
+                if (change === toBigInt(balanceChanges[i])) {
+                  lines.push(
+                    `Expected the ether balance of ${
+                      accountAddresses[i]
+                    } (the ${ordinal(
+                      i + 1,
+                    )} address in the list) NOT to change by ${balanceChanges[
+                      i
+                    ].toString()} wei, but it did`,
+                  );
+                }
+              });
+              return lines.join("\n");
+            },
+          );
+        }
+      };
+
+      const derivedPromise = Promise.all([
+        getBalanceChanges(provider, subject, accounts, options),
+        getAddresses(accounts),
+      ]).then(checkBalanceChanges);
+      this.then = derivedPromise.then.bind(derivedPromise);
+      this.catch = derivedPromise.catch.bind(derivedPromise);
+      this.promise = derivedPromise;
+      return this;
+    },
+  );
+}
+
+function validateInput(
+  obj: any,
+  accounts: Array<Addressable | string>,
+  balanceChanges: bigint[] | ((changes: bigint[]) => boolean),
+) {
+  try {
+    if (
+      Array.isArray(balanceChanges) &&
+      accounts.length !== balanceChanges.length
+    ) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.ACCOUNTS_NUMBER_DIFFERENT_FROM_BALANCE_CHANGES,
+        {
+          accounts: accounts.length,
+          balanceChanges: balanceChanges.length,
+        },
+      );
+    }
+  } catch (e) {
+    // if the input validation fails, we discard the subject since it could
+    // potentially be a rejected promise
+    Promise.resolve(obj).catch(() => {});
+    throw e;
+  }
+}
+
+export async function getBalanceChanges(
+  provider: EthereumProvider,
+  transaction: TransactionResponse | Promise<TransactionResponse>,
+  accounts: Array<Addressable | string>,
+  options?: BalanceChangeOptions,
+): Promise<bigint[]> {
+  const txResponse = await transaction;
+
+  const txReceipt = await txResponse.wait();
+  assertIsNotNull(txReceipt, "txReceipt");
+  const txBlockNumber = txReceipt.blockNumber;
+
+  const balancesAfter = await getBalances(provider, accounts, txBlockNumber);
+  const balancesBefore = await getBalances(
+    provider,
+    accounts,
+    txBlockNumber - 1,
+  );
+
+  const txFees = await getTxFees(accounts, txResponse, options);
+
+  return balancesAfter.map(
+    (balance, ind) => balance + txFees[ind] - balancesBefore[ind],
+  );
+}
+
+async function getTxFees(
+  accounts: Array<Addressable | string>,
+  txResponse: TransactionResponse,
+  options?: BalanceChangeOptions,
+): Promise<bigint[]> {
+  return Promise.all(
+    accounts.map(async (account) => {
+      if (
+        options?.includeFee !== true &&
+        (await getAddressOf(account)) === txResponse.from
+      ) {
+        const txReceipt = await txResponse.wait();
+        assertIsNotNull(txReceipt, "txReceipt");
+        const gasPrice = txReceipt.gasPrice ?? txResponse.gasPrice;
+        const gasUsed = txReceipt.gasUsed;
+        const txFee = gasPrice * gasUsed;
+
+        return txFee;
+      }
+
+      return 0n;
+    }),
+  );
+}

package/src/internal/matchers/changeTokenBalance.ts

@@ -0,0 +1,295 @@
+import type {
+  Addressable,
+  BaseContract,
+  BaseContractMethod,
+  BigNumberish,
+  ContractTransactionResponse,
+} from "ethers";
+import type { TransactionResponse } from "ethers/providers";
+import type { EthereumProvider } from "hardhat/types/providers";
+
+import {
+  assertHardhatInvariant,
+  HardhatError,
+} from "@nomicfoundation/hardhat-errors";
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
+import { toBigInt } from "ethers/utils";
+
+import {
+  CHANGE_TOKEN_BALANCES_MATCHER,
+  CHANGE_TOKEN_BALANCE_MATCHER,
+} from "../constants.js";
+import { getAddressOf } from "../utils/account.js";
+import { assertIsNotNull } from "../utils/asserts.js";
+import { buildAssert } from "../utils/build-assert.js";
+import { preventAsyncMatcherChaining } from "../utils/prevent-chaining.js";
+
+export type Token = BaseContract & {
+  balanceOf: BaseContractMethod<[string], bigint, bigint>;
+  name: BaseContractMethod<[], string, string>;
+  transfer: BaseContractMethod<
+    [string, BigNumberish],
+    boolean,
+    ContractTransactionResponse
+  >;
+  symbol: BaseContractMethod<[], string, string>;
+};
+
+export function supportChangeTokenBalance(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(
+    CHANGE_TOKEN_BALANCE_MATCHER,
+    function (
+      this: any,
+      provider: EthereumProvider,
+      token: Token,
+      account: Addressable | string,
+      balanceChange: bigint | ((change: bigint) => boolean),
+    ) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+
+      let subject = this._obj;
+      if (typeof subject === "function") {
+        subject = subject();
+      }
+
+      preventAsyncMatcherChaining(
+        this,
+        CHANGE_TOKEN_BALANCE_MATCHER,
+        chaiUtils,
+      );
+
+      checkToken(token, CHANGE_TOKEN_BALANCE_MATCHER);
+
+      const checkBalanceChange = ([actualChange, address, tokenDescription]: [
+        bigint,
+        string,
+        string,
+      ]) => {
+        const assert = buildAssert(negated, checkBalanceChange);
+
+        if (typeof balanceChange === "function") {
+          assert(
+            balanceChange(actualChange),
+            `Expected the balance of ${tokenDescription} tokens for "${address}" to satisfy the predicate, but it didn't (token balance change: ${actualChange.toString()} wei)`,
+            `Expected the balance of ${tokenDescription} tokens for "${address}" to NOT satisfy the predicate, but it did (token balance change: ${actualChange.toString()} wei)`,
+          );
+        } else {
+          assert(
+            actualChange === toBigInt(balanceChange),
+            `Expected the balance of ${tokenDescription} tokens for "${address}" to change by ${balanceChange.toString()}, but it changed by ${actualChange.toString()}`,
+            `Expected the balance of ${tokenDescription} tokens for "${address}" NOT to change by ${balanceChange.toString()}, but it did`,
+          );
+        }
+      };
+
+      const derivedPromise = Promise.all([
+        getBalanceChange(provider, subject, token, account),
+        getAddressOf(account),
+        getTokenDescription(token),
+      ]).then(checkBalanceChange);
+
+      this.then = derivedPromise.then.bind(derivedPromise);
+      this.catch = derivedPromise.catch.bind(derivedPromise);
+
+      return this;
+    },
+  );
+
+  Assertion.addMethod(
+    CHANGE_TOKEN_BALANCES_MATCHER,
+    function (
+      this: any,
+      provider: EthereumProvider,
+      token: Token,
+      accounts: Array<Addressable | string>,
+      balanceChanges: bigint[] | ((changes: bigint[]) => boolean),
+    ) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+
+      let subject = this._obj;
+      if (typeof subject === "function") {
+        subject = subject();
+      }
+
+      preventAsyncMatcherChaining(
+        this,
+        CHANGE_TOKEN_BALANCES_MATCHER,
+        chaiUtils,
+      );
+
+      validateInput(this._obj, token, accounts, balanceChanges);
+
+      const balanceChangesPromise = Promise.all(
+        accounts.map((account) =>
+          getBalanceChange(provider, subject, token, account),
+        ),
+      );
+      const addressesPromise = Promise.all(accounts.map(getAddressOf));
+
+      const checkBalanceChanges = ([
+        actualChanges,
+        addresses,
+        tokenDescription,
+      ]: [bigint[], string[], string]) => {
+        const assert = buildAssert(negated, checkBalanceChanges);
+
+        if (typeof balanceChanges === "function") {
+          assert(
+            balanceChanges(actualChanges),
+            `Expected the balance changes of ${tokenDescription} to satisfy the predicate, but they didn't`,
+            `Expected the balance changes of ${tokenDescription} to NOT satisfy the predicate, but they did`,
+          );
+        } else {
+          assert(
+            actualChanges.every(
+              (change, ind) => change === toBigInt(balanceChanges[ind]),
+            ),
+            `Expected the balances of ${tokenDescription} tokens for ${addresses.join(
+              ", ",
+            )} to change by ${balanceChanges.join(
+              ", ",
+            )}, respectively, but they changed by ${actualChanges.join(", ")}`,
+            `Expected the balances of ${tokenDescription} tokens for ${addresses.join(
+              ", ",
+            )} NOT to change by ${balanceChanges.join(
+              ", ",
+            )}, respectively, but they did`,
+          );
+        }
+      };
+
+      const derivedPromise = Promise.all([
+        balanceChangesPromise,
+        addressesPromise,
+        getTokenDescription(token),
+      ]).then(checkBalanceChanges);
+
+      this.then = derivedPromise.then.bind(derivedPromise);
+      this.catch = derivedPromise.catch.bind(derivedPromise);
+
+      return this;
+    },
+  );
+}
+
+function validateInput(
+  obj: any,
+  token: Token,
+  accounts: Array<Addressable | string>,
+  balanceChanges: bigint[] | ((changes: bigint[]) => boolean),
+) {
+  try {
+    checkToken(token, CHANGE_TOKEN_BALANCES_MATCHER);
+
+    if (
+      Array.isArray(balanceChanges) &&
+      accounts.length !== balanceChanges.length
+    ) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.ACCOUNTS_NUMBER_DIFFERENT_FROM_BALANCE_CHANGES,
+        {
+          accounts: accounts.length,
+          balanceChanges: balanceChanges.length,
+        },
+      );
+    }
+  } catch (e) {
+    // if the input validation fails, we discard the subject since it could
+    // potentially be a rejected promise
+    Promise.resolve(obj).catch(() => {});
+    throw e;
+  }
+}
+
+function checkToken(token: unknown, method: string) {
+  if (!isObject(token) || token === null || !("interface" in token)) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CHAI_MATCHERS.FIRST_ARGUMENT_MUST_BE_A_CONTRACT_INSTANCE,
+      {
+        method,
+      },
+    );
+  } else if (
+    isObject(token) &&
+    "interface" in token &&
+    isObject(token.interface) &&
+    "getFunction" in token.interface &&
+    typeof token.interface.getFunction === "function" &&
+    token.interface.getFunction("balanceOf") === null
+  ) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CHAI_MATCHERS.CONTRACT_IS_NOT_AN_ERC20_TOKEN,
+    );
+  }
+}
+
+export async function getBalanceChange(
+  provider: EthereumProvider,
+  transaction: TransactionResponse | Promise<TransactionResponse>,
+  token: Token,
+  account: Addressable | string,
+): Promise<bigint> {
+  const txResponse = await transaction;
+
+  const txReceipt = await txResponse.wait();
+  assertIsNotNull(txReceipt, "txReceipt");
+  const txBlockNumber = txReceipt.blockNumber;
+
+  const block = await provider.request({
+    method: "eth_getBlockByHash",
+    params: [txReceipt.blockHash, false],
+  });
+
+  assertHardhatInvariant(
+    isObject(block) &&
+      Array.isArray(block.transactions) &&
+      block.transactions.length === 1,
+    "There should be only 1 transaction in the block",
+  );
+
+  const address = await getAddressOf(account);
+
+  const balanceAfter = await token.balanceOf(address, {
+    blockTag: txBlockNumber,
+  });
+
+  const balanceBefore = await token.balanceOf(address, {
+    blockTag: txBlockNumber - 1,
+  });
+
+  return toBigInt(balanceAfter) - balanceBefore;
+}
+
+let tokenDescriptionsCache: Record<string, string> = {};
+/**
+ * Get a description for the given token. Use the symbol of the token if
+ * possible; if it doesn't exist, the name is used; if the name doesn't
+ * exist, the address of the token is used.
+ */
+async function getTokenDescription(token: Token): Promise<string> {
+  const tokenAddress = await token.getAddress();
+  if (tokenDescriptionsCache[tokenAddress] === undefined) {
+    let tokenDescription = `<token at ${tokenAddress}>`;
+    try {
+      tokenDescription = await token.symbol();
+    } catch (e) {
+      try {
+        tokenDescription = await token.name();
+      } catch (e2) {}
+    }
+
+    tokenDescriptionsCache[tokenAddress] = tokenDescription;
+  }
+
+  return tokenDescriptionsCache[tokenAddress];
+}
+
+// only used by tests
+export function clearTokenDescriptionsCache(): void {
+  tokenDescriptionsCache = {};
+}