@across-protocol/sdk 3.0.0

package/src/interfaces/HubPool.ts

@@ -0,0 +1,118 @@
+import { BigNumber } from "ethers";
+import { SortableEvent } from "./Common";
+
+export interface PoolRebalanceLeaf {
+  chainId: number;
+  groupIndex: number;
+  bundleLpFees: BigNumber[];
+  netSendAmounts: BigNumber[];
+  runningBalances: BigNumber[];
+  leafId: number;
+  l1Tokens: string[];
+}
+
+export interface RelayerRefundLeaf {
+  amountToReturn: BigNumber;
+  chainId: number;
+  refundAmounts: BigNumber[];
+  leafId: number;
+  l2TokenAddress: string;
+  refundAddresses: string[];
+}
+
+export interface ProposedRootBundle extends SortableEvent {
+  challengePeriodEndTimestamp: number;
+  poolRebalanceLeafCount: number;
+  bundleEvaluationBlockNumbers: BigNumber[];
+  poolRebalanceRoot: string;
+  relayerRefundRoot: string;
+  slowRelayRoot: string;
+  proposer: string;
+}
+
+export type RealizedLpFee = {
+  quoteBlock: number;
+  realizedLpFeePct: BigNumber;
+};
+
+export type ProposedRootBundleStringified = Omit<ProposedRootBundle, "bundleEvaluationBlockNumbers"> & {
+  bundleEvaluationBlockNumbers: string[];
+};
+
+export interface CancelledRootBundle extends SortableEvent {
+  disputer: string;
+  requestTime: number;
+}
+
+export interface DisputedRootBundle extends SortableEvent {
+  disputer: string;
+  requestTime: number;
+}
+
+export interface ExecutedRootBundle extends SortableEvent {
+  chainId: number;
+  bundleLpFees: BigNumber[];
+  netSendAmounts: BigNumber[];
+  runningBalances: BigNumber[];
+  incentiveBalances: BigNumber[];
+  leafId: number;
+  l1Tokens: string[];
+  proof: string[];
+}
+
+export type ExecutedRootBundleStringified = Omit<
+  ExecutedRootBundle,
+  "bundleLpFees" | "netSendAmounts" | "runningBalances" | "incentiveBalances"
+> & {
+  bundleLpFees: string[];
+  netSendAmounts: string[];
+  runningBalances: string[];
+  incentiveBalances: string[];
+};
+
+export type TokenRunningBalance = {
+  runningBalance: BigNumber;
+  incentiveBalance: BigNumber;
+};
+
+export interface RelayerRefundLeafWithGroup extends RelayerRefundLeaf {
+  groupIndex: number;
+}
+
+export interface L1Token {
+  address: string;
+  symbol: string;
+  decimals: number;
+}
+
+export interface LpToken {
+  lastLpFeeUpdate: number;
+  liquidReserves: BigNumber;
+}
+
+export interface CrossChainContractsSet extends SortableEvent {
+  l2ChainId: number;
+  spokePool: string;
+}
+
+export interface DestinationTokenWithBlock extends SortableEvent {
+  l2Token: string;
+  l1Token: string;
+}
+
+export interface SetPoolRebalanceRoot extends SortableEvent {
+  destinationChainId: number;
+  l1Token: string;
+  destinationToken: string;
+}
+
+export interface PendingRootBundle {
+  poolRebalanceRoot: string;
+  relayerRefundRoot: string;
+  slowRelayRoot: string;
+  proposer: string;
+  unclaimedPoolRebalanceLeafCount: number;
+  challengePeriodEndTimestamp: number;
+  bundleEvaluationBlockNumbers: number[];
+  proposalBlockNumber?: number;
+}

package/src/interfaces/SpokePool.ts

@@ -0,0 +1,119 @@
+import { BigNumber } from "ethers";
+import { SortableEvent } from "./Common";
+import { FilledRelayEvent, FilledV3RelayEvent, FundsDepositedEvent, V3FundsDepositedEvent } from "../typechain";
+import { SpokePoolClient } from "../clients";
+import { RelayerRefundLeaf } from "./HubPool";
+
+export type { FilledRelayEvent, FilledV3RelayEvent, FundsDepositedEvent, V3FundsDepositedEvent };
+
+export interface RelayData {
+  originChainId: number;
+  depositor: string;
+  recipient: string;
+  depositId: number;
+  inputToken: string;
+  inputAmount: BigNumber;
+  outputToken: string;
+  outputAmount: BigNumber;
+  message: string;
+  fillDeadline: number;
+  exclusiveRelayer: string;
+  exclusivityDeadline: number;
+}
+
+export interface Deposit extends RelayData {
+  destinationChainId: number;
+  quoteTimestamp: number;
+  speedUpSignature?: string;
+  updatedRecipient?: string;
+  updatedOutputAmount?: BigNumber;
+  updatedMessage?: string;
+}
+
+export interface DepositWithBlock extends Deposit, SortableEvent {
+  quoteBlockNumber: number;
+}
+
+export enum FillStatus {
+  Unfilled = 0,
+  RequestedSlowFill,
+  Filled,
+}
+
+export enum FillType {
+  FastFill = 0,
+  ReplacedSlowFill,
+  SlowFill,
+}
+
+export interface RelayExecutionEventInfo {
+  updatedRecipient: string;
+  updatedOutputAmount: BigNumber;
+  updatedMessage: string;
+  fillType: FillType;
+}
+
+export interface Fill extends RelayData {
+  destinationChainId: number;
+  relayer: string;
+  repaymentChainId: number;
+  relayExecutionInfo: RelayExecutionEventInfo;
+}
+
+export interface FillWithBlock extends Fill, SortableEvent {}
+
+export interface SpeedUp {
+  depositor: string;
+  depositorSignature: string;
+  depositId: number;
+  originChainId: number;
+  updatedRecipient: string;
+  updatedOutputAmount: BigNumber;
+  updatedMessage: string;
+}
+
+export interface SlowFillRequest extends RelayData {
+  destinationChainId: number;
+}
+export interface SlowFillRequestWithBlock extends SlowFillRequest, SortableEvent {}
+
+export interface SlowFillLeaf {
+  relayData: RelayData;
+  chainId: number;
+  updatedOutputAmount: BigNumber;
+}
+
+export interface RootBundleRelay {
+  rootBundleId: number;
+  relayerRefundRoot: string;
+  slowRelayRoot: string;
+}
+
+export interface RootBundleRelayWithBlock extends RootBundleRelay, SortableEvent {}
+
+export interface RelayerRefundExecution extends RelayerRefundLeaf {
+  rootBundleId: number;
+}
+
+export interface RelayerRefundExecutionWithBlock extends RelayerRefundExecution, SortableEvent {}
+
+export interface Refund {
+  [refundAddress: string]: BigNumber;
+}
+
+export interface RunningBalances {
+  [repaymentChainId: number]: {
+    [l1TokenAddress: string]: BigNumber;
+  };
+}
+
+export interface TokensBridged extends SortableEvent {
+  amountToReturn: BigNumber;
+  chainId: number;
+  leafId: number;
+  l2TokenAddress: string;
+}
+
+export interface SpokePoolClientsByChain {
+  [chainId: number]: SpokePoolClient;
+}

package/src/interfaces/TypedData.ts

@@ -0,0 +1,21 @@
+export interface MessageTypeProperty {
+  name: string;
+  type: string;
+}
+
+export interface MessageTypes {
+  [additionalProperties: string]: MessageTypeProperty[];
+}
+
+export interface TypedMessage<T extends MessageTypes> {
+  types: T;
+  primaryType: keyof T;
+  domain: {
+    name?: string;
+    version?: string;
+    chainId?: number;
+    verifyingContract?: string;
+    salt?: ArrayBuffer;
+  };
+  message: Record<string, unknown>;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,8 @@
+export * from "./Common";
+export * from "./ConfigStore";
+export * from "./HubPool";
+export * from "./SpokePool";
+export * from "./Bridge";
+export * from "./Error";
+export * from "./TypedData";
+export * from "./CachingMechanism";

package/src/lpFeeCalculator/README.md

@@ -0,0 +1,27 @@
+# LP Fee Calculator
+
+Calculates LP fee percentages when doing a transfer.
+
+## Usage
+
+See tests for more documentation: [LP Fee Calculator Test]("./lpFeeCalculator.test.ts")
+
+```ts
+import * as across from "@across/sdk"
+
+const { calculateApyFromUtilization, calculateRealizedLpFeePct } = across.lpFeeCalculator
+
+// sample interest rate model.
+const rateModel = { UBar: toBNWei("0.65"), R0: toBNWei("0.00"), R1: toBNWei("0.08"), R2: toBNWei("1.00") }
+
+// Each interval contains the utilization at pointA (before deposit), the
+// utilization at pointB (after the deposit), expected APY rate and the expected weekly rate.
+const interval = { utilA: toBNWei("0"), utilB: toBNWei("0.01"), apy: "615384615384600", wpy: "11830749673498" }
+
+// Calculate the realized yearly LP Fee APY Percent for a given rate model, utilization before and after the deposit.
+const apyFeePct = calculateApyFromUtilization(rateModel, interval.utilA, interval.utilB)
+assert.equal(apyFeePct.toString(), interval.apy)
+
+const realizedLpFeePct = calculateRealizedLpFeePct(rateModel, interval.utilA, interval.utilB).toString()
+assert.equal(realizedLpFeePct.toString(), interval.wpy)
+```

package/src/lpFeeCalculator/index.ts

@@ -0,0 +1 @@
+export * from "./lpFeeCalculator";

package/src/lpFeeCalculator/lpFeeCalculator.ts

@@ -0,0 +1,169 @@
+// This Util calculates the across realized LP fees. See https://gist.github.com/chrismaree/a713725e4fe96c531c42ed7b629d4a85
+// gist for a python implementation of the logic in this file. This implementation is designed to work with both web3.js
+// and ethers BNs in the main entry point function calculateRealizedLpFeePct.
+
+import Decimal from "decimal.js";
+import { BigNumberish, BN, toBN, toBNWei, fromWei, min, max, fixedPointAdjustment } from "../utils";
+
+// note a similar type exists in the constants file, but are strings only. This is a bit more permissive to allow
+// backward compatibility for callers with a rate model defined with bignumbers and not strings.
+export interface RateModel {
+  UBar: BigNumberish; // denote the utilization kink along the rate model where the slope of the interest rate model changes.
+  R0: BigNumberish; // is the interest rate charged at 0 utilization
+  R1: BigNumberish; // R_0+R_1 is the interest rate charged at UBar
+  R2: BigNumberish; // R_0+R_1+R_2 is the interest rate charged at 100% utilization
+}
+
+// converts an APY rate to a one week rate. Uses the Decimal library to take a fractional exponent
+function convertApyToWeeklyFee(apy: BN): BN {
+  // R_week = (1 + apy)^(1/52) - 1
+  const weeklyFeePct = Decimal.pow(
+    new Decimal("1").plus(fromWei(apy)),
+    new Decimal("1").dividedBy(new Decimal("52"))
+  ).minus(new Decimal("1"));
+
+  // Convert from decimal back to BN, scaled by 1e18.
+  return toBN(weeklyFeePct.times(fixedPointAdjustment.toString()).floor().toString());
+}
+
+export function truncate18DecimalBN(input: BN, digits: number): BN {
+  const digitsToDrop = 18 - digits;
+  const multiplier = toBN(10).pow(digitsToDrop);
+  return input.div(multiplier).mul(multiplier);
+}
+
+export class LPFeeCalculator {
+  constructor(private readonly rateModel: RateModel) {}
+
+  /**
+   * Compute area under curve of the piece-wise linear rate model.
+   * @param rateModel Rate model to be used in this calculation.
+   * @param utilization The current utilization of the pool.
+   * @returns The area under the curve of the piece-wise linear rate model.
+   */
+  public calculateAreaUnderRateCurve(utilization: BN): BN {
+    // Area under first piecewise component
+    const utilizationBeforeKink = min(utilization, this.rateModel.UBar);
+    const rectangle1Area = utilizationBeforeKink.mul(this.rateModel.R0).div(fixedPointAdjustment);
+    const triangle1Area = toBNWei("0.5")
+      .mul(this.calculateInstantaneousRate(utilizationBeforeKink).sub(this.rateModel.R0))
+      .mul(utilizationBeforeKink)
+      .div(fixedPointAdjustment)
+      .div(fixedPointAdjustment);
+
+    // Area under second piecewise component
+    const utilizationAfter = max(toBN("0"), utilization.sub(this.rateModel.UBar));
+    const rectangle2Area = utilizationAfter
+      .mul(toBN(this.rateModel.R0).add(this.rateModel.R1))
+      .div(fixedPointAdjustment);
+    const triangle2Area = toBNWei("0.5")
+      .mul(this.calculateInstantaneousRate(utilization).sub(toBN(this.rateModel.R0).add(this.rateModel.R1)))
+      .mul(utilizationAfter)
+      .div(fixedPointAdjustment)
+      .div(fixedPointAdjustment);
+
+    return rectangle1Area.add(triangle1Area).add(rectangle2Area).add(triangle2Area);
+  }
+
+  /**
+   * Calculate the instantaneous rate for a 0 sized deposit (infinitesimally small).
+   * @param utilization The current utilization of the pool.
+   * @returns The instantaneous rate for a 0 sized deposit.
+   */
+  public calculateInstantaneousRate(utilization: BigNumberish): BN {
+    // Assuming utilization >= 0, if UBar = 0 then the value beforeKink is 0 since min(>=0, 0) = 0.
+    const beforeKink =
+      this.rateModel.UBar.toString() === "0"
+        ? toBN(0)
+        : min(utilization, this.rateModel.UBar).mul(this.rateModel.R1).div(this.rateModel.UBar);
+    const afterKink = max(toBN("0"), toBN(utilization).sub(this.rateModel.UBar))
+      .mul(this.rateModel.R2)
+      .div(toBNWei("1").sub(this.rateModel.UBar));
+
+    return toBN(this.rateModel.R0).add(beforeKink).add(afterKink);
+  }
+
+  /**
+   * Calculate the realized LP Fee Percent for a given rate model, utilization before and after the deposit.
+   * @param rateModel Rate model to be used in this calculation.
+   * @param utilizationBeforeDeposit The utilization of the pool before the deposit.
+   * @param utilizationAfterDeposit The utilization of the pool after the deposit.
+   * @param truncateDecimals Whether to truncate the decimals to 6.
+   * @returns The realized LP fee percent.
+   */
+  public calculateRealizedLpFeePct(
+    utilizationBeforeDeposit: BigNumberish,
+    utilizationAfterDeposit: BigNumberish,
+    truncateDecimals = false
+  ): BN {
+    const apy = this.calculateApyFromUtilization(toBN(utilizationBeforeDeposit), toBN(utilizationAfterDeposit));
+
+    // ACROSS UMIP requires that the realized fee percent is floor rounded as decimal to 6 decimals.
+    return truncateDecimals ? truncate18DecimalBN(convertApyToWeeklyFee(apy), 6) : convertApyToWeeklyFee(apy);
+  }
+  /**
+   * Calculate the realized yearly LP Fee APY Percent for a given rate model, utilization before and after the deposit.
+   * @param rateModel Rate model to be used in this calculation.
+   * @param utilizationBeforeDeposit The utilization of the pool before the deposit.
+   * @param utilizationAfterDeposit The utilization of the pool after the deposit.
+   * @returns The realized LP fee APY percent.
+   */
+  public calculateApyFromUtilization(utilizationBeforeDeposit: BN, utilizationAfterDeposit: BN): BN {
+    if (utilizationBeforeDeposit.eq(utilizationAfterDeposit))
+      return this.calculateInstantaneousRate(utilizationBeforeDeposit);
+
+    // Get the area of [0, utilizationBeforeDeposit] and [0, utilizationAfterDeposit]
+    const areaBeforeDeposit = this.calculateAreaUnderRateCurve(utilizationBeforeDeposit);
+    const areaAfterDeposit = this.calculateAreaUnderRateCurve(utilizationAfterDeposit);
+
+    const numerator = areaAfterDeposit.sub(areaBeforeDeposit);
+    const denominator = utilizationAfterDeposit.sub(utilizationBeforeDeposit);
+    return numerator.mul(fixedPointAdjustment).div(denominator);
+  }
+}
+
+/**
+ * Calculate the instantaneous rate for a 0 sized deposit (infinitesimally small).
+ * @param rateModel Rate model to be used in this calculation.
+ * @param utilization The current utilization of the pool.
+ * @returns The instantaneous rate for a 0 sized deposit.
+ */
+export function calculateInstantaneousRate(rateModel: RateModel, utilization: BigNumberish): BN {
+  return new LPFeeCalculator(rateModel).calculateInstantaneousRate(utilization);
+}
+
+/**
+ * Calculate the realized yearly LP Fee APY Percent for a given rate model, utilization before and after the deposit.
+ * @param rateModel Rate model to be used in this calculation.
+ * @param utilizationBeforeDeposit The utilization of the pool before the deposit.
+ * @param utilizationAfterDeposit The utilization of the pool after the deposit.
+ * @returns The realized LP fee APY percent.
+ */
+export function calculateApyFromUtilization(
+  rateModel: RateModel,
+  utilizationBeforeDeposit: BN,
+  utilizationAfterDeposit: BN
+): BN {
+  return new LPFeeCalculator(rateModel).calculateApyFromUtilization(utilizationBeforeDeposit, utilizationAfterDeposit);
+}
+
+/**
+ * Calculate the realized LP Fee Percent for a given rate model, utilization before and after the deposit.
+ * @param rateModel Rate model to be used in this calculation.
+ * @param utilizationBeforeDeposit The utilization of the pool before the deposit.
+ * @param utilizationAfterDeposit The utilization of the pool after the deposit.
+ * @param truncateDecimals Whether to truncate the decimals to 6.
+ * @returns The realized LP fee percent.
+ */
+export function calculateRealizedLpFeePct(
+  rateModel: RateModel,
+  utilizationBeforeDeposit: BigNumberish,
+  utilizationAfterDeposit: BigNumberish,
+  truncateDecimals = false
+): BN {
+  return new LPFeeCalculator(rateModel).calculateRealizedLpFeePct(
+    utilizationBeforeDeposit,
+    utilizationAfterDeposit,
+    truncateDecimals
+  );
+}

package/src/lpFeeCalculator/rateModel.ts

@@ -0,0 +1,183 @@
+import { ethers } from "ethers";
+import { isDefined } from "../utils";
+
+// Each L1 token is mapped to an array of stringified rate models, ordered by the block height at which they were
+// published on-chain. This dictionary is used internally to fetch a rate model for a block height.
+type RateModelEventsDictionary = {
+  [l1TokenAddress: string]: { blockNumber: number; rateModel: string }[];
+};
+
+// Events should be reformatted into this shape to be used as input into methods in this file.
+export type RateModelEvent = {
+  blockNumber: number;
+  transactionIndex: number;
+  logIndex: number;
+  rateModel: string;
+  l1Token: string;
+};
+
+interface RateModel {
+  UBar: string; // denote the utilization kink along the rate model where the slope of the interest rate model changes.
+  R0: string; // is the interest rate charged at 0 utilization
+  R1: string; // R_0+R_1 is the interest rate charged at UBar
+  R2: string; // R_0+R_1+R_2 is the interest rate charged at 100% utilization
+}
+
+const expectedRateModelKeys = ["UBar", "R0", "R1", "R2"];
+
+export class RateModelDictionary {
+  public rateModelDictionary: RateModelEventsDictionary = {};
+
+  private _throwIfNotInitialized() {
+    if (Object.keys(this.rateModelDictionary).length == 0)
+      throw new Error("RateModelUtility method called before updating rate model dictionary!");
+  }
+
+  updateWithEvents(rateModelEvents: RateModelEvent[]): void {
+    this.rateModelDictionary = createRateModelEventDictionary(rateModelEvents);
+  }
+
+  /**
+   * Return the rate model for L1 token set at the block height.
+   * @param l1Token L1 token address to get rate model for.
+   * @param blockNumber Block height to get rate model for.
+   * @returns Rate model object.
+   */
+  getRateModelForBlockNumber(l1Token: string, blockNumber?: number): RateModel {
+    this._throwIfNotInitialized();
+
+    const l1TokenNormalized = ethers.utils.getAddress(l1Token);
+
+    if (!this.rateModelDictionary[l1TokenNormalized] || this.rateModelDictionary[l1TokenNormalized].length === 0)
+      throw new Error(`No updated rate model events for L1 token: ${l1TokenNormalized}`);
+
+    if (!blockNumber) {
+      // If block number is undefined, use latest updated rate model.
+      return parseAndReturnRateModelFromString(this.rateModelDictionary[l1TokenNormalized].slice(-1)[0].rateModel);
+    } else {
+      const firstEventBlockNumber = this.rateModelDictionary[l1TokenNormalized][0].blockNumber;
+      if (blockNumber < firstEventBlockNumber) {
+        throw new Error(
+          `Block number #${blockNumber} is before first UpdatedRateModel event block ${firstEventBlockNumber}`
+        );
+      }
+
+      // We're looking for the latest rate model update that occurred at or before the block number.
+      // Rate model events are inserted into the array from oldest at index 0 to newest at index length-1, so we'll
+      // reverse the array so it goes from newest at index 0 to oldest at index length-1, and then find the first event
+      // who's block number is less than or equal to the target block number.
+      const rateModel = this.rateModelDictionary[l1TokenNormalized]
+        .slice()
+        .reverse() // reverse() modifies memory in place so create a copy first.
+        .find((event) => event.blockNumber <= blockNumber);
+
+      if (!rateModel)
+        throw new Error(`No updated rate model events before block #${blockNumber} for L1 token: ${l1TokenNormalized}`);
+      return parseAndReturnRateModelFromString(rateModel?.rateModel);
+    }
+  }
+
+  /**
+   * @notice Return all L1 tokens that had a rate model associated with it at the block number.
+   * @param blockNumber Returns l1 tokens that were mapped to a rate model at this block height. If undefined,
+   * this function will return all L1 tokens that have a block number as of the latest block height.
+   * @returns array of L1 token addresses.
+   */
+  getL1TokensFromRateModel(blockNumber: number | undefined = undefined): string[] {
+    this._throwIfNotInitialized();
+
+    return Object.keys(this.rateModelDictionary)
+      .map((l1Token) => {
+        const l1TokenNormalized = ethers.utils.getAddress(l1Token);
+
+        // Check that there is at least one UpdatedRateModel event before the provided block number, otherwise
+        // this L1 token didn't exist in the RateModel at the block height and we shouldn't include it in the returned
+        // array.
+        if (
+          !blockNumber ||
+          this.rateModelDictionary[l1TokenNormalized].find((event) => event.blockNumber <= blockNumber)
+        )
+          return ethers.utils.getAddress(l1Token);
+        else return null;
+      })
+      .filter(isDefined);
+  }
+}
+
+/**
+ * Helper method that returns parsed rate model from string, or throws.
+ * @param rateModelString Stringified rate model to parse.
+ * @returns Rate model object. Must conform to `expectedRateModelKeys` format.
+ */
+export const parseAndReturnRateModelFromString = (rateModelString: string): RateModel => {
+  const rateModelFromEvent = JSON.parse(rateModelString);
+
+  // Rate model must contain the exact same keys in `expectedRateModelKeys`.
+  for (const key of expectedRateModelKeys) {
+    if (!Object.keys(rateModelFromEvent).includes(key)) {
+      throw new Error(
+        `Rate model does not contain all expected keys. Expected keys: [${expectedRateModelKeys}], actual keys: [${Object.keys(
+          rateModelFromEvent
+        )}]`
+      );
+    }
+  }
+
+  for (const key of Object.keys(rateModelFromEvent)) {
+    if (!expectedRateModelKeys.includes(key)) {
+      throw new Error(
+        `Rate model contains unexpected keys. Expected keys: [${expectedRateModelKeys}], actual keys: [${Object.keys(
+          rateModelFromEvent
+        )}]`
+      );
+    }
+  }
+
+  return {
+    UBar: rateModelFromEvent.UBar,
+    R0: rateModelFromEvent.R0,
+    R1: rateModelFromEvent.R1,
+    R2: rateModelFromEvent.R2,
+  };
+};
+
+/**
+ * Given an unsorted array of updated rate model events, return a dictionary mapping token addresses to sorted
+ * rate model events. This method is used internally to enforce chronological sorting of events and mapping rate models
+ * to token addresses.
+ * @param rateModelEvents Unsorted updated rate model events, each of which contains a token address, the stringified
+ * rate model for that token, and the block height of the update.
+ * @returns Dictionary mapping token addresses to chronologically sorted rate model updates.
+ */
+const createRateModelEventDictionary = (rateModelEvents: RateModelEvent[]): RateModelEventsDictionary => {
+  const updatedRateModelEventsForToken: RateModelEventsDictionary = {};
+
+  // Sort events in-place from oldest to newest:
+  rateModelEvents.sort((a, b) => {
+    if (a.blockNumber !== b.blockNumber) {
+      return a.blockNumber - b.blockNumber;
+    }
+
+    if (a.transactionIndex !== b.transactionIndex) {
+      return a.transactionIndex - b.transactionIndex;
+    }
+
+    return a.logIndex - b.logIndex;
+  });
+
+  for (const updatedRateModelEvent of rateModelEvents) {
+    // The contract enforces that all rate models are mapped to addresses, therefore we do not need to check that
+    // `l1Token` is a valid address.
+    const l1TokenNormalized = ethers.utils.getAddress(updatedRateModelEvent.l1Token);
+    if (!updatedRateModelEventsForToken[l1TokenNormalized]) updatedRateModelEventsForToken[l1TokenNormalized] = [];
+
+    // We assume that events are returned from oldest to newest, so we can simply push events into the array and
+    // and maintain their time order.
+    updatedRateModelEventsForToken[l1TokenNormalized].push({
+      blockNumber: updatedRateModelEvent.blockNumber,
+      rateModel: updatedRateModelEvent.rateModel,
+    });
+  }
+
+  return updatedRateModelEventsForToken;
+};

package/src/merkleDistributor/MerkleDistributor.ts

@@ -0,0 +1,37 @@
+import { MerkleTree } from "@across-protocol/contracts/dist/utils/MerkleTree";
+import { ethers } from "ethers";
+import { DistributionRecipientsWithProofs, DistributionRecipient } from "./model";
+
+export class MerkleDistributor {
+  /**
+   * Generate the Merkle root and the proofs for a collection of recipients.
+   *
+   * @param recipients An object which describes the recipients
+   * @param windowIndex Parameter to specify an window index. This allows using the same smart contract for multiple token distributions.
+   */
+  static createMerkleDistributionProofs(recipients: DistributionRecipient[], windowIndex: number) {
+    const merkleTree = new MerkleTree<DistributionRecipient>(recipients, MerkleDistributor.createLeaf);
+    const recipientsWithProofs = recipients.reduce((acc, recipient) => {
+      return {
+        ...acc,
+        [recipient.account]: {
+          ...recipient,
+          proof: merkleTree.getHexProof(recipient),
+          windowIndex,
+        },
+      };
+    }, {} as DistributionRecipientsWithProofs);
+    return { recipientsWithProofs, merkleRoot: merkleTree.getHexRoot() };
+  }
+
+  /**
+   * Encode the account address, the amount and the account index into a Merkle Tree leaf.
+   * It is equivalent to Solidity's keccak256(abi.encode(account, amount))
+   * @param recipient The recipient of the token distribution
+   * @returns The Merkle Tree leaf
+   */
+  static createLeaf(recipient: DistributionRecipient) {
+    const { account, amount, accountIndex } = recipient;
+    return ethers.utils.solidityKeccak256(["address", "uint256", "uint256"], [account, amount, accountIndex]);
+  }
+}