Decentralizing NFT metadata on OpenSea

An NFT is a unique token with decentralized ownership. The answer to the question “who owns this token?” is stored and tracked on many different computers simultaneously, preventing unauthorized changes to its possession.

But the media attachments and properties associated with NFTs (collectively called “NFT metadata”) have not been consistently decentralized due to the gas costs associated with storing and modifying data directly on smart contracts. Without decentralization, collectors can’t count on the integrity and immutability of a token’s metadata.

OpenSea has supported NFTs with decentralized metadata since we launched in 2017. Today, we’re announcing the ability for creators to decentralize their metadata using the Interplanetary File System (IPFS) and Filecoin when creating on the platform. We’re also providing a way for collectors to see when the metadata for an NFT is immutable or not, further augmenting the toolkit that OpenSea collectors have at their disposal when valuing NFTs.

Keep reading for info on how it all works and why decentralizing metadata matters, and check out our help center tutorial if you want to learn how to decentralize your OpenSea-made NFTs.

Decentralized vs frozen metadata

If you aren’t familiar with NFT metadata, the overview in our ever-popular NFT Bible is worth a read; otherwise, here’s a look at the technical details.

For Ethereum-based tokens, the smart contract that governs an NFT usually specifies the location of the metadata using a function:

  • For the ERC721 standard: function tokenURI(uint256 _tokenId) external view returns (string memory)

  • For the ERC1155 standard:  function uri(uint256 _id) external view returns (string memory)

The value returned by this function is often a URL in Google Cloud, Amazon Web Services, or some other form of centralized storage that can go offline or be mutated by the developer.

This is in contrast with decentralized storage solutions like IPFS, Filecoin and Arweave, which replicate metadata across storage nodes in a decentralized network.

Centralized storage is subject to two weaknesses:

  1. Impermanence: The server can go down or offline, making it hard to find the image (unless it was mirrored by an NFT index like OpenSea).

  2. Mutability: The developer can modify the image to something a collector does not expect.

There are four types of metadata storage for NFTs. Here’s a handy grid:

The concept of “frozenness” is distinct from centralization. Even when they are stored in a decentralized manner, it’s often still possible for the creator to make a transaction and change the metadata associated with an NFT. We call NFTs that have unchangeable metadata “frozen”.

Without better visibility on which NFTs are frozen and which are not, collectors can’t know if what they’re buying will be the same in 1, 10, or 100 years.

Not all NFTs fit cleanly into just one quadrant. Let’s go through them with some examples:

  1. Centralized: Most NFTs have a function on their smart contract to return the metadata associated with a particular token identifier. The result is often a URL on a web server run by the developer (e.g. When the properties and media of an NFT are all controlled by a server like this, the NFT is centralized, and will be subject to impermanence and mutability problems.

  2. Centralized and verifiable: One of the earliest NFTs, CryptoPunks by Larva Labs, stores its images in a centralized server. However, the smart contract stores the hash of this image in the smart contract. This means that while CryptoPunks may be subject to impermanence, any modification to its images can be checked against this hash, so we can “verify” if a CryptoPunk image is original or modified.

    Other projects, like CrypoKitties (API docs), have variations of this system, such as storing NFT traits on-chain but renderings of the traits in a centralized server. In this variation, the images can be modified, but the kitty “genes” and rarity information cannot.

  3. Decentralized: Instead of storing metadata in a central server, developers have the option to store it directly in the smart contract or in a file-friendly decentralized network. Two of the best options are IPFS with Filecoin and Arweave.

    Arweave requires miners to refer to data that was previously stored, similar to a blockchain (called their “blockweave”). IPFS allows peers to store, request, and transfer verifiable data with each other, and can be used with Filecoin to incentivize miners to continue storing data persistently with verifiable proofs.

    An example of this kind of project is Bored Ape Yacht Club. The metadata is stored in IPFS, though the root URI used for IPFS is changeable by the contract owner.

  4. Decentralized and frozen: It’s tricky to know when an NFT’s metadata is frozen or not, as there are usually multiple ways of changing it. This is a manual process, but OpenSea now shows when NFTs made on OpenSea have been frozen and when many NFTs outside of OpenSea are immutable as well:

    Clicking “Frozen” above takes you to the decentralized URI for the item if it’s on a file storage network, supporting IPFS and Arweave (including `ipfs://` and `ar://` URLs).

    Some examples of decentralized and frozen projects include:
    SuperRare (IPFS)
    Sandbox (IPFS)
    Uniswap (on-chain)
    1111 by Kevin Abosch (Arweave)

Note: some projects store their metadata directly in the smart contract. For example, a different project by Larva Labs, Autoglyphs, returns character art directly from the contract, and was the first NFT to do so. It does not depend on any other system aside from Ethereum to render the image, so we call it decentralized, on-chain, and (in this case) frozen.

There are benefits and drawbacks to all four approaches. But it’s helpful for collectors to know more about NFT implementation when making value-based decisions. That’s why we’re introducing a new event type to augment the ERC1155 and ERC721 standards so that developers can tell platforms like OpenSea when they intend to mark a specific NFT as “frozen”.

Permanent URIs

To solve the tension between frozen and unfrozen metadata, this new event will tell OpenSea to register a URI change as a “permanent” one, called PermanentURI. Here’s the event signature:

event PermanentURI(string _value, uint256 indexed _id);

After a PermanentURI event is emitted by an NFT smart contract, no one should be allowed to change the URI for the specific token ID again. More information is available in our docs. Like most standards in crypto, this is an ongoing development and subject to change based on community feedback.

Freezing NFTs on OpenSea

In December 2020, we launched a gas-free NFT creator to drastically reduce the barriers to entry for artists looking to sell their work on the blockchain. At the time, we added pre-emptive support for metadata freezing to the smart contract, meaning creators can now freeze the metadata for any unsold tokens in collections they’ve made over the last six months.

To get started, head to your collection’s “Edit” page and press the pencil icon in the top right corner of one of your NFTs (you can find them under the search bar below the “Add New Item” button). Click the Freeze Metadata toggle, and you’ll see a window pop up, as shown below. Tick the box if you’re happy to proceed, then click Submit Transaction. While OpenSea doesn’t charge anything, you’ll need to pay a gas fee to save the new metadata URL to the smart contract:

Once you freeze an NFT, you cannot unfreeze it or change its metadata. It will be available for as long as Ethereum and Filecoin exist.

After you’ve frozen an NFT, you can view its IPFS URL directly from its OpenSea page. You can also view more information about how many Filecoin deals have been made for it using the NFT.Storage API in combination with your NFT’s IPFS content hash. For example:

The Future of Decentralized Metadata

One of OpenSea’s missions is to provide a source of truth for any NFT, regardless of the blockchain, metadata format, or decentralized storage solution used to implement it. The future is going to be chaotic, and there will be many ways to create NFTs. We’re excited to bring more transparency to it.

Gas-Free Freezing

For the last six months, we’ve been excitedly launching support for the Polygon sidechain to provide users with a gas-free experience on OpenSea. For those with access to the private beta NFT minter, you can now freeze your Polygon NFTs to IPFS and Filecoin as well.

Just like with Polygon trading, there is no associated gas cost to save the IPFS URI to the NFT’s smart contract – OpenSea will pay it for you. Stay tuned for the larger release soon, and let us know what you think on Discord!

P.S. If you’re passionate about the nuances in NFT metadata, we’re hiring. Be sure to check out our open positions:

The featured image used for this article is part of the Art Blocks collection and is called Subscapes #638. It was created by Matt DesLauriers