DOCUMENTATION

1. Platform Overview

1.1 What is Revolution Pad?

Revolution Pad is a decentralized launchpad platform built on Binance Smart Chain (BSC) that enables users to:

Create professional ERC20 tokens in 60 seconds
Launch fair presale events
Manage token vesting and locks
Run referral competitions
Automatically lock liquidity

1.2 Key Features

Feature

Description

Token Factory

Create tokens with mint, burn, custom tax (up to 25%), multiple recipients

Fair Launch

Dynamic pricing based on market demand

Standard Presale

Fixed rate token sales

Automated Liquidity

Liquidity locked for configurable duration

Referral System

Multi-level rewards with custom influencer rates

Leaderboard

Competition-based prize distribution

Token Locker

Secure vesting with automatic release

Multi-Network

BSC Mainnet (56) and Testnet (97)

1.3 Technology Stack

Frontend:
  - Next.js 15 (App Router)
  - React 19
  - TypeScript
  - Tailwind CSS
  - Lucide Icons

Web3:
  - Wagmi (React hooks for Ethereum)
  - Viem (TypeScript interface for Ethereum)
  - RainbowKit (Wallet connection UI)

Backend:
  - Next.js API Routes
  - Prisma ORM
  - PostgreSQL (Neon)

Blockchain:
  - Solidity 0.8.20
  - Hardhat
  - EIP-1167 (Minimal Proxy Clones)
  - BSC Mainnet & Testnet

2. System Architecture

2.1 Overall Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         USER BROWSER                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   Wallet    │  │   Frontend  │  │    UI       │             │
│  │ (MetaMask)  │  │   (Next.js) │  │  (React)    │             │
│  └──────┬──────┘  └──────┬──────┘  └─────────────┘             │
└─────────┼────────────────┼──────────────────────────────────────┘
          │                │
          │                │
┌─────────┼────────────────┼──────────────────────────────────────┐
│         │                │                                      │
│  ┌──────▼──────┐  ┌──────▼──────┐                              │
│  │  RPC Node   │  │  API Routes │  ┌──────────────────────┐    │
│  │  (BSC)      │  │ (Next.js)   │  │   PostgreSQL DB      │    │
│  └──────┬──────┘  └──────┬──────┘  │  (Neon)              │    │
│         │                │         │                      │    │
│         │                │         │ - Users              │    │
│  ┌──────▼──────┐  ┌──────▼──────┐ │ - Projects           │    │
│  │  Smart      │  │  Database   │ │ - Tokens             │    │
│  │  Contracts  │  │  (Prisma)   │ │ - Comments           │    │
│  │             │  │             │ │ - Leaderboard        │    │
│  │ TokenFactory│  │             │ └──────────────────────┘    │
│  │ Presale     │◄─┤             │                              │
│  │ Locker      │  │             │                              │
│  └─────────────┘  └─────────────┘                              │
└─────────────────────────────────────────────────────────────────┘

2.2 Data Flow

Token Creation Flow

User Input (UI)
    ↓
Form Validation
    ↓
Write Contract (Wagmi)
    ↓
Blockchain Transaction
    ↓
Token Factory Contract
    ↓
Token Deployed
    ↓
Event: TokenCreated
    ↓
API: POST /api/token
    ↓
Database: Token Record Created
    ↓
UI Update: Token in "My Tokens"

Presale Purchase Flow

User: Enter BNB Amount + Click Buy
    ↓
Contract: deposit() with referrer
    ↓
Blockchain: Transaction Confirmed
    ↓
Events: Deposited, ReferrerPaid
    ↓
API: POST /api/deposit
    ↓
Database: Deposit + Leaderboard Records
    ↓
UI: Update Progress + Referral Stats

3. Frontend Application

3.1 Project Structure

src/
├── app/
│   ├── page.tsx                    # Homepage
│   ├── admin/
│   │   └── page.tsx                # Admin dashboard
│   ├── create-token/
│   │   └── page.tsx                # Token creation UI
│   ├── launchpad/
│   │   ├── page.tsx                # Launchpad list
│   │   ├── create/
│   │   │   └── page.tsx            # Presale creation
│   │   └── [id]/
│   │       ├── page.tsx            # Presale detail (server)
│   │       └── client-page.tsx     # Presale detail (client)
│   └── api/
│       ├── auth/
│       │   └── route.ts            # Nickname auth
│       ├── token/
│       │   └── route.ts            # Token CRUD
│       ├── project/
│       │   └── route.ts            # Project CRUD
│       ├── deposit/
│       │   └── route.ts            # Deposit tracking
│       ├── withdraw/
│       │   └── route.ts            # Withdraw tracking
│       ├── leaderboard/
│       │   └── route.ts            # Leaderboard data
│       └── comment/
│           └── route.ts            # Comments
├── components/
│   ├── providers.tsx               # Web3 providers
│   └── ui/                         # Reusable components
├── lib/
│   ├── contracts.ts                # Contract ABIs & addresses
│   ├── deployed-contracts.json     # Network addresses
│   ├── prisma.ts                   # DB client
│   └── utils.ts                    # Utilities
└── hooks/
    └── useImageAspectRatio.ts      # Image validation

3.2 Key Pages

Homepage (/)

Landing page with:

Platform introduction
Live presales list
Statistics (total raised, active presales)
Navigation to create token/sale

Create Token (/create-token)

Token creation wizard. Use the stepper below for the flow.

Basic Info

Token name
Symbol
Total supply
Decimals

Tax Configuration

Buy tax (0-25%)
Sell tax (0-25%)
Tax recipients (multiple)

Features

Mintable (yes/no)
Burnable (yes/no)
Ownable (yes/no)
Trade enabled (yes/no)

Review & Deploy

Show all parameters
Gas estimate
Deploy button

Launchpad List (/launchpad)

Displays all presales with filters:

All
Live
Upcoming
Ended

Each card shows:

Project logo
Token name/symbol
Status badge
Start/end time
Progress bar
Raised/Hardcap

Launchpad Detail (/launchpad/[id])

Comprehensive presale page with tabs:

Details Tab:

Project description
Video/image media
Token info
Social links

Tokenomics Tab:

Token allocation breakdown
Lock durations

Leaderboard Tab:

Top referrers
Prize pool
User ranking
Claim prizes

Buy Section:

BNB input
Buy button (when active)
Claim buttons (when finalized)
Withdraw button (when available)

3.3 State Management

Local State (useState)

Form inputs
Modal visibility
Active tab
Error messages

Server State (Wagmi Hooks)

// Read contract data
const { data: info } = useReadContract({
  address: presaleAddress,
  abi: CONTRACTS.Presale.abi,
  functionName: 'info',
  query: { refetchInterval: 3000 }
});

// Write contract transactions
const { writeContract, isPending } = useWriteContract();
const { isSuccess } = useWaitForTransactionReceipt({ hash });

Global State (Context)

Theme (dark/light)
User authentication
Network switching

3.4 Responsive Design

Breakpoints:

Mobile: < 768px
Tablet: 768px - 1024px
Desktop: > 1024px

Mobile Optimizations:

Stacked layouts
Touch-friendly buttons
Simplified navigation
Optimized gas estimates

4. Backend API

4.1 API Routes

Authentication (/api/auth)

POST /api/auth

Set or update user nickname.

Request: { address: string, nickname: string }
Response: { user: User }

Token Management (/api/token)

GET /api/token

Fetch tokens by owner or all tokens.

Query: ?owner={address}
Response: Token[]

POST /api/token

Create token record after deployment.

Request: {
  address: string
  name: string
  symbol: string
  ownerAddress: string
  isMintable: boolean
  isBurnable: boolean
  isOwnable: boolean
  buyTax: number
  sellTax: number
  tradeEnabled: boolean
}
Response: Token

Project Management (/api/project)

GET /api/project

Fetch project by presale address or all projects.

Query: ?id={presaleAddress} | ?chainId={56|97}
Response: Project | Project[]

POST /api/project

Create project record.

Request: {
  id: string (presale address)
  chainId: number
  description: string
  logoUrl: string
  mediaType: 'video' | 'image'
  mediaUrl: string
  twitter: string
  telegram: string
  website: string
  tokenomics: string (JSON)
  listingType: string
  unsoldAction: 'Burn' | 'Return'
}
Response: Project

PATCH /api/project

Update project info (requires signature).

Request: {
  id: string
  description: string
  logoUrl: string
  mediaType: string
  mediaUrl: string
  twitter: string
  telegram: string
  website: string
  signature: string
  message: string
}
Response: Project

Deposit Tracking (/api/deposit)

POST /api/deposit

Record deposit for leaderboard.

Request: {
  projectId: string
  user: string
  amount: string (wei)
  referrer: string
  txHash: string
}
Response: { success: true }

Withdraw Tracking (/api/withdraw)

POST /api/withdraw

Remove deposit records after withdrawal.

Request: {
  projectId: string
  user: string
}
Response: { success: true }

Leaderboard (/api/leaderboard)

GET /api/leaderboard

Fetch leaderboard data for a project.

Query: ?projectId={presaleAddress}
Response: Array<{
  address: string
  volume: string
  count: number
}>

4.2 Error Handling

try {
  // Database operation
} catch (error) {
  console.error('API Error:', error);
  return NextResponse.json(
    { error: 'Operation failed' },
    { status: 500 }
  );
}

4.3 Validation

URL Validation:

YouTube URLs (strict regex)
Image URLs (must start with http/https)
Social media URLs (http/https required)

Address Validation:

EVM address format (/^0x[a-fA-F0-9]{40}$/)
Contract existence check

Signature Verification:

Recover address from signature
Compare with contract owner
Authorize update

5. Database Layer

5.1 Database Schema

User Table

model User {
  id        String   @id
  nickname  String?
  createdAt DateTime @default(now())
}

Token Table

model Token {
  address       String   @id
  name          String
  symbol        String
  ownerAddress  String
  isMintable    Boolean  @default(false)
  isBurnable    Boolean  @default(false)
  isOwnable     Boolean  @default(false)
  buyTax        Int      @default(0)
  sellTax       Int      @default(0)
  tradeEnabled  Boolean  @default(false)
  createdAt     DateTime @default(now())
}

Project Table

model Project {
  id            String   @id (presale address)
  chainId       Int
  description   String   @db.Text
  logoUrl       String   @db.Text
  mediaType     String   @default("video")
  mediaUrl      String?
  youtubeUrl    String?  // Legacy field
  twitter       String?
  telegram      String?
  website       String?
  tokenomics    String?  @db.Text (JSON)
  listingType   String?
  unsoldAction  String?
  createdAt     DateTime @default(now())
}

Comment Table

model Comment {
  id        String   @id @default(autoincrement())
  content   String   @db.Text
  createdAt DateTime @default(now())
  userId    String
  projectId String
  user      User     @relation(fields: [userId], references: [id])
  project   Project  @relation(fields: [projectId], references: [id])
}

Deposit Table

model Deposit {
  id        String   @id @default(autoincrement())
  projectId String
  user      String
  amount    String   // Wei as string
  referrer  String
  txHash    String   @unique
  createdAt DateTime @default(now())

  @@unique([projectId, user, txHash])
}

Leaderboard Table

model Leaderboard {
  id        String   @id @default(autoincrement())
  projectId String
  address   String
  volume    String   // Wei as string
  count     Int
  createdAt DateTime @default(now())

  @@unique([projectId, address])
}

5.2 Database Operations

Prisma Client

import { PrismaClient } from '@/lib/prisma';

const prisma = new PrismaClient();

// Create
await prisma.token.create({ data: tokenData });

// Read
await prisma.project.findUnique({ where: { id } });
await prisma.token.findMany({ where: { ownerAddress } });

// Update
await prisma.project.update({
  where: { id },
  data: { description }
});

// Delete
await prisma.deposit.deleteMany({
  where: { projectId, user }
});

5.3 Relationships

User ──1:N── Comments
              │
              └── Project

Project ──1:N── Comments
         └──1:N── Deposits
                  │
                  └── Leaderboard (Aggregated)

Token ── (No direct relations, referenced by address)

6. Smart Contracts

6.1 Contract Overview

Contract

Purpose

Key Features

RevolutionToken

Token template

Mintable, burnable, custom tax, multi-recipient

TokenFactory

Token creation

Deploy tokens, set taxes, manage collateral

Presale

Presale template

Sales, referrals, leaderboard, finalization

LaunchpadFactory

Presale creation

Clone presales, manage allocations

TokenLocker

Token vesting

Lock tokens, release schedules

6.2 RevolutionToken

Features

Mintable:

function mint(address to, uint256 amount) external onlyOwner

Only owner can mint
Enables flexible supply management

Burnable:

function burn(uint256 amount) external

Anyone can burn their tokens
Permanently reduces supply

Tax System:

struct TaxRecipient {
    address wallet;
    uint256 buyPercent;
    uint256 sellPercent;
}

TaxRecipient[] public taxRecipients;
uint8 public buyTax;
uint8 public sellTax;

Tax Calculation:

// On transfer
uint256 taxAmount = (amount * taxRate) / 100;
uint256 netAmount = amount - taxAmount;

// Distribute to recipients
for (uint i = 0; i < taxRecipients.length; i++) {
    uint256 share = (taxAmount * taxRecipients[i].percent) / 100;
    _transfer(from, taxRecipients[i].wallet, share);
}

Trade Toggle:

function setTradeEnabled(bool _enabled) external onlyOwner

Owner can enable/disable trading
Prevents early trading

6.3 TokenFactory

State Variables

uint256 public collateralAmount;          // Required collateral
uint256 public platformTaxDuration;       // Tax collection period
address public routerAddress;             // PancakeSwap router
mapping(address => bool) public hasPaid;  // Collateral tracking

Token Deployment

function createToken(
    string memory name,
    string memory symbol,
    uint256 totalSupply,
    uint8 decimals,
    uint8 buyTax,
    uint8 sellTax,
    bool isMintable,
    bool isBurnable,
    bool isOwnable,
    bool tradeEnabled,
    TaxRecipient[] memory taxRecipients
) external payable returns (address)

Process:

Validate tax rates (≤ 25%)
Validate recipient percentages (sum to 100)
Deploy RevolutionToken
Mint totalSupply to creator
Set tax recipients
Record payment

Collateral System:

// User pays collateral
require(msg.value >= collateralAmount, "Insufficient collateral");

// After duration, refund
if (block.timestamp >= deploymentTime + platformTaxDuration) {
    payable(owner).transfer(collateralAmount);
}

6.4 Presale

State Variables

// Token info
address public token;
uint256 public rate;
uint256 public hardcap;
uint256 public softcap;
uint256 public minBuy;
uint256 public maxBuy;
uint256 public liquidityPercent;
uint256 public lockDuration;
uint256 public startTime;
uint256 public endTime;

// Status
bool public finalized;
bool public canceled;
bool public isPrivate;
bool public isFairLaunch;

// Allocations
uint256 public totalTokensForSale;

// Owner
address public owner;
address public lockerAddress;

Purchase Function

function deposit(address referrer) external payable nonReentrant

Validation:

Presale active (not finalized/canceled)
Within time range
Above minBuy
Below maxBuy
Whitelisted (if private)

Process:

// 1. Check presale status
require(!finalized && !canceled, "Presale ended");
require(block.timestamp >= startTime && block.timestamp <= endTime);

// 2. Validate amount
require(msg.value >= minBuy && msg.value <= maxBuy);

// 3. Check whitelist
if (isPrivate) {
    require(whitelist[msg.sender], "Not whitelisted");
}

// 4. Update totals
totalRaised += msg.value;
investments[msg.sender] += msg.value;

// 5. Process referral
if (referrer != address(0) && referrer != msg.sender) {
    _processReferral(msg.sender, msg.value, referrer);
}

// 6. Update leaderboard
if (leaderboardEnabled) {
    _updateLeaderboard(msg.value, referrer);
}

emit Deposited(msg.sender, msg.value, referrer);

Finalization

function finalize() external onlyOwner

Conditions:

Hardcap reached OR time ended
Softcap reached (if time ended)

Process:

require(!finalized, "Already finalized");
require(
    totalRaised >= hardcap || block.timestamp > endTime,
    "Presale active"
);
if (block.timestamp > endTime) {
    require(totalRaised >= softcap, "Softcap not reached");
}

finalized = true;

// 1. Calculate liquidity
uint256 liquidityBNB = (totalRaised * liquidityPercent) / 100;
uint256 liquidityTokens = liquidityBNB * listingRate;

// 2. Add liquidity
_approveToken(router, liquidityTokens);
IRouter(router).addLiquidityETH{value: liquidityBNB}(...);

// 3. Lock liquidity
IERC20(lpToken).transfer(lockerAddress, liquidityTokens);
TokenLocker(lockerAddress).lockPresaleLiquidity(...);

// 4. Enable trading
RevolutionToken(token).setTradeEnabled(true);

emit Finalized(totalRaised);

6.5 LaunchpadFactory

Clone Pattern (EIP-1167)

import "@openzeppelin/contracts/proxy/Clones.sol";

address public implementation;

function createPresale(...) external payable returns (address) {
    // Clone implementation
    address presale = Clones.clone(implementation);

    // Initialize
    Presale(presale).initialize(...);

    return presale;
}

Gas Savings:

Full deployment: ~2,500,000 gas
Clone deployment: ~250,000 gas
Savings: ~90%

Allocation Locks

struct AllocationLock {
    uint256 amount;
    uint256 lockMonths;
    string description;
}

Process:

// 1. Calculate tokens
uint256 totalAllocation = 0;
for (uint i = 0; i < _allocations.length; i++) {
    totalAllocation += _allocations[i].amount;
}

// 2. Transfer to factory
token.transferFrom(msg.sender, address(this), totalAllocation);

// 3. Approve locker
token.approve(lockerAddress, totalAllocation);

// 4. Lock each
for (uint i = 0; i < _allocations.length; i++) {
    TokenLocker(lockerAddress).lockPending(
        token,
        msg.sender,
        _allocations[i].amount,
        unlockDate,
        _allocations[i].description,
        presale
    );
}

6.6 TokenLocker

Lock Types

Pending Lock:

struct PendingLock {
    address token;
    address beneficiary;
    uint256 amount;
    uint256 unlockDate;
    string description;
    address presale;
}

Active Lock:

struct Lock {
    address token;
    address beneficiary;
    uint256 totalAmount;
    uint256 claimedAmount;
    uint256 startTimestamp;
    uint256 endTimestamp;
    uint256 releaseInterval;
    uint256 totalIntervals;
}

Claim Function

function claimLock(uint256 lockId) external

Calculation:

Lock storage lock = locks[lockId];
require(msg.sender == lock.beneficiary);

uint256 elapsed = block.timestamp - lock.startTimestamp;
uint256 intervalsPassed = elapsed / lock.releaseInterval;

if (intervalsPassed > lock.totalIntervals) {
    intervalsPassed = lock.totalIntervals;
}

uint256 claimable = (lock.totalAmount * intervalsPassed) / lock.totalIntervals;
claimable -= lock.claimedAmount;

require(claimable > 0, "Nothing to claim");

lock.claimedAmount += claimable;
IERC20(lock.token).transfer(msg.sender, claimable);

7. Blockchain Integration

7.1 Network Configuration

const NETWORKS = {
  mainnet: {
    id: 56,
    name: 'BSC',
    rpc: 'https://bsc-dataseed1.binance.org/',
    explorer: 'https://bscscan.com'
  },
  testnet: {
    id: 97,
    name: 'BSC Testnet',
    rpc: 'https://data-seed-prebsc-1-s1.binance.org:8545/',
    explorer: 'https://testnet.bscscan.com'
  }
};

7.2 Contract Addresses

Network-aware address selection:

export function getContractAddress(
  contract: keyof typeof CONTRACTS,
  chainId: number | undefined
): string {
  if (!chainId) return '';
  const c = CONTRACTS[contract] as any;
  return c[chainId.toString()] || '';
}

// Usage
const tokenFactoryAddress = getContractAddress(CONTRACTS.TokenFactory, chainId);

7.3 Read Operations

// Single read
const { data: info } = useReadContract({
  address: presaleAddress,
  abi: CONTRACTS.Presale.abi,
  functionName: 'info'
});

// Multiple reads (batch)
const { data: results } = useReadContracts({
  contracts: [
    { address: addr, abi, functionName: 'totalRaised' },
    { address: addr, abi, functionName: 'finalized' },
    { address: addr, abi, functionName: 'canceled' }
  ]
});

7.4 Write Operations

const { writeContract, isPending } = useWriteContract();
const { isSuccess } = useWaitForTransactionReceipt({ hash });

// Execute
writeContract({
  address: presaleAddress,
  abi: CONTRACTS.Presale.abi,
  functionName: 'deposit',
  args: [referrer],
  value: parseEther(amount)
});

// Handle success
useEffect(() => {
  if (isSuccess) {
    refetch();
    showSuccess();
  }
}, [isSuccess]);

8. Wallet Connection

8.1 Provider Setup

// RainbowKit + Wagmi configuration
const config = getDefaultConfig({
  appName: "Revolution Pad",
  projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
  chains: [bsc, bscTestnet],
  transports: {
    [bsc.id]: http(),
    [bscTestnet.id]: http()
  }
});

8.2 Supported Wallets

MetaMask
Trust Wallet
Coinbase Wallet
WalletConnect
Ledger
Rabby
OKX Wallet
Rainbow

8.3 Connection Flow

User clicks "Connect Wallet"
    ↓
RainbowKit modal opens
    ↓
User selects wallet
    ↓
Wallet approval request
    ↓
User approves
    ↓
Account connected
    ↓
Switch to correct network (if needed)
    ↓
UI updates with address + balance

8.4 Network Switching

Automatic network switching:

const { switchChain } = useSwitchChain();

// If wrong network, prompt switch
if (chainId !== targetChainId) {
  switchChain({ chainId: targetChainId });
}

9. User Flows

9.1 Token Creation Flow

Navigate to /create-token

Open the token creation wizard.

Enter token details

Name: e.g. "Revolution"
Symbol: e.g. "RVL"
Supply: e.g. "1000000"
Decimals: e.g. "18"

Configure taxes (optional)

Buy Tax: e.g. 5%
Sell Tax: e.g. 5%
Recipients: [{ wallet: "0x...", percentage: "100" }]

Select features

Mintable: yes/no
Burnable: yes/no
Ownable: yes/no
Trade Enabled: yes/no

Review & Deploy

Show summary
Estimate gas (example: ~0.01 BNB)
Click "Create Token"

Wallet confirmation

Pay collateral (example: 0.00123 BNB)
Pay gas (example: ~0.01 BNB)

Token created

Token address displayed
Tokens minted to wallet
Record saved to database

Next steps

View on BSCScan
Create presale
Configure tax recipients

9.2 Presale Creation Flow

Navigate to /launchpad/create

Open the presale creation page.

Select token

Choose from "My Tokens"
Token: RVL (0x...)
Balance: e.g. 1,000,000 RVL

Presale configuration

Hardcap: e.g. 10 BNB
Softcap: e.g. 5 BNB
Rate: e.g. 1000 (1 BNB = 1000 RVL)
Liquidity %: e.g. 60%
Lock Duration: e.g. 365 days
Start Time / End Time
Min Buy / Max Buy

Referral settings (optional)

Enable: yes/no
Mode: Standard
Level 1: e.g. 5%
Level 2: e.g. 3%
Threshold: e.g. 0.1 BNB

Leaderboard settings (optional)

Enable: yes/no
Prize Pool %: e.g. 5%
Top Count: e.g. 10

Allocation breakdown (optional)

Team: e.g. 10% (locked 6 months)
Marketing: e.g. 5% (unlocked)
Public Sale: e.g. 70%
Liquidity: e.g. 30%

Project info

Description, logo URL, media (YouTube/image)
Website, Twitter, Telegram

Token requirements calculation

Presale Tokens, Liquidity Tokens, Allocation Tokens
Total required tokens example: 17,000 RVL

Approve token spend

Approve required tokens to LaunchpadFactory (example: 17,000 RVL)

Create presale

Pay creation fee (example: 0 BNB)
Gas estimate (example: ~0.5 BNB)

Presale created

Presale address displayed
Share link provided (example: rvl.network/launchpad/0x...)

9.3 Purchase Flow

Open presale page

URL: rvl.network/launchpad/[presale-address]

Verify eligibility

Status: Active Sale
Wallet: Connected
Whitelist: Approved (if private)

Enter amount

Input: e.g. 1 BNB
Receive: e.g. 1,000 RVL

Optional referral code

From URL: ?ref=0x...
Or manual entry

Click "Buy Tokens"

Initiates the purchase transaction.

Wallet confirmation

Pay purchase amount + gas

Transaction confirmed

Tokens purchased
Investment recorded
Referrer rewarded
Leaderboard updated

9.4 Claim Flow (After Finalization)

Open presale page

Status: Completed

View available claims

Tokens available
Referral rewards (if any)
Leaderboard prizes (if applicable)

Click "Claim Tokens"

Triggers claim transaction.

Wallet confirmation

Pay gas (example: ~0.01 BNB)

Tokens received

Tokens transferred to wallet

10. Admin Panel

10.1 Overview

Admin panel (/admin) provides platform statistics and contract management.

10.2 Dashboard Sections

Statistics View:

Total tokens created
Total presales launched
Total BNB raised
Active presales count

Contract Information:

TokenFactory address
LaunchpadFactory address
TokenLocker address
PancakeSwap Router address

Contract Cards: Each contract displays:

Address (with copy button)
Owner (if applicable)
Key metrics
View on BSCScan button

TokenFactory Card:

Collateral amount
Tax duration
Router address

LaunchpadFactory Card:

Creation fee
Implementation address
Total presales count

TokenLocker Card:

Type: Escrow
Governance: Decentralized

10.3 Admin Features

View real-time data (auto-refresh every 3s)
Investment tracking
Token balances
Manage contracts (view details, copy addresses, open BSCScan)

11. Launchpad System

11.1 Presale Lifecycle

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ Creation │ ───▶│ Upcoming │ ───▶│  Active  │ ───▶│  Ended   │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                          │               │
          ┌──────────────┐               │               │
          │   Canceled   │◀──────────────┴───────────────┤
          └──────────────┘                                 │
                                                          ▼
                                                  ┌──────────────┐
                                                  │  Finalizing  │
                                                  └──────────────┘
                                                          │
                        ┌───────────────┬──────────────────┘
                        ▼               ▼
                 ┌──────────┐    ┌──────────┐
                 │ Failed   │    │Completed │
                 └──────────┘    └──────────┘

11.2 Status Definitions

Status

Trigger

User Actions

Upcoming

currentTime < startTime

View project, wait

Active

startTime ≤ currentTime ≤ endTime

Buy tokens, withdraw

Ended

currentTime > endTime

Wait for finalization

Completed

finalized = true

Claim tokens/rewards

Failed

ended && raised < softcap

Refund investment

Canceled

canceled = true

Refund investment

11.3 Presale Types

Standard Presale

Fixed rate presale with predetermined pricing.

Formula:

Tokens Received = BNB Amount × Rate

Fair Launch

Dynamic pricing based on total raised.

Formula:

Current Rate = Total Tokens / Total BNB Raised
Tokens Received = BNB Amount × Current Rate

11.4 Finalization Process

Successful Finalization (Softcap Reached)

Owner calls finalize
Validate conditions
Calculate liquidity (BNB & tokens)
Add liquidity to PancakeSwap
Lock LP tokens in TokenLocker
Enable trading on RevolutionToken
Emit Finalized event
Users can claim tokens

Failed Finalization (Softcap Not Reached)

Presale ends
Status becomes Failed
Users can refund via refund()
Tokens returned to owner

12. Token Factory

12.1 Token Creation Process

Step 1: User Input

const formData = {
  name: "Revolution",
  symbol: "RVL",
  totalSupply: "1000000000000000000000000", // 1M * 10^18
  decimals: "18",
  buyTax: "5",
  sellTax: "5",
  isMintable: false,
  isBurnable: true,
  isOwnable: true,
  tradeEnabled: true,
  taxRecipients: [
    { wallet: "0x...", percentage: "100" }
  ]
};

Step 2: Validation

// Frontend validation
if (!formData.name || formData.name.length > 50) {
  throw new Error("Invalid name");
}

if (!/^[A-Z0-9]+$/.test(formData.symbol)) {
  throw new Error("Symbol must be uppercase alphanumeric");
}

if (Number(formData.buyTax) > 25) {
  throw new Error("Buy tax cannot exceed 25%");
}

// Sum of percentages must equal 100
const totalPercent = taxRecipients.reduce(
  (sum, r) => sum + Number(r.percentage), 0
);
if (totalPercent !== 100) {
  throw new Error("Percentages must sum to 100");
}

Step 3: Contract Deployment

function createToken(...) external payable returns (address) {
    // 1. Validate collateral
    require(msg.value >= collateralAmount);

    // 2. Deploy token
    RevolutionToken token = new RevolutionToken(
        name,
        symbol,
        totalSupply,
        decimals,
        buyTax,
        sellTax,
        isMintable,
        isBurnable,
        isOwnable,
        tradeEnabled
    );

    address tokenAddress = address(token);

    // 3. Set tax recipients
    if (taxRecipients.length > 0) {
        token.setTaxRecipients(taxRecipients);
    }

    // 4. Record payment
    hasPaid[tokenAddress] = true;

    emit TokenCreated(tokenAddress, msg.sender);

    return tokenAddress;
}

Step 4: Database Record

// After successful deployment
await fetch('/api/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    address: tokenAddress,
    name: formData.name,
    symbol: formData.symbol,
    ownerAddress: userAddress,
    isMintable: formData.isMintable,
    isBurnable: formData.isBurnable,
    isOwnable: formData.isOwnable,
    buyTax: Number(formData.buyTax),
    sellTax: Number(formData.sellTax),
    tradeEnabled: formData.tradeEnabled
  })
});

12.2 Tax System

Tax Configuration

struct TaxRecipient {
    address wallet;
    uint256 buyPercent;
    uint256 sellPercent;
}

TaxRecipient[] public taxRecipients;
uint8 public buyTax;
uint8 public sellTax;

Setting Recipients

function setTaxRecipients(TaxRecipient[] memory _recipients) external onlyOwner {
    // Validate percentages sum to 100
    uint256 totalBuy;
    uint256 totalSell;

    for (uint i = 0; i < _recipients.length; i++) {
        totalBuy += _recipients[i].buyPercent;
        totalSell += _recipients[i].sellPercent;
    }

    require(totalBuy == buyTax, "Buy percent mismatch");
    require(totalSell == sellTax, "Sell percent mismatch");

    taxRecipients = _recipients;
}

Tax Collection on Transfer

function _transfer(address from, address to, uint256 amount) internal override {
    // Skip tax if trading disabled or excluded
    if (!tradeEnabled || isExcluded[from] || isExcluded[to]) {
        super._transfer(from, to, amount);
        return;
    }

    // Determine if buy or sell
    bool isBuy = from == uniV2Pair;
    bool isSell = to == uniV2Pair;

    uint8 taxRate = isBuy ? buyTax : sellTax;

    if (taxRate == 0 || (!isBuy && !isSell)) {
        super._transfer(from, to, amount);
        return;
    }

    // Calculate tax
    uint256 taxAmount = (amount * taxRate) / 100;
    uint256 netAmount = amount - taxAmount;

    // Distribute tax
    for (uint i = 0; i < taxRecipients.length; i++) {
        uint256 share = (taxAmount * taxRecipients[i].buyPercent) / 100;
        super._transfer(from, taxRecipients[i].wallet, share);
    }

    // Transfer net amount
    super._transfer(from, to, netAmount);
}

13. Referral System

13.1 System Overview

Multi-level referral system with:

Level 1: Direct referrals (default 5%)
Level 2: Indirect referrals (default 3%)
Custom influencer rates
Threshold requirement

13.2 Referral Structure

User A (Top Referrer)
  ├─ User B (Level 1 from A) ── Gets 5% reward
  │   └─ User C (Level 2 from A) ── Gets 3% reward
  │
  ├─ User D (Level 1 from A) ── Gets 5% reward
  │   └─ User E (Level 2 from A) ── Gets 3% reward
  └─ User F (Level 1 from A) ── Gets 5% reward

13.3 Reward Calculation

Standard Referral

User B purchases 1 BNB with referrer User A

Level 1 Reward (User A):
  Reward = 1 BNB × 5% = 0.05 BNB

If User C refers User D:
Level 2 Reward (User C):
  Reward = 1 BNB × 3% = 0.03 BNB

Custom Influencer Rate

User X has custom rate of 10%

User Y purchases 1 BNB with referrer User X

Reward = 1 BNB × 10% = 0.1 BNB

13.4 Referral Configuration

struct ReferralInfo {
    uint8 mode;           // 0=disabled, 1=standard
    uint256[4] rewardPercents; // [L1, L2, unused, unused]
    uint256 threshold;    // Minimum purchase for rewards
    uint256 poolPercent;  // For leaderboard
}

// 5% = 500 basis points
rewardPercents[0] = 500; // Level 1
rewardPercents[1] = 300; // Level 2

// Threshold: 0.1 BNB = 100,000,000 wei
threshold = 100000000;

13.5 Threshold Validation

function _processReferral(address buyer, uint256 amount, address referrer) internal {
    // Validate threshold
    if (amount < threshold) {
        return; // No reward if below threshold
    }

    // Check if referrer has custom rate
    uint256 rate = influencerRates[referrer];
    if (rate == 0) {
        rate = rewardPercents[0]; // Use default Level 1
    }

    // Calculate and store reward
    uint256 reward = (amount * rate) / 10000;
    refRewards[referrer] += reward;
    userRefRewardsGenerated[referrer] += reward; // Anti-ghost fix
}

13.6 Anti-Ghost Reward Fix

Previous Bug: Users could claim rewards that weren't actually generated.

Fix: Track actual rewards generated vs. rewards claimed.

mapping(address => uint256) public userRefRewardsGenerated;

function claimRefRewards() external nonReentrant {
    uint256 reward = refRewards[msg.sender];
    require(reward > 0, "No rewards");

    // Critical check
    require(
        userRefRewardsGenerated[msg.sender] >= reward,
        "Excess claim"
    );

    refRewards[msg.sender] = 0;
    payable(msg.sender).transfer(reward);
}

14. Leaderboard System

14.1 Overview

Competition-based system where top referrers share a prize pool.

14.2 Prize Pool Calculation

Prize Pool = Total Raised × Leaderboard Percentage

Example:
- Total Raised: 10 BNB
- Leaderboard Percent: 5%
- Prize Pool: 10 × 0.05 = 0.5 BNB

14.3 Winner Selection

Proportional Distribution

function calculateWinners(uint256 poolAmount, uint256 topCount) {
    address[] memory winners = new address[](topCount);
    uint256[] memory shares = new uint256[](topCount);

    // Get top N referrers by volume
    uint256 totalVolume = 0;

    for (uint i = 0; i < topCount; i++) {
        winners[i] = topReferrers[i];
        totalVolume += refVolumes[topReferrers[i]];
    }

    // Calculate proportional shares
    for (uint i = 0; i < topCount; i++) {
        uint256 volume = refVolumes[winners[i]];
        shares[i] = (poolAmount * volume) / totalVolume;
    }

    return (winners, shares);
}

Example Distribution

Top 3 Referrers:
1. User A: 5 BNB volume
2. User B: 3 BNB volume
3. User C: 2 BNB volume
Total: 10 BNB

Prize Pool: 0.5 BNB (5% of 10 BNB)

User A Share: (0.5 × 5/10) = 0.25 BNB
User B Share: (0.5 × 3/10) = 0.15 BNB
User C Share: (0.5 × 2/10) = 0.10 BNB

14.4 Setting Winners

function setLeaderboardWinners(
    address[] calldata _winners,
    uint256[] calldata _shares
) external onlyOwner {
    require(finalized, "Not finalized");
    require(!lbWinnersSet, "Already set");
    require(_winners.length == _shares.length);

    for (uint i = 0; i < _winners.length; i++) {
        lbShares[_winners[i]] = _shares[i];
    }

    lbWinnersSet = true;
    emit WinnersSet(_winners, _shares);
}

14.5 Claiming Prizes

function claimLbReward() external nonReentrant {
    require(lbWinnersSet, "Winners not set");
    require(!lbClaimed[msg.sender], "Already claimed");

    uint256 share = lbShares[msg.sender];
    require(share > 0, "No prize");

    lbClaimed[msg.sender] = true;
    payable(msg.sender).transfer(share);

    emit LbPrizeClaimed(msg.sender, share);
}

15. Security Architecture

15.1 Smart Contract Security

Access Control

// OnlyOwner modifier
modifier onlyOwner() {
    require(msg.sender == owner, "Not owner");
    _;
}

// Usage
function finalize() external onlyOwner { ... }
function cancelPresale() external onlyOwner { ... }

Reentrancy Protection

import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

contract Presale is ReentrancyGuard {
    function claim() external nonReentrant {
        // Safe from reentrancy attacks
    }
}

Input Validation

// Tax rate cap
require(_buyTax <= 25, "Tax too high");

// Time validation
require(_endTime > _startTime, "Invalid time range");

// Cap validation
require(_hardcap >= _softcap, "Invalid caps");

// Liquidity minimum
require(_liquidityPercent >= 51, "Liquidity too low");

Safe Math

Solidity 0.8+ has built-in overflow protection.

15.2 Frontend Security

URL Validation

// YouTube URLs (strict)
const youtubeRegex = /^(https?:\/\/)?(www\.)?(youtube\.com|youtu\.be)\/.+$/;

if (!youtubeRegex.test(url)) {
    throw new Error("Invalid YouTube URL");
}

// Image URLs
if (!url.startsWith('http://') && !url.startsWith('https://')) {
    throw new Error("Invalid URL");
}

Address Validation

import { isAddress } from 'viem';

if (!isAddress(inputAddress)) {
    throw new Error("Invalid address");
}

Signature Verification

// For project updates
const recoveredAddress = await verifyMessage({
    address: message.split(":")[1],
    message: message,
    signature: signature
});

// Verify ownership
const owner = await publicClient.readContract({
    address: presaleAddress,
    abi: CONTRACTS.Presale.abi,
    functionName: "owner"
});

if (recoveredAddress.toLowerCase() !== owner.toLowerCase()) {
    throw new Error("Unauthorized");
}

15.3 Backend Security

SQL Injection Prevention

Prisma ORM prevents SQL injection:

// Safe - parameterized
await prisma.user.findUnique({
    where: { id: userId }
});

// Never do this
await prisma.$queryRaw(`SELECT * FROM users WHERE id = '${userId}'`);

Rate Limiting

Consider implementing rate limiting for API endpoints.

CORS

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: 'https://rvl.network' }
        ]
      }
    ];
  }
};

16. Deployment

16.1 Local Development

# Install dependencies
npm install

# Start PostgreSQL
# (Using Neon cloud database)

# Configure .env
cp .env.example .env.local
# Edit .env.local with your values

# Run development server
npm run dev

16.2 Production Build

# Build frontend
npm run build

# Start production server
npm run start

16.3 Smart Contract Deployment

cd blockchain

# Configure .env
PRIVATE_KEY=your_private_key
BSCSCAN_API_KEY=your_api_key

# Deploy to testnet
node scripts/deploy-all.js bscTestnet

# Deploy to mainnet
node scripts/deploy-all.js bsc

16.4 Environment Variables

# Database
DATABASE_URL=postgresql://...

# WalletConnect
NEXT_PUBLIC_WC_PROJECT_ID=your_project_id

# App URL
NEXT_PUBLIC_APP_URL=https://rvl.network

16.5 Server Deployment

With PM2:

# Install PM2
npm install -g pm2

# Build
npm run build

# Start
pm2 start npm --name "rvlpad" -- start

# Save
pm2 save

# Auto-start on reboot
pm2 startup

With Docker:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

17. Mathematical Algorithms

17.1 Token Requirements

Standard Presale

Presale Tokens = Hardcap × Rate
Liquidity BNB = Hardcap × (Liquidity Percent / 100)
Liquidity Tokens = Liquidity BNB × Listing Rate
Allocation Tokens = Σ(Allocation[i].percent × TotalSupply / 100)

Total Required = Presale Tokens + Liquidity Tokens + Allocation Tokens

Fair Launch

Presale Tokens = TotalTokensForSale
Liquidity BNB = Hardcap × (Liquidity Percent / 100)
Liquidity Tokens = Liquidity BNB × ListingRate (estimated)
Allocation Tokens = Σ(Allocation[i].percent × TotalSupply / 100)

Total Required = Presale Tokens + Liquidity Tokens + Allocation Tokens

17.2 Progress Calculation

Progress = (TotalRaised / Hardcap) × 100
Progress = min(Progress, 100) // Cap at 100%

17.3 Referral Rewards

Rate Determination:
IF influencerRates[user] > 0:
    Rate = influencerRates[user] / 100 (basis points to percent)
ELSE:
    Rate = rewardPercents[0] / 100 (default Level 1)

Reward Calculation:
Reward = PurchaseAmount × (Rate / 100)

Threshold Check:
IF PurchaseAmount < Threshold:
    No reward

Level 2 Rewards:
When Level 1 referral makes a purchase:
Level2Reward = PurchaseAmount × (rewardPercents[1] / 100)

17.4 Leaderboard Distribution

Prize Pool = TotalRaised × (PoolPercent / 100)

Winner Share Calculation:
TotalVolume = Σ(TopNVolumes[i])
WinnerShare[i] = Prize Pool × (WinnerVolume[i] / TotalVolume)

Validation:
Σ(WinnerShare[i]) = Prize Pool (within rounding)

17.5 Token Vesting

Vesting Calculation:
Elapsed = CurrentTime - StartTime
IntervalsPassed = Elapsed / ReleaseInterval
IntervalsPassed = min(IntervalsPassed, TotalIntervals)

Claimable = (TotalAmount / TotalIntervals) × IntervalsPassed
NetClaimable = Claimable - AlreadyClaimed

17.6 Tax Distribution

TaxCollection:
TaxAmount = (TokenAmount × TaxRate) / 100
NetAmount = TokenAmount - TaxAmount

Distribution:
FOR each recipient:
    Share = (TaxAmount × RecipientPercent) / 100
    Transfer Share to Recipient

17.7 Liquidity Addition

Liquidity BNB = TotalRaised × (LiquidityPercent / 100)
Liquidity Tokens = Liquidity BNB × ListingRate

LP Tokens Received = (Liquidity BNB × Liquidity Tokens) / (Pool BNB + Pool Tokens)

Appendix

Contract Addresses (Mainnet)

Contract

Address

TokenFactory

0xe646cD6f07CbBC7e275b264B9c33A2b1b5eb8091

LaunchpadFactory

0xE44bD842eeA5D58bb70581D757220e0834f5f82B

TokenLocker

0x4e702C466f130127f675E83C6be0CC3970C38FDB

Router (PancakeSwap)

0x10ED43C718714eb63d5aA57B78B54704E256024E

Contract Addresses (Testnet)

Contract

Address

TokenFactory

0xa82ec4078AF406b8e044A3094628B96292B7D18E

LaunchpadFactory

0x9F387ED44F1afCaa9cE1235Fd1966b7aA4300987

TokenLocker

0xB0a49Ea3CDB859F1bea9a7340b60C8c4a84A4f8E

Router (PancakeSwap)

0xD99D1c33F9fC3444f8101754aBC46c52416550D1

hashtag1. Platform Overview

hashtag1.1 What is Revolution Pad?

hashtag1.2 Key Features

hashtag1.3 Technology Stack

hashtag2. System Architecture

hashtag2.1 Overall Architecture

hashtag2.2 Data Flow

hashtag3. Frontend Application

hashtag3.1 Project Structure

hashtag3.2 Key Pages

hashtagBasic Info

hashtagTax Configuration

hashtagFeatures

hashtagReview & Deploy

hashtag3.3 State Management

hashtag3.4 Responsive Design

hashtag4. Backend API

hashtag4.1 API Routes

hashtag4.2 Error Handling

hashtag4.3 Validation

hashtag5. Database Layer

hashtag5.1 Database Schema

hashtag5.2 Database Operations

hashtag5.3 Relationships

hashtag6. Smart Contracts

hashtag6.1 Contract Overview

hashtag6.2 RevolutionToken

hashtag6.3 TokenFactory

hashtag6.4 Presale

hashtag6.5 LaunchpadFactory

hashtag6.6 TokenLocker

hashtag7. Blockchain Integration

hashtag7.1 Network Configuration

hashtag7.2 Contract Addresses

hashtag7.3 Read Operations

hashtag7.4 Write Operations

hashtag8. Wallet Connection

hashtag8.1 Provider Setup

hashtag8.2 Supported Wallets

hashtag8.3 Connection Flow

hashtag8.4 Network Switching

hashtag9. User Flows

hashtag9.1 Token Creation Flow

hashtagNavigate to /create-token

hashtagEnter token details

hashtagConfigure taxes (optional)

hashtagSelect features

hashtagReview & Deploy

hashtagWallet confirmation

hashtagToken created

hashtagNext steps

hashtag9.2 Presale Creation Flow

hashtagNavigate to /launchpad/create

hashtagSelect token

hashtagPresale configuration

hashtagReferral settings (optional)

hashtagLeaderboard settings (optional)

hashtagAllocation breakdown (optional)

hashtagProject info

hashtagToken requirements calculation

hashtagApprove token spend

hashtagCreate presale

hashtagPresale created

hashtag9.3 Purchase Flow

hashtagOpen presale page

hashtagVerify eligibility

hashtagEnter amount

hashtagOptional referral code

hashtagClick "Buy Tokens"

hashtagWallet confirmation

hashtagTransaction confirmed

hashtag9.4 Claim Flow (After Finalization)

hashtagOpen presale page

hashtagView available claims

hashtagClick "Claim Tokens"

hashtagWallet confirmation

hashtagTokens received

hashtag10. Admin Panel

hashtag10.1 Overview

hashtag10.2 Dashboard Sections

1. Platform Overview

1.1 What is Revolution Pad?

1.2 Key Features

1.3 Technology Stack

2. System Architecture

2.1 Overall Architecture

2.2 Data Flow

3. Frontend Application

3.1 Project Structure

3.2 Key Pages

Basic Info

Tax Configuration

Features

Review & Deploy

3.3 State Management

3.4 Responsive Design

4. Backend API

4.1 API Routes

4.2 Error Handling

4.3 Validation

5. Database Layer

5.1 Database Schema

5.2 Database Operations

5.3 Relationships

6. Smart Contracts

6.1 Contract Overview

6.2 RevolutionToken

6.3 TokenFactory

6.4 Presale

6.5 LaunchpadFactory

6.6 TokenLocker

7. Blockchain Integration

7.1 Network Configuration

7.2 Contract Addresses

7.3 Read Operations

7.4 Write Operations

8. Wallet Connection

8.1 Provider Setup

8.2 Supported Wallets

8.3 Connection Flow

8.4 Network Switching

9. User Flows

9.1 Token Creation Flow

Navigate to /create-token

Enter token details

Configure taxes (optional)

Select features

Review & Deploy

Wallet confirmation

Token created

Next steps

9.2 Presale Creation Flow

Navigate to /launchpad/create

Select token

Presale configuration

Referral settings (optional)

Leaderboard settings (optional)

Allocation breakdown (optional)

Project info

Token requirements calculation

Approve token spend

Create presale

Presale created

9.3 Purchase Flow

Open presale page

Verify eligibility

Enter amount

Optional referral code

Click "Buy Tokens"

Wallet confirmation

Transaction confirmed

9.4 Claim Flow (After Finalization)

Open presale page

View available claims

Click "Claim Tokens"

Wallet confirmation

Tokens received

10. Admin Panel

10.1 Overview

10.2 Dashboard Sections