Metadados on-chain

O que são metadados on-chain?

Metadados on-chain são informações descritivas sobre um ativo cripto, contrato inteligente, NFT, token, objeto de carteira ou registro baseado em blockchain, armazenadas diretamente em uma blockchain, e não apenas em um servidor externo.

Em termos simples, os metadados explicam o que é um ativo de blockchain. Metadados on-chain significa que essa descrição está no estado da blockchain, nos dados de transação, no armazenamento do contrato, nos logs de eventos ou no resultado codificado do contrato.

Em um NFT, os metadados podem incluir nome, descrição, referência à imagem, atributos, características de raridade, arquivo de animação, link externo, dados do criador, detalhes da licença ou propriedades de jogo.

Em um contrato de token, os metadados podem incluir nome, símbolo, logotipo, descrição, site, colaboradores ou informações de exibição.

Em um contrato inteligente, os metadados podem incluir identidade do contrato, informações do projeto, detalhes de versão, referências de esquema e links para recursos relacionados.

Essa expressão é importante porque muitos ativos cripto armazenam apenas a propriedade on-chain, enquanto o arquivo descritivo ou a mídia ficam em outro lugar.

Os metadados on-chain buscam reduzir essa dependência externa, mantendo mais informações sobre a identidade do ativo dentro da própria blockchain.

O padrão ERC-721 define uma extensão opcional de metadados em que tokenURI pode apontar para um arquivo JSON com campos de nome, descrição e imagem.

O padrão ERC-1155 permite que cada ID de token represente um tipo configurável de token, com metadados, oferta e atributos próprios.

Os metadados on-chain são especialmente importantes para NFTs, ativos tokenizados, itens de jogos, registros de identidade digital, ativos de DAOs, projetos de colecionáveis e qualquer objeto cripto cuja verificabilidade de longo prazo seja relevante.

Principais pontos sobre metadados on-chain

• • Metadados on-chain são informações sobre ativos armazenadas diretamente em uma blockchain ou retornadas diretamente por um contrato inteligente.
  • Podem descrever NFTs, tokens fungíveis, contratos inteligentes, coleções, tokens de ativos do mundo real, itens de jogos, credenciais de identidade e registros de DAOs.
  • Os campos comuns de metadados incluem nome, descrição, imagem, animação, atributos, links externos, características, níveis, detalhes do criador e informações da coleção.
  • Metadados totalmente on-chain podem aumentar a permanência, a auditabilidade e a resistência à censura.
  • Metadados on-chain podem ser caros, pois o armazenamento e o processamento na blockchain são recursos limitados.
  • Muitos projetos de NFT usam metadados híbridos: o token e o URI ficam on-chain, enquanto o JSON ou a mídia são armazenados por meio do IPFS, do Arweave ou de outra camada de armazenamento.
  • Os metadados podem ser estáticos, mutáveis, dinâmicos, selados ou gerados inteiramente pela lógica do contrato inteligente.
  • Padrões de metadados ajudam carteiras, exploradores, jogos, indexadores e aplicativos a exibir ativos de forma consistente.
  • Metadados on-chain não comprovam automaticamente titularidade de direitos autorais, originalidade artística, direitos legais ou valor de investimento.
  • Os usuários devem verificar onde os metadados e a mídia estão armazenados antes de comprar, fazer mint ou confiar em um ativo tokenizado.

Como funcionam os metadados on-chain

Os metadados on-chain funcionam colocando dados descritivos ou a lógica de recuperação de metadados em uma transação de blockchain ou contrato inteligente.

Um contrato simples pode armazenar uma string com todo o JSON dos metadados.

Outro contrato pode retornar um data URI codificado em Base64 que contém os metadados diretamente.

Outro contrato pode gerar metadados dinamicamente a partir do ID do token, de dados do bloco, do estado do jogo ou de outras variáveis do contrato.

Um contrato também pode armazenar apenas um URI on-chain, enquanto o arquivo de metadados propriamente dito fica off-chain.

Esse último método é comum, mas não representa metadados totalmente on-chain, pois o JSON descritivo ainda depende de outro local de armazenamento.

Um NFT totalmente on-chain pode retornar todos os metadados essenciais pelo próprio contrato, sem depender de um site comum ou servidor centralizado.

Um NFT híbrido pode manter a propriedade e um link endereçado pelo conteúdo on-chain, enquanto armazena imagens ou vídeos pesados fora da blockchain.

Em geral, a escolha envolve equilibrar custo e permanência.

Armazenar tudo on-chain pode ser mais duradouro, mas também pode ser muito mais caro e menos flexível.

Metadados on-chain vs. metadados off-chain

Metadados on-chain são armazenados ou gerados diretamente pela infraestrutura da blockchain.

Metadados off-chain são armazenados fora da blockchain e referenciados por uma URL, endpoint de API, link de armazenamento descentralizado ou outro ponteiro externo.

Por exemplo, um contrato de NFT pode armazenar um tokenURI que aponta para um arquivo JSON hospedado em um site.

Nesse caso, a propriedade do token é on-chain, mas o arquivo de metadados é off-chain.

Se o site desaparecer, alterar o arquivo, bloquear o acesso ou retornar dados incorretos, a exibição do NFT pode falhar.

Se os metadados forem armazenados diretamente no contrato, o ativo dependerá menos do site.

Metadados off-chain podem ser mais baratos e fáceis de atualizar.

Metadados on-chain podem ser mais transparentes e duradouros.

Nenhum dos modelos é ideal para todos os casos de uso.

Um bom design de ativo escolhe o modelo de armazenamento adequado à finalidade do ativo, aos limites de custo, às necessidades jurídicas e à vida útil esperada.

Metadados on-chain vs. mídia on-chain

Metadados e mídia estão relacionados, mas não são a mesma coisa.

Metadados são as informações descritivas sobre o ativo.

Mídia é a imagem, animação, áudio, vídeo, modelo 3D ou arquivo interativo que os usuários veem ou utilizam.

Um NFT pode armazenar metadados on-chain e apontar para mídia off-chain.

Outro NFT pode armazenar tanto os metadados quanto a mídia inteiramente on-chain.

Um terceiro NFT pode não armazenar nenhum dos dois totalmente on-chain e manter apenas uma URL que aponta para um servidor.

Essa distinção importa porque um projeto pode divulgar que possui metadados on-chain e ainda depender de mídia off-chain.

Por exemplo, o contrato pode retornar um objeto JSON on-chain, mas o campo de imagem desse JSON pode apontar para o IPFS ou outro sistema de armazenamento.

Esse ainda pode ser um bom design se a mídia usar armazenamento endereçado pelo conteúdo e persistente.

No entanto, os usuários devem entender exatamente quais partes estão on-chain e quais são externas.

Metadados ERC-721

ERC-721 é o padrão de NFT mais conhecido nos sistemas de contratos inteligentes no estilo Ethereum.

A extensão de metadados ERC-721 inclui as funções name, symbol e tokenURI.

A função tokenURI retorna um URI para um ID de token específico.

Esse URI pode apontar para um arquivo JSON que segue o esquema JSON de metadados ERC-721.

O padrão descreve campos comuns, como nome, descrição e imagem.

Em um design totalmente on-chain, tokenURI pode retornar um data URI que contém o JSON diretamente, em vez de apontar para um arquivo externo.

Isso permite que carteiras e aplicativos leiam os metadados sem buscar uma URL externa tradicional.

No entanto, nem todas as interfaces oferecem o mesmo suporte a todos os formatos on-chain avançados.

Os desenvolvedores devem testar como carteiras, exploradores e aplicativos exibem seus metadados.

Um padrão pode definir a estrutura, mas a exibição no mundo real ainda depende do suporte do software.

Metadados ERC-1155

ERC-1155 é um padrão multi-token que pode representar ativos fungíveis, não fungíveis e semifungíveis em um único contrato.

O padrão permite que cada ID de token represente um tipo diferente de token.

Cada tipo de token pode ter metadados, oferta e atributos próprios.

Isso torna o ERC-1155 útil para jogos, colecionáveis, associações, edições, recompensas e coleções de ativos com vários tipos de itens.

Os metadados ERC-1155 costumam usar um padrão de URI em que o ID do token é inserido no caminho dos metadados.

Isso pode tornar coleções grandes mais eficientes, pois um contrato pode gerenciar vários tokens.

Os metadados on-chain para ERC-1155 podem ser úteis quando itens de jogos ou edições precisam de uma identidade duradoura.

Também podem ser caros se cada item tiver muitos campos exclusivos.

Os desenvolvedores podem armazenar propriedades essenciais on-chain e usar armazenamento endereçado pelo conteúdo para arquivos maiores.

O melhor design depende da frequência com que os metadados mudam e da quantidade de dados necessária para cada token.

Metadados no nível do contrato

Metadados no nível do contrato descrevem o próprio contrato inteligente ou a coleção, e não um ID de token específico.

Podem incluir nome da coleção, descrição, imagem de perfil, imagem de banner, imagem em destaque, site, colaboradores e outras informações de exibição.

O rascunho do padrão contractURI ERC-7572 propõe uma função contractURI para retornar metadados no nível do contrato.

O ERC-7572 afirma que a string retornada pode ser um recurso off-chain ou uma string JSON de dados on-chain.

Isso importa porque muitos aplicativos precisam de informações sobre a coleção, não apenas sobre cada token.

Uma carteira pode querer exibir o logotipo de uma coleção.

Um explorador pode querer exibir a descrição de um contrato.

Um painel de DAO pode querer apresentar o contexto verificado do projeto.

Metadados no nível do contrato podem melhorar a usabilidade quando são precisos e controlados com segurança.

Também podem criar riscos se um invasor puder atualizar a descrição, a imagem ou a lista de colaboradores do contrato sem as permissões adequadas.

ERC-8049 e os desenvolvimentos mais recentes em metadados on-chain

O rascunho da proposta ERC-8049 define um padrão para armazenar metadados no nível do contrato on-chain.

Ele amplia o conceito de metadados no nível do contrato ao fornecer uma interface de armazenamento on-chain baseada em chaves de string e valores em bytes.

Esse tipo de proposta mostra que os padrões de metadados continuam evoluindo.

Os padrões mais antigos de metadados de tokens costumam se concentrar em links tokenURI.

Os desenvolvimentos mais recentes exploram identidade de contratos, compatibilidade entre blockchains, armazenamento previsível, eventos de atualização de metadados e descoberta aprimorada para carteiras e exploradores.

Como o ERC-8049 está marcado como rascunho, os desenvolvedores não devem tratá-lo como um requisito universal definitivo.

Ainda assim, podem estudá-lo para entender possíveis direções para o design de metadados.

A tendência mais ampla é clara.

Aplicativos cripto precisam de formas mais confiáveis de descobrir o que é um contrato, o que ele representa, quem pode atualizar seus dados de exibição e onde essas informações estão armazenadas.

Os metadados on-chain estão se tornando mais importantes à medida que as blockchains passam a oferecer suporte a aplicativos mais complexos do que simples transferências.

Eventos de atualização de metadados

Os metadados podem mudar em alguns projetos.

Um item de jogo pode subir de nível.

O status de um token de associação pode mudar.

Um NFT dinâmico pode mudar de aparência com base no tempo, em conquistas ou em dados de oráculos.

A extensão de atualização de metadados ERC-4906 adiciona os eventos MetadataUpdate e BatchMetadataUpdate para tokens ERC-721.

Esses eventos ajudam os aplicativos a saber quando devem atualizar os metadados dos tokens.

Isso é útil porque indexadores e carteiras podem armazenar metadados em cache para reduzir consultas repetidas.

Se os metadados mudarem sem que um aviso seja emitido, os usuários poderão ver informações desatualizadas.

Os eventos de atualização criam um caminho mais organizado para metadados dinâmicos.

Eles também tornam importante controlar as permissões, pois atualizações não autorizadas podem prejudicar a confiança.

NFTs com vários metadados

Alguns NFTs precisam de mais de um URI de metadados.

Um token pode ter diferentes formatos de exibição para diferentes telas.

Uma obra de arte colaborativa pode incluir várias versões de artistas.

Um item de jogo pode ter um histórico de melhorias.

Um ativo do mundo real tokenizado pode precisar de metadados atuais, arquivados e de compliance.

A extensão de vários metadados ERC-7160 propõe suporte a vários URIs de metadados por token ERC-721 e a um URI principal fixado.

Isso mostra que os metadados nem sempre são mais um único arquivo estático.

À medida que os ativos cripto se tornam mais complexos, os metadados podem precisar de histórico, versões e estados de exibição selecionáveis pelo usuário.

Designs com vários metadados podem aumentar a flexibilidade.

Também podem gerar confusão se os usuários não souberem qual versão é oficial, atual, arquivada ou selecionada pelo usuário.

Metadados estáticos

Metadados estáticos são aqueles que não mudam depois do mint ou de uma revelação final.

São comuns em arte fixa, colecionáveis, registros históricos e tokens cujo valor depende da permanência.

Metadados estáticos podem ser armazenados totalmente on-chain, selados por meio de um contrato inteligente ou fixados em armazenamento endereçado pelo conteúdo.

Os colecionadores costumam preferir metadados estáticos quando querem ter confiança de que o ativo não será alterado posteriormente.

Metadados estáticos facilitam a verificação porque os campos esperados permanecem estáveis.

Também podem reduzir o risco operacional, pois não existe uma autoridade contínua para atualizar os metadados.

A desvantagem é que os erros podem se tornar permanentes.

Se um erro de digitação, imagem incorreta, atributo errado ou link quebrado for finalizado, pode ser difícil ou impossível corrigi-lo.

Metadados estáticos funcionam melhor quando o projeto realiza uma revisão rigorosa antes do mint.

A finalização só é valiosa quando os dados finalizados estão corretos.

Metadados dinâmicos

Metadados dinâmicos mudam com o tempo.

Podem ser úteis para jogos, programas de fidelidade, arte evolutiva, colecionáveis esportivos, ativos do mundo real, credenciais de identidade e sistemas de conquistas.

Um NFT dinâmico pode mudar de aparência quando o usuário conclui uma missão.

Um ativo tokenizado pode atualizar sua avaliação, seu status, seus registros de inspeção ou suas informações de vencimento.

Um token de associação pode mudar de nível quando o usuário alcança uma nova faixa de contribuição.

Metadados dinâmicos podem tornar os ativos de blockchain mais úteis e interativos.

Também levantam questões de confiança.

Quem pode atualizar os metadados?

Quais regras controlam a atualização?

O proprietário pode verificar o histórico de atualizações?

O emissor pode alterar características importantes depois da venda?

Metadados dinâmicos devem ter permissões, eventos, trilhas de auditoria e expectativas dos usuários claramente definidos.

Metadados totalmente on-chain

Metadados totalmente on-chain significam que os principais campos descritivos são armazenados ou gerados diretamente pelo contrato de blockchain.

Isso pode ser feito por meio do armazenamento do contrato, strings codificadas diretamente, SVGs gerados, JSON codificado em Base64 ou lógica determinística de renderização.

Metadados totalmente on-chain podem tornar um ativo mais duradouro por não depender de um servidor web comum.

Também podem tornar o ativo mais transparente, pois os usuários podem inspecionar o contrato e verificar como os metadados são produzidos.

A arte generativa totalmente on-chain é um exemplo importante.

O contrato pode criar a imagem e os metadados a partir do ID do token, de valores de seed ou de características armazenadas.

Essa abordagem pode favorecer a preservação de longo prazo.

A principal desvantagem é o custo.

Cada byte armazenado on-chain consome recursos escassos da blockchain.

Armazenar imagens grandes, vídeos e metadados complexos inteiramente on-chain pode ser caro ou impraticável.

Metadados híbridos

Metadados híbridos combinam armazenamento on-chain e off-chain.

Esse é o modelo prático mais comum em muitos sistemas de NFTs e tokens.

O contrato pode armazenar on-chain a propriedade do token, o ID do token e um URI de metadados.

O URI de metadados pode apontar para IPFS, Arweave, HTTPS ou outro sistema de armazenamento.

O arquivo de mídia pode ser armazenado separadamente dos metadados JSON.

Essa abordagem reduz os custos da blockchain e ainda permite descobrir o ativo por meio de um registro de blockchain.

A solidez do design depende do método de armazenamento externo.

Uma URL comum pode deixar de funcionar se o domínio expirar ou o servidor for removido.

Um CID do IPFS endereçado pelo conteúdo pode ajudar os usuários a verificar se o conteúdo não foi alterado.

As orientações do IPFS para dados de NFT recomendam planejar como os dados de NFT serão armazenados, endereçados e mantidos ao longo do tempo.

Endereçamento por conteúdo e metadados

O endereçamento por conteúdo significa identificar um arquivo por uma referência criptográfica ao seu conteúdo, em vez de usar o endereço mutável de um servidor.

O IPFS usa identificadores de conteúdo, também chamados de CIDs, para identificar conteúdo.

Se o arquivo mudar, o CID também muda.

Isso torna o endereçamento por conteúdo útil para metadados de NFT, pois os usuários podem detectar se um arquivo foi substituído.

Um tokenURI que aponta para um CID do IPFS pode ser mais confiável do que um tokenURI que aponta apenas para uma URL comum.

No entanto, o endereçamento por conteúdo não garante automaticamente a disponibilidade.

Alguém ainda precisa fixar, hospedar ou preservar o conteúdo para que ele possa ser recuperado.

Por isso, o design do armazenamento deve considerar tanto a integridade quanto a persistência.

Integridade significa que os dados não foram alterados.

Persistência significa que os dados ainda poderão ser encontrados no futuro.

Metadados em Base64

Metadados em Base64 são uma forma comum de retornar JSON ou mídia diretamente de um contrato inteligente.

Um contrato pode retornar um tokenURI iniciado por um data URI, como data:application/json;base64.

O conteúdo codificado pode incluir nome, descrição, imagem e atributos do NFT.

A própria imagem também pode ser codificada em SVG ou outro formato de dados.

Essa abordagem é popular em NFTs totalmente on-chain porque permite que o contrato retorne tudo o que é necessário para a exibição.

Também evita a dependência de um servidor externo de metadados.

A desvantagem é que dados em Base64 podem aumentar o tamanho do resultado do contrato e dificultar a leitura direta por pessoas.

O uso de gas também pode ser mais caro se valores grandes forem armazenados ou gerados de forma ineficiente.

Os desenvolvedores devem testar os metadados em Base64 em diferentes carteiras e exploradores.

Diferentes interfaces podem ter níveis distintos de suporte a imagens codificadas, animações ou campos incomuns.

Metadados on-chain para ativos do mundo real tokenizados

Ativos do mundo real tokenizados exigem um design cuidadoso dos metadados, pois o token pode representar algo que existe fora da blockchain.

Os metadados podem descrever uma fatura, participação em fundo, título de dívida, registro imobiliário, direito sobre commodity, crédito de carbono, colecionável ou contrato jurídico.

Parte dessas informações pode ser pública e adequada ao armazenamento on-chain.

Outra parte pode ser privada, regulamentada ou pessoalmente sensível.

Armazenar dados jurídicos ou pessoais sensíveis diretamente on-chain pode ser perigoso, pois registros públicos em blockchain podem ser difíceis de remover.

Um design melhor pode armazenar hashes, atestações, referências a documentos ou provas com permissão on-chain, mantendo documentos privados em armazenamento controlado.

Metadados on-chain podem favorecer a transparência, mas não devem expor informações confidenciais sem necessidade.

Metadados de ativos do mundo real também precisam de controle de versões.

Termos, status de garantias, datas de vencimento, auditorias e documentos jurídicos podem mudar com o tempo.

Os projetos devem explicar claramente quais metadados são oficiais e como as atualizações são gerenciadas.

Metadados on-chain para jogos

Jogos em blockchain usam metadados para descrever itens, personagens, skins, terrenos, armas, conquistas e consumíveis.

Metadados on-chain podem ajudar os jogadores a verificar escassez, características, propriedade e histórico de itens.

Metadados dinâmicos podem permitir que um item evolua conforme o jogador o utiliza.

Por exemplo, um NFT de espada pode ganhar pontos de experiência, um NFT de personagem pode subir de nível ou um NFT de terreno pode mudar depois de uma construção.

Metadados de jogos totalmente on-chain podem aumentar a composabilidade, pois outros contratos podem ler diretamente o estado do item.

No entanto, jogos costumam exigir imagens grandes, mudanças frequentes de estado e lógica complexa.

Armazenar tudo isso diretamente on-chain pode ser caro demais.

Muitos jogos usam um modelo híbrido, em que a propriedade e os atributos essenciais ficam on-chain, enquanto os ativos mais pesados ficam off-chain.

O melhor design de metadados para jogos separa características permanentes dos dados de jogo que mudam rapidamente.

Isso ajuda a equilibrar custo, velocidade e confiança dos jogadores.

Metadados on-chain para identidade digital

Sistemas de identidade digital podem usar metadados para descrever credenciais, atestações, distintivos, associações ou registros de reputação.

Metadados on-chain podem facilitar a verificação pública de uma credencial.

Também podem criar riscos à privacidade se informações pessoais forem expostas para sempre.

Uma blockchain pública geralmente não é um bom lugar para armazenar números de passaporte, endereços residenciais, dados de saúde ou registros jurídicos privados em formato bruto.

Em vez disso, sistemas de identidade costumam usar hashes, divulgação seletiva, provas de conhecimento zero, identificadores descentralizados ou registros criptografados off-chain.

Os metadados podem descrever o tipo de credencial sem revelar informações sensíveis.

Por exemplo, um registro on-chain pode provar que uma credencial existe e foi emitida por uma autoridade conhecida.

Os detalhes privados podem permanecer off-chain e ser apresentados apenas quando necessário.

Metadados on-chain para identidade devem seguir o princípio da minimização de dados.

A blockchain deve armazenar apenas o que realmente precisa de verificação pública.

Metadados on-chain e procedência

Procedência é o histórico de criação, propriedade, transferência e modificação.

Metadados on-chain podem ajudar a estabelecer a procedência ao tornar os detalhes e as atualizações do ativo visíveis na blockchain.

Para NFTs, a procedência pode incluir horário de mint, endereço do criador, ID do token, hash dos metadados, evento de revelação, evento de atualização e histórico de transferências.

Para ativos tokenizados, a procedência pode incluir emissão, auditorias, mudanças de custódia, resgates e referências a documentos.

Uma procedência robusta ajuda os usuários a verificar se um ativo é o que afirma ser.

Uma procedência fraca pode dificultar a detecção de cópias, falsificações e ativos enganosos.

Os metadados, por si só, não comprovam autenticidade.

Um golpista pode criar metadados que afirmam representar uma obra famosa ou um ativo real.

Os usuários ainda precisam verificar o emissor, o endereço do contrato, o histórico de mint e os direitos externos.

Metadados on-chain são evidências, não uma verdade automática.

Metadados on-chain e imutabilidade

Imutabilidade significa que é difícil alterar dados depois que são registrados on-chain.

Metadados imutáveis podem aumentar a confiança dos colecionadores, pois campos importantes não podem ser alterados posteriormente.

Também podem proteger os usuários contra mudanças nos metadados semelhantes a rug pulls, nas quais o ativo exibido é substituído após a venda.

No entanto, a imutabilidade também pode perpetuar erros.

Se os metadados incluírem um link de imagem quebrado, uma característica incorreta, um nome escrito errado ou uma licença equivocada, talvez seja impossível corrigir o problema.

Metadados mutáveis podem corrigir erros, mas exigem confiança na autoridade que os atualiza.

Isso cria uma escolha de design.

Alguns projetos devem congelar os metadados depois da revelação.

Outros devem permitir atualizações sob governança transparente.

Alguns projetos devem separar características essenciais imutáveis de campos de exibição mutáveis.

Metadados on-chain e custos de gas

O custo de gas é uma das maiores limitações dos metadados on-chain.

Blockchains públicas cobram taxas porque armazenamento, processamento e execução de transações são recursos limitados.

Armazenar uma string curta pode ser acessível.

Armazenar uma imagem grande, uma animação longa ou um arquivo de metadados complexo pode ser caro.

Os desenvolvedores costumam reduzir custos armazenando hashes, valores compactos de características, lógica de geração de SVG ou links endereçados pelo conteúdo, em vez de arquivos grandes.

Redes Layer 2 podem reduzir os custos de algumas operações de metadados, mas não tornam o armazenamento gratuito.

O custo também afeta os usuários.

Se as atualizações de metadados exigirem transações, os usuários ou operadores do projeto poderão ter de pagar taxas sempre que os dados mudarem.

Um design de metadados que parece adequado nos testes pode se tornar caro em grande escala.

Planejar um armazenamento eficiente faz parte de um bom design de contrato inteligente.

Metadados on-chain e indexadores

Indexadores são serviços que leem dados da blockchain e os organizam para aplicativos.

Carteiras, exploradores, jogos e painéis frequentemente dependem de indexadores para exibir metadados rapidamente.

Mesmo quando os metadados estão on-chain, os aplicativos ainda precisam saber como encontrá-los, decodificá-los, armazená-los em cache e atualizá-los.

Funções e eventos padronizados ajudam os indexadores a funcionar de forma confiável.

Por exemplo, tokenURI ajuda os indexadores a encontrar metadados no nível do token.

contractURI pode ajudar os indexadores a encontrar metadados no nível do contrato.

Eventos MetadataUpdate podem ajudar os indexadores a saber quando os dados em cache devem ser atualizados.

Sem padrões, cada projeto pode exigir uma lógica de indexação própria.

Isso dificulta a exibição dos ativos e aumenta o risco de interpretações equivocadas.

Padrões de metadados melhoram a interoperabilidade em todo o ecossistema cripto.

Metadados on-chain e exibição em carteiras

Carteiras usam metadados para mostrar aos usuários o que eles possuem.

Uma carteira pode exibir nome do token, nome da coleção, imagem, símbolo, descrição, características, saldo, endereço do contrato e rede.

Se os metadados estiverem ausentes ou quebrados, a carteira poderá exibir uma imagem em branco, um token desconhecido ou um espaço reservado genérico.

Se os metadados forem enganosos, o usuário poderá aprovar ou negociar o ativo errado.

Isso torna os metadados uma questão de segurança do usuário, e não apenas de design.

As carteiras devem exibir endereços de contratos e sinais de alerta quando os metadados forem suspeitos.

Os desenvolvedores devem evitar metadados que dependam de servidores frágeis ou formatos de arquivo pouco claros.

Os usuários não devem confiar em um ativo apenas porque a imagem exibida na carteira parece familiar.

Golpistas podem copiar nomes, imagens e descrições.

O endereço do contrato e o histórico do emissor costumam ser mais importantes do que os metadados exibidos.

Metadados on-chain e segurança

Metadados on-chain podem aumentar a segurança ao reduzir a dependência de servidores externos mutáveis.

Também podem criar novos problemas de segurança se a lógica de atualização for fraca.

Uma chave do proprietário do projeto que pode atualizar metadados se torna um alvo importante.

Se essa chave for comprometida, um invasor poderá alterar imagens, descrições, links ou dados de exibição no nível do contrato.

Links nos metadados também podem direcionar usuários a páginas de phishing, arquivos maliciosos ou alegações falsas.

Os contratos inteligentes devem restringir as funções de atualização de metadados com controles de acesso claros.

Os projetos devem informar se os metadados podem ser alterados.

Também devem explicar quem pode alterá-los e em quais condições.

Os usuários devem ter cautela quando os metadados incluírem links ou instruções externas.

Metadados legíveis podem influenciar o comportamento dos usuários e, por isso, devem ser tratados como parte da superfície de segurança.

Metadados on-chain e direitos autorais

Metadados on-chain não concedem automaticamente direitos autorais, direitos de marca registrada ou direitos comerciais.

Um NFT pode incluir um campo de imagem, mas isso não comprova que quem fez o mint seja o proprietário da obra.

Um token pode descrever um ativo do mundo real, mas isso não comprova automaticamente a titularidade legal do ativo.

Os metadados podem informar termos de licença, nomes de criadores ou links externos.

Essas declarações ainda precisam de respaldo jurídico e factual.

O comprador deve verificar a licença do projeto, o emissor, o endereço do contrato, o histórico de mint e a documentação oficial.

Para ativos de alto valor, contratos jurídicos podem ser mais importantes do que o texto dos metadados.

Metadados on-chain são excelentes para registrar declarações.

Isso não equivale a comprovar que todas as declarações são juridicamente válidas.

Propriedade digital e direitos de propriedade intelectual não devem ser confundidos.

Metadados on-chain e privacidade

Qualquer pessoa pode ver metadados públicos on-chain.

Isso é útil para a transparência, mas pode colocar informações privadas em risco.

Depois que dados sensíveis são gravados em uma blockchain pública, pode ser muito difícil removê-los.

Os metadados não devem expor dados de identidade pessoal, a menos que haja um motivo importante e consentimento claro.

Até metadados aparentemente inofensivos podem se tornar sensíveis quando combinados com o histórico da carteira.

Por exemplo, um distintivo de associação pode revelar onde uma pessoa trabalha, de qual comunidade participa ou a qual evento compareceu.

Sistemas de identidade e credenciais devem evitar o armazenamento direto de dados pessoais brutos on-chain.

Devem considerar hashes, compromissos criptográficos, armazenamento criptografado, acesso com permissão ou provas de conhecimento zero.

A permanência dos metadados é poderosa.

Esse poder deve ser usado com cuidado.

Metadados on-chain e ativos gerados por IA

Arte, música, personagens e ativos de jogos gerados por IA tornam o design de metadados ainda mais importante.

Os metadados podem descrever o histórico dos prompts, a versão do modelo, a data de geração, a carteira do criador, os termos da licença e notas de procedência.

Alguns projetos podem armazenar essas informações on-chain para aumentar a transparência.

Outros podem armazenar apenas um hash ou uma referência, pois o registro completo da geração é extenso.

Metadados on-chain podem ajudar a comprovar quando um ativo gerado foi criado por mint e qual contrato o emitiu.

Não podem comprovar automaticamente que o conteúdo é original, não infringe direitos ou foi criado por uma pessoa.

À medida que ativos cripto gerados por IA se tornam mais comuns, os metadados devem distinguir claramente entre declarações do criador, detalhes gerados por máquinas e fatos verificados.

Metadados bem elaborados podem reduzir a confusão.

Metadados ruins podem fazer uma procedência falsa parecer oficial.

Os usuários devem analisar os metadados com senso crítico, especialmente em ativos de alto valor.

Benefícios dos metadados on-chain

O primeiro benefício dos metadados on-chain é a durabilidade.

Dados armazenados diretamente on-chain dependem menos de servidores externos.

O segundo benefício é a verificabilidade.

Os usuários podem inspecionar contratos inteligentes, registros de transação e resultados de metadados diretamente.

O terceiro benefício é a resistência à censura.

É mais fácil remover um site comum do que dados incorporados em uma blockchain descentralizada.

O quarto benefício é a procedência.

As mudanças nos metadados e os eventos de atualização podem criar um histórico visível.

O quinto benefício é a composabilidade.

Outros contratos inteligentes podem ler atributos on-chain e utilizá-los em jogos, DeFi, sistemas de identidade e ferramentas de DAO.

O sexto benefício é a menor dependência de plataformas.

Vários aplicativos podem exibir os ativos se seguirem padrões comuns.

Riscos e limitações dos metadados on-chain

A primeira limitação é o custo.

O armazenamento em blockchain pode ser caro em comparação com o armazenamento externo.

A segunda limitação é o tamanho.

Imagens grandes, vídeos e arquivos complexos costumam ser impraticáveis para armazenamento totalmente on-chain.

A terceira limitação é a permanência dos erros.

Metadados incorretos podem ser difíceis de corrigir depois de finalizados.

A quarta limitação é a privacidade.

Metadados públicos podem revelar informações sensíveis.

A quinta limitação é a compatibilidade de exibição.

Algumas carteiras e aplicativos podem não ser compatíveis com todos os formatos de metadados.

A sexta limitação é o risco de governança.

Metadados mutáveis exigem confiança em quem controla as atualizações.

A sétima limitação são as declarações falsas.

Os metadados podem afirmar autenticidade, raridade ou direitos que não foram realmente comprovados.

Erros comuns com metadados on-chain

Um erro comum é presumir que todo NFT armazena sua imagem on-chain.

Muitos NFTs armazenam a propriedade on-chain, mas mantêm a mídia em outro lugar.

Outro erro é presumir que um link do IPFS estará sempre disponível.

O conteúdo do IPFS ainda exige planejamento de persistência.

Um terceiro erro é presumir que metadados imutáveis são sempre melhores.

Metadados imutáveis podem perpetuar erros.

Um quarto erro é conceder a uma carteira administrativa poder ilimitado de atualização de metadados sem informar os usuários.

Um quinto erro é armazenar informações pessoais sensíveis em uma blockchain pública.

Um sexto erro é usar campos fora do padrão que carteiras e indexadores não conseguem ler.

Um sétimo erro é tratar metadados como prova de direitos legais.

Um oitavo erro é não emitir eventos de atualização para metadados dinâmicos.

Um nono erro é depender de um servidor centralizado para ativos divulgados como permanentes.

Um décimo erro é não testar a exibição dos metadados em carteiras e exploradores comuns.

Boas práticas para desenvolvedores

Escolha o modelo de armazenamento de metadados antes da implementação.

Use padrões de token estabelecidos, como ERC-721, ERC-1155, ERC-4906, ERC-7160 ou padrões de metadados no nível do contrato, quando forem adequados ao caso de uso.

Armazene características imutáveis essenciais on-chain quando a confiança de longo prazo for importante.

Use armazenamento endereçado pelo conteúdo para mídias grandes quando o armazenamento totalmente on-chain for caro demais.

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

Documente se os metadados são mutáveis, imutáveis, sujeitos a revelação atrasada ou totalmente gerados on-chain.

Proteja as funções de atualização com controles de acesso robustos.

Evite armazenar dados pessoais sensíveis diretamente em uma blockchain pública.

Teste tokenURI, contractURI, data URIs, campos Base64 e links de mídia em diferentes aplicativos.

Mantenha os esquemas de metadados simples, consistentes e fáceis de interpretar pelos indexadores.

Boas práticas para usuários

Verifique se os metadados são totalmente on-chain, endereçados pelo conteúdo ou hospedados em uma URL comum.

Verifique o endereço do contrato antes de confiar na imagem ou no nome exibido.

Procure documentação do projeto que explique se os metadados podem ser alterados.

Verifique se o proprietário do contrato pode alterar os metadados depois do mint.

Tenha cautela quando os metadados apontarem para links externos.

Entenda que a imagem de NFT exibida pode não ser a mesma coisa que o registro de propriedade do token.

Não presuma que metadados on-chain comprovam direitos autorais ou direitos legais.

Quando possível, use exploradores de blockchain para inspecionar tokenURI ou contractURI.

Para ativos de alto valor, verifique a persistência da mídia e o histórico do emissor.

Trate os metadados como parte da due diligence, não como a verdade completa.

Quando os metadados on-chain são úteis

Metadados on-chain são úteis quando a permanência é importante.

São úteis quando um NFT ou token precisa continuar compreensível mesmo que um site desapareça.

São úteis para arte generativa que pode ser produzida diretamente pela lógica do contrato.

São úteis para jogos em que contratos inteligentes precisam ler atributos de itens.

São úteis para ativos de DAOs que exigem registros públicos para as comunidades.

São úteis para ativos tokenizados que precisam de referências transparentes de estado ou auditoria.

São úteis para sistemas de identidade quando apenas dados de verificação não sensíveis são armazenados.

São úteis quando os metadados precisam ser verificados de forma independente por vários aplicativos.

São menos úteis para arquivos privados grandes, mídias pesadas ou informações que talvez precisem ser apagadas.

São menos úteis quando o custo de armazenamento é mais importante do que a permanência.

Metadados on-chain em uma frase

Metadados on-chain são dados descritivos armazenados em blockchain ou gerados por contratos inteligentes que ajudam usuários, carteiras, exploradores e aplicativos a entender o que um ativo ou contrato cripto representa sem depender inteiramente de servidores externos.

Perguntas frequentes

O que significam metadados on-chain?

Metadados on-chain são informações descritivas sobre um ativo ou contrato, armazenadas diretamente em uma blockchain ou retornadas diretamente por um contrato inteligente.

Todos os metadados de NFT ficam on-chain?

Não. Muitos NFTs armazenam a propriedade on-chain, enquanto os metadados e a mídia são mantidos por meio de URLs externas, IPFS, Arweave ou outros sistemas de armazenamento.

Qual é a diferença entre metadados e mídia?

Os metadados descrevem o ativo, enquanto a mídia é a imagem, animação, áudio, vídeo ou arquivo propriamente dito associado ao ativo.

O que é tokenURI?

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

O que é contractURI?

contractURI é uma função de metadados no nível do contrato usada para retornar informações da coleção ou do contrato, como nome, descrição e imagem.

Por que os metadados on-chain são caros?

São caros porque o armazenamento e o processamento em blockchain pública são recursos escassos que exigem taxas de transação.

Os metadados on-chain podem ser alterados?

Isso depende do design do contrato, pois alguns metadados são imutáveis, enquanto outros podem ser atualizados por contas autorizadas ou de acordo com regras do contrato inteligente.

Metadados no IPFS são iguais a metadados on-chain?

Não. Os metadados no IPFS geralmente são off-chain, mas endereçados pelo conteúdo, enquanto os metadados on-chain são armazenados ou gerados diretamente pelo contrato de blockchain.

Metadados on-chain comprovam a titularidade dos direitos de uma obra?

Não. Metadados on-chain podem registrar declarações e referências, mas os direitos legais dependem de direitos autorais, licenças, contratos e autoridade do emissor.

Por que as carteiras precisam de metadados?

As carteiras precisam de metadados para exibir nomes, imagens, descrições, características, informações de coleção e outros detalhes mais compreensíveis para os usuários.

O que são metadados dinâmicos?

Metadados dinâmicos mudam com o tempo em função de atualizações, estado do jogo, conquistas, dados de oráculos ou regras do contrato.

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

Os usuários devem verificar o endereço do contrato, o método de armazenamento dos metadados e da mídia, as permissões de atualização, o histórico do emissor e os direitos legais associados ao ativo.

Conclusão

Metadados on-chain são um conceito fundamental para entender como os ativos cripto se tornam compreensíveis, úteis e verificáveis.

Uma blockchain pode comprovar que uma carteira possui um token, mas os metadados explicam o que esse token representa.

Em NFTs, os metadados podem definir o nome, a imagem, a descrição e as características que os usuários veem em carteiras e aplicativos.

Em contratos inteligentes, os metadados podem definir a identidade do contrato, o perfil da coleção, as imagens de exibição e as informações do projeto.

Em ativos tokenizados, os metadados podem conectar registros de blockchain a documentos, direitos, status ou referências de auditoria do mundo real.

Armazenar metadados on-chain pode aumentar a permanência, a transparência e a confiança minimizada.

Isso pode reduzir a dependência de sites que podem desaparecer ou mudar.

Também pode tornar os ativos mais composáveis, pois outros contratos e aplicativos podem ler os metadados diretamente.

No entanto, metadados on-chain nem sempre são a melhor opção para todos os campos ou arquivos.

Armazenar mídia grande diretamente on-chain pode ser caro.

Em geral, informações privadas não devem ser armazenadas em ledgers públicos.

Metadados mutáveis podem ser úteis, mas exigem controles de atualização confiáveis.

Metadados imutáveis podem ser duradouros, mas também podem preservar erros para sempre.

Os melhores sistemas de metadados deixam claro o que é armazenado on-chain, o que fica em outro lugar e quem pode alterar essas informações.

Eles usam padrões para que carteiras, exploradores, jogos e indexadores entendam corretamente o ativo.

Usam armazenamento endereçado pelo conteúdo quando o armazenamento totalmente on-chain não é prático.

Protegem as permissões de atualização e emitem eventos quando os metadados mudam.

Evitam confundir os usuários ao alegar permanência quando arquivos essenciais ainda dependem de servidores frágeis.

Para os usuários, metadados on-chain devem fazer parte de toda due diligence de NFTs e tokens.

Uma imagem bonita na carteira não basta.

A pergunta principal é onde os metadados estão armazenados, quem os controla, se podem mudar e se o emissor possui os direitos que declara ter.

No universo cripto, metadados não são apenas decoração.

São a ponte entre a propriedade registrada em blockchain e o significado compreensível para as pessoas.