From 1d3f389cdfa70ffa03ec74b18068aa1ee03edda3 Mon Sep 17 00:00:00 2001 From: Dennis Won Date: Thu, 18 Apr 2024 10:25:31 -0700 Subject: [PATCH] docs: entrypoint v.7 docs --- .../core/src/account/smartContractAccount.ts | 4 + packages/core/src/entrypoint/types.ts | 2 + site/.vitepress/config.ts | 2 +- site/.vitepress/sidebar/index.ts | 12 + site/migration-guides/entrypoint-v7.md | 255 ++++++++++++++++++ .../migrating-to-v3.md} | 10 +- site/resources/errors.md | 0 site/resources/types.md | 32 ++- site/smart-accounts/entrypoint-support.md | 25 ++ .../entrypoint-v7-how-to-estimate-gas.md | 0 10 files changed, 334 insertions(+), 8 deletions(-) create mode 100644 site/migration-guides/entrypoint-v7.md rename site/{migration-guide.md => migration-guides/migrating-to-v3.md} (95%) create mode 100644 site/resources/errors.md create mode 100644 site/smart-accounts/entrypoint-support.md create mode 100644 site/using-smart-accounts/entrypoint-v7-how-to-estimate-gas.md 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/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/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..e08c5ee884 100644 --- a/site/.vitepress/sidebar/index.ts +++ b/site/.vitepress/sidebar/index.ts @@ -26,6 +26,18 @@ export const sidebar: DefaultTheme.Sidebar = [ { text: "Send UserOperations", link: "/send-uos" }, ], }, + { + text: "Migration Guides", + collapsed: false, + base: "/migration-guides", + items: [ + { text: "Introduction", link: "/migrating-to-v3" }, + { + text: "Entrypoint v0.7.0", + link: "/entrypoint-v7", + }, + ], + }, ], }, { diff --git a/site/migration-guides/entrypoint-v7.md b/site/migration-guides/entrypoint-v7.md new file mode 100644 index 0000000000..cdad8fd1d0 --- /dev/null +++ b/site/migration-guides/entrypoint-v7.md @@ -0,0 +1,255 @@ +--- +outline: deep +head: + - - meta + - property: og:title + content: Migration Guide + - - meta + - name: description + content: How to update from Entrypoint v0.6 to v0.7. + - - meta + - property: og:description + content: How to update from Entrypoint v0.6 to v0.7. + - - meta + - name: twitter:title + content: Migration Guide + - - meta + - name: twitter:description + content: How to update from Entrypoint v0.6 to v0.7. +--- + +# Entrypoint v0.7 Update Guide + +## Entrypoint v0.7: A Milestone in Account Abstraction + +Version 0.7, the latest advancement, brings significant updates and optimizations driven by community feedback and evolving needs: + +Optimized Gas Management: Making transactions more cost-effective. +Advanced Security: Introducing stringent security measures for better account and transaction protection. +Enhanced Developer Tools: Offering improved resources for creating AA-enabled dApps. +With upgrade made for `aa-sdk` version `v3.8.4`, `aa-sdk` now supports both EntryPoint v0.6.0 and v.0.7.0 contract for different smart accounts. + +Below are the steps to update your project from using Entrypoint v0.6.0 to v0.7.0 of the `aa-sdk`. + +::: tip Note +This migration guide is assuming you are currently using the `aa-sdk` version `^3.x.x` to version `^3.8.4`. If you are looking to upgrade from the older versions of `aa-sdk`, you can follow the [Migration Guide](./migrating-to-v3.md) for `aa-sdk` version `3.x.x`. +::: + +Upgrading to the latest version `v3.8.4` of `aa-sdk` will **not** involve breaking changes if you continue to stay on using Entrypoint v0.6.0 for your smart accounts. If you are looking into update to using Entrypoint v0.7.0, it simply requires passing in the optional entrypoint version parameter as `0.7.0` to your `SmartContractAccounts`. Otherwise, the default Entrypoint version is `0.6.0` for the initial launch of Entrypoint v0.7 support in `aa-sdk` version `^3.x.x`. + +### Account Support + +Because [Entrypoint](https://eips.ethereum.org/EIPS/eip-4337#definitions) is a singleton contract, where there is only one implementation and one instance exists on each chain, you first need to make sure the smart account and the bundler you are using is updated with a certain Entrypoint version. + +From version `^3.8.4`, `aa-sdk` lets you easily configure which Entrypoint version compatible Smart Account to use. `aa-sdk` supports 4 types of accounts natively, and the below table details which EntryPoints each account is valid for. + +| Account | EntryPoint v0.7 | EntryPoint v0.6 | +| :---------------------------- | :-------------- | :-------------- | +| SimpleAccount | ✅ | ✅ | +| LightAccount v1 (_< v.2.0.0_) | ❌ | ✅ | +| LightAccount v2 (_>= v2.0.0_) | ✅ | ❌ | +| MultiOwnerLightAccount | ✅ | ❌ | +| MultiOwnerModularAccount | ❌ | ✅ | +| MultisigModularAccount | ❌ | ✅ | + +### Account: [`ToSmartContractAccountParams`](/resources/types#ToSmartContractAccountParams)'s optional `entryPoint` parameter + +The only change that needs to be made to update to using Entrypoint v.7 is to specify the optional `entryPoint` parameter of the [`ToSmartContractAccountParams`](/resources/types#ToSmartContractAccountParams) used for the [`toSmartContractAccount`](/packages/aa-core/accounts/) function when instantiating a `SmartContractAccount`. Based on the `entryPoint` parameter, which is of type [`EntryPointDef`](/resources/types#EntryPointDef) of the specific `EntryPointVersion`, the output `SmartContractAccount` will be strongly-typed with the structure compatible to perform the desired `EntryPointVersion` user operations. Using `SimpleAccount` as an example, you will have to make the following changes: + +```ts +import { createSimpleAccount } from "@alchemy/aa-core"; +import { LocalAccountSigner, type Hex } from "@alchemy/aa-core"; +import { sepolia } from "@alchemy/aa-core"; + +const chain = sepolia; + +const account = await createSimpleAccount({ + transport: http("RPC_URL"), + signer, + chain, + entryPoint: getEntryPoint(chain, { version: "0.7.0" }), // [!code ++] +}); +``` + +### Client: signature changes on methods + +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: 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 +so that you don't have to pass the account to every method. + +#### Option 1: Passing the Account to the Client Methods + +```ts +import { createLightAccount } from "@alchemy/aa-accounts"; +import { + createBundlerClient, + createSmartAccountClientFromExisting + LocalAccountSigner, + type Hex, +} from "@alchemy/aa-core"; +import { sepolia } from "@alchemy/aa-core"; +import { custom, http } from "viem"; + +const chain = sepolia; + +const client = createBundlerClient({ + chain, + transport: http("JSON_RPC_URL"), +}); + +// [!code focus:99] +// createSmartAccountClientFromExisting is a helper method that allows you +// to reuse a JSON RPC client to create a Smart Account client. +const smartAccountClient = createSmartAccountClientFromExisting({ + client, +}); + +const account = await createLightAccount({ + signer, + chain, + transport: custom(client), +}); + +const { hash } = await smartAccountClient.sendUserOperation({ + uo: { + target: "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef", + data: "0x", + value: 10n, + }, + account, // [!code ++] +}); +``` + +#### Option 2: Hoisting the Account + +Hoisting the account is similar to using `.connect` in previous versions. You simply create your client with an account passed in to it. + +```ts +import { createLightAccount } from "@alchemy/aa-accounts"; +import { + createBundlerClient, + createSmartAccountClientFromExisting + LocalAccountSigner, + type Hex, +} from "@alchemy/aa-core"; +import { sepolia } from "@alchemy/aa-core"; +import { http, custom } from "viem"; + +const chain = sepolia; + +const client = createBundlerClient({ + chain, + transport: http("JSON_RPC_URL"), +}); + +// [!code focus:99] +const account = await createLightAccount({ + signer, + transport: custom(client), + chain, +}); + +const smartAccountClient = createSmartAccountClientFromExisting({ + account, // [!code ++] + client, +}); + +const { hash } = await smartAccountClient.sendUserOperation({ + uo: { + target: "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef", + data: "0x", + value: 10n, + }, + account, // [!code --] +}); +``` + +### 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: + +```ts +type toSmartContractAccount = < + Name extends string = string, + TTransport extends Transport = Transport +>({ + transport, + chain, + source, + entryPointAddress, + accountAddress, + getAccountInitCode, + signMessage, + signTypedData, + encodeBatchExecute, + encodeExecute, + getDummySignature, + signUserOperationHash, + encodeUpgradeToAndCall, +}: ToSmartContractAccountParams) => Promise< + SmartContractAccount +>; +``` + +### Account: SimpleAccount and NaniAccount initialization params + +`chain` and `transport` have been added to the constructor and `rpcClient` has been removed. + +### Account: SimpleAccount and LightAccount intialization params + +`index` is now called `salt` + +### Signer: `signTypedData` signature change + +The `signTypedData` method found on `SmartAccountSigner` has been updated to match the signature found on `SmartContractAccount` and viem's `Account`. + +```ts +signTypedData: (params: SignTypedDataParams) => Promise; // [!code --] + +signTypedData: < + const TTypedData extends TypedData | { [key: string]: unknown }, + TPrimaryType extends string = string +>( + params: TypedDataDefinition +) => Promise; +``` + +### Ethers: Removed methods + +The `with*` methods have been removed from the Provider and Signer classes. +The `connect` methods has been removed in favor of immutable properties on the Provider and Signer classes. See updated AccountSigner constructor below. + +### Ethers: `getPublicErc4337Client` → `getBundlerClient` + +The `getPublicErc4337Client` method has been renamed to `getBundlerClient` to match the naming found in `aa-core`. + +### Ethers: Updated Signer Adapter constructor + +The `AccountSigner` now takes in a `SmartContractAccount` as a param in its constructor. + +### Core: Transition from ~~`Percent`~~ to `Multiplier` api and types + +The `Percent` type and `PercentSchema` have been removed in favor of the `Multiplier` type and `MultiplierSchema`. + +Going forward when using the feeOptions, you can specify the `Multiplier` type instead of a `Percent`. The `Multiplier` type is a number that represents direct multipliaction of the estimation. For example, `0.1` is 10% of the estimated value and `1` is 100% of the estimated value. + +```ts +createModularAccountAlchemyClient({ + ... + opts: { + ... + // The maxFeePerGas and maxPriorityFeePerGas estimated values will now be multipled by 1.5 + feeOptions: { + // This was previously { percent: 50n } + maxFeePerGas: { multiplier: 1.5 }, + // This was previously { percent: 25n } + maxPriorityFeePerGas: { multiplier: 1.25 }, + }, + }, + }); +``` diff --git a/site/migration-guide.md b/site/migration-guides/migrating-to-v3.md similarity index 95% rename from site/migration-guide.md rename to site/migration-guides/migrating-to-v3.md index bb834e359d..1741698e52 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 @@ -81,7 +81,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` diff --git a/site/resources/errors.md b/site/resources/errors.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/site/resources/types.md b/site/resources/types.md index 96d10e00b6..889126b92b 100644 --- a/site/resources/types.md +++ b/site/resources/types.md @@ -76,9 +76,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 @@ -118,12 +126,32 @@ 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 ::: +## `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`](``), +chain, +entryPoint, +source, +accountAddress, +getAccountInitCode, +signMessage, +signTypedData, +encodeBatchExecute, +encodeExecute, +getDummySignature, +signUserOperationHash, +encodeUpgradeToAndCall, + +::: 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. diff --git a/site/smart-accounts/entrypoint-support.md b/site/smart-accounts/entrypoint-support.md new file mode 100644 index 0000000000..c13f761940 --- /dev/null +++ b/site/smart-accounts/entrypoint-support.md @@ -0,0 +1,25 @@ +--- +outline: deep +head: + - - meta + - property: og:title + content: Entrypoint Support + - - meta + - name: description + content: Entrypoint Support for Alchemy Accounts + - - meta + - property: og:description + content: Entrypoint Support for Alchemy Accounts +--- + +# Entrypoint Support + +`aa-sdk` supports 4 types of accounts natively (but can easily be extended to support any compatible [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) or [ERC-6900](https://eips.ethereum.org/EIPS/eip-6900) account). The below table details which EntryPoints each account is valid for. + +| Account | EntryPoint v0.7 | EntryPoint v0.6 | +| :----------------------- | :--------------- | :--------------- | +| SimpleAccount | ✅ | ✅ | +| LightAccount | ✅ (_>= v2.0.0_) | ✅ (_< v.2.0.0_) | +| MultiOwnerLightAccount | ✅ | ❌ | +| MultiOwnerModularAccount | ❌ | ✅ | +| MultisigModularAccount | ❌ | ✅ | diff --git a/site/using-smart-accounts/entrypoint-v7-how-to-estimate-gas.md b/site/using-smart-accounts/entrypoint-v7-how-to-estimate-gas.md new file mode 100644 index 0000000000..e69de29bb2