@across-protocol/sdk 4.1.63-beta.1 → 4.1.63-beta.3

package/src/arch/evm/BlockUtils.ts

@@ -0,0 +1,209 @@
+import assert from "assert";
+import { Provider, Block as EthersBlock } from "@ethersproject/abstract-provider";
+import { clamp, sortedIndexBy } from "lodash";
+import { chainIsOPStack, getNetworkName } from "../../utils/NetworkUtils";
+import { isDefined } from "../../utils/TypeGuards";
+import {
+  BlockFinder,
+  type Block,
+  type BlockFinderOpts as Opts,
+  type BlockTimeAverage,
+  type BlockFinderHints,
+} from "../../utils/BlockFinder";
+import { getCurrentTime } from "../../utils/TimeUtils";
+import { CHAIN_IDs } from "../../constants";
+
+// Extension of the EthersBlock type which implements `Block`.
+interface EVMBlock extends Block, EthersBlock {}
+
+// Archive requests typically commence at 128 blocks past the head of the chain.
+// Round down to 120 blocks to avoid slipping into archive territory.
+const defaultBlockRange = 120;
+
+// Default offset to the high block number. This is subtracted from the block number of the high block
+// when it is queried from the network, rather than having been specified by the caller. This is useful
+// since the supplied Provider instance may be backed by multiple RPC providers, which can lead to some
+// providers running slower than others and taking time to synchronise on the latest block.
+const defaultHighBlockOffset = 10;
+
+// Retain computations for 15 minutes.
+const cacheTTL = 60 * 15;
+const now = getCurrentTime(); // Seed the cache with initial values.
+const blockTimes: { [chainId: number]: BlockTimeAverage } = {
+  [CHAIN_IDs.INK]: { average: 1, timestamp: now, blockRange: 1 },
+  [CHAIN_IDs.LINEA]: { average: 3, timestamp: now, blockRange: 1 },
+  [CHAIN_IDs.MAINNET]: { average: 12.5, timestamp: now, blockRange: 1 },
+  [CHAIN_IDs.OPTIMISM]: { average: 2, timestamp: now, blockRange: 1 },
+  [CHAIN_IDs.UNICHAIN]: { average: 1, timestamp: now, blockRange: 1 },
+};
+
+/**
+ * @description Compute the average block time over a block range.
+ * @returns Average number of seconds per block.
+ */
+export async function averageBlockTime(
+  provider: Provider,
+  { highBlock, highBlockOffset, blockRange }: Opts = {}
+): Promise<Pick<BlockTimeAverage, "average" | "blockRange">> {
+  // Does not block for StaticJsonRpcProvider.
+  const { chainId } = await provider.getNetwork();
+
+  // OP stack chains inherit Optimism block times, but can be overridden.
+  const cache = blockTimes[chainId] ?? (chainIsOPStack(chainId) ? blockTimes[CHAIN_IDs.OPTIMISM] : undefined);
+
+  const now = getCurrentTime();
+  if (isDefined(cache) && now < cache.timestamp + cacheTTL) {
+    return { average: cache.average, blockRange: cache.blockRange };
+  }
+
+  // If the caller was not specific about highBlock, resolve it via the RPC provider. Subtract an offset
+  // to account for various RPC provider sync issues that might occur when querting the latest block.
+  if (!isDefined(highBlock)) {
+    highBlock = await provider.getBlockNumber();
+    highBlock -= highBlockOffset ?? defaultHighBlockOffset;
+  }
+  blockRange ??= defaultBlockRange;
+
+  const earliestBlockNumber = highBlock - blockRange;
+  const [firstBlock, lastBlock] = await Promise.all([
+    provider.getBlock(earliestBlockNumber),
+    provider.getBlock(highBlock),
+  ]);
+  [firstBlock, lastBlock].forEach((block: Block | undefined) => {
+    if (!isDefined(block?.timestamp)) {
+      const network = getNetworkName(chainId);
+      const blockNumber = block === firstBlock ? earliestBlockNumber : highBlock;
+      throw new Error(`BlockFinder: Failed to fetch block ${blockNumber} on ${network}`);
+    }
+  });
+
+  const average = (lastBlock.timestamp - firstBlock.timestamp) / blockRange;
+  blockTimes[chainId] = { timestamp: now, average, blockRange };
+
+  return { average, blockRange };
+}
+
+async function estimateBlocksElapsed(seconds: number, cushionPercentage = 0.0, provider: Provider): Promise<number> {
+  const cushionMultiplier = cushionPercentage + 1.0;
+  const { average } = await averageBlockTime(provider);
+  return Math.floor((seconds * cushionMultiplier) / average);
+}
+
+export class EVMBlockFinder extends BlockFinder<EVMBlock> {
+  constructor(
+    private readonly provider: Provider,
+    private readonly blocks: EVMBlock[] = []
+  ) {
+    super();
+  }
+
+  /**
+   * @notice Gets the latest block whose timestamp is <= the provided timestamp.
+   * @param number Timestamp timestamp to search.
+   * @param hints Optional low and high block to bound the search space.
+   */
+  public async getBlockForTimestamp(timestamp: number | string, hints: BlockFinderHints = {}): Promise<EVMBlock> {
+    timestamp = Number(timestamp);
+    assert(timestamp !== undefined && timestamp !== null, "timestamp must be provided");
+    // If the last block we have stored is too early, grab the latest block.
+    if (this.blocks.length === 0 || this.blocks[this.blocks.length - 1].timestamp < timestamp) {
+      const block = await this.getLatestBlock();
+      if (timestamp >= block.timestamp) return block;
+    }
+
+    // Prime the BlockFinder cache with any supplied hints.
+    // If the hint is accurate, then this will bypass the subsequent estimation.
+    await Promise.all(
+      Object.values(hints)
+        .filter((blockNumber) => isDefined(blockNumber))
+        .map((blockNumber) => this.getBlock(blockNumber))
+    );
+
+    // Check the first block. If it's greater than our timestamp, we need to find an earlier block.
+    if (this.blocks[0].timestamp > timestamp) {
+      const initialBlock = this.blocks[0];
+      // We use a 2x cushion to reduce the number of iterations in the following loop and increase the chance
+      // that the first block we find sets a floor for the target timestamp. The loop converges on the correct block
+      // slower than the following incremental search performed by `findBlock`, so we want to minimize the number of
+      // loop iterations in favor of searching more blocks over the `findBlock` search.
+      const cushion = 1;
+      const incrementDistance = Math.max(
+        // Ensure the increment block distance is _at least_ a single block to prevent an infinite loop.
+        await estimateBlocksElapsed(initialBlock.timestamp - timestamp, cushion, this.provider),
+        1
+      );
+
+      // Search backwards by a constant increment until we find a block before the timestamp or hit block 0.
+      for (let multiplier = 1; ; multiplier++) {
+        const distance = multiplier * incrementDistance;
+        const blockNumber = Math.max(0, initialBlock.number - distance);
+        const block = await this.getBlock(blockNumber);
+        if (block.timestamp <= timestamp) break; // Found an earlier block.
+        assert(blockNumber > 0, "timestamp is before block 0"); // Block 0 was not earlier than this timestamp. The row.
+      }
+    }
+
+    // Find the index where the block would be inserted and use that as the end block (since it is >= the timestamp).
+    const index = sortedIndexBy(this.blocks, { timestamp } as Block, "timestamp");
+    return this.findBlock(this.blocks[index - 1], this.blocks[index], timestamp);
+  }
+
+  // Grabs the most recent block and caches it.
+  private async getLatestBlock() {
+    const block = await this.provider.getBlock("latest");
+    const index = sortedIndexBy(this.blocks, block, "number");
+    if (this.blocks[index]?.number !== block.number) this.blocks.splice(index, 0, block);
+    return this.blocks[index];
+  }
+
+  // Grabs the block for a particular number and caches it.
+  private async getBlock(number: number) {
+    let index = sortedIndexBy(this.blocks, { number } as Block, "number");
+    if (this.blocks[index]?.number === number) return this.blocks[index]; // Return early if block already exists.
+    const block = await this.provider.getBlock(number);
+
+    // Recompute the index after the async call since the state of this.blocks could have changed!
+    index = sortedIndexBy(this.blocks, { number } as Block, "number");
+
+    // Rerun this check to avoid duplicate insertion.
+    if (this.blocks[index]?.number === number) return this.blocks[index];
+    this.blocks.splice(index, 0, block); // A simple insert at index.
+    return block;
+  }
+
+  // Return the latest block, between startBlock and endBlock, whose timestamp is <= timestamp.
+  // Effectively, this is an interpolation search algorithm to minimize block requests.
+  // Note: startBlock and endBlock _must_ be different blocks.
+  private async findBlock(_startBlock: EVMBlock, _endBlock: EVMBlock, timestamp: number): Promise<EVMBlock> {
+    const [startBlock, endBlock] = [_startBlock, _endBlock];
+    // In the case of equality, the endBlock is expected to be passed as the one whose timestamp === the requested
+    // timestamp.
+    if (endBlock.timestamp === timestamp) return endBlock;
+
+    // If there's no equality, but the blocks are adjacent, return the startBlock, since we want the returned block's
+    // timestamp to be <= the requested timestamp.
+    if (endBlock.number === startBlock.number + 1) return startBlock;
+
+    assert(endBlock.number !== startBlock.number, "startBlock cannot equal endBlock");
+    assert(
+      timestamp < endBlock.timestamp && timestamp > startBlock.timestamp,
+      "timestamp not in between start and end blocks"
+    );
+
+    // Interpolating the timestamp we're searching for to block numbers.
+    const totalTimeDifference = endBlock.timestamp - startBlock.timestamp;
+    const totalBlockDistance = endBlock.number - startBlock.number;
+    const blockPercentile = (timestamp - startBlock.timestamp) / totalTimeDifference;
+    const estimatedBlock = startBlock.number + Math.round(blockPercentile * totalBlockDistance);
+
+    // Clamp ensures the estimated block is strictly greater than the start block and strictly less than the end block.
+    const newBlock = await this.getBlock(clamp(estimatedBlock, startBlock.number + 1, endBlock.number - 1));
+
+    // Depending on whether the new block is below or above the timestamp, narrow the search space accordingly.
+    if (newBlock.timestamp < timestamp) {
+      return this.findBlock(newBlock, endBlock, timestamp);
+    } else {
+      return this.findBlock(startBlock, newBlock, timestamp);
+    }
+  }
+}

package/src/arch/evm/index.ts

@@ -1 +1,2 @@
 export * from "./SpokeUtils";
+export * from "./BlockUtils";

package/src/arch/svm/SpokeUtils.ts

@@ -21,22 +21,29 @@ import {
 import assert from "assert";
 import { arrayify, hexZeroPad, hexlify } from "ethers/lib/utils";
 import { Logger } from "winston";
+
 import { CHAIN_IDs } from "../../constants";
-import { Deposit, FillStatus, FillWithBlock, RelayData } from "../../interfaces";
+import { Deposit, DepositWithBlock, FillStatus, FillWithBlock, RelayData } from "../../interfaces";
 import {
   BigNumber,
+  isUnsafeDepositId,
   SvmAddress,
-  chainIsSvm,
-  chunk,
   getTokenInfo,
   isDefined,
-  isUnsafeDepositId,
-  keccak256,
   toAddressType,
+  keccak256,
+  chainIsSvm,
+  chunk,
 } from "../../utils";
-import { SvmCpiEventsClient, getEventAuthority, getFillStatusPda, getStatePda, unwrapEventData } from "./";
+import { getStatePda, SvmCpiEventsClient, getFillStatusPda, unwrapEventData, getEventAuthority } from "./";
 import { SVMEventNames, SVMProvider } from "./types";
 
+/**
+ * @note: Average Solana slot duration is about 400-500ms. We can be conservative
+ *        and choose 400 to ensure that the most slots get included in our ranges
+ */
+export const SLOT_DURATION_MS = 400;
+
 /**
  * @param spokePool SpokePool Contract instance.
  * @param deposit V3Deopsit instance.
@@ -81,17 +88,76 @@ export function getDepositIdAtBlock(_contract: unknown, _blockTag: number): Prom
   throw new Error("getDepositIdAtBlock: not implemented");
 }
 
-export function findDepositBlock(
-  _spokePool: unknown,
+/**
+ * Finds deposit events within a 2-day window ending at the specified slot.
+ *
+ * @remarks
+ * This implementation uses a slot-limited search approach because Solana PDA state has
+ * limitations that prevent directly referencing old deposit IDs. Unlike EVM chains where
+ * we might use binary search across the entire chain history, in Solana we must query within
+ * a constrained slot range.
+ *
+ * The search window is calculated by:
+ * 1. Using the provided slot (or current confirmed slot if none is provided)
+ * 2. Looking back 2 days worth of slots from that point
+ *
+ * We use a 2-day window because:
+ * 1. Most valid deposits that need to be processed will be recent
+ * 2. This covers multiple bundle submission periods
+ * 3. It balances performance with practical deposit age
+ *
+ * @important
+ * This function may return `undefined` for valid deposit IDs that are older than the search
+ * window (approximately 2 days before the specified slot). This is an acceptable limitation
+ * as deposits this old are typically not relevant to current operations.
+ *
+ * @param eventClient - SvmCpiEventsClient instance
+ * @param depositId - The deposit ID to search for
+ * @param slot - The slot to search up to (defaults to current slot). The search will look
+ *              for deposits between (slot - secondsLookback) and slot.
+ * @param secondsLookback - The number of seconds to look back for deposits (defaults to 2 days).
+ * @returns The deposit if found within the slot window, undefined otherwise
+ */
+export async function findDeposit(
+  eventClient: SvmCpiEventsClient,
   depositId: BigNumber,
-  _lowBlock: number,
-  _highBlock?: number
-): Promise<number | undefined> {
+  slot?: bigint,
+  secondsLookback = 2 * 24 * 60 * 60 // 2 days
+): Promise<DepositWithBlock | undefined> {
   // We can only perform this search when we have a safe deposit ID.
   if (isUnsafeDepositId(depositId)) {
     throw new Error(`Cannot binary search for depositId ${depositId}`);
   }
-  throw new Error("findDepositBlock: not implemented");
+
+  const provider = eventClient.getRpc();
+  const currentSlot = await provider.getSlot({ commitment: "confirmed" }).send();
+
+  // If no slot is provided, use the current slot
+  // If a slot is provided, ensure it's not in the future
+  const endSlot = slot !== undefined ? BigInt(Math.min(Number(slot), Number(currentSlot))) : currentSlot;
+
+  // Calculate start slot (approximately secondsLookback seconds earlier)
+  const slotsInElapsed = BigInt(Math.round((secondsLookback * 1000) / SLOT_DURATION_MS));
+  const startSlot = endSlot - slotsInElapsed;
+
+  // Query for the deposit events with this limited slot range. Filter by deposit id.
+  const depositEvent = (await eventClient.queryEvents("FundsDeposited", startSlot, endSlot))?.find((event) =>
+    depositId.eq((event.data as unknown as { depositId: BigNumber }).depositId)
+  );
+
+  // If no deposit event is found, return undefined
+  if (!depositEvent) {
+    return undefined;
+  }
+
+  // Return the deposit event with block info
+  return {
+    txnRef: depositEvent.signature.toString(),
+    blockNumber: Number(depositEvent.slot),
+    txnIndex: 0,
+    logIndex: 0,
+    ...(unwrapEventData(depositEvent.data) as Record<string, unknown>),
+  } as DepositWithBlock;
 }
 
 /**
@@ -318,9 +384,9 @@ export async function fillRelayInstruction(
     getFillStatusPda(spokePool.toV2Address(), deposit, deposit.destinationChainId),
     getEventAuthority(),
   ]);
-  const depositIdBuffer = Buffer.alloc(32);
-  const shortenedBuffer = Buffer.from(deposit.depositId.toHexString().slice(2), "hex");
-  shortenedBuffer.copy(depositIdBuffer, 32 - shortenedBuffer.length);
+  const depositIdBuffer = new Uint8Array(32);
+  const shortenedBuffer = new Uint8Array(Buffer.from(deposit.depositId.toHexString().slice(2), "hex"));
+  depositIdBuffer.set(shortenedBuffer, 32 - shortenedBuffer.length);
 
   return SvmSpokeClient.getFillRelayInstruction({
     signer: relayer,
@@ -343,7 +409,7 @@ export async function fillRelayInstruction(
       originChainId: BigInt(deposit.originChainId),
       fillDeadline: deposit.fillDeadline,
       exclusivityDeadline: deposit.exclusivityDeadline,
-      depositId: new Uint8Array(depositIdBuffer),
+      depositId: depositIdBuffer,
       message: new Uint8Array(Buffer.from(deposit.message.slice(2), "hex")),
     }),
     repaymentChainId: some(BigInt(repaymentChainId)),
@@ -409,7 +475,11 @@ export async function getAssociatedTokenAddress(
 ): Promise<Address<string>> {
   const [associatedToken] = await getProgramDerivedAddress({
     programAddress: ASSOCIATED_TOKEN_PROGRAM_ADDRESS,
-    seeds: [owner.toBuffer(), SvmAddress.from(tokenProgramId).toBuffer(), mint.toBuffer()],
+    seeds: [
+      new Uint8Array(owner.toBuffer()),
+      new Uint8Array(SvmAddress.from(tokenProgramId).toBuffer()),
+      new Uint8Array(mint.toBuffer()),
+    ],
   });
   return associatedToken;
 }

package/src/arch/svm/eventsClient.ts

@@ -1,7 +1,15 @@
 import { Idl } from "@coral-xyz/anchor";
 import { getDeployedAddress, SvmSpokeIdl } from "@across-protocol/contracts";
 import { getSolanaChainId } from "@across-protocol/contracts/dist/src/svm/web3-v1";
-import web3, { Address, Commitment, GetSignaturesForAddressApi, GetTransactionApi, Signature } from "@solana/kit";
+import {
+  address,
+  Address,
+  Commitment,
+  getProgramDerivedAddress,
+  GetSignaturesForAddressApi,
+  GetTransactionApi,
+  Signature,
+} from "@solana/kit";
 import { bs58, chainIsSvm, getMessageHash } from "../../utils";
 import { EventName, EventWithData, SVMProvider } from "./types";
 import { decodeEvent, isDevnet } from "./utils";
@@ -56,12 +64,12 @@ export class SvmCpiEventsClient {
   }
 
   public static async createFor(rpc: SVMProvider, programId: string, idl: Idl): Promise<SvmCpiEventsClient> {
-    const address = web3.address(programId);
-    const [eventAuthority] = await web3.getProgramDerivedAddress({
-      programAddress: address,
+    const programAddress = address(programId);
+    const [eventAuthority] = await getProgramDerivedAddress({
+      programAddress,
       seeds: ["__event_authority"],
     });
-    return new SvmCpiEventsClient(rpc, address, eventAuthority, idl);
+    return new SvmCpiEventsClient(rpc, programAddress, eventAuthority, idl);
   }
 
   /**

package/src/arch/svm/utils.ts

@@ -1,4 +1,5 @@
-import { SvmSpokeClient } from "@across-protocol/contracts";
+import bs58 from "bs58";
+import { ethers } from "ethers";
 import { BN, BorshEventCoder, Idl } from "@coral-xyz/anchor";
 import {
   Address,
@@ -9,6 +10,7 @@ import {
   isAddress,
   type TransactionSigner,
 } from "@solana/kit";
+import { SvmSpokeClient } from "@across-protocol/contracts";
 import { FillType, RelayData } from "../../interfaces";
 import { BigNumber, SvmAddress, getRelayDataHash, isUint8Array } from "../../utils";
 import { EventName, SVMEventNames, SVMProvider } from "./types";
@@ -220,3 +222,12 @@ export const getEventAuthority = async () => {
   });
   return eventAuthority;
 };
+
+/**
+ * Returns a random SVM address.
+ */
+export function getRandomSvmAddress() {
+  const bytes = ethers.utils.randomBytes(32);
+  const base58Address = bs58.encode(bytes);
+  return address(base58Address);
+}

package/src/clients/HubPoolClient.ts

@@ -22,9 +22,9 @@ import {
   TokenRunningBalance,
 } from "../interfaces";
 import * as lpFeeCalculator from "../lpFeeCalculator";
+import { EVMBlockFinder } from "../arch/evm";
 import {
   BigNumber,
-  BlockFinder,
   bnZero,
   dedupArray,
   EventSearchConfig,
@@ -97,7 +97,7 @@ export class HubPoolClient extends BaseAbstractClient {
   protected pendingRootBundle: PendingRootBundle | undefined;
 
   public currentTime: number | undefined;
-  public readonly blockFinder: BlockFinder;
+  public readonly blockFinder: EVMBlockFinder;
 
   constructor(
     readonly logger: winston.Logger,
@@ -121,7 +121,7 @@ export class HubPoolClient extends BaseAbstractClient {
     this.firstHeightToSearch = eventSearchConfig.from;
 
     const provider = this.hubPool.provider;
-    this.blockFinder = new BlockFinder(provider);
+    this.blockFinder = new EVMBlockFinder(provider);
   }
 
   protected hubPoolEventFilters(): Record<HubPoolEvent, EventFilter> {

package/src/clients/SpokePoolClient/SVMSpokePoolClient.ts

@@ -7,6 +7,7 @@ import {
   getTimestampForSlot,
   getStatePda,
   SvmCpiEventsClient,
+  findDeposit,
   relayFillStatus,
   fillStatusArray,
 } from "../../arch/svm";
@@ -15,6 +16,8 @@ import {
   BigNumber,
   DepositSearchResult,
   EventSearchConfig,
+  InvalidFill,
+  isZeroAddress,
   MakeOptional,
   sortEventsAscendingInPlace,
 } from "../../utils";
@@ -208,10 +211,31 @@ export class SvmSpokePoolClient extends SpokePoolClient {
 
   /**
    * Finds a deposit based on its deposit ID on the SVM chain.
-   * TODO: Implement SVM state query for deposit details.
    */
-  public findDeposit(_depositId: BigNumber): Promise<DepositSearchResult> {
-    throw new Error("findDeposit not implemented for SVM");
+  public async findDeposit(depositId: BigNumber): Promise<DepositSearchResult> {
+    const deposit = await findDeposit(this.svmEventsClient, depositId);
+    if (!deposit) {
+      return {
+        found: false,
+        code: InvalidFill.DepositIdNotFound,
+        reason: `Deposit with ID ${depositId} not found`,
+      };
+    }
+    // Because we have additional context about this deposit, we can enrich it
+    // with additional information.
+    return {
+      found: true,
+      deposit: {
+        ...deposit,
+        quoteBlockNumber: await this.getBlockNumber(Number(deposit.quoteTimestamp)),
+        originChainId: this.chainId,
+        fromLiteChain: this.isOriginLiteChain(deposit),
+        toLiteChain: this.isDestinationLiteChain(deposit),
+        outputToken: isZeroAddress(deposit.outputToken)
+          ? this.getDestinationTokenForDeposit(deposit)
+          : deposit.outputToken,
+      },
+    };
   }
 
   /**

package/src/clients/SpokePoolClient/SpokePoolClient.ts

@@ -18,6 +18,7 @@ import {
   toAddress,
   validateFillForDeposit,
   chainIsEvm,
+  chainIsProd,
 } from "../../utils";
 import { duplicateEvent, sortEventsAscendingInPlace } from "../../utils/EventUtils";
 import { ZERO_ADDRESS } from "../../constants";
@@ -349,7 +350,7 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
     fillCount: number;
     invalidFills: FillWithBlock[];
   } {
-    const { outputAmount } = deposit;
+    const { outputAmount, originChainId } = deposit;
     const fillsForDeposit = this.depositHashesToFills[this.getDepositHash(deposit)];
     // If no fills then the full amount is remaining.
     if (fillsForDeposit === undefined || fillsForDeposit.length === 0) {
@@ -405,8 +406,10 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
       }
       return newInvalidFill;
     });
+    // Log invalid and unrepayable fills as warns if we are on a production network.
+    const logLevel = chainIsProd(originChainId) ? "warn" : "debug";
     if (invalidFillsForDeposit.length > 0) {
-      this.logger.warn({
+      this.logger[logLevel]({
         at: "SpokePoolClient",
         chainId: this.chainId,
         message: "Invalid fills found matching deposit ID",
@@ -417,7 +420,7 @@ export abstract class SpokePoolClient extends BaseAbstractClient {
     }
     const unrepayableFillsForDeposit = unrepayableFills.filter((x) => x.depositId.eq(deposit.depositId));
     if (unrepayableFillsForDeposit.length > 0) {
-      this.logger.warn({
+      this.logger[logLevel]({
         at: "SpokePoolClient",
         chainId: this.chainId,
         message: "Unrepayable fills found where we need to switch repayment address and or chain",