SecureKYC: A Blockchain-Based Consent-Driven KYC Framework

Short name in UI: securekyc.

End-to-end prototype for decentralized KYC:

• User uploads KYC once.
• Document is AES-encrypted and stored off-chain on IPFS (Pinata).
• Blockchain stores only document hash + status + consent-aware access rules.
• Banks request access; users grant/revoke consent; authorized banks verify.

Architecture

Components

• blockchain/: Hardhat + Solidity smart contract (SecureKYC.sol)
• backend/: Node.js + Express API, AES encryption, IPFS upload, wallet-signature auth
• frontend/: React + TypeScript dashboard for User/Bank/Admin
• shared/: generated contract ABI + address (SecureKYC.json) after deploy

Data Flow

1. User signs login nonce with MetaMask (prevents replay).
2. User uploads file to backend.
3. Backend computes SHA-256, encrypts with AES-256-GCM, uploads encrypted blob to IPFS.
4. CID + encrypted hash are returned; frontend writes hash + CID on-chain via MetaMask.
5. Bank requests access.
6. User grants consent.
7. Bank verifies/rejects KYC.
8. UI shows status from backend + on-chain read path.

Security Design

• Integrity: SHA-256 file and encrypted-content hashing.
• Confidentiality: AES-256-GCM for file-at-rest before IPFS upload.
• Authentication: wallet signatures (MetaMask) + JWT session.
• Authorization: role-based access (user, bank, admin).
• Replay protection: one-time nonce during wallet login.
• Least on-chain disclosure: only metadata/hash/status/consent logic on chain.
• Auditability: smart contract emits events for user registration/upload/consent/verification.

Smart Contract Features

SecureKYC.sol includes:

• user registration
• KYC metadata upload (encryptedDocHash, encryptedDocCid)
• bank authorization/revocation (admin-controlled)
• consent management per user-bank pair
• bank verification decision
• read access control for KYC records
• nonce mechanism placeholder (useNonce) for extending anti-replay flows

Deploy for remote testers (Sepolia + hosted API + UI)

See DEPLOYMENT.md for Vercel + Render, environment variables, and how to get the shareable frontend URL after you deploy.

Setup (Local Demo)

Run everything from the single project folder:

cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC"

1) Blockchain (Terminal 1 + Terminal 2)

cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC\blockchain"
copy .env.example .env
npm install
npm run compile
npm run test

Start local chain:

npm run node

Deploy contract in another terminal:

cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC\blockchain"
npm run deploy:local

This creates shared/SecureKYC.json.

2) Backend (Terminal 3)

Generate 32-byte AES key (hex):

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Create env:

cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC\backend"
copy .env.example .env

Set required .env values:

• FILE_ENCRYPTION_KEY_HEX
• PINATA_JWT
• RELAYER_PRIVATE_KEY (admin wallet key for bank authorization tx)
• CONTRACT_ADDRESS (from deploy output)

Start API:

npm install
npm run dev

3) Frontend (Terminal 4)

cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC\frontend"
copy .env.example .env
npm install
npm run dev

Set VITE_CONTRACT_ADDRESS in frontend/.env to deployed contract address.

Open http://localhost:5173.

Quick Restart (Manual)

Use four terminals:

1. cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC\blockchain" then npm run node
2. cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC\blockchain" then npm run deploy:local
3. cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC\backend" then npm run dev
4. cd "C:\Users\NFSU_BTECH-MTECH\Downloads\SecureKYC\frontend" then npm run dev

Demo Workflow

1. Login as Admin, authorize a bank wallet.
2. Login as User, upload KYC file.
3. Login as Bank, request access for the user wallet.
4. Login as User, grant consent to bank wallet.
5. Login as Bank, verify/reject KYC.
6. View status from User/Bank panel.

REST API Summary

• POST /api/auth/nonce
• POST /api/auth/verify
• POST /api/kyc/upload (multipart document)
• POST /api/kyc/access/request
• GET /api/kyc/access/requests
• POST /api/kyc/access/grant
• POST /api/kyc/verify
• GET /api/kyc/status/:wallet
• POST /api/admin/bank/authorize
• POST /api/admin/bank/revoke

Comparison: Traditional vs Blockchain KYC

• Traditional KYC: repeated submissions, siloed records, weak cross-institution reuse.
• Blockchain KYC: single upload + reusable verification state, tamper-evident audit trail, consent-centric access.
• Privacy impact: raw files stay off-chain; chain stores proof/status only.

Resume-Ready Project Description

Built a full-stack Blockchain-Based Secure KYC framework using Solidity, Hardhat, Node.js, Express, React, and IPFS. Implemented wallet-signature authentication, AES-256-GCM encrypted off-chain document storage, SHA-256 integrity checks, role-based access control, consent-driven data sharing, and event-auditable verification workflows for banks and users.