Staking System

Configurable staking engine supporting multiple reward models.

---

Purpose

The staking system allows players to lock NFTs (or tokens) and receive rewards based on configurable parameters. It exists because:

• Competitive games need mechanisms to incentivize long-term participation
• Different games have fundamentally different economic needs
• A single hardcoded staking model forces projects to fork instead of configure

Critical design rule: This system does NOT enforce a single staking model. It provides a parameter-driven engine that supports multiple reward strategies.

---

Why Configurable?

Game Type	Needs	Wrong Model
Competitive PvP	Prize pool funding from stakers	Passive emissions (no game loop)
Collection game	Rarity-weighted rewards	Flat-rate emissions
Seasonal game	Time-bounded reward epochs	Infinite emission schedule
Community-funded	Fee sharing from tournament entry fees	Fixed APY regardless of activity

A one-size-fits-all model fails for at least one of these cases.

---

Supported Models

1. Fixed Emissions

Staker locks NFT
       │
       ▼
Reward accrues at fixed rate per epoch
       │
       ▼
Staker claims accumulated THC

Parameters:

• reward_per_epoch — THC distributed per staking epoch
• epoch_duration — length of each epoch (e.g., 24 hours)
• eligible_collections — which NFT collections can be staked

When to use: Simple games that need predictable reward schedules.

Risk: Can cause inflation if not paired with sufficient THC sinks.

2. Pooled Rewards

Revenue Pool (AVAX from tournament fees, marketplace fees)
       │
       ▼
Distributed proportionally to all stakers
       │
       ▼
Staker share = (staker_weight / total_weight) * pool_balance

Parameters:

• distribution_interval — how often the pool is distributed
• weight_function — how NFT attributes affect share (rarity, level, etc.)
• revenue_sources — which contracts feed into the reward pool

When to use: Games where rewards should scale with actual economic activity.

Advantage: No inflation — rewards come from real revenue, not minting.

3. Tournament Funding

Stakers lock NFTs
       │
       ▼
Staking pool funds tournament prize pools
       │
       ▼
Top tournament performers receive prizes
       │
       ▼
Remaining pool distributed to stakers as yield

Parameters:

• tournament_allocation — % of pool directed to tournaments
• staker_allocation — % returned to stakers as passive yield
• lock_duration — minimum staking period before withdrawal

When to use: Competitive games where staking should drive competitive activity.

4. Fee Sharing

Game generates fees (marketplace, entry, crafting)
       │
       ▼
Fee pool accumulated
       │
       ▼
Distributed to stakers based on weight

Parameters:

• fee_share_percent — % of collected fees distributed to stakers
• weight_function — staker weight calculation
• claim_cooldown — minimum time between claims

When to use: Games with active fee-generating mechanics.

5. Hybrid

Any combination of the above. A game could:

• Use fixed emissions for THC
• Plus pooled rewards from AVAX tournament fees
• Plus fee sharing from marketplace activity

---

Contract Architecture

┌──────────────────────────────────────────────────────┐
│                  Staking Engine Contract              │
│                                                      │
│  ┌────────────────────────────────────────────────┐   │
│  │  Configuration (per-game)                      │   │
│  │                                                │   │
│  │  • reward_model: enum                          │   │
│  │  • epoch_duration: uint256                     │   │
│  │  • reward_per_epoch: uint256                   │   │
│  │  • eligible_collections: address[]             │   │
│  │  • weight_function: enum / callback            │   │
│  │  • fee_share_percent: uint256                  │   │
│  │  • lock_duration: uint256                      │   │
│  └────────────────────────────────────────────────┘   │
│                                                      │
│  ┌────────────────────────────────────────────────┐   │
│  │  State                                         │   │
│  │                                                │   │
│  │  • stakes: mapping(address => StakedNFT[])     │   │
│  │  • total_weight: uint256                       │   │
│  │  • reward_pool: uint256                        │   │
│  │  • last_distribution: uint256                  │   │
│  │  • pending_rewards: mapping(address => uint256)│   │
│  └────────────────────────────────────────────────┘   │
│                                                      │
│  ┌────────────────────────────────────────────────┐   │
│  │  Functions                                     │   │
│  │                                                │   │
│  │  • stake(tokenId)                              │   │
│  │  • unstake(tokenId)                            │   │
│  │  • claim()                                     │   │
│  │  • distribute() — called by keeper or cron     │   │
│  │  • updateConfig() — owner only                 │   │
│  │  • fundPool() — anyone can add to pool         │   │
│  └────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────┘

---

Weight Functions

How a staked NFT's weight is calculated:

Function	Formula	Use Case
Flat	weight = 1	All NFTs equal weight
Rarity-based	weight = rarity_multiplier[nft.rarity]	Higher rarity = more share
Attribute-sum	weight = nft.attack + nft.defense	Stats-based weighting
Level-based	weight = nft.level	Progression-based
Custom	weight = callback(tokenId)	Game-specific formula

---

Staking Lifecycle

Player stakes NFT
       │
       ▼
NFT transferred to staking contract
(or approved, depending on implementation)
       │
       ▼
Player weight added to total_weight
       │
       ▼
               ┌──── Epoch passes ────┐
               │                       │
               ▼                       │
      Rewards distributed             │
      (or accumulated)                 │
               │                       │
               └──── Repeat ───────────┘
       │
       ▼
Player calls claim()
       │
       ▼
Pending rewards transferred to player
       │
       ▼
Player unstakes NFT (optional)
       │
       ▼
NFT returned to player
(lock_duration must have elapsed)

---

Configuration Example

// Example: Faded Monsuta staking configuration
{
  reward_model: "hybrid",
  epoch_duration: 86400,          // 24 hours in seconds
  
  // Fixed emissions component
  emissions: {
    thc_per_epoch: 10000,         // 10,000 THC distributed per epoch
    eligible_collections: [
      "0x1234...monsutaNFT"
    ]
  },
  
  // Pooled rewards component
  pooled: {
    revenue_sources: [
      "0xABCD...prizePoolContract",
      "0xEF01...marketplaceContract"
    ],
    distribution_interval: 604800  // Weekly
  },
  
  // Weight
  weight_function: "rarity",
  rarity_multipliers: {
    "common": 1,
    "uncommon": 2,
    "rare": 4,
    "epic": 8,
    "legendary": 16
  },
  
  // Lock
  lock_duration: 259200            // 3 days minimum stake
}

---

Integration Guide for Other Games

Step 1: Choose Your Reward Model

Decide which of the 5 models (or hybrid) fits your game economy. Consider:

• Where do rewards come from? (minting vs revenue vs fees)
• Do you want inflation-based or revenue-based rewards?
• What NFT attributes should affect weight?

Step 2: Deploy the Staking Contract

• Set your configuration parameters
• Register eligible NFT collections
• Fund the initial reward pool (if using emissions or pooled model)

Step 3: Integrate with Your Game Server

• Expose staking status via API
• In-game benefits for stakers (cosmetic, priority queue, etc.)
• Display reward accrual in game UI

Step 4: Monitor Economic Health

• Track mint rate vs consumption rate
• Adjust reward_per_epoch or fee_share_percent as needed
• Monitor total staked supply to detect unhealthy lock-up ratios