☀️ SolarChain

SolarChain is an open-source research prototype for urban distributed-energy verification and market coordination. It connects a physics-bounded solar simulator, embodied PV agents, a planner-facing map and review console, MetaMask, and a local EVM contract suite into one inspectable workflow.

The machine calculates a defensible generation boundary. The planner decides whether a candidate distributed energy resource (DER) should proceed. Approved records are signed by a wallet and registered on-chain; rejected or anomalous records remain visible in the audit trail.

The system closes the loop between physical modeling, adaptive verification, human judgment, and market settlement.

flowchart TB
 subgraph INPUTS["1. Urban energy inputs"]
 WEATHER["Open-Meteo weather"]
 DER["PV node profiles"]
 DEMAND["Factory demand"]
 end
 subgraph INTELLIGENCE["2. Physics and agent layer"]
 MODEL["pvlib + SolarPVModel<br/>Physical P_max boundary"]
 AGENTS["SolarAgents coordination<br/>trust, memory, verification"]
 AUDIT["Hash-linked events<br/>audit and state traces"]
 end
 subgraph EXPERIENCE["3. Human decision layer"]
 API["FastAPI simulator"]
 UI["React + Leaflet<br/>Planner Console"]
 REVIEW{"Planner review"}
 end
 subgraph SETTLEMENT["4. Verifiable settlement"]
 WALLET["MetaMask signature"]
 REGISTRY["SolarPanels + Factory"]
 MARKET["EnergyExchange + PowerReward<br/>SOLR + Shop"]
 end
 WEATHER --> MODEL
 DER --> MODEL
 MODEL --> AGENTS
 DEMAND --> AGENTS
 AGENTS --> API
 AGENTS --> AUDIT
 API --> UI
 UI --> REVIEW
 REVIEW -->|Reject| AUDIT
 REVIEW -->|Approve| WALLET
 WALLET --> REGISTRY
 REGISTRY --> MARKET
 AGENTS -->|Verified market step| MARKET
 MARKET --> UI

1. Observe: weather and node metadata drive a bounded PV generation model.
2. Verify: agent policies compare P_reported_W with the physical boundary and update trust, calibration, and verification state.
3. Review: the planner inspects the candidate queue, map context, residuals, and FDIA status.
4. Sign: an approved candidate is signed through MetaMask and registered as an on-chain solar panel.
5. Settle: verified supply enters the configurable reward/liquidity market, where factories purchase energy and rewards accrue.
6. Audit: event, decision, market, and state records form reproducible, hash-linked traces.

The bundled benchmark is a reproducible, weather-driven simulation over Beijing, Chengdu, Hangzhou, Shanghai, and Shenzhen. It uses city-level Open-Meteo observations, pvlib solar modeling, synthetic PV node profiles, scripted false-data injection, and controlled market construction.

Release record Evaluation map Dataset provenance

• Node.js 18+ and npm
• Python 3.9+
• Git
• MetaMask for wallet-signed interactions

git clone https://github.com/sunshineluyao/SolarSave.git
cd SolarSave

cd smart_contract
npm install
npx hardhat node

Keep the Hardhat node running. In a second terminal, deploy the contracts:

cd smart_contract
npx hardhat run scripts/deployAll.js --network localhost

The deployment script authorizes the contract relationships, funds local test accounts, and synchronizes contract addresses with the frontend and simulator.

cd Simulator
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m uvicorn main:app --reload

The API is available at http://127.0.0.1:8000; interactive API documentation is available at http://127.0.0.1:8000/docs.

cd client
npm install
npm run dev

Open http://127.0.0.1:3000 and connect MetaMask to:

The camera-ready artifact centers on the April 2026 controlled benchmark and the EIoT evaluation suite.

Run from the repository root after installing the simulator dependencies:

python Simulator/data/generate_monthly_datasets.py
python Simulator/experiments/run_all_eiot_experiments.py
python Simulator/data/visualizations.py

python -m pytest tests

cd smart_contract
npm test

cd client
npm run build

The default market allocation is 20% producer reward / 80% liquidity, represented on-chain as rewardRatioBps = 2000.

This repository is the final artifact release for:

SolarChain: A Physics-Grounded Embodied IoT System for Verifiable Urban Solar Market Design
UbiComp Companion '26, Shanghai, China

See the camera-ready release record for the paper checksum and the evaluation artifact map for reproducibility links.

Contributions are welcome:

1. Fork the repository.
2. Create a focused branch.
3. Add or update tests for behavioral changes.
4. Open a pull request describing the motivation, implementation, and evidence.

For questions or proposals, open a GitHub issue.

SolarChain is released under the MIT License.