🌾 AgriChain: Agricultural Supply Chain Smart Contract Platform

A production-ready blockchain solution for agricultural supply chain management with comprehensive traceability, secure payments, and quality assurance.

📋 Table of Contents

• Overview
• Key Features
• Architecture
• Supply Chain Flow
• Smart Contract Components
• Installation & Setup
• Usage
• Testing
• Deployment
• API Reference
• Security
• Contributing
• License

🌟 Overview

AgriChain is an enterprise-grade blockchain platform designed specifically for agricultural supply chain management. Built on Ethereum with Hardhat framework and OpenZeppelin security standards, it provides end-to-end traceability from farm to consumer with advanced features including escrow payments, dispute resolution, reputation systems, and comprehensive quality assurance.

🎯 Business Value

• Complete Traceability: Track products from farm to consumer
• Financial Security: Escrow-based payments with dispute resolution
• Quality Assurance: Built-in expiration tracking and quality controls
• Trust Building: Reputation system for all participants
• Compliance Ready: IPFS metadata storage for certificates and documentation
• Scalable Operations: Batch processing for efficient management

🚀 Key Features

🔒 Security & Trust

• Reentrancy Protection: OpenZeppelin ReentrancyGuard implementation
• Role-Based Access Control: Secure permissions for farmers, distributors, retailers, consumers
• User Verification: Admin-controlled user verification system
• Emergency Controls: Pausable functionality for crisis management
• Input Validation: Comprehensive validation for all operations

💰 Financial Management

• Escrow Payments: Secure multi-party payment system
• Dispute Resolution: Built-in arbitration with multiple resolution options
• Automatic Refunds: Timeout-based refund mechanisms
• Price Validation: Configurable price ranges and validation
• Gas Optimization: Efficient contract design for cost-effective operations

🏆 Reputation & Quality

• 5-Star Rating System: Comprehensive user rating mechanism
• Transaction History: Success/failure tracking for reputation building
• Quality Assurance: Expiration tracking and deadline management
• Review Verification: Admin-verified review system
• Reputation Levels: Automated reputation scoring algorithm

⚡ Performance & Scalability

• Batch Operations: Process up to 50 products simultaneously
• IPFS Integration: Off-chain metadata storage for cost efficiency
• Gas Optimization: Packed structs and efficient storage patterns
• Event Optimization: Minimal gas cost event emission
• Cross-chain Ready: Designed for future multi-chain deployment

🏗️ Architecture

graph TB
    subgraph "AgriChain Platform"
        SC[SupplyChain Contract]
        E[Escrow Contract]
        R[Reputation Contract]
        AR[Access Control Roles]
    end

    subgraph "Frontend Application"
        FE[Next.js Frontend]
        UI[shadcn/ui Components]
        WEB3[Web3 Integration]
    end

    subgraph "Participants"
        F[Farmer]
        D[Distributor]
        RT[Retailer]
        C[Consumer]
        A[Arbitrator]
    end

    subgraph "External Systems"
        IPFS[IPFS Storage]
        BC[Blockchain Network]
        MM[MetaMask Wallet]
    end

    F --> SC
    D --> SC
    RT --> SC
    C --> SC
    A --> E

    SC --> E
    SC --> R
    SC --> AR

    SC --> IPFS
    SC --> BC
    FE --> SC
    FE --> WEB3
    WEB3 --> MM
    UI --> FE

    style SC fill:#e1f5fe
    style E fill:#f3e5f5
    style R fill:#e8f5e8
    style IPFS fill:#fff3e0

🔄 Supply Chain Flow

flowchart TD
    A[🌱 Farmer Produces Product] --> B[📝 Add IPFS Metadata]
    B --> C[💰 Set Price & List for Sale]
    C --> D[🛒 Distributor Purchases]
    D --> E[💸 Escrow Payment Created]
    E --> F[🚚 Farmer Ships Product]
    F --> G[📦 Distributor Receives]
    G --> H[⚙️ Distributor Processes]
    H --> I[📋 Distributor Packages]
    I --> J[💰 Distributor Lists for Sale]
    J --> K[🛒 Retailer Purchases]
    K --> L[💸 Escrow Payment Created]
    L --> M[🚚 Distributor Ships]
    M --> N[📦 Retailer Receives]
    N --> O[💰 Retailer Lists for Sale]
    O --> P[🛒 Consumer Purchases]
    P --> Q[💸 Escrow Payment Created]
    Q --> R[✅ Transaction Complete]

    style A fill:#e8f5e8
    style R fill:#e8f5e8
    style E fill:#fff3e0
    style L fill:#fff3e0
    style Q fill:#fff3e0

📦 Smart Contract Components

Core Components

Smart Contracts

Frontend Application

Contract Relationships

classDiagram
    class SupplyChain {
        +produceItemByFarmer()
        +sellItemByFarmer()
        +purchaseItemByDistributor()
        +processedItemByDistributor()
        +packageItemByDistributor()
        +sellItemByDistributor()
        +purchaseItemByRetailer()
        +sellItemByRetailer()
        +purchaseItemByConsumer()
        +createBatchOperation()
        +checkExpiredProducts()
    }

    class Escrow {
        +createEscrow()
        +releasePayment()
        +refundPayment()
        +openDispute()
        +resolveDispute()
        +addArbitrator()
    }

    class Reputation {
        +registerUser()
        +addReview()
        +verifyReview()
        +recordTransactionSuccess()
        +recordTransactionFailure()
        +getUserReputation()
        +calculateReputationLevel()
    }

    class FarmerRole {
        +addFarmer()
        +removeFarmer()
        +isFarmer()
    }

    class DistributorRole {
        +addDistributor()
        +removeDistributor()
        +isDistributor()
    }

    class RetailerRole {
        +addRetailer()
        +removeRetailer()
        +isRetailer()
    }

    class ConsumerRole {
        +addConsumer()
        +removeConsumer()
        +isConsumer()
    }

    SupplyChain --> Escrow : uses
    SupplyChain --> Reputation : uses
    SupplyChain --> FarmerRole : inherits
    SupplyChain --> DistributorRole : inherits
    SupplyChain --> RetailerRole : inherits
    SupplyChain --> ConsumerRole : inherits

🛠️ Installation & Setup

Prerequisites

• Node.js: v16.17.0 or higher
• Hardhat: v2.22.0 or higher
• Solidity: ^0.8.24
• Git: For version control

Quick Start

1. Clone the repository

   git clone https://github.com/your-org/agrichain-supply-chain.git
   cd agrichain-supply-chain

2. Install dependencies

   npm install

3. Compile contracts

   npm run compile

4. Start local Hardhat network

   npm run node

5. Deploy contracts (Localhost)

   npm run deploy:localhost

6. Deploy to Polygon Amoy (Testnet)

   # Set up environment variables
   cp .env.template .env
   # Edit .env with your private key and PolygonScan API key
   
   # Deploy to Amoy
   npm run deploy:amoy

7. Start frontend

   cd frontend
   npm install
   npm run dev

8. Open application

   http://localhost:3000

9. Run tests

   npm test

Frontend Configuration

After deploying contracts, update the frontend configuration:

For Amoy Testnet:

cd frontend
cp env.local.example .env.local
# Edit .env.local with Amoy contract addresses

For Localhost:

cd frontend
cp env.local.example .env.local
# Edit .env.local with localhost contract addresses

MetaMask Network Configuration:

• Network Name: Polygon Amoy
• RPC URL: https://rpc-amoy.polygon.technology/
• Chain ID: 80002
• Currency Symbol: MATIC
• Block Explorer: https://amoy.polygonscan.com/

Environment Configuration

Create a .env file in the root directory:

# Private key for deployment (without 0x prefix)
PRIVATE_KEY=your_private_key_here

# RPC URLs
AMOY_RPC_URL=https://rpc-amoy.polygon.technology/
POLYGON_RPC_URL=https://polygon-rpc.com
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_KEY
MAINNET_RPC_URL=https://mainnet.infura.io/v3/YOUR_INFURA_KEY

# Block Explorer API Keys
POLYGONSCAN_API_KEY=your_polygonscan_api_key
ETHERSCAN_API_KEY=your_etherscan_api_key

# Gas Reporting
REPORT_GAS=true

🌐 Deployed Contracts

Polygon Amoy Testnet (Live)

Network Details:

• Network: Polygon Amoy Testnet
• Chain ID: 80002
• RPC URL: https://rpc-amoy.polygon.technology/
• Block Explorer: https://amoy.polygonscan.com/

Localhost Development

📖 Usage

Basic Workflow

1. Farmer Operations

// Produce agricultural product
await supplyChain.produceItemByFarmer(
  0, // productCode (auto-generated)
  'QmHash123...', // IPFS hash for metadata
  ethers.parseEther('0.1'), // price
  Math.floor(Date.now() / 1000) + 86400 // shipping deadline
);

// List product for sale
await supplyChain.sellItemByFarmer(productCode, ethers.parseEther('0.15'));

// Ship product after purchase
await supplyChain.shippedItemByFarmer(productCode);

2. Distributor Operations

// Purchase from farmer
await supplyChain.purchaseItemByDistributor(productCode, {
  value: ethers.parseEther('0.15'),
});

// Receive and process product
await supplyChain.receivedItemByDistributor(productCode);
await supplyChain.processedItemByDistributor(productCode, 5); // 5 slices
await supplyChain.packageItemByDistributor(productCode);

// Sell to retailer
await supplyChain.sellItemByDistributor(productCode, ethers.parseEther('0.25'));

3. Retailer Operations

// Purchase from distributor
await supplyChain.purchaseItemByRetailer(productCode, {
  value: ethers.parseEther('0.25'),
});

// Receive and sell to consumer
await supplyChain.receivedItemByRetailer(productCode);
await supplyChain.sellItemByRetailer(productCode, ethers.parseEther('0.35'));

4. Consumer Operations

// Purchase final product
await supplyChain.purchaseItemByConsumer(productCode, {
  value: ethers.parseEther('0.35'),
});

Advanced Features

Batch Operations

// Create batch operation for multiple products
const productCodes = [1, 2, 3, 4, 5];
await supplyChain.createBatchOperation(productCodes);

Reputation Management

// Add review for a participant
await reputation.addReview(
  farmerAddress,
  5, // 5-star rating
  'Excellent quality produce!'
);

// Record successful transaction
await reputation.recordTransactionSuccess(farmerAddress);

Escrow Management

// Open dispute if needed
await escrow.openDispute(
  escrowId,
  'Product quality issue',
  { value: ethers.parseEther('0.01') } // arbitration fee
);

// Resolve dispute (arbitrator only)
await escrow.resolveDispute(escrowId, 1); // Resolution.Buyer

🧪 Testing

Test Coverage

The test suite includes comprehensive coverage for:

• ✅ Product Creation & Management (3 tests)
• ✅ Sale & Purchase Operations (3 tests)
• ✅ Complete Supply Chain Flow (1 test)
• ✅ Batch Operations (2 tests)
• ✅ Reputation System (3 tests)
• ✅ Escrow & Dispute Resolution (3 tests)
• ✅ Access Control (2 tests)
• ✅ Pause Functionality (1 test)

Total: 18 tests passing

Running Tests

# Run all tests
npm test

# Run specific test file
npx hardhat test test/SupplyChain.test.js

# Run with gas reporting
REPORT_GAS=true npm test

# Run with coverage
npx hardhat coverage

Test Results

SupplyChain
  Product Creation
    ✔ Should create a product successfully
    ✔ Should reject product creation with invalid price
    ✔ Should reject product creation with past deadline
  Product Sale and Purchase
    ✔ Should allow farmer to sell product
    ✔ Should allow distributor to purchase product with escrow
    ✔ Should reject purchase with insufficient payment
  Supply Chain Flow
    ✔ Should complete full supply chain flow
  Batch Operations
    ✔ Should create batch operation
    ✔ Should reject batch operation exceeding limit
  Reputation System
    ✔ Should add review
    ✔ Should verify review and update reputation
    ✔ Should record successful transaction
  Escrow System
    ✔ Should create escrow for purchase
    ✔ Should open dispute
    ✔ Should resolve dispute
  Access Control
    ✔ Should reject unauthorized user actions
    ✔ Should reject unverified user actions
  Pause Functionality
    ✔ Should pause and unpause contract

18 passing (747ms)

🚀 Deployment

Local Development

# Start local Hardhat node
npm run node

# Deploy to local network
npm run deploy:localhost

Testnet Deployment

# Deploy to Mumbai testnet
npm run deploy:mumbai

# Deploy to Sepolia testnet
npm run deploy:sepolia

Mainnet Deployment

# Deploy to Polygon mainnet
npm run deploy:polygon

# Deploy to Ethereum mainnet
npm run deploy:mainnet

Verification

Contracts are automatically verified on block explorers after deployment:

# Manual verification if needed
npx hardhat verify --network mumbai <CONTRACT_ADDRESS> <CONSTRUCTOR_ARGS>

📚 API Reference

SupplyChain Contract

Core Functions

Utility Functions

Escrow Contract

Reputation Contract

🔒 Security

Security Features

• Reentrancy Protection: OpenZeppelin ReentrancyGuard
• Access Control: Role-based permissions with verification
• Input Validation: Comprehensive parameter validation
• Emergency Controls: Pausable functionality
• Gas Optimization: Efficient storage and operations
• Audit Ready: Clean, well-documented code

Security Best Practices

1. Always verify user roles before allowing operations
2. Use escrow payments for high-value transactions
3. Implement proper access controls for admin functions
4. Monitor contract state for suspicious activities
5. Keep private keys secure and use hardware wallets
6. Regular security audits before mainnet deployment

Known Limitations

• IPFS Dependency: Requires IPFS for metadata storage
• Gas Costs: Ethereum mainnet gas costs can be high
• Scalability: Limited by blockchain throughput
• Off-chain Data: Some data stored off-chain for efficiency

🧪 Testing the Application

Test on Polygon Amoy

1. Add Amoy Network to MetaMask:

   • Network Name: Polygon Amoy
   • RPC URL: https://rpc-amoy.polygon.technology/
   • Chain ID: 80002
   • Currency Symbol: MATIC
   • Block Explorer: https://amoy.polygonscan.com/

2. Get Testnet MATIC:

   • Visit Polygon Faucet
   • Request Amoy testnet MATIC tokens

3. Start Frontend:

   cd frontend
   npm run dev

4. Test Workflow:

   • Connect MetaMask to Amoy network
   • Open http://localhost:3000
   • Connect wallet
   • Test farmer operations (create products)
   • Test distributor operations (purchase, process)
   • Test retailer operations (resell)
   • Test consumer operations (final purchase)

Test Scenarios

Farmer Testing:

• Create agricultural product
• Set price and shipping deadline
• List product for sale
• Ship product to distributor

Distributor Testing:

• Purchase product from farmer
• Confirm receipt
• Process product (slice into smaller units)
• Package processed product
• List for sale to retailer

Retailer Testing:

• Purchase from distributor
• Confirm receipt
• List for consumer sale

Consumer Testing:

• Purchase final product
• Complete supply chain

View Transactions

All transactions are visible on Amoy PolygonScan:

• Contract interactions
• Token transfers
• Event logs
• Gas usage

🤝 Contributing

We welcome contributions to AgriChain! Please follow these guidelines:

Development Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Code Standards

• Solidity: Follow Solidity style guide
• JavaScript: Use ESLint configuration
• Tests: Maintain 100% test coverage
• Documentation: Update README for new features
• Commits: Use conventional commit messages

Issue Reporting

When reporting issues, please include:

• Environment details: Node.js version, OS, etc.
• Steps to reproduce: Clear reproduction steps
• Expected behavior: What should happen
• Actual behavior: What actually happens
• Screenshots/logs: If applicable

📄 License

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

🙏 Acknowledgments

• OpenZeppelin: For secure, audited smart contract libraries
• Hardhat: For the excellent development environment
• Ethereum Foundation: For the blockchain platform
• IPFS: For decentralized storage solutions
• Community: For feedback and contributions

📞 Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]