docs: Add semantic data and claims engine integration specifications #3
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` | ||
|
Comment on lines
+104
to
+111
Contributor
There was a problem hiding this comment. The claim lifecycle depicted here (
To improve clarity and consistency, it's recommended to unify the claim lifecycle across all related documents. Consider updating this diagram to reflect the more comprehensive status flow.
Contributor
Author
There was a problem hiding this comment. @S4mmyb Could you have a look at this? I want to make sure we are clearly anchoring the work here in a way that is grounded in the technical approach you and @regen-network/jean-cosmos as well. side note, I am working on upping my game with ai assistance to contribute and manage processes here on github, so apologies if some way I am engaging is outside of norms. Feel free to let me know if I can improve something. |
||
|
|
||
| --- | ||
|
|
||
| ## 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:<base58_encoded_hash>.<format> | ||
| ``` | ||
|
|
||
| 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.* | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
|
Contributor
There was a problem hiding this comment. The document is missing the specification for |
||
| ## 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) | ||
|
Comment on lines
+74
to
+75
Contributor
There was a problem hiding this comment. The reputation score adjustments are hardcoded as magic numbers (e.g., Consider defining these values in a separate configuration section or table, for example: ### Reputation Parameters
| Trigger | Score Change |
|---|---|
| `claim_verified` | +10 |
| `attestation_confirmed` | +5 |
| `challenge_won` | +15 |
| `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.* | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The IRI for the
on_chain_anchoris identical to the IRI for thelab_analysisevidence (line 64). This can be confusing as it suggests the anchor for the entire claim is the same as the anchor for just one piece of its evidence. For clarity, consider using a distinct IRI for the claim's on-chain anchor to represent the claim object itself, or add a note explaining why they are identical if this is the intended design.