ncmaxxing - Blockchain Transparency Ledger

A full-stack blockchain application for transparent project tracking and corruption reporting. Features a React frontend with cookie-based user authentication (no MetaMask required) and Ethereum smart contracts for immutable data storage.

Features

Core Functionality

Project Management: Add and track projects with complete details (name, value, contractor, location)
Corruption Reporting: Submit and view corruption reports with optional anonymity
Cookie-Based Authentication: Persistent user identification without wallet requirements
Real-time Blockchain Integration: All data stored on-chain with instant verification
Transaction Transparency: View transaction hashes and block confirmations
MetaMask-Free Operation: Hardhat test account handles all transactions automatically

Technical Highlights

Smart contract-based data persistence
Local Ethereum network for development
Modern React UI with Vite build system
Ethers.js v6 for blockchain interaction
Responsive design with Tailwind CSS

Project Structure

ncmaxxing/
├── be/                                # Backend (Smart Contracts)
│   ├── contracts/
│   │   └── TransparencyLedger.sol    # Main smart contract
│   ├── scripts/
│   │   ├── deploy-simple.cjs         # Contract deployment script
│   │   ├── start-and-deploy.cjs      # Automated node + deploy
│   │   ├── check-contract.cjs        # Contract verification utility
│   │   ├── check-transaction.cjs     # Transaction verification utility
│   │   └── check-blockchain-status.cjs # Blockchain status checker
│   ├── artifacts/                    # Compiled contract artifacts
│   ├── hardhat.config.ts            # Hardhat configuration
│   └── package.json                 # Backend dependencies
├── fe/                              # Frontend (React Application)
│   ├── src/
│   │   ├── components/
│   │   │   ├── AddProject.jsx       # Project submission form
│   │   │   ├── ReportCorruption.jsx # Corruption report form
│   │   │   └── TransactionPopup.jsx # Transaction confirmation UI
│   │   ├── pages/
│   │   │   ├── Home.jsx             # Main project listing page
│   │   │   └── Reports.jsx          # Corruption reports page
│   │   ├── utils/
│   │   │   └── web3.js              # Blockchain integration layer
│   │   ├── main.jsx                 # Application entry point
│   │   └── index.css                # Global styles
│   ├── index.html                   # HTML template
│   ├── vite.config.js               # Vite configuration
│   └── package.json                 # Frontend dependencies
├── START_BLOCKCHAIN.bat             # Batch script to start node
├── DEPLOY_CONTRACT.bat              # Batch script to deploy contract
├── START_FRONTEND.bat               # Batch script to start frontend
└── QUICKSTART.md                    # Quick reference guide

Prerequisites

Node.js v18+ and npm
Windows PowerShell (for batch scripts)
Git (for version control)

Installation

1. Clone Repository

git clone https://github.com/CAT-Cabang-Programming/ncmaxxing.git
cd ncmaxxing

2. Install Backend Dependencies

cd be
npm install

Required packages:

hardhat v3.0.7
ethers v6.15.0
@nomicfoundation/hardhat-toolbox-viem
@nomicfoundation/hardhat-ethers
solidity v0.8.28

3. Install Frontend Dependencies

cd ../fe
npm install

Required packages:

react v18.3.1
react-router-dom v7.1.1
ethers v6.15.0
vite v5.4.20
tailwindcss v3.4.17
lucide-react v0.469.0

Running the Application

Method 1: Automated Start (Recommended)

Using the provided wrapper script that manages both node and deployment:

cd be
node scripts/start-and-deploy.cjs

This script will:

Start the Hardhat blockchain node
Wait for node initialization
Deploy the TransparencyLedger contract
Display the contract address
Keep the node running

Expected output:

Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/
Node is ready! Deploying contract in 3 seconds...
DEPLOYING CONTRACT
TransparencyLedger deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3
DEPLOYMENT SUCCESS
Hardhat node is still running...
Press Ctrl+C to stop the blockchain

Keep this terminal open. The blockchain node must remain running.

Method 2: Using Batch Files (Windows)

Step 1: Start blockchain node

# Double-click START_BLOCKCHAIN.bat or run:
.\START_BLOCKCHAIN.bat

Keep this window open. Do not close it.

Step 2: Deploy smart contract

# In a new terminal, double-click DEPLOY_CONTRACT.bat or run:
.\DEPLOY_CONTRACT.bat

Copy the displayed contract address.

Step 3: Update frontend configuration

Edit fe/src/utils/web3.js line 34:

const DEFAULT_CONTRACT_ADDRESS = "0x5FbDB2315678afecb367f032d93F642f64180aa3"

Replace with your deployed contract address.

Step 4: Start frontend application

# Double-click START_FRONTEND.bat or run:
.\START_FRONTEND.bat

Method 3: Manual Start (Step by Step)

Terminal 1 - Blockchain Node:

cd be
npx hardhat node

Terminal 2 - Contract Deployment:

cd be
node scripts/deploy-simple.cjs

Note the contract address from output.

Terminal 3 - Frontend:

cd fe
npm run dev

Access the application at http://localhost:5173

Smart Contract Details

Contract: TransparencyLedger.sol

Location: be/contracts/TransparencyLedger.sol

Deployed Address (default local): 0x5FbDB2315678afecb367f032d93F642f64180aa3

Data Structures

Project Struct:

struct Project {
    uint256 id;              // Unique project identifier
    string projectName;      // Project name
    uint256 projectValue;    // Value in wei
    string workerCompany;    // Contractor company
    string location;         // Project location
    address addedBy;         // Address that added project
    uint256 timestamp;       // Block timestamp
}

CorruptionReport Struct:

struct CorruptionReport {
    uint256 id;              // Unique report identifier
    uint256 relatedProjectId; // Associated project ID (0 if none)
    string reportType;       // Type: bribery, embezzlement, fraud, nepotism, other
    string description;      // Detailed description
    address reportedBy;      // Reporter address (0x0 if anonymous)
    uint256 timestamp;       // Block timestamp
    bool isAnonymous;        // Anonymity flag
    string status;           // Status: pending, processing, investigating, resolved, rejected, dismissed
}

Public Functions

Project Management:

function addProject(
    string calldata _projectName,
    uint256 _projectValue,
    string calldata _workerCompany,
    string calldata _location
) external

function getAllProjects() external view returns (Project[] memory)

function getProjectById(uint256 _id) external view returns (Project memory)

function totalProjects() external view returns (uint256)

Corruption Reporting:

function reportCorruption(
    uint256 _relatedProjectId,
    string calldata _reportType,
    string calldata _description,
    bool _isAnonymous
) external

function getAllReports() external view returns (CorruptionReport[] memory)

function getReportsByProject(uint256 _projectId) external view returns (CorruptionReport[] memory)

function updateReportStatus(uint256 _reportId, string calldata _newStatus) external

function totalReports() external view returns (uint256)

Events

event ProjectAdded(
    uint256 indexed id,
    string projectName,
    uint256 projectValue,
    string workerCompany,
    string location,
    address indexed addedBy
)

event CorruptionReported(
    uint256 indexed id,
    uint256 indexed relatedProjectId,
    string reportType,
    address indexed reportedBy,
    bool isAnonymous
)

Frontend Architecture

Cookie-Based User System

The application implements a persistent user identification system using browser localStorage:

File: fe/src/utils/web3.js

function getUserId() {
  let userId = localStorage.getItem('user_id')
  if (!userId) {
    userId = '0x' + Array.from({length: 40}, () => 
      Math.floor(Math.random() * 16).toString(16)
    ).join('')
    localStorage.setItem('user_id', userId)
  }
  return userId
}

Features:

40-character hexadecimal identifier
Persists across browser sessions
No wallet or registration required
Automatically generated on first visit
Stored in localStorage under key user_id

Transaction Signing

All blockchain transactions are signed using Hardhat test account #0:

const HARDHAT_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
const HARDHAT_ACCOUNT = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"

This eliminates the need for MetaMask or user-managed wallets during development.

Web3 Service Layer

File: fe/src/utils/web3.js

Key methods:

initialize(): Connect to local blockchain node
addProject(): Submit new project with blockchain confirmation
getAllProjects(): Retrieve all projects from smart contract
reportCorruption(): Submit corruption report
getAllReports(): Retrieve all corruption reports
formatCurrency(): Format values for display

UI Components

AddProject.jsx:

Project submission form
Real-time validation
Transaction confirmation popup
Transaction hash display with copy functionality
Success/error handling

ReportCorruption.jsx:

Corruption report form
Project selection dropdown
Anonymous reporting option
Transaction confirmation
Report type categorization

TransactionPopup.jsx:

Transaction hash display
Copy to clipboard functionality
Block confirmation status
Close button with manual control

Pages

Home.jsx:

Project listing with blockchain data
Real-time statistics dashboard
Add project modal
Report corruption modal
Connection status indicator
Refresh functionality

Reports.jsx:

Corruption reports listing
Filtering by status and type
Search functionality
Pagination support
Report statistics dashboard

Configuration Files

Backend Configuration

hardhat.config.ts:

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox-viem";
import "@nomicfoundation/hardhat-ethers";

const config: HardhatUserConfig = {
  solidity: "0.8.28",
  networks: {
    hardhat: {
      chainId: 31337,
      type: "edr-simulated"
    },
    localhost: {
      url: "http://127.0.0.1:8545",
      type: "http"
    }
  }
};

Frontend Configuration

vite.config.js:

export default {
  server: {
    port: 5173,
    strictPort: true
  }
}

tailwind.config.cjs:

Custom color schemes
Responsive breakpoints
Component styling utilities

Development Workflow

Adding a New Project

Navigate to http://localhost:5173
Click "Add Project" button
Fill in project details:
- Project Name
- Project Value (in ETH equivalent)
- Worker Company
- Location
Click "Add to Blockchain"
View transaction hash in success popup
Project appears in main listing

Reporting Corruption

Click "Report Corruption" button
Select report type (bribery, embezzlement, fraud, nepotism, other)
Optionally select related project
Enter detailed description
Choose anonymous or identified reporting
Submit report
View confirmation and transaction hash

Verifying Transactions

Use the provided verification scripts:

cd be

# Check specific transaction
node scripts/check-transaction.cjs 0x<TRANSACTION_HASH>

# Check contract status
node scripts/check-contract.cjs

# Check blockchain status
node scripts/check-blockchain-status.cjs

# Check specific address
node scripts/check-address.cjs

Testing and Verification

Contract Compilation

cd be
npx hardhat compile

Output location: be/artifacts/contracts/TransparencyLedger.sol/

Running Tests

Create test files in be/test/ directory:

npx hardhat test

Local Network Details

Network: Hardhat Local
Chain ID: 31337
RPC URL: http://127.0.0.1:8545
Block Time: Instant (no mining delay)
Accounts: 20 pre-funded accounts with 10,000 ETH each

Default Test Account (Account #0)

Address: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
Private Key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
Balance: 10,000 ETH
Usage: All frontend transactions are signed with this account

Troubleshooting

Common Issues

Issue: "Contract not available" or empty data display

Solution:

Verify Hardhat node is running (npx hardhat node)
Check contract is deployed (look for deployment confirmation)
Confirm contract address in fe/src/utils/web3.js matches deployed address
Refresh browser after updating contract address

Issue: "Connection refused" or "ECONNREFUSED 127.0.0.1:8545"

Solution:

Ensure Hardhat node is running in a separate terminal
Wait 3-5 seconds after starting node before deploying
Check no other process is using port 8545
Verify Windows Firewall isn't blocking localhost connections

Issue: Transactions succeed but data doesn't appear

Solution:

Check browser console for errors (F12)
Verify contract address is correct in frontend
Ensure Hardhat node wasn't restarted (restarts create fresh blockchain)
Click "Refresh" button on the UI to reload data

Issue: "Module not found" errors

Solution:

# Backend
cd be
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

# Frontend
cd fe
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Issue: Hardhat node stops immediately after starting

Solution:

Use the automated script: node scripts/start-and-deploy.cjs
Or use batch files which keep terminals open
Avoid starting node from VS Code integrated terminal (use separate PowerShell window)

Issue: Port already in use

Solution:

# Kill all Node.js processes
Get-Process -Name node | Stop-Process -Force

# Wait a few seconds, then restart
Start-Sleep -Seconds 3
npx hardhat node

Resetting the Application

Full Reset:

# Kill all node processes
Get-Process -Name node | Stop-Process -Force

# Clear browser data
# 1. Open browser DevTools (F12)
# 2. Application tab > Storage > Clear site data

# Restart blockchain
cd be
npx hardhat node

# In new terminal, redeploy
node scripts/deploy-simple.cjs

# Update contract address in fe/src/utils/web3.js
# Restart frontend
cd fe
npm run dev

Security Considerations

Development Environment

This application is designed for local development and testing:

Uses publicly known private keys (Hardhat defaults)
No authentication or authorization beyond cookie-based IDs
All data is publicly readable
Transactions are free (local network only)
Data resets when blockchain node restarts

Production Deployment Warnings

DO NOT use this configuration in production without:

Implementing proper wallet integration (MetaMask, WalletConnect)
Removing hardcoded private keys
Adding access control and permissions
Deploying to a testnet or mainnet
Implementing proper authentication
Adding data validation and sanitization
Setting up monitoring and logging
Conducting security audits
Implementing rate limiting
Adding HTTPS/SSL certificates

Performance Optimization

Frontend

React.lazy for code splitting
Memoization of expensive computations
Debounced search inputs
Pagination for large datasets
Virtual scrolling for long lists (if needed)

Backend

Batch contract calls where possible
Cache frequently accessed data
Use view functions for read-only operations
Optimize contract storage layout
Index events for faster filtering

Deployment to Testnet

Prerequisites

Obtain testnet ETH (Sepolia faucet)
Create .env file with private key:

PRIVATE_KEY=your_actual_private_key_here
SEPOLIA_RPC_URL=https://rpc.sepolia.org

Update hardhat.config.ts:

networks: {
  sepolia: {
    url: process.env.SEPOLIA_RPC_URL,
    accounts: [process.env.PRIVATE_KEY]
  }
}

Deploy:

npx hardhat run scripts/deploy-simple.cjs --network sepolia

Update frontend with new contract address

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/YourFeature)
Commit changes (git commit -m 'Add YourFeature')
Push to branch (git push origin feature/YourFeature)
Open a Pull Request

Project Roadmap

Phase 1 (Current)

Local development environment
Basic project and report management
Cookie-based user identification

Phase 2 (Planned)

MetaMask integration option
Testnet deployment
Enhanced reporting features
File upload to IPFS

Phase 3 (Future)

Role-based access control
Report investigation workflow
Email notifications
Mobile responsive improvements
Analytics dashboard

References

Documentation

Hardhat: https://hardhat.org/docs
Ethers.js: https://docs.ethers.org/v6/
Viem: https://viem.sh/
Solidity: https://docs.soliditylang.org/
React: https://react.dev/
Vite: https://vitejs.dev/

Tools

Hardhat Network: Local Ethereum development network
Vite: Next-generation frontend build tool
Tailwind CSS: Utility-first CSS framework
Lucide Icons: Icon library

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contact

Repository: https://github.com/CAT-Cabang-Programming/ncmaxxing

For issues and questions, please use the GitHub Issues page.

ncmaxxing - Blockchain Transparency Ledger Developed by CAT-Cabang-Programming

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
be		be
fe		fe
.gitignore		.gitignore
DEPLOY_CONTRACT.bat		DEPLOY_CONTRACT.bat
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SETUP_GUIDE.md		SETUP_GUIDE.md
START_BLOCKCHAIN.bat		START_BLOCKCHAIN.bat
START_FRONTEND.bat		START_FRONTEND.bat
TransparencyLedger.sol		TransparencyLedger.sol
hardhat.config.ts		hardhat.config.ts
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ncmaxxing - Blockchain Transparency Ledger

Features

Core Functionality

Technical Highlights

Project Structure

Prerequisites

Installation

1. Clone Repository

2. Install Backend Dependencies

3. Install Frontend Dependencies

Running the Application

Method 1: Automated Start (Recommended)

Method 2: Using Batch Files (Windows)

Method 3: Manual Start (Step by Step)

Smart Contract Details

Smart Contract Details

Contract: TransparencyLedger.sol

Data Structures

Public Functions

Events

Frontend Architecture

Cookie-Based User System

Transaction Signing

Web3 Service Layer

UI Components

Pages

Configuration Files

Backend Configuration

Frontend Configuration

Development Workflow

Adding a New Project

Reporting Corruption

Verifying Transactions

Testing and Verification

Contract Compilation

Running Tests

Local Network Details

Default Test Account (Account #0)

Troubleshooting

Common Issues

Resetting the Application

Security Considerations

Development Environment

Production Deployment Warnings

Performance Optimization

Frontend

Backend

Deployment to Testnet

Prerequisites

Contributing

Project Roadmap

Phase 1 (Current)

Phase 2 (Planned)

Phase 3 (Future)

References

Documentation

Tools

License

Contact

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages