Core Concepts
EnergyAS organizes energy data around four building blocks: Organizations (Watchers), Projects, Authorized Submitters (Attesters), and Energy Records (Attestations).
Organizations (Watchers)
An Organization — called a Watcher in the protocol — is the top-level entity that owns and manages energy projects. Any wallet can register an organization by calling registerWatcher(name) — no approval needed, no fees beyond the transaction cost.
- Self-registration is fully open — anyone can create an organization
- The wallet that registers becomes the owner
- Owners can transfer ownership for key rotation or team changes
- Each organization gets a unique sequential ID (
uint64) - Organizations are never deleted — they persist permanently
Projects
A Project represents a single energy site — a solar farm, a wind turbine, a data center, or any facility that generates or consumes energy. Projects are registered under an organization.
| Property | Description |
|---|---|
watcherId | The organization that owns this project |
name | Human-readable label (e.g., "Solar Farm Alpha") |
energyType | Energy source: 0 = consumer, 1–13 = generation type |
registered | Can be deregistered to block new submissions; historical data is preserved |
Warning: Energy type is permanent. A generator cannot be changed to a consumer, or vice versa. This prevents misclassification of historical records.
Authorized Submitters (Attesters)
Attesters are wallets authorized to submit energy readings. There are two levels of authorization, and a wallet only needs one to be allowed to submit:
Per-project authorization
Added via addAttester(projectId, wallet). The wallet can only submit readings for that specific project. This is the recommended setup for IoT devices — if one device is compromised, only its single project is affected.
Organization-wide authorization
Added via addWatcherAttester(watcherId, wallet). The wallet can submit readings for any project under the organization. Useful for manual backup operators or human auditors.
Energy Records (Attestations)
An energy record — called an Attestation in the protocol — is a signed, on-chain submission of energy data sent through EAS. Each record contains interval readings in watt-hours (Wh), a collection method label, an energy type, and an optional metadata URI for supporting documents.
- Readings are stored in watt-hours (Wh) to avoid floating-point precision issues
- Each record covers a time period defined by
fromTimestamp,readingIntervalMinutes, and the number of readings - The same period cannot be submitted twice for the same project
- Corrections use replacement records (via
refUID) — direct revocations are blocked to preserve the audit trail - Each submission automatically updates running totals (accumulators) per project and per organization
- Corrections adjust accumulators by the delta between old and new values
Energy Accumulators
The registry maintains four running totals that update automatically with every submission and correction:
| Accumulator | Scope | Updated by |
|---|---|---|
totalGeneratedWh | Per project | Generator submissions |
totalConsumedWh | Per project | Consumer submissions |
totalGeneratedWhByWatcher | Per organization | Generator submissions across all projects |
totalConsumedWhByWatcher | Per organization | Consumer submissions across all projects |