Three rarity modes (DEFAULT, HYBRID, CUSTOM) with creator-owned weights, per-token overrides, and trait-type weighting. How rarity scoring stays transparent while letting collection owners express their own intent.
Rarity is one of the most subjective signals in any NFT marketplace. A purely platform-computed score ignores what the creator considers rare; a fully creator-controlled score is unverifiable and easy to game. The marketplace splits the difference: every collection has a transparent platform score, and creators can layer their own scoring on top through one of three modes.
| Mode | Behavior | Best For |
|---|---|---|
DEFAULT | Platform-computed score from on-chain trait distributions | Most collections — no creator action needed |
HYBRID | Blend of platform score and creator-supplied per-token scores using configurable weights | Collections where some tokens have story value beyond raw trait math |
CUSTOM | Ranking driven entirely by creator-supplied scores, but the platform score remains stored on every token for transparency | Generative + manually curated drops, "1/1 within edition" mechanics |
The platform score is never deleted — even in CUSTOM mode it stays on each token row so anyone can compare the creator's ranking to the trait-distribution baseline.
Per-collection settings live in collectionRarityAlgorithms:
| Field | Purpose |
|---|---|
mode | DEFAULT / HYBRID / CUSTOM |
defaultWeight | Weight applied to the platform-computed score in HYBRID mode |
customWeight | Weight applied to the creator-supplied score in HYBRID mode |
config | JSONB blob with optional fine-grained controls: traitValueWeight, traitCountWeight, traitTypeWeights (per-trait-type multipliers) |
createdByAddress / updatedByAddress | Audit trail tying every change back to a wallet |
In HYBRID mode, the effective score for a token is:
score = (defaultWeight * platformScore) + (customWeight * customScore)If only one weight is non-zero, HYBRID degenerates cleanly into DEFAULT or CUSTOM behavior.
Creators can override individual tokens in collectionTokenRarityOverrides regardless of mode:
| Field | Purpose |
|---|---|
tokenIdentifier | Which token within the collection |
customScore | Numeric score used by HYBRID/CUSTOM modes |
customRank | Explicit rank that wins over computed score (useful for "this is the artist's pick") |
label | Optional display label (e.g. "Founder's Edition", "Legendary") |
metadata | Free-form JSONB for whatever else the creator wants to surface |
Override rows are keyed by (collectionId, tokenIdentifier) so a creator can selectively annotate a handful of tokens without touching the rest. Indexes on customScore and customRank keep sort/list queries fast even on collections with tens of thousands of tokens.
Per-token rarity is materialized into collectionTokenStats for cheap lookups:
| Column | Purpose |
|---|---|
traitCount | Number of traits the token carries (a common rarity heuristic) |
defaultRarityScore | Platform-computed score, always present |
defaultRarityRank | Platform-computed rank within the collection |
The marketplace surfaces both the platform values and the override values side-by-side, so buyers can see both views and decide which one matters to them.
A pure trait-distribution score punishes intent. A 1/1 hand-drawn piece that happens to share a common background trait would rank below noisier algorithmic art. By making the override path first-class — and recording every change as an authenticated, audited update — the marketplace lets creators express their actual ranking without forcing buyers to take the creator's word for it. Both numbers are always visible.