tokenByIndexuint256

tokenByIndex(uint256) is a function defined in the ERC-721 Enumerable extension, which provides the ability to enumerate all token identifiers in a contract. It returns the tokenId located at a given index within the global list of tokens that currently exist in the contract.

In the standard interface IERC721Enumerable, the function signature is tokenByIndex(uint256 index) external view returns (uint256). The index is zero-based and must be in the range from 0 to totalSupply() - 1, where totalSupply reflects the number of tokens currently existing.

Behavior and guarantees: tokenByIndex is a view function that returns the tokenId associated with the specified index in the contract’s global enumeration. If index is out of bounds (i.e., index >= totalSupply()), the call typically reverts. The function relies on an internal data structure, commonly an array that stores all existing token IDs, enabling constant-time access.

Implementation notes: In widely used implementations, tokenByIndex uses a compact representation such as an _allTokens array coupled with an _allTokensIndex mapping. totalSupply tracks the number of tokens currently existing (excluding burned tokens). This arrangement enables efficient on-chain enumeration of all tokens and stable iteration order as tokens are minted or burned.

Use cases: tokenByIndex is useful for external applications that need to iterate over all tokens in a contract, such as wallets, marketplaces, indexers, or analytics tools, independent of token ownership. It complements tokenOfOwnerByIndex, which enumerates tokens owned by a specific address.

Limitations: While on-chain calls are deterministic, enumerating large collections may be resource-intensive; off-chain tools commonly perform such enumeration via repeated view calls or by maintaining external indices.