# The Nest — Whitepaper

**Version 1.0 — May 2026**

---

## 1. Introduction

The Nest is an on-chain game built on Base in which players hatch, evolve, and trade NFT chickens that generate a continuous stream of NEST token yield. It is the direct successor to the EGGS/Chicken ecosystem, retaining the same community roots while introducing a fully rebuilt economic model, on-chain upgrade mechanics, a native marketplace, and a staking layer.

The core design principle is straightforward: NFTs generate yield; players reinvest that yield into upgrades; upgrades increase yield output; the protocol burns the majority of every spend to keep supply in check. The result is a closed loop where active gameplay directly supports token economics.

The project is live on Base mainnet. Core contracts are deployed on Base, with verification status tracked publicly in the live contracts document. The Uniswap v3 liquidity pool is active with LP tokens locked via UNCX.

---

## 2. The NEST Token

| Parameter | Value |
|---|---|
| Name | NEST |
| Symbol | NEST |
| Network | Base mainnet (chain ID 8453) |
| Contract | `0x61E98e582f5249559242E4B02C4D1eaf6CB313F9` |
| Decimals | 18 |
| Max Supply | 21,000,000 NEST |
| Genesis Supply | 4,100,000 NEST |
| Buy Tax | 0% |
| Sell Tax | 0% |
| Primary Pool | NEST/USDC on Uniswap v3, Base |
| LP Lock | UNCX — position #5028147 |

NEST is the single utility and reward token of the ecosystem. It is earned through NFT yield, spent on gameplay actions, traded on the open market, and staked for weekly rewards. Every gameplay spend is subject to a burn mechanism that reduces circulating supply over time.

### 2.1 Genesis Allocation

| Bucket | Amount | Purpose |
|---|---:|---|
| LP Reserve | 2,100,000 NEST | Initial liquidity (1,270,000) + LP expansion reserve |
| Treasury | 900,000 NEST | Protocol operations and LP support |
| Reward Vault | 1,000,000 NEST | Staking and yield reserve |
| Supporter Airdrop | 100,000 NEST | Platinum EarlyBird holder claims (10 × 10,000) |
| **Total Genesis** | **4,100,000 NEST** | |

The remaining 16,900,000 NEST is mintable only through the protocol's game mechanics — yield distribution and staking rewards — subject to the 21M hard cap enforced at the contract level.

### 2.2 Supply Controls

The 21,000,000 NEST cap is set in the token constructor via OpenZeppelin's `ERC20Capped` extension. There is no setter. No admin action, contract upgrade, or role grant can raise or modify this cap.

Minting is gated by `MINTER_ROLE`, currently held by two non-upgradeable smart contracts: the `YieldDistributor` and the `GameController`. Every mint call reverts if it would push total supply past the cap.

The admin can rotate which contracts hold `MINTER_ROLE` — for example, to deploy an upgraded distributor. Any such rotation is an on-chain transaction, publicly visible on BaseScan before taking effect.

---

## 3. NFT Mechanics

### 3.1 The Nest NFT

The Nest NFT collection (`TNEST`) represents the core game asset — a chicken that generates daily NEST yield. Each NFT has a level from 1 to 5. Higher levels produce more yield per day.

| Level | Daily Yield | Nickname |
|---:|---:|---|
| 1 | 1 NEST/day | Hen |
| 2 | 10 NEST/day | Bird |
| 3 | 25 NEST/day | Hawk |
| 4 | 75 NEST/day | Eagle |
| 5 | 250 NEST/day | Dragon |

### 3.2 Acquiring NFTs

There are four ways to obtain a Nest NFT:

**Free Starter Mint** — Every connected wallet can claim one free Level 1 NFT. This NFT is non-transferable and non-sellable. It exists to give every player a yield-generating asset from day one with no financial barrier.

**Paid Original Mint** — Players can mint up to two additional tradable Level 1 NFTs (Slot 2 and Slot 3) for 15 USDC and 30 USDC respectively. USDC revenue is split 50% to the LP reserve and 50% to the development team.

**Legacy Migration** — Players who hold NFTs from the predecessor EGGS/Chicken collection can migrate them into the Nest ecosystem. Each legacy NFT can be converted once, minting a new Nest NFT at the appropriate level. Migration costs 1,000 NEST (81% burned, 19% to the staking pool).

**Native Mint** — A gated mechanism for active ecosystem participants. Requirements include a minimum staked NEST balance and recent gameplay activity. Cost: 7,500 NEST (81% burned, 19% to the staking pool).

### 3.3 NFT Upgrades

Players can attempt to upgrade their NFT from its current level to the next. The process uses a commit-reveal randomness mechanism implemented directly in the `GameController` contract — no external oracle is required.

| Upgrade Path | Cost | Success Rate |
|---|---:|---:|
| Level 1 → 2 | 1,000 NEST | 90% |
| Level 2 → 3 | 2,500 NEST | 60% |
| Level 3 → 4 | 10,000 NEST | 30% |
| Level 4 → 5 | 50,000 NEST | 10% |

Regardless of success or failure, the spent NEST is distributed: 81% burned, 19% routed to the staking prize pool. Failed upgrades still contribute to the deflationary pressure of the ecosystem.

---

## 4. Yield System

### 4.1 How Yield Works

Each Nest NFT accrues NEST yield continuously based on its level. The yield is authorized by an off-chain signing service and claimed on-chain via the `YieldDistributor` contract using an EIP-712 signed payload. The signature expires, cannot be reused (nonce system), and is only valid for the wallet that earned it.

When a player claims their yield, the distribution is:
- **98%** to the player
- **1%** burned directly (reducing total supply)
- **1%** to the LP reserve (supporting liquidity depth over time)

### 4.2 EarlyBird Yield Boosts

EarlyBird NFT holders receive a permanent yield multiplier applied to their daily NEST generation. Boosts are active only while the EarlyBird NFT remains in the original minter's wallet.

| EarlyBird Tier | Yield Boost |
|---|---:|
| Bronze | +1% |
| Silver | +2% |
| Gold | +3% |
| Platinum | +4% |

Platinum holders also received a one-time claim of 10,000 NEST at launch.

---

## 5. Staking

### 5.1 Overview

Players can stake NEST tokens to earn weekly rewards from the staking prize pool. There are five lock tiers, from flexible to 100-day lock. Longer commitments access a larger share of the weekly pool.

On every stake and unstake action, 1% of the amount is burned.

### 5.2 Weekly Pool Distribution

| Tier | Weekly Pool Share |
|---|---:|
| 100 days | 50% |
| 50 days | 25% |
| 25 days | 13% |
| 10 days | 8% |
| Flexible | 4% |

Within each tier bucket, rewards are distributed proportionally to raw amount staked, with no multiplier.

### 5.3 Prize Pool Sources

The staking prize pool is continuously fed by:
- 19% of every upgrade payment
- 19% of every evolve payment
- 19% of every native mint payment
- Early unstake penalties from locked tiers
- A weekly autonomous mint floor (capped at 50,000 NEST/week)

### 5.4 Early Unstake

Locked-tier stakers who exit early incur a linear penalty based on remaining lock time. The penalty amount is returned to the staking prize pool rather than being burned.

---

## 6. Marketplace

### 6.1 Overview

The Nest Marketplace is a native NFT exchange built into the protocol. Players can list, buy, and sell tradable Nest NFTs in NEST tokens. The marketplace contract is deployed as a UUPS upgradeable proxy on Base mainnet and is verified on BaseScan.

### 6.2 Sale Fee Structure

On every completed sale, the proceeds are distributed as follows:

| Recipient | Share |
|---|---:|
| Seller | 95% |
| Protocol Treasury | 2.5% |
| Original Creator Fee | 2.5% |

Listing, cancellation, and price edits are gas-only with no protocol fee.

---

## 7. Token Economics Summary

### 7.1 Burn Mechanisms

NEST has multiple built-in burn paths across all major gameplay actions:

| Action | Burn Rate |
|---|---:|
| Upgrade (per attempt) | 81% of cost |
| Evolve | 81% of cost |
| Native Mint | 81% of cost |
| Legacy Migration | 81% of cost |
| Yield Claim | 1% of yield |
| Stake | 1% of amount |
| Unstake | 1% of amount |

### 7.2 Deflationary Design

The combination of a 21M hard cap and aggressive in-game burn rates creates sustained deflationary pressure. Every gameplay action that spends NEST destroys the majority of the tokens involved. As the game matures and player activity increases, the burn rate is expected to exceed the mint rate during high-activity phases.

### 7.3 Revenue Flows

| Revenue Source | LP Reserve | Treasury | Dev | Staking Pool | Burn |
|---|---:|---:|---:|---:|---:|
| Paid Hatch (USDC) | 50% | 0% | 50% | 0% | 0% |
| Yield Claim | 1% | 0% | 0% | 0% | 1% |
| Upgrade / Evolve / Native Mint | 0% | 0% | 0% | 19% | 81% |
| Marketplace Sale (of price) | 0% | 2.5% | 0% | 0% | 0% |

---

## 8. Smart Contracts

All contracts are deployed on Base mainnet (chain ID 8453). Verification status is tracked in the live contracts document.

| Contract | Address | Notes |
|---|---|---|
| NEST Token | `0x61E98e582f5249559242E4B02C4D1eaf6CB313F9` | ERC20Capped, Pausable, Permit |
| Nest NFT (TNEST) | `0x4C2dF54ef596a925188bcE6DB84defaa263827ee` | Dynamic NFT, 5 levels |
| EarlyBird NFT (EBIRD) | `0x13042e4de9063E34bC99A20eBB840ef9212222de` | Non-transferable supporter NFT |
| Game Controller | `0xF93ec7eB18330607E67D06d5d7D335d5B0F46B6f` | Mint, upgrade, legacy logic |
| Yield Distributor | `0x6b718FF22D895f87c831beb011a98a0D778Bb445` | EIP-712 signed yield claims |
| Marketplace (Proxy) | `0xa7a2015f14e543D7505d15d746eB800EB40F732b` | UUPS, active listings |
| Fee Splitter | `0x6c53cc4382c05decab7e36e6ec65fcf3bf8ba694` | Fee routing |
| Uniswap v3 Pool | `0x89f02984910Cd0a87c99Cc064c1078AD3106B147` | NEST/USDC, Base |

---

## 9. Security Model

### 9.1 Role Architecture

The NEST token uses OpenZeppelin `AccessControl` with role separation:

- **MINTER_ROLE** — held by `YieldDistributor` and `GameController`. These are non-upgradeable contracts; their mint logic is fixed in bytecode. The protocol admin can rotate which contracts hold this role to support future upgrades, with all rotations publicly visible on-chain.
- **PAUSER_ROLE** — held by the protocol admin wallets. The pause mechanism (`ERC20Pausable`) freezes all token transfers including purchases — it cannot be used selectively against sellers. This capability exists as an emergency brake. It has already been exercised twice in response to bot spam attacks targeting the free-mint NFT system, both of which were contained without user losses.
- **DEFAULT_ADMIN_ROLE** — held by two protocol wallets. This role can manage operational parameters (fee amounts, success probabilities, signer rotation) but cannot modify user balances, bypass the 21M cap, or alter deployed contract bytecode.

### 9.2 LP Security

The initial Uniswap v3 LP position is locked via UNCX (position #5028147). The lock is publicly verifiable on-chain.

### 9.3 Yield Authorization

Yield claims require a valid EIP-712 off-chain signature from a dedicated signer wallet (`SIGNER_ROLE`). Each signature includes wallet address, amount, nonce, and expiry. Signatures are single-use, wallet-bound, and expire after a deadline. Replay attacks are prevented by the nonce system.

### 9.4 Upgrade Randomness

NFT upgrades use a commit-reveal scheme. The player submits a hash commitment in one transaction, then reveals the secret in a subsequent block. The result is derived from `blockhash` combined with the secret, preventing both miner and player manipulation. The reveal window expires after 256 blocks.

---

## 10. Roadmap

| Status | Milestone |
|---|---|
| ✅ Done | Token launch and LP creation on Base mainnet |
| ✅ Done | LP lock via UNCX |
| ✅ Done | Nest NFT collection live |
| ✅ Done | EarlyBird NFT sale and Platinum claims |
| ✅ Done | Free mint, paid mint, legacy migration |
| ✅ Done | Yield distribution system live |
| ✅ Done | Native marketplace with fee routing |
| 🔄 In Progress | Staking prize pool activation |
| 🔄 In Progress | Trust Wallet and CoinGecko listing |
| 🔄 In Progress | Blockaid security database review |
| 📅 Upcoming | Native mint activation |
| 📅 Upcoming | Evolve mechanic |
| 📅 Upcoming | Staking tier system |

---

## 11. Links

| Resource | URL |
|---|---|
| Website | https://the-nest.xyz |
| Token Safety | https://the-nest.xyz/token-safety |
| Game Guide | https://the-nest.xyz/guide |
| Token on BaseScan | https://basescan.org/token/0x61E98e582f5249559242E4B02C4D1eaf6CB313F9 |
| Verified Source | https://basescan.org/address/0x61E98e582f5249559242E4B02C4D1eaf6CB313F9#code |
| Uniswap Pool | https://dexscreener.com/base/0x89f02984910Cd0a87c99Cc064c1078AD3106B147 |
| GoPlus Report | https://gopluslabs.io/token-security/8453/0x61E98e582f5249559242E4B02C4D1eaf6CB313F9 |

---

*This document reflects the live state of the protocol as of May 2026. It is not financial advice. NEST is a utility token powering gameplay mechanics within The Nest ecosystem.*