Integrating the Cartridge Controller

Overview

This guide provides a complete implementation for integrating the Cartridge Controller into your Scaffold-Stark project, enabling advanced wallet connections.

Crucial Notes Before Implementation

• The Cartridge Controller cannot be used in localhost environments without relying on ngrok or other alternatives. Additionally, developers must use Katana or Slot.
• This guide focuses only on Sepolia and Mainnet deployments and integration with Vercel.

Implementation Guide

1. Add Controller Dependency

Update your packages/nextjs/package.json to include the Cartridge dependency:

nextjs/package.json

{
  "dependencies": {
    "@cartridge/connector": "^0.5.7"
  }
}

2. Create Controller Configuration

Create a new file index.tsx in nextjs/services/web3/controller/index.tsx. You can also review different configurations in the Cartridge Controller documentation to understand how to integrate policies or sessions and other powerful features, especially for gaming or UX improvements.

View full code

utils/scaffold-stark/controller.tsx

"use client";

import ControllerConnector from "@cartridge/connector/controller";
import { constants } from "starknet";
import scaffoldConfig from "~~/scaffold.config";
import { SessionPolicies } from "@cartridge/controller";

// Standard contract addresses
export const ETH_CONTRACT_ADDRESS = "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
export const STRK_CONTRACT_ADDRESS = "0x04718f5a0Fc34cC1AF16A1cdee98fFB20C31f5cD61D6Ab07201858f4287c938D";

// Supported chains configuration
const chains = [
  {
    id: constants.StarknetChainId.SN_SEPOLIA,
    name: "Sepolia",
    rpcUrl: process.env.NEXT_PUBLIC_RPC_SEPOLIA ?? "https://api.cartridge.gg/x/starknet/sepolia",
  },
  {
    id: constants.StarknetChainId.SN_MAIN,
    name: "Mainnet",
    rpcUrl: process.env.NEXT_PUBLIC_RPC_MAINNET ?? "https://api.cartridge.gg/x/starknet/mainnet",
  },
];

// Session policies for contracts
const policies: SessionPolicies = {
  contracts: {
    [ETH_CONTRACT_ADDRESS]: {
      methods: [
        { name: "approve", entrypoint: "approve" },
        { name: "transfer", entrypoint: "transfer" },
      ],
    },
    [STRK_CONTRACT_ADDRESS]: {
      methods: [
        { name: "approve", entrypoint: "approve" },
        { name: "transfer", entrypoint: "transfer" },
      ],
    },
  },
};

// Create Cartridge Controller instance
export const controllerInstance = new ControllerConnector({
  policies,
  defaultChainId: constants.StarknetChainId.SN_SEPOLIA,
  chains: chains,
  url: process.env.NEXT_PUBLIC_KEYCHAIN_DEPLOYMENT_URL,
  profileUrl: process.env.NEXT_PUBLIC_PROFILE_DEPLOYMENT_URL,
});

3. Register Controller as an Extra Wallet

In Scaffold-Stark v3, wallets are auto-discovered via the wallet standard (get-starknet). For wallets that don't implement the standard natively, you can pass them via the extraWallets prop to StarknetConfig.

Update services/web3/connectors.tsx to export the Controller as an extra wallet:

View changes

nextjs/services/web3/connectors.tsx

import { controllerInstance } from "~~/services/web3/controller/index";

// Add Cartridge Controller as an extra wallet for non-devnet networks
const extraWallets = [];
if (!targetNetworks.some(network => (network.network as string) === "devnet")) {
  extraWallets.push(controllerInstance);
}

export { extraWallets };

Then pass extraWallets to your StarknetConfig provider:

<StarknetConfig extraWallets={extraWallets} ...>
  {children}
</StarknetConfig>

Wallet Standard

If the Cartridge Controller implements WalletWithStarknetFeatures from the wallet standard, it will be auto-discovered and you don't need to pass it as an extra wallet. Check the Cartridge Controller documentation for the latest compatibility information.

4. Configure Deployment Settings

Update Network Configuration

Modify scaffold.config.ts to target sepolia or mainnet:

scaffold.config.ts

const scaffoldConfig = {
  targetNetworks: [chains.sepolia],
};

Prepare for Deployment

To deploy your application, install Vercel and log in:

yarn install -g vercel
vercel login
yarn vercel

If you want to deploy without pre-checks, use:

yarn vercel:yolo

For more details, refer to the Vercel deployment guide. If you need to disable type linting checks, see Disabling Type Checks.