3. MRV Harmonization

Summary: MRV harmonization turns many registry and project formats into one clean, comparable schema. It normalizes fields, units, and time, binds everything to the same evidenceHash and claimId, and records the exact method_hash and inputs_hash so any reviewer can reproduce results.

What MRV harmonization does

It takes source data (meter exports, project reports, inspection PDFs, satellite summaries) and emits one standardized payload that PoV attestors can verify. The output always includes the canonical window fields device_id, start_ts, end_ts, quantity_wh (or carbon equivalents), the derived evidenceHash, and calculated values like baseline_wh and delta_wh under a frozen method_hash.

Canonical field taxonomy

Use these names across all MRV sources. Keep types and units identical so results are comparable.

Energy windows: device_id (bytes32), start_ts (uint64, UTC seconds), end_ts (uint64), quantity_wh (uint128), optional grid_node, method_hash, baseline_wh, delta_wh, inputs_hash.
Carbon periods: project_id, start_ts, end_ts, measured_tco2e (decimal string), baseline_tco2e, reduction_tco2e, method_hash, inputs_hash.
Shared integrity: batch_id, nonce, source_file_hash, and the computed evidenceHash for the canonical JSON.

Important: energy is always Wh in quantity_wh, not kWh; time is always UTC seconds.

Schema adapters

Each external format gets a small adapter that renames fields, converts units, fixes timezones, and rejects ambiguity. Adapters must be deterministic: the same input file yields the same canonical JSON bytes and the same evidenceHash.

Example mapping (conceptual):

source.energy_kwh        -> quantity_wh = round(energy_kwh * 1000)
source.period_start_iso  -> start_ts    = to_utc_seconds(iso)
source.period_end_iso    -> end_ts      = to_utc_seconds(iso)
source.meter_id_hex      -> device_id   = to_bytes32(hex)
source.file_sha256_hex   -> source_file_hash

After mapping, emit the canonical JSON (sorted, minified), then hash it to get evidenceHash.

Units, time, and decimals

Normalize all energy to Wh and all time to UTC. Reject any float fields in the canonical JSON; if decimals are unavoidable (for example, measured_tco2e), send them as decimal strings (not binary floats). Never accept locale formats (no comma decimals). If a source mixes units or zones, fix it in the adapter or fail fast with a clear reason.

Methods and baselines

Every calculation must reference a frozen method version. Include method_hash in Verification.v1, and record the results:

Energy flex: baseline_wh and delta_wh.
Carbon credits: baseline_tco2e and reduction_tco2e.

If the method uses external series (weather, matched days), pack a compact descriptor and hash it into inputs_hash so reviewers can fetch the exact inputs you used.

Binding to PoV

Once the adapter emits canonical JSON, compute evidenceHash = SHA-256(utf8(canonical_json)) and derive claimId with (device_id, start_ts, end_ts, quantity_wh, evidenceHash). PoV attestations must reference that exact evidenceHash, and the Gate enforces equality and One-Claim exclusivity.

Reporting outputs (so ESG is reproducible)

Harmonized records are rendered into consistent ESG outputs: energy generation by period, carbon reductions by method and vintage, retirements linked to the token that was retired. Because every record carries method_hash and inputs_hash, anyone can rerun the math from the same inputs and get the same numbers.

Reference mappers

TypeScript (unit/time normalization):

export function toWh(energy_kwh: number): number {
  if (!Number.isFinite(energy_kwh)) throw new Error("BAD_ENERGY");
  const wh = Math.round(energy_kwh * 1000);
  if (wh < 0) throw new Error("NEGATIVE_QUANTITY");
  return wh;
}

export function toUtcSeconds(iso: string): number {
  const t = Date.parse(iso);
  if (Number.isNaN(t)) throw new Error("BAD_TIME");
  return Math.floor(t / 1000);
}

Python (canonical dump):

import json, hashlib

def canonical_dump(obj: dict) -> str:
    return json.dumps(obj, separators=(',', ':'), ensure_ascii=False, sort_keys=True)

def evidence_hash(obj: dict) -> str:
    canon = canonical_dump(obj).encode('utf-8')
    return '0x' + hashlib.sha256(canon).hexdigest()

Edge cases and how to handle them

If a source omits a required field (for example, no end_ts), the adapter must either derive it from context (documented) or fail with a precise code. If a registry uses inconsistent units across files, fail fast; do not guess. If an upstream revokes or amends data, use the PoV revocation and rectification flow; never overwrite history.

Versioning and governance

Every adapter is versioned (.v1, .v2) and approved by governance. Changing field semantics or unit rules creates a new version. Explorers display which adapter version mapped a record and the linked method_hash.

Conformance

Use the canonical names and units, produce sorted and minified JSON, compute the exact evidenceHash, derive claimId from the fixed tuple, include method_hash and inputs_hash when calculations are involved, and reference the same evidenceHash in Verification.v1. If any part is ambiguous, stop and return a clear reason instead of guessing.

Bottom line: harmonize first, then verify. With one schema, stable units, and explicit method_hash and inputs_hash, MRV stops being a reconciliation exercise and becomes a clean, comparable record that PoV can enforce.

Last updated 2 months ago