diff --git a/SUMMARY.md b/SUMMARY.md index b99d9e73..8f2864a5 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -109,7 +109,7 @@ * [Tradable Collection Example](x-tokenization/examples/txs/msgcreatecollection/tradable-nft-collection.md) * [MsgUpdateUserApprovals Examples](x-tokenization/examples/txs/msgupdate-user-approvals/README.md) * [Updating Outgoing Approvals](x-tokenization/examples/txs/msgupdate-user-approvals/updating-outgoing-approvals.md) -* [πŸ€– MCP Builder Skills](x-tokenization/examples/skills/README.md) +* [πŸ€– Builder Skills](x-tokenization/examples/skills/README.md) * [Smart Token](x-tokenization/examples/skills/smart-token.md) * [Minting](x-tokenization/examples/skills/minting.md) * [Liquidity Pools](x-tokenization/examples/skills/liquidity-pools.md) @@ -163,11 +163,12 @@ * [SDK Commands](for-developers/cli/sdk-commands.md) * [API Commands](for-developers/cli/api-commands.md) * [Chain Commands](for-developers/cli/chain-commands.md) - * [Build Commands](for-developers/cli/build-commands.md) + * [Builder Templates](for-developers/cli/builder-templates.md) + * [Builder Commands](for-developers/cli/builder-commands.md) * [CLI for AI Agents](for-developers/cli/for-ai-agents.md) * [πŸ€– AI Agents & Bots](for-developers/ai-agents/README.md) * [Testnet Faucet API](for-developers/ai-agents/testnet-faucet.md) - * [MCP Builder Tools Reference](for-developers/ai-agents/mcp-builder-tools.md) + * [Builder Tools Reference](for-developers/ai-agents/builder-tools.md) * [WebSocket Events](for-developers/ai-agents/websocket-events.md) * [Bot Examples](for-developers/ai-agents/bot-examples.md) * [E2E: AI Agent with USDC Vault](for-developers/ai-agents/openclaw-vault-tutorial.md) diff --git a/for-developers/ai-agents/README.md b/for-developers/ai-agents/README.md index 69f19d3b..c12f40fe 100644 --- a/for-developers/ai-agents/README.md +++ b/for-developers/ai-agents/README.md @@ -55,22 +55,22 @@ console.log('TX Hash:', result.txHash); | Path | Best For | Install | |------|----------|---------| | **CLI & Chain Binary** | Terminal agents, shell scripts, any language | `curl -fsSL .../install.sh \| sh` β€” [guide](../cli/for-ai-agents.md) | -| **MCP Builder Tools** | AI assistants (Claude, Cursor, etc.) | `npm i -g bitbadges-builder-mcp` | +| **BitBadges Builder Tools** | AI assistants (Claude, Cursor, etc.) | `npm i -g bitbadgesjs-sdk` | | **SDK Signing Client** | Full-featured TypeScript bots | `npm i bitbadgesjs-sdk` | | **Direct HTTP** | Lightweight scripts, any language | REST calls to `api.bitbadges.io` | | **Agent Spending Authorization** | Set daily caps, time windows, and revocation | [guide](agent-spending-authorization.md) | -### MCP Quick Setup +### Quick Setup ```bash # Claude Code (one command) -claude mcp add bitbadges-builder -- npx -y bitbadges-builder-mcp +claude mcp add bitbadges-builder -- npx -y -p bitbadgesjs-sdk bitbadges-builder # Or install globally -npm install -g bitbadges-builder-mcp +npm install -g bitbadgesjs-sdk ``` -See the full [MCP Builder Tools Reference](mcp-builder-tools.md) for all 50+ tools (including session-based per-field builders), configuration for Claude Desktop / Cursor, and workflow guides. +See the full [Builder Tools Reference](builder-tools.md) for all 50+ tools (including session-based per-field builders), configuration for Claude Desktop / Cursor, and workflow guides. ## Network Configuration @@ -90,7 +90,7 @@ Additional endpoints (testnet): | Page | Description | |------|-------------| | [Testnet Faucet API](testnet-faucet.md) | Get free testnet BADGE tokens for your bot | -| [MCP Builder Tools Reference](mcp-builder-tools.md) | All 50+ MCP tools for AI assistants | +| [Builder Tools Reference](builder-tools.md) | All 50+ builder tools for AI assistants | | [WebSocket Events](websocket-events.md) | Subscribe to real-time blockchain events | | [Bot Examples](bot-examples.md) | Copy-paste examples for common bot patterns | | [E2E: AI Agent with USDC Vault](openclaw-vault-tutorial.md) | Full tutorial: wallet setup, vault rules, withdraw/deposit | diff --git a/for-developers/ai-agents/bot-examples.md b/for-developers/ai-agents/bot-examples.md index 9938ff39..e16eba3a 100644 --- a/for-developers/ai-agents/bot-examples.md +++ b/for-developers/ai-agents/bot-examples.md @@ -172,9 +172,9 @@ ws.on('close', () => { }); ``` -## Example 5: MCP Agent Workflow +## Example 5: Builder Agent Workflow -When using the BitBadges MCP tools (e.g., in Claude Desktop or Claude Code), there are two build approaches: +When using the BitBadges builder tools (e.g., in Claude Desktop or Claude Code), there are two build approaches: ### Session-Based Build (Recommended) @@ -197,7 +197,7 @@ add_transfer({ from: "Mint", toAddresses: ["bb1youraddress..."], balances: [...] # 4. Verify (in parallel) validate_transaction() -audit_collection() +review_collection() simulate_transaction() # 5. Export the final transaction JSON @@ -210,10 +210,10 @@ For quick collection creation from the terminal, use the CLI build commands: ```bash # Generate a vault token (outputs transaction JSON) -bitbadges-cli build vault --backing-coin USDC --name "My Vault" --dry-run --explain +bitbadges-cli builder templates vault --backing-coin USDC --name "My Vault" --explain # Generate a subscription collection -bitbadges-cli build subscription --interval monthly --price 10 --denom USDC --recipient bb1... +bitbadges-cli builder templates subscription --interval monthly --price 10 --denom USDC --recipient bb1... ``` See [CLI Build Commands](../cli/build-commands.md) for the full list of 18 template builders. @@ -227,7 +227,7 @@ search({ query: "my collection name" }) β†’ verify_ownership({ collectionId: "123", address: "bb1...", badgeIds: [...] }) ``` -> **Note:** The MCP server builds and validates transactions but does not sign or broadcast. Use the BitBadges SDK signing client or the BitBadges frontend to sign and submit. +> **Note:** The builder builds and validates transactions but does not sign or broadcast. Use the BitBadges SDK signing client or the BitBadges frontend to sign and submit. ## Tips for AI Agents diff --git a/for-developers/ai-agents/mcp-builder-tools.md b/for-developers/ai-agents/builder-tools.md similarity index 85% rename from for-developers/ai-agents/mcp-builder-tools.md rename to for-developers/ai-agents/builder-tools.md index 049fca94..5eaabd97 100644 --- a/for-developers/ai-agents/mcp-builder-tools.md +++ b/for-developers/ai-agents/builder-tools.md @@ -1,17 +1,17 @@ -# MCP Builder Tools Reference +# Builder Tools Reference -The [BitBadges Builder MCP server](https://github.com/BitBadges/bitbadges-builder-mcp) provides 50+ tools for AI assistants to build, audit, and validate BitBadges transactions. It works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. +The [BitBadges Builder](https://github.com/bitbadges/bitbadgesjs/tree/main/packages/bitbadgesjs-sdk/src/builder) provides 50+ tools for AI assistants to build, audit, and validate BitBadges transactions. It works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. -> For terminal-based workflows without MCP, use the [BitBadges CLI](../cli/) β€” it provides 104+ API routes, review/audit tools, and built-in docs from the command line. See [CLI for AI Agents](../cli/for-ai-agents.md). +> For terminal-based workflows without an MCP client, use the [BitBadges CLI](../cli/) β€” it provides 104+ API routes, review/audit tools, and built-in docs from the command line. See [CLI for AI Agents](../cli/for-ai-agents.md). ## Installation ```bash # Install globally -npm install -g bitbadges-builder-mcp +npm install -g bitbadgesjs-sdk # Or run directly (no install) -npx bitbadges-builder-mcp +npx -p bitbadgesjs-sdk bitbadges-builder ``` ### Claude Desktop @@ -23,7 +23,7 @@ Add to your `claude_desktop_config.json`: "mcpServers": { "bitbadges-builder": { "command": "npx", - "args": ["-y", "bitbadges-builder-mcp"], + "args": ["-y", "-p", "bitbadgesjs-sdk", "bitbadges-builder"], "env": { "BITBADGES_API_KEY": "your-api-key", "BITBADGES_MNEMONIC": "your mnemonic phrase" @@ -36,7 +36,7 @@ Add to your `claude_desktop_config.json`: ### Claude Code ```bash -claude mcp add bitbadges-builder -- npx -y bitbadges-builder-mcp +claude mcp add bitbadges-builder -- npx -y -p bitbadgesjs-sdk bitbadges-builder ``` ### Cursor @@ -48,7 +48,7 @@ Add to `.cursor/mcp.json`: "mcpServers": { "bitbadges-builder": { "command": "npx", - "args": ["-y", "bitbadges-builder-mcp"], + "args": ["-y", "-p", "bitbadgesjs-sdk", "bitbadges-builder"], "env": { "BITBADGES_API_KEY": "your-api-key" } @@ -112,8 +112,7 @@ Standalone tools for building specific non-collection resources. | Tool | Description | |------|-------------| -| `audit_collection` | Security audit: centralization, supply inflation, approval flaws, common bugs (9 categories) | -| `verify_standards` | Verify a collection transaction complies with BitBadges protocol standards. Returns violations with severity levels | +| `review_collection` | Unified review: audit, standards compliance, and UX findings in one call with audience filtering | | `explain_collection` | Human-readable collection report with Q&A mode (user/developer/auditor audiences) | | `analyze_collection` | Structured analysis of transferability, approvals, permissions, and how to obtain/transfer tokens | @@ -175,7 +174,7 @@ The per-field tools build up a collection incrementally in a session. This is th ``` set_standards + set_valid_token_ids + set_invariants + add_approval + set_permissions + set_default_balances + set_collection_metadata + set_token_metadata β†’ (optional) add_transfer (for auto-mint at creation) - β†’ validate_transaction + audit_collection + simulate_transaction (in parallel) + β†’ validate_transaction + review_collection + simulate_transaction (in parallel) β†’ fix errors with remove_approval + re-add (max 3 attempts) β†’ get_transaction (final JSON) ``` @@ -184,7 +183,7 @@ set_standards + set_valid_token_ids + set_invariants + add_approval + set_permis 1. **Build** β€” Call per-field tools in parallel to define the collection: standards, token IDs, invariants, approvals, permissions, metadata, balances. 2. **Auto-Mint** (optional) β€” If the user wants tokens minted to specific addresses at creation, call `add_transfer` to append a `MsgTransferTokens` alongside the collection creation. -3. **Verify** β€” Call `validate_transaction`, `audit_collection`, and `simulate_transaction` in parallel. Fix any errors with targeted `remove_approval` + re-add. +3. **Verify** β€” Call `validate_transaction`, `review_collection`, and `simulate_transaction` in parallel. Fix any errors with targeted `remove_approval` + re-add. 4. **Export** β€” Call `get_transaction` to get the final transaction JSON for signing. ### Query & Verification (No Signing) @@ -193,7 +192,7 @@ set_standards + set_valid_token_ids + set_invariants + add_approval + set_permis query_collection β†’ verify_ownership β†’ (take action based on result) ``` -> **Note:** The MCP server does not handle signing or broadcasting. Transaction signing must be done externally using the BitBadges SDK, a wallet, or the BitBadges frontend. +> **Note:** The builder does not handle signing or broadcasting. Transaction signing must be done externally using the BitBadges SDK, a wallet, or the BitBadges frontend. ## Auto-Mint at Creation @@ -210,9 +209,9 @@ Maximum 4 transfer messages per transaction. ## Skills (Guided Workflows) -The MCP server includes skill instructions accessible via `get_skill_instructions`. These guide AI agents through building specific collection types. +The builder includes skill instructions accessible via `get_skill_instructions`. These guide AI agents through building specific collection types. -For full instructions and examples for each skill, see the **[MCP Builder Skills reference](../../x-tokenization/examples/skills/README.md)**. +For full instructions and examples for each skill, see the **[Builder Skills reference](../../x-tokenization/examples/skills/README.md)**. Common features like ownership requirements, codes, and passwords are built into the approval system directly and can be composed with any skill. @@ -224,9 +223,9 @@ Common features like ownership requirements, codes, and passwords are built into | **GitBook MCP** | [docs.bitbadges.io/~gitbook/mcp](https://docs.bitbadges.io/~gitbook/mcp) | Search BitBadges documentation | | **BitBadges API** | [api.bitbadges.io](https://api.bitbadges.io) | REST API for queries and data | -## MCP Resources +## Builder Resources -The MCP server also exposes embedded documentation as resources: +The builder also exposes embedded documentation as resources: | Resource URI | Name | Description | |-------------|------|-------------| diff --git a/for-developers/ai-agents/claims-for-agents.md b/for-developers/ai-agents/claims-for-agents.md index b53c8317..91f42dfc 100644 --- a/for-developers/ai-agents/claims-for-agents.md +++ b/for-developers/ai-agents/claims-for-agents.md @@ -60,7 +60,7 @@ await api.createClaim({ }); ``` -If you are using the BitBadges MCP tools or the AI builder, use the `build_claim` tool instead of constructing the payload manually (see MCP Tool Workflow below). The AI builder auto-generates `seedCode` and codes server-side for the `codes` plugin β€” you only need to specify `numCodes` in `publicParams`. +If you are using the BitBadges Builder tools or the AI builder, use the `build_claim` tool instead of constructing the payload manually (see Builder Tool Workflow below). The AI builder auto-generates `seedCode` and codes server-side for the `codes` plugin β€” you only need to specify `numCodes` in `publicParams`. ## Completing a Claim @@ -160,9 +160,9 @@ The `prioritizedApprovals` array tells the chain which approval to check. The `a - **Ownership-gated minting**: Use the `must-own-badges` plugin to gate minting based on existing token ownership. Users who hold token X can mint token Y. - **Time-windowed drops**: Add `transferTimes` constraints to limit when claims can be completed. -## MCP Tool Workflow +## Builder Tool Workflow -If you are using the BitBadges MCP builder tools, the `build_claim` tool handles payload construction: +If you are using the BitBadges Builder tools, the `build_claim` tool handles payload construction: ``` build_claim({ diff --git a/for-developers/ai-agents/openclaw-vault-tutorial.md b/for-developers/ai-agents/openclaw-vault-tutorial.md index c5d50602..021a6e9f 100644 --- a/for-developers/ai-agents/openclaw-vault-tutorial.md +++ b/for-developers/ai-agents/openclaw-vault-tutorial.md @@ -327,5 +327,5 @@ Give your agent the prompt from the **AI Prompt** tab (Step 3) as part of its sy - [MsgTransferTokens](../../x-tokenization/messages/msg-transfer-tokens.md) - Transfer message details - [IBC Backed Paths](../../x-tokenization/concepts/ibc-backed-paths.md) - How backing works - [Bot Examples](bot-examples.md) - More agent patterns -- [MCP Builder Tools](mcp-builder-tools.md) - If your agent uses MCP (Claude, etc.) +- [BitBadges Builder Tools](builder-tools.md) - If your agent speaks MCP (Claude, etc.) - [Testnet Faucet](testnet-faucet.md) - Get testnet tokens for testing diff --git a/for-developers/bitbadges-blockchain/create-and-broadcast-txs/broadcast-to-a-node.md b/for-developers/bitbadges-blockchain/create-and-broadcast-txs/broadcast-to-a-node.md index 64a69c07..3c948aad 100644 --- a/for-developers/bitbadges-blockchain/create-and-broadcast-txs/broadcast-to-a-node.md +++ b/for-developers/bitbadges-blockchain/create-and-broadcast-txs/broadcast-to-a-node.md @@ -11,6 +11,8 @@ const res = await BitBadgesApi.simulateTx(txBody); //Returned from signing steps This will return the gas used and success statuses on a dry run of the transaction. +> **Payload shapes.** `/api/v0/simulate` accepts two payload shapes. Use the proto-encoded form (`{ mode, tx_bytes }`) shown above β€” this is the fully supported path and what the signing flows produce after signing. A second shape, `{ messages, memo?, fee, creatorAddress }` with unsigned JSON messages, is also accepted and proto-encoded server-side for internal agent/CLI tooling. The JSON path is still stabilizing and only covers the tokenization + baseline Cosmos message tiers, so external integrations should stick with the `tx_bytes` form. + ```typescript export interface SimulateTxRouteSuccessResponse { gas_info: { diff --git a/for-developers/bitbadges-blockchain/create-and-broadcast-txs/signing-client.md b/for-developers/bitbadges-blockchain/create-and-broadcast-txs/signing-client.md index c52f648e..6cdd4477 100644 --- a/for-developers/bitbadges-blockchain/create-and-broadcast-txs/signing-client.md +++ b/for-developers/bitbadges-blockchain/create-and-broadcast-txs/signing-client.md @@ -100,7 +100,7 @@ console.log('Transaction hash:', result.txHash); ### Server-Side Signing (EVM Path β€” Recommended) -> **Building an AI agent or bot?** See the [AI Agents & Bots](../../ai-agents/) section for end-to-end examples, testnet faucet, and MCP tool reference. +> **Building an AI agent or bot?** See the [AI Agents & Bots](../../ai-agents/) section for end-to-end examples, testnet faucet, and builder tool reference. Server-side signing uses `GenericEvmAdapter` which connects to the EVM JSON-RPC endpoint and broadcasts via precompile calls. This is the recommended path for bots, agents, and backend services. diff --git a/for-developers/bitbadges-sdk/cli.md b/for-developers/bitbadges-sdk/cli.md index cca375f1..fa255600 100644 --- a/for-developers/bitbadges-sdk/cli.md +++ b/for-developers/bitbadges-sdk/cli.md @@ -88,9 +88,11 @@ bitbadges-cli sdk review 42 --testnet echo '{"messages":[...]}' | bitbadges-cli sdk review - ``` -If `BITBADGES_API_KEY` is set, transactions are sent to the enriched simulate endpoint. Falls back to local analysis (`validateTransaction` + `auditCollection` + `verifyStandardsCompliance`) if the API is unavailable. +If `BITBADGES_API_KEY` is set, transactions are sent to the enriched simulate endpoint. Falls back to local analysis via the unified `reviewCollection()` entry point if the API is unavailable. -For collection JSON (no `messages` field), runs `auditCollection` and `verifyStandardsCompliance` locally. +For collection JSON (no `messages` field), runs `reviewCollection()` locally. + +`reviewCollection()` composes three check families β€” `audit` (permission/supply/centralization), `standards` (protocol conformance), and `ux` (the deterministic UX checks ported from the frontend review sidebar) β€” into a single `Finding[]`. Each finding carries an `audience` field (`'agent' | 'human' | 'both'`) so consumers can filter: agents get everything; the frontend sidebar passes `audienceFilter: 'human'` via `ReviewContext` to hide audit findings the MCP validators already surface during construction. ### interpret-tx @@ -172,7 +174,7 @@ bitbadges-cli sdk gen-list-id bb1abc... --blacklist ### skills -List available MCP Builder skills or fetch a specific skill's instructions from the bundled docs. +List available Builder skills or fetch a specific skill's instructions from the bundled docs. ```bash bitbadges-cli sdk skills # list all skills @@ -292,7 +294,7 @@ Add that line to your `.bashrc` or `.zshrc` for persistent completions. ## Build Commands -Token building (creating collections, generating approvals, etc.) is handled by the [MCP Builder Tools](../ai-agents/mcp-builder-tools.md), not the CLI directly. The CLI focuses on analysis, review, and API access. +Token building (creating collections, generating approvals, etc.) is handled by the [BitBadges Builder Tools](../ai-agents/builder-tools.md), not the CLI directly. The CLI focuses on analysis, review, and API access. ## bitbadgeschaind Delegation diff --git a/for-developers/bitbadges-sdk/common-snippets/balance-lookups.md b/for-developers/bitbadges-sdk/common-snippets/balance-lookups.md index 1bb9b3ef..f10cd979 100644 --- a/for-developers/bitbadges-sdk/common-snippets/balance-lookups.md +++ b/for-developers/bitbadges-sdk/common-snippets/balance-lookups.md @@ -70,7 +70,7 @@ Returns a single amount. Defaults to the current time if `time` is omitted. --- -## MCP Tools +## Builder Tools ### Full flow diff --git a/for-developers/bitbadges-sdk/common-snippets/interpret-collection.md b/for-developers/bitbadges-sdk/common-snippets/interpret-collection.md index 4ad5f6ae..b5590dc8 100644 --- a/for-developers/bitbadges-sdk/common-snippets/interpret-collection.md +++ b/for-developers/bitbadges-sdk/common-snippets/interpret-collection.md @@ -33,5 +33,5 @@ The function automatically strips sensitive claim parameters (`seedCode`, `preim ## Also Available Via -- **MCP**: The `explain_collection` tool uses this under the hood +- **Builder**: The `explain_collection` tool uses this under the hood - **Frontend**: Displayed on collection overview pages diff --git a/for-developers/bitbadges-sdk/common-snippets/simulation-balance-diffs.md b/for-developers/bitbadges-sdk/common-snippets/simulation-balance-diffs.md index a9e33d77..c91b4a4d 100644 --- a/for-developers/bitbadges-sdk/common-snippets/simulation-balance-diffs.md +++ b/for-developers/bitbadges-sdk/common-snippets/simulation-balance-diffs.md @@ -52,5 +52,5 @@ const netChanges = calculateNetChanges(parsed, fee, signerAddress); ## Also Available Via -- **MCP**: The `simulate_transaction` tool returns structured `parsedEvents` and `netChanges` +- **Builder**: The `simulate_transaction` tool returns structured `parsedEvents` and `netChanges` - **Frontend**: The TxModal "Net Changes" tab uses this under the hood diff --git a/for-developers/claim-builder/leveraging-ai.md b/for-developers/claim-builder/leveraging-ai.md index 18ca3169..1fbcb122 100644 --- a/for-developers/claim-builder/leveraging-ai.md +++ b/for-developers/claim-builder/leveraging-ai.md @@ -1,6 +1,6 @@ # Leveraging AI -> **Building an AI agent or bot that interacts with BitBadges directly?** See the [AI Agents & Bots](../ai-agents/) section for signing, broadcasting, MCP tools, and bot examples. +> **Building an AI agent or bot that interacts with BitBadges directly?** See the [AI Agents & Bots](../ai-agents/) section for signing, broadcasting, builder tools, and bot examples. A great way to implement both criteria and utility is through AI models and agents. This can be done through custom plugins created in the [developer portal](https://bitbadges.io/developer). diff --git a/for-developers/claim-builder/overview.md b/for-developers/claim-builder/overview.md index fb00363f..9ddd439b 100644 --- a/for-developers/claim-builder/overview.md +++ b/for-developers/claim-builder/overview.md @@ -1,6 +1,6 @@ # Overview -> πŸ’‘ **Note:** This documentation is intended to provide developer documentation for more advanced use cases. Most of the time, you can directly do everything in-site. Or if you need custom functionality, it is oftentimes a better approach to just self-implement the functionality you need rather than deal with the complexities of connecting with claims. LLMs, especially with MCP, are great for implementing all of this stuff. We just provide claims as an out of the box tool in-site. +> πŸ’‘ **Note:** This documentation is intended to provide developer documentation for more advanced use cases. Most of the time, you can directly do everything in-site. Or if you need custom functionality, it is oftentimes a better approach to just self-implement the functionality you need rather than deal with the complexities of connecting with claims. LLMs, especially with builder tools, are great for implementing all of this stuff. We just provide claims as an out of the box tool in-site. BitBadges claims are designed to be a comprehensive tool directly within the site or via the API for you to custom gate your utility. Claims can be simply thought of as: **Meet criteria? -> Offer utility / rewards.** The implementation process aims to be super flexible, allowing you maximum customization. diff --git a/for-developers/claims/designing-claims.md b/for-developers/claims/designing-claims.md index 34324752..71077e40 100644 --- a/for-developers/claims/designing-claims.md +++ b/for-developers/claims/designing-claims.md @@ -89,7 +89,7 @@ Claims integrate with BitBadges' points system. Award points on successful claim ### AI-Powered Criteria -With AI x MCP x LLMs and services like Zapier or Pipedream, you really have endless possibilities for checking criteria and implementing rewards on your own. It is all just one prompt away. +With AI x Builder x LLMs and services like Zapier or Pipedream, you really have endless possibilities for checking criteria and implementing rewards on your own. It is all just one prompt away. **Criteria side:** Pre-evaluate users with your AI model and add eligible addresses to a dynamic store. This avoids long wait times during claim execution and provides better UX. diff --git a/for-developers/cli/README.md b/for-developers/cli/README.md index a532a45b..acd1572f 100644 --- a/for-developers/cli/README.md +++ b/for-developers/cli/README.md @@ -60,7 +60,7 @@ The CLI is the recommended interface for AI agents and automation. It provides: See [CLI for AI Agents](for-ai-agents.md) for end-to-end agent workflows. -For building token collections with AI assistants (Claude, Cursor, etc.), see the [MCP Builder Tools](../ai-agents/mcp-builder-tools.md) which provide 50+ tools on top of the CLI. +For building token collections with AI assistants (Claude, Cursor, etc.), see the [BitBadges Builder Tools](../ai-agents/builder-tools.md) which provide 50+ tools on top of the CLI. ## Next Steps @@ -68,4 +68,6 @@ For building token collections with AI assistants (Claude, Cursor, etc.), see th - [SDK Commands](sdk-commands.md) β€” review, interpret, address tools, docs, skills - [API Commands](api-commands.md) β€” 104+ API routes from your terminal - [Chain Commands](chain-commands.md) β€” keys, transactions, on-chain queries +- [Builder Templates](builder-templates.md) β€” flag-based generators for vault, subscription, bounty, auction, and 14 other token types +- [Builder Commands](builder-commands.md) β€” tools, review, verify, simulate, preview, doctor, session, resources - [CLI for AI Agents](for-ai-agents.md) β€” agent workflows and automation patterns diff --git a/for-developers/cli/builder-commands.md b/for-developers/cli/builder-commands.md new file mode 100644 index 00000000..2c2c931c --- /dev/null +++ b/for-developers/cli/builder-commands.md @@ -0,0 +1,242 @@ +# Builder Commands + +The `bitbadges-cli builder` command group is the umbrella for every non-template builder subcommand: the fine-grained tool registry, the review / verify / simulate / validate check family, the preview uploader, the environment doctor, the persisted session store, and the static resource registry. + +If you are looking for flag-based template generators (`vault`, `nft`, `subscription`, …), see [Builder Templates](builder-templates.md). Everything else lives here. + +All commands are also available via `bitbadgeschaind builder …` β€” the chain binary forwards `builder` subcommands to the Node.js CLI in-process, so there is no functional difference between `bitbadges-cli builder review tx.json` and `bitbadgeschaind builder review tx.json`. + +## Overview + +| Command | Purpose | +|---------|---------| +| [`builder tools list`](#builder-tools-list) | List every builder tool with its JSON schema | +| [`builder tools call `](#builder-tools-call) | Invoke a builder tool by name | +| [`builder review `](#builder-review) | Run `reviewCollection()` over a tx or collection | +| [`builder verify `](#builder-verify) | Aggregate validate + review + metadata coverage | +| [`builder validate `](#builder-validate) | Offline structural validation only | +| [`builder simulate `](#builder-simulate) | Dry-run a tx against the BitBadges API simulate endpoint | +| [`builder explain `](#builder-explain) | Plain-English explanation of a tx or collection | +| [`builder preview `](#builder-preview) | Upload a tx and print a shareable `bitbadges.io` preview URL | +| [`builder doctor`](#builder-doctor) | Environment + session health check | +| [`builder session list / show / reset`](#builder-session) | Inspect, dump, or delete persisted builder sessions | +| [`builder resources list / read`](#builder-resources) | Browse the static resource registry (recipes, skills, docs, …) | + +Every command that takes an `` accepts the same five shapes: + +- A file path (`tx.json`) +- A `@file.json` path token +- Inline JSON (`'{"messages":[...]}'`) +- A numeric collection ID (for `review` and `explain` only β€” fetched from the API) +- `-` to read from stdin + +## builder tools + +The `tools` subcommand is the in-process twin of the BitBadges Builder MCP stdio server. Every tool the `bitbadges-builder-mcp` bin exposes to Claude Desktop is reachable here as a plain function call β€” no subprocess, no MCP protocol round-trip. + +### builder tools list + +List every builder tool with its full JSON schema. + +```bash +bitbadges-cli builder tools list # full schemas, as JSON +bitbadges-cli builder tools list --names # just the tool names, one per line +``` + +### builder tools call + +Invoke a builder tool by name. Arguments come from `--args` (inline JSON) or `--args-file` (path to a JSON file). + +```bash +bitbadges-cli builder tools call get_current_timestamp +bitbadges-cli builder tools call get_skill_instructions --args '{"skill":"smart-token"}' +bitbadges-cli builder tools call set_collection_metadata \ + --args-file ./metadata.json \ + --session demo +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--args ` | Tool arguments as an inline JSON string | +| `--args-file ` | Tool arguments read from a JSON file | +| `--session ` | Session id for stateful tools. Persisted to `~/.bitbadges/sessions/.json`. Defaults to `--args.sessionId`, or the built-in default session. | +| `--raw` | Print the structured result instead of the formatted text block | + +Stateful tools (`set_*`, `add_*`, `remove_*`, `get_transaction`, …) read from and write to the named session. Sessions survive across invocations, so agents can compose a collection across many CLI calls: + +```bash +SESSION=demo +bitbadges-cli builder tools call set_standards --session $SESSION --args '{"standards":["SmartToken"]}' +bitbadges-cli builder tools call set_collection_metadata --session $SESSION --args @meta.json +bitbadges-cli builder tools call add_approval --session $SESSION --args @approval.json +bitbadges-cli builder tools call get_transaction --session $SESSION # emit final JSON +``` + +Unknown tool names exit 1 and print the available tool list on stderr. + +## builder review + +Top-level alias for `sdk review`. Runs `reviewCollection()` over a transaction, collection, or on-chain collection ID and prints the grouped findings. + +```bash +bitbadges-cli builder review tx.json +bitbadges-cli builder review collection.json --strict +bitbadges-cli builder review 42 --testnet # fetch by collection id +echo '{"messages":[...]}' | bitbadges-cli builder review - +``` + +`reviewCollection()` composes three check families β€” `audit` (permission / supply / centralization), `standards` (protocol conformance), and `ux` (the deterministic UX checks ported from the frontend review sidebar) β€” into a single `Finding[]`. The CLI, the MCP `review_collection` tool, the indexer validation gate, and the frontend review sidebar all dispatch through this exact same entry point. + +**Options:** + +| Flag | Description | +|------|-------------| +| `--json` | Output the full `ReviewResult` as JSON | +| `--strict` | Exit 1 on warnings. Critical findings always exit 2. | +| `--output-file ` | Write the rendered output to a file instead of stdout | +| `--network ` | Target network for numeric-id fetches | +| `--testnet` / `--local` / `--url ` | Shorthands for `--network` and base URL overrides | + +## builder verify + +One-stop diligence command. Runs `validate` + `review` + metadata coverage scan in a single pass and renders all three sections with the same terminal renderer the templates use. Saves agents 3+ separate calls per build. + +```bash +bitbadges-cli builder verify tx.json +bitbadges-cli builder verify tx.json --json # single structured payload +bitbadges-cli builder verify tx.json --strict # exit 1 on any warnings +bitbadges-cli builder verify tx.json --no-metadata # skip the metadata section +``` + +For transactions whose first collection message isn't at `messages[0]` (e.g. `[MsgTransferTokens, MsgCreateCollection]`, emitted by `add_transfer` + post-fact create), `verify` finds the collection message by walking the array. The `review` and metadata sections only run when a collection message is present β€” for user-level approvals, transfers, or dynamic store messages, only `validate` + `simulate` are useful signal and `review` stays silent. + +**Options:** + +| Flag | Description | +|------|-------------| +| `--json` | Output a structured aggregate JSON instead of rendered sections | +| `--strict` | Exit 1 on warnings; criticals always exit 2 | +| `--no-validate` | Skip the structural validation section | +| `--no-review` | Skip the design review section | +| `--no-metadata` | Skip the metadata coverage section | +| `--output-file ` | Write the rendered sections to a file instead of stdout | + +Exit codes: `0` clean, `1` when `--strict` and warnings are present, `2` when there are critical findings or validation errors. + +## builder validate + +Offline structural validation only β€” no API calls, no design review, no metadata scan. Checks JSON structure, uint ranges, approval criteria shape, and every other invariant that can be verified statically. + +```bash +bitbadges-cli builder validate tx.json +bitbadges-cli builder validate tx.json --json +``` + +Use `validate` when you want the fastest possible pre-commit gate (no network, no API key), and `verify` when you want the full diligence report. + +## builder simulate + +Dry-run a built tx against the BitBadges API `/api/v0/simulate` endpoint. Returns gas estimates and per-address net balance changes. Requires an API key β€” set `BITBADGES_API_KEY`, run `bitbadges-cli config set apiKey `, or target a key-less local indexer with `--network local`. + +```bash +bitbadges-cli builder simulate tx.json +bitbadges-cli builder simulate tx.json --json +bitbadges-cli builder simulate tx.json --events # include raw chain events +bitbadges-cli builder simulate tx.json --creator bb1... # override the sim context address +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--json` | Output the structured `SimulateResult` as JSON instead of a rendered section | +| `--creator
` | Override the simulation context address (default: `bb1simulation`) | +| `--events` | Dump the full raw chain events array in the rendered output (default: just the count) | +| `--network` / `--testnet` / `--local` / `--url` | Network targeting | + +User-level approval messages (`MsgUpdateUserApprovals`, `MsgSetIncomingApproval`, `MsgSetOutgoingApproval`, `MsgDeleteIncomingApproval`, `MsgDeleteOutgoingApproval`, `MsgPurgeApprovals`) are **not simulable** β€” they describe a state mutation on an existing user approval list, not a self-contained tx. Use `builder validate` + `builder review` on those instead. + +## builder explain + +Human-readable explanation of a transaction body or a raw collection. Auto-detects which shape was passed: a `MsgCreateCollection` / `MsgUpdateCollection` / `MsgUniversalUpdateCollection` tx goes through `interpretTransaction()`, a raw collection goes through `interpretCollection()`. Numeric input is fetched from the indexer as a collection id. + +```bash +bitbadges-cli builder explain tx.json +bitbadges-cli builder explain 42 --testnet +bitbadges-cli builder explain tx.json --output-file summary.txt +``` + +## builder preview + +Upload a built tx to the indexer and print a shareable `bitbadges.io` preview URL. Lets agents and humans hand off a tx to a non-CLI reviewer for visual inspection without giving them edit or submit rights. + +```bash +bitbadges-cli builder preview tx.json +bitbadges-cli builder preview tx.json --json +bitbadges-cli builder preview tx.json --frontend-url https://testnet.bitbadges.io +``` + +The endpoint (`/api/v0/builder/preview`) is open β€” no API key required. The unguessable code baked into the returned URL is the secret. Uploaded previews live in the indexer's Redis cache for one hour. + +**Options:** + +| Flag | Description | +|------|-------------| +| `--json` | Output the structured upload result (code, URL, expiry) as JSON | +| `--frontend-url ` | Override the `bitbadges.io` base for the printed URL (default: `https://bitbadges.io`) | +| `--network` / `--testnet` / `--local` / `--url` | Indexer target for the upload | + +## builder doctor + +One-shot environment + session health check. Runs six independent probes: + +1. **Node version** β€” must be β‰₯ 18 +2. **SDK package + version** β€” loaded from `bitbadgesjs-sdk`'s own `package.json` +3. **CLI config file** β€” `~/.bitbadges/config.json` +4. **API key reachability** β€” pings `/api/v0/simulate` with a no-op request +5. **MCP stdio bin presence** β€” smoke launch of the `bitbadges-builder-mcp` entry +6. **Persisted sessions** β€” every file under `~/.bitbadges/sessions/` parses + +Each probe reports `PASS` / `FAIL` / `WARN` / `SKIP`. The command exits non-zero only if any probe is a hard `FAIL`; warnings and skips are informational. + +```bash +bitbadges-cli builder doctor +bitbadges-cli builder doctor --json +bitbadges-cli builder doctor --with-preview # adds a preview round-trip probe +``` + +`--with-preview` adds a seventh probe: builds a minimal tx, posts it to `/api/v0/builder/preview`, fetches it back by code, and asserts the round trip is byte-equivalent. Catches indexer, Redis, and preview-route regressions. + +## builder session + +Persisted builder sessions live at `~/.bitbadges/sessions/.json`. They are the storage backend for the stateful `builder tools call` flow and the in-process MCP session dispatcher. + +```bash +bitbadges-cli builder session list # list every persisted session id +bitbadges-cli builder session show demo # dump a session as JSON +bitbadges-cli builder session reset demo # delete a session file +``` + +Sessions are plain JSON β€” you can inspect or edit them by hand if needed. Corrupted session files are surfaced by `builder doctor` on the next run. + +## builder resources + +The resource registry is the static half of the builder surface: the token registry, collection recipes, skill instructions, bundled docs, error patterns, and every other content resource the MCP server exposes via `bitbadges://` URIs. + +```bash +bitbadges-cli builder resources list # full metadata, as JSON +bitbadges-cli builder resources list --uris # URIs only, one per line +bitbadges-cli builder resources read bitbadges://skills/all +bitbadges-cli builder resources read bitbadges://recipes/all +``` + +Every resource URI exposed by the MCP server is readable through this command. Agents that want to pre-load skill instructions or recipe catalogues into a prompt can stream them directly from the CLI instead of spawning the MCP stdio bin. + +## See Also + +- [Builder Templates](builder-templates.md) β€” the `bitbadges-cli builder templates *` tree for flag-based template generators +- [SDK Commands](sdk-commands.md) β€” address, alias, lookup, and docs utilities under `bitbadges-cli sdk` +- [Builder Tools Reference](../ai-agents/builder-tools.md) β€” the full tool registry reference, including input schemas and workflows +- [CLI for AI Agents](for-ai-agents.md) β€” end-to-end agent workflows and automation patterns diff --git a/for-developers/cli/build-commands.md b/for-developers/cli/builder-templates.md similarity index 87% rename from for-developers/cli/build-commands.md rename to for-developers/cli/builder-templates.md index 072b5ece..59e82e40 100644 --- a/for-developers/cli/build-commands.md +++ b/for-developers/cli/builder-templates.md @@ -1,6 +1,6 @@ # CLI Build Commands -The `bitbadges-cli build` command provides 18 template builders that generate ready-to-sign transaction JSON. Each builder creates a complete collection or approval configuration from simple, human-readable parameters. +The `bitbadges-cli builder templates` command provides 18 template builders that generate ready-to-sign transaction JSON. Each builder creates a complete collection or approval configuration from simple, human-readable parameters. All build commands accept friendly inputs -- use coin symbols like `USDC` instead of raw IBC denominations, and duration shorthands like `30d` instead of millisecond timestamps. The output is a fully-formed transaction message that can be signed and broadcast using the SDK, the BitBadges frontend, or the chain binary. @@ -27,11 +27,11 @@ These commands generate `MsgUniversalUpdateCollection` transaction JSON for crea Create an IBC-backed vault token with optional withdrawal limits, 2FA gating, and emergency recovery. ```bash -bitbadges-cli build vault --backing-coin USDC \ +bitbadges-cli builder templates vault --backing-coin USDC \ --name "My Vault" \ --symbol vUSDC \ --daily-withdraw-limit 1000 \ - --dry-run --explain + --explain ``` | Flag | Required | Description | @@ -50,7 +50,7 @@ bitbadges-cli build vault --backing-coin USDC \ Create a recurring subscription collection with configurable intervals, pricing, and optional multi-tier support. ```bash -bitbadges-cli build subscription --interval monthly \ +bitbadges-cli builder templates subscription --interval monthly \ --price 10 --denom USDC --recipient bb1... \ --tiers 3 --transferable ``` @@ -71,7 +71,7 @@ bitbadges-cli build subscription --interval monthly \ Create a bounty with escrowed funds, a verifier who approves completion, and a designated recipient. ```bash -bitbadges-cli build bounty --amount 500 --denom USDC \ +bitbadges-cli builder templates bounty --amount 500 --denom USDC \ --verifier bb1... --recipient bb1... --expiration 30d ``` @@ -89,7 +89,7 @@ bitbadges-cli build bounty --amount 500 --denom USDC \ Create a crowdfunding collection with a funding goal and deadline. ```bash -bitbadges-cli build crowdfund --goal 10000 --denom USDC \ +bitbadges-cli builder templates crowdfund --goal 10000 --denom USDC \ --crowdfunder bb1... --deadline 30d ``` @@ -106,8 +106,9 @@ bitbadges-cli build crowdfund --goal 10000 --denom USDC \ Create an auction collection with configurable bidding and acceptance windows. ```bash -bitbadges-cli build auction --bid-deadline 7d --accept-window 7d \ - --name "Rare Item" --description "Limited edition collectible" +bitbadges-cli builder templates auction --bid-deadline 7d --accept-window 7d \ + --name "Rare Item" --description "Limited edition collectible" \ + --seller bb1seller... ``` | Flag | Required | Description | @@ -117,13 +118,14 @@ bitbadges-cli build auction --bid-deadline 7d --accept-window 7d \ | `--name ` | No | Item name (default: "Auction") | | `--description ` | No | Item description | | `--image ` | No | Item image URL | +| `--seller
` | No | Seller address β€” only this address can accept the winning bid (defaults to `--creator`) | ### `build product-catalog` Create a product catalog collection with multiple products, each having its own price and optional supply limit. ```bash -bitbadges-cli build product-catalog \ +bitbadges-cli builder templates product-catalog \ --products '[{"name":"Widget","price":25,"denom":"USDC","maxSupply":100}]' \ --store-address bb1... ``` @@ -139,7 +141,7 @@ bitbadges-cli build product-catalog \ Create a binary prediction market (YES/NO outcome tokens) with a designated resolver. ```bash -bitbadges-cli build prediction-market --verifier bb1... \ +bitbadges-cli builder templates prediction-market --verifier bb1... \ --denom USDC --name "Will X happen by 2027?" ``` @@ -156,7 +158,7 @@ bitbadges-cli build prediction-market --verifier bb1... \ Create an IBC-backed smart account with optional trading and AI agent vault support. ```bash -bitbadges-cli build smart-account --backing-coin USDC \ +bitbadges-cli builder templates smart-account --backing-coin USDC \ --symbol sUSDC --tradable --ai-agent-vault ``` @@ -173,7 +175,7 @@ bitbadges-cli build smart-account --backing-coin USDC \ Create a credit or prepaid token where users pay to receive a configurable number of tokens. ```bash -bitbadges-cli build credit-token --payment-denom USDC \ +bitbadges-cli builder templates credit-token --payment-denom USDC \ --recipient bb1... --symbol CREDIT --tokens-per-unit 100 ``` @@ -190,7 +192,7 @@ bitbadges-cli build credit-token --payment-denom USDC \ Create a custom 2FA token collection for use as a second authentication factor in other collections. ```bash -bitbadges-cli build custom-2fa --name "My 2FA Token" --burnable +bitbadges-cli builder templates custom-2fa --name "My 2FA Token" --burnable ``` | Flag | Required | Description | @@ -206,7 +208,7 @@ bitbadges-cli build custom-2fa --name "My 2FA Token" --burnable Create a quest or reward collection where users claim token rewards up to a maximum number of claims. ```bash -bitbadges-cli build quests --reward 10 --denom USDC --max-claims 1000 +bitbadges-cli builder templates quests --reward 10 --denom USDC --max-claims 1000 ``` | Flag | Required | Description | @@ -221,7 +223,7 @@ bitbadges-cli build quests --reward 10 --denom USDC --max-claims 1000 Create an on-chain address list (not a token collection -- uses a separate message type). ```bash -bitbadges-cli build address-list --name "Allowlist" --description "Approved addresses" +bitbadges-cli builder templates address-list --name "Allowlist" --description "Approved addresses" ``` | Flag | Required | Description | @@ -239,7 +241,7 @@ These commands generate user-level approval messages for marketplace listings, b Create an OTC swap intent (user outgoing approval) on the Intent Exchange. ```bash -bitbadges-cli build intent --address bb1... \ +bitbadges-cli builder templates intent --address bb1... \ --collection-id 5 \ --pay-denom USDC --pay-amount 100 \ --receive-denom BADGE --receive-amount 500 \ @@ -261,7 +263,7 @@ bitbadges-cli build intent --address bb1... \ Create a recurring payment approval (user incoming approval) for subscription collections. ```bash -bitbadges-cli build recurring-payment --collection-id 10 \ +bitbadges-cli builder templates recurring-payment --collection-id 10 \ --amount 25 --denom USDC --interval monthly \ --recipient bb1... --expiration 365d ``` @@ -280,7 +282,7 @@ bitbadges-cli build recurring-payment --collection-id 10 \ Create a marketplace listing (user outgoing approval) to sell tokens from a collection. ```bash -bitbadges-cli build listing --address bb1... \ +bitbadges-cli builder templates listing --address bb1... \ --collection-id 7 --token-ids "1-5" \ --price 50 --denom USDC --max-sales 1 --expiration 30d ``` @@ -300,7 +302,7 @@ bitbadges-cli build listing --address bb1... \ Create a marketplace bid (user incoming approval) to buy tokens from a collection. ```bash -bitbadges-cli build bid --address bb1... \ +bitbadges-cli builder templates bid --address bb1... \ --collection-id 7 --token-ids "1-5" \ --price 40 --denom USDC --expiration 7d ``` @@ -319,7 +321,7 @@ bitbadges-cli build bid --address bb1... \ Create a prediction market sell intent (user outgoing approval) to sell outcome tokens. ```bash -bitbadges-cli build pm-sell-intent --address bb1... \ +bitbadges-cli builder templates pm-sell-intent --address bb1... \ --collection-id 12 --token yes \ --amount 10 --price 50 --denom USDC ``` @@ -339,7 +341,7 @@ bitbadges-cli build pm-sell-intent --address bb1... \ Create a prediction market buy intent (user incoming approval) to buy outcome tokens. ```bash -bitbadges-cli build pm-buy-intent --address bb1... \ +bitbadges-cli builder templates pm-buy-intent --address bb1... \ --collection-id 12 --token no \ --amount 10 --price 50 --denom USDC ``` @@ -360,13 +362,13 @@ All commands support `--json` for passing parameters as a JSON object. This is u ```bash # Inline JSON -bitbadges-cli build vault --json '{"backingCoin":"USDC","name":"My Vault"}' +bitbadges-cli builder templates vault --json '{"backingCoin":"USDC","name":"My Vault"}' # From a file -bitbadges-cli build vault --json ./params.json +bitbadges-cli builder templates vault --json ./params.json # From stdin -echo '{"backingCoin":"USDC"}' | bitbadges-cli build vault --json - +echo '{"backingCoin":"USDC"}' | bitbadges-cli builder templates vault --json - ``` ## Output diff --git a/for-developers/cli/for-ai-agents.md b/for-developers/cli/for-ai-agents.md index b640e36b..9a9db910 100644 --- a/for-developers/cli/for-ai-agents.md +++ b/for-developers/cli/for-ai-agents.md @@ -103,14 +103,14 @@ bitbadgeschaind tx tokenization create-collection ./collection.json \ bitbadges-cli api tx broadcast-tx --body @signed-tx.json ``` -## Combining with MCP Builder Tools +## Combining with BitBadges Builder Tools -For AI assistants that support MCP (Claude, Cursor, etc.), the [MCP Builder Tools](../ai-agents/mcp-builder-tools.md) provide 50+ higher-level tools for building token collections. The CLI and MCP tools are complementary: +For AI assistants that speak MCP (Claude, Cursor, etc.), the [BitBadges Builder Tools](../ai-agents/builder-tools.md) provide 50+ higher-level tools for building token collections. The CLI and builder tools are complementary: | Use Case | Tool | |----------|------| | Query data, browse docs, review transactions | **CLI** (`bitbadges-cli`) | -| Build token collections with guided workflows | **MCP Builder Tools** | +| Build token collections with guided workflows | **BitBadges Builder Tools** | | Sign and broadcast transactions | **Chain binary** (`bitbadgeschaind`) or **SDK Signing Client** | | Key management | **Chain binary** (`bitbadgeschaind`) | @@ -150,5 +150,5 @@ fi - [Bot Examples](../ai-agents/bot-examples.md) β€” TypeScript bot patterns - [Agent Spending Authorization](../ai-agents/agent-spending-authorization.md) β€” on-chain spending limits for agents -- [MCP Builder Tools](../ai-agents/mcp-builder-tools.md) β€” 50+ tools for AI assistants +- [BitBadges Builder Tools](../ai-agents/builder-tools.md) β€” 50+ tools for AI assistants - [Claims for Agents](../ai-agents/claims-for-agents.md) β€” automated minting via claims diff --git a/for-developers/cli/sdk-commands.md b/for-developers/cli/sdk-commands.md index f0b75787..31f4a87a 100644 --- a/for-developers/cli/sdk-commands.md +++ b/for-developers/cli/sdk-commands.md @@ -13,9 +13,11 @@ bitbadges-cli sdk review 42 --testnet echo '{"messages":[...]}' | bitbadges-cli sdk review - ``` -If `BITBADGES_API_KEY` is set, transactions are sent to the enriched simulate endpoint. Falls back to local analysis (`validateTransaction` + `auditCollection` + `verifyStandardsCompliance`) if the API is unavailable. +If `BITBADGES_API_KEY` is set, transactions are sent to the enriched simulate endpoint. Falls back to local analysis via the unified `reviewCollection()` entry point if the API is unavailable. -For collection JSON (no `messages` field), runs `auditCollection` and `verifyStandardsCompliance` locally. +For collection JSON (no `messages` field), runs `reviewCollection()` locally. + +`reviewCollection()` composes three check families β€” `audit` (permission/supply/centralization), `standards` (protocol conformance), and `ux` (the deterministic UX checks ported from the frontend review sidebar) β€” into a single `Finding[]`. Each finding carries an `audience` field (`'agent' | 'human' | 'both'`) so consumers can filter: agents get everything (audit + standards + ux); the frontend sidebar passes `audienceFilter: 'human'` via `ReviewContext` to hide audit findings the MCP validators already surface during construction. ## interpret-tx @@ -97,7 +99,7 @@ bitbadges-cli sdk gen-list-id bb1abc... --blacklist ## skills -List available MCP Builder skills or fetch a specific skill's instructions from the bundled docs. +List available Builder skills or fetch a specific skill's instructions from the bundled docs. ```bash bitbadges-cli sdk skills # list all skills diff --git a/for-developers/getting-started.md b/for-developers/getting-started.md index 01a98972..22965ac1 100644 --- a/for-developers/getting-started.md +++ b/for-developers/getting-started.md @@ -18,7 +18,7 @@ bitbadges-cli api tokens get-collection 1 # query any collection bitbadges-cli sdk docs # browse docs from terminal ``` -> **For AI agents:** The CLI is the recommended interface. See [CLI for AI Agents](cli/for-ai-agents.md) for end-to-end workflows, or use the [MCP Builder Tools](ai-agents/mcp-builder-tools.md) for building tokens with Claude/Cursor. +> **For AI agents:** The CLI is the recommended interface. See [CLI for AI Agents](cli/for-ai-agents.md) for end-to-end workflows, or use the [BitBadges Builder Tools](ai-agents/builder-tools.md) for building tokens with Claude/Cursor. --- @@ -74,16 +74,16 @@ const api = new BitBadgesAPI({ await BitBadgesAPI.getCollection(...); ``` -## Quick Start - MCP Builder Tools (AI) +## Quick Start - BitBadges Builder Tools (AI) -The BitBadges MCP server gives any AI assistant (Claude, Cursor, etc.) 30+ tools to build, audit, sign, and broadcast BitBadges transactions β€” no manual JSON required. +The BitBadges Builder gives any AI assistant (Claude, Cursor, etc.) 30+ tools to build, audit, sign, and broadcast BitBadges transactions β€” no manual JSON required. ```bash # Install globally -npm install -g bitbadges-builder-mcp +npm install -g bitbadgesjs-sdk # Or run directly with npx -npx bitbadges-builder-mcp +npx -p bitbadgesjs-sdk bitbadges-builder ``` **Claude Desktop** β€” add to `claude_desktop_config.json`: @@ -93,7 +93,7 @@ npx bitbadges-builder-mcp "mcpServers": { "bitbadges-builder": { "command": "npx", - "args": ["-y", "bitbadges-builder-mcp"], + "args": ["-y", "-p", "bitbadgesjs-sdk", "bitbadges-builder"], "env": { "BITBADGES_API_KEY": "your-api-key" } @@ -105,10 +105,10 @@ npx bitbadges-builder-mcp **Claude Code:** ```bash -claude mcp add bitbadges-builder -- npx -y bitbadges-builder-mcp +claude mcp add bitbadges-builder -- npx -y -p bitbadgesjs-sdk bitbadges-builder ``` -See the full [MCP Builder Tools Reference](ai-agents/mcp-builder-tools.md) for all tools, schemas, and workflows. For bot/agent guides, see [AI Agents & Bots](ai-agents/). +See the full [Builder Tools Reference](ai-agents/builder-tools.md) for all tools, schemas, and workflows. For bot/agent guides, see [AI Agents & Bots](ai-agents/). ## Developing with AI @@ -116,7 +116,7 @@ Below, we provide some resources that may be helpful for developing with AI. If | Resource | Link | |----------|------| -| **MCP Builder Tools** | `npm i -g bitbadges-builder-mcp` β€” [Reference](ai-agents/mcp-builder-tools.md) | +| **BitBadges Builder Tools** | `npm i -g bitbadgesjs-sdk` β€” [Reference](ai-agents/builder-tools.md) | | **BitBadges SDK** | `npm i bitbadgesjs-sdk` β€” [Docs](bitbadges-sdk/overview.md) | | **AI Quickstarter Repo** | [github.com/BitBadges/bitbadges-quickstarter-ai](https://github.com/BitBadges/bitbadges-quickstarter-ai) | | **GitBook MCP** | [docs.bitbadges.io/~gitbook/mcp](https://docs.bitbadges.io/~gitbook/mcp) β€” searchDocumentation tool | diff --git a/overview/bitbadges-vs-erc3643.md b/overview/bitbadges-vs-erc3643.md index 2de7a7ba..f2edee8f 100644 --- a/overview/bitbadges-vs-erc3643.md +++ b/overview/bitbadges-vs-erc3643.md @@ -14,7 +14,7 @@ Looking to understand how BitBadges and ERC-3643 (T-REX) relate? They are not co |---------|-----------|----------| | **Enforcement layer** | Protocol-level -- rules are enforced by the chain itself | Contract-level -- rules are enforced by Solidity smart contracts | | **Smart contracts required** | No -- collections are configured through structured transaction messages | Yes -- each token requires deploying multiple Solidity contracts (token, identity registry, compliance module, claim topics) | -| **Deployment experience** | No-code UI, CLI template builders, or AI-assisted MCP tools | Developer-only -- requires Solidity expertise and contract deployment | +| **Deployment experience** | No-code UI, CLI template builders, or AI-assisted builder tools | Developer-only -- requires Solidity expertise and contract deployment | | **Multi-chain support** | Native IBC (Inter-Blockchain Communication) to all Cosmos chains | Bridge-dependent for cross-chain transfers (unless deployed on BitBadges, which has native IBC) | | **Identity and compliance** | Built-in approval criteria with configurable checks (ownership requirements, merkle proofs, signature challenges, on-chain queries) | ONCHAINID identity framework with claim topics and trusted issuers | | **Transfer restrictions** | Configurable per-approval rules: address allowlists, time windows, amount limits, tracker-based caps, 2FA gating, coin payment requirements | Compliance modules with modular rule contracts (country restrictions, investor limits, time locks) | @@ -35,7 +35,7 @@ Looking to understand how BitBadges and ERC-3643 (T-REX) relate? They are not co - **No smart contract development** -- Creating a compliant token requires zero code; everything is configured through transaction parameters or the no-code UI - **Protocol-level guarantees** -- Transfer rules cannot be bypassed by contract bugs or upgradeable proxy exploits because they are enforced by the chain itself - **Broader token types** -- The same standard handles subscriptions, prediction markets, vaults, auctions, bounties, NFTs, and more -- not just equity tokens -- **AI and automation friendly** -- MCP tools and CLI template builders allow AI agents to create and manage compliant tokens programmatically +- **AI and automation friendly** -- builder tools and CLI template builders allow AI agents to create and manage compliant tokens programmatically - **Cosmos ecosystem** -- Native IBC connectivity to 50+ Cosmos chains without bridges - **Lower barrier to entry** -- No Solidity expertise, gas optimization, or contract auditing required @@ -47,7 +47,7 @@ This means: - **ERC-3643 as a familiar interface** -- Solidity developers can interact with BitBadges tokens using the ERC-3643 function signatures they already know, while the actual compliance enforcement happens at the protocol level - **Protocol-level enforcement under the hood** -- Transfer rules, identity checks, and compliance logic are enforced by the chain itself, not by the Solidity contract. The precompile bridges the call into the native standard -- **No-code path still available** -- You don't need to use the ERC-3643 interface at all. The no-code UI, CLI template builders, and MCP tools interact with the protocol standard directly +- **No-code path still available** -- You don't need to use the ERC-3643 interface at all. The no-code UI, CLI template builders, and builder tools interact with the protocol standard directly - **Best of both worlds** -- Get the institutional familiarity and tooling compatibility of ERC-3643 with the protocol-level guarantees and broader token type support of BitBadges ## Further Reading diff --git a/overview/official-links.md b/overview/official-links.md index d419e0e5..eabe5251 100644 --- a/overview/official-links.md +++ b/overview/official-links.md @@ -17,7 +17,7 @@ Supports Linux, macOS (Intel + Apple Silicon), and Windows (Git Bash / WSL). See * [Chain Binary Releases](https://github.com/BitBadges/bitbadgeschain/releases) * [SDK CLI (npm)](https://www.npmjs.com/package/bitbadgesjs-sdk) β€” `npm install -g bitbadgesjs-sdk` -* [MCP Builder Tools (npm)](https://www.npmjs.com/package/bitbadges-builder-mcp) β€” `npm install -g bitbadges-builder-mcp` +* [BitBadges Builder Tools (npm)](https://www.npmjs.com/package/bitbadgesjs-sdk) β€” `npm install -g bitbadgesjs-sdk` ### Get Featured diff --git a/token-standard/bb-402/collection-recipes.md b/token-standard/bb-402/collection-recipes.md index 6ccf2f5d..73e56c2a 100644 --- a/token-standard/bb-402/collection-recipes.md +++ b/token-standard/bb-402/collection-recipes.md @@ -165,7 +165,7 @@ Mint the appropriate token ID to each user. Check with `$or` for "any tier" or s ## How to Create Collections can be created: -- **On-site** at [bitbadges.io](https://bitbadges.io) β€” recommended for most cases. You can also use an LLM with the [BitBadges Builder MCP](https://github.com/BitBadges/bitbadges-plugins/tree/main/packages/bitbadges-builder-mcp) to help configure collections. +- **On-site** at [bitbadges.io](https://bitbadges.io) β€” recommended for most cases. You can also use an LLM with the [BitBadges Builder](https://github.com/bitbadges/bitbadgesjs/tree/main/packages/bitbadgesjs-sdk/src/builder) to help configure collections. - **Via SDK** using `MsgUniversalUpdateCollection` from `bitbadgesjs-sdk` - **Via chain CLI** using `bitbadgeschaind tx tokenization` diff --git a/token-standard/learn/approval-criteria/predetermined-balances.md b/token-standard/learn/approval-criteria/predetermined-balances.md index 02929f79..6d59a993 100644 --- a/token-standard/learn/approval-criteria/predetermined-balances.md +++ b/token-standard/learn/approval-criteria/predetermined-balances.md @@ -215,7 +215,7 @@ Enable proportional transfers where users can transfer any integer multiple of t - **`maxScalingMultiplier` is enforced per transfer, not cumulatively.** A user can execute multiple transfers each up to the max. To cap total exposure, pair scaling with `maxNumTransfers` (limit number of uses) or `approvalAmounts` (limit total token quantity). Without these, the only limit is the escrow/approver's available balance. - When `coinTransfers` use `overrideFromWithApproverAddress: true`, the escrow/approver pays `multiplier * baseAmount` per transfer β€” set `maxScalingMultiplier` conservatively and always set `maxNumTransfers` or `approvalAmounts` to bound total payout - Amount scaling is **incompatible** with Quest, Subscription, Invoice, Product, Bid/Listing, and Scheduled Payment standards (these require fixed amounts per transfer) -- The `audit_collection` tool flags `allowAmountScaling + overrideFromWithApproverAddress` as a warning for review +- The `review_collection` tool flags `allowAmountScaling + overrideFromWithApproverAddress` as a warning for review ## Precalculating Balances diff --git a/x-tokenization/examples/skills/README.md b/x-tokenization/examples/skills/README.md index 97416f27..939d32f5 100644 --- a/x-tokenization/examples/skills/README.md +++ b/x-tokenization/examples/skills/README.md @@ -1,8 +1,8 @@ -# πŸ€– MCP Builder Skills +# πŸ€– Builder Skills -These pages document every guided build skill available in the [BitBadges MCP Builder](https://github.com/bitbadges/bitbadges-builder-mcp). Each skill provides step-by-step instructions for building a specific type of token or configuring a specific feature. +These pages document every guided build skill available in the BitBadges Builder (shipped as part of [bitbadgesjs-sdk](https://github.com/BitBadges/bitbadgesjs)). Each skill provides step-by-step instructions for building a specific type of token or configuring a specific feature. -> **Tip:** If you're using the MCP builder in Claude, Cursor, or another AI tool, these instructions are loaded automatically when you select a skill. These pages are provided as a human-readable reference. +> **Tip:** If you're using the BitBadges builder in Claude, Cursor, or another AI tool via the MCP server (`npx bitbadgesjs-sdk-mcp`) or the `bitbadges-cli builder` command surface, these instructions are loaded automatically when you select a skill. These pages are provided as a human-readable reference. ## Token Types diff --git a/x-tokenization/examples/skills/auction.md b/x-tokenization/examples/skills/auction.md index 9c198be1..ed472ac0 100644 --- a/x-tokenization/examples/skills/auction.md +++ b/x-tokenization/examples/skills/auction.md @@ -18,10 +18,14 @@ Required standards: ["Auction"] - initiatedByListId on mint-to-winner = seller address (only seller can accept) - maxNumTransfers = 1 on all approvals (one-shot) - overridesToIncomingApprovals: false on mint-to-winner (bidder's incoming approval handles payment) +- Burn approval has NO override flags β€” relies on defaultBalances autoApproveSelfInitiatedOutgoingTransfers + burn destination +- noForcefulPostMintTransfers: true in invariants (permanently locks out forceful transfers post-mint) +- After settlement, the mint-to-winner approval is auto-deleted via afterOneUse β€” protocol validators treat a missing mint-to-winner as a valid post-settlement state, not an error - All permissions frozen after creation - DON'T use coinTransfers on collection approvals β€” payment happens via intent matching - DON'T set initiatedByListId to "All" on mint-to-winner β€” must be seller - DON'T set transferTimes to forever β€” must be bounded to accept window +- DON'T put override flags on the burn approval β€” auction has noForcefulPostMintTransfers: true, so non-mint override flags would be invariant violations - DO use autoDeletionOptions.afterOneUse: true on mint-to-winner ## Instructions @@ -37,7 +41,8 @@ A single-item auction where the seller creates a collection, bidders place inten - Token ID 1 = The auctioned item - Standard: "Auction" - validTokenIds: [{ start: "1", end: "1" }] -- invariants: { noCustomOwnershipTimes: true } +- invariants: \`{ noCustomOwnershipTimes: true, maxSupplyPerId: "0", noForcefulPostMintTransfers: true, disablePoolCreation: true }\` +- \`noForcefulPostMintTransfers: true\` locks the collection so no non-mint approval can ever use \`overridesFromOutgoingApprovals\` or \`overridesToIncomingApprovals\` β€” the burn approval below relies on \`defaultBalances\` auto-approve flags instead - All permissions frozen after creation ### Bidding Mechanism @@ -85,17 +90,12 @@ Bids must have transferTimes that stay valid through the END of the accept windo "toListId": "", "initiatedByListId": "All", "tokenIds": [{ "start": "1", "end": "1" }], - "transferTimes": [{ "start": "1", "end": "18446744073709551615" }], - "approvalCriteria": { - "overridesFromOutgoingApprovals": true, - "overridesToIncomingApprovals": true, - "coinTransfers": [], - "maxNumTransfers": { "overallMaxNumTransfers": "1" }, - "autoDeletionOptions": { "afterOneUse": true, "afterOverallMaxNumTransfers": true } - } + "transferTimes": [{ "start": "1", "end": "18446744073709551615" }] } \`\`\` +> **No \`approvalCriteria\` overrides:** because the invariants lock \`noForcefulPostMintTransfers: true\`, the burn approval MUST NOT set \`overridesFromOutgoingApprovals\` or \`overridesToIncomingApprovals\`. It relies on \`defaultBalances.autoApproveSelfInitiatedOutgoingTransfers: true\` for the outgoing side and on the burn destination for the incoming side. + ### Auction Flow 1. **Create**: Seller creates auction collection with 2 approvals. No token is minted yet. @@ -107,7 +107,7 @@ Bids must have transferTimes that stay valid through the END of the accept windo 1. \`set_valid_token_ids\` β€” set [{ start: "1", end: "1" }] 2. \`set_standards\` β€” set ["Auction"] -3. \`set_invariants\` β€” set { noCustomOwnershipTimes: true } +3. \`set_invariants\` β€” set \`{ noCustomOwnershipTimes: true, maxSupplyPerId: "0", noForcefulPostMintTransfers: true, disablePoolCreation: true }\` 4. \`add_approval\` x2 β€” mint-to-winner, burn 5. \`set_collection_metadata\` β€” auction title, description, image 6. \`set_token_metadata\` β€” token 1 metadata (the item being auctioned) @@ -121,6 +121,8 @@ Bids must have transferTimes that stay valid through the END of the accept windo - DON'T set initiatedByListId to "All" on mint-to-winner β€” only the seller can accept bids - DON'T set transferTimes to forever β€” MUST be bounded to accept window (bidDeadline β†’ bidDeadline + acceptWindow) - DON'T set overridesToIncomingApprovals to true on mint-to-winner β€” must be false so the bidder's incoming approval (payment intent) is checked +- DON'T add override flags to the burn approval β€” the invariant \`noForcefulPostMintTransfers: true\` rejects \`overridesFromOutgoingApprovals\` or \`overridesToIncomingApprovals\` on any non-mint approval +- DON'T worry if the mint-to-winner approval is absent after settlement β€” \`autoDeletionOptions.afterOneUse: true\` removes it after the first successful mint, and the protocol validator accepts that as a valid post-settlement state - DON'T create a separate mint-to-seller approval β€” the token should not exist until the seller accepts a bid - DON'T forget autoDeletionOptions on mint-to-winner β€” without afterOneUse: true, the seller could mint to multiple bidders - DON'T forget that bids must have transferTimes valid through the END of the accept window, not just the bid deadline diff --git a/x-tokenization/examples/skills/credit-token.md b/x-tokenization/examples/skills/credit-token.md index 2d4d4e29..3d6f627d 100644 --- a/x-tokenization/examples/skills/credit-token.md +++ b/x-tokenization/examples/skills/credit-token.md @@ -111,7 +111,7 @@ MUST include an alias path so tokens display nicely: }, "symbol": "", "denomUnits": [], - "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" } + "metadata": { "uri": "ipfs://METADATA_ALIAS_u", "customData": "" } }] ``` diff --git a/x-tokenization/examples/skills/crowdfund.md b/x-tokenization/examples/skills/crowdfund.md index cb11535b..8357fb3b 100644 --- a/x-tokenization/examples/skills/crowdfund.md +++ b/x-tokenization/examples/skills/crowdfund.md @@ -17,6 +17,7 @@ Required standards: ["Crowdfund"] - maxScalingMultiplier: MAX_UINT for unrestricted scaling - Deposit coinTransfer.to = "Mint" (auto-resolves to escrow) - requireToEqualsInitiatedBy: true on deposit-refund (contributor receives their own refund token) +- invariants: \`noForcefulPostMintTransfers: true\` β€” the refund approval (non-mint) MUST NOT set \`overridesFromOutgoingApprovals\` or \`overridesToIncomingApprovals\` (both must be false or omitted). It relies on \`defaultBalances.autoApproveSelfInitiatedOutgoingTransfers: true\` for the outgoing side and on the burn destination for the incoming side. The deposit-refund / deposit-progress / success approvals ARE Mint-side and keep \`overridesFromOutgoingApprovals: true\` as the chain requires, with \`overridesToIncomingApprovals: false\` - All permissions frozen after creation - DON'T use votingChallenges β€” goal tracking is via mustOwnTokens, not voting - DON'T forget allowAmountScaling on ALL 4 approvals diff --git a/x-tokenization/examples/skills/liquidity-pools.md b/x-tokenization/examples/skills/liquidity-pools.md index fd4071e6..2d0c9a68 100644 --- a/x-tokenization/examples/skills/liquidity-pools.md +++ b/x-tokenization/examples/skills/liquidity-pools.md @@ -50,9 +50,9 @@ When enabling liquidity pools for a collection, follow these requirements: "decimals": "6", "symbol": "vATOM", "isDefaultDisplay": true, - "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" } + "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom_UNIT", "customData": "" } }], - "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" } + "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom", "customData": "" } }] } ``` @@ -61,6 +61,6 @@ When enabling liquidity pools for a collection, follow these requirements: - disablePoolCreation MUST be false (not true) - MUST configure at least one alias path (required for liquidity pools) -- All alias path and denomUnit metadata MUST include an `image` field with a valid URL (token logo) +- PathMetadata (on every aliasPath and denomUnit) is ONLY `{ uri, customData }`. Put the token logo in the off-chain JSON at the placeholder URI and register a matching entry in `metadataPlaceholders` β€” never put `image` on the proto. - Merkle challenges are NOT compatible with liquidity pools - This enables decentralized exchange (DEX) trading interfaces diff --git a/x-tokenization/examples/skills/prediction-market.md b/x-tokenization/examples/skills/prediction-market.md index d4fd9385..0f6fb932 100644 --- a/x-tokenization/examples/skills/prediction-market.md +++ b/x-tokenization/examples/skills/prediction-market.md @@ -11,6 +11,7 @@ Required standards: ["Prediction Market"] - Binary prediction market: "Will X happen by Y?" Users deposit USDC to mint paired YES+NO tokens. Trade YES↔NO on a liquidity pool. Verifier settles by voting. Winner redeems 1:1. - Token ID 1 = YES, Token ID 2 = NO (via alias paths with 6 decimals) - mintEscrowAddress holds all deposited USDC +- invariants: \`noForcefulPostMintTransfers: true\` β€” locks non-mint approvals (redeem, settlement, transferable) from using \`overridesFromOutgoingApprovals\` or \`overridesToIncomingApprovals\`. Non-mint approvals rely on \`defaultBalances.autoApproveSelfInitiatedOutgoingTransfers: true\` for outgoing-side auth and on the burn destination for incoming-side auth - All permissions frozen after creation - 7 approvals: paired mint, freely transferable, pre-settlement redeem, yes-wins, no-wins, push-yes, push-no - Alias paths for YES (token 1) and NO (token 2) with 6 decimals diff --git a/x-tokenization/examples/skills/product-catalog.md b/x-tokenization/examples/skills/product-catalog.md index a88e4ab7..5cc24f4f 100644 --- a/x-tokenization/examples/skills/product-catalog.md +++ b/x-tokenization/examples/skills/product-catalog.md @@ -13,7 +13,7 @@ Required standards: ["Products"] - Each purchase approval: fromListId="Mint", toListId="All" (or burn address if burn-on-purchase), 1 coinTransfer paying the store address - Payment goes directly to store address (NOT to escrow) β€” overrideFromWithApproverAddress: false - Each product has independent price, supply limit (maxNumTransfers), and burn-on-purchase toggle -- predeterminedBalances.startBalances: 1x of that product's token ID +- predeterminedBalances.incrementedBalances.startBalances: 1x of that product's token ID - Optional burn approval: !Mint β†’ burn address, no coinTransfers - invariants: { noCustomOwnershipTimes: true } - All permissions frozen after creation diff --git a/x-tokenization/examples/skills/smart-token.md b/x-tokenization/examples/skills/smart-token.md index ec4033a2..dba21c9f 100644 --- a/x-tokenization/examples/skills/smart-token.md +++ b/x-tokenization/examples/skills/smart-token.md @@ -20,8 +20,8 @@ Required standards: ["Smart Token"] - Unbacking fromListId uses "!Mint:backingAddress" syntax (excludes both Mint and backing address β€” meaning only regular holders can unback) - Backing address is deterministic β€” use generate_backing_address tool - Optional: Add "AI Agent Vault" to standards for AI Prompt tab (display-only) -- Alias path: symbol = base unit (e.g. "uvatom"), denomUnits = display units with decimals > 0 only, each denomUnit MUST have metadata with an image -- All alias path and denomUnit metadata MUST include an `image` field (token logo URL) +- Alias path: symbol = base unit (e.g. "uvatom"), denomUnits = display units with decimals > 0 only, each denomUnit MUST have PathMetadata with a placeholder uri +- PathMetadata ONLY has `{ uri, customData }` β€” do NOT include image/name/description fields. Set metadata.uri to a placeholder like `"ipfs://METADATA_ALIAS_"` and register the image/name/description in the metadataPlaceholders sidecar keyed by that URI ## Instructions @@ -182,9 +182,9 @@ MUST configure at least one alias path. Structure: "decimals": "6", "symbol": "vATOM", "isDefaultDisplay": true, - "metadata": { "uri": "ipfs://...", "customData": "" } + "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom_UNIT", "customData": "" } }], - "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" } + "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom", "customData": "" } }] } ``` @@ -192,10 +192,9 @@ MUST configure at least one alias path. Structure: Rules: - symbol = base unit symbol (e.g., "uvatom") - denomUnits = display units with decimals > 0 ONLY (base decimals 0 is implicit) -- Each denomUnit MUST have metadata with an image field (often the same image as the base alias path) -- The alias path itself MUST have metadata with an image field β€” this is the token logo shown in the UI +- Each denomUnit and the path itself MUST have PathMetadata of the form `{ uri, customData }`. Use a placeholder URI like `"ipfs://METADATA_ALIAS_"` / `"ipfs://METADATA_ALIAS__UNIT"`. - isDefaultDisplay: true for the primary display unit -- **CRITICAL**: All metadata objects (alias path, denomUnits, cosmosCoinWrapperPaths) MUST include an `image` field with a valid URL. Missing images will be auto-fixed to a default but you should always provide a descriptive image. +- **CRITICAL**: PathMetadata has EXACTLY two fields β€” `uri` and `customData`. Never add `image`, `name`, or `description` here. Register the name, description, and image for each placeholder URI in the `metadataPlaceholders` sidecar returned alongside the transaction β€” the metadata auto-apply flow uploads the off-chain JSON and substitutes the placeholder URIs with real IPFS URIs after deploy. ### Cosmos Coin Wrapper (Optional) @@ -209,8 +208,8 @@ For wrapping native Cosmos SDK coins, use `allowSpecialWrapping: true` and `cosm "sideA": { "amount": "1" }, "sideB": [{ "amount": "1", "tokenIds": [{ "start": "1", "end": "1" }], "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }] }] }, - "denomUnits": [{ "decimals": "6", "symbol": "ATOM", "isDefaultDisplay": true, "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" } }], - "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" }, + "denomUnits": [{ "decimals": "6", "symbol": "ATOM", "isDefaultDisplay": true, "metadata": { "uri": "ipfs://METADATA_WRAPPER_uatom_UNIT", "customData": "" } }], + "metadata": { "uri": "ipfs://METADATA_WRAPPER_uatom", "customData": "" }, "allowOverrideWithAnyValidToken": false }] } @@ -271,8 +270,8 @@ Require ownership of a 2FA token to withdraw. Add mustOwnTokens to the unbacking ### Metadata Guidance -- Collection metadata, token metadata, alias path metadata, and denomUnit metadata should all have descriptive names/descriptions and images -- Do NOT use lazy placeholder names like "Backing Approval" β€” write real user-facing descriptions explaining what each approval does +- Collection, token, alias path, and denomUnit metadata proto fields are ALL shaped as `{ uri, customData }`. Use placeholder URIs (`ipfs://METADATA_COLLECTION`, `ipfs://METADATA_TOKEN_`, `ipfs://METADATA_ALIAS_`, etc.) and register the real names, descriptions, and images in the `metadataPlaceholders` sidecar keyed by those URIs. The auto-apply flow uploads the off-chain JSON and substitutes the placeholder URIs with real uploaded URIs after deploy. +- Do NOT use lazy placeholder names like "Backing Approval" β€” write real user-facing descriptions inside the metadataPlaceholders entries explaining what each approval / collection / token does. ### Key Rules Summary