@across-protocol/sdk 4.3.53 → 4.3.55

package/src/clients/HubPoolClient.ts

@@ -193,14 +193,14 @@ export class HubPoolClient extends BaseAbstractClient {
     destinationChainId: number,
     latestHubBlock = Number.MAX_SAFE_INTEGER
   ): Address {
-    if (!this.l1TokensToDestinationTokensWithBlock?.[l1Token.toEvmAddress()]?.[destinationChainId]) {
+    if (!this.l1TokensToDestinationTokensWithBlock?.[l1Token.toNative()]?.[destinationChainId]) {
       const chain = getNetworkName(destinationChainId);
       const { symbol } = this.l1Tokens.find(({ address }) => address.eq(l1Token)) ?? { symbol: l1Token.toString() };
       throw new Error(`Could not find SpokePool mapping for ${symbol} on ${chain} and L1 token ${l1Token}`);
     }
     // Find the last mapping published before the target block.
     const l2Token: DestinationTokenWithBlock | undefined = sortEventsDescending(
-      this.l1TokensToDestinationTokensWithBlock[l1Token.toEvmAddress()][destinationChainId]
+      this.l1TokensToDestinationTokensWithBlock[l1Token.toNative()][destinationChainId]
     ).find((mapping: DestinationTokenWithBlock) => mapping.blockNumber <= latestHubBlock);
     if (!l2Token) {
       const chain = getNetworkName(destinationChainId);
@@ -250,13 +250,13 @@ export class HubPoolClient extends BaseAbstractClient {
   }
 
   l2TokenEnabledForL1Token(l1Token: EvmAddress, destinationChainId: number): boolean {
-    return this.l1TokensToDestinationTokens?.[l1Token.toEvmAddress()]?.[destinationChainId] != undefined;
+    return this.l1TokensToDestinationTokens?.[l1Token.toNative()]?.[destinationChainId] != undefined;
   }
 
   l2TokenEnabledForL1TokenAtBlock(l1Token: EvmAddress, destinationChainId: number, hubBlockNumber: number): boolean {
     // Find the last mapping published before the target block.
     const l2Token: DestinationTokenWithBlock | undefined = sortEventsDescending(
-      this.l1TokensToDestinationTokensWithBlock?.[l1Token.toEvmAddress()]?.[destinationChainId] ?? []
+      this.l1TokensToDestinationTokensWithBlock?.[l1Token.toNative()]?.[destinationChainId] ?? []
     ).find((mapping: DestinationTokenWithBlock) => mapping.blockNumber <= hubBlockNumber);
     return l2Token !== undefined;
   }
@@ -340,18 +340,14 @@ export class HubPoolClient extends BaseAbstractClient {
     timeToCache: number
   ): Promise<BigNumber> {
     // Resolve this function call as an async anonymous function
-    const resolver = async () => {
+    const resolver = () => {
       const overrides = { blockTag: blockNumber };
-      if (depositAmount.eq(0)) {
-        // For zero amount, just get the utilisation at `blockNumber`.
-        return await this.hubPool.callStatic.liquidityUtilizationCurrent(hubPoolToken.toEvmAddress(), overrides);
-      }
+      const token = hubPoolToken.toNative();
 
-      return await this.hubPool.callStatic.liquidityUtilizationPostRelay(
-        hubPoolToken.toEvmAddress(),
-        depositAmount,
-        overrides
-      );
+      // For zero amount, just get the utilisation at `blockNumber`.
+      return depositAmount.eq(bnZero)
+        ? this.hubPool.callStatic.liquidityUtilizationCurrent(token, overrides)
+        : this.hubPool.callStatic.liquidityUtilizationPostRelay(token, depositAmount, overrides);
     };
 
     // Resolve the cache locally so that we can appease typescript
@@ -363,11 +359,9 @@ export class HubPoolClient extends BaseAbstractClient {
     }
 
     // Otherwise, let's resolve the key
-    // @note Avoid collisions with pre-existing cache keys by appending an underscore (_) for post-relay utilization.
-    // @fixme This can be removed once the existing keys have been ejected from the cache (i.e. 7 days).
-    const key = depositAmount.eq(0)
-      ? `utilization_${hubPoolToken.toEvmAddress()}_${blockNumber}`
-      : `utilization_${hubPoolToken.toEvmAddress()}_${blockNumber}_${depositAmount.toString()}_`;
+    const key = depositAmount.eq(bnZero)
+      ? `utilization_${hubPoolToken.toNative()}_${blockNumber}`
+      : `utilization_${hubPoolToken.toNative()}_${blockNumber}_${depositAmount.toString()}`;
     const result = await cache.get<string>(key);
     if (isDefined(result)) {
       return BigNumber.from(result);
@@ -409,9 +403,19 @@ export class HubPoolClient extends BaseAbstractClient {
       const tokenKey = `${deposit.originChainId}-${deposit.inputToken}`;
       if (this.l2TokenHasPoolRebalanceRoute(deposit.inputToken, deposit.originChainId, quoteBlockNumber)) {
         return (hubPoolTokens[tokenKey] ??= this.getL1TokenForDeposit({ ...deposit, quoteBlockNumber }));
-      } else return undefined;
+      }
+
+      return undefined;
     };
-    const getHubPoolTokens = (): EvmAddress[] => dedupArray(Object.values(hubPoolTokens).filter(isDefined));
+
+    // Filter hubPoolTokens for duplicates by reverting to their native string
+    // representation. This is required for deduplication to work reliably.
+    const getHubPoolTokens = (): EvmAddress[] =>
+      dedupArray(
+        Object.values(hubPoolTokens)
+          .filter(isDefined)
+          .map((token) => token.toNative())
+      ).map((token) => EvmAddress.from(token));
 
     // Helper to resolve the unqiue hubPoolToken & quoteTimestamp mappings.
     const resolveUniqueQuoteTimestamps = (deposit: LpFeeRequest): void => {
@@ -425,9 +429,10 @@ export class HubPoolClient extends BaseAbstractClient {
       }
 
       // Append the quoteTimestamp for this HubPool token, if it isn't already enqueued.
-      utilizationTimestamps[hubPoolToken.toEvmAddress()] ??= [];
-      if (!utilizationTimestamps[hubPoolToken.toEvmAddress()].includes(quoteTimestamp)) {
-        utilizationTimestamps[hubPoolToken.toEvmAddress()].push(quoteTimestamp);
+      const token = hubPoolToken.toNative();
+      utilizationTimestamps[token] ??= [];
+      if (!utilizationTimestamps[token].includes(quoteTimestamp)) {
+        utilizationTimestamps[token].push(quoteTimestamp);
       }
     };
 
@@ -435,7 +440,7 @@ export class HubPoolClient extends BaseAbstractClient {
     // Produces a mapping of blockNumber -> utilization for a specific token.
     const resolveUtilization = async (hubPoolToken: EvmAddress): Promise<Record<number, BigNumber>> => {
       return Object.fromEntries(
-        await mapAsync(utilizationTimestamps[hubPoolToken.toEvmAddress()], async (quoteTimestamp) => {
+        await mapAsync(utilizationTimestamps[hubPoolToken.toNative()], async (quoteTimestamp) => {
           const blockNumber = quoteBlocks[quoteTimestamp];
           const utilization = await this.getUtilization(
             hubPoolToken,
@@ -471,7 +476,7 @@ export class HubPoolClient extends BaseAbstractClient {
         quoteBlock
       );
 
-      const preUtilization = utilization[hubPoolToken.toEvmAddress()][quoteBlock];
+      const preUtilization = utilization[hubPoolToken.toNative()][quoteBlock];
       const postUtilization = await this.getUtilization(
         hubPoolToken,
         quoteBlock,
@@ -500,7 +505,7 @@ export class HubPoolClient extends BaseAbstractClient {
     // This can be reused for each deposit with the same HubPool token and quoteTimestamp pair.
     utilization = Object.fromEntries(
       await mapAsync(getHubPoolTokens(), async (hubPoolToken) => [
-        hubPoolToken.toEvmAddress(),
+        hubPoolToken.toNative(),
         await resolveUtilization(hubPoolToken),
       ])
     );
@@ -529,7 +534,7 @@ export class HubPoolClient extends BaseAbstractClient {
   }
 
   getLpTokenInfoForL1Token(l1Token: EvmAddress): LpToken | undefined {
-    return this.lpTokens[l1Token.toEvmAddress()];
+    return this.lpTokens[l1Token.toNative()];
   }
 
   areTokensEquivalent(
@@ -925,6 +930,7 @@ export class HubPoolClient extends BaseAbstractClient {
     if (!this.configStoreClient.isUpdated) {
       throw new Error("ConfigStoreClient not updated");
     }
+
     const update = await this._update(eventsToQuery);
     if (!update.success) {
       if (update.reason !== UpdateFailureReason.AlreadyUpdated) {

package/src/clients/SpokePoolClient/EVMSpokePoolClient.ts

@@ -11,13 +11,12 @@ import { DepositWithBlock, FillStatus, RelayData } from "../../interfaces";
 import {
   BigNumber,
   DepositSearchResult,
-  getMessageHash,
   getNetworkName,
   InvalidFill,
   MakeOptional,
   toBN,
   EvmAddress,
-  toAddressType,
+  unpackDepositEvent,
 } from "../../utils";
 import {
   EventSearchConfig,
@@ -195,37 +194,19 @@ export class EVMSpokePoolClient extends SpokePoolClient {
       };
     }
 
-    const spreadEvent = spreadEventWithBlockNumber(event) as Omit<
-      DepositWithBlock,
-      "originChainId" | "inputToken" | "outputToken" | "depositor" | "recipient" | "exclusiveRelayer"
-    > & {
-      inputToken: string;
-      outputToken: string;
-      depositor: string;
-      recipient: string;
-      exclusiveRelayer: string;
-    };
+    const partialDeposit = unpackDepositEvent(spreadEventWithBlockNumber(event), this.chainId);
+    const quoteBlockNumber = await this.getBlockNumber(partialDeposit.quoteTimestamp);
+    const outputToken = partialDeposit.outputToken.isZeroAddress()
+      ? this.getDestinationTokenForDeposit({ ...partialDeposit, quoteBlockNumber })
+      : partialDeposit.outputToken;
 
-    const originChainId = this.chainId;
     deposit = {
-      ...spreadEvent,
-      originChainId: this.chainId,
-      inputToken: toAddressType(spreadEvent.inputToken, originChainId),
-      outputToken: toAddressType(spreadEvent.outputToken, spreadEvent.destinationChainId),
-      depositor: toAddressType(spreadEvent.depositor, originChainId),
-      recipient: toAddressType(spreadEvent.recipient, spreadEvent.destinationChainId),
-      exclusiveRelayer: toAddressType(spreadEvent.exclusiveRelayer, spreadEvent.destinationChainId),
-      quoteBlockNumber: await this.getBlockNumber(spreadEvent.quoteTimestamp),
-      messageHash: getMessageHash(spreadEvent.message),
-      fromLiteChain: true, // To be updated immediately afterwards.
-      toLiteChain: true, // To be updated immediately afterwards.
-    };
-
-    if (deposit.outputToken.isZeroAddress()) {
-      deposit.outputToken = this.getDestinationTokenForDeposit(deposit);
-    }
-    deposit.fromLiteChain = this.isOriginLiteChain(deposit);
-    deposit.toLiteChain = this.isDestinationLiteChain(deposit);
+      ...partialDeposit,
+      outputToken,
+      quoteBlockNumber,
+      fromLiteChain: this.isOriginLiteChain(partialDeposit),
+      toLiteChain: this.isDestinationLiteChain(partialDeposit),
+    } satisfies DepositWithBlock;
 
     this.logger.debug({
       at: "SpokePoolClient#findDeposit",

package/src/clients/SpokePoolClient/SVMSpokePoolClient.ts

@@ -227,15 +227,16 @@ export class SVMSpokePoolClient extends SpokePoolClient {
       };
     }
 
-    // Because we have additional context about this deposit, we can enrich it
-    // with additional information.
+    // Because we have additional context about this deposit, we can enrich it with additional information.
+    // outputToken is known to not be 0x0 on SVM SpokePool implementations.
+    const originChainId = this.chainId;
     return {
       found: true,
       deposit: {
         ...deposit,
+        originChainId,
         quoteBlockNumber: await this.getBlockNumber(Number(deposit.quoteTimestamp)),
-        originChainId: this.chainId,
-        fromLiteChain: this.isOriginLiteChain(deposit),
+        fromLiteChain: this.isOriginLiteChain({ ...deposit, originChainId }),
         toLiteChain: this.isDestinationLiteChain(deposit),
       },
     };

package/src/clients/SpokePoolClient/SpokePoolClient.ts

@@ -13,13 +13,14 @@ import {
   assign,
   getRelayEventKey,
   isDefined,
-  getMessageHash,
   isSlowFill,
   validateFillForDeposit,
   chainIsEvm,
   chainIsProd,
   Address,
   toAddressType,
+  unpackDepositEvent,
+  unpackFillEvent,
 } from "../../utils";
 import { duplicateEvent, sortEventsAscendingInPlace } from "../../utils/EventUtils";
 import { CHAIN_IDs, ZERO_ADDRESS } from "../../constants";
@@ -39,7 +40,6 @@ import {
   SortableEvent,
   SpeedUpWithBlock,
   TokensBridged,
-  RelayExecutionEventInfo,
 } from "../../interfaces";
 import { BaseAbstractClient, UpdateFailureReason } from "../BaseAbstractClient";
 import { AcrossConfigStoreClient } from "../AcrossConfigStoreClient";
@@ -463,7 +463,9 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
     return `${event.depositId.toString()}-${event.originChainId}`;
   }
 
-  protected canResolveZeroAddressOutputToken(deposit: DepositWithBlock): boolean {
+  protected canResolveZeroAddressOutputToken(
+    deposit: Pick<DepositWithBlock, "originChainId" | "inputToken" | "quoteBlockNumber" | "destinationChainId">
+  ): boolean {
     if (
       !this.hubPoolClient?.l2TokenHasPoolRebalanceRoute(
         deposit.inputToken,
@@ -519,39 +521,10 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
     }
 
     // Performs the indexing of a deposit-like spoke pool event.
-    const originChainId = this.chainId;
     const queryDepositEvents = async (eventName: string) => {
-      const depositEvents = (queryResults[eventsToQuery.indexOf(eventName)] ?? []).map((_event) => {
-        const event = _event as Omit<
-          DepositWithBlock,
-          "originChainId" | "depositor" | "recipient" | "inputToken" | "outputToken" | "exclusiveRelayer"
-        > & {
-          depositor: string;
-          recipient: string;
-          inputToken: string;
-          outputToken: string;
-          exclusiveRelayer: string;
-        };
-        return {
-          ...event,
-          originChainId,
-          depositor: toAddressType(event.depositor, originChainId),
-          recipient: toAddressType(event.recipient, event.destinationChainId),
-          inputToken: toAddressType(event.inputToken, originChainId),
-          outputToken: toAddressType(event.outputToken, event.destinationChainId),
-          exclusiveRelayer: toAddressType(event.exclusiveRelayer, event.destinationChainId),
-          messageHash: getMessageHash(event.message),
-        } satisfies Omit<DepositWithBlock, "quoteBlockNumber" | "fromLiteChain" | "toLiteChain">;
-      });
-      if (depositEvents.length > 0) {
-        this.log(
-          "debug",
-          `Using ${depositEvents.length} newly queried ${eventName} deposit events for chain ${this.chainId}`,
-          {
-            earliestEvent: depositEvents[0].blockNumber,
-          }
-        );
-      }
+      const depositEvents = (queryResults[eventsToQuery.indexOf(eventName)] ?? []).map((event) =>
+        unpackDepositEvent(event, this.chainId)
+      );
 
       // For each deposit, resolve its quoteTimestamp to a block number on the HubPool.
       // Don't bother filtering for uniqueness; the HubPoolClient handles this efficienctly.
@@ -560,16 +533,17 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
         const quoteBlockNumber = quoteBlockNumbers[Number(event.quoteTimestamp)];
 
         // Derive and append the common properties that are not part of the onchain event.
+        const outputToken = event.outputToken.isZeroAddress()
+          ? this.getDestinationTokenForDeposit({ ...event, quoteBlockNumber })
+          : event.outputToken;
+
         const deposit = {
           ...event,
+          outputToken,
           quoteBlockNumber,
           fromLiteChain: this.isOriginLiteChain(event),
           toLiteChain: this.isDestinationLiteChain(event),
-        };
-
-        if (deposit.outputToken.isZeroAddress()) {
-          deposit.outputToken = this.getDestinationTokenForDeposit(deposit);
-        }
+        } satisfies DepositWithBlock;
 
         if (this.depositHashes[getRelayEventKey(deposit)] !== undefined) {
           // Sanity check that this event is not a duplicate, even though the relay data hash is a duplicate.
@@ -645,6 +619,7 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
 
     // Performs indexing of "requested slow fill"-like events.
     const queryRequestedSlowFillEvents = (eventName: string) => {
+      const destinationChainId = this.chainId;
       const slowFillRequests = (queryResults[eventsToQuery.indexOf(eventName)] ?? []).map((_event) => {
         const event = _event as Omit<
           SlowFillRequestWithBlock,
@@ -658,24 +633,21 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
         };
         return {
           ...event,
+          destinationChainId,
           depositor: toAddressType(event.depositor, event.originChainId),
-          recipient: toAddressType(event.recipient, this.chainId),
+          recipient: toAddressType(event.recipient, destinationChainId),
           inputToken: toAddressType(event.inputToken, event.originChainId),
-          outputToken: toAddressType(event.outputToken, this.chainId),
-          exclusiveRelayer: toAddressType(event.exclusiveRelayer, this.chainId),
-        } as SlowFillRequestWithBlock;
+          outputToken: toAddressType(event.outputToken, destinationChainId),
+          exclusiveRelayer: toAddressType(event.exclusiveRelayer, destinationChainId),
+        } satisfies SlowFillRequestWithBlock;
       });
-      for (const event of slowFillRequests) {
-        const slowFillRequest = {
-          ...event,
-          destinationChainId: this.chainId,
-        };
 
-        const depositHash = getRelayEventKey({ ...slowFillRequest, destinationChainId: this.chainId });
+      for (const slowFillRequest of slowFillRequests) {
+        const depositHash = getRelayEventKey(slowFillRequest);
 
         // Sanity check that this event is not a duplicate.
         if (this.slowFillRequests[depositHash] !== undefined) {
-          duplicateEvents.push(event);
+          duplicateEvents.push(slowFillRequest);
           continue;
         }
 
@@ -690,45 +662,10 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
     });
 
     // Performs indexing of filled relay-like events.
-    const destinationChainId = this.chainId;
     const queryFilledRelayEvents = (eventName: string) => {
-      const fillEvents = (queryResults[eventsToQuery.indexOf(eventName)] ?? []).map((_event) => {
-        const event = _event as Omit<
-          FillWithBlock,
-          | "destinationChainId"
-          | "depositor"
-          | "recipient"
-          | "inputToken"
-          | "outputToken"
-          | "exclusiveRelayer"
-          | "relayer"
-          | "relayExecutionInfo"
-        > & {
-          depositor: string;
-          recipient: string;
-          inputToken: string;
-          outputToken: string;
-          exclusiveRelayer: string;
-          relayer: string;
-          relayExecutionInfo: Omit<RelayExecutionEventInfo, "updatedRecipient"> & { updatedRecipient: string };
-        };
-
-        return {
-          ...event,
-          destinationChainId,
-          depositor: toAddressType(event.depositor, event.originChainId),
-          recipient: toAddressType(event.recipient, destinationChainId),
-          inputToken: toAddressType(event.inputToken, event.originChainId),
-          outputToken: toAddressType(event.outputToken, destinationChainId),
-          exclusiveRelayer: toAddressType(event.exclusiveRelayer, destinationChainId),
-          relayer: toAddressType(event.relayer, event.repaymentChainId),
-          relayExecutionInfo: {
-            ...event.relayExecutionInfo,
-            updatedRecipient: toAddressType(event.relayExecutionInfo.updatedRecipient, this.chainId),
-          },
-        } satisfies FillWithBlock;
-      });
-
+      const fillEvents = (queryResults[eventsToQuery.indexOf(eventName)] ?? []).map((event) =>
+        unpackFillEvent(event, this.chainId)
+      );
       if (fillEvents.length > 0) {
         this.log("debug", `Using ${fillEvents.length} newly queried ${eventName} events for chain ${this.chainId}`, {
           earliestEvent: fillEvents[0].blockNumber,
@@ -858,7 +795,9 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
    * @param deposit The deposit to retrieve the destination token for.
    * @returns The destination token.
    */
-  protected getDestinationTokenForDeposit(deposit: DepositWithBlock): Address {
+  protected getDestinationTokenForDeposit(
+    deposit: Pick<DepositWithBlock, "originChainId" | "inputToken" | "quoteBlockNumber" | "destinationChainId">
+  ): Address {
     if (!this.canResolveZeroAddressOutputToken(deposit)) {
       return toAddressType(ZERO_ADDRESS, CHAIN_IDs.MAINNET);
     }
@@ -900,7 +839,7 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
    * @returns True if the deposit originates from a lite chain, false otherwise. If the hub pool client is not defined,
    *          this method will return false.
    */
-  protected isOriginLiteChain(deposit: DepositWithBlock): boolean {
+  protected isOriginLiteChain(deposit: Pick<DepositWithBlock, "originChainId" | "quoteTimestamp">): boolean {
     return this.configStoreClient?.isChainLiteChainAtTimestamp(deposit.originChainId, deposit.quoteTimestamp) ?? false;
   }
 
@@ -910,7 +849,7 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
    * @returns True if the deposit is destined to a lite chain, false otherwise. If the hub pool client is not defined,
    *          this method will return false.
    */
-  protected isDestinationLiteChain(deposit: DepositWithBlock): boolean {
+  protected isDestinationLiteChain(deposit: Pick<DepositWithBlock, "destinationChainId" | "quoteTimestamp">): boolean {
     return (
       this.configStoreClient?.isChainLiteChainAtTimestamp(deposit.destinationChainId, deposit.quoteTimestamp) ?? false
     );

package/src/constants.ts

@@ -57,7 +57,7 @@ export const DEFAULT_CACHING_TTL = 60 * 60 * 24 * 7 * 2; // 2 Weeks
 export const DEFAULT_CACHING_SAFE_LAG = 60 * 60; // 1 hour
 
 export const DEFAULT_SIMULATED_RELAYER_ADDRESS = "0x07aE8551Be970cB1cCa11Dd7a11F47Ae82e70E67";
-export const DEFAULT_SIMULATED_RELAYER_ADDRESS_SVM = "FmMK62wrtWVb5SVoTZftSCGw3nEDA79hDbZNTRnC1R6t";
+export const DEFAULT_SIMULATED_RELAYER_ADDRESS_SVM = "E4bX4nCwe2GcKqt9NpofnXVrCeRp37PAMaiZtV9x3kxC";
 export const DEFAULT_SIMULATED_RELAYER_ADDRESS_TEST = "0x9A8f92a830A5cB89a3816e3D267CB7791c16b04D"; // Görli, ...
 
 export const DEFAULT_ARWEAVE_STORAGE_ADDRESS = "Z6hjBM8FHu90lYWB8o5jR1dfX92FlV2WBaND9xgp8Lg";

package/src/utils/SpokeUtils.ts

@@ -1,11 +1,21 @@
 import { encodeAbiParameters, Hex, keccak256 } from "viem";
 import { fixedPointAdjustment as fixedPoint } from "./common";
 import { MAX_SAFE_DEPOSIT_ID, ZERO_BYTES } from "../constants";
-import { Fill, FillType, RelayData, SlowFillLeaf } from "../interfaces";
+import {
+  DepositWithBlock,
+  Fill,
+  FillWithBlock,
+  FillType,
+  RelayData,
+  RelayExecutionEventInfo,
+  SlowFillLeaf,
+  SortableEvent,
+} from "../interfaces";
+import { svm } from "../arch";
 import { BigNumber } from "./BigNumberUtils";
 import { isMessageEmpty } from "./DepositUtils";
 import { chainIsSvm } from "./NetworkUtils";
-import { svm } from "../arch";
+import { toAddressType } from "./AddressUtils";
 
 export function isSlowFill(fill: Fill): boolean {
   return fill.relayExecutionInfo.fillType === FillType.SlowFill;
@@ -15,6 +25,92 @@ export function getSlowFillLeafLpFeePct(leaf: SlowFillLeaf): BigNumber {
   const { relayData, updatedOutputAmount } = leaf;
   return relayData.inputAmount.sub(updatedOutputAmount).mul(fixedPoint).div(relayData.inputAmount);
 }
+
+/**
+ * Given a SortableEvent type, unpack the available FundsDeposited fields.
+ * @note Some fields cannot be evaluated without additional context - i.e. quoteBlockNumber, {from,to}LiteChain.
+ * @param rawEvent emitted by FundsDeposited event.
+ * @param originChainId Deposit originChainId
+ * @returns A mostly-populated DepositWithBlock event.
+ */
+export function unpackDepositEvent(
+  rawEvent: SortableEvent,
+  originChainId: number
+): Omit<DepositWithBlock, "quoteBlockNumber" | "fromLiteChain" | "toLiteChain"> {
+  const event = rawEvent as Omit<
+    DepositWithBlock,
+    | "originChainId"
+    | "depositor"
+    | "recipient"
+    | "inputToken"
+    | "outputToken"
+    | "exclusiveRelayer"
+    | "quoteBlockNumber"
+    | "fromLiteChain"
+    | "toLiteChain"
+  > & {
+    depositor: string;
+    recipient: string;
+    inputToken: string;
+    outputToken: string;
+    exclusiveRelayer: string;
+  };
+
+  return {
+    ...event,
+    originChainId,
+    depositor: toAddressType(event.depositor, originChainId),
+    recipient: toAddressType(event.recipient, event.destinationChainId),
+    inputToken: toAddressType(event.inputToken, originChainId),
+    outputToken: toAddressType(event.outputToken, event.destinationChainId),
+    exclusiveRelayer: toAddressType(event.exclusiveRelayer, event.destinationChainId),
+    messageHash: getMessageHash(event.message),
+  } satisfies Omit<DepositWithBlock, "quoteBlockNumber" | "fromLiteChain" | "toLiteChain">;
+}
+
+/**
+ * Given a SortableEvent type, unpack the complete set of FilledRelay fields.
+ * @param rawEvent emitted by FundsDeposited event.
+ * @param originChainId Deposit originChainId
+ * @returns A mostly-populated DepositWithBlock event.
+ */
+export function unpackFillEvent(rawEvent: SortableEvent, destinationChainId: number): FillWithBlock {
+  const event = rawEvent as Omit<
+    FillWithBlock,
+    | "destinationChainId"
+    | "depositor"
+    | "recipient"
+    | "inputToken"
+    | "outputToken"
+    | "exclusiveRelayer"
+    | "relayer"
+    | "relayerExecutionInfo"
+  > & {
+    depositor: string;
+    recipient: string;
+    inputToken: string;
+    outputToken: string;
+    exclusiveRelayer: string;
+    relayer: string;
+    relayExecutionInfo: Omit<RelayExecutionEventInfo, "updatedRecipient"> & { updatedRecipient: string };
+  };
+
+  return {
+    ...event,
+    destinationChainId,
+    depositor: toAddressType(event.depositor, event.originChainId),
+    recipient: toAddressType(event.recipient, destinationChainId),
+    inputToken: toAddressType(event.inputToken, event.originChainId),
+    outputToken: toAddressType(event.outputToken, destinationChainId),
+    exclusiveRelayer: toAddressType(event.exclusiveRelayer, destinationChainId),
+    relayer: toAddressType(event.relayer, event.repaymentChainId),
+    relayExecutionInfo: {
+      ...event.relayExecutionInfo,
+      updatedRecipient: toAddressType(event.relayExecutionInfo.updatedRecipient, destinationChainId),
+    },
+  } satisfies FillWithBlock;
+}
+
 /**
  * Compute the RelayData hash for a fill. This can be used to determine the fill status.
  * @param relayData RelayData information that is used to complete a fill.