VoucherHub - Decentralized Voucher Marketplace

A complete Web3 solution for creating, issuing, redeeming, and managing digital vouchers on the blockchain

🌟 Overview

VoucherHub is a great decentralized platform that enables merchants to create, distribute, and manage digital vouchers and users to get and redeem them using blockchain technology. Built with modern Web3 technologies, it provides a secure, transparent, and efficient way to handle voucher transactions without intermediaries.

✨ Key Features

• 🏪 Merchant Registration: Secure merchant onboarding with admin approval
• 🎟️ Voucher Creation: Create digital vouchers with custom metadata and pricing
• 🔐 Secure Issuing: EIP712 signature-based voucher issuing system
• 💰 Marketplace: Browse vouchers and approach respective merchants for purchase
• 🔄 Redemption System: Easy voucher redemption with burn mechanism
• 👨‍💼 Admin Dashboard: Complete admin control over merchant approvals and voucher management
• 📱 Responsive UI: Modern interface built with React and Tailwind CSS

🏗️ Architecture

VoucherHub follows a modern three-tier architecture:

┌───────────────────┐    ┌─────────────────┐    ┌───────────────────┐
│   Frontend        │    │    Backend      │    │ Smart Contracts   │
│   (React)         │◄──►│   (Node.js)     │◄──►│   (Solidity)      │
│                   │    │                 │    │                   │
│ • User Interface  │    │ • API Server    │    │ • VoucherERC1155  │
│ • Web3 Integration│    │ • Database      │    │ • MerchantRegistry│
│ • Wallet Connect  │    │ • Authentication│    │ • OpenZeppelin    │
└───────────────────┘    └─────────────────┘    └───────────────────┘

🛠️ Tech Stack

Frontend

• React 18.3.1 - Modern UI framework
• Vite - Fast build tool and dev server
• Tailwind CSS - Utility-first CSS framework
• Ethers.js 5.8.0 - Ethereum interaction library
• React Router - Client-side routing
• Axios - HTTP client for API calls

Backend

• Node.js 20.19 - JavaScript runtime
• Express.js - Web application framework
• MongoDB - NoSQL database
• Mongoose - MongoDB object modeling
• JWT - JSON Web Token authentication
• Helmet - Security middleware

Smart Contracts

• Solidity 0.8.20 - Smart contract language
• Foundry - Development framework
• OpenZeppelin - Security-audited contract libraries
• ERC1155 - Multi-token standard
• EIP712 - Typed structured data signing

Development Tools

• ESLint - Code linting
• Nodemon - Development server
• Pinata (IPFS) - Decentralized storage & pinning service
• Foundry - Smart contract development framework

📁 Project Structure

VoucherHub/
│
├── 📂 frontend/                    # React frontend application
│   ├── 📂 src/
│   │   │
│   │   ├── 📂 Components/          # Reusable UI components
│   │   │   ├── 📂 admin/           # Admin-specific components
│   │   │   ├── 📂 common/          # Shared components
│   │   │   ├── 📂 connect/         # Wallet connection
│   │   │   ├── 📂 merchant/        # Merchant dashboard
│   │   │   └── 📂 user/            # User interface
│   │   │
│   │   ├── 📂 Context/             # React context providers
│   │   │   ├── RoleContext.jsx     # User role management
│   │   │   └── WalletContext.jsx   # Web3 wallet integration
│   │   │
│   │   ├── 📂 Pages/               # Application pages
│   │   │   ├── AdminPage.jsx       # Admin dashboard
│   │   │   ├── ConnectPage.jsx     # Wallet connection page
│   │   │   ├── Marketplace.jsx     # Voucher marketplace
│   │   │   ├── MerchantPage.jsx    # Merchant dashboard
│   │   │   └── UserPage.jsx        # User dashboard
│   │   │
│   │   ├── 📂 utils/               # Utility functions & services
│   │   │   ├── eip712.js           # EIP712 signature utilities
│   │   │   ├── fetchVouchers.js    # Voucher data fetching
│   │   │   ├── ipfs.js             # IPFS integration
│   │   │   ├── roleDetection.js    # User role detection
│   │   │   └── utilsMerchantRequests.js # Merchant request utilities
│   │   │
│   │   ├── App.jsx                 # Main application component
│   │   ├── main.jsx                # Application entry point
│   │   └── index.css               # Global styles
│   │
│   ├── package.json
│   └── vite.config.js
│
├── 📂 backend/                     # Express.js backend server
│   ├── 📂 src/
│   │   │
│   │   ├── 📂 config/              # Configuration files
│   │   │   └── db.js               # Database connection setup
│   │   │
│   │   ├── 📂 controllers/         # Request handlers
│   │   │   ├── merchantRequestController.js # Merchant request logic
│   │   │   └── voucherController.js # Voucher CRUD operations
│   │   │
│   │   ├── 📂 middleware/          # Authentication & validation
│   │   │   ├── authMiddleware.js   # JWT authentication
│   │   │   └── validateVoucher.js  # Voucher validation
│   │   │
│   │   ├── 📂 models/              # Database models
│   │   │   ├── MerchantRequest.js  # Merchant request schema
│   │   │   └── Voucher.js          # Voucher schema
│   │   │
│   │   └── 📂 routes/              # API routes
│   │       ├── merchantRequestRoutes.js # Merchant request endpoints
│   │       └── voucherRoutes.js    # Voucher endpoints
│   │
│   ├── package.json
│   └── server.js                   # Express server entry point
│
├── 📂 contracts/                   # Smart contracts
│   ├── 📂 src/                     # Solidity contracts
│   │   ├── VoucherERC1155.sol      # Main voucher contract (ERC1155)
│   │   └── MerchantRegistry.sol    # Merchant registration & management
│   │
│   ├── 📂 script/                  # Deployment scripts
│   ├── 📂 test/                    # Contract tests
│   └── foundry.toml                # Foundry configuration
│
├── 📂 spec/                        # Project specifications
└── README.md                       # Project documentation

🚀 Quick Start

Prerequisites

• Node.js (v20.19 or higher)
• npm or yarn
• Git
• MetaMask or compatible Web3 wallet
• MongoDB (local or cloud instance)
• Pinata Account (for IPFS storage)

Installation

1. Clone the repository

   git clone https://github.com/veyrix-Tr/VoucherHub.git
   cd VoucherHub

2. Install dependencies for all components

   # Install frontend dependencies
   cd frontend
   npm install
   
   # Install backend dependencies
   cd ../backend
   npm install
   
   # Install contract dependencies
   cd ../contracts
   forge install
   forge build

3. Environment Setup

   Frontend (.env)

   VITE_BACKEND_URL=http://localhost:5000
   VITE_CHAIN_ID=11155111
   VITE_PINATA_JWT=your_pinata_jwt_token
   VITE_PINATA_GATEWAY=https://gateway.pinata.cloud

   Backend (.env)

   PORT=5000
   MONGODB_URI=mongodb://localhost:27017/voucherhub
   JWT_SECRET=your_jwt_secret_key # Note: JWT authentication currently disabled for development
   RPC_URL=your_rpc_url
   CHAIN_ID=11155111

4. Start the servers

   Terminal 1 - Backend

   cd backend
   npm run dev

   Terminal 2 - Frontend

   cd frontend
   npm run dev

📋 Smart Contract Details

VoucherERC1155

The main contract that handles voucher creation, minting, and redemption.

Key Functions:

• mintFromVoucher() - Mint vouchers using EIP712 signatures
• burnForRedeem() - Redeem and burn vouchers
• setVoucherApproval() - Admin approval for voucher creation
• issueVoucherToUser() - Direct voucher issuance by merchants

MerchantRegistry

Manages merchant registration and verification.

Key Functions:

• registerMerchant() - Register new merchants (admin only)
• updateMerchantStatus() - Activate/deactivate merchants
• isMerchant() - Check if address is an active merchant

🔄 Voucher Lifecycle

1. Merchant Registration - Merchants submit registration requests through the platform
2. Admin Approval - Admins review and approve/reject merchant applications
3. Voucher Creation - Approved merchants create vouchers with EIP712 signatures
4. Voucher Approval - Admins approve vouchers before users can mint them
5. Voucher Distribution - Users mint approved vouchers; merchants may also issue them directly to users.
6. Voucher Usage - Users approach merchants to use their vouchers
7. Voucher Redemption - Users redeem vouchers, which burns the tokens permanently

🎯 User Roles

👤 Regular Users

• Browse marketplace
• Purchase vouchers
• Redeem vouchers
• View transaction history

🏪 Merchants

• Create voucher listings
• Manage voucher inventory
• Track sales and redemptions
• Update voucher metadata

👨‍💼 Admins

• Approve/reject merchant applications
• Approve/reject voucher listings
• Monitor platform activity
• Manage system settings

🔧 API Endpoints

Voucher Routes

GET    /api/vouchers              # Get all vouchers
POST   /api/vouchers              # Create new voucher
GET    /api/vouchers/:id          # Get voucher by ID
PUT    /api/vouchers/:id/approve  # Approve voucher (admin only)
PUT    /api/vouchers/:id/reject   # Reject voucher (admin only)
PUT    /api/vouchers/:id/redeem   # Redeem voucher
PUT    /api/vouchers/:id/minted   # Update minted count

Merchant Request Routes

POST   /api/merchant-requests     # Submit merchant application
GET    /api/merchant-requests/me  # Get my merchant request
GET    /api/merchant-requests     # Get all requests (admin only)
PUT    /api/merchant-requests/:id/approve # Approve merchant (admin only)
PUT    /api/merchant-requests/:id/reject  # Reject merchant (admin only)

🧪 Testing

Smart Contract Tests

cd contracts
forge test -vv

🚀 Deployment

Backend (Production)

cd backend
npm start

Frontend (Production)

cd frontend
npm run build
npm run preview

📄 License

This project is licensed under the MIT License.

🆘 Support

If you encounter any issues or have questions:

• 📧 Email: chiraggoyal3637@gmail.com
• 🐛 Issues: GitHub Issues
• 🐦 Twitter: @veyrix_Tr

🙏 Acknowledgments

• OpenZeppelin for secure smart contract libraries
• The Ethereum community for Web3 standards
• React and Node.js communities for excellent frameworks

---

Made with ❤️ by the veyrix-Tr [Chirag Goyal]