diff --git a/CHANGELOG.md b/CHANGELOG.md index f0ec973..4c32ae1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to the BitBadges Claude Code plugin will be documented in th ## [Unreleased] +### Changed +- `query/SKILL.md` — description now lists the standards surface (auctions, crowdfunds, payment-requests, intents, smart-tokens, etc) alongside the raw API routes. Added a "Standards shortcuts" section pointing Claude at `bitbadges-cli list / show / status` as the preferred route over `bitbadges-cli api ...` when the user asks about a standard by name. API route count bumped from 104 → 106 (SDK #223 + #228 added 27+ indexer routes including consolidated `/swap/*` and gamm queries). +- `broadcast/SKILL.md` — added a fifth signing path (`deploy --with-keyring --from `) for headless CLI-only flows that already have a key in the chain binary's keyring; the CLI prints + runs the equivalent `bitbadgeschaind tx ...` so users see what's being signed. Added a top-level note about `--wait-for-indexer [timeout-ms]` for agent scripts that immediately need to query the newly-created entity. + ### Added - Initial scaffolding: plugin manifest, MCP server registration, README, LICENSE. - 8 skills, all hand-written as routing guides on top of the CLI / MCP / docs (no duplicated SDK content): diff --git a/README.md b/README.md index b21d410..7632f77 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,24 @@ The BitBadges chain binary + CLI are the canonical way to interact with BitBadge curl -fsSL https://install.bitbadges.io | sh ``` -This installs `bitbadgeschaind` (the chain binary) and `bitbadges-cli` (the JS CLI that exposes 104+ API routes plus the `bitbadges-builder` MCP server). This plugin is a Claude Code convenience layer on top of those — it does not replace them. +This installs `bitbadgeschaind` (the chain binary), `bitbadges-cli` (the JS SDK CLI that exposes 106+ API routes plus the `bitbadges-builder` MCP server), and a friendly `bb` alias that wraps `bitbadgeschaind`. This plugin is a Claude Code convenience layer on top of those — it does not replace them. + +## Two entrypoints — when to use which + +There are two binaries on PATH after install, and the skills route to each one accordingly: + +| Form | What it covers | When skills use it | +|---|---|---| +| **`bb cli `** (preferred) | The full Node SDK CLI surface — `build`, `deploy`, `api`, `auctions`, `crowdfunds`, `intents`, `auth`, etc. `bb cli` is `bitbadgeschaind cli` is `bitbadges-cli` — same code, friendlier alias. | Almost all skills (`build`, `query`, `simulate`, `explain`, `review`, `claim`, `address`, most of `broadcast`). | +| **`bitbadgeschaind tx \| query \| keys`** (no `cli` forwarder) | Native Cosmos chain-binary surface — keyring management, signing, on-chain queries. NOT forwarded through `bitbadges-cli`. | `broadcast` skill's "chain binary" path (`bitbadgeschaind tx `). Address skill's keyring lookups. | +| **`bitbadges-cli `** (direct) | Same as `bb cli ` — the underlying JS binary, no chain-binary wrapper. Use when the chain binary isn't on PATH or scripts pin the JS-only entry. | Fallback only — examples in the skills standardize on `bb cli` for terseness. | + +**Rule of thumb**: when in doubt, use `bb cli `. The only time you must use `bitbadgeschaind` directly is for the Cosmos-native surface (`tx`, `query`, `keys`) — those don't have a `bb cli` equivalent because they're not part of the JS SDK. Get an API key at [bitbadges.io/developer](https://bitbadges.io/developer) and configure it once: ```sh -bitbadges-cli config set apiKey YOUR_KEY +bb cli config set apiKey YOUR_KEY ``` ## Install the plugin diff --git a/skills/broadcast/SKILL.md b/skills/broadcast/SKILL.md index 06bb2a8..0d074a1 100644 --- a/skills/broadcast/SKILL.md +++ b/skills/broadcast/SKILL.md @@ -8,17 +8,29 @@ This is the only skill that touches money. Treat it as on-rails, not LLM-discove ## Pick a path -There are four signing paths. Choose based on what the user actually has — not what's most convenient for you. +There are five signing paths. Choose based on what the user actually has — not what's most convenient for you. | What the user has | Use | |---|---| -| A bb1 key in `bitbadgeschaind keys` (or a hardware wallet that signs ADR-36) | **Chain binary** — `bitbadgeschaind tx ...` | +| A bb1 key in `bitbadgeschaind keys` and a CLI workflow | **`deploy --with-keyring --from `** — the CLI prints the equivalent `bitbadgeschaind tx ...` command, runs it, returns the response. Best for headless scripts. | +| Same but driving the chain binary directly | **Chain binary** — `bitbadgeschaind tx ...` | | Just a browser wallet (Keplr, MetaMask, Phantom) | **Browser bridge** — `bitbadges-cli deploy --browser` | | Want zero wallet setup for a one-shot create-collection | **Burner** — `bitbadges-cli deploy --burner` | | A programmatic signer (cosmjs / ethers / viem / hardware that takes raw bytes) | **gen-tx-payload** — produces SignDoc bytes, user signs in their own code | If the user can't tell you which they have, ask. Don't guess. The simulator and review steps are identical regardless of path. +## Useful flag on every `deploy` path: `--wait-for-indexer` + +After broadcast succeeds, the indexer is eventually-consistent — querying the new collection / dynamic store immediately can 404 for a few seconds. Add `--wait-for-indexer [timeout-ms]` (default 30000) to any `deploy` invocation to poll until the entity appears, so the next step in an agent script can rely on it. The CLI returns a `waited: { entity, id, attempts, elapsedMs, ok }` field on the response envelope. + +```bash +bitbadges-cli deploy --burner --msg-stdin --manager bb1... \ + --wait-for-indexer +``` + +Skip the flag when you don't need to query the entity immediately afterwards. + ## Hard requirements (universal) - The transaction has been **simulated and reviewed** in the same session. @@ -43,6 +55,18 @@ Network flags: - Mainnet (default): no flag - Testnet: `--node https://rpc-testnet.bitbadges.io --chain-id bitbadges-1-testnet` +## Path 1b — CLI keyring shortcut (`deploy --with-keyring --from `) + +Same outcome as Path 1, but you stay inside `bitbadges-cli`. The CLI inspects the msg JSON, prints the equivalent `bitbadgeschaind tx ...` command (so users see exactly what's being signed), executes it, and returns the chain response. Best when you've already piped a `build` output and don't want to context-switch: + +```bash +bitbadges-cli build vault --name … \ + | bitbadges-cli deploy --with-keyring --from mykey --msg-stdin \ + --keyring-backend test --manager bb1… +``` + +The msg is unrestricted — works for any tokenization msg, not just create-collection. + ## Path 2 — Browser bridge (`deploy --browser`) For users whose wallet only lives in a browser extension (Keplr, MetaMask, Phantom, WalletConnect). The CLI opens `/sign` on bitbadges.io, the user reviews + signs in their wallet, the tx hash comes back to the terminal. diff --git a/skills/query/SKILL.md b/skills/query/SKILL.md index 60537f0..ae561e0 100644 --- a/skills/query/SKILL.md +++ b/skills/query/SKILL.md @@ -1,5 +1,5 @@ --- -description: Query BitBadges collections, balances, accounts, claims, addresses, and any of the 104+ API routes. Discovers routes via --help-json instead of guessing. +description: Query BitBadges collections, balances, accounts, claims, addresses, standards (auctions / crowdfunds / payment-requests / intents / smart-tokens / ...), and any of the 106+ API routes. Discovers routes via --help-json instead of guessing. --- # Query @@ -29,6 +29,28 @@ The `--help-json` output is the source of truth for routes and parameters. Read Or use the MCP fast-paths: `query_collection`, `query_balance`, `verify_ownership`. +## Standards shortcuts (preferred over raw API) + +For every BitBadges standard the CLI exposes a typed list / show / status surface that's friendlier than the raw indexer routes. Reach for these BEFORE `api ...` when the user asks about a standard by name: + +```bash +bitbadges-cli auctions list # browse active auctions +bitbadges-cli auctions show 42 # one auction +bitbadges-cli auctions status 42 # bidding | accepting | sold | expired + +bitbadges-cli crowdfunds list # crowdfund campaigns +bitbadges-cli pay-requests list --mine bb1... # payment requests TO me +bitbadges-cli intents list --pay-denom uusdc # intent-exchange offers +bitbadges-cli prediction-markets list --open # active prediction markets +bitbadges-cli credit-tokens show # one credit-token collection +bitbadges-cli smart-tokens status # one smart token +bitbadges-cli subscriptions status # subscription tier status +bitbadges-cli swap assets / chains / balances # cross-chain swap surface +bitbadges-cli dynamic-stores list-values # on-chain key→bool map +``` + +Every standard supports `--mine ` (or equivalent) to scope to a specific user. Add `--testnet` / `--local` for non-mainnet. Output is structured JSON. The full surface lives at the docs Standards Commands reference. + ## Networks Add `--testnet` to any command to hit testnet. Add `--local` for `http://localhost:3001`. Default is mainnet.