[Engine] Add search transactions and batch transaction support

Author: joaquim-verges

.changeset/engine-enhancements.md

@@ -0,0 +1,71 @@
+---
+"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"],
+      },
+    ],
+  });
+
+  // Search by chain ID and sender address
+  const transactions = await Engine.searchTransactions({
+    client,
+    filters: [
+      {
+        filters: [
+          {
+            field: "from",
+            values: ["0x1234567890123456789012345678901234567890"],
+          },
+          {
+            field: "chainId",
+            values: ["8453"],
+          },
+        ],
+        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

.changeset/stupid-adults-flow.md

@@ -0,0 +1,5 @@
+---
+"@thirdweb-dev/engine": patch
+---
+
+Updated to latest API

packages/engine/src/client/sdk.gen.ts

@@ -7,6 +7,8 @@ import type {
 } from "@hey-api/client-fetch";
 import { client as _heyApiClient } from "./client.gen.js";
 import type {
+  CreateAccountData,
+  CreateAccountResponse,
   EncodeFunctionDataData,
   EncodeFunctionDataResponse,
   GetNativeBalanceData,
@@ -15,6 +17,8 @@ import type {
   GetTransactionAnalyticsResponse,
   GetTransactionAnalyticsSummaryData,
   GetTransactionAnalyticsSummaryResponse,
+  ListAccountsData,
+  ListAccountsResponse,
   ReadContractData,
   ReadContractResponse,
   SearchTransactionsData,
@@ -48,6 +52,56 @@ export type Options<
   meta?: Record<string, unknown>;
 };
 
+/**
+ * List Server Wallets
+ * List all engine server wallets for the current project. Returns an array of EOA addresses with their corresponding predicted smart account addresses.
+ */
+export const listAccounts = <ThrowOnError extends boolean = false>(
+  options?: Options<ListAccountsData, ThrowOnError>,
+) => {
+  return (options?.client ?? _heyApiClient).get<
+    ListAccountsResponse,
+    unknown,
+    ThrowOnError
+  >({
+    security: [
+      {
+        name: "x-secret-key",
+        type: "apiKey",
+      },
+    ],
+    url: "/v1/accounts",
+    ...options,
+  });
+};
+
+/**
+ * Create Server Wallet
+ * Create a new engine server wallet. This is a helper route for creating a new EOA with your KMS provider, provided as a convenient alternative to creating an EOA directly with your KMS provider. Your KMS credentials are not stored, and usage of created accounts require your KMS credentials to be sent with requests.
+ */
+export const createAccount = <ThrowOnError extends boolean = false>(
+  options?: Options<CreateAccountData, ThrowOnError>,
+) => {
+  return (options?.client ?? _heyApiClient).post<
+    CreateAccountResponse,
+    unknown,
+    ThrowOnError
+  >({
+    security: [
+      {
+        name: "x-secret-key",
+        type: "apiKey",
+      },
+    ],
+    url: "/v1/accounts",
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers,
+    },
+  });
+};
+
 /**
  * Write Contract
  * Call a write function on a contract.

packages/engine/src/client/types.gen.ts

@@ -9,7 +9,7 @@ export type TransactionsFilterValue = {
     | "smartAccountAddress"
     | "chainId";
   values: Array<string>;
-  operation: "AND" | "OR";
+  operation?: "AND" | "OR";
 };
 
 export type TransactionsFilterNested = {
@@ -92,6 +92,70 @@ export type AaZksyncExecutionOptions = {
   chainId: string;
 };
 
+export type ListAccountsData = {
+  body?: never;
+  path?: never;
+  query?: never;
+  url: "/v1/accounts";
+};
+
+export type ListAccountsResponses = {
+  /**
+   * Accounts retrieved successfully
+   */
+  200: {
+    result: Array<{
+      /**
+       * EVM address in hex format
+       */
+      address: string;
+      /**
+       * The predicted smart account address for use with the default thirdweb v0.7 AccountFactory
+       */
+      smartAccountAddress?: string;
+    }>;
+  };
+};
+
+export type ListAccountsResponse =
+  ListAccountsResponses[keyof ListAccountsResponses];
+
+export type CreateAccountData = {
+  body?: {
+    label: string;
+  };
+  headers?: {
+    /**
+     * Vault Access Token used to access your EOA
+     */
+    "x-vault-access-token"?: string;
+  };
+  path?: never;
+  query?: never;
+  url: "/v1/accounts";
+};
+
+export type CreateAccountResponses = {
+  /**
+   * Account created successfully
+   */
+  201: {
+    result: {
+      /**
+       * EVM address in hex format
+       */
+      address: string;
+      /**
+       * The predicted smart account address for use with the default thirdweb v0.7 AccountFactory
+       */
+      smartAccountAddress?: string;
+    };
+  };
+};
+
+export type CreateAccountResponse =
+  CreateAccountResponses[keyof CreateAccountResponses];
+
 export type WriteContractData = {
   body?: {
     /**

packages/thirdweb/src/bridge/Chains.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 import { TEST_CLIENT } from "~test/test-clients.js";
 import { chains } from "./Chains.js";
 
-describe("chains", () => {
+describe.runIf(process.env.TW_SECRET_KEY)("chains", () => {
   it("should fetch chains", async () => {
     // Setup
     const client = TEST_CLIENT;

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

@@ -0,0 +1,57 @@
+import { createAccount } from "@thirdweb-dev/engine";
+import { stringify } from "viem";
+import type { ThirdwebClient } from "../client/client.js";
+import { getThirdwebBaseUrl } from "../utils/domains.js";
+import { getClientFetch } from "../utils/fetch.js";
+
+export type CreateServerWalletArgs = {
+  client: ThirdwebClient;
+  label: string;
+};
+
+/**
+ * Create a server wallet.
+ * @param params - The parameters for the server wallet.
+ * @param params.client - The thirdweb client to use.
+ * @param params.label - The label for the server wallet.
+ * @returns The server wallet signer address and the predicted smart account address.
+ * @engine
+ * @example
+ * ```ts
+ * import { Engine } from "thirdweb";
+ *
+ * const serverWallet = await Engine.createServerWallet({
+ *   client,
+ *   label: "My Server Wallet",
+ * });
+ * console.log(serverWallet.address);
+ * console.log(serverWallet.smartAccountAddress);
+ * ```
+ */
+export async function createServerWallet(params: CreateServerWalletArgs) {
+  const { client, label } = params;
+  const result = await createAccount({
+    baseUrl: getThirdwebBaseUrl("engineCloud"),
+    bodySerializer: stringify,
+    fetch: getClientFetch(client),
+    body: {
+      label,
+    },
+  });
+
+  if (result.error) {
+    throw new Error(
+      `Error creating server wallet with label ${label}: ${stringify(
+        result.error,
+      )}`,
+    );
+  }
+
+  const data = result.data?.result;
+
+  if (!data) {
+    throw new Error(`No server wallet created with label ${label}`);
+  }
+
+  return data;
+}

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`,
-  );
-}