@across-protocol/sdk 3.0.0

package/src/utils/BundleUtils.ts

@@ -0,0 +1,109 @@
+import { AcrossConfigStoreClient, HubPoolClient } from "../clients";
+import { ProposedRootBundle } from "../interfaces";
+
+/**
+ * Return block number for `chain` in `bundleEvaluationBlockNumbers` using the mapping
+ * in `chainIdListForBundleEvaluationBlockNumbers` to figure out which index in `bundleEvaluationBlockNumbers`
+ * the block for `chain` is
+ * @param bundleEvaluationBlockNumbers Usually, the bundle end blocks proposed in a root bundle.
+ * @param chain The chain to look up block for
+ * @param chainIdListForBundleEvaluationBlockNumbers The hardcoded sequence of chain IDs. For example:
+ * [1, 10, 137, 288, 42161] implies that if we're looking for the block for chain 137, it's at index 2 in
+ * `bundleEvaluationBlockNumbers`.
+ * @returns The block for `chain` in `bundleEvaluationBlockNumbers`.
+ */
+export function getBlockForChain(
+  bundleEvaluationBlockNumbers: number[],
+  chain: number,
+  chainIdListForBundleEvaluationBlockNumbers: number[]
+): number {
+  const indexForChain = chainIdListForBundleEvaluationBlockNumbers.indexOf(chain);
+  if (indexForChain === -1) {
+    throw new Error(`Could not find chain ${chain} in chain ID list ${chainIdListForBundleEvaluationBlockNumbers}`);
+  }
+  const blockForChain = bundleEvaluationBlockNumbers[indexForChain];
+  if (blockForChain === undefined) {
+    throw new Error(`Invalid block range for chain ${chain}`);
+  }
+  return blockForChain;
+}
+
+/**
+ * Similar concept as `getBlockForChain`, but returns the block range for `chain` in `blockRanges`.
+ * @param blockRanges
+ * @param chain
+ * @param chainIdListForBundleEvaluationBlockNumbers
+ * @returns
+ */
+export function getBlockRangeForChain(
+  blockRanges: number[][],
+  chain: number,
+  chainIdListForBundleEvaluationBlockNumbers: number[]
+): number[] {
+  const indexForChain = chainIdListForBundleEvaluationBlockNumbers.indexOf(chain);
+  if (indexForChain === -1) {
+    throw new Error(`Could not find chain ${chain} in chain ID list ${chainIdListForBundleEvaluationBlockNumbers}`);
+  }
+  const blockRangeForChain = blockRanges[indexForChain];
+  if (!blockRangeForChain || blockRangeForChain.length !== 2) {
+    throw new Error(`Invalid block range for chain ${chain}`);
+  }
+  return blockRangeForChain;
+}
+
+/**
+ * Return bundle block range for `rootBundle` whose bundle end blocks were included in the proposal.
+ * This amounts to reconstructing the bundle range start block.
+ * @param rootBundle Root bundle to return bundle block range for
+ * @returns blockRanges: number[][], [[startBlock, endBlock], [startBlock, endBlock], ...]
+ */
+export function getImpliedBundleBlockRanges(
+  hubPoolClient: HubPoolClient,
+  configStoreClient: AcrossConfigStoreClient,
+  rootBundle: ProposedRootBundle
+): number[][] {
+  const prevRootBundle = hubPoolClient.getLatestFullyExecutedRootBundle(rootBundle.blockNumber);
+  // If chain is disabled for this bundle block range, end block should be same as previous bundle.
+  // Otherwise the range should be previous bundle's endBlock + 1 to current bundle's end block.
+
+  // Get enabled chains at the mainnet start block of the current root bundle.
+  // We'll check each chain represented in the bundleEvaluationBlockNumbers to see if it's enabled and
+  // use that to determine the implied block range.
+  const mainnetStartBlock = prevRootBundle?.bundleEvaluationBlockNumbers[0].toNumber() ?? 0;
+  const enabledChainsAtMainnetStartBlock = configStoreClient.getEnabledChains(mainnetStartBlock);
+
+  // Load all chain indices in order to map bundle evaluation block numbers to enabled chains list.
+  const chainIdIndices = configStoreClient.getChainIdIndicesForBlock(rootBundle.blockNumber);
+  const result = rootBundle.bundleEvaluationBlockNumbers.map((endBlock, i) => {
+    const fromBlock = prevRootBundle?.bundleEvaluationBlockNumbers?.[i]
+      ? prevRootBundle.bundleEvaluationBlockNumbers[i].toNumber() + 1
+      : 0;
+    const chainId = chainIdIndices[i];
+    if (!enabledChainsAtMainnetStartBlock.includes(chainId)) {
+      return [endBlock.toNumber(), endBlock.toNumber()];
+    }
+    return [fromBlock, endBlock.toNumber()];
+  });
+
+  // Lastly, sanity check the results to catch errors early:
+  // 1. If the chain is enabled, the start block should be strictly less than to the end block.
+  // 2. If the chain is disabled, the start block should be equal to the end block.
+  result.forEach(([start, end], i) => {
+    const chainId = chainIdIndices[i];
+    if (enabledChainsAtMainnetStartBlock.includes(chainId)) {
+      if (start >= end) {
+        throw new Error(
+          `Invalid block range for enabled chain ${chainId}: start block ${start} is greater than or equal to end block ${end}`
+        );
+      }
+    } else {
+      if (start !== end) {
+        throw new Error(
+          `Invalid block range for disabled chain ${chainId}: start block ${start} is not equal to end block ${end}`
+        );
+      }
+    }
+  });
+
+  return result;
+}

package/src/utils/CachingUtils.ts

@@ -0,0 +1,56 @@
+import { DEFAULT_CACHING_SAFE_LAG, DEFAULT_CACHING_TTL } from "../constants";
+import { CachingMechanismInterface, Deposit, Fill, SlowFillRequest } from "../interfaces";
+import { assert } from "./LogUtils";
+import { composeRevivers, objectWithBigNumberReviver } from "./ReviverUtils";
+import { getRelayHashFromEvent } from "./SpokeUtils";
+import { getCurrentTime } from "./TimeUtils";
+import { isDefined } from "./TypeGuards";
+
+export function shouldCache(eventTimestamp: number, latestTime: number, cachingMaxAge: number): boolean {
+  assert(eventTimestamp.toString().length === 10, "eventTimestamp must be in seconds");
+  assert(latestTime.toString().length === 10, "eventTimestamp must be in seconds");
+  return latestTime - eventTimestamp >= cachingMaxAge;
+}
+
+/**
+ * Calls the cache's get method and returns the result if it is defined, otherwise returns undefined.
+ * @param key The key to get from the cache.
+ * @param cache The cache to get the key from.
+ * @returns The value associated with the key in the cache, or undefined if the key is not in the cache.
+ */
+export async function getDepositInCache(key: string, cache: CachingMechanismInterface): Promise<Deposit | undefined> {
+  const depositRaw = await cache.get<string>(key);
+  return isDefined(depositRaw) ? JSON.parse(depositRaw, composeRevivers(objectWithBigNumberReviver)) : undefined;
+}
+
+export async function setDepositInCache(
+  deposit: Deposit,
+  currentChainTime: number,
+  cache: CachingMechanismInterface,
+  expirySeconds = DEFAULT_CACHING_TTL,
+  timeToCache = DEFAULT_CACHING_SAFE_LAG
+): Promise<void> {
+  const currentTimeInSeconds = getCurrentTime();
+  // We should first confirm that neither the deposit's quoteTimestamp nor the currentChainTime
+  // are in the future. If they are, we should not cache the deposit.
+  if (deposit.quoteTimestamp > currentTimeInSeconds || currentChainTime > currentTimeInSeconds) {
+    return;
+  }
+
+  // We should note here that the user can theoretically set the deposit's quoteTimestamp
+  // to whatever they want. As a result, this could be used to manipulate the caching mechanism.
+  if (shouldCache(deposit.quoteTimestamp, currentChainTime, timeToCache)) {
+    await cache.set(getDepositKey(deposit), JSON.stringify(deposit), expirySeconds);
+  }
+}
+
+/**
+ * Resolves the key for caching a bridge event.
+ * @param bridgeEvent The depositId, and originChainId are used to generate the key for v2, and the
+ * full V3 relay hash is used for v3 events..
+ * @returns The key for caching the event.
+ */
+export function getDepositKey(bridgeEvent: Deposit | Fill | SlowFillRequest): string {
+  const relayHash = getRelayHashFromEvent(bridgeEvent);
+  return `deposit_${bridgeEvent.originChainId}_${bridgeEvent.depositId}_${relayHash}`;
+}

package/src/utils/DeploymentUtils.ts

@@ -0,0 +1,5 @@
+export {
+  getContractInfoFromAddress,
+  getDeployedAddress,
+  getDeployedBlockNumber,
+} from "@across-protocol/contracts/dist/src/DeploymentUtils";

package/src/utils/DepositUtils.ts

@@ -0,0 +1,144 @@
+import assert from "assert";
+import { SpokePoolClient } from "../clients";
+import { DEFAULT_CACHING_TTL, EMPTY_MESSAGE } from "../constants";
+import { CachingMechanismInterface, Deposit, DepositWithBlock, Fill, SlowFillRequest } from "../interfaces";
+import { getNetworkName } from "./NetworkUtils";
+import { getDepositInCache, getDepositKey, setDepositInCache } from "./CachingUtils";
+import { validateFillForDeposit } from "./FlowUtils";
+import { getCurrentTime } from "./TimeUtils";
+import { isDefined } from "./TypeGuards";
+import { isDepositFormedCorrectly } from "./ValidatorUtils";
+
+// Load a deposit for a fill if the fill's deposit ID is outside this client's search range.
+// This can be used by the Dataworker to determine whether to give a relayer a refund for a fill
+// of a deposit older or younger than its fixed lookback.
+
+export enum InvalidFill {
+  DepositIdInvalid = 0, // Deposit ID seems invalid for origin SpokePool
+  DepositIdNotFound, // Deposit ID not found (bad RPC data?)
+  FillMismatch, // Fill does not match deposit parameters for deposit ID.
+}
+
+export type DepositSearchResult =
+  | { found: true; deposit: DepositWithBlock }
+  | { found: false; code: InvalidFill; reason: string };
+
+/**
+ * Attempts to resolve a deposit for a fill. If the fill's deposit Id is within the spoke pool client's search range,
+ * the deposit is returned immediately. Otherwise, the deposit is queried first from the provided cache, and if it is
+ * not found in the cache, it is queried from the spoke pool client. If the deposit is found, it is cached before
+ * being returned.
+ * @param spokePoolClient The spoke pool client to use to query the deposit.
+ * @param fill The fill to resolve a deposit for.
+ * @param cache An optional cache to use to store the deposit. Optional.
+ * @returns The deposit for the fill, or undefined if the deposit could not be found.
+ * @throws If the fill's origin chain ID does not match the spoke pool client's chain ID.
+ * @throws If the spoke pool client has not been updated.
+ */
+export async function queryHistoricalDepositForFill(
+  spokePoolClient: SpokePoolClient,
+  fill: Fill | SlowFillRequest,
+  cache?: CachingMechanismInterface
+): Promise<DepositSearchResult> {
+  if (fill.originChainId !== spokePoolClient.chainId) {
+    throw new Error(`OriginChainId mismatch (${fill.originChainId} != ${spokePoolClient.chainId})`);
+  }
+
+  // We need to update client so we know the first and last deposit ID's queried for this spoke pool client, as well
+  // as the global first and last deposit ID's for this spoke pool.
+  if (!spokePoolClient.isUpdated) {
+    throw new Error("SpokePoolClient must be updated before querying historical deposits");
+  }
+
+  const { depositId } = fill;
+  let { firstDepositIdForSpokePool: lowId, lastDepositIdForSpokePool: highId } = spokePoolClient;
+  if (depositId < lowId || depositId > highId) {
+    return {
+      found: false,
+      code: InvalidFill.DepositIdInvalid,
+      reason: `Deposit ID ${depositId} is outside of SpokePool bounds [${lowId},${highId}].`,
+    };
+  }
+
+  ({ earliestDepositIdQueried: lowId, latestDepositIdQueried: highId } = spokePoolClient);
+  if (depositId >= lowId && depositId <= highId) {
+    const deposit = spokePoolClient.getDeposit(depositId);
+    if (isDefined(deposit) && validateFillForDeposit(fill, deposit)) {
+      return { found: true, deposit };
+    }
+
+    return {
+      found: false,
+      code: isDefined(deposit) ? InvalidFill.FillMismatch : InvalidFill.DepositIdNotFound,
+      reason: `Deposit ID ${depositId} not found in SpokePoolClient event buffer.`,
+    };
+  }
+
+  let deposit: DepositWithBlock, cachedDeposit: Deposit | undefined;
+  if (cache) {
+    cachedDeposit = await getDepositInCache(getDepositKey(fill), cache);
+    // We only want to warn and remove the cached deposit if it
+    //    A: exists
+    //    B: is not formed correctly
+    if (isDefined(cachedDeposit) && !isDepositFormedCorrectly(cachedDeposit)) {
+      spokePoolClient.logger.warn({
+        at: "[SDK]:DepositUtils#queryHistoricalDepositForFill",
+        message: "Cached deposit was not formed correctly, removing from cache",
+        fill,
+        cachedDeposit,
+      });
+      // By setting this value to undefined, we eventually have to pull
+      // the deposit from our spoke pool client. Because this new deposit
+      // is formed correctly, we will cache it below.
+      cachedDeposit = undefined;
+    }
+  }
+
+  if (isDefined(cachedDeposit)) {
+    deposit = cachedDeposit as DepositWithBlock;
+  } else {
+    deposit = await spokePoolClient.findDeposit(fill.depositId, fill.destinationChainId, fill.depositor);
+    if (cache) {
+      await setDepositInCache(deposit, getCurrentTime(), cache, DEFAULT_CACHING_TTL);
+    }
+  }
+
+  if (validateFillForDeposit(fill, deposit)) {
+    return { found: true, deposit };
+  }
+
+  return {
+    found: false,
+    code: InvalidFill.FillMismatch,
+    reason: `Fill is not valid for ${getNetworkName(deposit.originChainId)} deposit ${depositId}`,
+  };
+}
+
+/**
+ * Determines if a message is empty or not.
+ * @param message The message to check.
+ * @returns True if the message is empty, false otherwise.
+ */
+export function isMessageEmpty(message = EMPTY_MESSAGE): boolean {
+  return message === "" || message === "0x";
+}
+
+/**
+ * Determines if a deposit was updated via a speed-up transaction.
+ * @param deposit Deposit to evaluate.
+ * @returns True if the deposit was updated, otherwise false.
+ */
+export function isDepositSpedUp(deposit: Deposit): boolean {
+  return isDefined(deposit.speedUpSignature) && isDefined(deposit.updatedOutputAmount);
+}
+
+/**
+ * Resolves the applicable message for a deposit.
+ * @param deposit Deposit to evaluate.
+ * @returns Original or updated message string, depending on whether the depositor updated the deposit.
+ */
+export function resolveDepositMessage(deposit: Deposit): string {
+  const message = isDepositSpedUp(deposit) ? deposit.updatedMessage : deposit.message;
+  assert(isDefined(message)); // Appease tsc about the updatedMessage being possibly undefined.
+  return message;
+}

package/src/utils/EventUtils.ts

@@ -0,0 +1,227 @@
+import { Result } from "@ethersproject/abi";
+import { delay } from "./common";
+import { SortableEvent } from "../interfaces";
+import { Contract, Event, EventFilter } from "ethers";
+
+const maxRetries = 3;
+const retrySleepTime = 10;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function spreadEvent(args: Result = {} as Result): any {
+  const keys = Object.keys(args).filter((key: string) => isNaN(+key)); // Extract non-numeric keys.
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const returnedObject: any = {};
+  keys.forEach((key: string) => {
+    switch (typeof args[key]) {
+      case "boolean": // fallthrough
+      case "number":
+      case "string":
+        returnedObject[key] = args[key];
+        break;
+      case "object":
+        if (Array.isArray(args[key])) {
+          returnedObject[key] =
+            Object.keys(args[key]).filter((key: string) => isNaN(+key)).length > 0
+              ? spreadEvent(args[key]) // Record/array hybrid...
+              : args[key]; // Just an array
+        } else {
+          returnedObject[key] = args[key];
+        }
+        break;
+    }
+  });
+
+  // ID information, if included in an event, should be cast to a number rather than a BigNumber.
+  if (returnedObject.groupIndex) {
+    returnedObject.groupIndex = Number(returnedObject.groupIndex);
+  }
+  if (returnedObject.leafId) {
+    returnedObject.leafId = Number(returnedObject.leafId);
+  }
+  if (returnedObject.chainId) {
+    returnedObject.chainId = Number(returnedObject.chainId);
+  }
+  if (returnedObject.destinationChainId) {
+    returnedObject.destinationChainId = Number(returnedObject.destinationChainId);
+  }
+  if (returnedObject.originChainId) {
+    returnedObject.originChainId = Number(returnedObject.originChainId);
+  }
+  if (returnedObject.repaymentChainId) {
+    returnedObject.repaymentChainId = Number(returnedObject.repaymentChainId);
+  }
+  if (returnedObject.l2ChainId) {
+    returnedObject.l2ChainId = Number(returnedObject.l2ChainId);
+  }
+  if (returnedObject.rootBundleId) {
+    returnedObject.rootBundleId = Number(returnedObject.rootBundleId);
+  }
+
+  return returnedObject;
+}
+
+export interface EventSearchConfig {
+  fromBlock: number;
+  toBlock: number;
+  maxBlockLookBack?: number;
+}
+
+export async function paginatedEventQuery(
+  contract: Contract,
+  filter: EventFilter,
+  searchConfig: EventSearchConfig,
+  retryCount = 0
+): Promise<Event[]> {
+  // If the max block look back is set to 0 then we dont need to do any pagination and can query over the whole range.
+  if (searchConfig.maxBlockLookBack === 0) {
+    return await contract.queryFilter(filter, searchConfig.fromBlock, searchConfig.toBlock);
+  }
+
+  // Compute the number of queries needed. If there is no maxBlockLookBack set then we can execute the whole query in
+  // one go. Else, the number of queries is the range over which we are searching, divided by the maxBlockLookBack,
+  // rounded up. This gives us the number of queries we need to execute to traverse the whole block range.
+  const paginatedRanges = getPaginatedBlockRanges(searchConfig);
+
+  try {
+    return (
+      (
+        await Promise.all(
+          paginatedRanges.map(([fromBlock, toBlock]) => contract.queryFilter(filter, fromBlock, toBlock))
+        )
+      )
+        .flat()
+        // Filter events by block number because ranges can include blocks that are outside the range specified for caching reasons.
+        .filter((event) => event.blockNumber >= searchConfig.fromBlock && event.blockNumber <= searchConfig.toBlock)
+    );
+  } catch (error) {
+    if (retryCount < maxRetries) {
+      await delay(retrySleepTime);
+      return await paginatedEventQuery(contract, filter, searchConfig, retryCount + 1);
+    } else {
+      throw error;
+    }
+  }
+}
+
+/**
+ * @dev Warning: this is a specialized function!! Its functionality is not obvious.
+ * This function attempts to return block ranges to repeat ranges as much as possible. To do so, it may include blocks that
+ * are outside the provided range. The guarantee is that it will always include _at least_ the blocks requested.
+ * @param eventSearchConfig contains fromBlock, toBlock, and maxBlockLookBack.
+ * The range is inclusive, so the results will include events in the fromBlock and in the toBlock.
+ * maxBlockLookback defined the maximum number of blocks to search. Because the range is inclusive, the maximum diff
+ * in the returned pairs is maxBlockLookBack - 1. This is a bit non-intuitive here, but this is meant so that this
+ * parameter more closely aligns with the more commonly understood definition of a max query range that node providers
+ * use.
+ * @returns an array of disjoint fromBlock, toBlock ranges that should be queried. These cover at least the entire
+ * input range, but can include blocks outside of the desired range, so results should be filtered. Results
+ * are ordered from smallest to largest.
+ */
+export function getPaginatedBlockRanges({
+  fromBlock,
+  toBlock,
+  maxBlockLookBack,
+}: EventSearchConfig): [number, number][] {
+  // If the maxBlockLookBack is undefined, we can look back as far as we like. Just return the entire range.
+  if (maxBlockLookBack === undefined) {
+    return [[fromBlock, toBlock]];
+  }
+
+  // If the fromBlock is > toBlock, then return no ranges.
+  if (fromBlock > toBlock) {
+    return [];
+  }
+
+  // A maxBlockLookBack of 0 is not allowed.
+  if (maxBlockLookBack <= 0) {
+    throw new Error("Cannot set maxBlockLookBack <= 0");
+  }
+
+  // Floor the requestedFromBlock to the nearest smaller multiple of the maxBlockLookBack to enhance caching.
+  // This means that a range like 5 - 45 with a maxBlockLookBack of 20 would look like:
+  // 0-19, 20-39, 40-45.
+  // This allows us to get the max number of repeated node queries. The maximum number of "nonstandard" queries per
+  // call of this function is 1.
+  const flooredStartBlock = Math.floor(fromBlock / maxBlockLookBack) * maxBlockLookBack;
+
+  // Note: range is inclusive, so we have to add one to the number of blocks to query.
+  const iterations = Math.ceil((toBlock + 1 - flooredStartBlock) / maxBlockLookBack);
+
+  const ranges: [number, number][] = [];
+  for (let i = 0; i < iterations; i++) {
+    // Each inner range start is just a multiple of the maxBlockLookBack added to the start block.
+    const innerFromBlock = flooredStartBlock + maxBlockLookBack * i;
+
+    // The innerFromBlock is just the max range from the innerFromBlock or the outer toBlock, whichever is smaller.
+    // The end block should never be larger than the outer toBlock. This is to avoid querying blocks that are in the
+    // future.
+    const innerToBlock = Math.min(innerFromBlock + maxBlockLookBack - 1, toBlock);
+    ranges.push([innerFromBlock, innerToBlock]);
+  }
+
+  return ranges;
+}
+
+export function spreadEventWithBlockNumber(event: Event): SortableEvent {
+  return {
+    ...spreadEvent(event.args),
+    blockNumber: event.blockNumber,
+    transactionIndex: event.transactionIndex,
+    logIndex: event.logIndex,
+    transactionHash: event.transactionHash,
+  };
+}
+
+// This copies the array and sorts it, returning a new array with the new ordering.
+export function sortEventsAscending<T extends SortableEvent>(events: T[]): T[] {
+  return sortEventsAscendingInPlace([...events]);
+}
+
+// This sorts the events in place, meaning it modifies the passed array and returns a reference to the same array.
+// Note: this method should only be used in cases where modifications are acceptable.
+export function sortEventsAscendingInPlace<T extends SortableEvent>(events: T[]): T[] {
+  return events.sort((ex, ey) => {
+    if (ex.blockNumber !== ey.blockNumber) {
+      return ex.blockNumber - ey.blockNumber;
+    }
+    if (ex.transactionIndex !== ey.transactionIndex) {
+      return ex.transactionIndex - ey.transactionIndex;
+    }
+    return ex.logIndex - ey.logIndex;
+  });
+}
+
+// This copies the array and sorts it, returning a new array with the new ordering.
+export function sortEventsDescending<T extends SortableEvent>(events: T[]): T[] {
+  return sortEventsDescendingInPlace([...events]);
+}
+
+// This sorts the events in place, meaning it modifies the passed array and returns a reference to the same array.
+// Note: this method should only be used in cases where modifications are acceptable.
+export function sortEventsDescendingInPlace<T extends SortableEvent>(events: T[]): T[] {
+  return events.sort((ex, ey) => {
+    if (ex.blockNumber !== ey.blockNumber) {
+      return ey.blockNumber - ex.blockNumber;
+    }
+    if (ex.transactionIndex !== ey.transactionIndex) {
+      return ey.transactionIndex - ex.transactionIndex;
+    }
+    return ey.logIndex - ex.logIndex;
+  });
+}
+
+// Returns true if ex is older than ey.
+export function isEventOlder<T extends SortableEvent>(ex: T, ey: T): boolean {
+  if (ex.blockNumber !== ey.blockNumber) {
+    return ex.blockNumber < ey.blockNumber;
+  }
+  if (ex.transactionIndex !== ey.transactionIndex) {
+    return ex.transactionIndex < ey.transactionIndex;
+  }
+  return ex.logIndex < ey.logIndex;
+}
+
+export function getTransactionHashes(events: SortableEvent[]): string[] {
+  return [...Array.from(new Set(events.map((e) => e.transactionHash)))];
+}

package/src/utils/FlowUtils.ts

@@ -0,0 +1,48 @@
+import { Deposit, Fill, RelayData, SlowFillRequest } from "../interfaces";
+import { getRelayDataHash } from "./SpokeUtils";
+
+export const FILL_DEPOSIT_COMPARISON_KEYS = [
+  "depositId",
+  "originChainId",
+  "destinationChainId",
+  "depositor",
+  "recipient",
+  "message",
+] as const;
+
+export const V3_DEPOSIT_COMPARISON_KEYS = [
+  ...FILL_DEPOSIT_COMPARISON_KEYS,
+  "inputToken",
+  "inputAmount",
+  "outputToken",
+  "outputAmount",
+  "fillDeadline",
+  "exclusivityDeadline",
+  "exclusiveRelayer",
+] as const;
+
+export function filledSameDeposit(fillA: Fill, fillB: Fill): boolean {
+  // Don't bother hashing obvious mismatches.
+  if (fillA.depositId !== fillB.depositId) {
+    return false;
+  }
+
+  const { destinationChainId: chainA } = fillA;
+  const { destinationChainId: chainB } = fillB;
+  return getRelayDataHash(fillA, chainA) === getRelayDataHash(fillB, chainB);
+}
+
+export function validateFillForDeposit(
+  relayData: RelayData & { destinationChainId: number }, // V3Fill, SlowFillRequest...
+  deposit?: Deposit
+): boolean {
+  if (deposit === undefined) {
+    return false;
+  }
+
+  return validateV3FillForDeposit(relayData, deposit);
+}
+
+function validateV3FillForDeposit(fill: Fill | SlowFillRequest, deposit: Deposit): boolean {
+  return getRelayDataHash(fill, fill.destinationChainId) === getRelayDataHash(deposit, deposit.destinationChainId);
+}