Valid Badge IDs

Valid Badge IDs define the range of badge IDs that exist within a collection. This is mainly informational but also may be used to enforce certain rules within the collection.

Key Concepts

Badge ID Range Definition

• The range of valid badge IDs (e.g., 1-100) must be defined on-chain in the core collection details

• IDs must start at 1 and have no gaps

• This range is separate from circulating supply

Separation from Circulating Supply

• Valid badge IDs define what can exist

• Circulating supply defines what actually exists

• Circulating supply is managed through transfers/approvals and balance allocations

• Circulating supply should obey the valid badge IDs defined on-chain

Creating Badge IDs

During Collection Creation

Use the validBadgeIds field in MsgCreateCollection:

{
    "creator": "bb1...",
    "validBadgeIds": [
        {
            "start": "1",
            "end": "100"
        }
    ],
    "collectionPermissions": {
        "canUpdateValidBadgeIds": [
            // { ... }
        ]
    }
}

During Collection Updates

Use the validBadgeIds field in MsgUpdateCollection:

{
    "creator": "bb1...",
    "collectionId": "1",
    "validBadgeIds": [
        {
            "start": "101",
            "end": "200"
        }
    ]
}

Permission Control

Updates to valid badge IDs must obey the canUpdateValidBadgeIds permission:

Permission Structure

"canUpdateValidBadgeIds": [
  {
    "badgeIds": [{"start": "1", "end": "1000"}],
    "permanentlyPermittedTimes": [{"start": "1", "end": "18446744073709551615"}],
    "permanentlyForbiddenTimes": []
  }
]

Permission Behaviors

Note that the canUpdateValidBadgeIds permission applies to the updatability of the validBadgeIds field.

We find the first-match for (current time, badge ID) for each badge ID that is changed, and check the permission for that time. If no time matches, the permission is default enabled. See Permissions for more details.

Permission Best-Practices

Typically, the desired functionality falls into one of the following categories:

• Set and Lock All: Set the valid badge IDs upon genesis and lock everything from further updates

• Set and Lock All Current, Allow Expansion: Set the valid badge IDs upon genesis and lock the current ones from being updated, but allow expansion in the future.

Examples

Basic Badge Creation

// Create badges 1-50
{
    "validBadgeIds": [
        {
            "start": "1",
            "end": "50"
        }
    ]
}

Expanding Badge Range

// Later add badges 51-100 (must be sequential)
{
    "validBadgeIds": [
        {
            "start": "1",
            "end": "100"
        }
    ]
}

Best Practices

1. Plan ahead: Consider future expansion when setting initial badge ID ranges

2. Sequential additions: Always add badge IDs sequentially to maintain the no-gaps requirement

3. Permission management: Carefully configure canUpdateValidBadgeIds permissions based on collection lifecycle

4. Documentation: Clearly document the intended use of different badge ID ranges