Programmable NFTs

Version 1.7 of Token Metadata introduced a new type of asset class called Programmable NFTs allowing, amongst other things, creators to enforce royalties on secondary sales.

Since version 1.0 of Candy Machine Core and version 1.0 of Candy Guard, it is now possible to mint Programmable NFTs from candy machines and even update the token standard of existing candy machines.

For new candy machines

A new instruction called initializeV2 has been added to the Candy Machine Core program. This instruction is similar to the initialize instruction, but it allows you to specify the token standard you want to use for your candy machine. This instruction will mark the newly created Candy Machine as V2 to differentiate it from the V1 Candy Machines that do not store the token standard. These new fields are using existing padding in the Candy Machine account data to avoid breaking changes in the Candy Machine serialization logic.

The initializeV2 instruction can also be used to create a Candy Machine that mints regular NFTs and, therefore, the initialize instruction is now deprecated. Note that no changes are needed for the Candy Guard program here since it delegates to the Candy Machine Core when minting the NFT.

Also, note that some optional accounts may be required depending on the token standard you choose. For example, the ruleSet account may be provided to assign a specific rule set to all minted Programmable NFTs. If no ruleSet account is provided, it will use the rule set of the Collection NFT if any. Otherwise, minted Programmable NFTs will simply not have any rule set assigned. On the other hand, the ruleSet account will be ignored when minting regular NFTs.

Additionally, the collectionDelegateRecord account should now refer to the new Metadata Delegate Record from Token Metadata.

You may want to read the "Create Candy Machines" section of this documentation for more details but here are some examples on how to use our SDKs to create a new Candy Machine that mints Programmable NFTs.

Create a new PNFT Candy Machine

import { TokenStandard } from '@metaplex-foundation/mpl-token-metadata'
import { create } from '@metaplex-foundation/mpl-candy-machine'
import { generateSigner } from '@metaplex-foundation/umi'

await create(umi, {
  // ...
  tokenStandard: TokenStandard.ProgrammableNonFungible,

API References: create

For existing candy machines

It is possible to update the token standard of existing Candy Machines via the new setTokenStandard instruction. When calling this instruction on a Candy Machine V1, it will also upgrade the Candy Machine to V2 and store the token standard in the account data.

You may want to read the "Update Token Standard" section of this documentation for more details but here are some examples on how to use our SDKs to update the token standard of an existing Candy Machine to Programmable NFTs.

Change the Token Standard of a Candy Machine

import { TokenStandard } from '@metaplex-foundation/mpl-token-metadata'
import { setTokenStandard } from '@metaplex-foundation/mpl-candy-machine'

await setTokenStandard(umi, {
  candyMachine: candyMachine.publicKey,
  collectionMint: candyMachine.collectionMint,
  tokenStandard: TokenStandard.ProgrammableNonFungible,

API References: setTokenStandard

Additionally, a new setCollectionV2 instruction has been added to support setting a collection that is compatible with Programmable NFTs. This instruction also works with regular NFTs and deprecates the setCollection instruction.

Here as well, you can read more about it in the "Update Collection" section of this documentation.

Update the collection of your Candy Machine

import { setCollectionV2 } from '@metaplex-foundation/mpl-candy-machine'

await setCollectionV2(umi, {
  candyMachine: candyMachine.publicKey,
  collectionMint: candyMachine.collectionMint,
  collectionUpdateAuthority: collectionUpdateAuthority.publicKey,
  newCollectionMint: newCollectionMint.publicKey,

API References: setCollectionV2

A new minting instruction

The mint instruction of both the Candy Machine Core and the Candy Guard programs has been updated to support minting Programmable NFTs. This new instruction is called mintV2 and it is similar to the mint instruction, but requires additional accounts to be passed in. Here as well, the new mintV2 instructions can be used to mint regular NFTs and, therefore, they deprecate the existing mint instructions.

The entire "Minting" page has been updated to use the new mintV2 instructions but here's a quick example of how to use them with Programmable NFTs.

Mint from your Candy Machine

import { mintV2 } from '@metaplex-foundation/mpl-candy-machine'
import { setComputeUnitLimit } from '@metaplex-foundation/mpl-toolbox'
import { transactionBuilder, generateSigner } from '@metaplex-foundation/umi'

const nftMint = generateSigner(umi)
await transactionBuilder()
  .add(setComputeUnitLimit(umi, { units: 800_000 }))
    mintV2(umi, {
      candyMachine: candyMachine.publicKey,
      collectionMint: collectionNft.publicKey,
      collectionUpdateAuthority: collectionNft.metadata.updateAuthority,

API References: mintV2

Note that some of the guards offered by the Candy Guard program have also been updated to support Programmable NFTs. Whilst the updates do not introduce breaking changes when minting regular NFTs, they may expect more remaining accounts when minting depending on the token standard.

The guards affected by these changes are:

  • The nftBurn and nftPayment guards now allow the burned/sent NFT to be a Programmable NFT.
  • The FreezeSolPayment and FreezeTokenPayment guards. Since Programmable NFTs are by definition always frozen, they are Locked when minted via a Utility delegate and Unlocked when the thaw conditions have been met.

Additional reading

You may find the following resources about Programmable NFTs and Candy Machines useful: