URI base

O que é um URI base em cripto?

Um URI base é o caminho inicial compartilhado que um contrato inteligente usa para montar o link completo dos metadados dos tokens de uma coleção cripto.

Em sistemas de metadados de NFTs e tokens, um URI informa às carteiras, aos exploradores de blockchain e aos aplicativos onde encontrar os metadados em JSON que descrevem um token.

O padrão oficial ERC-721 define tokenURI como uma função que retorna um Uniform Resource Identifier distinto para determinado ativo.

Um URI base costuma ser combinado com um ID de token para gerar esse tokenURI completo.

Por exemplo, um URI base pode ser ipfs://exampleCID/ e o ID de token 25 pode apontar para ipfs://exampleCID/25.

Em outra configuração, o caminho completo dos metadados pode incluir uma extensão de arquivo, como ipfs://exampleCID/25.json.

O resultado exato depende de como o contrato inteligente monta o tokenURI.

A documentação ERC-721 da OpenZeppelin explica que a função _baseURI é usada para calcular ERC721.tokenURI e que o URI resultante pode ser a concatenação de baseURI e tokenId.

Isso torna o URI base uma ferramenta prática para economizar gas, organizar metadados e facilitar o gerenciamento de grandes coleções de NFTs.

Para usuários de cripto, o URI base é importante porque afeta de onde são carregadas as imagens, características, descrições e outros metadados dos NFTs.

Por que o URI base é importante

O URI base é importante porque a propriedade do token e seus metadados nem sempre ficam armazenados no mesmo local.

Uma blockchain pode armazenar o proprietário do token, o ID do token, o histórico de transferências, as aprovações e a lógica do contrato.

A imagem, o nome, a descrição, os atributos, a animação e as mídias externas costumam ser armazenados fora da blockchain.

O URI base conecta o token on-chain ao local dos metadados off-chain ou descentralizado.

Quando o URI base está correto, carteiras e aplicativos conseguem exibir o token adequadamente.

Se o URI base estiver incorreto, quebrado, centralizado ou for alterado de forma maliciosa, o token poderá exibir imagens ausentes, características erradas ou informações enganosas.

Isso é especialmente importante para NFTs, pois boa parte do valor percebido pelo usuário pode depender dos metadados.

Um item colecionável com características raras pode parecer valioso apenas se os metadados estiverem disponíveis e forem confiáveis.

Um item de jogo pode precisar de metadados para exibir seu nível, classe, aparência ou utilidade.

Um NFT de associação pode precisar de metadados para mostrar seu nível ou direitos de acesso.

Assim, o URI base afeta a experiência do usuário, a integridade dos metadados, a confiança na coleção e a legibilidade do ativo no longo prazo.

Como funciona o URI base

Em geral, o URI base funciona armazenando ou retornando um prefixo comum dentro do contrato do token.

Em seguida, o contrato acrescenta um valor específico do token, geralmente seu ID, para criar o URI completo dos metadados.

Por exemplo, se o URI base for ipfs://bafyExampleCollection/ e o ID do token for 100, o tokenURI final poderá ser ipfs://bafyExampleCollection/100.

Se o contrato acrescentar um sufixo JSON, o tokenURI final poderá ser ipfs://bafyExampleCollection/100.json.

Alguns contratos armazenam o URI base como uma variável de estado que um endereço autorizado pode atualizar.

Outros definem o URI base permanentemente no código durante a implantação.

Há contratos que retornam URIs base diferentes conforme o estado de revelação, o tipo de token, o chain ID ou uma lógica personalizada.

Alguns contratos não usam URI base e armazenam, em vez disso, um URI completo e exclusivo para cada token.

O URI base não é um requisito universal de todos os contratos de NFT.

É um padrão de implementação comum para gerar caminhos de metadados de tokens com eficiência.

URI base e tokenURI

O tokenURI é o URI completo retornado para um token específico.

O URI base é o prefixo reutilizável que pode ajudar a criar diversos tokenURIs.

Nos contratos ERC-721, tokenURI faz parte da extensão opcional de metadados.

O padrão ERC-721 diz que tokenURI pode apontar para um arquivo JSON que siga o esquema ERC-721 Metadata JSON Schema.

Esse arquivo JSON costuma incluir campos como nome, descrição e imagem.

O URI base não é o mesmo que os próprios metadados JSON.

É o caminho que ajuda uma carteira ou um aplicativo a encontrar esses metadados JSON.

Um contrato simples pode retornar tokenURI juntando o URI base ao ID do token.

Um contrato mais complexo pode retornar um URI totalmente personalizado para cada token.

Um contrato de NFT dinâmico pode gerar tokenURI a partir do estado on-chain, sem usar um URI base fixo.

Os usuários devem se concentrar no que tokenURI retorna, pois esse é o local efetivo dos metadados utilizado pelos aplicativos.

URI base em NFTs ERC-721

ERC-721 é o padrão de token mais associado a NFTs únicos e IDs de token exclusivos.

Cada token ERC-721 tem um ID exclusivo dentro de um contrato específico.

O par formado pelo endereço do contrato e pelo ID do token identifica de forma exclusiva o NFT naquela blockchain.

A extensão de metadados permite que os aplicativos solicitem tokenURI ao contrato.

O URI base ajuda o contrato a evitar o armazenamento de um URI completo para cada token.

Isso é útil porque armazenar strings longas on-chain pode ser caro.

Em vez de armazenar 10.000 links completos de metadados, uma coleção pode guardar um único URI base e usar os IDs dos tokens para montar links individuais.

Esse modelo é comum em coleções de fotos de perfil, itens de jogos, passes de associação, séries de arte e conjuntos de itens colecionáveis.

Por exemplo, os tokens 1, 2 e 3 podem compartilhar o mesmo URI base, embora cada um aponte para um arquivo de metadados diferente.

O URI base compartilhado mantém a estrutura simples e previsível.

URI base em tokens ERC-1155

ERC-1155 é um padrão de múltiplos tokens que pode oferecer suporte a tokens fungíveis, semifungíveis e NFTs em um único contrato.

O ERC-1155 lida com metadados de forma diferente de muitas implementações ERC-721.

O padrão ERC-1155 oficial diz que o valor de URI permite que os clientes substituam o ID quando a string {id} aparece em um URI.

Os clientes devem substituir {id} pelo ID real do token em hexadecimal minúsculo, preenchido com zeros até 64 caracteres quando necessário.

Isso permite que muitos IDs de token usem um único padrão de URI compartilhado.

Por exemplo, um URI pode ter o formato https://example.com/metadata/{id}.json.

Uma carteira ou um aplicativo substitui {id} pelo ID do token formatado para encontrar o arquivo JSON correto.

O objetivo é semelhante ao do URI base: criar muitos links para metadados de tokens a partir de um único padrão compartilhado.

No entanto, o ERC-1155 usa uma regra específica de substituição, em vez do padrão simples de URI base mais ID do token visto em muitos contratos ERC-721.

Os desenvolvedores não devem presumir que os caminhos de metadados ERC-721 e ERC-1155 sejam montados da mesma forma.

URI base e metadados de NFT

Os metadados de NFT são informações estruturadas que mostram aos usuários o que um token representa.

Os metadados podem incluir nome, descrição, imagem, URL de animação, atributos, plano de fundo, características de raridade, níveis, referências a conteúdos desbloqueáveis, links externos e outros campos.

O esquema de metadados ERC-721 inclui campos básicos como nome, descrição e imagem.

O esquema de metadados ERC-1155 também inclui campos descritivos comuns e oferece suporte a dados de exibição específicos de cada token.

Em geral, o URI base aponta para um diretório ou endpoint onde os arquivos de metadados podem ser encontrados.

Se os metadados estiverem armazenados em arquivos JSON, cada ID de token costuma corresponder a um arquivo JSON.

Se os metadados forem dinâmicos, o URI base poderá apontar para um endpoint de API que retorna JSON diferente ao longo do tempo.

Se os metadados forem endereçados por conteúdo, o URI base poderá apontar para um identificador de armazenamento descentralizado.

A qualidade do URI base determina se os aplicativos conseguem encontrar e exibir os metadados de forma consistente.

Um token com metadados ausentes ainda pode existir on-chain, mas pode ser muito mais difícil para os usuários entendê-lo ou atribuir valor a ele.

URI base e IPFS

IPFS é um sistema comum de armazenamento descentralizado usado para metadados e mídias de NFT.

O guia de dados de NFT do IPFS oficial recomenda usar URIs IPFS para conectar contratos inteligentes a dados externos de NFT armazenados no IPFS.

Um URI IPFS geralmente começa com ipfs:// e inclui um identificador de conteúdo, também chamado de CID.

Um URI base com IPFS pode ter o formato ipfs://bafyExampleCID/.

Em seguida, cada arquivo de metadados de token pode ser armazenado nesse diretório IPFS.

Esse modelo pode tornar os metadados de NFT mais resistentes a adulterações do que links comuns da web, pois um CID identifica o conteúdo pelos dados, e não apenas pela localização em um servidor.

Se o conteúdo mudar, o CID também muda.

Isso ajuda os usuários a detectar se os metadados foram alterados.

No entanto, o conteúdo IPFS ainda precisa estar disponível em pelo menos um nó ou provedor de pinning para que os usuários possam acessá-lo facilmente.

Usar um URI base IPFS melhora a integridade, mas não elimina a necessidade de planejar o armazenamento de longo prazo.

URI base e URLs HTTP

Um URI base também pode usar uma URL HTTPS comum.

Por exemplo, uma coleção pode usar https://example.com/metadata/ como URI base.

O tokenURI do token 100 poderá então ser https://example.com/metadata/100.json.

Metadados HTTPS podem ser simples e flexíveis, pois o projeto consegue atualizar arquivos em um servidor web.

Essa flexibilidade pode ser útil para jogos, NFTs dinâmicos, associações ou arte em evolução.

Ela também cria riscos de confiança, pois o proprietário do servidor pode alterar, excluir, redirecionar ou bloquear os metadados.

Se o domínio expirar ou o provedor de hospedagem ficar offline, o NFT poderá deixar de ser exibido corretamente.

Se a conta de administrador do projeto for comprometida, o URI base ou endpoint de metadados poderá fornecer conteúdo malicioso ou enganoso.

Metadados HTTP centralizados são fáceis de usar, mas podem reduzir a permanência no longo prazo.

Os usuários devem verificar se um projeto usa armazenamento endereçado por conteúdo, servidores web centralizados ou uma abordagem híbrida.

URI base e armazenamento no estilo Arweave

Alguns projetos de NFT usam sistemas de armazenamento permanente para metadados e mídias.

Nesses sistemas, os metadados podem ser referenciados por um ID de transação ou caminho de conteúdo permanente.

Um URI base pode apontar para um gateway de armazenamento permanente ou para um caminho de manifesto que organiza vários arquivos de metadados de tokens.

Essa abordagem pode reduzir o risco de desaparecimento de um servidor web comum.

Ela também pode reduzir a necessidade de pagamentos contínuos de pinning quando o sistema de armazenamento é projetado para persistência de longo prazo.

Mesmo assim, os usuários devem entender o formato exato do URI e o comportamento do gateway.

Uma URL de gateway nem sempre é igual ao identificador permanente do conteúdo subjacente.

Se o contrato armazenar apenas uma URL no formato de gateway, a exibição poderá depender da disponibilidade desse gateway.

Um projeto mais robusto torna o identificador permanente claro e verificável.

O design do URI base deve facilitar a auditoria da localização dos dados no longo prazo.

URI base e metadados on-chain

Alguns tokens não dependem de um URI base externo porque seus metadados são armazenados ou gerados inteiramente on-chain.

Metadados on-chain podem ser retornados como um data URI que inclui JSON codificado diretamente pelo contrato inteligente.

Nesse modelo, tokenURI pode retornar uma string que começa com data:application/json, em vez de ipfs:// ou https://.

Isso pode tornar os metadados mais autossuficientes, pois o próprio contrato do token os gera.

Metadados on-chain podem ser úteis para arte generativa, jogos totalmente on-chain, sistemas de identidade e itens colecionáveis imutáveis.

A desvantagem é que o armazenamento e a computação on-chain podem ser caros.

Imagens grandes, animações e metadados complexos podem ser difíceis de armazenar diretamente on-chain.

Por isso, muitos projetos usam um URI base para metadados externos e reservam metadados totalmente on-chain para casos de uso específicos.

Não existe um único modelo ideal para todos os projetos.

O melhor design de metadados depende do custo, da permanência, da flexibilidade, das expectativas dos usuários e da complexidade técnica.

URI base e revelação de metadados

Muitas coleções de NFT usam URI base durante o processo de revelação.

Antes da revelação, todos os tokens podem retornar os mesmos metadados provisórios.

Esse conteúdo provisório pode exibir uma imagem misteriosa ou uma descrição genérica da coleção.

Após a revelação, o projeto atualiza o URI base para que cada token aponte para seu arquivo final de metadados.

Isso pode tornar a emissão mais justa na percepção dos usuários, pois eles não conhecem as características finais de cada token antes da revelação.

No entanto, modelos de revelação exigem confiança.

Se o projeto controla o URI base, pode conseguir alterar os metadados após a emissão.

Se o processo não for transparente, os usuários podem temer que as características raras tenham sido atribuídas de forma injusta.

Os projetos podem reduzir essa preocupação publicando hashes de proveniência, usando aleatoriedade verificável, bloqueando os metadados após a revelação ou tornando auditável a geração dos metadados.

Os usuários devem entender se o URI base de uma coleção é temporário, já foi revelado, é mutável ou está permanentemente bloqueado.

URI base mutável

Um URI base mutável pode ser alterado após a implantação do contrato.

Isso pode ser útil quando os metadados não estão prontos no lançamento, quando é preciso migrar mídias ou quando NFTs dinâmicos precisam de atualizações.

Também pode ser perigoso, pois quem controla a função de atualização pode mudar o que todos os tokens exibem.

Um projeto poderia substituir artes, alterar características, redirecionar os metadados para um novo servidor ou remover conteúdo.

Um administrador mal-intencionado poderia alterar os metadados de modo a prejudicar o valor do token ou enganar os usuários.

Uma chave de administrador comprometida poderia causar o mesmo resultado, mesmo que a equipe original fosse honesta.

Os usuários devem verificar se o URI base ainda pode ser alterado.

Também devem verificar quem pode alterá-lo.

Um URI base mutável controlado por uma única carteira de propriedade externa apresenta mais riscos do que um processo de atualização com governança cuidadosa.

A possibilidade de alteração dos metadados deve ser divulgada claramente, pois muda o modelo de confiança do token.

URI base imutável

Um URI base imutável não pode ser alterado após a implantação ou depois de uma ação final de bloqueio.

Isso pode aumentar a confiança, pois os usuários sabem que um administrador não poderá alterar o caminho dos metadados posteriormente.

URIs base imutáveis são comuns em projetos que buscam a permanência de itens colecionáveis no longo prazo.

Essa configuração é especialmente robusta quando combinada com armazenamento endereçado por conteúdo, como CIDs do IPFS.

No entanto, a imutabilidade também pode causar problemas se o URI original contiver um erro.

Se os arquivos de metadados estiverem ausentes, malformados ou em um caminho incorreto, talvez o projeto não consiga corrigir o problema.

Se um gateway de armazenamento mudar seu comportamento, o contrato talvez não consiga se adaptar.

Os desenvolvedores devem testar cuidadosamente os caminhos dos metadados antes de bloquear o URI base.

Os usuários devem entender que a imutabilidade impede alterações posteriores, mas não garante que os metadados originais estejam corretos.

Um erro permanente continua sendo permanente.

URI base e atualizações de metadados ERC-4906

ERC-4906 é uma extensão de atualização de metadados para tokens ERC-721.

O padrão ERC-4906 oficial adiciona os eventos MetadataUpdate e BatchMetadataUpdate para sinalizar alterações nos metadados.

Isso é importante porque carteiras, indexadores e aplicativos costumam armazenar metadados em cache.

Se o URI base mudar, mas os aplicativos não atualizarem o cache, os usuários poderão continuar vendo os metadados antigos.

O ERC-4906 oferece aos contratos uma maneira padronizada de informar sistemas de terceiros que os metadados dos tokens mudaram.

Isso é útil para revelações, NFTs dinâmicos, itens de jogo em evolução e correções de metadados após a emissão.

No entanto, o padrão não torna as alterações de metadados seguras por si só.

Ele apenas ajuda a sinalizar que os metadados foram alterados.

Os controles de permissão para essas alterações continuam sendo importantes.

Se um projeto usa URI base mutável ou metadados dinâmicos, a autoridade de atualização deve ser segura e estar claramente documentada.

URI base e metadados múltiplos ERC-7160

ERC-7160 é uma extensão do ERC-721 que oferece suporte a vários URIs de metadados por token.

O padrão ERC-7160 oficial descreve um sistema em que um token pode ter vários URIs de metadados e um URI principal fixado.

Isso é relevante para o URI base porque os metadados deixam de estar sempre em um único local estático.

Um token pode ter várias versões, formatos, revisões ou opções de exibição.

Por exemplo, uma obra de arte dinâmica pode ter vários estados de metadados aprovados.

Um item de jogo pode ter metadados diferentes após melhorias ou eventos.

Um NFT colaborativo pode incluir metadados de vários criadores.

O suporte a vários metadados pode aumentar a flexibilidade, mas também torna a auditoria mais complexa.

Usuários e aplicativos precisam saber qual URI é o principal e se os URIs antigos continuarão acessíveis.

O URI base continua importante porque costuma ser o caminho raiz por trás de um ou mais desses locais de metadados.

URI base e eficiência de gas

O URI base costuma ser usado para reduzir custos de gas.

Armazenar um URI completo de metadados para cada token pode ser caro, pois o armazenamento on-chain consome gas.

Um URI base compartilhado permite que o contrato armazene menos informações.

Em vez de salvar milhares de strings longas, o contrato pode armazenar um prefixo e calcular os caminhos específicos dos tokens quando necessário.

Isso é especialmente útil em coleções grandes com muitos IDs de token.

Por exemplo, uma coleção com 10.000 tokens pode usar um único URI base e 10.000 arquivos JSON nomeados conforme o ID do token.

O contrato só precisa de lógica suficiente para combinar o URI base e o ID do token.

Isso economiza armazenamento, mas reduz a flexibilidade em comparação com o armazenamento de um URI personalizado para cada token.

Os desenvolvedores precisam escolher entre economia de gas e flexibilidade dos metadados.

Mesmo um modelo de baixo custo pode ser inseguro se facilitar demais a alteração dos metadados ou dificultar sua verificação.

URI base e nomenclatura de arquivos

A nomenclatura dos arquivos é importante porque a montagem do tokenURI precisa corresponder aos arquivos de metadados existentes.

Se o contrato retornar ipfs://CID/1, o local de armazenamento deverá conter um arquivo ou objeto chamado 1.

Se o local tiver 1.json, mas o contrato retornar apenas 1, alguns aplicativos poderão não carregar os metadados.

Se o contrato retornar 0001.json, mas os arquivos forem nomeados 1.json, os metadados também poderão deixar de funcionar.

O ERC-1155 acrescenta outra camada, pois a substituição do ID do token usa formatação hexadecimal minúscula preenchida com zeros.

Os desenvolvedores devem definir a nomenclatura dos arquivos antes da implantação.

Devem testar os resultados de tokenURI com arquivos reais de metadados em redes de teste.

Devem testar vários IDs de token, incluindo IDs baixos, altos e não sequenciais.

Também devem testar como carteiras e indexadores interpretam os metadados.

Pequenos erros de nomenclatura podem causar grandes problemas de exibição em toda uma coleção.

URI base e barras finais

A barra final é a barra no fim de um URI base.

Ela pode determinar se o tokenURI final será válido.

Por exemplo, ipfs://CID/ mais o ID do token 1 resulta em ipfs://CID/1.

Sem a barra, ipfs://CID mais o ID do token 1 resulta em ipfs://CID1, o que pode estar incorreto.

O mesmo problema pode ocorrer com caminhos HTTPS.

https://example.com/metadata/ mais 1.json forma um caminho de arquivo claro.

https://example.com/metadata mais 1.json resulta em https://example.com/metadata1.json, que talvez não exista.

Os desenvolvedores devem tratar as barras e os sufixos de forma consistente no contrato.

Os usuários nem sempre conseguem perceber esse problema pela exibição em um marketplace.

Quando os metadados não carregam, uma das primeiras coisas a verificar costuma ser a string exata de tokenURI retornada pelo contrato.

URI base e cache de metadados

Muitas carteiras, marketplaces, exploradores e serviços de indexação armazenam em cache metadados de NFT.

O cache melhora a velocidade, pois os aplicativos não precisam buscar os metadados do zero a cada acesso.

No entanto, o cache pode tornar confusas as alterações do URI base.

Um projeto pode atualizar os metadados, mas alguns aplicativos ainda podem exibir a imagem ou os atributos antigos.

Essa é uma das razões pelas quais os eventos de atualização de metadados podem ser úteis.

O ERC-4906 foi criado para oferecer aos contratos uma maneira padronizada de sinalizar alterações nos metadados.

Ainda assim, nem todos os aplicativos atualizam o cache imediatamente ou oferecem suporte a todos os eventos de metadados.

Os usuários devem entender que um token pode exibir metadados diferentes em aplicativos distintos durante atrasos de atualização.

Isso nem sempre significa que a propriedade do token mudou ou que ele deixou de funcionar.

Pode simplesmente significar que o cache de metadados ainda não foi atualizado.

URI base e risco de centralização

O URI base pode criar riscos de centralização quando aponta para um servidor ou domínio controlado por uma única parte.

Se um projeto armazena metadados em um domínio web comum, o proprietário do domínio pode alterar os arquivos.

O domínio também pode expirar, ser confiscado, sofrer um ataque ou ficar offline.

Uma pesquisa sobre riscos de centralização de metadados de NFT destaca que o armazenamento centralizado pode expor dados de NFT à censura, a violações e a alterações administrativas.

Isso importa porque muitos usuários pensam que a propriedade de um NFT significa que o ativo inteiro está armazenado permanentemente on-chain.

Na realidade, o token pode apenas apontar para metadados armazenados em outro lugar.

Se esse apontador for frágil, o ativo exibido ao usuário também poderá ser frágil.

O armazenamento endereçado por conteúdo e o bloqueio claro dos metadados podem reduzir esse risco.

No entanto, todo projeto precisa de um plano de armazenamento de longo prazo.

Um NFT bonito pode virar um link quebrado se seu URI base for mal gerenciado.

URI base e endereçamento por conteúdo

O endereçamento por conteúdo significa que o identificador se baseia no próprio conteúdo.

Os CIDs do IPFS são um exemplo comum em metadados cripto.

Quando os metadados são endereçados por conteúdo, uma alteração neles gera um identificador diferente.

Isso facilita a detecção de adulterações.

Assim, um URI base que inclui um CID pode dar aos usuários mais confiança de que os arquivos referenciados não foram alterados silenciosamente.

Isso difere de uma URL comum, na qual o servidor pode fornecer conteúdo novo no mesmo endereço.

O endereçamento por conteúdo não significa que o conteúdo será armazenado automaticamente para sempre.

Alguém ainda precisa hospedar, fixar ou preservar os dados de outra forma.

Também não garante que os metadados originais fossem honestos ou de boa qualidade.

Ele apenas ajuda a verificar se o conteúdo associado àquele identificador permanece igual.

URI base e NFTs dinâmicos

NFTs dinâmicos são tokens cujos metadados podem mudar conforme eventos, tempo, ações do usuário, estado do jogo, dados de oráculos ou lógica do contrato.

NFTs dinâmicos podem usar um URI base que aponta para uma API ou serviço de metadados dinâmicos.

Também podem gerar metadados on-chain com base em estados que mudam.

Um URI base dinâmico pode tornar os NFTs mais interativos e úteis.

Por exemplo, um NFT de personagem de jogo pode subir de nível e exibir novos atributos.

Um NFT de associação pode mudar de aparência quando o usuário alcança determinado nível de status.

Um token de ativo do mundo real pode atualizar os metadados quando os documentos forem renovados.

O risco é que metadados dinâmicos exigem confiança nas regras de atualização.

Os usuários devem saber o que pode mudar, quem pode fazer a alteração e se ela é controlada por código, administradores ou sistemas off-chain.

Metadados dinâmicos só são poderosos quando suas regras são transparentes.

URI base e segurança

A segurança do URI base depende do armazenamento, do controle de acesso, da lógica do contrato e das expectativas dos usuários.

Se o URI base puder ser atualizado, a função de atualização deverá ter controles de permissão robustos.

Se uma única chave privada controlar o URI base, essa chave se tornará um alvo de alto valor.

Se uma carteira multisig controlar o URI base, a segurança dependerá da confiabilidade dos signatários e das regras de quórum.

Se a governança controlar o URI base, a segurança dependerá da distribuição dos votos e dos processos de atualização.

Se o URI base apontar para um servidor, a segurança do servidor e do domínio será importante.

Se apontar para o IPFS, o pinning e a disponibilidade do conteúdo serão importantes.

Se os metadados forem gerados on-chain, a correção do contrato será importante.

Não há um único modelo de segurança para URIs base.

A pergunta certa é sempre o que pode mudar, quem pode mudar e como os usuários podem verificar isso.

URI base e atualizações de contratos inteligentes

Contratos inteligentes atualizáveis podem mudar a forma como tokenURI é calculado.

Isso significa que a lógica do URI base pode mudar mesmo que a variável visível do URI base pareça estável.

Um contrato de NFT atualizável pode permitir que os desenvolvedores corrijam erros ou adicionem recursos.

Também pode permitir alterações no comportamento dos metadados depois que os usuários comprarem tokens.

Os usuários devem verificar se o contrato pode ser atualizado.

Também devem verificar quem controla as atualizações e se existe um timelock ou processo de governança.

Um URI base bloqueado tem menos significado se uma atualização puder substituir toda a função tokenURI.

Para obter garantias robustas sobre os metadados, é preciso revisar tanto o URI base quanto o caminho de atualização do contrato.

Os desenvolvedores devem informar claramente se o contrato pode ser atualizado, pois isso afeta a confiança.

Os usuários não devem avaliar a permanência dos metadados apenas pelo URI base.

URI base e verificação de tokens

O URI base pode ajudar os usuários a verificar se os metadados de um token vêm da fonte esperada da coleção.

No entanto, os usuários não devem confiar apenas na aparência da imagem ou no nome do token.

Tokens falsos podem copiar metadados, nomes, símbolos e imagens de coleções legítimas.

O identificador verdadeiro é o endereço do contrato e o ID do token na blockchain correta.

O URI base pode mostrar para onde apontam os metadados, mas não prova, sozinho, que o token é autêntico.

Um contrato fraudulento pode apontar para metadados copiados de uma coleção legítima.

Os usuários devem verificar o endereço do contrato, o padrão do token, as informações do criador, o caminho dos metadados, o histórico de propriedade e as fontes oficiais do projeto.

Os desenvolvedores devem tornar os resultados de tokenURI previsíveis e fáceis de inspecionar.

Um design claro de URI base facilita a verificação, mas não substitui a verificação do contrato.

A autenticidade depende tanto da identidade do token quanto da integridade dos metadados.

URI base e metadados da coleção

O URI base costuma se referir aos caminhos de metadados no nível do token.

Os metadados da coleção são diferentes, pois descrevem o contrato ou a coleção como um todo.

Os metadados da coleção podem incluir nome, descrição, imagem, banner, links externos, taxas ou informações sociais.

Alguns contratos disponibilizam metadados da coleção por meio de funções separadas, como contractURI.

O URI base de um token não deve ser confundido com o URI dos metadados da coleção.

O URI base do token ajuda a gerar metadados para IDs de token individuais.

O URI dos metadados da coleção descreve a coleção inteira.

Ambos podem afetar a forma como carteiras e aplicativos exibem um projeto.

Ambos também podem apresentar riscos de centralização ou mutabilidade.

Os usuários devem entender qual URI controla os dados de cada token e qual controla os dados de exibição da coleção.

URI base e congelamento de metadados

Congelar metadados significa torná-los permanentemente imutáveis ou indicar que não devem mais mudar.

Um projeto pode congelar os metadados removendo a possibilidade de atualizar o URI base.

Também pode congelá-los definindo o URI base como um caminho de armazenamento endereçado por conteúdo e renunciando à autoridade de atualização.

Alguns projetos anunciam que os metadados foram congelados após a revelação.

Os usuários devem verificar se o congelamento é imposto pelo código ou apenas prometido pela equipe.

Uma promessa é menos robusta que um bloqueio no nível do contrato.

Um bloqueio no nível do contrato também é menos robusto se o contrato ainda puder ser atualizado.

Para congelar os metadados de fato, é preciso revisar todos os caminhos que poderiam alterar os resultados de tokenURI.

Congelar os metadados pode aumentar a confiança dos colecionadores quando a permanência é importante.

No entanto, congelá-los cedo demais pode preservar erros que não poderão ser corrigidos posteriormente.

URI base e experiência do usuário

O URI base afeta a experiência do usuário porque os aplicativos usam metadados para mostrar o que cada pessoa possui.

Quando o URI base carrega rapidamente, os NFTs são exibidos sem problemas.

Se o URI base for lento, ficar indisponível ou for bloqueado, as carteiras poderão exibir imagens em branco ou espaços reservados genéricos.

Se o JSON dos metadados estiver malformado, os aplicativos poderão não conseguir interpretá-lo.

Se os links de imagem dentro dos metadados estiverem quebrados, o token poderá mostrar texto, mas nenhuma mídia.

Se as características forem inconsistentes, ferramentas de raridade e jogos poderão interpretar o token de forma errada.

Os usuários costumam avaliar as coleções pelo que veem na carteira.

Por isso, os desenvolvedores devem tratar o design do URI base como parte da qualidade do produto.

Os metadados devem ser válidos, estáveis, rápidos o suficiente para carregar e consistentes entre os IDs de token.

Mesmo um contrato inteligente robusto pode parecer defeituoso se o URI base e os metadados forem mal gerenciados.

Exemplos de URI base

Um URI base IPFS simples pode ter o formato ipfs://bafyExampleCID/.

Se o contrato acrescentar o ID de token 7 e o sufixo .json, o tokenURI completo poderá ser ipfs://bafyExampleCID/7.json.

Um URI base HTTPS simples pode ter o formato https://example.com/api/token/.

Se o contrato acrescentar o ID de token 7, o tokenURI completo poderá ser https://example.com/api/token/7.

Um modelo de URI ERC-1155 pode ter o formato https://example.com/metadata/{id}.json.

Nesse caso, os clientes compatíveis substituem {id} pelo ID do token formatado.

Um data URI on-chain pode começar com data:application/json;base64, em vez de usar um URI base.

Esses exemplos mostram por que os usuários devem verificar o tokenURI realmente retornado, em vez de presumir com base no site da coleção.

A função tokenURI do contrato é a fonte que os aplicativos normalmente consultam.

O URI base só é útil quando gera resultados de tokenURI válidos e acessíveis.

Benefícios de usar um URI base

O primeiro benefício do URI base é a eficiência de gas.

Um prefixo compartilhado pode reduzir a quantidade de dados armazenados on-chain.

O segundo benefício é a organização mais simples da coleção.

Os desenvolvedores podem armazenar arquivos de metadados em uma pasta ou endpoint e associá-los aos IDs dos tokens.

O terceiro benefício é facilitar a emissão de grandes coleções.

Novos tokens podem apontar automaticamente para caminhos previsíveis de metadados.

O quarto benefício é facilitar o gerenciamento da revelação.

Quando o contrato permite, um projeto pode trocar os metadados provisórios pelos finais alterando um único URI base.

O quinto benefício é a compatibilidade.

Carteiras, exploradores e aplicativos estão acostumados a ler tokenURI e caminhos de metadados no formato URI.

O sexto benefício é a flexibilidade.

O URI base pode oferecer suporte a IPFS, HTTPS, links de armazenamento permanente, endpoints de API ou modelos híbridos.

Riscos de usar um URI base

O primeiro risco são metadados quebrados.

Um URI base incorreto pode afetar todos os tokens de uma coleção.

O segundo risco é a centralização.

Um URI base que aponta para um servidor comum depende desse servidor, domínio e operador.

O terceiro risco são atualizações maliciosas.

Se um administrador puder alterar o URI base, poderá potencialmente mudar o que todos os tokens exibem.

O quarto risco é a mutabilidade oculta.

Os usuários podem acreditar que os metadados são permanentes quando o URI base ainda pode ser editado.

O quinto risco é a confusão causada pelo cache.

Após uma atualização do URI base, os aplicativos podem continuar exibindo metadados antigos.

O sexto risco é a disponibilidade do armazenamento.

Mesmo metadados endereçados por conteúdo podem ser difíceis de acessar se ninguém os hospedar ou fixar.

O sétimo risco é a lógica atualizável.

Uma atualização do contrato pode alterar o comportamento de tokenURI mesmo quando o URI base parece bloqueado.

Como verificar um URI base

Os usuários podem verificar o funcionamento do URI base chamando a função tokenURI para um ID de token específico.

Devem comparar o URI retornado com as informações oficiais do projeto sobre os metadados.

Devem verificar se o URI começa com ipfs://, https://, data:, ar:// ou outro esquema.

Devem testar se o arquivo de metadados carrega e retorna JSON válido.

Devem verificar se o JSON inclui imagem, descrição, atributos e outros campos esperados.

Também devem verificar se os links de imagem dentro do JSON são estáveis e acessíveis.

Devem analisar o contrato para descobrir se o URI base pode ser alterado.

Devem verificar se o contrato pode ser atualizado.

Devem acompanhar os eventos de atualização de metadados quando uma coleção afirma que houve mudanças.

Não devem presumir que um token é seguro apenas porque é exibido corretamente em uma carteira.

Boas práticas para desenvolvedores

Os desenvolvedores devem decidir como os metadados serão armazenados antes de implantar o contrato do token.

Devem escolher se o URI base será imutável, mutável, baseado em revelação, dinâmico ou totalmente on-chain.

Devem usar links endereçados por conteúdo quando a integridade de longo prazo for importante.

Devem testar os resultados de tokenURI para muitos IDs antes do lançamento.

Devem manter consistentes os nomes de arquivos, sufixos e barras finais.

Devem proteger as funções de atualização do URI base com controles de acesso robustos.

Devem informar se os metadados poderão mudar após a emissão.

Quando os metadados mudarem, devem emitir eventos padronizados de atualização se o contrato oferecer suporte a esse padrão.

Devem manter backups e planos de hospedagem de longo prazo para todos os metadados e mídias.

Devem lembrar que os metadados fazem parte da confiança do usuário, não são apenas um recurso de exibição.

Boas práticas para usuários

Os usuários devem verificar o endereço do contrato antes de confiar nos metadados.

Devem verificar o tokenURI de um token real, em vez de confiar em capturas de tela.

Devem preferir projetos que expliquem claramente onde os metadados são armazenados.

Devem entender se o URI base ainda pode ser alterado.

Devem verificar se os metadados estão em sistemas endereçados por conteúdo ou em servidores centralizados.

Devem ter cuidado com projetos que prometem permanência, mas mantêm poderes administrativos de atualização.

Devem observar alterações repentinas nos metadados após a revelação ou venda.

Devem lembrar que a propriedade de um NFT nem sempre significa propriedade do arquivo de mídia, direitos autorais ou direitos off-chain.

Quando o acesso de longo prazo for importante, os usuários devem salvar localmente os metadados e as mídias relevantes.

Devem tratar metadados quebrados ou suspeitos como um sinal de risco.

Equívocos comuns sobre URI base

Um equívoco comum é pensar que o URI base armazena o próprio NFT.

Em geral, o URI base aponta para os metadados, enquanto o contrato inteligente registra a propriedade.

Outro equívoco é pensar que a imagem de um NFT está sempre armazenada on-chain.

Muitas imagens de NFT ficam off-chain ou em armazenamento descentralizado e são referenciadas pelos metadados.

Um terceiro equívoco é pensar que o IPFS garante que o conteúdo permanecerá online para sempre.

O IPFS melhora a integridade do conteúdo, mas alguém ainda precisa disponibilizá-lo.

Um quarto equívoco é pensar que um URI base bloqueado garante a propriedade legal do ativo exibido nos metadados.

A permanência dos metadados e os direitos legais são questões distintas.

Um quinto equívoco é pensar que toda alteração do URI base é ruim.

Algumas mudanças são legítimas para revelações, NFTs dinâmicos ou correções de erros, mas devem ser transparentes e devidamente controladas.

Um sexto equívoco é pensar que uma exibição correta prova que o URI base é seguro.

Os caches podem ocultar problemas, e os usuários devem inspecionar o tokenURI real sempre que possível.

Termos cripto relacionados

URI significa Uniform Resource Identifier, uma string usada para identificar um recurso, como um arquivo de metadados.

tokenURI significa a função ERC-721 que retorna o URI dos metadados para um ID de token específico.

ERC-721 é um padrão de token comum da Ethereum para tokens não fungíveis.

ERC-1155 é um padrão de múltiplos tokens que pode oferecer suporte a ativos fungíveis, semifungíveis e não fungíveis.

Metadados de NFT são dados JSON ou estruturados que descrevem o nome, a imagem, as características e outras propriedades de um token.

IPFS significa InterPlanetary File System, uma rede de armazenamento endereçado por conteúdo usada com frequência para dados de NFT.

CID significa identificador de conteúdo, uma referência endereçada por conteúdo usada pelo IPFS.

Data URI é um URI que incorpora dados diretamente na própria string do URI.

Revelação de metadados é o processo de substituir os metadados provisórios dos tokens pelos metadados finais.

Congelamento de metadados é o processo de tornar os metadados do token ou seus caminhos imutáveis após determinado momento.

FAQ

O que significa URI base em NFTs?

URI base é o caminho inicial compartilhado que um contrato inteligente usa para montar o URI completo dos metadados de cada NFT.

URI base é igual a tokenURI?

Não. O URI base costuma ser o prefixo compartilhado, enquanto tokenURI é o URI completo dos metadados retornado para um token específico.

Como funciona o URI base no ERC-721?

Em muitos contratos ERC-721, o URI base é combinado com o ID do token para gerar o tokenURI final daquele NFT.

Como funciona o URI base no ERC-1155?

O ERC-1155 costuma usar um modelo de URI com substituição de {id}, em que os clientes substituem {id} pelo ID do token formatado.

É possível alterar um URI base?

Sim. Um URI base pode ser alterado se o contrato tiver uma função de atualização e uma conta autorizada ainda controlá-la.

Um URI base mutável apresenta riscos?

Sim. Um URI base mutável apresenta riscos porque seu controlador pode conseguir alterar os metadados de muitos ou de todos os tokens.

Um URI base imutável é sempre melhor?

Um URI base imutável pode aumentar a confiança, mas também pode tornar erros permanentes se os caminhos dos metadados estiverem incorretos no lançamento.

Por que projetos de NFT usam IPFS no URI base?

Os projetos usam IPFS porque os CIDs são endereçados por conteúdo e ajudam a verificar se os metadados referenciados não foram alterados silenciosamente.

O IPFS garante que os metadados de NFT ficarão online para sempre?

Não. O IPFS ajuda a preservar a integridade, mas o conteúdo ainda precisa ser hospedado, fixado ou disponibilizado de outra forma.

Por que a imagem do meu NFT não aparece, embora eu tenha o token?

A imagem pode não aparecer porque o URI base está incorreto, o arquivo de metadados está indisponível, o link da imagem está quebrado ou o cache do aplicativo ainda não foi atualizado.

O que é revelação de metadados?

Revelação de metadados é quando um projeto troca os metadados provisórios dos tokens pelos metadados finais, muitas vezes atualizando o URI base ou a lógica de tokenURI.

Como verificar se o URI base de um NFT é seguro?

Você pode verificar o resultado de tokenURI, o tipo de armazenamento, as permissões de atualização, a possibilidade de atualização do contrato, o formato dos metadados e a disponibilidade dos arquivos em armazenamento confiável.

Conclusão

O URI base é um conceito fundamental de metadados em contratos de NFTs e tokens cripto.

É o caminho compartilhado que ajuda um contrato a montar o URI completo dos metadados de cada token.

Em muitas coleções ERC-721, o URI base é combinado com o ID do token para gerar tokenURI.

No ERC-1155, uma função semelhante costuma ser realizada por um modelo de URI que usa a substituição de {id}.

O URI base facilita e barateia o gerenciamento de grandes coleções, pois um prefixo compartilhado pode servir a muitos arquivos de metadados de tokens.

Ele também levanta questões importantes de confiança, pois os metadados muitas vezes ficam fora da blockchain.

Se o URI base apontar para servidores centralizados, os usuários dependerão desses servidores e de seus operadores.

Se apontar para armazenamento endereçado por conteúdo, os usuários poderão obter garantias maiores de integridade, mas ainda dependerão da disponibilidade do conteúdo.

Se o URI base puder ser alterado, os usuários precisarão confiar na autoridade de atualização e em seus controles de segurança.

Se o URI base for imutável, os usuários terão permanência, mas perderão flexibilidade caso existam erros.

Os desenvolvedores devem projetar cuidadosamente a lógica do URI base antes do lançamento, testar os caminhos dos arquivos, proteger as permissões de atualização e informar claramente se os metadados podem mudar.

Os usuários devem inspecionar tokenURI, verificar os endereços dos contratos, entender o tipo de armazenamento e evitar presumir que as mídias exibidas sejam automaticamente permanentes ou de sua propriedade legal.

A principal lição é que a propriedade de um NFT e seus metadados estão relacionados, mas não são a mesma coisa.

O contrato inteligente comprova a propriedade do token, enquanto o URI base ajuda os aplicativos a encontrar os dados que explicam o que o token representa.

Um design robusto de URI base torna essa conexão estável, transparente e fácil de verificar.

Um design frágil pode transformar um token aparentemente valioso em um link quebrado, uma promessa mutável ou um risco à segurança dos metadados.