Overview

Rhinestone’s framework for creating and managing session keys. It is a powerful system for creating onchain permissions.

Introduction

Session keys are cryptographically signed keys generated by a user’s master key (passkey, ECDSA, or multisig). Smart Sessions enables session keys to be created and used with all major smart account implementations (via ERC-7579) and is fully compatible with Rhinestone’s Warp transaction infrastructure.

Examples of the onchain permissions that can be tailored with Smart Sessions include:

• Interacting only with a specific DeFi protocol (Aave or Uniswap)
• Spending limits on ERC20s or ETH
• Timeframes for expiry after a pre-determined period
• Combining permissions (e.g., Uniswap-only, 1000 USDC limit, 3-day expiry)

Key example use cases include:

• Skipping confirmations: Store a session key locally for “one-click trading,” allowing seamless decentralized application (dapp) interactions without repeated signing prompts.
• Automating transactions: Users share a scoped key for server-side execution, enabling:
  • Subscription payments
  • Limit orders or stop orders
  • Auto-repaying loans to prevent liquidation
  • This granular control enhances security, streamlines dapp interactions, and makes Web3 more user-friendly.

How it works

Smart Sessions is built around three concepts: owners (who can sign), permissions (what they can do), and policies (under what conditions).

Owners

Smart Sessions support a wide range of signing mechanisms out of the box:

• Single ECDSA key
• Multiple ECDSA keys (i.e. multisig)
• Passkeys

You can also use custom validators to validate sessions, as long as they are ERC-7780 compatible.

Permissions

Permissions define what calls a session is allowed to make. A permission is defined by an ABI and a target address, and lists the functions on that contract the session can call. The SDK derives selectors and parameter offsets from the ABI and checks parameter value types against ABI input types.

When defining multiple permissions within a session, a transaction that matches any specified permission is considered valid. If no permissions are specified, any transaction will pass.

When using smart contracts directly, you need to explicitly provide a list of valid permissions.

Policies

Policies let you restrict the session to hit specific conditions. You can define policies at the session (affects the entire session) or function (affects a single function within a permission) level.

Supported policies include:

• Sudo: allows any transaction
• Call: allows transactions with the specified calldata
• Spending limit: allows a limited value of ERC20 tokens to be transferred and approved
• Timeframe: allows transactions within the specified time frame
• Usage limit: allows a limited number of transactions
• Value limit: allows a limited ETH value transferred

When defining multiple policies within a function, a transaction that passes every specified policy is considered valid. If no policies are specified, any transaction will pass (i.e., the sudo policy is applied).

Policies work like a logical AND. If a function has two policies, the transaction must pass both policies to be valid.

Usage

Installing the validation

You can install the validator during account deployment:

const rhinestoneAccount = await rhinestone.createAccount({
  owners: {
    type: 'ecdsa',
    accounts: [ownerAccount],
  },
  sessions: {
    enabled: true,
  },
})

You can also install it when the account is already deployed:

import { enable } from '@rhinestone/sdk/actions/smart-sessions'

const transaction = await rhinestoneAccount.prepareTransaction({
  chain: base,
  calls: [enable()],
})

To uninstall the validator:

import { disable } from '@rhinestone/sdk/actions/smart-sessions'

const transaction = await rhinestoneAccount.prepareTransaction({
  chain: base,
  calls: [disable()],
})

Creating Sessions

To create a session, use RhinestoneSDK.createSession:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: 'ecdsa',
    accounts: [sessionOwnerAccount],
  },
})

You can also limit the session to specific allowed permissions:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: 'ecdsa',
    accounts: [sessionOwnerAccount],
  },
  permissions: [
    {
      abi: erc20Abi,
      address: usdcAddress,
      functions: { transfer: {} },
    },
  ],
})

Finally, you can constrain function parameters. The SDK derives the selector and parameter offsets from the ABI, so you reference parameters by name:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: 'ecdsa',
    accounts: [sessionOwnerAccount],
  },
  permissions: [
    {
      abi: erc20Abi,
      address: usdcAddress,
      functions: {
        transfer: {
          params: {
            recipient: {
              condition: 'equal',
              value: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
            },
          },
        },
      },
    },
  ],
})

Configuring session signing

Smart Sessions control ERC-1271 signatures separately from transaction permissions. Set signing on createSession to choose a mode:

• Disabled ({ mode: 'disabled' }): The session cannot sign messages or typed data.
• Unrestricted ({ mode: 'unrestricted' }): The session can sign any message or typed data.
• Scoped ({ mode: 'scoped', allowedContents: [...] }): The session can sign only EIP-712 typed data matching an allowed domain and primary-type schema. Plain messages and arbitrary hashes are not allowed.

If you omit signing, the SDK uses unrestricted signing with no validity window. This is identical to explicitly setting { mode: 'unrestricted' }, preserving existing session identities and behavior. Disable signing unless your session needs ERC-1271 signatures.

Both unrestricted and scoped signing accept optional validAfter and validUntil dates. One window applies to the entire signing capability. With neither bound, the SDK selects the unrestricted policy. If you provide either bound, it selects the time-frame policy.

Unrestricted, time-boxed signing

This session can sign any message or typed data for one hour:

const validAfter = new Date()
const validUntil = new Date(validAfter.getTime() + 60 * 60 * 1000)

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: 'ecdsa',
    accounts: [sessionOwnerAccount],
  },
  signing: {
    mode: 'unrestricted',
    validAfter,
    validUntil,
  },
})

Scoped Permit2 typed data

This session allows the Permit2 PermitSingle domain and schema. Provide the human-readable EIP-712 domain, types, and primaryType; the SDK derives the domain separator and canonical type encoding.

const permit2Address = '0x000000000022D473030F116dDEE9F6B43aC78BA3'

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: 'ecdsa',
    accounts: [sessionOwnerAccount],
  },
  signing: {
    mode: 'scoped',
    allowedContents: [
      {
        domain: {
          name: 'Permit2',
          chainId: base.id,
          verifyingContract: permit2Address,
        },
        types: {
          PermitDetails: [
            { name: 'token', type: 'address' },
            { name: 'amount', type: 'uint160' },
            { name: 'expiration', type: 'uint48' },
            { name: 'nonce', type: 'uint48' },
          ],
          PermitSingle: [
            { name: 'details', type: 'PermitDetails' },
            { name: 'spender', type: 'address' },
            { name: 'sigDeadline', type: 'uint256' },
          ],
        },
        primaryType: 'PermitSingle',
      },
    ],
  },
})

The scope matches the exact EIP-712 domain and canonical primary-type schema. It does not constrain message values such as the token, amount, spender, or deadline. Add transaction permissions or use separate sessions when those values need different controls.

You can configure and enable scoped sessions today, but direct scoped signing through signTypedData remains unavailable until safe ERC-7739 signature emission is restored. The SDK fails fast instead of emitting an unsafe signature.

Cross-chain permits

Use crossChainPermits to scope which routes, tokens, amounts, and recipients it may bridge:

const usdcOnBase = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
const usdcOnArbitrum = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: 'ecdsa',
    accounts: [sessionOwnerAccount],
  },
  crossChainPermits: [
    {
      from: [{ chain: base, token: usdcOnBase }],
      to: [{ chain: arbitrum, token: usdcOnArbitrum }],
    },
  ],
})

See Cross-chain permits for guardrails, recipient safety, and settlement-layer options.

Installing sessions

To enable a session:

import { enableSession } from '@rhinestone/sdk/actions/smart-sessions'

const sessions = [session]
const sessionDetails =
  await rhinestoneAccount.getSessionDetails(sessions)
const enableSignature =
  await rhinestoneAccount.signEnableSession(sessionDetails)
const sessionIndex = 0

const transaction = await rhinestoneAccount.prepareTransaction({
  chain,
  calls: [
    enableSession(
      session,
      enableSignature,
      sessionDetails.hashesAndChainIds,
      sessionIndex,
    ),
  ],
})

You can also enable session with a signature. See Multi-Session Signature for more details.

Checking session status

To check if a session is enabled:

const isEnabled = await rhinestoneAccount.isSessionEnabled(session)

Using sessions

To authorize a transaction with a session key you’ve enabled before:

const prepared = await rhinestoneAccount.prepareTransaction({
  chain,
  calls: [
    {
      to: usdcAddress,
      data: encodeFunctionData({
        abi: erc20Abi,
        functionName: 'transfer',
        args: ['0xd8da6bf26964af9d7eed9e03e53415d37aa96045', 1n],
      }),
    },
  ],
  signers: {
    type: 'session',
    session,
  },
})
const signed = await rhinestoneAccount.signTransaction(prepared)
const transactionResult = await rhinestoneAccount.submitTransaction(signed)

This will prompt the signature request from the session owner(s) and submit the transaction on their behalf.

You can also enable and use the smart session in one transaction using the “enable mode”.

Disabling a session

To disable a single enabled session, use disableSession. This only removes a single session: to uninstall the validator entirely (and every session with it), use disable instead.

import { disableSession } from '@rhinestone/sdk/actions/smart-sessions'

const transaction = await rhinestoneAccount.prepareTransaction({
  chain,
  calls: [disableSession(session)],
})

Security

Smart Sessions is a powerful tool that unlocks a bunch of new opportunities and use cases. To keep your users secure when using sessions, follow these guidelines:

• Store the session key securely. Depending on the use case, you can opt to store it in the browser or on your backend. Consider key management solutions like KMS or Lit Protocol.
• Stick to the principle of least privilege: do not request more actions than you need.
• Guard your smart session with granular policies (e.g., restrict the amount of ETH that can be transacted through the session)
• If possible, timebox your session (e.g., make it valid for only 1 week)

By default, the SDK creates a session that allows any transaction. Make sure you restrict it with relevant permissions and policies.

Reach out to us if you need any help!