SolanaHub

A trustless, decentralized freelance marketplace built on Solana blockchain

Empowering freelancers and clients with instant payments, transparent escrow, and community-driven dispute resolution

• Features
• Architecture
• Getting Started
• Tech Stack
• Documentation

---

🔗 Live Demo

Note: This is a UI demo only. The demo may be temporarily unavailable at times.

---

Features

Core Functionality

• Trustless Escrow System - Smart contract-based escrow with milestone-based payments
• Instant Settlements - Lightning-fast USDC payments on Solana blockchain
• Milestone Management - Create, track, and approve project milestones with on-chain verification
• Reputation System - Transparent rating and review system stored on-chain
• Dispute Resolution - Community-governed dispute resolution through decentralized voting
• Messaging System - Secure communication between clients and freelancers
• Social Feed - Share updates, achievements, and engage with the community
• Project Categories - Organized marketplace with multiple service categories

Advanced Features

• Smart Discovery - MongoDB-powered search and filtering for efficient project discovery
• Real-time Indexing - Blockchain event watcher for instant data synchronization
• Modern UI/UX - Responsive Next.js frontend with Tailwind CSS
• Notifications - Real-time updates on project status, payments, and messages
• Token Staking - Stake tokens for governance participation and platform benefits

---

Architecture

SolanaHub follows a three-tier architecture combining on-chain security with off-chain performance:

graph LR
    %% Define Styles
    classDef frontend fill:#e0f2fe,stroke:#0284c7,stroke-width:3px,color:#000;
    classDef backend fill:#dcfce7,stroke:#16a34a,stroke-width:3px,color:#000;
    classDef blockchain fill:#f3e8ff,stroke:#9333ea,stroke-width:3px,color:#000;
    classDef database fill:#fef3c7,stroke:#f59e0b,stroke-width:3px,color:#000;

    %% Frontend Layer
    subgraph Frontend["🖥️ FRONTEND LAYER"]
        UI["Next.js 16 App<br/>React + Tailwind CSS v4"]
        Wallet["Wallet Adapter<br/>Phantom/Solflare"]
        Query["React Query<br/>State Management"]
    end

    %% Backend Layer
    subgraph Backend["⚙️ BACKEND LAYER"]
        API["Express API<br/>Node.js + TypeScript"]
        Watcher["Event Watcher<br/>Blockchain Indexer"]
        Auth["JWT Auth<br/>Wallet Verification"]
    end

    %% Database Layer
    subgraph Database["📊 DATABASE LAYER"]
        MongoDB[("MongoDB Atlas<br/>Projects, Users, Messages")]
    end

    %% Blockchain Layer
    subgraph Blockchain["⛓️ BLOCKCHAIN LAYER"]
        Program["Solana Program<br/>Rust + Anchor v0.32"]
        PDAs["PDAs<br/>Project, Escrow, Milestone"]
        USDC["USDC Token<br/>Payments"]
    end

    %% Connections - Frontend to Backend
    UI -->|"REST API Calls"| API
    Wallet -->|"Sign Transactions"| Program
    Query -->|"Fetch Data"| API

    %% Connections - Backend to Database
    API -->|"CRUD Operations"| MongoDB
    Watcher -->|"Index Events"| MongoDB
    Auth -->|"Store Sessions"| MongoDB

    %% Connections - Backend to Blockchain
    API -->|"Read State"| Program
    Watcher -->|"Listen Events"| Program

    %% Connections - Blockchain Internal
    Program -->|"Manage PDAs"| PDAs
    Program -->|"Transfer Funds"| USDC

    %% Connections - Data Flow Back
    MongoDB -.->|"Query Results"| API
    API -.->|"JSON Response"| UI
    Program -.->|"Emit Events"| Watcher

    %% Apply Styles
    class UI,Wallet,Query frontend;
    class API,Watcher,Auth backend;
    class MongoDB database;
    class Program,PDAs,USDC blockchain;

Loading

Data Flow

1. Project Creation → Client signs transaction → Protocol initializes PDA → Event emitted
2. Indexing → Watcher service detects event → Updates MongoDB → API serves to frontend
3. Milestone Release → Protocol verifies conditions → Transfers USDC from escrow PDA → Updates state
4. Dispute Resolution → Community votes → Smart contract tallies → Automated fund distribution

---

Getting Started

Prerequisites

Ensure you have the following installed:

• Node.js 18+ (Download)
• Rust & Cargo Latest stable (Install)
• Solana CLI (Install Guide)
• Anchor Framework 0.30+ (Install)
• MongoDB Local or cloud instance (MongoDB Atlas)

Installation

1. Clone the repository

git clone https://github.com/raushan728/solanahub.git
cd solanahub

2. Setup Solana Program (Smart Contracts)

cd solanahub_protocol
anchor build
anchor deploy --provider.cluster devnet
anchor test

3. Setup Backend Server

# Return to root directory
cd ..

# Install dependencies
npm install

# Configure environment variables (see Environment Configuration section below)
cp .env.example .env
# Edit .env and add your configurations

# Start development server
npm run dev

4. Setup Frontend Application

cd client
npm install

# Configure frontend environment
cp .env.local.example .env.local
# Edit .env.local with your configurations

npm run dev

5. Access the application

Open your browser and navigate to:

http://localhost:3000

---

Environment Configuration

Backend Environment Variables (Root .env)

Create a .env file in the root directory with the following variables:

# Solana Network Configuration
# CRITICAL: Use HTTP endpoint for RPC calls, NOT WebSocket
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_WS_URL=wss://api.devnet.solana.com

# MongoDB Database
# Get your connection string from MongoDB Atlas (https://www.mongodb.com/cloud/atlas)
MONGODB_URI=mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/?appName=Cluster0

# Server Configuration
PORT=3001                    # Backend API server port
NODE_ENV=development         # Environment: development | production | test

# Solana Program
# Your deployed program ID from 'anchor deploy'
SOLANA_PROGRAM_ID=H4R1nUBp4Gfuw9uPZwfrKyTVgP3TrQ2RzMD1puWjqYsY

# Frontend URL (for CORS)
FRONTEND_URL=http://localhost:3000

Frontend Environment Variables (Client .env.local)

Create a .env.local file in the client/ directory:

# Solana Network
# Public RPC endpoint for client-side blockchain calls
NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com

# Solana Program ID
# Must match the deployed program ID
NEXT_PUBLIC_PROGRAM_ID=H4R1nUBp4Gfuw9uPZwfrKyTVgP3TrQ2RzMD1puWjqYsY

# Backend API URL
# URL where your backend server is running
NEXT_PUBLIC_API_URL=http://localhost:3001

# Network Type
# Options: devnet | testnet | mainnet-beta
NEXT_PUBLIC_NETWORK=devnet

Important Notes

• MongoDB URI: Replace with your actual MongoDB connection string from MongoDB Atlas
• Program ID: Update after deploying your Solana program with anchor deploy
• RPC Endpoints: For production, consider using dedicated RPC providers like:
  • Helius
  • QuickNode
  • Alchemy
• Environment Prefixes: Next.js requires NEXT_PUBLIC_ prefix for client-side environment variables

---

Tech Stack

Blockchain Layer

• Solana - High-performance blockchain (Devnet deployment)
• Anchor Framework - Solana program development framework (v0.30+)
• Rust - Systems programming language for smart contracts

Backend Layer

• Node.js - JavaScript runtime (v18+)
• Express.js - Web application framework
• TypeScript - Type-safe JavaScript (v5.0+)
• MongoDB - NoSQL database for indexing and caching
• Mongoose - MongoDB object modeling
• @solana/web3.js - Solana JavaScript API

Frontend Layer

• Next.js 16 - React framework with App Router
• React - UI component library
• Tailwind CSS v4 - Utility-first CSS framework
• Framer Motion - Animation library
• React Query - Data fetching and state management

Development Tools

• Anchor - Testing and deployment
• tsx - TypeScript execution
• dotenv - Environment variable management

---

Project Structure

solanahub/
├── solanahub_protocol/    # Solana Smart Contracts (Rust/Anchor)
├── src/                   # Backend API (Node.js/Express)
├── client/                # Frontend (Next.js)
└── package.json           # Dependencies

---

Documentation

Smart Contract Instructions

The Solana program (solanahub_protocol) provides the following instructions:

• initialize - Initialize global state
• create_project - Create a new freelance project
• assign_freelancer - Assign freelancer to project
• initialize_escrow - Lock funds in escrow
• create_milestone - Define project milestones
• submit_deliverable - Submit milestone deliverable
• approve_milestone - Approve completed milestone
• reject_milestone - Reject milestone submission
• release_milestone - Release milestone payment
• process_auto_release - Auto-release after timeout
• raise_dispute - Initiate dispute resolution
• cast_vote - Vote on dispute outcome
• submit_review - Submit project review
• create_post - Create social feed post
• like_post - Like a post
• send_message - Send encrypted message
• stake - Stake platform tokens

API Endpoints

Backend API provides RESTful endpoints for:

• Project management and search
• User profiles and authentication
• Notifications and messaging
• Social feed and interactions
• Blockchain event indexing

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Maintainer

Raushan Kumar

• Telegram: @raushan_singh_29
• Twitter: @Raushan_090
• LinkedIn: raushan-kumar-807916390
• Email: raushansinghrajpoot687@gmail.com

---

Built on Solana