Extensão Enumerable

O que é a extensão Enumerable?

A extensão Enumerable é um recurso opcional do padrão de tokens não fungíveis ERC-721 que permite que contratos inteligentes e aplicativos de cripto descubram IDs de tokens NFT por meio de consultas de índice on-chain.

Ela é comumente identificada pelo nome de interface

ou pelo nome de implementação .

A especificação oficial do ERC-721 define a extensão como uma forma de um contrato publicar a lista completa de NFTs válidos e os IDs de token pertencentes a cada endereço.

A extensão adiciona três funções chamadas

, e .

Essas funções complementam a interface principal de propriedade e transferência do ERC-721.

Elas não substituem funções como

, , ou .

A extensão Enumerable é opcional. Portanto, um contrato NFT pode estar totalmente em conformidade com o ERC-721 sem oferecer suporte a ela.

Por que ela se chama Enumerable?

Enumerar uma coleção significa identificar seus elementos um a um usando um índice ou outro método organizado.

A interface principal do ERC-721 pode informar a um aplicativo quem é o proprietário de um ID de token conhecido.

Ela também pode informar quantos NFTs pertencem a um endereço.

No entanto, a interface principal não oferece uma função on-chain direta para descobrir todos os IDs de token existentes ou todos os IDs de token de um proprietário específico.

A extensão Enumerable preenche essa lacuna ao adicionar acesso indexado à coleção global e aos ativos de cada proprietário.

Um aplicativo pode começar pelo índice zero e continuar consultando índices maiores até alcançar a oferta relevante ou o saldo do proprietário.

Qual é o ID de interface da extensão Enumerable?

O ID de interface ERC-165 da extensão Enumerable do ERC-721 é

.

Um contrato compatível deve retornar

quando sua função for chamada com esse valor.

O padrão de detecção de interface ERC-165 permite que aplicativos perguntem a um contrato inteligente quais interfaces ele afirma implementar.

A interface principal do ERC-721 tem um ID separado. Assim, um aplicativo pode testar de forma independente o suporte à interface principal e à Enumerable.

Um contrato que implementa a extensão Enumerable também precisa implementar a interface principal do ERC-721.

Uma resposta positiva na detecção de interface melhora a verificação de compatibilidade, mas não comprova que a implementação seja correta, segura ou honesta.

Funções adicionadas pela extensão Enumerable

A extensão Enumerable adiciona apenas três funções públicas de consulta.

A função

retorna o número de NFTs válidos que o contrato acompanha atualmente.

A função

retorna um ID de token da lista geral do contrato.

A função

retorna um ID de token dos ativos atuais de um proprietário.

As três funções são somente leitura (view) na interface padrão.

A extensão não adiciona funções de transferência, aprovação, emissão (minting), queima (burning), metadados ou royalties.

A função totalSupply

A função

retorna o número de NFTs válidos que pertencem atualmente a um endereço diferente do endereço zero.

Ela informa a oferta ativa atual, e não a oferta máxima possível.

Por exemplo, um contrato pode informar uma oferta total de 8.000 e ainda manter a autoridade para emitir mais NFTs no futuro.

Se um NFT for queimado e deixar de ser considerado propriedade válida, a oferta total informada normalmente diminuirá.

Isso significa que

não é necessariamente igual ao número de NFTs já emitidos.

Também não comprova que a coleção tenha um limite permanente.

Os usuários devem analisar a lógica de emissão e as permissões privilegiadas para verificar alegações de escassez.

A função tokenByIndex

A função

retorna o ID de token que ocupa uma posição especificada na enumeração geral do contrato.

O índice começa em zero.

Um índice válido precisa ser menor que o valor retornado por

.

Se a oferta total for 100, os índices válidos vão de zero a 99.

Uma consulta com o índice 100 ou um número maior deve falhar.

O ID de token retornado não precisa ser igual ao índice.

Por exemplo, o índice zero pode retornar o ID de token 500, enquanto o índice um pode retornar o ID 12.

Os aplicativos nunca devem presumir que os IDs de token são sequenciais só porque os índices de enumeração são.

A função tokenOfOwnerByIndex

A função

retorna um ID de token pertencente a um endereço especificado.

O índice começa em zero e precisa ser menor que o resultado de

para esse proprietário.

Se um endereço possuir três NFTs, seus índices válidos de proprietário serão zero, um e dois.

A função deve falhar quando o índice estiver fora do saldo atual do proprietário.

Ela também deve falhar quando o proprietário informado for o endereço zero.

A função permite que aplicativos on-chain e off-chain listem os NFTs de um endereço sem pesquisar todos os IDs de token possíveis.

Como as três funções funcionam em conjunto

Um aplicativo pode chamar

para descobrir quantos NFTs válidos existem no momento.

Em seguida, pode chamar

uma vez para cada índice, de zero até um a menos que a oferta.

Para cada ID de token retornado, pode chamar

para identificar o proprietário atual.

Para listar os ativos de um endereço, o aplicativo pode chamar

e depois consultar para cada índice válido do proprietário.

Esse processo permite descobrir tokens por meio de funções on-chain padronizadas.

Coleções grandes ainda podem exigir muitas chamadas RPC. Por isso, aplicativos em produção costumam usar paginação, processamento em lote, cache ou indexação de eventos.

A ordem da enumeração não é garantida

A especificação ERC-721 não define uma ordem de classificação obrigatória para

ou .

A ordem retornada não precisa seguir o ID do token, o horário de emissão, o horário de transferência, a raridade, os metadados ou o tempo de propriedade.

Um contrato pode alterar a posição de um token quando outro token é transferido ou queimado.

Os aplicativos não devem tratar um índice de enumeração como um identificador permanente.

O ID do token é o identificador estável dentro do contrato; o índice é apenas uma posição de consulta atual.

Uma interface que precise de resultados ordenados deve classificar off-chain os IDs de token retornados, de acordo com suas próprias regras.

Enumeração com swap-and-pop

Uma implementação comum usa uma técnica chamada swap and pop para remover IDs de token de arrays com eficiência.

Quando um token é removido, a implementação coloca o último token na posição do array que era ocupada pelo token removido.

Em seguida, exclui a última entrada do array.

Isso evita deslocar todos os tokens seguintes e mantém relativamente baixa a complexidade da remoção.

No entanto, a ordem dos IDs de token restantes é alterada.

A implementação atual de ERC721Enumerable da OpenZeppelin usa esse método tanto para os índices globais quanto para os específicos de cada proprietário.

Por isso, durante um processo de enumeração longo, um aplicativo deve reiniciar a paginação ou reconciliá-la cuidadosamente se a propriedade mudar.

Exemplo de enumeração da coleção inteira

Suponha que um contrato ERC-721 informe uma oferta total de quatro.

Um aplicativo chama

com os índices zero, um, dois e três.

O contrato retorna os IDs de token 18, 42, 7 e 105.

O aplicativo agora conhece todos os IDs de token válidos, embora eles não sejam sequenciais.

Ele pode chamar

e para cada ID e exibir a propriedade e os metadados.

Se o ID de token 42 for queimado posteriormente, a enumeração global poderá retornar 18, 105 e 7, pois a implementação pode mover o último item para a posição removida.

Essa alteração é válida porque o padrão não garante a ordem da enumeração.

Exemplo de enumeração por proprietário

Suponha que Alice possua os IDs de token 9, 30 e 88 em um contrato NFT Enumerable.

A função

do contrato retorna três para o endereço de Alice.

Um aplicativo consulta os índices de proprietário zero, um e dois usando

.

O contrato retorna os três IDs de token de Alice.

Em seguida, Alice transfere o ID de token 30 para Bob.

O saldo de Alice cai para dois, e os IDs restantes podem aparecer em uma ordem de índice diferente.

Antes de repetir a enumeração do proprietário, o aplicativo deve consultar o saldo atualizado.

Extensão Enumerable vs. ERC-721 principal

O padrão ERC-721 principal oferece propriedade, transferências, aprovações, eventos e verificações de destinatário seguro.

Ele pode responder se um ID de token conhecido existe e quem é seu proprietário.

Ele não oferece uma lista on-chain padronizada de todos os IDs de token.

A extensão Enumerable adiciona essa camada de descoberta.

Uma coleção sem enumeração ainda pode transferir NFTs normalmente e funcionar com carteiras compatíveis com ERC-721.

A ausência de enumeração não torna o NFT inválido nem incompatível com o padrão.

Para oferecer ampla compatibilidade com ERC-721, os aplicativos precisam aceitar coleções Enumerable e não Enumerable.

Extensão Enumerable vs. extensão Metadata

A extensão Enumerable identifica IDs de token existentes e os ativos dos proprietários.

A extensão Metadata fornece o nome, o símbolo e a URI do token da coleção.

A enumeração não descreve a imagem, os atributos, o título nem o conteúdo externo associado a um NFT.

O suporte a metadados não fornece uma lista completa de tokens.

Um contrato pode implementar uma extensão, ambas ou nenhuma delas e ainda manter o comportamento principal do ERC-721.

Os aplicativos devem verificar cada interface separadamente.

Extensão Enumerable vs. apenas totalSupply

Alguns contratos NFT adicionam uma função personalizada

sem implementar a extensão Enumerable completa.

Um nome de função conhecido não comprova o suporte a

ou .

O significado de uma função de oferta personalizada também pode ser diferente da definição de enumeração do ERC-721.

Ela pode informar o número de tokens já emitidos, o próximo ID de token, o tamanho máximo da coleção ou outro valor específico do projeto.

Os aplicativos devem usar ERC-165 para testar a interface Enumerable completa, em vez de confiar em um único seletor de função.

Por que a extensão Enumerable custa mais gas

A enumeração exige que o contrato mantenha estruturas de armazenamento adicionais.

Uma implementação comum armazena um array com todos os IDs de token existentes.

Ela também armazena a lista indexada de tokens de cada proprietário e mapeamentos que registram as posições dos tokens.

A emissão precisa adicionar o novo token à lista global e à lista do proprietário.

A transferência precisa remover o token da lista do proprietário anterior e adicioná-lo à lista do novo proprietário.

A queima precisa remover o token da lista do proprietário e da lista global.

Essas gravações adicionais no armazenamento aumentam o custo de gas das transações que alteram o estado.

As orientações atuais de implementação ERC-721 observam que a extensão costuma ser omitida por gerar uma sobrecarga considerável de gas.

As consultas de enumeração são gratuitas?

Um usuário pode chamar funções view por meio de um endpoint RPC sem enviar uma transação à blockchain.

Nesse caso, não há pagamento de taxa de gas on-chain, pois um nó simula a leitura localmente.

No entanto, o nó ainda realiza processamento e pode aplicar limites de frequência ou restrições às solicitações.

Se outro contrato inteligente chamar uma função de enumeração durante uma transação, o processamento consumirá gas da transação.

Um loop que consulta centenas ou milhares de índices de token on-chain pode se tornar caro demais para ser concluído.

Os desenvolvedores não devem confundir uma leitura off-chain sem custo de gas com processamento on-chain ilimitado.

Loops e limites de gas dos blocos

Um contrato inteligente deve evitar funções que alterem o estado e percorram todos os NFTs de uma coleção ou todos os NFTs de um endereço sem limites.

O número de iterações pode crescer com o tempo até que a transação ultrapasse o limite de gas do bloco.

A documentação de segurança do Solidity alerta que loops dependentes do armazenamento podem, eventualmente, impedir a conclusão das operações do contrato.

Funções view chamadas off-chain não geram a mesma taxa de transação, mas ainda podem sobrecarregar um provedor RPC.

Para grandes conjuntos de dados, os aplicativos devem usar páginas limitadas, consultas de índices individuais ou indexação off-chain.

Indexação off-chain de eventos como alternativa

Todo contrato ERC-721 compatível emite eventos

quando NFTs são emitidos, transferidos ou queimados.

Um indexador off-chain pode processar esses eventos desde o bloco de implantação do contrato para reconstruir a propriedade atual.

A emissão normalmente é representada por uma transferência a partir do endereço zero.

A queima normalmente é representada por uma transferência para o endereço zero.

As transferências normais alteram a propriedade entre dois endereços diferentes de zero.

A indexação de eventos evita as gravações adicionais no armazenamento exigidas pela enumeração on-chain.

Ela também oferece suporte mais eficiente a buscas, classificação, filtragem e paginação em coleções grandes.

A desvantagem é que os usuários precisam confiar no sistema de indexação ou operá-lo por conta própria, além de garantir que ele permaneça sincronizado.

Extensão Enumerable vs. indexação de eventos

A enumeração on-chain dá aos contratos inteligentes acesso direto e padronizado aos índices dos tokens.

A indexação de eventos oferece uma descoberta off-chain mais rica e escalável.

A enumeração é útil quando outro contrato inteligente precisa verificar ou selecionar IDs de token sem depender de um banco de dados externo.

A indexação de eventos costuma ser mais prática para interfaces de carteira, páginas de coleções, análises e buscas históricas.

Um projeto pode oferecer suporte aos dois métodos.

A melhor escolha depende de a possibilidade de descoberta on-chain justificar o gas adicional pago em cada emissão, transferência e queima.

A enumeração oferece paginação?

A extensão não define uma função que retorne uma página de IDs de token.

Ela fornece um ID de token por consulta de índice.

Um aplicativo off-chain pode criar paginação solicitando um intervalo limitado de índices.

Por exemplo, a primeira página pode consultar os índices de zero a 49, enquanto a segunda consulta de 50 a 99.

O aplicativo precisa levar em conta as mudanças na oferta e na ordem enquanto avança entre as páginas.

Uma transferência ou queima pode mover tokens entre índices e fazer um processo de paginação longo ignorar ou repetir um ID.

O uso de dados de uma altura fixa de bloco pode fornecer um retrato mais consistente quando o sistema RPC oferece suporte a consultas históricas.

A enumeração lista todos os proprietários?

A extensão lista os IDs de token globalmente e os IDs de token de um proprietário conhecido.

Ela não oferece uma função que retorne todos os endereços únicos de proprietários.

Um aplicativo pode derivar a lista de proprietários chamando

para cada ID de token ou processando eventos de transferência.

O mesmo proprietário pode aparecer várias vezes, pois um endereço pode possuir vários NFTs.

Por isso, criar uma lista de titulares únicos costuma ser uma tarefa de indexação off-chain.

A enumeração comprova a autenticidade do token?

Não. A enumeração apenas informa os IDs de token acompanhados por um contrato inteligente específico.

Qualquer pessoa pode implantar um contrato ERC-721 Enumerable com nomes, imagens, símbolos ou metadados copiados.

A rede blockchain e o endereço completo do contrato continuam sendo partes essenciais da identidade de um NFT.

Uma interface Enumerable correta não comprova que o emissor seja proprietário da arte, controle o ativo alegado ou tenha intenções honestas.

Os usuários devem verificar o contrato por meio de informações oficiais do projeto e analisar suas permissões de forma independente.

totalSupply comprova escassez?

Uma contagem de oferta atual não estabelece uma oferta máxima permanente.

O contrato pode conter uma função pública de emissão, uma função de emissão para administradores, um sistema de emissão por bridge ou autoridade para atualizações.

Um ID de token sem proprietário atual também pode ser emitido posteriormente.

Contratos atualizáveis podem alterar suas regras de oferta após a implantação.

Os usuários devem examinar o código e o modelo de controle de acesso antes de confiar em uma alegação de escassez.

A enumeração facilita a consulta da oferta atual, mas não garante o cumprimento de promessas econômicas.

Emissão e enumeração

Quando um novo NFT é emitido, uma implementação Enumerable precisa adicionar o ID do token ao índice global e ao índice do primeiro proprietário.

A oferta total aumenta em um.

O ID do token pode aparecer em qualquer índice global válido permitido pela implementação.

Uma política de emissão sequencial não exige que o índice de enumeração permaneça igual ao ID do token.

A lógica de emissão personalizada precisa atualizar todas as estruturas de enumeração exigidas de maneira consistente.

Uma atualização incompleta pode fazer com que saldos, registros de propriedade, oferta total e resultados da enumeração sejam divergentes.

Transferências e enumeração

Normalmente, uma transferência não altera a oferta total.

Ela remove o ID do token da enumeração do proprietário anterior e o adiciona à enumeração do destinatário.

A lista global de tokens normalmente continua contendo o mesmo ID de token.

As posições dos índices específicos do proprietário podem mudar durante o processo de remoção.

Transferências para o próprio endereço exigem uma implementação cuidadosa, pois o remetente e o destinatário são o mesmo endereço.

Implementações revisadas tratam essa situação sem remover ou duplicar o token incorretamente.

Queima e enumeração

A queima remove um token da propriedade válida do ERC-721.

Uma implementação Enumerable remove o ID do token queimado da lista do proprietário e da lista global.

A oferta total diminui.

Os antigos índices globais e do proprietário do token não devem mais ser usados.

Outros tokens podem ocupar essas posições devido à remoção por swap-and-pop.

Aplicativos históricos devem usar eventos, e não a enumeração atual, quando precisarem manter um registro de NFTs queimados.

Compatibilidade com emissão em lote

Algumas implementações ERC-721 oferecem suporte à emissão em lote comprimida ou consecutiva durante a construção do contrato.

Esses sistemas podem calcular a propriedade sem registrar cada token pela lógica normal de atualização da enumeração.

A implementação atual da OpenZeppelin alerta que sua extensão de emissão consecutiva interfere em

e não deve ser combinada com ela.

A implementação Enumerable atual também rejeita o caminho não compatível de atualização de saldo em lote.

Os desenvolvedores não devem combinar extensões apenas porque cada uma funciona de forma independente.

O comportamento de herança, armazenamento, eventos, saldos e ganchos de atualização deve ser analisado em conjunto.

Enumeração e contratos atualizáveis

Um contrato NFT atualizável pode adicionar ou modificar a lógica após a implantação, se o sistema de governança permitir.

Adicionar enumeração depois que muitos NFTs já existem exige cuidado especial.

O novo armazenamento de enumeração pode começar vazio, embora o contrato principal já acompanhe milhares de tokens.

Pode ser necessário um processo de migração para preencher os índices globais e específicos dos proprietários.

Loops de migração on-chain grandes podem ultrapassar os limites de gas.

Erros no layout de armazenamento também podem corromper dados existentes de propriedade ou aprovação.

Administradores de contratos atualizáveis devem usar procedimentos de migração testados, transações limitadas e uma análise de segurança independente.

Enumeração e lógica personalizada de balanceOf

A enumeração do proprietário depende de informações precisas sobre o saldo ERC-721.

Uma extensão que calcula

por meio de um método personalizado ou comprimido pode entrar em conflito com os índices de proprietário armazenados.

As orientações atuais de implementação alertam especificamente que extensões com lógica de saldo personalizada podem ser incompatíveis com a enumeração.

Os desenvolvedores precisam confirmar que cada emissão, transferência e queima atualiza as contagens e os índices de propriedade por caminhos de código compatíveis.

Um contrato que informa saldo de cinco para um proprietário, mas armazena apenas quatro IDs de token indexados, é internamente inconsistente.

Riscos de segurança para aplicativos integrados

Um aplicativo deve verificar o suporte à interface Enumerable antes de chamar suas funções.

Ele deve tratar erros de índice fora dos limites, em vez de presumir que um índice consultado anteriormente continua válido.

Não deve confiar na ordem da enumeração para cálculos de raridade, prioridade ou financeiros.

Deve se proteger contra resultados duplicados ou ausentes se o estado mudar durante a paginação.

Também deve verificar se cada ID de token retornado pertence ao contrato e à rede esperados.

Para decisões de alto valor, o aplicativo pode precisar de um retrato consistente de bloco e de um nível de finalização adequado.

RPC e consistência dos dados

Um endpoint RPC pode retornar dados de enumeração de um bloco recente, seguro, finalizado ou histórico, conforme a rede e a configuração da solicitação.

Duas chamadas feitas em alturas de bloco diferentes podem produzir listas de oferta ou de proprietários distintas.

Um NFT transferido recentemente pode aparecer com proprietários diferentes em fontes de dados ainda não sincronizadas.

Quando a consistência for importante, os aplicativos devem registrar o número do bloco usado em consultas de enumeração com várias chamadas.

Sistemas críticos podem comparar vários nós ou operar um nó verificado de forma independente.

A enumeração elimina a dependência de uma API específica da coleção, mas não elimina todas as considerações de confiança em RPC.

Benefícios da extensão Enumerable

A extensão oferece uma forma padronizada de descobrir todos os IDs de token atuais.

Ela permite que outro contrato inteligente consulte os NFTs de um proprietário sem um indexador externo.

Oferece uma função padrão para consultar a oferta atual.

Pode simplificar coleções pequenas, jogos on-chain, sistemas de associação e aplicativos que exigem a seleção direta de tokens.

Também disponibiliza consultas básicas de inventário NFT mesmo quando o site do projeto ou seu banco de dados privado deixam de existir.

Limitações da extensão Enumerable

A extensão aumenta os custos de gas de emissões, transferências e queimas.

Ela não garante uma ordem estável dos tokens.

Não oferece paginação, classificação, filtragem ou enumeração de titulares integradas.

Informa os tokens atuais, e não um histórico completo.

Pode ser incompatível com sistemas de emissão em lote comprimida ou de saldo personalizado.

Loops on-chain grandes continuam limitados pelo gas da transação.

Ela também não fornece metadados, royalties, preços, autenticidade nem garantias de limite de oferta.

Quando um projeto deve usar enumeração?

Um projeto pode se beneficiar da enumeração quando contratos inteligentes precisam descobrir diretamente IDs de token on-chain.

Ela também pode ser adequada para uma coleção pequena, na qual o custo adicional das transferências seja aceitável.

Um jogo pode usá-la quando a lógica do contrato precisa selecionar um dos NFTs de um jogador por índice.

Um contrato de associação pode usá-la quando um processo on-chain precisa verificar os tokens de associação atuais de um titular.

Ainda assim, o projeto deve limitar loops e avaliar se um mapeamento mais simples ou um índice específico do aplicativo seria mais eficiente.

Quando um projeto pode evitar a enumeração?

Uma coleção NFT grande pode evitar a enumeração para reduzir o custo de cada emissão, transferência e queima.

Um projeto também pode evitá-la quando todas as funções de descoberta e busca já dependem de um indexador de eventos off-chain.

Sistemas de emissão em lote comprimida podem usar modelos de propriedade que não funcionam bem com o armazenamento padrão de enumeração.

Um projeto que nunca precisa listar tokens on-chain pode ter pouco benefício em pagar por índices on-chain permanentes.

A decisão deve se basear nos requisitos reais do aplicativo, e não na suposição de que toda extensão opcional é necessária.

Como os desenvolvedores devem implementar a extensão

Os desenvolvedores devem começar com uma implementação Enumerable de ERC-721 mantida e revisada ativamente.

Devem garantir que

informe .

Todos os caminhos de emissão, transferência e queima precisam atualizar corretamente a enumeração global e a dos proprietários.

As extensões personalizadas devem ser verificadas quanto a conflitos com propriedade, saldos, emissão em lote, wrapping, pausas e atualizações.

Os testes devem abranger os primeiros e os últimos índices, índices fora dos limites, transferências para o próprio endereço, queimas, novas emissões quando permitidas e mudanças repetidas de propriedade.

Os testes de invariantes devem verificar se

é igual ao número de tokens enumeráveis globalmente.

Também devem verificar se a quantidade de tokens enumeráveis de cada proprietário é igual a

.

Como os usuários podem verificar o suporte à extensão Enumerable

O primeiro passo é verificar o endereço do contrato NFT e a rede blockchain.

O segundo é chamar

com .

O terceiro é confirmar também o suporte à interface principal do ERC-721.

O quarto é comparar

com uma pequena amostra de índices válidos.

O quinto é comparar o resultado de

de um proprietário com os IDs de token retornados pela enumeração do proprietário.

Essas verificações podem identificar inconsistências evidentes, mas não substituem uma análise completa do contrato.

Erros comuns relacionados à extensão Enumerable

Um erro comum é presumir que todo contrato ERC-721 oferece suporte à enumeração.

Outro é tratar um índice de enumeração como um ID de token permanente.

Um terceiro erro é presumir que os IDs de token seguem uma ordem numérica ou de emissão.

Um quarto erro é tratar

como um limite permanente de oferta.

Um quinto erro é percorrer uma coleção sem limite dentro de uma transação que altera o estado.

Um sexto erro é ignorar mudanças na ordem durante a paginação.

Um sétimo erro é presumir que uma função personalizada

comprova o suporte à extensão completa.

Um oitavo erro é combinar implementações incompatíveis de emissão em lote e enumeração.

Um nono erro é adicionar enumeração a uma coleção atualizável sem migrar os tokens anteriores.

Um décimo erro é tratar o suporte à interface Enumerable como prova de que uma coleção NFT é autêntica ou valiosa.

Perguntas frequentes

O que significa extensão Enumerable em cripto?

Geralmente, refere-se à extensão opcional do ERC-721 que permite aos aplicativos listar todos os IDs de token NFT atuais e os IDs de token pertencentes a um endereço especificado.

A extensão Enumerable é obrigatória no ERC-721?

Não. Um contrato NFT pode estar em conformidade com o ERC-721 principal sem oferecer suporte à enumeração.

Qual é o ID de interface da extensão Enumerable?

O ID de interface ERC-165 é

.

Quais funções a extensão adiciona?

Ela adiciona

, e .

O que totalSupply retorna?

Retorna o número de NFTs atualmente válidos acompanhados pelo contrato.

totalSupply informa a oferta máxima possível?

Não. Informa a oferta atual e não comprova que futuras emissões sejam impossíveis.

O que tokenByIndex retorna?

Retorna o ID de token armazenado em um índice especificado da enumeração global.

O que tokenOfOwnerByIndex retorna?

Retorna um ID de token pertencente a um endereço especificado, em um índice de proprietário especificado.

Os índices de enumeração começam em zero?

Sim. Os índices válidos começam em zero e terminam uma posição antes da oferta ou do saldo relevante.

Um índice de enumeração é igual a um ID de token?

Não. O índice é uma posição temporária na lista, enquanto o ID de token identifica o NFT dentro do contrato.

Os IDs de token são retornados em ordem numérica?

Não. O padrão não exige uma ordem específica de enumeração.

A ordem da enumeração pode mudar?

Sim. Transferências e queimas podem alterar as posições dos índices, especialmente em implementações que usam remoção por swap-and-pop.

Queimar um NFT reduz totalSupply?

Sim. Um contrato Enumerable implementado corretamente remove o NFT queimado e reduz a oferta total atual.

Transferir um NFT altera totalSupply?

Não. Uma transferência normal altera a enumeração do proprietário, mas não o número de NFTs existentes.

Por que a extensão é cara?

Ela exige gravações adicionais no armazenamento para manter os índices globais e específicos dos proprietários durante emissões, transferências e queimas.

As chamadas de enumeração são gratuitas?

Leituras RPC off-chain não exigem pagamento de gas on-chain, mas chamadas de contratos inteligentes feitas durante uma transação consomem gas.

Um contrato pode percorrer todos os NFTs Enumerable?

Pode tentar, mas um loop on-chain sem limite pode, eventualmente, ultrapassar o limite de gas do bloco.

A extensão oferece paginação?

Não. Os aplicativos criam paginação consultando intervalos de índices selecionados.

A extensão lista todos os titulares de NFTs?

Não. Ela lista IDs de token globalmente e para um proprietário conhecido, mas não retorna uma lista única de todos os endereços proprietários.

A indexação de eventos pode substituir a enumeração?

Sim. Um indexador off-chain pode reconstruir a oferta e a propriedade dos tokens a partir dos eventos Transfer do ERC-721.

A enumeração inclui metadados NFT?

Não. Os metadados são fornecidos por uma extensão opcional separada do ERC-721.

A enumeração comprova a autenticidade de um NFT?

Não. Qualquer pessoa pode implantar um contrato Enumerable. Por isso, os usuários precisam verificar a rede, o endereço do contrato, o emissor e as permissões.

A enumeração pode ser adicionada após a implantação?

Um contrato atualizável pode adicioná-la, mas os tokens existentes precisam ser migrados com segurança para as novas estruturas de indexação.

ERC721Enumerable é compatível com todas as extensões ERC-721?

Não. A emissão em lote comprimida e implementações de saldo personalizadas podem entrar em conflito com o armazenamento Enumerable padrão.

Quando a extensão Enumerable é mais útil?

Ela é mais útil quando contratos ou aplicativos precisam de acesso on-chain padronizado à lista atual de tokens ou aos IDs de token de um proprietário.

Conclusão

A extensão Enumerable é um recurso opcional do ERC-721 que permite descobrir IDs de token NFT por meio de consultas on-chain padronizadas.

Seu ID de interface é

.

A extensão adiciona

, e .

Essas funções podem listar a coleção atual e os IDs de token pertencentes a um endereço conhecido.

Os índices de enumeração não são identificadores permanentes, e o padrão não garante sua ordem.

A extensão também não fornece metadados, royalties, listas de titulares, registros históricos ou comprovação de uma oferta fixa.

A manutenção de índices globais e específicos dos proprietários exige gravações adicionais no armazenamento, o que aumenta os custos de gas de emissões, transferências e queimas.

Aplicativos grandes costumam usar eventos Transfer do ERC-721 e indexação off-chain, em vez de pagar pela enumeração on-chain completa.

Os desenvolvedores que implementam a extensão precisam manter sincronizadas todas as estruturas de propriedade, saldo e índice em todos os caminhos que alteram o estado.

Os usuários devem verificar de forma independente o suporte à interface, a identidade do contrato, a autoridade de emissão, as permissões de atualização e a oferta atual.

Entender a extensão Enumerable ajuda os usuários de cripto a distinguir a descoberta direta de NFTs on-chain de metadados, histórico de propriedade, escassez e serviços de indexação off-chain.