On-Chain Flows

Overview

The Carrot Network's smart contracts execute five major on-chain flows. Each flow is designed to be atomic — either every step completes successfully or none of them do, preventing partial state changes.

All transactions are recorded on-chain and visible through any blockchain block explorer (e.g., PolygonScan). The main operations are also reflected in the Carrot Explorer with environmental context and traceability data.

Minting

When verified data is ready for tokenization, the InventoryManager creates the foundational on-chain assets in a coordinated operation.

Step 1 — MassID minting

MassID NFTs are minted to the Vault, each with an IPFS metadata URI containing provenance data: material type, weight, geographic origin, and the full chain of custody from waste generation through collection and sorting.

Step 2 — Certificate and credit minting

Certificate NFTs are minted and linked to their parent MassIDs via the CertificateRegistry. Corresponding credit tokens (ERC-20) are minted in matching amounts and deposited into the Vault.

After minting, all assets are held by the Vault and ready for credit purchases. The CertificateRegistry records which MassID backs each certificate, establishing the traceability chain that persists for the lifetime of those assets.

Credit purchase

An atomic transaction executed by the CreditPurchaseManager that handles the entire purchase in a single operation. If any step fails, the entire transaction reverts.

Step 1 — Purchase signature validation

The purchase order is verified using an EIP-712 typed data signature from an authorized signer. This cryptographic validation ensures that only legitimate, pre-approved purchase orders are executed on-chain.

Step 2 — Payment

USDC is transferred from the payer to the RewardsVault, where it becomes available for rewards distribution to participants.

Step 3 — Certificate update

The purchased amount is recorded on each backing certificate, reducing the available inventory. This ensures that the same credits cannot be sold twice.

Step 4 — Credit transfer

Credit tokens (e.g. C-BIOW, C-CARB.CH4) are transferred from the Vault to the buyer's wallet address. At this point, the buyer holds fungible credit tokens that they can hold or retire.

Step 5 — Receipt minting

A CreditPurchaseReceipt NFT is minted to the Vault as permanent, immutable proof of the transaction. The receipt records the certificates involved, the buyer, the amount, and the payment details.

Step 6 — Rewards recording

A Merkle root representing the complete rewards distribution is recorded in the RewardsVault. This enables participants to claim their share of the payment without revealing participant details on-chain.

Integrated retirement

If the buyer opts for integrated retirement, the credits are burned (instead of transferred to the buyer) in the same transaction, and a CreditRetirementReceipt is also minted. This allows buyers to purchase and retire credits in a single step — useful for those who intend to immediately claim the environmental offset.

Rewards distribution

Rewards distribution uses a privacy-preserving mechanism that keeps individual participant identities off-chain while maintaining on-chain verifiability.

Recording

During each credit purchase, a Merkle root is committed on-chain in the RewardsVault. This root represents the complete rewards distribution for that transaction. Participant identities are anonymized — only hashed commitments are stored publicly on-chain. The underlying distribution data is maintained off-chain by the backend.

Claiming

Participants can claim their rewards by providing Merkle proofs that verify their entitlement against the on-chain root. The RewardsVault validates the proof and releases the allocated USDC to the claimant. Each allocation can only be claimed once — the contract tracks claimed status to prevent double-claiming.

Auditability

While individual participant identities are not visible on-chain, authorized auditors can access the underlying distribution data to identify participants for compliance purposes. The on-chain Merkle roots serve as cryptographic commitments that the off-chain data has not been tampered with.

Credit retirement (standalone)

For credit holders who want to retire credits they already own, the CreditRetirementManager executes a standalone retirement flow.

Step 1 — Retirement signature validation

The retirement order is verified using an EIP-712 typed data signature, ensuring only authorized retirement requests are processed.

Step 2 — Credit burning

Credit tokens are burned (permanently destroyed) from the holder's balance. Burned tokens can never be recovered or re-issued — the environmental offset is permanently claimed.

Step 3 — Certificate tracking

The retired amounts are recorded on the backing certificates, updating their retirement totals. This maintains accurate accounting across the certificate layer.

Step 4 — Receipt minting

A CreditRetirementReceipt NFT is minted to the Vault as permanent proof of the retirement. This receipt is the definitive on-chain evidence that the credits were retired.

Retired credits are recorded on the blockchain and visible through the Carrot Explorer, providing transparent, auditable evidence that the environmental offset has been claimed and cannot be double-counted.

Revocation

Assets can be revoked when underlying data is found to be incorrect or fraudulent. Revocation is a protective mechanism that preserves the credibility of the Carrot Network's environmental claims.

MassID revocation

Revoking a MassID triggers a cascading revocation:

• All certificates linked to the revoked MassID are automatically revoked.
• Any unsold credits backed by those certificates are burned.
• Protection: Revocation is blocked if any credits from the linked certificates have already been sold. This prevents retroactively invalidating credits that buyers have already purchased in good faith.

Certificate revocation

Individual certificates can be revoked independently without affecting the parent MassID or sibling certificates. This allows targeted corrections when only specific environmental claims need to be invalidated.

• As with MassID revocation, certificate revocation is blocked if credits from that certificate have already been sold.

Audit trail preservation

Revocation preserves the complete audit trail. The original IPFS metadata for revoked assets remains accessible, and the revocation reason is recorded on-chain. This ensures that even revoked assets can be examined by auditors and regulators — nothing is hidden or deleted, only marked as invalid.

Next steps

• Contract Categories — Detailed breakdown of each contract involved in these flows.
• Security — How access control, pausability, and governance protect these operations.
• Purchasing Credits — The buyer perspective on credit purchases.
• Retiring Credits — How and why credits are permanently retired.