Skip to main content

​
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

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

​
Policy Management

​
How Policies Work with Paymaster

Policies serve two purposes:
  1. Security: Define what contracts/methods can be called
  2. 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

  1. Be specific: Only allow the methods users actually need
  2. Start minimal: Begin with basic policies, add more as needed
  3. Explain policies: Let users know what they’re approving and that matching transactions will be gasless
  4. Group related operations: Put related game actions in the same policy set
  5. 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

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