Skip to main content

​
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: 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. A session with permissions does not reject everything else by default: calls that match no permission are executed as intents through the Orchestrator. See Restrict a session to turn that off.
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
  • Cross-chain permits: scopes the routes, tokens, amounts, and recipients a session may bridge
  • 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.

​
Guides

Create a session

Install the validator, define a session, and scope it with permissions and parameter constraints.

Use a session

Enable a session, check its status, transact with it, and disable it.

Restrict a session

Drop the intent-execution fallback so the session runs only the calls it lists.

Session signing

Control the ERC-1271 surface: disabled, unrestricted, or scoped to specific typed data.

Swap sessions

Scope a session to a single swap: two tokens, a fixed recipient, a spend cap, and agreed venues.

Multi-chain session

Sign once and enable sessions across chains with the same signature.

​
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, and a session with permissions still routes other calls through the Orchestrator. Restrict it with relevant permissions and policies, and restrict it to its explicit actions when the session must only run the calls it lists.
Reach out to us if you need any help!