docs: add docs for using 3rd party bundlers and paymasters

packages/alchemy/src/middleware/gasManager.ts

@@ -1,4 +1,7 @@
-import type { ClientMiddleware, ClientMiddlewareFn } from "@alchemy/aa-core";
+import type {
+  ClientMiddlewareConfig,
+  ClientMiddlewareFn,
+} from "@alchemy/aa-core";
 import {
   deepHexlify,
   defaultGasEstimator,
@@ -34,12 +37,26 @@ export interface AlchemyGasEstimationOptions {
   fallbackFeeDataGetter?: ClientMiddlewareFn;
 }
 
+const dummyPaymasterAndData =
+  <C extends ClientWithAlchemyMethods>(client: C) =>
+  () => {
+    switch (client.chain.id) {
+      case 1:
+      case 10:
+      case 137:
+      case 42161:
+        return "0x4Fd9098af9ddcB41DA48A1d78F91F1398965addcfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c";
+      default:
+        return "0xc03aac639bb21233e0139381970328db8bceeb67fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c";
+    }
+  };
+
 export const alchemyGasManagerMiddleware = <C extends ClientWithAlchemyMethods>(
   client: C,
   config: AlchemyGasManagerConfig
 ): Pick<
-  ClientMiddleware,
-  "dummyPaymasterAndData" | "paymasterAndData" | "feeEstimator" | "gasEstimator"
+  ClientMiddlewareConfig,
+  "paymasterAndData" | "feeEstimator" | "gasEstimator"
 > => {
   const gasEstimationOptions = config.gasEstimationOptions;
   const disableGasEstimation =
@@ -103,25 +120,6 @@ export const alchemyGasManagerMiddleware = <C extends ClientWithAlchemyMethods>(
             maxPriorityFeePerGas,
           };
         },
-    dummyPaymasterAndData: async (struct) => {
-      switch (client.chain.id) {
-        case 1:
-        case 10:
-        case 137:
-        case 42161:
-          return {
-            ...struct,
-            paymasterAndData:
-              "0x4Fd9098af9ddcB41DA48A1d78F91F1398965addcfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c",
-          };
-        default:
-          return {
-            ...struct,
-            paymasterAndData:
-              "0xc03aac639bb21233e0139381970328db8bceeb67fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c",
-          };
-      }
-    },
     paymasterAndData: disableGasEstimation
       ? requestPaymasterAndData(client, config)
       : requestGasAndPaymasterData(client, config),
@@ -131,9 +129,9 @@ export const alchemyGasManagerMiddleware = <C extends ClientWithAlchemyMethods>(
 const requestGasAndPaymasterData: <C extends ClientWithAlchemyMethods>(
   client: C,
   config: AlchemyGasManagerConfig
-) => ClientMiddlewareFn =
-  (client, config) =>
-  async (struct, { overrides, feeOptions, account }) => {
+) => ClientMiddlewareConfig["paymasterAndData"] = (client, config) => ({
+  dummyPaymasterAndData: dummyPaymasterAndData(client),
+  paymasterAndData: async (struct, { overrides, feeOptions, account }) => {
     const userOperation: UserOperationRequest = deepHexlify(
       await resolveProperties(struct)
     );
@@ -196,14 +194,15 @@ const requestGasAndPaymasterData: <C extends ClientWithAlchemyMethods>(
       ...struct,
       ...result,
     };
-  };
+  },
+});
 
 const requestPaymasterAndData: <C extends ClientWithAlchemyMethods>(
   client: C,
   config: AlchemyGasManagerConfig
-) => ClientMiddlewareFn =
-  (client, config) =>
-  async (struct, { account }) => {
+) => ClientMiddlewareConfig["paymasterAndData"] = (client, config) => ({
+  dummyPaymasterAndData: dummyPaymasterAndData(client),
+  paymasterAndData: async (struct, { account }) => {
     const { paymasterAndData } = await client.request({
       method: "alchemy_requestPaymasterAndData",
       params: [
@@ -219,4 +218,5 @@ const requestPaymasterAndData: <C extends ClientWithAlchemyMethods>(
       ...struct,
       paymasterAndData,
     };
-  };
+  },
+});

packages/core/src/client/smartAccountClient.ts

@@ -24,6 +24,7 @@ import {
   type BaseSmartAccountClientActions,
 } from "./decorators/smartAccountClient.js";
 import { SmartAccountClientOptsSchema } from "./schema.js";
+import type { ClientMiddlewareConfig } from "./types.js";
 
 type SmartAccountClientOpts = z.output<typeof SmartAccountClientOptsSchema>;
 
@@ -40,7 +41,7 @@ export type SmartAccountClientConfig<
   > & {
     account?: account;
     opts?: z.input<typeof SmartAccountClientOptsSchema>;
-  } & Partial<ClientMiddleware>
+  } & ClientMiddlewareConfig
 >;
 
 export type SmartAccountClientRpcSchema = [

packages/core/src/client/types.ts

@@ -1,6 +1,10 @@
 import type { Address } from "abitype";
 import type { Hash, Hex } from "viem";
 import type { z } from "zod";
+import type {
+  ClientMiddleware,
+  ClientMiddlewareFn,
+} from "../middleware/types.js";
 import type { UserOperationRequest } from "../types.js";
 import type { ConnectionConfigSchema } from "./schema.js";
 
@@ -19,3 +23,13 @@ export type UpgradeToData = {
   implAddress: Address;
   initializationData: Hex;
 };
+
+export type ClientMiddlewareConfig = Omit<
+  Partial<ClientMiddleware>,
+  "dummyPaymasterAndData" | "paymasterAndData"
+> & {
+  paymasterAndData?: {
+    dummyPaymasterAndData: () => Hex;
+    paymasterAndData: ClientMiddlewareFn;
+  };
+};

packages/core/src/middleware/actions.ts

@@ -10,6 +10,7 @@ import type {
   BundlerActions,
   BundlerRpcSchema,
 } from "../client/decorators/bundlerClient.js";
+import type { ClientMiddlewareConfig } from "../client/types.js";
 import { defaultFeeEstimator } from "./defaults/feeEstimator.js";
 import { defaultGasEstimator } from "./defaults/gasEstimator.js";
 import { defaultPaymasterAndData } from "./defaults/paymasterAndData.js";
@@ -31,7 +32,7 @@ export type MiddlewareClient<
 >;
 
 export const middlewareActions =
-  (overrides: Partial<ClientMiddleware>) =>
+  (overrides: ClientMiddlewareConfig) =>
   <
     TTransport extends Transport = Transport,
     TChain extends Chain | undefined = Chain | undefined,
@@ -43,11 +44,17 @@ export const middlewareActions =
   ): { middleware: ClientMiddleware } => ({
     middleware: {
       customMiddleware: overrides.customMiddleware ?? noopMiddleware,
-      dummyPaymasterAndData:
-        overrides.dummyPaymasterAndData ?? defaultPaymasterAndData,
+      dummyPaymasterAndData: overrides.paymasterAndData?.dummyPaymasterAndData
+        ? async (struct) => ({
+            ...struct,
+            paymasterAndData:
+              overrides.paymasterAndData!.dummyPaymasterAndData(),
+          })
+        : defaultPaymasterAndData,
       feeEstimator: overrides.feeEstimator ?? defaultFeeEstimator(client),
       gasEstimator: overrides.gasEstimator ?? defaultGasEstimator(client),
-      paymasterAndData: overrides.paymasterAndData ?? defaultPaymasterAndData,
+      paymasterAndData:
+        overrides.paymasterAndData?.paymasterAndData ?? defaultPaymasterAndData,
       userOperationSimulator:
         overrides.userOperationSimulator ?? noopMiddleware,
     },

site/.vitepress/sidebar/new.ts

@@ -146,9 +146,10 @@ export const newSidebar: DefaultTheme.Sidebar = [
   },
   {
     text: "Third Party Integrations",
+    base: "/third-party",
     items: [
-      { text: "Bundlers", link: "/" },
-      { text: "Paymasters", link: "/" },
+      { text: "Bundlers", link: "/bundlers" },
+      { text: "Paymasters", link: "/paymasters" },
     ],
   },
   packagesSidebar,

site/packages/aa-alchemy/smart-account-client/index.md

@@ -77,6 +77,16 @@ A new instance of an `AlchemySmartAccountClient`.
 
   - `policyId: string` -- the policy id of the gas manager you want to use.
 
+- `account?: SmartContractAccount` -- [optional] the smart account to use as context for all of your calls. If not provided, then the account can be provided to each individual call instead.
+
+- `entryPointAddress: Address | undefined` -- [optional] the entry point contract address. If not provided, the entry point contract address for the provider is the connected account's entry point contract, or if not connected, falls back to the default entry point contract for the chain. See [getDefaultEntryPointAddress](/packages/aa-core/utils/getDefaultEntryPointAddress.html#getdefaultentrypointaddress).
+
+- `feeEstimator?: ClientMiddlewareFn` -- [optional] an override for the fee estimator middleware. The `feeEstimator` middleware function calculates `maxFeePerGas` and `maxPriorityFeePerGas` for your User Operation.
+
+- `gasEstimator?: ClientMiddlewareFn` -- [optional] an override for the gas estimator middleware. The `gasEstimator` middleware function calculates the gas fields of your User Operation.
+
+- `customMiddleware?: ClientMiddlewareFn` -- [optional] if you would like to run a custom transformation on your User Operation after Gas and Fee estimation, but before your paymaster is called, you can provide a custom middleware function here.
+
 - `opts: SmartAccountProviderOpts | undefined` -- [optional] overrides on provider config variables having to do with fetching transaction receipts and fee computation.
 
   - `txMaxRetries: string | undefined` -- [optional] the maximum number of times to try fetching a transaction receipt before giving up (default: 5).

site/packages/aa-core/smart-account-client/index.md

@@ -106,15 +106,16 @@ A new instance of a `SmartAccountClient`.
 
 - `entryPointAddress: Address | undefined` -- [optional] the entry point contract address. If not provided, the entry point contract address for the provider is the connected account's entry point contract, or if not connected, falls back to the default entry point contract for the chain. See [getDefaultEntryPointAddress](/packages/aa-core/utils/getDefaultEntryPointAddress.html#getdefaultentrypointaddress).
 
-- `dummyPaymasterAndData?: ClientMiddlewareFn` -- [optional] an override for the dummy paymaster and data middleware. This is useful if you want to use a paymaster. The `dummyPaymasterAndData` middleware function is run before all other middlewares and is used during gas and fee estimation. It should be a value that does not cause your paymaster to revert.
-
 - `feeEstimator?: ClientMiddlewareFn` -- [optional] an override for the fee estimator middleware. The `feeEstimator` middleware function calculates `maxFeePerGas` and `maxPriorityFeePerGas` for your User Operation.
 
 - `gasEstimator?: ClientMiddlewareFn` -- [optional] an override for the gas estimator middleware. The `gasEstimator` middleware function calculates the gas fields of your User Operation.
 
 - `customMiddleware?: ClientMiddlewareFn` -- [optional] if you would like to run a custom transformation on your User Operation after Gas and Fee estimation, but before your paymaster is called, you can provide a custom middleware function here.
 
-- `paymasterAndData?: ClientMiddlewareFn` -- [optional] if you owuld like to use a paymaster, then this middleware must be supplied in conjunction with the above `dummyPaymasterAndData` middleware. This middleware runs after gas and fee estimation and should generate the `paymasterAndData` field that will be used to sponsor your user operation.
+- `paymasterAndData?: ClientMiddlewareConfig["paymasterAndData"]` -- [optional] if you would like to use a paymaster, then this config must be supplied.
+
+  - `paymasterAndData: ClientMiddlewareFn` -- this middleware function calculates the paymaster and data fields of your User Operation after estimating gas and fees
+  - `dummyPaymasterAndData: () => Hex` -- this just returns a Hex string to be used during gas and fee estimation. This will depend on your paymaster provider and must be a value that accurately resembles the gas cost of using your paymaster and does not revert during validation.
 
 - `opts: SmartAccountProviderOpts | undefined` -- [optional] overrides on provider config variables having to do with fetching transaction receipts and fee computation.