Skip to content
/ nft-marketplace Public

Multi-collection NFT marketplace supporting fixed price listings, English auctions, offers, ERC-2981 royalties, and platform fees.

1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

Enricrypto/nft-marketplace

BranchesTags

Repository files navigation

NFT Marketplace — Multi-Module Trading Protocol

A production-ready, modular NFT marketplace built with Solidity and Foundry, featuring:

  • Fixed-price listings
  • English auctions
  • Cross-collection & token-level offers
  • ERC-2981 royalties
  • Platform fees
  • Full audit-grade safety patterns

Solidity Foundry License: MIT Tests

🌟 Overview

This NFT Marketplace is a modular trading protocol supporting multiple sale types and marketplace operations across any ERC-721 collection.

The system is split into three independent components:

1. NFTMarketplace.sol — Fixed-price listings

2. AuctionHouse.sol — English auctions with auto-extension

3. OffersManager.sol — Global offers system

All modules support:

  • ERC-2981 royalties
  • Platform fees
  • Safe ETH + NFT transfers
  • Custom errors
  • Pausable emergency shutdown
  • CEI & reentrancy-safe execution

🎯 Technical Highlights

Modular Architecture

Each module is isolated for security, upgradeability, and gas efficiency.

Full ERC-721 Compatibility

Works with ANY NFT collection—no per-collection deployment required.

Security-First Engineering

  • Reentrancy guards
  • CEI pattern
  • Pull-payment withdrawal model
  • Strict validation of timestamps, approvals, and payment amounts

Gas Optimization

  • Custom errors
  • Tight storage
  • Reduced SSTORE
  • Minimal overhead in critical flows

Advanced Market Logic

  • Auto-extending English auctions
  • Offers on unlisted NFTs
  • Pull-pattern bid refunds
  • Proper ERC-2981 royalty routing

Perfect for demonstrating:

  • DeFi-grade Solidity engineering
  • Multi-contract marketplace architecture
  • Secure ETH handling & settlement flows
  • Advanced testing patterns

🏗️ Architecture

┌────────────────────────────────────────────────────────────┐
│             NFTMarketplace.sol                              │
│       (Fixed Price Listings - Primary User Path)           │
│  • Create, update, cancel, and purchase listings           │
│  • Fee + royalty distribution                              │
│  • Multi-collection support                                │
└───────────────┬──────────────────────────────┬─────────────┘
                │                              │
     ┌──────────▼────────┐          ┌─────────▼──────────┐
     │   AuctionHouse    │          │   OffersManager    │
     │    (English       │          │  (Global Offers    │
     │    Auctions)      │          │     System)        │
     │  • Bids           │          │  • Make offers     │
     │  • Settlements    │          │  • Accept offers   │
     │  • Time extends   │          │  • Cancel/Refund   │
     └───────────────────┘          └────────────────────┘

🧩 Core Modules

1. NFTMarketplace.sol

  • Fixed-price listings
  • Price updates & cancellations
  • Purchase flow with royalties + fees
  • SafeTransfer + CEI everywhere

2. AuctionHouse.sol

  • English auctions
  • Minimum bid increments (default 5%)
  • Auto-extend (default 15 minutes)
  • Pull-based refund mechanism
  • Settlement with royalties

3. OffersManager.sol

  • Collection-wide or token-specific offers
  • Fully independent from listings
  • Offer updates
  • Automatic refund on cancellation/expiration

🧩 Features

🔹 Fixed-Price Listings

  • Create listing
  • Update price
  • Cancel listing
  • Buy instantly

🔹 English Auctions

  • Create auction
  • Enforce min bid increment
  • Auto-extend near expiry
  • Withdraw outbid bids
  • Settle after expiration

🔹 Offers System

  • Make offers on any NFT (listed or unlisted)
  • Accept offers instantly
  • Update or cancel offers
  • Full pull-pattern refund logic

🔹 Royalties & Fees

Distribution order (OpenSea style):

  1. ERC-2981 royalties
  2. Platform fee
  3. Remainder → seller

⚙️ Default Configuration

Parameter Value
Min Listing Duration 1 hour
Max Listing Duration 180 days
Max Platform Fee 10%
Min Auction Duration 1 hour
Max Auction Duration 30 days
Min Bid Increment 5%
Auction Time Extension 15 minutes
Max Offer Duration 30 days

🔒 Security Features

Implemented Protections

  • Reentrancy Guard on all ETH flows
  • CEI pattern everywhere
  • Pull-payment for all refunds
  • Strict ERC-721 approval checks
  • Pausable emergency mode
  • Custom errors
  • Graceful royalty fallback

Attack Vectors Considered

  • Reentrancy during purchases/bids
  • Wrong ETH refund accounting
  • Auction griefing
  • Timestamp manipulation
  • Royalty overflow
  • Approval swapping
  • Front-running of updates

📁 Project Structure

nft-marketplace/
├── docs/
│   ├── DEPLOYMENT_GUIDE.md
│   └── DEPLOYMENT_QUICK.md
├── script/
│   └── Deploy.s.sol
├── src/
│   ├── NFTMarketplace.sol
│   ├── AuctionHouse.sol
│   ├── OffersManager.sol
│   ├── interfaces/
│   │   ├── INFTMarketplace.sol
│   │   ├── IAuctionHouse.sol
│   │   └── IOffersManager.sol
│   └── libraries/
│       ├── MarketplaceErrors.sol
│       └── MarketplaceTypes.sol
├── test/
│   ├── e2e/
│   │   ├── README.md
│   │   ├── QUICK_REFERENCE.md
│   │   ├── MarketplaceUserFlows.t.sol
│   │   └── MarketplaceEdgeCases.t.sol
│   ├── unit/
│   │   ├── NFTMarketplaceTest.t.sol
│   │   ├── AuctionHouseTest.t.sol
│   │   └── OffersManagerTest.t.sol
│   ├── integration/
│   │   └── MarketplaceIntegrationTest.t.sol
│   └── mocks/
│       └── MockNFT.sol
├── .env
├── .gitignore
└── README.md

🧪 Testing Strategy

✅ Test Results

Status: All tests passing ✅
Total Tests: 140 tests
Success Rate: 100%

Test Coverage by Type

Test Suite Tests Purpose
Unit Tests 90+ Individual contract functions
Integration Tests 20+ Cross-contract interactions
E2E User Flows 10 Realistic user journeys
E2E Edge Cases 13 Boundary conditions
E2E Stress Tests 3 High-load scenarios

E2E Test Scenarios

User Flow Tests (10 scenarios)

  1. ✅ First-Time Buyer Journey - Offer → Accept → Ownership
  2. ✅ NFT Flipper Strategy - Buy Low → Relist High → Profit
  3. ✅ Competitive Auction with Sniping - Multiple bidders, time extensions
  4. ✅ Offer War Scenario - Competing offers, highest wins
  5. ✅ Failed Auction Below Reserve - Reserve not met, NFT returns
  6. ✅ Cross-Platform Strategy - Switch between listing types
  7. ✅ Panic Cancel Scenario - Error recovery (wrong price)
  8. ✅ Long-term Holder Journey - Buy → Hold → Relist → Sell
  9. ✅ Auction Outbid Frustration - Multiple outbids, withdrawals
  10. ✅ Bulk Operations - Collection-wide management

Edge Case Tests (13 scenarios)

  • Expired listing race conditions
  • Offer expires during transaction
  • Multiple time extensions
  • Ownership changes during offers
  • Maximum duration listings (180 days)
  • Minimum bid precision (1 wei bids)
  • Offer update mechanics
  • Zero-bid auctions
  • Price update edge cases
  • Simultaneous operations
  • Large amount handling
  • Late settlements
  • Cancelled offer cleanup

Stress Tests (3 scenarios)

  • 50+ offers on same NFT
  • 20 rapid auction bids
  • Collection-wide operations (20 NFTs)

Test Documentation

For detailed E2E test documentation:

Running Tests

# Run all tests
forge test

# Run with verbosity
forge test -vvv

# Run specific test suite
forge test --match-path "test/unit/*.sol"
forge test --match-path "test/e2e/*.sol"

# Run specific test
forge test --match-test testListNFT

# Run with gas report
forge test --gas-report

# Run E2E tests with console logs
forge test --match-path "test/e2e/*.sol" -vv

# Run coverage
forge coverage

💸 Gas Benchmarks (Production Metrics)

NFT Marketplace (Fixed-Price Listings)

Operation Average Gas Min Gas Max Gas Notes
List NFT 226,930 222,420 242,344 Includes approval check + storage
Buy NFT 135,556 33,212 177,186 With royalty + fee distribution
Cancel Listing 37,142 37,142 37,142 State cleanup
Update Listing 38,408 36,865 39,952 Price/duration changes

Auction House (English Auctions)

Operation Average Gas Min Gas Max Gas Notes
Create Auction 297,566 285,054 325,009 NFT escrow + state setup
Place Bid 67,873 57,145 86,845 Includes refund mechanism
Settle Auction 136,353 64,735 174,532 NFT transfer + payments
Withdraw Pending 31,092 31,092 31,092 Pull-pattern refund

Offers Manager (Buy Offers)

Operation Average Gas Min Gas Max Gas Notes
Make Offer 228,857 208,137 279,349 ETH escrow + tracking
Accept Offer 126,031 33,192 178,679 NFT transfer + distribution
Cancel Offer 41,647 41,647 41,647 Refund + state cleanup
Update Offer 39,674 39,674 39,674 Amount/duration changes

Gas Optimization Highlights

  • ✅ Custom errors save ~50% vs string reverts
  • ✅ Tight storage packing reduces SSTORE costs
  • ✅ Pull-pattern prevents expensive loops
  • ✅ Cached storage reads in hot paths
  • ✅ Minimal external calls per transaction

Deployment Costs

Contract Deployment Cost Deployment Size
NFTMarketplace 1,493,237 gas 6,732 bytes
AuctionHouse 1,698,196 gas 7,680 bytes
OffersManager 1,581,479 gas 7,140 bytes
Total 4,772,912 gas 21,552 bytes

Gas prices based on actual test runs with Foundry gas reporting

📖 Usage Examples

Listing an NFT

nft.approve(address(marketplace), tokenId);

marketplace.listNFT(
    address(nft),
    tokenId,
    1 ether,
    7 days
);

Buying

marketplace.buyNFT{value: 1 ether}(listingId);

Starting an Auction

nft.approve(address(auctionHouse), tokenId);

auctionHouse.createAuction(
    address(nft),
    tokenId,
    0.5 ether,      // starting price
    1 ether,        // reserve price (0 for no reserve)
    block.timestamp,
    7 days,
    500             // 5% minimum bid increment
);

Placing a Bid

auctionHouse.placeBid{value: 0.6 ether}(auctionId);

Making an Offer

offersManager.makeOffer{value: 0.3 ether}(
    address(nft),
    tokenId,
    7 days
);

Accepting an Offer

nft.approve(address(offersManager), tokenId);
offersManager.acceptOffer(offerId);

🚀 Getting Started

Prerequisites

Install

git clone https://github.com/Enricrypto/nft-marketplace.git
cd nft-marketplace
forge install
forge build

Run Tests

# Run all tests
forge test

# Run E2E tests with detailed output
forge test --match-path "test/e2e/*.sol" -vv

# Generate gas report
forge test --gas-report

# Generate coverage report
forge coverage

🚀 Deployment

For detailed deployment instructions, see:

Quick Deploy

# Configure environment
cp .env.example .env
source .env

# Deploy to testnet
forge script script/Deploy.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast --verify

See docs/DEPLOYMENT_GUIDE.md for network-specific instructions.

📍 Deployed Contracts

Sepolia Testnet

All contracts have been deployed and verified on the Sepolia testnet.

All contracts have been deployed and verified on the Sepolia testnet:

🏛️ NFTMarketplace

0xe3A0A6F0B0925a535f7c83fBe680C74E096a8500
➡️ https://sepolia.etherscan.io/address/0xe3A0A6F0B0925a535f7c83fBe680C74E096a8500

🏦 AuctionHouse

0x9107fc30F33811509Ed111d2fD7fCa732d5503E5
➡️ https://sepolia.etherscan.io/address/0x9107fc30F33811509Ed111d2fD7fCa732d5503E5

🎁 OffersManager

0x017b449Ccc3D1Cc3A1aE756627bc318092b298FB
➡️ https://sepolia.etherscan.io/address/0x017b449Ccc3D1Cc3A1aE756627bc318092b298FB

Deployment Details

  • Network: Sepolia Testnet (Chain ID: 11155111)
  • Deployer: 0xd0D211cCEF07598946bB0dF5ECee0bF75cAF3ECC
  • Platform Fee: 2.5% (250 basis points)
  • Fee Recipient: 0xd0D211cCEF07598946bB0dF5ECee0bF75cAF3ECC
  • Deployment Date: December 2, 2024
  • Total Gas Used: 4,772,948 gas
  • Total Cost: 0.000004773 ETH (~$0.009 USD)
  • Status: ✅ Verified on Etherscan

🧪 Interact with the Contracts

Create a Listing

  1. Visit the NFTMarketplace on Etherscan
  2. Connect your wallet
  3. Call listNFT

Start an Auction

  1. Visit the AuctionHouse on Etherscan
  2. Connect your wallet
  3. Call createAuction

Make an Offer

  1. Visit the OffersManager on Etherscan
  2. Connect your wallet
  3. Call makeOffer (send ETH as msg.value)

🟣 Mainnet Deployment

Coming soon after final security audit.

🔧 Configuration (.env)


MAINNET_RPC_URL=
SEPOLIA_RPC_URL=
ETHERSCAN_API_KEY=
PRIVATE_KEY=

FEE_RECIPIENT=0x...
PLATFORM_FEE=250 # 2.5%

📍 Roadmap

Phase 1 — Core Protocol ✓

  • ✅ Fixed price listings
  • ✅ English auctions
  • ✅ Offers system
  • ✅ Royalty + fee architecture
  • ✅ Comprehensive test suite (140 tests)
  • ✅ Gas optimization
  • ✅ Production-ready security patterns

Phase 2 — Advanced Features

  • Batch listings
  • Dutch auctions
  • ERC-1155 support
  • Collection verification
  • Signature-based listings

Phase 3 — Infrastructure

  • Subgraph indexing
  • Frontend SDK
  • API documentation
  • Audit completion

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass: forge test
  5. Submit a pull request

Test Requirements

  • All new features must include unit tests
  • Complex flows should have E2E tests
  • Maintain 100% test pass rate
  • Gas regressions should be justified

📚 Additional Resources

Documentation

Standards

📝 License

MIT

⭐ Acknowledgments

  • ERC-721 + ERC-2981 standards
  • OpenZeppelin contracts
  • Foundry framework
  • Trail of Bits security patterns

📧 Contact

Enricrypto – GitHub

Project Link: https://github.com/Enricrypto/nft-marketplace

🎯 Quick Start Summary

# Clone and setup
git clone https://github.com/Enricrypto/nft-marketplace.git
cd nft-marketplace
forge install

# Build
forge build

# Test
forge test                                      # All tests
forge test --match-path "test/e2e/*.sol" -vv   # E2E tests with logs
forge test --gas-report                         # With gas report

# Deploy locally
anvil                                           # In another terminal
forge script script/Deploy.s.sol --rpc-url http://localhost:8545 --broadcast

Status: Production-ready • Fully tested • Gas-optimized • Security-focused

About

Multi-collection NFT marketplace supporting fixed price listings, English auctions, offers, ERC-2981 royalties, and platform fees.

Topics

ethereum smart-contracts blockchain solidity web3 foundry auctions royalties nft erc721 defi opensea nft-marketplace erc2981

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages