feat: batching for reads and smart-account writes (#773)

* Refactor: Add readMulticall route for batch contract reads

* bump thirdweb + serialise bigint

* Address review comments

* fixed import

* feat: add batch operations support for transactions and enhance wallet details retrieval

* SDK changes

* Address review comments

sdk/src/services/BackendWalletService.ts

@@ -629,6 +629,78 @@ export class BackendWalletService {
         });
     }
 
+    /**
+     * Send a batch of raw transactions atomically
+     * Send a batch of raw transactions in a single UserOp. Transactions will be sent in-order and atomically. Can only be used with smart wallets.
+     * @param chain A chain ID ("137") or slug ("polygon-amoy-testnet"). Chain ID is preferred.
+     * @param xBackendWalletAddress Backend wallet address
+     * @param requestBody
+     * @param simulateTx Simulates the transaction before adding it to the queue, returning an error if it fails simulation. Note: This step is less performant and recommended only for debugging purposes.
+     * @param xIdempotencyKey Transactions submitted with the same idempotency key will be de-duplicated. Only the last 100000 transactions are compared.
+     * @param xAccountAddress Smart account address
+     * @param xAccountFactoryAddress Smart account factory address. If omitted, Engine will try to resolve it from the contract.
+     * @param xAccountSalt Smart account salt as string or hex. This is used to predict the smart account address. Useful when creating multiple accounts with the same admin and only needed when deploying the account as part of a userop.
+     * @returns any Default Response
+     * @throws ApiError
+     */
+    public sendTransactionBatchAtomic(
+        chain: string,
+        xBackendWalletAddress: string,
+        requestBody: {
+            transactions: Array<{
+                /**
+                 * A contract or wallet address
+                 */
+                toAddress?: string;
+                /**
+                 * A valid hex string
+                 */
+                data: string;
+                /**
+                 * An amount in wei (no decimals). Example: "50000000000"
+                 */
+                value: string;
+            }>;
+        },
+        simulateTx: boolean = false,
+        xIdempotencyKey?: string,
+        xAccountAddress?: string,
+        xAccountFactoryAddress?: string,
+        xAccountSalt?: string,
+    ): CancelablePromise<{
+        result: {
+            /**
+             * Queue ID
+             */
+            queueId: string;
+        };
+    }> {
+        return this.httpRequest.request({
+            method: 'POST',
+            url: '/backend-wallet/{chain}/send-transaction-batch-atomic',
+            path: {
+                'chain': chain,
+            },
+            headers: {
+                'x-backend-wallet-address': xBackendWalletAddress,
+                'x-idempotency-key': xIdempotencyKey,
+                'x-account-address': xAccountAddress,
+                'x-account-factory-address': xAccountFactoryAddress,
+                'x-account-salt': xAccountSalt,
+            },
+            query: {
+                'simulateTx': simulateTx,
+            },
+            body: requestBody,
+            mediaType: 'application/json',
+            errors: {
+                400: `Bad Request`,
+                404: `Not Found`,
+                500: `Internal Server Error`,
+            },
+        });
+    }
+
     /**
      * Sign a transaction
      * Sign a transaction
@@ -833,6 +905,7 @@ export class BackendWalletService {
                 onchainStatus: ('success' | 'reverted' | null);
                 effectiveGasPrice: (string | null);
                 cumulativeGasUsed: (string | null);
+                batchOperations: null;
             }>;
         };
     }> {
@@ -928,6 +1001,7 @@ export class BackendWalletService {
                 onchainStatus: ('success' | 'reverted' | null);
                 effectiveGasPrice: (string | null);
                 cumulativeGasUsed: (string | null);
+                batchOperations: null;
             } | string);
         }>;
     }> {

sdk/src/services/ContractService.ts

@@ -46,6 +46,50 @@ export class ContractService {
         });
     }
 
+    /**
+     * Batch read from multiple contracts
+     * Execute multiple contract read operations in a single call using Multicall
+     * @param chain
+     * @param requestBody
+     * @returns any Default Response
+     * @throws ApiError
+     */
+    public readBatch(
+        chain: string,
+        requestBody: {
+            calls: Array<{
+                contractAddress: string;
+                functionName: string;
+                functionAbi?: string;
+                args?: Array<any>;
+            }>;
+            /**
+             * Address of the multicall contract to use. If omitted, multicall3 contract will be used (0xcA11bde05977b3631167028862bE2a173976CA11).
+             */
+            multicallAddress?: string;
+        },
+    ): CancelablePromise<{
+        results: Array<{
+            success: boolean;
+            result: any;
+        }>;
+    }> {
+        return this.httpRequest.request({
+            method: 'POST',
+            url: '/contract/{chain}/read-batch',
+            path: {
+                'chain': chain,
+            },
+            body: requestBody,
+            mediaType: 'application/json',
+            errors: {
+                400: `Bad Request`,
+                404: `Not Found`,
+                500: `Internal Server Error`,
+            },
+        });
+    }
+
     /**
      * Write to contract
      * Call a write function on a contract.

sdk/src/services/TransactionService.ts

@@ -78,6 +78,7 @@ export class TransactionService {
                 onchainStatus: ('success' | 'reverted' | null);
                 effectiveGasPrice: (string | null);
                 cumulativeGasUsed: (string | null);
+                batchOperations: null;
             }>;
             totalCount: number;
         };
@@ -162,6 +163,7 @@ export class TransactionService {
             onchainStatus: ('success' | 'reverted' | null);
             effectiveGasPrice: (string | null);
             cumulativeGasUsed: (string | null);
+            batchOperations: null;
         };
     }> {
         return this.httpRequest.request({
@@ -245,6 +247,7 @@ export class TransactionService {
                 onchainStatus: ('success' | 'reverted' | null);
                 effectiveGasPrice: (string | null);
                 cumulativeGasUsed: (string | null);
+                batchOperations: null;
             }>;
             totalCount: number;
         };

src/scripts/generate-sdk.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import { kill } from "node:process";
 
 const ENGINE_OPENAPI_URL = "https://demo.web3api.thirdweb.com/json";
-// const ENGINE_OPENAPI_URL = "http://localhost:3005/json";
+// const ENGINE_OPENAPI_URL = "http://127.0.0.1:3005/json";
 const REPLACE_LOG_FILE = "sdk/replacement_log.txt";
 
 type BasicOpenAPISpec = {

src/server/routes/backend-wallet/send-transaction-batch-atomic.ts

@@ -0,0 +1,143 @@
+import { Type, type Static } from "@sinclair/typebox";
+import type { FastifyInstance } from "fastify";
+import { StatusCodes } from "http-status-codes";
+import type { Address, Hex } from "thirdweb";
+import { insertTransaction } from "../../../shared/utils/transaction/insert-transaction";
+import {
+  requestQuerystringSchema,
+  standardResponseSchema,
+  transactionWritesResponseSchema,
+} from "../../schemas/shared-api-schemas";
+import {
+  maybeAddress,
+  walletChainParamSchema,
+  walletWithAAHeaderSchema,
+} from "../../schemas/wallet";
+import { getChainIdFromChain } from "../../utils/chain";
+import {
+  getWalletDetails,
+  isSmartBackendWallet,
+  type ParsedWalletDetails,
+  WalletDetailsError,
+} from "../../../shared/db/wallets/get-wallet-details";
+import { createCustomError } from "../../middleware/error";
+import { RawTransactionParamsSchema } from "../../schemas/transaction/raw-transaction-parms";
+
+const requestBodySchema = Type.Object({
+  transactions: Type.Array(RawTransactionParamsSchema, {
+    minItems: 1,
+  }),
+});
+
+export async function sendTransactionBatchAtomicRoute(fastify: FastifyInstance) {
+  fastify.route<{
+    Params: Static<typeof walletChainParamSchema>;
+    Body: Static<typeof requestBodySchema>;
+    Reply: Static<typeof transactionWritesResponseSchema>;
+    Querystring: Static<typeof requestQuerystringSchema>;
+  }>({
+    method: "POST",
+    url: "/backend-wallet/:chain/send-transaction-batch-atomic",
+    schema: {
+      summary: "Send a batch of raw transactions atomically",
+      description:
+        "Send a batch of raw transactions in a single UserOp. Transactions will be sent in-order and atomically. Can only be used with smart wallets.",
+      tags: ["Backend Wallet"],
+      operationId: "sendTransactionBatchAtomic",
+      params: walletChainParamSchema,
+      body: requestBodySchema,
+      headers: Type.Omit(walletWithAAHeaderSchema, ["x-transaction-mode"]),
+      querystring: requestQuerystringSchema,
+      response: {
+        ...standardResponseSchema,
+        [StatusCodes.OK]: transactionWritesResponseSchema,
+      },
+    },
+    handler: async (request, reply) => {
+      const { chain } = request.params;
+      const {
+        "x-backend-wallet-address": fromAddress,
+        "x-idempotency-key": idempotencyKey,
+        "x-account-address": accountAddress,
+        "x-account-factory-address": accountFactoryAddress,
+        "x-account-salt": accountSalt,
+      } = request.headers as Static<typeof walletWithAAHeaderSchema>;
+      const chainId = await getChainIdFromChain(chain);
+      const shouldSimulate = request.query.simulateTx ?? false;
+      const transactionRequests = request.body.transactions;
+
+      const hasSmartHeaders = !!accountAddress;
+
+      // check that we either use SBW, or send using EOA with smart wallet headers
+      if (!hasSmartHeaders) {
+        let backendWallet: ParsedWalletDetails | undefined;
+
+        try {
+          backendWallet = await getWalletDetails({
+            address: fromAddress,
+          });
+        } catch (e: unknown) {
+          if (e instanceof WalletDetailsError) {
+            throw createCustomError(
+              `Failed to get wallet details for backend wallet ${fromAddress}. ${e.message}`,
+              StatusCodes.BAD_REQUEST,
+              "WALLET_DETAILS_ERROR",
+            );
+          }
+        }
+
+        if (!backendWallet) {
+          throw createCustomError(
+            "Failed to get wallet details for backend wallet. See: https://portal.thirdweb.com/engine/troubleshooting",
+            StatusCodes.INTERNAL_SERVER_ERROR,
+            "WALLET_DETAILS_ERROR",
+          );
+        }
+
+        if (!isSmartBackendWallet(backendWallet)) {
+          throw createCustomError(
+            "Backend wallet is not a smart wallet, and x-account-address is not provided. Either use a smart backend wallet or provide x-account-address. This endpoint can only be used with smart wallets.",
+            StatusCodes.BAD_REQUEST,
+            "BACKEND_WALLET_NOT_SMART",
+          );
+        }
+      }
+
+      if (transactionRequests.length === 0) {
+        throw createCustomError(
+          "No transactions provided",
+          StatusCodes.BAD_REQUEST,
+          "NO_TRANSACTIONS_PROVIDED",
+        );
+      }
+
+      const queueId = await insertTransaction({
+        insertedTransaction: {
+          transactionMode: undefined,
+          isUserOp: false,
+          chainId,
+          from: fromAddress as Address,
+          accountAddress: maybeAddress(accountAddress, "x-account-address"),
+          accountFactoryAddress: maybeAddress(
+            accountFactoryAddress,
+            "x-account-factory-address",
+          ),
+          accountSalt: accountSalt,
+          batchOperations: transactionRequests.map((transactionRequest) => ({
+            to: transactionRequest.toAddress as Address | undefined,
+            data: transactionRequest.data as Hex,
+            value: BigInt(transactionRequest.value),
+          })),
+        },
+        shouldSimulate,
+        idempotencyKey,
+      });
+
+      reply.status(StatusCodes.OK).send({
+        result: {
+          queueId,
+        },
+      });
+    },
+  });
+}