Controller Setup Cartridge Controller is a gaming-focused smart contract wallet for Starknet with session keys, passkeys, and paymaster support. Installation

Basic Controller usage

pnpm add @cartridge/controller starknet

With framework connectors (React, native apps)

pnpm

add

@cartridge/controller @cartridge/connector starknet

Quick Start

import

Controller

from

"@cartridge/controller"

;

const

controller

=

new

Controller

(

)

;

const

account

=

await

controller

.

connect

(

)

;

// Ready to execute transactions

Session Policies

Session policies are

required

for session-based transaction execution.

Without policies,

execute()

fails with error code 130 because the Controller's session validation needs a merkle proof per call.

Without policies, Controller falls back to manual approval via the hosted keychain modal.

On local Katana, policies are required because new Controller accounts cannot be properly deployed without them.

Choosing a Connector

Use Case

Connector

Key Difference

Web apps with starknet-react

ControllerConnector

Keys managed via browser cookies & localStorage

Native/mobile apps

SessionConnector

App generates local keypair, authenticates via browser redirect

ControllerConnector (Web)

import

{

ControllerConnector

}

from

"@cartridge/connector"

;

const

connector

=

new

ControllerConnector

(

{

policies

,

// Session policies (required for session-based execution)

signupOptions

,

// Optional auth methods to show

}

)

;

SessionConnector (Native/Mobile)

import

{

SessionConnector

}

from

"@cartridge/connector"

;

import

{

constants

}

from

"starknet"

;

const

connector

=

new

SessionConnector

(

{

policies

,

rpc

:

"https://api.cartridge.gg/x/starknet/mainnet"

,

chainId

:

constants

.

StarknetChainId

.

SN_MAIN

,

redirectUrl

:

"myapp://auth-callback"

,

disconnectRedirectUrl

:

"myapp://logout"

,

// Optional logout redirect

signupOptions

:

[

"webauthn"

,

"google"

]

,

// Optional auth methods

}

)

;

Session flow

App generates keypair → User authenticates in browser → Browser redirects back → App signs transactions locally. Chain Configuration Default RPC endpoints are provided. Override with custom chains: import { constants } from "starknet" ; const controller = new Controller ( { chains : [ { rpcUrl : "https://api.cartridge.gg/x/starknet/mainnet" } , { rpcUrl : "https://api.cartridge.gg/x/starknet/sepolia" } , { rpcUrl : "http://localhost:5050" } , // Local Katana ] , defaultChainId : constants . StarknetChainId . SN_MAIN , } ) ; Local Development with Katana When using Controller with a local Katana instance, the Katana config must deploy Controller contracts at genesis. Without this, transactions fail with "Requested contract address ... is not deployed". Required katana.toml config: [ dev ] dev = true no_fee = true [ cartridge ] paymaster = true

Enables paymaster AND deploys Controller contracts at genesis

[

server

]

http_cors_origins

=

"*"

Note:

paymaster = true

implicitly enables

controllers = true

.

Start Katana with config:

katana

--config

katana.toml

See the

Katana configuration guide

for all TOML options.

Performance: Lazy Loading

Defer iframe mounting until

connect()

is called:

const

controller

=

new

Controller

(

{

lazyload

:

true

,

}

)

;

ControllerOptions Reference

type

ControllerOptions

=

{

chains

?

:

Chain

[

]

;

// Custom RPC endpoints

defaultChainId

?

:

string

;

// Default chain (hex encoded)

policies

?

:

SessionPolicies

;

// Session policies

propagateSessionErrors

?

:

boolean

;

// Return errors to caller

errorDisplayMode

?

:

"modal"

|

"notification"

|

"silent"

;

lazyload

?

:

boolean

;

// Defer iframe mount

preset

?

:

string

;

// Theme preset name

signupOptions

?

:

AuthOptions

;

// Auth methods to show

}

;

Package Compatibility

{

"@cartridge/connector"

:

"0.11.3-alpha.1"

,

"@cartridge/controller"

:

"0.11.3-alpha.1"

,

"@starknet-react/core"

:

"^5.0.1"

,

"@starknet-react/chains"

:

"^5.0.1"

,

"starknet"

:

"^8.1.2"

}

Common Issues

Cookies required

Controller sets essential cookies for initialization.

HTTPS required in dev

Use

vite-plugin-mkcert

for local HTTPS.

Connector outside components

Create ControllerConnector outside React components to avoid recreation on re-render.