Decentralized Exchange — Full Documentation

What Is This

This is a fully functional decentralized exchange (DEX) forked from PancakeSwap V2. It includes the complete smart contract suite and a working frontend — not a template or mockup.

All contracts are compiled, tested, and deploy from a single Hardhat project. The frontend connects to your deployed contracts automatically via configuration scripts.

What This Is NOT

• Not a SaaS platform — you deploy and own everything
• Not connected to PancakeSwap — fully independent after deployment
• Does not include a backend API server — the NFT marketplace page requires one and is not functional without it
• Does not include a SubGraph indexer — some analytics features (info pages) depend on The Graph and are disabled

Features Included

Architecture

How It Works

1. Deploy contracts to your target blockchain using Hardhat
2. The deploy script saves all contract addresses to deployed-addresses.json
3. update-frontend.js reads those addresses and patches the frontend config files
4. patch-sdk.js patches the @pancakeswap/sdk with your factory address and init code hash
5. The frontend reads chain ID from .env.development and connects to your contracts

Requirements

For Deployment to a Live Network

• Private key of a funded wallet (deployer account)
• RPC endpoint for your target chain (Alchemy, Infura, QuickNode, or public RPC)
• Native gas tokens — deployment costs approximately 0.15–0.3 of the chain's native token (varies by network)

Project Structure

Install Dependencies

# Smart contracts
cd dex-contracts
npm install

# Frontend
cd ../fireswap-frontend
yarn install

Deploy Smart Contracts

# dex-contracts/.env
DEPLOYER_PRIVATE_KEY=your_private_key_here

# Pick your network RPC:
BSC_TESTNET_RPC_URL=https://data-seed-prebsc-1-s1.bnbchain.org:8545
# SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY

cd dex-contracts
npx hardhat run scripts/deploy.js --network bscTestnet

# Add liquidity to pools, deploy lottery
npx hardhat run scripts/setup-testnet.js --network bscTestnet

# Deploy syrup staking pools
npx hardhat run scripts/deploy-pools.js --network bscTestnet

# Deploy price prediction game
npx hardhat run scripts/deploy-prediction.js --network bscTestnet

# Deploy NFT collection
npx hardhat run scripts/deploy-nft.js --network bscTestnet

Setup Frontend

cd dex-contracts
node scripts/update-frontend.js

node scripts/patch-sdk.js

cd ../fireswap-frontend
yarn dev

yarn build
# Deploy the 'out' or '.next' directory to Vercel, Netlify, or any static host

Change the Main Token

The default governance/reward token is called CakeToken in the contracts. To rebrand it (e.g., to "FIRE", "MYTOKEN", etc.), update these locations:

1. Smart Contract — Token Name & Symbol

Edit dex-contracts/contracts/farm/CakeToken.sol:

// In the constructor or token metadata:
constructor() BEP20('Your Token Name', 'SYMBOL') {
    // ...
}

Redeploy after changing this.

2. Frontend — Token Display

Edit fireswap-frontend/src/config/constants/tokens.ts — update the localTokens.cake entry:

cake: new Token(
  CUSTOM_CHAIN_ID,
  '0xYOUR_TOKEN_ADDRESS',
  18,
  'SYMBOL',        // Display symbol
  'Your Token Name', // Display name
  '#',
),

3. Farm Labels

Edit fireswap-frontend/src/config/constants/farms.ts — update the lpSymbol values:

// pid 0
lpSymbol: 'SYMBOL',

// pid 1
lpSymbol: 'SYMBOL-BNB LP',

4. Token Icon

Place your token icon (PNG, 128x128 recommended) at:

fireswap-frontend/public/images/tokens/{your_token_address}.png

The filename must be the checksummed contract address with a .png extension.

5. Emission Rate

The MasterChef mints your token at a configurable rate. Edit in dex-contracts/scripts/deploy.js:

// 40 tokens per block (default)
const cakePerBlock = ethers.utils.parseEther("40");

This is set at deployment time and cannot be changed after MasterChef is deployed.

Swap Fees

Trading Fee (Default: 0.2%)

Every swap charges a 0.2% fee on the input amount. This fee is split between liquidity providers and (optionally) a protocol treasury.

How to Change the Swap Fee

The fee is hardcoded in two contract files. Both must match:

File 1: contracts/periphery/libraries/PancakeLibrary.sol

// Line 47 — getAmountOut()
uint amountInWithFee = amountIn.mul(998);  // 998 = 0.2% fee
// For 0.3% fee, use 997. For 0.25% fee, use 9975 (and change 1000 → 10000).

// Line 58 — getAmountIn()
uint denominator = reserveOut.sub(amountOut).mul(998);

File 2: contracts/core/PancakePair.sol

// Lines 180-181 — swap()
uint balance0Adjusted = balance0.mul(1000).sub(amount0In.mul(2));
uint balance1Adjusted = balance1.mul(1000).sub(amount1In.mul(2));
// The "2" here = 1000 - 998 = 2 (the fee in thousandths)
// For 0.3% fee: change 2 → 3, and PancakeLibrary to 997

Protocol Fee Recipient

To enable the protocol treasury fee, call setFeeTo() on the Factory contract after deployment:

// In a Hardhat script or via block explorer:
factory.setFeeTo("0xYOUR_TREASURY_ADDRESS");

If feeTo is the zero address (default), all fees go to LPs.

Farms & Pools

Adding a New Farm

Farms are managed by the MasterChef contract. Each farm tracks an LP token and distributes your main token as rewards.

On-Chain (MasterChef)

// Call add() on MasterChef — only the owner can do this
masterChef.add(
  2000,            // allocPoint — share of total emissions
  "0xLP_ADDRESS", // LP token address from Factory.getPair()
  true             // withUpdate — update all pools
);

The allocPoint determines what fraction of token emissions this farm receives. If total allocPoints across all farms is 10000 and your farm has 2000, it gets 20% of emissions.

Frontend Config

Edit fireswap-frontend/src/config/constants/farms.ts and add an entry:

{
  pid: 3,                    // Must match the MasterChef pool ID
  lpSymbol: 'TOKEN-BNB LP',
  lpAddresses: {
    97: '0xLP_ADDRESS_TESTNET',
    56: '0xLP_ADDRESS_MAINNET',
  },
  token: serializedTokens.yourToken,
  quoteToken: serializedTokens.wbnb,
},

Adding a Syrup Pool (SmartChef)

Syrup pools are standalone contracts. Deploy a new SmartChef for each pool:

// Constructor parameters:
SmartChef(
  stakedToken,     // Token users deposit (e.g., your main token)
  rewardToken,     // Token users earn (e.g., BUSD)
  rewardPerBlock,  // Reward rate per block (in wei)
  startBlock,      // Block number when rewards begin
  bonusEndBlock,   // Block number when rewards stop
)

After deploying, transfer reward tokens to the SmartChef contract to fund it, then add the pool to fireswap-frontend/src/config/constants/pools.tsx.

Branding & Theme

Colors

Theme colors are defined in the UIKit package:

fireswap-frontend/packages/uikit/src/theme/colors.ts

Edit darkColors and lightColors objects. Key properties: primary, secondary, background, backgroundAlt, cardBorder.

Logo

Replace the logo files in:

fireswap-frontend/public/logo.png
fireswap-frontend/packages/uikit/src/components/Svg/Icons/Logo*.tsx

Site Title & Metadata

Edit fireswap-frontend/src/views/*/index.tsx — each page has a <PageMeta /> component that sets the page title. Global defaults are in src/components/Layout/Page.tsx.

Menu Items

The navigation menu is configured in:

fireswap-frontend/src/components/Menu/config/config.ts

The localConfig array controls which menu items appear. Add or remove items as needed.

Core Contracts

Farm Contracts

MasterChef Key Parameters

Lottery & Prediction Contracts

Lottery

Lottery rounds are managed by an operator address. Key functions: startLottery(), closeLottery(), drawFinalNumberAndMakeLotteryClaimable().

Prediction

Supported Blockchains

This DEX can be deployed on any EVM-compatible blockchain. The contracts are standard Solidity and the frontend uses standard Web3 libraries.

Pre-configured Networks

Adding a New Network

1. Add the network to dex-contracts/hardhat.config.js:

polygon: {
  url: process.env.POLYGON_RPC_URL || "",
  chainId: 137,
  accounts: process.env.DEPLOYER_PRIVATE_KEY ? [process.env.DEPLOYER_PRIVATE_KEY] : [],
},

2. Deploy with npx hardhat run scripts/deploy.js --network polygon

3. The update-frontend.js and patch-sdk.js scripts automatically detect the chain ID from deployed-addresses.json.

Compatible Chains (non-exhaustive)

Any chain with EVM bytecode compatibility, a JSON-RPC endpoint, and a block explorer will work.

Environment Variables

dex-contracts/.env

fireswap-frontend/.env.development

These are automatically set by update-frontend.js:

Scripts Reference

Troubleshooting

Swap page shows no output amount

First deployment exits early with "hash mismatch"

Token icons are broken / missing

Pages redirect to /swap unexpectedly

Farms/Pools show 0 APR or "Loading"

Prediction page shows loading spinner