Tokenomics Explained — Token Design, Supply, and Economic Models

# Token supply projection simulator
def project_token_supply(
    initial_supply: float,
    model: str,
    annual_inflation_pct: float = 0,
    annual_burn_pct: float = 0,
    halving_interval_blocks: int = 0,
    initial_block_reward: float = 0,
    years: int = 20
) -> list:
    """
    Project token supply over time under different models.
    
    Args:
        initial_supply: Starting token supply
        model: "fixed", "inflationary", "deflationary", "halving"
        annual_inflation_pct: Yearly inflation rate (for inflationary)
        annual_burn_pct: Yearly burn rate (for deflationary)
        halving_interval_blocks: Blocks between halvings (for halving model)
        initial_block_reward: Initial reward per block
        years: Projection period
    
    Returns:
        List of yearly supply snapshots
    """
    supply = initial_supply
    projections = [{"year": 0, "supply": supply, "event": "Genesis"}]

    for year in range(1, years + 1):
        event = ""

        if model == "fixed":
            # Bitcoin-like: supply never changes after cap reached
            event = "Fixed cap maintained"

        elif model == "inflationary":
            new_tokens = supply * (annual_inflation_pct / 100)
            supply += new_tokens
            event = f"Inflation: +{new_tokens:,.0f} tokens"

        elif model == "deflationary":
            burned = supply * (annual_burn_pct / 100)
            supply -= burned
            event = f"Burn: -{burned:,.0f} tokens"

        elif model == "halving":
            # Simplified: reward halves at intervals
            num_periods = year * 52560 // halving_interval_blocks  # ~52,560 blocks/year for ETH
            reward = initial_block_reward
            for _ in range(min(num_periods, 64)):  # max 64 halvings
                reward /= 2
            supply += reward * 52560
            event = f"Reward: {reward:.6f} per block"

        elif model == "inflationary_with_burn":
            minted = supply * (annual_inflation_pct / 100)
            burned = supply * (annual_burn_pct / 100)
            supply += minted - burned
            net = minted - burned
            event = f"Mint: +{minted:,.0f}, Burn: -{burned:,.0f}, Net: {net:+,.0f}"

        projections.append({
            "year": year,
            "supply": round(supply),
            "change": round(supply - projections[-1]["supply"]),
            "event": event
        })

    return projections

print("Fixed Supply (Bitcoin, 21M cap):")
btc = project_token_supply(19_500_000, "fixed")
for p in btc[::5]:  # every 5 years
    print(f"  Year {p['year']}: {p['supply']:,} BTC — {p['event']}")

print("\nInflationary (Ethereum-like, 0.5% annual):")
eth = project_token_supply(120_000_000, "inflationary", 0.5)
for p in eth[::5]:
    print(f"  Year {p['year']}: {p['supply']:,} ETH — {p['event']}")

print("\nDeflationary (EIP-1559-like, 1% annual burn > issuance):")
def_eth = project_token_supply(120_000_000, "inflationary_with_burn", 0.5, 1.5)
for p in def_eth[::5]:
    print(f"  Year {p['year']}: {p['supply']:,} ETH — {p['event']}")

# Token distribution analyzer
def analyze_token_distribution(
    total_supply: float,
    allocations: dict,
    vesting_schedules: dict
) -> dict:
    """
    Analyze a token's distribution fairness and vesting schedule.
    
    Args:
        total_supply: Total token supply
        allocations: Dict of group -> percentage
        vesting_schedules: Dict of group -> (cliff_months, total_vest_months)
    
    Returns:
        Analysis with circulation projections and fairness metrics
    """
    # Gini coefficient calculation (simplified)
    sorted_allocs = sorted(allocations.values())
    n = len(sorted_allocs)
    gini = 0
    for i, alloc in enumerate(sorted_allocs):
        gini += (2 * i - n + 1) * alloc
    gini = gini / (n * sum(sorted_allocs)) if sum(sorted_allocs) > 0 else 0

    # Concentrated ownership check
    top_3_pct = sum(sorted(allocations.values(), reverse=True)[:3])

    # Monthly circulating supply projection
    monthly_circulation = []
    circulating = 0

    for month in range(1, 49):  # 4 years
        monthly_unlock = 0
        for group, pct in allocations.items():
            if group in vesting_schedules:
                cliff, total_vest = vesting_schedules[group]
                if month >= cliff and month <= total_vest + cliff:
                    unlock = (total_supply * pct / 100) / total_vest
                    monthly_unlock += unlock
                elif month > total_vest + cliff:
                    pass  # already fully vested
                else:
                    pass  # still in cliff

        circulating += monthly_unlock

        if month % 6 == 0:  # every 6 months
            pct_circulating = (circulating / total_supply) * 100
            monthly_circulation.append({
                "month": month,
                "circulating": round(circulating),
                "pct_circulating": round(pct_circulating, 1)
            })

    return {
        "total_supply": total_supply,
        "allocations": allocations,
        "gini_coefficient": round(gini, 3),
        "top_3_concentration_pct": round(top_3_pct, 1),
        "concentration_risk": "High" if top_3_pct > 60 else
                              "Medium" if top_3_pct > 40 else "Low",
        "circulation_schedule": monthly_circulation,
        "fully_diluted_by_month": max(v[0] + v[1] for v in vesting_schedules.values())
    }

# Example: Compare two token distributions
fair_project = {
    "Public Sale": 25,
    "Ecosystem Fund": 30,
    "Team (4yr vest, 1yr cliff)": 15,
    "Advisors": 5,
    "Liquidity": 10,
    "Community Rewards": 15
}

sketchy_project = {
    "VC Sale": 45,
    "Team": 25,
    "Advisors": 10,
    "Public Sale": 5,
    "Marketing": 10,
    "Ecosystem": 5
}

vesting_fair = {
    "Public Sale": (0, 0),          # unlocked at TGE
    "Ecosystem Fund": (0, 24),
    "Team (4yr vest, 1yr cliff)": (12, 36),
    "Advisors": (6, 18),
    "Liquidity": (0, 12),
    "Community Rewards": (0, 48)
}

vesting_sketchy = {
    "VC Sale": (0, 12),
    "Team": (12, 24),
    "Advisors": (6, 18),
    "Public Sale": (0, 0),
    "Marketing": (0, 6),
    "Ecosystem": (0, 12)
}

fair_result = analyze_token_distribution(1_000_000_000, fair_project, vesting_fair)
sketchy_result = analyze_token_distribution(1_000_000_000, sketchy_project, vesting_sketchy)

print("Fair Project:")
print(f"  Gini: {fair_result['gini_coefficient']}")
print(f"  Top 3 concentration: {fair_result['top_3_concentration_pct']}% ({fair_result['concentration_risk']})")
print(f"  Circulation at 24mo: {fair_result['circulation_schedule'][3]['pct_circulating']}%")

print("\nSketchy Project:")
print(f"  Gini: {sketchy_result['gini_coefficient']}")
print(f"  Top 3 concentration: {sketchy_result['top_3_concentration_pct']}% ({sketchy_result['concentration_risk']})")
print(f"  Circulation at 24mo: {sketchy_result['circulation_schedule'][3]['pct_circulating']}%")

# Token velocity analysis — how often tokens change hands
def analyze_token_velocity(
    total_supply: float,
    daily_tx_volume_usd: float,
    token_price: float,
    staked_pct: float = 0.30,
    locked_pct: float = 0.20
) -> dict:
    """
    Analyze token velocity — a key indicator of sustainable value.
    
    The Velocity of Money (MV = PQ): velocity = (transaction volume) / (circulating supply * price)
    Higher velocity = each token changes hands more often.
    Utility tokens with high velocity tend to have lower prices.
    """
    circulating_supply = total_supply * (1 - staked_pct - locked_pct)
    annual_tx_volume = daily_tx_volume_usd * 365
    market_cap = total_supply * token_price
    circulating_market_cap = circulating_supply * token_price

    velocity = annual_tx_volume / circulating_market_cap if circulating_market_cap > 0 else 0

    return {
        "total_supply": total_supply,
        "circulating_supply": round(circulating_supply),
        "staked_pct": f"{staked_pct * 100}%",
        "locked_pct": f"{locked_pct * 100}%",
        "market_cap_usd": f"${market_cap:,.0f}",
        "circulating_market_cap": f"${circulating_market_cap:,.0f}",
        "annual_tx_volume_usd": f"${annual_tx_volume:,.0f}",
        "velocity": round(velocity, 2),
        "velocity_rating": "Low (good for store of value)" if velocity < 5 else
                          "Moderate" if velocity < 20 else
                          "High (utility token, needs growth)" if velocity < 50 else
                          "Very high (potential structural issue)"
    }

# Compare ETH vs a typical utility token
eth_velocity = analyze_token_velocity(
    total_supply=120_000_000,
    daily_tx_volume_usd=15_000_000_000,  # ~$15B daily DEX volume
    token_price=3000,
    staked_pct=0.25,
    locked_pct=0.10
)

utility_velocity = analyze_token_velocity(
    total_supply=1_000_000_000,
    daily_tx_volume_usd=50_000_000,
    token_price=0.50,
    staked_pct=0.05,
    locked_pct=0.10
)

print("ETH Velocity Analysis:")
for k, v in eth_velocity.items():
    print(f"  {k}: {v}")

print("\nTypical Utility Token Velocity:")
for k, v in utility_velocity.items():
    print(f"  {k}: {v}")