This is a how-to guide for the developer who wants to use the latest Metaplex sugar, which at the time of this writing is sugar 2.1.1 and/or the developer who wants to deploy a Candy Machine v3 with the option of adding protections for creator royalties. This article consolidates different areas of the Metaplex documentation and what I’ve learned from the experts on the Metaplex Discord to help clarify or point out areas in the docs that might still be out of sync.

I don’t want to repeat things that the Metaplex docs already say — I only want to add notes for developers who might not know where to start, or may be spinning in circles, or may want to avoid skipping certain steps. Because not all of the docs have kept up with the implementation and there are multiple locations within the doc that cover similar topics but for older Candy Machines, it can be challenging sometimes. At least it was for me. This is something I wish I had had when I was ready to send Porcupine Playground Pals into production.

Always test on devnet before going to production!

Getting Started

The How to create a Candy Machine v3 – Part 1 (Sugar) in the Metaplex docs is the first place to start. It points you to how to install the Solana CLI and create a wallet for devnet, so follow those. However, at the Install Sugar step, ignore the stuff about alpha. It’s out of alpha and is the latest release, so go ahead and follow the Installation page.

Once sugar is installed, follow the directions to set up your project with your assets — your images and json files. More information about the structure and contents of your assets is located in the Developer Tools > Sugar: Candy Machine CLI > Guides > Preparing your Assets section, including information about the collection json and collection image.

Then follow the directions to create a config file, which is the first bullet in the outline of my next section. Note: the Developer Tools > Sugar: Candy Machine CLI > Guides > Working with Sugar section includes a video that uses the sugar launch command. launch runs several of the steps below in a row but skips over some optional ones, so I would avoid it.

Sugar Steps Outline

• sugar config create
• (optional) change the tokenStandard to pnft in the config
• (optional) add a ruleset to the config
• (recommended) sugar validate
• sugar upload
• sugar deploy
• (recommended) sugar verify
• (optional) sugar mint
• sugar guard add
• (recommended) sugar guard show
• (if you make guard modifications) sugar guard update
• (if you want to change the tokenStandard and have already deployed) sugar config set -t pnft
• (if you want to change the tokenStandard and have already deployed) sugar config set --ruleset {ruleset address}

Optional Modifications to Config

tokenStandard

If you want all your NFTs to be minted as Programmable NFTs, opening your config.json file now and changing the tokenStandard to pnft is the simplest way to do it. One reason you might be interested in going with pnft is because you could then apply a ruleSet to restrict secondary sales to only those marketplaces committed to honoring the sellerFeeBasisPoints you’ve specified, thereby adding protections for the creator’s royalties on secondary sales.

ruleSet

Rule sets are either allow lists or deny lists of programs that may transfer (or may not transfer) your PNFTs. You have the option to create your own rule set or choose between the two that Metaplex is maintaining: the Metaplex Foundation Rule Set (strict) or Compatibility Rule Set (less strict). According to the Metaplex royalties migration site, the Metaplex Foundation Rule Set is a deny-list, and according to the Metaplex Royalties UI Guide, it is an allow-list, but either way, it may “change over time based on usage and ecosystem feedback” and is curated by Metaplex. I opted for the stricter rule set. The addresses of both are on the official-links of the Metaplex Discord server.

Metaplex Rulesets
Metaplex Foundation Rule Set - eBJLFYPxJmMGKuFwpDWkzxZeUrad92kZRC5BJLpzyT9
Compatability Rule Set - AdH2Utn6Fus15ZhtenW4hZBQnvtLgM1YCW2MfVp7pYS5 

Validate assets

The How to create a Candy Machine v3 – Part 1 (Sugar) does not include this step, but Sugar for Candy Machine V3 does.

sugar validate

If you have any errors, you get a chance to fix them before uploading, so I recommend that you sugar validate.

Upload, Deploy, Verify

Now back to the primary tutorial, How to create a Candy Machine v3 – Part 1 (Sugar). I have nothing to add to the next 3 steps, so follow the instructions for Upload Images and Metadata to External Storage, Deploy a Candy Machine, and Verify Successful Deployment.

Command line mint

The next section in the Metaplex tutorial is Mint an NFT so you know everything is working. With your Solana CLI configured as the creator of the collection, you are able to mint from the command line.

sugar mint

You can confirm that the minted NFT is a PNFT by viewing its metadata on a Solana explorer such as solscan.io, and seeing its tokenStandard is 4. If you left the tokenStandard as nft, it will show as 0.

To verify that your rule set has been applied, we are fortunate that TonyBoyle.sol has shared this View NFT tool among his sol-tools.

You probably don’t want to be the only one who can mint, so to allow others to mint from your candy machine, you can add Candy Guards.

Add solPayment Candy Guard

There are quite a few default Candy Guards you can add to your Candy Machine v3, and you can write your own. You can also have guard groups for more advanced configurations. I am not going to go into details about groups, but I will say that if you do use guard groups, the label for the group cannot exceed 6 characters or you will run into this mysterious error. (Thank you to Discord for someone posting this error and character limitation finding.)

???? Error running command (re-run needed): AnchorError { error_name: "ExceededLength", error_code_number: 6010, error_msg: "Value exceeded maximum length", error_origin: Some(Source(Source { filename: "/Users/runner/.cargo/registry/src/github.com-1ecc6299db9ec823/mpl-candy-guard-1.0.1/src/utils.rs", line: 106 })), compared_values: None }

I’m only going to focus on the solPayment guard because that is the one where you set the price and specify the treasury wallet that receives payment so that others can buy an NFT.The treasury wallet is a single wallet destination. If you specified multiple creators to receive different shares, that is for secondary sales, and does not apply to the initial mint. If you are interested in splitting the payments for the mint into multiple wallets, for example, donating a portion of the proceeds to a donor-advised fund like Porcupine Playground Pals has done, I learned from Metaplex Discord, that you can create a wallet that distributes to other wallets with Hydra. I also learned from Discord that there is a Hydra UI, but I haven’t used it.

Once you add the json for candy guards to your config.json and save the file, you can add the guard.

sugar guard add

When I went live in production, this command failed at the wrap stage! I’ll admit I tried to run the same command repeatedly thinking it might pick up where it left off like sugar upload does, but it kept creating a new guard and failing to wrap it. Agony! I managed to finally get a guard wrapped after manually placing the guard address created the last time I ran the command into my config.json file and running sugar guard add. This time it didn’t create a new guard and the wrap succeeded.

Verify Guards are in place

You can confirm your guards are in place by showing the guard on-chain.

sugar guard show

Modify Guards

You can change the guards locally in your config.json file and update your guards on-chain from the command line.

sugar guard update

Deployed without changing tokenStandard or adding ruleSet?

If you already deployed your collection to mainnet-beta without setting the tokenStandard or adding a ruleSet in your config.json (like I did, smh), it’s not too late. You can still change your Candy Machine v3.

sugar config set -t pnft
sugar config set --ruleset {ruleset address}

All NFTs minted going forward after that will be minted as PNFTs with a rule set in place.

If you are unsure of rule sets but still want the option to apply a rule set later, you can change the config to set the token standard to PNFT, and as I learned on Discord, then later modify the rule set of minted PNFTs using Metaboss, The Solana Metaplex NFT ‘Swiss Army Knife’ tool. For example, you could update one or more minted PNFTs with

metaboss update rule-set --mint {mint address of PNFT} --new-rule-set {ruleset address}

or

metaboss update rule-set-all --mint-list {json file of PNFT addresses} --new-rule-set {ruleset address}

If some NFTs were already minted with the default token standard of “nft” (i.e., shows a “0” in the metadata when viewed on a Solana explorer) and you want to change them to a PNFT, Metaboss is also able to change the token standard with the set command. There are warnings in the Metaboss docs, though, that the tool is for advanced users, so use with caution. “Set commands are either irreversible or require a new update authority to reverse.”

Next Steps

Now that you have deployed and configured your Candy Machine, you are ready to build your mint UI! Move on to Part 2 of this 3-part series.