Getting started with Session Keys
@account-kit/smart-contracts
exports all of the definitions you need to use session keys with a Modular Account. We provide a simple SessionKeySigner
class that generates session keys on the client and can be used as the signer
for the Multi Owner Modular Account.
We also export the necessary decorators which can be used to extend your modularAccountClient
to make interacting with session keys easy.
Usage
Let's take a look at a full example that demonstrates how to use session keys with a Modular Account.
/* eslint-disable @typescript-eslint/no-unused-vars */
import { LocalAccountSigner } from "@aa-sdk/core";
import { alchemy, sepolia } from "@account-kit/infra";
import {
SessionKeyAccessListType,
SessionKeyPermissionsBuilder,
SessionKeyPlugin,
SessionKeySigner,
createModularAccountAlchemyClient,
sessionKeyPluginActions,
} from "@account-kit/smart-contracts";
import { zeroHash } from "viem";
const chain = sepolia;
const transport = alchemy({ apiKey: "YOUR_API_KEY" });
// this is the signer to connect with the account, later we will create a new client using a session key signe
const signer = LocalAccountSigner.mnemonicToAccountSigner("MNEMONIC");
const sessionKeySigner = new SessionKeySigner();
const client = (
await createModularAccountAlchemyClient({
chain,
transport,
signer,
})
).extend(sessionKeyPluginActions);
// 1. check if the plugin is installed
const isPluginInstalled = await client
.getInstalledPlugins({})
// This checks using the default address for the chain, but you can always pass in your own plugin address here as an override
.then((x) => x.includes(SessionKeyPlugin.meta.addresses[chain.id]));
// 2. if the plugin is not installed, then install it and set up the session key
if (!isPluginInstalled) {
// lets create an initial permission set for the session key giving it an eth spend limit
const initialPermissions = new SessionKeyPermissionsBuilder()
.setNativeTokenSpendLimit({
spendLimit: 1000000n,
})
// this will allow the session key plugin to interact with all addresses
.setContractAccessControlType(SessionKeyAccessListType.ALLOW_ALL_ACCESS)
.setTimeRange({
validFrom: Math.round(Date.now() / 1000),
// valid for 1 hour
validUntil: Math.round(Date.now() / 1000 + 60 * 60),
});
const { hash } = await client.installSessionKeyPlugin({
// 1st arg is the initial set of session keys
// 2nd arg is the tags for the session keys
// 3rd arg is the initial set of permissions
args: [
[await sessionKeySigner.getAddress()],
[zeroHash],
[initialPermissions.encode()],
],
});
await client.waitForUserOperationTransaction({ hash });
}
// 3. set up a client that's using our session key
const sessionKeyClient = (
await createModularAccountAlchemyClient({
chain,
signer: sessionKeySigner,
transport,
// this is important because it tells the client to use our previously deployed account
accountAddress: client.getAddress({ account: client.account }),
})
).extend(sessionKeyPluginActions);
// 4. send a user operation using the session key
const result = await sessionKeyClient.executeWithSessionKey({
args: [
[
{
target: "0x1234123412341234123412341234123412341234",
value: 1n,
data: "0x",
},
],
await sessionKeySigner.getAddress(),
],
});
Breaking it down
Determine where the session key is stored
Session keys can be held on the client side or on a backend agent. Client side session keys are useful for skipping confirmations, and agent side keys are useful for automations.
In the above example, we use a client-side key using the SessionKeySigner
exported from @account-kit/smart-contracts
.
import { SessionKeySigner } from "@account-kit/smart-contracts";
const sessionKeySigner = new SessionKeySigner();
If you are using backend agent controlled session keys, then the agent should generate the private key and send only the address to the client. This protects the private key by not exposing it to the user.
Extend your client with Modular Account Decorators
The base modularAccountClient
and AlchemymodularAccountClient
, only include base functionality for sending user operations. If you are using a ModularAccount
, then you will want to extend your client with the various decorators exported by @account-kit/smart-contracts
.
import { modularAccountClient } from "./client";
import { sessionKeyPluginActions } from "@account-kit/smart-contracts";
const extendedClient = modularAccountClient.extend(sessionKeyPluginActions);
Check if the Session Key Plugin is installed
Before you can start using session keys, you need to check whether the user’s account has the session key plugin installed. You can perform this check using the account loupe decorator, which lets you inspect the state of installed plugins on a Modular Account.
import { SessionKeyPlugin } from "@account-kit/smart-contracts";
// 1. check if the plugin is installed
const isPluginInstalled = await modularAccountClient
.getInstalledPlugins({})
// This checks using the default address for the chain, but you can always pass in your own plugin address here as an override
.then((x) => x.includes(SessionKeyPlugin.meta.addresses[chain.id]));
Install the Session Key Plugin
If the Session Key Plugin is not yet installed, you need to install it before it can be used. To simplify the workflow, it is also possible to batch the plugin installation along with creating session keys and performing other actions, which combines all of these steps into one user operation.
import { SessionKeyPermissionsBuilder } from "@account-kit/smart-contracts";
// 2. if the plugin is not installed, then install it and set up the session key
if (!isPluginInstalled) {
// lets create an initial permission set for the session key giving it an eth spend limit
// if we don't set anything here, then the key will have 0 permissions
const initialPermissions =
new SessionKeyPermissionsBuilder().setNativeTokenSpendLimit({
spendLimit: 1000000n,
});
const { hash } = await extendedClient.installSessionKeyPlugin({
// 1st arg is the initial set of session keys
// 2nd arg is the tags for the session keys
// 3rd arg is the initial set of permissions
args: [
[await sessionKeySigner.getAddress()],
[zeroHash],
[initialPermissions.encode()],
],
});
await extendedClient.waitForUserOperationTransaction({ hash });
}
Construct the initial set of permissions
Session keys are powerful because of permissions that limit what actions they can take. When you add a session key, you should also specify the initial permissions that apply over the key.
See the Supported Permissions page for more information on how to used the permissions builder.
Let's use the permission builder to build a set of permissions that sets a spend limit:
import { SessionKeyPermissionsBuilder } from "@account-kit/smart-contracts";
const initialPermissions =
new SessionKeyPermissionsBuilder().setNativeTokenSpendLimit({
spendLimit: 1000000n,
});
const result = await extendedClient.updateKeyPermissions({
args: [sessionKeyAddress, initialPermissions.encode()],
});
Managing Session Keys
The Session Key Plugin allows you to:
- Add session keys, and set the key's initial permissions.
- Remove session keys.
- Update key permissions.
- Rotate session keys. This action replaces the previous session key with a new session key, while keeping the existing permissions.
Add a Session Key
Session keys can be added either during installation, or using the addSessionKey
function.
import { SessionKeyPermissionsBuilder } from "@account-kit/smart-contracts";
import { keccak256 } from "viem";
import { client } from "./base-client";
const result = await client.addSessionKey({
key: "0xSessionKeyAddress",
// tag is an identifier for the emitted SessionKeyAdded event
tag: keccak256(new TextEncoder().encode("session-key-tag")),
permissions: new SessionKeyPermissionsBuilder().encode(),
});
Remove a Session Key
Session keys can be removed using the removeSessionKey
function.
import { client } from "./base-client";
const result = await client.removeSessionKey({
key: "0xSessionKeyAddress",
});
Update a Key's permissions
Session key permissions can be edited after creation using the updateKeyPermissions
function. Note that you should configure initial permissions when the key is added, and not rely on a second user operation to set the permissions.
import { SessionKeyPermissionsBuilder } from "@account-kit/smart-contracts";
import { client } from "./base-client";
const result = await client.updateSessionKeyPermissions({
key: "0xSessionKeyAddress",
// add other permissions to the builder
permissions: new SessionKeyPermissionsBuilder()
.setTimeRange({
validFrom: Math.round(Date.now() / 1000),
// valid for 1 hour
validUntil: Math.round(Date.now() / 1000 + 60 * 60),
})
.encode(),
});
Rotate a Session Key
If the key is no longer available, but there exists a tag identifying a previous session key configured for your application, you may instead choose to rotate the previous key’s permissions. This can be performed using rotateKey
.
import { client } from "./base-client.js";
const result = await client.rotateSessionKey({
oldKey: "0xOldKey",
newKey: "0xNewKey",
});