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: Automatic gasless transactions - Cartridge sponsors (pays for) all transaction fees automatically

Starkzap integrates seamlessly with Cartridge Controller, making it perfect for gaming applications where you want seamless, gasless transactions.

Why Use Cartridge?

✅ Perfect for Gaming: Specialized for gaming applications with session-based transactions
✅ Automatic Gasless Transactions: Built-in paymaster sponsors all transactions—users never pay gas fees
✅ 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 Proposition: Unlike Privy or Private Key strategies (which require separate AVNU Paymaster configuration), Cartridge includes a built-in paymaster that automatically sponsors all transactions. This means users never see gas fees or need to approve individual transactions—perfect for gaming where you want seamless, uninterrupted gameplay.

Setup

1. Install Cartridge Controller

The Cartridge Controller is included as a peer dependency of Starkzap:

npm install @cartridge/controller

2. Initialize SDK

import { StarkZap, OnboardStrategy } from "starkzap";

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

Integration

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

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

Why Use Cartridge?

Setup

1. Install Cartridge Controller

2. Initialize SDK

Integration

Basic Connection

Using Policies

Session Registration

Accessing Controller Features

Complete Example

User Flow

Policy Management

How Policies Work with Paymaster

Dynamic Policies

Policy Best Practices

Error Handling

Resources

Best Practices

​Overview

​Why Use Cartridge?

​Setup

​1. Install Cartridge Controller

​2. Initialize SDK

​Integration

​Basic Connection

​Using Policies

​Session Registration

​Accessing Controller Features

​Complete Example

​User Flow

​Policy Management

​How Policies Work with Paymaster

​Dynamic Policies

​Policy Best Practices

​Error Handling

​Resources

​Best Practices

Overview

Why Use Cartridge?

Setup

1. Install Cartridge Controller

2. Initialize SDK

Integration

Basic Connection

Using Policies

Session Registration

Accessing Controller Features

Complete Example

User Flow

Policy Management

How Policies Work with Paymaster

Dynamic Policies

Policy Best Practices

Error Handling

Resources

Best Practices