Skip to content

Commit ab9594b

Browse files
docs: Update documentation for controller PR #1851 (#56)
Updates documentation to reflect changes made in: Fix execute when no policies Related controller PR: cartridge-gg/controller#1851 Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 parent 6d80c75 commit ab9594b

File tree

3 files changed

+68
-3
lines changed

3 files changed

+68
-3
lines changed

src/pages/controller/configuration.md

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ export type ControllerOptions = {
2020
defaultChainId?: string; // Default chain to use (hex encoded). If using Starknet React, this gets overridden by the same param in StarknetConfig
2121

2222
// Session options
23-
policies?: SessionPolicies; // Session policies for pre-approved transactions
23+
policies?: SessionPolicies; // Optional: Session policies for pre-approved transactions
2424
propagateSessionErrors?: boolean; // Propagate transaction errors back to caller
2525

2626
// Customization options
@@ -34,3 +34,31 @@ The configuration options are organized into several categories:
3434
- **Chain Options**: Core network configuration and chain settings
3535
- [**Session Options**](/controller/sessions.md): Session policies and transaction-related settings
3636
- **Customization Options**: [Presets](/controller/presets.md) for themes and verified policies, [Slot](/controller/inventory.md) for custom indexing
37+
38+
## When to Use Policies
39+
40+
**Policies are optional** in Cartridge Controller. Choose based on your application's needs:
41+
42+
### Use Policies When:
43+
- Building games that need frequent, seamless transactions
44+
- You want gasless transactions via Cartridge Paymaster
45+
- Users should not be interrupted with approval prompts during gameplay
46+
- You need session-based authorization for better UX
47+
48+
### Skip Policies When:
49+
- Building simple applications with occasional transactions
50+
- Manual approval for each transaction is acceptable
51+
- You don't need gasless transaction capabilities
52+
- You want minimal setup complexity
53+
54+
```typescript
55+
// Without policies - simple setup, manual approvals
56+
const simpleController = new Controller();
57+
58+
// With policies - session-based, gasless transactions
59+
const sessionController = new Controller({
60+
policies: {
61+
// ... policy definitions
62+
}
63+
});
64+
```

src/pages/controller/getting-started.mdx

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,13 +50,14 @@ Here's a simple example of how to initialize and use the controller:
5050
```ts
5151
import Controller from "@cartridge/controller";
5252

53-
// Initialize the controller with basic configuration
53+
// Initialize the controller without policies
54+
// This requires manual approval for each transaction
5455
const controller = new Controller();
5556

5657
// Connect to get an account instance
5758
const account = await controller.connect();
5859

59-
// Execute transactions
60+
// Execute transactions - user will see approval dialog
6061
const tx = await account.execute([
6162
{
6263
contractAddress: "0x...",
@@ -66,6 +67,8 @@ const tx = await account.execute([
6667
]);
6768
```
6869

70+
> **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.
71+
6972
## Configuration with Session Policies
7073

7174
For games that need gasless transactions and session management:

src/pages/controller/sessions.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,40 @@ Cartridge Controller supports session-based authorization and policy-based trans
1515
4. **Gasless Execution**: Games can execute approved transactions without user prompts
1616
5. **Paymaster Integration**: Transactions can be sponsored through Cartridge Paymaster
1717

18+
## Transactions Without Policies
19+
20+
Cartridge Controller can execute transactions **without** defining policies. When no policies are provided:
21+
22+
- Each transaction requires manual user approval via the Cartridge interface
23+
- Users will see a confirmation screen for every transaction
24+
- No gasless transactions or paymaster integration
25+
- Suitable for simple applications that don't need session-based authorization
26+
27+
```typescript
28+
// Controller without policies - requires manual approval for each transaction
29+
const controller = new Controller();
30+
const account = await controller.connect();
31+
32+
// This will prompt the user for approval
33+
const tx = await account.execute([
34+
{
35+
contractAddress: "0x123...",
36+
entrypoint: "transfer",
37+
calldata: ["0x456...", "100"],
38+
}
39+
]);
40+
```
41+
42+
## Sessions vs. Manual Approval
43+
44+
| Feature | With Policies (Sessions) | Without Policies (Manual) |
45+
|---------|--------------------------|---------------------------|
46+
| Transaction Approval | Pre-approved via policies | Manual approval each time |
47+
| User Experience | Seamless gameplay | Confirmation prompts |
48+
| Gasless Transactions | Yes (via Paymaster) | No |
49+
| Setup Complexity | Higher (policy definition) | Lower (basic setup) |
50+
| Best For | Games, frequent transactions | Simple apps, occasional transactions |
51+
1852
## Session Options
1953

2054
```typescript

0 commit comments

Comments
 (0)