Smart Tokens and existing vaults

Smart Token represents a token backed by an existing chain coin. Deposit and withdrawal use the coin-backed path and reserved backing address. This page covers the shipping Smart Token and Vault builders; it does not include the paused Agent Vault standard.

Configuration and variants#

bb build smart-token --backing-coin USDC --symbol vUSDC \
  --creator "$CREATOR" --uri "$METADATA_URI"
bb build vault --backing-coin USDC --daily-withdraw-limit 100 \
  --creator "$CREATOR" --uri "$METADATA_URI"
bb smart-tokens show "$COLLECTION_ID"
bb smart-tokens status "$COLLECTION_ID"

A daily limit uses backing-coin display units at construction and is converted to base units. It is per initiator, not a global reserve limit or necessarily a holder limit. The generated schedule starts at the next UTC midnight and repeats every 86,400,000 milliseconds. Before that first reset, the initial tracker interval applies. Separate approvals have separate counters even if their tracker labels match.

The existing --ai-agent-vault Smart Token flag is only a discovery tag. It does not add agent delegation, spending policies, or the paused Agent Vault behavior. Emergency recovery is a substantive trust decision: the designated address can move holders' tokens. It is not merely a contact field.

Lifecycle and state#

bb smart-tokens list, show, and status expose recognized collections. Use bb smart-tokens deposit <collection-id> --creator <address> --amount <n> or bb smart-tokens withdraw <collection-id> --creator <address> --amount <n>. Both interpret amounts as display units by default and accept --base-units for raw integers. There is no separate bb vaults action group. Generic Smart Token actions are applicable only when their validator accepts the actual vault configuration; extra withdrawal gates may require matching proof or authorization inputs.

Depositing locks backing coins and obtains the backed token. Withdrawing returns tokens through the backing path and releases backing coins, subject to the approval and user authorization checks. These are not invoice payments: inspect reserve state, token balances, and the backing invariant rather than a payment completion tracker.

The vault deposit and withdrawal approvals use backed-minting authorization, not forceful overrides of the reserved backing address. The vault disables pool creation and freezes permissions. Existing aliases/wrapper denominations must satisfy chain naming and uniqueness rules; a display symbol is not proof that a new denomination is available.

Review Smart Token primitives, coin wrapper paths, invariants, ownership gates, and liquidity pools. Validate the actual backing path and approval shape before treating a tagged collection as redeemable.

Smart Token JSON#

Save the following input as smart-token.json, replace the demo addresses and metadata, then build it with the CLI command below. backingCoin resolves a supported backing denomination. symbol configures the wrapper display path. tradable adds the pool capability; it does not create a funded pool. The forceful-transfer flag controls the invariant, not a particular delegated payment permission.

{
  "backingCoin": "BADGE",
  "symbol": "vBADGE",
  "tradable": true,
  "allowForcefulPostMintTransfers": false,
  "uri": "https://example.com/metadata.json"
}

bb build smart-token --json smart-token.json \
  --backing-coin "$(jq -r '.backingCoin' smart-token.json)" \
  --creator "$CREATOR" --output-file smart-token-proposal.json

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the CLI lifecycle. SDK reference: buildSmartToken.

Vault JSON#

Save the following input as vault.json, replace the demo addresses and metadata, then build it with the CLI command below. dailyWithdrawLimit is a display-unit number per initiating address per reset interval; zero means unlimited. Optional require2fa is a collection ID string and emergencyRecovery is an address. Those fields add authorization paths and must be reviewed explicitly.

{
  "backingCoin": "BADGE",
  "symbol": "vBADGE",
  "dailyWithdrawLimit": 100,
  "uri": "https://example.com/metadata.json"
}

bb build vault --json vault.json \
  --backing-coin "$(jq -r '.backingCoin' vault.json)" \
  --creator "$CREATOR" --output-file vault-proposal.json

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the CLI lifecycle. SDK reference: buildVault.

IBC Token Factory#

The frontend's IBC Token Factory template creates a token with a Cosmos coin wrapper path. It is distinct from the Smart Token's existing-coin backing invariant. A wrapper converts collection token balances into a corresponding chain coin denomination; it does not by itself make the asset backed by USDC or another external reserve.

The /mint/ibc-token form uses token ID 1, mint and wrapper approvals, a one-to-one conversion path, allowSpecialWrapping: true, and no manager. Its wrapper path defines denomination metadata and conversion balances. Use generic collection/session tools and the wrapper path reference for SDK construction; the CLI has no bb build ibc-token command.

The following field fragment identifies the capability; it is not the complete collection. The required approvals and cosmosCoinWrapperPaths configuration must also be present and validated.

{
  "standards": ["IBC Token Factory"],
  "validTokenIds": [{ "start": "1", "end": "1" }],
  "invariants": { "allowSpecialWrapping": true }
}

Inspect both the original collection balance and the wrapped coin balance when reconciling conversions. A symbol is not a denomination identifier, and denomination paths must satisfy chain naming/uniqueness requirements. An IBC-compatible representation is not evidence that a cross-chain transfer or remote-chain registration has completed.