Token Metadata
Metaplex Token Metadata é o padrão NFT legado: uma conta de mint mais metadata PDA, master edition e contas token record opcionais. Ainda alimenta grande parte da liquidez em mercados secundários e coleções antigas.
Receita
const TOKEN_METADATA_PROGRAM = "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s";
// Metadata PDA: ["metadata", program_id, mint_id]# Prefira Metaplex Umi / ferramentas Sugar em vez de CLI manual para novos mints compatíveis com legadoQuando usar:
- Integrar com marketplaces que exigem layout Token Metadata
- Manter coleções existentes já no Token Metadata
- Ler NFTs históricos em indexadores
- Rules pNFT (programmable NFT) com contas token record
Exemplo prático
import { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
import { mplTokenMetadata } from "@metaplex-foundation/mpl-token-metadata";
import { fetchMetadataFromSeeds } from "@metaplex-foundation/mpl-token-metadata";
import { publicKey } from "@metaplex-foundation/umi";
const umi = createUmi("https://api.mainnet-beta.solana.com").use(mplTokenMetadata());
const mint = publicKey("MINT_PUBKEY");
const metadata = await fetchMetadataFromSeeds(umi, { mint });
console.log(metadata.name, metadata.uri);
console.log("seller fee bps:", metadata.sellerFeeBasisPoints);// Leitura DAS (preferida para carteiras)
const asset = await dasRpc("getAsset", { id: mint.toString() });O que isso demonstra:
- Metadata PDA derivada do mint + program ID
sellerFeeBasisPointsarmazena percentual de royalty (500 = 5%)- DAS abstrai cálculo de PDA para leituras de portfólio
Mergulho profundo
Como funciona
- Program ID:
metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s - Mint: token SPL com supply 1, decimals 0
- Conta de metadados: nome, símbolo, uri, criadores, coleção
- Master edition: supply de prints para edições;
max_supplypara prints limitados
Conjunto de contas
| Conta | Propósito |
|---|---|
| Mint | Token de propriedade SPL |
| Metadata PDA | uri JSON, criadores, royalty bps |
| Master edition | Regras de edição/escassez |
| Token record | Estado de autorização pNFT |
Notas TypeScript
// Verificar coleção: instruções setCollectionV1 + verifyCollectionV1
// Use @metaplex-foundation/mpl-token-metadata para todos os builders de instruçãoErros comuns
- Campo de coleção não verificado - nomes de coleção falsificados. Correção: execute instrução de verificação on-chain.
- Rent alto por muitas contas - mints caros. Correção: prefira Core ou cNFT para novos projetos.
- Complexidade de autorização pNFT - token record exigido para transferências. Correção: siga matriz de compatibilidade de marketplace.
- Surpresas de metadados mutáveis - update authority pode alterar uri. Correção: revogue ou use flag imutável quando apropriado.
- Bugs de derivação manual de PDA - endereço de metadados errado. Correção: use helpers de seeds do SDK ou DAS.
Alternativas
| Alternativa | Use quando | Não use quando |
|---|---|---|
| Metaplex Core | Novas coleções | Precisa permanecer no Token Metadata |
| cNFT | Drops em massa | Precisa mint on-chain completo por item |
| Leituras apenas DAS | Exibição em carteira | Construir instruções de mint |
FAQs
Token Metadata está obsoleto?
Não foi removido - mas Metaplex recomenda Core para novos NFTs enquanto Token Metadata permanece suportado.
O que é uma metadata PDA?
Conta derivada do programa armazenando nome, uri, criadores e campos de coleção do NFT.
O que são pNFTs?
NFTs programáveis com contas token record controlando transferências via rulesets.
Como royalties são definidas?
sellerFeeBasisPoints nos metadados - aplicadas por marketplaces cooperantes.
Metadados podem mudar?
Sim se update authority for mantida e não for imutável.
Como verificar coleção?
Collection authority assina instrução verify_collection vinculando metadados ao mint da coleção.
DAS vs GPA?
DAS preferida para carteiras; GPA ainda usada por indexadores ingerindo atualizações brutas.
NFTs de edição?
Master edition + instruções de mint de print para prints numerados.
Sugar CLI?
Metaplex Sugar foca lançamentos de coleção Token Metadata - verifique docs para alternativas Core.
Programas Anchor lendo metadados?
Desserialize conta de metadados via crate mpl-token-metadata em programas Rust.
Program ID no mainnet?
metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.
Quando ainda é exigido?
Requisitos de listagem em marketplace exigindo explicitamente layout Token Metadata.
Relacionados
- Metaplex Core - alternativa moderna
- Coleções e verificação - coleções verificadas
- Royalties e enforcement - royalty bps
Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.