Esquema de metadados de token

O que é um esquema de metadados de token?

Um esquema de metadados de token é um formato estruturado que define como as informações sobre um token de criptomoeda devem ser escritas, armazenadas e lidas por carteiras, dApps, exploradores, marketplaces, jogos e ferramentas de indexação.

Na maioria das conversas sobre cripto, Token Metadata Schema refere-se à estrutura JSON usada para descrever NFTs e outros ativos tokenizados.

O esquema informa aos aplicativos quais campos devem ser esperados, como

, , , e links de mídia.

Um contrato de token pode armazenar a propriedade on-chain, enquanto seus metadados são armazenados por meio de uma URI que aponta para um arquivo JSON.

O padrão oficial ERC-721 informa que uma URI de token pode apontar para um arquivo JSON compatível com o ERC-721 Metadata JSON Schema.

O padrão oficial ERC-1155 define um ERC-1155 Metadata URI JSON Schema para contratos multitoquen.

Um esquema de metadados é importante porque ajuda diferentes aplicativos a exibir o mesmo token de forma consistente.

Sem um esquema, cada projeto poderia nomear os campos de maneira diferente, e as carteiras teriam dificuldade em saber qual valor corresponde à imagem, à descrição e às características.

Para iniciantes, a forma mais simples de entender um Token Metadata Schema é imaginá-lo como um formato de etiqueta para um ativo cripto.

A blockchain comprova que o token existe e quem é seu proprietário, enquanto o esquema de metadados explica o que o token representa.

Por que o esquema de metadados de token é importante no mercado cripto

O esquema de metadados de token é importante porque os usuários não interagem apenas com IDs de token brutos.

Eles interagem com imagens, nomes, descrições, características, níveis, badges, informações de raridade, conteúdo desbloqueável e outros detalhes legíveis por humanos.

Uma carteira só consegue exibir corretamente um token quando sabe como ler seus metadados.

Um jogo só consegue mostrar corretamente um item quando entende os atributos e campos de mídia desse item.

Um marketplace só consegue filtrar corretamente coleções quando as características são estruturadas de forma previsível.

Um protocolo de empréstimo que aceita NFTs como garantia pode precisar de informações precisas sobre coleção, características e mídia para dar suporte aos processos de avaliação.

Uma plataforma de ativos do mundo real pode precisar de campos de metadados que façam referência a documentos, emissores, avaliações, termos jurídicos ou status de verificação.

Um aplicativo com acesso restrito por token pode precisar de metadados para verificar se um token concede acesso a determinado nível de associação.

Quando os metadados são claramente estruturados, os aplicativos conseguem lê-los automaticamente.

Quando os metadados são desorganizados ou inconsistentes, os usuários podem ver imagens quebradas, características ausentes, nomes incorretos ou detalhes desatualizados do ativo.

Por isso, o design do esquema de metadados faz parte da experiência do usuário no mercado cripto, e não é apenas um detalhe para desenvolvedores.

Esquema de metadados de token e Token URI

Uma Token URI é o link ou identificador que aponta para os metadados de um token.

Um Token Metadata Schema é a estrutura dos dados encontrados nesse link ou nessa resposta codificada.

Por exemplo, um contrato ERC-721 pode retornar

a partir de .

O arquivo JSON nessa URI deve seguir um esquema de metadados para que as carteiras consigam compreendê-lo.

A Token URI é o endereço dos metadados.

O Token Metadata Schema é o formato dos metadados.

Essa diferença é importante porque uma URI funcional não é suficiente se o JSON dentro dela for inválido ou confuso.

Um token pode ter um arquivo de metadados acessível, mas ainda ser exibido incorretamente se os campos estiverem ausentes ou tiverem nomes não padronizados.

Um token também pode ter um esquema correto, mas não carregar se a URI apontar para um armazenamento indisponível.

Um bom design de NFT requer tanto uma Token URI confiável quanto um Token Metadata Schema bem estruturado.

Esquema de metadados de token no ERC-721

ERC-721 é o padrão clássico para NFTs únicos em redes no estilo Ethereum.

A extensão de metadados ERC-721 inclui

, e .

O padrão ERC-721 descreve os metadados com um esquema JSON simples que pode incluir campos como

, e .

Essa estrutura simples ajudou os NFTs a se tornarem mais fáceis de exibir em carteiras e aplicativos.

Um token ERC-721 pode representar arte digital, itens de jogos, passes de associação, certificados, terrenos virtuais, badges de identidade ou registros de ativos do mundo real.

Cada ID de token pode ter seu próprio arquivo de metadados.

Isso significa que o ID de token 1 pode ter uma imagem, nome e atributos diferentes do ID de token 2.

O esquema ajuda os clientes a entender quais campos descrevem cada token único.

Os desenvolvedores geralmente estendem o padrão básico de metadados ERC-721 com campos adicionais para características, mídia, animação, raridade, licenciamento ou dados específicos do projeto.

Essas extensões podem ser úteis, mas os campos principais devem permanecer claros e compatíveis com ferramentas Web3 comuns.

Esquema de metadados de token no ERC-1155

ERC-1155 é um padrão multitoquen que pode gerenciar tokens fungíveis, semifungíveis e não fungíveis em um único contrato.

O esquema de metadados ERC-1155 é especialmente importante porque um contrato pode conter muitos IDs de token com significados diferentes.

Um único contrato ERC-1155 pode representar moedas de jogos, armas, armaduras, ingressos, badges, edições limitadas e colecionáveis únicos.

O padrão ERC-1155 permite que uma URI inclua o placeholder

.

O software cliente substitui

pelo ID de token real antes de buscar os metadados.

A documentação oficial do OpenZeppelin ERC-1155 Metadata URI explica que a extensão de URI de metadados aponta cada token para um arquivo JSON que segue o ERC-1155 Metadata URI JSON Schema.

Os metadados ERC-1155 podem incluir campos como

, , , e outros dados específicos do token.

O esquema permite que carteiras e dApps exibam muitos tipos de ativos de um único contrato sem precisar de lógica personalizada para cada ID de token.

Os metadados ERC-1155 devem ser tratados com cuidado, pois uma substituição incorreta de ID pode causar exibições quebradas ou incorretas.

Um design sólido de metadados ERC-1155 torna cada ID de token fácil de interpretar e recuperar de forma confiável.

Campos comuns em um esquema de metadados de token

O campo mais comum é

, que fornece ao token um título legível por humanos.

O próximo campo comum é

, que explica o que o token representa.

O campo

geralmente aponta para a imagem principal exibida em carteiras e marketplaces.

O campo

pode apontar para mídias mais avançadas, como vídeo, áudio, objetos 3D ou conteúdo interativo, quando houver suporte do cliente.

O campo

pode apontar para uma página oficial com mais informações sobre o token ou a coleção.

O campo

geralmente contém uma matriz de objetos de características usada para raridade, filtragem, estatísticas de jogos e organização de coleções.

O campo

às vezes é usado para sugerir uma cor de fundo para a exibição do ativo.

O campo

é frequentemente usado para metadados no estilo ERC-1155 ou informações estruturadas específicas do projeto.

Alguns projetos adicionam campos como

, , , ou .

Campos personalizados podem ser úteis, mas devem ser documentados para que os aplicativos possam interpretá-los corretamente.

Exemplo de um esquema básico de metadados de NFT

Um arquivo simples de metadados de NFT geralmente é um objeto JSON com alguns campos claros.

Este exemplo mostra um nome legível, uma descrição, uma referência de imagem e dois atributos.

O esquema é simples o suficiente para que carteiras e dApps possam analisá-lo.

A imagem usa uma URI no estilo IPFS, o que significa que a mídia é referenciada por meio de armazenamento endereçado por conteúdo.

Os atributos são estruturados como uma matriz, o que torna mais fácil criar ferramentas de filtragem e raridade.

Um projeto pode adicionar mais campos, mas deve evitar complexidade desnecessária que prejudique a compatibilidade.

Os melhores metadados são legíveis por máquinas e fáceis de entender por humanos.

O campo Name

O campo

fornece ao token seu título de exibição.

Para uma coleção de NFTs, um padrão comum é usar o nome da coleção e o número do token.

Um exemplo é

.

Um item de jogo pode usar um nome como

ou .

Um token de associação pode usar um nome como

.

O nome deve ser estável, claro e não enganoso.

Uma coleção falsa pode copiar o nome de um projeto real, portanto os usuários nunca devem confiar apenas no campo de nome.

O endereço oficial do contrato é mais importante do que o nome exibido.

Os desenvolvedores devem evitar alterar nomes inesperadamente, a menos que o token tenha sido projetado para ser dinâmico.

Um bom campo de nome melhora o reconhecimento sem fingir comprovar autenticidade.

O campo Description

O campo

explica o que o token representa.

Uma descrição clara ajuda os usuários a entender a finalidade, a história, a utilidade ou o papel de associação do ativo.

Para NFTs de arte, a descrição pode explicar o conceito ou o tema da coleção.

Para itens de jogo, ela pode explicar como o item é usado.

Para tokens de ativos do mundo real, ela pode resumir a categoria do ativo enquanto direciona os usuários a documentos jurídicos em outro local.

A descrição não deve incluir alegações enganosas sobre valor, retornos garantidos ou status oficial.

Carteiras e dApps podem mostrar a descrição diretamente aos usuários; portanto, links inseguros ou mensagens de golpe podem criar risco de phishing.

Os desenvolvedores devem manter as descrições úteis e honestas.

Os usuários devem lembrar que uma descrição é fornecida pelo criador do token ou pelo controlador dos metadados.

Uma descrição não é uma verificação independente da qualidade ou legitimidade do token.

O campo Image

O campo

aponta para o arquivo de mídia principal exibido para o token.

Ele pode apontar para PNG, JPG, GIF, SVG ou outro formato de imagem compatível, dependendo do aplicativo.

A imagem pode ser armazenada no IPFS, Arweave, servidores HTTPS ou codificada diretamente nos metadados.

O campo de imagem é importante porque muitos usuários identificam NFTs visualmente.

Um link de imagem quebrado pode fazer um token parecer incompleto, mesmo que a propriedade seja válida on-chain.

Uma imagem enganosa pode fazer um token falso parecer legítimo.

Uma URL de imagem centralizada pode desaparecer se o servidor ou domínio falhar.

Uma URI de imagem endereçada por conteúdo pode melhorar a integridade, mas o conteúdo ainda precisa estar disponível por meio de armazenamento ou pinning.

Os desenvolvedores devem usar armazenamento de imagem durável para ativos de longo prazo.

Os usuários devem verificar a qualidade do armazenamento da imagem antes de confiar em NFTs de alto valor.

O campo Attributes

O campo

é comumente usado para descrever características, raridade, propriedades de jogo, níveis, status ou outros recursos estruturados.

Cada atributo geralmente é um objeto com

e .

Por exemplo,

pode ser e pode ser .

Para um item de jogo,

pode ser e pode ser .

A estrutura dos atributos é importante porque marketplaces e ferramentas de análise a utilizam para filtragem e classificação de raridade.

Atributos inconsistentes podem tornar as ferramentas de raridade imprecisas.

Nomes de características com erros de ortografia podem dividir o que deveria ser uma categoria em várias categorias.

Atributos numéricos devem ser formatados de forma consistente para que as ferramentas possam compará-los corretamente.

NFTs dinâmicos devem deixar claro se os atributos podem mudar com o tempo.

Bons atributos ajudam os usuários a entender a identidade e a utilidade do token.

O campo Properties

O campo

é frequentemente usado para armazenar metadados estruturados além dos dados básicos de nome, descrição e imagem.

Exemplos de metadados ERC-1155 geralmente usam

para informações adicionais sobre o token.

Um item de jogo pode incluir propriedades como raridade, classe, durabilidade ou materiais de criação.

Um token de ingresso pode incluir propriedades como data do evento, nível do assento, local e tipo de acesso.

Um token de ativo do mundo real pode incluir propriedades como categoria do ativo, referência do emissor, jurisdição, hash de documento ou status de verificação.

As propriedades podem ser poderosas porque permitem modelos de dados mais ricos.

Elas também podem se tornar desorganizadas se cada projeto usar nomes e formatos diferentes sem documentação.

Os desenvolvedores devem manter os nomes das propriedades estáveis e previsíveis.

Os aplicativos devem tratar propriedades como dados não confiáveis até que sejam verificadas pela lógica do contrato ou por fontes confiáveis.

Um campo de propriedade pode descrever um ativo, mas não comprova automaticamente que a alegação é verdadeira.

Esquema de metadados de token e IPFS

O IPFS é comumente usado para armazenar metadados de tokens e arquivos de mídia.

A documentação oficial de endereçamento por conteúdo do IPFS explica que o IPFS usa Content Identifiers, ou CIDs, para referenciar dados com base no próprio conteúdo.

Isso é útil para metadados porque um CID pode mostrar se o conteúdo referenciado foi alterado.

Se os metadados JSON forem alterados, o CID também deverá mudar.

Isso oferece aos usuários maior integridade do que uma URL normal de servidor que pode alterar o conteúdo no mesmo endereço.

No entanto, o IPFS não garante automaticamente a disponibilidade para sempre.

Os arquivos de metadados e imagens precisam ser fixados por pinning ou disponibilizados por nós para que os clientes possam recuperá-los.

Um esquema de metadados armazenado no IPFS ainda pode falhar se ninguém mantiver o conteúdo disponível.

Os desenvolvedores devem planejar o pinning e o armazenamento de longo prazo antes de fazer o mint de tokens.

Os usuários devem entender que o endereçamento por conteúdo melhora a integridade, mas a disponibilidade ainda exige suporte de armazenamento.

Esquema de metadados de token e armazenamento HTTP

Alguns projetos armazenam metadados em servidores HTTPS padrão.

Isso pode tornar os metadados fáceis de atualizar, gerar e disponibilizar rapidamente.

É comum em NFTs dinâmicos, ativos de jogos, mecânicas de reveal e ativos que dependem de sistemas de backend ativos.

A desvantagem é que os metadados HTTP dependem do tempo de atividade do servidor, do controle do domínio, da segurança da hospedagem e das operações do projeto.

Se o servidor ficar offline, os metadados do token poderão desaparecer das interfaces dos usuários.

Se o domínio expirar, o endpoint de metadados poderá se tornar inseguro ou indisponível.

Se o operador do servidor alterar o JSON, os usuários poderão ver conteúdo diferente sem uma alteração on-chain.

Os metadados HTTP não são automaticamente ruins, mas devem ser divulgados com clareza.

Os desenvolvedores devem explicar se os metadados são mutáveis e por quanto tempo o armazenamento será mantido.

Os usuários devem ter mais cuidado com ativos de alto valor que dependem inteiramente de servidores centralizados de metadados.

Esquema de metadados de token e metadados on-chain

Metadados on-chain significam que os metadados do token são armazenados ou gerados diretamente pelo contrato inteligente.

Isso pode reduzir a dependência de sistemas externos de armazenamento.

Um contrato pode retornar uma URI

que contém metadados codificados.

Os metadados podem incluir uma imagem SVG on-chain ou lógica de arte generativa.

Os metadados on-chain podem melhorar a durabilidade porque os dados estão vinculados ao estado da blockchain.

Também podem ser mais caros, pois armazenar e gerar dados on-chain consome recursos.

Os metadados on-chain podem ser mais difíceis de alterar, o que é útil para permanência, mas menos útil para jogos ou credenciais dinâmicas.

Os desenvolvedores devem escolher metadados on-chain quando permanência e minimização de confiança forem mais importantes do que flexibilidade.

Os usuários ainda devem inspecionar a lógica do contrato, pois os metadados on-chain também podem ser dinâmicos se o contrato permitir.

Metadados on-chain são um modelo de armazenamento, não uma garantia automática de qualidade.

Esquema de metadados de token e NFTs dinâmicos

NFTs dinâmicos são tokens cujos metadados podem mudar com base em eventos, tempo, jogabilidade, dados de oráculos, decisões de governança ou ações dos usuários.

Metadados dinâmicos podem tornar os NFTs mais úteis e interativos.

Um personagem de jogo pode subir de nível.

Um passe de associação pode mudar de ativo para expirado.

Uma credencial pode ser atualizada após um usuário concluir uma nova conquista.

Um token de ativo do mundo real pode atualizar o status de verificação ou referências de documentos.

O esquema de metadados deve deixar os campos dinâmicos claros.

Os usuários devem saber quais campos podem mudar e quem controla essas alterações.

Um NFT dinâmico não deve ocultar controle administrativo arbitrário por trás de uma linguagem vaga de metadados.

Bons metadados dinâmicos são previsíveis, documentados e vinculados a um comportamento significativo do token.

Esquema de metadados de token e atualizações de metadados

Atualizações de metadados são comuns durante reveals, progressão em jogos, verificação de ativos e correção de erros.

A extensão oficial de atualização de metadados ERC-4906 define eventos que notificam clientes quando os metadados de NFT foram alterados.

Isso é importante porque carteiras e indexadores geralmente armazenam metadados em cache para ganhar velocidade.

Se os metadados mudarem, mas nenhum sinal de atualização for emitido, os usuários poderão continuar vendo informações antigas.

Um esquema de metadados deve ser combinado com um comportamento claro de atualização.

Em um reveal, o projeto deve explicar quando os metadados de placeholder serão alterados para os metadados finais.

Para ativos dinâmicos, o projeto deve explicar quais eventos acionam alterações nos metadados.

Para atualizações controladas por administradores, o projeto deve divulgar quem pode alterar os metadados e sob quais condições.

Atualizações transparentes de metadados geram confiança.

Atualizações ocultas de metadados criam incerteza e podem prejudicar o valor do token.

Esquema de metadados de token e metadados no nível do contrato

Os metadados no nível do token descrevem um ID de token específico.

Os metadados no nível do contrato descrevem todo o contrato ou coleção.

O padrão oficial ERC-7572 de metadados no nível do contrato padroniza

para informações completas no nível do contrato, como nome, descrição e imagem.

Isso é útil porque uma coleção pode precisar de logo, banner, descrição, informações de taxas, links sociais ou imagem no nível do projeto.

Um único NFT em uma coleção pode ter seu próprio Token Metadata Schema, enquanto a coleção também possui um esquema de metadados no nível do contrato.

Ambas as camadas são importantes para a experiência do usuário.

Se os metadados do token estiverem corretos, mas os metadados da coleção estiverem errados, os usuários ainda poderão ver informações confusas.

Se os metadados da coleção estiverem corretos, mas os metadados do token estiverem quebrados, os tokens individuais poderão não ser exibidos adequadamente.

Os desenvolvedores devem oferecer suporte a metadados no nível do token e do contrato quando isso for relevante.

Os usuários devem entender que essas são camadas de metadados relacionadas, mas diferentes.

Esquema de metadados de token e ERC-1046

ERC-1046 amplia as ideias de Token URI para além dos casos de uso básicos de NFT.

A proposta oficial de interoperabilidade ERC-1046 tokenURI adiciona suporte a Token URI para ERC-20 e amplia a interoperabilidade de metadados entre tipos de tokens.

Isso é importante porque tokens fungíveis também podem precisar de metadados.

Um token fungível pode precisar de logo, descrição, detalhes do emissor, links oficiais, observações de conformidade ou referências de documentação.

Metadados padronizados ajudam carteiras e aplicativos a apresentar tokens fungíveis com mais clareza.

No entanto, os usuários não devem tratar campos de metadados como prova de legitimidade.

Um token de golpe pode fornecer um logo e uma descrição atraentes.

O endereço do contrato, o emissor, a liquidez, a segurança, a tokenomics e as fontes oficiais continuam sendo importantes.

O ERC-1046 mostra que esquemas de metadados não tratam apenas de imagens colecionáveis.

Eles fazem parte de um esforço mais amplo para tornar as informações de tokens interoperáveis.

Esquema de metadados de token e ERC-5625

ERC-5625 é uma extensão de metadados proposta relacionada a informações de armazenamento descentralizado para NFTs.

A extensão oficial ERC-5625 NFT Metadata JSON Schema dStorage adiciona uma propriedade de armazenamento descentralizado aos metadados de NFT, para que as informações de armazenamento de ativos possam ser descritas com mais clareza.

Isso é importante porque os metadados geralmente apontam para arquivos armazenados fora da blockchain.

Um token pode parecer durável, mas sua mídia pode depender de acordos de armazenamento pouco claros.

Adicionar metadados relacionados ao armazenamento pode ajudar usuários e aplicativos a entender onde os dados do ativo são armazenados.

Isso também pode ajudar a identificar se o conteúdo é armazenado no IPFS, Arweave ou em outro sistema de armazenamento descentralizado.

Os metadados de armazenamento não garantem permanência por si só.

Eles oferecem aos aplicativos uma maneira mais clara de descrever e inspecionar as premissas de armazenamento.

Para NFTs de alto valor, detalhes sobre armazenamento descentralizado podem ser uma parte importante da due diligence.

Um esquema de metadados se torna mais robusto quando explica tanto o que é o ativo quanto como seus dados são preservados.

Validação de esquema

Validação de esquema significa verificar se os metadados seguem a estrutura esperada.

Um validador pode verificar se o JSON é válido.

Ele pode verificar se os campos obrigatórios estão presentes.

Ele pode verificar se o campo de imagem é uma URI válida.

Ele pode verificar se os atributos estão formatados como uma matriz.

Ele pode verificar se os valores numéricos são armazenados de forma consistente.

Ele pode verificar se os campos de mídia apontam para tipos de arquivo compatíveis.

A validação de esquema ajuda a evitar exibições quebradas em carteiras e erros em marketplaces.

Ela também ajuda desenvolvedores a detectar erros antes do mint ou do reveal.

Um projeto deve validar os metadados antes de publicá-los permanentemente em armazenamento descentralizado.

Esquema de metadados e raridade

As ferramentas de raridade geralmente dependem do campo

nos metadados de NFT.

Se os atributos forem inconsistentes, os cálculos de raridade poderão se tornar imprecisos.

Por exemplo,

, e podem ser tratados como valores diferentes por algumas ferramentas.

Se um token usar

e outro usar , as ferramentas de raridade poderão dividir a categoria de característica.

Se uma característica estiver ausente em alguns tokens, os cálculos de raridade poderão mudar inesperadamente.

Os projetos devem usar nomes e valores de características consistentes em toda a coleção.

Também devem congelar os metadados finais quando a coleção for destinada a ser imutável.

Os usuários devem ter cuidado durante períodos de reveal, pois os dados de raridade podem ainda não estar estáveis.

A qualidade do esquema de metadados pode afetar diretamente a forma como colecionadores avaliam um NFT.

Para coleções com preços baseados em características, metadados bem estruturados são especialmente importantes.

Esquema de metadados e ativos de jogos

Ativos de jogos geralmente precisam de esquemas de metadados mais completos do que NFTs de arte simples.

Um item de jogo pode precisar de campos para nível, durabilidade, poder de ataque, defesa, raridade, classe, elemento, cooldown, status de aprimoramento ou slot de equipamento.

Um NFT de personagem pode precisar de campos para experiência, habilidades, inventário, facção, saúde e estado visual.

Alguns desses campos podem mudar durante a jogabilidade.

Os desenvolvedores devem decidir quais valores pertencem à blockchain e quais valores pertencem aos metadados.

A lógica importante de jogo não deve depender apenas de metadados off-chain não verificados.

Um contrato ou servidor de jogo deve verificar valores importantes antes de permitir ações de alto valor.

Os metadados podem melhorar a exibição, mas as regras do jogo devem ser protegidas por lógica confiável.

Os usuários devem entender se o valor de um item depende de o jogo continuar operando.

Um esquema de metadados pode descrever um ativo de jogo, mas é o ecossistema do jogo que lhe dá utilidade.

Esquema de metadados e ativos do mundo real

Tokens de ativos do mundo real podem usar esquemas de metadados para descrever ativos off-chain.

Os exemplos podem incluir registros imobiliários, commodities, faturas, títulos, cotas de fundos, colecionáveis, créditos de carbono ou credenciais vinculadas à identidade.

O esquema de metadados pode incluir campos para emissor, categoria do ativo, URI do documento, data de avaliação, jurisdição, custodiante, status de verificação e hash do documento.

Esses campos podem ajudar os usuários a entender o token, mas não criam automaticamente propriedade legal.

Os direitos legais dependem de documentos do emissor, contratos, acordos de custódia, jurisdição e regras de resgate.

Um esquema de metadados de ativos do mundo real deve separar informações de marketing de referências juridicamente importantes.

Ele deve evitar alegações vagas que não possam ser verificadas.

Ele deve preservar a integridade dos documentos por meio de hashes ou armazenamento durável, quando possível.

Os usuários devem ler documentos jurídicos oficiais antes de confiar nos metadados de ativos do mundo real.

Os metadados podem apoiar a divulgação, mas não substituem a due diligence jurídica.

Esquema de metadados e riscos de segurança

Os metadados de token podem criar riscos de segurança porque carteiras e dApps buscam e exibem dados de fontes externas.

Um arquivo de metadados malicioso pode incluir links de phishing, mensagens falsas de recompensa, imagens enganosas ou URLs externas perigosas.

Um NFT de spam pode aparecer em uma carteira e usar metadados para instruir o usuário a visitar uma página falsa de resgate.

Uma coleção falsa pode copiar nomes, imagens e atributos de uma coleção real.

Um servidor de metadados comprometido pode posteriormente transformar metadados aparentemente seguros em conteúdo malicioso.

Carteiras e dApps devem tratar metadados como entrada não confiável.

Eles não devem executar scripts provenientes de metadados.

Eles devem higienizar links externos e conteúdo de mídia quando possível.

Os usuários nunca devem inserir frases de recuperação, chaves privadas ou backups de carteira porque os metadados instruem que façam isso.

Um esquema de metadados visualmente bem estruturado não comprova que o token é seguro.

Esquema de metadados e mutabilidade

Mutabilidade significa que os metadados podem mudar depois que o token é criado por mint.

Alguns projetos precisam de mutabilidade porque o token é dinâmico.

Outros projetos prometem que os metadados serão permanentes e inalterados.

O esquema de metadados deve corresponder à promessa do projeto.

Se uma coleção for divulgada como arte imutável, os metadados não devem permanecer sob controle administrativo irrestrito.

Se um token for um item de jogo, metadados dinâmicos podem ser esperados.

Se um token for uma credencial, atualizações podem ser necessárias, mas devem ser auditáveis.

Os usuários devem verificar quem controla as atualizações de metadados.

Os desenvolvedores devem documentar se os metadados são imutáveis, dinâmicos, controlados por administradores ou controlados pela governança.

A mutabilidade oculta é um dos maiores riscos de confiança nos metadados de NFT.

Esquema de metadados e cache

Cache significa armazenar metadados temporariamente para que os aplicativos possam carregar tokens mais rapidamente.

Carteiras, marketplaces, exploradores e indexadores geralmente armazenam metadados em cache.

O cache é útil porque buscar repetidamente cada arquivo de metadados seria lento.

O problema é que os metadados em cache podem ficar desatualizados.

Durante um reveal, alguns aplicativos podem continuar mostrando imagens de placeholder depois que os metadados finais forem publicados.

Durante uma atualização dinâmica, alguns aplicativos podem mostrar atributos antigos até que o cache seja atualizado.

Os padrões de atualização de metadados podem ajudar os clientes a saber quando atualizar os dados armazenados em cache.

Os desenvolvedores devem oferecer suporte a eventos de atualização quando houver previsão de mudança dos metadados.

Os usuários devem entender que atrasos na exibição podem ser causados pelo cache, e não por falha do token.

Um esquema de metadados sólido funciona melhor quando combinado com um bom comportamento de atualização de cache.

Esquema de metadados e indexadores

Indexadores coletam dados de blockchain e os organizam para aplicativos.

Para metadados de token, os indexadores podem chamar

, buscar arquivos JSON, analisar atributos, armazenar imagens em cache e fornecer respostas de API.

Os indexadores precisam de esquemas de metadados previsíveis para funcionar de forma eficiente.

Se cada projeto usar nomes de campo incomuns, os indexadores precisarão criar lógica personalizada.

Se os arquivos de metadados forem inválidos ou lentos, os indexadores poderão deixar de exibir os ativos corretamente.

Se os metadados mudarem sem eventos, os indexadores poderão mostrar dados desatualizados.

Por isso, a consistência do esquema ajuda todo o ecossistema Web3.

Os desenvolvedores devem testar metadados com o comportamento de indexadores comuns antes do lançamento.

Os usuários devem saber que carteiras diferentes podem mostrar metadados diferentes se seus indexadores forem atualizados em momentos distintos.

Os indexadores são uma parte oculta, mas importante, da usabilidade dos metadados de token.

Melhores práticas para desenvolvedores

Use campos de metadados amplamente compatíveis, como

, , e .

Retorne JSON válido de cada Token URI.

Use nomes e valores de características estáveis em toda uma coleção.

Use armazenamento durável para arquivos de metadados e mídia.

Faça pinning de arquivos IPFS ou use um plano confiável de armazenamento de longo prazo.

Documente se os metadados são mutáveis, imutáveis ou dinâmicos.

Emita eventos de atualização de metadados quando os metadados mudarem.

Valide os metadados antes de publicá-los permanentemente.

Teste o comportamento de exibição em carteiras, exploradores e dApps.

Evite colocar promessas jurídicas sensíveis apenas dentro de metadados editáveis.

Melhores práticas para usuários

Verifique se os metadados do token estão armazenados no IPFS, em um servidor, no Arweave ou on-chain.

Verifique o endereço oficial do contrato em vez de confiar no nome ou na imagem do token.

Tenha cuidado com metadados que contêm links externos ou alegações de recompensa.

Não assine transações apenas para visualizar metadados.

Não insira uma frase de recuperação em nenhuma página vinculada aos metadados do token.

Verifique se os metadados podem ser alterados por um administrador.

Analise cuidadosamente os atributos durante períodos de reveal de NFTs.

Entenda que uma imagem exibida não comprova autenticidade.

Para tokens de ativos do mundo real, leia os documentos jurídicos fora do arquivo de metadados.

Trate os metadados como informações úteis, e não como prova independente de valor ou segurança.

Erros comuns em esquemas de metadados de token

O primeiro erro é publicar JSON inválido.

O segundo erro é usar nomes de atributos inconsistentes entre tokens.

O terceiro erro é apontar campos de imagem para arquivos indisponíveis.

O quarto erro é depender de um servidor centralizado sem divulgar isso.

O quinto erro é alterar metadados após o mint sem regras claras.

O sexto erro é esquecer os requisitos de substituição de

do ERC-1155.

O sétimo erro é usar formatos de mídia não compatíveis sem imagens alternativas.

O oitavo erro é tratar metadados como juridicamente vinculantes quando eles são apenas descritivos.

O nono erro é não emitir eventos de atualização quando os metadados mudam.

O décimo erro é incluir links inseguros que podem expor usuários a phishing.

FAQ

O que significa Token Metadata Schema?

Token Metadata Schema significa o formato estruturado usado para descrever os metadados de um token de criptomoeda, geralmente em JSON.

Token Metadata Schema é apenas para NFTs?

Não. Ele é mais comum em NFTs, mas esquemas de metadados também podem oferecer suporte a tokens fungíveis, tokens de ativos do mundo real e tokens específicos de aplicativos.

Quais campos são comuns nos metadados de NFT?

Os campos comuns incluem

, , , , e .

Qual é a diferença entre Token URI e Token Metadata Schema?

A Token URI aponta para os metadados, enquanto o Token Metadata Schema define a estrutura dos metadados encontrados nesse local.

O que é ERC-721 Metadata JSON Schema?

É o esquema básico de metadados descrito pelo ERC-721 para metadados de NFT retornados por meio de uma Token URI.

O que é ERC-1155 Metadata URI JSON Schema?

É o esquema de metadados usado por tokens ERC-1155, incluindo suporte para substituição de ID de token por meio de

.

Os metadados de token podem ser armazenados no IPFS?

Sim. Os metadados de token podem ser armazenados no IPFS usando identificadores de conteúdo que ajudam a verificar a integridade do conteúdo.

O IPFS garante que os metadados estarão sempre disponíveis?

Não. O IPFS melhora o endereçamento por conteúdo, mas os arquivos ainda precisam ser fixados por pinning ou disponibilizados para que os usuários possam recuperá-los.

Os metadados de token podem mudar após o mint?

Sim. Os metadados podem mudar se o projeto usar metadados dinâmicos, servidores mutáveis, URIs-base controladas por administradores ou lógica de resolução atualizável.

O que são metadados dinâmicos de token?

Metadados dinâmicos de token são metadados que mudam com base no tempo, jogabilidade, atividade do usuário, dados de oráculos, estado do contrato ou atualizações do projeto.

Para que serve o ERC-4906?

O ERC-4906 define eventos de atualização de metadados para que carteiras e aplicativos saibam quando os metadados de NFT devem ser atualizados.

Para que serve o ERC-7572?

O ERC-7572 padroniza

para metadados no nível do contrato, como nome, descrição e imagem da coleção.

Os metadados podem ser maliciosos?

Sim. Os metadados podem incluir links de phishing, alegações falsas de recompensa, imagens enganosas ou referências externas inseguras.

Por que as características de NFT às vezes são exibidas incorretamente?

As características de NFT podem ser exibidas incorretamente porque os atributos são inconsistentes, ausentes, escritos incorretamente, armazenados em cache ou formatados de uma maneira que o cliente não entende.

O que torna um Token Metadata Schema bom?

Um bom Token Metadata Schema é válido, consistente, durável, documentado, compatível com ferramentas comuns e deixa claro se os metadados podem mudar.

Conclusão

Token Metadata Schema é o formato estruturado que informa a carteiras, dApps, exploradores, jogos, marketplaces e indexadores como ler informações sobre um token de criptomoeda.

Ele é mais importante para NFTs porque a propriedade do NFT é armazenada on-chain, enquanto nomes, imagens, características, descrições e mídias geralmente são armazenados por meio de arquivos de metadados.

ERC-721 e ERC-1155 definem padrões de metadados que ajudam os aplicativos a resolver e exibir informações de tokens de maneira consistente.

Um bom esquema de metadados torna os tokens mais fáceis de entender, filtrar, negociar, verificar e usar em aplicativos.

Um esquema de metadados fraco pode causar imagens quebradas, características ausentes, dados desatualizados, risco de phishing e confusão para os usuários.

Os campos importantes incluem

, , , , e propriedades específicas do projeto.

Opções de armazenamento como IPFS, HTTPS, Arweave e dados on-chain afetam permanência, mutabilidade, custo e confiança.

As atualizações de metadados devem ser transparentes, especialmente para reveals, NFTs dinâmicos, ativos de jogos, credenciais e tokens de ativos do mundo real.

Os desenvolvedores devem validar metadados, usar armazenamento durável, documentar a mutabilidade, emitir eventos de atualização e testar em ferramentas Web3 comuns.

Os usuários devem verificar endereços de contratos, evitar links suspeitos em metadados, entender o risco de armazenamento e tratar os metadados como descritivos, e não como prova absoluta.

Em um glossário cripto, Token Metadata Schema deve ser entendido como o formato de dados que dá aos tokens de criptomoeda um significado legível por humanos e permite que o ecossistema Web3 exiba informações de tokens de forma consistente e segura.