Getting started with Session Keys

@alchemy/aa-accounts 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 SmartAccountClient 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.

full-example.ts

import {
  SessionKeyAccessListType,
  SessionKeyPermissionsBuilder,
  SessionKeyPlugin,
  SessionKeySigner,
  sessionKeyPluginActions,
} from "@alchemy/aa-accounts";
import { createModularAccountAlchemyClient } from "@alchemy/aa-alchemy";
import { LocalAccountSigner, sepolia } from "@alchemy/aa-core";
import { zeroHash } from "viem";
 
const chain = sepolia;
// 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,
    apiKey: "ALCHEMY_API_KEY",
    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,
    apiKey: "ALCHEMY_API_KEY",
    // this is important because it tells the client to use our previously deployed account
    accountAddress: client.getAddress(),
  })
).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 @alchemy/aa-accounts.

import { SessionKeySigner } from "@alchemy/aa-accounts";
 
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 SmartAccountClient and AlchemySmartAccountClient, 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 @alchemy/aa-accounts.

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.

// 1. check if the plugin is installed
const extendedClient = 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]));

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.

// 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:

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.

add-session-key.ts

import { SessionKeyPermissionsBuilder } from "@alchemy/aa-accounts";
import { keccak256 } from "viem";
import { client } from "./base-client.js";
 
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.

remove-session-key.ts

import { client } from "./base-client.js";
 
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.

update-session-key.ts

import { SessionKeyPermissionsBuilder } from "@alchemy/aa-accounts";
import { client } from "./base-client.js";
 
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 .

rotate-session-key.ts

import { client } from "./base-client.js";
 
const result = await client.rotateSessionKey({
  oldKey: "0xOldKey",
  newKey: "0xNewKey",
});