NFT Marketplace Architecture: Onchain Settlement and Discovery Layer Design

Web3 marketplaces combine onchain settlement primitives with offchain indexing and discovery. Unlike centralized platforms, they split custody (always user retained), order propagation (mostly offchain), and settlement (fully onchain) into discrete components. This architecture creates specific trade-offs around liquidity fragmentation, MEV exposure, and metadata reliability that centralized equivalents do not face. This article walks through the core mechanics, the interplay between order book and aggregation layers, and the operational details practitioners need when integrating or building marketplace infrastructure.

Order Representation and Execution Models

NFT marketplaces implement three primary order types: onchain order books, offchain signed orders with onchain settlement, and bonding curve based instant liquidity pools.

Onchain order books store bid and ask data directly in contract state. Every order placement costs gas. Cancellations cost gas. This model offers full transparency and composability but becomes prohibitively expensive during high activity periods. Protocols using this model typically see order density collapse when gas exceeds single digit gwei.

Offchain signed orders dominate production marketplaces. A seller signs an EIP-712 structured message containing the NFT contract address, token ID, price, expiration timestamp, and accepted payment token. The signature proves intent without requiring an onchain transaction. The order propagates through a centralized API or gossip network. Settlement occurs onchain only when a buyer calls the marketplace contract, submits the signed order, and transfers payment. The contract verifies the signature, checks expiration and ownership, then executes the atomic swap. This model reduces gas overhead but introduces reliance on offchain infrastructure for order discovery.

Bonding curve pools like sudoswap deploy a contract that holds multiple NFTs from a collection and quotes prices algorithmically based on a mathematical curve. Buyers and sellers trade against the pool’s inventory. The curve adjusts prices as inventory changes. This provides instant liquidity but limits pool creation to collections with sufficient fungibility expectations.

Aggregation Layers and Liquidity Routing

Marketplace aggregators query multiple order sources, compare prices, and route transactions to the best available execution venue. The aggregator contract typically implements a multi-call pattern: it accepts an array of calls targeting different marketplace contracts, executes them atomically, and returns any unsold asset to the caller if a fill fails.

This introduces two edge cases. First, order staleness: an aggregator displays an order from marketplace A that has already been filled directly on marketplace A moments earlier. The aggregator transaction reverts, wasting gas. Second, partial fills across heterogeneous protocols require fallback logic. If an aggregator attempts to buy three NFTs from three different marketplaces and the second call reverts, the contract must decide whether to complete the other two purchases or revert the entire transaction. Most production aggregators revert entirely to maintain atomicity, but this reduces effective fill rates when routing across many sources.

Aggregators also surface royalty enforcement discrepancies. Some marketplaces honor creator royalties onchain by checking an external registry and transferring the royalty percentage before completing the sale. Others ignore royalties entirely. Aggregators must either normalize this (by adding royalty transfers when the originating marketplace omits them) or pass the heterogeneity downstream to the user interface.

Metadata Availability and IPFS Pinning

NFT metadata typically lives offchain, referenced by a URI stored in the token contract. Most projects use IPFS content addressing (ipfs://Qm…). The marketplace must fetch and cache this metadata to display images, traits, and names in the user interface.

Metadata availability directly impacts marketplace utility. If the IPFS hash is not pinned by any accessible node, the marketplace cannot display the asset. Centralized marketplaces run their own IPFS gateways and proactively pin metadata for indexed collections. Decentralized marketplaces rely on public gateways or require users to supply metadata externally.

Metadata mutability presents a subtler risk. Some contracts use ipfs:// URIs but allow the contract owner to update the base URI. Others use centralized https:// endpoints. Marketplaces cannot reliably surface this distinction in the interface, so buyers assume immutability that may not exist. Checking the token URI function implementation and verifying IPFS content addressing is the only reliable confirmation.

Royalty Enforcement Mechanisms

Onchain royalty enforcement fragmented after marketplace competition eroded voluntary compliance in 2022 and 2023. Projects now implement operator filtering at the contract level using registries like the Operator Filter Registry. The NFT contract maintains a list of banned marketplace addresses. Any transfer initiated by a banned marketplace reverts. This forces secondary sales through compliant marketplaces that honor royalties.

The registry introduces centralization and maintenance overhead. Projects must manually update the ban list as new marketplaces launch. The registry itself is controlled by a multisig. Marketplaces can evade filtering by routing transfers through unfiltered proxy contracts, creating an ongoing arms race.

Some projects embed royalty logic directly into transfer hooks (ERC-2981 reporting combined with transfer validation). The contract checks whether the caller has paid the required royalty to a designated address before allowing the transfer. This approach eliminates reliance on external registries but increases gas costs and reduces composability with protocols that perform complex multi-step transfers.

Worked Example: Offchain Order Settlement Flow

A seller owns token ID 1234 from contract 0xNFT. They want to sell for 2 ETH. The seller calls the marketplace frontend, which constructs an EIP-712 message:

{
nftContract: 0xNFT,
tokenId: 1234,
price: 2000000000000000000,
paymentToken: 0x0 (ETH),
expiration: 1735689600,
seller: 0xSeller
}

The seller signs this message with their wallet. The signature and order details are sent to the marketplace API, which indexes the order in a database. The API exposes the order via REST or GraphQL endpoints.

A buyer queries the API, sees the listing, and submits a transaction to the marketplace contract’s fulfillOrder function with the order details and signature. The contract performs the following checks:

1. Verify the signature matches the seller address
2. Confirm the current block timestamp is before expiration
3. Check that 0xSeller still owns token 1234 at contract 0xNFT
4. Verify the marketplace contract has approval to transfer the token (either via setApprovalForAll or token level approval)

If all checks pass, the contract transfers 2 ETH from the buyer to the seller (minus marketplace fee, typically 0.5 to 2.5 percent) and transfers the NFT from seller to buyer in a single atomic transaction. If any check fails, the transaction reverts and no state changes occur.

Common Mistakes and Misconfigurations

• Approving individual tokens instead of setApprovalForAll: Listings fail because the marketplace contract lacks transfer rights. Use setApprovalForAll for the marketplace contract address, not per token approvals.
• Ignoring order expiration on the client side: Displaying expired orders wastes user gas when they attempt to fill. Index expiration timestamps and filter client side before presenting orders.
• Assuming metadata immutability without verification: Check the tokenURI implementation. If it uses a mutable base URI or centralized server, the displayed metadata may not match future state.
• Failing to simulate aggregator calls before submission: Aggregators route through multiple contracts. Simulate the transaction with a service like Tenderly to identify which sub-call will revert before spending gas onchain.
• Not accounting for royalty variance across execution venues: An aggregator may route to a zero royalty marketplace even if the user expects royalties to be paid. Check the aggregator’s royalty policy and destination marketplace before executing.
• Using stale allowance checks: A seller may have revoked marketplace approval after listing. Always verify current approval state immediately before settlement, not at listing time.

What to Verify Before You Rely on This

• Current marketplace contract addresses and whether they have been upgraded or deprecated
• Whether the NFT collection implements operator filtering and which marketplaces are currently banned
• The marketplace fee structure (percentage, flat fee, dynamic fee based on sale price)
• Whether the marketplace supports ERC-1155 or only ERC-721 if you are trading multi-edition tokens
• The specific EIP-712 domain separator and type hash the marketplace uses for signature verification
• Whether the aggregator you are using normalizes royalty payments or passes through the behavior of each underlying marketplace
• The metadata URI scheme (IPFS, IPFS via HTTP gateway, centralized server) and whether the contract owner can mutate it
• Gas behavior of the marketplace contract, particularly for batch operations or bundle sales
• Whether the marketplace API indexes all orders or only featured collections
• The marketplace’s policy on order cancellation (onchain cancellation transaction required or offchain invalidation supported)

Next Steps

• Deploy a local fork and simulate order creation, signature generation, and fulfillment against a production marketplace contract to understand the exact calldata structure and gas costs
• Index marketplace contract events (OrderFilled, OrderCancelled) for collections you track to build your own order book state and detect arbitrage opportunities before aggregator frontends surface them
• Integrate an operator filter registry check into any contract that will programmatically transfer NFTs to ensure transfers are not unexpectedly blocked by collection level bans

Category: NFTs & Web3 Markets