Core Candy Machine Program Overview

Summary

Core Candy Machine is the Metaplex minting and distribution program purpose-built for launching MPL Core Asset collections on Solana. It manages the full lifecycle of an NFT drop, from loading item metadata through guarded minting to post-launch cleanup.

• Supports over 23 composable guards for payment, access control, scheduling, and bot protection
• Mints MPL Core Assets (single-account NFTs), not legacy Token Metadata NFTs
• Items are loaded as metadata references; on-chain assets are created only at mint time
• The separate Candy Guard program provides a forkable access-control layer for custom minting workflows

Introduction

By September 2022, 78% of all NFTs in Solana were minted through Metaplex's Candy Machine. This includes most of the well known NFT projects in the Solana ecosystem. Come 2024 Metaplex introduced the Core protocol which redefines NFTs on Solana and with it a new Candy Machine to accommodate the same minting mechanics users loved for the Core standard.

Here are some of the features it offers.

• Accept payments in SOL, NFTs or any Solana token.
• Restrict your launch via start/end dates, mint limits, third party signers, etc.
• Protect your launch against bots via configurable bot taxes and gatekeepers like Captchas.
• Restrict minting to specific Asset/NFT/Token holders or to a curated list of wallets.
• Create multiple minting groups with different sets of rules.
• Reveal your Assets after the launch whilst allowing your users to verify that information.
• And so much more!

Core Candy Machine Lifecycle

The Core Candy Machine lifecycle consists of four sequential phases: creation, item loading, minting, and optional withdrawal. Each phase must complete before the next can begin.

Phase 1 — Create and Configure the Candy Machine

The first step is for the creator to create a new Core Candy Machine and configure its settings, including the collection address, item count, and optional Config Line Settings or Hidden Settings.

The created Core Candy Machine keeps track of its own settings which determine how all of its Assets should be created. For instance, there is a collection parameter which will be assigned to all Assets created from this Core Candy Machine. See Creating a Core Candy Machine for details on all available settings.

Phase 2 — Insert Items into the Candy Machine

After creation, the Candy Machine must be loaded with the metadata for each item to be minted. Each item consists of a name and a uri pointing to pre-uploaded JSON metadata.

Each item is composed of two parameters:

• A name: The name of the Asset.
• A uri: The URI pointing to the JSON metadata of the Asset. This implies that the JSON metadata has already been uploaded via either an on-chain (e.g. Arweave, IPFS) or off-chain (e.g. AWS, your own server) storage provider. The tools that you can use to create the Candy Machine, like the CLI or the JS SDK offer helpers to do so.

All other parameters are shared between Assets and are therefore kept in the settings of the Candy Machine directly to avoid repetition. See Inserting Items for more details.

Phase 3 — Mint Assets from the Candy Machine

Once the Candy Machine is fully loaded and all configured guard conditions are satisfied, users can begin minting Core Assets. Each mint consumes one item from the Candy Machine and creates a new on-chain Asset.

Before minting, some users may need to perform additional verification steps — such as completing a Captcha or submitting a Merkle Proof. See Minting for more details.

Phase 4 — Withdraw the Candy Machine

After all Assets have been minted, the Candy Machine has served its purpose and can be deleted to reclaim on-chain storage rent. The authority receives the reclaimed SOL.

Core Candy Machine Account Structure

The Core Candy Machine account stores all configuration and state data needed to manage the minting process. The on-chain data structure tracks the machine version, enabled features, authority keys, collection binding, and redemption count.

The authority controls management operations such as updating settings, inserting items, and withdrawing rent. The mint_authority controls who can trigger the mint instruction. When a Candy Guard is attached, it becomes the mint authority so that all guard validations must pass before minting proceeds.

Candy Guard System

The Candy Guard program is a companion Solana program that provides composable, configurable access control for Core Candy Machine minting. Guards are modular rules that restrict or modify the minting process.

Creators can use what we call "Guards" to add various features to their Core Candy Machine. The Metaplex Core Candy Machine ships with an additional Solana Program called Candy Guard that ships with a total of over 23 default guards. By using an additional program, it allows advanced developers to fork the default Candy Guard program to create their own custom guards whilst still being able to rely on the main Candy Machine program.

Each guard can be enabled and configured at will so creators can pick and choose the features they need. Disabling all guards would be equivalent to allowing anyone to mint Assets for free at any time, which is likely not what creators want.

Candy Guard Composition Example

Guards compose together to form a complete minting policy. The following example demonstrates how four guards combine to create a bot-protected, time-gated, rate-limited, paid mint.

Say a Core Candy Machine has the following guards:

• Sol Payment: Ensures the minting wallet pays a configured amount of SOL to a configured destination wallet.
• Start Date: Ensures minting can only begin after the configured time.
• Mint Limit: Ensures each wallet cannot mint more than a configured amount.
• Bot Tax: Charges a small configured amount of SOL to any wallet whose mint attempt fails guard validation, deterring automated bots.

What we end up with is a bot-protected Candy Machine that charges SOL, launches at a specific time and only allows a limited amount of mints per wallet. Here is a concrete example.

With more than 23 default guards and the ability to create custom guards, creators can cherry-pick the features that matter to them and compose their perfect Candy Machine. Guards can also be organized into Guard Groups to define multiple minting phases with different rules (for example, an early-access phase for allow-listed wallets followed by a public mint). The best place to start learning about guards is the Candy Guards page.

Notes

• Core Candy Machine mints MPL Core Assets exclusively. To mint Token Metadata NFTs, use Candy Machine V3 instead.
• All items must be inserted before minting can begin when using Config Line Settings.
• The JSON metadata for each item must be uploaded to a storage provider (Arweave, IPFS, AWS, etc.) before inserting items into the Candy Machine.
• Withdrawing a Candy Machine is irreversible and deletes all on-chain data for that machine.
• The Candy Guard program is separate from the Candy Machine Core program. Forking the guard program for custom logic does not require modifying the core minting program.
• Guard validation failures with Bot Tax enabled will charge the failed minter rather than simply rejecting the transaction.

FAQ

What is the Core Candy Machine and how does it differ from Candy Machine V3?

Core Candy Machine is the latest Metaplex minting program designed specifically for MPL Core Assets. Candy Machine V3 mints Token Metadata NFTs using the older standard. Core Candy Machine produces lighter, more cost-efficient assets because MPL Core uses a single-account model instead of multiple accounts per NFT.

How many guards are available for Core Candy Machine?

Core Candy Machine ships with over 23 default guards through the companion Candy Guard program. These guards cover payment collection (SOL, SPL tokens, NFTs), access control (allow lists, token gates, NFT gates), scheduling (start and end dates), and bot protection (bot tax, gatekeepers).

Can developers create custom guards for Core Candy Machine?

Yes. The guard system is implemented as a separate Candy Guard program that can be forked. Developers can create custom guards while still relying on the main Candy Machine program for the actual minting logic.

What happens to a Core Candy Machine after all items are minted?

After all items are minted, the Candy Machine can be withdrawn to reclaim the on-chain storage rent. This operation is irreversible and returns the SOL used for rent to the authority wallet.

Do items need to exist as on-chain Assets before loading a Core Candy Machine?

No. You load the Candy Machine with item metadata (name and URI pairs), not actual on-chain assets. The Core Assets are only created on the Solana blockchain at the moment a user mints from the Candy Machine. See Inserting Items for details.

What is the difference between the Candy Machine authority and the mint authority?

The authority controls configuration and management of the Candy Machine (updating settings, inserting items, withdrawing). The mint authority controls who can trigger minting. Typically, the Candy Guard account is set as the mint authority so that guard validations are enforced before any mint occurs.

Glossary