06 poai system

What is PoAI?

PoAI (Proof of Asset Integrity) is the platform's verification pipeline that ensures:

• Asset Integrity: The real-world project exists and is legitimate

• Data Integrity: The documents and metrics are consistent and verifiable

• Process Integrity: The approval workflow is authentic (reviewers, signatures, governance)

PoAI produces a proof bundle and immutable hashes that get anchored on-chain.

Key Design Rule

No ProjectRecord minting and no credit issuance should be allowed unless PoAI is "Approved" and the PoAI proof hashes are attached.

PoAI Module Boundaries

Off-Chain Components (PoAI Service)

• Document ingestion

• Validation checks + reviewer workflow

• Proof bundle creation (structured JSON)

• Hashing and signing

• Storage of proof bundle (encrypted file storage / IPFS / S3)

• API endpoints for status, approvals, audits

On-Chain Components

• Storing minimal, immutable proof anchors:

  • poaiBundleHash

  • assetProofHash

  • dataProofHash

  • processProofHash

  • reviewerSignatureHash (optional)

• Enforcing gating checks:

  • ProjectRecord can only be minted if PoAI Approved

  • Credit issuance only if ProjectRecord exists + PoAI hash attached

PoAI State Machine

A single project moves through these PoAI states:

DRAFT
  ↓ (submit)
SUBMITTED
  ↓ (assign reviewer)
IN_REVIEW
  ↓ (approve / request changes)
APPROVED / CHANGES_REQUIRED
  ↓ (if approved, governance)
PENDING_DAO
  ↓ (if rejected)
REJECTED

State Definitions

• DRAFT: Project created, docs not submitted

• SUBMITTED: Docs submitted, awaiting review

• IN_REVIEW: PoAI reviewer assigned & checks running

• CHANGES_REQUIRED: Missing info/clarifications needed

• APPROVED: PoAI passed (proof hashes generated)

• REJECTED: Failed due to fraud/inconsistency/unverifiable data

• EXPIRED: PoAI validity window expired; needs re-validation

Important: State transitions must be auditable (log every action, actor, timestamp).

PoAI Data Model (DB Schema)

Tables

projects

- id (PK)
- name
- type
- location
- vintage_year
- methodology
- verifier_name
- verifier_ref_id
- status (Draft/PendingPoAI/PendingDAO/Approved/Rejected/Suspended)
- created_at
- updated_at

project_documents

- id (PK)
- project_id (FK)
- doc_type (enum: KYC, OWNERSHIP, VERIFIER_REPORT, MRV, IMPACT_REPORT, GPS, PHOTOS, CERTIFICATE, etc.)
- uri
- hash
- uploaded_by
- uploaded_at

poai_cases

- id (PK)
- project_id (FK)
- state (enum)
- assigned_reviewer_id
- submitted_at
- review_started_at
- resolved_at
- valid_until (for re-validation policy)

poai_checks

- id (PK)
- poai_case_id (FK)
- category (enum: ASSET, DATA, PROCESS)
- check_name (e.g., "Verifier Report Match")
- status (enum: PASS/FAIL/WARN/PENDING)
- notes
- evidence_uri
- created_at

poai_proofs

- id (PK)
- poai_case_id (FK)
- bundle_uri (where full proof bundle JSON is stored)
- bundle_hash (sha256 of canonical JSON)
- asset_proof_hash
- data_proof_hash
- process_proof_hash
- reviewer_signature (optional raw signature)
- reviewer_signature_hash
- generated_at

audit_logs

- id (PK)
- actor_id
- actor_role
- action
- entity_type
- entity_id
- before (JSON)
- after (JSON)
- timestamp

PoAI Proof Bundle (Canonical JSON)

This is what PoAI generates and stores (as JSON) after approval.

Example Structure

{
  "projectId": "PJT-1029",
  "version": "1.0",
  "timestamp": "2026-01-14T10:00:00Z",
  "assetIntegrity": {
    "checks": [
      {
        "name": "Project Ownership Verified",
        "status": "PASS",
        "evidence": "uri://documents/ownership-cert.pdf",
        "verifiedBy": "REV-01",
        "verifiedAt": "2026-01-14T09:30:00Z"
      },
      {
        "name": "Geo Coordinates Verified",
        "status": "PASS",
        "evidence": "uri://documents/gps-coordinates.json",
        "verifiedBy": "REV-01",
        "verifiedAt": "2026-01-14T09:35:00Z"
      }
    ],
    "summary": {
      "totalChecks": 2,
      "passed": 2,
      "failed": 0,
      "warnings": 0
    }
  },
  "dataIntegrity": {
    "checks": [
      {
        "name": "Verifier Report Valid",
        "status": "PASS",
        "evidence": "uri://documents/verifier-report-2024.pdf",
        "verifiedBy": "REV-01",
        "verifiedAt": "2026-01-14T09:40:00Z"
      },
      {
        "name": "Vintage Year Consistency",
        "status": "PASS",
        "evidence": "uri://documents/mrv-data-2024.json",
        "verifiedBy": "REV-01",
        "verifiedAt": "2026-01-14T09:45:00Z"
      }
    ],
    "summary": {
      "totalChecks": 2,
      "passed": 2,
      "failed": 0,
      "warnings": 0
    }
  },
  "processIntegrity": {
    "reviewer": {
      "id": "REV-01",
      "name": "Jane Doe",
      "signature": "0x1234...",
      "signedAt": "2026-01-14T10:00:00Z"
    },
    "workflow": [
      {
        "action": "SUBMITTED",
        "by": "ISSUER-12",
        "at": "2026-01-13T14:00:00Z"
      },
      {
        "action": "ASSIGNED",
        "by": "ADMIN-01",
        "to": "REV-01",
        "at": "2026-01-13T15:00:00Z"
      },
      {
        "action": "REVIEW_STARTED",
        "by": "REV-01",
        "at": "2026-01-14T09:00:00Z"
      },
      {
        "action": "APPROVED",
        "by": "REV-01",
        "at": "2026-01-14T10:00:00Z"
      }
    ]
  },
  "issuanceCap": {
    "maxTons": 10000,
    "vintageYear": 2024,
    "methodology": "VCS",
    "verifier": "Verra"
  },
  "hashes": {
    "assetProofHash": "0xabc123...",
    "dataProofHash": "0xdef456...",
    "processProofHash": "0x789ghi...",
    "bundleHash": "0xmainhash..."
  }
}

Hashing Rule

1. Canonicalize JSON (stable key ordering)

2. Hash with SHA256 or Keccak256 (pick one standard)

3. Store only the hashes on-chain

On-Chain Integration (Critical Gating)

ProjectRecord Contract Changes

When minting a ProjectRecord, require:

require(poaiStatus == APPROVED, "PoAI not approved");
require(bundleHash != 0x0, "PoAI hash missing");
require(issuanceCap > 0, "Invalid cap");

Store:

• bundleHash

• assetProofHash

• dataProofHash

• processProofHash

• validUntil (optional)

Mint Function Signature

function mintProjectRecord(
    uint256 projectId,
    bytes32 metadataHash,
    uint256 capUnits,
    bytes32 poaiBundleHash,
    bytes32 poaiAssetHash,
    bytes32 poaiDataHash,
    bytes32 poaiProcessHash
) external onlyRole(GOVERNANCE_ROLE);

Credit Issuance Contract Gating

Issuance must check:

require(projectRegistry.exists(projectTokenId), "Project not found");
require(projectRegistry.isActive(projectTokenId), "Project not active");
require(projectRegistry.isPoAIApproved(projectTokenId), "PoAI not approved");
require(issued[tokenId] + amount <= cap[tokenId], "Exceeds cap");

PoAI Developer Flow (Sequence)

1

Project Submission (Issuer)

• Issuer creates project in platform (projects table)

• Uploads required documents (project_documents table)

• Clicks "Submit for PoAI"

• System creates poai_case → state SUBMITTED

2

Review (Reviewer)

• Reviewer opens PoAI case

• System runs automated checks (optional)

• Reviewer marks checks PASS/FAIL with evidence

• If missing details → state CHANGES_REQUIRED and issuer notified

3

Approval

• Reviewer clicks "Approve"

• PoAI service:

  • Compiles proof bundle JSON

  • Creates proof hashes

  • Signs bundle hash (optional)

  • Stores bundle (encrypted)

  • Writes to poai_proofs table

• Update poai_case.state = APPROVED

• Update projects.status = PendingDAO

4

Governance Approval (DAO)

• DAO votes to approve project + cap

• If passed, platform triggers on-chain mint

• Call mintProjectRecord(...) with PoAI hashes

• Update project status to Approved

5

Credit Issuance

• Issuer/admin calls issueCredits(projectId, amountUnits)

• Contract enforces cap

• Credits become purchasable/allocatable

6

Retirement

• User retires units

• Certificate references:

  • Retirement tx hash

  • Project tokenId

  • PoAI bundle hash

  • PoAI bundle URI (optional access-controlled)

APIs for PoAI Module (REST)

Issuer Endpoints

POST   /projects                    # Create project
POST   /projects/:id/documents      # Upload document
POST   /projects/:id/poai/submit    # Submit for PoAI
GET    /projects/:id/poai/status    # Get PoAI status

Reviewer Endpoints (RBAC)

GET    /poai/cases?state=SUBMITTED           # List cases
GET    /poai/cases/:id                       # Get case details
POST   /poai/cases/:id/checks                # Add/update checks
POST   /poai/cases/:id/request-changes       # Request changes
POST   /poai/cases/:id/approve               # Approve case
POST   /poai/cases/:id/reject                # Reject case

Governance/Mint Orchestration

POST   /projects/:id/governance/propose       # Create proposal
POST   /projects/:id/onchain/mintProjectRecord  # Admin/system trigger
POST   /projects/:id/onchain/issueCredits    # Admin/system trigger

UI Screens for PoAI Module (Minimum)

Issuer Side

• Project submission form

  • Project details input

  • Document upload checklist (progress-based)

  • Submit button

• PoAI status timeline

  • Visual timeline: submitted → review → changes → approved

  • Status badges

  • Reviewer comments

Reviewer Side

• PoAI case list

  • Filters by state, project type, date

  • Assigned cases highlighted

• Case detail page

  • Document viewer + hash check

  • Checklist status (Asset/Data/Process)

  • Approve / Reject / Request changes buttons

  • Evidence upload

Admin Side

• Governance proposal status view

  • List of proposals

  • Voting status

  • Execution status

• On-chain mint trigger

  • Manual trigger (or automatic after DAO pass)

  • Transaction status

• Audit log export

  • Filterable logs

  • CSV/JSON export

Acceptance Criteria (PoAI Module)

A project cannot move to on-chain mint unless:

• ✅ poai_case.state == APPROVED

• ✅ poai_proofs.bundle_hash exists

• ✅ issuanceCap set and consistent

• ✅ All required checks passed

PoAI module must provide:

• ✅ Full audit trail of every decision

• ✅ Evidence links for checks

• ✅ Revalidation path (EXPIRED → IN_REVIEW)

Implementation Note (Security & Privacy)

Proof Bundle Storage

Proof bundles often contain sensitive documents:

• Store bundles encrypted (S3 with presigned URLs / IPFS encrypted payloads)

• On-chain store only hashes + minimal metadata

• Allow auditors access via time-limited secure links

Access Control

• Reviewers can only access assigned cases

• Issuers can only view their own projects

• Admins have full audit access

• Public can view PoAI status (approved/rejected) but not full bundles