internet-court/internet-court-skill / vendored/metaplex/metaplex
metaplex
VerifiedMetaplex 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.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.6 KB |
| SKILL.md | skill md | 9.7 KB |
| references/cli-agent.md | markdown | 8.8 KB |
| references/cli-bubblegum.md | markdown | 5.8 KB |
| references/cli-candy-machine.md | markdown | 10.2 KB |
| references/cli-config.md | markdown | 1.5 KB |
| references/cli-core.md | markdown | 8.9 KB |
| references/cli-genesis.md | markdown | 24.6 KB |
| references/cli-initial-setup.md | markdown | 2.7 KB |
| references/cli-token-metadata.md | markdown | 3.3 KB |
| references/cli-toolbox.md | markdown | 4.3 KB |
| references/cli-troubleshooting.md | markdown | 2.2 KB |
| references/cli.md | markdown | 5.4 KB |
| references/concepts.md | markdown | 12.0 KB |
| references/metadata-json.md | markdown | 1.8 KB |
| references/sdk-agent.md | markdown | 21.7 KB |
| references/sdk-bubblegum.md | markdown | 11.3 KB |
| references/sdk-core.md | markdown | 20.5 KB |
| references/sdk-genesis-low-level.md | markdown | 21.7 KB |
| references/sdk-genesis.md | markdown | 24.4 KB |
| references/sdk-token-metadata-kit.md | markdown | 8.4 KB |
| references/sdk-token-metadata.md | markdown | 13.7 KB |
| references/sdk-umi.md | markdown | 6.1 KB |
references/concepts.md
View on GitHub# Metaplex Concepts Reference
## Token Standards
### Token Metadata Standards
| Standard | Use Case | Accounts |
|----------|----------|----------|
| `Fungible` | SPL tokens, memecoins, utility tokens | Mint + Metadata |
| `FungibleAsset` | Semi-fungible, non-divisible | Mint + Metadata |
| `NonFungible` | Standard NFT (1/1) | Mint + Metadata + MasterEdition |
| `NonFungibleEdition` | Print editions | Mint + Metadata + Edition |
| `ProgrammableNonFungible` | NFT with enforced royalties (pNFT) | + TokenRecord |
| `ProgrammableNonFungibleEdition` | Print edition of a pNFT | + TokenRecord + Edition |
### Core vs Token Metadata
| Aspect | Core | Token Metadata |
|--------|------|----------------|
| Accounts per NFT | 1 | 3-4 |
| Mint cost | ~0.0029 SOL | ~0.022 SOL |
| Compute units | ~17,000 CU | ~205,000 CU |
| Royalty enforcement | Built-in | Requires pNFT |
| Plugins | Yes | No |
| Best for | New NFT projects | Fungibles, legacy NFTs |
---
## Account Structures
### Token Metadata Accounts
```
Metadata Account
├── key: Key (1 byte)
├── updateAuthority: PublicKey
├── mint: PublicKey
├── name: string (max 32)
├── symbol: string (max 10)
├── uri: string (max 200)
├── sellerFeeBasisPoints: u16
├── creators: Option<Vec<Creator>>
├── primarySaleHappened: bool
├── isMutable: bool
├── editionNonce: Option<u8>
├── tokenStandard: Option<TokenStandard>
├── collection: Option<Collection>
├── uses: Option<Uses>
├── collectionDetails: Option<CollectionDetails>
└── programmableConfig: Option<ProgrammableConfig>
MasterEdition Account
├── key: Key
├── supply: u64
└── maxSupply: Option<u64>
TokenRecord Account (pNFTs only)
├── key: Key
├── bump: u8
├── state: TokenState
├── delegate: Option<PublicKey>
├── delegateRole: Option<TokenDelegateRole>
└── lockedTransfer: Option<PublicKey>
```
### Core Asset Structure
```
Asset Account (Single Account)
├── key: Key
├── owner: PublicKey
├── updateAuthority: UpdateAuthority
├── name: string
├── uri: string
├── seq: Option<u64>
└── plugins: Vec<PluginHeader + Plugin>
Collection Account
├── key: Key
├── updateAuthority: PublicKey
├── name: string
├── uri: string
├── numMinted: u32
├── currentSize: u32
└── plugins: Vec<PluginHeader + Plugin>
```
---
## PDA Seeds
### Token Metadata PDAs
| Account | Seeds |
|---------|-------|
| Metadata | `['metadata', program_id, mint]` |
| Master Edition | `['metadata', program_id, mint, 'edition']` |
| Edition | `['metadata', program_id, mint, 'edition']` |
| Token Record | `['metadata', program_id, mint, 'token_record', token]` |
| Collection Authority | `['metadata', program_id, mint, 'collection_authority', authority]` |
| Use Authority | `['metadata', program_id, mint, 'user', use_authority]` |
### Agent Registry Accounts
```
AgentIdentityV2 (104 bytes) — current version, created by RegisterIdentityV1
├── key: u8 (discriminator)
├── bump: u8
├── _padding: [u8; 6]
├── asset: Pubkey (the MPL Core asset)
├── agentToken: OptionalPubkey (32 bytes — Genesis token mint, set via SetAgentTokenV1)
└── _reserved: [u8; 32]
AgentIdentityV1 (40 bytes) — legacy, auto-upgraded to V2 by SetAgentTokenV1
├── key: u8 (discriminator)
├── bump: u8
├── _padding: [u8; 6]
└── asset: Pubkey (the MPL Core asset)
ExecutiveProfileV1 (40 bytes)
├── key: u8 (discriminator)
├── _padding: [u8; 7]
└── authority: Pubkey
ExecutionDelegateRecordV1 (104 bytes)
├── key: u8 (discriminator)
├── bump: u8
├── _padding: [u8; 6]
├── executiveProfile: Pubkey
├── authority: Pubkey
└── agentAsset: Pubkey
```
### Agent Registry PDAs
| Account | Seeds |
|---------|-------|
| Agent Identity | `['agent_identity', asset]` |
| Executive Profile | `['executive_profile', authority]` |
| Execution Delegate Record | `['execution_delegate_record', executive_profile, agent_asset]` |
---
## Authorities
### Token Metadata Authorities
| Authority | Can |
|-----------|-----|
| Update Authority | Update metadata, verify creators, verify collection |
| Mint Authority | Mint new tokens (fungibles) |
| Freeze Authority | Freeze token accounts |
### Core Authorities
| Authority | Can |
|-----------|-----|
| Owner | Transfer, burn, add owner-managed plugins |
| Update Authority | Update metadata, add authority-managed plugins |
---
## Collection Patterns
### Core Collections
- Assets created with `collection` param are **auto-verified**
- No separate verification step needed
### Token Metadata Collections
- Collection is an NFT itself
- Items reference collection but start **unverified**
- Must call `verifyCollectionV1` as collection authority
---
## Core Plugin Types
### Owner-Managed
- `TransferDelegate` - Allow another to transfer
- `FreezeDelegate` - Allow another to freeze
- `BurnDelegate` - Allow another to burn
### Authority-Managed
- `Royalties` - Enforce royalties on transfers
- `UpdateDelegate` - Allow another to update
- `Attributes` - On-chain attributes
### Permanent (Immutable after adding)
- `PermanentTransferDelegate`
- `PermanentFreezeDelegate`
- `PermanentBurnDelegate`
---
## Common Errors
| Error | Cause | Solution |
|-------|-------|----------|
| `InvalidTokenStandard` | Wrong standard for operation | Check asset's actual token standard |
| `InvalidAuthority` | Signer doesn't match authority | Verify update/mint authority |
| `CollectionNotVerified` | Collection not verified | Call `verifyCollectionV1` |
| `TokenRecordNotFound` | Missing TokenRecord for pNFT | Include token record PDA |
| `PluginNotFound` | Plugin doesn't exist | Add plugin first or check name |
| `InsufficientFunds` | Not enough SOL | Fund wallet |
| `Invalid data enum variant` | Wrong JSON format | Check array format, type field, ruleSet object |
---
## Cost Comparison
| Operation | Token Metadata | Core | Savings |
|-----------|---------------|------|---------|
| Mint NFT | ~0.022 SOL | ~0.0029 SOL | 87% |
| Compute Units | ~205,000 CU | ~17,000 CU | 92% |
| Accounts | 3-4 | 1 | 75% |
---
## Genesis Concepts
### Launch Types
- **Launchpool**: Configurable allocations, 48-hour deposit window, team vesting support, custom Raydium liquidity split.
- **Bonding Curve**: Instant constant product AMM — no deposit window, trading starts immediately. Optional creator fees, first buy, and agent mode. Auto-graduates to Raydium CPMM when all tokens are sold.
Both types have a total supply of 1 billion tokens and graduate to Raydium liquidity.
### Lifecycle
```text
Initialize → Add Buckets → Finalize (irreversible) → Deposit Period → Transition → Graduation → Claim Period
```
- **Initialize**: Creates a Genesis account + the token mint. All configuration happens here (name, symbol, supply, quote mint).
- **Add Buckets**: Configure how tokens are distributed. See Bucket Types below.
- **Finalize**: Locks the configuration. No more buckets can be added. **Irreversible.** Requires 100% of supply allocated to buckets.
- **Deposit Period**: Users deposit SOL (quote token) into the LaunchPool bucket.
- **Transition**: After deposit period ends, executes end behaviors (e.g., routes deposited SOL to outflow buckets). Call `triggerBehaviorsV2`.
- **Graduation**: LP tokens are graduated to Raydium. Call `graduateToRaydiumCpmmV2`.
- **Claim Period**: Users claim tokens proportional to their deposit.
### Bucket Types
| Bucket | Purpose | User Interaction |
|--------|---------|-----------------|
| **LaunchPool** | Pro-rata allocation — users deposit SOL, receive tokens proportionally | deposit / withdraw / claim |
| **Presale** | Fixed-price allocation (price = quoteCap / allocation), first-come-first-served | deposit / withdraw / claim |
| **BondingCurve** | Constant-product AMM with virtual reserves | swap (buy/sell) |
| **Unlocked** | Team/treasury — tokens go directly to a recipient, no deposits | claim only |
| **Vault** | Holds SOL received from end behaviors | deposit / withdraw |
| **RaydiumCpmm** | Raydium LP graduation — receives tokens + SOL, creates LP | graduation |
| **Streamflow** | Vesting via Streamflow — tokens unlock over time | lock / claim via Streamflow |
### Fees
Genesis charges protocol-level fees on deposits and withdrawals. For current fee rates, see: https://metaplex.com/docs/protocol-fees
### Condition Objects
Buckets use condition objects for timing (deposit start/end, claim start/end). Use the helper:
```typescript
import { createTimeAbsoluteCondition } from '@metaplex-foundation/genesis';
const condition = createTimeAbsoluteCondition(BigInt(unixTimestamp));
```
This handles the required padding and triggered timestamp fields automatically. Other condition types: `createTimeRelativeCondition()` (relative to another bucket), `createNeverCondition()` (permanently locked).
### End Behaviors
After a LaunchPool's deposit period ends, `endBehaviors` define what happens to the deposited SOL:
```typescript
{
__kind: 'SendQuoteTokenPercentage', // Send % of collected SOL to another bucket
padding: Array(4).fill(0), // Reserved bytes (required)
destinationBucket: publicKey(bucket), // Target bucket address (e.g., Unlocked bucket for team)
percentageBps: 10000, // 10000 = 100% of collected SOL
processed: false, // Set by program after execution — always pass false
}
```
Available end behavior types:
- `SendQuoteTokenPercentage` — Route a percentage of collected SOL to another bucket
- `BaseTokenRollover` — Move a percentage of unsold base tokens to another bucket
- `SendStartPrice` — Send the starting price (SOL) to a destination bucket
- `ReallocateBaseTokensOnFailure` — On minimum threshold failure, move tokens to another bucket
### Claim Schedules
Buckets can have claim schedules that control when users can claim tokens:
```typescript
import { createClaimSchedule, createNeverClaimSchedule } from '@metaplex-foundation/genesis';
// Linear vesting with cliff
const schedule = createClaimSchedule({
startTime: BigInt(startTimestamp), // When linear vesting begins
endTime: BigInt(endTimestamp), // When vesting completes
cliffTime: BigInt(cliffTimestamp), // Cliff date
cliffAmountBps: 1000, // 10% unlocked at cliff
period: 2_592_000n, // Release every 30 days
});
// Permanently locked (e.g., LP tokens that should never vest)
const locked = createNeverClaimSchedule();
```
### Allowlists
Presale and launch pool buckets support merkle-tree allowlists to restrict who can deposit:
```typescript
import { prepareAllowlist } from '@metaplex-foundation/genesis';
const { root, proofs, treeHeight } = prepareAllowlist([
{ address: publicKey('Addr111...') },
{ address: publicKey('Addr222...') },
]);
```
Pass `allowlist` config when adding a bucket, and provide merkle proofs as remaining accounts when depositing.
### Token Supply Decimals
Genesis tokens default to 9 decimals. Supply is specified in base units:
| Human Amount | Base Units (9 decimals) |
|---|---|
| 1 token | `1_000_000_000n` |
| 1,000,000 tokens | `1_000_000_000_000_000n` |
| 1,000,000,000 tokens | `1_000_000_000_000_000_000n` |
## For more info
Consult these Metaplex docs when you need deeper detail than this reference provides:
- Core vs Token Metadata: https://metaplex.com/docs/smart-contracts/core/tm-differences
- What is a Core asset: https://metaplex.com/docs/smart-contracts/core/what-is-an-asset
- Core plugins: https://metaplex.com/docs/smart-contracts/core/plugins
- Token standards: https://metaplex.com/docs/smart-contracts/token-metadata/token-standard
- Agents overview: https://metaplex.com/docs/agents
- MPL Agent identity: https://metaplex.com/docs/smart-contracts/mpl-agent/identity
- Genesis overview: https://metaplex.com/docs/smart-contracts/genesis
- Launch pool: https://metaplex.com/docs/smart-contracts/genesis/launch-pool
- Bonding curve: https://metaplex.com/docs/smart-contracts/genesis/bonding-curve
- Protocol fees: https://metaplex.com/docs/protocol-fees
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |