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

package/src/utils/AddressUtils.ts

@@ -1,6 +1,5 @@
 import { providers, utils } from "ethers";
 import bs58 from "bs58";
-import { Address as V2Address } from "@solana/kit";
 import { BigNumber, chainIsEvm } from "./";
 
 /**
@@ -78,9 +77,9 @@ export function isValidEvmAddress(address: string): boolean {
  * @returns a child `Address` type most fitting for the chain ID.
  * @todo: Change this to `toAddress` once we remove the other `toAddress` function.
  */
-export function toAddressType(address: string): Address | EvmAddress | SvmAddress {
+export function toAddressType(address: string, chainId: number): Address | EvmAddress | SvmAddress {
   try {
-    if (utils.isHexString(address)) {
+    if (chainIsEvm(chainId)) {
       return EvmAddress.from(address);
     }
     return SvmAddress.from(address);
@@ -147,11 +146,6 @@ export class Address {
     return this.toBytes32();
   }
 
-  // Converts the address to a Buffer type.
-  toBuffer(): Buffer {
-    return Buffer.from(this.rawAddress);
-  }
-
   // Implements `Hexable` for `Address`. Needed for encoding purposes. This class is treated by default as a bytes32 primitive type, but can change for subclasses.
   toHexString(): string {
     return this.toBytes32();
@@ -191,16 +185,6 @@ export class Address {
     return utils.stripZeros(this.rawAddress).length === 0;
   }
 
-  // Forces `rawAddress` to become an SvmAddress type. This will only throw if `rawAddress.length > 32`.
-  forceSvmAddress(): SvmAddress {
-    return SvmAddress.from(this.toBase58());
-  }
-
-  // Forces `rawAddress` to become an EvmAddress type. This will throw if `rawAddress.length > 20`.
-  forceEvmAddress(): EvmAddress {
-    return EvmAddress.from(this.toEvmAddress());
-  }
-
   // Checks if the other address is equivalent to this address.
   eq(other: Address): boolean {
     return this.toString() === other.toString();
@@ -239,20 +223,8 @@ export class EvmAddress extends Address {
   }
 
   // Constructs a new EvmAddress type.
-  static from(address: string, encoding: "base16" | "base58" = "base16"): EvmAddress {
-    if (encoding === "base16") {
-      return new this(utils.arrayify(address));
-    }
-
-    const decodedAddress = bs58.decode(address);
-    const padding = decodedAddress.subarray(0, 12);
-    const evmAddress = decodedAddress.subarray(12);
-
-    if (padding.length !== 12 || utils.stripZeros(padding).length !== 0 || evmAddress.length !== 20) {
-      throw new Error(`Not a valid base58-encoded EVM address: ${address}`);
-    }
-
-    return new this(evmAddress);
+  static from(hexString: string): EvmAddress {
+    return new this(utils.arrayify(hexString));
   }
 }
 
@@ -269,27 +241,12 @@ export class SvmAddress extends Address {
     return this.toBase58();
   }
 
-  // Small utility to convert an SvmAddress to a Solana Kit branded type.
-  toV2Address(): V2Address<string> {
-    return this.toBase58() as V2Address<string>;
-  }
-
-  // Forces an SvmAddress to an EVM address string by truncating the leading 12 bytes.
   override toEvmAddress(): string {
     return toAddress(`0x${this.toBytes32().slice(-40)}`);
   }
 
   // Constructs a new SvmAddress type.
-  static from(address: string, encoding: "base58" | "base16" = "base58"): SvmAddress {
-    if (encoding === "base58") {
-      return new this(bs58.decode(address));
-    }
-
-    const decodedAddress = utils.arrayify(address);
-    if (decodedAddress.length !== 32) {
-      throw new Error(`Not a valid base16-encoded SVM address: ${address}`);
-    }
-
-    return new this(decodedAddress);
+  static from(bs58Address: string): SvmAddress {
+    return new this(bs58.decode(bs58Address));
   }
 }

package/src/utils/ArrayUtils.ts

@@ -168,15 +168,3 @@ export function includesAsync<T>(
 export function isArrayOf<T>(array: unknown, predicate: (value: unknown) => value is T): array is T[] {
   return Array.isArray(array) && array.every(predicate);
 }
-
-/**
- * Checks if a value is a Uint8Array.
- * @param value The value to check.
- * @returns True if the value is a Uint8Array, false otherwise.
- */
-export function isUint8Array(value: unknown): value is Uint8Array {
-  return (
-    Array.isArray(value) &&
-    value.every((item) => typeof item === "number" && Number.isInteger(item) && item >= 0 && item < 256)
-  );
-}

package/src/utils/BlockUtils.ts

@@ -1,9 +1,219 @@
+import assert from "assert";
+import type { Block, Provider } from "@ethersproject/abstract-provider";
+import { clamp, sortedIndexBy } from "lodash";
+import { chainIsOPStack, getNetworkName } from "./NetworkUtils";
 import { isDefined } from "./TypeGuards";
 import { getCurrentTime } from "./TimeUtils";
 import { CachingMechanismInterface } from "../interfaces";
 import { shouldCache } from "./CachingUtils";
-import { BlockFinderHints, BlockFinder, Block } from "./BlockFinder";
-import { DEFAULT_CACHING_SAFE_LAG } from "../constants";
+import { CHAIN_IDs, DEFAULT_CACHING_SAFE_LAG } from "../constants";
+
+type Opts = {
+  highBlock?: number;
+  highBlockOffset?: number;
+  blockRange?: number;
+};
+
+type BlockTimeAverage = {
+  average: number;
+  blockRange: number;
+  timestamp: number;
+};
+
+// 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 type BlockFinderHints = {
+  lowBlock?: number;
+  highBlock?: number;
+};
+
+export class BlockFinder {
+  constructor(
+    private readonly provider: Provider,
+    private readonly blocks: Block[] = []
+  ) {}
+
+  /**
+   * @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<Block> {
+    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: Block, _endBlock: Block, timestamp: number): Promise<Block> {
+    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);
+    }
+  }
+}
 
 /**
  * @notice Get the block number for a given timestamp fresh from on-chain data if not found in redis cache.
@@ -14,16 +224,16 @@ import { DEFAULT_CACHING_SAFE_LAG } from "../constants";
  * or loading from cache. This is useful for testing primarily.
  * @returns Block number for the requested timestamp.
  */
-export async function getCachedBlockForTimestamp<TBlock extends Block>(
+export async function getCachedBlockForTimestamp(
   chainId: number,
   timestamp: number,
-  blockFinder: BlockFinder<TBlock>,
+  blockFinder: BlockFinder,
   cache?: CachingMechanismInterface,
   hints?: BlockFinderHints
 ): Promise<number> {
   // Resolve a convenience function to directly compute what we're
   // looking for.
-  const resolver = async () => (await blockFinder.getBlockForTimestamp(timestamp, hints || {})).number;
+  const resolver = async () => (await blockFinder.getBlockForTimestamp(timestamp, hints)).number;
 
   // If no redis client, then request block from blockFinder.
   if (!isDefined(cache)) {

package/src/utils/EventUtils.ts

@@ -99,9 +99,9 @@ export function spreadEvent(args: Result | Record<string, unknown>): { [key: str
 }
 
 export interface EventSearchConfig {
-  from: number;
-  to: number;
-  maxLookBack?: number;
+  fromBlock: number;
+  toBlock: number;
+  maxBlockLookBack?: number;
 }
 
 export const eventToLog = (event: Event): Log => ({ ...event, event: event.event!, args: spreadEvent(event.args!) });
@@ -113,8 +113,8 @@ export async function paginatedEventQuery(
   retryCount = 0
 ): Promise<Log[]> {
   // If the max block look back is set to 0 then we dont need to do any pagination and can query over the whole range.
-  if (searchConfig.maxLookBack === 0) {
-    const events = await contract.queryFilter(filter, searchConfig.from, searchConfig.to);
+  if (searchConfig.maxBlockLookBack === 0) {
+    const events = await contract.queryFilter(filter, searchConfig.fromBlock, searchConfig.toBlock);
     return events.map(eventToLog);
   }
 
@@ -132,7 +132,7 @@ export async function paginatedEventQuery(
       )
         .flat()
         // Filter events by block number because ranges can include blocks that are outside the range specified for caching reasons.
-        .filter((event) => event.blockNumber >= searchConfig.from && event.blockNumber <= searchConfig.to)
+        .filter((event) => event.blockNumber >= searchConfig.fromBlock && event.blockNumber <= searchConfig.toBlock)
         .map(eventToLog)
     );
   } catch (error) {
@@ -159,11 +159,11 @@ export async function paginatedEventQuery(
  * input range, but can include blocks outside of the desired range, so results should be filtered. Results
  * are ordered from smallest to largest.
  */
-export function getPaginatedBlockRanges({ from, to, maxLookBack }: EventSearchConfig): [number, number][] {
-  const fromBlock = from;
-  const toBlock = to;
-  const maxBlockLookBack = maxLookBack;
-
+export function getPaginatedBlockRanges({
+  fromBlock,
+  toBlock,
+  maxBlockLookBack,
+}: EventSearchConfig): [number, number][] {
   // If the maxBlockLookBack is undefined, we can look back as far as we like. Just return the entire range.
   if (maxBlockLookBack === undefined) {
     return [[fromBlock, toBlock]];

package/src/utils/JSONUtils.ts

@@ -33,8 +33,6 @@ export function stringifyJSONWithNumericString(obj: unknown): string {
   return JSON.stringify(obj, (_key, value) => {
     if (typeof value === "object" && value !== null && value.type === "BigNumber") {
       return BigNumber.from(value).toString();
-    } else if (typeof value === "bigint" && value !== null) {
-      return value.toString();
     }
     return value;
   });

package/src/utils/SpokeUtils.ts

@@ -1,11 +1,9 @@
-import { encodeAbiParameters, Hex, keccak256 } from "viem";
+import { encodeAbiParameters, keccak256 } from "viem";
 import { MAX_SAFE_DEPOSIT_ID, ZERO_ADDRESS, ZERO_BYTES } from "../constants";
 import { Deposit, RelayData } from "../interfaces";
 import { toBytes32 } from "./AddressUtils";
 import { BigNumber } from "./BigNumberUtils";
 import { isMessageEmpty } from "./DepositUtils";
-import { chainIsSvm } from "./NetworkUtils";
-import { svm } from "../arch";
 
 /**
  * Produce the RelayData for a Deposit.
@@ -65,9 +63,7 @@ export function getRelayDataHash(relayData: RelayData, destinationChainId: numbe
     outputToken: toBytes32(relayData.outputToken),
     exclusiveRelayer: toBytes32(relayData.exclusiveRelayer),
   };
-  if (chainIsSvm(destinationChainId)) {
-    return svm.getRelayDataHash(_relayData, destinationChainId);
-  }
+
   return keccak256(encodeAbiParameters(abi, [_relayData, destinationChainId]));
 }
 
@@ -91,5 +87,5 @@ export function isZeroAddress(address: string): boolean {
 }
 
 export function getMessageHash(message: string): string {
-  return isMessageEmpty(message) ? ZERO_BYTES : keccak256(message as Hex);
+  return isMessageEmpty(message) ? ZERO_BYTES : keccak256(message as "0x{string}");
 }

package/src/utils/index.ts

@@ -2,7 +2,6 @@ export * from "./common";
 export * from "./abi";
 export * from "./ArrayUtils";
 export * from "./BlockUtils";
-export * from "./BlockFinder";
 export * from "./EventUtils";
 export * from "./ObjectUtils";
 export * from "./TimeUtils";

package/dist/cjs/arch/evm/BlockUtils.d.ts

@@ -1,15 +0,0 @@
-import { Provider, Block as EthersBlock } from "@ethersproject/abstract-provider";
-import { BlockFinder, type Block, type BlockFinderOpts as Opts, type BlockTimeAverage, type BlockFinderHints } from "../../utils/BlockFinder";
-interface EVMBlock extends Block, EthersBlock {
-}
-export declare function averageBlockTime(provider: Provider, { highBlock, highBlockOffset, blockRange }?: Opts): Promise<Pick<BlockTimeAverage, "average" | "blockRange">>;
-export declare class EVMBlockFinder extends BlockFinder<EVMBlock> {
-    private readonly provider;
-    private readonly blocks;
-    constructor(provider: Provider, blocks?: EVMBlock[]);
-    getBlockForTimestamp(timestamp: number | string, hints?: BlockFinderHints): Promise<EVMBlock>;
-    private getLatestBlock;
-    private getBlock;
-    private findBlock;
-}
-export {};