15 contract architecture

Overview

This document provides detailed technical architecture for the smart contract system, focusing on the ERC-1155 semi-fungible implementation and integration with Project Records and PoAI.

Contract Set (Recommended)

A) ProjectRegistry (Project "NFT" Record)

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

Purpose: Immutable project identity anchor

Stores:

• Project metadata hash

• PoAI proof hashes

• Issuance cap

• Project status

---

B) CarbonCredit1155 (Semi-Fungible Units)

Standard: ERC-1155 (Multi-Token Standard)

Purpose: Credit units that are fungible within project, non-fungible across projects

Stores:

• Balances per user per tokenId

• Caps per tokenId

• Issued/retired totals per tokenId

• Transfer policies per tokenId

---

C) Governance/Access (Roles)

Implementation: OpenZeppelin AccessControl or similar

Purpose: Role-based access control

Roles:

• ISSUER_ROLE: Can mint credits

• GOVERNANCE_ROLE: Can configure projects and execute governance

• PAUSER_ROLE: Can pause contracts (emergency)

---

Token ID Strategy

Option 1: tokenId = ProjectRecordId (Recommended for v1)

Mapping:

ProjectRecord tokenId = 101
Credit Units tokenId = 101

Advantages:

• Easiest to trace

• Direct 1:1 mapping

• Simple implementation

Use Case: One project record = one issuance batch

Option 2: tokenId = hash(projectId + vintage + verifier + methodology)

---

Units & Decimals Implementation

Fixed-Point Units

Definition:

uint256 public constant UNIT = 1e6; // or 1e18 for maximum precision

Conversion:

1 ton CO₂ = 1 * UNIT = 1,000,000 (if UNIT = 1e6)
0.25 ton = 0.25 * UNIT = 250,000
12,437.62 tons = 12,437.62 * UNIT = 12,437,620,000

UI Display:

// On-chain: stored as 250000
// UI display: 250000 / UNIT = 0.25
const displayAmount = onChainAmount / UNIT;

---

CarbonCredit1155 Contract Design

Storage Structure

contract CarbonCredit1155 is ERC1155, AccessControl, Pausable {
    // Project configuration per tokenId
    mapping(uint256 => uint256) public cap;              // Max issuable units
    mapping(uint256 => uint256) public issued;           // Total minted
    mapping(uint256 => uint256) public retired;          // Total burned
    mapping(uint256 => bool) public projectActive;      // Can mint/transfer
    mapping(uint256 => TransferPolicy) public transferPolicy;
    
    // Reference to ProjectRegistry
    IProjectRegistry public projectRegistry;
    
    // Constants
    uint256 public constant UNIT = 1e6;
    
    enum TransferPolicy {
        OPEN,        // P2P transfers allowed
        RESTRICTED,  // Only approved operators
        DISABLED     // No transfers; only buy and retire
    }
}

---

Core Functions

setProjectConfig

function setProjectConfig(
    uint256 tokenId,
    uint256 capUnits,
    TransferPolicy policy,
    bool active
) external onlyRole(GOVERNANCE_ROLE) {
    require(
        projectRegistry.isPoAIApproved(tokenId),
        "PoAI not approved"
    );
    require(capUnits > 0, "Invalid cap");
    
    cap[tokenId] = capUnits;
    transferPolicy[tokenId] = policy;
    projectActive[tokenId] = active;
    
    emit ProjectConfigured(tokenId, capUnits, policy, active);
}

Validations:

• PoAI must be approved

• Cap must be > 0

• Caller must have GOVERNANCE_ROLE

---

mintCredits

function mintCredits(
    uint256 tokenId,
    address to,
    uint256 amountUnits
) external onlyRole(ISSUER_ROLE) whenNotPaused {
    require(projectActive[tokenId], "Project not active");
    require(
        issued[tokenId] + amountUnits <= cap[tokenId],
        "Exceeds cap"
    );
    
    issued[tokenId] += amountUnits;
    _mint(to, tokenId, amountUnits, "");
    
    emit CreditsMinted(tokenId, to, amountUnits);
}

Validations:

• Project must be active

• Issuance must not exceed cap

• Caller must have ISSUER_ROLE

---

retire

function retire(
    uint256 tokenId,
    uint256 amountUnits
) external whenNotPaused {
    require(
        balanceOf(msg.sender, tokenId) >= amountUnits,
        "Insufficient balance"
    );
    
    retired[tokenId] += amountUnits;
    _burn(msg.sender, tokenId, amountUnits);
    
    emit CreditsRetired(tokenId, msg.sender, amountUnits);
}

Validations:

• User must have sufficient balance

• Burns credits permanently

---

_beforeTokenTransfer (Transfer Policy Enforcement)

function _beforeTokenTransfer(
    address operator,
    address from,
    address to,
    uint256[] memory ids,
    uint256[] memory amounts,
    bytes memory data
) internal virtual override {
    super._beforeTokenTransfer(operator, from, to, ids, amounts, data);
    
    // Allow mint (from == address(0)) and burn (to == address(0))
    if (from == address(0) || to == address(0)) {
        return;
    }
    
    // Enforce transfer policy for transfers
    for (uint256 i = 0; i < ids.length; i++) {
        uint256 tokenId = ids[i];
        TransferPolicy policy = transferPolicy[tokenId];
        
        if (policy == TransferPolicy.DISABLED) {
            revert("Transfers disabled for this project");
        }
        
        if (policy == TransferPolicy.RESTRICTED) {
            require(
                isApprovedForAll(from, operator) || 
                hasRole(APPROVED_OPERATOR_ROLE, operator),
                "Transfer restricted to approved operators"
            );
        }
    }
}

---

PoAI Integration (Gating)

ProjectRegistry Integration

contract ProjectRegistry is ERC721, AccessControl {
    struct ProjectRecord {
        bytes32 metadataHash;
        uint256 maxIssuableUnits;
        bytes32 poaiBundleHash;
        bytes32 poaiAssetHash;
        bytes32 poaiDataHash;
        bytes32 poaiProcessHash;
        bool active;
    }
    
    mapping(uint256 => ProjectRecord) public projectRecords;
    
    function isPoAIApproved(uint256 projectId) external view returns (bool) {
        ProjectRecord memory record = projectRecords[projectId];
        return record.poaiBundleHash != bytes32(0) && record.active;
    }
}

CarbonCredit1155 Gating

function setProjectConfig(...) external {
    require(
        projectRegistry.isPoAIApproved(tokenId),
        "PoAI not approved"
    );
    // ... rest of function
}

Result: No PoAI → no activation → no mint.

---

Complete On-Chain Flow

1

Step 1: Project Approved (PoAI + Governance)

• Off-chain PoAI verification generates hashes

• Governance approves project and sets issuance cap

• ProjectRecord minted with cap and PoAI hashes

projectRegistry.mintProjectRecord(
    projectId,
    metadataHash,
    capUnits,
    poaiBundleHash,
    poaiAssetHash,
    poaiDataHash,
    poaiProcessHash
);

2

Step 2: Issue Credit Units

carbonCredit1155.setProjectConfig(
    projectTokenId,
    capUnits,
    TransferPolicy.OPEN,
    true
);

carbonCredit1155.mintCredits(
    projectTokenId,
    treasuryAddress,
    amountUnits
);

Enforces:

• Project active

• issued + amount <= cap

3

Step 3: User Holds Credits

uint256 balance = carbonCredit1155.balanceOf(userWallet, projectTokenId);
// balance is in UNIT scale (e.g., 250000 = 0.25 tons if UNIT = 1e6)

4

Step 4: Retirement (Burn)

carbonCredit1155.retire(projectTokenId, amountUnits);

Contract Actions:

• Burns units from user

• Increments retired counter

• Emits CreditsRetired event

5

Step 5: Certificate Generation (Off-Chain)

Indexer listens to CreditsRetired event:

• Generates certificate

• References tx hash + event details

• Includes PoAI proof hash from ProjectRecord

---

Metadata Structure

uri(tokenId) Returns JSON

{
  "name": "Solar Rajasthan 2024",
  "description": "Renewable energy project",
  "project": {
    "id": "PJT-101",
    "type": "Renewable Energy",
    "geography": "Rajasthan, India",
    "vintageYear": 2024,
    "methodology": "VCS",
    "verifier": "Verra"
  },
  "poai": {
    "bundleHash": "0x...",
    "assetHash": "0x...",
    "dataHash": "0x...",
    "processHash": "0x..."
  },
  "issuance": {
    "capUnits": "10000000000",
    "issuedUnits": "2000000000",
    "retiredUnits": "250000"
  },
  "links": {
    "proofBundle": "https://...",
    "projectDetails": "https://..."
  }
}

---

Security Considerations

Access Control

• Role-based access (OpenZeppelin AccessControl)

• Multi-sig for critical operations (optional)

Reentrancy Protection

• Use nonReentrant modifier

• Checks-effects-interactions pattern

Integer Safety

• Solidity 0.8+ (built-in overflow protection)

• Or SafeMath library

Pausable

• Emergency pause mechanism

• whenNotPaused modifier on critical functions

---

Gas Optimization

Storage Optimization

• Pack structs efficiently

• Use events for historical data

• Store only essential data on-chain

Function Optimization

• Batch operations where possible

• Minimize external calls

• Use view functions for reads