Core Concepts
EnergyAS organizes energy data around four key concepts: Watchers, Projects, Attesters, and Attestations.
Watchers
A Watcher is an organization or operator that owns and manages energy projects on-chain. Any wallet can register as a watcher by calling registerWatcher(name) — no approval needed.
- Self-registration is fully permissionless
- The registering wallet becomes the watcher owner
- Owners can transfer ownership for key rotation or team changes
- Each watcher gets a unique sequential ID (uint64)
- Watchers are never deleted — they persist permanently
Projects
A Project represents an individual energy site — a solar farm, wind turbine, data center, or any facility that generates or consumes energy. Projects are registered under a watcher.
| Property | Description |
|---|---|
| watcherId | The watcher that owns this project |
| name | Human-readable label (e.g., "Solar Farm Alpha") |
| projectType | 0 = generator, 1 = consumer (immutable after registration) |
| registered | Can be deregistered to block new attestations; historical data preserved |
Warning: Project type is immutable. A generator cannot be changed to a consumer, or vice versa. This prevents misclassification of energy data.
Attesters
Attesters are wallets authorized to submit energy readings for specific projects. EnergyAS supports two levels of whitelisting:
Per-Project Attesters
Added via addAttester(projectId, wallet). The attester can only submit readings for that specific project. This is ideal for IoT devices — if one is compromised, it only affects a single project.
Watcher-Wide Attesters
Added via addWatcherAttester(watcherId, wallet). The attester can submit readings for any project under the watcher. Useful for manual backup operators or auditors.
An attester only needs one authorization — either per-project or watcher-wide. Both are checked during attestation validation.
Attestations
An attestation is a signed, on-chain energy reading submitted through EAS. Each attestation contains interval data (readings in Wh), the collection method, energy source type, and an optional metadata URI.
- Readings are in watt-hours (Wh) to avoid floating-point precision issues
- Each attestation covers a time period derived from fromTimestamp + readingCount * interval
- The same period cannot be attested twice for the same project (revoke first to correct)
- Attestations update running totals (accumulators) per project and per watcher
- Revocations decrement accumulators and clear period locks for re-attestation
Energy Accumulators
The registry maintains four running totals that update automatically with every attestation and revocation:
| Accumulator | Scope | Updated By |
|---|---|---|
| totalGeneratedWh | Per project | Generator attestations |
| totalConsumedWh | Per project | Consumer attestations |
| totalGeneratedWhByWatcher | Per watcher | Generator attestations across all projects |
| totalConsumedWhByWatcher | Per watcher | Consumer attestations across all projects |