Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
326 lines (243 loc) · 8.67 KB

SETUP_GUIDE.md

File metadata and controls

326 lines (243 loc) · 8.67 KB
Raw

🚀 Complete Setup Guide - Frontend Connected to Blockchain

Overview

This guide will help you connect the frontend (React) to the backend (Hardhat blockchain) so users can add projects and reports without needing MetaMask. The system uses cookie-based persistent user IDs stored in localStorage.

📋 Prerequisites

Make sure you have:

  • ✅ Node.js installed
  • ✅ npm installed
  • ✅ Both be and fe folders with dependencies installed

🔧 Step-by-Step Setup

Step 1: Start Hardhat Local Blockchain

Open Terminal 1 (PowerShell):

cd d:\maxxing\be
npx hardhat node

Expected Output:

Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/

Accounts
========
Account #0:  0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266 (10000 ETH)
...

✅ Keep this terminal open! The blockchain needs to stay running.

Step 2: Deploy Smart Contract

Open Terminal 2 (PowerShell):

cd d:\maxxing\be
node scripts/deploy-simple.cjs

Expected Output:

🚀 Deploying TransparencyLedger contract...
📝 Deploying from account: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
✅ TransparencyLedger deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3

📝 IMPORTANT: Update this address in your frontend!
   File: fe/src/utils/web3.js
   const DEFAULT_CONTRACT_ADDRESS = "0x5FbDB2315678afecb367f032d93F642f64180aa3"

✅ Copy the contract address! You'll need it for the next step.

Step 3: Update Frontend Contract Address

Open fe/src/utils/web3.js and update the contract address:

// Find this line (around line 18):
const DEFAULT_CONTRACT_ADDRESS = "0x5FbDB2315678afecb367f032d93F642f64180aa3"

// Replace it with your deployed contract address from Step 2
const DEFAULT_CONTRACT_ADDRESS = "YOUR_DEPLOYED_ADDRESS_HERE"

Step 4: Start Frontend Development Server

In Terminal 2 (or open Terminal 3):

cd d:\maxxing\fe
npm run dev

Expected Output:

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

✅ Open your browser and go to: http://localhost:5173/

🎯 How It Works

Cookie-Based User System (No MetaMask!)

  1. First Visit:

    • System generates a unique persistent ID (e.g., 0x1a2b3c4d...)
    • ID is saved to localStorage under key user_id
    • This ID stays forever on the device (even after closing browser)

  2. Adding a Project:

    • User fills out the form
    • System uses ONE of the Hardhat test accounts (Account #0) to send the transaction
    • User's cookie-based ID is recorded in the contract
    • No MetaMask popup appears!

  3. Viewing Data:

    • All data is read from the blockchain
    • Shows projects from all users
    • Each project shows who added it

🔑 Backend System (How Transactions Work)

The backend uses Hardhat Account #0 as a "shared wallet" to send all transactions:

// In deploy-simple.cjs and web3.js
const privateKey = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
const wallet = new ethers.Wallet(privateKey, provider);

Important: This is ONLY for local development! Never use these keys in production!

📝 Testing the System

Test 1: Add a Project (No MetaMask)

  1. Open http://localhost:5173/
  2. Click "Add Project" button
  3. Fill in the form:
    • Project Name: "Test Road Construction"
    • Project Value: "1000000"
    • Contractor: "ABC Company"
    • Location: "Jakarta"
  4. Click "Add Project"
  5. ✅ Success popup appears with transaction hash
  6. ✅ Project appears in the list immediately
  7. ✅ No MetaMask popup!

Test 2: Report Corruption (No MetaMask)

  1. Click "Report Corruption" button
  2. Fill in the form:
    • Related Project: Select a project (optional)
    • Type: Choose corruption type
    • Description: Write detailed description (min 20 chars)
    • Anonymous: Check if you want anonymity
  3. Click "Submit Report"
  4. ✅ Success popup appears
  5. ✅ Go to "Laporan" page to see your report
  6. ✅ No MetaMask popup!

Test 3: Persistent User ID

  1. Add a project
  2. Note your user ID (displayed in console or project details)
  3. Close the browser completely
  4. Reopen and visit the site
  5. Add another project
  6. ✅ Same user ID is used!

🛠️ Troubleshooting

Problem: "Failed to fetch"

Solution:

  • Make sure Hardhat node is running (Terminal 1)
  • Check if the contract is deployed
  • Verify contract address in fe/src/utils/web3.js

Problem: "Contract not found"

Solution:

  • Redeploy the contract: node scripts/deploy-simple.cjs
  • Update the contract address in fe/src/utils/web3.js
  • Restart the frontend server

Problem: "Transaction failed"

Solution:

  • Stop Hardhat node (Ctrl+C)
  • Clear cache: Remove-Item -Recurse -Force cache,artifacts
  • Restart Hardhat node
  • Redeploy contract

Problem: Port 8545 already in use

Solution:

# Find and kill the process
Get-Process | Where-Object {$_.ProcessName -like "*node*"} | Stop-Process -Force

📊 Architecture

┌─────────────────────────────────────────────┐
│           Frontend (React + Vite)           │
│              Port: 5173                     │
│                                             │
│  - Cookie-based User ID (localStorage)     │
│  - web3.js (ethers.js integration)         │
│  - No MetaMask required!                    │
└──────────────────┬──────────────────────────┘
                   │
                   │ HTTP Requests
                   │ (JSON-RPC)
                   ▼
┌─────────────────────────────────────────────┐
│      Hardhat Local Blockchain Node          │
│              Port: 8545                     │
│                                             │
│  - 20 test accounts (each 10,000 ETH)      │
│  - Uses Account #0 for all transactions    │
│  - TransparencyLedger Contract              │
└─────────────────────────────────────────────┘

🔒 Security Notes

For Local Development Only:

  • ✅ Using Hardhat test accounts
  • ✅ All private keys are publicly known (for testing)
  • ❌ NEVER use these private keys in production
  • ❌ NEVER deploy to mainnet with these keys

For Production:

  • Use proper wallet management
  • Implement server-side transaction signing
  • Add authentication and authorization
  • Use environment variables for sensitive data

📦 File Structure

d:\maxxing\
├── be/                              # Backend
│   ├── contracts/
│   │   └── TransparencyLedger.sol   # Smart contract
│   ├── scripts/
│   │   └── deploy-simple.cjs         # Deployment script
│   ├── hardhat.config.ts            # Hardhat config
│   └── package.json
│
└── fe/                              # Frontend
    ├── src/
    │   ├── components/
    │   │   ├── AddProject.jsx       # Add project form
    │   │   └── ReportCorruption.jsx # Report form
    │   ├── pages/
    │   │   ├── Home.jsx             # Main page
    │   │   └── Reports.jsx          # Reports page
    │   └── utils/
    │       └── web3.js              # Blockchain integration
    └── package.json

🎉 Success Checklist

Before considering the setup complete, verify:

  • Hardhat node is running on port 8545
  • Smart contract is deployed successfully
  • Contract address is updated in fe/src/utils/web3.js
  • Frontend is running on port 5173
  • Can add projects without MetaMask
  • Can report corruption without MetaMask
  • User ID persists across browser sessions
  • All data is stored on blockchain
  • Transaction hashes are displayed

🚀 Quick Start Commands

Terminal 1 - Start Blockchain:

cd d:\maxxing\be && npx hardhat node

Terminal 2 - Deploy & Start Frontend:

cd d:\maxxing\be && node scripts/deploy-simple.cjs
# Copy the contract address
# Update fe/src/utils/web3.js with the address
cd ..\fe && npm run dev

Open Browser:

http://localhost:5173/

📞 Need Help?

  • Check Terminal 1 for blockchain logs
  • Check Terminal 2 for frontend logs
  • Check browser console (F12) for errors
  • All transactions are logged in Terminal 1

Happy coding! 🎉