Coffee Supply Chain - Hyperledger Fabric Chaincode

A comprehensive blockchain-based solution for coffee supply chain management using Hyperledger Fabric with advanced RBAC (Role-Based Access Control), traceability, and certification features.

📋 Overview

This project implements a complete, secure, and auditable coffee supply chain tracking system on Hyperledger Fabric. It enables stakeholders from farmers to retailers to record and verify activities throughout the coffee lifecycle, ensuring product integrity, quality, and transparency.

Key Features

• Advanced RBAC System: Fine-grained permissions for different supply chain participants
• Complete Coffee Lifecycle Management: Track coffee from cultivation to retail
• Quality Control: Record and verify quality metrics at different stages
• Batch Operations: Split, merge, and bulk transfer coffee batches
• Certifications: Assign, verify, and renew product certifications with automatic expiry tracking
• IoT Integration: Capture sensor data from production environments
• Private Data Collections: Store sensitive information with restricted access
• Real-time Analytics: Process supply chain data for operational insights
• External Data Verification: Integration with oracles and external data sources
• Blockchain-Enforced Endorsement Policies: Ensure stakeholder consensus on critical operations

🏗️ Architecture

Participant Roles

• System Admin: Manages the platform and users
• Farmer: Records cultivation and harvesting activities
• Processor: Processes raw coffee beans
• Exporter: Manages international coffee export
• Importer: Handles international coffee import
• Roaster: Roasts and prepares coffee for distribution
• Distributor: Distributes roasted coffee to retailers
• Retailer: Sells coffee to end consumers
• Certifier: Manages quality and ethical certifications

Supply Chain Stages

The system tracks coffee through these stages:

• Cultivation → Harvesting → Processing → Export → Import → Roasting → Packaging → Distribution → Retail → Consumer

Core Components

• Participant Management: Create, update, and manage participant identities
• Batch Management: Handle coffee batches through the supply chain
• Quality Control: Record and access quality metrics
• Certification Management: Issue and verify certifications
• Documentation System: Store and verify supply chain documentation
• Transaction History: Trace the complete journey of coffee batches

🚀 Installation

Prerequisites

• Hyperledger Fabric v2.x
• Node.js 14+
• TypeScript
• Docker and Docker Compose

Setup Instructions

1. Clone the repository:

   git clone https://github.com/artbm/ekwata-chaincode-fabric.git
   cd coffee-supply-chain

2. Install dependencies:

   npm install

3. Compile the chaincode:

   npm run build

4. Package the chaincode:

   npm run package

5. Install and deploy the chaincode on your Hyperledger Fabric network following standard procedures.

📊 Usage Examples

Registering a New Participant

// Register a new farmer
const farmerResponse = await contract.submitTransaction(
  "createParticipant",
  "FARMER001",
  "Maria Garcia",
  "maria@farmcoop.com",
  "FARMER",
  "PUBLIC_KEY_DATA"
);

Creating a Coffee Batch

// Create a new coffee batch
const batchResponse = await contract.submitTransaction(
  "createCoffeeBatch",
  "BATCH0001",
  "500",
  "KG",
  "Arabica",
  "2023-04-15",
  "Washed"
);

Transferring a Batch

// Transfer batch to processor
const transferResponse = await contract.submitTransaction(
  "transferBatch",
  "BATCH0001",
  "PROCESSOR001",
  "PROCESSING"
);

Adding Quality Metrics

// Add quality metrics
const metricsResponse = await contract.submitTransaction(
  "addQualityMetrics",
  "BATCH0001",
  "8.5", // flavor
  "8.2", // aroma
  "7.9", // acidity
  "8.0", // body
  "10.5", // moisture
  "2", // defect count
  "Bright citrus notes with chocolate finish"
);

Assigning Certification

// Assign organic certification
const certResponse = await contract.submitTransaction(
  "assignCertification",
  "BATCH0001",
  "ORGANIC",
  "2025-06-30"
);

Splitting a Batch

// Split a batch into two smaller batches
const splitResponse = await contract.submitTransaction(
  "splitBatch",
  "BATCH0001",
  "[300, 200]",
  '["BATCH0001A", "BATCH0001B"]'
);

🔍 Advanced Features

Private Data Management

Store sensitive quality metrics in private data collections:

// Add private quality metrics
await contract.submitTransaction(
  "addPrivateQualityMetrics",
  "BATCH0001",
  JSON.stringify({
    cupping_score: 92,
    moisture_content: 10.2,
    proprietary_metrics: {
      // Internal quality parameters
    },
  })
);

IoT Data Integration

// Record temperature and humidity data
await contract.submitTransaction(
  "recordIoTData",
  "BATCH0001",
  "SENSOR123",
  "ENVIRONMENT",
  JSON.stringify([
    { timestamp: "2023-05-10T08:00:00Z", value: 24.5, unit: "C" },
    { timestamp: "2023-05-10T09:00:00Z", value: 25.1, unit: "C" },
  ])
);

Analytics

// Get quality metrics by supply chain stage
const qualityByStage = await contract.evaluateTransaction(
  "getQualityMetricsByStage"
);

🛠️ Development

Running Tests

npm test

Building for Production

npm run build

📄 License

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

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📚 Documentation

For full API documentation and detailed explanations of all features, please see the official documentation.

---

Developed by Ekwata