Using IPFS Distributed File Storage for Game Asset Metadata
Overview
Non-fungible tokens represent a new, innovative way to own, preserve, and distribute digital property. The concept of digital property is foreign for many people, but gamers understand this concept intuitively: gamers spend hundreds to thousands of hours playing video games each year, pouring in countless effort to earn rare items, and calling those rewards ours. This notion of ownership is even stronger for gamers who’ve played trading card games like Magic: The Gathering, or those who have clocked a measly few thousand hours in World of Warcraft.
Blockchain gaming is a natural next step in the evolution of video games. Combining real world ownership of gaming assets with modern massive multiplayer online games just makes sense. It’s a big part of the reason why The Matrix and Ready Player One resonate so strongly with modern gamers: the digital world is as real as anything tangible, and ownership of identity and property is a part of that.
The logistics of providing long-lasting digital assets is a bit more involved than it seems at face value. First, for an asset to be truly decentralized, with verifiable ownership, a record of the asset should exist on a public blockchain, such as Ethereum. In theory, this would be enough: all information relevant to the ownership and the identity of the asset can exist on-chain. In reality, storing more information than absolutely necessary can be prohibitively expensive — especially as many game assets can have multiple images or 3D models, sound files, pages of lore, and so forth.
There is a way to link the asset directly to all of the associated metadata off-chain, but many current implementations reference centralized services, such as Amazon Web Services, Google Cloud, or Heroku. In the event that any of these sources go offline or get shut down, the assets that should be inextricably linked to the NFT are missing.
The good news is that there is a way to resolve this problem: store all of the metadata in a decentralized, distributed file system. IPFS, or InterPlanetary File System, is such a system intended to store large files across multiple sources around the world, and in the process relinquish direct control over the asset files in favor of providing them for the public to host, support, and use. It’s significantly cheaper and more effective at storing and providing decentralized assets, and it’s the natural progression for NFTs to have substantial data without adding weight and cost to public blockchains.
Written & researched by Cr0wn_Gh0ul.
IPFS OVERVIEW
IPFS is “a peer-to-peer hypermedia protocol designed to make the web faster, safer, and more open”. Put simply, it’s a P2P file-sharing network. If you are not familiar with this type of system you can find more information on how it works here.
For an example, take the file ‘cr0wngh0ul.gif’. If I store it on my server and want to share it with people, they can access it here. However, if my website gets shut down because I didn’t pay the AWS bill (oops!) or accidentally erased all my storage, then nobody would be able to access this file anymore.
Luckily, I also uploaded my storage to IPFS. When I pin ‘cr0wngh0ul.gif’ to IPFS it gets the following content identifier (also called a CID):
QmYcwpKrv5icSDDDx9Jc4QA9y369WYkeZh13fTGYW5ArBo
A CID is a cryptographic hash of the file contents which is also how it’s identified on the network. If the file changes, even the slightest bit, the CID will be completely different. So if anyone claims that the CID of my file is C0ffEeKrv5icSDDDx9Jc4QA9y369WYkeZh13fTGYW5ArBo, we will know it isn’t the actual file. Now that you have the CID for my file and you know it is authentic, you can either use an IPFS client or a public gateway to view and save the file locally.
A client will connect to peers on the network, allowing you to access files. A gateway allows access to IPFS files over HTTP from a single IPFS server. If my server is still up and running you can view the file through my IPFS gateway: https://ipfs.cr0wngh0ul.org/ipfs/QmYcwpKrv5icSDDDx9Jc4QA9y369WYkeZh13fTGYW5ArBo
Although, if my server is offline, thanks to P2P we can view it through other gateways such as Infura or IPFS.io.
https://ipfs.infura.io/ipfs/QmYcwpKrv5icSDDDx9Jc4QA9y369WYkeZh13fTGYW5ArBo
https://gateway.ipfs.io/ipfs/QmYcwpKrv5icSDDDx9Jc4QA9y369WYkeZh13fTGYW5ArBo
IPNS OVERVIEW
If we have a text file named “hello.txt” and it contains “Hello World!” we will already know it will have a unique CID and can be accessed at /ipfs/<CID>. Now let’s say we want to update that file to say “Good night, Moon!”. We will now have a new completely new CID and /ipfs/<OLD CID> will read “Hello World!” and /ipfs/<NEW CID> will read “Good night, Moon!”.
If we have a directory filled with files we want on IPFS. We can add the entire directory and access it at /ipfs/<DIRECTORY CID>/ and the individual files at /ipfs/<DIRECTORY CID>/<FILENAME or FILE CID>. However, if we want to add another file, the directory CID will change. That means we will have to let everything that uses this directory know the new CID in order to have the latest version.
This is where IPNS comes in. We can create a CID (using our Peer ID or a new key) and publish /ipfs/<CID> to it as /ipns/<STATIC CID>. This is very useful if you have a website or a directory which may add or remove files. If you add your site to IPFS and it becomes /ipfs/<ORIGINAL WEBSITE CID> and later want to update the site, you will have a new /ipfs/<NEW WEBSITE CID> for every update, and that may confuse a lot of people trying to view the latest version of the site.
The same is true for directory filled with our files. When we add or remove files, we will have a new /ipfs/<DIRECTORY CID> and have to update any services that may rely on it to stay up-to-date. When we update our website or directory and get a new CID, we can publish that CID to IPNS and access it at the same /ipns/<IPNS CID> every time. This is basically the same concept as DNS. If our server gets a new IP address we don’t have to get a new domain name, we simply change the DNS record to point to the new IP address.
NFT (ERC-721)
NFTs are non-fungible tokens on the Ethereum blockchain. The most popular contract standard for representing NFTs is the ERC-721 standard. One of the great things about NFTs is the ability to set a metadata URI for the token to give it unique attributes. Storing metadata information directly on the blockchain would be costly, so we store the metadata on external sources.
In our case, metadata is stored in a JSON file, which lists attributes such as name, description, image, traits, etc. This metadata can be reused by multiple tokens or can be different for each one. If somebody wants to view the metadata for a token, they will call the contract and get the metadata URI for the token, for example http://madeupwebsite.example/256.json, which is stored in a traditional system such as AWS S3, Google Cloud, etc. Next, they read the JSON file to get all the information for that token.
Metadata Problem
What happens if the company or person that minted your super awesome NFT disappears and their hosting provider shuts the service off, or a malicious hacker erases all the metadata on the system? Not you, nor the crypto gods, will be able to save the metadata attached to your NFT. This is a fundamental problem with having a single centralized source for metadata files. On the contrary, decentralized and distributed file storage provides increased security, redundancy, and immutability to your game assets, creating more sovereign identities for your digital property.
IPFS / IPNS Metadata
IPFS is here to save the day. Now we can save the metadata URL as just /IPNS/<CID>/<TOKEN_ID> instead of a url and access it across multiple different gateways. If we decide to add more metadata to the directory which is storing our files, then we need to only publish the directories new CID to the IPNS and our contract metadataURI will still point it to the correct location.
Integrity of the metadata is kept intact because the IPFS CID of the metadata is a cryptographic, verifiable hash of the contents inside the file. This ensures that the metadata we get from a peer is a legitimate unaltered copy of the file.
Persistence of the metadata is maintained because we can always access the metadata through different peer gateways. If one peer gateway is unreachable we can access it through another peer gateway.
So now our metadata is immutable, distributed, and we can access it through multiple sources at a static IPNS address. Yay!!
By combining NFTs and IPFS we can get a distributed and cryptographically secure metadata system. We can create, own, and trade unique tokens on the ethereum blockchain that store a IPFS CID hash and then we can lookup the IPFS CID through a gateway to reliably and securely retrieve metadata, which would be otherwise too costly (and not to mention wasteful) to store on the blockchain.
NFT IPFS / IPNS EXAMPLE
Overview: This is an NFT which has an IPNS metadata URL. The metadata file follows the ERC-721 Metadata standard, and modified slightly to fit the OpenSea metadata standard. Essentially each NFT token is holding the information of different IPFS files which can be viewed and shared by others.
App
The web app is a simple form which creates an API call to our IPFS server.
- Fill out the form with the asset information.
- Choose an image to upload for the asset.
- Submit the form.
It’s that easy.
When the server receives the request it performs the following:
- Pins the image to IPFS
- Turn the asset information, including the images new ipfs CID, into metadata.
- Pins the metadata to IPFS.
- Mints a new token.
If we use the Neon District “Season Zero: Baus” as an example, we simply fill out the form upload a GIF of the Baus. The server pins the GIF to IPFS which has the CID QmNf7…Csjf8 Then it creates and pins the metadata to IPFS which has the CID QmYF1…YsFej.
Note: CIDs abbreviated for clarity.
Next the server generates a new hash for its storage directory and publishes it to IPNS as the servers PeerID which is /ipns/QmVc5…W7y3v. Now the files can be accessed directly through their IPFS CID such as:
https://ipfs.io/ipfs/QmNf7vFHpUowAQEDMfGcGDjFyQapubnFfXEjFFC8uCsjf8
Or through the IPNS which is set in the contract as the token’s metadata URL.
