Skip to main content

Rarity DTO

Schema for NFT card/rarity definitions used in drop APIs.

Description​

The Rarity DTO schema defines the structure of NFT card information including rarity levels, images, and game mechanics values. Used in drop responses and wallet NFT queries.

Class Validator Schema​

import { IsNumber, IsOptional, IsString } from "class-validator";

export class RarityDto {
  @IsNumber()
  rarity: number;

  @IsString()
  image: string;

  @IsString()
  @IsOptional()
  animation?: string;

  @IsNumber()
  burnThreshold: number;

  @IsString()
  name: string;

  @IsNumber()
  base: number;

  @IsNumber()
  stack: number;

  @IsNumber()
  maximum: number;
}

TypeScript Type​

interface RarityDto {
  rarity: number;
  image: string;
  animation?: string;
  burnThreshold: number;
  name: string;
  base: number;
  stack: number;
  maximum: number;
}

Example​

{
  "rarity": 1,
  "image": "https://example.com/common-card.jpg",
  "animation": "https://example.com/animation.mp4",
  "burnThreshold": 100,
  "name": "Common Card",
  "base": 50,
  "stack": 10,
  "maximum": 1000
}

Field Descriptions​

FieldTypeRequiredDescription
raritynumberYesRarity level (1 = common, 2 = rare, etc.)
imagestringYesCard image URL
animationstringNoCard animation URL (optional)
burnThresholdnumberYesBurn threshold value
namestringYesCard/rarity name
basenumberYesBase game mechanics value
stacknumberYesStack game mechanics value
maximumnumberYesMaximum game mechanics value

Example Response​

{
  "id": "rarity-1",
  "name": "Common",
  "probability": 0.7,
  "maxSupply": 7000
}

Field Descriptions​

FieldTypeRequiredDescription
idstringYesUnique identifier for the rarity tier
namestringYesHuman-readable rarity name
probabilitynumberYesProbability of minting this rarity (0-1)
maxSupplynumberYesMaximum number of NFTs for this rarity tier

Common Rarity Tiers​

Typical rarity tier names include:

  • Common: Most frequent, highest probability
  • Uncommon: Less frequent than common
  • Rare: Uncommon, lower probability
  • Epic: Very rare, low probability
  • Legendary: Extremely rare, lowest probability

Usage Example​

// Example rarity configuration
const rarityTiers = [
  {
    id: "rarity-1",
    name: "Common",
    probability: 0.7,
    maxSupply: 7000,
  },
  {
    id: "rarity-2",
    name: "Uncommon",
    probability: 0.2,
    maxSupply: 2000,
  },
  {
    id: "rarity-3",
    name: "Rare",
    probability: 0.08,
    maxSupply: 800,
  },
  {
    id: "rarity-4",
    name: "Epic",
    probability: 0.015,
    maxSupply: 150,
  },
  {
    id: "rarity-5",
    name: "Legendary",
    probability: 0.005,
    maxSupply: 50,
  },
];

// Validate probabilities sum to 1
const totalProbability = rarityTiers.reduce((sum, tier) => sum + tier.probability, 0);
console.log("Total probability:", totalProbability); // Should be 1.0

Validation Rules​

  • probability: Must be between 0 and 1
  • maxSupply: Must be a positive integer
  • id: Must be a unique string identifier
  • name: Must be a non-empty string

Next Steps​