Tokenomics Design for Agent Networks: Token Models That Actually Work

#!/usr/bin/env python3
"""
Token Emission and Supply/Demand Simulator for Agent Networks
Purple Flea Research — purpleflea.com
Models vesting schedules, emission decay, and equilibrium price dynamics.
"""

from dataclasses import dataclass, field
from typing import List, Dict, Tuple
import math
import json


@dataclass
class VestingSchedule:
    name: str
    total_allocation: float     # fraction of total supply (0.0 - 1.0)
    cliff_months: int           # months before first unlock
    vest_months: int            # total vesting duration in months
    start_month: int = 0       # month offset from TGE


@dataclass
class TokenomicsConfig:
    total_supply: float = 1_000_000_000  # 1 billion tokens
    tge_price_usd: float = 0.10
    annual_protocol_revenue_usd: float = 5_000_000
    fee_buyback_fraction: float = 0.3   # 30% of fees used for buyback/burn
    emission_model: str = "continuous_decay"  # or "halving" or "fixed"
    emission_total_fraction: float = 0.35  # 35% of supply via emissions
    emission_duration_months: int = 60     # 5 year emission window
    schedules: List[VestingSchedule] = field(default_factory=list)


class TokenomicsSimulator:

    def __init__(self, config: TokenomicsConfig):
        self.config = config

    def emission_rate(self, month: int) -> float:
        """Monthly token emission based on chosen model."""
        total = self.config.total_supply * self.config.emission_total_fraction
        dur = self.config.emission_duration_months

        if month >= dur:
            return 0.0

        if self.config.emission_model == "fixed":
            return total / dur

        elif self.config.emission_model == "continuous_decay":
            # Exponential decay: rate(t) = C * exp(-lambda * t)
            # Calibrated so integral from 0 to dur = total
            lam = 4.0 / dur
            normalization = lam / (1 - math.exp(-lam * dur))
            return total * normalization * math.exp(-lam * month)

        elif self.config.emission_model == "halving":
            # Halving every 12 months
            halving_period = 12
            epoch = month // halving_period
            first_epoch_rate = total / (halving_period * ((2 ** (dur // halving_period)) - 1)) * (2 ** (dur // halving_period) - 1)
            return (total / halving_period) / (2 ** epoch)

        return 0.0

    def vesting_unlock(self, month: int) -> float:
        """Total tokens unlocked from vesting schedules at given month."""
        total_unlock = 0.0
        for sched in self.config.schedules:
            allocation = self.config.total_supply * sched.total_allocation
            effective_month = month - sched.start_month

            if effective_month < sched.cliff_months:
                continue
            elif effective_month == sched.cliff_months:
                # Cliff unlock: deliver cliff portion
                cliff_frac = sched.cliff_months / sched.vest_months
                total_unlock += allocation * cliff_frac
            elif effective_month <= sched.vest_months:
                # Linear monthly vest after cliff
                remaining_months = sched.vest_months - sched.cliff_months
                total_unlock += allocation * (1 - sched.cliff_months / sched.vest_months) / remaining_months

        return total_unlock

    def buyback_burn(self, month: int) -> float:
        """Tokens bought back and burned from protocol revenue."""
        monthly_revenue = self.config.annual_protocol_revenue_usd / 12
        buyback_usd = monthly_revenue * self.config.fee_buyback_fraction
        # Simplified: assume current price from simulation state
        return buyback_usd  # Will be divided by price in simulate()

    def simulate(self, months: int = 120) -> List[Dict]:
        """Run full simulation over specified months."""
        results = []
        circulating = 0.0
        total_burned = 0.0
        price = self.config.tge_price_usd

        for m in range(months):
            emitted = self.emission_rate(m)
            unlocked = self.vesting_unlock(m)
            burned_usd = self.buyback_burn(m)
            burned_tokens = burned_usd / max(price, 0.0001)

            circulating += emitted + unlocked - burned_tokens
            circulating = max(0, circulating)
            total_burned += burned_tokens

            # Simplified supply/demand price model
            # P = Revenue * P/E ratio / circulating supply
            annual_rev = self.config.annual_protocol_revenue_usd
            implied_pe = 20 + min(30, m / 12 * 5)  # PE expands as protocol matures
            if circulating > 0:
                fundamental_price = (annual_rev * implied_pe) / circulating
                # Blend with momentum
                price = price * 0.7 + fundamental_price * 0.3

            results.append({
                "month": m,
                "year": round(m / 12, 1),
                "circulating_supply": round(circulating),
                "monthly_emission": round(emitted),
                "monthly_unlock": round(unlocked),
                "monthly_burn": round(burned_tokens),
                "total_burned": round(total_burned),
                "price_usd": round(price, 4),
                "market_cap_usd": round(circulating * price),
            })

        return results


if __name__ == "__main__":
    config = TokenomicsConfig(
        total_supply=1_000_000_000,
        tge_price_usd=0.10,
        annual_protocol_revenue_usd=10_000_000,
        fee_buyback_fraction=0.25,
        emission_model="continuous_decay",
        schedules=[
            VestingSchedule("Team", 0.20, cliff_months=12, vest_months=48),
            VestingSchedule("Investors", 0.10, cliff_months=6, vest_months=24),
            VestingSchedule("Treasury", 0.15, cliff_months=0, vest_months=60),
        ]
    )

    sim = TokenomicsSimulator(config)
    results = sim.simulate(months=120)

    # Print yearly snapshots
    yearly = [r for r in results if r["month"] % 12 == 0]
    print(json.dumps(yearly, indent=2))