07 project onboarding flow

Overview

The project onboarding flow is the critical path that ensures only verified, legitimate projects can issue carbon credits on the platform. This flow involves multiple stakeholders and strict verification gates.

Goal

Allow only verified projects to mint Project Records + issue credit units.

Complete Flow Diagram

Project Owner Submits Project
    ↓
Status: PendingPoAI
    ↓
PoAI Review (Verifier/Reviewer)
    ↓
Status: PendingDAO (if approved) OR Rejected
    ↓
DAO Governance Vote
    ↓
Status: Approved (if passed)
    ↓
Mint Project Record (Non-Fungible NFT)
    ↓
Issue Semi-Fungible Credit Units
    ↓
Credits Available for Purchase

Step-by-Step Flow

1

Project Owner Submits Project

Actor: Project Owner / Issuer

Actions:

• Create project profile in platform

• Enter project details:

  • Project name

  • Project type (Renewable Energy, Reforestation, etc.)

  • Geography/location

  • Methodology (VCS, Gold Standard, etc.)

  • Vintage year

  • Verifier name and reference ID

• Upload required documents:

  • Ownership documents

  • Verifier reports

  • MRV (Monitoring, Reporting, Verification) data

  • Impact reports

  • GPS coordinates

  • Photos (optional)

  • Certificates

• Submit for PoAI review

Inputs:

• Project details form data

• Document files (PDFs, JSON, images)

• Verifier references

System Actions:

• Create Project record with status Draft

• Store documents in encrypted storage

• Generate document hashes

• Create poai_case with status SUBMITTED

• Notify PoAI reviewers

Status Transition: Draft → PendingPoAI

2

PoAI Review

Actor: Verifier / PoAI Reviewer

Actions:

• Reviewer assigned to PoAI case

• Reviewer accesses project documents

• Reviewer performs integrity checks:

  Asset Integrity Checks:

  • Verify project ownership

  • Verify geographic location (GPS coordinates)

  • Verify project exists in real world

  • Cross-reference with verifier database

  Data Integrity Checks:

  • Verify verifier report validity

  • Check vintage year consistency

  • Validate MRV data

  • Verify methodology compliance

  • Check document consistency

  Process Integrity Checks:

  • Verify submission workflow

  • Verify reviewer assignment

  • Verify all required documents present

  • Verify document authenticity

• Reviewer marks each check as:

  • PASS: Check passed

  • FAIL: Check failed (blocks approval)

  • WARN: Warning (may require clarification)

  • PENDING: Not yet checked

• Reviewer decision:

  • Approve: All checks pass → proceed to governance

  • Request Changes: Missing info/clarifications needed

  • Reject: Fraud/inconsistency/unverifiable data

If Changes Required:

• Status → CHANGES_REQUIRED

• Issuer notified with reviewer comments

• Issuer can update documents and resubmit

• Flow returns to PoAI Review

If Approved:

• PoAI service generates proof bundle

• Creates proof hashes:

  • bundleHash

  • assetProofHash

  • dataProofHash

  • processProofHash

• Stores proof bundle (encrypted)

• Reviewer signs approval (optional)

• Status → PendingDAO

Status Transition: PendingPoAI → PendingDAO (or Rejected)

3

DAO Governance Vote

Actor: DAO Voters / Governance Members

Actions:

• Governance proposal created automatically:

  • Proposal type: OnboardProject

  • Project details

  • PoAI proof hashes

  • Proposed issuance cap

  • Transfer policy recommendation

• Proposal published to governance interface

• Voters review:

  • Project details

  • PoAI status and proof hashes

  • Proposed cap

  • Project type and methodology

• Voting window opens

• Voters cast votes:

  • FOR: Approve project

  • AGAINST: Reject project

  • ABSTAIN: No opinion

• Voting window closes

• Results calculated:

  • Check quorum threshold

  • Check majority threshold

  • Determine outcome

If Proposal Passes:

• Status → Approved

• Proposal status → Passed

• System prepares on-chain mint

If Proposal Fails:

• Status → Rejected

• Proposal status → Failed

• Project cannot proceed (can resubmit with changes)

Status Transition: PendingDAO → Approved (or Rejected)

4

Mint Project Record (Non-Fungible)

Actor: System / Admin (triggered by governance)

Actions:

1. System calls ProjectRegistry.mintProjectRecord():

   mintProjectRecord(
       projectId,
       metadataHash,
       capUnits,
       poaiBundleHash,
       poaiAssetHash,
       poaiDataHash,
       poaiProcessHash
   )

2. Contract validates:

   • PoAI status is APPROVED

   • PoAI hashes are non-zero

   • Cap is greater than zero

   • Project doesn't already exist

3. Contract mints NFT:

   • Generates unique tokenId

   • Stores metadata hash

   • Stores PoAI proof hashes

   • Stores issuance cap

   • Emits ProjectRecordMinted event

4. System updates database:

   • Link Project to ProjectRecord

   • Store onChainTokenId

   • Update project status

Result: Project now has immutable on-chain identity.

5

Configure Credit Units Contract

Actor: System / Admin

Actions:

1. System calls CarbonCredit1155.setProjectConfig():

   setProjectConfig(
       projectTokenId,
       capUnits,
       transferPolicy,
       active = true
   )

2. Contract validates:

   • ProjectRecord exists

   • PoAI approved

   • Cap matches ProjectRecord cap

3. Contract activates project for credit issuance

4. Emits ProjectConfigured event

Result: Project is now "live" and can issue credits.

6

Issue Semi-Fungible Credit Units

Actor: Issuer / Admin

Actions:

• Issuer/admin decides to issue credits

• Determines amount to issue (must be ≤ cap)

• Calls CarbonCredit1155.mintCredits():

  mintCredits(
      projectTokenId,
      treasuryAddress,
      amountUnits
  )

• Contract validates:

  • Project is active

  • issued + amount <= cap

  • Caller has ISSUER_ROLE

• Contract mints credits:

  • Increments issued[projectTokenId]

  • Transfers credits to treasury

  • Emits CreditsMinted event

• System updates database:

  • Record issuance transaction

  • Update supply metrics

Result: Credits exist on-chain and are available for purchase/allocations.

Developer Notes

Critical Rules

1. The "Project Record" is the anchor for everything

   • All credit units reference the ProjectRecord tokenId

   • No credits can exist without a ProjectRecord

2. Credits must be non-interchangeable across projects

   • Credits from Project A ≠ Credits from Project B

   • Enforced by tokenId segregation

3. PoAI is a hard gate

   • No ProjectRecord without PoAI approval

   • No credit issuance without ProjectRecord

4. Governance controls caps

   • Issuance cap set by governance vote

   • Cannot be exceeded by smart contract enforcement

State Transitions Summary

Draft
  ↓ (submit)
PendingPoAI
  ↓ (PoAI approve)
PendingDAO
  ↓ (governance approve)
Approved
  ↓ (mint ProjectRecord)
[ProjectRecord exists]
  ↓ (configure credits)
[Credits can be issued]

Error Handling

PoAI Rejection:

• Project status → Rejected

• Cannot proceed to governance

• Issuer can resubmit with changes

Governance Rejection:

• Project status → Rejected

• PoAI proof remains valid

• Can resubmit to governance with different cap

Issuance Cap Exceeded:

• Transaction reverts

• Must request governance to increase cap

Acceptance Criteria

• ✅ Project cannot be submitted without required documents

• ✅ PoAI review must complete all checks before approval

• ✅ Project cannot proceed to governance without PoAI approval

• ✅ ProjectRecord cannot be minted without PoAI hashes

• ✅ Credit units cannot be issued without ProjectRecord

• ✅ Issuance cannot exceed governance-approved cap

• ✅ All state transitions are auditable