Sessions and Policies
Cartridge Controller supports session-based authorization and policy-based transaction approvals. When a policy is preapproved, games can perform interactions seamlessly without requesting approval from the player each time.
Session Options
export type SessionOptions = {
rpc: string; // RPC endpoint URL
chainId: string; // Chain ID for the session
policies: SessionPolicies; // Approved transaction policies
redirectUrl: string; // URL to redirect after registration
};
Defining Policies
Policies allow your application to define permissions that can be pre-approved by the user:
type SessionPolicies = {
contracts: {
[address: string]: ContractPolicy; // Contract interaction policies
};
messages?: TypedDataMessage[]; // Optional signed message policies
};
type ContractPolicy = {
name?: string; // Human-readable name of the contract
description?: string; // Description of the contract
methods: Method[]; // Allowed contract methods
};
type ContractMethod = {
name: string; // Method name
entrypoint: string; // Contract method entrypoint
description?: string; // Optional method description
};
type SignMessagePolicy = TypedDataPolicy & {
name?: string; // Human-readable name of the policy
description?: string; // Description of the policy
};
type TypedDataPolicy = {
types: Record<string, StarknetType[]>;
primaryType: string;
domain: StarknetDomain;
};
Usage Examples
Contract Interaction Policies Example
const policies: SessionPolicies = {
contracts: {
"0x4ed3a7c5f53c6e96186eaf1b670bd2e2a3699c08e070aedf4e5fc6ac246ddc1": {
name: "Pillage",
description: "Allows you to raid a structure and pillage resources",
methods: [
{
name: "Battle Pillage",
description: "Pillage a structure",
entrypoint: "battle_pillage"
}
]
},
"0x2620f65aa2fd72d705306ada1ee7410023a3df03da9291f1ccb744fabfebc0": {
name: "Battle contract",
description: "Required to engage in battles",
methods: [
{
name: "Battle Start",
description: "Start a battle",
entrypoint: "battle_start"
},
{
name: "Battle Join",
description: "Join a battle",
entrypoint: "battle_join"
},
{
name: "Battle Leave",
description: "Leave a battle",
entrypoint: "battle_leave"
},
]
},
// Include other contracts as needed
}
};
// Using the controller directly
const controller = new Controller({
policies,
// other options
});
// Using starknet-react connector
const connector = new CartridgeConnector({
policies,
// other options
});
Signed Message Policy Example
Signed Message policies allow the application to sign a typed message without manual approval from the user.
const policies: SessionPolicies = {
messages: [
{
name: "Eternum Message Signing",
description: "Allows signing messages for Eternum",
types: {
StarknetDomain: [
{ name: "name", type: "shortstring" },
{ name: "version", type: "shortstring" },
{ name: "chainId", type: "shortstring" },
{ name: "revision", type: "shortstring" }
],
"s0_eternum-Message": [
{ name: "identity", type: "ContractAddress" },
{ name: "channel", type: "shortstring" },
{ name: "content", type: "string" },
{ name: "timestamp", type: "felt" },
{ name: "salt", type: "felt" }
]
},
primaryType: "s0_eternum-Message",
domain: {
name: "Eternum",
version: "1",
chainId: "SN_MAIN",
revision: "1"
}
}
]
};
Verified Sessions
Verified session policies provide a better user experience by attesting to the validity of a games session policy configuration, providing confidence to it's players.
Verified configs can be committed to the configs
folder in @cartridge/presets
.
Before they are merged, the team will need to collaborate with Cartridge to verify the policies.