Skip to content
Alchemy Logo

@alchemy/smart-accounts

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 viem

import { 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 LightAccount
  • toMultiOwnerLightAccount - Multi-owner variant
  • predictLightAccountAddress / predictMultiOwnerLightAccountAddress - Counterfactual address prediction

  • toMultiOwnerModularAccountV1 - Account constructor
  • predictMultiOwnerModularAccountV1Address - Address prediction

  • toModularAccountV2 - Account constructor with EIP-7702 support
  • deferralActions / installValidationActions - Client decorators
  • Modules - AllowlistModule, NativeTokenLimitModule, PaymasterGuardModule, SingleSignerValidationModule, TimeRangeModule
  • PermissionBuilder - Fluent builder for session key permissions
  • Signature utilities - packUOSignature, pack1271Signature, toReplaySafeTypedData

MIT

ClassDescription
AccountAddressAsTargetErrorError class for when an account address is used as target.
DeadlineOverLimitErrorError class for when a deadline is over the limit.
DuplicateTargetAddressErrorError class for when a duplicate target address is added to a permission builder.
EntityIdOverrideErrorError class denoting that the provided entity id is invalid because it's overriding the native entity id.
ExpiredDeadlineErrorError class for when a deadline is expired.
InvalidDeferredActionNonceErrorError class denoting that the deferred action nonce used is invalid.
InvalidEntityIdErrorError class denoting that the provided entity id is invalid because it's too large.
InvalidNonceKeyErrorError class denoting that the nonce key is invalid because its too large.
InvalidOwnerErrorError class denoting that the owner for an account is invalid
MultipleGasLimitErrorError class for when a multiple gas limit permission is added to a permission builder.
MultipleNativeTokenTransferErrorError class for when a multiple native token transfer permission is added to a permission builder.
NoFunctionsProvidedErrorError class for when no functions are provided to a permission builder.
PermissionBuilderA builder for constructing a Permission object.
PermissionBuilderErrorAbstract class representing a Permission Builder Error, subclassed by all permission builder errors.
RootPermissionOnlyErrorError class for when a root permission is added to a permission builder.
SelectorNotAllowedError class for when a selector is not allowed.
UnsupportedPermissionTypeErrorError class for when an unsupported permission type is added to a permission builder.
ValidationConfigUnsetErrorError class for when a validation config is unset.
ZeroAddressErrorError class for when a zero address is provided to a permission builder.

Type AliasDescription
BaseMaV1AccountImplementation-
BaseModularAccountV2Implementation-
BuildNonceParams-
BuildPreSignatureDeferredActionPayloadParams-
CreateDeferredActionTypedDataParams-
DeferralActions-
DeferredActionReturnData-
DeferredActionTypedData-
EncodeDeferredActionWithSignatureParams-
EntityIdAndNonceParams-
EntryPointFromAccountRegistryInfers the EntryPoint details as a type, given the account type and version.
ExecutionDataView-
GetAccountParameter-
GetLightAccountAddressFromFactoryDataParams-
GetLightAccountType-
GetMAV2UpgradeToData-
GetModularAccountV2AddressFromFactoryDataParams-
GetMultiOwnerLightAccountAddressFromFactoryDataParams-
GetMultiOwnerModularAccountV1AddressFromFactoryDataParams-
HookConfig-
HookIdentifier-
HookType-
InstallValidationActions-
InstallValidationParams-
LightAccount-
LightAccountAbi-
LightAccountType-
LightAccountVersion-
ModularAccountV1Base-
ModularAccountV2-
ModularAccountV2Base-
ModuleEntity-
MultiOwnerLightAccount-
MultiOwnerModularAccountV1-
Pack1271SignatureParams-
PackUOSignatureParams-
Permission-
PermissionType-
PredictLightAccountAddressParams-
PredictModularAccountV2AddressParams-
PredictMultiOwnerLightAccountAddressParams-
PredictMultiOwnerModularAccountV1AddressParams-
SemiModularAccount7702StaticImpl-
SemiModularAccountV2FactoryArgs-
SemiModularAccountV2StaticImpl-
SignaturePrefix-
SignatureRequest-
SignerEntity-
SmartAccountWithDecodeCallsHelper type that converts a SmartAccount type to have a required decodeCalls function. This is useful for account implementations that always provide the decodeCalls functionality.
StaticSmartAccountImplementation-
ToLightAccountParams-
ToModularAccountV1BaseParams-
ToModularAccountV2BaseParams-
ToModularAccountV2Params-
ToMultiOwnerLightAccountParams-
ToMultiOwnerModularAccountV1Params-
UninstallValidationParams-
UpgradeToData-
ValidationConfig-
ValidationData-
ValidationDataParams-
ValidationDataView-

VariableDescription
AccountVersionRegistryAccount version registry interface that defines the light account versions and the version definition for each light account type
AllowlistModule-
DEFAULT_OWNER_ENTITY_IDThe default owner entity ID.
DefaultAddressA mapping of default addresses for the ModularAccountV2.
DefaultMaV1AddressA mapping of default addresses for the ModularAccountV1.
DefaultMaV1PluginAddressA mapping of default addresses for the ModularAccountV1 plugins.
DefaultModuleAddressA mapping of default addresses for the ModularAccountV2 modules.
ENTITY_ID_AND_NONCE_READER_BYTECODE-
EXECUTE_USER_OP_SELECTORThe selector for the execute user operation function.
HookIdentifierA pseudo-enum for hook identifiers.
HookType-
lightAccountStaticImplV1_0_1-
lightAccountStaticImplV1_0_2-
lightAccountStaticImplV1_1_0-
lightAccountStaticImplV2_0_0-
LightAccountUnsupported1271FactoriesCan be used to check if the account with one of the following factory addresses to not support 1271 signing.
LightAccountUnsupported1271ImplsCan be used to check if the account with one of the following implementation addresses to not support 1271 signing.
LightAccountV1VersionsLight Account v1 versions
LightAccountV2VersionsLight Account v2 versions
multiOwnerLightAccountStaticImplV2_0_0-
multiOwnerModularAccountStaticImplStatic implementation logic for ModularAccountV1.
NativeTokenLimitModule-
PaymasterGuardModule-
PermissionTypeA pseudo-enum for permission types.
semiModularAccount7702StaticImplStatic implementation logic for SemiModularAccount7702.
semiModularAccountV2StaticImplStatic implementation logic for SemiModularAccountV2.
SignaturePrefix-
SingleSignerValidationModule-
TimeRangeModule-

FunctionDescription
buildFullNonceKeyBuilds a full nonce key.
decodeCallsLADecodes 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.
decodeCallsMAv1Decodes 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.
decodeCallsMAv2Decodes 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.
defaultLightAccountVersionGet the default light account version for the given light account type
deferralActionsProvides deferred action functionalities for a MA v2 client, ensuring compatibility with SmartAccountClient.
encodeCallsLAEncodes 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.
encodeCallsMAv1Encodes 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.
encodeCallsMAv2Encodes 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.
encodeDeferredActionWithSignatureEncodes the deferred action with its signature, producing the payload to prepend to the userOp signature.
getLightAccountAddressFromFactoryDataGets 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.
getLightAccountImplAddressGet the light account implementation address for the given light account
getMAV2UpgradeToDataGets the upgrade to data for the ModularAccountV2.
getModularAccountV2AddressFromFactoryDataGets 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.
getMultiOwnerLightAccountAddressFromFactoryDataGets 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.
getMultiOwnerModularAccountV1AddressFromFactoryDataGets 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.
installValidationActionsProvides validation installation and uninstallation encoding functionalities for a MA v2 client.
isLightAccountVersion1Type guard to check if a version is a Light Account v1 version
isLightAccountVersion2Type guard to check if a version is a Light Account v2 version
isModularAccountV2Checks if an account is a ModularAccountV2.
pack1271SignatureSignature packing utility for 1271 signatures.
packUOSignatureSignature packing utility for user operations.
parseDeferredActionParses out the 3 components from a deferred action.
predictLightAccountAddressPredicts the address of a light account based on provided parameters such as factory address, salt, owner address, and version.
predictModularAccountV2AddressPredicts 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".
predictMultiOwnerLightAccountAddressPredicts the address of a Multi-Owner Light Account given the factory, salt and the set of owner addresses.
predictMultiOwnerModularAccountV1AddressPredicts the address of a MultiOwnerModularAccountV1 smart account before deployment.
serializeHookConfigSerializes a HookConfig object into a Hex format by encoding the hook type, presence of post/pre hooks, address, and entity ID.
serializeModuleEntitySerializes a module entity into a hexadecimal format by concatenating the module address and entity ID.
serializeValidationConfigSerializes a validation configuration into a hexadecimal string representation. This involves converting boolean flags into bitwise representation and combining them with serialized module entity data.
toLightAccountCreates a light account.
toModularAccountV1BaseCreates a ModularAccountV1Base instance.
toModularAccountV2Creates a MAv2 account.
toModularAccountV2BaseCreates a ModularAccountV2Base instance.
toMultiOwnerLightAccountCreates a multi-owner light account.
toMultiOwnerModularAccountV1Creates a multi-owner MAv1 account.
toReplaySafeTypedDataConverts a hash to a replay safe typed data.
Was this page helpful?