controller-sessions

Original：🇺🇸 English
Translated

Configure session keys and policies for Cartridge Controller to enable gasless, pre-approved transactions. Use when defining contract interaction policies, setting spending limits, configuring signed message policies, or implementing error handling for session-based transactions. Covers SessionPolicies type, policy definitions, verified sessions, and error display modes.

15installs
Sourcecartridge-gg/docs
Added on

NPX Install

npx skill4agent add cartridge-gg/docs controller-sessions

Tags

Translated version includes tags in frontmatter
session-policiesgasless-transactionscartridge-controllererror-handlingsmart-contract-interaction

SKILL.md Content

View Translation Comparison →

Controller Sessions & Policies

Sessions enable pre-approved, gasless transactions without user prompts for each interaction.

How Sessions Work

  1. Define policies (which contracts/methods your app needs)
  2. User approves policies once during connection
  3. Controller creates session with approved permissions
  4. Transactions execute seamlessly via Paymaster

With vs Without Policies

FeatureWith PoliciesWithout Policies
Transaction approvalPre-approvedManual each time
Gasless transactionsYes (Paymaster)No
Error handlingConfigurable display modesStandard modal
Best forGames, frequent txsSimple apps

Defining Policies

typescript
import { SessionPolicies } from "@cartridge/controller";

const policies: SessionPolicies = {
  contracts: {
    "0x1234...": {
      name: "My Game",
      description: "Game contract interactions",
      methods: [
        {
          name: "Move Player",
          entrypoint: "move_player",
          description: "Move player on the map",
        },
        {
          name: "Attack",
          entrypoint: "attack",
        },
      ],
    },
  },
};

const controller = new Controller({ policies });

Token Spending Limits

For 
approve
methods, specify spending limits in hex format:
typescript
const policies: SessionPolicies = {
  contracts: {
    // ETH contract
    "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7": {
      name: "Ethereum",
      methods: [
        {
          name: "approve",
          entrypoint: "approve",
          spender: "0x1234567890abcdef1234567890abcdef12345678",
          amount: "0x3", // Limit: 3 ETH (hex, accounts for decimals)
        },
      ],
    },
  },
};
  • Use 
    0xffffffffffffffffffffffffffffffff
    for unlimited (max uint128)
  • Users see USD values alongside token amounts when price data is available

Signed Message Policies

Pre-approve typed message signing:
typescript
const policies: SessionPolicies = {
  messages: [
    {
      name: "Game Message",
      types: {
        StarknetDomain: [
          { name: "name", type: "shortstring" },
          { name: "version", type: "shortstring" },
          { name: "chainId", type: "shortstring" },
          { name: "revision", type: "shortstring" },
        ],
        GameMessage: [
          { name: "content", type: "string" },
          { name: "timestamp", type: "felt" },
        ],
      },
      primaryType: "GameMessage",
      domain: {
        name: "MyGame",
        version: "1",
        chainId: "SN_MAIN",
        revision: "1",
      },
    },
  ],
};

Error Handling

Error Display Modes

typescript
const controller = new Controller({
  policies,
  errorDisplayMode: "notification", // "modal" | "notification" | "silent"
});
  • modal (default): Full error modal, blocks interaction
  • notification: Toast notification (clickable to open modal), non-blocking
  • silent: Console only, custom handling required

Error Handling Interaction

propagateSessionErrors
errorDisplayMode
Behavior
true
AnyErrors rejected immediately, no UI shown
false
(default)
modal
Opens controller modal
false
notification
Shows clickable toast
false
silent
No UI, logged to console

Error Propagation

Return errors to your app instead of showing keychain UI:
typescript
import { Controller, ResponseCodes } from "@cartridge/controller";

const controller = new Controller({
  policies,
  propagateSessionErrors: true,
});

const result = await account.execute(calls);
if (result.code === ResponseCodes.SUCCESS) {
  console.log("Tx hash:", result.transaction_hash);
} else if (result.code === ResponseCodes.ERROR) {
  console.error(result.message, result.error);
}
Note: 
SessionRefreshRequired
and 
ManualExecutionRequired
always show modal regardless of settings.

Disconnect Redirect

For mobile apps and cross-platform logout flows:
typescript
const connector = new SessionConnector({
  policies,
  rpc: "https://api.cartridge.gg/x/starknet/mainnet",
  chainId: "SN_MAIN",
  redirectUrl: "myapp://callback",
  disconnectRedirectUrl: "myapp://logout", // Where to go after logout
});

Verified Sessions

Verified policies display trust badges and streamlined approval flows. Submit configs to 
@cartridge/presets
 for verification.

SessionOptions Type

typescript
type SessionOptions = {
  rpc: string;                        // RPC endpoint URL
  chainId: string;                    // Chain ID
  policies: SessionPolicies;          // Approved transaction policies
  redirectUrl: string;                // URL to redirect after auth
  disconnectRedirectUrl?: string;     // URL to redirect after logout
  signupOptions?: AuthOptions;        // Auth methods to show
};