# 🔗 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                   |
