docs: add documentation for smart account provider fee options and ov…

…errides (#277) * feat: support one-off percentage overrides for user operations * feat: apply user op override or fee option utils in aa-core * docs: add documentation for smart account provider fee options and overrides * docs: add glossary section and add general types doc in the section
alchemyplatform · Dec 1, 2023 · 258d80e · 258d80e
1 parent dc979ff
commit 258d80e
Show file tree

Hide file tree

Showing 19 changed files with 426 additions and 22 deletions.
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -16,7 +16,7 @@ export type EmptyHex = `0x`;
 
 // based on @account-abstraction/common
 export type PromiseOrValue<T> = T | Promise<T>;
-export type BytesLike = Uint8Array | string;
+export type BytesLike = Uint8Array | Hex;
 export type Percentage = z.infer<typeof PercentageSchema>;
 
 export type BigNumberish = z.infer<typeof BigNumberishSchema>;

diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts
@@ -451,6 +451,25 @@ export default defineConfig({
               },
             ],
           },
+          {
+            text: "Types",
+            base: "/packages/aa-core/types",
+            collapsed: true,
+            items: [
+              {
+                text: "UserOperationFeeOptions",
+                link: "/UserOperationFeeOptions",
+              },
+              {
+                text: "UserOperationFeeOptionsField",
+                link: "/userOperationFeeOptionsField",
+              },
+              {
+                text: "UserOperationOverrides",
+                link: "/userOperationOverrides",
+              },
+            ],
+          },
           {
             text: "Utils",
             base: "/packages/aa-core/utils",
@@ -752,6 +771,28 @@ export default defineConfig({
           },
         ],
       },
+      {
+        text: "Glossary",
+        base: "/glossary",
+        items: [
+          {
+            text: "Types",
+            base: "/glossary/types",
+            collapsed: true,
+            items: [
+              { text: "BigNumberish", link: "/bigNumberish" },
+              {
+                text: "BigNumberishRange",
+                link: "/bigNumberishRange",
+              },
+              {
+                text: "Percentage",
+                link: "/percentage",
+              },
+            ],
+          },
+        ],
+      },
     ],
 
     socialLinks: [

diff --git a/site/glossary/types/bigNumberish.md b/site/glossary/types/bigNumberish.md
@@ -0,0 +1,46 @@
+---
+outline: deep
+head:
+  - - meta
+    - property: og:title
+      content: BigNumberish
+  - - meta
+    - name: description
+      content: Overview of the BigNumberish type in aa-core types
+  - - meta
+    - property: og:description
+      content: Overview of the BigNumberish type in aa-core types
+---
+
+# BigNumberish
+
+one of `Hex` (`0x{string}`), `bigint` or `number` type for representing `bigint` convertible values
+
+```ts
+import { z } from "zod";
+
+export const HexSchema = z.custom<`0x${string}` | "0x">((val) => {
+  return isHex(val) || val === "0x";
+});
+
+/*
+ * type BigNumberish = Hex | number | bigint
+ */
+export const BigNumberishSchema = z.union([HexSchema, z.number(), z.bigint()]);
+```
+
+## Usage
+
+::: code-group
+
+```ts [example.ts]
+import { type BigNumberish, isBigNumberish } from "@alchemy/aa-core";
+
+const bigNumberish1 = 10000000n;
+const bigNumberish2 = 0xf23cde;
+
+console.log(isBigNumberish(bigNumberish1)); // true
+console.log(isBigNumberish(bigNumberish2)); // true
+```
+
+:::
diff --git a/site/glossary/types/bigNumberishRange.md b/site/glossary/types/bigNumberishRange.md
@@ -0,0 +1,50 @@
+---
+outline: deep
+head:
+  - - meta
+    - property: og:title
+      content: BigNumberishRange
+  - - meta
+    - name: description
+      content: Overview of the BigNumberishRange type in aa-core types
+  - - meta
+    - property: og:description
+      content: Overview of the BigNumberishRange type in aa-core types
+---
+
+# BigNumberishRange
+
+object with optional fields `min` and `max` where each field is of type [`BigNumberish`](./bigNumberish.md) to represent a range type value between `min` and `max` inclusive
+
+```ts
+import { z } from "zod";
+
+/*
+ * type BigNumberishRange = {
+ *   min?: Hex | number | bigint
+ *   max?: Hex | number | bigint
+ * }
+ */
+
+export const BigNumberishRangeSchema = z
+  .object({
+    min: BigNumberishSchema.optional(),
+    max: BigNumberishSchema.optional(),
+  })
+  .strict();
+```
+
+## Usage
+
+::: code-group
+
+```ts [example.ts]
+import { type BigNumberishRange } from "@alchemy/aa-core";
+
+const bigNumberishRange = {
+  min: 1n,
+  max: "0x345dfe",
+};
+```
+
+:::
diff --git a/site/glossary/types/percentage.md b/site/glossary/types/percentage.md
@@ -0,0 +1,56 @@
+---
+outline: deep
+head:
+  - - meta
+    - property: og:title
+      content: Percentage
+  - - meta
+    - name: description
+      content: Overview of the Percentage type in aa-core types
+  - - meta
+    - property: og:description
+      content: Overview of the Percentage type in aa-core types
+---
+
+# Percentage
+
+object with required field `percentage` with a `number` value between 1 and 1000 inclusive
+
+```ts
+import { z } from "zod";
+
+/*
+ * type Percentage = {
+ *   percentage?: number
+ * }
+ */
+
+export const PercentageSchema = z
+  .object({
+    /**
+     * Percent value between 1 and 1000 inclusive
+     */
+    percentage: z.number().min(1).max(1000),
+  })
+  .strict();
+```
+
+## Usage
+
+::: code-group
+
+```ts [example.ts]
+import { type Percentage, isPercentage } from "@alchemy/aa-core";
+
+const percentage1 = {
+  percentage: 10,
+};
+const percentage2 = {
+  percentage: 100000,
+};
+
+console.log(isPercentage(percentage1)); // true
+console.log(isPercentage(percentage2)); // false
+```
+
+:::
diff --git a/site/guides/sponsoring-gas/gas-sponsorship-eligibility.md b/site/guides/sponsoring-gas/gas-sponsorship-eligibility.md
@@ -76,7 +76,7 @@ If you attempt to execute the `sendUserOperation` method for user operations ine
 
 This section of the guide elucidates how you can circumvent the `PaymasterMiddleware`, enabling the sending of user operations without gas sponsorship. This functionality permits the sending of user operations where users pay the gas fee themselves via their smart account.
 
-When employing various methods on `SmartAccountProvider` to send user operations (e.g., [`sendUserOperation`](/packages/aa-core/provider/sendUserOperation.md) or [`sendTransaction`](/packages/aa-core/provider/sendTransaction.md)), apart from the `UserOperationCallData` or `BatchUserOperationCallData`, you have the option to include an additional parameter named `overrides`. This parameter allows the specification of override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData`. To bypass the `PaymasterMiddleware`, you can specifically set the `paymasterAndData` override. For example, assigning an empty hex string (`0x`) to the `paymasterAndData` field in the overrides would result in the user operation being sent without the paymaster covering the gas fee, but rather paid from the user's own smart account.
+When employing various methods on `SmartAccountProvider` to send user operations (e.g., [`sendUserOperation`](/packages/aa-core/provider/sendUserOperation.md) or [`sendTransaction`](/packages/aa-core/provider/sendTransaction.md)), apart from the `UserOperationCallData` or `BatchUserOperationCallData`, you have the option to include an additional parameter named `overrides`. This parameter allows the specification of override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData`. To bypass the `PaymasterMiddleware`, you can specifically set the `paymasterAndData` override. For example, assigning an empty hex string (`0x`) to the `paymasterAndData` field in the overrides would result in the user operation being sent without the paymaster covering the gas fee, but rather paid from the user's own smart account.
 
 ```ts [bypass-paymaster-middleware.ts]
 // If gas sponsorship ineligible, baypass paymaster middleware by passing in the paymasterAndData override

diff --git a/site/packages/aa-alchemy/provider/introduction.md b/site/packages/aa-alchemy/provider/introduction.md
@@ -18,8 +18,8 @@ head:
 
 Notable differences between `AlchemyProvider` and `SmartAccountProvider` are implementations for:
 
-1.  [`gasEstimator`](/packages/aa-alchemy/provider/gasEstimator) -- overrides the `SmartAccountProvider` gas estimator.
-2.  [`withAlchemyGasManager`](/packages/aa-alchemy/provider/withAlchemyGasManager) -- adds the Alchemy Gas Manager middleware to the provider.
+1.  [`gasEstimator`](/packages/aa-core/provider/withGasEstimator.md) -- overrides the base `SmartAccountProvider` gas estimator.
+2.  [`withAlchemyGasManager`](/packages/aa-alchemy/provider/withAlchemyGasManager.md) -- adds the Alchemy Gas Manager middleware to the provider.
 
 ## Usage
 

diff --git a/site/packages/aa-alchemy/provider/simulateUserOperationAssetChanges.md b/site/packages/aa-alchemy/provider/simulateUserOperationAssetChanges.md
@@ -70,6 +70,6 @@ const uo = await provider.sendUserOperation(uoStruct);
 - `data: Hex` - can be either `0x` or a call data string
 - `value?: bigint` - optionally, set the value in wei you want to send to the target
 
-### `overrides?: UserOperationOverrides`
+### `overrides?:` [`UserOperationOverrides`](/packages/aa-core/types/userOperationOverrides.md)
 
-Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData` on the user operation request
+Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData` on the user operation request
diff --git a/site/packages/aa-core/provider/buildUserOperation.md b/site/packages/aa-core/provider/buildUserOperation.md
@@ -75,6 +75,6 @@ A Promise containing the _unsigned_ UO struct resulting from the middleware pipe
 - `data: Hex` - can be either `0x` or a call data string
 - `value?: bigint` - optionally, set the value in wei you want to send to the target
 
-### `overrides?: UserOperationOverrides`
+### `overrides?:` [`UserOperationOverrides`](/packages/aa-core/types/userOperationOverrides.md)
 
-Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData` on the user operation request
+Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData` on the user operation request
diff --git a/site/packages/aa-core/provider/buildUserOperationFromTx.md b/site/packages/aa-core/provider/buildUserOperationFromTx.md
@@ -60,6 +60,6 @@ A Promise containing the _unsigned_ UO struct converted from the input transacti
 
 The `RpcTransactionRequest` object representing a traditional ethereum transaction
 
-### `overrides?: UserOperationOverrides`
+### `overrides?:` [`UserOperationOverrides`](/packages/aa-core/types/userOperationOverrides.md)
 
-Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData` on the user operation request
+Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData` on the user operation request
diff --git a/site/packages/aa-core/provider/checkGasSponsorshipEligibility.md b/site/packages/aa-core/provider/checkGasSponsorshipEligibility.md
@@ -59,6 +59,6 @@ A Promise containing the boolean value indicating whether the UO to be sent is e
 - `data: Hex` - can be either `0x` or a call data string
 - `value?: bigint` - optionally, set the value in wei you want to send to the target
 
-### `overrides?: UserOperationOverrides`
+### `overrides?:` [`UserOperationOverrides`](/packages/aa-core/types/userOperationOverrides.md)
 
-Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData` on the user operation request
+Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData` on the user operation request
diff --git a/site/packages/aa-core/provider/constructor.md b/site/packages/aa-core/provider/constructor.md
@@ -57,12 +57,27 @@ A new instance of a `SmartAccountProvider`.
 
 - `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).
 
-- `opts: Object | undefined` -- [optional] overrides on provider config variables having to do with fetching transaction receipts and fee computation.
+- `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).
 
   - `txRetryIntervalMs: string | undefined` -- [optional] the interval in milliseconds to wait between retries while waiting for transaction receipts (default: 2_000).
 
   - `txRetryMulitplier: string | undefined` -- [optional] the mulitplier on interval length to wait between retries while waiting for transaction receipts (default: 1.5).
 
-  - `minPriorityFeePerBid: string | undefined` --[optional] used when computing the fees for a user operation (default: 100_000_000).
+  - `feeOptions:` [`UserOperationFeeOptions`](/packages/aa-core/types/userOperationFeeOptions.md) `| undefined` --[optional] user operation fee options to be used for gas estimation, set at the global level on the provider.
+    If not set, default fee options for the chain are used. Available fields in `feeOptions` include `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` where each field is of type [`UserOperationFeeOptionsField`](/packages/aa-core/types/userOperationFeeOptionsField.md).
+
+    - `maxFeePerGas`: `UserOperationFeeOptionsField`
+    - `maxPriorityFeePerGas`: `UserOperationFeeOptionsField`
+    - `callGasLimit`: `UserOperationFeeOptionsField`
+    - `verificationGasLimit`: `UserOperationFeeOptionsField`
+    - `preVerificationGas`: `UserOperationFeeOptionsField`
+
+:::tip Note
+The fee options set upon the provider initialization are available from each middleware of the `SmartAccountProvider`. For example, the default middlewares such as [`gasEstimator`](/packages/aa-core/provider/withGasEstimator.md) or [`feeDataGetter`](/packages/aa-core/provider/withFeeDataGetter.md) apply the fee options to the estimated values if the fee options are set.
+:::
+
+:::tip Note
+Note that if you are using your own middleware, for example a custom `feeDataGetter` using [`withFeeDataGetter`](/packages/aa-core/provider/withFeeDataGetter.md) method on the provider, then the default `feeDataGetter` middleware is overriden. As you are opting out of using the default middleware, you are also responsible for handling the fee options appropriately for the fee options set upon provider initialization.
+:::
diff --git a/site/packages/aa-core/provider/dropAndReplaceUserOperation.md b/site/packages/aa-core/provider/dropAndReplaceUserOperation.md
@@ -51,6 +51,6 @@ A Promise containing the hash of the user operation and the request that was sen
 
 A previously submitted `UserOperation`.
 
-### `overrides?: UserOperationOverrides`
+### `overrides?:` [`UserOperationOverrides`](/packages/aa-core/types/userOperationOverrides.md)
 
-Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData` on the user operation request
+Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData` on the user operation request
diff --git a/site/packages/aa-core/provider/sendTransaction.md b/site/packages/aa-core/provider/sendTransaction.md
@@ -54,6 +54,6 @@ A Promise containing the transaction hash
 
 The `RpcTransactionRequest` object representing a traditional ethereum transaction
 
-### `overrides?: UserOperationOverrides`
+### `overrides?:` [`UserOperationOverrides`](/packages/aa-core/types/userOperationOverrides.md)
 
-Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData` on the user operation request
+Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData` on the user operation request
diff --git a/site/packages/aa-core/provider/sendTransactions.md b/site/packages/aa-core/provider/sendTransactions.md
@@ -75,6 +75,6 @@ A Promise containing the transaction hash
 
 An `RpcTransactionRequest` array representing a traditional ethereum transaction
 
-### `overrides?: UserOperationOverrides`
+### `overrides?:` [`UserOperationOverrides`](/packages/aa-core/types/userOperationOverrides.md)
 
-Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData` on the user operation request
+Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData` on the user operation request
diff --git a/site/packages/aa-core/provider/sendUserOperation.md b/site/packages/aa-core/provider/sendUserOperation.md
@@ -73,6 +73,6 @@ A Promise containing the hash of the user operation and the request that was sen
 - `data: Hex` - can be either `0x` or a call data string
 - `value?: bigint` - optionally, set the value in wei you want to send to the target
 
-### `overrides?: UserOperationOverrides`
+### `overrides?:` [`UserOperationOverrides`](/packages/aa-core/types/userOperationOverrides.md)
 
-Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas` or `paymasterAndData` on the user operation request
+Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit` or `paymasterAndData` on the user operation request