Developing an NFT Rarity System: Algorithms and On-Chain Verification

Without a well-designed rarity system, a collection of 10,000 tokens trades as a homogeneous mass where price is determined solely by floor price. With a proper system, the top 1% of the collection can be worth 10–50 times the floor — directly impacting liquidity and trader interest. The task consists of two parts: off-chain generation and ranking, and on-chain verification via Merkle tree or metadata storage. We develop such systems turnkey: from algorithm selection to marketplace integration. With over 5 years on the market and dozens of completed NFT projects, our experience guarantees transparency at every stage.

How to Choose the Rarity Score Algorithm?

Statistical rarity (Rarity Tools method)

The classic approach: for each attribute, the frequency of occurrence in the collection is calculated. Score = sum of 1 / trait_frequency across all attributes of the token.

# Pseudocode calculation for nft in collection: score = 0 for trait_type, trait_value in nft['attributes']: frequency = count(trait_value) / total_supply score += 1 / frequency nft['rarity_score'] = score 

Problem with statistical rarity: trait count bias. A token with 10 common attributes can get a higher score than a token with 5 attributes, one of which is unique (1/10000). This is counterintuitive for users.

Information content rarity (Rarity Sniper method)

Uses an information-theoretic approach: each attribute contributes proportionally to its information content -log2(probability).

IC(trait) = -log2(count(trait) / total_supply) 

Information content rarity outperforms statistical rarity by 2–3 times in ranking fairness — it does not suffer from trait count bias.

Normalized score for single-attribute rarities

If the collection has a trait type like "background" with 20 variants and a trait "special" with 2 variants (one of which occurs in 1 token), normalization allows comparing contributions of different trait types on a single scale:

normalized_score(trait) = rarity_score(trait) / max_rarity_score(trait_type) 

Why On-Chain Verification Matters?

Generation and calculation (off-chain)

Python script with three stages:

1. Trait analysis — parse all JSON metadata, build frequency table for each trait_type/trait_value
2. Score calculation — selected algorithm, normalization, ranking
3. Output — updated JSON files with added fields rarity_score, rarity_rank

Key point: metadata is updated before uploading to IPFS. After pinning on IPFS, the CID is fixed — changing rarity score without changing CID is impossible. Transparency and immutability are mandatory for project trust.

Merkle-based on-chain verification

For projects that want on-chain rarity verification (e.g., for issuing bonuses to top-100 holders):

// Merkle proof verification of rarity rank function verifyRarityRank( uint256 tokenId, uint256 rank, bytes32[] calldata proof ) external view returns (bool) { bytes32 leaf = keccak256(abi.encodePacked(tokenId, rank)); return MerkleProof.verify(proof, rarityMerkleRoot, leaf); } 

Gas costs for on-chain verification via Merkle tree are less than $10 per update — saving about 90% compared to full storage. That means a collection with 10,000 tokens can save over $90,000 in gas over its lifetime.

API for aggregators

Rarity Tool, Rarity Sniper, OpenSea — all read metadata from tokenURI(). It is important to correctly format the attributes field:

{ "attributes": [ {"trait_type": "Background", "value": "Gold"}, {"trait_type": "Eyes", "value": "Laser"}, {"display_type": "number", "trait_type": "Rarity Rank", "value": 42}, {"display_type": "number", "trait_type": "Rarity Score", "value": 847.3} ] } 

display_type: "number" allows OpenSea and other marketplaces to show rarity rank as a numeric field with sorting.

Comparison of Rarity Score Algorithms

Statistical rarity is simple and widely supported but suffers from trait count bias; it's best for collections with equal number of attributes. Information content rarity avoids bias and is mathematically fair, making it suitable for variable attribute counts. Normalized score eases comparison but depends on max score, ideal for single-attribute rarities. Overall, information content rarity is often the best choice for most modern collections, outperforming statistical rarity by 2–3 times in fairness.

Development Stages and Timelines

for nft in collection: score = 0 for trait_type, trait_value in nft['attributes']: frequency = count(trait_value) / total_supply score += 1 / frequency nft['rarity_score'] = score 

Typical Mistakes in Rarity System Development

• Trait count not accounted for. Tokens with different numbers of attributes (some NFTs may lack certain trait_type) get an unfair score. Solution: treat None as a separate value with its frequency.
• Score calculated before final generation. If the artist adds new variants after the score calculation, the entire table becomes invalid. Rarity is calculated once on the final collection, before any changes.
• Lack of tiebreaker. Tokens with the same score receive the same rank. Standard approach: tiebreak by tokenId (smaller ID = higher rank for equal scores).

What's Included in the Work

• Documentation of the algorithm and calculation process
• Updated JSON metadata with rarity score and rank
• CSV export of rare tokens
• Merkle tree and verification contract (if needed)
• Support after implementation for 2 weeks

Timelines: 2–3 days for collections up to 10,000 tokens. For larger collections or non-standard algorithms, up to 5 days. Typical development costs range from $2,000 to $5,000 depending on complexity. Contact us — we'll evaluate your case and offer the optimal solution.