Upgradeable NFT metadata is a powerful feature that allows NFT creators and projects to modify the metadata associated with their tokens after minting. This metadata might be an image, video, gif, or object linking to any number of variable attributes. If this metadata can change over time, it can open up a world of new possibilities for dynamic, evolving NFTs that can evolve intelligently in response to specific events.
We’re going to guide you through step-by-step the process for setting up your development environment, then writing and deploying a simple ERC721 smart contract that will allow its owner to modify the tokenURI and subsequent metadata associated with the token. The NFT use case here will be a series of powerup NFTs that have attributes that can be modified. The resulting image will be different, reflecting the updated metadata attributes.
We'll need the following dependencies to get started:
1. Create a new TypeScript project
Ensure Yarn Package Manager is installed globally:
Command Line:
Now lets install some of the core dependencies via the command line:
2. Install Foundry and Run the Setup
Follow the CLI prompts carefully. If you run into any installation issues, see Foundry’s FAQs.
Now, Foundry is installed. We’ll also need to configure the foundry.toml file to connect to the Sepolia testnet and add OpenZeppelin dependencies. Create a "foundry.toml" file in the root of the directory if it wasn't created already, and specify our RPC endpoint.
foundry.toml:
We'll use OpenZeppelin's upgradeable contracts library for this example.
3. Metadata Hosting: Pinata Cloud
Before we create the metadata for the NFTs, let's align on what the collection is thematically for the tutorial:
Each NFT in the collection represents a unique superpower. The metadata includes traits like speed, altitude, transparency, etc., that describe the superpower's characteristics.
Upgrading is simply a matter of updating the metadata on the storage provider and using the upgradeSuperPower() function to update the TokenURI on-chain to redirect the NFT to a new image.
For this tutorial, the quickest free solution for storing basic images (and metadata files) was Pinata Cloud. Depending on your use case, you may opt to go with other solutions. We have uploaded our pre-generated images AND metadata-JSON files (or see Step 3 more guided instruction on how to do it). If you’ve already uploaded your metadata, take note of the CIDs - we will assign the token for these two different values later on in the tutorial.
4. TypeScript Configuration (tsconfig.json)
5. Environment File (.env)
💡 Note: it is STRONGLY ADVISED to never put production private keys into plain text. Be sure to have all .env files ignored with any github repository uploads, and avoid using production keys carrying significant value in this manner.
Once everything is installed and set up, we'll be ready to move onto the contract setup steps.
We're going to make an ERC721 NFT that contains special superpowers that can be upgraded over time.
First, Create a folder called contracts/ in your root project directory.
Then, add a new file called SuperPowerNFT.sol
Let's wait before deploying this contract...
Key Elements:
Create a directory called "metadata" in the root directory.
Move a number of desired images (or other type of unique data) that you would like to demonstrate the capabilities of upgradeable metadata. in our case, we used 2 1024x1024 images generated by ChatGPT. Those images have been placed in the "/metadata" directory. You can create a script yourself to bulk upload large numbers images to your hosting provider from this directory - OR for small numbers of file uploads (such as this tutorial), we can manually upload them to Pinata Cloud. Take note of the CID - with Pinata uploads, the image can be hyperlinked simply via ipfs.io/ipfs/<CID>
For example:
https://ipfs.io/ipfs/QmdcHnUu7ViWdzXzj4X8CfzLksX29nSzmqrgFSfZRysHkU
Next, In your metadata/ directory created in Step 1 above, let’s next create a new file named initialMetadata.json. This JSON file is what OpenSea reads and interprets to redirect users to the creators’ images.
Now upload this metadata file to Pinata as well, and note the IPFS URL of this metadata file as well. This new metadata URL will contain an image URL within it. Save this URL for the constructor argument in our deployment command. For example it may look like this:
https://ipfs.io/ipfs/3CiqtD8C2e8fycQs1VRzwmBeuqHGmltpDRC4Vo8hRqs
We're now going to compile the contract and deploy it on the Sepolia testnet!
Note: The steps and code deployed are very similar if you wish to deploy on other EVM blockchains such as Polygon, Arbitrum, Optimism, or Base (to name a few!).
Back in the Environment Setup steps, we asked you to have an Ethereum wallet on hand funded with some faucet Sepolia Ethereum tokens. This will allow us to deploy the contract to Sepolia so we can get some live testing going. Remember that it costs some tokens to perform any amount of state changes on the network
1. Compile the Contract via the CLI and resolve errors, if any
2. Deploy from the Command Line
Be sure that your constructor arguments align with the solidity code itself:
💡You can run "foundry create -h" to get a list of all the possible arguments. If you run into gas fee issues, you can check the current gas price and adjust your priority gas price accordingly: https://sepolia.beaconcha.in/gasnow
3. Verifying the Contract
Verifying the contract allows you and the public to view the functions and code that make up the contract. This is important for building trust and assuring the community that you are more legitimate. We can do this with the forge cli as well!
Again, stay vigilant of the constructor requirements from the contract. Staying organized at all times is key when developing in web3!
How was the verification and deployment? If you were able to deploy and verify the contract, congratulations! It isn’t easy deploying contracts to networks with such volatile gas prices at times. You now have all your metadata set and the NFT contract deployed and initialized, and it should even be eventually viewable on OpenSea after a few minutes. Be sure to navigate to OpenSea’s testnet dashboard as we did not deploy to mainnet in this tutorial.
The next part of the tutorial will demonstrate the process of upgrading the existing NFT’s metadata to represent the new trait.
Validation Cloud is a Web3 data streaming and infrastructure company that connects organizations into Web3 through a fast, scalable, and intelligent platform. Headquartered in Zug, Switzerland, Validation Cloud offers highly performant and customizable products in staking, node, and data-as-a-service. Learn more at Validationcloud.io | LinkedIn | X