Contract Architecture Overview

Why the registry runs on a public blockchain

The Carrot Network records every environmental credit on a public blockchain to guarantee three properties that traditional databases cannot:

• Immutability — Every issuance, purchase, and retirement is permanently recorded on-chain, and provenance metadata is content-addressed on IPFS, where continued availability depends on active pinning. A token's metadata pointer can be corrected by governance, and MassIDs and certificates can be revoked — in both cases the change is itself recorded on-chain. Protocol-level contract logic (single-use checks and permanent destruction on retirement) prevents double-counting.
• Transparency — All transactions are publicly verifiable on the blockchain. Anyone can inspect the complete history of a credit via the Carrot Registry or any blockchain block explorer (e.g. PolygonScan), without requiring special access or credentials. Trust and verification do not depend on Carrot's infrastructure.
• Auditability — Registry records and every credit lifecycle event (issuance, purchase, retirement) exist on-chain. Together with platform data in the Carrot Registry, the full chain from physical waste to retired credit is traceable. Auditors, regulators, and stakeholders can independently verify the lifecycle without relying on a single party's records.

Deployment

The Carrot Network's smart contracts are implemented in Solidity and compatible with any EVM-compatible blockchain. They are currently deployed on Polygon PoS, which was selected for its low transaction costs and full EVM compatibility, allowing the network to process high volumes of registry-record creation, purchasing, and retirement operations without prohibitive gas fees while maintaining compatibility with the broader Ethereum ecosystem. The platform is blockchain network agnostic and could deploy on other EVM-compatible networks in the future.

Architecture overview

The smart contract ecosystem follows a modular architecture organized into five contract categories. Each category has a well-defined responsibility, and contracts interact through well-defined interfaces rather than monolithic logic.

This separation keeps each contract focused and auditable. Controllers contain the business logic, custodians manage asset custody, and NFTs and tokens represent the assets themselves. Registries provide the infrastructure that ties everything together.

Design principles

Upgradeability (UUPS)

All contracts use the Universal Upgradeable Proxy Standard (UUPS), allowing the protocol to evolve without losing state or requiring redeployment. When a contract is upgraded, its address stays the same and its stored data carries over — the logic changes, and the upgrade call can also run a migration against that existing storage. This enables the team to fix bugs, add features, and improve efficiency while preserving the integrity of the on-chain record.

Registry-based discovery

Contracts locate each other through the ContractRegistry using logical keys rather than hardcoded addresses. This decouples contracts from each other and enables independent upgrades. A logic upgrade keeps the proxy address, so no registry change is needed and every peer keeps resolving the same entry. The registry matters when a contract is replaced by a new proxy: updating that single registry entry repoints every peer without redeploying any of them. Either way, individual contracts can be improved, patched, or extended without a system-wide redeployment.

Soulbound NFTs

All NFTs in the Carrot Network are soulbound — non-transferable and permanently held by the Vault contract. This preserves the integrity of the environmental audit trail — tokens cannot be moved, sold, or hidden. A MassID or certificate can be burned by revocation; every issuance, transfer attempt, and revocation stays in the on-chain event log, so the chain of evidence survives the token.

Meta-transactions

Buyers never need to hold the network's native gas token or pay blockchain transaction fees — Carrot submits purchase and retirement transactions on their behalf, removing a significant barrier to adoption for buyers new to blockchain. The credit purchase and retirement contracts implement the ERC-2771 meta-transaction standard, so this can also be delegated to a trusted relayer.

Role-based access control

Every contract implements RBAC with defined roles for day-to-day operations, upgrades, and emergency actions. The five roles are assigned to five distinct addresses, so routine operation requires more than one key. See Security for what that separation does and does not guarantee.

Pausability

Critical operations can be paused in emergencies, halting every balance movement across the contract while a vulnerability or incident is investigated. Emergency pauses carry a 48-hour expiry, after which any account can lift them. Standard pauses, held by a separate pauser role, persist until explicitly lifted. See Security for the full access control and pausability model, including how an ongoing incident is held open past that window.

Next steps

• Contract Categories — Detailed breakdown of each contract and its role in the system.
• On-Chain Flows — Step-by-step walkthrough of minting, purchasing, rewards, and retirement.
• Security — Access control, governance security, and anti-manipulation mechanisms.