All field notes

Architecture · Retrospective

Moving our NFT images to NFT.Storage: what a content address guarantees

A blank signpost pointing at a glass cube that holds a picture card.
Concept illustration · AI-generated

On 1 September I wrote up a change to Playermon's NFTs for our Medium publication: their content is now served through NFT.Storage, which keeps data on IPFS and on Filecoin, and the images have been upgraded to higher definition with a background for each rarity. This is the longer reasoning behind the move.

What an NFT actually holds

A Playermon is an NFT on Polygon. Like most NFTs, what the chain holds is small: a token number, its owner, and a way to find a metadata file. Everything a person sees, the picture, the name, the traits a marketplace displays, lives in that file or in files it points to.

The contract guarantees who owns a given token. It guarantees nothing about the file at the end of the link unless the link itself does.

An ordinary web address does not. It names a server and a path. The server can go down, the path can start returning a 404, and the file at that path can be replaced with a different one while the address stays the same. For a game meant to run for years, an NFT whose image depends on one company's server staying up is weaker than the ownership record it is attached to.

What content addressing adds

IPFS names a file by its content. The identifier, a CID, is derived from the file's bytes, so an ipfs:// link points to exactly that data and nothing else. Anyone can fetch it from any node that has a copy, and anyone can check that what they received matches the identifier.

Our NFTs were already on IPFS before this month, pinned through Pinata and through an IPFS node we hosted ourselves. What NFT.Storage changes is who keeps the copies. It stores data on dedicated IPFS servers and on Filecoin, where storage providers have to keep proving they still hold the data to earn rewards, and are penalised if they cannot. That moves availability away from a machine we run and a single pinning service.

What a CID does not guarantee

Content addressing is precise about one property, integrity. It is easy to read more into it than that.

It does not keep a file online. A CID that nobody pins is a correct name for something nobody can fetch. That gap is what NFT.Storage's servers and Filecoin's storage proofs are there to cover, and it is why the move matters even though our files were already on IPFS.

It does not make the picture permanent. The upgrade itself shows this. A higher-definition image is a different file, so it has a different CID. Every new image needed a new identifier, and whatever points each token to its metadata had to be pointed at the new files. A CID tells you that the file you received is the one named. It does not tell you that the name will never be swapped for another. That decision sits with whoever controls the pointer, and holders are entitled to ask who that is.

It does not update every copy at once. Marketplaces cache metadata and images. OpenSea will keep showing the old picture until it fetches again, so the post asked holders to press "Refresh Metadata" on the item page if their Playermon still looked the same.

Why rarity went into the picture

The visible half of the change is the backgrounds. Each rarity tier, common, uncommon, rare, epic and legendary, now has its own background, so a collector can tell a Playermon's rarity at a glance without opening each one on our website.

It is a design decision with an architectural reason behind it. Information that only our website shows is information a holder has to trust our website for. Putting rarity into the image puts it into the file the CID protects, and it travels wherever the image is shown.

The rest of the month

Ethereum moved to proof of stake on 15 September. It changed how that chain agrees on blocks. It did not change where any NFT's picture is kept, on Ethereum or on Polygon. The token and the file it points to are separate systems, and each needs its own answer to the question of who keeps it running.

Inside the game, September ended with the Anchorland alpha test concluded and its rewards announced, with a BETA season to follow. The storage work is quieter than either of those, but it is the part a holder relies on every time they open their collection.