Smart sessions

Smart sessions let your dapp act on the user’s behalf within an explicit policy: a set of allowed contracts, function selectors, and an expiry. The user signs once to grant the session; afterwards every UserOperation that fits inside the policy can be executed by a session signer without prompting the user again. Smart sessions are implemented as an ERC-7579 validator module. The Startale AA SDK ships first-party helpers around the Rhinestone Smart Sessions module so you can install it and grant permissions through the same StartaleAccountClient you already use.

Source: StartaleGroup/scs-aa-sdk. The flow below mirrors the production integration in the Startale super-app.

How it fits together

Two artefacts come out of the granting step:

A permission id that identifies the policy onchain.
A session key keypair. The public key is committed to the policy; the private key is used by your backend or browser to sign UserOperations within scope.

1. Check whether the module is installed

getSmartSessionsValidator builds the validator descriptor. The module is keyed by its onchain address, so you can call isModuleInstalled on the account client to check status before installing.

import {
  getSmartSessionsValidator,
  type StartaleAccountClient,
} from "@startale-scs/aa-sdk"

const SMART_SESSIONS_MODULE = "0x00000000008bDABA73cD9815d79069c247Eb4bDA" as const

async function isSmartSessionsInstalled(client: StartaleAccountClient) {
  const sessionModule = getSmartSessionsValidator({})
  sessionModule.address = SMART_SESSIONS_MODULE
  sessionModule.module = SMART_SESSIONS_MODULE
  return client.isModuleInstalled({ module: sessionModule })
}

Symbol	Source	Role
`getSmartSessionsValidator`	`@startale-scs/aa-sdk`	Returns a validator descriptor pre-wired for the Smart Sessions module.
`isModuleInstalled`	`StartaleAccountClient` (ERC-7579 actions)	Reads the account’s installed validators onchain.

2. Install the module (one-time per account)

If the module is not installed, install it once. Installation is itself a UserOperation, so it goes through your bundler and (optionally) your paymaster.

async function installSmartSessions(client: StartaleAccountClient) {
  const sessionModule = getSmartSessionsValidator({})
  sessionModule.address = SMART_SESSIONS_MODULE
  sessionModule.module = SMART_SESSIONS_MODULE

  const userOpHash = await client.installModule({ module: sessionModule })
  return client.waitForUserOperationReceipt({ hash: userOpHash })
}

Symbol	Source	Role
`installModule`	`StartaleAccountClient` (ERC-7579 actions)	Sends a UserOperation that installs the module on the account.
`waitForUserOperationReceipt`	`StartaleAccountClient`	Polls the bundler for the receipt.

3. Define the permission scope

A session scope is a list of CreateSessionDataParams. Each entry binds the session key to a contract and a function selector, with optional onchain policies.

import type { CreateSessionDataParams } from "@startale-scs/aa-sdk"
import type { Address } from "viem"

function buildSessionScope(sessionPublicKey: Address): CreateSessionDataParams[] {
  return [
    {
      sessionPublicKey,
      actionPoliciesInfo: [
        {
          contractAddress: "0x...USDC...",
          functionSelector: "0x095ea7b3", // approve(address,uint256)
          sudo: true,
        },
        {
          contractAddress: "0x...Router...",
          functionSelector: "0xa3443faa", // your target selector
          sudo: true,
        },
      ],
    },
  ]
}

Field	Type	Notes
`sessionPublicKey`	`Address`	The public key of the session signer. The corresponding private key signs UserOperations within scope.
`actionPoliciesInfo[].contractAddress`	`Address`	Contract the session is allowed to call.
`actionPoliciesInfo[].functionSelector`	`Hex`	The 4-byte selector the session is allowed to call on that contract.
`actionPoliciesInfo[].sudo`	`boolean`	When `true`, allows any arguments. Set to `false` and add granular policies (spending caps, allowlists) for tighter control.

Generate the session key with viem’s generatePrivateKey() + privateKeyToAccount() and store the private key wherever you intend to sign from (typically a backend service or a sealed browser store).

4. Grant the permission

Granting the permission is also a UserOperation, signed once by the account owner. Use smartSessionCreateActions to extend the account client with the granting action, then call grantPermission.

import {
  smartSessionCreateActions,
  toSmartSessionsValidator,
  type Signer,
} from "@startale-scs/aa-sdk"
import type { Address, Hex } from "viem"

async function grantSession(
  client: StartaleAccountClient,
  sessionPublicKey: Address,
) {
  const sessionData = buildSessionScope(sessionPublicKey)

  const sessionSigner = toSmartSessionsValidator({
    account: client.account,
    signer: {
      address: sessionPublicKey,
      // Backend or remote signer holds the private key; the frontend uses a noop.
      signMessage: () => Promise.resolve("0x" as Hex),
      signTransaction: () => Promise.resolve("0x" as Hex),
      signTypedData: () => Promise.resolve("0x" as Hex),
      publicKey: "0x" as Hex,
      source: "",
      type: "local",
    } as Signer,
  })

  const response = await client
    .extend(smartSessionCreateActions(sessionSigner))
    .grantPermission({ sessionRequestedInfo: sessionData })

  return {
    permissionIds: response.permissionIds,
    userOpHash: response.userOpHash,
  }
}

Symbol	Source	Role
`toSmartSessionsValidator`	`@startale-scs/aa-sdk`	Builds the per-session validator object bound to the account and the session signer.
`smartSessionCreateActions`	`@startale-scs/aa-sdk`	Extends `StartaleAccountClient` with `grantPermission`.
`grantPermission`	extended client action	Sends a UserOperation that registers the policy and returns one permission id per `sessionRequestedInfo` entry.

5. Execute UserOperations under the session

Once granted, build a separate StartaleAccountClient whose signer is the session key. UserOperations from this client are validated by the Smart Sessions module instead of the account’s default validator.

import { http } from "viem"
import { privateKeyToAccount } from "viem/accounts"
import { soneiumMinato } from "viem/chains"
import {
  createSmartAccountClient,
  toStartaleSmartAccount,
} from "@startale-scs/aa-sdk"

const sessionSigner = privateKeyToAccount(SESSION_PRIVATE_KEY)

const sessionAccount = await toStartaleSmartAccount({
  signer: sessionSigner,
  chain: soneiumMinato,
  transport: http(),
  accountAddress: ownerAccountAddress, // same smart account, different signer
})

const sessionClient = createSmartAccountClient({
  account: sessionAccount,
  transport: http(process.env.BUNDLER_URL!),
  client: publicClient,
})

const hash = await sessionClient.sendUserOperation({
  calls: [{ to: routerAddress, data: callData, value: 0n }],
})

The user is not prompted; the session key signs locally, and the Smart Sessions module decides onchain whether the call is in scope.

Operational guidance

Treat session private keys like any other production secret. Keep them on a backend or in a sealed enclave, never in plain localStorage. Set the shortest expiry that still produces a good UX, and rotate keys on a schedule.

Concern	Recommendation
Storage	Backend KMS, secure enclave, or sealed browser storage.
Rotation	Issue short sessions (minutes-to-hours for high-risk flows, days for low-risk).
Revocation	Revoke a permission id by calling the module’s revocation flow when a session is compromised.
Auditing	Persist permission ids alongside `userOpHash` so you can correlate signed sessions with onchain activity.

Next steps

Social recovery

Combine sessions with a guardian-based recovery module.

Parallel transactions

Run independent session UserOperations concurrently.

Smart account setup

Refresh the underlying account and client setup.

Overview

Getting started

Tutorials

Auth providers

Advanced

EIP-7702

Resources

FAQ

How it fits together

1. Check whether the module is installed

2. Install the module (one-time per account)

3. Define the permission scope

4. Grant the permission

5. Execute UserOperations under the session

Operational guidance

Next steps

Social recovery

Sponsored paymaster

Parallel transactions

Smart account setup

​How it fits together

​1. Check whether the module is installed

​2. Install the module (one-time per account)

​3. Define the permission scope

​4. Grant the permission

​5. Execute UserOperations under the session

​Operational guidance

​Next steps

Social recovery

Sponsored paymaster

Parallel transactions

Smart account setup

How it fits together

1. Check whether the module is installed

2. Install the module (one-time per account)

3. Define the permission scope

4. Grant the permission

5. Execute UserOperations under the session

Operational guidance

Next steps