Designing for Compatibility

To make your collection compatible with the BitBadges Indexer / API (and thus the official website), please make sure everything is compatible when hosting details off-chain.

Badge and Collection Metadata Format

🖼️Metadata

Off-Chain Balances Metadata

🪙Balance Types

Approval Metadata

For providing additional details about an approval, you can host a JSON via the approval.uri field. This allows the BitBadges site to obtain certain metadata about the approval. Markdown is supported for description.

{
    "name": "....",
    "description": "...."
}

Merkle Challenge Details

In a JSON hosted at merkleChallenge.uri, you can also provide Merkle challenge details if you have self-created a Merkle challenge, such as self-generating codes / passwords. This is only needed if you want compatibility with the BitBadges site and to be able to claim / transfer w/ this Merkle challenge directly on the site. We need to know how to generate the Merkle path for users.

{

    "treeOptions": MerkleTreeJsOptions, // see below
    "isHashed": boolean;
    "leaves": string[];

}

IMPORTANT: Do not reveal any secret codes via leaves (Merkle leaves) here, as whatever is stored here is publicly visible.

Whitelist trees: leaves are the BitBadges addresses and isHashed is false.

Codes trees: leaves are the secret codes SHA256 hashed once and isHashed is true. KEEP THE PREIMAGES (SECRET CODES) PRIVATE. The only thing that should be publicly visible are the hashed codes.

Tree Options

We use the 'merkletreejs' NPM package to construct and build the Merkle trees accordng to the code below. You can use treeOptions to make sure the tree is built correctly.

import { Options as MerkleTreeJsOptions } from "merkletreejs/dist/MerkleTree";

import SHA256 from 'crypto-js/sha256';
import MerkleTree from 'merkletreejs';

new MerkleTree(leavesDetails?.leaves.map(x => {
      return leavesDetails?.isHashed ? x : SHA256(x);
  }) ?? [],
  SHA256,
  treeOptions
)