Mezo veNFT Marketplace

An escrowless, peer-to-peer secondary marketplace for trading veBTC and veMEZO vote-escrowed NFTs on the Mezo Network. Sellers retain full custody until atomic purchase.

---

Table of Contents

1. Overview
2. Architecture
3. Contract Addresses
4. Quick Start
5. Deployment Guide
6. Environment Variables
7. Security & Audit Diff
8. Bounty Compliance
9. Maintenance Plan

---

Overview

The Mezo veNFT Marketplace provides a secondary liquidity layer for locked Bitcoin and MEZO governance positions. Users can:

• List veBTC and veMEZO positions for sale at any price in BTC, MEZO, or MUSD
• Browse all active listings with real-time intrinsic value, voting power, lock expiry, and discount percentage
• Buy listed positions with a single atomic transaction — NFT and payment swap simultaneously
• Bid — make an offer on any veNFT; the owner accepts it on-chain. Your funds stay in your wallet (only an approval is held) until a bid is accepted
• Pay in any token — buy a listing priced in one currency using another; the swap routes automatically through Mezo's Velodrome DEX
• Cancel listings at any time with no penalty
• View full position details: locked amount, voting weight (with decay), time remaining, price-to-value ratio

Key Design Properties

Property	Detail
Escrowless	NFT stays in seller's wallet until purchase — no custodial risk
Atomic swap	NFT transfer happens before payment — buyer cannot lose funds if NFT moved
Multi-token	Native BTC, MEZO governance token, MUSD stablecoin
Protocol fee	Default 2%, hardcapped at 5%, 48-hour timelock on changes
Emergency pause	Admin can halt marketplace instantly

---

Architecture

Four modular smart contracts — adapted from the OpenXSwap audited pattern for Mezo's dual-token system:

Contract	Role	Source
VeNFTMarketplace	Core listing and trading logic	contracts/core/VeNFTMarketplace.sol
MezoVeNFTAdapter	Read-only veNFT value queries (locked amount, decay, voting power)	contracts/adapters/MezoVeNFTAdapter.sol
PaymentRouter	BTC/MEZO/MUSD payment routing with fee split	contracts/core/PaymentRouter.sol
MarketplaceAdmin	Governance, emergency pause, timelocked fee management	contracts/core/MarketplaceAdmin.sol

v2 Modules

Additive contracts deployed on top of the core marketplace (the core is unchanged):

Contract	Role	Mainnet
VeNFTBidding	On-chain offers/bids — escrowless; acceptBid settles the fee split directly	0xef35dc538b50549e95687a51e8aa542D485ea384
SwapPaymentRouter	Pay-with-any-token — swaps via Mezo's Velodrome DEX, then buyNFT	0x638Bab65738bA7BcD47D3c1d6Cb4eaf6CC872617

Bidding flow: bidder approves the bidding contract → createBid (funds stay in wallet) → the NFT owner calls acceptBid, which atomically transfers the NFT and pulls payment, routing the protocol fee to the treasury. No escrow.

Swap flow: buyer calls swapAndBuy → the router swaps their token → the listing's quote token through the Velodrome BTC/MUSD pool (pool-direct, no oracle), then calls the marketplace's buyNFT and forwards the NFT. Single transaction. (MEZO has no DEX pool, so MEZO-priced listings are paid in MEZO directly.)

Listings & activity are served by a Goldsky subgraph indexer (subgraph/) when SUBGRAPH_URL is configured, with an automatic on-chain fallback.

Deployment Order

1. MezoVeNFTAdapter(veBTC, veMEZO)
2. PaymentRouter(feeRecipient, admin, MUSD, feeBps)
3. MarketplaceAdmin(admin, isTestnet)
4. VeNFTMarketplace(adapter, router, admin)
5. router.setMarketplace(marketplace)    ← security: restrict routePayment caller (one-time)
6. admin.setPaymentRouter(router)        ← governance: link fee control
7. router.transferAdmin(adminContract)   ← propose admin transfer to MarketplaceAdmin
8. admin.acceptRouterAdmin()             ← accept: enforce 48h timelock on fee changes

---

Contract Addresses

Mezo Testnet (Chain ID: 31611)

Contract	Address
BTC (native)	0x7b7c000000000000000000000000000000000000
MEZO	0x7b7c000000000000000000000000000000000001
MUSD	0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503
veBTC (ERC-721)	0x38E35d92E6Bfc6787272A62345856B13eA12130a
veMEZO (ERC-721)	0xaCE816CA2bcc9b12C59799dcC5A959Fb9b98111b
VeNFTMarketplace	0xF18016FbadfA732c58814b6341054484FcDBF26f
MezoVeNFTAdapter	0x526A542F7B2809376391CD7f884Daf4967fFEb14
PaymentRouter	0x157ed850E41e0f220549005da8b55bBE2AE32d7D
MarketplaceAdmin	0xdBBc692828866ab0ee8BC8C2e6B7d911F7B89Ed4
RPC	https://rpc.test.mezo.org
Explorer	https://explorer.test.mezo.org
Faucet	https://faucet.test.mezo.org

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗