Beasts NFT Collection

Beasts is a fully onchain NFT collection featuring 75 unique monster species that integrate with the Loot Survivor game ecosystem on Starknet. Each Beast is dynamically generated with unique attributes, names, and artwork—all stored and rendered directly from the blockchain.

Overview

The Beasts are a collection of digital-native creatures, born onchain and built for battle. With 1,243 variants across 75 species, the fixed supply of 93,225 Beasts balances abundance and scarcity. Beasts carry two sets of traits: visual and combat.

• Visual traits power collecting: Shiny and Animated forms activate pixel-perfect effects. Each Beast has live ranking within its species (1–1,243) that updates as new Beasts are minted; once a species is complete, a King Beast is crowned.
• Combat traits power play: On mint, a Beast includes level and health. Together with its type and tier, this defines a combat profile compatible with the Loot Survivor system that first brought Beasts into the world.
• Live, credibly neutral traits such as Adventurers slain, last Adventurer who defeated a Beast, and timestamp of that defeat enable long-term growth systems without hardcoding game logic.
• Beasts are earned by worthy Adventurers in the dungeons of Loot Survivor using verifiable randomness. Every step is etched onchain for permanent provenance. For collectors, Beasts offer verifiable scarcity and provenance; for players, they unlock endless onchain fun.

🎨 Example Beasts

🚀 Features

• 🎨 Fully Onchain Artwork: Every Beast’s image data and metadata are generated onchain
• 🎮 Born Onchain: Beasts emerge from the dungeons of Loot Survivor
• ⚔️ Battle-Ready: Each Beast is minted with level and health and is compatible with the Loot Survivor combat system
• 🏛️ 75 Unique Species: From mystical Warlocks to fierce Minotaurs, each with distinct visual traits
• 📊 Tiered Rarity System: 5 tiers with visual indicators through border colors and effects

📦 Installation

Prerequisites

• Scarb 2.10.1
• Starknet Foundry 0.46.0
• Cairo Coverage 0.5.0 (for test coverage)

Setup

1. Clone the repository:

git clone https://github.com/Provable-Games/beasts.git
cd beasts

2. Build contracts:

scarb build

3. Run tests:

snforge test

🏗️ Architecture

Smart Contract Structure

src/
├── lib.cairo                  # Entry point; exposes modules and ERC721 contract (beasts_nft)
├── pack.cairo                 # Attribute packing (id, name parts, level, health, shiny, animated)
├── beast_definitions.cairo    # 75 species definitions and names
├── beast_manager.cairo        # Validation and uniqueness hashing
├── beast_ranking.cairo        # Per-species live ranking + king logic
├── metadata_generator.cairo   # Onchain JSON metadata generation
├── beast_svg.cairo            # Dynamic SVG artwork generation
├── minting_coordinator.cairo  # Single and batch mint prep
└── interfaces.cairo           # External interfaces (image data providers, systems)

Beast Data Model

Each Beast is efficiently packed into 53 bits:

PackableBeast {
    id: u8,       // 7 bits - species (1–75)
    prefix: u8,   // 7 bits - name prefix
    suffix: u8,   // 5 bits - name suffix
    level: u16,   // 16 bits - level
    health: u16,  // 16 bits - health
    shiny: u8,    // 1 bit  - visual trait
    animated: u8, // 1 bit  - visual trait
}

🎮 Beast Types & Tiers

Beast Types

• 🔮 Magical: Mystical creatures with arcane powers
• 🏹 Hunter: Swift and agile predators
• ⚔️ Brute: Raw strength and physical dominance

Tier System

• Tier 1: Orange borders (Legendary) - Most powerful beasts
• Tier 2: Purple borders (Epic)
• Tier 3: Blue borders (Rare)
• Tier 4: Green borders (Uncommon)
• Tier 5: White borders (Common) - Entry level beasts

🧪 Testing

Run the comprehensive test suite:

# Run foundry with coverage
snforge test --coverage

# Summarize coverage locally
lcov --summary coverage/coverage.lcov

CI enforces formatting and coverage on patches (≥35%); aim for ≥80% overall when feasible.

🚢 Deployment

1. Configure environment variables:

cp .env.example .env
# Edit .env with your configuration

Required in .env (no defaults are assumed):

• STARKNET_ACCOUNT, STARKNET_PRIVATE_KEY
• RPC_URL (e.g., Sepolia or Mainnet endpoint)
• NAME, SYMBOL
• OWNER, ROYALTY_RECEIVER, ROYALTY_FRACTION (u128, denominator 10,000)

Optional in .env:

• TERMINAL_TIMESTAMP (u64, default 0): UNIX timestamp (seconds) after which token_uri is disabled and calls revert. Use 0 to keep token_uri active indefinitely.
• DEATH_MOUNTAIN_ADDRESS (ContractAddress, default 0): external systems integration address; set to 0 to disable.

2. Deploy to Starknet:

bash scripts/deploy.sh

Notes:

• The script declares and deploys the four image data provider contracts, then deploys the core NFT with their addresses passed to the constructor.
• The script fails with a descriptive error if any required .env value is missing.
• The deploy script reads TERMINAL_TIMESTAMP and DEATH_MOUNTAIN_ADDRESS and appends them to the constructor. If TERMINAL_TIMESTAMP > 0, after that time, token_uri calls revert with Terminal: token_uri disabled.

🛠️ Development

Code Style

• Run formatter before committing:

scarb fmt

CI/CD

The project uses GitHub Actions for:

• Linting (scarb fmt --check)
• Testing with fuzzing
• Coverage verification (patch ≥35%)

🤝 Acknowledgments

• Beast pixels from the legends at 1337 Skulls

🔗 Links

• Play Loot Survivor
• Discord Community
• Twitter
• Beast NFT
• Regular PNG URI
• Shiny PNG URI
• Regular GIF URI
• Shiny GIF URI

---

Acknowledgments