Claims Engine forward compatibility — structured retirement metadata + CLAMS registry alignment

[glandua]

Context

The Regen Claims Engine ecosystem is converging around a shared schema vocabulary (ADR-004, regen-data-standards PR #53) that will be used by both the KOI semantic layer (off-chain intelligence) and the CLAMS CosmWasm contract (on-chain verification). This issue proposes a lightweight, phased integration path so that Regen Compute's planned Phase 3 CosmWasm contract aligns with that architecture — making retirements composable with other claims engine consumers (PACTO, ASHA, RI Pod, etc.).

This is NOT blocking current work. Everything here is Phase 2+ and designed to build on existing architecture.

Note: Regen Compute retirements already happen on Regen Ledger and are already indexed by KOI through normal ledger event indexing. This issue is about enriching that data and aligning future contract work, not about making retirements discoverable — they already are.

Proposed Integration Path

Phase A: Structured Retirement Reason (Low effort, nice-to-have)

The reason field in MsgRetire currently carries free text. When it makes sense, this could carry structured JSON that adds semantic context:

{
  "@context": "https://schema.regen.network/v1",
  "type": "ComputeFootprintRetirement",
  "footprintEstimate": {
    "value": 0.5,
    "unit": "kgCO2e",
    "methodology": "Luccioni2023+IEA2024",
    "uncertaintyRange": "10x"
  },
  "period": "2026-03",
  "tool": "regen-compute",
  "version": "0.4.0"
}

This is fully backward-compatible (still a valid reason string) and adds richer context for anyone querying retirements — linking each one to a specific footprint estimate, methodology, and tool version. Not urgent, but a clean pattern to adopt when convenient.

Files affected: src/services/retirement.ts, src/services/retire-subscriber.ts — the reason parameter in MsgRetire and MsgBuyDirect (auto-retire).

Phase B: Footprint Estimation as Claim Type (ADR-004 extension)

The estimate_session_footprint and estimate_monthly_footprint tools produce structured data (kWh, CO2 kg, methodology, uncertainty). This could be formalized as a claim type in the ADR-004 vocabulary:

# Addition to regen-data-standards ClaimType enum
COMPUTE_FOOTPRINT:
  description: "Estimated ecological footprint of AI compute usage"

# Claim attributes used:
# - impactType: COMPUTE_FOOTPRINT
# - quantity + unit: e.g., 0.5 kgCO2e
# - methodology: Luccioni2023+IEA2024
# - temporalScope: session or monthly period
# - verificationStatus: SELF_REPORTED (heuristic estimate)

This makes footprint estimates into proper claims — comparable across tools, attestable by energy researchers, aggregatable into network-level reports.

Depends on: PR #53 merge + claim type taxonomy stabilization. No rush.

Phase C: CLAMS Registry Alignment for Phase 3 CosmWasm Contract (The main event)

The Regen Compute ROADMAP already plans a Phase 3 CosmWasm contract for on-chain pool aggregation and REGEN burn. The CLAMS claims engine contract is emerging as a cross-chain registry pattern — recording WHERE claims/retirements are anchored rather than replicating Data Module logic.

This is the substantive integration point. When Phase 3 contract design begins, aligning with the CLAMS registry architecture would mean:

• Pool retirement batches registered as composite claims in CLAMS
• REGEN burn events registered as governance actions
• Cross-chain retirements (via ecoBridge) tracked with origin chain metadata
• EAS export for Ethereum-side discovery (subscriber impact attestations on Sepolia/mainnet)

Depends on: CLAMS contract architecture finalization (Marie + Giancarlo, in progress). The right time to align is when Christian starts Phase 3 design.

Phase D: Identity Bridge (Subscriber self-custody path)

Current architecture uses HD-derived addresses (m/44'/118'/0'/0/{subscriberId}) — operator holds all keys. The claims engine Identity Bridge (KOI #13, already implemented) supports wallet_address on entities with bech32 validation and 3-tier address fallback.

When/if Regen Compute moves toward subscriber self-custody, the identity bridge pattern is ready. Subscribers could link their own Regen addresses, making them the verified owners of their retirement history.

No action needed now — a note for Phase 3+ planning.

Relationship to Existing Issues

• Public impact dashboard — aggregate retirement stats and live counter #65 (Public impact dashboard) — Could surface claims-engine-sourced aggregate data alongside indexer data
• 402 Payment Required: crypto payment pathway for autonomous agents #99 (Crypto payment / cross-chain) — ecoBridge retirements are the strongest CLAMS registry integration candidate (cross-chain provenance tracking)

Who Needs to Talk (When the Time Comes)

Person	Role in this integration	When
Christian	Phase 3 CosmWasm contract design	When Phase 3 starts
Marie	CLAMS registry pattern alignment	When CLAMS architecture finalizes
Giancarlo	Contract implementation coordination	When both contracts are in design
Sam	EAS/Hypercerts export mapping	When Phase C is active
Gregory	Cross-project coordination	Ongoing

Next Steps

1. No immediate action needed — current regen-compute work is not affected
2. Phase A is a nice pattern to adopt whenever retirement.ts is being touched anyway
3. Phase C is the key milestone — when Phase 3 contract design starts, connect with Marie/Giancarlo on CLAMS alignment
4. Watch PR Add simple workflow example to documentation #53 — when ADR-004 schemas merge, Phase B becomes actionable

---

Filed by Gregory via claims engine architectural review. This is forward-looking and non-blocking. The goal is to make sure Regen Compute's Phase 3 contract work aligns with the broader claims engine ecosystem.