# Stablecoin supply growth → crypto market liquidity expansion
# Historical correlation: BTC price and total stablecoin supply r > 0.85
stablecoin_supply = {
    "USDT": 140_000_000_000,    # ~$140B (dominant, ~65% share)
    "USDC": 45_000_000_000,     # ~$45B (~20% share)
    "DAI": 5_000_000_000,       # ~$5B (decentralized)
    "FDUSD": 3_000_000_000,     # ~$3B (Binance ecosystem)
    "USDS": 2_000_000_000,      # ~$2B (Sky/MakerDAO)
}
total = sum(stablecoin_supply.values())

def mint_burn_signal(mint_events, burn_events, lookback_days=7):
    """Analyze recent stablecoin mint/burn events."""
    net_mint = sum(e.amount for e in mint_events if e.days_ago <= lookback_days)
    net_burn = sum(e.amount for e in burn_events if e.days_ago <= lookback_days)
    net_flow = net_mint - net_burn
    if net_flow > 1_000_000_000:    # >$1B net mint in 7 days
        return "large_capital_inflow"
    elif net_flow > 500_000_000:
        return "moderate_inflow"
    elif net_flow > 0:
        return "mild_inflow"
    elif net_flow > -500_000_000:
        return "mild_outflow"
    else:
        return "large_capital_outflow"

# Exchange stablecoin reserve interpretation
def exchange_reserve_signal(reserve_change_7d_pct, total_reserve_usd):
    """
    Rising exchange stablecoin reserves = buying power accumulating
    Falling exchange stablecoin reserves = capital deployed or withdrawn
    """
    if reserve_change_7d_pct > 5:
        return "buy_power_accumulating"     # Dry powder building up
    elif reserve_change_7d_pct > 2:
        return "mild_accumulation"
    elif reserve_change_7d_pct < -5:
        return "deployed_or_withdrawn"       # Either bought crypto or left exchange
    elif reserve_change_7d_pct < -2:
        return "mild_deployment"
    else:
        return "stable"

# Stablecoin dominance as a contrarian indicator
stablecoin_dominance = total_stablecoin_mcap / total_crypto_mcap * 100
if stablecoin_dominance > 12:
    signal = "high_cash_allocation"      # Market fearful, lots of cash on sidelines
    contrarian = "bullish"               # Cash will eventually re-enter
elif stablecoin_dominance > 8:
    signal = "moderate_cash"
    contrarian = "neutral"
elif stablecoin_dominance < 5:
    signal = "low_cash_allocation"       # Market fully invested, little dry powder
    contrarian = "bearish"               # No marginal buyers left

def velocity_signal(transfer_volume_7d, supply):
    velocity = transfer_volume_7d / supply
    velocity_annualized = velocity * 52  # Weekly to annual
    if velocity_annualized > 50:
        return "high_activity"     # Very active usage, likely bull market
    elif velocity_annualized > 20:
        return "moderate_activity"
    elif velocity_annualized < 10:
        return "low_activity"      # Stablecoins idle, bear market / accumulation

stablecoin_score = {
    "supply_growth": 0,           # -2 to +2: 30-day total supply change
    "mint_burn_net": 0,           # -2 to +2: recent large mint/burn events
    "exchange_reserves": 0,       # -2 to +2: exchange stablecoin reserve change
    "dominance": 0,               # -2 to +2: stablecoin dominance level (contrarian)
    "velocity": 0,                # -2 to +2: on-chain activity level
}
# Total range: -10 to +10
# > +5: strong liquidity expansion → bullish for crypto
# +2 to +5: moderate inflow → mild bullish
# -2 to +2: neutral
# < -2: liquidity contraction → bearish
# < -5: capital flight → strong bearish

## Stablecoin Flow Analysis — [Date Range]
 
### Supply Overview
| Stablecoin | Supply | 7d Change | 30d Change |
|------------|--------|-----------|------------|
| USDT | $XXX B | +X.X% | +X.X% |
| USDC | $XX B | +X.X% | +X.X% |
| Total | $XXX B | +X.X% | +X.X% |
 
### Mint/Burn Events (7 days)
- **Net minting**: +$X.X B
- **Largest events**: [Tether minted $500M on DATE, Circle burned $200M on DATE]
- **Signal**: [large capital inflow / mild / outflow]
 
### Exchange Reserves
- **Total stablecoins on exchanges**: $XX B
- **7d change**: [+/- X.X%]
- **Interpretation**: [buy power accumulating / deployed / withdrawn]
 
### Stablecoin Dominance
- **Current**: X.X%
- **30d ago**: X.X%
- **Signal**: [high cash = contrarian bullish / low cash = contrarian bearish]
 
### Chain Distribution Shifts
- **Inflow chains**: [Solana +$XM, Arbitrum +$XM]
- **Outflow chains**: [Tron -$XM]
- **Interpretation**: [DeFi expansion / speculative activity / capital consolidation]
 
### Composite Signal
| Dimension | Score (-2~+2) | Basis |
|-----------|---------------|-------|
| Supply growth | +2 | +4% in 30 days |
| Mint/burn | +1 | Net $1.2B minted this week |
| Exchange reserves | +1 | Reserves up 3% |
| Dominance | 0 | 8.5%, neutral range |
| Velocity | +1 | Rising on-chain activity |
 
### Market Implication
- **Liquidity outlook**: [expanding / stable / contracting]
- **Direction**: [bullish / neutral / bearish]
- **Key watch**: [next large mint event, USDC/USDT ratio trend]