Migration Guide

Below are the steps to migrate your project from older versions of the aa-sdk and account-kit to the latest version.

Migrating to Version V4.X.X

Packages

All of the v3 packages have been renamed or removed. The new packages are as follows:

• @alchemy/aa-core -> @aa-sdk/core
• @alchemy/aa-ethers -> @aa-sdk/ethers
• @alchemy/aa-alchemy -> split into @account-kit/signer, @account-kit/infra, @account-kit/core, @account-kit/react
• @alchemy/aa-accounts -> @account-kit/smart-contracts
• @alchemy/aa-signers -> removed

Smart Account Signers

The @alchemy/aa-signers package has been deprecated. The signers in that package are still compatible with v4, but they will not be receiving future support and the interfaces are not guaranteed to work with future versions of the SDK. If you want to integrate a 3rd party signer, it’s still very easy if the signer exposes an EIP-1193 interface. See this guide.

Alchemy Transport

The new Transport type: AlchemyTransport has been added. This impacts how Alchemy clients, middleware, and configs are created.

For Smart Account Clients, the create*AlchemyClient methods have been updated to take a new transport property (of type AlchemyTransport) instead of rpcUrl or apiKey directly.

The alchemyFeeEstimator and alchemyUserOperationSimulator middleware methods now no longer take in a ClientWithAlchemyMethods (returned by createAlchemyPublicRpcClient) and instead take in an AlchemyTransport as well.

The AlchemyTransport is a type of viem transport that makes it easier to configure your communication with Alchemy RPC. It supports splitting traffic between Alchemy’s smart account infra and other Node providers (if needed). The AlchemyTransport has been added to @account-kit/infra and is exported as alchemy.

Creating a config with @account-kit/core or @account-kit/react has been updated to accept an AlchemyTransport and the parameters of createConfig have been simplified as a result. You will now need to replace your rpcUrl or apiKey params with transport: alchemy({...}).

For more detailed examples, see the relevant Quickstart guides, depending on which package you are using. If you don’t know where to start, checkout the React Quickstart.

Hooks: useSendTransaction and useSendTransactions removed

These methods have been removed since useSendUserOperation can be used to send transactions. If you were using useSendTransaction or useSendTransactions, you can replace them with useSendUserOperation and pass in waitForTxn: true so that all sendUserOperation calls will wait for the transaction to be mined.

Utils: verifyEIP6492Signature removed

This method has been removed. Use verifyMessage from viem.

Utils: defineReadOnly removed

This method is no longer used internally and has been removed. The reference impl can be found within ethers.js.

Utils: getChain removed

This method was not super efficient and maintainable because it was importing all the chains from viem. That meant that if you used this method, it risked increasing your bundle size massively. Now all methods require a Chain instead of chainId in some places.

Ethers: Chain required param

Certain methods required a chainId which would be converted into a Chain using the above method. This has been removed for the reasons above.

Alchemy Chain defs

The Alchemy Chain definitions have been moved from @aa-sdk/core to @account-kit/infra.

Ethers: getPublicErc4337Client → getBundlerClient

This method on the AccountSigner has been renamed.

Accounts: Default LightAccount Version Is Now v2.0.0

If you were creating LightAccounts for users without explicitly specifying the version (ie. in createLightAccount or useAccount or useSmartAccountClient), you should manually specify the previous default of v1.1.0.

Accounts: create*Client methods now have the account parameters un-nested

Previously, the create*Client (ie. createLightAccountClient) methods used to have an account parameter which took in the params for the underlying account. This is resulted in different APIs for both the corresponding create*AlchemyClient (ie. createLightAccountAlchemyClient) which had these as top-level parameters. If you were using createLightAccountClient or similar methods, you should now pass the account parameters as top-level parameters.

Accounts: getNonce -> getAccountNonce

Due to a clash in the typing of viem’s Account type, the getNonce method has been renamed to getAccountNonce.

Viem Version

The version of viem has been updated to 2.20.0 and been added as a peer dependency. If you have viem listed as a dependency, make sure it is updated to 2.20.0.

Dropped CJS Support

Due to our dependency on wagmi in the core and react packages, those packages no longer support cjs builds. To keep things consistent across all of our packages, we’ve dropped CJS support in all the packages in this repo. See this guide on how to migrate from CJS to ESM.

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. To address this, version 3.x.x of the SDK switches to an approach more idiomatic to viem.

Viem Version

We have updated our dependency to viem v2.x.x. This means you will need to update your project to use >= v2.5.0 of viem.

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. To get started with the new clients, you can do the following:

Client: removed sign*With6492 methods

The signMessageWith6492 and signTypedDataWith6492 methods have been removed from the SmartAccountClient. Now, all clients will always use 6492 when signing messages. However, if you need to sign messages without 6492, you can still use the client.account.signMessage methods.

Client: checkGasSponsorshipEligibility return type updated

The checkGasSponsorshipEligibility methods now returns an object that includes the eligibility status of a transaction as well as the UserOperationStruct that the eligibility is for. This now ensures that checking for sponsorship doesn’t cause you to use up your gas sponsorship limits. If your transaction is eligible, then you can sign the UO with client.signUserOperation and send it with client.sendRawUserOperation.

1
import { SmartAccountProvider } from "@aa-sdk/core"; // [!code --]
2
import { getDefaultEntryPointAddress } from "@aa-sdk/core"; // [!code --]
3
import { http } from "viem"; // [!code ++]
4
import { sepolia } from "@aa-sdk/core";
5
6
const provider = new SmartAccountProvider({ // [!code --]
7
const client = createSmartAccountClient({ // [!code ++]
8
  rpcProvider: "RPC_URL", // [!code --]
9
  transport: http("RPC_URL"), // [!code ++]
10
  chain: sepolia,
11
  entryPointAddress: getDefaultEntryPointAddress(sepolia), // [!code --]
12
});

Client: Removal of with* middleware override functions

The SmartAccountProvider in previous versions had a number of with* functions that mapped to the corresponding middleware functions on the provider. The concept of the middlewares is still present in this version, but their configuration has been moved to the SmartAccountClient creator. For example,

1
import { SmartAccountProvider } from "@aa-sdk/core"; // [!code --]
2
import { getDefaultEntryPointAddress } from "@aa-sdk/core"; // [!code --]
3
import { http } from "viem"; // [!code ++]
4
import { sepolia } from "@aa-sdk/core";
5
6
const provider = new SmartAccountProvider({ // [!code --]
7
const client = createSmartAccountClient({ // [!code ++]
8
    rpcProvider: "RPC_URL", // [!code --]
9
    transport: http("RPC_URL"), // [!code ++]
10
    chain: sepolia,
11
    entryPointAddress: getDefaultEntryPointAddress(sepolia), // [!code --]
12
}).withGasEstimator(async () => ({ // [!code --]
13
    gasEstimator: async (struct) => ({ // [!code ++]
14
        ...struct, // [!code ++]
15
        callGasLimit: 0n,
16
        preVerificationGas: 0n,
17
        verificationGasLimit: 0n,
18
    }), // [!code ++]
19
});

Client: Signature Changes on Methods

To support the various ways 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

The next big change is the removal of the class-based BaseSmartContractAccount that all accounts extended from. This has been replaced with a SmartContractAccount type that extends viem’s Account, and instantiation of an account is now an async action. To get started with the new accounts (using LightAccount as an example), you will have to make the following changes:

1
import {
2
  LightSmartContractAccount, // [!code --]
3
  createLightAccount, // [!code ++]
4
  getDefaultLightAccountFactoryAddress, // [!code --]
5
} from "@account-kit/smart-contracts";
6
import {
7
  LocalAccountSigner,
8
  type Hex,
9
} from "@aa-sdk/core";
10
import { sepolia } from "@aa-sdk/core";
11
12
const chain = sepolia;
13
14
const account = new LightSmartContractAccount({ // [!code --]
15
const account = await createLightAccount({ // [!code ++]
16
    rpcClient: client, // [!code --]
17
    transport: http("RPC_URL"), // [!code ++]
18
    signer,
19
    chain,
20
    factoryAddress: getDefaultLightAccountFactoryAddress(chain), // [!code --]
21
  });

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

1
import { createLightAccount } from "@account-kit/smart-contracts";
2
import {
3
  createBundlerClient,
4
  createSmartAccountClientFromExisting
5
  LocalAccountSigner,
6
  type Hex,
7
} from "@aa-sdk/core";
8
import { sepolia } from "@aa-sdk/core";
9
import { custom, http } from "viem";
10
11
const chain = sepolia;
12
13
const client = createBundlerClient({
14
  chain,
15
  transport: http("JSON_RPC_URL"),
16
});
17
18
// [!code focus:99]
19
// createSmartAccountClientFromExisting is a helper method that allows you
20
// to reuse a JSON RPC client to create a Smart Account client.
21
const smartAccountClient = createSmartAccountClientFromExisting({
22
  client,
23
});
24
25
const account = await createLightAccount({
26
  signer,
27
  chain,
28
  transport: custom(client),
29
});
30
31
const { hash } = await smartAccountClient.sendUserOperation({
32
    uo: {
33
        target: "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
34
        data: "0x",
35
        value: 10n,
36
    },
37
    account, // [!code ++]
38
});

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.

1
import { createLightAccount } from "@account-kit/smart-contracts";
2
import {
3
  createBundlerClient,
4
  createSmartAccountClientFromExisting
5
  LocalAccountSigner,
6
  type Hex,
7
} from "@aa-sdk/core";
8
import { sepolia } from "@aa-sdk/core";
9
import { http, custom } from "viem";
10
11
const chain = sepolia;
12
13
const client = createBundlerClient({
14
  chain,
15
  transport: http("JSON_RPC_URL"),
16
});
17
18
// [!code focus:99]
19
const account = await createLightAccount({
20
  signer,
21
  transport: custom(client),
22
  chain,
23
});
24
25
const smartAccountClient = createSmartAccountClientFromExisting({
26
  account, // [!code ++]
27
  client,
28
});
29
30
const { hash } = await smartAccountClient.sendUserOperation({
31
  uo: {
32
    target: "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
33
    data: "0x",
34
    value: 10n,
35
  },
36
  account, // [!code --]
37
});

Account: Custom Accounts

In prior versions, using your own wallet 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:

1
type toSmartContractAccount = <
2
  Name extends string = string,
3
  TTransport extends Transport = Transport,
4
>({
5
  transport,
6
  chain,
7
  source,
8
  entryPointAddress,
9
  accountAddress,
10
  getAccountInitCode,
11
  signMessage,
12
  signTypedData,
13
  encodeBatchExecute,
14
  encodeExecute,
15
  getDummySignature,
16
  signUserOperationHash,
17
  encodeUpgradeToAndCall,
18
}: ToSmartContractAccountParams<Name, TTransport>) => Promise<
19
  SmartContractAccount<Name>
20
>;

Account: SimpleAccount and NaniAccount initialization params

chain and transport have been added to the constructor and rpcClient has been removed.

Account: SimpleAccount and LightAccount initialization 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.

1
(params: SignTypedDataParams) => Promise<Hex>; // [!code --]
2
3
<
4
  const TTypedData extends TypedData | { [key: string]: unknown },
5
  TPrimaryType extends string = string,
6
>(
7
  params: TypedDataDefinition<TTypedData, TPrimaryType>,
8
) => Promise<Hex>;

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 multiplication of the estimation. For example, 0.1 is 10% of the estimated value and 1 is 100% of the estimated value.

1
createModularAccountAlchemyClient({
2
    ...
3
    opts: {
4
      ...
5
      // The maxFeePerGas and maxPriorityFeePerGas estimated values will now be multipled by 1.5
6
      feeOptions: {
7
        // This was previously { percent: 50n }
8
        maxFeePerGas: { multiplier: 1.5 },
9
        // This was previously { percent: 25n }
10
        maxPriorityFeePerGas: { multiplier: 1.25 },
11
      },
12
    },
13
  });