Contract Categories

Overview

The Carrot Network's smart contracts are organized into five categories, each with a distinct responsibility. This modular design keeps individual contracts focused and auditable, while the ContractRegistry ties them together at runtime.

Controllers

Controllers are the entry points for all major operations. They orchestrate complex workflows that span multiple contracts, ensuring that each operation is executed atomically — either every step succeeds or none of them do.

InventoryManager

Creates the foundational on-chain assets. When verified data is ready for tokenization, the InventoryManager mints MassID NFTs, Certificate NFTs, and Credit tokens in a single coordinated operation. It also registers the relationships between these assets through the CertificateRegistry. All minted assets are deposited into the Vault.

CreditPurchaseManager

Executes atomic credit purchases. In a single transaction, the CreditPurchaseManager:

• Validates the purchase order using an EIP-712 typed data signature
• Processes payment in USDC
• Updates the backing certificate records
• Transfers credit tokens to the buyer
• Mints a CreditPurchaseReceipt as permanent proof
• Records reward allocations for participants

The CreditPurchaseManager also supports integrated retirement — purchasing and retiring credits in one transaction, which avoids the need for a separate retirement step.

CreditRetirementManager

Handles standalone credit retirement for holders who want to permanently remove credits from circulation. The CreditRetirementManager burns the credit tokens, updates the backing certificate tracking, and mints a CreditRetirementReceipt as permanent proof of the retirement.

Custodians

Custodians hold and manage assets on behalf of the network. They enforce strict access controls — only authorized contracts (controllers) can transfer or burn assets from custody.

Vault

The central custodian for all soulbound NFTs (MassIDs, Certificates, CreditPurchaseReceipt and CreditRetirementReceipt NFTs) and credit token balances before purchase. The Vault is the permanent home for every non-transferable token in the system, ensuring they remain immutable and traceable. Credit tokens are also held here as available inventory until a buyer purchases them.

RewardsVault

Manages the privacy-preserving rewards distribution system. During credit purchases, USDC payments are deposited into the RewardsVault, and cryptographic commitments (Merkle roots) representing the rewards distribution are committed on-chain. This keeps participant identities and individual reward details private — only hashed commitments are stored publicly. Participants claim their rewards by providing Merkle proofs that are verified against the stored roots. The RewardsVault holds USDC allocated for rewards until participants claim them.

NFTs (Soulbound ERC-721)

All NFTs in the Carrot Network are soulbound — non-transferable and permanently held by the Vault. This ensures an immutable, tamper-proof audit trail. No NFT can be moved, sold, or hidden after minting.

MassID

Represents a verified batch of waste material. Each MassID records the material type, weight, and full chain of custody from waste generation through collection and sorting. MassIDs are the foundation of the token hierarchy — every certificate traces back to a single MassID.

Certificate

Represents a verified environmental outcome — either recycling (RecycledID) or carbon avoidance (GasID). Certificates are linked to their parent MassIDs via the CertificateRegistry and track their lifecycle through four quantities: the total amount (set at minting), the purchased amount (updated at each sale), the retired amount (updated at each retirement), and the available amount (derived from the other three). This accounting model is central to preventing double-counting — the contract enforces that credits cannot be sold or retired beyond the available balance.

CreditPurchaseReceipt

Immutable proof that a credit purchase occurred. Each receipt records which certificates were involved, the buyer's address, the amount purchased, and the payment details. Purchase receipts are visible in the Carrot Explorer and provide a permanent record for compliance and reporting.

CreditRetirementReceipt

Permanent proof that credits were retired (burned). Retirement receipts record the certificates involved, the amount retired, and the retiring party. They are used for ESG reporting and regulatory compliance, and are viewable through the Carrot Explorer or any blockchain block explorer (e.g. PolygonScan).

Tokens (Fungible ERC-20)

Credit

Fungible environmental credit tokens. The Carrot Network issues two credit types:

Credits are the only transferable tokens in the system. They are designed for market activity — purchasing, holding, and retiring environmental offsets. All other tokens (MassIDs, certificates, receipts) are soulbound and cannot be transferred. The credit system is designed to support additional credit types beyond the current C-BIOW and C-CARB.CH4 as new environmental methodologies are validated.

Registries

Registries provide the infrastructure for contract coordination and relationship tracking. They contain no business logic themselves but are essential to the system's upgradeability and traceability.

ContractRegistry

The central registry that maps logical contract names to their deployed addresses on-chain. Instead of hardcoding addresses, contracts query the ContractRegistry to discover each other at runtime. This is key to the upgradeability model — when a contract is upgraded to a new implementation, only the registry entry needs to change. All dependent contracts automatically discover the new address without redeployment.

CertificateRegistry

Tracks the parent-child relationship between MassID tokens and their linked certificates. Every certificate can be traced back to the specific waste batches it represents through this registry. The CertificateRegistry is what makes end-to-end traceability possible — from a retired credit, through its certificate, all the way back to the physical waste.

Token relationships

The on-chain assets form a directed graph of relationships:

• MassID → Certificate — Linked via the CertificateRegistry. One or more MassIDs back each certificate.
• Certificate → Credit — Credit tokens are generated at minting time in amounts corresponding to their backing certificates.
• CreditPurchaseReceipt and CreditRetirementReceipt — Record transactions against specific certificates, providing the audit trail for every purchase and retirement.

This structure ensures that every credit in circulation can be traced back through its certificate to the specific waste batches that produced it.

Next steps

• On-Chain Flows — Step-by-step walkthrough of how these contracts interact during minting, purchasing, and retirement.
• Security — Access control, pausability, and governance protections.
• Token Hierarchy — The MassID → Certificate → Credit lifecycle.