Design and Implementation of a Decentralized Supply Chain dApp
This publication presents the design and implementation of a blockchain-based supply chain tracking system built on the Ethereum Sepolia testnet enabling authorized users to create, track, and manage supply chain batches.
The application combines a Solidity smart contract, MetaMask wallet integration, React frontend components, and ethers.js to create a decentralized application (dApp) capable of tracking products through a simplified supply chain lifecycle:
Created → Shipped → Delivered
A coffee supply chain scenario was used to validate role-based operations involving Farmers, Distributors, and Retailers. Testing was conducted on the Ethereum Sepolia Testnet to verify core functionality, access-control mechanisms, and complete supply chain lifecycle operations.
The dApp is intended for both technical and non-technical users involved in supply chain operations, including developers, supply chain managers, logistics providers, agricultural producers, retailers, and regulatory authorities.
Supply chains often rely on centralized databases that can suffer from limited transparency, fragmented data ownership, and challenges in auditing product provenance.
Blockchain technology (Nakamoto, 2008, Buterin, 2014) offers an alternative approach by providing:
Recent research has also demonstrated the potential of blockchain technology to improve traceability, transparency, and accountability within supply chain management systems
This project explores how Ethereum smart contracts can be used to manage product batches across multiple supply chain participants while maintaining a transparent and tamper-resistant history.
Traditional supply chain systems face several challenges:
The goal of this project was to develop a decentralized proof-of-concept that demonstrates:
Supply Chain Managers & Logistics Companies
Farmers & Agricultural Producers
Distributors & Warehousing Providers
Retailers & End-Consumers
Regulatory & Compliance Officers
Use Case: Preventing Counterfeit Products
Use Case: Rapid Recall Management
Use Case: Supply Chain Optimization
Use Case: Fair Trade & Ethical Sourcing
The following workflow illustrates the high-level architecture of the proposed blockchain-based supply chain tracking system.
The application consists of a Solidity smart contract (SupplyChainBatch.sol) deployed on the Ethereum Sepolia Testnet and a React-based frontend that provides the user interface. Smart contracts are developed and deployed using Remix IDE, while MetaMask provides wallet authentication and transaction signing. Communication between the frontend and the blockchain is handled through ethers.js using the contract's Application Binary Interface (ABI), enabling authorized users to create, track, ship, and deliver product batches through a web-based dashboard.
┌─────────────────────────┐
│ Remix IDE │
│ Solidity Smart Contract│
└───────────┬─────────────┘
│ Deploy
▼
┌──────────────────────────────────────────────────┐
│ Ethereum Sepolia Testnet │
│ Supply Chain Smart Contract │
└───────────────────────▲─────────────────────────┘
│
│ ethers.js
│
┌───────┴────────┐
│ MetaMask │
│ Wallet Provider│
└───────▲────────┘
│
│ Account Connection
│ Transaction Signing
▼
┌──────────────────────────────────────────────────┐
│ React Frontend │
│ Supply Chain Tracking Dashboard │
└──────────────────────────────────────────────────┘
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React | Builds the decentralized application (dApp) user interface. |
| Smart Contract | Solidity 0.8.x | Implements batch management, lifecycle state transitions, and role-based access control. |
| Blockchain Network | Ethereum Sepolia Testnet | Executes smart contracts and stores immutable transaction records. |
| Wallet Integration | MetaMask | Authenticates users and signs blockchain transactions. |
| Web3 Library | ethers.js | Enables communication between the frontend and the deployed smart contract via the ABI. |
| Development Environment | Remix IDE | Develops, compiles, tests, and deploys smart contracts. |
| Runtime Environment | Node.js | Manages project dependencies and runs the React development environment. |
The system was implemented using React for the frontend interface, Solidity for smart contract development, MetaMask for wallet-based authentication, and ethers.js for blockchain interaction. Smart contracts were developed and deployed through Remix IDE to the Ethereum Sepolia Testnet.
The application was validated using a Coffee Supply Chain (Farm-to-Retail) workflow involving three participants:
Farmer ↓ Create Distributor ↓ Ship Retailer ↓ Deliver
Every state transition is permanently stored on-chain.
This scenario was used to verify batch creation, shipment tracking, delivery confirmation, role-based access control, blockchain persistence, and end-to-end traceability.
The implementation consists of four principal components.
The core business logic is implemented in the SupplyChainBatch.sol smart contract, which manages product batches, enforces role-based access control, validates lifecycle state transitions, records lifecycle timestamps, emits blockchain events, and stores batch information on the Ethereum blockchain.
The smart contract provides the following capabilities:
Created → Shipped → Delivered)createdAt, shippedAt, deliveredAt)The principal public functions are:
createBatch() shipBatch() deliverBatch() getBatchReadable() getStateText()
Note: Lifecycle Auditing: Besides maintaining the batch state and participant addresses, the smart contract records lifecycle timestamps (
createdAt,shippedAt, anddeliveredAt) to support auditability and product traceability. While these values are permanently stored on-chain, they are not currently exposed through the React user interface, leaving scope for future visualization enhancements.
The React-based frontend provides a user-friendly dashboard that allows participants to connect their MetaMask wallet, create product batches, update shipment status, deliver products, and retrieve batch information from the blockchain.
The React dashboard provides:
MetaMask provides decentralized authentication by linking application permissions to Ethereum wallet addresses. Users must approve all state-changing transactions through MetaMask before they are submitted to the blockchain, ensuring that only authorized participants can perform supply chain operations.
Three predefined roles were implemented:
| Role | Permission |
|---|---|
| Farmer | Create batches |
| Distributor | Ship batches |
| Retailer | Deliver batches |
Note: To interact with the blockchain, each account related to each role, requires a small amount of Sepolia ETH to pay transaction fees.
Both the frontend and the smart contract validate user roles to prevent unauthorized operations and maintain data integrity throughout the supply chain lifecycle.
This publication includes a complete GitHub code repository with all source code, configuration files, and test cases.
Ensure the following are installed:
npm --versiongit clone https://github.com/micag2025/Supply_Chain_project.git cd Supply_Chain_project
npm install
This installs all required packages: ethers.js, react-dom, and other dependencies listed in package.json.
Create a .env file in the project root (see src/.env.example):
REACT_APP_CONTRACT= YOUR_DEPLOYED_CONTRACT_ADDRESS REACT_APP_NETWORK_NAME=Sepolia
How to obtain contract address:
.env fileNote: Use the contract address from Remix "Deployed Contracts" panel, NOT farmer/distributor/retailer wallet addresses.
Launch the React development server:
npm start
The server will start and automatically open your browser.
Compiled successfully!
You can now view supplychain-ui in the browser.
Local: http://localhost:3000
On Your Network: http://[YOUR_IP]:3000
Note that the development build is not optimized.
To create a production build, use npm run build.
http://localhost:3000 (opens automatically)The dashboard includes the following features:
Connect Wallet and Disconnect buttonsSearch queries blockchainThe testing strategy combined functional verification, security validation, and end-to-end workflow testing to ensure both technical correctness and realistic supply chain execution.
Testing the full workflow was performed on the Ethereum Sepolia Testnet using MetaMask accounts representing each supply chain participant.
To provide coverage of both technical correctness and real-world operational scenarios, the evaluation framework consisted of three complementary testing categories:
The following areas were validated:
✓ Batch creation
✓ Batch shipment
✓ Batch delivery
✓ Wallet-based authentication
✓ Blockchain state persistence
✓ Role-based access control
✓ Invalid state transition prevention
✓ Duplicate batch prevention
✓ Unauthorized access prevention*
✓ Complete batch lifecycle execution
✓ Correct role-based workflow progression
✓ Frontend-to-blockchain synchronization
✓ Batch traceability from creation to delivery
* Unauthorized access prevention was validated by attempting restricted actions from accounts assigned to incorrect roles.
Detailed test cases and execution results are available in the accompanying GitHub repository.
| Metric | Value |
|---|---|
| Total Test Cases | 20 |
| Passed | 20 |
| Failed | 0 |
| Roles Tested | 3 |
| End-to-End Scenarios | 5 |
| Success Rate | 100% |
All test cases passed successfully, confirming correct behavior of the smart contract, frontend application, wallet integration, and role-based workflow management across the entire supply chain lifecycle.
These results demonstrate that the proposed blockchain-based supply chain system can reliably enforce role-based operations while maintaining transparent and persistent product traceability throughout the supply chain lifecycle.
The dashboard features a wallet connection panel showing the connected account and role, a batch management section with create and lookup forms, and a real-time overview table displaying all batches.
The following scenarios demonstrate the primary application workflows and illustrate how different supply chain participants interact with the blockchain through the React-based user interface.
The Farmer creates a batch and records product information on-chain workflow was validated. The figure shows the Farmer batch creation process, including validated batch creation, instant display in the overview table, blockchain confirmation, and batch lookup with full details.
The Distributor updates batch state from: Created → Shipped workflow was validated. The figures show the Distributor shipment process, including viewing only “Created” batches, using the “Ship” action, and updating batch status to “Shipped” . The screenshots also confirm that the Distributor address is recorded on-chain, updates appear in real time, and farmers cannot perform shipping actions (button disabled).
The Retailer completes the lifecycle: Shipped → Delivered workflow was validated. The figures show the Retailer delivery process, including viewing “Shipped” batches, using the “Deliver” action, and updating the state to “Delivered.” These screenshots also confirm on-chain recording of the Retailer address, real-time updates, and restricted access for Distributors (button disabled).
The Non-authorized roles cannot perform restricted actions workflow was validated. The figure demonstrates an access control scenario where a distributor attempts to create a batch. It shows that the “Create Batch” action is unavailable for non-farmer roles, preventing unauthorized actions. The interface clearly indicates role restrictions, and no gas is consumed since the action is blocked at the UI level.
The Users receive clear feedback when querying non-existing batches workflow was validated. The figure shows the behavior when a user searches for a non-existing batch. It displays a clear “Batch not found” error message with user-friendly formatting. Thus, it ensures no invalid data is returned, and confirms that the read-only operation does not consume gas.
Handling MetaMask account changes required continuous UI synchronization.
Blockchain transactions are asynchronous and require confirmation before frontend updates.
To provide a better user experience while maintaining security, access control needed validation at both:
The proposed blockchain-based supply chain tracking system successfully demonstrates decentralized batch creation, shipment tracking, delivery verification, and role-based access control through Ethereum smart contracts and a React-based user interface. However, as a proof-of-concept implementation, the system has several limitations that should be addressed in future iterations.
Created → Shipped → Delivered). Additional states such as production, quality inspection, warehousing, customs clearance, and returns are not modeled, limiting the realism and granularity of supply chain tracking.Despite these limitations, the project successfully demonstrates the feasibility of using blockchain technology to provide transparent, immutable, and role-controlled supply chain tracking. The identified limitations also provide a clear roadmap for future enhancements and system expansion.
The proposed architecture was intentionally designed as a modular proof-of-concept that can be extended to support more realistic supply chain requirements. Future work will focus on improving scalability, usability, traceability, and production readiness while preserving the system's decentralized design principles.
Contributors are encouraged to extend the system with the following enhancements:
Additional technical details, implementation considerations, and the complete development roadmap are available in the accompanying GitHub repository.
This project demonstrates the feasibility of using blockchain technology to implement a decentralized supply chain tracking system that combines smart contracts, wallet-based authentication, and a React frontend. The proposed apporach successfully validates product traceability, role-based access control, and immutable lifecycle tracking on the Ethereum Sepolia Testnet. Although implemented as a proof of concept, the modular architecture provides a solid foundation for future enhancements, including advanced analytics, decentralized storage, multi-network deployment, and real-world supply chain integration.
Contributions are welcome to enhance the Supply Chain dApp. Follows these steps:
git checkout -b feat/your-feature
Official documentation and resources:
This project is licensed under the MIT License
This project was built with contributions and inspiration from the developers who enrolled in the Sviluppatore Blockchain Traininig, organised by Cieffe with the support of Trentino Lavoro. Special thanks to the trainer, Giacomo Scettri, who provided feedback during development and testing phases.