docs: document the test utils functions

test/utils/asserts.ts

@@ -2,12 +2,35 @@ import { BigNumberish, Provider } from "ethers";
 import { LiquidityBridgeContractV2 } from "../../typechain-types";
 import { expect } from "chai";
 
+/**
+ * Creates an assertion that checks the difference between the balance of an address
+ * before and after the assertion is created. The current balance is determined when
+ * **this function** is called. The expected difference is compared with the difference
+ * of the balance that the address has in the moment the assertion is called minus the
+ * balance the address had when the assertion was created.
+ *
+ * @param args.source The source of the balance information. Might be an LBC instance
+ * or an RPC provider. So this function might be used to verify network balance or
+ * protocol balance.
+ *
+ * @param args.address The address to check the balance.
+ *
+ * @param args.expectedDiff The expected difference between the balance when this function
+ * is called (the assert function creation) and the balance when the assert function
+ * is called.
+ *
+ * @param args.message The message to display when the assertion fails.
+ *
+ * @returns { Promise<() => Promise<void>> } The assertion function itself. When the assertion function
+ * is called it will fetch the balance again and subtract from it the balance that was fetched when
+ * **this** function was called. The result is compared with the `expectedDiff` parameter.
+ */
 export async function createBalanceDifferenceAssertion(args: {
   source: LiquidityBridgeContractV2 | Provider;
   address: string;
   expectedDiff: BigNumberish;
   message: string;
-}): Promise<() => void> {
+}): Promise<() => Promise<void>> {
   const { source, address, expectedDiff, message } = args;
 
   const balanceNow = await source.getBalance(address);
@@ -17,6 +40,32 @@ export async function createBalanceDifferenceAssertion(args: {
   };
 }
 
+/**
+ * Creates an assertion that checks the difference between the balance of an address
+ * before and after the assertion is created. The current balance is determined when
+ * **this function** is called. The difference of the balance that the address has
+ * when the assertion is called minus the balance the address had when the
+ * assertion was created is compared to the `balanceUpdate` parameter received by the
+ * assert function.
+ *
+ * The difference between this function and {@link createBalanceDifferenceAssertion} is
+ * that in {@link createBalanceDifferenceAssertion} the expected difference is passed when
+ * the assertion is created, while in this function the expected difference is passed when
+ * the assertion is called. You should use this function when you are not sure about the
+ * expected difference because it depends on other factors.
+ *
+ * @param args.source The source of the balance information. Might be an LBC instance
+ * or an RPC provider. So this function might be used to verify network balance or
+ * protocol balance.
+ *
+ * @param args.address The address to check the balance.
+ *
+ * @param args.message The message to display when the assertion fails.
+ *
+ * @returns { Promise<(balanceUpdate: bigint) => void> } The assertion function itself. When the assertion
+ * function is called it will fetch the balance again and subtract from it the balance that was fetched when
+ * **this** function was called. The result is compared with the `balanceUpdate` parameter.
+ */
 export async function createBalanceUpdateAssertion(args: {
   source: LiquidityBridgeContractV2 | Provider;
   address: string;
@@ -30,13 +79,36 @@ export async function createBalanceUpdateAssertion(args: {
   };
 }
 
+/**
+ * This function has the same purpose as {@link createBalanceDifferenceAssertion} but
+ * it is used to check the collateral balance of a liquidity provider. The difference
+ * between this function and {@link createBalanceDifferenceAssertion} is that this function
+ * is used to compare protocol collateral, while the other function is used to compare network
+ * or protocol balance of any address.
+ *
+ * @param args.lbc The LBC contract instance.
+ *
+ * @param args.address The address to check the collateral.
+ *
+ * @param args.expectedDiff The expected difference between the collateral when this function
+ * is called (the assert function creation) and the collateral when the assert function
+ * is called.
+ *
+ * @param args.message The message to display when the assertion fails.
+ *
+ * @param args.type The type of collateral to check. It can be "pegin" or "pegout".
+ *
+ * @returns { Promise<() => Promise<void>> } The assertion function itself. When the assertion function
+ * is called it will fetch the collateral again and subtract from it the collateral that was fetched when
+ * **this** function was called. The result is compared with the `expectedDiff` parameter.
+ */
 export async function createCollateralUpdateAssertion(args: {
   lbc: LiquidityBridgeContractV2;
   address: string;
   expectedDiff: BigNumberish;
   message: string;
   type: "pegin" | "pegout";
-}): Promise<() => void> {
+}): Promise<() => Promise<void>> {
   let balanceNow: bigint;
   const { lbc, address, expectedDiff, message, type } = args;
 

test/utils/btc.ts

@@ -39,6 +39,15 @@ export function getTestBtcAddress(addressType: BtcAddressType): BytesLike {
   }
 }
 
+/**
+ * Generates a raw BTC transaction paying to the address specified in the given quote.
+ * The transaction will have two outputs, one for the specified amount and one null data
+ * script output for the quote hash.
+ * @param lbc The LBC contract instance to hash the quote
+ * @param quote The pegout quote
+ * @param scriptType The type of the output script to generate
+ * @returns { Promise<string> } The raw BTC transaction
+ */
 export async function generateRawTx(
   lbc: LiquidityBridgeContractV2,
   quote: QuotesV2.PegOutQuoteStruct,
@@ -75,6 +84,9 @@ export async function generateRawTx(
   return btcTx;
 }
 
+/**
+ * Use this function to get hardcoded values to use as merkle proofs in tests
+ */
 export function getTestMerkleProof() {
   const blockHeaderHash =
     "0x02327049330a25d4d17e53e79f478cbb79c53a509679b1d8a1505c5697afb326";

test/utils/encoding.ts

@@ -1,5 +1,10 @@
 import * as ethers from "ethers";
 
+/**
+ * Converts number to little-endian hex without the 0x prefix
+ * @param n The number to convert
+ * @returns { string } The little-endian hex representation of the number
+ */
 export const toLeHex = (n: ethers.BigNumberish) =>
   ethers
     .toBeHex(n)
@@ -8,6 +13,11 @@ export const toLeHex = (n: ethers.BigNumberish) =>
     .reverse()
     .join("");
 
+/**
+ * Converts a little-endian hex string to a number
+ * @param hex The little-endian hex string
+ * @returns { bigint } The number represented by the hex string
+ */
 export const fromLeHex: (hex: string) => bigint = (hex: string) =>
   hex.startsWith("0x")
     ? fromLeHex(hex.slice(2))
@@ -19,4 +29,9 @@ export const fromLeHex: (hex: string) => bigint = (hex: string) =>
             .join("")
       );
 
+/**
+ * Converts a number to a big-endian hex string without the 0x prefix
+ * @param n The number to convert
+ * @returns { string } The big-endian hex representation of the number
+ */
 export const toBeHex = (n: ethers.BigNumberish) => ethers.toBeHex(n).slice(2);

test/utils/fixtures.ts

@@ -7,6 +7,17 @@ import { LP_COLLATERAL } from "./constants";
 
 /**
  * Fixture that deploys the LBC contract and upgrades it to the latest version.
+ * @returns { {
+ *   lbc: LiquidityBridgeContractV2,
+ *   lbcOwner: HardhatEthersSigner,
+ *   accounts: HardhatEthersSigner[],
+ *   bridgeMock: BridgeMock
+ * } }
+ * The returned object contains the following:
+ * - lbc: The LiquidityBridgeContractV2 contract instance. Connected to the account 0 of the hardhat network.
+ * - lbcOwner: The account 0 of the hardhat network.
+ * - accounts: The accounts 1 to 19 of the hardhat network.
+ * - bridgeMock: The BridgeMock contract instance. Connected to the account 0 of the hardhat network.
  */
 export async function deployLbcFixture() {
   const network = hre.network.name;
@@ -28,7 +39,24 @@ export async function deployLbcFixture() {
 }
 
 /**
- * Fixture that deploys the LBC contract and registers the last 3 ethers signers as liquidity providers.
+ * Fixture that deploys the LBC contract and registers the last 3 hardhat signers as liquidity providers.
+ * @returns { {
+ *  lbc: LiquidityBridgeContractV2,
+ *  liquidityProviders: {
+ *  signer: HardhatEthersSigner,
+ *    registerParams: Parameters<LiquidityBridgeContractV2["register"]>
+ *  }[],
+ *  lbcOwner: HardhatEthersSigner,
+ *  bridgeMock: BridgeMock,
+ *  accounts: HardhatEthersSigner[]
+ * } }
+ * The returned object contains the following:
+ * - lbc: The LiquidityBridgeContractV2 contract instance. Connected to the account 0 of the hardhat network.
+ * - liquidityProviders: An array of objects containing the signer and the parameters to register as a liquidity provider.
+ *   the signers of the liquidity providers are the last 3 signers of the hardhat network accounts.
+ * - lbcOwner: The account 0 of the hardhat network.
+ * - bridgeMock: The BridgeMock contract instance. Connected to the account 0 of the hardhat network.
+ * - accounts: The accounts 1 to 16 of the hardhat network.
  */
 export async function deployLbcWithProvidersFixture() {
   const network = hre.network.name;

test/utils/quotes.ts

@@ -88,6 +88,11 @@ export function getTestPegoutQuote(args: {
   return quote;
 }
 
+/**
+ * Get the total value of a pegin or pegout quote
+ * @param quote The quote to get the total value of
+ * @returns { bigint } The total value of the quote
+ */
 export function totalValue(
   quote: QuotesV2.PeginQuoteStruct | QuotesV2.PegOutQuoteStruct
 ): bigint {
@@ -99,6 +104,14 @@ export function totalValue(
   );
 }
 
+/**
+ * Get mock bitcoin block headers for the given quote
+ * @param args.quote The quote to get the block headers for
+ * @param args.firstConfirmationSeconds The time in seconds for the first confirmation
+ * @param args.nConfirmationSeconds The time in seconds for the n-th confirmation
+ * @returns { firstConfirmationHeader, nConfirmationHeader } The block headers for the first and n-th confirmations.
+ * Their only populated field will be the block timestamp
+ */
 export function getBtcPaymentBlockHeaders(args: {
   quote: QuotesV2.PeginQuoteStruct | QuotesV2.PegOutQuoteStruct;
   firstConfirmationSeconds: number;