┌─────────────────────────────────────────────────────────────────────────────┐
│                    THE SCOPE OF TOKENOMICS                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    CREATION & DISTRIBUTION                          │   │
│  │  How tokens are created, minted, and allocated to participants.     │   │
│  │  • Initial supply                                                   │   │
│  │  • Minting mechanisms                                               │   │
│  │  • Distribution methods (ICO, IDO, airdrops, etc.)                 │   │
│  │  • Vesting schedules                                                │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    UTILITY & FUNCTIONALITY                          │   │
│  │  What the token is used for within the ecosystem.                  │   │
│  │  • Governance rights                                                │   │
│  │  • Access to services                                               │   │
│  │  • Fee payment                                                      │   │
│  │  • Staking and rewards                                              │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    VALUE MECHANISMS                                 │   │
│  │  How value is created, captured, and transferred.                  │   │
│  │  • Demand and supply dynamics                                      │   │
│  │  • Token velocity                                                   │   │
│  │  • Burn mechanisms                                                  │   │
│  │  • Value accrual                                                    │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    INCENTIVE STRUCTURES                             │   │
│  │  How participants are incentivised to contribute.                  │   │
│  │  • Rewards for staking                                             │   │
│  │  • Penalties for malicious behaviour                               │   │
│  │  • Governance participation                                        │   │
│  │  • Liquidity provision                                              │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                    TOKEN CATEGORIES                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. UTILITY TOKENS                                                          │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • Provide access to a product or service                            │   │
│  │ • Not designed as an investment                                     │   │
│  │ • Examples: Filecoin (storage access), BAT (advertising)           │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  2. SECURITY TOKENS                                                         │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • Represent ownership, debt, or rights                              │   │
│  │ • Subject to securities regulation                                  │   │
│  │ • Examples: Tokenised stocks, real estate tokens                   │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  3. GOVERNANCE TOKENS                                                       │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • Grant voting rights in a protocol                                 │   │
│  │ • Used for decision-making                                          │   │
│  │ • Examples: UNI (Uniswap), MKR (MakerDAO)                         │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  4. PAYMENT TOKENS                                                          │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • Used as a medium of exchange                                      │   │
│  │ • Examples: Bitcoin, Litecoin, USDC                                 │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  5. ASSET-BACKED TOKENS                                                     │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • Backed by physical or financial assets                            │   │
│  │ • Examples: PAXG (gold-backed), USDC (USD-backed)                  │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  6. MEME TOKENS                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • Community-driven, often humorous                                  │   │
│  │ • Value driven by social sentiment                                  │   │
│  │ • Examples: Dogecoin, Shiba Inu                                     │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Velocity = GDP of the Token Economy / Money Supply

# ===================================================================
# MODULE 6, LESSON 1: INTRODUCTION TO TOKENOMICS
# ===================================================================

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
from typing import Dict, List
import warnings
warnings.filterwarnings('ignore')

print("="*70)
print("INTRODUCTION TO TOKENOMICS")
print("="*70)

# ----------------------------------------------------------------
# PART A: TOKEN SUPPLY SIMULATION
# ----------------------------------------------------------------

print("\n" + "-"*60)
print("PART A: Token Supply Simulation")
print("-"*60)

class TokenSupply:
    """
    Simulated token supply with different emission models.
    """
    def __init__(self, max_supply: int = 1000000):
        self.max_supply = max_supply
        self.circulating_supply = 0
        self.burned_supply = 0
        self.history = []
    
    def mint(self, amount: int) -> bool:
        """Mint new tokens."""
        if self.circulating_supply + amount > self.max_supply:
            print(f"Cannot mint {amount}: exceeds max supply")
            return False
        self.circulating_supply += amount
        self.history.append({
            'type': 'mint',
            'amount': amount,
            'circulating': self.circulating_supply,
            'burned': self.burned_supply
        })
        return True
    
    def burn(self, amount: int) -> bool:
        """Burn existing tokens."""
        if amount > self.circulating_supply:
            print(f"Cannot burn {amount}: insufficient supply")
            return False
        self.circulating_supply -= amount
        self.burned_supply += amount
        self.history.append({
            'type': 'burn',
            'amount': amount,
            'circulating': self.circulating_supply,
            'burned': self.burned_supply
        })
        return True
    
    def get_inflation_rate(self, window: int = 10) -> float:
        """Calculate inflation rate over a window."""
        if len(self.history) < window:
            return 0
        recent = self.history[-window:]
        start_supply = recent[0]['circulating']
        end_supply = recent[-1]['circulating']
        if start_supply == 0:
            return 0
        return (end_supply - start_supply) / start_supply
    
    def get_metrics(self) -> Dict:
        return {
            'max_supply': self.max_supply,
            'circulating_supply': self.circulating_supply,
            'burned_supply': self.burned_supply,
            'total_supply': self.circulating_supply + self.burned_supply,
            'percentage_circulating': (self.circulating_supply / self.max_supply) * 100
        }

# Simulate token supply
token = TokenSupply(max_supply=1000000)

print("Token Supply Simulation:")
for i in range(20):
    # Mint some tokens
    mint_amount = np.random.randint(1000, 5000)
    token.mint(mint_amount)
    
    # Occasionally burn tokens
    if np.random.random() < 0.1:
        burn_amount = np.random.randint(100, 1000)
        token.burn(burn_amount)

# Metrics
metrics = token.get_metrics()
print(f"Max Supply: {metrics['max_supply']:,}")
print(f"Circulating Supply: {metrics['circulating_supply']:,}")
print(f"Burned Supply: {metrics['burned_supply']:,}")
print(f"Total Supply: {metrics['total_supply']:,}")
print(f"Percentage Circulating: {metrics['percentage_circulating']:.1f}%")

# ----------------------------------------------------------------
# PART B: TOKEN ECONOMY SIMULATION
# -----------------------------------------------------------------

print("\n" + "-"*60)
print("PART B: Token Economy Simulation (MV = PQ)")
print("-"*60)

class TokenEconomy:
    """
    Simulated token economy using the equation of exchange.
    """
    def __init__(self, name: str):
        self.name = name
        self.money_supply = 0
        self.velocity = 0
        self.price_level = 0
        self.quantity = 0
        self.equilibrium_price = 0
        self.history = []
    
    def simulate(self, money_supply: float, velocity: float, quantity: float):
        """Simulate token economy with given parameters."""
        self.money_supply = money_supply
        self.velocity = velocity
        self.quantity = quantity
        # MV = PQ → P = MV / Q
        self.equilibrium_price = (money_supply * velocity) / quantity
        self.price_level = self.equilibrium_price
        
        self.history.append({
            'money_supply': money_supply,
            'velocity': velocity,
            'quantity': quantity,
            'price': self.equilibrium_price
        })
        
        return self.equilibrium_price
    
    def simulate_scenario(self, scenarios: List[Dict]) -> pd.DataFrame:
        """Simulate different economic scenarios."""
        results = []
        for scenario in scenarios:
            m = scenario.get('money_supply', self.money_supply)
            v = scenario.get('velocity', self.velocity)
            q = scenario.get('quantity', self.quantity)
            price = (m * v) / q
            results.append({
                'scenario': scenario.get('name', 'Scenario'),
                'money_supply': m,
                'velocity': v,
                'quantity': q,
                'price': price
            })
        return pd.DataFrame(results)
    
    def get_metrics(self) -> Dict:
        if not self.history:
            return {}
        last = self.history[-1]
        return {
            'name': self.name,
            'money_supply': last['money_supply'],
            'velocity': last['velocity'],
            'quantity': last['quantity'],
            'price': last['price']
        }

# Simulate token economy
economy = TokenEconomy("Sample Economy")

print("Token Economy Simulation:")
print("Scenario 1: Base Case")
price1 = economy.simulate(
    money_supply=1000000,
    velocity=10,
    quantity=50000
)
print(f"  Money Supply: 1,000,000 tokens")
print(f"  Velocity: 10 transactions/year")
print(f"  Quantity: 50,000 units of service")
print(f"  Price per unit: ${price1:.2f}")

print("\nScenario 2: Increased Velocity")
price2 = economy.simulate(
    money_supply=1000000,
    velocity=20,
    quantity=50000
)
print(f"  Money Supply: 1,000,000 tokens")
print(f"  Velocity: 20 transactions/year")
print(f"  Quantity: 50,000 units of service")
print(f"  Price per unit: ${price2:.2f}")
print(f"  Impact of velocity increase: {(price2/price1 - 1) * 100:.0f}% price increase")

print("\nScenario 3: Increased Supply")
price3 = economy.simulate(
    money_supply=2000000,
    velocity=10,
    quantity=50000
)
print(f"  Money Supply: 2,000,000 tokens")
print(f"  Velocity: 10 transactions/year")
print(f"  Quantity: 50,000 units of service")
print(f"  Price per unit: ${price3:.2f}")
print(f"  Impact of supply increase: {(price3/price1 - 1) * 100:.0f}% price increase")

# ----------------------------------------------------------------
# PART C: TOKEN DISTRIBUTION VISUALISATION
# -----------------------------------------------------------------

print("\n" + "-"*60)
print("PART C: Token Distribution Visualisation")
print("-"*60)

# Simulate token distribution
distribution = {
    'Category': ['Team', 'Investors', 'Community', 'Treasury', 'Airdrops'],
    'Percentage': [15, 25, 30, 20, 10],
    'Vesting (months)': [24, 12, 6, 0, 0]
}

dist_df = pd.DataFrame(distribution)
print(dist_df.to_string(index=False))

# Visualise distribution
fig, axes = plt.subplots(1, 2, figsize=(14, 5))

ax1 = axes[0]
ax1.pie(dist_df['Percentage'], labels=dist_df['Category'], autopct='%1.1f%%', startangle=90)
ax1.set_title('Token Distribution by Category')

ax2 = axes[1]
ax2.bar(dist_df['Category'], dist_df['Vesting (months)'], color='teal', alpha=0.7)
ax2.set_xlabel('Category')
ax2.set_ylabel('Vesting Period (months)')
ax2.set_title('Vesting Period by Category')
ax2.grid(True, alpha=0.3)

plt.tight_layout()
plt.savefig('token_distribution.png', dpi=300, bbox_inches='tight')
plt.show()
print("Token distribution chart saved as 'token_distribution.png'")

# ----------------------------------------------------------------
# PART D: SUMMARY AND RECOMMENDATIONS
# -----------------------------------------------------------------

print("\n" + "="*70)
print("PART D: Summary and Recommendations")
print("="*70)

print("""
Introduction to Tokenomics – Key Takeaways:

1. Tokenomics is the design of economic systems around blockchain tokens.
2. Key components: creation/distribution, utility/functionality, value mechanisms, incentive structures.
3. Token categories: utility, security, governance, payment, asset-backed, meme.
4. Key parameters: supply (max, circulating, inflation/deflation rate), distribution (vesting, allocation), utility.
5. Equation of exchange: MV = PQ (Money supply × Velocity = Price × Quantity).
6. Token velocity affects price: higher velocity → lower price (utility-driven).
7. Inflationary models: minting (rewards, mining). Deflationary models: burning (scarcity).

Recommendations:
  - Design tokenomics for long-term sustainability.
  - Align incentives between all stakeholders.
  - Consider both inflationary and deflationary mechanisms.
  - Ensure fair distribution with appropriate vesting.
  - Build real utility to support token value.
  - Monitor velocity and adjust parameters.
  - Be transparent about tokenomics design.
""")