From 2d4dd104bbfcc9441a6324333a33faf3bcdac3f4 Mon Sep 17 00:00:00 2001 From: Dennis Won Date: Thu, 18 Apr 2024 10:25:31 -0700 Subject: [PATCH] docs: update account kit documentation with up to date version of the sdk --- packages/accounts/CHANGELOG.md | 6 +-- .../core/src/account/smartContractAccount.ts | 4 ++ packages/core/src/client/types.ts | 2 + packages/core/src/entrypoint/types.ts | 2 + packages/core/src/types.ts | 28 +++++++++----- site/.vitepress/config.ts | 2 +- site/.vitepress/sidebar/index.ts | 6 +++ .../migrating-to-v3.md} | 22 +++++------ .../actions/estimateUserOperationGas.md | 14 +++++-- .../actions/buildUserOperation.md | 30 +-------------- .../actions/buildUserOperationFromTx.md | 36 +++--------------- .../actions/buildUserOperationFromTxs.md | 14 +------ .../actions/checkGasSponsorshipEligibility.md | 22 +---------- .../actions/sendTransaction.md | 26 +------------ .../actions/sendUserOperation.md | 34 +++-------------- .../actions/upgradeAccount.md | 2 +- .../smart-account-client/middleware/index.md | 16 +++++++- site/resources/terms.md | 4 +- site/resources/types.md | 37 +++++++++++++++++-- site/snippets/aa-core/send-tx-param.md | 12 +++--- site/snippets/aa-core/send-uo-param.md | 21 +++++------ 21 files changed, 138 insertions(+), 202 deletions(-) rename site/{migration-guide.md => migration-guides/migrating-to-v3.md} (90%) diff --git a/packages/accounts/CHANGELOG.md b/packages/accounts/CHANGELOG.md index f35c5a737d..a62a605ccb 100644 --- a/packages/accounts/CHANGELOG.md +++ b/packages/accounts/CHANGELOG.md @@ -196,10 +196,10 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline - **aa-ethers:** aa-ethers has had some functionality removed and apis changed -* inputs to the ProviderAdapter now require a SmartAccountClient -* with\* methods have been removed, middleware config now exists +- inputs to the ProviderAdapter now require a SmartAccountClient +- with\* methods have been removed, middleware config now exists on the SmartAccountClient -* the Account Signer has been updated to take a SmartContractAccount +- the Account Signer has been updated to take a SmartContractAccount as input - all interfaces now use the new smart account diff --git a/packages/core/src/account/smartContractAccount.ts b/packages/core/src/account/smartContractAccount.ts index 6b6ae46887..4dc5a74a55 100644 --- a/packages/core/src/account/smartContractAccount.ts +++ b/packages/core/src/account/smartContractAccount.ts @@ -116,6 +116,7 @@ export interface AccountEntryPointRegistry "0.7.0": SmartContractAccount; } +//#region ToSmartContractAccountParams export type ToSmartContractAccountParams< Name extends string = string, TTransport extends Transport = Transport, @@ -135,6 +136,7 @@ export type ToSmartContractAccountParams< signUserOperationHash?: (uoHash: Hex) => Promise; encodeUpgradeToAndCall?: (params: UpgradeToAndCallParams) => Promise; } & Omit; +//#endregion ToSmartContractAccountParams export const parseFactoryAddressFromAccountInitCode = ( initCode: Hex @@ -190,6 +192,7 @@ export const getAccountAddress = async ({ throw new GetCounterFactualAddressError(); }; +//#region toSmartContractAccount export async function toSmartContractAccount< Name extends string = string, TTransport extends Transport = Transport, @@ -215,6 +218,7 @@ export async function toSmartContractAccount< TChain, TEntryPointVersion >): Promise>; +//#endregion toSmartContractAccount export async function toSmartContractAccount({ transport, diff --git a/packages/core/src/client/types.ts b/packages/core/src/client/types.ts index d36f527cfd..b62b568206 100644 --- a/packages/core/src/client/types.ts +++ b/packages/core/src/client/types.ts @@ -32,6 +32,7 @@ export type UpgradeToData = { }; //#endregion UpgradeToData +//#region ClientMiddlewareConfig export type ClientMiddlewareConfig< TContext extends UserOperationContext | undefined = | UserOperationContext @@ -45,3 +46,4 @@ export type ClientMiddlewareConfig< paymasterAndData: ClientMiddlewareFn; }; }; +//#endregion ClientMiddlewareConfig diff --git a/packages/core/src/entrypoint/types.ts b/packages/core/src/entrypoint/types.ts index c9afb2edff..22c16bf0ed 100644 --- a/packages/core/src/entrypoint/types.ts +++ b/packages/core/src/entrypoint/types.ts @@ -65,6 +65,7 @@ export interface EntryPointRegistry "0.7.0": SupportedEntryPoint<"0.7.0", TChain, typeof EntryPointAbi_v7>; } +//#region EntryPointDef export type EntryPointDef< TEntryPointVersion extends EntryPointVersion, TChain extends Chain = Chain, @@ -81,6 +82,7 @@ export type EntryPointDef< userOperation: UserOperationRequest ) => Hex; }; +//#endregion EntryPointDef export interface EntryPointDefRegistry extends EntryPointRegistryBase< diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts index 770d79c449..66fdafcfea 100644 --- a/packages/core/src/types.ts +++ b/packages/core/src/types.ts @@ -67,6 +67,7 @@ export type UserOperationOverridesParameter< ? { overrides: UserOperationOverrides } : { overrides?: UserOperationOverrides }; +//#region UserOperationPaymasterOverrides export type UserOperationPaymasterOverrides< TEntryPointVersion extends EntryPointVersion > = TEntryPointVersion extends "0.6.0" @@ -79,14 +80,17 @@ export type UserOperationPaymasterOverrides< // paymasterData overrides only allows '0x' for bypassing the paymaster middleware // if set to '0x', all paymaster related fields are omitted from the user op request paymasterData: EmptyHex; - paymasterVerificationGasLimit: NoUndefined< - UserOperationStruct<"0.7.0">["paymasterVerificationGasLimit"] - >; - paymasterPostOpGasLimit: NoUndefined< - UserOperationStruct<"0.7.0">["paymasterPostOpGasLimit"] - >; + paymasterVerificationGasLimit: + | NoUndefined< + UserOperationStruct<"0.7.0">["paymasterVerificationGasLimit"] + > + | Multiplier; + paymasterPostOpGasLimit: + | NoUndefined["paymasterPostOpGasLimit"]> + | Multiplier; } : {}; +//#endregion UserOperationOverridesParameter //#region UserOperationOverrides export type UserOperationOverrides< @@ -116,6 +120,14 @@ export type UserOperationOverrides< * one user operation for your account in a bundle */ nonceKey: bigint; + + /** The same state overrides for + * [`eth_call`](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#eth-call) method. + * An address-to-state mapping, where each entry specifies some state to be ephemerally overridden + * prior to executing the call. State overrides allow you to customize the network state for + * the purpose of the simulation, so this feature is useful when you need to estimate gas + * for user operation scenarios under conditions that aren’t currently present on the live network. + */ stateOverride: StateOverride; } & UserOperationPaymasterOverrides >; @@ -393,7 +405,3 @@ export type UserOperationStruct = ? UserOperationStruct_v7 : never; //#endregion UserOperationStruct - -export type UserOperationStructUnion = - | UserOperationStruct_v6 - | UserOperationStruct_v7; diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index 05770239e9..7d9e9f3093 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -21,7 +21,7 @@ export default defineConfig({ items: [ { text: "Migrating to 3.x.x", - link: "/migration-guide", + link: "/migration-guides/migrating-to-v3", }, { text: "Changelog", diff --git a/site/.vitepress/sidebar/index.ts b/site/.vitepress/sidebar/index.ts index 99a9aaa0e5..0821e74409 100644 --- a/site/.vitepress/sidebar/index.ts +++ b/site/.vitepress/sidebar/index.ts @@ -26,6 +26,12 @@ export const sidebar: DefaultTheme.Sidebar = [ { text: "Send UserOperations", link: "/send-uos" }, ], }, + { + text: "Migration Guides", + collapsed: false, + base: "/migration-guides", + items: [{ text: "Migrating to v3.x.x", link: "/migrating-to-v3" }], + }, ], }, { diff --git a/site/migration-guide.md b/site/migration-guides/migrating-to-v3.md similarity index 90% rename from site/migration-guide.md rename to site/migration-guides/migrating-to-v3.md index bb834e359d..32531ca894 100644 --- a/site/migration-guide.md +++ b/site/migration-guides/migrating-to-v3.md @@ -3,19 +3,19 @@ outline: deep head: - - meta - property: og:title - content: Migration Guide + content: Migrating to aa-sdk v3 - - meta - name: description - content: How to upgrade through breaking changes of aa-sdk. + content: How to upgrade through breaking changes of aa-sdk v3 - - meta - property: og:description - content: How to upgrade through breaking changes of aa-sdk. + content: How to upgrade through breaking changes of aa-sdk v3. - - meta - name: twitter:title content: Migration Guide - - meta - name: twitter:description - content: How to upgrade through breaking changes of aa-sdk + content: How to upgrade through breaking changes of aa-sdk v3. --- # Migration Guide @@ -24,8 +24,7 @@ Below are the steps to migrate your project from older versions of the `aa-sdk` ## Migrating to version 3.x.x -This version update brings a lot of breaking changes. As we began to support Modular Accounts and their interfaces, we realized -that the previous version of the SDK was not as flexible as it could have been to handle the modularity of the new account interfaces. +This version update brings a lot of breaking changes. As we began to support Modular Accounts and their interfaces, we realized that the previous version of the SDK was not as flexible as it could have been to handle the modularity of the new account interfaces. To address this, version 3.x.x of the SDK switches to an approach more idiomatic to `viem`. ### Viem Version @@ -34,8 +33,7 @@ We have updated our dependency to viem v2.x.x. This means you will need to updat ### Client: `SmartAccountProvider` → `SmartAccountClient` -The biggest change is that the `SmartAccountProvider` class has been removed and replaced with a `SmartAccountClient` type that extends -`viem`'s [`Client`](https://viem.sh/docs/clients/custom). To get started with the new clients, you can do the following: +The biggest change is that the `SmartAccountProvider` class has been removed and replaced with a `SmartAccountClient` type that extends `viem`'s [`Client`](https://viem.sh/docs/clients/custom). To get started with the new clients, you can do the following: ```ts import { SmartAccountProvider } from "@alchemy/aa-core"; // [!code --] @@ -81,7 +79,7 @@ const client = createSmartAccountClient({ // [!code ++] ### Client: signature changes on methods -To support [the various ways](/migration-guide#account-connecting-to-a-smart-account) of connecting to a smart account, the signatures of the methods on `SmartAccountClient` have changed. Almost all methods now have an optional param for `account` and have been converted into single argument functions that take an object with the their properties instead. +To support [the various ways](/migration-guides/migrating-to-v3#account-connecting-to-a-smart-account) of connecting to a smart account, the signatures of the methods on `SmartAccountClient` have changed. Almost all methods now have an optional param for `account` and have been converted into single argument functions that take an object with the their properties instead. ### Account: `BaseSmartContractAccount` → `SmartContractAccount` @@ -113,8 +111,7 @@ const account = await createLightAccount({ // [!code ++] ### Account: Connecting to a Smart Account -In earlier versions, a provider could not be used with a smart account until it was connected to one using `.connect`. In version 3.x.x, -you have the option of keeping the two disconnected and passing the account to the client methods directly. You also have the option to hoist the account +In earlier versions, a provider could not be used with a smart account until it was connected to one using `.connect`. In version 3.x.x, you have the option of keeping the two disconnected and passing the account to the client methods directly. You also have the option to hoist the account so that you don't have to pass the account to every method. #### Option 1: Passing the Account to the Client Methods @@ -206,8 +203,7 @@ const { hash } = await smartAccountClient.sendUserOperation({ ### Account: Custom Accounts -In prior versions, using your own smart contract account implementations required that you extend `BaseSmartContractAccount`. In version 3.x.x, you can use the -`toSmartContractAccount` method which will allow you to use any account with `SmartAccountClient`. `toSmartContractAccount` has the form of: +In prior versions, using your own smart contract account implementations required that you extend `BaseSmartContractAccount`. In version 3.x.x, you can use the `toSmartContractAccount` method which will allow you to use any account with `SmartAccountClient`. `toSmartContractAccount` has the form of: ```ts type toSmartContractAccount = < diff --git a/site/packages/aa-core/bundler-client/actions/estimateUserOperationGas.md b/site/packages/aa-core/bundler-client/actions/estimateUserOperationGas.md index 4d9fcbb253..afd14cde66 100644 --- a/site/packages/aa-core/bundler-client/actions/estimateUserOperationGas.md +++ b/site/packages/aa-core/bundler-client/actions/estimateUserOperationGas.md @@ -14,7 +14,7 @@ head: # estimateUserOperationGas -Calls `eth_estimateUserOperationGas` and returns the result +Calls `eth_estimateUserOperationGas` and returns the result. ## Usage @@ -25,7 +25,8 @@ import { client } from "./client"; const estimates = await client.estimateUserOperationGas( { - // ... user operation + // ... user operation request with account dummySignature, + // initCode, encoded user operation call data, sender address, etc. }, "0xEntryPointAddress" ); @@ -38,14 +39,19 @@ const estimates = await client.estimateUserOperationGas( ### `Promise` -The result of the estimate including the `callGasLimit`, `verificationGasLimit`, `preVerificationGas`, and additionally, `paymasterVerificationGasLimit` for EntryPointVersion v0.7.0 user operations. +The result of the estimate including the `callGasLimit`, `verificationGasLimit`, `preVerificationGas`, and additionally, `paymasterVerificationGasLimit` for EntryPointVersion `v0.7.0` user operations. ## Parameters ### `request: UserOperationRequest` -The user operation to send +The user operation to estimate the gas for sending the user oepration. ### `entryPoint: Address` The address of the entry point to send the user operation to + +### `stateOverride?: StateOverride` + +A type defining state overrides for [`eth_call`](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#eth-call) method. An optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. +State overrides allow you to customize the network state for the purpose of the simulation, so this feature is useful when you need to estimate gas for user operation scenarios under conditions that aren’t currently present on the live network. diff --git a/site/packages/aa-core/smart-account-client/actions/buildUserOperation.md b/site/packages/aa-core/smart-account-client/actions/buildUserOperation.md index c8b27220e4..62e9deac97 100644 --- a/site/packages/aa-core/smart-account-client/actions/buildUserOperation.md +++ b/site/packages/aa-core/smart-account-client/actions/buildUserOperation.md @@ -16,13 +16,7 @@ head: Builds an _unsigned_ `UserOperation` (UO) struct with all middleware of the `SmartAccountClient` run through the middleware pipeline. -The order of the middlewares is: - -1. `dummyPaymasterDataMiddleware` -- populates a dummy paymaster data to use in estimation (default: "0x") -2. `feeDataGetter` -- sets maxfeePerGas and maxPriorityFeePerGas -3. `gasEstimator` -- calls eth_estimateUserOperationGas -4. `paymasterMiddleware` -- used to set paymasterAndData. (default: "0x") -5. `customMiddleware` -- allows you to override any of the results returned by previous middlewares +Learn more about [`ClientMiddleware`](/packages/aa-core/smart-account-client/middleware/index) to learn more about the internals of `SmartAccountClient` middleware pipeline that builds the user operation request given the user transaction call data and the operating account data. ## Usage @@ -95,24 +89,4 @@ const uoHash = await smartAccountClient.sendRawUserOperation({ A `Promise` containing the _unsigned_ UO struct resulting from the middleware pipeline -## Parameters - -### `SendUserOperationParameters` - -- `uo:` [`UserOperationCallData`](/resources/types#UserOperationCallData) | [`BatchUserOperationCallData`](/resources/types#BatchUserOperationCallData) - - ::: details UserOperationCallData - <<< @/../packages/core/src/types.ts#UserOperationCallData - ::: - - - `target: Address` - the target of the call (equivalent to `to` in a transaction) - - `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`](/resources/types#useroperationoverrides) - -Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit`, `paymasterAndData`, or `nonceKey` for the user operation request. You can also specify a `stateOverride` to be passed into `eth_estimateUserOperationGas` during fee estimation. - -- `account?: TAccount extends SmartContractAccount | undefined` - -When using this action, if the `SmartContractAccount` has not been connected to the `SmartAccountClient` (e.g. `SmartAccountClient` not instantiated with your `SmartContractAccount` during [`createSmartAccountClient`](/packages/aa-core/smart-account-client/)). You can check if the account is connected to the client by checking the `account` field of `SmartAccountClient`. If the account is not connected, you can specify the `SmartContractAccount` instance to use for the function call. + diff --git a/site/packages/aa-core/smart-account-client/actions/buildUserOperationFromTx.md b/site/packages/aa-core/smart-account-client/actions/buildUserOperationFromTx.md index f17c319a33..5db797e605 100644 --- a/site/packages/aa-core/smart-account-client/actions/buildUserOperationFromTx.md +++ b/site/packages/aa-core/smart-account-client/actions/buildUserOperationFromTx.md @@ -18,11 +18,11 @@ Converts a traditional Ethereum transaction and builds an _unsigned_ `UserOperat The order of the middlewares is: -1. `dummyPaymasterDataMiddleware` -- populates a dummy paymaster data to use in estimation (default: "0x") -2. `feeDataGetter` -- sets maxfeePerGas and maxPriorityFeePerGas -3. `gasEstimator` -- calls eth_estimateUserOperationGas -4. `paymasterMiddleware` -- used to set paymasterAndData. (default: "0x") -5. `customMiddleware` -- allows you to override any of the results returned by previous middlewares +1. `dummyPaymasterDataMiddleware` -- populates a dummy paymaster data to use in estimation (default: "0x") +2. `feeDataGetter` -- sets maxfeePerGas and maxPriorityFeePerGas +3. `gasEstimator` -- calls eth_estimateUserOperationGas +4. `paymasterMiddleware` -- used to set paymasterAndData. (default: "0x") +5. `customMiddleware` -- allows you to override any of the results returned by previous middlewares Note that `to`, `data`, `value`, `maxFeePerGas`, `maxPriorityFeePerGas` fields of the transaction request type are considered and used to build the user operation from the transaction, while other fields are not used. @@ -68,28 +68,4 @@ const uoHash = await smartAccountClient.sendRawUserOperation({ request, entryPoi A `Promise` containing the _unsigned_ UO struct converted from the input transaction with all the middleware run on the resulting UO -## Parameters - -### `args: SendTransactionParameters` - -::: details SendTransactionParameters - -```ts -export type SendTransactionParameters< - TChain extends Chain | undefined = Chain | undefined, - TAccount extends Account | undefined = Account | undefined, - TChainOverride extends Chain | undefined = Chain | undefined, - /// - derivedChain extends Chain | undefined = DeriveChain -> = UnionOmit, "from"> & - GetAccountParameter & - GetChainParameter; -``` - -::: - -The [`SendTransactionParameters`](https://github.com/wevm/viem/blob/6ef4ac131a878bf1dc4b335f5dc127e62618dda0/src/types/transaction.ts#L209) used as the parameter to the `WalletAction` [`sendTransaction`](https://viem.sh/docs/actions/wallet/sendTransaction) method representing a traditional ethereum transaction request. - -- `overrides?:` [`UserOperationOverrides`](/resources/types#useroperationoverrides) - -Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit`, `paymasterAndData`, or `nonceKey` for the user operation request + diff --git a/site/packages/aa-core/smart-account-client/actions/buildUserOperationFromTxs.md b/site/packages/aa-core/smart-account-client/actions/buildUserOperationFromTxs.md index 8395ec6b97..4e5566055d 100644 --- a/site/packages/aa-core/smart-account-client/actions/buildUserOperationFromTxs.md +++ b/site/packages/aa-core/smart-account-client/actions/buildUserOperationFromTxs.md @@ -14,19 +14,7 @@ head: # buildUserOperationFromTxs -Converts traditional Ethereum transactions in batch and builds an _unsigned_ `UserOperation` (UO) struct with all middleware of the `SmartAccountClient` run through the middleware pipeline. - -The order of the middlewares is: - -1. `dummyPaymasterDataMiddleware` -- populates a dummy paymaster data to use in estimation (default: "0x") -2. `feeDataGetter` -- sets maxfeePerGas and maxPriorityFeePerGas -3. `gasEstimator` -- calls eth_estimateUserOperationGas -4. `paymasterMiddleware` -- used to set paymasterAndData. (default: "0x") -5. `customMiddleware` -- allows you to override any of the results returned by previous middlewares - -**NOTE**: Not all Smart Contract Accounts support batching. The `SmartContractAccount` implementation must implement the encodeBatchExecute method for the `SmartAccountClient` to execute the batched user operation successfully. - -Note that `to`, `data`, `value`, `maxFeePerGas`, `maxPriorityFeePerGas` fields of the transaction request type are considered and used to build the user operation from the transaction, while other fields are not used. +Performs [`buildUserOperationFromTx`](./buildUserOperationFromTx.md) in batch and builds into a single, yet to be signed `UserOperation` (UO) struct. The output user operation struct will be filled with all gas fields (and paymaster data if a paymaster is used) based on the transactions data (`to`, `data`, `value`, `maxFeePerGas`, `maxPriorityFeePerGas`) computed using the configured [`ClientMiddlewares`](/packages/aa-core/smart-account-client/middleware/index) on the `SmartAccountClient` ## Usage diff --git a/site/packages/aa-core/smart-account-client/actions/checkGasSponsorshipEligibility.md b/site/packages/aa-core/smart-account-client/actions/checkGasSponsorshipEligibility.md index 5a9eeb1437..fbe17891c7 100644 --- a/site/packages/aa-core/smart-account-client/actions/checkGasSponsorshipEligibility.md +++ b/site/packages/aa-core/smart-account-client/actions/checkGasSponsorshipEligibility.md @@ -53,24 +53,4 @@ console.log( A `Promise` containing the boolean value indicating whether the UO to be sent is eligible for gas sponsorship or not. -## Parameters - -### `SendUserOperationParameters` - -- `uo:` [`UserOperationCallData`](/resources/types#UserOperationCallData) | [`BatchUserOperationCallData`](/resources/types#BatchUserOperationCallData) - - ::: details UserOperationCallData - <<< @/../packages/core/src/types.ts#UserOperationCallData - ::: - - - `target: Address` - the target of the call (equivalent to `to` in a transaction) - - `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`](/resources/types#useroperationoverrides) - -Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit`, `paymasterAndData`, or `nonceKey` for the user operation request - -- `account?: TAccount extends SmartContractAccount | undefined` - -When using this action, if the `SmartContractAccount` has not been connected to the `SmartAccountClient` (e.g. `SmartAccountClient` not instantiated with your `SmartContractAccount` during [`createSmartAccountClient`](/packages/aa-core/smart-account-client/)). You can check if the account is connected to the client by checking the `account` field of `SmartAccountClient`. If the account is not connected, you can specify the `SmartContractAccount` instance to use for the function call. + diff --git a/site/packages/aa-core/smart-account-client/actions/sendTransaction.md b/site/packages/aa-core/smart-account-client/actions/sendTransaction.md index 9c95ec7150..ccc8750380 100644 --- a/site/packages/aa-core/smart-account-client/actions/sendTransaction.md +++ b/site/packages/aa-core/smart-account-client/actions/sendTransaction.md @@ -49,28 +49,4 @@ const txHash = await smartAccountClient.sendTransaction(tx); A `Promise` containing the transaction hash -## Parameters - -### `args: SendTransactionParameters` - -::: details SendTransactionParameters - -```ts -export type SendTransactionParameters< - TChain extends Chain | undefined = Chain | undefined, - TAccount extends Account | undefined = Account | undefined, - TChainOverride extends Chain | undefined = Chain | undefined, - /// - derivedChain extends Chain | undefined = DeriveChain -> = UnionOmit, "from"> & - GetAccountParameter & - GetChainParameter; -``` - -::: - -The [`SendTransactionParameters`](https://github.com/wevm/viem/blob/6ef4ac131a878bf1dc4b335f5dc127e62618dda0/src/types/transaction.ts#L209) used as the parameter to the `WalletAction` [`sendTransaction`](https://viem.sh/docs/actions/wallet/sendTransaction) method representing a traditional ethereum transaction request. - -- `overrides?:` [`UserOperationOverrides`](/resources/types#useroperationoverrides) - -Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit`, `paymasterAndData`, or `nonceKey` for the user operation request + diff --git a/site/packages/aa-core/smart-account-client/actions/sendUserOperation.md b/site/packages/aa-core/smart-account-client/actions/sendUserOperation.md index dd240439a5..e98a5256d4 100644 --- a/site/packages/aa-core/smart-account-client/actions/sendUserOperation.md +++ b/site/packages/aa-core/smart-account-client/actions/sendUserOperation.md @@ -18,11 +18,11 @@ Sends a user operation or batch of user operations using the connected account. Before executing, sendUserOperation will run the user operation through the middleware pipeline. The order of the middlewares is: -1. `dummyPaymasterDataMiddleware` -- populates a dummy paymaster data to use in estimation (default: "0x") -2. `feeDataGetter` -- sets maxfeePerGas and maxPriorityFeePerGas -3. `gasEstimator` -- calls eth_estimateUserOperationGas -4. `paymasterMiddleware` -- used to set paymasterAndData. (default: "0x") -5. `customMiddleware` -- allows you to override any of the results returned by previous middlewares +1. `dummyPaymasterDataMiddleware` -- populates a dummy paymaster data to use in estimation (default: "0x") +2. `feeDataGetter` -- sets maxfeePerGas and maxPriorityFeePerGas +3. `gasEstimator` -- calls eth_estimateUserOperationGas +4. `paymasterMiddleware` -- used to set paymasterAndData. (default: "0x") +5. `customMiddleware` -- allows you to override any of the results returned by previous middlewares ## Usage @@ -71,26 +71,4 @@ A `Promise` containing the hash of the user operation and the request that was s **Note**: The hash is not the User Operation Receipt. The user operation still needs to be bundled and included in a block. The user operation result is more of a proof of submission than a receipt. -## Parameters - -## Parameters - -### `SendUserOperationParameters` - -- `uo:` [`UserOperationCallData`](/resources/types#UserOperationCallData) | [`BatchUserOperationCallData`](/resources/types#BatchUserOperationCallData) - - ::: details UserOperationCallData - <<< @/../packages/core/src/types.ts#UserOperationCallData - ::: - - - `target: Address` - the target of the call (equivalent to `to` in a transaction) - - `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`](/resources/types#useroperationoverrides) - -Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit`, `paymasterAndData`, or `nonceKey` for the user operation request - -- `account?: TAccount extends SmartContractAccount | undefined` - -When using this action, if the `SmartContractAccount` has not been connected to the `SmartAccountClient` (e.g. `SmartAccountClient` not instantiated with your `SmartContractAccount` during [`createSmartAccountClient`](/packages/aa-core/smart-account-client/)). You can check if the account is connected to the client by checking the `account` field of `SmartAccountClient`. If the account is not connected, you can specify the `SmartContractAccount` instance to use for the function call. + diff --git a/site/packages/aa-core/smart-account-client/actions/upgradeAccount.md b/site/packages/aa-core/smart-account-client/actions/upgradeAccount.md index 04d37f9bde..7398cea112 100644 --- a/site/packages/aa-core/smart-account-client/actions/upgradeAccount.md +++ b/site/packages/aa-core/smart-account-client/actions/upgradeAccount.md @@ -68,7 +68,7 @@ The [`SmartContractClient`](/packages/aa-core/smart-account-client/) instance - `overrides?:` [`UserOperationOverrides`](/resources/types#useroperationoverrides) -Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit`, `paymasterAndData`, or `nonceKey` for the user operation request +Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit`, `paymasterAndData`, or `nonceKey` for the user operation request. You can also specify a `stateOverride` to be passed into `eth_estimateUserOperationGas` during fee estimation. - `waitForTx?: boolean` diff --git a/site/packages/aa-core/smart-account-client/middleware/index.md b/site/packages/aa-core/smart-account-client/middleware/index.md index 10c4aaa517..887bdf8d53 100644 --- a/site/packages/aa-core/smart-account-client/middleware/index.md +++ b/site/packages/aa-core/smart-account-client/middleware/index.md @@ -37,6 +37,8 @@ export type ClientMiddleware = { }; ``` +## Types of ClientMiddlewares + ### feeEstimator `feeEstimator` middleware is responsible for computing `maxFeePerGas` and `maxPriorityFeePerGas` fields of [EIP-4337](https://eips.ethereum.org/EIPS/eip-4337#specification) user operation. @@ -57,9 +59,19 @@ This is a no-op middleware, but you can include any custom step during the user If you are simulating a user operation using [`simulateUserOperation`](/packages/aa-alchemy/smart-account-client/actions/simulateUserOperation.md), `SmartAccountClient` will include `userOperationSimulator` middleware during the pipeline run to simulate the user operation instead of sending it to the network to be mined. -## Use custom middleware using `ClientMiddlewareConfig` in `SmartAccountClientConfig` +During the `SmartAccountClient` middleware pipeline run, each middleware is applied to compute certain fields of the [`UserOperationStruct`](/resources/types#useroperationstruct) in the following sequential order: + +1. `dummyPaymasterDataMiddleware` -- populates a dummy paymaster data to use in estimation (default: `0x` for no paymater) +2. `feeEstimator` -- sets maxfeePerGas and maxPriorityFeePerGas +3. `gasEstimator` -- calls eth_estimateUserOperationGas +4. `customMiddleware` -- default no-op middleware, available for any custom operation to be done in addition and override any of the results returned by previous middlewares +5. `paymasterMiddleware` -- used to set paymaster fields of a user operation. (default: `0x` for no paymater) +6. `userOperationSimulator` -- used for the simulation of a user operation instead of sending it to the network to be mined. +7. `signUserOperation` -- used for the signing the built, but yet to be signed, user operation after all other middlewares are run. Note that `signUserOperation` middleware run is decoupled from the other middlewares pipeline run for building the user operation. Rather, the user operation is signed right before the client sends the user operation to the network. + +## Overriding default middlewares with your own -For each middleware, a default exists that `SmartAccountClient` uses. Still, these defaults can be overridden flexibly with your custom middleware function upon the creation of the client by using `ClientMiddlewareConfig` included in `SmartAccountClientConfig` used as `createSmartAccountClient()` method to create the client. Below is an example of how you can use your version of the gas estimator if you opt out of using the default gas estimator. +For each middleware, a default middleware is available for the `SmartAccountClient`, which computes user operation fields based on the user input of operation call data. If you are looking to customize certain behaviors of user operation struct construction for your client, you can flexibly override with your own middleware specifying in the [`ClientMiddlewareConfig`](/resources/types.md#clientmiddlewareconfig) during the `SmartAccountClient` instantiation. For example, the following illustrates how you can override the default gas estimation behavior by overriding the default gas estimator with your own. ```ts export type ClientMiddlewareConfig = Omit< diff --git a/site/resources/terms.md b/site/resources/terms.md index b6ec5ad1b2..951d175b9c 100644 --- a/site/resources/terms.md +++ b/site/resources/terms.md @@ -38,7 +38,7 @@ A standardized smart contract that acts as the primary gateway for processing `U ## ERC-4337 -A standard authored by the [Ethereum Foundation](https://ethereum.foundation/) for [account abstraction](https://docs.alchemy.com/docs/introduction-to-account-abstraction), establishing a uniform interface for all smart accounts. This standard also outlines the roles and functionalities of [Bundlers](https://docs.alchemy.com/docs/bundler-services), [Paymasters](https://www.alchemy.com/overviews/what-is-a-paymaster), and [`EntryPoint`](#entrypoint). Reference: https://eips.ethereum.org/EIPS/eip-4337 +A standard authored by the [Ethereum Foundation](https://ethereum.foundation/) for [account abstraction](https://docs.alchemy.com/docs/introduction-to-account-abstraction), establishing a uniform interface for all smart accounts. This standard also outlines the roles and functionalities of [Bundlers](https://docs.alchemy.com/docs/bundler-services), [Paymasters](https://www.alchemy.com/overviews/what-is-a-paymaster), and [`EntryPoint`](#entrypoint). Reference: ## ERC-6492 @@ -95,7 +95,7 @@ A [Smart Contract Account (SCA)](https://accountkit.alchemy.com/smart-accounts/. `Transactions` in blockchain are cryptographically signed data messages that contain a set of instructions. These instructions can be interpreted to send native tokens from one account to another or interact with a smart contract deployed on the blockchain. A `Transaction` usually consists of the following parameters: `nonce`, `gasPrice`, `gasLimit`, `to`, `value`, `data`, `v`, `r`, `s`. Ethereum and other EVM blockchains have evolved to allow other transaction standards such as [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), to allow more predictable gas fees and a more efficient transaction market. -# Transaction Calldata +## Transaction Calldata Transaction `calldata` refers to the data passed along with a transaction that allows accounts to send messages to other entities or interact with smart contracts. When calling smart contracts on-chain (either from an `EOA` or another contract), the `calldata` is the encoded data within the `Transaction` containing the input parameters (or arguments) of the function being called on the contract. diff --git a/site/resources/types.md b/site/resources/types.md index 96d10e00b6..8c0a62aa09 100644 --- a/site/resources/types.md +++ b/site/resources/types.md @@ -68,6 +68,14 @@ Middleware represents different operations involved in the [`SmartAccountClient` <<< @/../packages/core/src/middleware/types.ts#ClientMiddleware ::: +## `ClientMiddlewareConfig` + +Configuration object to configure `ClientMiddleware` of the [`SmartAccountClient`](/packages/aa-core/smart-account-client/) during the client instantiation. You can configure using this object to configure the middleware of your interest selectively. + +::: details ClientMiddlewareFn +<<< @/../packages/core/src/client/types.ts#ClientMiddlewareConfig +::: + ## `ClientMiddlewareFn` Each middleware is a function that takes in a user operation object, `UserOperationStruct`, performs its job to retrieve or compute the data, and populate different fields of the user operation to pass onto the next middleware in the pipeline before being signed and sent to the network. `ClientMiddlewareFn` is the function type that represents each middleware. In optional [`UserOperationOverrides`](#useroperationoverrides), and [`UserOperationFeeOptions`](/packages/aa-core/smart-account-client/types/userOperationFeeOptions), and returns a promise that resolves to a modified `UserOperationStruct`. This function is what you specify as your overridden middleware value for applying custom logic during the `UserOperationStruct` object to be sent to the bundler for on-chain execution. @@ -76,9 +84,17 @@ Each middleware is a function that takes in a user operation object, `UserOperat <<< @/../packages/core/src/middleware/types.ts#ClientMiddlewareFn ::: +## `EntryPointDef` + +An object type that defines the interface for `EntryPoint` functions for packing the user operation to the optimized data structure to enhance performance and reduce gas costs of transactions, and generating the hash of the user operation for the format compatible to the specified `Chain` and `EntryPointVersion`. + +::: details EntryPointDef +<<< @/../packages/core/src/entrypoint/types.ts#EntryPointDef +::: + ## `Multiplier` -An object type with a required `multipler` field, which is a `number` that must be within the range of 1 to 1000. +An object type with a required `multipler` field, which is a `number` value with max precision of 4 decmial places. ::: details Multiplier <<< @/../packages/core/src/utils/schema.ts#Multiplier @@ -94,7 +110,7 @@ An extension of the [`SmartAccountSigner`](#smartaccountsigner) interface, this ## `SmartAccountClient` -`SmartAccountClient` is a custom `viem` `Client`, like the [`BundlerClient`](#bundlerclient), which is an intermediary or connector that enables your client application to interact with the `SmartContractAccount`. `SmartAccountClient` is analogous to the [`WalletClient`](https://viem.sh/docs/clients/wallet). The difference is that while `WalletClient` has [`WalletActions`](https://viem.sh/docs/actions/wallet/introduction) that lets your client application interact with an [Externally-owned account (EOA)](https://ethereum.org/developers/docs/accounts) with a [wallet](#wallet), `SmartAccountClient` provides [`SmartAccountClientActions`](#smartaccountclientaction) for client applications to interact with `SmartContractAccounts`. +`SmartAccountClient` is a custom `viem` `Client`, like the [`BundlerClient`](#bundlerclient), which is an intermediary or connector that enables your client application to interact with the `SmartContractAccount`. `SmartAccountClient` is analogous to the [`WalletClient`](https://viem.sh/docs/clients/wallet). The difference is that while `WalletClient` has [`WalletActions`](https://viem.sh/docs/actions/wallet/introduction) that lets your client application interact with an [Externally-owned account (EOA)](https://ethereum.org/developers/docs/accounts) with a [wallet](./terms#wallet), `SmartAccountClient` provides [`SmartAccountClientActions`](#smartaccountclientaction) for client applications to interact with `SmartContractAccounts`. ::: details SmartAccountClient <<< @/../packages/core/src/client/smartAccountClient.ts#SmartAccountClient @@ -118,12 +134,25 @@ An interface representing a signer capable of signing messages and typed data. I ## `SmartContractAccount` -As smart contract accounts are essentially the contract codes that operate on the blockchain, `SmartContractAccount` defines the interface with different functionalities for managing and interacting with the contract account. It includes different functionalities for creating, managing, and using your smart account. In addition to supporting all functionalities achieved with a basic [EOA](./terms#wallet) alone, `SmartContractAccount` can have custom capabilities such as automating processes or executing actions based on predefined conditions. Smart contract wallets allow users to customize how they manage their digital assets, offering a more tailored approach to handling funds securely. +As smart contract accounts are essentially the contract codes that operate on the blockchain, `SmartContractAccount` defines the interface with different functionalities for managing and interacting with the contract account. It includes different functionalities for creating, managing, and using your smart account. In addition to supporting all functionalities achieved with a basic [EOA](./terms#wallet) alone, `SmartContractAccount` can have custom capabilities such as automating processes or executing actions based on predefined conditions. Smart contract wallets allow users to customize how they manage their digital assets, offering a more tailored approach to handling funds securely. `SmartContractAccount` type extends `viem`'s [`Account`](https://viem.sh/docs/accounts/custom), and instantiation of an account is done using the [`toSmartContractAccount`](/packages/aa-core/accounts/) action. ::: details SmartContractAccount <<< @/../packages/core/src/account/smartContractAccount.ts#SmartContractAccount ::: +## `StateOverride` + +A type defining state overrides for [`eth_call`](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#eth-call) method. An optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. +State overrides allow you to customize the network state for the purpose of the simulation, so this feature is useful when you need to test or simulate scenarios under conditions that aren’t currently present on the live network. + +## `ToSmartContractAccountParams` + +This type defines the parameters to the `SmartContractAccount` instantiation action, [`toSmartContractAccount`](/packages/aa-core/accounts/). You can configure this parameter to specify the [`Transport`](https://viem.sh/docs/clients/intro.html#transports), [`Chain`](https://viem.sh/docs/glossary/types#chain), [`EntryPointDef`](#entrypointdef), and other base functionalities of the smart account that you are creating. + +::: details ToSmartContractAccountParams +<<< @/../packages/core/src/account/smartContractAccount.ts#ToSmartContractAccountParams +::: + ## `User` `User` is a type that defines the model for the details of a user's Embedded Account via an Alchemy Signer. It includes the user's `email`, `orgId`, `userId`, `userId`, `address` (the EOA signer address corresponding to the user credentials), and `credentialId`. You can use the [`useUser`](../react/useUser.md) react hook to look up a user. @@ -140,7 +169,7 @@ As smart contract accounts are essentially the contract codes that operate on th <<< @/../packages/core/src/types.ts#UserOperationCallData ::: -## `UserOperationEstimateGasResponse` +## `UserOperationEstimateGasResponse` An interface that defines the structure for the response received from the RPC method [`eth_estimateUserOperationGas`](https://docs.alchemy.com/reference/eth-estimateuseroperationgas). This response provides detailed information about the estimated gas usage for a `UserOperation`. diff --git a/site/snippets/aa-core/send-tx-param.md b/site/snippets/aa-core/send-tx-param.md index acc465ed69..cec74757e9 100644 --- a/site/snippets/aa-core/send-tx-param.md +++ b/site/snippets/aa-core/send-tx-param.md @@ -1,3 +1,9 @@ +## Parameters + +### `SendTransactionParameters` + +Same as `viem` [`TransactionRequest`](https://viem.sh/docs/glossary/types#transactionrequest), but with the `from` field excluded + ```ts export type SendTransactionParameters< TChain extends Chain | undefined = Chain | undefined, @@ -10,12 +16,6 @@ export type SendTransactionParameters< GetChainParameter; ``` -## Parameters - -### `SendTransactionParameters` - -Same as `viem` [`TransactionRequest`](https://viem.sh/docs/glossary/types#transactionrequest), but with the `from` field excluded - - `overrides?:` [`UserOperationOverrides`](/resources/types#useroperationoverrides) Optional parameter where you can specify override values for `maxFeePerGas`, `maxPriorityFeePerGas`, `callGasLimit`, `preVerificationGas`, `verificationGasLimit`, `paymasterAndData`, or `nonceKey` for the user operation request. You can also specify a `stateOverride` to be passed into `eth_estimateUserOperationGas` during fee estimation. diff --git a/site/snippets/aa-core/send-uo-param.md b/site/snippets/aa-core/send-uo-param.md index f7cca3d798..6b21f47af5 100644 --- a/site/snippets/aa-core/send-uo-param.md +++ b/site/snippets/aa-core/send-uo-param.md @@ -1,17 +1,16 @@ -```ts -export type SendUserOperationParameters< - TAccount extends SmartContractAccount | undefined -> = { - uo: UserOperationCallData | BatchUserOperationCallData; - overrides?: UserOperationOverrides; -} & GetAccountParameter; -``` - ## Parameters -### [`SendUserOperationParameters`](/resources/types#SendUserOperationParameters) +### `SendUserOperationParameters` + +::: details SendUserOperationParameters +<<< @/../packages/core/src/actions/smartAccount/types.ts#SendUserOperationParameters +::: + +- `uo:` [`UserOperationCallData`](/resources/types#UserOperationCallData) | [`BatchUserOperationCallData`](/resources/types#BatchUserOperationCallData) -- `uo:` [`UserOperationCallData`](/resources/types#SendUserOperationParameters) | [`BatchUserOperationCallData`](/resources/types#SendUserOperationParameters) + ::: details UserOperationCallData + <<< @/../packages/core/src/types.ts#UserOperationCallData + ::: - `target: Address` - the target of the call (equivalent to `to` in a transaction) - `data: Hex` - can be either `0x` or a call data string