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:

ExtensionWhat it adds
ERC721SeaDropRandomOffsetAfter 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.
ERC721SeaDropLockableLocks that pause trading or make tokens non-transferable for good, with the events in Locked and staked NFTs.
ERC721SeaDropAgentsTokens 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 mintSeaDrop and reads getMintStats to enforce wallet limits and the max supply, and Studio publishes stages and payouts through multiConfigure. Preserve the individual configuration functions too.
  • Call super when you override _beforeTokenTransfers, isApprovedForAll or supportsInterface. _beforeTokenTransfers runs the transfer validator that enforces creator fees, and isApprovedForAll preapproves 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 tokenURI returns, emit an ERC-4906 event so OpenSea refreshes the metadata. The owner can call emitBatchMetadataUpdate(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 --sizes to 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.