@across-protocol/sdk 3.0.0

package/src/clients/index.ts

@@ -0,0 +1,9 @@
+export {
+  DEFAULT_CONFIG_STORE_VERSION,
+  GLOBAL_CONFIG_STORE_KEYS,
+  AcrossConfigStoreClient,
+  ConfigStoreUpdate,
+} from "./AcrossConfigStoreClient";
+export { HubPoolClient, LpFeeRequest } from "./HubPoolClient";
+export { SpokePoolClient, SpokePoolUpdate } from "./SpokePoolClient";
+export * as mocks from "./mocks";

package/src/clients/mocks/MockConfigStoreClient.ts

@@ -0,0 +1,129 @@
+import assert from "assert";
+import winston from "winston";
+import { Contract, Event, ethers } from "ethers";
+import { EventSearchConfig, MakeOptional, isDefined, utf8ToHex } from "../../utils";
+import {
+  AcrossConfigStoreClient,
+  ConfigStoreUpdate,
+  DEFAULT_CONFIG_STORE_VERSION,
+  GLOBAL_CONFIG_STORE_KEYS,
+} from "../AcrossConfigStoreClient";
+import { EventManager, EventOverrides, getEventManager } from "./MockEvents";
+
+export class MockConfigStoreClient extends AcrossConfigStoreClient {
+  public configStoreVersion = DEFAULT_CONFIG_STORE_VERSION;
+  private eventManager: EventManager | null;
+  private availableChainIdsOverride: number[] | undefined;
+
+  // Event signatures. Not strictly required, but they make generated events more recognisable.
+  public readonly eventSignatures: Record<string, string> = {
+    OwnershipTransferred: "address,address",
+    UpdatedGlobalConfig: "bytes32,string",
+    UpdatedTokenConfig: "address,string",
+  };
+
+  constructor(
+    logger: winston.Logger,
+    configStore: Contract,
+    eventSearchConfig: MakeOptional<EventSearchConfig, "toBlock"> = { fromBlock: 0, maxBlockLookBack: 0 },
+    configStoreVersion: number,
+    chainId = 1,
+    mockUpdate = false,
+    availableChainIdsOverride?: number[]
+  ) {
+    super(logger, configStore, eventSearchConfig, configStoreVersion);
+    this.chainId = chainId;
+    this.eventManager = mockUpdate ? getEventManager(chainId, this.eventSignatures) : null;
+    if (isDefined(this.eventManager) && this.eventManager) {
+      this.updateGlobalConfig(GLOBAL_CONFIG_STORE_KEYS.CHAIN_ID_INDICES, JSON.stringify(availableChainIdsOverride), {
+        blockNumber: this.eventManager.blockNumber,
+      });
+    }
+  }
+
+  setAvailableChains(chainIds: number[]): void {
+    this.availableChainIdsOverride = chainIds;
+  }
+
+  getChainIdIndicesForBlock(block?: number): number[] {
+    return this.availableChainIdsOverride ?? super.getChainIdIndicesForBlock(block);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  getConfigStoreVersionForBlock(_blockNumber: number): number {
+    return this.configStoreVersion === DEFAULT_CONFIG_STORE_VERSION
+      ? super.getConfigStoreVersionForBlock(_blockNumber)
+      : this.configStoreVersion;
+  }
+
+  setConfigStoreVersion(version: number): void {
+    this.configStoreVersion = version;
+  }
+
+  async _update(): Promise<ConfigStoreUpdate> {
+    // Backwards compatibility for pre-existing MockConfigStoreClient users.
+    if (this.eventManager === null) {
+      return super._update();
+    }
+
+    const eventNames = ["UpdatedGlobalConfig", "UpdatedTokenConfig"];
+    const latestBlockSearched = this.eventManager.blockNumber;
+
+    // Ensure an array for every requested event exists, in the requested order.
+    // All requested event types must be populated in the array (even if empty).
+    const globalConfigUpdateTimes: number[] = [];
+    const _events: Event[][] = eventNames.map(() => []);
+    for (const event of this.eventManager.getEvents().flat()) {
+      const idx = eventNames.indexOf(event.event as string);
+      if (idx !== -1) {
+        _events[idx].push(event);
+      }
+
+      if (event.event === "UpdatedGlobalConfig") {
+        const block = await event.getBlock();
+        globalConfigUpdateTimes.push(block.timestamp);
+      }
+    }
+
+    // Transform 2d-events array into a record.
+    const events = Object.fromEntries(eventNames.map((eventName, idx) => [eventName, _events[idx]]));
+
+    return {
+      success: true,
+      chainId: this.chainId as number,
+      searchEndBlock: this.eventSearchConfig.toBlock || latestBlockSearched,
+      events: {
+        updatedGlobalConfigEvents: events["UpdatedGlobalConfig"],
+        globalConfigUpdateTimes,
+        updatedTokenConfigEvents: events["UpdatedTokenConfig"],
+      },
+    };
+  }
+
+  updateGlobalConfig(key: string, value: string, overrides: EventOverrides = {}): Event {
+    return this.generateConfig("UpdatedGlobalConfig", utf8ToHex(key), value, overrides);
+  }
+
+  updateTokenConfig(key: string, value: string, overrides: EventOverrides = {}): Event {
+    // Verify that the key is a valid address
+    if (ethers.utils.isAddress(key) === false) {
+      throw new Error(`Invalid address: ${key}`);
+    }
+    return this.generateConfig("UpdatedTokenConfig", key, value, overrides);
+  }
+
+  private generateConfig(event: string, key: string, value: string, overrides: EventOverrides = {}): Event {
+    assert(this.eventManager !== null);
+
+    const topics = [key, value];
+    const args = { key, value };
+
+    return this.eventManager.generateEvent({
+      event,
+      address: this.configStore.address,
+      topics: topics.map((topic) => topic.toString()),
+      args,
+      blockNumber: overrides.blockNumber,
+    });
+  }
+}

package/src/clients/mocks/MockEvents.ts

@@ -0,0 +1,156 @@
+import assert from "assert";
+import { utils as ethersUtils, Event, providers } from "ethers";
+import { random } from "lodash";
+import { isDefined, randomAddress, toBN } from "../../utils";
+
+const { id, keccak256, toUtf8Bytes } = ethersUtils;
+export type EventOverrides = {
+  blockNumber?: number;
+};
+
+type Block = providers.Block;
+type TransactionResponse = providers.TransactionResponse;
+type TransactionReceipt = providers.TransactionReceipt;
+
+type EthersEventTemplate = {
+  address: string;
+  event: string;
+  topics: string[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  args: Record<string, any>;
+  data?: string;
+  blockNumber?: number;
+  transactionIndex?: number;
+};
+
+const eventManagers: { [chainId: number]: EventManager } = {};
+
+// May need to populate getTransaction and getTransactionReceipt if calling code starts using it.
+// https://docs.ethers.org/v5/api/providers/provider/#Provider-getTransaction
+const getTransaction = (): Promise<TransactionResponse> => {
+  throw new Error("getTransaction() not supported");
+};
+// https://docs.ethers.org/v5/api/providers/provider/#Provider-getTransactionReceipt
+const getTransactionReceipt = (): Promise<TransactionReceipt> => {
+  throw new Error("getTransactionReceipt() not supported");
+};
+const removeListener = (): void => {
+  throw new Error("removeListener not supported");
+};
+
+export class EventManager {
+  private logIndexes: Record<string, number> = {};
+  public events: Event[] = [];
+  public readonly minBlockRange = 10;
+  public readonly eventSignatures: Record<string, string> = {};
+
+  constructor(public blockNumber = 0) {}
+
+  addEventSignatures(eventSignatures: Record<string, string>): void {
+    Object.entries(eventSignatures).forEach(([event, signature]) => {
+      if (isDefined(this.eventSignatures[event])) {
+        assert(signature === this.eventSignatures[event], `Event ${event} conflict detected.`);
+      }
+      this.eventSignatures[event] = signature;
+    });
+  }
+
+  addEvent(event: Event): void {
+    this.events.push(event);
+  }
+
+  getEvents(): Event[] {
+    const events = this.events;
+    this.events = [];
+    return events;
+  }
+
+  generateEvent(inputs: EthersEventTemplate): Event {
+    const { address, event, topics: _topics, data, args } = inputs;
+    const eventSignature = `${event}(${this.eventSignatures[event]})`;
+    const topics = [keccak256(toUtf8Bytes(eventSignature))].concat(_topics);
+
+    let { blockNumber, transactionIndex } = inputs;
+
+    // Increment the block number by at least 1, by default. The caller may override
+    // to force the same block number to be used, but never a previous block number.
+    blockNumber ??= random(this.blockNumber + 1, this.blockNumber + this.minBlockRange, false);
+    assert(blockNumber >= this.blockNumber, `${blockNumber} < ${this.blockNumber}`);
+    this.blockNumber = blockNumber;
+
+    transactionIndex ??= random(1, 32, false);
+    const transactionHash = id(`Across-${event}-${blockNumber}-${transactionIndex}-${random(1, 100_000)}`);
+
+    const _logIndex = `${blockNumber}-${transactionIndex}`;
+    this.logIndexes[_logIndex] ??= 0;
+    const logIndex = this.logIndexes[_logIndex]++;
+
+    const decodeError = new Error(`${event} decoding error`);
+    const parentHash = id(`Across-blockHash-${random(1, 100_000)}`);
+    const blockHash = id(`Across-blockHash-${parentHash}-${random(1, 100_000)}`);
+
+    // getBlock() may later be used to retrieve (for example) the block timestamp.
+    // @todo: If multiple events coincide on the same block number, this callback should return the same Block object.
+    const getBlock = (): Promise<Block> => {
+      return Promise.resolve({
+        hash: blockHash,
+        parentHash,
+        number: blockNumber as number,
+        timestamp: Math.floor(Date.now() / 1000),
+        nonce: "",
+        difficulty: random(1, 1000, false),
+        _difficulty: toBN(random(1, 1000, false)),
+        gasLimit: toBN(random(1_000_000, 10_000_000, false)),
+        gasUsed: toBN(random(1, 1000, false)),
+        miner: randomAddress(),
+        extraData: `Block containing test transaction ${transactionHash}.`,
+        transactions: [transactionHash],
+      });
+    };
+
+    const generatedEvent = {
+      blockNumber,
+      transactionIndex,
+      logIndex,
+      transactionHash,
+      removed: false,
+      address,
+      data: data ?? id(`Across-random-txndata-${random(1, 100_000)}`),
+      topics,
+      args,
+      blockHash,
+      event,
+      eventSignature,
+      decodeError,
+      getBlock,
+      getTransaction,
+      getTransactionReceipt,
+      removeListener,
+    } as Event;
+
+    this.addEvent(generatedEvent);
+    return generatedEvent;
+  }
+}
+
+/**
+ * @description Retrieve an instance of the EventManager for a specific chain, or instantiate a new one.
+ * @param chainId Chain ID to retrieve EventManager for.
+ * @param eventSignatures Event Signatures to append to EventManager instance.
+ * @param Initial blockNumber to use if a new EventManager is instantiated.
+ * @returns EventManager instance for chain ID.
+ */
+export function getEventManager(
+  chainId: number,
+  eventSignatures?: Record<string, string>,
+  blockNumber?: number
+): EventManager {
+  if (!isDefined(eventManagers[chainId])) {
+    eventManagers[chainId] = new EventManager(blockNumber);
+  }
+  const eventManager = eventManagers[chainId];
+  if (isDefined(eventSignatures)) {
+    eventManager.addEventSignatures(eventSignatures);
+  }
+  return eventManager;
+}

package/src/clients/mocks/MockHubPoolClient.ts

@@ -0,0 +1,257 @@
+import winston from "winston";
+import { BigNumber, Contract, Event } from "ethers";
+import { randomAddress, assign, bnZero } from "../../utils";
+import { L1Token, PendingRootBundle, RealizedLpFee } from "../../interfaces";
+import { AcrossConfigStoreClient as ConfigStoreClient } from "../AcrossConfigStoreClient";
+import { HubPoolClient, HubPoolUpdate, LpFeeRequest } from "../HubPoolClient";
+import { EventManager, EventOverrides, getEventManager } from "./MockEvents";
+
+const emptyRootBundle: PendingRootBundle = {
+  poolRebalanceRoot: "",
+  relayerRefundRoot: "",
+  slowRelayRoot: "",
+  proposer: "",
+  unclaimedPoolRebalanceLeafCount: 0,
+  challengePeriodEndTimestamp: 0,
+  bundleEvaluationBlockNumbers: [],
+  proposalBlockNumber: undefined,
+};
+
+export class MockHubPoolClient extends HubPoolClient {
+  public rootBundleProposal = emptyRootBundle;
+  private realizedLpFeePct: BigNumber = bnZero;
+  private realizedLpFeePctOverride = false;
+
+  private l1TokensMock: L1Token[] = []; // L1Tokens and their associated info.
+  private tokenInfoToReturn: L1Token = { address: "", decimals: 0, symbol: "" };
+
+  private spokePoolTokens: { [l1Token: string]: { [chainId: number]: string } } = {};
+
+  private eventManager: EventManager;
+
+  constructor(
+    logger: winston.Logger,
+    hubPool: Contract,
+    configStoreClient: ConfigStoreClient,
+    deploymentBlock = 0,
+    chainId = 1
+  ) {
+    super(logger, hubPool, configStoreClient, deploymentBlock, chainId);
+    this.eventManager = getEventManager(chainId, this.eventSignatures, deploymentBlock);
+  }
+
+  setDefaultRealizedLpFeePct(fee: BigNumber): void {
+    this.realizedLpFeePct = fee;
+    this.realizedLpFeePctOverride = true;
+  }
+
+  clearDefaultRealizedLpFeePct(): void {
+    this.realizedLpFeePctOverride = false;
+  }
+
+  async computeRealizedLpFeePct(deposit: LpFeeRequest): Promise<RealizedLpFee> {
+    const { realizedLpFeePct, realizedLpFeePctOverride } = this;
+    return realizedLpFeePctOverride
+      ? { realizedLpFeePct, quoteBlock: 0 }
+      : await super.computeRealizedLpFeePct(deposit);
+  }
+  async batchComputeRealizedLpFeePct(_deposits: LpFeeRequest[]): Promise<RealizedLpFee[]> {
+    const { realizedLpFeePct, realizedLpFeePctOverride } = this;
+    return realizedLpFeePctOverride
+      ? _deposits.map(() => {
+          return { realizedLpFeePct, quoteBlock: 0 };
+        })
+      : await super.batchComputeRealizedLpFeePct(_deposits);
+  }
+
+  setCrossChainContracts(chainId: number, contract: string, blockNumber = 0): void {
+    assign(
+      this.crossChainContracts,
+      [chainId],
+      [
+        {
+          spokePool: contract,
+          blockNumber: blockNumber,
+          transactionIndex: 0,
+          logIndex: 0,
+        },
+      ]
+    );
+  }
+
+  setLatestBlockNumber(blockNumber: number) {
+    this.latestBlockSearched = blockNumber;
+  }
+
+  addL1Token(l1Token: L1Token) {
+    this.l1TokensMock.push(l1Token);
+  }
+
+  getL1Tokens() {
+    return this.l1TokensMock;
+  }
+
+  getTokenInfoForDeposit() {
+    return this.tokenInfoToReturn;
+  }
+
+  setTokenMapping(l1Token: string, chainId: number, l2Token: string) {
+    this.spokePoolTokens[l1Token] ??= {};
+    this.spokePoolTokens[l1Token][chainId] = l2Token;
+  }
+
+  getL1TokenForL2TokenAtBlock(l2Token: string, chainId: number, blockNumber: number): string {
+    const l1Token = Object.keys(this.spokePoolTokens).find(
+      (l1Token) => this.spokePoolTokens[l1Token]?.[chainId] === l2Token
+    );
+    return l1Token ?? super.getL1TokenForL2TokenAtBlock(l2Token, chainId, blockNumber);
+  }
+
+  getL2TokenForL1TokenAtBlock(l1Token: string, chainId: number, blockNumber: number): string {
+    const l2Token = this.spokePoolTokens[l1Token]?.[chainId];
+    return l2Token ?? super.getL2TokenForL1TokenAtBlock(l1Token, chainId, blockNumber);
+  }
+
+  getTokenInfoForL1Token(l1Token: string): L1Token | undefined {
+    return this.l1TokensMock.find((token) => token.address === l1Token);
+  }
+
+  setTokenInfoToReturn(tokenInfo: L1Token) {
+    this.tokenInfoToReturn = tokenInfo;
+  }
+
+  _update(eventNames: string[]): Promise<HubPoolUpdate> {
+    // Generate new "on chain" responses.
+    const latestBlockSearched = this.eventManager.blockNumber;
+    const currentTime = Math.floor(Date.now() / 1000);
+
+    // Ensure an array for every requested event exists, in the requested order.
+    // All requested event types must be populated in the array (even if empty).
+    const _events: Event[][] = eventNames.map(() => []);
+    this.eventManager
+      .getEvents()
+      .flat()
+      .forEach((event) => {
+        const idx = eventNames.indexOf(event.event as string);
+        if (idx !== -1) {
+          _events[idx].push(event);
+        }
+      });
+
+    // Transform 2d-events array into a record.
+    const events = Object.fromEntries(eventNames.map((eventName, idx) => [eventName, _events[idx]]));
+
+    return Promise.resolve({
+      success: true,
+      currentTime,
+      latestBlockSearched,
+      pendingRootBundleProposal: this.rootBundleProposal,
+      events,
+      searchEndBlock: this.eventSearchConfig.toBlock || latestBlockSearched,
+    });
+  }
+
+  public readonly eventSignatures: Record<string, string> = {
+    SetEnableDepositRoute: "uint256,uint256,address,bool",
+    SetPoolRebalanceRoute: "uint256,address,address",
+    ProposeRootBundle: "uint32,uint8,uint256[],bytes32,bytes32,bytes32,address",
+    RootBundleExecuted: "uint256,uint256,uint256,address[],uint256[],int256[],int256[],address",
+  };
+
+  setPoolRebalanceRoute(
+    destinationChainId: number,
+    l1Token: string,
+    destinationToken: string,
+    overrides: EventOverrides = {}
+  ): Event {
+    const event = "SetPoolRebalanceRoute";
+
+    const topics = [destinationChainId, l1Token, destinationToken];
+    const args = {
+      destinationChainId,
+      l1Token,
+      destinationToken,
+    };
+
+    return this.eventManager.generateEvent({
+      event,
+      address: this.hubPool.address,
+      topics: topics.map((topic) => topic.toString()),
+      args,
+      blockNumber: overrides.blockNumber,
+    });
+  }
+
+  proposeRootBundle(
+    challengePeriodEndTimestamp: number,
+    poolRebalanceLeafCount: number,
+    bundleEvaluationBlockNumbers: BigNumber[],
+    poolRebalanceRoot?: string,
+    relayerRefundRoot?: string,
+    slowRelayRoot?: string,
+    proposer?: string,
+    overrides: EventOverrides = {}
+  ): Event {
+    const event = "ProposeRootBundle";
+
+    poolRebalanceRoot ??= "XX";
+    relayerRefundRoot ??= "XX";
+    slowRelayRoot ??= "XX";
+    proposer ??= randomAddress();
+
+    const topics = [poolRebalanceRoot, relayerRefundRoot, proposer];
+    const args = {
+      challengePeriodEndTimestamp,
+      poolRebalanceLeafCount,
+      bundleEvaluationBlockNumbers,
+      poolRebalanceRoot,
+      relayerRefundRoot,
+      slowRelayRoot,
+      proposer,
+    };
+
+    return this.eventManager.generateEvent({
+      event,
+      address: this.hubPool.address,
+      topics: topics.map((topic) => topic.toString()),
+      args,
+      blockNumber: overrides.blockNumber,
+    });
+  }
+
+  executeRootBundle(
+    groupIndex: BigNumber,
+    leafId: number,
+    chainId: BigNumber,
+    l1Tokens: string[],
+    bundleLpFees: BigNumber[],
+    netSendAmounts: BigNumber[],
+    runningBalances: BigNumber[],
+    caller?: string,
+    overrides: EventOverrides = {}
+  ): Event {
+    const event = "RootBundleExecuted";
+
+    caller ??= randomAddress();
+
+    const topics = [leafId, chainId, caller];
+    const args = {
+      groupIndex,
+      leafId,
+      chainId,
+      l1Tokens,
+      bundleLpFees,
+      netSendAmounts,
+      runningBalances,
+      caller,
+    };
+
+    return this.eventManager.generateEvent({
+      event,
+      address: this.hubPool.address,
+      topics: topics.map((topic) => topic.toString()),
+      args,
+      blockNumber: overrides.blockNumber,
+    });
+  }
+}