Finally: A Guide to Updating Your Solana NFT Collection’s Metadata

We’re still in “early days” because documentation is… sparse?

There are tons of NFT project developers out there that, like myself, are learning as they go. The opportunity for really cool ideas to come to fruition right now is vast, but access to information about how to manage your project’s blockchain assets is limited. Not that it’s behind some sort of paywall (for now), but it’s hard to find.

With Metaplex’s Token Standard changing recently as they launched Candy Machine V2, then Verified Collections, and now their Sugar CLI, it’s easy to feel behind on what your project’s data needs to look like and where to best manage it.

This article aims to give a single, concrete, example of how I took an NFT we had minted in the past and updated its metadata URI using Arweave (via Bundlr) and Metaboss. You can take this example and expand it to updating an entire collection (but be ready with a custom RPC node and some SOL)!

Backstory — Mickey DeGods & Chaotic Mints

This is just a little backstory about HOW we got to where we needed this change, and you can feel free to skip to the how-to below :)

I’ve been the Lead Developer of Mickey DeGods, a sub-community of the DeGods collection on Solana that features PFPs with fast food restaurant traits — the Mickey DeGods Visor and the Mickey DeGods Uniform. Our goal is to make ownership of a DeGod with these traits fun and engaging, with a bit of a LARPing side to it (we often talk to each other like we’re on shift at the restaurant and debate who’s turn it is to clean the putrid toilets). We’ve since inspired a good number of other community members to find similar ways to enhance the experience of owning an NFT with interesting traits.

My DeGod #8426, with the Mickey DeGods Uniform

In order to take the LARPing to the next level, our Artist/Head Chef Fox Bellafonte cooked up some tasty menu items that we sold as NFTs. Customers could come mint them, choosing from three menu item options, each of them with their own rarities and (sometimes sickly) traits.

We minted three separate projects during three very different times in the lifespan of Metaplex Candy Machines. This in itself is a great use case for Metaboss: now that Metaplex introduced Verified Collections, we are working on migrating all our old assets to the newest token standard AND migrating them all to their specific Collections.

How to Update Attribute Metadata

Let’s start with your resources — use these well:

• Metaboss Docs: https://metaboss.rs/overview.html
• Bundlr Docs: https://docs.bundlr.network/docs/client/cli
• Solana Tool Suite Installation Guide: https://docs.solana.com/cli/install-solana-cli-tools
• Metaplex Token Data Structs: https://docs.metaplex.com/guides/archived/architecture/deep_dive/overview

The simplest use case to help introduce this topic is the following:

A customer noticed a small spelling error in the metadata for his menu item. Here at Mickey DeGods, we take customer service very seriously and wanted to make his order right ASAP. How would we update an NFT that was already minted from a Candy Machine, that he has in his wallet?

Some vital token metadata is stored on-chain, but not all of it. You can tell what is on-chain by taking a look at Metaplex’s Data Structs documentation:

pub struct Data {
/// The name of the asset
pub name: String,
/// The symbol for the asset
pub symbol: String,
/// URI pointing to JSON representing the asset
pub uri: String,
/// Royalty basis points that goes to creators in secondary sales (0–10000)
pub seller_fee_basis_points: u16,
/// Array of creators, optional
pub creators: Option<Vec<Creator>>,
}

So this tells us that attribute/trait metadata is stored off-chain as JSON data. This data is very often stored on services like Arweave, but you can actually store this data anywhere. Your priority, nevertheless, should be security, redundancy, and censorship resistance. That’s why I highly prefer Arweave.

Okay, so now we know what needs to be changed, and where it lives. Our goal is to update the JSON metadata that already lives on Arweave. This brings about two more questions:

1. Can you update metadata for NFTs out in the wild? Well I’d hope so, or why the hell am I writing this article? The key is that you must have set the NFT collection’s “mutable” state to true.
2. Is data uploaded to a hosting service editable? The answer is “not easily, if at all”.

Let’s see what we can do!

Uploading New Metadata to Arweave

For the sake of this example, I’m going to assume the following:

1. You have custody of the wallet that created the Candy Machine (this is called update authority).
2. The collection, when created, was set as “mutable” (this is recommended by Metaplex and, in previous generations of their Candy Machine, was set by default).
3. You have a little bit of experience interacting with a command line interface (CLI) like Apple’s Terminal or a bash window.
4. You have the URI of your tokens’ metadata on hand already, either via a cache file from the Candy Machine creation, or otherwise. This just makes updating the JSON metadata easier as you can copy and paste the old one into a new file and make small adjustments in there.

If you are having trouble finding your NFT’s token metadata stored on Arweave, don’t panic! If you can find the original JSON you paired your PNG files with when you set up the Candy Machine, then you can just use the formatted JSON I’ll paste below as your guide.

My metadata URI could be found at: https://arweave.net/txMqr8zsX2Oo1GZgKtEVH9nCa5kM4OTNwZ0Bb52otYg

Prettified, it looks something like this:

Note that this file already has some data fields that are now stored on-chain, and are therefore redundant (though, they won’t hurt your NFT AFAIK).

Copy this data and paste it into a new file with your changes. For us, the customer wanted the “Vibe” trait to say “Half Life = 69,420 years”. Classic.

Save this file with whatever name you want, as long as you can find it.

Bundlr Is Your Best Friend

Hot take: Interacting with Arweave is cumbersome and involves going off and purchasing some of their token (AR) in order to pay for uploads to their storage nodes. There is a better way, and it’s called Bundlr.

You might be familiar with it if you’ve created a number of Candy Machines, because that’s a common storage option on there. TLDR: Bundlr allows you to upload to Arweave by allowing you to hop into one of their “bundles” that uploads every two minutes from Layer 2 onto Layer 1 Arweave, while using a variety of tokens as payment options.

Download the Solana Tool Suite, create a wallet using their CLI, and fund it. Or better yet, connect to the wallet that has update authority on your NFTs and skip a step. More on that below if you don’t have the keypair for Solana CLI yet.

Now, we can get that shiny new data onto Arweave. Download Bundlr’s CLI:

npm install -g @bundlr-network/client

added 883 packages, and audited 884 packages in 34s

111 packages are looking for funding

run `npm fund` for details

found 0 vulnerabilities

Using the CLI, uploading your file to Arweave is as simple as:

bundlr upload <data.json> -h https://node1.bundlr.network -w <wallet.json> -c solana

Uploaded to https://arweave.net/zt3-t8SHDSck0TLcSuC-hdQb2E0civ0DVMRgwf6sCz0

Fill in the path to your funded wallet, the path to your data, and you’re done. The provided host URL worked for me. You can check the URI to see that your data is hosted successfully.

Updating Your NFT with Metaboss

Metaboss is really cool. What we’re about to do is like, 1000x easier thanks to these guys. You should read more about it on their website.

You can download Metaboss on the command line:

bash <(curl -sSf https://raw.githubusercontent.com/samuelvanderwaal/metaboss/main/scripts/install.sh)

Finally, make sure you switch to the wallet that has update authority for your NFTs on the Solana CLI. If you don’t have access to it in the CLI, look into the following command you can access via Solana CLI:

solana-keygen recover

For our single-NFT example, this is a piece of cake. We have the URI on hand for our updated metadata, we can get the Mint Address / Token Address of our NFT from Solscan, and we have our wallet. We can now update the dang thing like so:

metaboss update uri — keypair ~/.config/solana/xyz.json — account CGfpsuse8G3Y5e1Di6PazM68dbMVd1GvPWddwbuHGSJq — new-uri https://arweave.net/hhKePQVQGeSpzE3B6joBsTJIV_fvc55W1T2FpEpkIjs

[2022–08–22T21:57:15Z WARN metaboss] Using a public RPC URL is not recommended for heavy tasks as you will be rate-limited and suffer a performance hit.

Please use a private RPC endpoint for best performance results.

Tx sig: bzdnDkXJayUHsucr3YoYAJbkPhYmzbf7yoVzSLxEXTq3qbL8ppAo2dajaRyqqMqBiRaFWWdBFRC3wc1WafX6Gtw

Done!

We use the update uri command, reference our keypair path, our NFT’s token address (here called “account”), and the new pointer to our metadata. That’s it! We’re done!

Conclusion

It still requires a sort of medley of tools, but for the moment, this is what I’ve found to be the most straightforward way to update NFT metadata. You can expand this to the on-chain metadata, or to the entire collection, but this involves a lot more careful data management and a few different commands. But all of this is achievable by reading through the documentation I left you above. If you run into issues, I’d be more than happy to help out in the comments. You can also reach out to me on Twitter.