diff --git a/src/pages/controller/configuration.md b/src/pages/controller/configuration.md index 972bf38..efb0072 100644 --- a/src/pages/controller/configuration.md +++ b/src/pages/controller/configuration.md @@ -20,7 +20,7 @@ export type ControllerOptions = { chainId?: string; // hex encoded // Session options - policies?: SessionPolicies; // Session policies for pre-approved transactions + policies?: SessionPolicies; // Optional: Session policies for pre-approved transactions propagateSessionErrors?: boolean; // Propagate transaction errors back to caller // Customization options @@ -34,3 +34,31 @@ The configuration options are organized into several categories: - **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 + +## When to Use Policies + +**Policies are optional** in Cartridge Controller. Choose based on your application's needs: + +### Use Policies When: +- Building games that need frequent, seamless transactions +- You want gasless transactions via Cartridge Paymaster +- Users should not be interrupted with approval prompts during gameplay +- You need session-based authorization for better UX + +### Skip Policies When: +- Building simple applications with occasional transactions +- Manual approval for each transaction is acceptable +- You don't need gasless transaction capabilities +- You want minimal setup complexity + +```typescript +// Without policies - simple setup, manual approvals +const simpleController = new Controller(); + +// With policies - session-based, gasless transactions +const sessionController = new Controller({ + policies: { + // ... policy definitions + } +}); +``` diff --git a/src/pages/controller/getting-started.mdx b/src/pages/controller/getting-started.mdx index 91f08f0..f944139 100644 --- a/src/pages/controller/getting-started.mdx +++ b/src/pages/controller/getting-started.mdx @@ -50,13 +50,14 @@ Here's a simple example of how to initialize and use the controller: ```ts import Controller from "@cartridge/controller"; -// Initialize the controller with basic configuration +// Initialize the controller without policies +// This requires manual approval for each transaction const controller = new Controller(); // Connect to get an account instance const account = await controller.connect(); -// Execute transactions +// Execute transactions - user will see approval dialog const tx = await account.execute([ { contractAddress: "0x...", @@ -66,6 +67,8 @@ const tx = await account.execute([ ]); ``` +> **Note:** When no policies are provided, each transaction requires manual user approval through the Cartridge interface. This is suitable for simple applications or testing, but games typically benefit from using [session policies](#configuration-with-session-policies) for a smoother experience. + ## Configuration with Session Policies For games that need gasless transactions and session management: diff --git a/src/pages/controller/sessions.md b/src/pages/controller/sessions.md index 9116cb7..1cf9c77 100644 --- a/src/pages/controller/sessions.md +++ b/src/pages/controller/sessions.md @@ -15,6 +15,40 @@ Cartridge Controller supports session-based authorization and policy-based trans 4. **Gasless Execution**: Games can execute approved transactions without user prompts 5. **Paymaster Integration**: Transactions can be sponsored through Cartridge Paymaster +## Transactions Without Policies + +Cartridge Controller can execute transactions **without** defining policies. When no policies are provided: + +- Each transaction requires manual user approval via the Cartridge interface +- Users will see a confirmation screen for every transaction +- No gasless transactions or paymaster integration +- Suitable for simple applications that don't need session-based authorization + +```typescript +// Controller without policies - requires manual approval for each transaction +const controller = new Controller(); +const account = await controller.connect(); + +// This will prompt the user for approval +const tx = await account.execute([ + { + contractAddress: "0x123...", + entrypoint: "transfer", + calldata: ["0x456...", "100"], + } +]); +``` + +## Sessions vs. Manual Approval + +| Feature | With Policies (Sessions) | Without Policies (Manual) | +|---------|--------------------------|---------------------------| +| Transaction Approval | Pre-approved via policies | Manual approval each time | +| User Experience | Seamless gameplay | Confirmation prompts | +| Gasless Transactions | Yes (via Paymaster) | No | +| Setup Complexity | Higher (policy definition) | Lower (basic setup) | +| Best For | Games, frequent transactions | Simple apps, occasional transactions | + ## Session Options ```typescript