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 minting, the InventoryManager mints MassID NFTs, and then Certificate NFTs and Credit tokens in a second transaction, at the moment the credit is issued from the verified batch. 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 — for purchases that are not fully retired in the same transaction
• Mints a CreditPurchaseReceipt as permanent proof
• Records reward allocations for participants

The CreditPurchaseManager supports integrated retirement — purchasing and retiring credits in one transaction — and this is the path in use today: every purchase is currently retired in full at the moment of sale, so credits are burned rather than delivered to the buyer. The contracts also support partial retirement, with the remainder transferred to the buyer, which is not yet used in production.

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 permanent and traceable, except where revoked. 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 pseudonymous — only a purchase-scoped hash is stored on-chain, and the hashes on their own cannot be correlated across purchases. The claiming wallet and the amount become visible on-chain when the reward is withdrawn, so reusing one wallet links a participant's withdrawals to each other. 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. No NFT can be transferred, sold, or traded. The only exception is revocation — an operator can burn a MassID or Certificate and point its metadata at a revocation record when the underlying data is found to be incorrect; the original metadata and the reason stay recoverable on-chain.

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 credit lifecycle — every certificate traces back to a single MassID.

Certificate

Represents a verified environmental outcome — either recycling (RecycledID) or carbon emission reductions (GasID). Certificates are linked to their parent MassID 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 at read time as total minus purchased; the retired amount does not affect it. This accounting model is central to preventing double-counting — the contract enforces that credits cannot be sold beyond the available balance, and cannot be retired beyond the amount that was actually purchased.

CreditPurchaseReceipt

Tamper-evident 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 Registry 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 Registry 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 decouples contracts from each other's addresses. An ordinary logic upgrade needs no registry change at all — the proxy address is stable, so dependents keep resolving the same entry. The registry matters when a contract is fully replaced with a new proxy: that takes one registry write plus explicit state migration, instead of redeploying every dependent contract.

CertificateRegistry

Tracks the parent-child relationship between MassID tokens and their linked certificates. Every certificate can be traced back through this registry to the specific waste batch it represents. 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. A single MassID can back several certificates; each certificate is backed by exactly one MassID.
• 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 batch 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.
• Credit Lifecycle — The MassID → Certificate → Credit lifecycle.