Beta — This package replaces @account-kit/smart-contracts. This is a low-level package. Most users should use @alchemy/wallet-apis unless you need to use interface with Smart Accounts directly via viem.
Viem-compatible smart account implementations for Alchemy's smart contract accounts. Supports LightAccount, Modular Account v1, and Modular Account v2 with EIP-7702.
npm install @alchemy/smart-accounts @alchemy/common viemimport { createPublicClient } from "viem";
import {
createBundlerClient,
createPaymasterClient,
} from "viem/account-abstraction";
import { sepolia } from "viem/chains";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
import { alchemyTransport } from "@alchemy/common";
import { estimateFeesPerGas } from "@alchemy/aa-infra";
import { toModularAccountV2 } from "@alchemy/smart-accounts";
const transport = alchemyTransport({ apiKey: "YOUR_API_KEY" });
// 1. Create a MAv2 smart account
const account = await toModularAccountV2({
client: createPublicClient({ chain: sepolia, transport }),
owner: privateKeyToAccount(generatePrivateKey()),
});
// 2. Create a bundler client with the account
const bundlerClient = createBundlerClient({
account,
chain: sepolia,
transport,
userOperation: {
estimateFeesPerGas,
},
// Optional: sponsor gas with a paymaster
paymaster: createPaymasterClient({ transport }),
paymasterContext: { policyId: "YOUR_POLICY_ID" },
});
// 3. Send a user operation
const hash = await bundlerClient.sendUserOperation({
calls: [{ to: "0x...", value: 0n, data: "0x" }],
});
const receipt = await bundlerClient.waitForUserOperationReceipt({ hash });toLightAccount- Single-owner LightAccounttoMultiOwnerLightAccount- Multi-owner variantpredictLightAccountAddress/predictMultiOwnerLightAccountAddress- Counterfactual address prediction
toMultiOwnerModularAccountV1- Account constructorpredictMultiOwnerModularAccountV1Address- Address prediction
toModularAccountV2- Account constructor with EIP-7702 supportdeferralActions/installValidationActions- Client decorators- Modules -
AllowlistModule,NativeTokenLimitModule,PaymasterGuardModule,SingleSignerValidationModule,TimeRangeModule PermissionBuilder- Fluent builder for session key permissions- Signature utilities -
packUOSignature,pack1271Signature,toReplaySafeTypedData
MIT
| Class | Description |
|---|---|
| AccountAddressAsTargetError | Error class for when an account address is used as target. |
| DeadlineOverLimitError | Error class for when a deadline is over the limit. |
| DuplicateTargetAddressError | Error class for when a duplicate target address is added to a permission builder. |
| EntityIdOverrideError | Error class denoting that the provided entity id is invalid because it's overriding the native entity id. |
| ExpiredDeadlineError | Error class for when a deadline is expired. |
| InvalidDeferredActionNonceError | Error class denoting that the deferred action nonce used is invalid. |
| InvalidEntityIdError | Error class denoting that the provided entity id is invalid because it's too large. |
| InvalidNonceKeyError | Error class denoting that the nonce key is invalid because its too large. |
| InvalidOwnerError | Error class denoting that the owner for an account is invalid |
| MultipleGasLimitError | Error class for when a multiple gas limit permission is added to a permission builder. |
| MultipleNativeTokenTransferError | Error class for when a multiple native token transfer permission is added to a permission builder. |
| NoFunctionsProvidedError | Error class for when no functions are provided to a permission builder. |
| PermissionBuilder | A builder for constructing a Permission object. |
| PermissionBuilderError | Abstract class representing a Permission Builder Error, subclassed by all permission builder errors. |
| RootPermissionOnlyError | Error class for when a root permission is added to a permission builder. |
| SelectorNotAllowed | Error class for when a selector is not allowed. |
| UnsupportedPermissionTypeError | Error class for when an unsupported permission type is added to a permission builder. |
| ValidationConfigUnsetError | Error class for when a validation config is unset. |
| ZeroAddressError | Error class for when a zero address is provided to a permission builder. |
| Variable | Description |
|---|---|
| AccountVersionRegistry | Account version registry interface that defines the light account versions and the version definition for each light account type |
| AllowlistModule | - |
| DEFAULT_OWNER_ENTITY_ID | The default owner entity ID. |
| DefaultAddress | A mapping of default addresses for the ModularAccountV2. |
| DefaultMaV1Address | A mapping of default addresses for the ModularAccountV1. |
| DefaultMaV1PluginAddress | A mapping of default addresses for the ModularAccountV1 plugins. |
| DefaultModuleAddress | A mapping of default addresses for the ModularAccountV2 modules. |
| ENTITY_ID_AND_NONCE_READER_BYTECODE | - |
| EXECUTE_USER_OP_SELECTOR | The selector for the execute user operation function. |
| HookIdentifier | A pseudo-enum for hook identifiers. |
| HookType | - |
| lightAccountStaticImplV1_0_1 | - |
| lightAccountStaticImplV1_0_2 | - |
| lightAccountStaticImplV1_1_0 | - |
| lightAccountStaticImplV2_0_0 | - |
| LightAccountUnsupported1271Factories | Can be used to check if the account with one of the following factory addresses to not support 1271 signing. |
| LightAccountUnsupported1271Impls | Can be used to check if the account with one of the following implementation addresses to not support 1271 signing. |
| LightAccountV1Versions | Light Account v1 versions |
| LightAccountV2Versions | Light Account v2 versions |
| multiOwnerLightAccountStaticImplV2_0_0 | - |
| multiOwnerModularAccountStaticImpl | Static implementation logic for ModularAccountV1. |
| NativeTokenLimitModule | - |
| PaymasterGuardModule | - |
| PermissionType | A pseudo-enum for permission types. |
| semiModularAccount7702StaticImpl | Static implementation logic for SemiModularAccount7702. |
| semiModularAccountV2StaticImpl | Static implementation logic for SemiModularAccountV2. |
| SignaturePrefix | - |
| SingleSignerValidationModule | - |
| TimeRangeModule | - |
| Function | Description |
|---|---|
| buildFullNonceKey | Builds a full nonce key. |
| decodeCallsLA | Decodes LightAccount calldata back into an array of calls. Used internally by the LightAccount SmartAccount implementation. Typically not needed directly unless you have an advanced use case. |
| decodeCallsMAv1 | Decodes ModularAccountV1 calldata back into an array of calls. Used internally by the ModularAccountV1 SmartAccount implementation. Typically not needed directly unless you have an advanced use case. |
| decodeCallsMAv2 | Decodes ModularAccountV2 calldata back into an array of calls. Strips the EXECUTE_USER_OP_SELECTOR prefix if present. Used internally by the ModularAccountV2 SmartAccount implementation. Typically not needed directly unless you have an advanced use case. |
| defaultLightAccountVersion | Get the default light account version for the given light account type |
| deferralActions | Provides deferred action functionalities for a MA v2 client, ensuring compatibility with SmartAccountClient. |
| encodeCallsLA | Encodes an array of calls into LightAccount calldata for execute or executeBatch. Used internally by the LightAccount SmartAccount implementation. Typically not needed directly unless you have an advanced use case. |
| encodeCallsMAv1 | Encodes an array of calls into ModularAccountV1 calldata for execute or executeBatch. Used internally by the ModularAccountV1 SmartAccount implementation. Typically not needed directly unless you have an advanced use case. |
| encodeCallsMAv2 | Encodes an array of calls into ModularAccountV2 calldata for execute or executeBatch. Used internally by the ModularAccountV2 SmartAccount implementation. Typically not needed directly unless you have an advanced use case. |
| encodeDeferredActionWithSignature | Encodes the deferred action with its signature, producing the payload to prepend to the userOp signature. |
| getLightAccountAddressFromFactoryData | Gets the light account address from factory data. If the factory is a known default, decodes the args and predicts without RPC. Otherwise falls back to calling the entry point's getSenderAddress. |
| getLightAccountImplAddress | Get the light account implementation address for the given light account |
| getMAV2UpgradeToData | Gets the upgrade to data for the ModularAccountV2. |
| getModularAccountV2AddressFromFactoryData | Gets the modular account v2 address from factory data. If the factory is a known default (SMA), decodes the args and predicts without RPC. Otherwise falls back to calling the entry point's getSenderAddress. |
| getMultiOwnerLightAccountAddressFromFactoryData | Gets the multi-owner light account address from factory data. If the factory is a known default, decodes the args and predicts without RPC. Otherwise falls back to calling the entry point's getSenderAddress. |
| getMultiOwnerModularAccountV1AddressFromFactoryData | Gets the multi-owner modular account v1 address from factory data. If the factory is a known default, decodes the args and predicts without RPC. Otherwise falls back to calling the entry point's getSenderAddress. |
| installValidationActions | Provides validation installation and uninstallation encoding functionalities for a MA v2 client. |
| isLightAccountVersion1 | Type guard to check if a version is a Light Account v1 version |
| isLightAccountVersion2 | Type guard to check if a version is a Light Account v2 version |
| isModularAccountV2 | Checks if an account is a ModularAccountV2. |
| pack1271Signature | Signature packing utility for 1271 signatures. |
| packUOSignature | Signature packing utility for user operations. |
| parseDeferredAction | Parses out the 3 components from a deferred action. |
| predictLightAccountAddress | Predicts the address of a light account based on provided parameters such as factory address, salt, owner address, and version. |
| predictModularAccountV2Address | Predicts the address of a modular account V2 based on the provided parameters, which include factory address, salt, and implementation address. This function supports different types of accounts including "SMA" and "MA". |
| predictMultiOwnerLightAccountAddress | Predicts the address of a Multi-Owner Light Account given the factory, salt and the set of owner addresses. |
| predictMultiOwnerModularAccountV1Address | Predicts the address of a MultiOwnerModularAccountV1 smart account before deployment. |
| serializeHookConfig | Serializes a HookConfig object into a Hex format by encoding the hook type, presence of post/pre hooks, address, and entity ID. |
| serializeModuleEntity | Serializes a module entity into a hexadecimal format by concatenating the module address and entity ID. |
| serializeValidationConfig | Serializes a validation configuration into a hexadecimal string representation. This involves converting boolean flags into bitwise representation and combining them with serialized module entity data. |
| toLightAccount | Creates a light account. |
| toModularAccountV1Base | Creates a ModularAccountV1Base instance. |
| toModularAccountV2 | Creates a MAv2 account. |
| toModularAccountV2Base | Creates a ModularAccountV2Base instance. |
| toMultiOwnerLightAccount | Creates a multi-owner light account. |
| toMultiOwnerModularAccountV1 | Creates a multi-owner MAv1 account. |
| toReplaySafeTypedData | Converts a hash to a replay safe typed data. |