Enumerable 扩展

什么是 Enumerable 扩展？

Enumerable 扩展是 ERC-721 非同质化代币标准的可选部分，允许智能合约和加密应用通过链上索引查询发现 NFT 代币 ID。

它通常以接口名称

或实现名称 标识。

官方ERC-721 规范将该扩展定义为一种方式，使合约能够公开其所有有效 NFT 的完整列表，以及每个地址持有的代币 ID。

该扩展新增了 3 个函数：

、 和 。

这些函数补充了 ERC-721 核心所有权与转账接口。

它们不会取代

、、 或 等函数。

Enumerable 扩展是可选的，因此 NFT 合约即使不支持该扩展，也可以完全符合 ERC-721 标准。

为什么称为 Enumerable？

枚举一个集合，意味着通过索引或其他有序方式逐一识别其中的成员。

ERC-721 核心接口可以告知应用某个已知代币 ID 的所有者。

它还可以告知应用某个地址持有多少枚 NFT。

不过，核心接口没有提供直接的链上函数，用于发现所有现存代币 ID，或某个特定所有者持有的全部代币 ID。

Enumerable 扩展通过为全局集合和每位所有者的持仓提供索引访问，弥补了这一不足。

应用可以从索引 0 开始，持续查询更高的索引，直到达到相关供应量或所有者余额。

什么是 Enumerable 扩展接口 ID？

ERC-721 Enumerable 扩展的 ERC-165 接口 ID 为

。

兼容合约在其

函数接收到此值时，应返回 。

ERC-165 接口检测标准允许应用查询智能合约声称实现了哪些接口。

ERC-721 核心接口有独立的接口 ID，因此应用可以分别检测核心接口和 Enumerable 扩展是否受支持。

实现 Enumerable 扩展的合约也必须实现 ERC-721 核心接口。

接口检测返回肯定结果有助于检查兼容性，但不能证明实现正确、安全或可信。

Enumerable 扩展新增的函数

Enumerable 扩展仅新增 3 个公开查询函数。

函数返回合约当前追踪的有效 NFT 数量。

函数返回合约全局代币列表中的一个代币 ID。

函数返回某位所有者当前持仓中的一个代币 ID。

在标准接口中，这 3 个函数都是只读的 view 函数。

该扩展不会新增转账、授权、铸造、销毁、元数据或版税函数。

totalSupply 函数

函数返回当前所有者不是零地址的有效 NFT 数量。

它报告当前有效供应量，而不是可能达到的最大供应量。

例如，某合约可能报告总供应量为 8,000，同时仍保留日后继续铸造 NFT 的权限。

如果 NFT 被销毁并从有效所有权记录中移除，报告的总供应量通常会减少。

这意味着

不一定等于曾经铸造过的 NFT 总数。

它也不能证明该系列有永久供应上限。

用户必须检查铸造逻辑和特权权限，才能核实有关稀缺性的说法。

tokenByIndex 函数

函数返回合约全局枚举中指定位置对应的代币 ID。

索引从 0 开始。

有效索引必须小于

返回的值。

如果总供应量为 100，有效索引为 0 到 99。

使用索引 100 或更大的值进行查询会失败。

返回的代币 ID 不必与索引相同。

例如，索引 0 可能返回代币 ID 500，而索引 1 可能返回代币 ID 12。

应用绝不能仅因枚举索引连续，就假设代币 ID 也是连续的。

tokenOfOwnerByIndex 函数

函数返回指定地址拥有的一个代币 ID。

索引从 0 开始，且必须小于该所有者的

返回值。

如果某地址拥有 3 枚 NFT，其有效所有者索引为 0、1 和 2。

索引超出所有者当前余额时，函数必须失败。

如果提供的所有者是零地址，函数也必须失败。

该函数使链上和链下应用无需搜索所有可能的代币 ID，即可列出某地址的 NFT。

三个函数如何协同工作

应用可以调用

，了解当前存在多少枚有效 NFT。

随后，它可以针对从 0 到供应量减 1 的每个索引，分别调用一次

。

对于每个返回的代币 ID，应用都可以调用

，识别当前所有者。

若要列出某个地址持有的 NFT，应用可以调用

，然后针对每个有效所有者索引查询 。

这一流程通过标准化链上函数实现了代币发现。

大型集合仍可能需要大量 RPC 调用，因此生产环境中的应用通常会使用分页、批处理、缓存或事件索引。

枚举顺序没有保证

ERC-721 规范没有规定

或 必须采用何种排序方式。

返回顺序不必遵循代币 ID、铸造时间、转账时间、稀有度、元数据或持有时长。

当其他代币被转移或销毁时，合约可以改变某个代币的位置。

应用不得将枚举索引视为永久标识符。

在合约内，代币 ID 是稳定标识符；索引则只是当前的查询位置。

如果界面需要排序结果，应根据自身规则在链下对返回的代币 ID 排序。

Swap-and-Pop 枚举

一种常见实现使用名为 swap and pop 的技术，从数组中高效移除代币 ID。

移除代币时，实现会将数组中最后一个代币移到被移除代币原先所在的位置。

随后删除数组最后一项。

这样无需移动后续所有代币，移除操作的复杂度也相对较低。

不过，这会改变其余代币 ID 的顺序。

当前的 OpenZeppelin ERC721Enumerable 实现在全局索引和所有者专属索引中都使用了这种方法。

因此，如果在长时间枚举过程中所有权发生变化，应用应重新开始分页，或仔细核对分页结果。

全系列枚举示例

假设某 ERC-721 合约报告的总供应量为 4。

应用分别使用索引 0、1、2 和 3 调用

。

合约返回代币 ID 18、42、7 和 105。

尽管这些 ID 并不连续，应用现在仍已获知所有有效代币 ID。

应用可以对每个 ID 调用

和 ，以显示所有权和元数据。

如果代币 ID 42 随后被销毁，全局枚举可能返回 18、105 和 7，因为实现可以将最后一项移到被移除项的位置。

这种变化符合规范，因为标准不保证枚举顺序。

所有者枚举示例

假设 Alice 在一个支持枚举的 NFT 合约中拥有代币 ID 9、30 和 88。

合约的

函数返回 Alice 地址的余额为 3。

应用通过

查询所有者索引 0、1 和 2。

合约返回 Alice 的 3 个代币 ID。

随后，Alice 将代币 ID 30 转给 Bob。

Alice 的余额降至 2，剩余代币 ID 的索引顺序也可能发生变化。

应用应先读取更新后的余额，再重新执行所有者枚举。

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 扩展会消耗更多 Gas

枚举要求合约维护额外的存储结构。

常见实现会存储一个包含所有现存代币 ID 的数组。

它还会存储每位所有者的索引代币列表，以及记录代币位置的映射。

铸造时，必须将新代币同时添加到全局列表和所有者列表中。

转账时，必须从前一所有者的列表中移除该代币，并将其添加到新所有者的列表中。

销毁时，必须从所有者列表和全局列表中移除该代币。

这些额外的存储写入会增加改变状态的交易所需 Gas。

当前的 ERC-721 实现指南指出，由于该扩展会造成显著的 Gas 开销，通常会选择不实现它。

枚举查询免费吗？

用户可以通过 RPC 端点调用 view 函数，而无需提交区块链交易。

在这种情况下，节点会在本地模拟读取，因此无需支付链上 Gas 费。

不过，节点仍需执行计算，并可能设置速率限制或请求限制。

如果另一个智能合约在交易过程中调用枚举函数，相关计算会消耗交易 Gas。

在链上循环查询数百或数千个代币索引，可能会变得过于昂贵，导致操作无法完成。

开发者不应将链下免 Gas 读取误认为链上计算不受限制。

循环与区块 Gas 限制

智能合约应避免在改变状态的函数中，遍历集合中的每一枚 NFT，或遍历不受限制地址持有的每一枚 NFT。

随着时间推移，迭代次数可能不断增加，最终导致交易超出区块 Gas 限制。

Solidity 安全文档警告称，依赖存储的循环最终可能使合约操作无法完成。

链下调用的 view 函数不会产生同样的交易费用，但仍可能使 RPC 服务提供商过载。

对于大型数据集，应用应使用有界分页、单独的索引查询或链下索引。

链下事件索引作为替代方案

每个符合 ERC-721 标准的合约都会在 NFT 铸造、转移或销毁时发出

事件。

链下索引器可以从合约部署区块开始处理这些事件，重建当前所有权。

铸造通常表示为从零地址转出。

销毁通常表示为转入零地址。

普通转账则是在两个非零地址之间转移所有权。

事件索引无需链上枚举所需的额外存储写入。

对于大型系列，它还可以更高效地支持搜索、排序、筛选和分页。

代价是用户必须信任索引系统或自行运行该系统，并确保它持续保持同步。

Enumerable 扩展与事件索引

链上枚举让智能合约能够通过标准化方式直接访问代币索引。

事件索引则提供更丰富、可扩展性更强的链下发现功能。

如果另一个智能合约必须在不依赖外部数据库的情况下验证或选择代币 ID，枚举会很有用。

对于钱包界面、系列页面、数据分析和历史搜索，事件索引通常更实用。

项目可以同时支持这两种方式。

应根据链上可发现性是否值得承担每次铸造、转账和销毁产生的额外 Gas 费用来决定采用哪种方式。

枚举功能支持分页吗？

该扩展没有定义返回一页代币 ID 的函数。

每次索引查询只返回一个代币 ID。

链下应用可以通过请求有限范围的索引来实现分页。

例如，第一页可以查询索引 0 到 49，第二页查询索引 50 到 99。

应用必须考虑分页过程中供应量和顺序的变化。

转账或销毁可能导致代币在索引之间移动，使耗时较长的分页过程遗漏或重复某个 ID。

如果 RPC 系统支持历史区块调用，使用同一固定区块高度的数据可以获得更一致的快照。

枚举功能会列出所有所有者吗？

该扩展会列出全局代币 ID，以及已知所有者持有的代币 ID。

它不提供返回所有唯一所有者地址的函数。

应用可以针对每个代币 ID 调用

，或处理转账事件，以推导所有者。

由于一个地址可以持有多枚 NFT，同一所有者可能会多次出现。

因此，构建唯一持有者列表通常属于链下索引任务。

枚举功能能证明代币真实性吗？

不能。枚举只会报告某个特定智能合约追踪的代币 ID。

任何人都可以部署一个使用复制名称、图像、符号或元数据的可枚举 ERC-721 合约。

区块链网络和完整合约地址仍是 NFT 身份的重要组成部分。

枚举接口正确，并不能证明发行方拥有相关作品、控制所声称的资产，或怀有诚信意图。

用户应通过权威项目信息核实合约，并独立检查其权限。

totalSupply 能证明稀缺性吗？

当前供应量并不能确定永久最大供应量。

合约可能包含公开铸造函数、管理员铸造角色、跨链桥铸造系统或升级权限。

当前没有所有者的代币 ID 也可能在以后被铸造。

可升级合约可以在部署后修改供应规则。

用户在依赖稀缺性声明前，应检查代码和访问控制模型。

枚举让当前供应量更容易查询，但不会强制执行经济承诺。

铸造与枚举

铸造新的 NFT 时，可枚举实现必须将代币 ID 添加到全局索引和首位所有者的索引中。

随后，总供应量增加 1。

根据实现方式，代币 ID 可以出现在任意有效的全局索引位置。

即使采用连续铸造策略，也不意味着枚举索引必须始终等于代币 ID。

自定义铸造逻辑必须一致地更新所有必需的枚举结构。

更新不完整可能导致余额、所有权记录、总供应量和枚举结果彼此不一致。

转账与枚举

转账通常不会改变总供应量。

它会从前一所有者的枚举中移除代币 ID，并将其添加到接收者的枚举中。

全局代币列表通常仍会包含同一个代币 ID。

移除过程中，所有者专属索引位置可能发生变化。

由于发送者和接收者是同一地址，自转账需要谨慎实现。

经过审查的实现会妥善处理这种情况，避免错误移除或重复添加代币。

销毁与枚举

销毁会将代币从有效 ERC-721 所有权中移除。

可枚举实现会从所有者列表和全局代币列表中移除被销毁的代币 ID。

总供应量随之减少。

此后不应再使用该代币原先的全局索引和所有者索引。

其他代币可能通过 swap-and-pop 移除方式移动到这些位置。

如果历史应用需要记录被销毁的 NFT，应使用事件，而不是当前枚举结果。

批量铸造兼容性

部分 ERC-721 实现支持在合约构造期间压缩或连续批量铸造。

这类系统可能通过计算所有权来实现功能，而不通过常规枚举更新逻辑逐一记录每个代币。

当前 OpenZeppelin 实现警告称，其连续铸造扩展与

冲突，不应同时使用。

当前 Enumerable 实现也会拒绝不受支持的批量余额更新路径。

开发者不应仅因多个扩展各自可以独立运行，就将它们组合使用。

必须综合审查继承关系、存储、事件、余额和更新钩子的行为。

枚举与可升级合约

如果治理系统允许，可升级 NFT 合约能在部署后添加或修改逻辑。

在已有大量 NFT 后添加枚举功能，需要特别谨慎。

新的枚举存储可能从空状态开始，而核心合约已追踪数千枚代币。

可能需要通过迁移流程填充全局索引和所有者专属索引。

大型链上迁移循环可能超出 Gas 限制。

存储布局错误还可能破坏现有所有权或授权数据。

升级管理员应采用经过测试的迁移流程、分批交易和独立安全审查。

枚举与自定义 balanceOf 逻辑

所有者枚举依赖准确的 ERC-721 余额信息。

通过自定义或压缩方法计算

的扩展，可能与存储的所有者索引冲突。

当前实现指南特别警告，采用自定义余额逻辑的扩展可能与枚举不兼容。

开发者必须确认每次铸造、转账和销毁都会通过兼容的代码路径更新所有权数量和索引。

如果合约报告某所有者的余额为 5，但只存储了 4 个索引代币 ID，则合约内部存在不一致。

集成应用的安全风险

应用在调用扩展函数前，应验证合约是否支持枚举。

应用应妥善处理索引越界错误，而不是假设此前观察到的索引仍然有效。

应用不得将枚举顺序用于稀有度、优先级或财务计算。

如果分页期间状态发生变化，应用应防止结果重复或遗漏。

应用还应验证每个返回的代币 ID 都属于预期的合约和网络。

对于高价值决策，应用可能需要一致的区块快照和适当的最终性级别。

RPC 与数据一致性

根据网络和请求配置，RPC 端点返回的枚举数据可能来自最近区块、安全区块、已最终确认区块或历史区块。

在不同区块高度发出的两次调用，可能返回不同的供应量或所有者列表。

如果数据源之间尚未同步，最近转移的 NFT 可能显示为属于不同所有者。

只要一致性很重要，应用在进行多次枚举调用时就应记录所用的区块号。

关键系统可以比较多个节点，或运行经过独立验证的节点。

枚举消除了对系列专属 API 的依赖，但并未消除所有 RPC 信任问题。

Enumerable 扩展的优点

该扩展提供了一种标准化方式，用于发现当前所有代币 ID。

它允许另一个智能合约在不依赖外部索引器的情况下查询某个所有者的 NFT 持仓。

它提供标准的当前供应量函数。

对于小型系列、链上游戏、会员系统以及需要直接选择代币的应用，它可以简化开发。

即使项目网站或私有数据库消失，它也能让用户查询基本 NFT 持仓信息。

Enumerable 扩展的局限

该扩展会增加铸造、转账和销毁的 Gas 成本。

它不保证代币顺序稳定。

它不内置分页、排序、筛选或持有者枚举功能。

它报告的是当前代币，而不是完整的历史记录。

它可能与压缩批量铸造或自定义余额系统不兼容。

大型链上循环仍受交易 Gas 限制。

它也不提供元数据、版税、定价、真实性或供应上限保证。

项目何时应使用枚举？

如果智能合约必须直接在链上发现代币 ID，项目可能会受益于枚举功能。

对于可以接受额外转账成本的小型系列，使用枚举也可能合理。

如果合约逻辑必须按索引选择玩家持有的一枚 NFT，游戏可能会使用该功能。

如果链上流程需要检查持有者当前持有的会员代币，会员合约也可能会使用该功能。

项目仍应限制循环范围，并考虑使用更简单的映射或特定于应用的索引是否更高效。

项目何时可能避免使用枚举？

大型 NFT 系列可能会避免使用枚举，以降低每次铸造、转账和销毁的成本。

如果所有发现和搜索功能都依赖链下事件索引器，项目也可能选择不使用枚举。

压缩批量铸造系统可能采用与标准枚举存储无法高效配合的所有权模型。

如果项目从不需要在链上列出代币，那么为永久链上索引付费带来的收益可能很有限。

应根据实际应用需求做出决定，而不是假设每个可选扩展都不可或缺。

开发者应如何实现该扩展

开发者应从积极维护且经过审查的 ERC-721 Enumerable 实现开始。

他们应确保

返回 。

每条铸造、转账和销毁路径都必须正确更新全局枚举和所有者专属枚举。

必须检查自定义扩展是否与所有权、余额、批量铸造、封装、暂停和升级功能冲突。

测试应涵盖第一个和最后一个索引、越界索引、自转账、销毁、允许情况下的重新铸造，以及重复的所有权变更。

不变量测试应验证

等于全局可枚举代币的数量。

还应验证每位所有者的可枚举代币数量等于

。

用户如何检查是否支持 Enumerable

第一步是核实 NFT 合约地址和区块链网络。

第二步是使用

调用 。

第三步是确认合约也支持 ERC-721 核心接口。

第四步是将

与少量有效索引的查询结果进行比较。

第五步是将某所有者的

结果与所有者枚举返回的代币 ID 数量进行比较。

这些检查可以发现明显的不一致，但不能代替完整的合约审查。

Enumerable 扩展的常见错误

一个常见错误是假设每个 ERC-721 合约都支持枚举。

另一个错误是将枚举索引视为永久代币 ID。

第三个错误是假设代币 ID 会按数值或铸造顺序排列。

第四个错误是将

视为永久供应上限。

第五个错误是在改变状态的交易中遍历不受限制的整个系列。

第六个错误是分页时忽略顺序变化。

第七个错误是假设自定义的

函数足以证明合约支持完整扩展。

第八个错误是将不兼容的批量铸造实现与枚举实现组合使用。

第九个错误是在可升级系列中添加枚举功能，却未迁移此前的代币。

第十个错误是将支持可枚举接口视为 NFT 系列真实或有价值的证明。

常见问题

加密领域中的 Enumerable 扩展是什么意思？

它通常指可选的 ERC-721 扩展，允许应用列出当前所有 NFT 代币 ID，以及指定地址拥有的代币 ID。

ERC-721 是否必须实现 Enumerable 扩展？

不需要。NFT 合约可以符合 ERC-721 核心标准，但不支持枚举。

Enumerable 扩展的接口 ID 是什么？

ERC-165 接口 ID 为

。

该扩展新增了哪些函数？

它新增

、 和 。

totalSupply 返回什么？

它返回合约当前追踪的有效 NFT 数量。

totalSupply 显示的是可能达到的最大供应量吗？

不是。它报告当前供应量，不能证明未来无法继续铸造。

tokenByIndex 返回什么？

它返回指定全局枚举索引处存储的代币 ID。

tokenOfOwnerByIndex 返回什么？

它返回指定地址在指定所有者索引处拥有的一个代币 ID。

枚举索引从 0 开始吗？

是。有效索引从 0 开始，到相关供应量或余额之前一个位置结束。

枚举索引等同于代币 ID 吗？

不等同。索引是临时的列表位置，而代币 ID 是合约内 NFT 的标识符。

代币 ID 会按数值顺序返回吗？

不会。标准没有规定任何特定的枚举顺序。

枚举顺序会发生变化吗？

会。转账和销毁可能改变索引位置，尤其是在使用 swap-and-pop 移除方式的实现中。

销毁 NFT 会降低 totalSupply 吗？

会。实现正确的可枚举合约会移除被销毁的 NFT，并降低当前总供应量。

转移 NFT 会改变 totalSupply 吗？

不会。普通转账会改变所有者枚举，但不会改变现存 NFT 的数量。

为什么该扩展成本较高？

铸造、转账和销毁时，维护全局及所有者专属代币索引需要额外的存储写入。

枚举调用免费吗？

链下 RPC 读取无需支付链上 Gas 费，但交易中发起的智能合约调用会消耗 Gas。

合约可以遍历所有可枚举 NFT 吗？

合约可以尝试这样做，但不受限制的链上循环最终可能超出区块 Gas 限制。

该扩展提供分页功能吗？

不提供。应用通过查询指定索引范围自行实现分页。

该扩展会列出所有 NFT 持有者吗？

不会。它会列出全局代币 ID 和某个已知所有者持有的代币 ID，但不会返回所有所有者地址的唯一列表。

事件索引可以取代枚举吗？

可以。链下索引器能够通过 ERC-721 Transfer 事件重建代币供应量和所有权。

枚举功能包含 NFT 元数据吗？

不包含。元数据由另一个可选 ERC-721 扩展提供。

枚举功能能证明 NFT 真实性吗？

不能。任何人都可以部署可枚举合约，因此用户必须核实网络、合约地址、发行方和权限。

部署后可以添加枚举功能吗？

可升级合约可以添加该功能，但必须安全地将现有代币迁移到新的索引结构中。

ERC721Enumerable 与所有 ERC-721 扩展都兼容吗？

不兼容所有扩展。压缩批量铸造和自定义余额实现可能与标准枚举存储冲突。

Enumerable 扩展在何时最有用？

当合约或应用需要通过标准化方式在链上访问当前代币列表或某个所有者的代币 ID 时，该扩展最有用。

总结

Enumerable 扩展是 ERC-721 的一项可选功能，可通过标准化链上查询发现 NFT 代币 ID。

其接口 ID 为

。

该扩展新增

、 和 。

这些函数可以列出当前系列中的代币，以及已知地址持有的代币 ID。

枚举索引不是永久标识符，标准也不保证其顺序。

该扩展也不提供元数据、版税、持有者列表、历史记录或固定供应量证明。

维护全局和所有者专属索引需要额外的存储写入，因此会增加铸造、转账和销毁的 Gas 成本。

大型应用通常使用 ERC-721 Transfer 事件和链下索引，而不是为完整的链上枚举支付额外成本。

实现该扩展的开发者必须确保所有权、余额和索引结构在每条改变状态的路径上保持同步。

用户应独立核实接口支持情况、合约身份、铸造权限、升级权限和当前供应量。

了解 Enumerable 扩展，有助于加密用户区分直接链上 NFT 发现、元数据、所有权历史、稀缺性和链下索引服务。