🌿 CarbonChain — Decentralized Carbon Credit Marketplace

A blockchain-based platform for small businesses to mint, trade, and retire verified carbon credits as ERC-721 NFTs on Ethereum. Built with Solidity, Hardhat, and React.

---

🧠 Why This Project?

Carbon credits represent verified reductions in CO₂ emissions — but traditional systems are opaque, slow, and prone to double-counting. CarbonChain solves this by putting the entire lifecycle of a carbon credit on-chain:

• Each credit is minted as an ERC-721 NFT — ownership is transparent and immutable
• Businesses can trade credits peer-to-peer through a decentralized marketplace
• Retired credits are permanently locked at the smart-contract level — mathematically impossible to re-trade or double-count
• A small 1% platform fee is collected on each sale to sustain the protocol

---

🚀 Key Features

📊 Dashboard

• View your full carbon credit portfolio at a glance
• Platform-wide stats: total credits issued, total CO₂ offset, active listings

🏷️ Marketplace — The Living Ledger

• Browse all verified carbon credits listed for sale as NFTs
• Filter by price range or search by project name / ID
• Buy any listing by sending ETH directly — no intermediary

💼 My Credits

• View all credits you own
• List a credit for sale at any price
• Cancel an active listing
• Permanently retire a credit — locks it forever, preventing double-counting

🏭 Issue Credit (ISSUER_ROLE only)

• Mint new verified carbon credits with project metadata
• Live NFT card preview before minting

---

🛠️ Tech Stack

Layer	Technology
Smart Contracts	Solidity 0.8.28, OpenZeppelin v5
Local Blockchain	Hardhat 2.22
Frontend	React 18 + Vite 5
Wallet Integration	ethers.js v6 + MetaMask
Styling	Vanilla CSS (dark glassmorphism)

---

🏗️ Project Structure

CarbonChain/
├── contracts/
│   ├── CarbonCredit.sol        # ERC-721 NFT with mint / retire / status logic
│   └── CarbonMarketplace.sol  # P2P marketplace — list / buy / cancel
├── scripts/
│   └── deploy.js              # Deploy + seed 3 demo listings automatically
├── frontend/
│   └── src/
│       ├── contexts/          # WalletContext (MetaMask + ethers.js)
│       ├── components/        # Navbar, CreditCard, ListingCard, Toast
│       ├── pages/             # Dashboard, Marketplace, MyCredits, Issue
│       └── contracts/         # ABI + address files (auto-generated on deploy)
├── hardhat.config.js
└── package.json

---

📋 Prerequisites

• Node.js v18 or later — nodejs.org
• MetaMask browser extension — metamask.io
• Git

---

⚡ Quick Start

1. Clone the Repository

git clone https://github.com/AnkeshGG/CarbonChain.git
cd CarbonChain

2. Install Dependencies

# Root (Hardhat + contracts)
npm install

# Frontend
cd frontend && npm install && cd ..

3. Compile Contracts

npm run compile

4. Start the Local Blockchain

Open Terminal A and keep it running:

npx hardhat node

This starts a local EVM at http://127.0.0.1:8545 and prints 20 test accounts (each with 10,000 test ETH).

5. Deploy Contracts + Seed Demo Data

Open Terminal B:

npm run deploy

This deploys both contracts, mints 3 demo carbon credits, lists them on the marketplace, and writes the ABIs + addresses to frontend/src/contracts/ automatically.

Demo listings created:

#	Project	CO₂	Verifier	Price
#0001	Amazon Reforestation 2024	100 tCO₂e	Verra	0.05 ETH
#0002	Nordic Boreal Shield Protection	200 tCO₂e	Gold Standard	0.12 ETH
#0003	Mangrove Coast Marine Restoration	75 tCO₂e	Plan Vivo	0.08 ETH

6. Start the Frontend

Open Terminal C:

cd frontend
npm run dev

Open http://localhost:5173 in your browser.

---

🦊 MetaMask Setup

Add the Hardhat Localhost Network

In MetaMask → Network dropdown → Add a custom network:

Field	Value
Network Name	Hardhat Localhost
RPC URL	http://127.0.0.1:8545
Chain ID	31337
Currency Symbol	ETH

Import a Test Account (Buyer)

In MetaMask → Account icon → Import Account → paste this private key:

0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d

This is Hardhat Account #1 — pre-funded with 10,000 test ETH. It is NOT the seller, so you can buy listings for demonstration.

⚠️ These are publicly known test keys. Never use them on Mainnet or send real ETH to these addresses.

Connect

Click Connect Wallet in the app header — the 3 demo listings will appear instantly on the Marketplace page.

---

📜 Smart Contract Overview

CarbonCredit.sol

• ERC-721 NFT where each token represents 1 verified carbon credit
• Role-based access: DEFAULT_ADMIN_ROLE, ISSUER_ROLE (via OpenZeppelin AccessControl)
• Credit lifecycle: Active → Listed → Active (tradeable) or → Retired (permanent)
• Retired credits are blocked at the transfer level — impossible to move or re-retire

CarbonMarketplace.sol

• Fixed-price peer-to-peer listings; only token owners can list
• 1% platform fee sent to the fee recipient on every sale
• Reentrancy-protected via OpenZeppelin ReentrancyGuard
• Automatically resets credit status back to Active after a successful purchase

---

🔄 Resetting the Demo

Because this runs on a local Hardhat node, you can reset the entire blockchain to a clean state in seconds:

# Terminal A — restart the blockchain
Ctrl+C
npx hardhat node

# Terminal B — redeploy fresh contracts + listings
npm run deploy

Then in MetaMask: Settings → Advanced → Reset Account (clears nonce cache).

---

🧪 Running Tests

npm test

The test suite covers:

• Credit minting with valid / invalid parameters
• Role enforcement (only ISSUER_ROLE can mint)
• Credit retirement and double-retirement prevention
• Transfer blocking for retired credits
• Marketplace listing, buying, and cancellation
• Fee calculation and distribution
• Edge cases (zero price, wrong caller, already listed)

---

📝 Available Scripts

# Root
npm run compile   # Compile Solidity contracts
npm run node      # Start local Hardhat blockchain
npm run deploy    # Deploy contracts to localhost + seed demo data

# Frontend
cd frontend
npm run dev       # Start Vite dev server → http://localhost:5173
npm run build     # Production build → frontend/dist/

---

🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit your changes
4. Push: git push origin feature/your-feature
5. Open a Pull Request

Guidelines

• Follow Solidity best practices and add NatSpec comments to new functions
• Ensure all 17 existing tests pass before submitting a PR
• For frontend changes, test both connected and disconnected wallet states

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

👨‍💻 About

Ankesh Kumar

Built to explore the intersection of blockchain transparency and real-world environmental impact — demonstrating how smart contracts can eliminate double-counting in carbon credit markets.

Connect

• 🌐 GitHub: @AnkeshGG
• 💼 LinkedIn: Ankesh Kumar

---

🙏 Acknowledgements

• OpenZeppelin — Battle-tested ERC-721 and AccessControl implementations
• Hardhat — Seamless local Ethereum development environment
• Verra / Gold Standard / Plan Vivo — Real-world carbon credit verification standards that inspired the project's data model
• ethers.js — Clean and modern Ethereum library for the React frontend

---

📊 Project Status

🟢 Active

• Version: 1.0.0
• Smart Contracts: Fully deployed and verified locally
• Network: Hardhat Localhost (Chain ID 31337)

---

Immutable provenance. Zero double-counting. Verified on-chain. 🌿