Skip to content

Add Metaplex skill and official Core fetch flow #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
posaune0423 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add Metaplex skill and official Core fetch flow #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions .agents/memory/todo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,32 @@
# Task Plan: Documentation English Translation (2026-03-12)

# Task Plan: Verify NFT Metadata Reference Path (2026-03-12)

- [x] Inspect the repository paths that mint, fetch, or validate NFT metadata.
- [x] Compare the implementation's expected metadata source with the provided Metaplex metadata object shape.
- [x] Conclude whether the current flow can resolve NFT metadata correctly and note any mismatches.

# Review: Verify NFT Metadata Reference Path (2026-03-12)

- Confirmed the repository is built around Metaplex Core, not Token Metadata account parsing. The program stores `name` and `uri` on the Core asset and resolves richer NFT metadata from the off-chain JSON behind that URI.
- Verified that `mint_doom_index_nft` writes the deterministic URI `{base_metadata_url}/{tokenId}.json` and does not inspect fields such as `data.creators`, `sellerFeeBasisPoints`, `edition`, or `collection.key`.
- Verified that the devnet mint script decodes the Core asset account to get the URI, fetches the JSON document, and currently requires both `image` and `animation_url`.
- Fetched the user-provided URI and confirmed it is reachable over HTTPS and returns JSON, but that sample metadata omits `animation_url`, so it would fail the repository's current DOOM-specific post-mint validation even though generic metadata fetch by URI works.

# Task Plan: Use Official Metaplex Core Patterns (2026-03-12)

- [x] Inspect where the repository hand-rolls Metaplex Core account handling instead of using official Core Anchor / JS helpers.
- [x] Replace on-chain Core account handling with official Anchor account types where applicable.
- [x] Replace handwritten Core asset decoding in scripts with official Metaplex JS SDK fetch paths.
- [x] Update tests and run targeted verification for the refactor.

# Review: Use Official Metaplex Core Patterns (2026-03-12)

- Replaced the mint instruction's `collection` account from `UncheckedAccount` to `Account<BaseCollectionV1>`, matching the Metaplex Core Anchor guidance enabled by the crate's `anchor` feature.
- Removed the handwritten Metaplex Core asset-account URI decoder from `scripts/devnet/mint.ts` and switched the script to `@metaplex-foundation/mpl-core` `fetchAsset()` plus `asset.uri`.
- Replaced the old decoder unit test with coverage for the new `fetchAssetUri` helper while keeping the existing URL reachability tests intact.
- Verified with `cargo fmt --all`, `bunx prettier scripts/devnet/mint.ts scripts/devnet/mint.test.ts --write`, `bun test scripts/devnet/mint.test.ts`, `bun run typecheck`, `cargo test -p tests --lib mint_with_valid_reservation_creates_core_asset -- --nocapture`, and `bun run test:contract`.

- [x] Inspect public markdown files and identify Japanese text that should be translated.
- [x] Translate `README.md` and `docs/*.md` to English while preserving technical meaning.
- [x] Verify that no Japanese text remains in the public documentation set.
Expand Down Expand Up @@ -194,6 +221,23 @@
- `initialize_collection` (`qVj2Rgi...`) は `1569040` lamports (`0.00156904 SOL`) で、内訳は fee `10000` + collection asset rent `1559040`。`computeUnitsConsumed = 15302`。
- `reserve_token_id` (`5rJadHXM...`) は `1243880` lamports (`0.00124388 SOL`) で、内訳は fee `5000` + reservation rent `1238880`。`computeUnitsConsumed = 10190`。
- `mint_doom_index_nft` (`2cevXVJF...`) は `3208240` lamports (`0.00320824 SOL`) で、内訳は fee `10000` + Core asset rent `3198240`。`computeUnitsConsumed = 25713`。

# Task Plan: Install Metaplex Skill (2026-03-12)

- [x] Load the project memory and the local `skill-installer` workflow.
- [x] Reproduce or independently verify the reported install failure source.
- [x] Check whether the referenced GitHub repository is publicly reachable.
- [x] Check whether the public SkillMD distribution is a valid Codex skill package.
- [x] Record the root cause and the verified next steps.

# Review: Install Metaplex Skill (2026-03-12)

- Confirmed the requested source `https://github.com/metaplex-foundation/metaplex-skill.git` is not publicly reachable on March 12, 2026. `git ls-remote` returns `repository not found`, and GitHub responds with HTTP `404`.
- The `npx skills add metaplex-foundation/metaplex-skill` error message is therefore misleading: it surfaces as an authentication problem, but the underlying issue is that the referenced repo path is not available to this environment.
- Found a public SkillMD page for the same skill at `https://skillmd.ai/how-to-build/metaplex/`, with a ZIP download at `https://skillmd.ai/skills/metaplex/download/`.
- Verified that the ZIP download succeeds, but the archive is not a valid Codex skill package as-is: it contains support files under `docs/`, `examples/`, `resources/`, and `templates/`, but no `SKILL.md`.
- Because both verified installation paths are incomplete or invalid, no local skill installation was applied. The actionable next step is to get the correct upstream source from the skill author: either a reachable GitHub repo/path or a fixed ZIP bundle that includes `SKILL.md`.
Comment on lines +233 to +239
Copy link

@coderabbitai coderabbitai bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Update this review note to match the current PR state.

These bullets still say no local skill installation was applied and only upstream fixes remain, but this PR now vendors a local Metaplex skill under .agents/skills/metaplex/ and adds skills-lock.json. Leaving the old conclusion here will give future agents stale memory.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.agents/memory/todo.md around lines 233 - 239, Update the review note in
.agents/memory/todo.md to reflect that the PR now vendors a local Metaplex skill
and therefore the previous conclusion ("no local skill installation was applied"
and "only upstream fixes remain") is stale: mention that the PR adds a vendored
skill at .agents/skills/metaplex/ and includes skills-lock.json, remove or amend
the bullet claiming installation failed, and add a short recommendation (if any)
about whether upstream fixes are still needed or can be deferred now that the
local skill is vendored.

- Notes: `docs/PRODUCT.md` exists in this repo, but `docs/TECH.md` and `docs/STRUCTURE.md` are currently absent.
- localnet で作られた account sizes は `GlobalConfig = 406 bytes`, collection asset `96 bytes`, reservation `50 bytes`, minted Core asset `116 bytes`。対応する rent は `solana rent` の実測と一致した。

# Task Plan: Code Review Against main (2026-03-12)
Expand Down Expand Up @@ -259,3 +303,16 @@
- Extended Rust and TypeScript coverage for reservation misuse, paused minting, transfer-admin handshakes, keypair permissions, reserve retries, on-chain URI decoding, and HEAD-to-GET asset validation.
- Verified and intentionally skipped two stale comments because the current code already addressed them: `scripts/build-test-sbf.sh` no longer reuses a dumped `mpl_core_program.so`, and the redundant `let config = global_config;` alias in `tests/src/lib.rs` was already gone after the earlier test-module split.
- Verified with `bun test scripts/devnet/common.test.ts scripts/devnet/mint.test.ts`, `cargo clippy --workspace --all-targets --all-features -- -D warnings`, `bun run check`, and the `bun run check` path’s `./scripts/test-contract-v1.sh` contract suite.

# Task Plan: Show target In VS Code Explorer (2026-03-12)

- [x] Inspect workspace-level VS Code settings and confirm what hides `target/`.
- [x] Apply the minimum settings change so `target/` is visible again in Explorer.
- [x] Validate the edited JSON and record the outcome.

# Review: Show target In VS Code Explorer (2026-03-12)

- Confirmed the hiding behavior came from workspace-local VS Code settings in `.vscode/settings.json`, where `files.exclude` contained `**/target: true`.
- Removed only the `files.exclude` rule for `target/`, which makes the folder visible again in the Explorer without changing other workspace noise filters.
- Kept `search.exclude` for `**/target` intact, so global search still skips build artifacts unless that setting is changed separately.
- Validated the edited JSON with a local parse check: `node -e "... JSON.parse(...)"` completed successfully.
119 changes: 119 additions & 0 deletions .agents/skills/metaplex/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
---
name: metaplex
description: Metaplex development on Solana — NFTs, tokens, compressed NFTs, candy machines, token launches. Use when working with Token Metadata, Core, Bubblegum, Candy Machine, Genesis, or the mplx CLI.
license: Apache-2.0
metadata:
author: metaplex-foundation
version: "0.1.0"
openclaw: {"emoji":"💎","os":["darwin","linux","win32"],"requires":{"bins":["node"]},"homepage":"https://developers.metaplex.com"}
---

# Metaplex Development Skill

## Overview

Metaplex provides the standard infrastructure for NFTs and tokens on Solana:
- **Core**: Next-gen NFT standard (recommended for new NFT projects)
- **Token Metadata**: Fungible tokens + legacy NFTs/pNFTs
- **Bubblegum**: Compressed NFTs (cNFTs) using Merkle trees — massive scale at minimal cost
- **Candy Machine**: NFT drops with configurable minting rules
- **Genesis**: Token launch protocol with fair distribution + liquidity graduation

## Tool Selection

> **Prefer CLI over SDK** for direct execution. Use SDK only when user specifically needs code.

| Approach | When to Use |
|----------|-------------|
| **CLI (`mplx`)** | Default choice - direct execution, no code needed |
| **Umi SDK** | User needs code — default SDK choice. Covers all programs (TM, Core, Bubblegum, Genesis) |
| **Kit SDK** | User specifically uses @solana/kit, or asks for minimal dependencies. Token Metadata only — no Core/Bubblegum/Genesis support |

## Task Router

> **IMPORTANT**: You MUST read the detail file for your task BEFORE executing any command or writing any code. The command syntax, required flags, setup steps, and batching rules are ONLY in the detail files. Do NOT guess commands from memory.

| Task Type | Read This File |
|-----------|----------------|
| Any CLI operation (shared setup) | `./references/cli.md` |
| CLI: Core NFTs/Collections | `./references/cli.md` + `./references/cli-core.md` |
| CLI: Token Metadata NFTs | `./references/cli.md` + `./references/cli-token-metadata.md` |
| CLI: Compressed NFTs (Bubblegum) | `./references/cli.md` + `./references/cli-bubblegum.md` |
| CLI: Candy Machine (NFT drops) | `./references/cli.md` + `./references/cli-candy-machine.md` |
| CLI: Token launch (Genesis) | `./references/cli.md` + `./references/cli-genesis.md` |
| CLI: Fungible tokens | `./references/cli.md` (toolbox section) |
| SDK setup (Umi) | `./references/sdk-umi.md` |
| SDK: Core NFTs | `./references/sdk-umi.md` + `./references/sdk-core.md` |
| SDK: Token Metadata | `./references/sdk-umi.md` + `./references/sdk-token-metadata.md` |
| SDK: Compressed NFTs (Bubblegum) | `./references/sdk-umi.md` + `./references/sdk-bubblegum.md` |
| SDK: Token Metadata with Kit | `./references/sdk-token-metadata-kit.md` |
| SDK: Token launch (Genesis) | `./references/sdk-umi.md` + `./references/sdk-genesis.md` |
| Account structures, PDAs, concepts | `./references/concepts.md` |

## CLI Capabilities

The `mplx` CLI can handle most Metaplex operations directly. **Read `./references/cli.md` for shared setup, then the program-specific file.**

| Task | CLI Support |
|------|-------------|
| Create fungible token | ✅ |
| Create Core NFT/Collection | ✅ |
| Create TM NFT/pNFT | ✅ |
| Transfer TM NFTs | ✅ |
| Transfer fungible tokens | ✅ |
| Transfer Core NFTs | ❌ SDK only |
| Upload to Irys | ✅ |
| Candy Machine drop | ✅ (setup/config/insert — minting requires SDK) |
| Compressed NFTs (cNFTs) | ✅ (batch limit ~100, use SDK for larger) |
| Check SOL balance / Airdrop | ✅ |
| Query assets by owner/collection | ❌ SDK only (DAS API) |
| Token launch (Genesis) | ✅ |

## Program IDs

```
Token Metadata: metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s
Core: CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d
Bubblegum V1: BGUMAp9SX3uS4efGcFjPjkAQZ4cUNZhtHaMq64nrGf9D
Bubblegum V2: BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY
Core Candy: CMACYFENjoBMHzapRXyo1JZkVS6EtaDDzkjMrmQLvr4J
Genesis: GNS1S5J5AspKXgpjz6SvKL66kPaKWAhaGRhCqPRxii2B
```
Comment on lines +74 to +81
Copy link

@coderabbitai coderabbitai bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add a language to this fenced block.

The Program IDs block is missing a fence language, which trips the current markdownlint rule set. text is enough here.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.agents/skills/metaplex/SKILL.md around lines 74 - 81, The fenced code block
containing the Program IDs (look for lines starting with "Token Metadata:
metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s" and entries like "Bubblegum V2:
BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY" and "Genesis:
GNS1S5J5AspKXgpjz6SvKL66kPaKWAhaGRhCqPRxii2B") needs a fence language to satisfy
markdownlint; fix it by changing the opening triple backticks to include the
language identifier (e.g., ```text) so the block is fenced as text.


## Quick Decision Guide

### NFTs: Core vs Token Metadata

| Choose | When |
|--------|------|
| **Core** | New NFT projects, lower cost (87% cheaper), plugins, royalty enforcement |
| **Token Metadata** | Existing TM collections, need editions, pNFTs for legacy compatibility |

### Compressed NFTs (Massive Scale)

Use **Bubblegum** when minting thousands+ of NFTs at minimal cost. See `./references/cli-bubblegum.md` (CLI) or `./references/sdk-bubblegum.md` (SDK).

### Fungible Tokens

Always use **Token Metadata**. Read `./references/cli.md` (toolbox section) for CLI commands.

### NFT Drops

Use **Core Candy Machine**. Read `./references/cli.md` + `./references/cli-candy-machine.md`.

### Token Launches (Token Generation Event / Fair Launch / Memecoin)

Use **Genesis**. The **Launch API** (`genesis launch create` / `createAndRegisterLaunch`) is recommended — it handles everything in one step. Two launch types:
- **`project`** (default): Configurable allocations, 48h deposit, team vesting support
- **`memecoin`**: Simplified, 1h deposit, hardcoded fund flows — only needs name, symbol, image, and deposit start time

Read `./references/cli.md` + `./references/cli-genesis.md` (CLI) or `./references/sdk-genesis.md` (SDK).

## External Resources

- Documentation: https://developers.metaplex.com
- Core: https://developers.metaplex.com/core
- Token Metadata: https://developers.metaplex.com/token-metadata
- Bubblegum: https://developers.metaplex.com/bubblegum-v2
- Candy Machine: https://developers.metaplex.com/core-candy-machine
- Genesis: https://developers.metaplex.com/genesis
126 changes: 126 additions & 0 deletions .agents/skills/metaplex/references/cli-bubblegum.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# Bubblegum CLI Reference

Commands for creating and managing compressed NFTs (cNFTs) via the `mplx` CLI.

> **Prerequisites**: Run Initial Setup from `./cli.md` first (RPC, keypair, SOL balance).
>
> **Batch limit**: CLI is practical for up to ~100 cNFTs. For larger mints (thousands+), use the Umi SDK (`./sdk-bubblegum.md`) or Candy Machine instead.

---

## When to Use Bubblegum

| Use Bubblegum | Use Core Instead |
|---------------|------------------|
| Minting thousands+ of NFTs | Small collections (< 1000) |
| Lowest possible cost per NFT | Need on-chain plugins (royalties, freeze) |
| Airdrops, loyalty programs, tickets | Marketplace-focused projects |
| Proof of attendance, credentials | Simple 1/1 NFTs |

---

## Key Concepts

### Merkle Trees

Bubblegum stores NFTs as leaves in a concurrent Merkle tree. Only the **Merkle root** (a single hash) lives on-chain — the actual NFT data is stored in transactions and indexed by RPC providers via the **DAS API**.

Each tree has two on-chain accounts:
- **Merkle Tree Account** — stores the tree structure, change log, and canopy
- **TreeConfigV2 Account** — PDA tracking tree creator, delegate, capacity, and mint count

### Tree Sizing

| cNFTs | Tree Depth | Canopy Depth | Buffer Size | Tree Cost | Cost per cNFT |
|-------|-----------|-------------|-------------|-----------|---------------|
| 16,384 | 14 | 8 | 64 | ~0.34 SOL | ~0.00002 SOL |
| 65,536 | 16 | 10 | 64 | ~0.71 SOL | ~0.00001 SOL |
| 262,144 | 18 | 12 | 64 | ~2.10 SOL | ~0.00001 SOL |
| 1,048,576 | 20 | 13 | 1024 | ~8.50 SOL | ~0.000008 SOL |
| 16,777,216 | 24 | 15 | 2048 | ~26.12 SOL | ~0.000002 SOL |
| 1,073,741,824 | 30 | 17 | 2048 | ~72.65 SOL | ~0.00000005 SOL |

- **Tree Depth** — determines max capacity (2^depth leaves)
- **Max Buffer Size** — concurrency limit (parallel mints in same block)
- **Canopy Depth** — cached upper tree nodes; higher = smaller proofs, better composability, but higher rent

### Proofs and DAS API

Operations on existing cNFTs (transfer, burn, update) require a **Merkle proof** to verify the leaf. Proofs are fetched from RPC providers via the DAS API — not from on-chain data.

---

## Commands

```bash
# Tree management
mplx bg tree create --wizard # Interactive (recommended)
mplx bg tree create --maxDepth <N> --maxBufferSize <N> --canopyDepth <N> # Manual
mplx bg tree list # List trees created via --wizard only

# cNFT operations
mplx bg nft create --wizard # Interactive
mplx bg nft create <TREE> --name <NAME> --uri <URI> # With pre-uploaded metadata
mplx bg nft create <TREE> --name <NAME> --image <PATH> --description <DESC> # With local files
mplx bg nft create <TREE> --name <NAME> --uri <URI> --collection <ADDR> # In collection
mplx bg nft fetch <ASSETID>
mplx bg nft transfer <ASSETID> <NEWOWNER>
mplx bg nft burn <ASSETID>
mplx bg nft update <ASSETID> --name <NAME>

# Collection for cNFTs (uses MPL Core collections)
mplx bg collection create --name <NAME> --uri <URI>
mplx bg collection create --name <NAME> --uri <URI> --royalties <PERCENT>
```

---

## CLI Workflow

```bash
# 1. Create a tree (wizard guides through depth/buffer/canopy selection)
mplx bg tree create --wizard

# 2. (Optional) Create a collection for your cNFTs
mplx bg collection create --name "My Collection" --uri "https://arweave.net/xxx"

# 3. Mint cNFTs into the tree
mplx bg nft create <TREE_NAME_OR_ADDRESS> --name "My cNFT" --image ./image.png --description "A compressed NFT"

# 4. Transfer (requires DAS-compatible RPC, not available on localnet)
mplx bg nft transfer <ASSETID> <RECIPIENT_ADDRESS>
```

For batch minting, chain commands:
```bash
mplx bg nft create <TREE> --name "cNFT #1" --uri "<URI_1>" && \
mplx bg nft create <TREE> --name "cNFT #2" --uri "<URI_2>" && \
mplx bg nft create <TREE> --name "cNFT #3" --uri "<URI_3>"
```

---

## Localnet Limitations

Only tree creation (`mplx bg tree create`) and minting (`mplx bg nft create`) work on localhost/localnet. Operations that require DAS API -- fetch, transfer, burn, update -- do NOT work on localnet because the test validator does not support DAS.

---

## Program IDs

```
Bubblegum V1: BGUMAp9SX3uS4efGcFjPjkAQZ4cUNZhtHaMq64nrGf9D
Bubblegum V2: BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY
```
Comment on lines +111 to +114
Copy link

@coderabbitai coderabbitai bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add a language to this fenced block.

The Program IDs block is unlabeled, so it fails the current markdownlint configuration. text would keep it simple.

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 111-111: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.agents/skills/metaplex/references/cli-bubblegum.md around lines 111 - 114,
The fenced code block containing the Program IDs lines "Bubblegum V1:
BGUMAp9SX3uS4efGcFjPjkAQZ4cUNZhtHaMq64nrGf9D" and "Bubblegum V2:
BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY" is missing a language label;
update that fenced block in .agents/skills/metaplex/references/cli-bubblegum.md
to use a language tag (use "text") so the block becomes ```text ... ``` to
satisfy markdownlint.


---

## Cost Comparison

| Standard | Cost per NFT | Accounts | Best For |
|----------|-------------|----------|----------|
| **Bubblegum** | ~$0.000005 | 0 (shared tree) | Massive scale |
| **Core** | ~0.0029 SOL | 1 | Small-medium collections |
| **Token Metadata** | ~0.022 SOL | 3-4 | Fungibles, legacy |

Bubblegum is ~98% cheaper than Token Metadata and ~90% cheaper than Core at scale. The trade-off is that cNFT operations require DAS API access for proof fetching.
Loading
Loading