Decentralised-Identity-System

© Angelo-Gabriel Barbu - angelo.barbu123@gmail.com - 2025

Table of Contents

1. Introduction
2. High-Level Software Architecture
3. Prerequisites
4. Project Structure
5. Project Components
   • Ganache
   • Smart Contracts
   • Business Logic
   • Visual Components
6. How to Install
7. Development Plan

Introduction

The project focuses on designing, implementing and testing a complete solution that incorporates a Decentralized Identity Verification System based on blockchain technology, having the purpose of providing a platform where individuals can issue, manage and revoke identity credentials, that can be used for identity confirmation. That way, we want to achieve a high level of control and privacy over sensitive personal information, by implementing an Identity Digital Wallet, while offering an efficient method to verify an individual's indetity by third-party entities through a Verification Interface.

The system is based on Ethereum blockchain and deployed on Ethereum Virtual Machine (EVM), as a viable choice, considering its major adoption, high degrees of stability and security and a well defined development and testing framework.

High-Level Software Architecture

Prerequisites

• Node.js - Business Logic (Frontend)
• React.js - Visual Components (Backend)
• npm - Node Package Manager
• Web3.js - JavaScript Libraries for Ethereum Node Interactions
• Truffle - Development Environment for Ethereum Virtual Machine (EVM)
• Ganache - Local Ethereum blockchain environment
• Solidity - Smart Contracts Programming Language
• MetaMask - Browser Extension for Digital Wallets

Project Structure

• backend/: Contains the Backend level of the project where Business Logic, Data Processing and Frontend <-> Smart Contracts communication is implemented, using Node.js.

• frontend/: Visual Components (Frontend level) for Identity Digital Wallet management and MetaMask connection, developed with React.js.

• ganache/: Bash scripts implemented to start and configure Ganache network using Ganache CLI.

• smart_contracts/: Smart Contracts module where implementation (Solidity), testing, compilation and migration instructions are developed, based on Truffle development environment and project structure.

Project Components

Ganache

The Ganache module is responsible for setting up and managing the Ethereum blockchain locally hosted using Ganache CLI.

Usage Instructions

1. Set up local blockchain: This will generate a mnemonic and a dummy database for contract deployments, transactions and test wallets.

./config-ganache.sh setup

NOTE: Reset environment database, including deployed contract, public-private wallet keypairs and past transactions.

./config-ganache.sh reset

2. Start Ethereum blockchain

./start-ganache.sh

• Ganache network runs at: http://127.0.0.1:8545.
• Config scripts uses a collection of words defined in an environment file to return the mnemonic. Consider adding an .env file with the following structure:

# Define the words to be used for generating mnemonics
MNEMONIC_WORDS="apple banana cherry date eagle falcon grape honey ice jelly kite lemon mango nut olive pear queen rose star tiger umbrella violet whale xray yellow zebra"

---

Smart Contracts

The Smart Contracts module contains the implementation of the Smart Contract for the system. It provided the methods responsible for issuing, verifying, revoking and retrieving identity credentials on the blockchain.

Contract Structure

Setting up

Compile and migrate smart contracts:

truffle compile
truffle migrate --reset

After compilation, the contract ABI generated at build/contracts/Identity.json is migrated to the frontend and backend module. The migration strategy can be found at migrations/2_deploy_contracts.js.

Testing

Integration and unit tests are implemented in test/Identity.test.js to check the functionality, the performance and the security of the smart contract and its methods. They can be executed using:

truffle test

The generated file test/test-results.json contains the performance data for the executed load test.

---

Business Logic

The Backend module is a Node.js server that follows the Model-View-Controller (MVC) pattern, organizing the business logic into structured components. It interacts with the Ethereum blockchain using Web3.js and connects with the frontend to process identity-related requests.

Setting up

1. Install NPM dependencies

npm install

2. Run backend server

npm run start

NOTE: For running with nodemon for development purposes:

npm run dev

3. Set up an .env file with the following structure as example:

PORT=5001
GANACHE_RPC_URL=http://127.0.0.1:8545
DEPLOYED_CONTRACT_ADDRESS=<DEPLOYED_CONTRACT_ADDRESS>
OCR_API_KEY=<OCR_API_KEY>
SECRET_KEY=<SECRET_KEY>

---

Visual Components

The Frontend module is a React.js application that provides a user-friendly interface for interacting with the system. It enables users to connect their MetaMask wallet, issue credentials, revoke credentials, and view their identity credentials.

Setting up

1. Install NPM dependencies

npm install

2. Start React.js application

npm start

NOTE: After setting up and running all project components, the application should be functional and accesible at http://localhost:3000.

How to Install

1. Set up Ganache environment

cd ganache # Considering project root directory
./config-ganache.sh setup

2. Start Ganache CLI

./start-ganache.sh

3. Compile and migrate Smart Contract

cd smart_contracts # Considering project root directory
truffle compile
truffle migrate --reset

4. Check if Smart Contract was compiled and deployed successfully

truffle test

5. Install backend dependencies and start Node.js server

cd backend # Considering project root directory
npm install
npm run start

6. Install frontend dependencies and start React.js application

cd frontend # Considering project root directory
npm install
npm start

• The application should be functional and accesible here (at http://localhost:3000).

Development Plan

There is a plan for further development, depending on the priority. At the current state of the system overall, the priority stands as follows:

High

1. Redefinition of Issue Credential Form(proper field validation, adding more relevant fields, identity document processing);
2. Handling multiple MetaMask Digital Wallets on a session.

Medium

1. Develop Verification Interface for third-party validation requests;
2. Implement authentication module that tests Verification Interface;
3. In-depth unit testing for all the components, with a high coverage degree;
4. Further performance improvements overall;
5. Implementing personal secret key for credential access.

Low

1. Implementing handling multiple wallet platforms.