Loading...
Loading...
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.
npx skill4agent add cartridge-gg/docs controller-sessions| 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 |
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 });approveconst policies: SessionPolicies = {
contracts: {
// ETH contract
"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7": {
name: "Ethereum",
methods: [
{
name: "approve",
entrypoint: "approve",
spender: "0x1234567890abcdef1234567890abcdef12345678",
amount: "0x3", // Limit: 3 ETH (hex, accounts for decimals)
},
],
},
},
};0xffffffffffffffffffffffffffffffffconst 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",
},
},
],
};const controller = new Controller({
policies,
errorDisplayMode: "notification", // "modal" | "notification" | "silent"
}); | | Behavior |
|---|---|---|
| Any | Errors rejected immediately, no UI shown |
| | Opens controller modal |
| | Shows clickable toast |
| | No UI, logged to console |
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);
}SessionRefreshRequiredManualExecutionRequiredconst 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
});@cartridge/presetstype 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
};