Metaplex Candy Machine Core (a.k.a. Candy Machine V3)

Overview

The Metaplex Protocol's Candy Machine is the leading minting and distribution program for fair NFT collection launches on Solana. It allows creators to bring their asset metadata on-chain and provides a mechanism to create (mint) NFTs from the on-chain configuration — in both deterministic and non-deterministic (random) way, like a traditional candy machine.

The latest iteration of the Candy Machine program retains the core functionality of minting an NFT only, while any access control configuration is now done by the new Candy Guard program.

The Candy Machine program is responsible for:

• config line (asset) management: configuration of how many assets are available and their metadata information;
• index generation and selection;
• NFT minting (token creation).

Why separating mint logic and access control?

Previous versions of the Candy Machine included access controls to limit who can mint, when minting is allowed and other settings related to the mint (e.g., price) as part of its minting procedure. While the combination of the mint logic with access controls works, this design makes it complex to add more features or to remove undesired ones.

Creating a clear separation provides a modular and flexible architechture to add and remove access control settings, whithout the risks and complexities of breaking the minting logic. Each access control logic can be implemented in isolation and users can choose to enable/disable individual ones.

Who can mint from a Candy Machine?

Each Candy Machine account has two authorities associated: an authority and mint_authority. The authority has permission to manage the configuration of the candy machine. This include adding config lines (assets), updating its settings, changing authority/mint authorities and closing/withdrawing the account.

The mint_authority is the only address that is able to mint from a candy machine — the only requirement being that there are NFTs to be minted from it. The authority of the candy machine can delegate the mint_authority to another address, either a wallet or PDA. This separation allows maximum flexibility and enables composability, since other programs can be set as mint_authority and provide additional features on top of the candy machine. An example of this is the Candy Guard program, which provides access control guards for the candy machine.

Account

The Candy Machine configuration is stored in a single account, which includes settings that control the behaviour of the candy machine and metadata information for the NFTs minted through it. The account data is represented by the CandyMachine struct, which include references to auxiliary structs Creator, ConfigLineSettings and HiddenSettings.

Instructions

Note The instructions make use of Anchor v0.26 support for positional optional accounts.

📄 add_config_lines

This instruction adds config lines to the hidden data section of the account. It can only be used if the candy machine has config_line_settings.

📄 initialize (deprecated)

This instruction creates and initializes a new CandyMachine account. It requires that the CandyMachine account has been created with the expected size before executing this instruction.

📄 initialize_v2

This instruction creates and initializes a new CandyMachine account that support multiple token standard. It requires that the CandyMachine account has been created with the expected size before executing this instruction. A Candy Machine created through this instruction will have its AccountVersion set to V2.

📄 mint (deprecated)

This instruction mints an NFT from the Candy Machine. Only the mint authority is able to mint from the Candy Machine.

📄 mint_v2

This instruction mints both NFT or pNFT from the Candy Machine. Only the mint authority is able to mint from the Candy Machine.

📄 set_authority

This instruction changes the authority of the candy machine. Note that this operation is irreversible, once you change the authority of the Candy Machine, the current authority will lose the right to operate it.

📄 set_collection (deprecated)

This instruction sets the collection to be used by the Candy Machine. The collection can only be changed if no NFTs have been minted.

📄 set_collection_v2

This instruction sets the collection to be used by Candy Machine's AccountVersion::V1 or AccountVersion::V2. The collection can only be changed if no (p)NFTs have been minted.

📄 set_mint_authority

This instruction changes the mint authority of the Candy Machine. Note that this operation is irreversible, once you change the mint authority of the Candy Machine, the current mint authority will lose the right to mint from the Candy Machine.

📄 set_token_standard

This instruction sets the token standard and (optional) rule set to be used by the Candy Machine. It will also update the version of the Candy Machine account to V2 and set a Medatada Collection delegate (instead of the Authority Record PDA).

📄 update

This instruction updates the configuration of the Candy Machine. There are restrictions on which configuration can be updated:

• items_available: can only be updated when hidden_settings are used.
• hidden_settings: it is not possible to switch to hidden_settings if the number of items_available is greater than 0; it is not possuble to swith from hidden_settings to config_line_settings.
• name_length and uri_length in config_line_settings: can only be updated with values that are smaller that current values used.
• is_sequential: can only be changed is the number of items_redemmed is equal to 0.

📄 withdraw

This instruction withdraws the rent lamports from the account and closes it. After executing this instruction, the Candy Machine will not be operational.

Features

Main improvements over the previous Candy Machine program.

Account space utilization

It is now possible to define a pattern to store the name and uri configuration in the format of prefix_name + name and prefix_uri + uri, where both prefix_name and prefix_uri are shared among all config lines. This provides account space saving, since there is no need to store repeated bytes in the account, leading to the possibility of creating larger Candy Machines and reducing the cost of deployment.

Instead of storing full URIs — e.g., https://arweave.net/yFoNLhe6cBK-wj0n_Wu-XuX7DC75VbMsNKwVbRSz4iQ?ext=png — for each config line, the prefix_uri is set to https://arweave.net/ and each config line only stores the different values in the uri space. This also applies to the prefix_name and name pair.

When a storage with deterministic URI generation — e.g., AWS S3 and Shadow Drive — is used, a significant space saving can be achieved by using replacement patterns in the prefix_name and prefix_uri, leaving each individual name and uri empty. In this case, the only space needed is to store the index representing the id for the random mint index generation.

A prefix_uri can include $ID$ or $ID+1$ patterns, which are automatically substituted for the mint index or mint index + 1 to generate a valid uri:

• https://shdw-drive.genesysgo.net/DCG6qThfZE8xbM72RoFRLwRSrhNVjeWE1gVPPCGvLYSS/$ID$.png gets expanded to https://shdw-drive.genesysgo.net/DCG6qThfZE8xbM72RoFRLwRSrhNVjeWE1gVPPCGvLYSS/0.png when the first NFT is minted.

This also applied to the prefix_name: My NFT #$ID+1$ gets expanded to My NFT #1 when the fist NFT is minted.

Hidden settings with "automatic" reveal

Hidden settings are the most space efficient way to create a Candy Machine since no config lines are stored on the account. At the same time, it is necessary to run an update metadata procedure — dubbed reveal — after the mint to set each individual name and URI on the metadata of minted NFTs.

When a storage with deterministic URI generation is used, the reveal is not required as one can use the same $ID$or $ID+1$ replacement patterns in the name and uri fields of hidden settings.

The difference between using config lines with patterns and hidden settings with patterns is that in the former, the index generation for the mint is random while in the later the index generation is sequential.

Note While the use of deterministic URIs saves you work in terms of not requiring to run an update the metadata on each NFT, it would be possible to determine the URI of an NFT before it is minted. In order to avoid the files to be publicly accessible ahead of time, a placeholder image with the same name can be used instead. Therefore, the trade-off is between running an update metadata on each NFT or updating the images.

Random Index Generation

Currently the random index generation uses a sequential procedure to find the next available mint index. While this procedure works for most cases, it is not efficient (in terms of compute units) and it can reach the limit of compute units on large Candy Machine deploys.

The new Candy Machine uses an improved procedure that consumes a fixed amount of compute units regardless of the number of items and, at the same time, shuffles the values to improve their unpredictability.