CarbonCreditNFT

Inherits: ERC721URIStorage, ERC721Enumerable, AccessControl, Pausable, ReentrancyGuard (OpenZeppelin 4.x) Token: name Carbonized Credit, symbol CBZ.

Each token is one carbon credit. Metadata is stored onchain in the CarbonCredit struct. Retiring a credit stores a certificate and burns the NFT.

Constructor

constructor() takes no parameters. The deployer receives DEFAULT_ADMIN_ROLE, PAUSER_ROLE and ISSUER_ADMIN_ROLE, and ISSUER_ROLE's role admin is set to ISSUER_ADMIN_ROLE. No other role is granted. On mainnet the deployer should grantRole all three to a multisig and renounce its own.

Roles

Data structures

struct CarbonCredit {
    string  projectId;
    string  projectName;
    string  methodology;        // e.g. "ICM_COMPLIANCE", "VERRA_VCS", "GOLD_STANDARD"
    uint256 co2Tonnes;          // 18 decimals: 1e18 = 1 tonne
    uint256 vintageYear;
    string  geography;
    bytes32 oracleProofHash;
    string  satelliteDataCID;
    address verificationSource; // msg.sender of the mint (the issuer)
    uint256 verificationDate;
    bool    isRetired;
    uint256 issuanceDate;
    string  serialNumber;       // external registry serial, mandatory
}

struct RetirementCertificate {
    uint256 originalTokenId;
    address retiredBy;
    uint256 retirementDate;
    string  retirementReason;
    uint256 co2Tonnes;
}

// declared at file level, used by batchMint
struct CreditData {
    string projectName; string serialNumber; string methodology;
    uint256 co2Tonnes; uint256 vintageYear; string geography;
    bytes32 oracleProofHash; string satelliteDataCID; string tokenURI;
}

Public state

Minting

mintCredit(...) returns uint256 tokenId

external, onlyRole(ISSUER_ROLE), whenNotPaused, nonReentrant.

Validation (shared by mintCredit and every item of batchMint):

Double-counting key. The serial is trimmed of ASCII whitespace, upper-cased (a-z) and hashed with abi.encode. The free-form methodology label is not part of the key, so the same serial cannot be tokenized again under another label. Serials should carry the registry prefix (for example VCS-12345). isSerialTokenized(methodology, serial) ignores its first argument and is kept for ABI compatibility.

Effects: increments the token counter, writes the struct (verificationSource = msg.sender), marks the serial used, updates stats and projectCredits, emits CreditMinted and SerialNumberRegistered, then _safeMint and sets the URI. State is written before the receiver callback and the function is nonReentrant.

batchMint(address to, string projectId, CreditData[] credits_) returns uint256[]

Same role and modifiers. Size must be 1 to 100 (Invalid batch size). Every item goes through the same validation and emits the same events as mintCredit, plus one CreditBatchMinted(tokenIds, projectId, totalTonnes) for the batch. One batch has a single recipient and a single projectId. Cost is about 0.49M gas per credit, so 100 credits would exceed the roughly 16.7M gas transaction limit of the target chain: the web app's Issuer page sends at most 25 credits per transaction. A reverting item reverts the whole batch.

Retirement

retireCredit(uint256 tokenId, string reason)

external, nonReentrant. The burn goes through _beforeTokenTransfer, which is whenNotPaused, so it reverts while the contract is paused.

Sets isRetired, writes the certificate, increments totalRetiredTonnes and userRetiredTonnes, decrements totalActiveCredits, emits CreditRetired, then _burns the token. A credit wrapped into a CCT is owned by the token contract, so it must be unwrapped before it can be retired.

The reason is free text chosen by the caller: it is a self-declared, unverified beneficiary statement and is public and permanent.

batchRetire(uint256[] tokenIds, string reason)

Same checks per token (Not owner, Already retired, Credit not initialised), 1 to 50 ids (Invalid batch size). The reason is not required to be non-empty here. Emits one CreditRetired per token.

Views

Burned credits can no longer be read with getCreditDetails, but credits(tokenId) and retirementCertificates(tokenId) still return the stored data.

Issuer administration

ISSUER_ROLE is administered by a dedicated role, ISSUER_ADMIN_ROLE, not by DEFAULT_ADMIN_ROLE. The constructor calls _setRoleAdmin(ISSUER_ROLE, ISSUER_ADMIN_ROLE), so only holders of ISSUER_ADMIN_ROLE can grantRole / revokeRole for ISSUER_ROLE. DEFAULT_ADMIN_ROLE administers ISSUER_ADMIN_ROLE itself, so the multisig can always re-point issuer administration.

The deployer receives ISSUER_ADMIN_ROLE in the constructor. Deployment scripts must hand ISSUER_ADMIN_ROLE to the multisig and renounce it from the deployer, otherwise the deployer keeps issuer-admin power. ISSUER_ADMIN_ROLE is never given to the governance timelock: issuance stays off-governance.

Admin

Events

Plus the standard ERC-721 Transfer, Approval, ApprovalForAll, and Paused/Unpaused/RoleGranted/RoleRevoked.

Size

The contract is large but under the EIP-170 limit of 24,576 bytes: the design document for the token stack records a runtime size of 19,616 bytes for the current source (compiler 0.8.20, viaIR, optimizer runs 1). Local Hardhat networks disable the contract-size limit (allowUnlimitedContractSize), so check the size with the project's size task and confirm the target chain accepts the bytecode before deploying. See Known limitations and security notes.