Feature: Adds blockRange option to getContractEvents (#2941)

Author: gregfromstl

.changeset/dirty-lemons-clap.md

@@ -0,0 +1,39 @@
+---
+"thirdweb": patch
+---
+
+Can now optionally specify `blockRange` on `getContractEvents` in combination with `toBlock` and `fromBlock`.
+
+## Usage
+
+Specify a `blockRange`, defaulting `toBlock` to the current block number.
+
+```ts
+await getContractEvents({
+  contract: myContract,
+  blockRange: 123456n,
+  events: [preparedEvent, preparedEvent2],
+});
+```
+
+Specify a block range with `toBlock`.
+
+```ts
+await getContractEvents({
+  contract: myContract,
+  toBlock: endBlock,
+  blockRange: 123456n,
+  events: [preparedEvent, preparedEvent2],
+});
+```
+
+Specify a block range starting from `fromBlock` (great for pagination).
+
+```ts
+await getContractEvents({
+  contract: myContract,
+  fromBlock: lastBlockFetched,
+  blockRange: 123456n,
+  events: [preparedEvent, preparedEvent2],
+});
+```

packages/thirdweb/src/event/actions/get-events.test.ts

@@ -7,21 +7,74 @@ import { transferEvent } from "../../extensions/erc721/__generated__/IERC721A/ev
 import { prepareEvent } from "../prepare-event.js";
 import { getContractEvents } from "./get-events.js";
 
+const LATEST_SIMULATED_BLOCK = 19139495n;
+
 // skip this test suite if there is no secret key available to test with
 // TODO: remove reliance on secret key during unit tests entirely
 describe.runIf(process.env.TW_SECRET_KEY)("getEvents", () => {
   it("should get all events", async () => {
     const events = await getContractEvents({
       contract: USDT_CONTRACT,
-      fromBlock: 19139495n - 10n,
+      fromBlock: LATEST_SIMULATED_BLOCK - 10n,
     });
     expect(events.length).toBe(261);
   });
 
+  it("should get events for blockHash", async () => {
+    const BLOCK_HASH =
+      "0xb0ad5ee7b4912b50e5a2d7993796944653a4c0632c57740fe4a7a1c61e426324";
+    const events = await getContractEvents({
+      contract: USDT_CONTRACT,
+      blockHash: BLOCK_HASH,
+    });
+    for (const e of events) {
+      expect(e.blockHash).toBe(BLOCK_HASH);
+    }
+    expect(events.length).toBe(14);
+  });
+
+  it("should get events for blockRange", async () => {
+    const events = await getContractEvents({
+      contract: USDT_CONTRACT,
+      blockRange: 10n,
+    });
+    expect(events.length).toBe(261);
+
+    const explicitEvents = await getContractEvents({
+      contract: USDT_CONTRACT,
+      fromBlock: LATEST_SIMULATED_BLOCK - 10n,
+      toBlock: LATEST_SIMULATED_BLOCK,
+    });
+    expect(explicitEvents.length).toEqual(events.length);
+  });
+
+  it("should get events for blockRange using fromBlock and toBlock", async () => {
+    const eventsFromBlock = await getContractEvents({
+      contract: USDT_CONTRACT,
+      fromBlock: LATEST_SIMULATED_BLOCK - 50n,
+      blockRange: 20n,
+    });
+    expect(eventsFromBlock.length).toBe(426);
+
+    const eventsToBlock = await getContractEvents({
+      contract: USDT_CONTRACT,
+      toBlock: LATEST_SIMULATED_BLOCK - 30n,
+      blockRange: 20n,
+    });
+    expect(eventsToBlock.length).toBe(426);
+
+    const explicitEvents = await getContractEvents({
+      contract: USDT_CONTRACT,
+      fromBlock: LATEST_SIMULATED_BLOCK - 50n,
+      toBlock: LATEST_SIMULATED_BLOCK - 30n,
+    });
+    expect(explicitEvents.length).toEqual(eventsFromBlock.length);
+  });
+
   it("should get individual events with signature", async () => {
     const events = await getContractEvents({
       contract: USDT_CONTRACT,
-      fromBlock: 19139495n - 100n,
+      fromBlock: LATEST_SIMULATED_BLOCK - 100n,
       events: [
         prepareEvent({
           signature: "event Burn(address indexed burner, uint256 amount)",
@@ -34,7 +87,7 @@ describe.runIf(process.env.TW_SECRET_KEY)("getEvents", () => {
   it("should get specified events", async () => {
     const events = await getContractEvents({
       contract: USDT_CONTRACT,
-      fromBlock: 19139495n - 10n,
+      fromBlock: LATEST_SIMULATED_BLOCK - 10n,
       events: [
         prepareEvent({
           signature: "event Burn(address indexed burner, uint256 amount)",
@@ -74,7 +127,7 @@ describe.runIf(process.env.TW_SECRET_KEY)("getEvents", () => {
   it("should get individual events with extension", async () => {
     const events = await getContractEvents({
       contract: DOODLES_CONTRACT,
-      fromBlock: 19139495n - 1000n,
+      fromBlock: LATEST_SIMULATED_BLOCK - 1000n,
       events: [transferEvent()],
     });
     expect(events.length).toBe(38);

packages/thirdweb/src/event/actions/get-events.ts

@@ -13,6 +13,7 @@ import type {
 } from "abitype";
 import { resolveContractAbi } from "../../contract/actions/resolve-abi.js";
 import type { ThirdwebContract } from "../../contract/contract.js";
+import { eth_blockNumber } from "../../rpc/actions/eth_blockNumber.js";
 import {
   type GetLogsBlockParams,
   type GetLogsParams,
@@ -61,6 +62,37 @@ export type GetContractEventsResult<
  *  events: [preparedEvent, preparedEvent2],
  * });
  * ```
+ * @example
+ * Optionally specify a blockRange as the number of blocks to retrieve. toBlock will default to the current block number.
+ * ```ts
+ * import { getContractEvents } from "thirdweb";
+ * const events = await getContractEvents({
+ *  contract: myContract,
+ *  blockRange: 123456n,
+ *  events: [preparedEvent, preparedEvent2],
+ * });
+ * ```
+ * @example
+ * Use fromBlock with blockRange for pagination.
+ * ```ts
+ * import { getContractEvents } from "thirdweb";
+ * const events = await getContractEvents({
+ *  contract: myContract,
+ *  fromBlock: lastBlockFetched,
+ *  blockRange: 123456n,
+ *  events: [preparedEvent, preparedEvent2],
+ * });
+ * ```
+ * @example
+ * Retrieve events for a specific block hash.
+ * ```ts
+ * import { getContractEvents } from "thirdweb";
+ * const events = await getContractEvents({
+ *  contract: myContract,
+ *  blockHash: "0x...",
+ *  events: [preparedEvent, preparedEvent2],
+ * });
+ * ```
  * @contract
  */
 export async function getContractEvents<
@@ -72,7 +104,42 @@ export async function getContractEvents<
 >(
   options: GetContractEventsOptions<abi, abiEvents, TStrict>,
 ): Promise<GetContractEventsResult<abiEvents, TStrict>> {
-  const { contract, events, ...restParams } = options;
+  const { contract, events, blockRange, ...restParams } = options;
+
+  const rpcRequest = getRpcClient(contract);
+
+  if (
+    restParams.blockHash &&
+    (blockRange || restParams.fromBlock || restParams.toBlock)
+  ) {
+    throw new Error("Cannot specify blockHash and range simultaneously,");
+  }
+
+  // Compute toBlock and fromBlock if blockRange was passed
+  if (blockRange) {
+    const { fromBlock, toBlock } = restParams;
+
+    // Make sure the inputs were properly defined
+    if (
+      fromBlock &&
+      toBlock &&
+      BigInt(toBlock) - BigInt(fromBlock) !== BigInt(blockRange)
+    ) {
+      throw new Error(
+        "Incompatible blockRange with specified fromBlock and toBlock. Please only define fromBlock or toBlock when specifying blockRange.",
+      );
+    }
+
+    if (fromBlock) {
+      restParams.toBlock = BigInt(fromBlock) + BigInt(blockRange);
+    } else if (toBlock) {
+      restParams.fromBlock = BigInt(toBlock) - BigInt(blockRange);
+    } else {
+      // If no from or to block specified, use the latest block as the to block
+      restParams.toBlock = await eth_blockNumber(rpcRequest);
+      restParams.fromBlock = BigInt(restParams.toBlock) - BigInt(blockRange);
+    }
+  }
 
   let resolvedEvents = events ?? [];
 
@@ -104,7 +171,6 @@ export async function getContractEvents<
       : // otherwise we want "all" events (aka not pass any topics at all)
         [{ ...restParams, address: contract?.address }];
 
-  const rpcRequest = getRpcClient(contract);
   const logs = await Promise.all(
     logsParams.map((ethLogParams) => eth_getLogs(rpcRequest, ethLogParams)),
   );

packages/thirdweb/src/rpc/actions/eth_getLogs.ts

@@ -16,11 +16,31 @@ export type GetLogsBlockParams =
       fromBlock?: BlockNumber | BlockTag;
       toBlock?: BlockNumber | BlockTag;
       blockHash?: never;
+      blockRange?: never;
     }
   | {
       fromBlock?: never;
       toBlock?: never;
       blockHash?: Hash;
+      blockRange?: never;
+    }
+  | {
+      fromBlock?: BlockNumber | "latest";
+      toBlock?: never;
+      blockRange: BlockNumber;
+      blockHash?: never;
+    }
+  | {
+      fromBlock?: never;
+      toBlock?: BlockNumber | "latest";
+      blockRange: BlockNumber;
+      blockHash?: never;
+    }
+  | {
+      fromBlock?: never;
+      toBlock?: never;
+      blockRange: BlockNumber;
+      blockHash?: never;
     };
 
 export type GetLogsParams = {