Metadados e armazenamento
Metadados de NFT combinam campos on-chain (nome, uri) com JSON e arquivos de mídia off-chain. Escolhas de armazenamento (Arweave, IPFS, HTTPS centralizado) afetam permanência, custo e confiança.
Receita
{
"name": "My NFT",
"symbol": "MNFT",
"description": "Example asset",
"image": "ar://HASH",
"attributes": [{ "trait_type": "Rarity", "value": "Gold" }],
"properties": { "files": [{ "uri": "ar://HASH", "type": "image/png" }] }
}# Sugar upload -> caminho típico Arweave bundlr
sugar uploadQuando usar:
- Preparar assets de coleção antes do mint on-chain
- Escolher hospedagem permanente vs mutável
- Validar schema de metadados para marketplaces
- Vincular campos animation_url e external_url
Exemplo prático
# Diretório por item: assets/0.json, assets/0.png, ...
sugar validate
sugar upload # envia imagens + metadados para Arweave via Bundlr
sugar deploy// Após upload, uri JSON nos metadados on-chain aponta para gateway Arweave ou ar://
const metadata = {
name: "Item #0",
symbol: "DEMO",
description: "Stored on Arweave",
image: "https://arweave.net/TX_ID",
attributes: [
{ trait_type: "Background", value: "Blue" },
{ trait_type: "Eyes", value: "Laser" },
],
};
// Campo uri on-chain -> mesma localização JSON// Fetch do cliente com cache bust no reveal
const res = await fetch(uri.replace("ar://", "https://arweave.net/"));
const json = await res.json();O que isso demonstra:
- Schema JSON padrão compatível com principais marketplaces
- Campo
imageobrigatório para exibição em galeria - Array
attributesalimenta filtros de traits e ferramentas de raridade
Mergulho profundo
Como funciona
- Conta on-chain armazena string
uricurta apontando para JSON - JSON referencia mídia via
image,animation_url,properties.files - Arweave: pagamento único, permanência endereçada por conteúdo
- IPFS: baseado em CID; serviço de pinning exigido para disponibilidade
Comparação de armazenamento
| Armazenamento | Permanência | Modelo de custo |
|---|---|---|
| Arweave | Alta | Antecipado por MB |
| IPFS + pin | Depende do pin | Taxas contínuas de pin |
| HTTPS | Baixa (mutável) | Hospedagem em servidor |
Notas TypeScript
// Valide schema JSON no CI antes do upload
// Faça hash dos arquivos e compare com compromisso on-chain se usar padrão NFT verificávelErros comuns
- Apenas uri HTTP - troca de metadados se servidor comprometido. Correção: Arweave/IPFS para coleções em produção.
- Imagens oversized - carregamento lento e rejeição em marketplace. Correção: comprima; siga limites de tamanho do marketplace.
- Mismatch token id vs nome de arquivo - imagem errada exibida. Correção:
sugar validatee verificações de hash. - Vazamento de reveal - JSON final enviado cedo demais. Correção: hidden settings + upload de reveal atrasado.
- Resolvedor
ar://quebrado - alguns clientes sem gateway. Correção: forneça fallback https://arweave.net na UI.
Alternativas
| Alternativa | Use quando | Não use quando |
|---|---|---|
| Arweave via Bundlr | Arte NFT em produção | Apenas teste descartável |
| IPFS NFT.Storage | Preferência ecossistema IPFS | Precisa garantia de permanência Arweave |
| SVG on-chain (pequeno) | Arte generativa minúscula | Arquivos de mídia grandes |
FAQs
O que vai on-chain vs off-chain?
Nome/uri on-chain; imagem e atributos tipicamente em JSON off-chain.
Arweave vs IPFS?
Arweave: permanência pagamento único. IPFS: CID com responsabilidade de pinning.
O que é Bundlr?
Camada de upload financiando transações Arweave - usada pelo Sugar.
Campos JSON obrigatórios?
name, image mínimo para a maioria dos marketplaces; attributes para traits.
animation_url?
Campo opcional para mídia vídeo/html interativa.
Metadados podem mudar?
Sim se update authority on-chain puder alterar uri para novo JSON.
Metadados imutáveis?
Revogue update authority após uri final definida; use armazenamento permanente.
Coleções generativas?
Pré-renderize todas as imagens ou SVG on-chain; JSON por índice com traits correspondentes.
Validar antes do mint?
sugar validate verifica pares json/imagem e problemas de schema.
Campo image da DAS?
DAS resolve content.links.image a partir de metadados indexados.
Risco de armazenamento centralizado?
Servidor pode trocar imagem - mina narrativa de permanência do NFT.
Limites de tamanho de arquivo?
Específicos por marketplace - comumente alguns MB para imagens.
Relacionados
- Candy Machine - fluxo de upload Sugar
- Metaplex Core - campo uri on-chain
- Lendo NFTs (DAS API) - metadados resolvidos
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.