ImmutableMetadata Plugin

The ImmutableMetadata Plugin permanently locks the name and URI of Assets or Collections. Once added, the metadata cannot be changed by anyone, ensuring permanent provenance.

Summary

The ImmutableMetadata plugin is an Authority Managed plugin that prevents any changes to an Asset or Collection's name and URI. Once added, this protection is permanent.

• Authority Managed (only update authority can add)
• Makes name and URI permanently unchangeable
• Cannot be removed after addition
• Collection plugin affects all Assets in that Collection

Out of Scope

Making other plugin data immutable (use authority None on those plugins), selective field immutability, and temporary locks.

Quick Start

Jump to: Add to Asset · Add to Collection

1. Ensure metadata (name, URI) is finalized
2. Add ImmutableMetadata plugin as update authority
3. Metadata is now permanently locked

Common Use Cases

• Art collectibles: Guarantee artwork and metadata will never change
• Certificates: Issue credentials that can't be altered
• Provenance protection: Prevent rug-pulls by locking metadata
• Historical records: Preserve NFT data permanently
• Brand guarantees: Assure collectors the NFT's identity is fixed

Works With

Arguments

The ImmutableMetadata Plugin requires no arguments.

Adding the immutableMetadata Plugin to an Asset code example

import {
  addPlugin,
} from '@metaplex-foundation/mpl-core'
await addPlugin(umi, {
  asset: asset.publicKey,
  plugin: {
    type: 'ImmutableMetadata',
  },
}).sendAndConfirm(umi)

Adding the immutableMetadata Plugin to a Collection code example

import {
  addCollectionPlugin,
} from '@metaplex-foundation/mpl-core'
await addCollectionPlugin(umi, {
  collection: collection.publicKey,
  plugin: {
    type: 'ImmutableMetadata',
  },
}).sendAndConfirm(umi)

Common Errors

Authority mismatch

Only the update authority can add the ImmutableMetadata plugin.

Cannot update metadata

The ImmutableMetadata plugin is active. The name and URI cannot be changed.

Notes

• This action is permanent and irreversible
• Double-check name and URI before adding this plugin
• Adding to a Collection makes ALL Assets in that Collection immutable
• The plugin has no arguments—just add it to lock metadata

Quick Reference

Affected Fields

Inheritance Behavior

FAQ

Can I undo adding ImmutableMetadata?

No. Once added, the ImmutableMetadata plugin cannot be removed. The metadata is permanently locked. This is by design for provenance guarantees.

What exactly becomes immutable?

The Asset or Collection's name and uri fields. Other plugin data is not affected—use authority None on individual plugins to make their data immutable.

If I add this to a Collection, are existing Assets affected?

Yes. When ImmutableMetadata is on a Collection, all Assets in that Collection inherit the immutability. Their metadata cannot be changed.

Can I add this during Asset creation?

Yes. You can add ImmutableMetadata during create() to ensure the metadata is locked from the start.

Why would I want immutable metadata?

Immutable metadata provides permanent provenance—collectors know the NFT's name and associated metadata URI can never be changed, preventing rug-pulls where creators swap out artwork or descriptions.

Related Plugins

• AddBlocker - Prevent new plugins (complementary to ImmutableMetadata)
• Attributes - On-chain data (not locked by ImmutableMetadata)
• Royalties - Set royalties before making immutable

Glossary