Cartridge Controller

Overview

Cartridge Controller is specialized for gaming applications and provides a powerful abstraction layer for managing account access and ownership on Starknet. Cartridge enables:

Social Login: Users can sign in with social accounts (Google, Twitter, etc.)
Passkey Authentication: Biometric authentication (Face ID, Touch ID, Windows Hello)
Policy-Based Access: Define policies for what contracts/methods can be called
Delegated Transactions: Users can approve transactions without managing keys directly
Built-in Paymaster: Policy-bound sponsorship — Cartridge can sponsor fees for calls that match approved policies (and eligible session / SNIP-9 paths), not every arbitrary transaction.

Starkzap integrates with Cartridge for gaming-style flows: web uses @cartridge/controller; React Native / Expo uses starkzap-native with a native session adapter (register it before connecting) when your package version supports native Cartridge.

StarkZap integration

When StarkZap connects Cartridge, it forwards your SDK network configuration (for example rpcUrl and chainId) into the Cartridge flow so you typically configure the network once on new StarkZap(...).

Network alignment is not auto-validated. You must use the same rpcUrl / chainId (or network preset) you intend the Cartridge session and paymaster to target. The SDK forwards these values but does not verify that some other tab, deep link, or preset was opened on a different chain. Mismatches often show up as SNIP-9 or paymaster errors.

You do not need to pass chain settings again when calling sdk.connectCartridge() or sdk.onboard({ strategy: "cartridge" }) on the same StarkZap instance.

Web (browser) vs React Native

	Web	React Native / Expo
Package	`starkzap` + `@cartridge/controller`	`starkzap-native` (depends on `starkzap`)
UX	Controller popup / embedded flow	In-app browser / deep link session flow
Before connect	Install `@cartridge/controller`	React Native setup: Metro `withStarkzap`, register the native Cartridge adapter when your SDK version exports it
Import	`import { StarkZap } from "starkzap"`	`import { StarkZap } from "starkzap-native"`

React Native / Expo (native Cartridge session)

Follow React Native Integration for Metro (withStarkzap) and dependencies.
Register the native Cartridge adapter once at startup before connectCartridge / onboard({ strategy: "cartridge" }) (for example registerCartridgeTsAdapter / registerCartridgeNativeAdapter — exact exports depend on your starkzap-native version).
Pass policies and/or a Cartridge preset that resolves policies for your chain.
Onboarding: native Cartridge often defaults to deploy: "never" or recommends it when deployment differs from the browser Controller; pass deploy: "if_needed" explicitly if you need core-style deployment checks.
Sponsored execution on native is tied to the session wallet (commonly feeMode: "sponsored" only).

See the examples/tic-tac-toe app in the Starkzap repository when available for a full Expo reference.

Why Use Cartridge?

✅ Perfect for Gaming: Specialized for gaming applications with session-based transactions
✅ Gasless-style UX for approved calls: Built-in paymaster can sponsor policy-matching transactions after users approve policies
✅ Better UX: No seed phrases or private key management
✅ Social Login: Users sign in with familiar accounts (Google, Twitter, etc.)
✅ Biometric Auth: Face ID, Touch ID, Windows Hello support
✅ Policy Control: Define what contracts/methods users can interact with
✅ Session Management: Users approve policies once, then transactions happen automatically

Key value: Unlike Privy or private-key flows (which often use AVNU Paymaster for sponsorship), Cartridge can sponsor policy-approved calls through its paymaster/session stack—so matching game or token operations stay gasless after users approve policies. Other calls may still require user fees or extra steps.

Setup (web browser)

1. Install Cartridge Controller

For web, install the Controller peer used by starkzap:

npm install @cartridge/controller

2. Initialize SDK

import { StarkZap, OnboardStrategy } from "starkzap";

const sdk = new StarkZap({ network: "mainnet" });

Integration (web)

Basic Connection

Connect a wallet using Cartridge Controller. Define policies that specify what contracts/methods can be called, and all matching transactions will be automatically sponsored (gasless) by Cartridge’s built-in paymaster:

const onboard = await sdk.onboard({
  strategy: OnboardStrategy.Cartridge,
  cartridge: {
    policies: [
      {
        target: "0xTOKEN_CONTRACT",
        method: "transfer",
      },
      {
        target: "0xGAME_CONTRACT",
        method: "play_card",
      },
    ],
  },
  deploy: "if_needed",
});

const wallet = onboard.wallet;

Using Policies

Policies define what contracts and methods can be called in paymastered transactions. Users approve these policies once when connecting, and then all transactions matching those policies are automatically sponsored by Cartridge’s paymaster:

const policies = [
  // Allow transfers from a specific token contract
  {
    target: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d", // STRK
    method: "transfer",
  },
  // Allow game operations
  {
    target: "0xGAME_CONTRACT",
    method: "play_card",
  },
  {
    target: "0xGAME_CONTRACT",
    method: "claim_rewards",
  },
  // Allow staking operations
  {
    target: "0xSTAKING_CONTRACT",
    method: "enter_delegation_pool",
  },
];

const wallet = await sdk.connectCartridge({ policies });

// All transactions matching these policies are automatically paymastered
// No user approval needed for individual transactions

Session Registration

When users connect and approve policies, a session is automatically registered. For paymastered transactions, sessions can be registered without requiring additional signatures—the initial policy approval is sufficient. This enables seamless, gasless transaction execution:

// User connects and approves policies
const onboard = await sdk.onboard({
  strategy: OnboardStrategy.Cartridge,
  cartridge: { policies },
});

// Session is automatically registered
// All transactions matching policies are paymastered automatically
const wallet = onboard.wallet;

// Execute transactions - no approval prompts, no gas fees
await wallet.execute([call]);

Accessing Controller Features

Get access to Cartridge-specific features:

const wallet = await sdk.connectCartridge({ policies });

// Access the controller
const controller = wallet.getController();

// Open user profile
controller.openProfile();

// Check if user is authenticated
const isAuthenticated = controller.isAuthenticated();

Complete Example

import { StarkZap, OnboardStrategy, Amount, fromAddress, mainnetTokens } from "starkzap";

const sdk = new StarkZap({ network: "mainnet" });

// Define policies for what the user can do
// All transactions matching these policies will be automatically paymastered
const policies = [
  {
    target: mainnetTokens.STRK.address,
    method: "transfer",
  },
  {
    target: "0xGAME_CONTRACT",
    method: "play_card",
  },
];

// Connect with Cartridge
// User approves policies once, session is registered automatically
const onboard = await sdk.onboard({
  strategy: OnboardStrategy.Cartridge,
  cartridge: { policies },
  deploy: "if_needed",
});

const wallet = onboard.wallet;

// Use the wallet like any other
const balance = await wallet.balanceOf(mainnetTokens.STRK);
console.log(`Balance: ${balance.toFormatted()}`);

// Transfer tokens - automatically paymastered (no approval, no gas fees)
// Because it matches the approved policy
const tx = await wallet.transfer(mainnetTokens.STRK, [
  {
    to: fromAddress("0xRECIPIENT"),
    amount: Amount.parse("10", mainnetTokens.STRK),
  },
]);

await tx.wait();
console.log("Transfer complete! (Gas paid by Cartridge)");

User Flow (web)

User clicks “Connect with Cartridge”
Cartridge popup appears with social login options
User signs in with Google, Twitter, or passkey
Wallet is created and connected automatically
User approves policies - Defines what contracts/methods can be called
Session is registered - Automatically registered for paymastered transactions
Transactions execute automatically - All transactions matching policies are paymastered (gasless) without additional approval

Policy Management

How Policies Work with Paymaster

Policies serve two purposes:

Security: Define what contracts/methods can be called
Paymaster eligibility: Only transactions matching policies are automatically paymastered

When a transaction matches an approved policy, it’s automatically sponsored by Cartridge’s paymaster. Transactions outside the policies require user approval and may not be paymastered.

Dynamic Policies

You can update policies based on user actions. Note that updating policies requires reconnection and user approval:

// Initial connection with basic policies
const wallet = await sdk.connectCartridge({
  policies: [
    { target: TOKEN_ADDRESS, method: "transfer" },
  ],
});

// Later, add more policies (requires reconnection and user approval)
const updatedWallet = await sdk.connectCartridge({
  policies: [
    { target: TOKEN_ADDRESS, method: "transfer" },
    { target: GAME_ADDRESS, method: "play_card" },
    { target: STAKING_ADDRESS, method: "enter_delegation_pool" },
  ],
});

// New session is registered with expanded policies
// All matching transactions are automatically paymastered

Policy Best Practices

Be specific: Only allow the methods users actually need
Start minimal: Begin with basic policies, add more as needed
Explain policies: Let users know what they’re approving and that matching transactions will be gasless
Group related operations: Put related game actions in the same policy set
Review regularly: Update policies based on user feedback and game features

Error Handling

try {
  const wallet = await sdk.connectCartridge({ policies });
} catch (error) {
  if (error.message.includes("popup")) {
    console.error("User blocked popup or closed window");
  } else if (error.message.includes("authentication")) {
    console.error("Authentication failed");
  } else {
    console.error("Connection failed:", error);
  }
}

Resources

Best Practices

Request minimal permissions - Only ask for what users need
Handle popup blockers - Guide users if popups are blocked
Provide clear instructions - Explain the connection process
Test on multiple browsers - Ensure compatibility
Monitor user experience - Track connection success rates

Getting Started

Configuration

Using LLMs

Modules

Integrations

Examples

Reference

Overview

StarkZap integration

Web (browser) vs React Native

React Native / Expo (native Cartridge session)

Why Use Cartridge?

Setup (web browser)

1. Install Cartridge Controller

2. Initialize SDK

Integration (web)

Basic Connection

Using Policies

Session Registration

Accessing Controller Features

Complete Example

User Flow (web)

Policy Management

How Policies Work with Paymaster

Dynamic Policies

Policy Best Practices

Error Handling

Resources

Best Practices

Getting Started

Configuration

Using LLMs

Modules

Integrations

Examples

Reference

​Overview

​StarkZap integration

​Web (browser) vs React Native

​React Native / Expo (native Cartridge session)

​Why Use Cartridge?

​Setup (web browser)

​1. Install Cartridge Controller

​2. Initialize SDK

​Integration (web)

​Basic Connection

​Using Policies

​Session Registration

​Accessing Controller Features

​Complete Example

​User Flow (web)

​Policy Management

​How Policies Work with Paymaster

​Dynamic Policies

​Policy Best Practices

​Error Handling

​Resources

​Best Practices

Overview

StarkZap integration

Web (browser) vs React Native

React Native / Expo (native Cartridge session)

Why Use Cartridge?

Setup (web browser)

1. Install Cartridge Controller

2. Initialize SDK

Integration (web)

Basic Connection

Using Policies

Session Registration

Accessing Controller Features

Complete Example

User Flow (web)

Policy Management

How Policies Work with Paymaster

Dynamic Policies

Policy Best Practices

Error Handling

Resources

Best Practices