Customize a SeaDrop contract
Extend ERC721SeaDrop with your own functionality and keep it compatible with OpenSea drops.
ERC721SeaDrop is the token contract OpenSea drops mint through. If your drop needs something it doesn't do, inherit it and add your code. A contract that keeps SeaDrop's minting functions works with OpenSea drops like any other.
Start from an extension
The SeaDrop repository has extensions in src/extensions you can deploy as they are or inherit from:
| Extension | What it adds |
|---|---|
| ERC721SeaDropRandomOffset | After the collection mints out, a random offset shifts which metadata file each token shows. Its randomness uses Ethereum's block.prevrandao; do not assume the same behavior on other chains. |
| ERC721SeaDropLockable | Locks that pause trading or make tokens non-transferable for good, with the events in Locked and staked NFTs. |
| ERC721SeaDropAgents | Tokens that are AI agents: an ERC-8004 agent registered for each token, and onchain metadata. See Agent NFTs. |
For an upgradeable contract, start from ERC721SeaDropUpgradeable in src/upgradeable.
Write your own
Clone the repository and install Foundry as the README describes. Add your contract under src/ and inherit ERC721SeaDrop. This example serves metadata files uploaded as 1.json, 2.json, and so on:
// SPDX-License-Identifier: MIT
pragma solidity 0.8.38;
import { ERC721SeaDrop } from "./ERC721SeaDrop.sol";
contract MyToken is ERC721SeaDrop {
constructor(address[] memory allowedSeaDrop)
ERC721SeaDrop("My Token", "MYT", allowedSeaDrop)
{ }
/// @notice The metadata files were uploaded as 1.json, 2.json, and so on.
function tokenURI(uint256 tokenId)
public
view
override
returns (string memory)
{
string memory uri = super.tokenURI(tokenId);
// A base URI that ends in a slash is a directory with a file per
// token. Any other base URI is one file for every token.
bytes memory baseURI = bytes(_baseURI());
if (baseURI.length == 0 || baseURI[baseURI.length - 1] != "/") {
return uri;
}
return string.concat(uri, ".json");
}
}Follow these rules so the contract keeps working with SeaDrop and OpenSea:
- Don't change the minting functions. SeaDrop calls
mintSeaDropand readsgetMintStatsto enforce wallet limits and the max supply, and Studio publishes stages and payouts throughmultiConfigure. Preserve the individual configuration functions too. - Call
superwhen you override_beforeTokenTransfers,isApprovedForAllorsupportsInterface._beforeTokenTransfersruns the transfer validator that enforces creator fees, andisApprovedForAllpreapproves OpenSea's conduit so holders can list without an extra approval. - If your contract locks transfers, emit the events in Locked and staked NFTs so OpenSea stops trading locked tokens. ERC721SeaDropLockable already does.
- When your contract changes what
tokenURIreturns, emit an ERC-4906 event so OpenSea refreshes the metadata. The owner can callemitBatchMetadataUpdate(fromTokenId, toTokenId)for a range of tokens. - Watch the contract size. A contract's code can't be larger than 24,576 bytes, and ERC721SeaDrop already uses about 19,400. Run
forge build --sizesto check.
Test and deploy
The tests in test/foundry show how to set up SeaDrop and mint in a test. Run them, and your own, with forge test.
To deploy, pass SeaDrop's address in allowedSeaDrop so it can mint on your contract:
forge create --rpc-url $RPC_URL --private-key $PRIV_KEY --broadcast src/MyToken.sol:MyToken \
--constructor-args "[0x00005EA00Ac477B1030CE78506496e8C2dE24bf5]"Verify the contract on the block explorer, then set up the drop on OpenSea starting with Part 2: Edit collection settings.
Updated about 23 hours ago