Contract Architecture Overview

Why blockchain

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

• Immutability — Once a credit is minted, its provenance data cannot be altered or deleted. Every issuance, purchase, and retirement is permanently recorded on-chain, while protocol-level contract logic (single-use checks, token burning 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 Explorer 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 — Tokenized assets and every credit lifecycle event (minting, purchase, retirement) exist on-chain. Together with platform data in the Carrot Explorer, 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 minting, 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 and stored data remain the same — only the logic changes. 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: when a contract is upgraded to a new implementation, only the registry entry needs to change. All other contracts automatically discover the new version through the registry, without any redeployment of their own. This means individual contracts can be improved, patched, or extended without requiring 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. Every MassID, certificate, purchase receipt, and retirement receipt remains exactly where it was created, forming an unbreakable chain of evidence.

Meta-transactions

The system supports gas-less transactions through meta-transaction relayers. This means end users do not need to hold cryptocurrency or pay blockchain transaction fees — the relayer submits transactions on their behalf, removing a significant barrier to adoption for non-crypto-native buyers.

Role-based access control

Every contract implements RBAC with defined roles for day-to-day operations, upgrades, and emergency actions. No single account can perform all operations. This separation of duties ensures that even if one key is compromised, the damage is contained.

Pausability

Critical operations can be paused in emergencies to halt all activity while a vulnerability or incident is investigated. Emergency pauses auto-expire after 48 hours to prevent indefinite lockouts — ensuring the network cannot be permanently frozen, even in worst-case scenarios. See Security for the full access control and pausability model.

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.