diff --git a/src/pages/controller/configuration.md b/src/pages/controller/configuration.md index 0283aad..972bf38 100644 --- a/src/pages/controller/configuration.md +++ b/src/pages/controller/configuration.md @@ -10,25 +10,27 @@ Controller provides several configuration options related to chains, sessions, a ## ControllerOptions ```typescript -export type ControllerOptions = { - // Provider options - chains: [ - { rpcUrl: "https://api.cartridge.gg/x/starknet/sepolia" }, - { rpcUrl: "https://api.cartridge.gg/x/starknet/mainnet" }, - ], - defaultChainId: constants.StarknetChainId.SN_SEPOLIA, +export type Chain = { + rpcUrl: string; +}; +export type ControllerOptions = { + // Chain configuration + chains?: Chain[]; // Custom RPC endpoints for slot katana instances + chainId?: string; // hex encoded + // Session options - policies?: SessionPolicies; // Session policies + policies?: SessionPolicies; // Session policies for pre-approved transactions propagateSessionErrors?: boolean; // Propagate transaction errors back to caller - - // Preset options - preset?: string; // The preset name + + // Customization options + preset?: string; // Preset name for custom themes and verified policies + slot?: string; // Slot project name for custom indexing }; ``` The configuration options are organized into several categories: -- **Provider Options**: Core RPC configuration -- [**Session Options**](/controller/sessions.md): Session and transaction related settings -- [**Preset Options**](/controller/presets.md): Configure a custom theme and verified session policies using Presets +- **Chain Options**: Core network configuration and chain settings +- [**Session Options**](/controller/sessions.md): Session policies and transaction-related settings +- **Customization Options**: [Presets](/controller/presets.md) for themes and verified policies, [Slot](/controller/inventory.md) for custom indexing diff --git a/src/pages/controller/examples/svelte.md b/src/pages/controller/examples/svelte.md index bc5cb30..dbd13c5 100644 --- a/src/pages/controller/examples/svelte.md +++ b/src/pages/controller/examples/svelte.md @@ -39,20 +39,24 @@ import { account, username } from "../stores/account"; import { ETH_CONTRACT } from "../constants"; let controller = new Controller({ - policies: [ - { - target: ETH_CONTRACT, - method: "approve", - description: - "Lorem Ipsum is simply dummy text of the printing and typesetting industry.", + policies: { + contracts: { + [ETH_CONTRACT]: { + methods: [ + { + name: "approve", + entrypoint: "approve", + description: "Approve spending of tokens", + }, + { + name: "transfer", + entrypoint: "transfer", + description: "Transfer tokens", + }, + ], + }, }, - { - target: ETH_CONTRACT, - method: "transfer", - }, - // ... other policies - ], - rpc: "https://api.cartridge.gg/x/starknet/mainnet" // sepolia, mainnet, or slot + }, }); ``` diff --git a/src/pages/controller/examples/telegram.md b/src/pages/controller/examples/telegram.md index 59250b0..fdb2dad 100644 --- a/src/pages/controller/examples/telegram.md +++ b/src/pages/controller/examples/telegram.md @@ -27,6 +27,8 @@ export const RPC_URL = "https://api.cartridge.gg/x/starknet/mainnet"; export const SESSION_POLICIES = { contracts: { "0x70fc96f845e393c732a468b6b6b54d876bd1a29e41a026e8b13579bf98eec8f": { + name: "Beast Game Contract", + description: "Contract for beast game interactions", methods: [ { name: "attack", diff --git a/src/pages/controller/getting-started.mdx b/src/pages/controller/getting-started.mdx index 3ffbce7..3da12be 100644 --- a/src/pages/controller/getting-started.mdx +++ b/src/pages/controller/getting-started.mdx @@ -8,6 +8,19 @@ title: Controller Getting Started Controller implements a standard StarkNet account interface and can be seamlessly integrated into your application like any other wallet. +## Quick Start + +The fastest way to get started is to install the controller package and connect to Cartridge: + +```ts +import Controller from "@cartridge/controller"; + +const controller = new Controller(); +const account = await controller.connect(); + +// You're ready to execute transactions! +``` + ## Installation :::code-group @@ -37,51 +50,88 @@ Here's a simple example of how to initialize and use the controller: ```ts import Controller from "@cartridge/controller"; -// Initialize the controller +// Initialize the controller with basic configuration const controller = new Controller(); // Connect to get an account instance const account = await controller.connect(); // Execute transactions -const tx = await account.execute({ - contractAddress: "0x...", - entrypoint: "my_function", - calldata: ["0x1", "0x2"], +const tx = await account.execute([ + { + contractAddress: "0x...", + entrypoint: "my_function", + calldata: ["0x1", "0x2"], + } +]); +``` + +## Configuration with Session Policies + +For games that need gasless transactions and session management: + +```ts +import Controller from "@cartridge/controller"; + +const controller = new Controller({ + policies: { + contracts: { + // Your game contract + "0x1234...": { + name: "My Game Contract", + methods: [ + { + name: "move_player", + entrypoint: "move_player", + description: "Move player character", + }, + { + name: "attack", + entrypoint: "attack", + description: "Attack enemy", + }, + ], + }, + }, + }, }); ``` ## Usage with Starknet React ```tsx -import React, { useCallback } from "react"; - +import React from "react"; import { sepolia, mainnet } from "@starknet-react/chains"; import { StarknetConfig, - publicProvider, - argent, - braavos, - useInjectedConnectors, - voyager, - Connector, jsonRpcProvider, - cartridgeProvider, + starkscan, } from "@starknet-react/core"; - -import { ControllerConnector } from "@cartridge/connector"; - -const cartridgeConnector = new ControllerConnector({ - rpc: cartridgeProvider().nodeUrl, +import ControllerConnector from "@cartridge/connector/controller"; + +// Create the connector outside the component to avoid recreation on renders +const connector = new ControllerConnector(); + +// Configure the JSON RPC provider +const provider = jsonRpcProvider({ + rpc: (chain) => { + switch (chain) { + case mainnet: + return { nodeUrl: "https://api.cartridge.gg/x/starknet/mainnet" }; + case sepolia: + default: + return { nodeUrl: "https://api.cartridge.gg/x/starknet/sepolia" }; + } + }, }); export function StarknetProvider({ children }: { children: React.ReactNode }) { return ( {children} diff --git a/src/pages/controller/overview.md b/src/pages/controller/overview.md index d98d9d5..4248721 100644 --- a/src/pages/controller/overview.md +++ b/src/pages/controller/overview.md @@ -7,11 +7,11 @@ title: Controller Overview ### TL;DR: Cartridge Controller is: -- A gaming-focused smart contract wallet -- Makes Web3 gaming accessible and fun via Session Keys -- Handles player onboarding and transaction management -- Provides identity and customization features for games -- Compatible with other wallets that implement the plugin account architecture +- A gaming-focused smart contract wallet for Starknet +- Makes Web3 gaming accessible and fun via Session Keys and gasless transactions +- Handles seamless player onboarding with Passkey authentication +- Provides identity, achievements, and customization features for games +- Compatible with popular frameworks like Starknet React and can be integrated across platforms ![Cartridge Controller Overview](/controller.png) diff --git a/src/pages/controller/sessions.md b/src/pages/controller/sessions.md index b8cdd57..9116cb7 100644 --- a/src/pages/controller/sessions.md +++ b/src/pages/controller/sessions.md @@ -5,7 +5,15 @@ description: Learn about Cartridge Controller's session-based authentication and # Sessions and Policies -Cartridge Controller supports session-based authorization and policy-based transaction approvals. When a policy is preapproved, games can perform interactions seamlessly without requesting approval from the player each time. +Cartridge Controller supports session-based authorization and policy-based transaction approvals. When policies are pre-approved by the user, games can execute transactions seamlessly without requesting approval for each interaction, creating a smooth gaming experience. + +## How Sessions Work + +1. **Policy Definition**: Games define which contract methods they need to call +2. **User Approval**: Users approve these policies once during initial connection +3. **Session Creation**: Controller creates a session with approved transaction permissions +4. **Gasless Execution**: Games can execute approved transactions without user prompts +5. **Paymaster Integration**: Transactions can be sponsored through Cartridge Paymaster ## Session Options