Skip to content

internet-court/internet-court-skill / vendored/metaplex/metaplex

metaplex

Verified

Metaplex development on Solana — NFTs, tokens, compressed NFTs, candy machines, token launches, autonomous agents. Use when working with Token Metadata, Core, Bubblegum, Candy Machine, Genesis, Agent Registry, or the mplx CLI.

references/cli-candy-machine.md

View on GitHub
# Core Candy Machine CLI Reference

Candy Machine enables NFT drops with configurable minting rules (guards).

> **Prerequisites**: CLI must be configured (RPC, keypair, funded wallet). If not yet verified this session, see `./cli-initial-setup.md`.

---

## Directory Structure

```
my-candy-machine/
├── assets/
│   ├── 0.png                 # Image for NFT #0
│   ├── 0.json                # Metadata for NFT #0
│   ├── 1.png
│   ├── 1.json
│   ├── 2.png
│   ├── 2.json
│   ├── ...
│   ├── collection.png        # Collection image (required)
│   └── collection.json       # Collection metadata (must have "name" field)
├── asset-cache.json          # Generated after upload
└── cm-config.json            # Generated by wizard or created manually
```

**Asset naming**: Files must be numbered starting from 0 (0.png, 0.json, 1.png, 1.json, etc.)

**collection.json example** (follows the NFT metadata standard — see `metadata-json.md`; use relative image path, CM CLI replaces with uploaded URI):
```json
{
  "name": "My Collection",
  "description": "A collection of NFTs",
  "image": "collection.png",
  "external_url": "https://yourproject.com",
  "attributes": [],
  "properties": {
    "files": [{ "uri": "collection.png", "type": "image/png" }],
    "category": "image"
  }
}
```

**Individual asset JSON example** (0.json, 1.json, etc. — same standard, see `metadata-json.md`):
```json
{
  "name": "NFT #0",
  "description": "Description here",
  "image": "0.png",
  "external_url": "https://yourproject.com",
  "attributes": [
    { "trait_type": "Background", "value": "Blue" }
  ],
  "properties": {
    "files": [{ "uri": "0.png", "type": "image/png" }],
    "category": "image"
  }
}
```

---

## Workflow Option 1: Wizard (Recommended)

```bash
mplx cm create --wizard
```

The wizard handles everything:
1. Validates assets and configuration
2. Uploads all assets with progress tracking
3. Creates the candy machine on-chain
4. Inserts all items with transaction progress
5. Provides completion summary with links

---

## Workflow Option 2: Manual

```bash
# 1. Create template directory structure
mplx cm create --template

# 2. Add your assets to the assets/ folder
#    - 0.png, 0.json, 1.png, 1.json, etc.
#    - collection.png, collection.json
# 3. Create a Core collection for the candy machine
mplx core collection create

# 4. Edit cm-config.json: add the collection address, configure guards, etc.
#    The "collection" field MUST contain a valid Core collection address.

# 5. Upload assets to storage
mplx cm upload

# 6. Create candy machine (reads cm-config.json)
mplx cm create

# 7. Insert items into candy machine
mplx cm insert

# 8. Validate (optional but recommended)
mplx cm validate --onchain
```

> **Note:** You MUST create a Core collection first (e.g. with `mplx core collection create`) and add its address to the `"collection"` field in `cm-config.json` before running `mplx cm create`. The CLI does NOT create the collection automatically — it will error if no collection address is provided.

---

## Commands Reference

```bash
mplx cm create --wizard              # Interactive wizard (does everything)
mplx cm create --template            # Create template directory
mplx cm create <DIR>                 # Create from existing cm-config.json
mplx cm upload <DIR>                 # Upload assets to storage
mplx cm insert <DIR>                 # Insert items into candy machine
mplx cm validate <DIR>               # Validate uploads
mplx cm validate <DIR> --onchain     # Validate items inserted on-chain
mplx cm fetch <ADDR>                 # Fetch candy machine info
mplx cm fetch <ADDR> --items         # Fetch with all items
mplx cm withdraw                     # Withdraw from CM directory (reads cm-config.json)
mplx cm withdraw <DIR>               # Withdraw and delete (recovers rent)
mplx cm withdraw --address <ADDR>    # Withdraw by address
```

---

## Guards Configuration

Guards control who can mint, when, and at what cost.

### Available Guards

| Category | Guards |
|----------|--------|
| **Payment** | `solPayment`, `solFixedFee`, `tokenPayment`, `token2022Payment`, `nftPayment`, `assetPayment`, `assetPaymentMulti` |
| **Access Control** | `addressGate`, `allowList`, `nftGate`, `tokenGate`, `assetGate`, `programGate`, `thirdPartySigner` |
| **Time-Based** | `startDate`, `endDate` |
| **Limits** | `mintLimit`, `allocation`, `nftMintLimit`, `assetMintLimit`, `redeemedAmount` |
| **Burn Guards** | `nftBurn`, `tokenBurn`, `assetBurn`, `assetBurnMulti` |
| **Special** | `botTax`, `edition`, `vanityMint` |
| **Freeze** | `freezeSolPayment`, `freezeTokenPayment` |

### cm-config.json Example

The config uses a nested `name/directory/config` wrapper format:

```json
{
  "name": "my-candy-machine",
  "directory": "/path/to/my-candy-machine",
  "config": {
    "collection": "<COLLECTION_ADDRESS>",
    "itemsAvailable": 10,
    "isMutable": true,
    "isSequential": false,
    "guardConfig": {
      "solPayment": {
        "lamports": 1000000000,
        "destination": "<PAYMENT_WALLET>"
      },
      "startDate": {
        "date": "2024-01-01T00:00:00Z"
      },
      "mintLimit": {
        "id": 1,
        "limit": 1
      },
      "botTax": {
        "lamports": 10000000,
        "lastInstruction": true
      }
    },
    "groups": []
  }
}
```

Key fields: `itemsAvailable` (not `number`), `collection` (must be set before `mplx cm create`). `sellerFeeBasisPoints` is set at the collection level (when creating the Core collection), not in the candy machine config.

### Guard Groups (Multiple Minting Phases)

Use `groups` instead of `guardConfig` to create separate minting phases (e.g., whitelist then public). Set `guardConfig: {}` when using groups.

```json
"groups": [
  {
    "label": "wl",
    "guards": {
      "allowList": {
        "merkleRoot": "<MERKLE_ROOT_HASH>"
      },
      "solPayment": {
        "lamports": 500000000,
        "destination": "<PAYMENT_WALLET>"
      },
      "startDate": {
        "date": "2024-01-01T00:00:00Z"
      }
    }
  },
  {
    "label": "public",
    "guards": {
      "solPayment": {
        "lamports": 1000000000,
        "destination": "<PAYMENT_WALLET>"
      },
      "startDate": {
        "date": "2024-01-02T00:00:00Z"
      }
    }
  }
]
```

---

## Common Guard Configurations

### SOL Payment

```json
"solPayment": {
  "lamports": 1000000000,
  "destination": "<WALLET_ADDRESS>"
}
```
Note: 1 SOL = 1,000,000,000 lamports

### Start/End Date

```json
"startDate": {
  "date": "2024-01-01T00:00:00Z"
},
"endDate": {
  "date": "2024-01-31T23:59:59Z"
}
```

### Mint Limit (per wallet)

```json
"mintLimit": {
  "id": 1,
  "limit": 3
}
```

### Allow List (whitelist)

```json
"allowList": {
  "merkleRoot": "<MERKLE_ROOT_HASH>"
}
```

To generate the Merkle root from a list of wallet addresses, use the Umi SDK:

```typescript
import { getMerkleRoot } from '@metaplex-foundation/mpl-core-candy-machine';
const merkleRoot = getMerkleRoot(['Addr1...', 'Addr2...']);
const merkleRootHex = Buffer.from(merkleRoot).toString('hex');
```

When minting with an allowlist, the minter must provide a Merkle proof (see Minting section below).

### Bot Tax

```json
"botTax": {
  "lamports": 10000000,
  "lastInstruction": true
}
```
Charges failed mints to deter bots.

---

## Withdrawing

After all items are minted (or to cancel):

```bash
# From directory with cm-config.json
mplx cm withdraw

# Or by address
mplx cm withdraw --address <CANDY_MACHINE_ADDRESS>

# Force without confirmation
mplx cm withdraw --force
```

⚠️ **WARNING**: Withdrawing permanently deletes the candy machine. Non-redeemed items are lost.

---

## Minting from a Candy Machine

The CLI **creates and configures** candy machines but does not have a mint command. Minting requires the Umi SDK (`@metaplex-foundation/mpl-core-candy-machine`).

- **Frontend app** — Build a minting UI with the Umi SDK
- **Script** — Mint programmatically with `mintV1` from the SDK

See `./sdk-umi.md` for Umi setup and the [Candy Machine documentation](https://metaplex.com/docs/smart-contracts/core-candy-machine/guards) for minting code examples and guard-specific mint args.

---

## Localnet Limitations

The `mplx cm upload` step requires Irys storage and **will not work on localnet**. For localnet testing, you can skip the upload step by manually creating an `asset-cache.json` file with pre-populated URIs:

```json
{
  "assetItems": {
    "0": {
      "name": "My NFT #0",
      "image": "0.png",
      "json": "0.json",
      "loaded": false,
      "onChain": false,
      "imageType": "image/png",
      "imageUri": "https://example.com/0.png",
      "jsonUri": "https://example.com/0.json"
    }
  }
}
```

With this cache in place, you can proceed directly to `mplx cm create` and `mplx cm insert`.

---

## Best Practices

1. **Test on devnet first** before mainnet deployment
2. **Validate assets** before uploading: consistent naming (0.png, 0.json, etc.)
3. **Keep file sizes reasonable** (< 10MB per image recommended)
4. **Include collection.json** with a valid "name" field
5. **Add at least one guard** (otherwise anyone can mint for free)
6. **Save explorer links** for verification
7. **Back up cm-config.json** after creation

## For more info

Consult these Metaplex docs when you need deeper detail than this reference provides:

- Core Candy Machine: https://metaplex.com/docs/smart-contracts/core-candy-machine
- Overview: https://metaplex.com/docs/smart-contracts/core-candy-machine/overview
- Create: https://metaplex.com/docs/smart-contracts/core-candy-machine/create
- Insert items: https://metaplex.com/docs/smart-contracts/core-candy-machine/insert-items
- Guards: https://metaplex.com/docs/smart-contracts/core-candy-machine/guards
- Guard groups: https://metaplex.com/docs/smart-contracts/core-candy-machine/guard-groups
- Mint: https://metaplex.com/docs/smart-contracts/core-candy-machine/mint
- Preparing assets: https://metaplex.com/docs/smart-contracts/core-candy-machine/preparing-assets
- Withdrawing: https://metaplex.com/docs/smart-contracts/core-candy-machine/withdrawing-a-candy-machine
- Anti-bot best practices: https://metaplex.com/docs/smart-contracts/core-candy-machine/anti-bot-protection-best-practices
- CLI Candy Machine: https://metaplex.com/docs/dev-tools/cli/cm
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall