Implement Faltric MVP: Blockchain, Frontend, Backend, and AI Service

[Copilot]

Greenfield implementation of the Faltric platform — a decentralized green energy marketplace combining P2P token trading on Ethereum Sepolia, geospatial grid visualization, and AI-driven generation recommendations.

Blockchain (/blockchain)

• EnergyToken.sol: ERC-20 (ENRG), 1 token = 1 kWh; minting gated by MINTER_ROLE via OpenZeppelin AccessControl
• TradeEngine.sol: Two-phase escrow — seller calls lockTrade() (transfers tokens in), buyer calls fundTrade() (sends ETH), then either party or owner triggers releaseTrade() / cancelTrade(); protected with ReentrancyGuard
• Hardhat config for localhost + Sepolia, deploy script, contract test suite

Frontend (/frontend)

• React + Vite + Tailwind SPA with protected routes
• AuthContext: JWT session + MetaMask wallet linking with localStorage persistence for auto-reconnect
• GridMap: Mapbox GL JS with color-coded installation markers (solar/wind/biogas), admin polygon draw tool, owner identities anonymized to wallet address prefix (0x71C…)
• Exchange: ENRG balance display, trade modal correctly calling lockTrade (no ETH) then fundTrade (ETH) as separate phases
• Connect: Socket.io real-time "Green Community" channel
• AdminDashboard: Approve/reject pending installations

Backend (/backend)

• Express + Socket.io; JWT auth with register, login, link-wallet endpoints
• MongoDB models: User, Installation (GeoJSON), MeterReading, ChatMessage
• Meter poller: 15-min setInterval, computes surplus T = max(0, G − C), mints ENRG via ethers.js

AI Service (/ai-service)

• FastAPI; POST /predict scores sources via S = Σ(Wᵢ × Vᵢ) with weather normalization + scikit-learn trend regression
• Generates PDF reports with reportlab; GET /reports/{uuid} validates UUID format and guards against path traversal via Path.resolve() boundary check

Infrastructure

• docker-compose.yml: all four services + MongoDB + Redis with health checks
• Dockerfiles per service; Nginx multi-stage build for frontend

Bug fixes applied during review

• Removed erroneous { value: ethAmountWei } from lockTrade call — seller does not send ETH at lock phase
• meterPoller config guard changed from tokenAddress === ethers.ZeroAddress (always false on env string) to a simple falsiness check
• AI score boost now applied before the min(100, …) cap so it can meaningfully influence ranking

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• binaries.soliditylang.org
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/Falitric/Falitric/blockchain/node_modules/.bin/hardhat test (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

As the Head of AI/ML and Blockchain R&D, I have formalized the technical and product specifications for Faltric. This document serves as the master blueprint for the engineering and design teams to begin the development of the MVP (Minimum Viable Product).

---

Product Requirements Document (PRD): Project Faltric

Version: 1.1

Status: Ready for Technical Implementation

Core Mission: To democratize green energy through decentralized finance, geospatial intelligence, and predictive AI.

---

1. Product Vision & Goals

Faltric aims to transform the traditional centralized energy grid into a community-driven ecosystem. By leveraging the Ethereum Sepolia Testnet, Faltric ensures transparent P2P transactions while using AI to optimize energy consumption and installation choices.

• Primary Goal: Enable seamless trading of renewable energy credits.
• Secondary Goal: Provide a visual, map-based transparency layer for urban energy distribution.
• Tertiary Goal: Use machine learning to lower the barrier to entry for renewable adoption.

---

2. User Personas

Persona	Access Level	Primary Interaction
Prosumer	User	Generates energy, sells excess credits, views AI reports.
Consumer	User	Buys green energy, participates in community chat.
Grid Admin	Admin (Electricity Dept)	Manages polygons, verifies meter APIs, monitors grid health.

---

3. Functional Requirements

3.1 Web3 & Blockchain Integration (Faltric Exchange)

• Wallet Connectivity: Implement a "Persistent Wallet" logic. Upon login via traditional credentials, the system checks for an active MetaMask session. If the user has signed in once, the wallet remains linked to the session.

• Smart Contracts: * EnergyToken (ERC-20): 1 Token = 1 kWh generated.

• TradeEngine: An escrow contract that holds ETH/Tokens during a P2P trade on Sepolia.

• Meter API Integration: Backend services will poll Smart Meter APIs every 15 minutes to sync real-world generation data with the on-chain "Minting" function.

3.2 Geospatial Mapping (Faltric GridMap)

• Public Map: A Leaflet/Mapbox integration showing a city-wide view.
• Visual Assets: Different icons/colors for Solar, Wind, and Biogas installations.
• Admin Polygon Tool: Admins can draw boundaries around specific properties to "verify" them as energy nodes.
• Privacy Layer: While the map is public, specific user names are anonymized to wallet addresses (e.g., 0x71C...) for security.

3.3 AI-Driven Analytics (Faltric Predict)

• Recommendation Engine: A regression model that processes:

• Input A: Historical generation data from the Smart Meter.

• Input B: Real-time Weather API (Solar irradiance, wind speed, precipitation).

• Output: A structured PDF/Dashboard report recommending the best resource (e.g., "Switch to Wind for Q4") and estimating potential earnings.

3.4 Community & Admin Features

• Faltric Connect: A WebSocket-powered (Socket.io) public chat system. It supports real-time messaging where all users are part of a single "Green Community" channel to discuss market trends.
• Admin Dashboard: A private UI for the Electricity Department to approve/reject new installations and monitor the "Polygon" layer.

---

4. Technical Stack

Component	Technology
Frontend	React.js, Tailwind CSS, Mapbox GL JS
Backend	Node.js (Express), Python (FastAPI for AI)
Blockchain	Solidity, Hardhat, Ethers.js, Sepolia Testnet
Database	MongoDB (User data/Chat logs), Redis (Real-time mapping)
AI/ML	Scikit-learn, OpenWeatherMap API

---

5. System Logic & Formulas

5.1 Energy Credit Calculation

The amount of tokens minted ($T$) is derived from the net generation ($G$) minus the local consumption ($C$):

$$T = \max(0, G - C)$$

5.2 Recommendation Logic

The AI score ($S$) for a specific renewable source is calculated as:

$$S = \sum (W_{i} \times V_{i})$$

Where $W$ is the weather weight (e.g., 0.8 for sun) and $V$ is the historical efficiency variable.

---

6. Success Metrics (KPIs)

• P2P Volume: Total kWh traded on the Sepolia network per month.
• Onboarding Speed: Time taken from Admin polygon creation to the first token minted.
• AI Accuracy: Variance between "Predicted Generation" and "Actual Meter Generation" (Target: < 10% error).

---

7. Roadmap: Phase 1 (Next 4 Weeks)

1. Week 1: Setup Sepolia Smart Contracts and MetaMask persistent login.
2. Week 2: Integrate Mapbox and build the Admin Polygon drawing tool.
3. Week 3: Connect Smart Meter Mock APIs and develop the AI Prediction model.
4. Week 4: Deploy Faltric Connect (Chat) and conduct end-to-end UAT.

---

Next Step:
To begin development, would you like me to generate the Solidity Smart Contract for the Faltric Exchange or the React Template for the Faltric GridMap ...

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.