On-Chain Flows

Overview

The Carrot Network's smart contracts execute five major on-chain flows. Every transaction is atomic — either every step completes successfully or none of them do, preventing partial state changes. Minting spans two transactions by design, because they happen at different moments: a MassID is minted before any certificate from it, and a certificate is minted together with its credits. Carrot mints certificates as inventory is needed, not all at once, so a certificate published in the Carrot Registry may not be on-chain yet.

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 Registry with environmental context and traceability data.

Minting

The InventoryManager creates the foundational on-chain assets in two steps, each its own transaction.

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 chain of custody from waste generation through collection and sorting, as cleared for publication (see Privacy & Masking).

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 delivery or retirement

Today every purchased credit is retired in the same transaction, so no credit tokens are delivered to the buyer's wallet. The contracts also support partial retirement, with credit tokens (e.g. C-BIOW, C-CARB.CH4) transferred from the Vault to the buyer's wallet for the remainder — a capability that is not yet used in production.

Step 5 — Receipt minting

A CreditPurchaseReceipt NFT is minted to the Vault as permanent, tamper-evident 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

With integrated retirement, the credits are burned (instead of transferred to the buyer) in the same transaction, and a CreditRetirementReceipt is also minted. This is how every purchase works today: buyers acquire and retire credits in a single step, and claim the environmental offset immediately.

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 stay pseudonymous — 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.

This flow is supported by the contracts but not yet used, because every purchase is retired when it settles.

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 Vault's own balance, not directly from the holder's wallet. The holder therefore transfers the credits to the Vault first, as an ordinary token transfer.

That deposit is a separate transaction, outside the atomic retirement described here: if the retirement order then fails, the deposit does not roll back with it, and the contracts expose no return path — only authorized controllers can move assets out of the Vault. Retry the retirement order rather than treating the credits as lost.

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 Registry, 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 does not cascade to its certificates:

• Linked certificates are not revoked automatically. Each certificate must be revoked on its own, before the MassID, to avoid leaving active certificates linked to a revoked MassID.
• Protection: A MassID cannot be revoked while any still-linked certificate has purchased credits — revoking it validates that every linked certificate would itself be revocable. This prevents retroactively invalidating credits that buyers have already purchased in good faith. Certificates that were already revoked are unlinked from the MassID by their own revocation, so they no longer block it.

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

Revoking an asset flags it as revoked, replaces its metadata URI with a revocation record, and burns the NFT — and for certificates, unlinks it from its parent MassID in the CertificateRegistry. The revoked flag stays permanently readable on-chain, and the revocation reason and the replacement metadata URI are readable in the revocation event, and the original metadata URI in the minting event. Auditors and regulators can still reconstruct the full history, even though the token itself no longer exists.

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.