URI de metadados

O que é uma URI de metadados?

Uma URI de metadados é um link que aponta para o arquivo de metadados de um ativo cripto, geralmente um NFT.

Em termos simples, ela informa às carteiras, marketplaces, jogos e aplicativos onde encontrar informações sobre um token.

Essas informações podem incluir o nome do token, a descrição, a imagem, a animação, o modelo 3D, os atributos, a URL externa, características de raridade e outros dados de exibição.

No caso dos NFTs, a URI de metadados é importante porque o próprio token muitas vezes não armazena diretamente todas as ilustrações e informações descritivas on-chain.

Em vez disso, o contrato inteligente armazena ou retorna uma URI que aponta para um arquivo JSON de metadados.

O padrão ERC-721 para NFTs inclui uma extensão opcional de metadados com uma função tokenURI, que pode retornar uma URI para um NFT específico.

Essa URI ajuda os aplicativos a entender o que o NFT deve exibir e como deve ser descrito.

Sem uma URI de metadados funcional, um NFT ainda pode existir on-chain, mas as carteiras e os marketplaces talvez não saibam exibir corretamente sua imagem, nome ou características.

Como funciona uma URI de metadados

Uma URI de metadados conecta o ID de um token na blockchain a metadados off-chain ou on-chain.

Quando um usuário abre um NFT em uma carteira ou marketplace, o aplicativo geralmente solicita ao contrato inteligente a URI do token.

Em seguida, o aplicativo busca o arquivo de metadados nessa URI.

O arquivo de metadados costuma ser escrito em JSON, um formato comum para dados estruturados.

Por exemplo, o arquivo JSON pode incluir campos como name, description, image, animation_url e attributes.

A carteira ou o marketplace lê esses campos e exibe o NFT para o usuário.

Esse processo facilita o uso dos NFTs, pois não é necessário armazenar arquivos de mídia grandes diretamente no contrato inteligente.

No entanto, isso também cria riscos, pois a exibição do ativo pode depender de os metadados vinculados continuarem disponíveis e inalterados.

URI de metadados vs. URI do token

URI de metadados e URI do token são termos estreitamente relacionados.

URI do token geralmente se refere à função ou ao valor do contrato inteligente que retorna a localização dos metadados de um token específico.

URI de metadados refere-se ao link ou caminho efetivo onde os metadados podem ser encontrados.

Em muitas discussões sobre NFTs, os dois termos são usados quase como sinônimos.

Para NFTs ERC-721, tokenURI é o nome comum da função que retorna a URI de metadados de um ID de token.

Para tokens ERC-1155, o modelo de URI pode aceitar a substituição do ID, inserindo o ID do token no caminho da URI.

O padrão ERC-1155 de múltiplos tokens define um esquema JSON de URI de metadados e explica como os clientes podem substituir a string {id} pelo ID real do token.

Quais informações são armazenadas nos metadados de NFT?

Os metadados de NFT geralmente armazenam as informações descritivas necessárias para que os aplicativos exibam o ativo.

Os campos mais comuns são name, description, image, external_url, animation_url e attributes.

O campo image pode apontar para um arquivo PNG, JPEG, GIF, SVG ou outro formato de mídia compatível.

O campo animation_url pode apontar para um vídeo, arquivo de áudio, experiência em HTML, modelo 3D ou arquivo de mídia interativa.

O campo attributes geralmente armazena características como plano de fundo, roupas, nível de raridade, tipo de item, classe do personagem ou estatísticas do jogo.

Essas características são especialmente importantes para coleções de NFTs, jogos blockchain, projetos de avatares, terrenos virtuais e ativos do metaverso.

Os metadados também podem incluir campos técnicos ou específicos do projeto, dependendo da plataforma e do padrão do token.

Metadados de qualidade devem ser claros, precisos e consistentes com o ativo que os usuários esperam receber.

Formatos comuns de URI de metadados

Os formatos mais comuns de URI de metadados incluem links HTTPS, links IPFS, links Arweave e URIs de dados totalmente on-chain.

Uma URI de metadados HTTPS aponta para um servidor web comum.

Esse formato é fácil de usar, mas pode oferecer riscos se o servidor ficar indisponível, alterar o arquivo ou remover o conteúdo.

Uma URI de metadados IPFS aponta para conteúdo armazenado por meio do InterPlanetary File System.

A documentação do IPFS sobre endereçamento de conteúdo explica que o IPFS usa identificadores de conteúdo, ou CIDs, para identificar o conteúdo com base nele próprio.

Isso é útil porque links baseados em conteúdo podem ajudar os usuários a verificar se o arquivo obtido corresponde ao conteúdo esperado.

Uma URI de metadados Arweave aponta para dados armazenados na Arweave, projetada para armazenamento descentralizado permanente.

O site oficial da Arweave descreve a Arweave como um disco rígido sem permissões que armazena dados permanentemente e incentiva os nós a mantê-los.

Uma URI de dados on-chain armazena os metadados diretamente no contrato inteligente ou retorna metadados codificados da blockchain.

Os metadados on-chain podem ser duráveis, mas também podem ter custos mais altos e limitações técnicas.

Por que as URIs de metadados são importantes para NFTs

As URIs de metadados são importantes porque afetam a aparência dos NFTs e a compreensão dos usuários sobre o que possuem.

Um NFT pode ter um ID de token e um endereço de proprietário on-chain, mas os metadados explicam a identidade e a aparência do ativo.

Se a URI de metadados deixar de funcionar, o NFT poderá aparecer sem imagens ou características, ou com informações de exibição incorretas.

Se a equipe do projeto puder alterar a URI de metadados, o NFT poderá exibir outro conteúdo posteriormente.

Por isso, colecionadores experientes e usuários de cripto costumam perguntar se os metadados estão congelados, descentralizados ou totalmente on-chain.

A qualidade dos metadados pode afetar a confiança, o valor de mercado, a utilidade em jogos, a compatibilidade com o metaverso e a preservação a longo prazo.

Para projetos cripto, o design dos metadados não é apenas um detalhe técnico.

Ele faz parte da confiabilidade do ativo e da experiência do usuário.

URI de metadados centralizada

Uma URI de metadados centralizada geralmente aponta para um arquivo hospedado em um servidor web comum ou serviço de nuvem.

Esse formato é simples e rápido para desenvolvedores.

Ele também permite que as equipes atualizem os metadados com facilidade caso precisem corrigir erros ou revelar ativos após a mintagem.

No entanto, metadados centralizados criam riscos de confiança.

Se o servidor ficar indisponível, o NFT poderá perder sua imagem ou suas características nas interfaces de carteira.

Se a equipe do projeto alterar o arquivo, o NFT poderá exibir metadados diferentes dos que os usuários esperavam.

Se o domínio expirar ou for tomado por terceiros, os usuários poderão ver conteúdo indisponível ou malicioso.

Metadados centralizados podem ser aceitáveis para alguns projetos, mas os usuários devem entender essa desvantagem.

URI de metadados descentralizada

Uma URI de metadados descentralizada geralmente aponta para conteúdo armazenado por sistemas como IPFS ou Arweave.

Isso pode aumentar a durabilidade e reduzir a dependência do servidor de uma única empresa.

No IPFS, os usuários costumam ver links que começam com ipfs:// seguidos de um CID.

Na Arweave, os usuários costumam ver links baseados em transações que apontam para dados armazenados.

O armazenamento descentralizado não é automaticamente perfeito.

O conteúdo no IPFS ainda precisa ser fixado (pinned) ou hospedado por nós para continuar fácil de recuperar.

A Arweave busca oferecer armazenamento permanente, mas os usuários ainda devem verificar se os arquivos corretos foram carregados e vinculados.

Os projetos de NFT mais sólidos geralmente tornam o armazenamento dos metadados transparente e fácil de verificar.

URI de metadados on-chain

Metadados on-chain são armazenados diretamente na blockchain ou gerados pelo contrato inteligente.

Essa abordagem pode reduzir a dependência de servidores e redes de armazenamento externos.

Ela costuma ser usada por projetos que buscam máxima durabilidade ou arte totalmente on-chain.

Os metadados on-chain podem usar uma URI de dados que inclui JSON codificado diretamente na resposta de tokenURI.

Isso pode tornar o NFT mais autossuficiente, pois não é necessário buscar os metadados em um site separado.

A principal limitação é o custo.

Armazenar imagens grandes, animações ou arquivos 3D diretamente on-chain pode ser caro ou inviável.

Por esse motivo, muitos projetos armazenam pequenos metadados on-chain e mantêm arquivos de mídia maiores em outros locais.

URI base

Uma URI base é um caminho inicial compartilhado por muitos tokens no mesmo contrato inteligente.

Em vez de armazenar um link completo de metadados para cada token, o contrato pode combinar um caminho base com um ID de token.

Por exemplo, um projeto pode usar um caminho base e acrescentar o número do token ao final para localizar cada arquivo de metadados.

Esse design pode reduzir os custos de armazenamento do contrato inteligente e simplificar coleções grandes de NFTs.

No entanto, o design da URI base também pode criar riscos de atualização se o proprietário do contrato puder alterar o caminho base posteriormente.

Se o caminho base mudar, os metadados de muitos tokens poderão mudar ao mesmo tempo.

Os usuários devem verificar se a URI base é fixa, atualizável ou controlada por uma carteira de administrador.

Metadados congelados

Metadados congelados são metadados bloqueados pelo projeto para que não possam ser alterados por meio de ações administrativas comuns.

Isso é importante para colecionadores de NFTs porque aumenta a confiança de que o ativo exibido não será alterado posteriormente.

Congelar os metadados nem sempre significa que os arquivos são perfeitamente permanentes.

Em geral, isso significa que o contrato inteligente ou a plataforma não permite mais que a equipe do projeto atualize o link dos metadados.

A durabilidade efetiva ainda depende do local onde os metadados e arquivos de mídia estão armazenados.

Por exemplo, metadados congelados que apontam para IPFS ou Arweave podem ser mais confiáveis do que metadados congelados que apontam para um servidor centralizado frágil.

URI de metadados e revelação de NFTs

Muitas coleções de NFTs usam URIs de metadados durante eventos de revelação.

Antes da revelação, todos os tokens podem apontar para uma imagem temporária ou um arquivo de metadados oculto.

Após a revelação, o projeto atualiza a URI base ou os arquivos de metadados para que cada token exiba sua arte e suas características finais.

Esse processo é comum, mas exige confiança.

Os usuários precisam confiar que o processo de revelação é justo e que a equipe não manipulará características raras.

Projetos melhores explicam claramente o método de revelação e usam aleatoriedade transparente ou verificação pública sempre que possível.

Após a revelação, os usuários geralmente preferem que os metadados sejam congelados ou armazenados de forma durável.

URI de metadados em jogos blockchain

As URIs de metadados são importantes em jogos blockchain porque os ativos do jogo costumam ter características, níveis, equipamentos, estatísticas e histórico de melhorias.

Um NFT de espada pode incluir poder de ataque, raridade, durabilidade, tipo de elemento e dados de imagem.

Um NFT de personagem pode incluir classe, nível, habilidades, roupas e dados de animação.

Alguns metadados de jogos são estáticos, enquanto outros são dinâmicos.

Os metadados dinâmicos podem mudar quando um jogador melhora um item, conclui uma missão ou desbloqueia uma nova forma.

Isso cria ativos mais interativos, mas também exige confiança nas regras de atualização do jogo.

Os usuários devem entender quem pode alterar os metadados e se as mudanças são controladas por contratos inteligentes, servidores do jogo ou administradores do projeto.

URI de metadados no metaverso

No metaverso, as URIs de metadados podem definir a aparência e o funcionamento dos ativos virtuais.

Um NFT de terreno virtual pode usar metadados para descrever a localização, o tamanho do lote, as coordenadas, a imagem de prévia e os dados do mundo.

Um NFT vestível pode usar metadados que apontam para um modelo 3D, arquivos de textura, arquivos de animação ou informações de compatibilidade.

Um NFT de ingresso para evento pode usar metadados para descrever direitos de entrada, data, tipo de badge e benefícios relacionados.

Os ativos do metaverso precisam de metadados confiáveis porque a experiência do usuário depende da capacidade dos aplicativos de carregar o objeto digital correto.

Se os metadados estiverem ausentes ou mal estruturados, o ativo poderá não ser exibido corretamente em carteiras, jogos ou mundos virtuais.

Riscos de segurança das URIs de metadados

O primeiro risco são metadados indisponíveis.

Se a URI apontar para um arquivo inexistente, o NFT poderá não ser exibido corretamente.

O segundo risco são metadados alterados.

Se o projeto puder mudar a URI ou o conteúdo do arquivo, os usuários talvez não recebam o ativo que esperavam a longo prazo.

O terceiro risco são metadados maliciosos.

Um arquivo de metadados ou link externo pode direcionar os usuários para sites inseguros ou páginas de phishing.

O quarto risco são ativos falsos.

Golpistas podem criar NFTs com imagens copiadas, nomes enganosos ou metadados falsos de coleção.

O quinto risco é o vazamento de privacidade.

Alguns links de metadados ou mídia podem revelar o comportamento dos usuários quando são carregados por servidores de rastreamento.

O sexto risco é a dependência de plataformas.

Um NFT pode existir tecnicamente on-chain, embora seu conteúdo visível dependa de uma API privada ou de um aplicativo centralizado.

Como avaliar uma URI de metadados

Comece verificando se a URI usa HTTPS, IPFS, Arweave ou dados on-chain.

Confira se o arquivo de metadados é carregado corretamente e corresponde ao ativo esperado.

Verifique se o arquivo de imagem ou mídia também aponta para um armazenamento durável.

Procure sinais de que os metadados foram congelados ou tornados imutáveis.

Confira se o proprietário do contrato inteligente pode alterar a URI base.

Verifique se os metadados incluem campos claros de nome, descrição, imagem e atributos.

Evite clicar em links externos desconhecidos dentro dos metadados de NFT.

Compare o endereço do contrato com fontes oficiais do projeto antes de confiar nos metadados.

No caso de NFTs valiosos, analise o contrato inteligente e o método de armazenamento antes de comprar.

URI de metadados vs. URI de mídia

Uma URI de metadados aponta para o arquivo de metadados do token.

Uma URI de mídia aponta para o arquivo efetivo de imagem, animação, vídeo, áudio ou 3D referenciado nos metadados.

Por exemplo, a URI de metadados pode apontar para um arquivo JSON.

Dentro desse arquivo JSON, o campo image pode apontar para uma URI de imagem separada.

Os dois links são importantes.

Se a URI de metadados funcionar, mas o link da mídia estiver indisponível, o NFT ainda poderá ser exibido incorretamente.

Um projeto de NFT sólido deve usar armazenamento durável tanto para os metadados quanto para a mídia.

Equívocos comuns sobre URIs de metadados

Um equívoco comum é acreditar que a imagem do NFT está sempre armazenada diretamente on-chain.

Em muitos casos, o contrato inteligente apenas aponta para uma URI de metadados, e a imagem fica armazenada em outro local.

Outro equívoco é acreditar que o IPFS garante automaticamente disponibilidade permanente.

O IPFS usa endereçamento de conteúdo, mas o conteúdo ainda precisa ser hospedado ou fixado (pinned) para que os usuários possam recuperá-lo.

Um terceiro equívoco é acreditar que metadados congelados sempre significam mídia permanente.

Metadados congelados podem bloquear o link, mas os arquivos vinculados ainda precisam de armazenamento durável.

Um quarto equívoco é acreditar que todo NFT com metadados é autêntico.

Golpistas podem copiar metadados e imagens, por isso os usuários devem verificar o contrato e a fonte da coleção.

Perguntas frequentes

O que é uma URI de metadados em cripto?

Uma URI de metadados é um link que aponta para o arquivo de metadados de um token, geralmente um NFT.

O que os metadados de NFT incluem?

Os metadados de NFT podem incluir o nome do token, a descrição, a imagem, a animação, as características, os atributos, a URL externa e outras informações de exibição.

Uma URI de metadados fica armazenada on-chain?

A URI pode ser armazenada ou retornada pelo contrato inteligente, mas o próprio arquivo de metadados costuma ficar armazenado off-chain.

O que é tokenURI?

tokenURI é uma função comum do ERC-721 que retorna a URI de metadados do ID de um NFT específico.

Qual é a diferença entre URI de metadados e URI de imagem?

A URI de metadados aponta para o arquivo JSON de metadados, enquanto a URI de imagem aponta para o arquivo de imagem ou mídia propriamente dito, indicado nesses metadados.

O IPFS é melhor do que HTTPS para metadados?

O IPFS pode oferecer armazenamento baseado em conteúdo, enquanto o HTTPS depende de um servidor web. No entanto, o conteúdo no IPFS ainda precisa ser fixado (pinned) ou hospedado para garantir acesso confiável.

O que significa metadados congelados?

Metadados congelados são metadados bloqueados pelo projeto para que não possam ser alterados facilmente por meio dos controles administrativos comuns.

Os metadados de NFT podem mudar após a mintagem?

Sim. Os metadados podem mudar se o contrato inteligente ou a configuração de armazenamento permitir que a equipe do projeto ou um administrador atualize a URI ou o conteúdo do arquivo.

Por que a imagem do meu NFT desapareceu?

A imagem de um NFT pode desaparecer se a URI de metadados, a URI de mídia, o servidor, o gateway ou o provedor de armazenamento não conseguir carregar o arquivo.

O que os usuários devem verificar antes de comprar um NFT?

Os usuários devem verificar o endereço do contrato, a URI de metadados, o método de armazenamento, o status de congelamento dos metadados, os links de mídia, os termos do projeto e a autenticidade da coleção.

Conclusão

Uma URI de metadados é uma parte essencial da forma como NFTs e outros ativos cripto exibem informações em carteiras, marketplaces, jogos e aplicativos do metaverso.

Ela conecta um ID de token a um arquivo de metadados que explica o nome, a imagem, a descrição, as características e os links de mídia do ativo.

As URIs de metadados tornam os NFTs mais flexíveis e fáceis de exibir, mas também criam riscos de armazenamento, segurança e confiança.

Uma configuração sólida de URI de metadados deve ser transparente, durável, precisa e difícil de manipular depois que os usuários compram o ativo.

Os usuários devem entender se os metadados são centralizados, descentralizados, on-chain, congelados ou atualizáveis.

Também devem verificar se os arquivos de mídia estão armazenados de forma confiável e se o contrato do NFT é autêntico.

No universo cripto, a propriedade é apenas uma parte da história do ativo.

A URI de metadados ajuda a definir a aparência do ativo, como ele é descrito e se os usuários podem confiar em sua exibição a longo prazo.