[Engine] Add search transactions and batch transaction support

Author: joaquim-verges

.changeset/engine-enhancements.md

@@ -0,0 +1,74 @@
+---
+"thirdweb": minor
+---
+
+Enhanced Engine functionality with search transactions and batch transaction support:
+
+- Added `Engine.searchTransactions()` to search for transactions by various filters (id, chainId, from address, etc.)
+
+  ```ts
+  // Search by transaction IDs
+  const transactions = await Engine.searchTransactions({
+    client,
+    filters: [
+      {
+        field: "id",
+        values: ["1", "2", "3"],
+        operation: "OR",
+      },
+    ],
+  });
+
+  // Search by chain ID and sender address
+  const transactions = await Engine.searchTransactions({
+    client,
+    filters: [
+      {
+        filters: [
+          {
+            field: "from",
+            values: ["0x1234567890123456789012345678901234567890"],
+            operation: "OR",
+          },
+          {
+            field: "chainId",
+            values: ["8453"],
+            operation: "OR",
+          },
+        ],
+        operation: "AND",
+      },
+    ],
+    pageSize: 100,
+    page: 0,
+  });
+  ```
+
+- Added `serverWallet.enqueueBatchTransaction()` to enqueue multiple transactions in a single batch
+
+  ```ts
+  // Prepare multiple transactions
+  const transaction1 = claimTo({
+    contract,
+    to: firstRecipient,
+    quantity: 1n,
+  });
+  const transaction2 = claimTo({
+    contract,
+    to: secondRecipient,
+    quantity: 1n,
+  });
+
+  // Enqueue as a batch
+  const { transactionId } = await serverWallet.enqueueBatchTransaction({
+    transactions: [transaction1, transaction2],
+  });
+
+  // Wait for batch completion
+  const { transactionHash } = await Engine.waitForTransactionHash({
+    client,
+    transactionId,
+  });
+  ```
+
+- Improved server wallet transaction handling with better error reporting

packages/thirdweb/src/engine/get-status.ts

@@ -2,7 +2,6 @@ import { searchTransactions } from "@thirdweb-dev/engine";
 import type { Chain } from "../chains/types.js";
 import { getCachedChain } from "../chains/utils.js";
 import type { ThirdwebClient } from "../client/client.js";
-import type { WaitForReceiptOptions } from "../transaction/actions/wait-for-tx-receipt.js";
 import { getThirdwebBaseUrl } from "../utils/domains.js";
 import type { Hex } from "../utils/encoding/hex.js";
 import { getClientFetch } from "../utils/fetch.js";
@@ -117,71 +116,3 @@ export async function getTransactionStatus(args: {
     id: data.id,
   };
 }
-
-/**
- * Wait for a transaction to be submitted onchain and return the transaction hash.
- * @param args - The arguments for the transaction.
- * @param args.client - The thirdweb client to use.
- * @param args.transactionId - The id of the transaction to wait for.
- * @param args.timeoutInSeconds - The timeout in seconds.
- * @engine
- * @example
- * ```ts
- * import { Engine } from "thirdweb";
- *
- * const { transactionHash } = await Engine.waitForTransactionHash({
- *   client,
- *   transactionId, // the transaction id returned from enqueueTransaction
- * });
- * ```
- */
-export async function waitForTransactionHash(args: {
-  client: ThirdwebClient;
-  transactionId: string;
-  timeoutInSeconds?: number;
-}): Promise<WaitForReceiptOptions> {
-  const startTime = Date.now();
-  const TIMEOUT_IN_MS = args.timeoutInSeconds
-    ? args.timeoutInSeconds * 1000
-    : 5 * 60 * 1000; // 5 minutes in milliseconds
-
-  while (Date.now() - startTime < TIMEOUT_IN_MS) {
-    const executionResult = await getTransactionStatus(args);
-    const status = executionResult.status;
-
-    switch (status) {
-      case "FAILED": {
-        throw new Error(
-          `Transaction failed: ${executionResult.error || "Unknown error"}`,
-        );
-      }
-      case "CONFIRMED": {
-        const onchainStatus =
-          executionResult && "onchainStatus" in executionResult
-            ? executionResult.onchainStatus
-            : null;
-        if (onchainStatus === "REVERTED") {
-          const revertData =
-            "revertData" in executionResult
-              ? executionResult.revertData
-              : undefined;
-          throw new Error(
-            `Transaction reverted: ${revertData?.errorName || ""} ${revertData?.errorArgs ? stringify(revertData.errorArgs) : ""}`,
-          );
-        }
-        return {
-          transactionHash: executionResult.transactionHash as Hex,
-          client: args.client,
-          chain: executionResult.chain,
-        };
-      }
-      default: {
-        // wait for the transaction to be confirmed
-        await new Promise((resolve) => setTimeout(resolve, 1000));
-      }
-    }
-  }
-  throw new Error(
-    `Transaction timed out after ${TIMEOUT_IN_MS / 1000} seconds`,
-  );
-}

packages/thirdweb/src/engine/index.ts

@@ -5,7 +5,11 @@ export {
 } from "./server-wallet.js";
 export {
   getTransactionStatus,
-  waitForTransactionHash,
   type ExecutionResult,
   type RevertData,
 } from "./get-status.js";
+export { waitForTransactionHash } from "./wait-for-tx-hash.js";
+export {
+  searchTransactions,
+  type SearchTransactionsArgs,
+} from "./search-transactions.js";

packages/thirdweb/src/engine/search-transactions.ts

@@ -0,0 +1,137 @@
+import {
+  type TransactionsFilterNested,
+  type TransactionsFilterValue,
+  searchTransactions as engineSearchTransactions,
+} from "@thirdweb-dev/engine";
+import type { ThirdwebClient } from "../client/client.js";
+import { getThirdwebBaseUrl } from "../utils/domains.js";
+import { getClientFetch } from "../utils/fetch.js";
+import { stringify } from "../utils/json.js";
+
+export type SearchTransactionsArgs = {
+  client: ThirdwebClient;
+  filters?: (TransactionsFilterValue | TransactionsFilterNested)[];
+  pageSize?: number;
+  page?: number;
+};
+
+/**
+ * Search for transactions by their ids.
+ * @param args - The arguments for the search.
+ * @param args.client - The thirdweb client to use.
+ * @param args.transactionIds - The ids of the transactions to search for.
+ * @engine
+ * @example
+ * ## Search for transactions by their ids
+ *
+ * ```ts
+ * import { Engine } from "thirdweb";
+ *
+ * const transactions = await Engine.searchTransactions({
+ *   client,
+ *   filters: [
+ *     {
+ *       field: "id",
+ *       values: ["1", "2", "3"],
+ *       operation: "OR",
+ *     },
+ *   ],
+ * });
+ * console.log(transactions);
+ * ```
+ *
+ * ## Search for transactions by chain id
+ *
+ * ```ts
+ * import { Engine } from "thirdweb";
+ *
+ * const transactions = await Engine.searchTransactions({
+ *   client,
+ *   filters: [
+ *     {
+ *       field: "chainId",
+ *       values: ["1", "137"],
+ *       operation: "OR",
+ *     },
+ *   ],
+ * });
+ * console.log(transactions);
+ * ```
+ *
+ * ## Search for transactions by sender wallet address
+ *
+ * ```ts
+ * import { Engine } from "thirdweb";
+ *
+ * const transactions = await Engine.searchTransactions({
+ *   client,
+ *   filters: [
+ *     {
+ *       field: "from",
+ *       values: ["0x1234567890123456789012345678901234567890"],
+ *       operation: "OR",
+ *     },
+ *   ],
+ * });
+ * console.log(transactions);
+ * ```
+ *
+ * ## Combined search
+ *
+ * ```ts
+ * import { Engine } from "thirdweb";
+ *
+ * const transactions = await Engine.searchTransactions({
+ *   client,
+ *   filters: [
+ *     {
+ *       filters: [
+ *         {
+ *          field: "from",
+ *          values: ["0x1234567890123456789012345678901234567890"],
+ *          operation: "OR",
+ *        },
+ *        {
+ *          field: "chainId",
+ *          values: ["8453"],
+ *          operation: "OR",
+ *        },
+ *      ],
+ *      operation: "AND",
+ *    },
+ *  ],
+ *  pageSize: 100,
+ *  page: 0,
+ * });
+ * console.log(transactions);
+ * ```
+ */
+export async function searchTransactions(args: SearchTransactionsArgs) {
+  const { client, filters, pageSize = 100, page = 1 } = args;
+  const searchResult = await engineSearchTransactions({
+    baseUrl: getThirdwebBaseUrl("engineCloud"),
+    bodySerializer: stringify,
+    fetch: getClientFetch(client),
+    body: {
+      filters,
+      limit: pageSize,
+      page,
+    },
+  });
+
+  if (searchResult.error) {
+    throw new Error(
+      `Error searching for transaction with filters ${stringify(filters)}: ${stringify(
+        searchResult.error,
+      )}`,
+    );
+  }
+
+  const data = searchResult.data?.result;
+
+  if (!data) {
+    throw new Error(`No transactions found with filters ${stringify(filters)}`);
+  }
+
+  return data;
+}

packages/thirdweb/src/engine/server-wallet.test.ts

@@ -95,6 +95,16 @@ describe.runIf(
         transactionId: result.transactionId,
       });
       expect(txHash.transactionHash).toBeDefined();
+
+      const res = await Engine.searchTransactions({
+        client: TEST_CLIENT,
+        filters: [
+          { field: "id", values: [result.transactionId], operation: "OR" },
+        ],
+      });
+      expect(res).toBeDefined();
+      expect(res.transactions.length).toBe(1);
+      expect(res.transactions[0]?.id).toBe(result.transactionId);
     });
 
     it("should send a extension tx", async () => {
@@ -115,6 +125,33 @@ describe.runIf(
       expect(tx).toBeDefined();
     });
 
+    it("should enqueue a batch of txs", async () => {
+      const tokenContract = getContract({
+        client: TEST_CLIENT,
+        chain: baseSepolia,
+        address: "0x87C52295891f208459F334975a3beE198fE75244",
+      });
+      const claimTx1 = mintTo({
+        contract: tokenContract,
+        to: serverWallet.address,
+        amount: "0.001",
+      });
+      const claimTx2 = mintTo({
+        contract: tokenContract,
+        to: serverWallet.address,
+        amount: "0.002",
+      });
+      const tx = await serverWallet.enqueueBatchTransaction({
+        transactions: [claimTx1, claimTx2],
+      });
+      expect(tx.transactionId).toBeDefined();
+      const txHash = await Engine.waitForTransactionHash({
+        client: TEST_CLIENT,
+        transactionId: tx.transactionId,
+      });
+      expect(txHash.transactionHash).toBeDefined();
+    });
+
     it("should get revert reason", async () => {
       const nftContract = getContract({
         client: TEST_CLIENT,