Overview
I built this NFT marketplace to understand Web3 from the contract up. It has an ERC-721 contract, a marketplace contract, an event indexer, a REST and WebSocket backend, and two React front ends: a marketplace for buyers and a dashboard for creators. It runs locally in Docker against a Hardhat network.
Key Features
Smart Contracts
- Batch minting: mint up to 20 NFTs in one transaction
- Royalties: a 2.5% default with per-token royalties, following ERC-2981
- Marketplace contract: listing, buying and cancelling, with a platform fee. It uses OpenZeppelin's ReentrancyGuard.
Marketplace and Creator Tools
- Live activity feed: WebSocket updates for marketplace activity
- Analytics: trading volume, price history per NFT and top traders, charted with Recharts
- IPFS metadata: images and metadata stored through Pinata
- Creator dashboard: minting, royalty settings and sales tracking
Trading Flow
Mint an NFT with its metadata and image, list it at a price, browse and filter the marketplace, buy it with a connected wallet, and see the transfer in the trading history.
What I Tested
The contract tests run with Hardhat, Mocha and Chai: 62 passing tests, 27 for the GameNFT contract and 35 for the Marketplace contract. They cover minting, batch minting, royalties, listing, buying, cancelling and fees, plus access control and the cases where a call should revert.
Beyond the contract tests there are four integration scripts (mint, marketplace, WebSocket and analytics flows) and an end-to-end lifecycle script. They need a running stack and are not part of the 62.
Event Indexing
A listener follows the contract events and writes them to PostgreSQL, so the marketplace can query trades and listings without scanning the chain. Historical events are processed in batches, and new ones are pushed to connected clients over WebSocket.
What I Learned
Writing the contract tests taught me more Solidity than any tutorial did. The edge cases only show up when you try to break your own code, such as a second listing of the same token or a purchase of a token that was never listed.
I also learned how much of a Web3 app sits around the contracts. Indexing, caching and serving the data took more code than the contracts themselves.
Tech Stack
Smart Contracts: Solidity, OpenZeppelin, Hardhat Blockchain: ethers.js, MetaMask integration Backend: Node.js, Express, Socket.IO, PostgreSQL Frontend: React, TypeScript, Recharts Storage: IPFS (Pinata), PostgreSQL Testing: Hardhat, Mocha, Chai Deployment: Docker, local Hardhat network