Thread by @pencilflip

The 🍬 Candy Machine 🍬 is a program built by @redacted_j and @baalazamon that's commonly used to mint Solana NFT collections.

This thread is about how the program works (not how to use the Candy Machine for your own collection).

Let's go! 👇

1/ First, if you want a simpler, shorter explanation, check out this comic!

https://twitter.com/TheMycoverse/status/1459955643893227523

2/ Now, some preliminary resources.

If you don't understand Solana's account model, check out this thread

https://twitter.com/pencilflip/status/1452402100470644739

3/ If you don't understand PDAs, check out this thread

https://twitter.com/pencilflip/status/1455948263853600768

4/ Finally, if you don't understand SPL tokens, check out this thread

https://twitter.com/pencilflip/status/1454141877972779013

5/ Alright, who's left? 😆 If you've got the above stuff covered, props to you! It certainly took me a while to understand it all.

Now, let's dive into the Candy Machine program.

6/ I'll give a birds-eye view before getting into the details.

The Candy Machine program lets the creator of an NFT collection create a Candy Machine account, i.e. an account that stores info about the collection.

Typically, this is done via Candy Machine's CLI.

7/ Once a Candy Machine account has been created, users can start minting NFTs.

Typically, this is done via the collection's website.

The minting code reads from the Candy Machine account to determine things like NFT price.

8/ That was the high-level overview. Let's go deeper.

There are three main steps to creating a Candy Machine account.

9/ 🍬 Creation Step #1 🍬

The nft_candy_machine::initialize_config instruction initializes a config account that contains config data.

For example, the config data includes the NFT collection's symbol, and how much royalties go to creators (for secondary sales).

10/ Here's a diagram of all the accounts in play so far. It's quite simple for now.

11/ 🍬 Creation Step #2 🍬

The nft_candy_machine::add_config_lines instruction adds lines to the config account.

There is one line per NFT, and each line contains the NFT's name and a URI pointing to its metadata.

12/ This step changes nothing about our account diagram. The only difference is that the config account has had some data added to it.

13/ 🍬 Creation Step #3 🍬

The nft_candy_machine::initialize_candy_machine instruction creates and initializes an account that contains more info about the Candy Machine.

I'm not sure why this is separated from the config data, maybe to keep account sizes down?

14/ This account stores info like how many items are in the collection, the collection's go-live-date, and the price of each NFT in the collection.

15/ Notably, the Candy Machine account is a PDA account.

The config account's address and a UUID are used as seeds.

This means that many Candy Machine accounts can be associated with a single config account, but they must have different UUIDs.

16/ Here's an updated account diagram. It's started to get more complicated 😬

Some things to note:
- The token mint account (on the left) is optional. If it exists, the Candy Machine accepts payment in that token. Otherwise, the Candy Machine accepts payment in SOL.

17/ (continued from above)

- The Candy Machine's wallet is where minting proceeds go.
- The Candy Machine's authority is the only account allowed to modify the Candy Machine (e.g. update the go-live-date) via the Candy Machine program.

18/ Alright, that's it for Candy Machine creation! Let's recap:

- First, a config account is initialized
- Then, lines are added to the config account, one per NFT
- Finally, the Candy Machine account is created

At the end of it all, the accounts look like this

19/ 🍬 Minting 🍬

At this point, the Candy Machine has been created, and fans of the collection can start minting!

This is done via the nft_candy_machine::mint_nft instruction.

20/ This instruction is more complicated to grok because it makes a bunch of CPIs to Metaplex's token metadata program.

One important thing to know is that this instruction DOES NOT MINT AN NFT.

Yes, the name is misleading.

21/ This instruction assumes the following:

- The NFT's mint account has been created
- A token account has been created for that mint account
- One token has been minted to the token account

So technically, the NFT has already been minted before the mint_nft instruction runs.

22/ If you don't believe me, check out this tx on Solana Explorer.

The 5th instruction is nft_candy_machine::mint_nft. The previous instructions create the mint account, create the token account, and mint a single token to the token account.

explorer.solana.com/tx/3m4X93TR8TJ…

23/ So, what does the mint_nft instruction do? Three main things:

1. Transfers SOL (or SPL tokens) from the minter to the CM's wallet (payment for the NFT)
2. Calls metaplex_token_metadata::create_metadata_accounts
3. Calls metaplex_token_metadata::create_master_edition

24/ Let's dig into steps 2 & 3.

create_metadata_accounts, unsurprisingly, creates a metadata account.

A metadata account is a PDA, ensuring there can only be ONE metadata account per token mint. See the linked tweet for how the PDA is derived.

https://twitter.com/pencilflip/status/1458121134344441868

25/ The metadata account contains a bunch of info.

One particularly interesting field is the "uri" field.

This field points to a JSON file that's (usually) stored on Arweave. The file stores more of the NFT's metadata, e.g. its name, description, and a link to its image.

26/ What's the difference between the metadata stored on-chain and stored on Arweave?

The former stores info that needs to be read/written on-chain, like how much royalties are given to creators.

The latter stores info that doesn't need to be accessed on-chain.

27/ create_master_edition creates a master edition account.

What's that? Basically, it dictates whether the NFT can be copied, and how many copies are allowed.

Each copy of a "master edition" is called an "edition."

28/ Here's what's stored in a master edition account.

supply is how many copies have been made.

max_supply is the max amount of copies allowed. If max_supply is 0, it means the NFT is a 1/1.

29/ Above, we said that mint_nft DOES NOT MINT AN NFT.

Instead, it decorates an existing mint account with PDA accounts (token metadata and master edition).

The existence of these PDA accounts shows that the mint account is associated with a specific NFT from some collection.

30/ If the mint account doesn't comply with Metaplex's standards, e.g. if it has a token supply greater than 1, then the mint_nft instruction will fail.

31/ Here's what the accounts look like after nft_candy_machine::mint_nft has been called.

The main thing to note is that the two PDAs on the bottom are created by calling mint_nft.

32/ Alright, that's about it. I skimmed over some important details, but I didn't want to make this thread 100 tweets 😆

33/ Here's a quick recap of how things work.

First, the collection creator tells the Candy Machine program to create new config + Candy Machine accounts. These contain info like the price of NFTs.

34/ Then, when an NFT is being minted, the Candy Machine program uses the associated Candy Machine account to determine how much to charge the minter, the NFT's name and metadata URI, etc.

35/ When it comes down to it, the Candy Machine program is basically a wrapper around Solana's token program.

It provides a nice API for minting a collection of NFTs and associating metadata with them, but at the core of it all are mint accounts and token accounts.

36/ That's not to say that Candy Machine isn't useful—it's incredibly useful, and used by just about every Solana NFT collection out there!

But if you want to understand how it works, don't psych yourself out—there's nothing too magical going on 😛

37/ If you want to read a more detailed version of this thread, check out my blog post!

github.com/arcticmatt/blo…