Creating a Core Candy Machine

Summary

The create instruction initializes a new Core Candy Machine account on Solana, linking it to a Core Collection and defining how assets are stored and distributed.

• Core instruction: create from @metaplex-foundation/mpl-core-candy-machine deploys a new Candy Machine account
• Storage modes: Choose Config Line Settings for prefix-compressed individual asset data or Hidden Settings for a single-reveal placeholder
• Guard support: Attach guards at creation time to control minting access, payments, and scheduling
• Prerequisite: A Core Collection must exist before the Candy Machine can be created

Jump to: Prerequisites · Creating a Candy Machine · Create Candy Machine Arguments · Config Line Settings · Hidden Settings · Creating with Guards · Notes · FAQ

Prerequisites

• Prepared Assets
• Create Core Collection

If you wish to create your Core Candy Machine Assets into a collection (new or existing) you will need to supply the Core Collection upon creation of the Core Candy Machine.

Creating a Core Candy Machine

The create function deploys a new Core Candy Machine account, assigns it to a Core Collection, and sets the total number of items available for minting.

mplx cm create --wizard

// Create the Candy Machine.
import { create } from '@metaplex-foundation/mpl-core-candy-machine'
import { generateSigner } from '@metaplex-foundation/umi'

const candyMachine = generateSigner(umi)

const createIx = await create(umi, {
  candyMachine,
  collection: collectionMint.publicKey,
  collectionUpdateAuthority: umi.identity,
  itemsAvailable: 1000,
  authority: umi.identity.publicKey,
})

await createIx.sendAndConfirm(umi)

Create Candy Machine Arguments

The create function accepts the following arguments to configure the Core Candy Machine at deployment time.

A newly generated keypair/signer that is used to create the Core Candy Machine.

authorityPda Field

The authorityPda is the PDA used to verify minted assets against the collection. This field is optional and is calculated automatically from default seeds when omitted.

authorityPda: string

authority Field

The authority is the wallet or public key that will have administrative control over the Core Candy Machine, including the ability to update settings and manage guards.

authority: string

payer Field

The payer is the wallet that pays for the transaction and rent costs. This field defaults to the current signer when omitted.

payer: publicKey

collection Field

The collection is the public key of the Core Collection that the Candy Machine will mint assets into.

collection: publicKey

collectionUpdateAuthority Field

The collectionUpdateAuthority is the update authority of the collection. This must be a signer so the Candy Machine can approve a delegate to verify created Assets to the Collection.

collectionUpdateAuthority: signer

itemsAvailable Field

The itemsAvailable field specifies the total number of assets that can be minted from the Core Candy Machine. This value is set at creation and determines the size of the Candy Machine account.

itemsAvailable: number

isMutable Field

The isMutable field is a boolean that determines whether minted assets can be updated after creation. When set to false, asset metadata is permanently locked at mint time.

isMutable: boolean

Config Line Settings Field

Config Line Settings stores individual asset names and URIs on-chain using prefix compression, significantly reducing the Candy Machine's rent cost compared to storing full strings for every asset.

By storing the Assets name and URI prefix into the Core Candy Machine the data required to be stored is significantly reduced as you will not be storing the same name and URI for every single Asset.

For example if all your Assets had the same naming structure of Example Asset #1 through to Example Asset #1000 this would normally require you to store the string Example Asset # 1000 times, taking up 15,000 bytes.

By storing the prefix of the name in the the Core Candy Machine and letting the Core Candy Machine append the index number created to the string you save these 15,000 bytes in rent cost.

This also applies to the URI prefix.

ConfigLineSettings = {
    prefixName: string;
    nameLength: number;
    prefixUri: string;
    uriLength: number;
    isSequential: boolean;
}

prefixName Field

The prefixName stores the name prefix of the assets and appends the minted index to the end of the name upon mint.

If your Asset's have a naming structure of Example Asset #1 then your prefix would be Example Asset #. Upon mint the Core Candy Machine will attach the index to the end of the string.

nameLength Field

The nameLength is the maximum length for the name of each inserted item excluding the name prefix.

For Example given...

• a candy machine containing 1000 items.
• The name of each item is Example Asset #X where X is the item's index starting from 1.

... would result in 19 characters that would need to be stored. 15 characters for "My NFT Project #" and 4 characters for the highest number which is "1000". When using the prefixName the nameLength instead can be reduced to 4.

prefixUri Field

The prefixUri is the base URI of your metadata excluding the variable identification id.

If your Asset's will have a metadata URI of https://example.com/metadata/0.json then your base metadata URI will be https://example.com/metadata/.

uriLength Field

The uriLength is the maximum length of your URIs excluding the prefixUri.

For Example given...

• a base URI https://arweave.net/ with 20 characters.
• and a unique unifier with a maximum length of 43 characters

... without prefix would result in 63 required characters to store. When using the prefixUri the uriLength can be reduced by 20 characters for https://arweave.net/ to the 43 characters for the unique identifier.

isSequential Field

The isSequential field indicates whether assets are minted in sequential order or pseudo-randomly. When set to false, the Candy Machine mints in a pseudo-random order. Hidden Settings always mint sequentially regardless of this field.

Config Line Settings Example

Here is an example of creating a Core Candy Machine with configLineSettings applied:

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

const candyMachine = generateSigner(umi)

const coreCollection = publicKey('11111111111111111111111111111111')

const createIx = await create(umi, {
  candyMachine,
  collection: coreCollection,
  collectionUpdateAuthority: umi.identity,
  itemsAvailable: 5000,
  configLineSettings: some({
    prefixName: 'Example Asset #',
    nameLength: 15,
    prefixUri: 'https://example.com/metadata/',
    uriLength: 29,
    isSequential: false,
  }),
})

await createIx.sendAndConfirm(umi)

Hidden Settings Field

Hidden Settings configures the Core Candy Machine to mint identical placeholder assets to all buyers, enabling the popular "reveal" mechanic where final metadata is assigned at a later date. It also supports printing Core Editions when combined with the Edition Guard.

hiddenSettings = {
  name: string,
  uri: string,
  hash: Uint8Array,
}

Hidden Settings name Field

The name is the name that appears on all assets minted with Hidden Settings enabled. Note that, just like for the prefixes of the Config Line Settings, special variables can be used for the Name and URI of the Hidden Settings. As a reminder, these variables are:

• $ID$: This will be replaced by the index of the minted Asset starting at 0.
• $ID+1$: This will be replaced by the index of the minted Asset starting at 1.

You should use this to be able to match the Assets that you want to your revealed data.

Hidden Settings uri Field

The uri is the metadata URI that appears on all assets minted with Hidden Settings enabled. This typically points to a shared placeholder JSON file.

Hidden Settings hash Field

The hash stores a cryptographic hash/checksum of the reveal data, allowing anyone to verify that the final revealed metadata matches the originally committed order. This prevents tampering such as rearranging rare assets to specific holders after minting.

import crypto from 'crypto'

const revealData = [
  { name: 'Nft #1', uri: 'http://example.com/1.json' },
  { name: 'Nft #2', uri: 'http://example.com/2.json' },
  { name: 'Nft #3', uri: 'http://example.com/3.json' },
]

const string = JSON.stringify(revealData)
const hash = crypto.createHash('sha256').update(string).digest()

console.log(hash)

Hidden Settings Creation Example

import { create } from '@metaplex-foundation/mpl-core-candy-machine'
import crypto from "crypto";

const candyMachine = generateSigner(umi)

const revealData = [
  { name: 'Nft #1', uri: 'http://example.com/1.json' },
  { name: 'Nft #2', uri: 'http://example.com/2.json' },
  { name: 'Nft #3', uri: 'http://example.com/3.json' },
]

const string = JSON.stringify(revealData)
const hash = crypto.createHash('sha256').update(string).digest()

const createIx = await create(umi, {
  candyMachine,
  collectionMint: collectionMint.publicKey,
  collectionUpdateAuthority,
  sellerFeeBasisPoints: percentAmount(10),
  itemsAvailable: 5000,
  hiddenSettings: {
    name: "Hidden Asset",
    uri: "https://example.com/hidden-asset.json",
    hash,
  }
})

await createIx.sendAndConfirm(umi)

Creating a Core Candy Machine with Guards

The create function accepts a guards field that attaches guard rules directly at creation time, controlling who can mint, when, and at what cost.

So far, the Core Candy Machine we created did not have any guards enabled. Now that we know all the guards available to us, let's see how we can set up new Candy Machines with some guards enabled.

The concrete implementation will depend on which SDK you are using (see below) but the main idea is that you enable guards by providing their required settings. Any guard that has not been set up will be disabled.

import { some, sol, dateTime } from '@metaplex-foundation/umi'

const createIx = await create(umi, {
  // ...
  guards: {
    botTax: some({ lamports: sol(0.01), lastInstruction: true }),
    solPayment: some({ lamports: sol(1.5), destination: treasury }),
    startDate: some({ date: dateTime('2023-04-04T16:00:00Z') }),
    // All other guards are disabled...
  },
})

await createIx.sendAndConfirm(umi)

Notes

• Config Line Settings and Hidden Settings are mutually exclusive. You must choose one or the other. Passing both to the create instruction will result in an error.
• Rent costs scale with item count and storage mode. Config Line Settings with short prefixes are cheaper than storing full names and URIs. Hidden Settings are the cheapest option because only a single name, URI, and hash are stored.
• The collection update authority must be a signer. The Candy Machine needs the collection update authority to sign the creation transaction so it can be approved as a verified delegate on the collection.
• Pseudo-random minting order is not cryptographically secure. When isSequential is set to false in Config Line Settings, the minting order is shuffled but can be predicted or influenced with sufficient resources. Use Hidden Settings with a reveal mechanic when unpredictability is important.
• This page covers Core Candy Machine, not legacy Candy Machine V3. Core Candy Machine mints Core assets. For minting Metaplex Token Metadata NFTs, see Candy Machine V3 instead.

FAQ

What is the difference between Config Line Settings and Hidden Settings?

Config Line Settings store individual asset names and URIs on-chain using prefix compression to reduce rent. Hidden Settings mint identical placeholder assets to all buyers, enabling a reveal mechanic at a later date. Only one can be used per Candy Machine because they are mutually exclusive.

How much does it cost to create a Core Candy Machine?

The rent cost depends on the number of items and the storage mode chosen. Config Line Settings with short prefixes reduce rent significantly because repeated prefixes are stored only once. Hidden Settings are the cheapest because only a single name, URI, and SHA-256 hash are stored regardless of how many items the Candy Machine holds.

Can I add guards after creating a Core Candy Machine?

Yes. You can create a separate Candy Guard account and set it as the mint authority of an existing Core Candy Machine at any time. Alternatively, you can pass guards directly in the create instruction for convenience.

Do I need an existing Core Collection before creating a Candy Machine?

Yes. The create instruction requires a Core Collection address. The collection update authority must sign the transaction so the Candy Machine can register as a verified delegate that adds minted assets to the collection.

What happens if isSequential is set to false in Config Line Settings?

The Candy Machine mints assets in a pseudo-random order rather than in index order. This randomness is not cryptographically secure and can be influenced with sufficient resources. When unpredictability is critical, prefer Hidden Settings with a reveal mechanic instead.