VeriJoule

Live demo: verijoule.wilderform.tools

A technical demo of tokenizing renewable energy using Chainlink Runtime Environment (CRE) and public grid data.

YouTube walkthrough of the demo — watch here.

VeriJoule mints tokens representing monthly net generation (MWh) at Colorado solar & wind farms. On request, a Chainlink CRE workflow fetches EIA (U.S. Energy Information Administration) plant-month generation data, reaches consensus, and writes it onchain. Settlement retires tokens when a buyer pays USDC to a facility wallet.

These tokens are not legally recognized RECs and are not for compliance use. Facilities in this project are for demonstration only. Settlement runs on testnet and no real value is transacted. See Limitations & Scope.

---

What this repo contains

Everything needed to run the pipeline lives in one repository — smart contracts, CRE workflow, web app, and indexer.

Component	Path	Purpose
Smart contracts	contracts/	CRE entry point, token registry (ERC-1155), USDC settlement; Foundry deploy and tests
CRE workflow	cre/verijoule-workflow/	HTTP-triggered EIA fetch, consensus, onchain write
CRE signer	cre/cre-signer/	HTTP microservice that triggers CRE mints
Web app	apps/web/	Next.js map UI, onchain ledger, USDC retirement
Indexer	apps/indexer/	Ponder indexer for onchain events
Documentation	docs/	Scope, limitations, deployed addresses

Directory map for agents and contributors: AGENTS.md.

---

How the pieces connect

Minting runs through CRE and smart contracts; the web app reads indexed onchain state and handles settlement separately.

flowchart LR
  EIA[EIA Form 923 API] --> CRE[cre/verijoule-workflow]
  EIA --> Web[apps/web]
  Signer[cre/cre-signer] -->|HTTP trigger| CRE
  CRE -->|Keystone onReport| Receiver[VeriJouleReceiver]
  Receiver -->|mintRECs| REC[VeriJouleREC]
  REC -->|events| Indexer[apps/indexer]
  Indexer -->|GraphQL| Web
  User[curl / client] --> Signer
  Web -->|settlement| Settlement[VeriJouleSettlement]
  Settlement -->|retire| REC

Loading

1. CRE signer triggers verijoule-workflow — one plant-month per execution. External callers hit the signer with { plantCode, period }; the workflow fetches that month's EIA generation, runs consensus, and delivers a report via the Keystone forwarder to VeriJouleReceiver.onReport, which calls VeriJouleREC.mintRECs.
2. Web app maps Colorado facilities with EIA generation data, reads onchain ledger and retirements from the indexer GraphQL API, and retires tokens via VeriJouleSettlement on Sepolia.
3. Indexer listens for REC and Settlement events and exposes a GraphQL API to the web app.

Each mint stores a SHA-256 of the attested EIA row so the offchain source is independently verifiable.

Key contracts:

• VeriJouleReceiver: CRE Keystone IReceiver — forwarder + workflow gate, then mint
• VeriJouleREC: plant registry, plant-month vintages, non-transferable vault, onchain metadata
• VeriJouleSettlement: USDC purchase + token retirement routed by plant code

Demo deployment (Sepolia proxies): docs/deployed-contracts.md.

---

Limitations

See Limitations & Scope for full project scope.

---

Tech stack

Full-stack web3: smart contracts, Chainlink CRE oracle layer, indexed onchain data, and a Next.js frontend.

Layer	Technology
Smart contracts	Solidity 0.8.34, Foundry (unit, invariant, fuzz), OpenZeppelin UUPS upgradeable (ERC-1155)
Oracle	Chainlink CRE (Go), HTTP signer microservice (JWT-signed requests to the CRE gateway)
Web	Next.js 16, React 19, TypeScript, wagmi/viem, Privy, MapLibre GL, Tailwind CSS 4
Indexer	Ponder 0.17, TypeScript, viem, Hono, GraphQL
Monorepo	pnpm workspaces, Turborepo, Node 22

---

CI

GitHub Actions run path-filtered checks on push/PR: Forge (build, unit, invariant, and fuzz tests), Slither and Aderyn static analysis, solhint, plus Go tests for CRE and lint/build for web and indexer.

---

Local setup

git submodule update --init --recursive
pnpm install
pnpm dev:web

Full env templates, Foundry/CRE commands, and platform deploy recipes: docs/operations.md and AGENTS.md.

---

Documentation

Doc	Contents
docs/limitations-and-scope.md	Canonical scope language
docs/deployed-contracts.md	Sepolia proxy addresses
docs/operations.md	Clone, env, deploy, Render/Vercel recipes
contracts/README.md	Onchain design (Receiver, REC, Settlement)
cre/README.md	CRE hub (workflow + signer)
apps/web/README.md · DATA.md	Map UI and EIA data pipeline
apps/indexer/README.md	Indexed events and GraphQL
AGENTS.md	Agent / contributor command map

---

Licensing

MIT. See LICENSE.