decharge-scout 2.5.6 → 4.0.2

package/.env

@@ -0,0 +1,18 @@
+# EIA API Key (Required - Get from https://www.eia.gov/opendata/register.php)
+EIA_API_KEY=w0FzlyIlSkmb0Rw8H8IpxssShajZkQp9eT2sAZ0V
+
+# Solana Configuration
+SOLANA_NETWORK=devnet
+SOLANA_RPC_URL=https://api.devnet.solana.com
+
+# Mock Oracle Escrow Address (Replace with your test wallet for demo)
+ORACLE_ESCROW_ADDRESS=YourDevWalletPublicKeyHere
+
+# Dashboard API (Optional - for testing dashboard integration)
+DASHBOARD_API_URL=http://localhost:3000/submit
+
+# Stake Amount (in SOL)
+STAKE_AMOUNT=0.01
+
+# Premium Feature Price (in SOL)
+PREMIUM_PRICE=0.001

package/.env.example

@@ -1,5 +1,16 @@
-# EIA API Key (Required - Get from https://www.eia.gov/opendata/register.php)
+# Energy Data API Keys
+# Choose ONE based on your location (FREE options available!):
+#
+# 🇺🇸 USA (FREE): EIA API - Get from https://www.eia.gov/opendata/register.php
 EIA_API_KEY=your_eia_api_key_here
+#
+# 🇪🇺 Europe (FREE): ENTSO-E - Get from https://transparency.entsoe.eu/
+ENTSOE_API_KEY=your_entsoe_api_key_here
+#
+# 🇬🇧 UK (NO KEY NEEDED): Carbon Intensity API is completely FREE!
+#
+# 🌍 Global (PAID): Electricity Maps - Get from https://www.electricitymaps.com/
+ELECTRICITY_MAPS_API_KEY=your_electricity_maps_api_key_here
 
 # Solana Configuration
 SOLANA_NETWORK=devnet

package/README.md

@@ -1,6 +1,8 @@
-# DeCharge Scout
+# 🌍 Global Energy Scout
 
-AI-powered energy grid data scout with Solana blockchain integration. This CLI tool scouts public energy grid data, performs optimizations to find the cheapest EV charging windows, and submits anonymized results to a mock DeCharge oracle on Solana.
+**Weather-powered intelligent energy price forecasting with Solana blockchain integration.**
+
+This CLI tool uses **real-time weather data** to simulate energy grid pricing globally, helping you find the cheapest EV charging windows. No expensive APIs needed - completely FREE weather-based simulation that works worldwide!
 
 ## 🚀 Quick Install
 
@@ -14,22 +16,47 @@ Then run: `decharge-scout`
 
 [See more installation options →](ONE_COMMAND_INSTALL.md)
 
-## Features
-
-- **Real-time Energy Data**: Fetches live energy pricing and demand data from EIA and Electricity Maps APIs
-- **Smart Optimization**: Finds the cheapest charging windows in the next 24 hours
-- **Blockchain Integration**: Submits results to Solana devnet with anti-spam staking
-- **Points System**: Earn points for successful submissions and good optimizations
-- **Location Tracking**: Auto-detects location via IP for global dashboard visualization
-- **Premium Features**: x402 micropayments for enhanced forecast data
-- **Dashboard Ready**: Structured data output for global visualization
+## ✨ Features
+
+### 🌤️ **Weather-Powered Simulation** (NEW!)
+- **FREE** real-time weather data from Open-Meteo API (no key required!)
+- Simulates energy pricing based on:
+  - 🌡️ **Temperature** (AC/heating demand)
+  - 💨 **Wind speed** (renewable energy availability)
+  - ☀️ **Solar radiation** (solar energy generation)
+  - 🌙 **Time-of-day** patterns (peak/off-peak)
+- **50+ regional pricing models** (US, EU, IN, BR, JP, AU, etc.)
+- Intelligent insights explaining **why** certain times are cheaper
+
+### 🧠 **Smart Optimization**
+- Finds the cheapest 1-hour EV charging window in next 24 hours
+- Shows weather conditions at optimal time
+- Calculates potential savings (%)
+- Regional peak/off-peak pattern matching
+
+### 🌍 **Local Alpha Contribution**
+- Share your local grid knowledge (e.g., "7-9PM peak in Lagos")
+- Earn bonus points for contributing
+- Community-driven peak time database
+
+### ⛓️ **Blockchain Integration**
+- Submits results to Solana devnet with anti-spam staking
+- Points system for successful submissions
+- x402 micropayments for premium features (optional)
+
+### 🗺️ **Global Coverage**
+- Works **anywhere in the world**
+- Auto-detects location via IP
+- Custom location override supported
+- Dashboard-ready structured output
 
 ## Prerequisites
 
 - Node.js v20 or higher
-- A Solana wallet keypair file (JSON format)
-- EIA API key (free from https://www.eia.gov/opendata/register.php)
-- At least 0.02 SOL in your devnet wallet for staking + fees
+- **NO API KEYS REQUIRED!** 🎉
+  - Uses FREE Open-Meteo weather API (no registration needed)
+  - Works globally without any paid subscriptions
+- At least 0.02 SOL in your devnet wallet for staking + fees (auto-airdropped in setup)
 
 ## Installation
 
@@ -233,19 +260,47 @@ decharge-scout/
 
 ## API Data Sources
 
-### Primary: EIA API (ERCOT)
-- Endpoint: `https://api.eia.gov/v2/electricity/rto/region-data/data/`
-- Provides: Real-time demand and pricing for Texas (ERCOT)
-- Requires: Free API key from https://www.eia.gov/opendata/register.php
-
-### Secondary: Electricity Maps
-- Endpoint: `https://api.electricitymaps.com/v3/power-breakdown/latest`
-- Provides: Power grid forecasts and carbon intensity
-- Free tier available
-
-### Fallback: Mock Data
-- Generated locally if APIs are unavailable
-- Simulates realistic daily pricing patterns
+The CLI uses **smart routing** to automatically choose the best FREE API based on your location!
+
+### 🆓 FREE APIs (Recommended!)
+
+#### 🇺🇸 EIA API (US-only, FREE)
+- **Coverage**: United States only (ERCOT, CAISO, NYISO, PJM, MISO, ISNE)
+- **Endpoint**: `https://api.eia.gov/v2/electricity/rto/region-data/data/`
+- **Provides**: Real-time demand and pricing for US grid regions
+- **Get Key**: FREE at https://www.eia.gov/opendata/register.php
+- **Auto-used for**: Texas, California, New York, etc.
+
+#### 🇪🇺 ENTSO-E (Europe, FREE)
+- **Coverage**: All European countries
+- **Endpoint**: `https://web-api.tp.entsoe.eu/api`
+- **Provides**: Day-ahead electricity prices and demand forecasts
+- **Get Key**: FREE at https://transparency.entsoe.eu/
+- **Auto-used for**: Germany, France, Spain, Italy, Poland, Netherlands, Belgium, Austria
+- **Registration**: Free account required, instant approval
+
+#### 🇬🇧 UK Carbon Intensity (UK, FREE - No key needed!)
+- **Coverage**: United Kingdom only
+- **Endpoint**: `https://api.carbonintensity.org.uk`
+- **Provides**: Real-time carbon intensity and price forecasts
+- **Get Key**: No key needed! Completely open API
+- **Auto-used for**: UK locations (works out of the box!)
+
+### 💰 PAID API (Global fallback)
+
+#### 🌍 Electricity Maps (GLOBAL, PAID)
+- **Coverage**: Global (India, EU, UK, Australia, US, and more)
+- **Endpoint**: `https://api.electricitymaps.com/v3/carbon-intensity/forecast`
+- **Provides**: Carbon intensity forecasts and grid data for 200+ zones
+- **Get Key**: Paid API at https://www.electricitymaps.com/
+- **Auto-used for**: India, Australia, and regions not covered by free APIs
+- **Pricing**: Expensive - use only if free options don't cover your region
+
+### 📊 Mock Data (FREE - Always available!)
+- **Coverage**: Worldwide
+- **Generated**: Locally using realistic pricing patterns
+- **Auto-used**: When no API keys are configured or all APIs fail
+- **Perfect for**: Testing, demos, and development
 
 ## Points System
 
@@ -264,8 +319,17 @@ decharge-scout/
 
 ## Troubleshooting
 
-### "EIA_API_KEY not set"
-Get your free API key from https://www.eia.gov/opendata/register.php and add to `.env`
+### "EIA_API_KEY not configured" or "No energy data API keys configured"
+Choose an API based on your location:
+- **US users**: Get FREE EIA API key from https://www.eia.gov/opendata/register.php
+- **International users**: Get Electricity Maps API key from https://www.electricitymaps.com/
+- **Testing**: Press Enter to skip and use mock data
+
+Add your key to `.env`:
+```
+EIA_API_KEY=your_key_here                    # For US
+ELECTRICITY_MAPS_API_KEY=your_key_here       # For global
+```
 
 ### "Insufficient balance"
 Fund your devnet wallet:

package/dashboard/api/alpha.js

@@ -0,0 +1,167 @@
+/**
+ * Vercel API Endpoint - Alpha Contributions
+ *
+ * GET /api/alpha - Get verified alpha contributions
+ * POST /api/alpha - Submit new alpha contribution
+ */
+
+import { createClient } from '@supabase/supabase-js';
+
+export const config = {
+  runtime: 'edge',
+};
+
+export default async function handler(req) {
+  // CORS headers
+  const headers = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type',
+    'Content-Type': 'application/json',
+  };
+
+  // Handle OPTIONS request for CORS
+  if (req.method === 'OPTIONS') {
+    return new Response(null, { status: 200, headers });
+  }
+
+  // Initialize Supabase client
+  const supabase = createClient(
+    process.env.SUPABASE_URL,
+    process.env.SUPABASE_ANON_KEY
+  );
+
+  // GET - Retrieve alpha contributions
+  if (req.method === 'GET') {
+    try {
+      const url = new URL(req.url);
+      const location = url.searchParams.get('location');
+      const verified = url.searchParams.get('verified') === 'true';
+      const minConfidence = parseFloat(url.searchParams.get('min_confidence') || '0');
+
+      let query = supabase
+        .from('alpha_contributions')
+        .select('*')
+        .order('created_at', { ascending: false })
+        .limit(100);
+
+      // Apply filters
+      if (location) {
+        query = query.ilike('location', `%${location}%`);
+      }
+
+      if (verified) {
+        query = query.eq('verified', true);
+      }
+
+      if (minConfidence > 0) {
+        query = query.gte('confidence', minConfidence);
+      }
+
+      const { data, error } = await query;
+
+      if (error) throw error;
+
+      // Get statistics
+      const { data: stats } = await supabase
+        .from('alpha_by_location')
+        .select('*')
+        .order('verified_count', { ascending: false })
+        .limit(10);
+
+      return new Response(
+        JSON.stringify({
+          contributions: data || [],
+          statistics: stats || [],
+          total: data?.length || 0,
+          timestamp: new Date().toISOString(),
+        }),
+        { status: 200, headers }
+      );
+    } catch (error) {
+      console.error('Alpha GET error:', error);
+      return new Response(
+        JSON.stringify({
+          error: 'Failed to fetch alpha contributions',
+          message: error.message,
+        }),
+        { status: 500, headers }
+      );
+    }
+  }
+
+  // POST - Submit alpha contribution
+  if (req.method === 'POST') {
+    try {
+      const data = await req.json();
+
+      // Validate required fields
+      if (!data.agent_name || !data.location || !data.contribution) {
+        return new Response(
+          JSON.stringify({ error: 'Missing required fields' }),
+          { status: 400, headers }
+        );
+      }
+
+      const { contribution } = data;
+
+      // Validate contribution structure
+      if (
+        typeof contribution.startHour !== 'number' ||
+        typeof contribution.endHour !== 'number' ||
+        !contribution.type ||
+        contribution.startHour < 0 ||
+        contribution.startHour > 23 ||
+        contribution.endHour < 0 ||
+        contribution.endHour > 23
+      ) {
+        return new Response(
+          JSON.stringify({ error: 'Invalid contribution data' }),
+          { status: 400, headers }
+        );
+      }
+
+      // Insert alpha contribution
+      const { data: insertedData, error: insertError } = await supabase
+        .from('alpha_contributions')
+        .insert({
+          agent_name: data.agent_name,
+          location: data.location,
+          contribution_type: contribution.type,
+          start_hour: contribution.startHour,
+          end_hour: contribution.endHour,
+          verified: data.verified || false,
+          confidence: data.confidence || 0.5,
+          verification_reasons: data.verificationReasons || [],
+          timestamp: new Date(data.timestamp || Date.now()).toISOString(),
+        })
+        .select()
+        .single();
+
+      if (insertError) throw insertError;
+
+      return new Response(
+        JSON.stringify({
+          success: true,
+          message: 'Alpha contribution submitted successfully',
+          contribution: insertedData,
+        }),
+        { status: 200, headers }
+      );
+    } catch (error) {
+      console.error('Alpha POST error:', error);
+      return new Response(
+        JSON.stringify({
+          error: 'Failed to submit alpha contribution',
+          message: error.message,
+        }),
+        { status: 500, headers }
+      );
+    }
+  }
+
+  return new Response(
+    JSON.stringify({ error: 'Method not allowed' }),
+    { status: 405, headers }
+  );
+}

package/dashboard/api/submit.js

@@ -65,6 +65,29 @@ export default async function handler(req) {
 
     if (submissionError) throw submissionError;
 
+    // Handle alpha contribution if present
+    if (data.alpha_contribution) {
+      const alpha = data.alpha_contribution;
+      const { error: alphaError } = await supabase
+        .from('alpha_contributions')
+        .insert({
+          agent_name: data.agent_name,
+          location: data.location,
+          contribution_type: alpha.type,
+          start_hour: alpha.startHour,
+          end_hour: alpha.endHour,
+          verified: alpha.verified || false,
+          confidence: alpha.confidence || 0.5,
+          verification_reasons: alpha.verificationReasons || [],
+          timestamp: new Date(data.timestamp).toISOString(),
+        });
+
+      // Don't fail the entire request if alpha submission fails
+      if (alphaError) {
+        console.warn('Alpha contribution failed:', alphaError);
+      }
+    }
+
     // Update agent heartbeat (upsert)
     const { error: heartbeatError } = await supabase
       .from('agent_heartbeat')

package/dashboard/lib/migration-alpha-contributions.sql

@@ -0,0 +1,185 @@
+-- DeCharge Scout Dashboard - Alpha Contributions Migration
+-- Add this to your Supabase database to support verified local alpha contributions
+
+-- ============================================================================
+-- TABLE: alpha_contributions
+-- Stores verified local knowledge contributions from agents
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS alpha_contributions (
+  id SERIAL PRIMARY KEY,
+  agent_name VARCHAR(255) NOT NULL,
+  location VARCHAR(255) NOT NULL,
+  contribution_type VARCHAR(20) NOT NULL CHECK (contribution_type IN ('peak', 'cheap', 'general')),
+  start_hour INTEGER NOT NULL CHECK (start_hour >= 0 AND start_hour <= 23),
+  end_hour INTEGER NOT NULL CHECK (end_hour >= 0 AND end_hour <= 23),
+
+  -- Verification fields
+  verified BOOLEAN DEFAULT FALSE,
+  confidence DECIMAL(4, 3) CHECK (confidence >= 0 AND confidence <= 1),
+  verification_reasons TEXT[],
+
+  -- Metadata
+  timestamp TIMESTAMP NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW(),
+
+  -- Indexes for performance
+  CONSTRAINT valid_hour_range CHECK (start_hour <= end_hour)
+);
+
+-- Indexes for efficient querying
+CREATE INDEX idx_alpha_location ON alpha_contributions(location);
+CREATE INDEX idx_alpha_verified ON alpha_contributions(verified);
+CREATE INDEX idx_alpha_confidence ON alpha_contributions(confidence DESC);
+CREATE INDEX idx_alpha_created_at ON alpha_contributions(created_at DESC);
+CREATE INDEX idx_alpha_type ON alpha_contributions(contribution_type);
+
+-- ============================================================================
+-- VIEW: Verified Alpha Contributions (high confidence only)
+-- ============================================================================
+CREATE OR REPLACE VIEW verified_alpha_contributions AS
+SELECT
+  id,
+  agent_name,
+  location,
+  contribution_type,
+  start_hour,
+  end_hour,
+  confidence,
+  verification_reasons,
+  timestamp,
+  created_at
+FROM alpha_contributions
+WHERE verified = TRUE AND confidence >= 0.6
+ORDER BY confidence DESC, created_at DESC;
+
+-- ============================================================================
+-- VIEW: Alpha Contributions Summary by Location
+-- ============================================================================
+CREATE OR REPLACE VIEW alpha_by_location AS
+SELECT
+  location,
+  COUNT(*) as total_contributions,
+  COUNT(CASE WHEN verified = TRUE THEN 1 END) as verified_count,
+  AVG(confidence) as avg_confidence,
+  MAX(created_at) as latest_contribution
+FROM alpha_contributions
+WHERE created_at > NOW() - INTERVAL '30 days'
+GROUP BY location
+ORDER BY verified_count DESC, total_contributions DESC;
+
+-- ============================================================================
+-- VIEW: Peak Hours Analysis (most commonly reported)
+-- ============================================================================
+CREATE OR REPLACE VIEW peak_hours_analysis AS
+WITH hour_counts AS (
+  SELECT
+    location,
+    generate_series(start_hour, end_hour) as hour,
+    confidence,
+    contribution_type
+  FROM alpha_contributions
+  WHERE contribution_type = 'peak'
+    AND verified = TRUE
+    AND created_at > NOW() - INTERVAL '30 days'
+)
+SELECT
+  location,
+  hour,
+  COUNT(*) as report_count,
+  AVG(confidence) as avg_confidence,
+  COUNT(*) * AVG(confidence) as weighted_score
+FROM hour_counts
+GROUP BY location, hour
+HAVING COUNT(*) >= 2  -- At least 2 reports
+ORDER BY location, weighted_score DESC;
+
+-- ============================================================================
+-- FUNCTION: Get Alpha Insights for Location
+-- ============================================================================
+CREATE OR REPLACE FUNCTION get_alpha_insights(
+  p_location VARCHAR(255),
+  p_min_confidence DECIMAL DEFAULT 0.6
+)
+RETURNS TABLE (
+  contribution_type VARCHAR(20),
+  start_hour INTEGER,
+  end_hour INTEGER,
+  confidence DECIMAL(4, 3),
+  report_count BIGINT,
+  latest_report TIMESTAMP
+) AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    ac.contribution_type,
+    ac.start_hour,
+    ac.end_hour,
+    AVG(ac.confidence)::DECIMAL(4, 3) as confidence,
+    COUNT(*) as report_count,
+    MAX(ac.created_at) as latest_report
+  FROM alpha_contributions ac
+  WHERE ac.location ILIKE '%' || p_location || '%'
+    AND ac.verified = TRUE
+    AND ac.confidence >= p_min_confidence
+    AND ac.created_at > NOW() - INTERVAL '30 days'
+  GROUP BY ac.contribution_type, ac.start_hour, ac.end_hour
+  ORDER BY report_count DESC, confidence DESC
+  LIMIT 10;
+END;
+$$ LANGUAGE plpgsql;
+
+-- ============================================================================
+-- FUNCTION: Calculate Contribution Quality Score
+-- ============================================================================
+CREATE OR REPLACE FUNCTION calculate_contribution_quality(
+  p_agent_name VARCHAR(255)
+)
+RETURNS TABLE (
+  agent_name VARCHAR(255),
+  total_contributions BIGINT,
+  verified_contributions BIGINT,
+  avg_confidence DECIMAL(4, 3),
+  quality_score DECIMAL(6, 2)
+) AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    p_agent_name::VARCHAR(255),
+    COUNT(*)::BIGINT as total_contributions,
+    COUNT(CASE WHEN verified = TRUE THEN 1 END)::BIGINT as verified_contributions,
+    AVG(confidence)::DECIMAL(4, 3) as avg_confidence,
+    (
+      (COUNT(CASE WHEN verified = TRUE THEN 1 END)::DECIMAL / NULLIF(COUNT(*), 0)) * 100 +
+      (AVG(confidence) * 100)
+    )::DECIMAL(6, 2) as quality_score
+  FROM alpha_contributions
+  WHERE agent_name = p_agent_name;
+END;
+$$ LANGUAGE plpgsql;
+
+-- ============================================================================
+-- COMMENTS for documentation
+-- ============================================================================
+COMMENT ON TABLE alpha_contributions IS 'Stores verified local energy pricing knowledge from agents';
+COMMENT ON COLUMN alpha_contributions.verified IS 'TRUE if contribution matches actual pricing data';
+COMMENT ON COLUMN alpha_contributions.confidence IS 'Confidence score 0-1, higher means better match with actual data';
+COMMENT ON COLUMN alpha_contributions.verification_reasons IS 'Array of reasons explaining verification result';
+
+-- ============================================================================
+-- Sample queries for testing
+-- ============================================================================
+
+-- Get all verified contributions for a location
+-- SELECT * FROM verified_alpha_contributions WHERE location ILIKE '%mumbai%';
+
+-- Get alpha insights for a specific location
+-- SELECT * FROM get_alpha_insights('Mumbai', 0.7);
+
+-- Get contribution quality for an agent
+-- SELECT * FROM calculate_contribution_quality('Agent-X8DOAO');
+
+-- Get peak hours analysis
+-- SELECT * FROM peak_hours_analysis WHERE location ILIKE '%india%';
+
+-- Get alpha summary by location
+-- SELECT * FROM alpha_by_location ORDER BY verified_count DESC LIMIT 10;