Preparing Assets for a Core Candy Machine

Summary

Preparing assets for a Core Candy Machine requires uploading image files and JSON metadata to a storage provider, then creating a Core Collection that groups all minted assets together.

• Upload image and animation files to decentralized storage such as Arweave (via Irys) or IPFS, or to a self-hosted solution
• Build JSON metadata files following the Metaplex token standard, embedding the uploaded image URIs
• Upload completed JSON metadata files and record the resulting URIs for use as config lines
• Create a Core Collection to serve as the parent for all assets minted from the Candy Machine

Required Asset Files

Every Core asset minted from a Core Candy Machine requires two categories of prepared files before the machine can be created and populated. These include:

• Image and animation files.
• JSON Metadata files.

Supported Asset Types

Core assets support five media categories that determine how wallets and marketplaces render the content:

• image
• video
• audio
• vr
• html

Preparing Image Files

Image files serve as the primary visual representation of each asset and are displayed across all wallets and marketplaces. While there are no enforced format restrictions, it is best practice to optimize images for web delivery. Not all users have access to high-speed internet connections -- users in remote areas may struggle to load large files, so keeping images under 1 MB improves the experience for your entire audience.

Even if your asset is of the type audio, video, html, or vr it is still worth preparing images as these will be used as fallback for areas such as wallets or marketplaces that may not support the loading of the other asset types.

Preparing Animation and Media Files

Animation and media files cover the remaining asset categories: audio, video, vr, and html. The same file-size considerations that apply to images apply here -- keep files as small as practical to minimize download times for end users.

The following file types have been tested and confirmed working in nearly all major wallets and marketplaces.

• video (.mp4)
• audio (.wav, .mp3)
• vr (.glb)
• html (.html)

Preparing JSON Metadata Files

JSON metadata files define the on-chain attributes, name, description, and media references for each asset. These files follow the same token standard used by other Metaplex asset types including NFTs, pNFTs, and cNFTs.

Automated Image and Metadata Generators

Several open-source scripts and web applications can generate large batches of asset images and JSON metadata files from layered artwork. You supply art layers and project parameters, and the generator produces the full set of image-metadata pairs.

Uploading Asset Files

All image and animation files must be uploaded to a storage provider before they can be referenced in JSON metadata. The choice of storage provider affects permanence, cost, and decentralization.

Storage Options

Arweave/Irys

"The Arweave network is like Bitcoin, but for data: A permanent and decentralized web inside an open ledger." - arweave.org

As Arweave is it's own blockchain we need to use a bridge in order to get our files stored on Arweave. Irys acts as a middle man between Solana and Arweave allowing you to pay for storage in SOL instead of AR while they handle the uploading of data to the Arweave chain for you.

You can either implement this manually via their own SDK or use an Umi storage plugin to upload to Arweave via Irys.

Self Hosting

Self-hosting on AWS, Google Cloud, or your own web server is a valid option for storing images and metadata. As long as the data is accessible from its stored location and is not blocked by CORS restrictions, it will work. It is advisable to create a few test Core assets or a small Core Candy Machine first to verify that self-hosted files display correctly in wallets and marketplaces.

Uploading Files with Umi

Umi provides storage plugins that simplify the upload process. The following plugins are currently supported:

• Irys
• AWS

Uploading to Arweave via Irys with Umi

For a more in-depth guide on uploading files with Umi, visit Umi Storage.

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
import { irysUploader } from '@metaplex-foundation/umi-uploader-irys'

const umi = createUmi("https://api.devnet.solana.com").use(irysUploader())

const uriUploadArray = await umi.uploader.upload([myFile1, myFile2])

console.log(uriUploadArray)

Assigning Image URIs to JSON Metadata

Once all image and animation files have been uploaded to a storage provider, the returned URIs must be inserted into each corresponding JSON metadata file. If your asset collection has 1,000 assets, you should have uploaded 1,000 images or animation files and received back a set of URIs indicating where each file is stored. You may need to manually log and store links if your upload platform does not support batch uploads.

The goal at this point is to have a complete list of URIs for all uploaded media.

[
  https://example.com/1.jpg
  https://example.com/2.jpg
  ...
]

With the indexed URI list of uploaded media you will then need to loop through your JSON metadata files and add the URIs to the appropriate places.

Image URIs would be inserted into the image: field, and also into the properties: files: [] array.

{
  "name": "My Nft #1",
  "description": "This is My Nft Collection",
  "image": "https://example.com/1.jpg", <---- Fill here.
  ...
  "properties": {
    "files": [
      {
        "uri": "https://example.com/1.jpg",
        "type": "image/jpg"
      }, <---- Make an object entry into the files array.
    ]
  }
}

Uploading JSON Metadata Files

At this point you should have a folder of JSON metadata files locally built out on your machine that look similar to this:

{
  "name": "My Nft #1",
  "description": "This is My Nft Collection",
  "image": "https://example.com/1.jpg",
  "external_url": "https://example.com",
  "attributes": [
    {
      "trait_type": "trait1",
      "value": "value1"
    },
    {
      "trait_type": "trait2",
      "value": "value2"
    }
  ],
  "properties": {
    "files": [
      {
        "uri": "https://example.com/1.jpg",
        "type": "image/jpg"
      }
    ],
    "category": "image"
  }
}

You will need to upload all your JSON metadata to a storage medium of choice and again log all the URIs for future use.

Creating a Core Collection

The final step in asset preparation is creating a Core Collection that the Core Candy Machine uses to group all minted assets together. This requires the mpl-core package.

The below example creates a basic Core Collection with no plugins. To view a list of available plugins and more advanced Core Collection creation you can view the documentation at Collection Management.

import { generateSigner, umi } from '@metaplex-foundation/umi'
import { createCollectionV1 } from '@metaplex-foundation/mpl-core'

const mainnet = 'https://api.mainnet-beta.solana.com'
const devnet = 'https://api.devnet.solana.com'

const keypair = // assign keypair

const umi = createUmi(mainnet)
.use(keypairIdentity(keypair)) // Assign identity signer of your choice.
.use(mplCore())

const collectionSigner = generateSigner(umi)

await createCollectionV1(umi, {
  collection: collectionSigner,
  name: 'My Collection',
  uri: 'https://example.com/my-collection.json',
}).sendAndConfirm(umi)

Notes

• Optimize all images for web delivery. Keep file sizes under 1 MB where possible to ensure fast loading across devices and network conditions.
• When self-hosting assets, verify that CORS headers are configured correctly. Assets blocked by CORS will not render in wallets or marketplaces.
• Store all uploaded URIs securely and back them up. Losing the URI list after uploading images means you cannot link metadata to the correct files.
• Arweave storage is permanent and immutable. Double-check file contents before uploading because you cannot delete or modify files once they are stored on Arweave.
• JSON metadata files must be uploaded after image files because metadata references image URIs that are only available after the upload completes.

Conclusion

At this point you should have completed all the preparations needed in order to create a Core Candy Machine.

• Upload images and other media files.
• Assign image and media file URIs to JSON Metadata files.
• Upload JSON Metadata files and stored URIs.
• Created a Core Collection.

FAQ

What image format is best for Core Candy Machine assets?

PNG and JPEG are the most widely supported formats across wallets and marketplaces. PNG is ideal for pixel art or images requiring transparency, while JPEG works well for photographic or high-detail artwork at smaller file sizes. Optimize images for web delivery to keep file sizes under 1 MB where possible.

What storage provider should I use for NFT metadata and images?

Arweave (via Irys) is the most popular choice because it provides permanent, decentralized storage paid in SOL. IPFS is another decentralized option but requires pinning services to ensure persistence. Self-hosted solutions (AWS, Google Cloud) work but introduce centralization and ongoing maintenance costs.

Can I use IPFS for Core Candy Machine assets?

Yes, IPFS URIs work with Core Candy Machine assets. However, you must use a pinning service such as Pinata, nft.storage, or a dedicated IPFS node to ensure your files remain accessible. Unpinned IPFS content may become unavailable over time.

Do I need to upload images before creating JSON metadata files?

Yes. The JSON metadata files reference image URIs in their image field and properties.files array. You must upload all image and animation files first, collect their URIs, and then insert those URIs into each corresponding JSON metadata file before uploading the metadata itself.

How many files do I need to prepare for a 1,000-item collection?

For a 1,000-item collection you need at minimum 1,000 image files and 1,000 JSON metadata files, plus one additional image and one JSON metadata file for the Core Collection itself. If your assets include animation files (video, audio, VR, HTML), you will also need 1,000 animation files.

Glossary