LexiChain/docs/implementation_plan.md

# Blockchain Integration — LexiChain BFSI Platform

## Goal

Add a **fully functional, 100% free** blockchain module to the existing LexiChain platform. This module provides:

1. **Proof of Deposit** — SHA-256 hash of each contract document is stored on-chain with a timestamp, making submission dates provable and tamper-proof.
2. **On-chain Verification** — Anyone can verify that a document existed at a specific time.
3. **Blockchain Explorer UI** — A new `/blockchain` page showing all on-chain transactions + per-contract verification status.

---

## User Review Required

> [!IMPORTANT]
> **Zero cost guaranteed.** The entire implementation uses:
> - **Hardhat local node** for development (free, instant, unlimited)
> - **Ethereum Sepolia testnet** for demo/presentation (free test ETH from faucets)
> - No MetaMask required for end-users — all blockchain operations run **server-side** via a backend wallet

> [!WARNING]
> **Server-side wallet approach**: Instead of requiring users to install MetaMask and sign transactions, the server holds a private key and signs transactions on behalf of the platform. This is the right UX for a BFSI enterprise platform (users shouldn't need crypto knowledge). The private key is stored in `.env` and never exposed to the client.

> [!IMPORTANT]
> **Dual-mode architecture**: 
> - `NODE_ENV=development` → Hardhat local node (`http://127.0.0.1:8545`)
> - `NODE_ENV=production` or env flag → Sepolia testnet (via free Alchemy/Infura RPC)
> 
> You can switch between modes with a single env variable change.

---

## Proposed Changes

### Component 1: Smart Contract (Hardhat + Solidity)

Creates a standalone `blockchain/` directory at the project root with a Hardhat project for developing, testing, and deploying the smart contract.

#### [NEW] [blockchain/contracts/DocumentRegistry.sol](file:///c:/Stage/Project-PFE/bfsi-project/blockchain/contracts/DocumentRegistry.sol)

Solidity smart contract with:
- `registerDocument(bytes32 docHash, string calldata fileName)` — stores hash + metadata on-chain
- `verifyDocument(bytes32 docHash)` — checks if a hash exists and returns timestamp + depositor
- `getDocumentsByDepositor(address depositor)` — lists all docs registered by an address
- Events: `DocumentRegistered(bytes32 indexed docHash, uint256 timestamp, address indexed depositor, string fileName)`
- Modifier to prevent duplicate registrations

#### [NEW] [blockchain/hardhat.config.ts](file:///c:/Stage/Project-PFE/bfsi-project/blockchain/hardhat.config.ts)

Hardhat config with:
- Local Hardhat network (default, free)
- Sepolia network config (reads RPC URL + private key from env)
- Solidity 0.8.24 compiler

#### [NEW] [blockchain/test/DocumentRegistry.test.ts](file:///c:/Stage/Project-PFE/bfsi-project/blockchain/test/DocumentRegistry.test.ts)

Comprehensive tests:
- Register a document and verify timestamp
- Prevent duplicate registration
- Verify non-existent document returns zero
- Multiple documents by same depositor

#### [NEW] [blockchain/scripts/deploy.ts](file:///c:/Stage/Project-PFE/bfsi-project/blockchain/scripts/deploy.ts)

Deployment script that outputs the contract address for use in `.env`.

#### [NEW] [blockchain/package.json](file:///c:/Stage/Project-PFE/bfsi-project/blockchain/package.json)

Separate package.json for the Hardhat project (keeps blockchain dependencies isolated from the Next.js app).

---

### Component 2: Next.js Blockchain Service Layer

Server-side service that connects to the blockchain from Next.js server actions. No browser wallet needed.

#### [NEW] [lib/services/blockchain.service.ts](file:///c:/Stage/Project-PFE/bfsi-project/lib/services/blockchain.service.ts)

Core blockchain service:
- `hashDocument(fileUrl: string): Promise<string>` — downloads contract PDF and computes SHA-256
- `registerOnChain(documentHash: string, fileName: string): Promise<{ txHash, blockNumber, blockTimestamp }>` — sends transaction to smart contract
- `verifyOnChain(documentHash: string): Promise<{ exists, timestamp, depositor }>` — reads on-chain data
- Uses `ethers.js v6` with `JsonRpcProvider` + `Wallet` (server-side, no MetaMask)
- Auto-detects network mode from env vars

#### [NEW] [lib/services/blockchain.types.ts](file:///c:/Stage/Project-PFE/bfsi-project/lib/services/blockchain.types.ts)

TypeScript types for blockchain data:
```typescript
interface BlockchainProof {
  documentHash: string;
  txHash: string;
  blockNumber: number;
  blockTimestamp: Date;
  network: 'hardhat' | 'sepolia';
  contractAddress: string;
  explorerUrl: string | null; // Sepolia etherscan link
}
```

---

### Component 3: Server Actions & Integration

#### [NEW] [features/blockchain/api/blockchain.action.ts](file:///c:/Stage/Project-PFE/bfsi-project/features/blockchain/api/blockchain.action.ts)

New server actions:
- `registerContractOnBlockchain(contractId: string)` — hashes + registers + saves proof to DB
- `verifyContractOnBlockchain(contractId: string)` — verifies on-chain status
- `getBlockchainTransactions()` — fetches all blockchain proofs for the authenticated user

#### [MODIFY] [features/contracts/api/contract.action.ts](file:///c:/Stage/Project-PFE/bfsi-project/features/contracts/api/contract.action.ts)

After successful AI analysis, **automatically trigger** blockchain registration:
- In `analyzeContractAction()`, after `ContractService.updateWithAIResults()`, call `BlockchainService.hashAndRegister()`
- Save `documentHash`, `txHash` to the contract record
- This means every analyzed contract gets an automatic on-chain proof

---

### Component 4: Database Schema Update

#### [MODIFY] [prisma/schema.prisma](file:///c:/Stage/Project-PFE/bfsi-project/prisma/schema.prisma)

Expand the existing blockchain placeholder fields on `Contract`:
```diff
  // Blockchain (later)
- documentHash String?
- txHash       String?
- ipfsUrl      String?
+ documentHash    String?
+ txHash          String?
+ blockNumber     Int?
+ blockTimestamp   DateTime?
+ blockchainNetwork String?  // 'hardhat' | 'sepolia'
+ contractAddress   String?  // smart contract address used
```

Add a new `BlockchainTransaction` model for the explorer view:
```prisma
model BlockchainTransaction {
  id             String   @id @default(cuid())
  userId         String
  user           User     @relation(...)
  contractId     String
  contract       Contract @relation(...)
  
  documentHash   String
  txHash         String   @unique
  blockNumber    Int
  blockTimestamp  DateTime
  network        String   // 'hardhat' | 'sepolia'
  contractAddress String
  status         String   @default("CONFIRMED") // PENDING, CONFIRMED, FAILED
  
  createdAt      DateTime @default(now())
}
```

---

### Component 5: Frontend — Blockchain Explorer Page

#### [NEW] [app/(dashboard)/blockchain/page.tsx](file:///c:/Stage/Project-PFE/bfsi-project/app/(dashboard)/blockchain/page.tsx)

New dashboard page at `/blockchain` with:
- **Header stats**: Total verified contracts, latest block, network status
- **Transaction table**: All blockchain proofs with txHash, contract name, timestamp, verification status
- **Verification panel**: Paste a document hash to check its on-chain status
- **Network indicator**: Shows whether connected to Hardhat (local) or Sepolia

#### [NEW] [features/blockchain/components/blockchain-explorer.tsx](file:///c:/Stage/Project-PFE/bfsi-project/features/blockchain/components/blockchain-explorer.tsx)

Main explorer component with:
- Animated blockchain-themed cards
- Transaction list with expandable details
- Real-time verification status badges
- Network health indicator

#### [NEW] [features/blockchain/components/verify-document.tsx](file:///c:/Stage/Project-PFE/bfsi-project/features/blockchain/components/verify-document.tsx)

Standalone verification widget:
- File upload → compute hash → check on-chain
- Shows proof details if found (timestamp, block, depositor)
- Visual "Verified ✓" / "Not Found ✗" result

#### [NEW] [features/blockchain/components/blockchain-proof-badge.tsx](file:///c:/Stage/Project-PFE/bfsi-project/features/blockchain/components/blockchain-proof-badge.tsx)

Small badge component to show on contract cards:
- 🟢 "On-Chain Verified" (with txHash link)
- 🟡 "Pending" (registration in progress)
- ⚫ "Not Registered" (no blockchain proof yet)

---

### Component 6: Navigation & Integration Updates

#### [MODIFY] [components/layout/navigation.tsx](file:///c:/Stage/Project-PFE/bfsi-project/components/layout/navigation.tsx)

Add new nav item:
```typescript
{
  href: "/blockchain",
  label: "Blockchain",
  icon: <Link2 className="w-5 h-5" />,
  description: "On-chain proofs",
}
```

#### [MODIFY] [types/contract.types.ts](file:///c:/Stage/Project-PFE/bfsi-project/types/contract.types.ts)

Add blockchain fields to the Contract interface:
```typescript
blockNumber: number | null;
blockTimestamp: Date | null;
blockchainNetwork: string | null;
contractAddress: string | null;
```

#### [MODIFY] [.env.example](file:///c:/Stage/Project-PFE/bfsi-project/.env.example)

Add blockchain env vars:
```env
# Blockchain
BLOCKCHAIN_PRIVATE_KEY=        # Server wallet private key (Hardhat default for dev)
BLOCKCHAIN_RPC_URL=            # RPC endpoint (empty = Hardhat local)
BLOCKCHAIN_CONTRACT_ADDRESS=   # Deployed DocumentRegistry address
BLOCKCHAIN_NETWORK=hardhat     # 'hardhat' or 'sepolia'
SEPOLIA_RPC_URL=               # Free Alchemy/Infura Sepolia RPC
```

---

## Architecture Diagram

```mermaid
flowchart TD
    U[User Browser] --> UI[Next.js App Router]
    
    UI -->|Server Action| BA[blockchain.action.ts]
    BA --> BS[BlockchainService]
    BS -->|ethers.js v6| BC[Smart Contract on Blockchain]
    BS -->|Hash document| PDF[Contract PDF from UploadThing]
    BA --> DB[(PostgreSQL - BlockchainTransaction)]
    
    UI -->|Server Action| CA[contract.action.ts]
    CA -->|After AI analysis| BA
    
    subgraph "Local Dev"
        HN[Hardhat Node :8545]
    end
    
    subgraph "Demo/Production"
        SN[Sepolia Testnet]
    end
    
    BC -.-> HN
    BC -.-> SN
```

---

## Implementation Order

| Step | Component | Estimated Effort |
|------|-----------|-----------------|
| 1 | Hardhat project + Smart Contract + Tests | ~30 min |
| 2 | Deploy to local Hardhat node | ~5 min |
| 3 | `BlockchainService` (server-side ethers.js) | ~30 min |
| 4 | Prisma schema update + migration | ~10 min |
| 5 | Server actions (`blockchain.action.ts`) | ~20 min |
| 6 | Integration into `analyzeContractAction` | ~10 min |
| 7 | Blockchain Explorer page + components | ~45 min |
| 8 | Navigation update + proof badges | ~15 min |
| 9 | Deploy to Sepolia testnet (optional, for demo) | ~15 min |

**Total: ~3 hours of implementation**

---

## Open Questions

> [!IMPORTANT]
> **1. Auto-register vs. Manual button?**
> The plan currently auto-registers contracts on the blockchain after AI analysis completes. Alternatively, we could add a manual "Register on Blockchain" button per contract. Which do you prefer? (I recommend **both**: auto-register + manual re-register option)

> [!IMPORTANT]  
> **2. Sepolia for presentation?**
> Do you want me to also set up the Sepolia testnet deployment for your PFE presentation/jury? This gives you real Etherscan links to show. You'll just need to grab free Sepolia ETH from a faucet (takes 2 minutes). We can start with Hardhat local and add Sepolia later.

> [!IMPORTANT]
> **3. IPFS integration?**
> Your schema has an `ipfsUrl` field. Do you want to also store contract files on IPFS (using a free service like Pinata with 1GB free tier)? This would give you decentralized file storage + on-chain hash. Or should we skip this to keep things simpler?

---

## Verification Plan

### Automated Tests
1. **Smart contract tests** — `cd blockchain && npx hardhat test` (tests register, verify, duplicate prevention)
2. **Integration test** — Upload a contract → AI analysis → verify blockchain fields are populated in DB
3. **Service test** — Call `BlockchainService.hashDocument()` + `registerOnChain()` directly

### Manual Verification
1. Start Hardhat node → deploy contract → upload a contract in the app → check `/blockchain` page shows the transaction
2. Use the verification panel to re-verify a document hash
3. Check the contract detail view shows the "On-Chain Verified" badge
4. If Sepolia is configured: verify the txHash on [Sepolia Etherscan](https://sepolia.etherscan.io/)