import pandas as pd import numpy as np import matplotlib.pyplot as plt import seaborn as sns from datetime import datetime import warnings warnings.filterwarnings('ignore') # ============================================================================ # CONFIGURATION SECTION - MODIFY THESE FOR EACH SEASON # ============================================================================ # Input files POINTS_FILE = 'final_sonic_s2_points.csv' TVL_FILE = 'active_tvl_week_s2.csv' # Output file OUTPUT_FILE = 'final_token_distribution.csv' # Token allocation parameters TOKEN_ALLOCATION = 3_540_000.0 TOKEN_PRICE = 0.14 MIN_TOKEN_THRESHOLD = 1.0 # Minimum tokens to receive (post-filter) # Progressive strategy parameters PROGRESSIVE_MULTIPLIERS = [3.5, 2.8, 2.2, 1.6, 1.0, 0.6, 0.4] # Tier 0-6 PROGRESSIVE_APY_CAPS = { 0: 40.0, # Tier 0 (lowest points): 40% max APY 1: 35.0, # Tier 1: 35% max APY 2: 30.0, # Tier 2: 30% max APY 3: 25.0, # Tier 3: 25% max APY 4: 20.0, # Tier 4: 20% max APY 5: 15.0, # Tier 5: 15% max APY 6: 10.0 # Tier 6 (highest points): 10% max APY } # ============================================================================ # END CONFIGURATION SECTION # ============================================================================ class UnifiedTokenDistributor: def __init__(self): """Initialize the unified token distributor with configuration parameters""" self.total_tokens = TOKEN_ALLOCATION self.token_price = TOKEN_PRICE self.min_token_threshold = MIN_TOKEN_THRESHOLD self.total_budget = self.total_tokens * self.token_price # Progressive strategy parameters self.progressive_multipliers = PROGRESSIVE_MULTIPLIERS self.progressive_apy_caps = PROGRESSIVE_APY_CAPS print("="*80) print(f"SONIC SEASON 2 DISTRIBUTION SYSTEM") print("="*80) print(f"Total Budget: ${self.total_budget:,.0f}") print(f"Total Tokens: {self.total_tokens:,}") print(f"Token Price: ${self.token_price:.2f}") print(f"Min Token Threshold (post-filter): {self.min_token_threshold:,}") # Load and combine data self.load_and_combine_data(POINTS_FILE, TVL_FILE) def load_and_combine_data(self, points_file, tvl_file): """Load and combine points and TVL data""" # Load points data points_df = pd.read_csv(points_file) # Rename column to match expected format points_df = points_df.rename(columns={'sonic_points': 'total_points'}) # Group by user_address (in case of duplicates) user_points = points_df.groupby('user_address').agg({ 'total_points': 'last' }).reset_index() # Load TVL data tvl_df = pd.read_csv(tvl_file) # Aggregate TVL by user tvl_agg = tvl_df.groupby('user_address').agg({ 'tvl': ['mean', 'count', 'sum'] }).reset_index() tvl_agg.columns = ['user_address', 'weekly_avg_tvl', 'weeks', 'total_weekly_tvl'] tvl_agg['avg_daily_tvl'] = tvl_agg['weekly_avg_tvl'] / 7.0 # Combine data combined_df = user_points.copy() combined_df = combined_df.merge(tvl_agg, on='user_address', how='left') combined_df = combined_df.fillna(0) # Calculate TVL-years using daily TVL exposure over actual weeks combined_df['tvl_years'] = ( combined_df['avg_daily_tvl'] * combined_df['weeks'] * 7.0 / 365.0 ) combined_df['total_avg_tvl'] = combined_df['avg_daily_tvl'] # Store all users self.all_users = combined_df.copy() def apply_prefilter(self): """ PRE-FILTER: Remove users with invalid data (zero TVL-years or zero points) This follows the methodology from progressive_token_distribution_with_apy_caps.py """ print(f"\n{'='*80}") print("STEP 1: APPLYING PRE-FILTER (Data Validation)") print(f"{'='*80}") # Filter out users with zero TVL-years or zero points (EXACT methodology from reference files) valid_mask = (self.all_users['tvl_years'] > 0) & \ (self.all_users['total_points'] > 0) self.eligible_users = self.all_users[valid_mask].copy() self.prefilter_excluded = self.all_users[~valid_mask].copy() print(f" Total users loaded: {len(self.all_users):,}") print(f" Users passing pre-filter: {len(self.eligible_users):,} ({len(self.eligible_users)/len(self.all_users)*100:.1f}%)") print(f" Users excluded (zero TVL-years or zero points): {len(self.prefilter_excluded):,} ({len(self.prefilter_excluded)/len(self.all_users)*100:.1f}%)") # Calculate base value per point for eligible users self.total_eligible_points = self.eligible_users['total_points'].sum() self.base_value_per_point = self.total_budget / self.total_eligible_points print(f"\n Total eligible points: {self.total_eligible_points:,.0f}") print(f" Base value per point: ${self.base_value_per_point:.8f}") return self.eligible_users def define_point_tiers(self): """Define point-based tiers based on eligible users data distribution""" print(f"\n{'='*80}") print("STEP 2: DEFINING POINT-BASED TIERS") print(f"{'='*80}") # Use only eligible users with >0 points for percentile calculation points_data = self.eligible_users[self.eligible_users['total_points'] > 0]['total_points'].copy() # Calculate key statistics min_points = points_data.min() max_points = points_data.max() mean_points = points_data.mean() median_points = points_data.median() print(f"Points range: {min_points:,.0f} - {max_points:,.0f}") print(f"Mean points: {mean_points:,.0f}") print(f"Median points: {median_points:,.0f}") # Calculate percentiles for tier boundaries percentiles = [0, 20, 40, 60, 75, 90, 97, 100] percentile_values = [] print(f"\nPoint Distribution Percentiles:") for p in percentiles: value = np.percentile(points_data, p) percentile_values.append(value) print(f" {p:2d}th percentile: {value:>12,.0f} points") # Create boundaries based on percentiles boundaries = [ 0, # Tier 0: Bottom 20% percentile_values[1], # Tier 1: 20th-40th percentile percentile_values[2], # Tier 2: 40th-60th percentile percentile_values[3], # Tier 3: 60th-75th percentile percentile_values[4], # Tier 4: 75th-90th percentile percentile_values[5], # Tier 5: 90th-97th percentile percentile_values[6], # Tier 6: Top 3% float('inf') ] # Round boundaries to nice numbers boundaries_rounded = [0] for i in range(1, len(boundaries)-1): if boundaries[i] < 1000: rounded = round(boundaries[i], -1) elif boundaries[i] < 10000: rounded = round(boundaries[i], -2) elif boundaries[i] < 100000: rounded = round(boundaries[i], -3) else: rounded = round(boundaries[i], -4) boundaries_rounded.append(rounded) boundaries_rounded.append(float('inf')) # Create descriptive tier names tier_names = [] for i in range(len(boundaries_rounded) - 1): if i == 0: tier_names.append(f'Tier 0: {boundaries_rounded[i]:,.0f}-{boundaries_rounded[i+1]:,.0f} pts (Bottom 20%)') elif i == len(boundaries_rounded) - 2: tier_names.append(f'Tier {i}: {boundaries_rounded[i]:,.0f}+ pts (Top 3%)') else: tier_names.append(f'Tier {i}: {boundaries_rounded[i]:,.0f}-{boundaries_rounded[i+1]:,.0f} pts') print(f"\nFinal Tier Boundaries:") for name in tier_names: print(f" {name}") return boundaries_rounded, tier_names def assign_tiers(self): """Assign users to point-based tiers""" boundaries, tier_names = self.define_point_tiers() self.eligible_users['tier'] = 0 self.eligible_users['tier_name'] = '' for i in range(len(boundaries) - 1): mask = (self.eligible_users['total_points'] > boundaries[i]) & \ (self.eligible_users['total_points'] <= boundaries[i+1]) self.eligible_users.loc[mask, 'tier'] = i self.eligible_users.loc[mask, 'tier_name'] = tier_names[i] # Print tier distribution print(f"\nTier Distribution:") tier_counts = self.eligible_users['tier'].value_counts().sort_index() for tier, count in tier_counts.items(): pct = (count / len(self.eligible_users)) * 100 avg_points = self.eligible_users[self.eligible_users['tier'] == tier]['total_points'].mean() print(f" Tier {tier}: {count:,} users ({pct:.1f}%) - Avg: {avg_points:,.0f} points") return self.eligible_users def apply_progressive_distribution(self): """ Apply progressive strategy with tier-based multipliers and APY caps This follows the methodology from progressive_token_distribution_with_apy_caps.py """ print(f"\n{'='*80}") print("STEP 3: APPLYING PROGRESSIVE DISTRIBUTION STRATEGY") print(f"{'='*80}") users_df = self.eligible_users.copy() # Apply multipliers by tier users_df['point_value_multiplier'] = 1.0 users_df['adjusted_point_value'] = self.base_value_per_point for tier, multiplier in enumerate(self.progressive_multipliers): tier_mask = users_df['tier'] == tier users_df.loc[tier_mask, 'point_value_multiplier'] = multiplier users_df.loc[tier_mask, 'adjusted_point_value'] = self.base_value_per_point * multiplier # Calculate distribution values users_df['raw_value'] = users_df['total_points'] * users_df['adjusted_point_value'] total_raw_value = users_df['raw_value'].sum() # Normalize to total budget normalization_factor = self.total_budget / total_raw_value users_df['final_value'] = users_df['raw_value'] * normalization_factor users_df['final_tokens'] = users_df['final_value'] / self.token_price users_df['final_apy'] = (users_df['final_value'] / users_df['tvl_years']) * 100 print(f"Progressive Distribution Applied:") print(f" Total raw value: ${total_raw_value:,.0f}") print(f" Normalization factor: {normalization_factor:.4f}") print(f" Final total value: ${users_df['final_value'].sum():,.0f}") print(f" Final total tokens: {users_df['final_tokens'].sum():,.0f}") print(f"\n Pre-Filter Distribution Results:") print(f" Total value: ${users_df['final_value'].sum():,.0f}") print(f" Total tokens: {users_df['final_tokens'].sum():,.0f}") print(f" Budget utilization: {users_df['final_value'].sum()/self.total_budget*100:.4f}%") # print(f" APY range: {users_df['final_apy'].min():.2f}% - {users_df['final_apy'].max():.2f}%") # print(f" Mean APY: {users_df['final_apy'].mean():.2f}%") # Filter by minimum token threshold and redistribute users_df = self.filter_and_redistribute(users_df) self.distributed_users = users_df return users_df def filter_and_redistribute(self, users_df): """ POST-FILTER: Filter users by minimum token threshold and redistribute excess tokens This follows the methodology from filter_and_redistribute.py """ print(f"\n{'='*80}") print("STEP 4: POST-FILTER & REDISTRIBUTION (Minimum Token Threshold)") print(f"{'='*80}") if self.min_token_threshold <= 0: print(f" No minimum token threshold applied - all users eligible") return users_df # Filter by minimum tokens eligible_mask = users_df['final_tokens'] >= self.min_token_threshold eligible_df = users_df[eligible_mask].copy() excluded_df = users_df[~eligible_mask].copy() print(f" Minimum token threshold: {self.min_token_threshold:,}") print(f" Eligible users (>= {self.min_token_threshold} tokens): {len(eligible_df):,} ({len(eligible_df)/len(users_df)*100:.1f}%)") print(f" Excluded users (< {self.min_token_threshold} tokens): {len(excluded_df):,} ({len(excluded_df)/len(users_df)*100:.1f}%)") # Calculate tokens to redistribute tokens_to_redistribute = excluded_df['final_tokens'].sum() remaining_tokens = eligible_df['final_tokens'].sum() print(f" Tokens to redistribute: {tokens_to_redistribute:,.2f}") print(f" Remaining tokens before redistribution: {remaining_tokens:,.2f}") # Redistribute tokens proportionally to eligible users if tokens_to_redistribute > 0 and len(eligible_df) > 0: redistribution_factor = tokens_to_redistribute / remaining_tokens # Add redistributed tokens eligible_df['redistributed_tokens'] = eligible_df['final_tokens'] * redistribution_factor eligible_df['final_tokens'] = eligible_df['final_tokens'] + eligible_df['redistributed_tokens'] eligible_df['final_value'] = eligible_df['final_tokens'] * self.token_price # Recalculate APY after redistribution eligible_df['final_apy'] = (eligible_df['final_value'] / eligible_df['tvl_years']) * 100 print(f" Redistribution factor: {redistribution_factor:.6f} ({redistribution_factor*100:.4f}%)") print(f" Total redistributed: {eligible_df['redistributed_tokens'].sum():,.2f}") print(f" Final total after redistribution: {eligible_df['final_tokens'].sum():,.2f}") # Verify the total is correct expected_total = users_df['final_tokens'].sum() actual_total = eligible_df['final_tokens'].sum() difference = abs(expected_total - actual_total) print(f"\n ✅ VERIFICATION:") print(f" Expected total: {expected_total:,.2f}") print(f" Actual total: {actual_total:,.2f}") print(f" Difference: {difference:,.6f}") if difference < 0.01: print(" ✅ Redistribution successful - totals match within rounding error!") else: print(" ⚠️ Warning: Small discrepancy in totals") print(f"\n Final Distribution Results (After Filtering & Redistribution):") print(f" Total value: ${eligible_df['final_value'].sum():,.0f}") print(f" Total tokens: {eligible_df['final_tokens'].sum():,.0f}") # print(f" APY range: {eligible_df['final_apy'].min():.2f}% - {eligible_df['final_apy'].max():.2f}%") # print(f" Mean APY: {eligible_df['final_apy'].mean():.2f}%") # Store excluded users for reference self.postfilter_excluded = excluded_df return eligible_df def create_analysis_report(self): """Create comprehensive analysis report""" print(f"\n{'='*80}") print("COMPREHENSIVE DISTRIBUTION ANALYSIS") print(f"{'='*80}") dist_df = self.distributed_users # Tier-by-tier analysis print(f"\n📊 TIER-BY-TIER ANALYSIS:") print(f"{'Tier':<6} {'Users':<8} {'% Users':<9} {'Multiplier':<12} {'Avg APY':<10} {'APY Cap':<10} {'Avg Tokens':<12} {'Total Tokens':<15}") print("-" * 100) for tier in range(7): tier_data = dist_df[dist_df['tier'] == tier] if len(tier_data) > 0: multiplier = tier_data['point_value_multiplier'].iloc[0] avg_apy = tier_data['final_apy'].mean() apy_cap = self.progressive_apy_caps[tier] avg_tokens = tier_data['final_tokens'].mean() total_tokens = tier_data['final_tokens'].sum() pct_users = (len(tier_data) / len(dist_df)) * 100 print(f"T{tier:<5} {len(tier_data):<8,} {pct_users:<9.1f} {multiplier:<12.1f} {avg_apy:<10.1f} {apy_cap:<10.0f} {avg_tokens:<12.0f} {total_tokens:<15,.0f}") def create_final_output(self): """Create final distribution CSV file""" print(f"\n{'='*80}") print("CREATING FINAL DISTRIBUTION OUTPUT") print(f"{'='*80}") # Create final distribution dataframe final_dist = self.distributed_users[['user_address', 'total_points', 'tier', 'tier_name', 'point_value_multiplier', 'final_tokens', 'final_value', 'final_apy', 'tvl_years']].copy() # Round values final_dist['final_tokens'] = final_dist['final_tokens'].round(6) final_dist['final_value_usd'] = final_dist['final_value'].round(2) final_dist['final_apy'] = final_dist['final_apy'].round(2) final_dist['tvl_years'] = final_dist['tvl_years'].round(4) # Select final columns final_columns = [ 'user_address', 'total_points', 'tier', 'tier_name', 'point_value_multiplier', 'final_tokens', 'final_value_usd', 'final_apy', 'tvl_years' ] final_dist = final_dist[final_columns] # Sort by final tokens descending final_dist = final_dist.sort_values('final_tokens', ascending=False) # Save to CSV final_dist.to_csv(OUTPUT_FILE, index=False) # print(f"✅ Final distribution saved to: {OUTPUT_FILE}") print(f" Total records: {len(final_dist):,}") print(f" Total tokens distributed: {final_dist['final_tokens'].sum():,.0f}") print(f" Total value distributed: ${final_dist['final_value_usd'].sum():,.0f}") # Show token distribution ranges print(f"\n🎯 TOKEN DISTRIBUTION RANGES:") ranges = [ (0, 10, "< 10 tokens"), (10, 100, "10-100 tokens"), (100, 1000, "100-1,000 tokens"), (1000, 10000, "1,000-10,000 tokens"), (10000, 100000, "10,000-100,000 tokens"), (100000, float('inf'), "100,000+ tokens") ] for min_val, max_val, label in ranges: if max_val == float('inf'): count = (final_dist["final_tokens"] >= min_val).sum() else: count = ((final_dist["final_tokens"] >= min_val) & (final_dist["final_tokens"] < max_val)).sum() pct = count / len(final_dist) * 100 print(f" {label}: {count:,} addresses ({pct:.1f}%)") return final_dist def run_distribution(self): """Run the complete token distribution pipeline""" print(f"\n{'='*80}") print("STARTING TOKEN DISTRIBUTION PIPELINE") print(f"{'='*80}") # Step 1: Apply pre-filter (remove users with invalid TVL-years) self.apply_prefilter() # Step 2: Assign tiers self.assign_tiers() # Step 3: Apply progressive distribution (includes post-filter & redistribution) self.apply_progressive_distribution() # Step 4: Create analysis report # self.create_analysis_report() # Step 5: Create final output final_dist = self.create_final_output() print(f"\n{'='*80}") print(f"✅ TOKEN DISTRIBUTION COMPLETE") print(f"{'='*80}") print(f"\n📊 FINAL SUMMARY:") print(f" Total users loaded: {len(self.all_users):,}") print(f" Users passing pre-filter: {len(self.eligible_users):,}") print(f" Users receiving tokens: {len(self.distributed_users):,}") print(f" Total tokens distributed: {self.distributed_users['final_tokens'].sum():,.0f}") print(f" Total value distributed: ${self.distributed_users['final_value'].sum():,.0f}") if hasattr(self, 'prefilter_excluded') and len(self.prefilter_excluded) > 0: print(f"\n Pre-filter exclusions (zero TVL-years/points): {len(self.prefilter_excluded):,}") if hasattr(self, 'postfilter_excluded') and len(self.postfilter_excluded) > 0: print(f" Post-filter exclusions (below {self.min_token_threshold:,} tokens): {len(self.postfilter_excluded):,}") excluded_tokens = self.postfilter_excluded['final_tokens'].sum() if 'final_tokens' in self.postfilter_excluded.columns else 0 if excluded_tokens > 0: print(f" Tokens from excluded users: {excluded_tokens:,.2f} (redistributed to eligible users)") return final_dist def main(): """Main function to run the unified token distribution""" # Create distributor and run distributor = UnifiedTokenDistributor() final_distribution = distributor.run_distribution() return final_distribution, distributor if __name__ == "__main__": final_distribution, distributor = main()