Controller Sessions & Policies

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

How Sessions Work

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

With vs Without Policies

Feature	With Policies	Without Policies
Transaction approval	Pre-approved	Manual each time
Gasless transactions	Yes (Paymaster)	No
Error handling	Configurable display modes	Standard modal
Best for	Games, frequent txs	Simple 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`	Any	Errors 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
};