🔧 CarbonCore Developer Wiki

📚 Platform Overview

CarbonCore.Earth is a comprehensive blockchain-based platform for streamlined creation, validation, and trading of carbon credits and CDR certificates. Built on Ethereum with smart contracts, the system provides complete transparency throughout the entire lifecycle of carbon sequestration projects.

Core Principles:

• UID-based Authentication: Users authorized by UIDs, not wallet addresses
• Role-Oriented System: Landowner, Expert, Government, Buyer, Administrator
• Multi-Stage Verification: Expert → Government → VVB validation
• Automatic Token Issuance: Every 24 hours without user intervention
• Universal Details Window: Unified interface for territory information

📖 Technical Guides

Comprehensive developer documentation in minimalist text format (Courier monospace, black on white):

🗂️ Architecture Stack

📜 Smart Contract Infrastructure

Sepolia Testnet Addresses:

🔄 Complete Project Lifecycle

Stage 1: Territory Registration

1. User creates UID profile (UserUID contract)
2. Register territory with geographic boundaries (TerritoryRegistry)
3. Submit onboarding request (RequestManager)
4. Status: PENDING + Pending

Stage 2: Verification Process

5. Admin generates invoice → COMPLETED + UnderExpertise
6. User pays → COMPLETED + Pending
7. Admin confirms payment → REVISION + Pending
8. Expert claims territory → REVISION + UnderExpertise
9. Expert submits verification with CO2 data → REVISION + ExpertVerified
10. Admin confirms expertise → APPROVED + ExpertVerified
11. VVB validation → APPROVED + GovernmentVerified
12. Admin final approval → COMPLETED + GovernmentVerified

Stage 3: Token Generation

13. Create project via CarbonCreditFactory.createProject()
14. Automatic ERC-20 token deployment via TerritoryTokenFactory
15. Daily token issuance via issueCredits() (callable by anyone)
16. Tokens sent to UID-based beneficiary
17. Status: HAS_ACTIVE_PROJECT

🪙 Token Economics

Token Calculation Formula:

Annual CO2 Absorption = Territory CO2 rate (kg/year)
Daily Token Rate = Annual CO2 / 365 days
Token Precision = 18 decimals (ERC-20 standard)

Example: Territory 24 (Honduras Forest)

Annual CO2: 94,000,000 kg/year
Daily Rate: 257,534 tokens/day
Token Symbol: CCT24-2025
Contract: Unique ERC-20 per project

Issuance Rules:

• Interval: Minimum 24 hours between issuances
• Accumulation: Maximum 90 days if not claimed
• Public Function: Anyone can trigger issuance
• Beneficiary: Tokens sent to UID owner

🛠️ Key Service Modules

UnifiedTokenManager

Single solution for all token operations with automatic decimal detection:

// Parse amounts with correct decimals
await tokenManager.parseAmount(amount, tokenAddress);

// Format for display
await tokenManager.formatAmount(wei, tokenAddress);

// Check balance
await tokenManager.getBalance(tokenAddress, walletAddress);

// Approve tokens
await tokenManager.approve(tokenAddress, spender, amount);

MetadataService

Deal metadata management through CommentManager:

// Get order metadata
await MetadataService.getOrderMetadata(orderId);

// Structure for RFQ
{
  "metadataType": "RFQ",
  "requirements": { ... },
  "contactPreferences": { ... }
}

TerritoryDetailsService

Universal details window accessible from all modules:

// Show details from any module
window.TerritoryDetailsService.showDetails(territoryId);

// Available from: territory list, token management, map, deals

🎯 14-Stage Status System

Category	Status	Description
1	Initial Appraisal	New territory submitted
2	Awaiting Payment	Invoice generated
3	Payment Verification	Payment submitted
4	Under Technical Expertise	Payment confirmed
5	Active Expert Appraisal	Expert engaged
6	Pending Expertise Confirmation	Expert completed
7	Under VVB Validation	Sent to VVB
8	Ready for Credit Issuance	VVB completed
9	Issuance-Ready (Active)	Can create project ✅
10	Active Carbon Project	Has tokens 🪙
11	Renewal Required	Expiring soon
12	Rejected	Failed verification
13	Inactive	Deactivated
14	Territory Modified	Split/Merge/Extend

📡 REST API Endpoints

Public Endpoints (No Auth):

GET  /projects              - List all carbon projects
GET  /projects/{id}         - Get project details

Admin Endpoints (JWT Required):

POST /admin/login           - Admin authentication
GET  /admin/validate         - Validate JWT session
GET  /admin/projects         - Admin project list
POST /admin/projects         - Create new project
PUT  /admin/projects/{id}    - Update project
DELETE /admin/projects/{id}  - Delete project
GET  /admin/transactions     - View all transactions
GET  /admin/project-types    - List project types

🔐 Security & Best Practices

Critical Rules:

Security Mechanisms:

• ReentrancyGuard on all contracts
• Pausable for emergency stops
• UID-based ownership (not wallet-based)
• JWT with 8-hour expiration
• Rate limiting on admin login
• Smart contract audits

📞 Developer Resources

Documentation:

• Platform Docs: documents.carboncore.earth
• GitHub: github.com/carboncore
• Etherscan: sepolia.etherscan.io

Support: