13 smart contract modules

Overview

The smart contract layer provides immutable, trustless functionality for project records, credit units, retirement, and governance. This document outlines the minimum viable on-chain set.

Contract Architecture

Core Contracts

• ProjectRegistry

• CarbonCredit1155

• Retirement

• Governance

Supporting Contracts

• AccessControl

• Pausable (optional)

---

ProjectRegistry Contract

Purpose: Store project records and PoAI anchors

Storage

struct ProjectRecord {
    uint256 projectId;
    bytes32 metadataHash;
    uint256 maxIssuableUnits;
    bytes32 poaiBundleHash;
    bytes32 poaiAssetHash;
    bytes32 poaiDataHash;
    bytes32 poaiProcessHash;
    bool active;
    uint256 createdAt;
}

mapping(uint256 => ProjectRecord) public projectRecords;
mapping(uint256 => bool) public projectExists;
uint256 public nextProjectId;

Functions

mintProjectRecord

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

Validations:

• PoAI hashes must be non-zero

• Cap must be > 0

• Project must not already exist

Actions:

• Creates ProjectRecord

• Assigns tokenId

• Stores PoAI hashes

• Emits ProjectRecordMinted event

isPoAIApproved

function isPoAIApproved(uint256 projectId) external view returns (bool);

Returns: true if project has PoAI hashes attached

suspendProject

function suspendProject(uint256 projectId) external onlyRole(GOVERNANCE_ROLE);

Actions:

• Sets active = false

• Emits ProjectSuspended event

reactivateProject

function reactivateProject(uint256 projectId) external onlyRole(GOVERNANCE_ROLE);

Actions:

• Sets active = true

• Emits ProjectReactivated event

Events

event ProjectRecordMinted(
    uint256 indexed projectId,
    uint256 indexed tokenId,
    uint256 maxIssuableUnits,
    bytes32 poaiBundleHash
);

event ProjectSuspended(uint256 indexed projectId);
event ProjectReactivated(uint256 indexed projectId);

---

CarbonCredit1155 Contract

Purpose: Semi-fungible credit units (ERC-1155)

Storage

mapping(uint256 => uint256) public cap;              // Max issuable per project
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;

enum TransferPolicy {
    OPEN,        // P2P transfers allowed
    RESTRICTED,  // Only approved operators
    DISABLED     // No transfers; only buy and retire
}

Functions

setProjectConfig

function setProjectConfig(
    uint256 tokenId,
    uint256 capUnits,
    TransferPolicy policy,
    bool active
) external onlyRole(GOVERNANCE_ROLE);

Validations:

• ProjectRecord must exist

• PoAI must be approved

• Cap must be > 0

Actions:

• Sets cap, policy, and active status

• Emits ProjectConfigured event

mintCredits

function mintCredits(
    uint256 tokenId,
    address to,
    uint256 amountUnits
) external onlyRole(ISSUER_ROLE);

Validations:

• Project must be active

• issued[tokenId] + amountUnits <= cap[tokenId]

Actions:

• Mints credits to to address

• Increments issued[tokenId]

• Emits CreditsMinted event

retire

function retire(
    uint256 tokenId,
    uint256 amountUnits
) external;

Validations:

• balanceOf(msg.sender, tokenId) >= amountUnits

Actions:

• Burns credits from msg.sender

• Increments retired[tokenId]

• Emits CreditsRetired event

balanceOf

function balanceOf(address account, uint256 tokenId) 
    public view returns (uint256);

Standard ERC-1155 balance query.

_beforeTokenTransfer

function _beforeTokenTransfer(
    address operator,
    address from,
    address to,
    uint256[] memory ids,
    uint256[] memory amounts,
    bytes memory data
) internal virtual override;

Transfer Policy Enforcement:

• If from == address(0): Mint (allowed)

• If to == address(0): Burn (allowed)

• Otherwise: Check transferPolicy[tokenId]

  • OPEN: Allow

  • RESTRICTED: Only approved operators

  • DISABLED: Revert

Events

event ProjectConfigured(
    uint256 indexed tokenId,
    uint256 capUnits,
    TransferPolicy policy,
    bool active
);

event CreditsMinted(
    uint256 indexed tokenId,
    address indexed to,
    uint256 amountUnits
);

event CreditsRetired(
    uint256 indexed tokenId,
    address indexed from,
    uint256 amountUnits
);

---

Retirement Contract (Optional Separate Contract)

Purpose: Dedicated retirement functionality (can be integrated into CarbonCredit1155)

Functions

retireCredits

function retireCredits(
    uint256 tokenId,
    uint256 amountUnits,
    string memory retirementReason
) external;

Actions:

• Calls CarbonCredit1155.retire()

• Records retirement reason

• Emits RetirementRecorded event

Events

event RetirementRecorded(
    uint256 indexed tokenId,
    address indexed retiredBy,
    uint256 amountUnits,
    string retirementReason,
    uint256 timestamp
);

---

Governance Contract

Purpose: DAO voting and proposal execution

Storage

struct Proposal {
    uint256 proposalId;
    ProposalType proposalType;
    bytes parameters;
    uint256 votesFor;
    uint256 votesAgainst;
    uint256 votingStart;
    uint256 votingEnd;
    bool executed;
}

enum ProposalType {
    OnboardProject,
    IssueUnits,
    SuspendProject,
    ParameterUpdate
}

mapping(uint256 => Proposal) public proposals;
uint256 public nextProposalId;

Functions

createProposal

function createProposal(
    ProposalType proposalType,
    bytes memory parameters,
    uint256 votingDuration
) external returns (uint256 proposalId);

Actions:

• Creates proposal

• Sets voting window

• Emits ProposalCreated event

vote

function vote(
    uint256 proposalId,
    bool support
) external;

Validations:

• Proposal must be active

• Voter must not have voted

• Voting window must be open

Actions:

• Records vote

• Updates vote counts

• Emits VoteCast event

executeProposal

function executeProposal(uint256 proposalId) external;

Validations:

• Proposal must be passed

• Quorum must be met

• Proposal must not be executed

• Execution delay must have passed

Actions:

• Executes proposal based on type

• Marks proposal as executed

• Emits ProposalExecuted event

Events

event ProposalCreated(
    uint256 indexed proposalId,
    ProposalType proposalType,
    bytes parameters
);

event VoteCast(
    uint256 indexed proposalId,
    address indexed voter,
    bool support,
    uint256 weight
);

event ProposalExecuted(uint256 indexed proposalId);

---

Access Control

Purpose: Role-based access control

Roles

bytes32 public constant ISSUER_ROLE = keccak256("ISSUER_ROLE");
bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE");
bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

Implementation

Use OpenZeppelin's AccessControl or similar:

• Role assignment

• Role revocation

• Role checking

---

Pausable (Optional)

Purpose: Emergency pause mechanism

Functions

pause

function pause() external onlyRole(PAUSER_ROLE);

unpause

function unpause() external onlyRole(PAUSER_ROLE);

Integration

• Add whenNotPaused modifier to critical functions

• Allows emergency halt of operations

---

Critical Enforcement Rules

• No Issuance Beyond Cap

require(issued[tokenId] + amountUnits <= cap[tokenId], "Exceeds cap");

• No Retirement Beyond Balance

require(balanceOf(msg.sender, tokenId) >= amountUnits, "Insufficient balance");

• Credits Segregated Per Project

  • Enforced by tokenId separation

  • Credits of Project A ≠ Credits of Project B

• Project Cannot Be Issued Without PoAI

require(
    projectRegistry.isPoAIApproved(projectId),
    "PoAI not approved"
);

• Retirement is Irreversible

  • Credits are burned (cannot be unminted)

  • Retirement events are permanent

---

Contract Interactions

Project Onboarding Flow

1

Governance → ProjectRegistry.mintProjectRecord()

2

Governance → CarbonCredit1155.setProjectConfig()

3

Issuer → CarbonCredit1155.mintCredits()

Retirement Flow

1

User → CarbonCredit1155.retire()

2

Event: CreditsRetired

3

Indexer → Certificate Generation

Governance Flow

1

Proposer → Governance.createProposal()

2

Voters → Governance.vote()

3

Executor → Governance.executeProposal()

4

Execution → Contract Function Calls

---

Security Considerations

Reentrancy Protection

• Use nonReentrant modifier

• Checks-effects-interactions pattern

Integer Overflow Protection

• Use Solidity 0.8+ (built-in overflow protection)

• Or use SafeMath library

Access Control

• Role-based access

• Multi-sig for critical operations (optional)

Upgradeability

• Consider upgradeable contracts (Proxy pattern)

• Or immutable contracts (simpler, more secure)

---

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