📚Overview

This directory contains comprehensive developer documentation for the BitBadges blockchain's x/badges module.

This section is a knowledge dump for how badges operate behind the scenes. For most use cases, you will not care about any of this as it will be handled for you via the site. And if you are self-implementing a badge-gated service, you can just fetch balances and metadata from the API without worrying about the underlying details.

const res = await BitBadgesApi.getBalanceByAddress(collectionId, address, {
    ...options,
});
console.log(res);

const res = await BitBadgesApi.getBadgeMetadata(1, 5);

Table of Contents

1. Introduction - Overview and key concepts

2. Concepts - Core data structures and business logic

3. State - State management and storage patterns

4. Messages - Transaction messages and handlers

5. Queries - Query types and endpoints

6. Events - Event emissions and tracking

7. Examples - Common usage patterns and building blocks

Tokens vs Badges

We use the terms tokens and badges interchangeably. For example, "badgeIds" refers to token IDs. In the past, our niche was primarily earned badges, and we are slowly trying to rollout rebrands to full tokens. However, the core interface is still named "badges" behind the scenes.

Message Reference

Collection Management

• MsgCreateCollection - Create new collection

• MsgUpdateCollection - Update existing collection

• MsgUniversalUpdateCollection - Universal create/update interface with invariants support

• MsgDeleteCollection - Delete collection

Badge Transfers

• MsgTransferBadges - Transfer badges between addresses

User Approvals

• MsgUpdateUserApprovals - Update transfer approvals

Address Lists & Dynamic Stores

• MsgCreateAddressLists - Create reusable address lists

• MsgCreateDynamicStore - Create key-value store

• MsgUpdateDynamicStore - Update dynamic store properties

• MsgDeleteDynamicStore - Delete dynamic store

• MsgSetDynamicStoreValue - Set address-specific store values

• MsgIncrementStoreValue - Increase values for addresses

• MsgDecrementStoreValue - Decrease values for addresses

• More messages... - See full message reference

Query Reference

Core Queries

• GetCollection - Retrieve collection data

• GetBalance - Get user balances

• GetApprovalTracker - Get approval usage data

• GetAddressList - Retrieve address list

• More queries... - See full query reference

Quick Links

• BitBadges Chain Repository

• BitBadges Documentation

• Proto Definitions

Documentation Style

This documentation follows the Cosmos SDK module documentation standards and is designed for developers building on or integrating with the BitBadges blockchain.