EnergyFi

Hardware-to-Blockchain Vertical Stack for EV Charging Infrastructure Tokenization

Try It Yourself

Mint 3 EV charging sessions on the current judge-facing Avalanche review network and verify them on the explorer:

cd contracts && npm install && npm run judge:testnet

The script processes 3 charging sessions through the full pipeline (SE signature → ChargeRouter → mint + revenue tracking), then prints explorer links for each transaction. Run it multiple times. Each run creates new sessions on the review network hardcoded in the script.

It prints the increase in KR11 region total pending revenue. The Home hero in the live MVP shows the demo investor's current pending share across holdings, so those numbers are expected to differ.

Requires Node.js 24.x only. No .env configuration needed — testnet credentials are embedded in the script.

Public MVP Verification

Live MVP: https://energyfi-mobile-demo.vercel.app
Short review checklist: docs/judge-quick-start.md
Contract deployment evidence: docs/contract-deployment-links.md

Current judge-facing review network:

Chain ID: 59823
RPC: https://subnets.avax.network/enf/testnet/rpc
Explorer: https://explorer-test.avax.network/enf

This network is defined in contracts/scripts/verify/judge-demo.ts and matches the repository's deployed contract surface.

What is EnergyFi?

A blockchain protocol that records EV charging infrastructure settlement data on-chain via a hardware-anchored trust chain (TPM 2.0 SE → STRIKON platform → Avalanche L1). Every charging session is cryptographically signed at the hardware level and immutably recorded per-session upon payment settlement.

How It Works — The Vertical Stack

EnergyFi is not just smart contracts. It is a 4-layer vertical stack where hardware, embedded systems, platform software, and blockchain work as a single pipeline.

flowchart TB
    subgraph L1["Layer 1 · Hardware"]
        SE["TPM 2.0 SE Chip<br/>Signs raw kWh data (P-256)"]
    end

    subgraph L2["Layer 2 · Embedded"]
        EMB["Embedded System<br/>Transmits SE-signed data"]
    end

    subgraph L3["Layer 3 · Platform"]
        STR["STRIKON Platform<br/>30+ Go microservices<br/>OCPP · Billing · Settlement"]
    end

    subgraph L4["Layer 4 · Blockchain"]
        EF["EnergyFi L1<br/>Avalanche Private Chain<br/>Essential + Derived Contracts"]
    end

    SE --> EMB --> STR -->|invoice.paid| EF

Layer 1 — Hardware: A TPM 2.0 Secure Element chip embedded in every charger signs raw metering data (kWh, timestamps) using P-256 (secp256r1) cryptography. This signature is created at the point of physical measurement — before the data ever leaves the device.

Layer 2 — Embedded: The proprietary embedded system transmits the SE-signed data packet to the platform. The hardware signature travels intact through this layer.

Layer 3 — Platform: STRIKON, a production EV charging platform with 30+ Go microservices, handles charger management (OCPP 1.6/2.1), billing, payment processing, and settlement. Only after a payment is fully settled does it emit an invoice.paid event.

Layer 4 — Blockchain: EnergyFi runs on a dedicated Avalanche L1 (Chain ID 59823) with zero-gas economics. The current deployment and judge review flow both run on this chain, defined in contracts/scripts/verify/judge-demo.ts.

Bookend Signature Model

How do we guarantee the data wasn't tampered with between the charger and the blockchain?

We don't need to trust every intermediate layer. Instead, we verify at both endpoints:

flowchart LR
    A["SE Chip<br/>(Layer 1)<br/>Signs raw data<br/>P-256"] --->|"Data travels through<br/>embedded + platform"| B["Bridge Wallet<br/>(Layer 3→4)<br/>Signs on-chain TX<br/>AWS KMS HSM"]

    B --> C{"DeviceRegistry<br/>compares SE signature<br/>vs on-chain data"}

    C -->|Match| D["✓ Path Integrity<br/>Proven"]
    C -->|Mismatch| E["✗ TX Reverted"]

The SE chip (origin) and Bridge wallet (destination) form a bookend. If the data at both ends matches, the entire intermediate path is proven intact — without requiring signatures at every hop.

Data Pipeline: Charging Session → On-Chain Record

When a charging session is paid, here is exactly what happens on-chain:

sequenceDiagram
    participant S as STRIKON Platform
    participant B as Bridge Wallet<br/>(AWS KMS)
    participant CR as ChargeRouter
    participant CT as ChargeTransaction<br/>(ERC-721)
    participant DR as DeviceRegistry
    participant SR as StationRegistry
    participant RT as RevenueTracker

    S->>B: invoice.paid event
    B->>CR: processCharge(session, period)

    rect rgb(240, 240, 245)
        Note over CR,RT: Atomic — both succeed or both revert
        CR->>CT: mint(session)
        CT->>DR: verifySignature(chargerId, hash, seSignature)
        DR-->>CT: ✓ valid SE signature
        CT->>SR: isRegistered(stationId)
        SR-->>CT: ✓ station exists
        CT-->>CT: _mint(address(this), tokenId)
        Note over CT: Soulbound ERC-721<br/>No transfers, permanent record

        CR->>RT: recordRevenue(stationId, krw, period)
        RT->>SR: getStation(stationId) → regionId
        RT-->>RT: accumulate revenue per station & region
    end

Atomicity: If the SE signature is invalid, the station is unregistered, or any check fails — the entire transaction reverts. No partial records ever exist on-chain.

Smart Contract Architecture

Every contract exists because a specific business requirement demanded it. Here is the mapping:

Business Requirement	Contract	Design Rationale
Prevent charger data tampering	`DeviceRegistry`	Pre-enrolls SE chip public keys (P-256, 64 bytes). Verifies hardware signature on every charging session
Map stations to investment regions	`StationRegistry`	Groups stations by 17 Korean administrative regions (ISO 3166-2:KR). Region = STO investment unit
Immutably record settled payments	`ChargeTransaction`	Soulbound ERC-721 — one token per session, no transfers, permanent record
Aggregate revenue per region	`RevenueTracker`	Accumulates distributable KRW per station and per region. Source data for STO investors
Single trusted entry point	`ChargeRouter`	Atomically executes mint + recordRevenue in one TX. `onlyBridge` access control
Issue per-region security tokens	`RegionSTO` + `RegionSTOFactory`	Current code includes an ERC-20-based prototype, but final token standard and issuance location remain policy-dependent
Station operational quality	`ReputationRegistry`	Oracle-published region metrics (trust, rhythm, site scores)

Current Demo Surface

The repository currently implements the contract surface below. For judge review, the live mutation path exercised by npm run judge:testnet directly touches ChargeRouter, ChargeTransaction, and RevenueTracker, and transitively depends on DeviceRegistry and StationRegistry. The full phased map is maintained in contracts/docs/implementation-roadmap.md.

Phase	Category	Contract	Token Standard	Status
1	Infrastructure	DeviceRegistry	—	Deployed
1	Infrastructure	StationRegistry	—	Deployed
2	Transaction	ChargeRouter	—	Deployed
2	Transaction	ChargeTransaction	ERC-721 (Soulbound)	Deployed
2	Revenue	RevenueTracker	—	Deployed
3	Investment	RegionSTO	ERC-20 prototype	Implemented in code (policy hold)
3	Investment	RegionSTOFactory	—	Deployed in repo-managed testnet artifacts
4	Operations	ReputationRegistry	—	Deployed in repo-managed testnet artifacts

Contract Dependency Graph

flowchart TD
    Bridge["Bridge Wallet<br/>(AWS KMS)"] --> CR["ChargeRouter"]
    CR --> CT["ChargeTransaction<br/>(ERC-721)"]
    CR --> RT["RevenueTracker"]
    CT --> DR["DeviceRegistry"]
    CT --> SR["StationRegistry"]
    RT --> SR
    RT -.->|revenue source| STO["RegionSTO<br/>(RegionSTOFactory)"]
    SR -.->|station data| REP["ReputationRegistry"]

Essential contracts (solid lines): DeviceRegistry, StationRegistry, ChargeTransaction, RevenueTracker, ChargeRouter — the core data pipeline. Without these, the system cannot operate.

Derived contracts (dashed lines): RegionSTO, RegionSTOFactory, and ReputationRegistry consume data produced by the essential contracts.

Key Design Decisions

Soulbound ERC-721: Charging sessions are immutable evidence, not tradeable assets. Minted to address(this), transfers disabled.
UUPS Proxy: All contracts are upgradeable via UUPS pattern for post-deployment bug fixes and regulatory adaptation.
BridgeGuarded base contract: The Bridge wallet (AWS KMS HSM) is the sole trusted entry point from STRIKON. onlyBridge modifier on all write operations.
Zero-gas L1: EnergyFi runs on a dedicated Avalanche L1 (Chain ID 59823) with zero-gas economics. Reviewers can run judge:testnet directly — testnet credentials are embedded in the script.

Investor Mobile App

Spec	Detail
Stack	React Native + Expo SDK 54, TypeScript
Routing	expo-router v6 (4 tabs)
i18n	Korean + English
Platforms	iOS, Android, Web

Tabs: Home (real-time impact data) · Explore (region reputation) · Portfolio (STO holdings) · Account (settings, KYC docs)

Testing

Test counts change over time, so this README does not freeze them. Use the contract test scripts below or CI as the current source of truth.

Key coverage areas:

DeviceRegistry P-256 / secp256k1 enrollment and signature verification
ChargeRouter atomicity across ChargeTransaction and RevenueTracker
Station/region mapping and revenue accumulation invariants
RegionSTO and ReputationRegistry demo surfaces

Local test entry points:

cd contracts && npm run test:unit — unit tests
cd contracts && npm run test:integration — integration tests
cd contracts && npm run test:all — unit + integration

Test titles for the local unit and integration suites are in English. Some auxiliary operational scripts may still contain Korean log text.

Why Avalanche?

Need	Avalanche Solution
Dedicated L1	Sovereign private chain per use case — isolated from public chain congestion
Zero gas	No transaction fees for on-chain data recording — critical for per-session writes
Absolute finality	BFT consensus — once confirmed, data is never reorganized or reverted
Managed infrastructure	AvaCloud — managed validators, monitoring, RPC endpoints without DevOps overhead

Quick Start

# Prerequisites: Node.js 24.x (nvm use 24)
git clone https://github.com/Seon-ung/EnergyFi.git
cd EnergyFi

# Smart Contracts
cd contracts
npm install
npm run compile
npm run test:unit            # unit tests
npm run test:integration     # integration tests
# or: npm run test:all       # full Hardhat-based local contract suite

# Investor Mobile App
cd ../mobile
npm install
npx expo start                                # iOS / Android / Web

Full setup guide: Environment Setup

For local compile and test runs, a deployment is not required. .env is mainly needed for networked scripts such as judge review, deployment, and seeded testnet flows.

Starting mobile/ locally does not reproduce the public review environment by itself. The committed app uses repo-local defaults from mobile/constants/contracts.ts unless you provide a mobile/.env for a specific network.

Project Structure

EnergyFi/
├── contracts/                  # Avalanche L1 smart contracts (Solidity, Hardhat 3)
│   ├── contracts/
│   │   ├── infra/              #   DeviceRegistry, StationRegistry
│   │   ├── core/               #   ChargeTransaction, ChargeRouter
│   │   ├── finance/            #   RevenueTracker
│   │   ├── sto/                #   RegionSTO, RegionSTOFactory
│   │   ├── ops/                #   ReputationRegistry
│   │   ├── base/               #   BridgeGuarded (shared access control)
│   │   └── interfaces/         #   All contract interfaces
│   ├── test/
│   │   ├── unit/               #   Contract unit tests
│   │   └── integration/        #   Cross-contract integration tests
│   ├── scripts/                #   Deploy, seed, and public verification scripts
│   └── tools/
│       ├── live/               #   Shared live-network verification engine
│       └── dashboard/          #   Express web dashboard on top of live tooling
├── mobile/                     # React Native + Expo SDK 54 (TypeScript)
│   ├── app/                    #   expo-router screens
│   ├── components/             #   UI building blocks
│   └── hooks/                  #   Data/view hooks
└── docs/                       # Architecture & specification documents

Documentation

Current Canonical Docs

Document	Description
Root Docs Map	Root-level document graph and authority map
Contracts Docs Map	Contract-doc graph, categories, and reading order
Implementation Roadmap	Primary contract planning reference for phases, dependencies, and risks
STRIKON Interface Spec	Off-chain interface boundary from charger flow to `invoice.paid`
Phase 1 Spec	Current canonical spec for `DeviceRegistry` and `StationRegistry`
Phase 2 Spec	Current canonical spec for `ChargeRouter`, `ChargeTransaction`, and `RevenueTracker`
Phase 3 Spec	`RegionSTO` and `RegionSTOFactory` prototype spec, issuance path comparison, and Revenue Attestation design. Code is implemented; final token standard and issuance ledger are policy-dependent.
Phase 4 Spec	Current canonical spec for region-level `ReputationRegistry` snapshots
Environment Setup	Full development environment and target-L1 reference setup

Top-Level Scope Docs

Document	Description
Architecture	Top-level architecture narrative and implementation/planning boundary map
Project Overview	Repository scope, deployment units, and current surface summary

Planning / Future-Phase Docs

Document	Description
Phase 5 Spec	Planned carbon pipeline design for future implementation

Name		Name	Last commit message	Last commit date
.agents/skills/vercel-react-native-skills		.agents/skills/vercel-react-native-skills
.github/workflows		.github/workflows
contracts		contracts
docs		docs
mobile		mobile
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md

Navigation Menu

Repository files navigation

EnergyFi

Hardware-to-Blockchain Vertical Stack for EV Charging Infrastructure Tokenization

Try It Yourself

Public MVP Verification

What is EnergyFi?

How It Works — The Vertical Stack

Bookend Signature Model

Data Pipeline: Charging Session → On-Chain Record

Atomicity: If the SE signature is invalid, the station is unregistered, or any check fails — the entire transaction reverts. No partial records ever exist on-chain.

Smart Contract Architecture

Current Demo Surface

Contract Dependency Graph

Key Design Decisions

Investor Mobile App

Testing

Why Avalanche?

Quick Start

Project Structure

Documentation

Current Canonical Docs

Top-Level Scope Docs

Planning / Future-Phase Docs

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

EnergyFi

Hardware-to-Blockchain Vertical Stack for EV Charging Infrastructure Tokenization

Try It Yourself

Public MVP Verification

What is EnergyFi?

How It Works — The Vertical Stack

Bookend Signature Model

Data Pipeline: Charging Session → On-Chain Record

Atomicity: If the SE signature is invalid, the station is unregistered, or any check fails — the entire transaction reverts. No partial records ever exist on-chain.

Smart Contract Architecture

Current Demo Surface

Contract Dependency Graph

Key Design Decisions

Investor Mobile App

Testing

Why Avalanche?

Quick Start

Project Structure

Documentation

Current Canonical Docs

Top-Level Scope Docs

Planning / Future-Phase Docs

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages