Shipment Milestone Tracker DApp

A simple blockchain-based decentralized application for tracking shipment milestones. This project demonstrates smart contract development, testing, and frontend integration.

Project Overview

Problem Solved: Missing or manipulated delivery records in shipping logistics.

Solution: Immutable milestone tracking on blockchain with role-based access control.

Features

• Core Functions:

  • Create shipments (Admin only)
  • Add milestones to shipments (Authorized carriers)
  • Track shipment progress (Anyone)
  • Complete shipments (Authorized carriers)
  • Authorize carriers (Admin only)

• Blockchain Benefits:

  • Immutable milestone records
  • Transparent tracking
  • No single point of failure
  • Verifiable delivery history

Technology Stack

• Smart Contract: Solidity ^0.8.19
• Development Framework: Hardhat
• Frontend: HTML, CSS, JavaScript
• Blockchain Interaction: Web3.js
• Testing: Hardhat + Chai
• Local Blockchain: Hardhat Network

Project Structure

shipment-tracker/
├── contracts/
│   └── ShipmentTracker.sol    # Main smart contract
├── test/
│   └── ShipmentTracker.test.js # Comprehensive tests
├── scripts/
│   └── deploy.js              # Deployment script
├── frontend/
│   ├── index.html            # Main UI
│   ├── app.js                # Web3 integration
│   ├── style.css             # Styling
│   └── contract.json         # Contract ABI & address (generated)
├── hardhat.config.js         # Hardhat configuration
└── package.json              # Dependencies

Setup Instructions

Prerequisites

• Node.js (v16 or higher)
• MetaMask browser extension
• Git

Installation

1. Clone and navigate to project:

   cd shipment-tracker

2. Install dependencies:

   npm install

3. Compile the smart contract:

   npm run compile

4. Run tests:

   npm test

Running the Application

1. Start Local Blockchain

npm run start

This starts a local Hardhat network on http://127.0.0.1:8545

2. Deploy Contract

In a new terminal:

npm run deploy

This deploys the contract and saves the address/ABI to frontend/contract.json

3. Setup MetaMask

• Add Hardhat network to MetaMask:

  • Network Name: Hardhat Local
  • RPC URL: http://127.0.0.1:8545
  • Chain ID: 1337
  • Currency Symbol: ETH

• Import test accounts (use private keys from Hardhat output)

4. Start Frontend

Open frontend/index.html in your browser or use a local server:

# Option 1: Direct file
# Just open frontend/index.html in browser

# Option 2: Local server (recommended)
cd frontend
python -m http.server 8080
# Then visit http://localhost:8080

Using the DApp

Roles

• Admin (Contract Owner): Can create shipments and authorize carriers
• Authorized Carriers: Can add milestones and complete shipments
• Anyone: Can track shipments

Workflow

1. Admin creates a shipment:

   • Go to Admin Panel
   • Enter shipment ID, carrier address, customer address
   • Click "Create"

2. Carrier adds milestones:

   • Go to Carrier Panel
   • Enter shipment ID and milestone description
   • Set timestamp and click "Add Milestone"

3. Anyone tracks shipment:

   • Go to Track Shipment tab
   • Enter shipment ID
   • View progress and milestones

4. Carrier completes shipment:

   • Use "Complete Shipment" in Carrier Panel

Smart Contract Functions

Main Functions

• createShipment(shipmentId, carrier, customer) - Create new shipment
• addMilestone(shipmentId, description, timestamp) - Add milestone
• completeShipment(shipmentId) - Mark shipment as completed
• authorizeCarrier(carrier) - Authorize new carrier

View Functions

• getShipment(shipmentId) - Get shipment details
• getMilestone(shipmentId, index) - Get specific milestone
• getAllShipmentIds() - Get all shipment IDs
• getMilestoneCount(shipmentId) - Get milestone count

Testing

Run the comprehensive test suite:

npm test

Test Coverage

• Contract deployment and initialization
• Carrier authorization
• Shipment creation with validation
• Milestone addition with restrictions
• Shipment completion
• Access control enforcement
• Error handling

Sample Test Output

ShipmentTracker
  ✓ Should set the right owner
  ✓ Should authorize owner as carrier by default
  ✓ Should allow owner to authorize carriers
  ✓ Should create a new shipment
  ✓ Should add milestone by authorized carrier
  ✓ Should complete shipment
  ... (25+ tests)

Common Issues & Solutions

MetaMask Connection Issues

• Ensure you're on the correct network (Hardhat Local)
• Refresh the page after network changes
• Check that contract is deployed

Transaction Failures

• Ensure you have enough ETH for gas
• Check if you have the right permissions
• Verify input parameters

Contract Not Found

• Make sure you ran npm run deploy
• Check that frontend/contract.json exists
• Restart local blockchain if needed

Learning Objectives

This project demonstrates:

• Smart Contract Development: Solidity basics, modifiers, events
• Testing: Comprehensive test coverage with Hardhat/Chai
• Frontend Integration: Web3.js for blockchain interaction
• Security: Access control, input validation
• Development Workflow: Compile, test, deploy cycle

Next Steps for Extension

• Add more complex milestone types
• Implement payment escrow
• Add GPS location tracking
• Create mobile app interface
• Deploy to testnets (Sepolia, Goerli)
• Add more sophisticated UI/UX

Troubleshooting

Port Already in Use

# Kill process on port 8545
npx kill-port 8545

Clean Restart

npm run clean
npm run compile
npm run deploy

Reset MetaMask Account

Settings → Advanced → Reset Account (clears transaction history)

License

MIT License - Feel free to use for educational purposes.

---

Note: This is a simplified educational DApp. For production use, additional security audits and features would be required.