AdemNefzi/LexiChain
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
LexiChain/docs/blockchain-module.md
Adem 165af509ef Pre-Final Backup
2026-05-03 13:26:31 +01:00

676 lines
24 KiB
Markdown
Raw Permalink Blame History

# 🔗 Blockchain Module — Complete Documentation
> **LexiChain BFSI Platform — Chapter: Blockchain Integration**
>
> This document explains everything about the blockchain module:
> what it does, how it works, how the code is organized, and how to run it.
> Written for beginners with no prior blockchain knowledge.
---
## Table of Contents
1. [What is Blockchain and Why Do We Need It?](#1-what-is-blockchain-and-why-do-we-need-it)
2. [What Does Our Blockchain Module Do?](#2-what-does-our-blockchain-module-do)
3. [Architecture Overview](#3-architecture-overview)
4. [Smart Contract: DocumentRegistry.sol](#4-smart-contract-documentregistrysol)
5. [Server-Side Integration: BlockchainService](#5-server-side-integration-blockchainservice)
6. [Database Schema: Storing Proof Data](#6-database-schema-storing-proof-data)
7. [Server Actions: The API Layer](#7-server-actions-the-api-layer)
8. [Frontend: Blockchain Explorer Page](#8-frontend-blockchain-explorer-page)
9. [Complete Data Flow](#9-complete-data-flow)
10. [How to Run Locally](#10-how-to-run-locally)
11. [Deploying to Sepolia Testnet](#11-deploying-to-sepolia-testnet)
12. [Technology Choices & Rationale](#12-technology-choices--rationale)
13. [File Reference](#13-file-reference)
---
## 1. What is Blockchain and Why Do We Need It?
### The Problem (in simple terms)
When a client sends an insurance claim or uploads a contract, they need **proof** that they submitted it on a specific date. Without proof:
- The insurance company could claim "we never received it"
- Deadlines could be disputed
- There's no transparency
### The Solution: Blockchain as a Notary
A **blockchain** is like a public, tamper-proof notebook. Once you write something in it, **nobody can erase or modify it** — not even the person who wrote it.
We use the blockchain as a **digital notary**:
1. We take the uploaded contract PDF
2. We create a unique **fingerprint** (hash) of that file
3. We write that fingerprint into the blockchain with a timestamp
4. Now there's permanent, verifiable proof that this exact document existed at this exact time
> **Key insight**: We don't store the actual document on the blockchain (that would be expensive). We only store its **fingerprint** (64 characters). If the document ever changes, even by one byte, the fingerprint would be completely different — proving tampering.
### What is a Smart Contract?
A **smart contract** is a program that runs on the blockchain. Think of it as a vending machine:
- You put in a coin (send a transaction)
- The machine executes its programmed logic
- The result is permanent and visible to everyone
Our smart contract (`DocumentRegistry.sol`) has two main functions:
- **Register**: Store a document fingerprint with a timestamp
- **Verify**: Check if a fingerprint exists and when it was stored
---
## 2. What Does Our Blockchain Module Do?
### Features Implemented
| Feature | Description |
| ------------------------- | --------------------------------------------------------------------------- |
| **Auto-Registration** | After AI analyzes a contract, its hash is automatically registered on-chain |
| **Manual Registration** | Users can register unregistered contracts via the Blockchain Explorer |
| **Document Verification** | Paste any document hash to check if it exists on-chain |
| **Transaction Explorer** | View all blockchain transactions with details |
| **Network Stats** | Live stats: verified documents, latest block, network status |
| **Proof Badges** | Contract list shows which contracts are blockchain-verified |
### What Happens When a User Uploads a Contract?
```
User uploads PDF → AI analyzes it → Blockchain registers the hash
```
The entire flow is automatic. The user doesn't need:
- ❌ MetaMask or any wallet
- ❌ Cryptocurrency knowledge
- ❌ To pay anything
Everything runs **server-side** with a platform wallet.
---
## 3. Architecture Overview
### High-Level Flow
```mermaid
flowchart TD
subgraph "User Browser"
UI[Next.js Frontend]
end
subgraph "Next.js Server"
SA[Server Actions<br/>blockchain.action.ts]
BS[BlockchainService<br/>blockchain.service.ts]
CA[Contract Action<br/>contract.action.ts]
end
subgraph "Data Layer"
DB[(PostgreSQL<br/>Prisma ORM)]
UT[UploadThing<br/>File Storage]
end
subgraph "Blockchain Network"
SC[Smart Contract<br/>DocumentRegistry.sol]
HN[Hardhat Local Node<br/>or Sepolia Testnet]
end
UI -->|"1. Upload contract"| CA
CA -->|"2. AI analyzes"| CA
CA -->|"3. Hash + register"| BS
BS -->|"4. Download PDF"| UT
BS -->|"5. SHA-256 hash"| BS
BS -->|"6. Send transaction"| SC
SC -->|"7. Store on-chain"| HN
BS -->|"8. Save proof"| DB
UI -->|"View /blockchain"| SA
SA -->|"Read transactions"| DB
SA -->|"Verify on-chain"| SC
```
### Network Modes
| Mode | When | URL | Cost |
| ----------- | ----------------- | ----------------------- | -------------- |
| **Hardhat** | Development | `http://127.0.0.1:8545` | Free (local) |
| **Sepolia** | Demo/Presentation | Via Alchemy/Infura RPC | Free (testnet) |
The mode is controlled by a single env variable: `BLOCKCHAIN_NETWORK`.
---
## 4. Smart Contract: DocumentRegistry.sol
**Location**: `blockchain/contracts/DocumentRegistry.sol`
### What It Does
The smart contract is written in **Solidity** (the programming language for Ethereum). It stores document fingerprints on the blockchain.
### Data Structures
```solidity
struct DocumentRecord {
uint256 timestamp; // When the document was registered
address depositor; // Who registered it (our server wallet)
string fileName; // Original file name
bool exists; // Whether this record is valid
}
```
### Core Functions
```mermaid
flowchart LR
subgraph "Write Operations (costs gas)"
R[registerDocument<br/>bytes32 hash, string fileName]
end
subgraph "Read Operations (free)"
V[verifyDocument<br/>bytes32 hash]
T[getTimestamp<br/>bytes32 hash]
D[getDocumentsByDepositor<br/>address]
end
R --> |"Stores hash + timestamp"| BC[(Blockchain State)]
BC --> V
BC --> T
BC --> D
```
#### `registerDocument(bytes32 _docHash)`
- **Purpose**: Store a document hash on-chain
- **Access**: Only the contract owner (our server wallet)
- **Guard**: Prevents duplicate registration (same hash can't be registered twice)
- **Event**: Emits `DocumentRegistered` for off-chain indexing
#### `verifyDocument(bytes32 _docHash)`
- **Purpose**: Check if a hash exists and get its details
- **Cost**: Free (read-only, no gas)
- **Returns**: `(exists, timestamp, depositor)`
### How the Hash Works
```mermaid
flowchart LR
PDF[Contract PDF<br/>2.4 MB] -->|SHA-256| HASH[0x7f83b165...4e2a<br/>32 bytes]
HASH -->|Store on-chain| BC[Blockchain]
PDF2[Same PDF] -->|SHA-256| HASH2[0x7f83b165...4e2a<br/>Identical hash!]
PDF3[Modified PDF<br/>1 byte changed] -->|SHA-256| HASH3[0xa1b2c3d4...9z8y<br/>Completely different!]
```
> **SHA-256** is a one-way function. You can't reconstruct the document from the hash, but the same document always produces the same hash.
### Testing
14 tests cover all functionality:
```
✓ should set the deployer as owner
✓ should start with zero documents
✓ should register a document and emit event
✓ should store correct timestamp
✓ should increment totalDocuments counter
✓ should prevent duplicate registration
✓ should allow different users to register different documents
✓ should verify a registered document
✓ should return false for unregistered document
✓ should track all documents by a depositor
✓ should return correct document count
✓ should transfer ownership
✓ should prevent non-owner from transferring ownership
✓ should prevent transfer to zero address
```
---
## 5. Server-Side Integration: BlockchainService
**Location**: `lib/services/blockchain.service.ts`
### Why Server-Side?
Most blockchain dApps require users to install MetaMask and sign transactions. This is bad UX for a BFSI enterprise platform because:
- Users shouldn't need crypto knowledge
- The platform manages documents, not individual users
- Server-side signing is more reliable
Instead, we use a **server wallet**: a private key stored in `.env` that the server uses to sign transactions automatically.
### How It Connects to the Blockchain
```mermaid
sequenceDiagram
participant S as Server Action
participant BS as BlockchainService
participant P as ethers.js Provider
participant W as ethers.js Wallet
participant C as Smart Contract
S->>BS: hashAndRegister(fileUrl, fileName)
BS->>BS: Download PDF from UploadThing
BS->>BS: Compute SHA-256 hash
BS->>P: Connect to RPC (Hardhat/Sepolia)
BS->>W: Sign transaction with private key
W->>C: registerDocument(hash)
C-->>W: Transaction receipt
W-->>BS: txHash, blockNumber, blockTimestamp
BS-->>S: BlockchainProof object
```
### Key Methods
| Method | Purpose | Gas Cost |
| ------------------------------------ | ------------------------------- | ---------------- |
| `hashDocument(fileUrl)` | Download file + compute SHA-256 | None (off-chain) |
| `registerOnChain(hash, fileName)` | Send tx to smart contract | ~50,000 gas |
| `verifyOnChain(hash)` | Read-only check | Free |
| `hashAndRegister(fileUrl, fileName)` | Combined: hash + register | ~50,000 gas |
| `getNetworkStats()` | Get block number, total docs | Free |
| `isConfigured()` | Check if env vars are set | None |
### Graceful Degradation
If blockchain is not configured (env vars missing), the service returns `isConfigured() = false` and all blockchain features are silently disabled. The rest of the app works normally.
---
## 6. Database Schema: Storing Proof Data
**Location**: `prisma/schema.prisma`
### Contract Model (updated fields)
```prisma
model Contract {
// ... existing fields ...
// Blockchain proof-of-deposit
documentHash String? // SHA-256 hash
txHash String? // Ethereum transaction hash
blockNumber Int? // Block number
blockTimestamp DateTime? // Block timestamp
blockchainNetwork String? // 'hardhat' | 'sepolia'
contractAddress String? // Smart contract address
}
```
### BlockchainTransaction Model (new)
```prisma
model BlockchainTransaction {
id String @id
userId String // Who triggered the registration
contractId String // Which contract was registered
documentHash String // SHA-256 hash
txHash String @unique // Ethereum tx hash
blockNumber Int // Block where tx was mined
blockTimestamp DateTime // Proof timestamp
network String // 'hardhat' | 'sepolia'
contractAddress String // Smart contract address
status String // PENDING, CONFIRMED, FAILED
createdAt DateTime
}
```
### Why Two Places?
- **Contract fields**: Quick access to proof data when displaying a single contract
- **BlockchainTransaction**: Separate table for the explorer page, supports querying all transactions for a user independently of contracts
---
## 7. Server Actions: The API Layer
**Location**: `features/blockchain/api/blockchain.action.ts`
### Actions Available
```mermaid
flowchart TD
subgraph "Blockchain Server Actions"
A1[registerContractOnBlockchain<br/>contractId → proof]
A2[verifyContractOnBlockchain<br/>contractId → verification]
A3[verifyDocumentHashOnBlockchain<br/>hash → exists/timestamp]
A4[getBlockchainTransactions<br/>→ transaction list]
A5[getBlockchainStats<br/>→ network stats]
end
subgraph "Called by"
UI1[Blockchain Explorer Page]
UI2[Contract List - Register Button]
UI3[Analysis Flow - Auto]
end
UI1 --> A3
UI1 --> A4
UI1 --> A5
UI2 --> A1
UI3 --> A1
```
### Auto-Registration Flow
In `features/contracts/api/contract.action.ts`, after AI analysis completes:
```typescript
// After AI analysis + RAG chunking...
try {
if (BlockchainService.isConfigured()) {
const proof = await BlockchainService.hashAndRegister(
contract.fileUrl,
contract.fileName
);
// Save proof to Contract + BlockchainTransaction
await prisma.contract.update({...});
await prisma.blockchainTransaction.create({...});
}
} catch (blockchainError) {
// Non-blocking: blockchain failure doesn't break analysis
console.warn("Blockchain registration skipped:", blockchainError);
}
```
> **Critical design decision**: Blockchain registration is wrapped in a try/catch. If the Hardhat node is down or there's a network issue, the AI analysis still completes successfully. Blockchain is an enhancement, not a dependency.
---
## 8. Frontend: Blockchain Explorer Page
**Location**: `app/(dashboard)/blockchain/page.tsx`
### Page Layout
```
┌─────────────────────────────────────────────────┐
│ 🔗 Blockchain Explorer [Refresh] │
├────────────┬────────────┬──────────┬────────────┤
│ Verified │ Latest │ Network │ Wallet │
│ Documents │ Block │ Status │ Address │
│ 12 │ #847 │ ● Live │ 0xf39F... │
├────────────┴────────────┴──────────┴────────────┤
│ ⚠️ 3 contracts not yet on blockchain │
│ ┌─ Insurance Auto [Register] ─┐ │
│ └─ Home Loan Policy [Register] ─┘ │
├──────────────────────┬──────────────────────────┤
│ Transaction History │ Verify Document │
│ ────────────────── │ ────────────────── │
│ ✓ Insurance Auto │ [Hash input field] │
│ Tx: 0x7f83... │ [Verify On-Chain] │
│ Block: #845 │ │
│ Time: Apr 19 │ ✓ Document Verified │
│ ────────────────── │ Timestamp: ... │
│ ✓ Home Loan │ Depositor: 0xf39F.. │
│ Tx: 0xa1b2... │ │
└──────────────────────┴──────────────────────────┘
```
### Navigation
The Blockchain page is accessible from the sidebar navigation at `/blockchain`, alongside Analytics and Contracts.
---
## 9. Complete Data Flow
### End-to-End: Upload → Proof
```mermaid
sequenceDiagram
actor U as User
participant UI as Browser
participant SA as Server Action
participant AI as AI Service
participant BS as BlockchainService
participant ES as EmailService
participant SC as Smart Contract
participant DB as PostgreSQL
U->>UI: Upload contract PDF
UI->>SA: saveContract(fileData)
SA->>DB: Create contract (UPLOADED)
SA->>SA: analyzeContractAction(id)
SA->>AI: Analyze document (Gemini)
AI-->>SA: AI results (title, dates, etc.)
SA->>DB: Update contract (COMPLETED)
Note over SA,SC: Blockchain Registration (automatic)
SA->>BS: hashAndRegister(fileUrl, fileName)
BS->>BS: Download PDF
BS->>BS: SHA-256 hash → 0x7f83b1...
BS->>SC: registerDocument(hash)
SC->>SC: Store hash + timestamp
SC-->>BS: Transaction receipt
BS-->>SA: BlockchainProof
SA->>DB: Save txHash, blockNumber, etc.
SA->>DB: Create BlockchainTransaction
SA->>ES: Send analysis + blockchain proof email
ES-->>U: Email received (or Ethereal preview in dev)
SA-->>UI: Success!
Note over U,UI: User visits /blockchain
U->>UI: Click "Blockchain" in sidebar
UI->>SA: getBlockchainTransactions()
SA->>DB: Fetch all transactions
DB-->>SA: Transaction list
SA-->>UI: Display in explorer
Note over U,UI: User verifies a document
U->>UI: Paste document hash
UI->>SA: verifyDocumentHashOnBlockchain(hash)
SA->>BS: verifyOnChain(hash)
BS->>SC: verifyDocument(hash)
SC-->>BS: (exists, timestamp, depositor)
BS-->>SA: Verification result
SA-->>UI: "✓ Document Verified"
```
---
## 10. How to Run Locally
### Prerequisites
- Node.js installed
- The Next.js app running (`npm run dev`)
### Step 1: Start the Hardhat Node
Open a **new terminal** and run:
```bash
cd blockchain
npx hardhat node
```
This starts a local Ethereum blockchain at `http://127.0.0.1:8545` with 20 pre-funded accounts (10,000 ETH each).
> ⚠️ **Keep this terminal open!** The node must be running for blockchain features to work.
### Step 2: Deploy the Smart Contract
In another terminal:
```bash
cd blockchain
npx hardhat run scripts/deploy.ts --network localhost
```
Copy the contract address and put it in your `.env`:
```env
BLOCKCHAIN_CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
```
### Step 3: Start the Next.js App
```bash
npm run dev
```
### Step 4: Test the Flow
1. Upload a contract PDF
2. Wait for AI analysis to complete
3. Check the blockchain icon/badge on the contract
4. Visit `/blockchain` to see the transaction in the explorer
5. Copy a document hash and paste it in the verification panel
### Important Notes
- If you restart the Hardhat node, you need to **redeploy** the contract (step 2) because the local blockchain state is reset
- The Hardhat node logs every transaction in real-time — you can watch the blockchain activity live
- All blockchain features gracefully degrade: if the node is offline, the app still works normally without blockchain
---
## 11. Deploying to Sepolia Testnet
For your PFE presentation, you can deploy to the real Ethereum Sepolia testnet to get actual Etherscan links.
### Step 1: Get a Free RPC URL
1. Go to [alchemy.com](https://alchemy.com) (free account)
2. Create a new app → select "Ethereum Sepolia"
3. Copy the HTTPS URL
### Step 2: Get Free Sepolia ETH
1. Go to [sepoliafaucet.com](https://sepoliafaucet.com) or [faucets.chain.link](https://faucets.chain.link)
2. Paste your wallet address
3. Receive 0.5 Sepolia ETH (enough for hundreds of transactions)
### Step 3: Update .env
```env
BLOCKCHAIN_NETWORK=sepolia
BLOCKCHAIN_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
BLOCKCHAIN_PRIVATE_KEY=your_sepolia_wallet_private_key
BLOCKCHAIN_CONTRACT_ADDRESS= # Will be filled after deployment
```
### Step 4: Deploy to Sepolia
```bash
# Set env vars for hardhat
set SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
set DEPLOYER_PRIVATE_KEY=your_private_key
cd blockchain
npx hardhat run scripts/deploy.ts --network sepolia
```
### Step 5: Verify on Etherscan
After deploying, transactions will have real Etherscan links:
```
https://sepolia.etherscan.io/tx/0x...
```
---
## 12. Technology Choices & Rationale
| Technology | Why We Chose It |
| ------------------------ | ----------------------------------------------------------------- |
| **Solidity 0.8.24** | Latest stable version with built-in overflow protection |
| **Hardhat** | Industry standard for Solidity development, free local blockchain |
| **ethers.js v6** | Modern, lightweight, TypeScript-native Ethereum library |
| **SHA-256** | Standard cryptographic hash, deterministic, collision-resistant |
| **Server-side wallet** | Users don't need MetaMask; enterprise-grade UX |
| **Sepolia testnet** | Official Ethereum testnet, free, has Etherscan explorer |
| **Graceful degradation** | Blockchain is optional; app works perfectly without it |
### Why NOT Web3j / Java?
The original project spec suggested Web3j (Java library). We chose ethers.js instead because:
1. Our backend is **Next.js/TypeScript**, not Spring Boot
2. ethers.js has **better TypeScript support** and is more actively maintained
3. Both libraries do the same job — interact with Ethereum — but ethers.js is native to our stack
---
## 13. File Reference
### Smart Contract Layer
| File | Purpose |
| ------------------------------------------- | ----------------------- |
| `blockchain/contracts/DocumentRegistry.sol` | Solidity smart contract |
| `blockchain/test/DocumentRegistry.test.ts` | 14 comprehensive tests |
| `blockchain/scripts/deploy.ts` | Deployment script |
| `blockchain/hardhat.config.ts` | Hardhat configuration |
| `blockchain/package.json` | Hardhat dependencies |
### Service Layer
| File | Purpose |
| ------------------------------------ | ---------------------------- |
| `lib/services/blockchain.service.ts` | Core blockchain interactions |
| `lib/services/blockchain.types.ts` | TypeScript type definitions |
### Server Actions
| File | Purpose |
| ---------------------------------------------- | ------------------------------ |
| `features/blockchain/api/blockchain.action.ts` | Blockchain server actions |
| `features/contracts/api/contract.action.ts` | Updated with auto-registration |
### Frontend
| File | Purpose |
| --------------------------------------- | ---------------------------- |
| `app/(dashboard)/blockchain/page.tsx` | Blockchain Explorer page |
| `app/(dashboard)/blockchain/layout.tsx` | Page metadata |
| `components/layout/navigation.tsx` | Updated with blockchain link |
### Database
| File | Purpose |
| ---------------------- | ------------------------------ |
| `prisma/schema.prisma` | Updated with blockchain fields |
### Configuration
| File | Purpose |
| -------------- | ----------------------------- |
| `.env` | Blockchain env vars |
| `.env.example` | Template for new developers |
| `.gitignore` | Blockchain artifacts excluded |
---
## Glossary
| Term | Definition |
| -------------------- | -------------------------------------------------------------------- |
| **Hash** | A fixed-size fingerprint of data. Same input → same output. |
| **SHA-256** | A specific hash algorithm producing 256-bit (32-byte) outputs |
| **Smart Contract** | A program stored on the blockchain that executes automatically |
| **Gas** | The fee for executing operations on Ethereum (free on testnet) |
| **Block** | A batch of transactions grouped together on the blockchain |
| **Transaction (Tx)** | A single operation on the blockchain (e.g., registering a hash) |
| **Tx Hash** | A unique identifier for a transaction (like a receipt number) |
| **Block Number** | The sequential number of the block containing a transaction |
| **Block Timestamp** | The time the block was created (proof of when the tx happened) |
| **Private Key** | Secret key used to sign transactions (like a password) |
| **Address** | Public identifier derived from the private key (like a username) |
| **ABI** | Application Binary Interface — the "API spec" of a smart contract |
| **Hardhat** | Development tool for writing, testing, and deploying smart contracts |
| **Sepolia** | Ethereum test network for free experimentation |
| **ethers.js** | JavaScript library for interacting with the Ethereum blockchain |
| **Faucet** | A service that gives free test ETH for development |
Reference in New Issue View Git Blame Copy Permalink