# Platform Overview - CarbonCore Documentation

## Introduction

CarbonCore is a comprehensive blockchain-based digital platform designed to streamline the creation, validation, and trading of carbon credits and Carbon Dioxide Removal (CDR) certificates. Built on Ethereum, our platform provides complete transparency throughout the entire lifecycle of carbon sequestration projects.

## Mission Statement

To democratize carbon markets by providing transparent, efficient, and accessible tools for carbon credit creation and trading. We leverage blockchain technology to create a more equitable and effective carbon economy that benefits both the environment and stakeholders worldwide.

## Core Value Propositions

### 1. Complete Transparency
- All territory data stored on blockchain
- Immutable verification records
- Public audit trail for all transactions
- Real-time monitoring of carbon credit generation

### 2. Automated Token Issuance
- Daily automatic credit generation (every 24 hours)
- No manual intervention required
- Based on verified CO2 absorption rates
- Maximum 90-day accumulation period

### 3. Multi-Stage Verification
- Expert technical assessment
- Government/VVB validation
- Standards compliance verification
- Insurance-backed credibility

### 4. NFT-Based Identity
- Secure user authentication via NFTs
- Transferable ownership rights
- Role-based access control (RBAC)
- Protection against wallet changes

## Technology Stack

### Blockchain Infrastructure
- **Network**: Ethereum Mainnet / Sepolia Testnet
- **Smart Contracts**: Solidity (11 deployed contracts)
- **Web3 Library**: Ethers.js v5
- **Authentication**: NFT-based identity system

### Frontend Technologies
- **Core**: HTML5, CSS3, JavaScript (ES6+)
- **Mapping**: Leaflet.js for territory visualization
- **State Management**: Modular service architecture
- **Responsive Design**: Mobile-first approach

### Backend Services
- **Database**: AWS RDS PostgreSQL
- **API**: AWS Lambda + API Gateway
- **Payments**: Stripe (Live ready)
- **Emails**: AWS SES
- **Authentication**: JWT (8-hour sessions)

### Data Integration
- Satellite imagery analysis
- Drone data processing (planned)
- Geographic Information Systems (GIS)
- Machine learning models (in development)

## System Architecture

### Smart Contract Layer
```
UserNFT (Identity)
    ↓
RoleManager (Permissions)
    ↓
TerritoryRegistry (Territories)
    ↓
CarbonCreditFactory (Projects)
    ↓
TerritoryToken (ERC-20 Credits)
```

### Service Layer
```
Frontend (carboncore.earth)
    ↓
API Gateway (api.carboncore.earth)
    ↓
Lambda Functions (JWT Auth)
    ↓
PostgreSQL Database + Stripe + SES
```

### OTC Marketplace
```
OTCMarketInterface (Trading)
    ↓
OTCMarketIndex (Indexing)
    ↓
RequestManager (Order Management)
    ↓
CommentManager (Metadata)
```

## Key Features

### For Territory Owners (Landowners)
- Register carbon sequestration territories
- Upload geographic boundaries (GeoJSON)
- Track verification progress
- Monitor daily token issuance
- Manage beneficiary rights
- List tokens for sale on OTC marketplace

### For Experts
- Claim territories for verification
- Submit technical assessments
- Provide CO2 absorption calculations
- Upload verification reports
- Earn verification fees

### For Government/VVB Entities
- Review expert assessments
- Provide official validation
- Set validity periods
- Issue compliance certificates
- Monitor territory compliance

### For Buyers
- Browse available carbon credits
- Create RFQ (Request for Quote)
- Execute instant purchases
- Retire credits with certificates
- Track portfolio value
- View territory details

### For Administrators
- Manage onboarding requests
- Generate invoices
- Confirm payments
- Approve verifications
- Monitor platform analytics
- Manage user roles

## User Roles & Permissions

### Role Hierarchy
1. **Administrator** (ADMIN_ROLE)
   - Full platform access
   - User management
   - Contract deployment
   - Emergency controls

2. **Landowner** (LANDOWNER_ROLE)
   - Register territories
   - Create projects
   - Manage tokens
   - Set beneficiaries

3. **Expert** (EXPERT_ROLE)
   - Claim territories
   - Submit verifications
   - Upload reports
   - Calculate CO2 rates

4. **Government** (GOVERNMENT_ROLE)
   - Validate territories
   - Issue certificates
   - Set validity periods
   - Compliance oversight

5. **Buyer** (BUYER_ROLE)
   - Purchase credits
   - Create RFQs
   - Retire credits
   - Receive certificates

6. **Guest** (GUEST_ROLE)
   - View public data
   - Browse marketplace
   - Request roles
   - Basic access

## Contract Addresses (Sepolia Testnet)

### Core Contracts
```
UserNFT: 0xdc06fD25E479D570310bA0D3b555974d6841c076
RoleManager: 0x60569F3910459056dA97076b49013BF9AB843102
TerritoryRegistry: 0x2Bb231045BcC27ec9925bB7453976c517162a5A7
CarbonCreditFactory: 0x20ACB9DA5a312903822A46DD77728112e9735cC0
TerritoryTokenFactory: 0xfC69CbCc115eB28DE6d8f3C3c5A1C19984FD4f93
```

### Supporting Contracts
```
RequestManager: 0xE52950D4Baa78C2caE0970F282701350f3681ee0
CommentManager: 0x97633F9C80CAD965a2a35AD579Eb4F6060d4cd14
StandardValidators: 0x571436936Ae7b7E6f0bEcc8Ca7E241FA390b67CC
InsuranceManager: 0xE441fAD098C71F27dBa8C83E979b30c34e152Ae9
```

### OTC Marketplace
```
OTCMarketInterface: 0xDAde447FCC8B2480c76cc8E0be23eb5772966C21
OTCMarketIndex: 0xd154C16A5d1fB9CE16B88F0c76593D1C28Bd046e
```

## Platform Workflow

### Complete Lifecycle: Territory → Tokens → Trade

**Phase 1: User Registration**
1. Connect Web3 wallet (MetaMask, etc.)
2. Create NFT profile with personal data
3. Automatic LANDOWNER_ROLE assignment
4. Profile stored on blockchain

**Phase 2: Territory Registration**
1. Define geographic boundaries (map/GeoJSON)
2. Specify territory details (type, area, etc.)
3. Upload supporting documents
4. Submit onboarding request
5. Admin generates invoice

**Phase 3: Payment & Verification**
1. Territory owner pays invoice
2. Admin confirms payment
3. Territory assigned to expert
4. Expert conducts assessment
5. Expert submits CO2 absorption data

**Phase 4: Government Validation**
1. Admin reviews expert assessment
2. Territory sent to VVB validation
3. Government entity validates
4. Validity period set (e.g., 1 year)
5. Territory status: GovernmentVerified

**Phase 5: Token Generation**
1. Territory owner creates project
2. ERC-20 token contract deployed
3. Daily rate calculated from CO2 data
4. Automatic token issuance begins
5. Tokens appear in owner's wallet

**Phase 6: OTC Trading**
1. Owner lists tokens for sale
2. Sets price and conditions
3. Buyers browse marketplace
4. Instant buy or RFQ process
5. Automatic escrow & exchange

## Project Status System

CarbonCore uses a sophisticated 14-stage status system that combines RequestManager status with TerritoryRegistry status:

### Onboarding Phase (Categories 1-3)
- **Initial Appraisal**: New territory submitted
- **Awaiting Payment**: Invoice generated
- **Payment Verification**: Payment submitted

### Verification Phase (Categories 4-6)
- **Under Technical Expertise**: Expert assigned
- **Active Expert Appraisal**: Assessment in progress
- **Pending Expertise Confirmation**: Expert completed

### Validation Phase (Categories 7-8)
- **Under VVB Validation**: Government review
- **Ready for Credit Issuance**: Validation confirmed

### Ready Phase (Category 9)
- **Issuance-Ready**: Can create project ✅

### Production Phase (Categories 10-11)
- **Active Carbon Project**: Tokens generating 🪙
- **Renewal Required**: Expiring soon ⚠️

### Final States (Categories 12-14)
- **Rejected**: Validation failed ❌
- **Inactive**: Territory deactivated 🔒
- **Territory Modified**: Split/merged/extended 🔄

## Token Economics

### Daily Token Issuance
```javascript
// Example: Territory with 94M kg CO2/year
Annual CO2 = 94,000,000 kg
Daily Rate = Annual CO2 / 365 = 257,534 tokens/day
Monthly = 7,726,027 tokens
Yearly = 94,000,000 tokens
```

### Token Characteristics
- **Standard**: ERC-20
- **Decimals**: 18
- **Name**: "CarbonCore Territory {ID} - {Year}"
- **Symbol**: "CCT{ID}-{Year}"
- **Mintable**: Only by CarbonCreditFactory
- **Burnable**: Yes (for retirement)

### Issuance Rules
- **Minimum Interval**: 24 hours (86,400 seconds)
- **Maximum Accumulation**: 90 days
- **Public Function**: Anyone can trigger issuance
- **Automatic**: No user action required
- **Beneficiary**: NFT-based recipient

## Security Features

### Contract-Level Security
- **ReentrancyGuard**: Protection against reentrancy attacks
- **Pausable**: Emergency stop mechanism
- **Ownable**: Owner-only critical functions
- **Role-Based**: Granular permission system

### Authentication Security
- **JWT Tokens**: 8-hour session expiration
- **Rate Limiting**: Prevents brute force attacks
- **Password Hashing**: SHA-256 for credentials
- **Token Verification**: HMAC-based signature

### Transaction Security
- **Escrow Mechanism**: Funds locked until completion
- **Multi-Signature**: Critical operations require approval
- **Audit Trail**: All actions logged on-chain
- **Immutable Records**: Cannot alter history

## Data Privacy

### User Data Protection
- **Minimal Collection**: Only necessary information
- **Encrypted Storage**: Sensitive data encrypted
- **GDPR Compliant**: Right to deletion
- **Access Control**: Role-based data access

### Blockchain Transparency
- **Public Data**: Territory boundaries, verification status
- **Private Data**: Personal information, financial details
- **Pseudonymous**: Wallet addresses, not real names
- **Audit Rights**: Verification of all claims

## Performance Metrics

### Current Capabilities
- **Territories**: Unlimited
- **Projects**: Unlimited
- **Token Types**: Unique per territory/year
- **Daily Issuance**: Automatic for all active projects
- **Transaction Speed**: ~15 seconds (Ethereum)
- **Cost**: Variable gas fees

### Scalability Plans
- **Layer 2 Integration**: Reduced fees
- **Batch Processing**: Multiple operations
- **Caching Strategy**: 5-minute metadata cache
- **Lazy Loading**: On-demand data fetching

## Integration Points

### External Systems
- **MetaMask**: Primary wallet integration
- **Stripe**: Payment processing (live ready)
- **AWS SES**: Email notifications
- **IPFS**: Document storage (planned)
- **Graph Protocol**: Advanced indexing (planned)

### API Access
- **REST API**: `api.carboncore.earth`
- **WebSocket**: Real-time updates (planned)
- **GraphQL**: Flexible queries (planned)
- **SDK**: JavaScript/TypeScript (in development)

## Support & Resources

### Documentation
- **Platform Overview**: This document
- **Smart Contracts**: Technical specifications
- **API Reference**: Endpoint documentation
- **Frontend Guide**: UI/UX patterns
- **Security**: Best practices

### Community
- **Discord**: Developer community
- **GitHub**: Open-source repositories
- **Twitter**: Platform updates
- **Email**: info@carboncore.earth

### Professional Services
- **Consulting**: Custom integrations
- **Training**: Platform workshops
- **Support**: Priority assistance
- **Whitelabel**: Branded solutions

## Future Roadmap

### Q1 2025 ✅
- ✅ Core platform launch
- ✅ OTC marketplace
- ✅ Automated token issuance
- ✅ JWT authentication

### Q2 2025 🔄
- 🔄 Advanced analytics dashboard
- 🔄 Mobile applications
- 🔄 API v2 with GraphQL
- 🔄 L2 integration (Polygon)

### Q3 2025 📋
- 📋 Satellite data integration
- 📋 ML-based verification
- 📋 Auction mechanism
- 📋 Reputation system

### Q4 2025 📋
- 📋 Cross-chain bridges
- 📋 Carbon derivatives
- 📋 Insurance products
- 📋 Global partnerships

## Conclusion

CarbonCore represents the next generation of carbon credit platforms, combining blockchain transparency, automated processes, and user-friendly interfaces. Our commitment to environmental impact and technological innovation makes us the premier choice for carbon credit digitization.

**Building a sustainable future, one carbon credit at a time.** 🌱

---

**Document Version**: 2.0
**Last Updated**: January 2025
**Author**: CarbonCore Team
**License**: Proprietary

For questions or support, contact: info@carboncore.earth