controller-sessions
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.
How do I install this agent skill?
npx skills add https://github.com/cartridge-gg/docs --skill controller-sessionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides documentation and code examples for managing session policies and error handling within the Cartridge Controller ecosystem. It references legitimate vendor resources and follows standard integration patterns without any security risks detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
Controller Sessions & Policies
Session policies define which contracts and methods your app can call.
They are required for session-based transaction execution — without policies, execute() will fail with error code 130 ("Array length mismatch") because the Controller's on-chain session validation requires a merkle proof for each call.
Without policies, Controller falls back to manual approval via the keychain modal. On local Katana, policies are required because new Controller accounts cannot be properly deployed without them.
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
Defining Policies
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:
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
0xfffffffffffffffffffffffffffffffffor unlimited (max uint128) - Users see USD values alongside token amounts when price data is available
Signed Message Policies
Pre-approve typed message signing:
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
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:
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:
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
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
};
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/cartridge-gg/docs/controller-sessions">View controller-sessions on skillZs</a>