Расширение Enumerable

Что такое расширение Enumerable?

Расширение Enumerable — необязательная часть стандарта невзаимозаменяемых токенов ERC-721. Оно позволяет смарт-контрактам и криптоприложениям находить ID NFT-токенов с помощью ончейн-запросов по индексам.

Обычно оно обозначается именем интерфейса

или именем реализации .

В официальной спецификации ERC-721 это расширение описано как способ, с помощью которого контракт может предоставлять полный список действительных NFT и ID токенов, принадлежащих каждому адресу.

Расширение добавляет три функции:

, и .

Эти функции дополняют базовый интерфейс ERC-721 для проверки владения и передачи токенов.

Они не заменяют такие функции, как

, , или .

Расширение Enumerable является необязательным, поэтому NFT-контракт может полностью соответствовать ERC-721, даже если не поддерживает его.

Почему оно называется Enumerable?

Перечисление коллекции означает последовательное определение ее элементов с помощью индекса или другого упорядоченного метода.

Базовый интерфейс ERC-721 позволяет приложению узнать, кому принадлежит токен с известным ID.

Он также позволяет узнать, сколько NFT принадлежит адресу.

Однако базовый интерфейс не предоставляет прямой ончейн-функции для поиска всех существующих ID токенов или всех ID токенов конкретного владельца.

Расширение Enumerable устраняет этот пробел, добавляя индексированный доступ к коллекции в целом и токенам каждого владельца.

Приложение может начать с индекса ноль и продолжать запрашивать следующие индексы, пока не достигнет соответствующего предложения токенов или баланса владельца.

Что такое ID интерфейса расширения Enumerable?

ID интерфейса ERC-165 для расширения ERC-721 Enumerable —

.

Совместимый контракт должен возвращать

, если вызвать его функцию с этим значением.

Стандарт обнаружения интерфейсов ERC-165 позволяет приложениям запрашивать у смарт-контракта, какие интерфейсы он заявляет к реализации.

У базового интерфейса ERC-721 отдельный ID, поэтому приложение может независимо проверить поддержку базового интерфейса и Enumerable.

Контракт, реализующий расширение Enumerable, должен также реализовать базовый интерфейс ERC-721.

Положительный ответ при обнаружении интерфейса повышает уверенность в совместимости, но не доказывает, что реализация корректна, безопасна или добросовестна.

Функции, добавляемые расширением Enumerable

Расширение Enumerable добавляет только три общедоступные функции запросов.

Функция

возвращает количество действительных NFT, которые в данный момент отслеживаются контрактом.

Функция

возвращает ID токена из общего списка токенов контракта.

Функция

возвращает ID токена из списка активов конкретного владельца.

В стандартном интерфейсе все три функции являются доступными только для чтения функциями

.

Расширение не добавляет новые функции передачи, подтверждения, выпуска, сжигания, работы с метаданными или роялти.

Функция totalSupply

Функция

возвращает количество действительных NFT, у которых в данный момент есть владелец, отличный от нулевого адреса.

Она показывает текущее активное предложение, а не максимально возможное предложение.

Например, контракт может сообщать об общем предложении в 8,000 NFT, сохраняя при этом возможность выпускать новые NFT в будущем.

Если NFT сжигают и он перестает быть действительным объектом владения, отображаемое общее предложение обычно уменьшается.

Это означает, что значение

не обязательно равно количеству NFT, когда-либо выпущенных контрактом.

Оно также не доказывает, что у коллекции установлен постоянный лимит предложения.

Чтобы проверить заявления о дефиците, пользователям необходимо изучить логику выпуска и привилегированные права доступа.

Функция tokenByIndex

Функция

возвращает ID токена, находящегося на указанной позиции в общем перечислении токенов контракта.

Индексация начинается с нуля.

Допустимый индекс должен быть меньше значения, возвращаемого функцией

.

Если общее предложение составляет 100, допустимы индексы от нуля до 99.

Запрос с индексом 100 или выше должен завершиться ошибкой.

Возвращаемый ID токена не обязан совпадать с индексом.

Например, индекс ноль может вернуть ID токена 500, а индекс один — ID токена 12.

Приложениям нельзя предполагать, что ID токенов идут по порядку, только потому что индексы перечисления последовательны.

Функция tokenOfOwnerByIndex

Функция

возвращает ID одного токена, принадлежащего указанному адресу.

Индексация начинается с нуля, а индекс должен быть меньше результата функции

для этого владельца.

Если адресу принадлежат три NFT, допустимые индексы владельца — ноль, один и два.

Функция должна завершиться ошибкой, если индекс выходит за пределы текущего баланса владельца.

Она также должна завершиться ошибкой, если в качестве владельца указан нулевой адрес.

Функция позволяет ончейн- и офчейн-приложениям перечислять NFT, принадлежащие адресу, без поиска по всем возможным ID токенов.

Как работают три функции вместе

Приложение может вызвать

, чтобы узнать, сколько действительных NFT существует в данный момент.

Затем оно может вызвать

для каждого индекса от нуля до значения на единицу меньше общего предложения.

Для каждого возвращенного ID токена приложение может вызвать

, чтобы определить его текущего владельца.

Чтобы перечислить активы конкретного адреса, приложение может вызвать

, а затем запросить для каждого допустимого индекса владельца.

Этот процесс позволяет находить токены с помощью стандартизированных ончейн-функций.

Для больших коллекций может по-прежнему потребоваться много RPC-вызовов, поэтому в производственных приложениях часто используют разбиение на страницы, пакетную обработку, кэширование или индексацию событий.

Порядок перечисления не гарантируется

Спецификация ERC-721 не определяет обязательный порядок сортировки для

или .

Возвращаемый порядок не обязан соответствовать ID токена, времени выпуска или передачи, редкости, метаданным либо длительности владения.

Контракт может изменить позицию токена при передаче или сжигании другого токена.

Приложениям нельзя считать индекс перечисления постоянным идентификатором.

В рамках контракта стабильным идентификатором является ID токена, тогда как индекс служит лишь текущей позицией для поиска.

Интерфейс, которому нужны отсортированные результаты, должен сортировать полученные ID токенов офчейн по собственным правилам.

Перечисление с помощью swap-and-pop

В распространенной реализации для эффективного удаления ID токенов из массивов используется метод под названием swap-and-pop.

При удалении токена реализация помещает последний токен на место удаленного элемента в массиве.

Затем она удаляет последнюю запись массива.

Это позволяет не сдвигать все последующие токены и сохранять относительно низкую вычислительную сложность удаления.

Однако порядок оставшихся ID токенов при этом меняется.

В текущей реализации OpenZeppelin ERC721Enumerable этот метод используется как для глобальных индексов, так и для индексов отдельных владельцев.

Поэтому при изменении прав собственности во время длительного перечисления приложению следует начать процесс заново или тщательно сверить результаты пагинации.

Пример перечисления всей коллекции

Предположим, контракт ERC-721 сообщает об общем предложении в четыре токена.

Приложение вызывает

с индексами ноль, один, два и три.

Контракт возвращает ID токенов 18, 42, 7 и 105.

Теперь приложению известен полный набор действительных ID токенов, хотя сами ID не идут по порядку.

Для каждого ID оно может вызвать

и , чтобы отобразить владельца и метаданные.

Если позже токен с ID 42 сожгут, глобальное перечисление может вернуть 18, 105 и 7, поскольку реализация может переместить последний элемент на место удаленного.

Это допустимое изменение: стандарт не гарантирует порядок перечисления.

Пример перечисления токенов владельца

Предположим, Алисе принадлежат токены с ID 9, 30 и 88 в NFT-контракте с поддержкой Enumerable.

Функция контракта

возвращает для адреса Алисы значение три.

Приложение запрашивает индексы владельца ноль, один и два с помощью

.

Контракт возвращает ID трех токенов Алисы.

Затем Алиса передает токен с ID 30 Бобу.

Баланс Алисы уменьшается до двух, а порядок индексов ее оставшихся токенов может измениться.

Перед повторным перечислением токенов владельца приложению следует получить обновленный баланс.

Расширение Enumerable и базовый ERC-721

Базовый стандарт ERC-721 предусматривает владение, передачу, подтверждения, события и проверки безопасного получения.

Он позволяет узнать, существует ли токен с известным ID и кому он принадлежит.

При этом он не предоставляет стандартизированный ончейн-список всех ID токенов.

Расширение Enumerable добавляет механизм поиска таких токенов.

Коллекция без перечисления может по-прежнему нормально передавать NFT и работать с кошельками, совместимыми с ERC-721.

Отсутствие перечисления не делает NFT недействительным или несоответствующим стандарту.

Для широкой совместимости с ERC-721 приложениям необходимо поддерживать как коллекции с перечислением, так и коллекции без него.

Расширение Enumerable и расширение Metadata

Расширение Enumerable позволяет определять существующие ID токенов и токены, принадлежащие конкретным владельцам.

Расширение Metadata предоставляет название и символ коллекции, а также URI токенов.

Перечисление не описывает изображение, атрибуты, название или внешний контент, связанный с NFT.

Поддержка метаданных не предоставляет полный список токенов.

Контракт может реализовать одно или оба расширения либо не реализовывать ни одно из них, сохраняя при этом базовую функциональность ERC-721.

Приложениям следует проверять каждый интерфейс отдельно.

Расширение Enumerable и одна лишь функция totalSupply

Некоторые NFT-контракты добавляют собственную функцию

, не реализуя полное расширение Enumerable.

Знакомое имя функции не доказывает поддержку

или .

Значение пользовательской функции предложения также может отличаться от определения, используемого в перечислении ERC-721.

Она может сообщать количество когда-либо выпущенных токенов, следующий ID токена, максимальный размер коллекции или другое значение, определенное проектом.

Вместо проверки только одного селектора функции приложениям следует использовать ERC-165 для проверки полного интерфейса Enumerable.

Почему расширение Enumerable увеличивает расход газа

Для перечисления контракту необходимо поддерживать дополнительные структуры хранения данных.

В распространенной реализации хранится массив всех существующих ID токенов.

Кроме того, для каждого владельца хранятся индексированный список токенов и отображения их позиций.

При выпуске новый токен нужно добавить и в глобальный список, и в список владельца.

При передаче токен необходимо удалить из списка прежнего владельца и добавить в список нового владельца.

При сжигании токен необходимо удалить как из списка владельца, так и из глобального списка.

Эти дополнительные операции записи в хранилище увеличивают расход газа при транзакциях, меняющих состояние.

В актуальных рекомендациях по реализации ERC-721 отмечается, что расширение часто не используют из-за значительных дополнительных затрат газа.

Бесплатны ли запросы перечисления?

Пользователь может вызывать функции

через RPC-эндпоинт, не отправляя транзакцию в блокчейн.

В этом случае он не платит ончейн-комиссию за газ, поскольку узел локально моделирует выполнение запроса.

Однако узел все равно выполняет вычисления и может применять ограничения частоты запросов или другие ограничения доступа.

Если другой смарт-контракт вызывает функцию перечисления в ходе транзакции, вычисления расходуют газ этой транзакции.

Ончейн-цикл, запрашивающий сотни или тысячи индексов токенов, может оказаться слишком дорогим для выполнения.

Разработчикам не следует путать бесплатное офчейн-чтение с неограниченными ончейн-вычислениями.

Циклы и лимиты газа блока

Смарт-контракту следует избегать функций, меняющих состояние и проходящих циклом по каждому NFT в коллекции или по каждому NFT, принадлежащему адресу с неограниченным числом токенов.

Количество итераций может со временем увеличиться настолько, что транзакция превысит лимит газа блока.

В документации Solidity по безопасности предупреждается, что циклы, зависящие от объема хранимых данных, могут со временем сделать выполнение операций контракта невозможным.

Офчейн-вызовы функций

не создают таких же расходов на транзакцию, но все же могут перегрузить RPC-провайдера.

Для больших наборов данных приложениям следует использовать ограниченные страницы, отдельные запросы по индексам или офчейн-индексацию.

Офчейн-индексация событий как альтернатива

Каждый совместимый с ERC-721 контракт генерирует события

при выпуске, передаче или сжигании NFT.

Офчейн-индексатор может обрабатывать эти события начиная с блока развертывания контракта и восстанавливать текущую информацию о владении.

Выпуск обычно представлен передачей с нулевого адреса.

Сжигание обычно представлено передачей на нулевой адрес.

При обычной передаче право собственности переходит между двумя ненулевыми адресами.

Индексация событий избавляет от дополнительных операций записи в хранилище, необходимых для ончейн-перечисления.

Она также эффективнее поддерживает поиск, сортировку, фильтрацию и пагинацию в больших коллекциях.

Компромисс заключается в том, что пользователям необходимо доверять системе индексации или самостоятельно ее обслуживать, а также следить за ее синхронизацией.

Расширение Enumerable и индексация событий

Ончейн-перечисление предоставляет смарт-контрактам прямой стандартизированный доступ к индексам токенов.

Индексация событий обеспечивает более широкие и масштабируемые возможности поиска офчейн.

Перечисление полезно, когда другому смарт-контракту необходимо проверять или выбирать ID токенов, не полагаясь на внешнюю базу данных.

Индексация событий обычно практичнее для интерфейсов кошельков, страниц коллекций, аналитики и исторического поиска.

Проект может поддерживать оба метода.

Оптимальный выбор зависит от того, оправдывает ли возможность ончейн-поиска дополнительные расходы на газ при каждом выпуске, передаче и сжигании.

Поддерживает ли перечисление пагинацию?

Расширение не определяет функцию, которая возвращала бы страницу с ID токенов.

Оно возвращает один ID токена для каждого запроса по индексу.

Офчейн-приложение может реализовать пагинацию, запрашивая ограниченный диапазон индексов.

Например, на первой странице можно запрашивать индексы от нуля до 49, а на второй — от 50 до 99.

При переходе между страницами приложение должно учитывать изменения предложения и порядка токенов.

Передача или сжигание токена может изменить позиции токенов, из-за чего длительный процесс пагинации пропустит или повторно вернет один из ID.

Если RPC-система поддерживает исторические вызовы, для получения более согласованного снимка можно использовать данные с одной фиксированной высоты блока.

Показывает ли перечисление всех владельцев?

Расширение перечисляет ID токенов глобально и ID токенов, принадлежащих известному владельцу.

Оно не предоставляет функцию, возвращающую все уникальные адреса владельцев.

Приложение может получить список владельцев, вызывая

для каждого ID токена или обрабатывая события передачи.

Один и тот же владелец может встречаться несколько раз, поскольку одному адресу могут принадлежать несколько NFT.

Поэтому создание списка уникальных держателей обычно относится к задачам офчейн-индексации.

Доказывает ли перечисление подлинность токенов?

Нет. Перечисление лишь сообщает ID токенов, отслеживаемых конкретным смарт-контрактом.

Любой может развернуть контракт ERC-721 с поддержкой Enumerable и скопировать названия, изображения, символы или метаданные.

Блокчейн-сеть и полный адрес контракта остаются важными составляющими идентификатора NFT.

Корректная реализация интерфейса Enumerable не доказывает, что эмитент владеет произведением искусства, контролирует заявленный актив или действует добросовестно.

Пользователям следует проверять контракт по авторитетной информации проекта и самостоятельно изучать его разрешения.

Доказывает ли totalSupply дефицит?

Текущее количество токенов не устанавливает постоянное максимальное предложение.

В контракте может быть публичная функция выпуска, роль администратора с правом выпуска, механизм выпуска через мост или право обновления контракта.

Токен, у которого сейчас нет владельца, также может быть выпущен позднее.

Правила предложения в обновляемых контрактах могут измениться после развертывания.

Прежде чем полагаться на заявление о дефиците, пользователям следует изучить код и модель контроля доступа.

Перечисление упрощает запрос текущего предложения, но не обеспечивает соблюдение экономических обещаний.

Выпуск токенов и перечисление

При выпуске нового NFT реализация с поддержкой Enumerable должна добавить его ID в глобальный индекс и индекс первого владельца.

После этого общее предложение увеличивается на единицу.

ID токена может находиться на любой допустимой глобальной позиции, предусмотренной реализацией.

Последовательный выпуск не означает, что индекс перечисления должен оставаться равным ID токена.

Пользовательская логика выпуска должна согласованно обновлять все необходимые структуры перечисления.

Неполное обновление может привести к расхождениям между балансами, записями о владельцах, общим предложением и результатами перечисления.

Передача токенов и перечисление

Передача обычно не меняет общее предложение.

ID токена удаляется из перечисления прежнего владельца и добавляется в перечисление получателя.

Обычно тот же ID токена остается в глобальном списке.

В процессе удаления позиции индексов конкретного владельца могут измениться.

Самопередачи требуют тщательной реализации, поскольку отправитель и получатель — один и тот же адрес.

Проверенные реализации обрабатывают такие случаи, не удаляя и не дублируя токен ошибочно.

Сжигание токенов и перечисление

Сжигание прекращает действительное владение токеном по ERC-721.

Реализация с поддержкой Enumerable удаляет ID сожженного токена из списка владельца и глобального списка токенов.

Общее предложение уменьшается.

Старые глобальный индекс и индекс владельца для этого токена больше не следует использовать.

При удалении методом swap-and-pop другие токены могут переместиться на эти позиции.

Для получения истории сожженных NFT историческим приложениям следует использовать события, а не текущее перечисление.

Совместимость с пакетным выпуском

Некоторые реализации ERC-721 поддерживают сжатый или последовательный пакетный выпуск при создании контракта.

Такие системы могут рассчитывать владение, не регистрируя каждый токен через обычную логику обновления перечисления.

В текущей реализации OpenZeppelin содержится предупреждение, что расширение последовательного выпуска конфликтует с

и их не следует использовать вместе.

Текущая реализация Enumerable также отклоняет неподдерживаемый путь пакетного обновления баланса.

Разработчикам не следует объединять расширения лишь потому, что каждое из них работает отдельно.

Необходимо совместно проверять наследование, хранилище, события, баланс и поведение хуков обновления.

Перечисление и обновляемые контракты

Если это допускает система управления, логику обновляемого NFT-контракта можно изменять после развертывания.

Добавление перечисления после того, как уже выпущено много NFT, требует особого внимания.

Новое хранилище для перечисления может быть пустым, хотя базовый контракт уже отслеживает тысячи токенов.

Для заполнения глобальных индексов и индексов владельцев может потребоваться миграция.

Большие ончейн-циклы миграции могут превысить лимиты газа.

Ошибки в расположении данных в хранилище также могут повредить существующие сведения о владении или подтверждения.

Администраторам обновления следует использовать протестированные процедуры миграции и ограниченные по объему транзакции, а также проводить независимый аудит безопасности.

Перечисление и пользовательская логика balanceOf

Перечисление токенов владельца зависит от точных данных ERC-721 о балансе.

Расширение, которое рассчитывает

с помощью пользовательского или сжатого метода, может конфликтовать с сохраненными индексами владельцев.

В актуальных рекомендациях по реализации отдельно предупреждается, что расширения с пользовательской логикой баланса могут быть несовместимы с перечислением.

Разработчики должны убедиться, что при каждом выпуске, передаче и сжигании совместимые пути кода обновляют счетчики владения и индексы.

Контракт, который сообщает о пяти токенах у владельца, но хранит только четыре индексированных ID, внутренне противоречив.

Риски безопасности для интегрирующих приложений

Перед вызовом функций расширения приложению следует проверить поддержку Enumerable.

Приложение должно обрабатывать ошибки выхода за границы индекса и не предполагать, что ранее проверенный индекс остается допустимым.

Нельзя использовать порядок перечисления для определения редкости, приоритетов или финансовых показателей.

Если состояние меняется во время пагинации, необходимо предотвращать появление повторов или пропусков в результатах.

Кроме того, следует проверять, что каждый возвращенный ID токена относится к ожидаемому контракту и сети.

Для принятия важных решений могут потребоваться согласованный снимок состояния на определенном блоке и подходящий уровень финальности.

RPC и согласованность данных

В зависимости от сети и параметров запроса RPC-эндпоинт может возвращать данные перечисления из недавнего, безопасного, финализированного или исторического блока.

Два вызова на разных высотах блоков могут возвращать разное общее предложение или разные списки токенов владельца.

Недавно переданный NFT может отображаться у разных владельцев в несинхронизированных источниках данных.

Если важна согласованность, при множественных запросах перечисления приложению следует записывать номер использованного блока.

Критически важные системы могут сверять данные нескольких узлов или использовать независимо проверенный узел.

Перечисление избавляет от зависимости от API конкретной коллекции, но не устраняет все риски, связанные с доверием к RPC.

Преимущества расширения Enumerable

Расширение предоставляет стандартизированный способ находить все текущие ID токенов.

Оно позволяет другому смарт-контракту запрашивать принадлежащие владельцу NFT без внешнего индексатора.

Оно предоставляет стандартную функцию для запроса текущего предложения.

Расширение может упростить работу с небольшими коллекциями, ончейн-играми, системами членства и приложениями, которым нужно напрямую выбирать токены.

Оно также позволяет выполнять базовые запросы об инвентаре NFT, даже если сайт проекта или его закрытая база данных перестанут работать.

Ограничения расширения Enumerable

Расширение увеличивает расходы газа при выпуске, передаче и сжигании токенов.

Оно не гарантирует неизменность порядка токенов.

В нем нет встроенных функций пагинации, сортировки, фильтрации или перечисления держателей.

Оно показывает текущие токены, а не полную историю.

Оно может быть несовместимо с сжатым пакетным выпуском или пользовательскими системами расчета баланса.

Большие ончейн-циклы по-прежнему ограничены газом транзакции.

Кроме того, расширение не предоставляет метаданные, роялти, цены, подтверждение подлинности или гарантии лимита предложения.

Когда проекту следует использовать перечисление?

Перечисление может быть полезно, если смарт-контрактам необходимо напрямую находить ID токенов ончейн.

Оно также может подойти для небольшой коллекции, если дополнительные расходы на передачу приемлемы.

Игра может использовать его, если логике контракта нужно выбирать NFT игрока по индексу.

Контракт системы членства может применять его, если ончейн-процессу необходимо проверять текущие токены членства пользователя.

Тем не менее проекту следует ограничивать циклы и оценить, не будет ли эффективнее использовать более простое отображение или специальный индекс приложения.

Когда проекту стоит отказаться от перечисления?

Большая NFT-коллекция может отказаться от перечисления, чтобы снизить расходы на каждый выпуск, передачу и сжигание.

Проект может не использовать его и в том случае, если все функции поиска и обнаружения токенов уже зависят от офчейн-индексатора событий.

Системы сжатого пакетного выпуска могут использовать модели владения, несовместимые с эффективной работой стандартного хранилища перечисления.

Если проекту никогда не понадобится ончейн-перечисление токенов, он может не получить существенной выгоды от постоянных затрат на ончейн-индексы.

Решение следует принимать исходя из реальных требований приложения, а не из предположения, что необходимо каждое необязательное расширение.

Как разработчикам реализовать расширение

Разработчикам следует начать с активно поддерживаемой и проверенной реализации ERC-721 Enumerable.

Необходимо убедиться, что функция

возвращает .

Все пути выпуска, передачи и сжигания должны корректно обновлять глобальное перечисление и перечисление владельцев.

Следует проверять пользовательские расширения на конфликты с владением, балансами, пакетным выпуском, обертками токенов, приостановкой и обновлениями.

Тесты должны охватывать первый и последний индексы, индексы за границами допустимого диапазона, самопередачи, сжигание, повторный выпуск, если он разрешен, и многократную смену владельца.

Инвариантные тесты должны подтверждать, что

равен числу глобально перечисляемых токенов.

Они также должны проверять, что количество перечисляемых токенов каждого владельца равно значению

.

Как пользователям проверить поддержку Enumerable

Сначала необходимо проверить адрес NFT-контракта и блокчейн-сеть.

Затем вызвать

со значением .

После этого убедиться, что поддерживается также базовый интерфейс ERC-721.

Затем сравнить значение

с небольшой выборкой допустимых индексов.

Наконец, сравнить результат

для владельца с ID токенов, возвращаемыми перечислением его токенов.

Такие проверки могут выявить очевидные несоответствия, но не заменяют полноценный аудит контракта.

Распространенные ошибки при работе с расширением Enumerable

Частая ошибка — предполагать, что каждый контракт ERC-721 поддерживает перечисление.

Другая ошибка — считать индекс перечисления постоянным ID токена.

Третья ошибка — предполагать, что ID токенов идут по возрастанию или в порядке выпуска.

Четвертая ошибка — считать

постоянным лимитом предложения.

Пятая ошибка — запускать цикл по неограниченной коллекции внутри транзакции, меняющей состояние.

Шестая ошибка — не учитывать изменение порядка при пагинации.

Седьмая ошибка — полагать, что пользовательская функция

доказывает поддержку расширения целиком.

Восьмая ошибка — объединять несовместимые реализации пакетного выпуска и перечисления.

Девятая ошибка — добавлять перечисление в обновляемую коллекцию, не перенося ранее выпущенные токены.

Десятая ошибка — считать поддержку интерфейса Enumerable доказательством подлинности или ценности NFT-коллекции.

Часто задаваемые вопросы

Что означает расширение Enumerable в криптовалютах?

Обычно так называют необязательное расширение ERC-721, которое позволяет приложениям перечислять все текущие ID NFT-токенов и ID токенов, принадлежащих указанному адресу.

Обязательно ли расширение Enumerable для ERC-721?

Нет. NFT-контракт может соответствовать базовому ERC-721, не поддерживая перечисление.

Какой ID интерфейса у расширения Enumerable?

ID интерфейса ERC-165 —

.

Какие функции добавляет расширение?

Оно добавляет

, и .

Что возвращает totalSupply?

Количество действительных NFT, которые контракт отслеживает в данный момент.

Показывает ли totalSupply максимально возможное предложение?

Нет. Функция сообщает о текущем предложении и не доказывает, что будущий выпуск невозможен.

Что возвращает tokenByIndex?

ID токена, находящегося на указанном глобальном индексе перечисления.

Что возвращает tokenOfOwnerByIndex?

ID одного токена, принадлежащего указанному адресу и находящегося на заданном индексе владельца.

Индексация перечисления начинается с нуля?

Да. Допустимые индексы начинаются с нуля и заканчиваются на единицу меньше соответствующего предложения или баланса.

Индекс перечисления — это то же самое, что ID токена?

Нет. Индекс — временная позиция в списке, а ID токена идентифицирует NFT в рамках контракта.

Возвращаются ли ID токенов в числовом порядке?

Нет. Стандарт не устанавливает обязательный порядок перечисления.

Может ли порядок перечисления измениться?

Да. Передачи и сжигания могут изменить позиции индексов, особенно в реализациях, использующих удаление методом swap-and-pop.

Уменьшает ли сжигание NFT значение totalSupply?

Да. Корректно реализованный контракт Enumerable удаляет сожженный NFT и уменьшает текущее общее предложение.

Меняет ли передача NFT значение totalSupply?

Нет. Обычная передача меняет перечисление токенов владельцев, но не количество существующих NFT.

Почему расширение дорого обходится?

Для поддержания глобальных индексов и индексов владельцев при выпуске, передаче и сжигании требуются дополнительные операции записи в хранилище.

Бесплатны ли запросы перечисления?

Офчейн-запросы через RPC не требуют оплаты ончейн-газа, но вызовы смарт-контрактов в ходе транзакции расходуют газ.

Может ли контракт пройти циклом по всем перечисляемым NFT?

Он может попытаться это сделать, однако неограниченный ончейн-цикл со временем может превысить лимит газа блока.

Предусматривает ли расширение пагинацию?

Нет. Приложения реализуют пагинацию, запрашивая выбранные диапазоны индексов.

Перечисляет ли расширение всех держателей NFT?

Нет. Оно перечисляет ID токенов глобально и для известного владельца, но не возвращает уникальный список всех адресов владельцев.

Может ли индексация событий заменить перечисление?

Да. Офчейн-индексатор может восстановить предложение токенов и информацию о владении по событиям ERC-721

.

Включает ли перечисление метаданные NFT?

Нет. Метаданные предоставляются отдельным необязательным расширением ERC-721.

Доказывает ли перечисление подлинность NFT?

Нет. Любой может развернуть контракт с поддержкой Enumerable, поэтому пользователям необходимо проверить сеть, адрес контракта, эмитента и разрешения.

Можно ли добавить перечисление после развертывания?

В обновляемый контракт его можно добавить, но существующие токены необходимо безопасно перенести в новые структуры индексов.

Совместим ли ERC721Enumerable со всеми расширениями ERC-721?

Нет. Сжатый пакетный выпуск и пользовательские реализации баланса могут конфликтовать со стандартным хранилищем перечисления.

Когда расширение Enumerable особенно полезно?

Оно особенно полезно, когда контрактам или приложениям нужен стандартизированный ончейн-доступ к текущему списку токенов или ID токенов владельца.

Заключение

Расширение Enumerable — необязательная функция ERC-721, которая позволяет находить ID NFT-токенов с помощью стандартизированных ончейн-запросов.

ID его интерфейса —

.

Расширение добавляет функции

, и .

С их помощью можно перечислить текущую коллекцию и ID токенов, принадлежащих известному адресу.

Индексы перечисления не являются постоянными идентификаторами, а стандарт не гарантирует их порядок.

Расширение также не предоставляет метаданные, роялти, списки владельцев, историю или подтверждение фиксированного предложения.

Поддержание глобальных индексов и индексов владельцев требует дополнительных операций записи в хранилище, что увеличивает расход газа при выпуске, передаче и сжигании.

Вместо оплаты полного ончейн-перечисления крупные приложения часто используют события ERC-721

и офчейн-индексацию.

Разработчики, реализующие расширение, должны синхронизировать все структуры владения, балансов и индексов во всех путях изменения состояния.

Пользователям следует самостоятельно проверять поддержку интерфейса, идентичность контракта, права на выпуск, разрешения на обновление и текущее предложение.

Понимание расширения Enumerable помогает пользователям криптовалют отличать прямой ончейн-поиск NFT от метаданных, истории владения, дефицита и офчейн-сервисов индексации.