From 7d5ad719ccfc9e03fbd3045b25d7d70e9ee819d7 Mon Sep 17 00:00:00 2001 From: broodling-bot Date: Tue, 24 Feb 2026 20:11:18 +0000 Subject: [PATCH] docs: add starterpack command documentation Cover starterpack info, quote, and purchase subcommands across README.md, LLM_USAGE.md, skill.md, and skill README.md. Document --ui (browser with crosschain/Apple Pay support) and --direct (on-chain via Controller session) purchase modes. --- .claude/skills/controller-skill/README.md | 31 +++++++ .claude/skills/controller-skill/skill.md | 100 ++++++++++++++++++++++ LLM_USAGE.md | 59 +++++++++++++ README.md | 41 +++++++++ 4 files changed, 231 insertions(+) diff --git a/.claude/skills/controller-skill/README.md b/.claude/skills/controller-skill/README.md index 93f709f..a374ace 100644 --- a/.claude/skills/controller-skill/README.md +++ b/.claude/skills/controller-skill/README.md @@ -148,6 +148,37 @@ You can create custom policy files for your specific contracts and methods. 13. **controller_config_get** - Get a config value 14. **controller_config_list** - List all config values +### Starterpacks +15. **controller_starterpack_info** - Get starterpack metadata (name, description, items) +16. **controller_starterpack_quote** - Get price quote (payment token, fees, total cost) +17. **controller_starterpack_purchase** - Purchase a starterpack (`--ui` for browser/crosschain/Apple Pay, `--direct` for on-chain via session) + +### Starterpacks +``` +You: "What's in starterpack #1?" + +Claude: [Uses controller starterpack info 1 --chain-id SN_MAIN --json] +Claude: "Starterpack #1 'Battle Kit' contains: Sword, Shield, 100 Gold" +``` + +``` +You: "How much does it cost?" + +Claude: [Uses controller starterpack quote 1 --chain-id SN_MAIN --json] +Claude: "Total cost: 10.70 STRK (base: 10.00, fees: 0.70)" +``` + +``` +You: "Buy it for me" + +Claude: "Would you like to purchase via browser (supports crosschain/Apple Pay) or directly from your wallet?" + +You: "Browser" + +Claude: [Uses controller starterpack purchase 1 --chain-id SN_MAIN] +Claude: "Opening the purchase page — complete payment in your browser." +``` + ## Calldata Formats Calldata values support multiple formats: diff --git a/.claude/skills/controller-skill/skill.md b/.claude/skills/controller-skill/skill.md index 6deb9c8..7b69352 100644 --- a/.claude/skills/controller-skill/skill.md +++ b/.claude/skills/controller-skill/skill.md @@ -21,6 +21,7 @@ Use this skill when the user wants to: - Check transaction status or receipts - Query token balances - Look up usernames or addresses +- Query or purchase starterpacks ## Tools @@ -652,6 +653,105 @@ controller marketplace buy --order-id 42 --collection 0x123...abc --token-id 1 - --- +### controller_starterpack_info + +Get metadata for a starterpack (name, description, image, items). + +**When to use:** To display starterpack details before purchasing. + +**Input Schema:** +```json +{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "Starterpack ID (decimal or hex)" }, + "chain_id": { "type": "string", "description": "Chain ID (e.g., 'SN_MAIN' or 'SN_SEPOLIA')" }, + "rpc_url": { "type": "string", "description": "RPC URL (overrides config, conflicts with chain_id)" } + }, + "required": ["id"] +} +``` + +**Example:** +```bash +controller starterpack info 1 --chain-id SN_MAIN --json +``` + +--- + +### controller_starterpack_quote + +Get a price quote for a starterpack (payment token, fees, total cost). + +**When to use:** To check the cost before purchasing. + +**Input Schema:** +```json +{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "Starterpack ID (decimal or hex)" }, + "quantity": { "type": "number", "description": "Quantity to purchase (default: 1)", "default": 1 }, + "chain_id": { "type": "string", "description": "Chain ID (e.g., 'SN_MAIN' or 'SN_SEPOLIA')" }, + "rpc_url": { "type": "string", "description": "RPC URL (overrides config, conflicts with chain_id)" } + }, + "required": ["id"] +} +``` + +**Example:** +```bash +controller starterpack quote 1 --chain-id SN_MAIN --json +``` + +--- + +### controller_starterpack_purchase + +Purchase a starterpack via UI (browser) or directly from Controller wallet. + +**When to use:** To purchase a starterpack for the user or a recipient. + +**Input Schema:** +```json +{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "Starterpack ID (decimal or hex)" }, + "ui": { "type": "boolean", "description": "Open browser UI for purchase (default mode). Supports crosschain payments and Apple Pay." }, + "direct": { "type": "boolean", "description": "Execute purchase directly via Controller wallet session. Requires approve + issue policies." }, + "recipient": { "type": "string", "description": "Recipient address (defaults to current controller). Direct mode only." }, + "quantity": { "type": "number", "description": "Quantity to purchase (default: 1). Direct mode only.", "default": 1 }, + "chain_id": { "type": "string", "description": "Chain ID (e.g., 'SN_MAIN' or 'SN_SEPOLIA')" }, + "rpc_url": { "type": "string", "description": "RPC URL (overrides config, conflicts with chain_id)" }, + "wait": { "type": "boolean", "description": "Wait for transaction confirmation. Direct mode only.", "default": false }, + "timeout": { "type": "number", "description": "Timeout in seconds when waiting (default: 300). Direct mode only.", "default": 300 }, + "no_paymaster": { "type": "boolean", "description": "Pay gas directly instead of using paymaster. Direct mode only.", "default": false } + }, + "required": ["id"] +} +``` + +**`--ui` mode (default):** Opens `https://x.cartridge.gg/starterpack//` in the browser. The user completes payment manually. Supports crosschain payments and Apple Pay. + +**`--direct` mode:** Executes `approve` + `issue` on-chain using the active session. The session must have policies for: +- `approve` on the payment token (check via `starterpack quote`) +- `issue` on the starterpack contract (`0x3eb03b8f2be0ec2aafd186d72f6d8f3dd320dbc89f2b6802bca7465f6ccaa43`) + +**Example (UI):** +```bash +controller starterpack purchase 1 --chain-id SN_MAIN +controller starterpack purchase 1 --ui --chain-id SN_MAIN +``` + +**Example (direct):** +```bash +controller starterpack purchase 1 --direct --chain-id SN_MAIN --json +controller starterpack purchase 1 --direct --recipient 0xABC... --quantity 2 --wait --json +``` + +--- + ## Calldata Formats Calldata values support multiple formats: diff --git a/LLM_USAGE.md b/LLM_USAGE.md index 764cd03..8b8fd74 100644 --- a/LLM_USAGE.md +++ b/LLM_USAGE.md @@ -45,6 +45,9 @@ Once installed, tools become available: - `controller_username` - Get account username - `controller_lookup` - Look up usernames/addresses - `controller_config` - Manage CLI configuration +- `controller_starterpack_info` - Get starterpack metadata +- `controller_starterpack_quote` - Get starterpack price quote +- `controller_starterpack_purchase` - Purchase a starterpack (UI or direct) **See:** [Skill Documentation](./.claude/skills/controller-skill/README.md) @@ -366,6 +369,62 @@ controller config list --json Valid keys: `rpc-url`, `keychain-url`, `api-url`, `storage-path`, `json-output`, `colors`, `callback-timeout`, `token.`. +### 12. Starterpacks + +Query starterpack info, get price quotes, and purchase starterpacks. + +**Get starterpack metadata:** +```bash +controller starterpack info --chain-id SN_MAIN --json +``` + +**Get a price quote:** +```bash +controller starterpack quote --chain-id SN_MAIN --json +``` + +Output: +```json +{ + "starterpack_id": "1", + "chain_id": "SN_MAIN", + "payment_token": "0x04718f...", + "base_price": "10.000000", + "referral_fee": "0.500000", + "protocol_fee": "0.200000", + "total_cost": "10.700000" +} +``` + +**Purchase via UI (default — opens browser):** +```bash +controller starterpack purchase --chain-id SN_MAIN +# or explicitly: +controller starterpack purchase --ui --chain-id SN_MAIN +``` + +Opens `https://x.cartridge.gg/starterpack//` in the user's browser. The UI supports crosschain payments and Apple Pay — use this when the user wants flexible payment options or doesn't have an active session. + +**Purchase directly via Controller wallet:** +```bash +controller starterpack purchase --direct --chain-id SN_MAIN --json +``` + +Executes `approve` + `issue` on-chain using the active session. Requires session policies that include: +- `approve` on the payment token (returned by `quote`) +- `issue` on the starterpack contract (`0x3eb03b8f2be0ec2aafd186d72f6d8f3dd320dbc89f2b6802bca7465f6ccaa43`) + +Additional flags for `--direct`: +- `--recipient
` — Purchase for a different address (defaults to controller) +- `--quantity ` — Number to purchase (default: 1) +- `--wait` — Wait for transaction confirmation +- `--timeout ` — Timeout when waiting (default: 300) +- `--no-paymaster` — Pay gas directly instead of using paymaster + +**When to use `--ui` vs `--direct`:** +- `--ui` (default): User wants crosschain payment, Apple Pay, or doesn't have a session with the right policies +- `--direct`: Automated/scripted purchases where the session already has `approve` + `issue` policies authorized + --- ### 12. Marketplace Commands diff --git a/README.md b/README.md index 50c6e46..8837eeb 100644 --- a/README.md +++ b/README.md @@ -253,6 +253,47 @@ MYTOKEN = "0x123..." | `CARTRIDGE_RPC_URL` | Default RPC endpoint | | `CARTRIDGE_JSON_OUTPUT` | Default to JSON output | +### 11. Starterpacks + +Query and purchase starterpacks (bundled game assets). + +**Get info:** + +```bash +controller starterpack info --chain-id SN_MAIN +``` + +**Get a price quote:** + +```bash +controller starterpack quote --chain-id SN_MAIN +``` + +**Purchase via UI (default):** + +```bash +controller starterpack purchase --chain-id SN_MAIN +# or explicitly: +controller starterpack purchase --ui --chain-id SN_MAIN +``` + +Opens the Cartridge purchase page in your browser. Supports crosschain payments and Apple Pay. + +**Purchase directly from Controller wallet:** + +```bash +controller starterpack purchase --direct --chain-id SN_MAIN --json +``` + +Executes the purchase on-chain using the active session. Requires session policies that include `approve` on the payment token and `issue` on the starterpack contract. + +Additional flags for `--direct` mode: +- `--recipient
` — Send to a different address (defaults to current controller) +- `--quantity ` — Number to purchase (default: 1) +- `--wait` — Wait for transaction confirmation +- `--timeout ` — Confirmation timeout (default: 300) +- `--no-paymaster` — Pay gas with user funds instead of paymaster + ## Architecture Built on [`account_sdk`](https://github.com/cartridge-gg/controller-rs) which provides session management, transaction execution, policy validation, and file-based storage. The CLI is a thin wrapper optimized for automation and scripting.