Updating a Core Candy Machine

Summary

The updateCandyMachine function modifies a Core Candy Machine's on-chain settings after initial creation, while updateCandyGuard lets you change the guards that control minting access.

• Update Candy Machine data fields such as itemsAvailable, isMutable, Config Line Settings, and Hidden Settings
• Reassign the mint authority to a new wallet using setMintAuthority
• Modify guard rules with updateCandyGuard -- note that the entire guards object is replaced on each update
• Manually associate or dissociate Candy Guard accounts using wrap and unwrap {.lead}

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

const candyMachine = generateSigner(umi)

await updateCandyMachine(umi, {
  candyMachine,
  data: {
    itemsAvailable: 3333;
    isMutable: true;
    configLineSettings: none();
    hiddenSettings: none();
}
}).sendAndConfirm(umi)

Update Function Arguments

The updateCandyMachine function accepts the Candy Machine public key and a data object containing the fields to modify.

Candy Machine Data Object

The data object defines the mutable settings of a Core Candy Machine. Pass this object to updateCandyMachine with the fields you want to change.

data =  {
    itemsAvailable: number | bigint;
    isMutable: boolean;
    configLineSettings: OptionOrNullable<ConfigLineSettingsArgs>;
    hiddenSettings: OptionOrNullable<HiddenSettingsArgs>;
}

Assigning a New Authority

The setMintAuthority function transfers the Core Candy Machine's mint authority to a new wallet address. Both the current authority and the new authority must sign the transaction.

export declare type SetMintAuthorityInstructionAccounts = { /Candy Machine account. */ candyMachine: PublicKey | Pda; / Candy Machine authority / authority?: Signer; /** New candy machine authority/ mintAuthority: Signer; };

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

const candyMachine = publicKey('11111111111111111111111111111111')
const newAuthority = publicKey('22222222222222222222222222222222')

await setMintAuthority(umi, {
  candyMachine,
  mintAuthority: newAuthority,
}).sendAndConfirm(umi)

Updating Candy Guards

The updateCandyGuard function replaces the entire guards configuration on a Candy Guard account. Use it to change mint prices, adjust start dates, enable new guards, or disable existing ones.

You can enable new guards by providing their settings or disable current ones by giving them empty settings.

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

const candyGuard = await fetchCandyGuard(umi, candyGuardId)
await updateCandyGuard(umi, {
  candyGuard: candyGuard.publicKey,
  guards: {
    ...candyGuard.guards,
    botTax: none(),
    solPayment: some({ lamports: sol(3), destination: treasury }),
  },
  groups: [
    // Either empty, or if you are using groups add the data here
  ]
})

Wrapping and Unwrapping Candy Guard Accounts

Wrapping associates a Candy Guard with a Core Candy Machine so that the guard rules are enforced during minting. Unwrapping dissociates them. Most projects create both accounts together, but you can manage them independently when needed.

You will first need to create the two accounts separately and associate/dissociate them manually.

import {
  some,
  percentAmount,
  sol,
  dateTime
} from '@metaplex-foundation/umi'
import {
  createCandyMachine,
  createCandyGuard,
  findCandyGuardPda,
  wrap,
  unwrap
} from '@metaplex-foundation/mpl-core-candy-machine'

// Create a Candy Machine without a Candy Guard.
const candyMachine = generateSigner(umi)
await createCandyMachine({
  candyMachine,
  tokenStandard: TokenStandard.NonFungible,
  collectionMint: collectionMint.publicKey,
  collectionUpdateAuthority: umi.identity,
  itemsAvailable: 100,
  sellerFeeBasisPoints: percentAmount(1.23),
  creators: [
    {
      address: umi.identity.publicKey,
      verified: false,
      percentageShare: 100
    },
  ],
  configLineSettings: some({
    prefixName: 'My NFT #',
    nameLength: 3,
    prefixUri: 'https://example.com/',
    uriLength: 20,
    isSequential: false,
  }),
}).sendAndConfirm(umi)

// Create a Candy Guard.
const base = generateSigner(umi)
const candyGuard = findCandyGuardPda(umi, { base: base.publicKey })
await createCandyGuard({
  base,
  guards: {
    botTax: { lamports: sol(0.01), lastInstruction: false },
    solPayment: { lamports: sol(1.5), destination: treasury },
    startDate: { date: dateTime('2022-10-17T16:00:00Z') },
  },
}).sendAndConfirm(umi)

// Associate the Candy Guard with the Candy Machine.
await wrap({
  candyMachine: candyMachine.publicKey,
  candyGuard,
}).sendAndConfirm(umi)

// Dissociate them.
await unwrap({
  candyMachine: candyMachine.publicKey,
  candyGuard,
}).sendAndConfirm(umi)

Notes

• Some Candy Machine settings -- including itemsAvailable -- are locked once the first item has been minted. Finalize all data fields before minting begins.
• Calling updateCandyGuard replaces the entire guards object. Always fetch the current guard state and spread existing values before applying changes, or you will unintentionally disable active guards.
• The Core Candy Machine authority and the collection asset update authority must match. If you reassign authority with setMintAuthority, update the collection asset authority as well.
• Wrapping and unwrapping are separate from guard creation. A Candy Guard has no effect on minting until it is wrapped (associated) with a Candy Machine.

FAQ

Can I change the itemsAvailable count after minting has started?

No. Some Core Candy Machine settings, including itemsAvailable, are locked once the first item has been minted. Update these fields before any minting occurs.

Does updating Candy Guards replace all existing guard settings?

Yes. The updateCandyGuard function overwrites the entire guards object. You must include all guards you want to keep, even if their settings have not changed. Fetch the current guard account first and spread its values into your update call.

Do I need to update the collection authority when I reassign the Candy Machine authority?

Yes. The Core Candy Machine authority and the collection asset update authority must match. After calling setMintAuthority, update the collection asset to use the same new authority.

What is the difference between wrapping and unwrapping a Candy Guard?

Wrapping associates a Candy Guard account with a Core Candy Machine so the guard rules are enforced during minting. Unwrapping dissociates them, removing guard enforcement. Most projects keep guards wrapped at all times.