@across-protocol/sdk 4.1.63-alpha.1 → 4.1.63-beta.0

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

@@ -32,7 +32,7 @@ export function getWidestPossibleExpectedBlockRange(
   // filled during the challenge period.
   const latestPossibleBundleEndBlockNumbers = chainIdListForBundleEvaluationBlockNumbers.map(
     (chainId: number, index) =>
-      spokeClients[chainId] && Math.max(spokeClients[chainId].latestBlockSearched - endBlockBuffers[index], 0)
+      spokeClients[chainId] && Math.max(spokeClients[chainId].latestHeightSearched - endBlockBuffers[index], 0)
   );
   return chainIdListForBundleEvaluationBlockNumbers.map((chainId: number, index) => {
     const lastEndBlockForChain = clients.hubPoolClient.getLatestBundleEndBlockForChain(

package/src/clients/HubPoolClient.ts

@@ -105,7 +105,7 @@ export class HubPoolClient extends BaseAbstractClient {
     public configStoreClient: ConfigStoreClient,
     public deploymentBlock = 0,
     readonly chainId: number = 1,
-    eventSearchConfig: MakeOptional<EventSearchConfig, "toBlock"> = { fromBlock: 0, maxBlockLookBack: 0 },
+    eventSearchConfig: MakeOptional<EventSearchConfig, "to"> = { from: 0, maxLookBack: 0 },
     protected readonly configOverride: {
       ignoredHubExecutedBundles: number[];
       ignoredHubProposedBundles: number[];
@@ -117,8 +117,8 @@ export class HubPoolClient extends BaseAbstractClient {
     cachingMechanism?: CachingMechanismInterface
   ) {
     super(eventSearchConfig, cachingMechanism);
-    this.latestBlockSearched = Math.min(deploymentBlock - 1, 0);
-    this.firstBlockToSearch = eventSearchConfig.fromBlock;
+    this.latestHeightSearched = Math.min(deploymentBlock - 1, 0);
+    this.firstHeightToSearch = eventSearchConfig.from;
 
     const provider = this.hubPool.provider;
     this.blockFinder = new BlockFinder(provider);
@@ -254,7 +254,7 @@ export class HubPoolClient extends BaseAbstractClient {
     return l2Token !== undefined;
   }
 
-  l2TokenHasPoolRebalanceRoute(l2Token: string, l2ChainId: number, hubPoolBlock = this.latestBlockSearched): boolean {
+  l2TokenHasPoolRebalanceRoute(l2Token: string, l2ChainId: number, hubPoolBlock = this.latestHeightSearched): boolean {
     return Object.values(this.l1TokensToDestinationTokensWithBlock).some((destinationTokenMapping) => {
       return Object.entries(destinationTokenMapping).some(([_l2ChainId, setPoolRebalanceRouteEvents]) => {
         return setPoolRebalanceRouteEvents.some((e) => {
@@ -312,7 +312,7 @@ export class HubPoolClient extends BaseAbstractClient {
   }
 
   async getCurrentPoolUtilization(l1Token: string): Promise<BigNumber> {
-    const blockNumber = this.latestBlockSearched ?? (await this.hubPool.provider.getBlockNumber());
+    const blockNumber = this.latestHeightSearched ?? (await this.hubPool.provider.getBlockNumber());
     return await this.getUtilization(l1Token, blockNumber, bnZero, getCurrentTime(), 0);
   }
 
@@ -523,7 +523,7 @@ export class HubPoolClient extends BaseAbstractClient {
     chainIdA: number,
     tokenB: string,
     chainIdB: number,
-    hubPoolBlock = this.latestBlockSearched
+    hubPoolBlock = this.latestHeightSearched
   ): boolean {
     if (
       !this.l2TokenHasPoolRebalanceRoute(tokenA, chainIdA, hubPoolBlock) ||
@@ -719,7 +719,7 @@ export class HubPoolClient extends BaseAbstractClient {
     if (n === 0) {
       throw new Error("n cannot be 0");
     }
-    if (!this.latestBlockSearched) {
+    if (!this.latestHeightSearched) {
       throw new Error("HubPoolClient::getNthFullyExecutedRootBundle client not updated");
     }
 
@@ -728,7 +728,7 @@ export class HubPoolClient extends BaseAbstractClient {
     // If n is negative, then return the Nth latest executed bundle, otherwise return the Nth earliest
     // executed bundle.
     if (n < 0) {
-      let nextLatestMainnetBlock = startBlock ?? this.latestBlockSearched;
+      let nextLatestMainnetBlock = startBlock ?? this.latestHeightSearched;
       for (let i = 0; i < Math.abs(n); i++) {
         bundleToReturn = this.getLatestFullyExecutedRootBundle(nextLatestMainnetBlock);
         const bundleBlockNumber = bundleToReturn ? bundleToReturn.blockNumber : 0;
@@ -740,12 +740,12 @@ export class HubPoolClient extends BaseAbstractClient {
     } else {
       let nextStartBlock = startBlock ?? 0;
       for (let i = 0; i < n; i++) {
-        bundleToReturn = this.getEarliestFullyExecutedRootBundle(this.latestBlockSearched, nextStartBlock);
+        bundleToReturn = this.getEarliestFullyExecutedRootBundle(this.latestHeightSearched, nextStartBlock);
         const bundleBlockNumber = bundleToReturn ? bundleToReturn.blockNumber : 0;
 
         // Add 1 so that next `getEarliestFullyExecutedRootBundle` call filters out the root bundle we just found
         // because its block number is < nextStartBlock.
-        nextStartBlock = Math.min(bundleBlockNumber + 1, this.latestBlockSearched);
+        nextStartBlock = Math.min(bundleBlockNumber + 1, this.latestHeightSearched);
       }
     }
 
@@ -831,7 +831,7 @@ export class HubPoolClient extends BaseAbstractClient {
       // instantiation. However, certain events generally must be queried back to HubPool genesis.
       const overrideEvents = ["CrossChainContractsSet", "L1TokenEnabledForLiquidityProvision", "SetPoolRebalanceRoute"];
       if (overrideEvents.includes(eventName) && !this.isUpdated) {
-        _searchConfig.fromBlock = this.deploymentBlock;
+        _searchConfig.from = this.deploymentBlock;
       }
 
       return {
@@ -853,7 +853,7 @@ export class HubPoolClient extends BaseAbstractClient {
     const [multicallOutput, ...events] = await Promise.all([
       hubPool.callStatic.multicall(
         multicallFunctions.map((f) => hubPool.interface.encodeFunctionData(f)),
-        { blockTag: searchConfig.toBlock }
+        { blockTag: searchConfig.to }
       ),
       ...eventSearchConfigs.map((config) => paginatedEventQuery(hubPool, config.filter, config.searchConfig)),
     ]);
@@ -874,7 +874,7 @@ export class HubPoolClient extends BaseAbstractClient {
       success: true,
       currentTime,
       pendingRootBundleProposal,
-      searchEndBlock: searchConfig.toBlock,
+      searchEndBlock: searchConfig.to,
       events: _events,
     };
   }
@@ -1087,9 +1087,9 @@ export class HubPoolClient extends BaseAbstractClient {
     }
 
     this.currentTime = currentTime;
-    this.latestBlockSearched = searchEndBlock;
-    this.firstBlockToSearch = update.searchEndBlock + 1; // Next iteration should start off from where this one ended.
-    this.eventSearchConfig.toBlock = undefined; // Caller can re-set on subsequent updates if necessary.
+    this.latestHeightSearched = searchEndBlock;
+    this.firstHeightToSearch = update.searchEndBlock + 1; // Next iteration should start off from where this one ended.
+    this.eventSearchConfig.to = undefined; // Caller can re-set on subsequent updates if necessary.
 
     this.isUpdated = true;
     this.logger.debug({ at: "HubPoolClient::update", message: "HubPool client updated!", searchEndBlock });

package/src/clients/SpokePoolClient/EVMSpokePoolClient.ts

@@ -39,20 +39,17 @@ export class EVMSpokePoolClient extends SpokePoolClient {
     hubPoolClient: HubPoolClient | null,
     chainId: number,
     deploymentBlock: number,
-    eventSearchConfig: MakeOptional<EventSearchConfig, "toBlock"> = { fromBlock: 0, maxBlockLookBack: 0 }
+    eventSearchConfig: MakeOptional<EventSearchConfig, "to"> = { from: 0, maxLookBack: 0 }
   ) {
     super(logger, hubPoolClient, chainId, deploymentBlock, eventSearchConfig);
   }
 
-  public override relayFillStatus(relayData: RelayData, blockTag?: number | "latest"): Promise<FillStatus> {
-    return relayFillStatus(this.spokePool, relayData, blockTag, this.chainId);
+  public override relayFillStatus(relayData: RelayData, atHeight?: number): Promise<FillStatus> {
+    return relayFillStatus(this.spokePool, relayData, atHeight, this.chainId);
   }
 
-  public override fillStatusArray(
-    relayData: RelayData[],
-    blockTag?: number | "latest"
-  ): Promise<(FillStatus | undefined)[]> {
-    return fillStatusArray(this.spokePool, relayData, blockTag);
+  public override fillStatusArray(relayData: RelayData[], atHeight?: number): Promise<(FillStatus | undefined)[]> {
+    return fillStatusArray(this.spokePool, relayData, atHeight);
   }
 
   public override getMaxFillDeadlineInRange(startBlock: number, endBlock: number): Promise<number> {
@@ -89,7 +86,7 @@ export class EVMSpokePoolClient extends SpokePoolClient {
       // However, certain events have special overriding requirements to their search ranges:
       // - EnabledDepositRoute: The full history is always required, so override the requested fromBlock.
       if (eventName === "EnabledDepositRoute" && !this.isUpdated) {
-        _searchConfig.fromBlock = this.deploymentBlock;
+        _searchConfig.from = this.deploymentBlock;
       }
 
       return {
@@ -110,7 +107,7 @@ export class EVMSpokePoolClient extends SpokePoolClient {
     const [multicallOutput, ...events] = await Promise.all([
       spokePool.callStatic.multicall(
         multicallFunctions.map((f) => spokePool.interface.encodeFunctionData(f)),
-        { blockTag: searchConfig.toBlock }
+        { blockTag: searchConfig.to }
       ),
       ...eventSearchConfigs.map((config) => paginatedEventQuery(this.spokePool, config.filter, config.searchConfig)),
     ]);
@@ -124,17 +121,22 @@ export class EVMSpokePoolClient extends SpokePoolClient {
       const errMsg = BigNumber.isBigNumber(currentTime)
         ? `currentTime: ${currentTime} < ${toBN(this.currentTime)}`
         : `currentTime is not a BigNumber: ${JSON.stringify(currentTime)}`;
-      throw new Error(`SpokePoolClient::update: ${errMsg}`);
+      throw new Error(`EVMSpokePoolClient::update: ${errMsg}`);
     }
 
     // Sort all events to ensure they are stored in a consistent order.
     events.forEach((events) => sortEventsAscendingInPlace(events.map(logToSortableEvent)));
 
+    // Map events to SortableEvent
+    const eventsWithBlockNumber = events.map((eventList) =>
+      eventList.map((event) => spreadEventWithBlockNumber(event))
+    );
+
     return {
       success: true,
       currentTime: currentTime.toNumber(), // uint32
-      searchEndBlock: searchConfig.toBlock,
-      events,
+      searchEndBlock: searchConfig.to,
+      events: eventsWithBlockNumber,
     };
   }
 
@@ -149,31 +151,31 @@ export class EVMSpokePoolClient extends SpokePoolClient {
     }
 
     // No deposit found; revert to searching for it.
-    const upperBound = this.latestBlockSearched || undefined; // Don't permit block 0 as the high block.
-    const fromBlock = await findDepositBlock(this.spokePool, depositId, this.deploymentBlock, upperBound);
+    const upperBound = this.latestHeightSearched || undefined; // Don't permit block 0 as the high block.
+    const from = await findDepositBlock(this.spokePool, depositId, this.deploymentBlock, upperBound);
     const chain = getNetworkName(this.chainId);
-    if (!fromBlock) {
+    if (!from) {
       const reason =
         `Unable to find ${chain} depositId ${depositId}` +
         ` within blocks [${this.deploymentBlock}, ${upperBound ?? "latest"}].`;
       return { found: false, code: InvalidFill.DepositIdNotFound, reason };
     }
 
-    const toBlock = fromBlock;
+    const to = from;
     const tStart = Date.now();
     // Check both V3FundsDeposited and FundsDeposited events to look for a specified depositId.
-    const { maxBlockLookBack } = this.eventSearchConfig;
+    const { maxLookBack } = this.eventSearchConfig;
     const query = (
       await Promise.all([
         paginatedEventQuery(
           this.spokePool,
           this.spokePool.filters.V3FundsDeposited(null, null, null, null, null, depositId),
-          { fromBlock, toBlock, maxBlockLookBack }
+          { from, to, maxLookBack }
         ),
         paginatedEventQuery(
           this.spokePool,
           this.spokePool.filters.FundsDeposited(null, null, null, null, null, depositId),
-          { fromBlock, toBlock, maxBlockLookBack }
+          { from, to, maxLookBack }
         ),
       ])
     ).flat();
@@ -184,7 +186,7 @@ export class EVMSpokePoolClient extends SpokePoolClient {
       return {
         found: false,
         code: InvalidFill.DepositIdNotFound,
-        reason: `${chain} depositId ${depositId} not found at block ${fromBlock}.`,
+        reason: `${chain} depositId ${depositId} not found at block ${from}.`,
       };
     }
 

package/src/clients/SpokePoolClient/SVMSpokePoolClient.ts

@@ -0,0 +1,244 @@
+import { Address, Rpc, RpcTransport, SolanaRpcApiFromTransport } from "@solana/kit";
+import winston from "winston";
+import {
+  SVMEventNames,
+  unwrapEventData,
+  getFillDeadline,
+  getTimestampForSlot,
+  getStatePda,
+  SvmCpiEventsClient,
+  relayFillStatus,
+  fillStatusArray,
+} from "../../arch/svm";
+import { FillStatus, RelayData, SortableEvent } from "../../interfaces";
+import {
+  BigNumber,
+  DepositSearchResult,
+  EventSearchConfig,
+  MakeOptional,
+  sortEventsAscendingInPlace,
+} from "../../utils";
+import { isUpdateFailureReason } from "../BaseAbstractClient";
+import { HubPoolClient } from "../HubPoolClient";
+import { knownEventNames, SpokePoolClient, SpokePoolUpdate } from "./SpokePoolClient";
+
+/**
+ * SvmSpokePoolClient is a client for the SVM SpokePool program. It extends the base SpokePoolClient
+ * and implements the abstract methods required for interacting with an SVM Spoke Pool.
+ */
+export class SvmSpokePoolClient extends SpokePoolClient {
+  /**
+   * Protected constructor. Use the async create() method to instantiate.
+   */
+  protected constructor(
+    logger: winston.Logger,
+    hubPoolClient: HubPoolClient | null,
+    chainId: number,
+    deploymentSlot: bigint, // Using slot instead of block number for SVM
+    eventSearchConfig: MakeOptional<EventSearchConfig, "to">,
+    public svmEventsClient: SvmCpiEventsClient,
+    protected programId: Address,
+    protected statePda: Address
+  ) {
+    // Convert deploymentSlot to number for base class, might need refinement
+    super(logger, hubPoolClient, chainId, Number(deploymentSlot), eventSearchConfig);
+  }
+
+  /**
+   * Factory method to asynchronously create an instance of SvmSpokePoolClient.
+   */
+  public static async create(
+    logger: winston.Logger,
+    hubPoolClient: HubPoolClient | null,
+    chainId: number,
+    deploymentSlot: bigint,
+    eventSearchConfig: MakeOptional<EventSearchConfig, "to"> = { from: 0, maxLookBack: 0 }, // Provide default
+    rpc: Rpc<SolanaRpcApiFromTransport<RpcTransport>>
+  ): Promise<SvmSpokePoolClient> {
+    const svmEventsClient = await SvmCpiEventsClient.create(rpc);
+    const programId = svmEventsClient.getProgramAddress();
+    const statePda = await getStatePda(programId);
+    return new SvmSpokePoolClient(
+      logger,
+      hubPoolClient,
+      chainId,
+      deploymentSlot,
+      eventSearchConfig,
+      svmEventsClient,
+      programId,
+      statePda
+    );
+  }
+
+  /**
+   * Factory method to asynchronously create an instance of SvmSpokePoolClient with an existing event client.
+   */
+  public static async createWithExistingEventClient(
+    logger: winston.Logger,
+    hubPoolClient: HubPoolClient | null,
+    chainId: number,
+    deploymentSlot: bigint,
+    eventSearchConfig: MakeOptional<EventSearchConfig, "to"> = { from: 0, maxLookBack: 0 }, // Provide default
+    eventClient: SvmCpiEventsClient
+  ) {
+    const programId = eventClient.getProgramAddress();
+    const statePda = await getStatePda(programId);
+    return new SvmSpokePoolClient(
+      logger,
+      hubPoolClient,
+      chainId,
+      deploymentSlot,
+      eventSearchConfig,
+      eventClient,
+      programId,
+      statePda
+    );
+  }
+
+  public _queryableEventNames(): string[] {
+    // We want to take the internal event names relevant to
+    // the SVM SpokePoolClient and filter them against the
+    // knownEventNames list that we reference in practice
+    const internalEventNames = Object.values(SVMEventNames);
+    return internalEventNames.filter((e) => knownEventNames.includes(e));
+  }
+
+  /**
+   * Performs an update to refresh the state of this client by querying SVM events.
+   */
+  protected async _update(eventsToQuery: string[]): Promise<SpokePoolUpdate> {
+    const searchConfig = await this.updateSearchConfig(this.svmEventsClient.getRpc());
+    if (isUpdateFailureReason(searchConfig)) {
+      const reason = searchConfig;
+      return { success: false, reason };
+    }
+
+    const deploymentSlot = BigInt(this.deploymentBlock);
+
+    const eventSearchConfigs = eventsToQuery.map((eventName) => {
+      if (!this._queryableEventNames().includes(eventName)) {
+        throw new Error(`SpokePoolClient: Cannot query unrecognised SpokePool event name: ${eventName}`);
+      }
+
+      const _searchConfig = { ...searchConfig }; // shallow copy
+
+      // By default, an event's query range is controlled by the `eventSearchConfig` passed in during instantiation.
+      // However, certain events have special overriding requirements to their search ranges:
+      // - EnabledDepositRoute: The full history is always required, so override the requested fromBlock.
+      if (eventName === "EnabledDepositRoute" && !this.isUpdated) {
+        _searchConfig.from = Number(deploymentSlot);
+      }
+
+      return _searchConfig as EventSearchConfig;
+    });
+
+    const spokePoolAddress = this.svmEventsClient.getProgramAddress();
+
+    this.log("debug", `Updating SpokePool client for chain ${this.chainId}`, {
+      eventsToQuery,
+      searchConfig,
+      spokePool: spokePoolAddress,
+    });
+
+    const timerStart = Date.now();
+
+    const [currentTime, ...eventsQueried] = await Promise.all([
+      this.svmEventsClient.getRpc().getBlockTime(BigInt(searchConfig.to)).send(),
+      ...eventsToQuery.map(async (eventName, idx) => {
+        const config = eventSearchConfigs[idx];
+        const events = await this.svmEventsClient.queryEvents(
+          eventName as SVMEventNames,
+          BigInt(config.from),
+          BigInt(config.to),
+          {
+            limit: config.maxLookBack,
+          }
+        );
+        return events.map(
+          (event): SortableEvent => ({
+            txnRef: event.signature,
+            blockNumber: Number(event.slot),
+            txnIndex: 0,
+            logIndex: 0,
+            ...(unwrapEventData(event.data) as Record<string, unknown>),
+          })
+        );
+      }),
+    ]);
+    this.log("debug", `Time to query new events from RPC for ${this.chainId}: ${Date.now() - timerStart} ms`);
+    if (currentTime < this.currentTime) {
+      const errMsg = `currentTime: ${currentTime} < ${this.currentTime}`;
+      throw new Error(`SvmSpokePoolClient::update: ${errMsg}`);
+    }
+
+    // Sort all events to ensure they are stored in a consistent order.
+    eventsQueried.forEach((events) => sortEventsAscendingInPlace(events));
+
+    return {
+      success: true,
+      currentTime: Number(currentTime), // uint32
+      searchEndBlock: searchConfig.to,
+      events: eventsQueried,
+    };
+  }
+
+  /**
+   * Retrieves the fill deadline buffer fetched from the State PDA.
+   * @note This function assumes that fill deadline buffer is a constant value in svm environments.
+   */
+  public override getMaxFillDeadlineInRange(_startSlot: number, _endSlot: number): Promise<number> {
+    return getFillDeadline(this.svmEventsClient.getRpc(), this.statePda);
+  }
+
+  /**
+   * Retrieves the timestamp for a given SVM slot number.
+   */
+  public override getTimestampForBlock(slot: number): Promise<number> {
+    return getTimestampForSlot(this.svmEventsClient.getRpc(), slot);
+  }
+
+  /**
+   * Retrieves the timestamp for a given SVM slot number.
+   * @note This function uses the same underlying function as getTimestampForBlock.
+   *       It is kept for consistency with the EVM SpokePoolClient.
+   */
+  public getTimeAt(slot: number): Promise<number> {
+    return getTimestampForSlot(this.svmEventsClient.getRpc(), slot);
+  }
+
+  /**
+   * 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");
+  }
+
+  /**
+   * Retrieves the fill status for a given relay data from the SVM chain.
+   */
+  public override relayFillStatus(
+    relayData: RelayData,
+    atHeight?: number,
+    destinationChainId?: number
+  ): Promise<FillStatus> {
+    destinationChainId ??= this.chainId;
+    return relayFillStatus(this.programId, relayData, destinationChainId, this.svmEventsClient, atHeight);
+  }
+
+  /**
+   * Retrieves the fill status for an array of given relay data.
+   * @param relayData The array relay data to retrieve the fill status for.
+   * @param atHeight The slot at which to query the fill status.
+   * @returns The fill status for each of the given relay data.
+   */
+  public fillStatusArray(
+    relayData: RelayData[],
+    atHeight?: number,
+    destinationChainId?: number
+  ): Promise<(FillStatus | undefined)[]> {
+    // @note: deploymentBlock actually refers to the deployment slot. Also, blockTag should be a slot number.
+    destinationChainId ??= this.chainId;
+    return fillStatusArray(this.programId, relayData, destinationChainId, this.svmEventsClient, atHeight, this.logger);
+  }
+}