Why an NFT Rarity System Breaks on the First Release
An NFT rarity system is most often assembled from two independent parts: the rarity table lives in a spreadsheet, while metadata generation lives in a separate script.
Layer and attribute weights are set by eye, are not recorded anywhere, and are not checked for convergence, while NFT rarity calculation is done manually after release — when it is too late to change anything. On a demo collection of a dozen tokens, this goes unnoticed.
On a mass release, statistics kick in. If weights are not normalized to one, attributes within a layer conflict, or some combinations are prohibited, the generator starts selecting not what is stated in the collection description.
The skew of the rarity distribution becomes visible across thousands of tokens: single items drop in batches, while the declared “one in ten thousand” appears in every hundredth.
Duplicate attributes and forbidden combinations go unnoticed — verification is done by eye on a sample.
Manual rarity tables do not scale for another reason: they are not connected to the release code. Any change to a weight after metadata is uploaded to storage requires recalculation and re-release, and already minted tokens cannot be fixed.
Rarity calculated after the fact turns into a marketing promise without technical backing — and into the first dispute with a buyer.
The root of the problem is not the generator itself, but the absence of a fixed rarity model: weights, compatibility rules, and the selection algorithm must be a single source of truth, verifiable before release. We break down how this is addressed.
What a Calculated Collection Rarity Model Provides
A collection rarity model is a distribution defined before generation: each trait is assigned a weight, and for a tier (common, rare, legendary) it is fixed in advance how many items will receive it.
Rarity metrics — trait frequency, total score, position in the top — are calculated on this distribution, not after release, so the share of rare items is known in advance to within individual items.
Release predictability rests on hard limits on trait combinations and duplicate checks: if a couple of percent of items fall into the same visual row, the collection loses value on the secondary market.
Therefore, we run the distribution through a simulation at full volume and compare actual shares for each tier against the plan.
Resistance to manipulation comes from the workflow: images and metadata are generated before release, fixed with checksums, and the order of issuance is tied to a pre-announced seed number.
Neither the team nor a buyer can substitute token contents after release — positions in rankings on marketplaces like OpenSea are calculated from public metadata.
Repeatability is the main measurable effect: each subsequent release is assembled on the same model, plan and actual converge, and deviation for rare tiers remains within fractions of a percent.
We deliver a report with rarity metrics together with the collection so the distribution can be verified independently.
Approaches to Rarity Calculation: Comparison of Options
Rarity is a derivative of metadata, not a property of an image. Therefore, the chosen approach to rarity calculation determines what the owner will see in the catalog and how the secondary market will behave after each new release.
The difference between the options comes down to two decisions: what exactly we consider the measure of rarity — weights and rankings of individual traits or their combinations — and where the calculation is performed, off-chain or on the blockchain.
This affects the amount of work during release, the possibility of recalculation, and whether an outside observer can verify the result.
| Option | When it fits | Limitations |
|---|---|---|
| By trait weights | 5–15 traits, there are clear “legendary” values | Weights are calibrated manually; the rarity of a pair of traits is not visible |
| By ordinal ranks | One number per token is needed for sorting and storefronts | Rank does not explain how rarity was accumulated; ties are possible with equal sums |
| By trait combinations | Value is created by a combination, not a single value | Recalculation volume grows with the number of traits |
| Off-chain calculation | Metadata is prepared before release, edits and audits are needed often | The result is not verified on the blockchain — trust rests on the export |
| On-chain calculation | Public verifiability of the rank for each token is needed | Release is more expensive, recalculation after token creation is impossible |
In practice, we most often settle on a hybrid: heavy recalculation by combinations is performed off-chain using a fixed trait table, while a compact confirmation of the final rank remains on-chain.
The client gets a predictable release cost and a verifiable result, while the rarity formula remains replaceable if the collection rules change.
How We Implement Rarity Calculation: Work Stages
Rarity calculation relies on token traits and the frequency of their values, so any heterogeneity in metadata distorts the final ranking. We work in sequential stages — from collection audit to handover of system management, with the result recorded at each step.
-
Collection audit. We export metadata for all tokens, inventory traits and their values, and look for gaps, duplicates, and different spellings of the same thing. The output is a summary distribution table: it shows which values are unique and which cover half the collection.
-
Weight scheme. We agree on rules: a trait's contribution to the final score, accounting for the rarity of a value within a trait, handling traits with a single variant. We record the rules in a document so there are no disputes about the result.
-
Calculation setup. We implement a calculation that assigns each token a score and a place in the ranking. We move weights and thresholds into configuration — they can be changed without editing code and re-releasing.
-
Test release verification. We run the calculation on a limited batch: compare the top and tail of the distribution, review borderline cases with equal scores, and check ranking stability when new tokens are added.
-
Comparison with expectations. We show the rarity distribution and points of divergence from the intent, and calibrate the formula until it matches.
-
Handover of system management. We provide the configuration, recalculation regulations, and the procedure for changing metadata, and train the team — the calculation is updated without our involvement.
Project Artifacts: From Weight Scheme to Regulations
After completion, the system does not remain a black box: the client receives a set of artifacts that its team uses to run collections independently — add traits, change weights, recalculate rarity, and ship new releases without our involvement.
- Weight and trait scheme — a list of all collection attributes with probability distribution by tier and boundaries where a trait is considered rare.
- Rarity scoring rules — the final rank algorithm: how weights add up and how a rare trait combination affects a token's position.
- Recalculation procedure — when and in what order recalculation is launched after new releases or trait edits, and how already issued ranks are preserved.
- Access policies — a role matrix: who changes weights, who launches recalculation, who confirms publication, and how each action is logged.
- System documentation — description of modules and connections between them, data schema, deployment and failure recovery instructions.
- New collection launch checklist — the sequence of steps from trait upload to publication, so launch does not depend on a specific engineer.
Separately, we hand over regulations for disputed situations: duplicate metadata, rank discrepancies after a change in trait composition, access revocation — with the procedure for recording the decision and the person responsible for it.
We review each item on a call and test it on a real collection: you change a trait weight, launch recalculation, and compare the result. Anything that remains unclear we close before handing over access.
Case Study: Rebuilding the Rarity of a 10,000-Item Collection
A collection of 10,000 items was assembled manually: trait rarity was calculated in spreadsheets, incompatible combinations were filtered out by eye, and tier distribution was checked after publication on the OpenSea marketplace.
By the middle of generation, a skew became visible — the share of legendary items came out several times lower than planned, and some trait sets repeated in dozens of copies.
We rebuilt generation as a computational model. Layers received weights, a target distribution of rare tiers was defined for the collection, and incompatibility rules for traits were described as a separate block.
The rarity score of each item is calculated from the probabilities of all its traits, not from the order of appearance in the list, so the result converges with the plan without manual adjustment.
What Changed
- Deviation of rare tiers from plan: was several times off — became up to 0.1 p.p.
- Share of duplicate trait sets: was about 6% — became 0.
- Manual batch verification: was about 20 hours — became a few minutes to read the report.
- Rebuilding the collection with new weights: instead of a week of edits — one run.
The model lives in the repository together with the layer configuration and distribution report: rarity rules can be changed and the collection recalculated for new mechanics without rewriting the generator.
The metadata file with scores is exported once and works both for upload and for independent audit verification.
How Static Rarity Differs from Dynamic Rarity
Static rarity is fixed at the moment of release: trait weights are calculated once across the entire collection, a token's ranking is the sum of the weights of its traits, and the value does not change afterward.
The scheme is deterministic: any holder reproduces the calculation from the same data snapshot and gets the same rank. There are almost no disputed situations, and verification does not require trust in our side.
Dynamic rarity is recalculated based on events: minting, transfer, burning, trait change, staking. Updatable weights depend on the current distribution, so the ranking reflects the real picture rather than the one at launch.
The price for this is idempotency of recalculation and versioning of the weights themselves; otherwise the metric will drift.
Technically, recalculation is built incrementally: an event changes only the affected traits, while the rest are taken from the latest snapshot. Each ranking version is stored separately — past states remain reproducible.
This is needed both for dispute resolution and for storefronts that display a token's number with a delay.
Typical failures are immediately visible: without versioning, indexing services and the smart contract diverge in numbers, and without idempotency one transfer shifts the ranking twice.
On Ethereum and other public networks, this results in different rarity assessments on different platforms, and holders stop trusting the metric.
The choice is not binary. Fixed weights suit collections with unchanging traits, where predictability is valuable. Dynamics are needed where traits evolve and rarity must account for holder activity. A workable compromise is base weights at release plus a dynamic multiplier on top of them.
Common Technical Questions About Rarity Calculation
Rarity is not a single number, but a rule: which attributes are considered formed, how their occurrence is determined, and how rank is derived from it. Until the rule is fixed, a dispute about “correct” rarity is settled by eye.
Below are the doubts that come up before the start.
How is rarity calculation protected from substitution?
The rule and metadata snapshot are fixed before release: rank is calculated from an immutable set of attributes, and the result and checksum of the input data go into versioned storage. A new update creates a new snapshot, while the previous one remains available.
Together with the calculation, we hand over the attribute specification, weight table, and a reproducible recalculation script that your team can use to repeat the result.
What happens if weights are changed for already released items?
Recalculation using new weights gives a different order, so the rules are versioned: each item retains a reference to the version by which it was evaluated. A weight change becomes an announced event rather than a silent edit — holders see that the rank changed and on what basis.
Will the calculation withstand a mass release?
Recalculation happens at the batch preparation stage, not at the moment of release: a full pass over attribute combinations is performed in batches, and ranks and metadata are published in advance.
During release, a link to the ready document is inserted, so collection growth does not turn into a transaction queue.
Let's Discuss the Task: What Data Is Needed for an Estimate
Timeline estimation for a rarity system relies on the collection's input data: attribute distribution rules, metadata format, and requirements for verifying rare items determine the scope of work and the order of stages.
Send them in any form — a spreadsheet, generation file, or free-form description: the fewer assumptions, the more accurate the plan.
- Collection size, number of attributes, and number of values within each — the data schema and storage method depend on this.
- Rarity distribution rules: fixed weights, percentages by tier, or manual lists of unique items.
- Forbidden attribute combinations and which combinations are considered rare by design, not by calculation.
- Image source files: ready layers, vector graphics, or assembly on the application side.
- Metadata format and display platforms — they determine required description fields and verification requirements.
- Where rarity is calculated: generated in advance or checked on contract calls, and who gets access to the keys.
- What is already ready — contracts, generation scripts, mockups, repository, testnet access.
- Priorities: the mandatory minimum for launch and what can be moved to the second stage.
Send what you have: we will assemble the data schema, separately record assumptions, and come back with a timeline estimate and work plan. We will agree on the order of stages before the start so the scope does not change along the way.