Token Presale Documentation

Complete guide to deploying, configuring, and managing your token presale platform with multi-stage pricing, boost vault, referral system, auto-liquidity, and P2P emergency market.

⚙ Requirements

Smart Contracts

Frontend

External Accounts

• Reown Cloud account — get a free Project ID at cloud.reown.com for wallet connections
• BNB wallet — deployer wallet with BNB for gas fees
• BscScan API key (optional) — for contract verification

✓ Installation

1. Install Foundry (for Smart Contracts)

Foundry is the Solidity development toolkit used for compiling, testing, and deploying the contracts.

# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Verify installation
forge --version

2. Install Contract Dependencies

cd contracts

# Install OpenZeppelin, Chainlink, and forge-std
forge install OpenZeppelin/openzeppelin-contracts --no-commit
forge install smartcontractkit/chainlink-brownie-contracts --no-commit
forge install foundry-rs/forge-std --no-commit

3. Install Frontend Dependencies

cd frontend
npm install

4. Start the Development Server

npm run dev
# Opens at http://localhost:5173

Build for Production

npm run build
# Output: frontend/dist/
# Upload the dist/ folder to any static hosting (Vercel, Netlify, etc.)

⚙ Configuration

All frontend configuration lives in frontend/.env. After deploying your own contracts, update these values:

# Reown (WalletConnect) project ID from cloud.reown.com
VITE_REOWN_PROJECT_ID=your_project_id_here

# PresaleVault contract address
VITE_CONTRACT_ADDRESS=0xYourPresaleVaultAddress

# EmergencyMarket contract address (leave empty to disable the Market tab)
VITE_EMERGENCY_MARKET_ADDRESS=0xYourEmergencyMarketAddress

# Whitelisted stablecoin addresses
VITE_USDT_ADDRESS=0xYourUSDTAddress
VITE_USDC_ADDRESS=0xYourUSDCAddress

# Display settings
VITE_PROJECT_NAME=Token Presale
VITE_TOKEN_SYMBOL=TOKEN
VITE_TOKEN_DECIMALS=18

# Chain ID: 97 = BSC Testnet, 56 = BSC Mainnet
VITE_CHAIN_ID=97

Reown Project ID

1. Create a Reown Cloud account
   Visit cloud.reown.com and sign up for free.
2. Create a new project
   Click "New Project", give it a name, and select "AppKit" as the SDK.
3. Copy the Project ID
   Paste it into your .env as VITE_REOWN_PROJECT_ID.

Chain Configuration

The chain is configured in frontend/src/lib/appkit-config.ts. To switch to BSC Mainnet:

// Change from:
import { bscTestnet } from "@reown/appkit/networks"
export const networks = [bscTestnet]

// Change to:
import { bsc } from "@reown/appkit/networks"
export const networks = [bsc]

And update VITE_CHAIN_ID=56 in your .env.

◇ PresaleVault Contract

The core contract that handles token sales, payment splitting, boost locking, and referral tracking.

Constructor Parameters

StageConfig Struct

struct StageConfig {
    uint256 priceUsd;              // Token price, 6 decimals (100 = $0.000100)
    uint256 tokenAllocation;       // Total tokens for this stage (18 decimals)
    uint48  startTime;             // Unix timestamp
    uint48  endTime;               // Unix timestamp
    uint256 minBuyUsd;             // Minimum purchase in USD (6 decimals)
    uint256 maxBuyPerWalletUsd;    // Per-wallet max in USD (6 decimals)
    uint256 boostBaseMultiplier;   // Base multiplier in BPS (200 = 2.0x)
}

BoostTier Struct

struct BoostTier {
    uint256 lockDuration;     // Seconds (30 days = 2592000)
    uint256 multiplierBps;    // Multiplier in BPS (12000 = 1.2x)
}

Key Functions

Security Features

• Ownable2Step — Two-step ownership transfer prevents accidental loss
• ReentrancyGuard — Protects all payment functions from reentrancy
• Pausable — Emergency pause mechanism for all operations
• Chainlink Price Feed — Real-time pricing with 1-hour staleness check
• SafeERC20 — Safe token transfer handling

◇ EmergencyMarket Contract

An optional P2P trading contract that lets presale holders sell tokens at a discount before exchange listing. Fully pausable and independent from the main presale.

Constructor Parameters

Key Functions

Price Validation

When a seller creates an order, the contract enforces:

▷ Deployment via CLI (Foundry)

The project includes ready-to-use Foundry deploy scripts. This is the recommended deployment method.

Deploy to BSC Testnet (Full Stack)

This script deploys everything: mock sale token, mock USDT/USDC, mock price feeds, and the PresaleVault. Perfect for testing.

cd contracts

PRIVATE_KEY=your_deployer_private_key \
forge script script/DeployTestnet.s.sol:DeployTestnet \
  --rpc-url https://data-seed-prebsc-1-s1.binance.org:8545 \
  --broadcast

This will deploy and log all addresses. Copy them into frontend/.env.

Deploy to BSC Mainnet

For mainnet, you need your own ERC20 sale token already deployed.

cd contracts

PRIVATE_KEY=your_deployer_private_key \
SALE_TOKEN=0xYourTokenAddress \
OWNER_WALLET=0xYourOwnerWallet \
LIQUIDITY_WALLET=0xYourLiquidityWallet \
forge script script/Deploy.s.sol:Deploy \
  --rpc-url https://bsc-dataseed1.binance.org \
  --broadcast

Deploy Emergency Market

Deploy separately after the PresaleVault is live. Update the hardcoded addresses in the script first.

cd contracts

# Edit script/DeployEmergencyMarket.s.sol first:
# - Set presaleVault to your deployed PresaleVault address
# - Set bnbFeed to the correct Chainlink feed
# - Set USDT/USDC addresses
# - Set stableFeed address

PRIVATE_KEY=your_deployer_private_key \
forge script script/DeployEmergencyMarket.s.sol:DeployEmergencyMarket \
  --rpc-url https://data-seed-prebsc-1-s1.binance.org:8545 \
  --broadcast

Verify on BscScan (Optional)

forge verify-contract 0xYourContractAddress src/PresaleVault.sol:PresaleVault \
  --chain-id 97 \
  --etherscan-api-key your_bscscan_api_key \
  --constructor-args $(cast abi-encode "constructor(address,address,address,address,uint256,uint256,(uint256,uint256,uint48,uint48,uint256,uint256,uint256)[],(uint256,uint256)[])" ...)

Chainlink Price Feed Addresses

▷ Deployment via Remix IDE

If you prefer a browser-based approach without CLI tools, you can deploy directly from Remix IDE.

1. Open Remix IDE

   Navigate to remix.ethereum.org in your browser.

2. Create the contract files

   In the File Explorer, create a new file for each contract. Copy the contents of PresaleVault.sol and EmergencyMarket.sol from the contracts/src/ folder.

3. Install dependencies via imports

   Remix handles OpenZeppelin and Chainlink imports automatically via npm-style paths. Change the import paths to use npm format:

   Remix Import Format

   // Change Foundry-style paths:
   import "@openzeppelin/contracts/access/Ownable2Step.sol";
   
   // These already work in Remix as-is!
   // Remix auto-resolves @openzeppelin and @chainlink from npm

4. Compile

   Go to the Solidity Compiler tab. Set compiler version to 0.8.24, enable optimization (200 runs), and click "Compile".

5. Connect your wallet

   In the "Deploy & Run" tab, set the environment to "Injected Provider - MetaMask". Make sure MetaMask is connected to BSC (testnet or mainnet).

6. Deploy PresaleVault

   Select PresaleVault from the contract dropdown. Fill in the constructor parameters:

// _saleToken:
0xYourSaleTokenAddress

// _bnbPriceFeed (BSC Mainnet):
0x0567F2323251f0Aab15c8dFb1967E4e8A7D42aeE

// _ownerWallet:
0xYourOwnerWallet

// _liquidityWallet:
0xYourLiquidityWallet

// _liquidityBps:
1000   // 10%

// _referralRewardBps:
300    // 3%

// _stages (3 stages, 7 days each):
[[100,"333333333000000000000000000",START_TIMESTAMP,END_STAGE1,1000000,10000000000,200],[150,"333333333000000000000000000",END_STAGE1,END_STAGE2,1000000,10000000000,150],[200,"333333334000000000000000000",END_STAGE2,END_STAGE3,1000000,10000000000,100]]

// _boostTiers (3 tiers):
[[2592000,12000],[5184000,15000],[7776000,20000]]

1. Fund the Vault

   After deployment, call transfer() on your sale token to send tokens to the PresaleVault address. The vault needs tokens in its balance to distribute during purchases.

2. Whitelist payment tokens

   Call whitelistToken() on the PresaleVault for each stablecoin you want to accept (USDT, USDC). You'll need the stablecoin address and its Chainlink price feed address.

3. Deploy EmergencyMarket (optional)

   Select EmergencyMarket, fill constructor with PresaleVault address, BNB price feed, fee (200), and max discount (5000). Then whitelist stablecoins on the market contract too.

★ How the Presale Works

Stage Progression

The presale operates in sequential stages. Each stage has its own price, time window, and token allocation. Price increases across stages to incentivize early participation.

Buying Flow

1. User connects wallet

   MetaMask, Trust Wallet, WalletConnect, or any supported wallet via Reown AppKit.

2. Select payment method

   Choose BNB (native), USDT, or USDC. For ERC20 tokens, an approve transaction is required first.

3. Enter amount and confirm

   The UI shows a live preview of tokens to receive based on the current stage price and Chainlink BNB/USD rate.

4. Payment is split automatically

   Referral commission (3%) + liquidity (10%) + owner (87%) are distributed in the same transaction.

5. Tokens received instantly

   Sale tokens are transferred to the buyer's wallet in the same transaction.

Token Price Calculation

Per-Wallet Limits

Each wallet has a maximum USD spend tracked per stage. The default configuration allows $10,000 per wallet per stage. Exceeding this limit reverts the transaction. The minimum buy is $1 per transaction.

⤴ Boost Vault

The Boost Vault lets users lock their purchased tokens for a chosen duration and receive bonus tokens as a reward. Longer locks and earlier stages give higher multipliers.

Available Tiers (Default)

Bonus Calculation

Stage Base Multipliers (Default)

Locking Flow

➦ Referral System

Built-in on-chain referral tracking. Referrers receive a percentage of every referred purchase, paid instantly in the same transaction.

How It Works

• Referral link format: https://yoursite.com/?ref=0xReferrerAddress
• Default commission: 3% of every referred purchase (300 BPS)
• Payment: BNB for BNB purchases, or original ERC20 for token purchases
• Validation: Referrer must have purchased tokens in any stage. Self-referral is blocked.
• Tracking: Referral earnings are tracked on-chain via referralEarnings[address]

Referral Payout Flow

↺ Auto-Liquidity

Every purchase automatically allocates a configurable percentage to a dedicated liquidity wallet. This builds up a transparent, verifiable liquidity fund for post-presale DEX listing.

Payment Split (Default 10%)

The liquidity wallet address and percentage are immutable — set at deployment and cannot be changed. This guarantees transparency: anyone can verify the allocation on-chain.

⚖ Emergency Market Feature

The Emergency Market provides pre-listing secondary liquidity. Presale holders can list tokens for sale at a discount, and other users can buy them below presale price.

Seller Flow

1. Approve tokens
   The UI handles this automatically. Seller approves the EmergencyMarket contract to spend their tokens.
2. Set price and amount
   Choose a discount (1–50% below current presale price) and token amount to sell.
3. Create listing
   Tokens are escrowed in the contract. The order appears in the Market tab for all buyers.
4. Wait for fills or cancel
   Orders can be partially filled. Cancel anytime to reclaim remaining tokens.

Buyer Flow

1. Browse orders
   See all active sell orders with discount percentages in the Market → Buy Orders section.
2. Select and fill
   Choose an order, enter amount, pay with BNB or USDT/USDC. Tokens transferred instantly.

Protocol Fee

A protocol fee (default 2%) is deducted from the buyer's payment. The remainder goes to the seller. Fees accumulate in the contract and can be withdrawn by the owner.

Enabling / Disabling the Market

# Leave empty or remove this line to hide Market tab
VITE_EMERGENCY_MARKET_ADDRESS=

VITE_EMERGENCY_MARKET_ADDRESS=0xYourEmergencyMarketAddress

# Pause the market
cast send 0xMarketAddress "pause()" \
  --rpc-url https://bsc-dataseed1.binance.org \
  --private-key your_owner_private_key

# Unpause the market
cast send 0xMarketAddress "unpause()" \
  --rpc-url https://bsc-dataseed1.binance.org \
  --private-key your_owner_private_key

⚛ Admin Functions Reference

PresaleVault — Owner Functions

EmergencyMarket — Owner Functions

⏻ Enable / Disable Features

Emergency Market

Presale Operations

⚛ Frontend Setup

Commands

Wallet Connection

The frontend uses Reown AppKit (formerly WalletConnect Web3Modal) which supports 20+ wallets out of the box:

• MetaMask
• Trust Wallet
• WalletConnect (QR code for mobile wallets)
• Coinbase Wallet
• Ledger Live
• And many more

Hosting

After npm run build, the dist/ folder is a static site. Deploy to:

• Vercel — Drop the frontend/ folder, set build command to npm run build
• Netlify — Same setup, auto-deploys from folder
• Any static host — Upload dist/ contents. No server required.
• IPFS — For fully decentralized hosting

☰ Frontend Project Structure

✎ Customization Guide

Change Token Name & Symbol

Update these values in frontend/.env:

VITE_PROJECT_NAME=My Token Sale
VITE_TOKEN_SYMBOL=MTK

Change Colors / Theme

All colors are defined as CSS variables in frontend/src/index.css. Edit the :root block for dark theme and [data-theme="light"] for light theme:

:root {
    --primary: #2dd4bf;          /* Main accent color */
    --background: #0b0f19;       /* Page background */
    --card: #141b2d;             /* Card background */
    --accent: #2dd4bf;           /* Accent color */
    --destructive: #f43f5e;      /* Error/warning color */
}

Modify Stage Configuration

Stages are set at contract deployment time and are immutable. To change prices, allocations, or timing, you must deploy a new contract. Edit the deploy script before running:

stages[0] = PresaleVault.StageConfig({
    priceUsd: 100,                        // $0.0001
    tokenAllocation: 333_333_333 ether,   // 333M tokens
    startTime: uint48(block.timestamp),
    endTime: uint48(block.timestamp + 7 days),
    minBuyUsd: 1e6,                       // $1 minimum
    maxBuyPerWalletUsd: 10_000e6,          // $10k max
    boostBaseMultiplier: 200              // 2.0x boost base
});

Modify Boost Tiers

Also set at deployment. Adjust in the deploy script:

tiers[0] = PresaleVault.BoostTier({
    lockDuration: 30 days,      // Lock period
    multiplierBps: 12000        // 1.2x multiplier
});

Change Liquidity / Referral Percentages

These are immutable constructor parameters. Set in the deploy script:

new PresaleVault(
    saleToken,
    bnbPriceFeed,
    ownerWallet,
    liquidityWallet,
    1000,   // 10% to liquidity (change this)
    300,    // 3% referral (change this)
    stages,
    tiers
);

Add More Payment Tokens

After deployment, the owner can add any ERC20 that has a Chainlink price feed:

cast send 0xPresaleVaultAddress \
  "whitelistToken(address,address)" \
  0xNewTokenAddress \
  0xChainlinkPriceFeedForToken \
  --rpc-url https://bsc-dataseed1.binance.org \
  --private-key your_owner_private_key

Then update the frontend .env to add the token address so the UI can display it as a payment option.