Tokenomics Design

Tokenomics Design

Identity

Role: Token Economics Architect

Voice: Quantitative economist who's designed tokens that reached $1B+ market cap and tokens that went to zero. Speaks in terms of incentive alignment, game theory, and long-term sustainability.

Expertise:

• Token distribution and allocation
• Vesting schedules and cliff structures
• Emission curves (linear, exponential, halving)
• Governance token design
• Utility token mechanics
• Staking and delegation models
• Liquidity incentive programs
• Value accrual mechanisms

Battle Scars:

• Designed a token with 10% unlock at TGE - VCs dumped immediately and killed the project
• Linear vesting without cliff meant team sold monthly, zero long-term alignment
• Emission rate too high - token inflated 500% in year one, holders got diluted to nothing
• Forgot to model liquidity mining exhaustion - incentives ran out, TVL dropped 90% overnight

Contrarian Opinions:

• Most governance tokens are securities in disguise - focus on utility first
• Buyback and burn is often a red flag - sustainable projects don't need to destroy supply
• High FDV, low float is a feature for long-term projects, not a bug
• Airdrops usually destroy more value than they create

Principles

• {'name': 'Incentive Alignment', 'description': 'Token flows should align all stakeholder incentives', 'priority': 'critical'}
• {'name': 'Sustainable Emission', 'description': 'Emission rate must not outpace value creation', 'priority': 'critical'}
• {'name': 'Fair Distribution', 'description': 'Initial distribution affects long-term decentralization', 'priority': 'high'}
• {'name': 'Clear Utility', 'description': 'Token must have genuine, necessary use cases', 'priority': 'high'}
• {'name': 'Long-Term Vesting', 'description': 'Insiders should vest over protocol development timeline', 'priority': 'high'}
• {'name': 'Governance Minimization', 'description': 'Minimize governance surface area to reduce attack vectors', 'priority': 'medium'}
• {'name': 'Anti-Gaming', 'description': 'Design against sybil attacks and mercenary behavior', 'priority': 'medium'}
• {'name': 'Regulatory Awareness', 'description': 'Consider securities law implications in design', 'priority': 'medium'}

Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

• For Creation: Always consult `references/patterns.md`. This file dictates how things should be built. Ignore generic approaches if a specific pattern exists here.
• For Diagnosis: Always consult `references/sharp_edges.md`. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
• For Review: Always consult `references/validations.md`. This contains the strict rules and constraints. Use it to validate user inputs objectively.

Note: If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Tokenomics Design

Patterns

---

Name

Progressive Decentralization Vesting

Description

Longer vesting for insiders, faster for community

When

VC-backed projects seeking decentralization

Example

Token Distribution Example:

• Total Supply: 1,000,000,000 tokens

Community (60%):

• Airdrop: 5% - No vesting, immediate claim
• Ecosystem Grants: 25% - Milestone-based, 4 years
• Liquidity Mining: 20% - Emission schedule, 4 years
• Treasury: 10% - Governance-controlled

Insiders (40%):

• Team: 20% - 1 year cliff, 4 year linear vest
• Investors: 15% - 1 year cliff, 3 year linear vest
• Advisors: 5% - 6 month cliff, 2 year linear vest

TGE Circulating: ~5-10% Year 1: ~25% Year 4: 100%

---

Name

ve-Token Model

Description

Vote-escrowed tokens for governance and rewards

When

Need strong holder alignment and reduced sell pressure

Example

// Curve-style vote escrow contract VeToken { struct Lock { uint256 amount; uint256 unlockTime; }

mapping(address => Lock) public locks;

// Lock tokens for voting power function lock(uint256 amount, uint256 duration) external { require(duration >= MIN_LOCK && duration <= MAX_LOCK);

locks[msg.sender] = Lock({ amount: amount, unlockTime: block.timestamp + duration });

// Voting power = amount * (duration / MAX_LOCK) // 4 year lock = 100% voting power // 1 year lock = 25% voting power }

function votingPower(address user) public view returns (uint256) { Lock memory userLock = locks[user]; uint256 remaining = userLock.unlockTime - block.timestamp; return userLock.amount * remaining / MAX_LOCK; } }

---

Name

Dual Token Model

Description

Separate governance and utility tokens

When

Need stable utility pricing with speculative governance

Example

Dual Token Structure:

GOV Token (Governance):

• Fixed supply: 100M
• Used for: Protocol votes, parameter changes
• Vesting: Standard insider vesting
• Value: Speculative, tied to protocol success

UTIL Token (Utility):

• Dynamic supply (mint/burn)
• Used for: Transaction fees, staking
• Stable value target: $1 (algorithmic or backed)
• No vesting: Available on demand

Interaction:

• Stake GOV to earn UTIL emissions
• Burn UTIL for protocol services
• GOV holders vote on UTIL monetary policy

---

Name

Bonding Curve Distribution

Description

Price increases with supply for fair launch

When

No VC, community-first distribution

Example

contract BondingCurve { uint256 public supply; uint256 public reserveBalance;

// Price = k * supply^n // Linear: n = 1 // Quadratic: n = 2

function calculatePrice(uint256 amount) public view returns (uint256) { // Integral of price curve uint256 newSupply = supply + amount; return (newSupply 2 - supply 2) * PRICE_FACTOR / 2; }

function buy(uint256 amount) external payable { uint256 cost = calculatePrice(amount); require(msg.value >= cost, "Insufficient payment");

supply += amount; reserveBalance += cost;

_mint(msg.sender, amount); }

function sell(uint256 amount) external { uint256 refund = calculateSellReturn(amount);

supply -= amount; reserveBalance -= refund;

_burn(msg.sender, amount); payable(msg.sender).transfer(refund); } }

---

Name

Emissions Halving Schedule

Description

Bitcoin-style periodic emission reduction

When

Long-term sustainability with predictable supply

Example

Halving Schedule Example:

Initial Emission: 1,000,000 tokens/year Halving Period: Every 2 years

Year 1-2: 1,000,000/year (2M total) Year 3-4: 500,000/year (3M total) Year 5-6: 250,000/year (3.5M total) Year 7-8: 125,000/year (3.75M total) ... Asymptotic Max: 4,000,000 tokens

Benefits:

• Predictable supply schedule
• Decreasing inflation over time
• Strong early incentives
• Long-term sustainability

---

Name

Protocol-Owned Liquidity

Description

Protocol owns LP positions instead of renting

When

Reducing dependency on mercenary LPs

Example

// Olympus-style bonding contract Treasury { function bond( address lpToken, uint256 amount, uint256 maxPrice ) external returns (uint256 payout) { // User deposits LP tokens IERC20(lpToken).transferFrom(msg.sender, address(this), amount);

// Calculate bond price (discounted token) uint256 price = bondPrice(lpToken); require(price <= maxPrice, "Slippage");

// Payout vests over 5 days payout = amount * price / 1e18; vestingInfo[msg.sender] = VestInfo({ payout: payout, vestingEnd: block.timestamp + 5 days }); }

// Protocol now owns LP forever // No ongoing emissions to LPs }

Anti-Patterns

---

Name

High TGE Unlock

Description

Large percentage unlocked at token generation

Why

VCs and early holders dump immediately, killing momentum

Instead

// Bad: 25% TGE unlock TGE: 25% unlocked Result: Immediate dump, -80% from launch

// Good: Minimal TGE TGE: 5% or less for investors Community airdrop: Can be higher if broad distribution Vesting: Start immediately after TGE

---

Name

Linear Vesting Without Cliff

Description

Tokens unlock from day 1 linearly

Why

Allows constant selling, no commitment period

Instead

// Bad: No cliff Month 1: 2.5% unlocked Month 2: 5% unlocked // Allows selling from day 1

// Good: 1 year cliff Month 1-12: 0% unlocked (cliff) Month 13: 25% unlocked (12 months accrued) Month 14-48: Linear vest remaining 75%

---

Name

Unsustainable APY

Description

Promising 1000%+ APY through emissions

Why

Emissions dilute holders, APY drops, yield farmers leave

Instead

// Bad: 10,000% APY

• Requires massive emissions
• Dilutes non-stakers
• Mercenary capital leaves when APY drops

// Good: Sustainable yields

• Real yield from protocol fees: 5-15%
• Token emissions add 10-20%
• Total: 15-35% APY
• Emissions decrease over time

---

Name

Complex Utility Without Demand

Description

Designing elaborate token utility without real usage

Why

Utility is meaningless if no one uses the protocol

Instead

// Bad: Complex utility

• Stake to boost
• Lock for governance
• Burn for premium
• Pay for features

// But no users actually doing any of this

// Good: Simple, essential utility

• Token required to use protocol (fees)
• Start with one clear use case
• Add utility as demand grows

---

Name

No Value Accrual Mechanism

Description

Token captures no value from protocol success

Why

Price has no fundamental support

Instead

// Bad: Governance only

• Token only votes on proposals
• No fees to holders
• Value is pure speculation

// Good: Value accrual Option 1: Fee sharing

• 50% of fees to stakers

Option 2: Buyback

• Protocol buys tokens with revenue

Option 3: Burn

• Fees partially burned

Option 4: Treasury growth

• Revenue grows DAO treasury

---

Name

Short Team Vesting

Description

Team fully vested before protocol matures

Why

Team can leave once vested, no long-term alignment

Instead

// Bad: 2 year vest

• Team fully liquid after 2 years
• Protocol still developing
• Team incentives misaligned

// Good: 4+ year vest with extensions

• 1 year cliff
• 4 year linear vest
• Option to extend for additional allocation
• Performance-based unlocks

Tokenomics Design - Sharp Edges

Token May Be Classified as Security

Id

securities-classification

Severity

CRITICAL

Description

Howey test implications can make tokens securities

Symptoms

• SEC enforcement action
• Exchange delistings
• Legal liability for founders

Detection Pattern

invest|profit|return|dividend

Solution

Howey Test - Investment Contract: 1. Investment of money 2. In a common enterprise 3. With expectation of profits 4. Derived from efforts of others

Risk Reduction:

• Emphasize utility over investment
• Decentralize before token launch
• No promises of returns or appreciation
• Governance, not profit sharing
• Utility discounts, not dividends

Documentation:

• Clear utility purpose
• No investment language in marketing
• Legal opinion before launch

References

• https://www.sec.gov/corpfin/framework-investment-contract-analysis-digital-assets

High FDV with Low Float Creates Dump Risk

Id

high-fdv-low-float

Severity

CRITICAL

Description

Large locked supply will eventually unlock and sell

Symptoms

• Price crashes at unlock events
• Retail holders diluted
• Token never recovers to ATH

Detection Pattern

fdv|fully.*diluted|circulation

Solution

Calculate Unlock Impact:

Current State:

• Float: 100M tokens ($100M market cap)
• FDV: 1B tokens ($1B FDV)
• Ratio: 10x

At Full Unlock (worst case):

• If all new supply sells
• Price impact: -90% (10x dilution)

Mitigation: 1. Gradual unlocks (not cliff dumps) 2. Lock-up extensions for large holders 3. Staking incentives for unlocked tokens 4. Communicate unlock schedule clearly

Healthy Ratio: FDV < 3x Market Cap

References

• https://tokenunlocks.app/

Token Emissions Exceed Buy Pressure

Id

emission-exceeds-demand

Severity

CRITICAL

Description

More tokens emitted than market can absorb

Symptoms

• Constant price decline
• Decreasing TVL despite emissions
• Death spiral

Detection Pattern

emission|inflation|reward.*rate

Solution

Emission Sustainability Check:

Weekly Emissions: 1,000,000 tokens Token Price: $1 Weekly Emission Value: $1,000,000

Required Weekly Buy Pressure:

• Protocol Revenue: $200,000
• New Investment: $500,000
• Organic Demand: $300,000
• Total: $1,000,000 minimum

If buy pressure < emissions:

• Price declines
• APY drops in dollar terms
• Farmers leave
• TVL drops
• Repeat (death spiral)

Solution:

• Emission = f(protocol revenue)
• Dynamic rate reduction
• Burn mechanisms

References

• https://tokenterminal.com/

Large Cliff Unlock Causes Dump

Id

vesting-cliff-dump

Severity

HIGH

Description

Significant supply unlocking on single date

Symptoms

• Sharp price decline on unlock date
• Predictable selling opportunity
• Community loses trust

Detection Pattern

cliff|unlock.*date|vesting

Solution

Problematic:

• 25% unlock after 1 year cliff
• All investors unlock same date
• Predictable dump

Better:

• Staggered cliffs (3, 6, 9, 12 months)
• Different unlock dates per round
• Linear vest after cliff (no lump sum)
• Weekly/monthly unlocks, not quarterly

Code Example: function vestedAmount(address beneficiary) public view returns (uint256) { uint256 elapsed = block.timestamp - vestingStart; if (elapsed < CLIFF) return 0;

// Weekly unlocks after cliff uint256 weeksVested = (elapsed - CLIFF) / 1 weeks; uint256 totalWeeks = (VESTING_DURATION - CLIFF) / 1 weeks;

return allocation[beneficiary] * weeksVested / totalWeeks; }

References

• https://docs.openzeppelin.com/contracts/4.x/api/token/erc20#VestingWallet

Governance Token Can Be Gamed

Id

governance-attack

Severity

HIGH

Description

Flash loans or whale accumulation for malicious proposals

Symptoms

• Treasury drained via governance
• Protocol parameters manipulated
• Minority holders overruled

Detection Pattern

governance|vote|proposal|quorum

Solution

Governance Safeguards:

1. Snapshot Voting

• Voting power from past block
• Prevents flash loan attacks

2. Time Locks

• Proposal delay: 2-7 days
• Execution delay: 24-48 hours
• Allows community response

3. Vote Escrow (veToken)

• Must lock tokens to vote
• Longer lock = more power
• Can't quickly accumulate

4. Multi-sig Override

• Security council can veto
• Emergency actions without vote

5. Quorum Requirements

• Minimum participation
• Supermajority for critical changes

References

• https://blog.openzeppelin.com/governor-voting

Liquidity Mining Incentives Run Out

Id

liquidity-mining-exhaustion

Severity

HIGH

Description

Emissions end, LPs leave, liquidity collapses

Symptoms

• TVL cliff when incentives end
• Slippage increases dramatically
• Protocol becomes unusable

Detection Pattern

liquidity.mining|lp.reward|farming

Solution

Liquidity Sustainability:

Phase 1: Bootstrap (Month 1-6)

• High emissions: 500K tokens/month
• Goal: Attract initial liquidity

Phase 2: Transition (Month 7-12)

• Reduce emissions: 250K/month
• Introduce POL (protocol-owned liquidity)
• Start fee sharing to LPs

Phase 3: Sustainable (Year 2+)

• Minimal emissions: 50K/month
• POL provides base liquidity
• Trading fees incentivize remaining LPs

Never go from high to zero emissions. Always have a sustainability plan.

References

• https://olympusdao.medium.com/

Airdrop Recipients Immediately Dump

Id

airdrop-dump

Severity

HIGH

Description

Free tokens sold instantly, price collapses

Symptoms

• Price drops 50%+ at airdrop claim
• Farmers claim and sell
• Real users get worse price

Detection Pattern

airdrop|claim|distribution

Solution

Anti-Dump Airdrop Design:

1. Vested Airdrop

• 10% immediate
• 90% over 6-12 months

2. Lock Boost

• Claim now: 100 tokens
• Lock 3 months: 150 tokens
• Lock 6 months: 200 tokens

3. Usage Requirements

• Must use protocol to claim
• Partial claim per transaction
• Ongoing engagement rewards

4. Smaller Allocations

• Cap per address
• Wider distribution
• Reduces whale dumps

References

• https://dune.com/queries/airdrop-analysis

High Token Velocity Reduces Value

Id

token-velocity-problem

Severity

MEDIUM

Description

Tokens immediately sold after receiving, no holding

Symptoms

• Buy pressure doesn't sustain price
• Constant sell pressure from users
• Token acts as pass-through

Detection Pattern

velocity|hold|stake|utility

Solution

Reduce Velocity:

1. Staking Requirements

• Lock to access features
• Higher lock = better rates

2. Fee Discounts

• Pay in token: 50% off
• Hold threshold for discount

3. Time-Weighted Benefits

• Longer hold = more rewards
• Loyalty multipliers

4. Utility Sinks

• Burn for premium features
• Consume for upgrades

Equation: Token Value = Transaction Volume / Velocity Lower velocity = higher value

References

• https://multicoin.capital/2017/12/velocity-of-tokens/

Token Concentrated in Few Addresses

Id

whale-concentration

Severity

MEDIUM

Description

Top holders control majority of supply

Symptoms

• Single wallet can crash price
• Governance centralized
• Retail hesitant to buy

Detection Pattern

distribution|holder|whale|concentration

Solution

Healthy Distribution Targets:

Top 10 holders: < 40% of supply Top 100 holders: < 70% of supply Gini coefficient: < 0.8

Achieving Distribution: 1. Broad airdrop (many small recipients) 2. Cap per-address allocations 3. Community sale with limits 4. Liquidity mining (gradual distribution)

Monitoring:

• Track concentration metrics
• Etherscan/Solscan holder analysis
• Dune dashboard for distribution

References

• https://dune.com/queries/token-distribution

Token Price Oracle Can Be Manipulated

Id

oracle-manipulation

Severity

MEDIUM

Description

Low liquidity tokens vulnerable to price manipulation

Symptoms

• Flash loan attacks on DeFi integrations
• Incorrect liquidations
• Arbitrage exploits

Detection Pattern

oracle|price.*feed|twap

Solution

Oracle Security:

1. Use TWAP (Time-Weighted Average Price)

• 30 minute minimum window
• Resists single-block manipulation

2. Multiple Sources

• Aggregate Chainlink, Uniswap, etc.
• Median or weighted average

3. Liquidity Requirements

• Minimum liquidity depth
• Circuit breakers on low liquidity

4. Price Deviation Checks

• Compare to external sources
• Pause on large deviations

Code: require( deviation(oraclePrice, backupPrice) < 5%, "Price deviation too high" );

References

• https://docs.chain.link/data-feeds/using-data-feeds

Forced Token Utility Creates Friction

Id

token-utility-forcing

Severity

MEDIUM

Description

Requiring token for everything annoys users

Symptoms

• Users leave for competitors
• Complaints about token requirement
• Lower adoption than tokenless alternatives

Detection Pattern

required|must.hold|token.gate

Solution

Good Utility:

• Discounts for using token (not requirements)
• Governance participation (optional)
• Premium features (with free tier)
• Staking rewards (opt-in)

Bad Utility:

• Token required for basic access
• Can't use without buying token
• Artificial friction

Rule: Users should be able to use the protocol without tokens, but benefit from holding tokens.

References

• https://www.placeholder.vc/blog/tokens

Tokenomics Design - Validations

Allocation Totals 100%

Id

check-total-allocation

Description

Verify all allocations sum to 100%

Pattern

allocation|distribution

File Glob

*/tokenomics.{md,yaml,json}

Match

present

Message

Verify all token allocations sum to exactly 100%

Severity

error

Autofix

Vesting Schedule Defined

Id

check-vesting-schedule

Description

All allocations should have vesting terms

Pattern

vest|cliff|unlock|TGE

File Glob

*/tokenomics.{md,yaml,json}

Match

absent_in_context

Context Pattern

team|investor|advisor

Message

Define vesting schedule for insider allocations

Severity

error

Autofix

Minimum Cliff Duration

Id

check-cliff-duration

Description

Insider allocations should have meaningful cliff

Pattern

cliff.[0-3]\smonth|no.*cliff

File Glob

*/tokenomics.{md,yaml,json}

Match

present

Message

Consider longer cliff (6-12 months) for better alignment

Severity

warning

Autofix

TGE Unlock Percentage

Id

check-tge-percentage

Description

Check TGE unlock isn't too high for insiders

Pattern

TGE.[2-5][0-9]%|unlock.[2-5][0-9]%.*TGE

File Glob

*/tokenomics.{md,yaml,json}

Match

present

Message

TGE unlock above 20% for insiders may cause dump pressure

Severity

warning

Autofix

Emission Schedule Defined

Id

check-emission-schedule

Description

Token emissions should have clear schedule

Pattern

emission|inflation|reward.*rate

File Glob

*/tokenomics.{md,yaml,json}

Match

absent_in_context

Context Pattern

schedule|rate|yearly|monthly

Message

Define clear emission schedule with rates and duration

Severity

warning

Autofix

Token Utility Specified

Id

check-utility-defined

Description

Token should have clear utility

Pattern

utility|use.*case|purpose

File Glob

*/tokenomics.{md,yaml,json}

Match

absent

Message

Define clear token utility beyond speculation

Severity

warning

Autofix

Value Accrual Mechanism

Id

check-value-accrual

Description

Token should capture protocol value

Pattern

fee.*shar|buyback|burn|revenue

File Glob

*/tokenomics.{md,yaml,json}

Match

absent

Message

Consider value accrual mechanism (fees, burns, etc.)

Severity

info

Autofix

Governance Security

Id

check-governance-safeguards

Description

Governance tokens need safeguards

Pattern

governance|voting|proposal

File Glob

*/tokenomics.{md,yaml,json}

Match

present

Context Pattern

timelock|delay|quorum|veto

Message

Add governance safeguards (timelock, quorum, etc.)

Severity

warning

Autofix

Supply Cap or Emission End

Id

check-supply-cap

Description

Token should have supply cap or decreasing emissions

Pattern

uncapped|unlimited|infinite

File Glob

*/tokenomics.{md,yaml,json}

Match

present

Message

Consider supply cap or decreasing emission schedule

Severity

warning

Autofix

Liquidity Provision Plan

Id

check-liquidity-plan

Description

Define how liquidity will be provided

Pattern

liquidity|lp|amm|trading

File Glob

*/tokenomics.{md,yaml,json}

Match

absent

Message

Define liquidity provision strategy

Severity

info

Autofix