Getting Started
Controller implements a standard StarkNet account interface and can be seamlessly integrated into your application like any other wallet.
Quick Start
The fastest way to get started is to install the controller package and connect to Cartridge:
import Controller from "@cartridge/controller";
const controller = new Controller({});
const account = await controller.connect();
// You're ready to execute transactions!
Installation
npm install @cartridge/controller starknet
Basic Usage
Here's a simple example of how to initialize and use the controller:
import Controller from "@cartridge/controller";
import { SessionPolicies } from "@cartridge/controller";
import { constants } from "starknet";
// Define your game's session policies
const policies: SessionPolicies = {
contracts: {
"0x1234...": {
name: "My Game Contract",
methods: [
{ name: "move_player", entrypoint: "move_player" },
{ name: "attack", entrypoint: "attack" },
],
},
},
};
// Initialize the controller _with_ session policies
const controller = new Controller({
policies,
// Optional: specify the default chain
defaultChainId: constants.StarknetChainId.SN_SEPOLIA,
});
// Initialize the controller _without_ policies
// This requires manual approval for each transaction
const controller = new Controller();
// Connect to get an account instance
const account = await controller.connect();
// Execute transactions - user will see approval dialog
const tx = await account.execute([
{
contractAddress: "0x1234...",
entrypoint: "move_player",
calldata: ["0x1", "0x2"],
}
]);
Simple Controller (No Sessions)
For basic usage without session management:
import Controller from "@cartridge/controller";
// Initialize with minimal configuration
const controller = new Controller();
// Connect and use
const account = await controller.connect();
Note: When no policies are provided, each transaction requires manual user approval through the Cartridge interface. This is suitable for simple applications or testing, but games typically benefit from using session policies for a smoother experience.
Configuration with Session Policies
For games that need gasless transactions and session management:
import Controller from "@cartridge/controller";
const controller = new Controller({
policies: {
contracts: {
// Your game contract
"0x1234...": {
name: "My Game Contract",
methods: [
{
name: "move_player",
entrypoint: "move_player",
description: "Move player character",
},
{
name: "attack",
entrypoint: "attack",
description: "Attack enemy",
},
],
},
},
},
});
Usage with Starknet React
Controller Connector
import React from "react";
import { sepolia, mainnet } from "@starknet-react/chains";
import {
StarknetConfig,
jsonRpcProvider,
cartridge,
} from "@starknet-react/core";
import ControllerConnector from "@cartridge/connector/controller";
import SessionConnector from "@cartridge/connector/session";
import { SessionPolicies } from "@cartridge/controller";
import { constants } from "starknet";
// Define session policies for your game
const policies: SessionPolicies = {
contracts: {
"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7": {
methods: [
{ name: "transfer", entrypoint: "transfer" },
{ name: "approve", entrypoint: "approve" },
],
},
},
};
// Create the controller connector
const controller = new ControllerConnector({
policies,
// Optional: customize chains and default chain
chains: [
{ rpcUrl: "https://api.cartridge.gg/x/starknet/sepolia" },
{ rpcUrl: "https://api.cartridge.gg/x/starknet/mainnet" },
],
defaultChainId: constants.StarknetChainId.SN_SEPOLIA,
});
// Create the session connector for direct session management
const session = new SessionConnector({
policies,
rpc: "https://api.cartridge.gg/x/starknet/sepolia",
chainId: constants.StarknetChainId.SN_SEPOLIA,
redirectUrl: typeof window !== "undefined" ? window.location.origin : "",
});
// Configure the JSON RPC provider
const provider = jsonRpcProvider({
rpc: (chain) => {
switch (chain) {
case mainnet:
return { nodeUrl: "https://api.cartridge.gg/x/starknet/mainnet" };
case sepolia:
default:
return { nodeUrl: "https://api.cartridge.gg/x/starknet/sepolia" };
}
},
});
export function StarknetProvider({ children }: { children: React.ReactNode }) {
return (
<StarknetConfig
defaultChainId={sepolia.id}
chains={[mainnet, sepolia]}
provider={provider}
connectors={[controller, session]}
explorer={cartridge}
>
{children}
</StarknetConfig>
);
}
Session Connector
The SessionConnector
provides direct session management capabilities, allowing for more granular control over session handling:
import SessionConnector from "@cartridge/connector/session";
import { SessionPolicies } from "@cartridge/controller";
import { constants } from "starknet";
const policies: SessionPolicies = {
contracts: {
"0x1234...": {
name: "My Game Contract",
methods: [
{ name: "move_player", entrypoint: "move_player" },
{ name: "attack", entrypoint: "attack" },
],
},
},
};
const sessionConnector = new SessionConnector({
policies,
rpc: "https://api.cartridge.gg/x/starknet/sepolia",
chainId: constants.StarknetChainId.SN_SEPOLIA,
redirectUrl: typeof window !== "undefined" ? window.location.origin : "",
// Optional: specify keychain URL for custom deployments
keychainUrl: "https://x.cartridge.gg",
});
The SessionConnector is ideal for applications that need:
- Direct control over session lifecycle
- Custom session management flows
- Integration with existing authentication systems
Compatibility Guide
The following common dependencies are compatible with the latest version of Cartridge Controller (v0.10.0):
"@cartridge/arcade": "0.0.2"
"@cartridge/connector": "0.10.0"
"@cartridge/controller": "0.10.0"
"@cartridge/presets": "0.5.4"
"@dojoengine/core": "1.7.0-preview.3"
"@dojoengine/predeployed-connector": "1.7.0-preview.3"
"@dojoengine/sdk": "1.7.0-preview.3"
"@dojoengine/torii-client": "1.7.0-preview.3"
"@dojoengine/torii-wasm": "1.7.0-preview.3"
"@dojoengine/utils": "1.7.0-preview.3"
"@starknet-io/types-js": "^0.8.4"
"@starknet-react/chains": "^5.0.1"
"@starknet-react/core": "^5.0.1"
"@tailwindcss/vite": "^4.1.4"
"@types/node": "^22.13.1"
"@types/react": "^19.1.0"
"@types/react-dom": "^19.1.0"
"bignumber.js": "^9.3.0"
"lucide-react": "^0.523.0"
"prettier": "^3.6.1"
"prettier-plugin-tailwindcss": "^0.6.13"
"react": "^19.1.0"
"react-dom": "^19.1.0"
"recharts": "^3.1.0"
"sonner": "^2.0.5"
"starknet": "^8.1.2"
"starknetkit": "^v2.12.1"
"tailwindcss": "^4.1.4"
"typescript": "^5.8.3"
"vite": "^6.3.3"
"vite-plugin-wasm": "^3.4.1"
"zustand": "^5.0.3"
Migration Notes for v0.10.0
StarkNet v8 Breaking Changes
If you're using WalletAccount
directly in your application, you'll need to update the constructor call:
// Before (v0.9.x)
const account = new WalletAccount(provider, address, signer);
// After (v0.10.0)
const account = new WalletAccount({
nodeUrl: provider,
address: address,
signer: signer
});
Ethereum Wallet Integration Changes
The MetaMask SDK has been removed in favor of the EIP-6963 standard. If your application relied on MetaMask SDK-specific features:
- Wallet detection now uses EIP-6963 standard wallet detection
- All Ethereum wallets are now handled through a shared base class
- This change improves bundle size and wallet compatibility
Lodash Removal
The lodash dependency has been completely removed. If you were importing lodash utilities from this package, you'll need to replace them with custom utilities or install lodash separately in your application.
Examples
For more detailed examples of how to use Cartridge Controller in different environments, check out our integration guides:
-
- Integration with
starknet-react
- Hooks and components
- State management
- Integration with
-
- Svelte stores and reactivity
- Component lifecycle
- Event handling
-
- Native integration
- Error handling
- Async operations
Each guide provides comprehensive examples and best practices for integrating Cartridge Controller in your preferred environment.
Next Steps
- Learn about Session Keys
- Set up Multiple Signers for backup authentication
- Integrate Purchase Functionality for game monetization
- Customize your Controller
- Set up Usernames
- Configure Paymaster