Updating Assets

This guide shows how to update Core Asset metadata on Solana using the Metaplex Core SDK. Modify the name, URI, or collection membership of Assets you control.

Summary

Update a Core Asset's metadata using the update instruction. Only the update authority (or an authorized delegate) can modify an Asset.

• Change name and uri to update metadata
• Use newCollection and newUpdateAuthority to add, move, or remove Assets from Collections
• Set updateAuthority to None to make immutable
• Updates are free (no rent cost) unless changing account size

Out of Scope

Updating Token Metadata NFTs (use mpl-token-metadata), plugin modifications (see Plugins), and ownership transfers (see Transferring Assets).

Quick Start

Jump to: Update Asset · Add to Collection · Change Collection · Remove from Collection · Make Immutable

1. Install: npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
2. Fetch the Asset to get current state
3. Call update(umi, { asset, name, uri }) with new values
4. Verify changes with fetchAsset()

Prerequisites

• Umi configured with a signer that is the Asset's update authority
• Asset address of the Asset to update
• New metadata uploaded to Arweave/IPFS (if changing URI) The update authority or delegate of a Core Asset has the ability to change some of the Asset's data.

Updating a Core Asset

Here is how you can use our SDKs to update an MPL Core Asset.

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { update } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { publicKey } from '@metaplex-foundation/umi'
5
6const umi = createUmi('https://api.devnet.solana.com').use(mplCore())
7const assetAddress = publicKey('AssetAddressHere...')
8
9// Update an existing NFT asset's metadata
10const result = await update(umi, {
11  asset: assetAddress,
12  name: 'Updated NFT Name',
13  uri: 'https://updated-example.com/metadata.json',
14}).sendAndConfirm(umi)
15
16console.log('Asset updated successfully')

Add an Asset to a Collection

The update instruction can add a standalone Asset to a Collection by setting newCollection to the target Collection address and newUpdateAuthority to the Collection type. The caller must be the update authority of both the Asset and the target Collection.

1import { publicKey } from '@metaplex-foundation/umi'
2import {
3  update,
4  fetchAsset,
5  fetchCollection,
6  updateAuthority,
7} from '@metaplex-foundation/mpl-core'
8
9const assetId = publicKey('11111111111111111111111111111111')
10const collectionId = publicKey('22222222222222222222222222222222')
11
12const asset = await fetchAsset(umi, assetId)
13const collection = await fetchCollection(umi, collectionId)
14
15// Assumes the asset is standalone. If it already belongs to a collection,
16// fetch that current collection and pass it as the `collection` parameter
17// alongside `newCollection` (see change-collection example); otherwise the
18// instruction will fail.
19await update(umi, {
20  asset,
21  newCollection: collection.publicKey,
22  newUpdateAuthority: updateAuthority('Collection', [collection.publicKey]),
23}).sendAndConfirm(umi)
24
25console.log('Asset added to collection')

1# Add a standalone asset to a collection
2mplx core asset update <assetId> --collection <collectionId>
3
4# Or use the convenience alias
5mplx core collection add <collectionId> <assetId>

Change the Collection of a Core Asset

The update instruction can move an Asset from one Collection to another.

1import { publicKey } from '@metaplex-foundation/umi'
2import {
3  update,
4  fetchAsset,
5  fetchCollection,
6  collectionAddress,
7  updateAuthority,
8} from '@metaplex-foundation/mpl-core'
9
10const assetId = publicKey('11111111111111111111111111111111')
11const newCollectionId = publicKey('22222222222222222222222222222222')
12
13const asset = await fetchAsset(umi, assetId)
14
15const currentCollectionId = collectionAddress(asset)
16if (!currentCollectionId) {
17  throw new Error('Asset does not belong to a collection')
18}
19const currentCollection = await fetchCollection(umi, currentCollectionId)
20
21await update(umi, {
22  asset,
23  collection: currentCollection,
24  newCollection: newCollectionId,
25  newUpdateAuthority: updateAuthority('Collection', [newCollectionId]),
26}).sendAndConfirm(umi)
27
28console.log('Asset moved to new collection')

1# Move an asset from its current collection to a different one
2mplx core asset update <assetId> --collection <newCollectionId>

Remove an Asset from a Collection

The update instruction can remove an Asset from its current Collection by changing the newUpdateAuthority from Collection to Address. This makes the Asset standalone again, with your wallet as its direct update authority.

1import { publicKey } from '@metaplex-foundation/umi'
2import {
3  update,
4  fetchAsset,
5  fetchCollection,
6  collectionAddress,
7  updateAuthority,
8} from '@metaplex-foundation/mpl-core'
9
10const assetId = publicKey('11111111111111111111111111111111')
11
12const asset = await fetchAsset(umi, assetId)
13
14const currentCollectionId = collectionAddress(asset)
15if (!currentCollectionId) {
16  throw new Error('Asset does not belong to a collection')
17}
18const collection = await fetchCollection(umi, currentCollectionId)
19
20await update(umi, {
21  asset,
22  collection,
23  newUpdateAuthority: updateAuthority('Address', [umi.identity.publicKey]),
24}).sendAndConfirm(umi)
25
26console.log('Asset removed from collection')

1# Remove an asset from its current collection
2mplx core asset update <assetId> --remove-collection

Making a Core Asset Data Immutable

Here is how you can use our SDKs to make a Core Asset fully immutable. Be aware that there are different levels of immutability described in the immutability Guide.

import { publicKey } from '@metaplex-foundation/umi'
import { update, fetchAsset } from '@metaplex-foundation/mpl-core'
const assetId = publicKey('11111111111111111111111111111111')
const asset = await fetchAsset(umi, asset)
await update(umi, {
  asset: asset,
  newUpdateAuthority: updateAuthority('None'),
}).sendAndConfirm(umi)

Common Errors

Authority mismatch

You're not the update authority of the Asset. Check:

const asset = await fetchAsset(umi, assetAddress)
console.log(asset.updateAuthority) // Must match your signer

Collection authority required

When changing Collections, you need authority on both the Asset and the target Collection.

Asset is immutable

The Asset's update authority is set to None. This cannot be reversed.

Notes

• Fetch the Asset before updating to ensure you have the current state
• Only the update authority (or delegate) can update an Asset
• Making an Asset immutable is permanent and irreversible
• Adding, moving, or removing Collection membership changes which plugins (royalties, etc.) apply to the Asset
• Removing an Asset from a Collection changes its update authority from the Collection to a wallet address
• Adding an Asset to a Collection changes its update authority from a wallet address to the Collection
• Updates don't change the Asset's owner

Quick Reference

Update Parameters

Authority Types

FAQ

Can I undo making an Asset immutable?

No. Setting the update authority to None is permanent. The Asset's name, URI, and collection membership are frozen forever. Only do this when you're certain.

How do I update only the name without changing the URI?

Pass only the fields you want to change. Omit uri to keep the current value:

await update(umi, { asset, name: 'New Name' }).sendAndConfirm(umi)

What's the difference between updating and transferring?

Update changes the Asset's metadata (name, URI). Transfer changes ownership. They're separate operations with different authority requirements.

Can a delegate update an Asset?

Yes, if they have been assigned as an Update Delegate via the Update Delegate plugin.

Does updating cost SOL?

Updates are free unless the new data is larger than the current account size (rare). The transaction fee (~0.000005 SOL) still applies.

Can I add a standalone Asset to a Collection after creation?

Yes. Use the update instruction with newCollection and set newUpdateAuthority to the Collection type. You need authority on both the Asset and the target Collection. See Add an Asset to a Collection.

Can I remove an Asset from a Collection?

Yes. Use the update instruction and set newUpdateAuthority to updateAuthority('Address', [yourWallet]). This detaches the Asset from the Collection and makes it standalone again. See Remove an Asset from a Collection.

Glossary