Blockchain Project

This repository contains the code developed for the Blockchain course project in the academic year 2024–2025.

Table of contents

• Architecture

• Installation

• Execution

• Upgrade Cashback Contract

• Authors

Architecture

Below is an overview of the main components required for the system to operate correctly:

• Blockchain network
  Generated and managed by Hardhat. This is a private PoA blockchain that automatically creates 20 accounts. It exposes an RPC endpoint at http://localhost:8545.

• Backend + MongoDB
  The backend stores selected off-chain data in clear text and provides access to the ABIs and public addresses of the deployed contracts. It is accessible at http://localhost:3000.

• Frontend
  Developed with Vue.js and integrated with MetaMask, the frontend manages all user interactions and blockchain operations. It is served at http://localhost:5173.

• Docker
  All components are containerized and orchestrated via Docker Compose, simplifying deployment and inter-service communication.

Default Wallet list

In this project we use the twenty default wallets provided by hardhat. In the ingnition we define the role for each address according to the following table:

WalletId	Role	Permissions
0	Deployer	Can modify ACL and upgradable contracts
1	Manufacturer	Can create and remove Product and Lot, modify CashBack multiplier, send Transaction
2-14	Retailer	Send Transaction, Redeem CashBack
15-19	Pharmacy	Send Transaction, Redeem CashBack, Sell Product

The private keys and wallet addresses, to import them in Metamask, can be retrived from Hardhat logs:

docker logs hardhat | less

Output:

Account #0: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 ETH)
Private Key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Account #1: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 (10000 ETH)
Private Key: 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d

Account #2: 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC (10000 ETH)
Private Key: 0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a

...

Account #19: 0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199 (10000 ETH)
Private Key: 0xdf57089febbacf7ba0bc227dafbffa9fc08a93fdc68e1e42411a14efcf23656e

Installation

Docker

This project is fully containerized, so the only requirement is to have the latest versions of Docker and Docker Compose installed on your system. All other dependencies are handled automatically within the containers.

To verify that Docker and Docker Compose are installed, run the following commands:

docker -v

docker compose version

If any of these commands report that a component is missing or not found, please install Docker and Docker Compose before proceeding to the execution step.

Connect metamask to local network

To interact with the blockchain and confirm transactions, you must use the MetaMask browser extension. You can install it in Firefox, Chrome, or any Chromium-based browser.

Below is a step-by-step guide to connect MetaMask to your local Hardhat blockchain and import an account:

1. Open metamask

2. In the top-left corner, click the network selector and choose Add a network manually (or Add network).

3. Fill in the network details as follows (leave the Block Explorer URL blank):

   • Network Name: Anything you want

   • New RPC URL: http://localhost:8545

   • Chain ID: 31337

   • Currency Symbol: ETH

4. Return to the main MetaMask screen and import an account. You can paste any of the 20 private keys automatically generated by Hardhat.

Once connected and the account imported, you’ll be able to use this wallet to sign and send transactions via the web application.

Execution

This project uses Docker Compose to orchestrate all the services. You only need two commands to start and stop everything:

To start the services:

docker compose up --build

To stop the services and clean up:

docker compose down -v --remove-orphans

Always stop the containers using the command above.
This ensures that all temporary volumes are properly removed. If you skip this step, leftover volumes may cause unexpected behavior the next time you start the project.

Upgrade Cashback Contract

When the project is running, enter the Hardhat console and upgrade the new cashback contract:

docker exec -it hardhat /bin/bash

# in the hardhat docker console
npx hardhat run scripts/upgrade.js --network localhost

After the upgrade, in order to change the call to the new contract, modify the constant flag IS_CASHBACK_UPGRADED in the frontend, in the file frontend/src/services/cashback.services.js:5 to true.

This will change the call to the cashback contract:

const handlerContract = new ethers.Contract(handlerAddress, handlerAbi, signer);
const redeemTx = IS_CASHBACK_UPGRADED ? await handlerContract["redeemCashback(uint256)"](MIN_CASHBACK_AMOUNT,{gasPrice: 0 }) : await handlerContract["redeemCashback()"]({gasPrice: 0 });

Authors

Name	Email
Dorijan Di Zepp	dorijan.dizepp@studenti.unitn.it
Enrico Carnelos	enrico.carnelos@studenti.unitn.it
Marco Roccon	marco.roccon@studenti.unitn.it
Nicola Mores	nicola.mores@studenti.unitn.it