From d9ea935f6c1f315f7397df9bbe710720102ad030 Mon Sep 17 00:00:00 2001 From: Gregory Landua Date: Fri, 6 Feb 2026 19:30:30 -0500 Subject: [PATCH] docs: Add semantic data and claims engine integration specifications Implements advanced claims engine features with semantic data approach: Key additions: - docs/integration/claims-engine-architecture.md - Ecological State Claim specification - Evidence hierarchy and validation pipeline - x/data module integration - Claims-to-credits flow - docs/integration/cosmwasm-work-packages.md - WP-CW-001: Attestation Bond Contract - WP-CW-002: Claims Registry Contract - WP-CW-003: Evidence Aggregator Contract - WP-CW-004: Reputation Registry Contract - WP-CW-005: Arbiter DAO Integration Anchored to regen-data-standards (LinkML schemas) Forward compatible with regen-econ-ontology References: - https://github.com/regen-network/regen-data-standards - https://github.com/glandua/regen-econ-ontology Co-Authored-By: Claude Opus 4.5 --- .../integration/claims-engine-architecture.md | 170 ++++++++++++++++++ docs/integration/cosmwasm-work-packages.md | 125 +++++++++++++ 2 files changed, 295 insertions(+) create mode 100644 docs/integration/claims-engine-architecture.md create mode 100644 docs/integration/cosmwasm-work-packages.md diff --git a/docs/integration/claims-engine-architecture.md b/docs/integration/claims-engine-architecture.md new file mode 100644 index 0000000..714da0d --- /dev/null +++ b/docs/integration/claims-engine-architecture.md @@ -0,0 +1,170 @@ +# Claims Engine Architecture + +## Overview + +The Claims Engine validates ecological data against predefined criteria, issues Ecological State Claims, and manages the full lifecycle from raw measurement to tradeable credit. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ CLAIMS ENGINE ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ DATA SOURCES CLAIMS ENGINE ON-CHAIN STATE │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Field │ │ Validation │ │ x/data │ │ +│ │ Measurements│──────────▶│ Pipeline │──────────▶│ Anchoring │ │ +│ │ │ │ │ │ │ │ +│ │ Remote │ │ Schema │ │ x/ecocredit │ │ +│ │ Sensing │──────────▶│ Conformance│──────────▶│ Issuance │ │ +│ │ │ │ │ │ │ │ +│ │ Lab │ │ Evidence │ │ Metadata │ │ +│ │ Results │──────────▶│ Linking │──────────▶│ Graph │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ +│ ┌─────────────┐ │ +│ │ Knowledge │ │ +│ │ Graph (KOI) │◀────── Semantic Indexing │ +│ │ │ │ +│ └─────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Core Concepts + +### 1. Ecological State Claim + +A verifiable assertion about ecological state at a specific time and place. + +```yaml +EcologicalStateClaim: + claim_id: "esc-2026-001" + claim_type: "soil_organic_carbon" + + subject: + project_id: "C06-4997" + location: + type: "Polygon" + coordinates: [[[...coordinates...]]] + temporal_bounds: + start: "2025-01-01" + end: "2025-12-31" + + assertion: + metric: "SOC_percentage" + value: 3.42 + unit: "percent" + depth_range: "0-30cm" + methodology: "regen:soil-carbon-v1.2.2" + + evidence: + - type: "lab_analysis" + iri: "regen:13toVfvfM5B7yuJqq8h3iVRHp3PKUJ4ABxHyvn4MeUMwwv1pWQGL295.rdf" + confidence: 0.95 + + - type: "remote_sensing" + iri: "regen:sentinel2_ndvi_2025_Q4.json" + confidence: 0.82 + + attestations: + - attestor: "regen1abc...xyz" + timestamp: "2026-01-15T10:30:00Z" + signature: "..." + + status: "verified" + on_chain_anchor: + iri: "regen:13toVfvfM5B7yuJqq8h3iVRHp3PKUJ4ABxHyvn4MeUMwwv1pWQGL295.rdf" + tx_hash: "ABC123..." + block_height: 12345678 +``` + +### 2. Evidence Hierarchy + +``` +Evidence Types (by strength): +├── Primary Evidence +│ ├── Lab Analysis Results (highest confidence) +│ ├── Certified Field Measurements +│ └── Peer-Reviewed Data +├── Supporting Evidence +│ ├── Remote Sensing Products +│ ├── Model Outputs +│ └── Historical Baselines +└── Contextual Evidence + ├── Practice Documentation + ├── Stakeholder Attestations + └── Third-Party Verifications +``` + +### 3. Claim Lifecycle + +``` +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Draft │───▶│ Submitted│───▶│ Validated│───▶│ Attested │───▶│ Anchored │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ + │ │ │ │ │ + │ Creator │ Automated │ Human or │ Cryptographic │ On-chain + │ prepares │ schema │ agent │ signatures │ immutable + │ claim │ validation │ verification │ collected │ record +``` + +--- + +## On-Chain Integration + +### x/data Module Usage + +The `x/data` module provides content-addressed storage with attestation capabilities: + +- **MsgAnchor**: Anchor data hash on-chain +- **MsgAttest**: Attest to data validity +- **ContentHash**: Raw or Graph content hashes + +### IRI Construction + +Regen IRIs follow the pattern: +``` +regen:. +``` + +Example: +``` +regen:13toVfvfM5B7yuJqq8h3iVRHp3PKUJ4ABxHyvn4MeUMwwv1pWQGL295.rdf +``` + +--- + +## Integration with regen-data-standards + +All claims must conform to schemas defined in [regen-data-standards](https://github.com/regen-network/regen-data-standards): + +- **LinkML** framework for semantic schema definition +- **JSON-LD** structured data for interoperability +- **SPARQL-queryable** ecological state claims + +--- + +## Forward Compatibility: regen-econ-ontology + +The Claims Engine is designed for forward compatibility with [regen-econ-ontology](https://github.com/glandua/regen-econ-ontology): + +| Current Schema | Economic Ontology | Purpose | +|----------------|-------------------|---------| +| `EcologicalStateClaim` | `eco:Claim` | Base claim type | +| `Evidence` | `eco:Attestation` | Proof of claim | +| `CreditBatch` | `eco:Asset` | Value unit | +| `SellOrder` | `eco:Offer` | Market primitive | + +--- + +## References + +- [regen-data-standards](https://github.com/regen-network/regen-data-standards) +- [x/data module documentation](https://docs.regen.network/modules/data) +- [Registry 2.0 Vision](https://www.youtube.com/watch?v=P2r0jrrybfI) + +--- + +*This document is part of the Regen Network Agentic Tokenomics framework.* diff --git a/docs/integration/cosmwasm-work-packages.md b/docs/integration/cosmwasm-work-packages.md new file mode 100644 index 0000000..c544c62 --- /dev/null +++ b/docs/integration/cosmwasm-work-packages.md @@ -0,0 +1,125 @@ +# CosmWasm Integration Work Packages + +## Overview + +This document specifies work packages for implementing Claims Engine functionality via CosmWasm smart contracts on Regen Ledger. + +--- + +## Work Package Summary + +| WP ID | Name | Priority | Dependencies | Estimated Effort | +|-------|------|----------|--------------|------------------| +| WP-CW-001 | Attestation Bond Contract | High | None | 4-6 weeks | +| WP-CW-002 | Claims Registry Contract | High | WP-CW-001 | 6-8 weeks | +| WP-CW-003 | Evidence Aggregator Contract | Medium | WP-CW-002 | 4-6 weeks | +| WP-CW-004 | Reputation Registry Contract | Medium | WP-CW-001 | 4-6 weeks | +| WP-CW-005 | Arbiter DAO Integration | Medium | WP-CW-002, WP-CW-004 | 6-8 weeks | + +--- + +## WP-CW-001: Attestation Bond Contract + +### Purpose +Enable economic skin-in-the-game for claim attestors through bonded attestations. + +### Key Functions +- `Attest`: Create a bonded attestation +- `IncreaseBond`: Increase bond on existing attestation +- `Challenge`: Challenge an attestation +- `ResolveChallenge`: Arbiter-only resolution +- `WithdrawBond`: Withdraw after unbonding period + +### Attestation Types +- `DataAccuracy`: Attesting data is accurate +- `MethodologyCompliance`: Attesting methodology was followed +- `FieldVerification`: Attesting on-site verification +- `FullClaim`: Attesting entire claim validity + +--- + +## WP-CW-002: Claims Registry Contract + +### Purpose +Central registry for ecological state claims with lifecycle management. + +### Key Functions +- `SubmitClaim`: Submit a new claim +- `UpdateClaimStatus`: Update claim status (authorized roles only) +- `LinkAttestation`: Link attestations to claim +- `RequestVerification`: Request claim verification +- `RequestCreditIssuance`: Convert verified claim to credit + +### Claim Status Flow +``` +Draft → Submitted → UnderReview → Validated → Attested → Verified + ↓ + Rejected +``` + +--- + +## WP-CW-004: Reputation Registry Contract + +### Purpose +Track and expose reputation scores for claim-related actors. + +### Reputation Dimensions +- Claims submitted/verified/rejected +- Attestations made/challenged/slashed +- Verifications performed and accuracy +- Composite reliability and expertise scores + +### Reputation Update Triggers +- Positive: claim_verified (+10), attestation_confirmed (+5), challenge_won (+15) +- Negative: claim_rejected (-15), attestation_slashed (-20), challenge_lost (-10) + +--- + +## WP-CW-005: Arbiter DAO Integration + +### Purpose +Connect claims dispute resolution to DAO DAO governance structures. + +### Arbiter Qualifications +- Reputation score > 0.75 +- Domain expertise (methodology-specific) +- Stake requirement met +- No conflict of interest + +--- + +## Implementation Timeline + +``` +2026 Q2 Q3 Q4 +├──────────────────────────┼──────────────────────┼──────────────────────┤ +│ WP-CW-001 │ │ │ +│ Attestation Bond │ │ │ +│ ████████████████ │ │ │ +│ │ │ │ +│ WP-CW-002 │ │ │ +│ Claims Registry │ │ │ +│ ████████████████████████████████ │ │ +│ │ │ │ +│ │ WP-CW-003/004 │ │ +│ │ Evidence/Reputation │ │ +│ │ ████████████████ │ │ +│ │ │ │ +│ │ │ WP-CW-005 │ +│ │ │ Arbiter DAO │ +│ │ │ ████████████████████ │ +└──────────────────────────┴──────────────────────┴──────────────────────┘ +``` + +--- + +## References + +- [CosmWasm Documentation](https://docs.cosmwasm.com/) +- [DAO DAO Contracts](https://github.com/DA0-DA0/dao-contracts) +- [Phase 3.1 Smart Contract Specs](../../phase-3/3.1-smart-contract-specs.md) + +--- + +*This document is part of the Regen Network Agentic Tokenomics framework.*