Updating Compressed NFTs

Summary

Updating a compressed NFT modifies its metadata using the updateMetadataV2 instruction. This page covers update authority rules for collection-based and tree-based cNFTs.

• Update cNFT metadata (name, URI, creators, royalties) using updateMetadataV2
• Collection authority updates cNFTs that belong to a collection
• Tree authority updates cNFTs that do not belong to a collection
• Changes are reflected in the merkle tree and indexed by DAS API providers
• Use leaf metadata from getAssetWithProof as updateMetadataV2's currentMetadata arg (IDL name for existing leaf state)

The updateMetadataV2 instruction can be used to modify the metadata of a Compressed NFT. The Merkle root is updated to reflect the propagated hash of the data, and RPC providers who conform to the Metaplex DAS API will update their index of the cNFTs.

The metadata can be updated by one of two authorities, depending on if the compressed NFT is a verified item in a collection.

Update Authority

A cNFT has two possible update authorities: the tree owner, or (if it belongs to a collection) the collection authority.

Collection Authority

If your cNFT belongs to a collection, then the update authority of that cNFT will be the authority of the collection. When updating the cNFT you will need to pass in a coreCollection arg to the update function.

The authority will be inferred from the current umi identity. If the authority is different from the current umi identity, then you will either have to pass in the authority arg as a signer type or create a noopSigner for later signing.

await updateMetadataV2(umi, {
  ...
  authority: collectionAuthority,
  coreCollection: publicKey("11111111111111111111111111111111"),
}).sendAndConfirm(umi)

Tree Authority

If your cNFT does not belong to a collection then the update authority for the cNFT will be the authority of the tree that the cNFT belongs to. In this case, you would omit the coreCollection arg from the update function.

The authority will be inferred from the current umi identity. If the authority is different from the current umi identity, then you will either have to pass in the authority arg as a signer type or create a noopSigner for later signing.

Update cNFT

import {
  getAssetWithProof,
  updateMetadataV2,
  UpdateArgsArgs,
} from '@metaplex-foundation/mpl-bubblegum'
import { some } from '@metaplex-foundation/umi'

// Use the helper to fetch the asset and proof.
const assetWithProof = await getAssetWithProof(umi, assetId, {
  truncateCanopy: true,
})

// Then we can use it to update metadata for the NFT.
const updateArgs: UpdateArgsArgs = {
  name: some('New name'),
  uri: some('https://updated-example.com/my-nft.json'),
}
await updateMetadataV2(umi, {
  ...assetWithProof,
  leafOwner,
  currentMetadata: {
    name: assetWithProof.metadata.name,
    symbol: assetWithProof.metadata.symbol,
    uri: assetWithProof.metadata.uri,
    sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints,
    primarySaleHappened: assetWithProof.metadata.primarySaleHappened,
    isMutable: assetWithProof.metadata.isMutable,
    tokenStandard: assetWithProof.metadata.tokenStandard,
    creators: assetWithProof.metadata.creators,
    collection: some(publicKey('22222222222222222222222222222222')),
  },
  updateArgs,
  // Optional param. If your authority is a different signer type 
  // than the current umi identity assign that signer here.
  authority: <Signer>,
  // Optional param. If cNFT belongs to a collection pass it here.
  coreCollection: publicKey("22222222222222222222222222222222"),
}).sendAndConfirm(umi)

1import {
2  getAssetWithProof,
3  updateMetadataV2,
4  UpdateArgsArgs,
5  mplBubblegum,
6} from '@metaplex-foundation/mpl-bubblegum'
7import { publicKey, some } from '@metaplex-foundation/umi'
8import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
9
10const umi = createUmi('https://api.devnet.solana.com').use(mplBubblegum())
11
12const assetId = publicKey('YOUR_ASSET_ID')
13const collectionPublicKey = publicKey('YOUR_COLLECTION_ADDRESS')
14
15const assetWithProof = await getAssetWithProof(umi, assetId, {
16  truncateCanopy: true,
17})
18
19// Switch from inherited royalties to an explicit seller fee before removing
20// the cNFT from its collection.
21const updateArgs: UpdateArgsArgs = {
22  sellerFeeBasisPoints: some(550), // explicit 5.5%
23}
24
25await updateMetadataV2(umi, {
26  ...assetWithProof,
27  currentMetadata: {
28    name: assetWithProof.metadata.name,
29    symbol: assetWithProof.metadata.symbol,
30    uri: assetWithProof.metadata.uri,
31    sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints,
32    primarySaleHappened: assetWithProof.metadata.primarySaleHappened,
33    isMutable: assetWithProof.metadata.isMutable,
34    tokenStandard: assetWithProof.metadata.tokenStandard,
35    creators: assetWithProof.metadata.creators,
36    collection: some(collectionPublicKey),
37  },
38  updateArgs,
39  coreCollection: collectionPublicKey,
40}).sendAndConfirm(umi)
41
42// Leaf seller fee updated from inherit sentinel (65535) to 550 basis points

Notes

• The update authority depends on whether the cNFT belongs to a collection. Collection cNFTs use the collection authority; standalone cNFTs use the tree authority.
• Pass leaf metadata from getAssetWithProof as updateMetadataV2's currentMetadata arg so the program can verify the current leaf before applying updates.
• Use some() for fields to update; omit fields you wish to leave unchanged.
• Inherited seller fees require an empty leaf-level creators array and a collection with the Royalties plugin.

FAQ

Who can update a compressed NFT's metadata?

If the cNFT belongs to a collection, only the collection authority can update it. If it does not belong to a collection, the tree authority (tree creator or delegate) can update it.

What fields can I update on a cNFT?

You can update the name, URI, seller fee basis points, and other metadata fields defined in UpdateArgsArgs. Use some('newValue') for fields you want to change.

Do I need to pass the collection when updating?

Yes, if the cNFT belongs to a collection. Pass the coreCollection parameter with the collection's public key. The collection authority must sign the transaction.

How do I update a cNFT that inherits royalties from its collection?

Pass leaf metadata from getAssetWithProof as updateMetadataV2's currentMetadata arg so the on-chain sentinel is used for verification. Use updateArgs.sellerFeeBasisPoints with some(SELLER_FEE_BASIS_POINTS_INHERIT) to switch to inherited royalties, or an explicit number to switch away from them.

Glossary