# Build, Validate, and Track Use `bb build` to create a standard and its domain command, such as `bb credit-tokens`, `bb subscriptions`, or `bb pay-requests`, to query and use an existing collection. The recipes below use the CLI throughout; no application code or private-key export is required. Set `CREATOR` to the intended creating wallet address and `PAYER` to the paying wallet when they differ. Replace demo addresses, metadata URLs, collection IDs, and dates before building. Choose the same network for every build, query, simulation, signing request, and confirmation. Use CLI `0.45.5` or later for this workflow; check your installed version with `bb --version`. ## 1. Resolve the Intent Record the network, expected signer, recipient addresses, asset denomination, amounts, time constraints, and whether consent applies once or recurs. A ticker such as USDC is insufficient to identify an asset across networks. Convert display amounts using the chosen asset's decimals; keep base units as integer strings throughout JSON. Select a [standard](https://docs.bitbadges.io/standards) whose state machine implements the request. An invoice cutoff is enforced; an informational due date is not a release condition. A partial-payment target transfers funds immediately; it does not promise a refund if the target is missed. Ask for a changed design when the chosen standard cannot enforce a requested term. ## 2. Discover and Build ```bash bb --help-json bb build payment-request-v2 --help bb build payment-request-v2 --example anyone | jq '.data' > terms.json # Edit terms.json: replace demo recipients, amounts, dates, and metadata. bb build payment-request-v2 --json terms.json --creator "$CREATOR" --mainnet --output-file proposal.json bb check proposal.json --mainnet bb explain proposal.json --mainnet ``` `terms.json` contains builder parameters. `proposal.json` is the CLI output envelope containing generated message data and reports. Preserve this distinction when piping commands; follow the accepted input formats in [Build](https://docs.bitbadges.io/cli/build) and [Deploy](https://docs.bitbadges.io/cli/deploy). Never submit a failed envelope as a transaction. The examples use `jq` to extract JSON; the input file for `--json` must contain the parameters, not a CLI envelope. For a published collection, query it and use the standard action helper instead of reconstructing approvals from labels: ```bash bb pay-requests show "$COLLECTION_ID" --mainnet bb pay-requests status "$COLLECTION_ID" --mainnet bb pay-requests pay "$COLLECTION_ID" --creator "$PAYER" --obligation payment-1 --units 1 --mainnet --output-file payment.json bb check payment.json --mainnet ``` Set `COLLECTION_ID` to the real published collection ID before running those queries or paying. Creating a collection and paying it are separate stages; do not assume an agent can guess the new ID or publish without a signer. ## 3. Validate the Real Configuration Inspect the full `bb check` report before proceeding. `--depth structural` checks only message shape and is not a substitute for full review. CLI `0.45.4` has known limitations when reviewing newly created V2 invoices and explaining saved build output; upgrade before following this workflow. Do not strip invoice protections or ignore critical findings to make a report green. Review the actual recipients, units, windows, approvals, and permissions, then simulate and inspect the wallet review before signing. Use [Check, Explain, and Simulate](https://docs.bitbadges.io/cli/analyze). The SDK's standard parser must validate actual approvals, permissions, ranges, trackers, and invariants against the declared terms. A recognized tag, trusted metadata URI, or readable description is not sufficient. Simulation uses current balances and state. Another transaction may consume a payment slot or change account sequence before submission, so the chain remains the final authority. Do not silently enlarge an amount, choose another recipient, or install a wider approval to make a failed simulation pass. ## 4. Request Human Signing Use the [browser handoff](https://docs.bitbadges.io/cli/deploy) when the human owns the funds. The agent prepares an exact request; the human reviews it with their wallet. The agent does not need the human's private key. Payment authorization and login/personal-sign messages are different operations. After checking the proposal, simulate it and request the specific wallet: ```bash bb deploy proposal.json --browser --expected-address "$CREATOR" --mainnet --dry-run bb deploy proposal.json --browser --expected-address "$CREATOR" --mainnet ``` The dry run requires the configured API access; the second command opens a real signing request. For a payment proposal, use `payment.json` and the expected payer instead. Review every message in a batch, including approval changes and fees. One invoice approval may atomically require several recipient payouts or denominations. A friendly title must not hide additional messages. ## 5. Confirm and Reconcile After submission, use `bb tx status` or `bb tx wait` with the returned transaction hash and the same network. Inspect execution success, not just hash presence. Refresh the standard's status after chain confirmation; indexer state can lag the chain. Persist the network, collection ID, obligation/action ID, signer, exact amounts, submitted hash, and final execution result. For payments, retain each obligation separately and each denomination separately. A lost browser callback or timeout is an uncertain outcome: check the wallet and chain before retrying. Reusable links have no terminal paid cap, so an automatic retry can create a second valid payment. ## Manager Visibility The invoice manager table exposes type, participants, payment progress, collected and remaining amounts, due/cutoff information, and state. Search, role/status filters, and pagination narrow the server result set. Use the collection's payment activity to inspect individual receipts. Unknown evidence must remain unknown. Do not substitute zero for a missing tracker, treat an empty page as the end without checking its cursor, or aggregate amounts across denominations. Consult [Payment State and Tracking](https://docs.bitbadges.io/standards/payment-tracking) for the exact model. ## CLI JSON Contract Each complete JSON recipe has a filename and a matching `bb build` command. Save the block to that file; JSON contains builder parameters, not the result envelope from another command. You can also use domain aliases such as `bb credit-tokens build` and `bb products build` where their help exposes the same builder. ```bash bb build credit-token --help bb credit-tokens --help bb credit-tokens show "$COLLECTION_ID" --mainnet bb credit-tokens purchase "$COLLECTION_ID" --units 3 --creator "$PAYER" --mainnet --output-file purchase.json bb check purchase.json --mainnet ``` `purchase` builds a proposal to buy units from an existing collection; it does not create the credit token or confirm a purchase. Choose the collection and inspect its exchange rate first. The same distinction applies to subscription claims, invoice payments, deposits, and marketplace actions. The V2 payment example uses `bb build payment-request-v2 --json terms.json`. Many other builders also accept `--json` from a file, inline JSON, or stdin. Inspect `bb build --help`: JSON input does not bypass required CLI flags. For example, `bb build subscription` still requires `--interval` even when the JSON contains `interval`. For those other builders, keep builder parameters and metadata in the JSON; do not assume flags are merged into it. The V2 payment builder has its own documented [metadata overrides](https://docs.bitbadges.io/cli/build#metadata-modes). Shared transaction fields such as `--creator` are handled separately from builder parameters. Addresses inside JSON, such as `creator`, `manager`, or `seller`, may also scope generated approvals; they are not automatically rewritten to match a different transaction signer. Keep those roles intentional and inspect the emitted result. | Layer | Shape | Consumer | | --- | --- | --- | | Builder parameters | Standard-specific fields such as `interval`, `payouts`, or `obligations` | `bb build --json ` or documented flags | | Unsigned message | Generated `typeUrl` and `value`, or documented message wrapper | Transaction validation, simulation, and review | | CLI result | `ok`, `data`, `warnings`, `error` | Automation checks `ok` before reading `data` | | Chain state | Current collection, balances, approvals, trackers | Standard parser and action helper | | Application record | Indexed status and activity | Dashboard/discovery; reconcile against confirmed execution | For command options and supported actions, run `bb --help` or inspect `bb --help-json`. SDK function names remain secondary references for integrations that need TypeScript; the JSON inputs correspond to those functions, but CLI users do not need to call them. JSON Schema describes structure only when a tool exposes it; there is no universal standard schema that can replace each standard's semantic validator. ## Metadata JSON A hosted collection metadata document uses the following basic fields. Replace the example image URL and host this JSON before passing its URI to a builder; creating a builder message does not upload the file. ```json { "name": "Developer Test Collection", "description": "Terms and purpose for the reviewer to inspect.", "image": "https://example.com/collection.png" } ``` Metadata communicates intent. Recipients, quantities, timing, supply, and authorization must also exist in the enforceable message configuration.