NFT Marketplace

Full-stack NFT marketplace on BNB Chain with ERC-721 minting, trading, and BugsCoin (ERC-20) payment integration. Built with Hardhat for smart contract development and React for the frontend.

System Architecture

Smart Contracts (Solidity 0.8.17)

Core Contracts:

• NFT.sol - ERC-721 implementation with enumerable extension
• NFTMarketplace.sol - Marketplace logic with listing/buying/offers
• IBugsCoin.sol - ERC-20 interface for payment token
• MockBugsCoin.sol - Test token for development

Governance:

• NFTGovernance.sol - On-chain governance for marketplace parameters
• NFTGovernanceTimelock.sol - Timelock for proposal execution

Frontend Stack

• React 18.2 - Component-based UI
• Wagmi 2.14 + Viem 2.27 - Ethereum library with TypeScript support
• RainbowKit 2.2 - Multi-wallet connection modal
• React Router 6 - Client-side routing
• Tailwind CSS - Utility-first CSS framework
• Axios - HTTP client for API requests
• Web3.Storage - Decentralized storage for NFT metadata

IPFS Integration

NFT metadata stored on IPFS via Pinata:

• Image uploads
• JSON metadata
• Gateway: https://gateway.pinata.cloud/ipfs/
• Backup gateway: https://cloudflare-ipfs.com/ipfs/

Smart Contract Architecture

NFT Contract Features

• Minting with royalty support
• Token URI management
• Enumerable tokens (pagination support)
• Batch minting capability
• Burn functionality

Marketplace Contract

• List NFTs for sale in BugsCoin
• Direct purchase
• Make offers
• Cancel listings
• Transfer ownership
• Marketplace fee (configurable)

Security Features

• ReentrancyGuard on all state-changing functions
• Access control via Ownable
• SafeERC20 for token transfers
• Pausable contract for emergency stops

Project Structure

NFTMARKET/
├── contracts/              # Solidity smart contracts
│   ├── NFT.sol
│   ├── NFTMarketplace.sol
│   ├── IBugsCoin.sol
│   └── governance/
├── test/                   # Contract tests
│   └── marketplace-test.js
├── hardhat.config.js       # Hardhat configuration
└── frontend/               # React application
    ├── src/
    │   ├── components/     # Reusable UI components
    │   ├── pages/          # Route pages
    │   ├── utils/          # Helper functions
    │   ├── config/         # Configuration
    │   └── abis/           # Contract ABIs
    ├── craco.config.js     # Webpack customization
    └── tailwind.config.js  # Tailwind configuration

Development Setup

Prerequisites

• Node.js 16+
• MetaMask or compatible Web3 wallet
• BNB for gas fees (testnet or mainnet)

Smart Contract Development

Install dependencies:

npm install

Compile contracts:

npx hardhat compile

Run tests:

npx hardhat test

Deploy to testnet:

npx hardhat run scripts/deploy.js --network testnet

Frontend Development

Navigate to frontend:

cd frontend
npm install
npm start

Development server runs on http://localhost:3000

Configuration

Environment Variables

Create .env in root:

PRIVATE_KEY=your_private_key
BSCSCAN_API_KEY=your_api_key

Create frontend/.env.production:

REACT_APP_NFT_ADDRESS=0x...
REACT_APP_MARKETPLACE_ADDRESS=0x...
REACT_APP_BUGSCOIN_ADDRESS=0x...
REACT_APP_WALLET_CONNECT_PROJECT_ID=...
REACT_APP_WEB3_STORAGE_TOKEN=...

Network Configuration

Hardhat networks configured in hardhat.config.js:

• hardhat - Local development network
• bnbmainnet - BNB Chain Mainnet (chainId: 56)
• bnbtestnet - BNB Chain Testnet (chainId: 97)

RPC endpoints use environment variables with fallback to public RPCs.

Deployment

Contract Deployment

Deploy all contracts:

npm run deploy:mainnet

This deploys:

1. NFT contract
2. Marketplace contract
3. Sets up initial configuration

Deployment addresses saved to frontend/src/config/contracts.js

Frontend Deployment

Build production bundle:

cd frontend
npm run build

Build output in frontend/build/ ready for:

• Vercel
• Netlify
• IPFS hosting
• Any static host

Production build includes:

• Code obfuscation
• Source map removal
• Tree shaking
• Image optimization

Testing Strategy

Smart Contract Tests

• Unit tests for each contract
• Integration tests for marketplace flows
• Gas optimization tests
• Edge case coverage

Run with coverage:

npx hardhat coverage

Frontend Tests

cd frontend
npm test

Gas Optimization

Contract optimization techniques:

• Packed storage variables
• Uint256 for loop counters
• Batch operations where possible
• Events for historical data
• Minimal storage reads

Average gas costs:

• Mint NFT: ~85k gas
• List for sale: ~55k gas
• Buy NFT: ~75k gas

Security Considerations

• All contracts audited
• No proxy patterns (immutable deployment)
• Rate limiting on frontend
• Input validation at multiple layers
• Protection against common attacks (reentrancy, overflow, etc.)

API Integration

Backend API (not included) should provide:

• NFT metadata caching
• User activity tracking
• Search and filtering
• Price history
• Analytics

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+
• Brave

Mobile browsers supported via WalletConnect.

License

MIT License - See LICENSE file for details