04 core objects data model

Overview

This document defines the core data entities and their relationships that form the foundation of the platform. These objects exist both on-chain (for immutability) and off-chain (for performance and rich data).

Core Entities

Project

Purpose: Represents a carbon project that can issue credits.

Attributes:

• id (string): Unique project identifier

• name (string): Project name

• type (enum): Project type (e.g., Renewable Energy, Reforestation, Carbon Capture)

• geography (string): Location/country

• methodology (string): Verification methodology standard

• vintageYear (integer): Year of credit generation

• verifierName (string): Name of verification body

• verifierRefId (string): Reference ID from verifier

• documents (array of URIs): Links to project documents

• status (enum): Project lifecycle status

Status Values:

• Draft: Project created but not submitted

• PendingPoAI: Submitted, awaiting PoAI review

• PendingDAO: PoAI approved, awaiting governance vote

• Approved: Fully approved, can issue credits

• Rejected: Failed verification or governance

• Suspended: Temporarily suspended (can be reactivated)

On-Chain Representation:

• Stored in ProjectRegistry contract

• Immutable metadata hash

• PoAI proof hash references

Off-Chain Representation:

• Full document storage

• Rich metadata

• Status tracking

---

ProjectRecord (Non-Fungible Project Record)

Purpose: Immutable on-chain anchor for each approved project.

Attributes:

• onChainTokenId (uint256): Unique NFT token ID

• projectId (string): Reference to Project entity

• metadataHash (bytes32): Hash of immutable project metadata

• maxIssuableUnits (uint256): Maximum credits that can be issued (in UNIT scale)

• poaiBundleHash (bytes32): Reference to PoAI proof bundle

• poaiAssetHash (bytes32): Asset integrity proof hash

• poaiDataHash (bytes32): Data integrity proof hash

• poaiProcessHash (bytes32): Process integrity proof hash

• createdAt (uint256): Timestamp of minting

• createdBy (address): Address that triggered minting

Key Properties:

• Non-Fungible: Each project gets exactly one record

• Immutable: Cannot be modified after minting

• Non-Tradable: Utility record, not a speculative asset

• 1:1 Relationship: One ProjectRecord per Project

Contract Standard: ERC-721 or ERC-1155 (supply = 1)

---

Credit Units (Semi-Fungible)

Purpose: Represents carbon credits that can be owned, transferred, and retired.

Attributes:

• projectTokenId (uint256): Reference to ProjectRecord tokenId

• projectId (string): Reference to Project entity

• balance (mapping): Balance per wallet/organization (in UNIT scale)

• totalIssued (uint256): Total units minted for this project

• totalRetired (uint256): Total units burned for this project

• cap (uint256): Maximum issuable units (from ProjectRecord)

Key Properties:

• Semi-Fungible: Fungible within project, non-fungible across projects

• Decimal Support: Uses fixed-point units (UNIT = 1e6 or 1e18)

• Project-Segregated: Credits from Project A ≠ Credits from Project B

• Transferable: Subject to project transfer policy

Contract Standard: ERC-1155 (multi-token)

Balance Storage:

balances.sol

mapping(address => mapping(uint256 => uint256)) balances;
// balances[user][projectTokenId] = amountUnits

---

PoAI Proof

Purpose: Verification proof bundle ensuring project integrity.

Attributes:

• poaiCaseId (string): Reference to PoAI review case

• projectId (string): Reference to Project entity

• bundleURI (string): Encrypted storage location of full proof bundle

• bundleHash (bytes32): SHA256 hash of canonical proof bundle JSON

• assetProofHash (bytes32): Asset integrity proof hash

• dataProofHash (bytes32): Data integrity proof hash

• processProofHash (bytes32): Process integrity proof hash

• reviewerSignature (bytes): Optional reviewer signature

• reviewerSignatureHash (bytes32): Hash of signature

• timestamp (uint256): When proof was generated

• validUntil (uint256): Optional expiration timestamp

On-Chain Storage:

• Only hashes stored on-chain (gas efficiency)

• Full bundle stored off-chain (encrypted)

Proof Bundle Structure:

{
  "projectId": "PJT-1029",
  "version": "1.0",
  "timestamp": "2026-01-14T10:00:00Z",
  "assetIntegrity": { "checks": [...] },
  "dataIntegrity": { "checks": [...] },
  "processIntegrity": { "reviewer": {...}, "workflow": [...] },
  "issuanceCap": { "maxTons": 10000 },
  "hashes": { ... }
}

---

Order / Purchase

Purpose: Records credit purchase transactions.

Attributes:

• orderId (string): Unique order identifier

• userOrOrgId (string): Buyer identifier

• projectId (string): Project being purchased

• units (uint256): Amount purchased (in UNIT scale)

• price (uint256): Price per unit (in payment token)

• totalPrice (uint256): Total payment amount

• paymentMethod (enum): Payment type (crypto, fiat, etc.)

• status (enum): Order status

• transactionHash (string): On-chain transaction hash (if applicable)

• createdAt (timestamp): Order creation time

• completedAt (timestamp): Order completion time

Status Values:

• Pending: Order created, payment pending

• Processing: Payment received, credits transferring

• Completed: Credits successfully transferred

• Failed: Order failed (refund if applicable)

• Cancelled: User cancelled order

---

Retirement

Purpose: Records permanent credit retirement (burn).

Attributes:

• retirementId (string): Unique retirement identifier

• projectId (string): Project whose credits were retired

• projectTokenId (uint256): On-chain project token ID

• unitsRetired (uint256): Amount retired (in UNIT scale)

• retiredBy (string): User or organization identifier

• retiredByAddress (address): Wallet address that executed retirement

• timestamp (uint256): On-chain block timestamp

• transactionHash (string): Retirement transaction hash

• certificateURI (string): Link to generated certificate

• certificateHash (bytes32): Hash of certificate content

• poaiBundleHash (bytes32): Reference to PoAI proof (for audit)

Key Properties:

• Irreversible: Credits are burned, cannot be undone

• Auditable: On-chain event + certificate

• Traceable: Links back to project and PoAI

On-Chain Event:

Retirement event (Solidity)

event CreditsRetired(
    uint256 indexed projectTokenId,
    address indexed from,
    uint256 amountUnits,
    uint256 timestamp
);

---

Governance Proposal

Purpose: Represents a governance vote on platform decisions.

Attributes:

• proposalId (string): Unique proposal identifier

• type (enum): Proposal type

• status (enum): Proposal status

• projectId (string): Related project (if applicable)

• parameters (object): Proposal-specific parameters

• createdBy (address): Proposer address

• createdAt (timestamp): Proposal creation time

• votingStart (timestamp): Voting window start

• votingEnd (timestamp): Voting window end

• votesFor (uint256): Votes in favor

• votesAgainst (uint256): Votes against

• executedAt (timestamp): Execution time (if passed)

• executionTxHash (string): On-chain execution transaction

Proposal Types:

• OnboardProject: Approve new project

• IssueUnits: Approve credit issuance

• SuspendProject: Suspend a project

• ParameterUpdate: Update platform parameters (fees, limits, thresholds)

Status Values:

• Open: Voting in progress

• Passed: Vote passed, awaiting execution

• Failed: Vote failed

• Executed: Successfully executed on-chain

• Cancelled: Proposal cancelled

---

Data Relationships

Entity Relationship Diagram (Conceptual)

Project (1) ──→ (1) ProjectRecord (NFT)
    │
    ├──→ (1) PoAI Proof
    │
    └──→ (many) Credit Units (Semi-Fungible)
            │
            ├──→ (many) Orders/Purchases
            │
            └──→ (many) Retirements
                    │
                    └──→ (1) Certificate

Governance Proposal ──→ (may affect) Project

Key Relationships

• Project → ProjectRecord: One-to-one (immutable anchor)

• ProjectRecord → Credit Units: One-to-many (one project can issue many credits)

• Credit Units → Orders: Many-to-many (credits can be purchased multiple times)

• Credit Units → Retirements: One-to-many (credits can be retired in batches)

• Project → PoAI Proof: One-to-one (one proof per project approval)

• Governance Proposal → Project: One-to-many (proposals can affect projects)

Database Schema (Off-Chain)

Core Tables

projects

- id (PK)
- name
- type
- geography
- methodology
- vintage_year
- verifier_name
- verifier_ref_id
- status
- created_at
- updated_at

project_records (on-chain sync)

- id (PK)
- project_id (FK)
- on_chain_token_id (unique)
- metadata_hash
- max_issuable_units
- poai_bundle_hash
- minted_at
- minted_by

credit_balances (on-chain sync)

- id (PK)
- project_token_id
- user_address
- balance_units
- last_updated_at

poai_proofs

- id (PK)
- project_id (FK)
- bundle_uri
- bundle_hash
- asset_proof_hash
- data_proof_hash
- process_proof_hash
- generated_at

retirements

- id (PK)
- project_id (FK)
- project_token_id
- units_retired
- retired_by
- transaction_hash
- certificate_uri
- retired_at