┌─────────────────────────────────────────────────────────────────────────────┐
│                    TOKEN SUPPLY SOURCES                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    INITIAL SUPPLY                                    │   │
│  │  Tokens created at genesis (pre-mined)                              │   │
│  │  • Fixed at launch                                                   │   │
│  │  • Distributed via allocation                                        │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    MINING & MINTING                                 │   │
│  │  New tokens created over time                                       │   │
│  │  • Proof of Work (mining rewards)                                   │   │
│  │  • Proof of Stake (staking rewards)                                 │   │
│  │  • Protocol emissions                                               │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    BURNING                                           │   │
│  │  Tokens permanently removed from circulation                        │   │
│  │  • Transaction fee burns                                             │   │
│  │  • Buy-and-burn programs                                            │   │
│  │  • Protocol mechanisms                                              │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    UNLOCKING                                         │   │
│  │  Previously locked tokens become available                          │   │
│  │  • Vesting schedules ending                                         │   │
│  │  • Staked tokens being withdrawn                                    │   │
│  │  • Lock-up periods expiring                                        │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                    TOKEN DEMAND DRIVERS                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    UTILITY DEMAND                                    │   │
│  │  Demand driven by functional use of the token.                      │   │
│  │  • Gas fees for transactions                                        │   │
│  │  • Access to services                                               │   │
│  │  • Storage fees                                                     │   │
│  │  • Governance participation                                         │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    INVESTMENT DEMAND                                │   │
│  │  Demand driven by expectation of future returns.                   │   │
│  │  • Speculation on price appreciation                               │   │
│  │  • Store of value                                                   │   │
│  │  • Portfolio diversification                                       │   │
│  │  • Inflation hedge                                                 │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    INCENTIVE DEMAND                                 │   │
│  │  Demand driven by economic incentives.                             │   │
│  │  • Staking rewards                                                  │   │
│  │  • Yield farming                                                    │   │
│  │  • Liquidity mining                                                │   │
│  │  • Referral rewards                                                │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    v                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    NETWORK EFFECT DEMAND                            │   │
│  │  Demand driven by network growth and adoption.                     │   │
│  │  • More users → More demand                                         │   │
│  │  • Metcalfe's Law                                                   │   │
│  │  • Ecosystem growth                                                │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Velocity = Transaction Volume / Circulating Supply

- High velocity: Tokens used frequently (transactional)
- Low velocity: Tokens held for investment (store of value)

┌─────────────────────────────────────────────────────────────────────────────┐
│                    VELOCITY AND PRICE RELATIONSHIP                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Equation of Exchange: MV = PQ                                             │
│                                                                             │
│  M = Money Supply (Token Supply)                                           │
│  V = Velocity (How fast tokens move)                                      │
│  P = Price of goods/services (in tokens)                                  │
│  Q = Quantity of goods/services (Ecosystem activity)                     │
│                                                                             │
│  Price = (M × V) / Q                                                       │
│                                                                             │
│  Implications:                                                              │
│  • Higher velocity → Lower price (all else equal)                          │
│  • Lower velocity → Higher price (all else equal)                          │
│  • Higher Q (activity) → Higher price                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                    ORDER BOOK DYNAMICS                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Buy Orders (Bids)      Price      Sell Orders (Asks)                     │
│  ──────────────────────────────────────────────────────────────────────────│
│  100 tokens @ $95       $95       200 tokens @ $100                       │
│  200 tokens @ $94       $94       150 tokens @ $101                       │
│  300 tokens @ $93       $93       100 tokens @ $102                       │
│  400 tokens @ $92       $92       80 tokens @ $103                       │
│                                                                             │
│  Market Price: $97.50 (midpoint)                                          │
│  Spread: $5.00 (difference between best bid and ask)                      │
│  Depth: Total buy/sell volume at each price level                         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

# ===================================================================
# MODULE 6, LESSON 5: TOKEN SUPPLY AND DEMAND DYNAMICS
# ===================================================================

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

print("="*70)
print("TOKEN SUPPLY AND DEMAND DYNAMICS")
print("="*70)

# ----------------------------------------------------------------
# PART A: SUPPLY AND DEMAND SIMULATION
# ----------------------------------------------------------------

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

class TokenMarket:
    """
    Simulated token market with supply and demand dynamics.
    """
    def __init__(self, initial_supply: int = 1000000, initial_price: float = 1.0):
        self.supply = initial_supply
        self.price = initial_price
        self.demand_shock = 0
        self.history = []
        self.burned = 0
        self.minted = 0
    
    def set_demand(self, demand: float):
        """Set demand level (0-100)."""
        self.demand_shock = max(0, min(100, demand))
    
    def mint_tokens(self, amount: int):
        """Mint new tokens (inflation)."""
        self.supply += amount
        self.minted += amount
    
    def burn_tokens(self, amount: int):
        """Burn tokens (deflation)."""
        if amount <= self.supply:
            self.supply -= amount
            self.burned += amount
    
    def calculate_price(self) -> float:
        """
        Calculate price based on supply and demand.
        Price = Base_Price × (Demand_Shock / Supply)
        """
        # Base price
        base_price = 1.0
        
        # Demand factor (0-2 scale)
        demand_factor = 1 + (self.demand_shock / 100)
        
        # Supply factor (inverse relationship)
        supply_factor = 1000000 / max(self.supply, 1)
        
        # Calculate price
        price = base_price * demand_factor * supply_factor
        self.price = price
        return price
    
    def step(self, demand: float = None):
        """
        Simulate one market step.
        """
        if demand is not None:
            self.set_demand(demand)
        
        price = self.calculate_price()
        
        self.history.append({
            'supply': self.supply,
            'demand': self.demand_shock,
            'price': price,
            'minted': self.minted,
            'burned': self.burned
        })
        
        return price
    
    def get_metrics(self) -> Dict:
        if not self.history:
            return {}
        last = self.history[-1]
        return {
            'supply': last['supply'],
            'demand': last['demand'],
            'price': last['price'],
            'minted': self.minted,
            'burned': self.burned,
            'net_change': self.minted - self.burned
        }

# Simulate token market
market = TokenMarket(initial_supply=1000000, initial_price=1.0)

print("Token Market Simulation:")
print("Initial Supply: 1,000,000 tokens")
print("Initial Price: $1.00\n")

# Simulate market cycles
demand_phases = [
    ('Phase 1: Low Demand', 20),
    ('Phase 2: Moderate Demand', 50),
    ('Phase 3: High Demand', 80),
    ('Phase 4: Very High Demand', 95),
    ('Phase 5: Demand Drop', 30),
    ('Phase 6: Recovery', 60)
]

for phase_name, demand in demand_phases:
    # Mint some tokens during high demand (inflation)
    if demand > 70:
        market.mint_tokens(10000)
    
    # Burn some tokens during low demand (deflation)
    if demand < 40:
        market.burn_tokens(5000)
    
    # Step simulation
    price = market.step(demand)
    print(f"{phase_name}: Demand={demand}%, Price=${price:.2f}")

# Metrics
metrics = market.get_metrics()
print(f"\nMarket Metrics:")
print(f"  Current Supply: {metrics['supply']:,}")
print(f"  Current Price: ${metrics['price']:.2f}")
print(f"  Net Supply Change: {metrics['net_change']:,}")

# ----------------------------------------------------------------
# PART B: VELOCITY AND PRICE SIMULATION
# -----------------------------------------------------------------

print("\n" + "-"*60)
print("PART B: Velocity and Price Simulation")
print("-"*60)

class VelocityModel:
    """
    Simulated token velocity and price relationship.
    """
    def __init__(self, supply: float = 1000000):
        self.supply = supply
        self.velocity = 0
        self.quantity = 0
        self.price = 0
        self.history = []
    
    def simulate(self, velocity: float, quantity: float) -> float:
        """Simulate price based on MV = PQ."""
        self.velocity = velocity
        self.quantity = quantity
        self.price = (self.supply * velocity) / quantity
        
        self.history.append({
            'velocity': velocity,
            'quantity': quantity,
            'price': self.price
        })
        
        return self.price
    
    def get_relationship(self) -> pd.DataFrame:
        """Generate data for velocity-price relationship."""
        data = []
        for velocity in np.linspace(1, 50, 20):
            price = (self.supply * velocity) / self.quantity
            data.append({
                'velocity': velocity,
                'price': price
            })
        return pd.DataFrame(data)

# Simulate velocity impact
velocity_model = VelocityModel(supply=1000000)

print("Velocity and Price Simulation:")
print("Fixed Quantity: 50,000 units of service\n")

velocities = [5, 10, 15, 20, 30, 50]
quantity = 50000

for v in velocities:
    price = velocity_model.simulate(v, quantity)
    print(f"Velocity: {v} → Price: ${price:.2f}")

print(f"\nVelocity Impact: {velocities[-1]/velocities[0]:.0f}x velocity increase → {price/velocities[0]:.1f}x price increase")

# Visualise velocity-price relationship
fig, ax = plt.subplots(figsize=(10, 5))
rel_data = velocity_model.get_relationship()
ax.plot(rel_data['velocity'], rel_data['price'], color='blue', linewidth=2)
ax.set_xlabel('Velocity')
ax.set_ylabel('Token Price')
ax.set_title('Velocity vs Token Price (MV = PQ)')
ax.grid(True, alpha=0.3)

plt.tight_layout()
plt.savefig('velocity_price.png', dpi=300, bbox_inches='tight')
plt.show()
print("Velocity-price chart saved as 'velocity_price.png'")

# ----------------------------------------------------------------
# PART C: SUPPLY AND DEMAND METRICS
# -----------------------------------------------------------------

print("\n" + "-"*60)
print("PART C: Supply and Demand Metrics")
print("-"*60)

metrics_data = {
    'Metric': ['Max Supply', 'Circulating Supply', 'Total Supply', 'Inflation Rate', 'Burn Rate', 'Staking Rate'],
    'Bitcoin (BTC)': ['21,000,000', '19,700,000', '19,700,000', '1.7%', '0%', '0%'],
    'Ethereum (ETH)': ['Unlimited', '120,000,000', '120,000,000', '0.5%', '0.1%', '25%'],
    'Solana (SOL)': ['~489,000,000', '~380,000,000', '~380,000,000', '5%', '0%', '65%'],
    'BNB': ['200,000,000', '~160,000,000', '~160,000,000', '0%', '~1%', '~10%']
}

metrics_df = pd.DataFrame(metrics_data)
print(metrics_df.to_string(index=False))

# ----------------------------------------------------------------
# PART D: MARKET MICROSTRUCTURE
# -----------------------------------------------------------------

print("\n" + "-"*60)
print("PART D: Market Microstructure Analysis")
print("-"*60)

microstructure_data = {
    'Factor': ['Order Book Depth', 'Slippage', 'Spread', 'Volume', 'Market Making'],
    'Description': [
        'Number of orders at each price level',
        'Price impact of large trades',
        'Bid-ask spread',
        'Trading volume',
        'Liquidity provision activity'
    ],
    'Impact on Price': [
        'Stability',
        'Trading cost',
        'Transaction cost',
        'Price discovery',
        'Price efficiency'
    ]
}

micro_df = pd.DataFrame(microstructure_data)
print(micro_df.to_string(index=False))

# ----------------------------------------------------------------
# PART E: SUMMARY AND RECOMMENDATIONS
# -----------------------------------------------------------------

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

print("""
Token Supply and Demand Dynamics – Key Takeaways:

1. Supply sources: initial supply, minting, burning, unlocking.
2. Supply metrics: max supply, circulating supply, total supply, inflation/burn rate.
3. Demand drivers: utility, investment, incentives, network effects.
4. Organic demand: sustainable, utility-driven. Speculative demand: volatile, sentiment-driven.
5. Token velocity: MV = PQ; higher velocity = lower price (all else equal).
6. Supply management: staking (reduces velocity), burning (reduces supply), vesting (delayed release).
7. Market microstructure: order books, slippage, spreads, volume, market making.

Recommendations:
  - Monitor velocity alongside price.
  - Analyse demand drivers (utility vs speculation).
  - Design supply mechanisms for sustainability.
  - Use staking to reduce velocity.
  - Implement burns to offset inflation.
  - Track market microstructure metrics.
  - Consider macro conditions in demand analysis.
""")