# Chain Commands `bb` is the chain node binary `bitbadgeschaind`, a Cosmos SDK binary with the BitBadges modules. This page covers the native commands: key management, transactions, queries, offline signing, and node operation. The SDK verbs (`build`, `deploy`, `api`, and the rest) are forwarded to `bitbadges-cli` and documented on the other CLI pages. ## Example ```bash bb keys add alice bb tx tokenization create-collection ./create-collection.json \ --from alice --chain-id bitbadges-1 --node https://rpc.bitbadges.io:443 \ --gas auto --gas-adjustment 1.5 --gas-prices 10ubadge bb query tokenization collection 2 --node https://rpc.bitbadges.io:443 --output json bb sign-arbitrary alice "auth challenge text" ``` The query prints the on-chain collection document (mainnet output, permissions and default balances trimmed): ```json { "collection": { "collectionId": "2", "collectionMetadata": { "uri": "ipfs://QmXSWKxRjpEVqnUnQP6mwsAqrWHo6KAsKzzhYXNu9KKmGj", "customData": "" }, "tokenMetadata": [ { "uri": "ipfs://QmXSWKxRjpEVqnUnQP6mwsAqrWHo6KAsKzzhYXNu9KKmGj", "customData": "", "tokenIds": [{ "start": "1", "end": "1" }] } ], "customData": "", "manager": "", "collectionApprovals": [], "standards": [], "isArchived": false, "validTokenIds": [{ "start": "1", "end": "1" }] } } ``` Endpoints and chain IDs: [Network](https://docs.bitbadges.io/chain). Mainnet is `bitbadges-1`; testnet (`bitbadges-2`) is offline. {% hint style="info" %} Ask your agent. Queries have MCP equivalents (`query_collection`, `query_balance`, `query_dynamic_store`); signing does not, by design. This prompt works, and the `bb tx` step stays with you and your keyring: ```text Fetch collection 2 from chain and summarize its approvals. ``` {% endhint %} ## keys BitBadges supports Ethereum-style `eth_secp256k1` keys and standard Cosmos `secp256k1` keys. The default keyring backend is `test` (unencrypted). Use `--keyring-backend os` or `file` outside development. ```bash bb keys add alice # new key; save the mnemonic bb keys add alice --recover # from a mnemonic bb keys add alice --key-type secp256k1 # Cosmos key, required by sign-arbitrary bb keys list bb keys show alice bb keys show alice --bech val # validator operator form bb keys export alice # armored private key bb keys import alice keyfile.armor bb keys delete alice ``` ## tx ```bash bb tx tokenization transfer-tokens ./transfer.json --from alice --chain-id bitbadges-1 \ --node https://rpc.bitbadges.io:443 --gas auto --gas-adjustment 1.5 --gas-prices 10ubadge ``` | Flag | Default | Description | | --- | --- | --- | | `--from` | required | Key name or address | | `--chain-id` | `bitbadgeschain` | Cosmos chain ID (`bitbadges-1` on mainnet) | | `--node` | `tcp://localhost:26657` | Node RPC endpoint (`https://rpc.bitbadges.io:443` on mainnet) | | `--gas` | `200000` | Gas limit, or `auto` to simulate | | `--gas-adjustment` | `1.0` | Multiplier with `--gas auto` | | `--gas-prices` | | Use `10ubadge` or higher; fees are calculated from the gas limit. | | `--keyring-backend` | `test` | `os`, `file`, `test` | | `--broadcast-mode` | `sync` | `sync`, `async`, `block` | | `--dry-run` | `false` | Simulate without broadcasting | | `--generate-only` | `false` | Print the unsigned transaction JSON | Generic subcommands under `bb tx`: `sign`, `sign-batch`, `multi-sign`, `multisign-batch`, `validate-signatures`, `broadcast`, `encode`, `decode`, `simulate`. Module subcommands follow. ### tokenization Most commands take a JSON argument, inline or as a file path. Field names match the protobuf messages in [Messages](https://docs.bitbadges.io/token-standard/messages). Every line below also takes the flags from the `tx` table; `FLAGS` stands for `--from alice --chain-id bitbadges-1 --node https://rpc.bitbadges.io:443 --gas auto --gas-adjustment 1.5 --gas-prices 10ubadge`. ```bash FLAGS="--from alice --chain-id bitbadges-1 --node https://rpc.bitbadges.io:443 --gas auto --gas-adjustment 1.5 --gas-prices 10ubadge" # collections bb tx tokenization create-collection ./create-collection.json $FLAGS bb tx tokenization universal-update-collection ./update.json $FLAGS bb tx tokenization update-collection ./update.json $FLAGS bb tx tokenization delete-collection 1 $FLAGS # transfers bb tx tokenization transfer-tokens ./transfer.json $FLAGS # approvals bb tx tokenization set-incoming-approval 1 ./approval.json $FLAGS bb tx tokenization set-outgoing-approval 1 ./approval.json $FLAGS bb tx tokenization delete-incoming-approval 1 agent-daily-budget $FLAGS bb tx tokenization delete-outgoing-approval 1 agent-daily-budget $FLAGS bb tx tokenization update-user-approved-transfers ./approvals.json $FLAGS bb tx tokenization purge-approvals 1 true "" false '[]' $FLAGS # metadata and configuration bb tx tokenization set-setcollectionmetadata ./metadata.json $FLAGS bb tx tokenization set-settokenmetadata ./metadata.json $FLAGS bb tx tokenization set-setcustomdata ./data.json $FLAGS bb tx tokenization set-setstandards ./standards.json $FLAGS bb tx tokenization set-setcollectionapprovals ./approvals.json $FLAGS bb tx tokenization set-valid-token-ids ./tokenids.json $FLAGS bb tx tokenization set-manager ./manager.json $FLAGS bb tx tokenization set-setisarchived ./archived.json $FLAGS # dynamic stores bb tx tokenization create-dynamic-store true $FLAGS bb tx tokenization update-dynamic-store 1 false true $FLAGS bb tx tokenization set-dynamic-store-value 1 bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue true $FLAGS bb tx tokenization delete-dynamic-store 1 $FLAGS # address lists and votes bb tx tokenization create-address-lists ./lists.json $FLAGS bb tx tokenization cast-vote 1 collection bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d multisig-approval proposal-1 100 $FLAGS ``` Example `transfer.json` (alice sends bob one unit of token ID 1 in collection 1): ```json { "collectionId": "1", "transfers": [ { "from": "bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d", "toAddresses": ["bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue"], "balances": [ { "amount": "1", "tokenIds": [{ "start": "1", "end": "1" }], "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }] } ] } ] } ``` | Command | Arguments | | --- | --- | | `create-collection`, `update-collection`, `universal-update-collection`, `set-manager`, `set-valid-token-ids`, `set-setcollectionmetadata`, `set-settokenmetadata`, `set-setcustomdata`, `set-setstandards`, `set-setcollectionapprovals`, `set-setisarchived`, `create-address-lists`, `transfer-tokens`, `update-user-approved-transfers` | `[tx-json-or-file]` | | `delete-collection` | `[collection-id]` | | `set-incoming-approval`, `set-outgoing-approval` | `[collection-id] [approval-json-or-file]` | | `delete-incoming-approval`, `delete-outgoing-approval` | `[collection-id] [approval-id]` | | `purge-approvals` | `[collection-id] [purge-expired] [approver-address] [purge-counterparty-approvals] [approvals-to-purge-json-or-file]` | | `create-dynamic-store` | `[default-value]` | | `update-dynamic-store` | `[store-id] [default-value] [global-enabled]` | | `set-dynamic-store-value` | `[store-id] [address] [value]` | | `delete-dynamic-store` | `[store-id]` | | `cast-vote` | `[collection-id] [approval-level] [approver-address] [approval-id] [proposal-id] [yes-weight]` | Files are easier than inline JSON for anything beyond a one-liner. Prefer `bb build` plus `bb deploy --with-keyring` for the common shapes; it validates before it signs. ### gamm ```bash bb tx gamm create-pool --pool-file ./pool.json $FLAGS bb tx gamm join-pool 2 1000000 1000000000ubadge,1000000ibc/E1116484B327AEE59CDC3DA73D319834781A13DB2A7DFC1F38A30CD45ABF58B8 $FLAGS bb tx gamm exit-pool 2 1000000 1ubadge,1ibc/E1116484B327AEE59CDC3DA73D319834781A13DB2A7DFC1F38A30CD45ABF58B8 $FLAGS bb tx gamm swap-exact-amount-in '[{"poolId":"2","tokenOutDenom":"ibc/E1116484B327AEE59CDC3DA73D319834781A13DB2A7DFC1F38A30CD45ABF58B8"}]' 1000000000ubadge 1 '[]' $FLAGS bb tx gamm swap-exact-amount-out '[{"poolId":"2","tokenInDenom":"ubadge"}]' 2000000000 1000000ibc/E1116484B327AEE59CDC3DA73D319834781A13DB2A7DFC1F38A30CD45ABF58B8 $FLAGS ``` Positional order: `join-pool [pool-id] [share-out-amount] [token-in-maxs]`, `exit-pool [pool-id] [share-in-amount] [token-out-mins]`, `swap-exact-amount-in [routes] [token-in] [token-out-min-amount] [affiliates]`, `swap-exact-amount-out [routes] [token-in-max-amount] [token-out]`. The pool-entry and exit variants (`join-swap-extern-amount-in`, `join-swap-share-amount-out`, `exit-swap-extern-amount-out`, `exit-swap-share-amount-in`) and `swap-exact-amount-in-with-ibc-transfer` follow the same pattern. Arguments and flags are in `bb tx gamm --help`. Message semantics: [gamm messages](https://docs.bitbadges.io/chain/modules/gamm/messages). ## query ```bash NODE="--node https://rpc.bitbadges.io:443 --output json" bb query tokenization collection 1 $NODE bb query tokenization balance 1 bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d $NODE bb query tokenization balance-for-token 1 bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d 7 1788739200000 $NODE bb query tokenization collection-stats 1 $NODE bb query tokenization params $NODE bb query tokenization address-list "bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d:bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue" $NODE bb query tokenization dynamic-store 1 $NODE bb query tokenization dynamic-store-value 1 bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue $NODE bb query tokenization wrappable-balances ubadge bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d $NODE bb query tokenization is-address-reserved-protocol bb1gycvn0nc50lh753dgk4qys5p2sdws8aw7ec9v9gg65pkhm6hqq3qjd3t3n $NODE bb query tokenization all-reserved-protocol-addresses $NODE bb query tokenization approvals-trackers 2 outgoing bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d agent-daily-budget agent-daily-budget overall "" $NODE bb query tokenization num-used-for-merkle-challenge 1 collection bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d code-claim code-claim 0 $NODE bb query tokenization num-used-for-eth-signature-challenge 1 collection bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d eth-gated eth-gated 0x9f1c2b3a4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8 $NODE bb query tokenization vote 1 collection bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d multisig-approval proposal-1 bb1zc268nctj8xwslgw7q22cahs6k4y048agr6fvf $NODE bb query tokenization votes 1 collection bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d multisig-approval proposal-1 $NODE bb query gamm pools $NODE bb query gamm pool 2 $NODE bb query gamm pool-params 2 $NODE bb query gamm spot-price 2 ubadge ibc/E1116484B327AEE59CDC3DA73D319834781A13DB2A7DFC1F38A30CD45ABF58B8 false $NODE bb query gamm estimate-swap-exact-amount-in 2 1000000000ubadge --swap-route-pool-ids=2 --swap-route-denoms=ibc/E1116484B327AEE59CDC3DA73D319834781A13DB2A7DFC1F38A30CD45ABF58B8 $NODE bb query gamm pools-with-filter 1000000 balancer $NODE bb query bank balances bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d $NODE bb query tx 903D4A6E205AD77D334933E3C9BB455012D8A334AA2D98DFD301C3F7E8AB92C6 $NODE bb query block --type=height 10000000 $NODE ``` `bb query bank balances` for an address that holds nothing prints `{ "balances": [], "pagination": {} }`. Every query accepts `--node ` and `--output json`. `q` is an alias for `query`. One page per query with the response shape: [Queries](https://docs.bitbadges.io/token-standard/queries). ## sign-arbitrary ```bash bb sign-arbitrary alice "auth challenge text" echo -n "auth challenge text" | bb sign-arbitrary alice bb sign-arbitrary alice --message-file challenge.txt bb sign-arbitrary alice "auth challenge text" --output raw # only the base64 signature ``` Output for a throwaway `secp256k1` key (real signature, produced offline): ```json { "address": "bb1hz59w73vsqygl7z9zl49yvwjnl534n0yyexmkf", "algo": "secp256k1", "format": "adr36", "message": "auth challenge text", "pubKey": "A7TliNEJ+WoiaZvtnrOrdIuLIaVayagqvp47kF2L3Np3", "signature": "Bk/AuuDrt/kChEgF4myQJMCX//1wqoEffd+4RghpKaU0q2QRpVjw0zaf+WHs3FnM8AsEnKm3CeMLc/2/AfKQ9A==" } ``` Signs any message with a keyring key in ADR-36 format, offline, with no chain access. The output feeds `bb auth login --signature "$SIG" --public-key "$PUBKEY" --message "$MSG"`; see [Auth](https://docs.bitbadges.io/cli/auth). The signed bytes equal Keplr's `serializeSignDoc(makeADR36AminoSignDoc(...))` and verify with `verifyADR36Amino`. | Flag | Description | | --- | --- | | `--message-file ` | Read the message from a file; cannot combine with a positional message. Stdin is read only when neither is supplied. | | `--output ` | Default `json` | | keyring flags, `--home` | Standard Cosmos keyring selection | Only `secp256k1` keys are supported; an `eth_secp256k1` key errors with a pointer to `bb keys add --key-type secp256k1`. EIP-191 support is a planned `--format eip191` flag. ## Node Operation | Command | Purpose | | --- | --- | | `start` | Run the node (Cosmos EVM server flags for JSON-RPC and EVM config) | | `init`, `genesis` | Initialize a home directory; genesis subcommands (`gentx`, `collect-gentxs`, `validate`, and the rest) | | `status`, `version` | Node status; binary version | | `config` | Manage `client.toml` (chain-owned; the SDK's settings live under `bb settings`) | | `export`, `rollback`, `index-eth-tx` | Cosmos EVM additions | | `pre-upgrade` | Pre-upgrade hook for cosmovisor | | `prune`, `snapshots`, `comet` (`tendermint`), `debug` | Standard Cosmos SDK maintenance | Running a validator or full node: [Run a Node](https://docs.bitbadges.io/chain/run-a-node). Build from source: [CLI](https://docs.bitbadges.io/cli#chain-binary-from-source). ## SDK Alternative ```ts import { BitBadgesSigningClient, GenericCosmosAdapter, MsgTransferTokens } from 'bitbadges'; const adapter = await GenericCosmosAdapter.fromMnemonic(process.env.MNEMONIC!, 'bitbadges-1'); const client = new BitBadgesSigningClient({ adapter, network: 'mainnet' }); const msg = new MsgTransferTokens({ creator: client.address, collectionId: '1', transfers: [ { from: client.address, toAddresses: ['bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue'], balances: [ { amount: '1', tokenIds: [{ start: '1', end: '1' }], ownershipTimes: [{ start: '1', end: '18446744073709551615' }] } ] } ] }); const result = await client.signAndBroadcast([msg]); console.log(result.txHash, result.success); ``` The [Signing Client](https://docs.bitbadges.io/sdk/transactions/signing-client) handles gas estimation, sequence management, and broadcasting for every message type. ## Related - [Messages](https://docs.bitbadges.io/token-standard/messages) - [Queries](https://docs.bitbadges.io/token-standard/queries) - [Deploy](https://docs.bitbadges.io/cli/deploy) - [Network](https://docs.bitbadges.io/chain)