@across-protocol/sdk 3.1.27 → 3.1.28

package/src/clients/BundleDataClient/index.ts

@@ -0,0 +1,2 @@
+export * from "./BundleDataClient";
+export * from "./utils";

package/src/clients/BundleDataClient/utils/DataworkerUtils.ts

@@ -0,0 +1,268 @@
+// Create a combined `refunds` object containing refunds for V2 + V3 fills
+
+import {
+  BundleDepositsV3,
+  BundleExcessSlowFills,
+  BundleFillsV3,
+  BundleSlowFills,
+  CombinedRefunds,
+  ExpiredDepositsToRefundV3,
+  PoolRebalanceLeaf,
+  Refund,
+  RunningBalances,
+} from "../../../interfaces";
+import {
+  bnZero,
+  AnyObject,
+  groupObjectCountsByTwoProps,
+  fixedPointAdjustment,
+  count2DDictionaryValues,
+  count3DDictionaryValues,
+} from "../../../utils";
+import {
+  addLastRunningBalance,
+  constructPoolRebalanceLeaves,
+  PoolRebalanceRoot,
+  updateRunningBalance,
+  updateRunningBalanceForDeposit,
+} from "./PoolRebalanceUtils";
+import { V3FillWithBlock } from "./shims";
+import { AcrossConfigStoreClient } from "../../AcrossConfigStoreClient";
+import { HubPoolClient } from "../../HubPoolClient";
+import { buildPoolRebalanceLeafTree } from "./MerkleTreeUtils";
+
+// and expired deposits.
+export function getRefundsFromBundle(
+  bundleFillsV3: BundleFillsV3,
+  expiredDepositsToRefundV3: ExpiredDepositsToRefundV3
+): CombinedRefunds {
+  const combinedRefunds: {
+    [repaymentChainId: string]: {
+      [repaymentToken: string]: Refund;
+    };
+  } = {};
+  Object.entries(bundleFillsV3).forEach(([repaymentChainId, fillsForChain]) => {
+    combinedRefunds[repaymentChainId] ??= {};
+    Object.entries(fillsForChain).forEach(([l2TokenAddress, { refunds }]) => {
+      // refunds can be undefined if these fills were all slow fill executions.
+      if (refunds === undefined) {
+        return;
+      }
+      // @dev use shallow copy so that modifying combinedRefunds doesn't modify the original refunds object.
+      const refundsShallowCopy = { ...refunds };
+      if (combinedRefunds[repaymentChainId][l2TokenAddress] === undefined) {
+        combinedRefunds[repaymentChainId][l2TokenAddress] = refundsShallowCopy;
+      } else {
+        // Each refunds object should have a unique refund address so we can add new ones to the
+        // existing dictionary.
+        combinedRefunds[repaymentChainId][l2TokenAddress] = {
+          ...combinedRefunds[repaymentChainId][l2TokenAddress],
+          ...refundsShallowCopy,
+        };
+      }
+    });
+  });
+  Object.entries(expiredDepositsToRefundV3).forEach(([originChainId, depositsForChain]) => {
+    combinedRefunds[originChainId] ??= {};
+    Object.entries(depositsForChain).forEach(([l2TokenAddress, deposits]) => {
+      deposits.forEach((deposit) => {
+        if (combinedRefunds[originChainId][l2TokenAddress] === undefined) {
+          combinedRefunds[originChainId][l2TokenAddress] = { [deposit.depositor]: deposit.inputAmount };
+        } else {
+          const existingRefundAmount = combinedRefunds[originChainId][l2TokenAddress][deposit.depositor];
+          combinedRefunds[originChainId][l2TokenAddress][deposit.depositor] = deposit.inputAmount.add(
+            existingRefundAmount ?? bnZero
+          );
+        }
+      });
+    });
+  });
+  return combinedRefunds;
+}
+
+export function prettyPrintV3SpokePoolEvents(
+  bundleDepositsV3: BundleDepositsV3,
+  bundleFillsV3: BundleFillsV3,
+  bundleInvalidFillsV3: V3FillWithBlock[],
+  bundleSlowFillsV3: BundleSlowFills,
+  expiredDepositsToRefundV3: ExpiredDepositsToRefundV3,
+  unexecutableSlowFills: BundleExcessSlowFills
+): AnyObject {
+  return {
+    bundleDepositsV3: count2DDictionaryValues(bundleDepositsV3),
+    bundleFillsV3: count3DDictionaryValues(bundleFillsV3, "fills"),
+    bundleSlowFillsV3: count2DDictionaryValues(bundleSlowFillsV3),
+    expiredDepositsToRefundV3: count2DDictionaryValues(expiredDepositsToRefundV3),
+    unexecutableSlowFills: count2DDictionaryValues(unexecutableSlowFills),
+    allInvalidFillsInRangeByDestinationChainAndRelayer: groupObjectCountsByTwoProps(
+      bundleInvalidFillsV3,
+      "destinationChainId",
+      (fill) => `${fill.relayer}`
+    ),
+  };
+}
+
+export function getEndBlockBuffers(
+  chainIdListForBundleEvaluationBlockNumbers: number[],
+  blockRangeEndBlockBuffer: { [chainId: number]: number }
+): number[] {
+  // These buffers can be configured by the bot runner. They have two use cases:
+  // 1) Validate the end blocks specified in the pending root bundle. If the end block is greater than the latest
+  // block for its chain, then we should dispute the bundle because we can't look up events in the future for that
+  // chain. However, there are some cases where the proposer's node for that chain is returning a higher HEAD block
+  // than the bot-runner is seeing, so we can use this buffer to allow the proposer some margin of error. If
+  // the bundle end block is less than HEAD but within this buffer, then we won't dispute and we'll just exit
+  // early from this function.
+  // 2) Subtract from the latest block in a new root bundle proposal. This can be used to reduce the chance that
+  // bot runs using different providers see different contract state close to the HEAD block for a chain.
+  // Reducing the latest block that we query also gives partially filled deposits slightly more buffer for relayers
+  // to fully fill the deposit and reduces the chance that the data worker includes a slow fill payment that gets
+  // filled during the challenge period.
+  return chainIdListForBundleEvaluationBlockNumbers.map((chainId: number) => blockRangeEndBlockBuffer[chainId] ?? 0);
+}
+
+export function _buildPoolRebalanceRoot(
+  latestMainnetBlock: number,
+  mainnetBundleEndBlock: number,
+  bundleV3Deposits: BundleDepositsV3,
+  bundleFillsV3: BundleFillsV3,
+  bundleSlowFillsV3: BundleSlowFills,
+  unexecutableSlowFills: BundleExcessSlowFills,
+  expiredDepositsToRefundV3: ExpiredDepositsToRefundV3,
+  clients: { hubPoolClient: HubPoolClient; configStoreClient: AcrossConfigStoreClient },
+  maxL1TokenCountOverride?: number
+): PoolRebalanceRoot {
+  // Running balances are the amount of tokens that we need to send to each SpokePool to pay for all instant and
+  // slow relay refunds. They are decreased by the amount of funds already held by the SpokePool. Balances are keyed
+  // by the SpokePool's network and L1 token equivalent of the L2 token to refund.
+  // Realized LP fees are keyed the same as running balances and represent the amount of LP fees that should be paid
+  // to LP's for each running balance.
+
+  // For each FilledRelay group, identified by { repaymentChainId, L1TokenAddress }, initialize a "running balance"
+  // to the total refund amount for that group.
+  const runningBalances: RunningBalances = {};
+  const realizedLpFees: RunningBalances = {};
+
+  /**
+   * REFUNDS FOR FAST FILLS
+   */
+
+  // Add running balances and lp fees for v3 relayer refunds using BundleDataClient.bundleFillsV3. Refunds
+  // should be equal to inputAmount - lpFees so that relayers get to keep the relayer fee. Add the refund amount
+  // to the running balance for the repayment chain.
+  Object.entries(bundleFillsV3).forEach(([_repaymentChainId, fillsForChain]) => {
+    const repaymentChainId = Number(_repaymentChainId);
+    Object.entries(fillsForChain).forEach(
+      ([l2TokenAddress, { realizedLpFees: totalRealizedLpFee, totalRefundAmount }]) => {
+        const l1TokenCounterpart = clients.hubPoolClient.getL1TokenForL2TokenAtBlock(
+          l2TokenAddress,
+          repaymentChainId,
+          mainnetBundleEndBlock
+        );
+
+        updateRunningBalance(runningBalances, repaymentChainId, l1TokenCounterpart, totalRefundAmount);
+        updateRunningBalance(realizedLpFees, repaymentChainId, l1TokenCounterpart, totalRealizedLpFee);
+      }
+    );
+  });
+
+  /**
+   * PAYMENTS SLOW FILLS
+   */
+
+  // Add running balances and lp fees for v3 slow fills using BundleDataClient.bundleSlowFillsV3.
+  // Slow fills should still increment bundleLpFees and updatedOutputAmount should be equal to inputAmount - lpFees.
+  // Increment the updatedOutputAmount to the destination chain.
+  Object.entries(bundleSlowFillsV3).forEach(([_destinationChainId, depositsForChain]) => {
+    const destinationChainId = Number(_destinationChainId);
+    Object.entries(depositsForChain).forEach(([outputToken, deposits]) => {
+      deposits.forEach((deposit) => {
+        const l1TokenCounterpart = clients.hubPoolClient.getL1TokenForL2TokenAtBlock(
+          outputToken,
+          destinationChainId,
+          mainnetBundleEndBlock
+        );
+        const lpFee = deposit.lpFeePct.mul(deposit.inputAmount).div(fixedPointAdjustment);
+        updateRunningBalance(runningBalances, destinationChainId, l1TokenCounterpart, deposit.inputAmount.sub(lpFee));
+        // Slow fill LP fees are accounted for when the slow fill executes and a V3FilledRelay is emitted. i.e. when
+        // the slow fill execution is included in bundleFillsV3.
+      });
+    });
+  });
+
+  /**
+   * EXCESSES FROM UNEXECUTABLE SLOW FILLS
+   */
+
+  // Subtract destination chain running balances for BundleDataClient.unexecutableSlowFills.
+  // These are all slow fills that are impossible to execute and therefore the amount to return would be
+  // the updatedOutputAmount = inputAmount - lpFees.
+  Object.entries(unexecutableSlowFills).forEach(([_destinationChainId, slowFilledDepositsForChain]) => {
+    const destinationChainId = Number(_destinationChainId);
+    Object.entries(slowFilledDepositsForChain).forEach(([outputToken, slowFilledDeposits]) => {
+      slowFilledDeposits.forEach((deposit) => {
+        const l1TokenCounterpart = clients.hubPoolClient.getL1TokenForL2TokenAtBlock(
+          outputToken,
+          destinationChainId,
+          mainnetBundleEndBlock
+        );
+        const lpFee = deposit.lpFeePct.mul(deposit.inputAmount).div(fixedPointAdjustment);
+        updateRunningBalance(runningBalances, destinationChainId, l1TokenCounterpart, lpFee.sub(deposit.inputAmount));
+        // Slow fills don't add to lpFees, only when the slow fill is executed and a V3FilledRelay is emitted, so
+        // we don't need to subtract it here. Moreover, the HubPoole expects bundleLpFees to be > 0.
+      });
+    });
+  });
+
+  /**
+   * DEPOSITS
+   */
+
+  // Handle v3Deposits. These decrement running balances from the origin chain equal to the inputAmount.
+  // There should not be early deposits in v3.
+  Object.entries(bundleV3Deposits).forEach(([, depositsForChain]) => {
+    Object.entries(depositsForChain).forEach(([, deposits]) => {
+      deposits.forEach((deposit) => {
+        updateRunningBalanceForDeposit(runningBalances, clients.hubPoolClient, deposit, deposit.inputAmount.mul(-1));
+      });
+    });
+  });
+
+  /**
+   * REFUNDS FOR EXPIRED DEPOSITS
+   */
+
+  // Add origin chain running balance for expired v3 deposits. These should refund the inputAmount.
+  Object.entries(expiredDepositsToRefundV3).forEach(([_originChainId, depositsForChain]) => {
+    const originChainId = Number(_originChainId);
+    Object.entries(depositsForChain).forEach(([inputToken, deposits]) => {
+      deposits.forEach((deposit) => {
+        const l1TokenCounterpart = clients.hubPoolClient.getL1TokenForL2TokenAtBlock(
+          inputToken,
+          originChainId,
+          mainnetBundleEndBlock
+        );
+        updateRunningBalance(runningBalances, originChainId, l1TokenCounterpart, deposit.inputAmount);
+      });
+    });
+  });
+
+  // Add to the running balance value from the last valid root bundle proposal for {chainId, l1Token}
+  // combination if found.
+  addLastRunningBalance(latestMainnetBlock, runningBalances, clients.hubPoolClient);
+
+  const leaves: PoolRebalanceLeaf[] = constructPoolRebalanceLeaves(
+    mainnetBundleEndBlock,
+    runningBalances,
+    realizedLpFees,
+    clients.configStoreClient,
+    maxL1TokenCountOverride
+  );
+
+  return {
+    runningBalances,
+    realizedLpFees,
+    leaves,
+    tree: buildPoolRebalanceLeafTree(leaves),
+  };
+}

package/src/clients/BundleDataClient/utils/FillUtils.ts

@@ -0,0 +1,46 @@
+import { Fill } from "../../../interfaces";
+import { getBlockRangeForChain, isSlowFill } from "../../../utils";
+import { HubPoolClient } from "../../HubPoolClient";
+
+export function getRefundInformationFromFill(
+  fill: Fill,
+  hubPoolClient: HubPoolClient,
+  blockRangesForChains: number[][],
+  chainIdListForBundleEvaluationBlockNumbers: number[],
+  fromLiteChain: boolean
+): {
+  chainToSendRefundTo: number;
+  repaymentToken: string;
+} {
+  // Handle slow relay where repaymentChainId = 0. Slow relays always pay recipient on destination chain.
+  // So, save the slow fill under the destination chain, and save the fast fill under its repayment chain.
+  let chainToSendRefundTo = isSlowFill(fill) ? fill.destinationChainId : fill.repaymentChainId;
+  // If the fill is for a deposit originating from the lite chain, the repayment chain is the origin chain
+  // regardless of whether it is a slow or fast fill (we ignore slow fills but this is for posterity).
+  if (fromLiteChain) {
+    chainToSendRefundTo = fill.originChainId;
+  }
+
+  // Save fill data and associate with repayment chain and L2 token refund should be denominated in.
+  const endBlockForMainnet = getBlockRangeForChain(
+    blockRangesForChains,
+    hubPoolClient.chainId,
+    chainIdListForBundleEvaluationBlockNumbers
+  )[1];
+
+  const l1TokenCounterpart = hubPoolClient.getL1TokenForL2TokenAtBlock(
+    fill.inputToken,
+    fill.originChainId,
+    endBlockForMainnet
+  );
+
+  const repaymentToken = hubPoolClient.getL2TokenForL1TokenAtBlock(
+    l1TokenCounterpart,
+    chainToSendRefundTo,
+    endBlockForMainnet
+  );
+  return {
+    chainToSendRefundTo,
+    repaymentToken,
+  };
+}

package/src/clients/BundleDataClient/utils/MerkleTreeUtils.ts

@@ -0,0 +1,26 @@
+import { MerkleTree } from "@across-protocol/contracts";
+import { PoolRebalanceLeaf } from "../../../interfaces";
+import { getParamType } from "../../../utils/ContractUtils";
+import { utils } from "ethers";
+
+export function buildPoolRebalanceLeafTree(poolRebalanceLeaves: PoolRebalanceLeaf[]): MerkleTree<PoolRebalanceLeaf> {
+  for (let i = 0; i < poolRebalanceLeaves.length; i++) {
+    // The 4 provided parallel arrays must be of equal length. Running Balances can optionally be 2x the length
+    if (
+      poolRebalanceLeaves[i].l1Tokens.length !== poolRebalanceLeaves[i].bundleLpFees.length ||
+      poolRebalanceLeaves[i].netSendAmounts.length !== poolRebalanceLeaves[i].bundleLpFees.length
+    ) {
+      throw new Error("Provided lef arrays are not of equal length");
+    }
+    if (
+      poolRebalanceLeaves[i].runningBalances.length !== poolRebalanceLeaves[i].bundleLpFees.length * 2 &&
+      poolRebalanceLeaves[i].runningBalances.length !== poolRebalanceLeaves[i].bundleLpFees.length
+    ) {
+      throw new Error("Running balances length unexpected");
+    }
+  }
+
+  const paramType = getParamType("MerkleLibTest", "verifyPoolRebalance", "rebalance");
+  const hashFn = (input: PoolRebalanceLeaf) => utils.keccak256(utils.defaultAbiCoder.encode([paramType], [input]));
+  return new MerkleTree<PoolRebalanceLeaf>(poolRebalanceLeaves, hashFn);
+}

package/src/clients/BundleDataClient/utils/PoolRebalanceUtils.ts

@@ -0,0 +1,238 @@
+import { MerkleTree } from "@across-protocol/contracts/dist/utils/MerkleTree";
+import { RunningBalances, PoolRebalanceLeaf, Clients, SpokePoolTargetBalance } from "../../../interfaces";
+import { SpokePoolClient } from "../../SpokePoolClient";
+import { BigNumber } from "ethers";
+import { bnZero, compareAddresses } from "../../../utils";
+import { HubPoolClient } from "../../HubPoolClient";
+import { V3DepositWithBlock } from "./shims";
+import { AcrossConfigStoreClient } from "../../AcrossConfigStoreClient";
+
+export type PoolRebalanceRoot = {
+  runningBalances: RunningBalances;
+  realizedLpFees: RunningBalances;
+  leaves: PoolRebalanceLeaf[];
+  tree: MerkleTree<PoolRebalanceLeaf>;
+};
+
+// This returns a possible next block range that could be submitted as a new root bundle, or used as a reference
+// when evaluating  pending root bundle. The block end numbers must be less than the latest blocks for each chain ID
+// (because we can't evaluate events in the future), and greater than the expected start blocks, which are the
+// greater of 0 and the latest bundle end block for an executed root bundle proposal + 1.
+export function getWidestPossibleExpectedBlockRange(
+  chainIdListForBundleEvaluationBlockNumbers: number[],
+  spokeClients: { [chainId: number]: SpokePoolClient },
+  endBlockBuffers: number[],
+  clients: Clients,
+  latestMainnetBlock: number,
+  enabledChains: number[]
+): number[][] {
+  // We impose a buffer on the head of the chain to increase the probability that the received blocks are final.
+  // Reducing the latest block that we query also gives partially filled deposits slightly more buffer for relayers
+  // to fully fill the deposit and reduces the chance that the data worker includes a slow fill payment that gets
+  // filled during the challenge period.
+  const latestPossibleBundleEndBlockNumbers = chainIdListForBundleEvaluationBlockNumbers.map(
+    (chainId: number, index) =>
+      spokeClients[chainId] && Math.max(spokeClients[chainId].latestBlockSearched - endBlockBuffers[index], 0)
+  );
+  return chainIdListForBundleEvaluationBlockNumbers.map((chainId: number, index) => {
+    const lastEndBlockForChain = clients.hubPoolClient.getLatestBundleEndBlockForChain(
+      chainIdListForBundleEvaluationBlockNumbers,
+      latestMainnetBlock,
+      chainId
+    );
+
+    // If chain is disabled, re-use the latest bundle end block for the chain as both the start
+    // and end block.
+    if (!enabledChains.includes(chainId)) {
+      return [lastEndBlockForChain, lastEndBlockForChain];
+    } else {
+      // If the latest block hasn't advanced enough from the previous proposed end block, then re-use it. It will
+      // be regarded as disabled by the Dataworker clients. Otherwise, add 1 to the previous proposed end block.
+      if (lastEndBlockForChain >= latestPossibleBundleEndBlockNumbers[index]) {
+        // @dev: Without this check, then `getNextBundleStartBlockNumber` could return `latestBlock+1` even when the
+        // latest block for the chain hasn't advanced, resulting in an invalid range being produced.
+        return [lastEndBlockForChain, lastEndBlockForChain];
+      } else {
+        // Chain has advanced far enough including the buffer, return range from previous proposed end block + 1 to
+        // latest block for chain minus buffer.
+        return [
+          clients.hubPoolClient.getNextBundleStartBlockNumber(
+            chainIdListForBundleEvaluationBlockNumbers,
+            latestMainnetBlock,
+            chainId
+          ),
+          latestPossibleBundleEndBlockNumbers[index],
+        ];
+      }
+    }
+  });
+}
+
+export function isChainDisabled(blockRangeForChain: number[]): boolean {
+  return blockRangeForChain[0] === blockRangeForChain[1];
+}
+
+// Note: this function computes the intended transfer amount before considering the transfer threshold.
+// A positive number indicates a transfer from hub to spoke.
+export function computeDesiredTransferAmountToSpoke(
+  runningBalance: BigNumber,
+  spokePoolTargetBalance: SpokePoolTargetBalance
+): BigNumber {
+  // Transfer is always desired if hub owes spoke.
+  if (runningBalance.gte(0)) {
+    return runningBalance;
+  }
+
+  // Running balance is negative, but its absolute value is less than the spoke pool target balance threshold.
+  // In this case, we transfer nothing.
+  if (runningBalance.abs().lt(spokePoolTargetBalance.threshold)) {
+    return bnZero;
+  }
+
+  // We are left with the case where the spoke pool is beyond the threshold.
+  // A transfer needs to be initiated to bring it down to the target.
+  const transferSize = runningBalance.abs().sub(spokePoolTargetBalance.target);
+
+  // If the transferSize is < 0, this indicates that the target is still above the running balance.
+  // This can only happen if the threshold is less than the target. This is likely due to a misconfiguration.
+  // In this case, we transfer nothing until the target is exceeded.
+  if (transferSize.lt(0)) {
+    return bnZero;
+  }
+
+  // Negate the transfer size because a transfer from spoke to hub is indicated by a negative number.
+  return transferSize.mul(-1);
+}
+
+// If the running balance is greater than the token transfer threshold, then set the net send amount
+// equal to the running balance and reset the running balance to 0. Otherwise, the net send amount should be
+// 0, indicating that we do not want the data worker to trigger a token transfer between hub pool and spoke
+// pool when executing this leaf.
+export function getNetSendAmountForL1Token(
+  spokePoolTargetBalance: SpokePoolTargetBalance,
+  runningBalance: BigNumber
+): BigNumber {
+  return computeDesiredTransferAmountToSpoke(runningBalance, spokePoolTargetBalance);
+}
+
+export function getRunningBalanceForL1Token(
+  spokePoolTargetBalance: SpokePoolTargetBalance,
+  runningBalance: BigNumber
+): BigNumber {
+  const desiredTransferAmount = computeDesiredTransferAmountToSpoke(runningBalance, spokePoolTargetBalance);
+  return runningBalance.sub(desiredTransferAmount);
+}
+
+export function updateRunningBalance(
+  runningBalances: RunningBalances,
+  l2ChainId: number,
+  l1Token: string,
+  updateAmount: BigNumber
+): void {
+  // Initialize dictionary if empty.
+  if (!runningBalances[l2ChainId]) {
+    runningBalances[l2ChainId] = {};
+  }
+  const runningBalance = runningBalances[l2ChainId][l1Token];
+  if (runningBalance) {
+    runningBalances[l2ChainId][l1Token] = runningBalance.add(updateAmount);
+  } else {
+    runningBalances[l2ChainId][l1Token] = updateAmount;
+  }
+}
+
+export function addLastRunningBalance(
+  latestMainnetBlock: number,
+  runningBalances: RunningBalances,
+  hubPoolClient: HubPoolClient
+): void {
+  Object.keys(runningBalances).forEach((repaymentChainId) => {
+    Object.keys(runningBalances[Number(repaymentChainId)]).forEach((l1TokenAddress) => {
+      const { runningBalance } = hubPoolClient.getRunningBalanceBeforeBlockForChain(
+        latestMainnetBlock,
+        Number(repaymentChainId),
+        l1TokenAddress
+      );
+      if (!runningBalance.eq(bnZero)) {
+        updateRunningBalance(runningBalances, Number(repaymentChainId), l1TokenAddress, runningBalance);
+      }
+    });
+  });
+}
+
+export function updateRunningBalanceForDeposit(
+  runningBalances: RunningBalances,
+  hubPoolClient: HubPoolClient,
+  deposit: V3DepositWithBlock,
+  updateAmount: BigNumber
+): void {
+  const l1TokenCounterpart = hubPoolClient.getL1TokenForL2TokenAtBlock(
+    deposit.inputToken,
+    deposit.originChainId,
+    deposit.quoteBlockNumber
+  );
+  updateRunningBalance(runningBalances, deposit.originChainId, l1TokenCounterpart, updateAmount);
+}
+
+export function constructPoolRebalanceLeaves(
+  latestMainnetBlock: number,
+  runningBalances: RunningBalances,
+  realizedLpFees: RunningBalances,
+  configStoreClient: AcrossConfigStoreClient,
+  maxL1TokenCount?: number
+): PoolRebalanceLeaf[] {
+  // Create one leaf per L2 chain ID. First we'll create a leaf with all L1 tokens for each chain ID, and then
+  // we'll split up any leaves with too many L1 tokens.
+  const leaves: PoolRebalanceLeaf[] = [];
+  Object.keys(runningBalances)
+    .map((chainId) => Number(chainId))
+    // Leaves should be sorted by ascending chain ID
+    .sort((chainIdA, chainIdB) => chainIdA - chainIdB)
+    .map((chainId) => {
+      // Sort addresses.
+      const sortedL1Tokens = Object.keys(runningBalances[chainId]).sort((addressA, addressB) => {
+        return compareAddresses(addressA, addressB);
+      });
+
+      // This begins at 0 and increments for each leaf for this { chainId, L1Token } combination.
+      let groupIndexForChainId = 0;
+
+      // Split addresses into multiple leaves if there are more L1 tokens than allowed per leaf.
+      const maxL1TokensPerLeaf =
+        maxL1TokenCount || configStoreClient.getMaxRefundCountForRelayerRefundLeafForBlock(latestMainnetBlock);
+      for (let i = 0; i < sortedL1Tokens.length; i += maxL1TokensPerLeaf) {
+        const l1TokensToIncludeInThisLeaf = sortedL1Tokens.slice(i, i + maxL1TokensPerLeaf);
+
+        const spokeTargetBalances = l1TokensToIncludeInThisLeaf.map((l1Token) =>
+          configStoreClient.getSpokeTargetBalancesForBlock(l1Token, chainId, latestMainnetBlock)
+        );
+
+        // Build leaves using running balances and realized lp fees data for l1Token + chain, or default to
+        // zero if undefined.
+        const leafBundleLpFees = l1TokensToIncludeInThisLeaf.map(
+          (l1Token) => realizedLpFees[chainId]?.[l1Token] ?? bnZero
+        );
+        const leafNetSendAmounts = l1TokensToIncludeInThisLeaf.map((l1Token, index) =>
+          runningBalances[chainId] && runningBalances[chainId][l1Token]
+            ? getNetSendAmountForL1Token(spokeTargetBalances[index], runningBalances[chainId][l1Token])
+            : bnZero
+        );
+        const leafRunningBalances = l1TokensToIncludeInThisLeaf.map((l1Token, index) =>
+          runningBalances[chainId]?.[l1Token]
+            ? getRunningBalanceForL1Token(spokeTargetBalances[index], runningBalances[chainId][l1Token])
+            : bnZero
+        );
+
+        leaves.push({
+          chainId: chainId,
+          bundleLpFees: leafBundleLpFees,
+          netSendAmounts: leafNetSendAmounts,
+          runningBalances: leafRunningBalances,
+          groupIndex: groupIndexForChainId++,
+          leafId: leaves.length,
+          l1Tokens: l1TokensToIncludeInThisLeaf,
+        });
+      }
+    });
+  return leaves;
+}