@across-protocol/sdk 3.0.0

package/src/utils/FormattingUtils.ts

@@ -0,0 +1,186 @@
+import { ethers } from "ethers";
+import { BN, toBN } from "./BigNumberUtils";
+import { fromWei } from "./common";
+import assert from "assert";
+import { BigNumber } from "bignumber.js";
+
+// Formats the input to round to decimalPlaces number of decimals if the number has a magnitude larger than 1 and fixes
+// precision to minPrecision if the number has a magnitude less than 1.
+export const formatWithMaxDecimals = (
+  num: number | string,
+  decimalPlaces: number,
+  minPrecision: number,
+  roundUp: boolean,
+  showSign: boolean
+): string => {
+  if (roundUp) {
+    BigNumber.set({ ROUNDING_MODE: BigNumber.ROUND_UP });
+  } else {
+    BigNumber.set({ ROUNDING_MODE: BigNumber.ROUND_DOWN });
+  }
+
+  const fullPrecisionFloat = new BigNumber(num);
+  const positiveSign = showSign && fullPrecisionFloat.gt(0) ? "+" : "";
+  let fixedPrecisionFloat;
+  // Convert back to BN to truncate any trailing 0s that the toFixed() output would print. If the number is equal to or larger than
+  // 1 then truncate to `decimalPlaces` number of decimal places. EG 999.999 -> 999.99 with decimalPlaces=2 If the number
+  // is less than 1 then truncate to minPrecision precision. EG: 0.0022183471 -> 0.002218 with minPrecision=4
+  if (fullPrecisionFloat.abs().gte(new BigNumber(1))) {
+    fixedPrecisionFloat = new BigNumber(fullPrecisionFloat).toFixed(decimalPlaces).toString();
+  } else {
+    fixedPrecisionFloat = new BigNumber(fullPrecisionFloat).toPrecision(minPrecision).toString();
+  }
+  // This puts commas in the thousands places, but only before the decimal point.
+  const fixedPrecisionFloatParts = fixedPrecisionFloat.split(".");
+  fixedPrecisionFloatParts[0] = fixedPrecisionFloatParts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return positiveSign + fixedPrecisionFloatParts.join(".");
+};
+
+export const createFormatFunction = (
+  numDisplayedDecimals: number,
+  minDisplayedPrecision: number,
+  showSign = false,
+  decimals = 18
+) => {
+  return (valInWei: string | BN): string =>
+    formatWithMaxDecimals(
+      formatWei(ConvertDecimals(decimals, 18)(valInWei)),
+      numDisplayedDecimals,
+      minDisplayedPrecision,
+      false,
+      showSign
+    );
+};
+export const formatFeePct = (relayerFeePct: BN): string => {
+  // 1e18 = 100% so 1e16 = 1%.
+  return createFormatFunction(2, 4, false, 16)(toBN(relayerFeePct).toString());
+};
+
+/**
+ * Shortens a lengthy hexadecimal string to a shorter version with an ellipsis in the middle.
+ * @param hex A hexadecimal string to be shortened.
+ * @param maxLength The maximum length of the shortened string. Defaults to 8.
+ * @param delimiter The delimiter to use in the middle of the shortened string. Defaults to "...".
+ * @returns The shortened hexadecimal string.
+ * @example createShortHexString("0x772871a444c6e4e9903d8533a5a13101b74037158123e6709470f0afbf6e7d94") -> "0x7787...7d94"
+ */
+export function createShortHexString(hex: string, maxLength = 8, delimiter = ".."): string {
+  // If we have more maxLength then the hex size, we can simply
+  // return the hex directly.
+  if (hex.length <= maxLength) {
+    return hex;
+  }
+  // Resolve the maximum available after we account for the delimiter.
+  const maxAvailable = maxLength - delimiter.length;
+  // Sanity check to make sure we have enough characters to
+  // create a shortened version.
+  if (maxAvailable <= 0) {
+    throw new Error("Invalid max length");
+  }
+  // We can simulate rounding by adding 0.5 to the integer. If
+  // we had an odd division, the floor will add one additional
+  // character to the left side.
+  const leftCharacters = Math.floor(maxAvailable / 2 + 0.5);
+  // A simple floor division between the max character length
+  const rightCharacters = Math.floor(maxAvailable / 2);
+  // Combine the two sides with the delimiter in the middle.
+  return `${hex.substring(0, leftCharacters)}${delimiter}${hex.substring(hex.length - rightCharacters)}`;
+}
+
+/**
+ * Converts a utf8 string to a hex string.
+ * @param input The utf8 string to convert.
+ * @returns The hex string.
+ */
+export function utf8ToHex(input: string): string {
+  return ethers.utils.formatBytes32String(input);
+}
+
+/**
+ * Converts a hexadecimal string to a utf8 string.
+ * @param input The hexadecimal string to convert.
+ * @returns The utf8 string.
+ */
+export function hexToUtf8(input: string): string {
+  return ethers.utils.toUtf8String(input);
+}
+
+/**
+ * Converts a BigNumber to a 32-byte hexadecimal string.
+ *
+ * @param input - The BigNumber to convert.
+ * @returns The 32-byte hexadecimal string representation of the input.
+ */
+export function bnToHex(input: BN): string {
+  return ethers.utils.hexZeroPad(ethers.utils.hexlify(toBN(input)), 32);
+}
+
+/**
+ * Converts a value from wei to a decimal value with the specified number of decimal places.
+ * @param weiVal - The value in wei to convert.
+ * @param decimals - The number of decimal places to include in the converted value.
+ * @returns The converted value as a string.
+ */
+export function convertFromWei(weiVal: string, decimals: number): string {
+  const formatFunction = createFormatFunction(2, 4, false, decimals);
+  return formatFunction(weiVal);
+}
+
+/**
+ * Shortens a list of addresses to a shorter version with only the first 10 characters.
+ * @param addresses A list of addresses to shorten.
+ * @returns A list of shortened addresses.
+ * @see createShortHexString
+ */
+export function shortenHexStrings(addresses: string[]): string[] {
+  return addresses.map((h) => createShortHexString(h));
+}
+
+// formatWei converts a string or BN instance from Wei to Ether, e.g., 1e19 -> 10.
+export const formatWei = (num: string | BN): string => {
+  // Web3's `fromWei` function doesn't work on BN objects in minified mode (e.g.,
+  // `web3.utils.isBN(web3.utils.fromBN("5"))` is false), so we use a workaround where we always pass in strings.
+  // See https://github.com/ethereum/web3.js/issues/1777.
+  return fromWei(num.toString());
+};
+
+// Take an amount based on fromDecimals and convert it to an amount based on toDecimals. For example 100 usdt = 100e6,
+// with 6 decimals. If you wanted to convert this to a base 18 decimals you would get:
+// convertDecimals(6,18)(100000000)  => 100000000000000000000 = 100e18.
+// Returns a BigNumber you will need to call toString on
+// fromDecimals: number - decimal value of amount
+// toDecimals: number - decimal value to convert to
+// web3: web3 object to get a big number function.
+// return => (amount:string)=>BN
+export const ConvertDecimals = (fromDecimals: number, toDecimals: number): ((amountIn: string | number | BN) => BN) => {
+  assert(fromDecimals >= 0, "requires fromDecimals as an integer >= 0");
+  assert(toDecimals >= 0, "requires toDecimals as an integer >= 0");
+  // amount: string, BN, number - integer amount in fromDecimals smallest unit that want to convert toDecimals
+  // returns: BN with toDecimals in smallest unit
+  return (amountIn: string | number | BN) => {
+    const amount = toBN(amountIn.toString());
+    if (amount.isZero()) return amount;
+    const diff = fromDecimals - toDecimals;
+    if (diff == 0) return amount;
+    if (diff > 0) return amount.div(toBN("10").pow(toBN(diff.toString())));
+    return amount.mul(toBN("10").pow(toBN((-1 * diff).toString())));
+  };
+};
+
+/**
+ * Converts a numeric decimal-inclusive string to winston, the base unit of Arweave
+ * @param numericString The numeric string to convert
+ * @returns The winston representation of the numeric string as a BigNumber
+ */
+export function parseWinston(numericString: string): ethers.BigNumber {
+  return ethers.utils.parseUnits(numericString, 12);
+}
+
+/**
+ * Converts a winston value to a numeric string
+ * @param winstonValue The winston value to convert
+ * @returns The numeric string representation of the winston value
+ */
+export function formatWinston(winstonValue: ethers.BigNumber): string {
+  return ethers.utils.formatUnits(winstonValue, 12);
+}

package/src/utils/IPFSUtils.ts

@@ -0,0 +1,48 @@
+import PinataClient from "@pinata/sdk";
+import axios from "axios";
+
+/**
+ * Build an IPFS client for interacting with the IPFS API
+ * @param APIKey The project ID
+ * @param secretAPIKey The project secret
+ * @returns An IPFS client for interacting with Pinata
+ */
+export function buildIPFSClient(APIKey: string, secretAPIKey: string): PinataClient {
+  return new PinataClient(APIKey, secretAPIKey);
+}
+
+/**
+ * Retrieves a value from an IPFS gateway
+ * @param contentHash The content hash of the value to retrieve
+ * @param publicGatewayURL The URL of the public IPFS gateway to use
+ * @returns The value retrieved from the IPFS gateway
+ * @throws Error if the value could not be retrieved
+ */
+export async function retrieveValueFromIPFS(contentHash: string, publicGatewayURL: string): Promise<string> {
+  const result = await axios.get(`${publicGatewayURL}/ipfs/${contentHash}`, {
+    // We need to set the Accept header to text/plain to avoid
+    // any anomalies with the response
+    headers: {
+      Accept: "text/plain",
+    },
+    // We want just the raw response, not the parsed response
+    transformResponse: (r) => r,
+  });
+  return result.data;
+}
+
+/**
+ * Pins a value to the IPFS network
+ * @param key A key to use for pinning the value. This is a metadata field.
+ * @param content The value to pin
+ * @param client The IPFS client to use
+ * @returns The content hash of the pinned value
+ */
+export async function storeValueInIPFS(key: string, content: string, client: PinataClient): Promise<string> {
+  const result = await client.pinJSONToIPFS(JSON.parse(content), {
+    pinataMetadata: {
+      name: key,
+    },
+  });
+  return result.IpfsHash;
+}

package/src/utils/JSONUtils.ts

@@ -0,0 +1,85 @@
+import { BigNumber } from "ethers";
+import { isDefined } from "./TypeGuards";
+
+/**
+ * This function converts a JSON string into a JSON object. The caveat is that if
+ * the parser detects a number, it will convert it to a string and floor it to
+ * an integer. This function will not throw but instead return an undefined value
+ * if the JSON string is invalid.
+ * @param jsonString The JSON string to parse
+ * @returns The parsed JSON object or undefined if the JSON string is invalid
+ */
+export function parseJSONWithNumericString(jsonString: string): unknown | undefined {
+  try {
+    return JSON.parse(jsonString, (_key, value) => {
+      if (typeof value === "number") {
+        return String(Math.floor(value));
+      }
+      return value;
+    });
+  } catch (e) {
+    return undefined;
+  }
+}
+
+/**
+ * This function converts an object into a JSON string. The caveat is that if
+ * the parser detects a BigNumber or BN, it will convert it to a string.
+ * @param obj The object to stringify
+ * @returns The stringified JSON object
+ * @throws Error if the object cannot be stringified
+ */
+export function stringifyJSONWithNumericString(obj: unknown): string {
+  return JSON.stringify(obj, (_key, value) => {
+    if (typeof value === "object" && value !== null && value.type === "BigNumber") {
+      return BigNumber.from(value).toString();
+    }
+    return value;
+  });
+}
+
+/**
+ * A replacer for use in `JSON.stringify` that converts big numbers to numeric strings.
+ * @param _key Unused
+ * @param value The value to convert
+ * @returns The converted value
+ */
+export function jsonReplacerWithBigNumbers(_key: string, value: unknown): unknown {
+  // If the value is not defined (null or undefined), return it as is
+  if (!isDefined(value)) {
+    return value;
+  }
+
+  // We need to check if this is a big number, because the JSON parser
+  // is not aware of BigNumbers and will convert them to the string representation
+  // of the object itself which is not what we want.
+  if (BigNumber.isBigNumber(value)) {
+    return value.toString();
+  }
+  // There's a legacy issues that returns BigNumbers as { type: "BigNumber", hex: "0x..." }
+  // so we need to check for that as well.
+  const recordValue = value as { type: string; hex: string };
+  if (recordValue.type === "BigNumber" && isDefined(recordValue.hex)) {
+    return BigNumber.from(recordValue.hex).toString();
+  }
+  // Return the value as is
+  return value;
+}
+
+/**
+ * A reviver for use in `JSON.parse` that converts numeric strings to big numbers.
+ * @param _key Unused
+ * @param value The value to convert
+ * @returns The converted value
+ */
+export function jsonReviverWithBigNumbers(_key: string, value: unknown): unknown {
+  // We need to check for both strings and big numbers, because the JSON parser
+  // is not aware of BigNumbers.
+  if (typeof value === "string" && /^-?\d+$/.test(value)) {
+    const bigNumber = BigNumber.from(value);
+    if (bigNumber.toString() === value) {
+      return bigNumber;
+    }
+  }
+  return value;
+}

package/src/utils/LogUtils.ts

@@ -0,0 +1,38 @@
+import { Logger } from "winston";
+
+export type DefaultLogLevels = "debug" | "info" | "warn" | "error";
+
+type LogParamType = {
+  level: DefaultLogLevels;
+  message: string;
+  at: {
+    location: string;
+    function: string;
+  };
+  data?: Record<string | number, unknown>;
+};
+
+export function formattedLog(
+  logger: Logger | undefined,
+  { level, message, at: { location, function: fnName }, data }: LogParamType
+): void {
+  if (logger) {
+    logger[level]({
+      at: `${location}#${fnName}`,
+      message,
+      ...data,
+    });
+  }
+}
+
+/**
+ * Asserts the truth of a condition. If the condition is false, an error is thrown with the provided message.
+ * @param condition The condition to assert.
+ * @param message The message to throw if the condition is false.
+ * @throws Error if the condition is false.
+ */
+export function assert(condition: boolean, message: string): void {
+  if (!condition) {
+    throw new Error(message);
+  }
+}

package/src/utils/Multicall.ts

@@ -0,0 +1,64 @@
+import { BigNumber, Contract, providers, Signer, utils as ethersUtils } from "ethers";
+import { getABI } from "./abi";
+
+type Provider = providers.Provider;
+type BlockTag = providers.BlockTag;
+type Result = ethersUtils.Result;
+
+export type Call3 = {
+  contract: Contract;
+  method: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  args?: any[];
+};
+
+// Multicall3 Constants:
+export const multicall3Addresses: Record<number, string> = {
+  1: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  10: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  137: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  324: "0xF9cda624FBC7e059355ce98a31693d299FACd963",
+  8453: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  34443: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  42161: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  59144: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  534352: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  // Testnets
+  5: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  300: "0xF9cda624FBC7e059355ce98a31693d299FACd963",
+  59140: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  59141: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  80002: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  84531: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  84532: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  421613: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  534351: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  11155111: "0xcA11bde05977b3631167028862bE2a173976CA11",
+  11155420: "0xcA11bde05977b3631167028862bE2a173976CA11",
+};
+
+export async function getMulticall3(
+  chainId: number,
+  signerOrProvider?: Signer | Provider
+): Promise<Contract | undefined> {
+  const address = multicall3Addresses[chainId];
+  if (!address) {
+    return undefined;
+  }
+
+  return new Contract(address, await getABI("Multicall3"), signerOrProvider);
+}
+
+export async function aggregate(multicall3: Contract, calls: Call3[], blockTag?: BlockTag): Promise<Result[]> {
+  const inputs = calls.map(({ contract, method, args }) => ({
+    target: contract.address,
+    callData: contract.interface.encodeFunctionData(method, args),
+  }));
+
+  const [, results] = await (multicall3.callStatic.aggregate(inputs, { blockTag }) as Promise<[BigNumber, string[]]>);
+
+  return results.map((result, idx) => {
+    const { contract, method } = calls[idx];
+    return contract.interface.decodeFunctionResult(method, result);
+  });
+}

package/src/utils/NetworkUtils.ts

@@ -0,0 +1,117 @@
+import { CHAIN_IDs, MAINNET_CHAIN_IDs, PUBLIC_NETWORKS, TESTNET_CHAIN_IDs } from "../constants";
+
+const hreNetworks: Record<number, string> = {
+  666: "Hardhat1",
+  1337: "Hardhat2",
+};
+
+/**
+ * Resolves a network name from a network id.
+ * @param networkId The network id to resolve the name for
+ * @returns The network name for the network id. If the network id is not found, returns "unknown"
+ */
+export function getNetworkName(networkId: number | string): string {
+  networkId = Number(networkId);
+  return PUBLIC_NETWORKS[networkId]?.name ?? hreNetworks[networkId] ?? "unknown";
+}
+
+/**
+ * Resolves a native token symbol from a chain id.
+ * @param chainId The chain id to resolve the native token symbol for
+ * @returns The native token symbol for the chain id. If the chain id is not found, returns "ETH"
+ */
+export function getNativeTokenSymbol(chainId: number | string): string {
+  return PUBLIC_NETWORKS[Number(chainId)]?.nativeToken ?? "ETH";
+}
+
+/**
+ * Determines whether a chain ID is part of the production network.
+ * @param chainId Chain ID to query.
+ * @returns true if the chain ID is part of the production network, otherwise false.
+ */
+export function chainIsProd(chainId: number): boolean {
+  return Object.values(MAINNET_CHAIN_IDs).includes(chainId);
+}
+
+/**
+ * Determines whether a chain ID is part of the production network.
+ * @param chainId Chain ID to query.
+ * @returns true if the chain ID is part of the production network, otherwise false.
+ */
+export function chainIsTestnet(chainId: number): boolean {
+  return Object.values(TESTNET_CHAIN_IDs).includes(chainId);
+}
+
+/**
+ * Determines whether a chain ID is a Polygon implementation.
+ * @param chainId Chain ID to evaluate.
+ * @returns True if chainId is a Polygon chain (mainnet or testnet), otherwise false.
+ */
+export function chainIsMatic(chainId: number): boolean {
+  return [CHAIN_IDs.POLYGON, CHAIN_IDs.POLYGON_AMOY].includes(chainId);
+}
+
+/**
+ * Determines whether a chain ID is an Optimism OP Stack implementation.
+ * @param chainId Chain ID to evaluate.
+ * @returns True if chainId is an OP stack, otherwise false.
+ */
+export function chainIsOPStack(chainId: number): boolean {
+  return [
+    CHAIN_IDs.OPTIMISM,
+    CHAIN_IDs.BASE,
+    CHAIN_IDs.MODE,
+    CHAIN_IDs.OPTIMISM_GOERLI,
+    CHAIN_IDs.BASE_GOERLI,
+    CHAIN_IDs.OPTIMISM_SEPOLIA,
+    CHAIN_IDs.BASE_SEPOLIA,
+    CHAIN_IDs.MODE_SEPOLIA,
+  ].includes(chainId);
+}
+
+/**
+ * Determines whether a chain ID is an Arbitrum implementation.
+ * @param chainId Chain ID to evaluate.
+ * @returns True if chainId is an Arbitrum chain, otherwise false.
+ */
+export function chainIsArbitrum(chainId: number): boolean {
+  return [CHAIN_IDs.ARBITRUM, CHAIN_IDs.ARBITRUM_GOERLI, CHAIN_IDs.ARBITRUM_SEPOLIA].includes(chainId);
+}
+
+/**
+ * Determines whether a chain ID is a Linea implementation.
+ * @param chainId Chain ID to evaluate.
+ * @returns True if chainId is a Linea chain, otherwise false.
+ */
+export function chainIsLinea(chainId: number): boolean {
+  return [CHAIN_IDs.LINEA, CHAIN_IDs.LINEA_GOERLI].includes(chainId);
+}
+
+/**
+ * Determines whether a chain ID has the capacity for having its USDC bridged via CCTP.
+ * @param chainId Chain ID to evaluate.
+ * @returns True if chainId is a CCTP-bridging enabled chain, otherwise false.
+ */
+export function chainIsCCTPEnabled(chainId: number): boolean {
+  return [
+    // Mainnets
+    CHAIN_IDs.BASE,
+    CHAIN_IDs.OPTIMISM,
+    CHAIN_IDs.ARBITRUM,
+    CHAIN_IDs.POLYGON,
+    // Testnets
+    CHAIN_IDs.BASE_SEPOLIA,
+    CHAIN_IDs.OPTIMISM_SEPOLIA,
+    CHAIN_IDs.ARBITRUM_SEPOLIA,
+    CHAIN_IDs.POLYGON_AMOY,
+  ].includes(chainId);
+}
+
+/**
+ * Determines if a chain ID requires a manual L1 -> L2 finalization step.
+ * @param chainId Chain ID to evaluate.
+ * @returns True if chainId requires manual L1 -> L2 finalization, otherwise false.
+ */
+export function chainRequiresL1ToL2Finalization(chainId: number): boolean {
+  return chainIsCCTPEnabled(chainId) || chainIsLinea(chainId);
+}

package/src/utils/NumberUtils.ts

@@ -0,0 +1,17 @@
+/**
+ * A typeguard for a number with the added check that the number is an integer.
+ * @param value The value to check.
+ * @returns True if the value is a number and an integer, false otherwise.
+ */
+export function isInteger(value: unknown): value is number {
+  return !Number.isNaN(Number(value)) && Number.isInteger(value);
+}
+
+/**
+ * A typeguard for a number with added checks that the number is an integer and is greater to zero.
+ * @param value The value to check.
+ * @returns True if the value is a number, an integer, and greater than zero, false otherwise.
+ */
+export function isPositiveInteger(value: unknown): value is number {
+  return isInteger(value) && value > 0;
+}

package/src/utils/ObjectUtils.ts

@@ -0,0 +1,77 @@
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// Append value along the keyPath to object. For example assign(deposits, ['1337', '31337'], [{depositId:1}]) will create
+// deposits = {1337:{31337:[{depositId:1}]}}. Note that if the path into the object exists then this will append. This
+// function respects the destination type; if it is an object then deep merge and if an array effectively will push.
+export function assign(obj: any, keyPath: any[], value: any): void {
+  const lastKeyIndex = keyPath.length - 1;
+  for (let i = 0; i < lastKeyIndex; ++i) {
+    const key = keyPath[i];
+    if (!(key in obj)) {
+      obj[key] = {};
+    }
+    obj = obj[key];
+  }
+  // If the object at the deep path does not exist then set to the value.
+  if (!obj[keyPath[lastKeyIndex]] || typeof obj[keyPath[lastKeyIndex]] == "string") {
+    obj[keyPath[lastKeyIndex]] = value;
+  }
+  // If the object at the deep path is an array then append array wise.
+  else if (Array.isArray(value)) {
+    obj[keyPath[lastKeyIndex]] = [...obj[keyPath[lastKeyIndex]], ...value];
+  }
+  // If the value is false bool then set to false. This special case is needed as {...false} = {} which causes issues.
+  else if (value === false) {
+    obj[keyPath[lastKeyIndex]] = false;
+  }
+  // If the object at the deep path is an object then append object wise.
+  else {
+    obj[keyPath[lastKeyIndex]] = { ...obj[keyPath[lastKeyIndex]], ...value };
+  }
+}
+
+// Refactor to be more generalized with N props
+export function groupObjectCountsByThreeProps(
+  objects: any[],
+  primaryProp: string,
+  secondaryProp: string,
+  tertiaryProp: string
+): any {
+  return objects.reduce((result, obj) => {
+    result[obj[primaryProp]] = result[obj[primaryProp]] ?? {};
+    result[obj[primaryProp]][obj[secondaryProp]] = result[obj[primaryProp]][obj[secondaryProp]] ?? {};
+    const existingCount = result[obj[primaryProp]][obj[secondaryProp]][obj[tertiaryProp]];
+    result[obj[primaryProp]][obj[secondaryProp]][obj[tertiaryProp]] =
+      existingCount === undefined ? 1 : existingCount + 1;
+    return result;
+  }, {});
+}
+export function groupObjectCountsByTwoProps(
+  objects: any[],
+  primaryProp: string,
+  getSecondaryProp: (obj: any) => string
+): any {
+  return objects.reduce((result, obj) => {
+    result[obj[primaryProp]] = result[obj[primaryProp]] ?? {};
+    const existingCount = result[obj[primaryProp]][getSecondaryProp(obj)];
+    result[obj[primaryProp]][getSecondaryProp(obj)] = existingCount === undefined ? 1 : existingCount + 1;
+    return result;
+  }, {});
+}
+
+export function groupObjectCountsByProp(objects: any[], getProp: (obj: any) => string): any {
+  return objects.reduce((result, obj) => {
+    const existingCount = result[getProp(obj)];
+    result[getProp(obj)] = existingCount === undefined ? 1 : existingCount + 1;
+    return result;
+  }, {});
+}
+
+/**
+ * Filter out falsy keys from an object. Falsy keys are keys with values of false, null, undefined, 0, or empty string.
+ * @param obj The object to filter
+ * @returns A new object with falsy keys removed
+ */
+export function filterFalsyKeys(obj: Record<string | number, unknown>): Record<string | number, unknown> {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v));
+}

package/src/utils/ReviverUtils.ts

@@ -0,0 +1,31 @@
+import { toBN } from "./BigNumberUtils";
+import { isDefined } from "./TypeGuards";
+import { Reviver } from "./TypeUtils";
+
+/**
+ * A reviver composer that takes a list of revivers and returns a single reviver that applies all of them.
+ * @param revivers The revivers to compose.
+ * @returns A single reviver that applies all of the revivers passed in. If no revivers are passed in, the identity
+ * function is returned.
+ */
+export function composeRevivers(...revivers: Reviver[]): Reviver {
+  // Filter out undefined revivers.
+  revivers = revivers.filter(isDefined);
+  // Return a single reviver that applies all of the revivers passed in. If no revivers are passed in, the identity
+  // function is implicitly returned.
+  return (key: string, value: unknown) => revivers.reduce((acc, reviver) => reviver(key, acc), value);
+}
+
+/**
+ * Reviver function that converts a stringified BigNumber object to a BigNumber object.
+ * @param _ The key to the value being revived. Unused.
+ * @param value The value being revived.
+ * @returns The revived value. If the value is not a stringified BigNumber object, it is returned as-is.
+ */
+export function objectWithBigNumberReviver(_: unknown, value: unknown): unknown {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  const resolvedValue = value as { type: string; hex: string };
+  return resolvedValue.type === "BigNumber" ? toBN(resolvedValue.hex) : resolvedValue;
+}