Adding Session Keys to your Modular Account V2

Adding a session key is simple with Account Kit! To add a session key, you need to 1) decide what permissions you want to grant the new key and 2) call the installValidation method on the account. This method will send a single user operation that will add the session key with scoped permission to your smart contract account on-chain. You can then use that session key to sign transactions for your account within the defined permissions!

Adding scoped permissions to keys will happen via permission modules that you can pass as configuration parameters on the installValidation method. Permissions can be combined to fit your use case (e.g. you can limit a session key to only be able to spend 10 USDC within the next 24 hours on behalf of your account).

Adding a global session key (i.e. additional owner)

This example shows:

1. Adding a global session key to your Modular Account V2. This essentially gives the session key full control of your account. Functionally, this is how you can add another owner on your smart account.
2. Adding a session key that can only call ‘execute’ on the account. Functionally, this allows the session key to have full control of the account other than changing the underlying account implementation.

import { 
function createModularAccountV2Client<TChain extends Chain = Chain, TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(args: CreateModularAccountV2AlchemyClientParams<AlchemyTransport, TChain, TSigner>): Promise<ModularAccountV2Client<TSigner, TChain, AlchemyTransport>> (+1 overload)
createModularAccountV2Client } from "@account-kit/smart-contracts";
import {
  
const installValidationActions: <TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(client: ModularAccountV2Client<TSigner>) => InstallValidationActions<TSigner>
Provides validation installation and uninstallation functionalities for a MA v2 client, ensuring compatibility with SmartAccountClient.
installValidationActions,
  
const getDefaultSingleSignerValidationModuleAddress: (chain: Chain) => Address
Maps a given chain to a specific address of the single signer validation module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultSingleSignerValidationModuleAddress,
  
const SingleSignerValidationModule: {
    encodeOnInstallData: (args: {
        entityId: number;
        signer: Address;
    }) => Hex;
    encodeOnUninstallData: (args: {
        entityId: number;
    }) => Hex;
}
SingleSignerValidationModule,
  
const semiModularAccountBytecodeAbi: readonly [{
    readonly type: "constructor";
    readonly inputs: readonly [{
        readonly name: "entryPoint";
        readonly type: "address";
        readonly internalType: "contract IEntryPoint";
    }, {
        readonly name: "executionInstallDelegate";
        readonly type: "address";
        readonly internalType: "contract ExecutionInstallDelegate";
    }];
    readonly stateMutability: "nonpayable";
}, ... 60 more ..., {
    ...;
}]
semiModularAccountBytecodeAbi,
} from "@account-kit/smart-contracts/experimental";
import { 
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner } from "@aa-sdk/core";
import { 
const sepolia: Chain
sepolia, 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy } from "@account-kit/infra";
import { 
function generatePrivateKey(): Hex
generatePrivateKey } from "viem/accounts";
import { 
const toFunctionSelector: (fn: string | AbiFunction) => `0x${string}`
Returns the function selector for a given function definition.
toFunctionSelector, 
function getAbiItem<const abi extends Abi | readonly unknown[], name extends AbiItemName<abi>, const args extends AbiItemArgs<abi, name> | undefined = undefined>(parameters: GetAbiItemParameters<abi, name, args>): GetAbiItemReturnType<abi, name, args>
getAbiItem } from "viem";
import { type 
interface SmartAccountSigner<Inner = any>
A signer that can sign messages and typed data.
SmartAccountSigner } from "@aa-sdk/core";

const 
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client = (
  await 
createModularAccountV2Client<Chain, LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>(args: CreateModularAccountV2AlchemyClientParams<...>): Promise<...> (+1 overload)
createModularAccountV2Client({
    
chain: {
    blockExplorers?: {
        [key: string]: ChainBlockExplorer;
        default: ChainBlockExplorer;
    } | undefined;
    ... 7 more ...;
    testnet?: boolean | undefined;
} & ChainConfig<...>
Chain for the client.
chain: 
const sepolia: Chain
sepolia,
    
transport: AlchemyTransport
The RPC transport
transport: 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy({ 
apiKey: string
apiKey: "your-api-key" }),
    
signer: LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>
signer: 
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner.
LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>.privateKeyToAccountSigner(key: Hex): LocalAccountSigner<PrivateKeyAccount>
Creates a LocalAccountSigner instance using the provided private key.
privateKeyToAccountSigner(
function generatePrivateKey(): Hex
generatePrivateKey()),
  })
).
extend: <InstallValidationActions<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>>(fn: (client: Client<...>) => InstallValidationActions<...>) => Client<...>
extend(
const installValidationActions: <TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(client: ModularAccountV2Client<TSigner>) => InstallValidationActions<TSigner>
Provides validation installation and uninstallation functionalities for a MA v2 client, ensuring compatibility with SmartAccountClient.
installValidationActions);

let 
let sessionKeyEntityId: number
sessionKeyEntityId = 1;
const 
const ecdsaValidationModuleAddress: `0x${string}`
ecdsaValidationModuleAddress =
  
function getDefaultSingleSignerValidationModuleAddress(chain: Chain): Address
Maps a given chain to a specific address of the single signer validation module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultSingleSignerValidationModuleAddress(
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
chain: Chain
Chain for the client.
chain);
const 
const sessionKeySigner: SmartAccountSigner<any>
sessionKeySigner: 
interface SmartAccountSigner<Inner = any>
A signer that can sign messages and typed data.
SmartAccountSigner =
  
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner.
LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>.mnemonicToAccountSigner(key: string, opts?: HDOptions): LocalAccountSigner<HDAccount>
Creates a LocalAccountSigner using the provided mnemonic key and optional HD options.
mnemonicToAccountSigner("SESSION_KEY_MNEMONIC");

// 1. Adding a session key with full permissions
await 
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
installValidation: (args: InstallValidationParams<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>) => Promise<SendUserOperationResult>
installValidation({
  
validationConfig: ValidationConfig
validationConfig: {
    
moduleAddress: `0x${string}`
moduleAddress: 
const ecdsaValidationModuleAddress: `0x${string}`
ecdsaValidationModuleAddress,
    
entityId: number
entityId: 
let sessionKeyEntityId: number
sessionKeyEntityId,
    
isGlobal: boolean
isGlobal: true,
    
isSignatureValidation: boolean
isSignatureValidation: true,
    
isUserOpValidation: boolean
isUserOpValidation: true,
  },
  
selectors: `0x${string}`[]
selectors: [],
  
installData: `0x${string}`
installData: 
const SingleSignerValidationModule: {
    encodeOnInstallData: (args: {
        entityId: number;
        signer: Address;
    }) => Hex;
    encodeOnUninstallData: (args: {
        entityId: number;
    }) => Hex;
}
SingleSignerValidationModule.
encodeOnInstallData: (args: {
    entityId: number;
    signer: Address;
}) => Hex
encodeOnInstallData({
    
entityId: number
entityId: 
let sessionKeyEntityId: number
sessionKeyEntityId,
    
signer: `0x${string}`
signer: await 
const sessionKeySigner: SmartAccountSigner<any>
sessionKeySigner.
SmartAccountSigner<any>.getAddress: () => Promise<Address>
getAddress(), // Address of the session key
  }),
  
hooks: {
    hookConfig: HookConfig;
    initData: Hex;
}[]
hooks: [],
});

// 2. Adding a session key that can only call `execute` or `executeBatch` on the account
let sessionKeyEntityId: number
sessionKeyEntityId = 2;
const 
const executeSelector: `0x${string}`
executeSelector = 
function toFunctionSelector(fn: string | AbiFunction): `0x${string}`
Returns the function selector for a given function definition.
toFunctionSelector(
  
getAbiItem<readonly [{
    readonly type: "constructor";
    readonly inputs: readonly [{
        readonly name: "entryPoint";
        readonly type: "address";
        readonly internalType: "contract IEntryPoint";
    }, {
        readonly name: "executionInstallDelegate";
        readonly type: "address";
        readonly internalType: "contract ExecutionInstallDelegate";
    }];
    readonly stateMutability: "nonpayable";
}, ... 60 more ..., {
    ...;
}], "execute", undefined>(parameters: GetAbiItemParameters<...>): {
    ...;
}
getAbiItem({
    
abi: readonly [{
    readonly type: "constructor";
    readonly inputs: readonly [{
        readonly name: "entryPoint";
        readonly type: "address";
        readonly internalType: "contract IEntryPoint";
    }, {
        readonly name: "executionInstallDelegate";
        readonly type: "address";
        readonly internalType: "contract ExecutionInstallDelegate";
    }];
    readonly stateMutability: "nonpayable";
}, ... 60 more ..., {
    ...;
}]
abi: 
const semiModularAccountBytecodeAbi: readonly [{
    readonly type: "constructor";
    readonly inputs: readonly [{
        readonly name: "entryPoint";
        readonly type: "address";
        readonly internalType: "contract IEntryPoint";
    }, {
        readonly name: "executionInstallDelegate";
        readonly type: "address";
        readonly internalType: "contract ExecutionInstallDelegate";
    }];
    readonly stateMutability: "nonpayable";
}, ... 60 more ..., {
    ...;
}]
semiModularAccountBytecodeAbi,
    
name: `0x${string}` | "entryPoint" | "installValidation" | "uninstallValidation" | "execute" | "accountId" | "executeBatch" | "executeUserOp" | "executeWithRuntimeValidation" | "getExecutionData" | ... 49 more ... | "ValidationSignatureSegmentMissing"
name: "execute",
  }),
);

const 
const executeBatchSelector: `0x${string}`
executeBatchSelector = 
function toFunctionSelector(fn: string | AbiFunction): `0x${string}`
Returns the function selector for a given function definition.
toFunctionSelector(
  
getAbiItem<readonly [{
    readonly type: "constructor";
    readonly inputs: readonly [{
        readonly name: "entryPoint";
        readonly type: "address";
        readonly internalType: "contract IEntryPoint";
    }, {
        readonly name: "executionInstallDelegate";
        readonly type: "address";
        readonly internalType: "contract ExecutionInstallDelegate";
    }];
    readonly stateMutability: "nonpayable";
}, ... 60 more ..., {
    ...;
}], "executeBatch", undefined>(parameters: GetAbiItemParameters<...>): {
    ...;
}
getAbiItem({
    
abi: readonly [{
    readonly type: "constructor";
    readonly inputs: readonly [{
        readonly name: "entryPoint";
        readonly type: "address";
        readonly internalType: "contract IEntryPoint";
    }, {
        readonly name: "executionInstallDelegate";
        readonly type: "address";
        readonly internalType: "contract ExecutionInstallDelegate";
    }];
    readonly stateMutability: "nonpayable";
}, ... 60 more ..., {
    ...;
}]
abi: 
const semiModularAccountBytecodeAbi: readonly [{
    readonly type: "constructor";
    readonly inputs: readonly [{
        readonly name: "entryPoint";
        readonly type: "address";
        readonly internalType: "contract IEntryPoint";
    }, {
        readonly name: "executionInstallDelegate";
        readonly type: "address";
        readonly internalType: "contract ExecutionInstallDelegate";
    }];
    readonly stateMutability: "nonpayable";
}, ... 60 more ..., {
    ...;
}]
semiModularAccountBytecodeAbi,
    
name: `0x${string}` | "entryPoint" | "installValidation" | "uninstallValidation" | "execute" | "accountId" | "executeBatch" | "executeUserOp" | "executeWithRuntimeValidation" | "getExecutionData" | ... 49 more ... | "ValidationSignatureSegmentMissing"
name: "executeBatch",
  }),
);

await 
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
installValidation: (args: InstallValidationParams<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>) => Promise<SendUserOperationResult>
installValidation({
  
validationConfig: ValidationConfig
validationConfig: {
    
moduleAddress: `0x${string}`
moduleAddress: 
const ecdsaValidationModuleAddress: `0x${string}`
ecdsaValidationModuleAddress,
    
entityId: number
entityId: 
let sessionKeyEntityId: number
sessionKeyEntityId,
    
isGlobal: boolean
isGlobal: false,
    
isSignatureValidation: boolean
isSignatureValidation: false,
    
isUserOpValidation: boolean
isUserOpValidation: true,
  },
  
selectors: `0x${string}`[]
selectors: [
const executeSelector: `0x${string}`
executeSelector, 
const executeBatchSelector: `0x${string}`
executeBatchSelector],
  
installData: `0x${string}`
installData: 
const SingleSignerValidationModule: {
    encodeOnInstallData: (args: {
        entityId: number;
        signer: Address;
    }) => Hex;
    encodeOnUninstallData: (args: {
        entityId: number;
    }) => Hex;
}
SingleSignerValidationModule.
encodeOnInstallData: (args: {
    entityId: number;
    signer: Address;
}) => Hex
encodeOnInstallData({
    
entityId: number
entityId: 
let sessionKeyEntityId: number
sessionKeyEntityId,
    
signer: `0x${string}`
signer: await 
const sessionKeySigner: SmartAccountSigner<any>
sessionKeySigner.
SmartAccountSigner<any>.getAddress: () => Promise<Address>
getAddress(), // Address of the session key
  }),
  
hooks: {
    hookConfig: HookConfig;
    initData: Hex;
}[]
hooks: [],
});

Adding a session key with permissions

Time range

Configuring a session key with a time range allows you to limit how long the session key is valid for (e.g. only allow this key to sign on my account for the next day). The Time Range Module is used to enforce time-based validation for User Operations (UOs) in the system. This example will show you how to add a session key that starts in a day and expires in two days.

Additional Notes

• the interval is inclusive i.e. [beginningOfInterval, endOfInterval]
• the values beginningOfInterval and endOfInterval are unix timestamps with a maximum size of uint32
• the timestamp specifying the end of the interval must be strictly greater than the beginning of the interval

import { 
function createModularAccountV2Client<TChain extends Chain = Chain, TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(args: CreateModularAccountV2AlchemyClientParams<AlchemyTransport, TChain, TSigner>): Promise<ModularAccountV2Client<TSigner, TChain, AlchemyTransport>> (+1 overload)
createModularAccountV2Client } from "@account-kit/smart-contracts";
import {
  
enum HookType
HookType,
  
const installValidationActions: <TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(client: ModularAccountV2Client<TSigner>) => InstallValidationActions<TSigner>
Provides validation installation and uninstallation functionalities for a MA v2 client, ensuring compatibility with SmartAccountClient.
installValidationActions,
  
const getDefaultSingleSignerValidationModuleAddress: (chain: Chain) => Address
Maps a given chain to a specific address of the single signer validation module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultSingleSignerValidationModuleAddress,
  
const SingleSignerValidationModule: {
    encodeOnInstallData: (args: {
        entityId: number;
        signer: Address;
    }) => Hex;
    encodeOnUninstallData: (args: {
        entityId: number;
    }) => Hex;
}
SingleSignerValidationModule,
  
const getDefaultTimeRangeModuleAddress: (chain: Chain) => Address
Maps a given chain to a specific address of the time range module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultTimeRangeModuleAddress,
  
const TimeRangeModule: {
    abi: readonly [{
        readonly type: "function";
        readonly name: "moduleId";
        readonly inputs: readonly [];
        readonly outputs: readonly [{
            readonly name: "";
            readonly type: "string";
            readonly internalType: "string";
        }];
        readonly stateMutability: "pure";
    }, {
        readonly type: "function";
        readonly name: "onInstall";
        readonly inputs: readonly [{
            readonly name: "data";
            readonly type: "bytes";
            readonly internalType: "bytes";
        }];
        readonly outputs: readonly [];
        readonly stateMutability: "nonpayable";
    }, {
        readonly type: "function";
        readonly name: "onUninstall";
        readonly inputs: readonly [{
            readonly name: "data";
            readonly type: "bytes";
            readonly internalType: "bytes";
        }];
        readonly outputs: readonly [];
        readonly stateMutability: "nonpayable";
    }, {
        readonly type: "function";
        readonly name: "preRuntimeValidationHook";
        readonly inputs: readonly [{
            readonly name: "entityId";
            readonly type: "uint32";
            readonly internalType: "uint32";
        }, {
            readonly name: "";
            readonly type: "address";
            readonly internalType: "address";
        }, {
            readonly name: "";
            readonly type: "uint256";
            readonly internalType: "uint256";
        }, {
            readonly name: "";
            readonly type: "bytes";
            readonly ...
TimeRangeModule,
} from "@account-kit/smart-contracts/experimental";
import { 
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner } from "@aa-sdk/core";
import { 
const sepolia: Chain
sepolia, 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy } from "@account-kit/infra";
import { 
function generatePrivateKey(): Hex
generatePrivateKey } from "viem/accounts";
import { type 
interface SmartAccountSigner<Inner = any>
A signer that can sign messages and typed data.
SmartAccountSigner } from "@aa-sdk/core";

const 
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client = (
  await 
createModularAccountV2Client<Chain, LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>(args: CreateModularAccountV2AlchemyClientParams<...>): Promise<...> (+1 overload)
createModularAccountV2Client({
    
chain: {
    blockExplorers?: {
        [key: string]: ChainBlockExplorer;
        default: ChainBlockExplorer;
    } | undefined;
    ... 7 more ...;
    testnet?: boolean | undefined;
} & ChainConfig<...>
Chain for the client.
chain: 
const sepolia: Chain
sepolia,
    
transport: AlchemyTransport
The RPC transport
transport: 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy({ 
apiKey: string
apiKey: "your-api-key" }),
    
signer: LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>
signer: 
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner.
LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>.privateKeyToAccountSigner(key: Hex): LocalAccountSigner<PrivateKeyAccount>
Creates a LocalAccountSigner instance using the provided private key.
privateKeyToAccountSigner(
function generatePrivateKey(): Hex
generatePrivateKey()),
  })
).
extend: <InstallValidationActions<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>>(fn: (client: Client<...>) => InstallValidationActions<...>) => Client<...>
extend(
const installValidationActions: <TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(client: ModularAccountV2Client<TSigner>) => InstallValidationActions<TSigner>
Provides validation installation and uninstallation functionalities for a MA v2 client, ensuring compatibility with SmartAccountClient.
installValidationActions);

let 
let sessionKeyEntityId: number
sessionKeyEntityId = 1;
const 
const ecdsaValidationModuleAddress: `0x${string}`
ecdsaValidationModuleAddress =
  
function getDefaultSingleSignerValidationModuleAddress(chain: Chain): Address
Maps a given chain to a specific address of the single signer validation module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultSingleSignerValidationModuleAddress(
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
chain: Chain
Chain for the client.
chain);
const 
const sessionKeySigner: SmartAccountSigner<any>
sessionKeySigner: 
interface SmartAccountSigner<Inner = any>
A signer that can sign messages and typed data.
SmartAccountSigner =
  
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner.
LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>.mnemonicToAccountSigner(key: string, opts?: HDOptions): LocalAccountSigner<HDAccount>
Creates a LocalAccountSigner using the provided mnemonic key and optional HD options.
mnemonicToAccountSigner("SESSION_KEY_MNEMONIC");

const 
const hookEntityId: 0
hookEntityId = 0; // Make sure that the account does not have a hook with this entity id on the module yet
const 
const validAfter: 0
validAfter = 0; // valid once added
const 
const validUntil: number
validUntil = 
const validAfter: 0
validAfter + 2 * 86400; // validity ends 2 days from now

// Adding a session key that starts in a day and expires in two days
await 
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
installValidation: (args: InstallValidationParams<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>) => Promise<SendUserOperationResult>
installValidation({
  
validationConfig: ValidationConfig
validationConfig: {
    
moduleAddress: `0x${string}`
moduleAddress: 
const ecdsaValidationModuleAddress: `0x${string}`
ecdsaValidationModuleAddress,
    
entityId: number
entityId: 
let sessionKeyEntityId: number
sessionKeyEntityId,
    
isGlobal: boolean
isGlobal: true,
    
isSignatureValidation: boolean
isSignatureValidation: true,
    
isUserOpValidation: boolean
isUserOpValidation: true,
  },
  
selectors: `0x${string}`[]
selectors: [],
  
installData: `0x${string}`
installData: 
const SingleSignerValidationModule: {
    encodeOnInstallData: (args: {
        entityId: number;
        signer: Address;
    }) => Hex;
    encodeOnUninstallData: (args: {
        entityId: number;
    }) => Hex;
}
SingleSignerValidationModule.
encodeOnInstallData: (args: {
    entityId: number;
    signer: Address;
}) => Hex
encodeOnInstallData({
    
entityId: number
entityId: 
let sessionKeyEntityId: number
sessionKeyEntityId,
    
signer: `0x${string}`
signer: await 
const sessionKeySigner: SmartAccountSigner<any>
sessionKeySigner.
SmartAccountSigner<any>.getAddress: () => Promise<Address>
getAddress(), // Address of the session key
  }),
  
hooks: {
    hookConfig: HookConfig;
    initData: Hex;
}[]
hooks: [
    {
      
hookConfig: HookConfig
hookConfig: {
        
address: `0x${string}`
address: 
function getDefaultTimeRangeModuleAddress(chain: Chain): Address
Maps a given chain to a specific address of the time range module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultTimeRangeModuleAddress(
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
chain: Chain
Chain for the client.
chain),
        
entityId: number
entityId: 
const hookEntityId: 0
hookEntityId,
        
hookType: HookType
hookType: 
enum HookType
HookType.
function (enum member) HookType.VALIDATION = "0x01"
VALIDATION, // fixed value
        
hasPreHooks: boolean
hasPreHooks: true, // fixed value
        
hasPostHooks: boolean
hasPostHooks: false, // fixed value
      },
      
initData: `0x${string}`
initData: 
const TimeRangeModule: {
    abi: readonly [{
        readonly type: "function";
        readonly name: "moduleId";
        readonly inputs: readonly [];
        readonly outputs: readonly [{
            readonly name: "";
            readonly type: "string";
            readonly internalType: "string";
        }];
        readonly stateMutability: "pure";
    }, {
        readonly type: "function";
        readonly name: "onInstall";
        readonly inputs: readonly [{
            readonly name: "data";
            readonly type: "bytes";
            readonly internalType: "bytes";
        }];
        readonly outputs: readonly [];
        readonly stateMutability: "nonpayable";
    }, {
        readonly type: "function";
        readonly name: "onUninstall";
        readonly inputs: readonly [{
            readonly name: "data";
            readonly type: "bytes";
            readonly internalType: "bytes";
        }];
        readonly outputs: readonly [];
        readonly stateMutability: "nonpayable";
    }, {
        readonly type: "function";
        readonly name: "preRuntimeValidationHook";
        readonly inputs: readonly [{
            readonly name: "entityId";
            readonly type: "uint32";
            readonly internalType: "uint32";
        }, {
            readonly name: "";
            readonly type: "address";
            readonly internalType: "address";
        }, {
            readonly name: "";
            readonly type: "uint256";
            readonly internalType: "uint256";
        }, {
            readonly name: "";
            readonly type: "bytes";
            readonly ...
TimeRangeModule.
encodeOnInstallData: (args: {
    entityId: number;
    validUntil: number;
    validAfter: number;
}) => Hex
encodeOnInstallData({
        
entityId: number
entityId: 
const hookEntityId: 0
hookEntityId,
        
validAfter: number
validAfter,
        
validUntil: number
validUntil,
      }),
    },
  ],
});

Paymaster guard

Purpose

This module provides the ability to limit a session key to only be able to use a specific single paymaster.

Additional Notes

• you MUST specify a paymaster when using this module
• if the paymaster that is registered with this module decides to no longer sponsor your user operations, the entity associated with this hook would no longer be able to send user operations.

import { 
function createModularAccountV2Client<TChain extends Chain = Chain, TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(args: CreateModularAccountV2AlchemyClientParams<AlchemyTransport, TChain, TSigner>): Promise<ModularAccountV2Client<TSigner, TChain, AlchemyTransport>> (+1 overload)
createModularAccountV2Client } from "@account-kit/smart-contracts";
import {
  
enum HookType
HookType,
  
const installValidationActions: <TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(client: ModularAccountV2Client<TSigner>) => InstallValidationActions<TSigner>
Provides validation installation and uninstallation functionalities for a MA v2 client, ensuring compatibility with SmartAccountClient.
installValidationActions,
  
const getDefaultSingleSignerValidationModuleAddress: (chain: Chain) => Address
Maps a given chain to a specific address of the single signer validation module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultSingleSignerValidationModuleAddress,
  
const SingleSignerValidationModule: {
    encodeOnInstallData: (args: {
        entityId: number;
        signer: Address;
    }) => Hex;
    encodeOnUninstallData: (args: {
        entityId: number;
    }) => Hex;
}
SingleSignerValidationModule,
  
const getDefaultPaymasterGuardModuleAddress: (chain: Chain) => Address
Maps a given chain to a specific address of the paymaster guard module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultPaymasterGuardModuleAddress,
  
const PaymasterGuardModule: {
    abi: readonly [{
        readonly type: "function";
        readonly name: "moduleId";
        readonly inputs: readonly [];
        readonly outputs: readonly [{
            readonly name: "";
            readonly type: "string";
            readonly internalType: "string";
        }];
        readonly stateMutability: "pure";
    }, {
        readonly type: "function";
        readonly name: "onInstall";
        readonly inputs: readonly [{
            readonly name: "data";
            readonly type: "bytes";
            readonly internalType: "bytes";
        }];
        readonly outputs: readonly [];
        readonly stateMutability: "nonpayable";
    }, {
        readonly type: "function";
        readonly name: "onUninstall";
        readonly inputs: readonly [{
            readonly name: "data";
            readonly type: "bytes";
            readonly internalType: "bytes";
        }];
        readonly outputs: readonly [];
        readonly stateMutability: "nonpayable";
    }, {
        readonly type: "function";
        readonly name: "paymasters";
        readonly inputs: readonly [{
            readonly name: "entityId";
            readonly type: "uint32";
            readonly internalType: "uint32";
        }, {
            readonly name: "account";
            readonly type: "address";
            readonly internalType: "address";
        }];
        readonly outputs: readonly [{
            readonly name: "paymaster";
            readonly type: "address";
            readonly internalType: "address";
        }];
        readonly stateMutability: "view"; ...
PaymasterGuardModule,
} from "@account-kit/smart-contracts/experimental";
import { 
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner } from "@aa-sdk/core";
import { 
const sepolia: Chain
sepolia, 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy } from "@account-kit/infra";
import { 
function generatePrivateKey(): Hex
generatePrivateKey } from "viem/accounts";
import { type 
interface SmartAccountSigner<Inner = any>
A signer that can sign messages and typed data.
SmartAccountSigner } from "@aa-sdk/core";

const 
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client = (
  await 
createModularAccountV2Client<Chain, LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>(args: CreateModularAccountV2AlchemyClientParams<...>): Promise<...> (+1 overload)
createModularAccountV2Client({
    
chain: {
    blockExplorers?: {
        [key: string]: ChainBlockExplorer;
        default: ChainBlockExplorer;
    } | undefined;
    ... 7 more ...;
    testnet?: boolean | undefined;
} & ChainConfig<...>
Chain for the client.
chain: 
const sepolia: Chain
sepolia,
    
transport: AlchemyTransport
The RPC transport
transport: 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy({ 
apiKey: string
apiKey: "your-api-key" }),
    
signer: LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>
signer: 
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner.
LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>.privateKeyToAccountSigner(key: Hex): LocalAccountSigner<PrivateKeyAccount>
Creates a LocalAccountSigner instance using the provided private key.
privateKeyToAccountSigner(
function generatePrivateKey(): Hex
generatePrivateKey()),
  })
).
extend: <InstallValidationActions<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>>(fn: (client: Client<...>) => InstallValidationActions<...>) => Client<...>
extend(
const installValidationActions: <TSigner extends SmartAccountSigner = SmartAccountSigner<any>>(client: ModularAccountV2Client<TSigner>) => InstallValidationActions<TSigner>
Provides validation installation and uninstallation functionalities for a MA v2 client, ensuring compatibility with SmartAccountClient.
installValidationActions);

let 
let sessionKeyEntityId: number
sessionKeyEntityId = 1;
const 
const ecdsaValidationModuleAddress: `0x${string}`
ecdsaValidationModuleAddress =
  
function getDefaultSingleSignerValidationModuleAddress(chain: Chain): Address
Maps a given chain to a specific address of the single signer validation module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultSingleSignerValidationModuleAddress(
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
chain: Chain
Chain for the client.
chain);
const 
const sessionKeySigner: SmartAccountSigner<any>
sessionKeySigner: 
interface SmartAccountSigner<Inner = any>
A signer that can sign messages and typed data.
SmartAccountSigner =
  
class LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>
Represents a local account signer and provides methods to sign messages and transactions, as well as static methods to create the signer from mnemonic or private key.
LocalAccountSigner.
LocalAccountSigner<T extends HDAccount | PrivateKeyAccount | LocalAccount>.mnemonicToAccountSigner(key: string, opts?: HDOptions): LocalAccountSigner<HDAccount>
Creates a LocalAccountSigner using the provided mnemonic key and optional HD options.
mnemonicToAccountSigner("SESSION_KEY_MNEMONIC");

const 
const hookEntityId: 0
hookEntityId = 0; // Make sure that the account does not have a hook with this entity id on the module yet
const 
const paymasterAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
paymasterAddress = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";

// Adding a session key that can only use the above paymaster for user operations
await 
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
installValidation: (args: InstallValidationParams<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>) => Promise<SendUserOperationResult>
installValidation({
  
validationConfig: ValidationConfig
validationConfig: {
    
moduleAddress: `0x${string}`
moduleAddress: 
const ecdsaValidationModuleAddress: `0x${string}`
ecdsaValidationModuleAddress,
    
entityId: number
entityId: 
let sessionKeyEntityId: number
sessionKeyEntityId,
    
isGlobal: boolean
isGlobal: true,
    
isSignatureValidation: boolean
isSignatureValidation: true,
    
isUserOpValidation: boolean
isUserOpValidation: true,
  },
  
selectors: `0x${string}`[]
selectors: [],
  
installData: `0x${string}`
installData: 
const SingleSignerValidationModule: {
    encodeOnInstallData: (args: {
        entityId: number;
        signer: Address;
    }) => Hex;
    encodeOnUninstallData: (args: {
        entityId: number;
    }) => Hex;
}
SingleSignerValidationModule.
encodeOnInstallData: (args: {
    entityId: number;
    signer: Address;
}) => Hex
encodeOnInstallData({
    
entityId: number
entityId: 
let sessionKeyEntityId: number
sessionKeyEntityId,
    
signer: `0x${string}`
signer: await 
const sessionKeySigner: SmartAccountSigner<any>
sessionKeySigner.
SmartAccountSigner<any>.getAddress: () => Promise<Address>
getAddress(), // Address of the session key
  }),
  
hooks: {
    hookConfig: HookConfig;
    initData: Hex;
}[]
hooks: [
    {
      
hookConfig: HookConfig
hookConfig: {
        
address: `0x${string}`
address: 
function getDefaultPaymasterGuardModuleAddress(chain: Chain): Address
Maps a given chain to a specific address of the paymaster guard module by its chain ID. If no direct mapping exists, it defaults to returning a specific address.
getDefaultPaymasterGuardModuleAddress(
const client: Client<AlchemyTransport, Chain, ModularAccountV2<LocalAccountSigner<{
    address: Address;
    nonceManager?: NonceManager | undefined;
    sign: (parameters: {
        hash: Hash;
    }) => Promise<Hex>;
    ... 6 more ...;
    type: "local";
}>>, [...], {
    ...;
} & ... 4 more ... & PublicActions>
client.
chain: Chain
Chain for the client.
chain),
        
entityId: number
entityId: 
const hookEntityId: 0
hookEntityId,
        
hookType: HookType
hookType: 
enum HookType
HookType.
function (enum member) HookType.VALIDATION = "0x01"
VALIDATION, // fixed value
        
hasPreHooks: boolean
hasPreHooks: true, // fixed value
        
hasPostHooks: boolean
hasPostHooks: false, // fixed value
      },
      
initData: `0x${string}`
initData: 
const PaymasterGuardModule: {
    abi: readonly [{
        readonly type: "function";
        readonly name: "moduleId";
        readonly inputs: readonly [];
        readonly outputs: readonly [{
            readonly name: "";
            readonly type: "string";
            readonly internalType: "string";
        }];
        readonly stateMutability: "pure";
    }, {
        readonly type: "function";
        readonly name: "onInstall";
        readonly inputs: readonly [{
            readonly name: "data";
            readonly type: "bytes";
            readonly internalType: "bytes";
        }];
        readonly outputs: readonly [];
        readonly stateMutability: "nonpayable";
    }, {
        readonly type: "function";
        readonly name: "onUninstall";
        readonly inputs: readonly [{
            readonly name: "data";
            readonly type: "bytes";
            readonly internalType: "bytes";
        }];
        readonly outputs: readonly [];
        readonly stateMutability: "nonpayable";
    }, {
        readonly type: "function";
        readonly name: "paymasters";
        readonly inputs: readonly [{
            readonly name: "entityId";
            readonly type: "uint32";
            readonly internalType: "uint32";
        }, {
            readonly name: "account";
            readonly type: "address";
            readonly internalType: "address";
        }];
        readonly outputs: readonly [{
            readonly name: "paymaster";
            readonly type: "address";
            readonly internalType: "address";
        }];
        readonly stateMutability: "view"; ...
PaymasterGuardModule.
encodeOnInstallData: (args: {
    entityId: number;
    paymaster: Address;
}) => Hex
encodeOnInstallData({
        
entityId: number
entityId: 
const hookEntityId: 0
hookEntityId,
        
paymaster: `0x${string}`
paymaster: 
const paymasterAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
paymasterAddress,
      }),
    },
  ],
});