Updating Solana token metadata

Two layers, two different sets of rules

Almost all confusion about metadata comes from treating it as one thing when it is two, with different owners and different permanence.

The on-chain metadata account holds the name, the symbol and a URI. It lives on Solana, it is modified by a transaction, and modifying it requires holding the update authority.

The JSON file at that URI holds the description, the image link and any additional display fields. It lives on ordinary web hosting somewhere, and changing it requires nothing but access to that hosting.

The practical consequence is significant and frequently missed: if you control the hosting, you can change the description and the image at any time, even after revoking the on-chain authority, because those live outside the chain entirely. What becomes permanent on revocation is the name, the symbol, and where the URI points.

What update authority actually controls

It controls the on-chain fields and nothing else, which is a narrower scope than the name suggests.

• Name and symbol. Both editable while the authority exists.
• The metadata URI. Where wallets go looking for the JSON.
• Certain flags depending on the standard used.

It does not control supply, which belongs to the mint authority. It does not control whether accounts can be frozen, which belongs to the freeze authority. Those are separate permissions with separate consequences, and conflating them is behind a good deal of misplaced worry in both directions. The on-chain reading guide covers where each one is displayed and what each actually permits.

What you can and cannot change

The third row is the lever most teams do not realise they have. Pointing the URI at hosting you own means the display layer stays editable permanently, which turns a revoked update authority from a one-way door into a reasonable decision.

Revoking, and what it costs you

Revoking update authority is read as a credibility signal, and the reasoning behind that reading is sound. A token whose name and symbol can be changed at any moment could, in principle, be renamed into something it is not. Removing that possibility removes a category of risk for holders.

What it costs is every future correction. A typo in the symbol is permanent. A URI pointing at hosting that later disappears is permanent, and that is the failure that actually bites, because free image hosts expire and personal servers go down. The missing image guide covers how routinely that happens weeks after a launch nobody was worried about.

The sensible order, therefore, is not to revoke early as a gesture. It is to get every field correct, point the URI somewhere permanent that you control, confirm everything loads from a clean network, and only then revoke. At that point the signal costs you nothing you will miss.

There is a middle option between keeping the authority and revoking it that gets overlooked. The authority can be transferred rather than destroyed, which means it can be moved to a multi-signature arrangement or to a separate wallet held away from day-to-day operations. That preserves the ability to fix a genuine problem while removing the concern that one compromised key can rename the token. It is a weaker signal than revocation and a considerably stronger one than an authority sitting on the same wallet that does everything else, and for many projects it is the honest middle position.

A safe sequence

1. Decide the final name and symbol. These are the fields that become permanent.
2. Host the JSON somewhere you control and intend to keep paying for.
3. Host the image in the same place, not on a temporary host used during launch.
4. Update the on-chain URI to point there.
5. Verify by fetching both URLs directly, from a network that is not yours, so you are not testing your own cache.
6. Wait for the ecosystem to catch up before concluding anything about whether it worked.
7. Then consider revoking, if you want the signal, knowing the display layer remains editable.

Step five is the one people skip and then spend an afternoon confused by, because a browser that already has the old file cached will show it back to you convincingly.

One practical detail about the transaction itself. Updating on-chain metadata rewrites the fields rather than appending to them, so whatever you submit becomes the complete new state. A partial update that omits a field can therefore clear it rather than leave it alone, depending on the tooling used. Read what your tool sends before signing, and check the result immediately afterwards on an explorer rather than assuming success, because the failure mode here is a token that now has a blank symbol and an authority you may have just revoked.

What happens downstream

Changing metadata on-chain does not change anything anywhere else immediately, and expecting it to leads to a great deal of unnecessary debugging.

Wallets cache. Screeners cache, and several do not read your metadata at all for the images they display, using their own records populated when the pair was first indexed. Aggregators maintain curated lists that update on their own schedule. The result is an uneven rollout where one interface is correct within minutes, another takes a day, and a third keeps showing the old version until something forces a refresh.

Two practical implications. Verify at the source rather than in an app, because the source is the only thing you control. And be careful with changes that alter identity, because a token whose name changes without explanation looks exactly like an impersonation attempt to anyone who notices. If a rename is genuinely necessary, announce it first and publish the transaction after, so that the change is discovered alongside its reason rather than on its own. The launch checklist covers getting these decisions right before launch, which is considerably cheaper than correcting them afterwards.