thirdweb Contracts

The Drop smart contracts are distribution mechanisms designed for releasing tokens to an audience under specific restrictions. They support three token standards:

• DropERC20: For distributing ERC20 tokens.
• DropERC721: For distributing ERC721 (NFT) tokens.
• DropERC1155: For distributing ERC1155 (Multi-token) tokens.

These contracts are specifically intended for scenarios where a contract admin pre-determines the tokens to be minted and wants to control how an audience claims them (e.g., via allowlists or specific payment requirements).

Pre-built contracts are audited, ready-to-deploy smart contracts written by the thirdweb team for common use cases. Available contracts include:

• Drops: DropERC20, DropERC721, DropERC1155, SignatureDrop
• Tokens: TokenERC20, TokenERC721, TokenERC1155
• Other: Marketplace, Multiwrap, VoteERC20, Split

These can be deployed via the thirdweb SDK, dashboard, or CLI.

An allowlist (provided via merkleRoot) acts as an override for specific addresses. For addresses included in the allowlist, an admin can specify different values for:

• Quantity limit
• Price
• Currency

If a value is not specified in the allowlist, the address falls back to the general ClaimCondition parameters.

Note on Currency: A currency override is only applied if a price override is also set.

CRITICAL LIMITATION: An address must not appear more than once in the same Merkle tree. If you attempt to list the same address multiple times with different parameters (e.g., different prices or quantities), the behavior is undefined and may prevent the user from claiming the intended total amount.

The Drop mechanism is implemented across three different token standards, with key differences in how claim conditions are managed:

Note on NFT Minting: DropERC721 and DropERC1155 use 'lazy minting', meaning the NFT content is defined by the contract before users claim them during a condition.

The Marketplace contract is a unified smart contract that manages both Direct Listings and Auction Listings. It uses shared data structures and functions to handle both types to optimize code size and maintain consistency.

Listing Comparison

Offers and Bids

Both Offers (to direct listings) and Bids (to auctions) share the same conceptual parameters:

• Offeror: The account making the offer.
• Quantity: The amount wanted from the listing.
• Total Amount: The total value of the offer/bid.
• Currency: The currency used for the offer/bid.

The Multiwrap contract allows you to bundle multiple assets (ERC20, ERC721, or ERC1155) into a single wrapped ERC721 NFT.

The Lifecycle

1. Wrapping: You escrow your existing tokens into the Multiwrap contract. In exchange, you receive a single wrapped ERC721 NFT. You can specify a recipient for this NFT and set its metadata URI during the process.
2. Holding/Trading: The resulting wrapped NFT can be transferred, sold on NFT marketplaces, or used as collateral in DeFi protocols.
3. Unwrapping: The wrapped NFT is burned, and the underlying assets are released to a specified recipient.

This pattern is useful for applications that need to transact over multiple independent tokens as a single asset, such as bundling an NFT with ETH for collateralized lending.

Signature minting is a mechanism that allows a contract admin to authorize an external party to mint tokens on their behalf. Instead of the admin performing the minting directly, the admin signs a MintRequest (a payload) containing specific minting parameters. An external party (like a web application) can then present this signed payload to the smart contract to trigger the minting process.

This is particularly useful for dynamic minting scenarios, such as generating a unique NFT certificate for a user where the metadata (like the user's name) is only known at the time of the request.

A core concept of the Drop contracts is the use of phases and claim conditions.

• Phases: These are specific periods of time during which a distribution occurs.
• Claim Conditions: Within each phase, the contract creator can specify multiple restrictions on how tokens are claimed.

Common use cases for claim conditions include:

• Allowlists: Restricting minting to only specific addresses.
• Payment Requirements: Requiring minters to pay a specific amount of a specific currency (e.g., _x_ amount of price in _y_ currency) to mint tokens.

Auctions are 'high commitment' English auctions. Unlike direct listings, both the NFTs and the winning bid amounts are escrowed in the Marketplace contract for the duration of the auction.

Fairness Mechanisms (Buffers):

1. Time Buffer: (Default: 900s) If a bid is made within this window of the closing time, the auction end time is extended by the buffer to prevent last-second sniping.
2. Bid Buffer: (Default: 5%) A new bid must be at least this percentage higher than the previous winning bid to be valid. This prevents insignificant incremental bidding.

Note on Gas: When a new winning bid is made, the Marketplace automatically refunds the previous bidder. The new winning bidder pays the gas for this refund to ensure a better user experience (single-action bidding).

Marketplace V3 is designed using a Plugin Pattern (influenced by EIP-2535) to overcome smart contract size limits and improve developer experience. Instead of a single monolithic contract, it is composed of three independent, modular extensions. This modularity allows for explicit functions and convenient view functions for each specific marketplace behavior.

The three core extensions are:

1. DirectListings: Used to list NFTs for sale at a fixed price and to buy NFTs from those listings.
2. EnglishAuctions: Used to put NFTs up for auction and to place bids. The highest bidder within the auction duration wins.
3. Offers: Used to make offers of ERC20 or native token currency for NFTs (whether listed or unlisted). Sellers can then accept these offers.

Each extension is independent and does not rely on the state of the others.

Direct listings allow NFT owners to sell ERC721 or ERC1155 tokens at a fixed price. This is a 'low commitment' model: NFTs are not escrowed in the contract, allowing sellers to keep their assets liquid and list them on multiple marketplaces simultaneously. To list, the owner must approve the Marketplace to transfer the tokens.

Key Features:

• Fixed Price: Buyers can purchase immediately at the buyoutPricePerToken.
• Offers: Buyers can make custom offers (different price or currency). Offers are not escrowed; instead, the buyer approves the Marketplace to transfer the offer amount if the lister accepts.
• Liquidity: Since assets aren't escrowed, sellers retain control until a sale is executed.