PoV Gate API & Conformance

Summary: The PoV Gate is the single on-chain entry point that admits or rejects real-world claims before any state change. A call succeeds only if (1) a governed attestor quorum verifies the same evidence, and (2) the One-Claim ledger confirms the evidence hasn’t been used elsewhere. Call the Gate in the same transaction that mints, settles, or grants access.

When to call the Gate

• Mint-Gate: before minting proofs or assets (ETT, Energy NFT, Carbon Credit NFT, EMT)

• Settle-Gate: before value moves (trades, retirements, milestone payout releases)

• Access-Gate: before granting gated capabilities (for example, API keys, roles)

Rule: no Gate pass → no action. Proof mints and conversions are gas-only on Base; settlement uses EDM.

Params payload

Struct passed to Gate:

struct Params {
  bytes32 batchId;
  bytes32 deviceId;
  uint64  startTs;
  uint64  endTs;
  uint128 quantityWh;
  bytes32 evidenceHash;
  bytes32 meterUID;          // EAS UID of MeterReadingBatch.v1
  bytes32[] verificationUIDs;// EAS UIDs of Verification.v1 (must include AUDITOR)
}

Derived in Gate:

• claimId = keccak256(abi.encodePacked(deviceId,startTs,endTs,quantityWh,evidenceHash))

• One-Claim reserve → checks → finalize (atomic in the same call)

Gate API surface

Solidity (interface excerpt):

interface IEAS {
  function isAttestationValid(bytes32 uid) external view returns (bool);
  function getAttestation(bytes32 uid) external view
    returns (address recipient, address attester, bytes memory data, uint64 time,
             uint64 expirationTime, bool revocable, bytes32 refUID);
}

interface IPoVAttestorRegistry {
  struct QuorumSpec { uint8 minTotal; bool auditorRequired; uint8 minDistinctRoles; }
  function quorum() external view returns (QuorumSpec memory);
  function roleOf(address attestor) external view returns (uint8 role, bool enabled);
}

interface IOneClaimLedger {
  function reserve(bytes32 claimId) external returns (bool);
  function finalize(bytes32 claimId) external;
}

Gate function and event:

event PoVPassed(bytes32 indexed claimId, bytes32 meterUID, bytes32[] verUIDs);

function assertVerified(Params calldata p) external;

Optional helper:

function precheck(Params calldata p) external view returns (bool ok, string memory reason);

Revert codes

• ALREADY_CLAIMED — One-Claim reservation failed (duplicate)

• METER_MISMATCH — meter attestation schema/fields don’t match Params

• EVIDENCE_HASH_MISMATCH — counted verifications don’t reference the same evidenceHash as the meter batch

• QUORUM_NOT_MET — fewer than minTotal or insufficient distinct roles

• AUDITOR_REQUIRED — no independent AUDITOR in the set where required

• ROLE_NOT_AUTHORIZED — attestor role disabled in Registry

• ATTESTATION_REVOKED_OR_EXPIRED — counted verification is revoked or past validUntil

Call pattern (by use case)

Mint-Gate (gas-only mints on Base):

1. Build canonical JSON; compute evidenceHash

2. Publish MeterReadingBatch.v1 and Verification.v1 attestations (include AUDITOR)

3. Call assertVerified(p)

4. On success, mint:

   • ETT: 1 per 10 kWh (non-transferable proof)

   • Energy NFT: when 100 ETT are present (or convert that evidence to Carbon NFTs where standards allow)

   • Carbon Credit NFT: 1 per verified tCO₂ (direct mint)

   • EMT: one per verified milestone

5. Emit domain event; store attestation links

Settle-Gate (EDM settlement on Base, anchored to L1):

1. Optionally re-run assertVerified if policy requires a fresh check

2. Compute fee via Fee contract

   • Energy/Carbon: 4% total (2% buyer + 2% seller), 50% burned

   • Commodity milestone tranche: 0.5% with caps (5k ≤ 1M, 12.5k 1–5M, 25k > 5M), 50% burned

3. Collect EDM, split burn/treasury on-chain; finalize transfer/payout

Access-Gate:

• Require assertVerified against the relevant Verification.v1 schema before granting roles/API keys

Conformance rules

• Same-tx requirement: call the Gate in the same transaction that mints, settles, or grants access

• Equality of evidence: counted verifications MUST reference the exact evidenceHash and batch/window of meterUID

• Quorum: at least minTotal, includes an AUDITOR, and meets minDistinctRoles

• Exclusivity: One-Claim reserve → checks → finalize is atomic; any revert rolls back the reservation

• Fail-safe: any mismatch, revocation, or role drift ⇒ revert; no partial state

• Economics: proof mints/conversions are gas-only on Base; settlement requires EDM with on-chain 50% burn; no auto-swap

Minimal wrapper examples

Energy mint wrapper (conceptual):

function mintEnergyProof(PoVGate.Params calldata p) external {
  gate.assertVerified(p);                // may revert with codes above
  ett.mintETT(msg.sender, _claimId(p));  // gas-only
}

Energy NFT from 100 ETT:

function mintEnergyNFT(bytes32[] calldata claimIds, PoVGate.Params calldata p) external {
  gate.assertVerified(p);                         // verifies scope; locks claimId(s)
  energyNFT.mintFromETT(msg.sender, claimIds);   // gas-only
}

Settlement (Energy/Carbon trade):

function settleEnergyTrade(address payer, uint256 tradeValueInEdm) external {
  // optional: gate.assertVerified(p) if policy requires fresh check
  feeRouter.settleEnergyCarbon(payer, tradeValueInEdm); // collects EDM, burns 50%, routes 50% to treasury
}

TypeScript helper (claimId)

import { solidityPackedKeccak256 } from "ethers";
export function claimId(deviceId: string, startTs: bigint, endTs: bigint, quantityWh: bigint, evidenceHash: string) {
  return solidityPackedKeccak256(["bytes32","uint64","uint64","uint128","bytes32"],
                                 [deviceId, startTs, endTs, quantityWh, evidenceHash]);
}

Testing checklist

• Happy path: meter + AUDITOR pass; assertVerified emits PoVPassed; One-Claim finalized; mint succeeds

• Double claim: repeat with identical Params → ALREADY_CLAIMED

• Hash mismatch: modify any field → EVIDENCE_HASH_MISMATCH

• Missing auditor: verifications without AUDITOR → AUDITOR_REQUIRED

• Role disabled: disable an attestor → ROLE_NOT_AUTHORIZED

• Revocation: revoke a counted verification post-mint → asset flagged via PoV Feed within SLA; rectification unflags

• TTL expiry: validUntil in the past → ATTESTATION_REVOKED_OR_EXPIRED or flag on next check