DEIS - Decentralized Exam Integrity System

🎯 Project Overview

The Decentralized Exam Integrity System (DEIS) is a blockchain-based solution designed to eliminate exam paper leaks through decentralized access control and cryptographic key management. This MVP demonstrates a complete end-to-end workflow for secure exam distribution using Ethereum smart contracts, client-side encryption, Filebase IPFS-based decentralized storage, and time-locked access control.

🏗️ Architecture

Technology Stack

Component	Technology	Purpose
Blockchain	Solidity 0.8.x, Ethereum Sepolia Testnet	Smart contract execution and audit trail
Frontend	React 18, Tailwind CSS	Modern, responsive UI
Web3	Ethers.js v5	Blockchain interaction
Encryption	CryptoJS (AES-256)	Client-side file encryption
Key Management	Shamir's Secret Sharing	Distributed key storage
Storage	Filebase IPFS (via config.js)	Decentralized encrypted file storage

Security Features

✅ Time-Locked Access Control - Exams cannot be accessed before release time
✅ Role-Based Authorization - Admin, Principal, and Proctor roles
✅ Cryptographic Encryption - AES-256 encryption for exam content
✅ Secret Sharing - Shamir's Secret Sharing for key distribution
✅ Immutable Audit Trail - All actions logged on blockchain
✅ Decentralized Storage - Encrypted files stored off-chain

📁 Project Structure

dapp-papers/
├── index.html                 # MAIN production DApp (React + Ethers + Filebase IPFS)
├── ExamManager.sol           # Full-featured ExamManager contract with time-locked access control
├── ExamManagerOptimized.sol  # Gas-optimized contract used by index.html
├── ExamManagerSimple.sol     # Ultra-minimal, gas-efficient variant
├── config.js                 # Network, storage (Filebase/IPFS) and UI configuration
├── filebase-storage.js       # Standalone Filebase S3/IPFS helper used by test utilities
├── App.jsx                   # React component version (for bundler-based development)
├── README.md                 # This file
├── *.md                      # Additional guides (architecture, deployment, quick start, visual guide, etc.)
└── sample-exam.txt           # Sample exam file for testing upload/decrypt flow

⚙️ Configuration & Storage

• config.js
  • Defines supported networks (sepolia, mainnet) and RPC URLs.
  • Optional pre-filled contract addresses per network.
  • Configures the storage provider (Filebase IPFS by default), gateways, and UI/security settings.
• Filebase IPFS integration (see FILEBASE_IMPLEMENTATION.md)
  • Encrypted exam files are uploaded via a ProductionFilebaseStorage class.
  • The smart contract stores only the resulting IPFS hash (CID).
  • During retrieval, the DApp downloads the encrypted file from IPFS and decrypts it client-side.

🚀 Deployment Guide

Prerequisites

1. Node.js (v16+) - Download
2. MetaMask - Install Extension
3. Ganache - Download
4. Remix IDE - Open Online

Step 1: Start Local Blockchain

By default the bundled index.html expects Ethereum Sepolia Testnet (chainId 11155111), but you can also use a local chain (e.g., Hardhat or Ganache) if you adjust the network checks in index.html.

Option A – Recommended: Sepolia Testnet

1. Open MetaMask
2. Click network dropdown → Add Network
3. Configure:
   • Network Name: Sepolia Testnet
   • RPC URL: https://rpc.sepolia.org (or any Sepolia RPC endpoint)
   • Chain ID: 11155111
   • Currency Symbol: SepoliaETH
   • Block Explorer: https://sepolia.etherscan.io
4. Get Sepolia test ETH from a faucet (see GET_FREE_ETH.md).

Option B – Local Development Network (Ganache/Hardhat)

1. Launch Ganache or a local Hardhat node
2. Note the RPC Server URL (e.g., http://127.0.0.1:7545)
3. In MetaMask, add a custom network (e.g., Ganache Local) with that RPC URL and matching chain ID
4. Import one of the local accounts using its private key

Step 2: Configure MetaMask

1. Open MetaMask extension
2. Click network dropdown → Add Network
3. Configure:
   • Network Name: Sepolia Testnet (or your local dev network name)
   • RPC URL: The RPC endpoint you chose (e.g., https://rpc.sepolia.org)
   • Chain ID: 11155111 for Sepolia, or your local chain ID
   • Currency Symbol: ETH / SepoliaETH
4. Import your funded account (Sepolia address or local test account)

Step 3: Deploy Smart Contract

Using Remix IDE:

1. Open Remix IDE
2. Create new file: ExamManager.sol
3. Copy contents from ExamManager.sol
4. Go to Solidity Compiler tab
   • Select compiler version: 0.8.0+
   • Click Compile ExamManager.sol
5. Go to Deploy & Run Transactions tab
   • Environment: Injected Provider - MetaMask
   • Ensure MetaMask is connected to your target network (Sepolia recommended)
   • Click Deploy
   • Confirm transaction in MetaMask
6. Copy the deployed contract address (you'll need this!)

🔎 Note: The default index.html checks that MetaMask is on Sepolia (chainId === 11155111). If you deploy to a different network (e.g., Ganache), update those checks in the connectWallet and connectContract functions.

Alternative: Using Truffle/Hardhat

# Install dependencies
npm install --save-dev hardhat @nomiclabs/hardhat-ethers ethers

# Initialize Hardhat project
npx hardhat

# Deploy script (scripts/deploy.js)
npx hardhat run scripts/deploy.js --network localhost

Step 4: Launch DApp

Option A: Direct HTML (Recommended for MVP)

1. Open index.html in a modern browser (Chrome/Firefox)
2. The DApp will load automatically

Option B: Local Development Server

# Using Python
python -m http.server 8000

# Using Node.js
npx http-server -p 8000

# Open browser to http://localhost:8000

Step 5: Connect DApp to Contract

1. Click "Connect Wallet" button
2. Approve MetaMask connection
3. Paste the deployed contract address in the input field
4. Click "Connect" button
5. Wait for confirmation notification

📖 User Guide

Admin Role

Purpose: Upload and register new exams

Workflow:

1. Switch to Admin tab
2. Fill in exam details:
   • Exam Title: e.g., "Mathematics Final 2025"
   • Select File: Choose exam paper (PDF/TXT)
   • Release Time: Set future date/time
3. Click "Upload & Secure Exam"
4. Confirm transaction in MetaMask
5. Wait for blockchain confirmation

What Happens:

• File is encrypted with AES-256 using random key
• Encryption key is split using Shamir's Secret Sharing (3 shares, 2 threshold)
• Encrypted file uploaded to Filebase IPFS via the configured storage provider
• File hash and key shares stored on blockchain
• ExamRegistered event emitted

Principal Role

Purpose: Authorize proctors to access specific exams

Workflow:

1. Switch to Principal tab
2. Select exam from dropdown
3. Enter proctor's Ethereum address
4. Click "Authorize Proctor"
5. Confirm transaction

What Happens:

• Proctor address added to authorized list for exam
• ProctorAuthorized event emitted
• Proctor can now retrieve exam after release time

Proctor Role

Purpose: Retrieve and decrypt exam papers

Workflow:

1. Switch to Proctor tab
2. View list of authorized exams with status:
   • 🟡 Pending: Not yet released (button disabled)
   • 🟢 Ready: Available for retrieval
   • 🔴 Expired: Past retrieval window
3. Click "Decrypt & Display" on ready exam
4. Confirm transaction to retrieve key parts
5. View decrypted content

What Happens:

• Smart contract verifies:
  • ✓ Proctor is authorized
  • ✓ Current time ≥ release time
  • ✓ Key not already retrieved
• Key parts returned from blockchain
• Encrypted file fetched from storage
• Key reconstructed using Shamir's Secret Sharing
• File decrypted and displayed
• KeyRevealed event emitted

🔐 Security Implementation

Encryption Flow

Original File → AES-256 Encryption → Encrypted File → Filebase IPFS (or configured storage)
                      ↓
                 Random Key
                      ↓
           Shamir's Secret Sharing
                      ↓
              [Share 1, Share 2, Share 3]
                      ↓
              Smart Contract Storage

Time-Lock Mechanism

The smart contract enforces time-based access control:

require(block.timestamp >= exam.releaseTimestamp, "Exam not yet released");

This ensures that even authorized proctors cannot access the exam before the scheduled release time.

Shamir's Secret Sharing (SSS)

Concept: Split encryption key into N shares where any K shares can reconstruct the original key.

Implementation (Simplified for MVP):

• N = 3 total shares
• K = 2 threshold (any 2 shares can reconstruct key)
• N-1 shares stored on-chain
• Reconstruction happens client-side

Production Note: Use a robust SSS library like secrets.js-grempe for production deployments.

📊 Audit Trail

All critical actions are logged as blockchain events:

Event	Triggered When	Data Logged
ExamRegistered	Admin uploads exam	Exam ID, title, hash, release time, creator
ProctorAuthorized	Principal authorizes proctor	Exam ID, proctor address, authorizer
KeyRevealed	Proctor retrieves key	Exam ID, proctor address, timestamp, block number
PrincipalAdded	Admin adds principal	Principal address, admin address
ExamDeactivated	Admin deactivates exam	Exam ID, admin address

View the Audit Trail section in the DApp to see real-time event logs.

🧪 Testing Scenarios

Test Case 1: Complete Exam Lifecycle

1. Admin: Upload exam with release time 5 minutes in future
2. Principal: Authorize proctor address
3. Proctor: Attempt early access (should fail)
4. Wait: Until release time passes
5. Proctor: Successfully retrieve and decrypt exam
6. Verify: Audit trail shows all events

Test Case 2: Unauthorized Access

1. Admin: Upload exam
2. Proctor: Try to access without authorization (should fail)
3. Principal: Authorize different address
4. Original Proctor: Still cannot access

Test Case 3: Time-Lock Enforcement

1. Admin: Upload exam with future release time
2. Principal: Authorize proctor
3. Proctor: Attempt immediate access
4. Expected: Transaction reverts with "Exam not yet released"

🛠️ Smart Contract Functions

DEIS ships three compatible contract variants:

• ExamManager – full-featured reference implementation used throughout the docs.
• ExamManagerOptimized – gas-optimized variant used by the bundled index.html UI.
• ExamManagerSimple – ultra-minimal, gas-efficient compatibility version.

The function signatures below describe the full ExamManager interface; the optimized variants expose equivalent behavior with slightly different types (e.g., uint32 IDs) and helper methods (e.g., getKeys, getAllExams).

Admin Functions

// Register new exam
function registerExam(
    string memory _examTitle,
    string memory _encryptedFileHash,
    uint256 _releaseTimestamp,
    string[] memory _encryptedKeyParts
) public onlyAdmin returns (uint256)

// Add principal role
function addPrincipal(address _principal) public onlyAdmin

// Deactivate exam
function deactivateExam(uint256 _examId) public onlyAdmin

Principal Functions

// Authorize proctor for exam
function authorizeProctor(
    uint256 _examId,
    address _proctor
) public onlyAdminOrPrincipal

// Revoke proctor authorization
function revokeProctor(
    uint256 _examId,
    address _proctor
) public onlyAdminOrPrincipal

Proctor Functions

// Retrieve encrypted key parts (time-locked)
function getEncryptedKeyParts(uint256 _examId) 
    public returns (string[] memory)

View Functions

// Get exam information
function getExamInfo(uint256 _examId) 
    public view returns (ExamInfo memory)

// Check if exam is released
function isExamReleased(uint256 _examId) 
    public view returns (bool)

// Check proctor authorization
function isProctorAuthorized(uint256 _examId, address _proctor) 
    public view returns (bool)

// Get all exam IDs
function getAllExamIds() 
    public view returns (uint256[] memory)

🔧 Troubleshooting

MetaMask Connection Issues

Problem: "Please install MetaMask!" error
Solution: Install MetaMask extension and refresh page

Problem: Wrong network
Solution: Switch MetaMask to Ganache Local network

Contract Connection Issues

Problem: "Contract connection failed"
Solution:

• Verify contract address is correct
• Ensure contract is deployed on current network
• Check Ganache is running

Transaction Failures

Problem: "Exam not yet released"
Solution: Wait until release time passes

Problem: "Not authorized for this exam"
Solution: Principal must authorize your address first

Problem: "Insufficient funds"
Solution: Ensure Ganache account has ETH

File Upload Issues

Problem: Upload fails silently
Solution:

• Check file size (keep under 1MB for testing)
• Ensure file is text-based (TXT, PDF)
• Check browser console for errors

📈 Future Enhancements

Production Readiness

• Add native Arweave/permaweb storage in addition to Filebase IPFS
• Implement robust SSS library (secrets.js-grempe)
• Add multi-signature admin controls
• Implement exam expiration logic
• Add encrypted metadata support
• Create mobile-responsive PWA
• Add comprehensive test suite
• Implement gas optimization
• Add event indexing (The Graph)
• Create admin dashboard analytics

Advanced Features

• Multi-exam batch operations
• Proctor reputation system
• Exam versioning and updates
• Automated time-zone handling
• Email/SMS notifications
• PDF viewer integration
• Watermarking for retrieved exams
• Access analytics and reporting
• Integration with LMS platforms
• Compliance reporting tools

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

This is an MVP demonstration project. For production use, conduct thorough security audits and testing.

📞 Support

For issues or questions:

1. Check the Troubleshooting section
2. Review Ganache and MetaMask logs
3. Inspect browser console for errors
4. Verify smart contract deployment

🎓 Educational Use

This project demonstrates:

• Smart contract development with Solidity
• Web3 integration with Ethers.js
• Client-side cryptography
• Decentralized application architecture
• Time-locked access control patterns
• Event-driven blockchain applications
• Role-based access control (RBAC)

---

Built with ❤️ for secure, decentralized education systems