Back to Details

controller-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Controller Setup

Controller 设置

Cartridge Controller is a gaming-focused smart contract wallet for Starknet with session keys, passkeys, and paymaster support.
Cartridge Controller是一款面向游戏场景的Starknet智能合约钱包，支持会话密钥、通行密钥以及Paymaster功能。

Installation

安装

bash
undefined
bash
undefined

Basic Controller usage

Basic Controller usage

pnpm add @cartridge/controller starknet
pnpm add @cartridge/controller starknet

With framework connectors (React, native apps)

With framework connectors (React, native apps)

pnpm add @cartridge/controller @cartridge/connector starknet
undefined
pnpm add @cartridge/controller @cartridge/connector starknet
undefined

Quick Start

快速开始

typescript
import Controller from "@cartridge/controller";

const controller = new Controller();
const account = await controller.connect();
// Ready to execute transactions
typescript
import Controller from "@cartridge/controller";

const controller = new Controller();
const account = await controller.connect();
// Ready to execute transactions

When to Use Policies

何时使用策略

Policies are optional. Choose based on your needs:
  • Use policies: Games needing frequent, seamless transactions with gasless execution via Paymaster
  • Skip policies: Simple apps where manual approval per transaction is acceptable
策略为可选功能。可根据需求选择：
  • 使用策略：需要频繁、无缝交易，且通过Paymaster实现无gas执行的游戏应用
  • 跳过策略：接受每笔交易手动授权的简单应用

Choosing a Connector

选择连接器

Use CaseConnectorKey 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
使用场景连接器核心差异
使用starknet-react的Web应用
ControllerConnector
通过浏览器Cookie与localStorage管理密钥
原生/移动应用
SessionConnector
应用生成本地密钥对，通过浏览器重定向完成认证

ControllerConnector (Web)

ControllerConnector（Web端）

typescript
import { ControllerConnector } from "@cartridge/connector";

const connector = new ControllerConnector({
  policies,              // Optional session policies
  signupOptions,         // Optional auth methods to show
});
typescript
import { ControllerConnector } from "@cartridge/connector";

const connector = new ControllerConnector({
  policies,              // Optional session policies
  signupOptions,         // Optional auth methods to show
});

SessionConnector (Native/Mobile)

SessionConnector（原生/移动端）

typescript
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.
typescript
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
});
会话流程：应用生成密钥对 → 用户在浏览器中完成认证 → 浏览器重定向回应用 → 应用本地签署交易。

Chain Configuration

链配置

Default RPC endpoints are provided. Override with custom chains:
typescript
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,
});
默认提供RPC端点。可通过自定义链进行覆盖：
typescript
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,
});

Performance: Lazy Loading

性能优化：懒加载

Defer iframe mounting until 
connect()
is called:
typescript
const controller = new Controller({
  lazyload: true,
});
延迟iframe挂载，直到调用
connect()
方法：
typescript
const controller = new Controller({
  lazyload: true,
});

ControllerOptions Reference

ControllerOptions 参考

typescript
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
};
typescript
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

包兼容性

json
{
  "@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"
}
json
{
  "@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.
需要Cookie支持：Controller会设置必要的Cookie以完成初始化。
开发环境需HTTPS：使用
vite-plugin-mkcert
实现本地HTTPS。
在组件外部创建Connector：在React组件外部创建
ControllerConnector
，避免重渲染时重复创建。