tokenOfOwnerByIndex

tokenOfOwnerByIndex is a function in the ERC-721 Enumerable extension that enables enumeration of tokens owned by a specific address. It allows external applications to retrieve the token ID at a given position within the set of tokens owned by an address, facilitating per-owner token listing.

The function has the signature: function tokenOfOwnerByIndex(address owner, uint256 index) external view returns (uint256 tokenId). It is a read-only operation and does not modify contract state. It requires that index is less than balanceOf(owner), meaning the caller must provide a valid index within the owner’s token count. The returned value is the tokenId of the token at the specified index for that owner.

Implementation typically relies on internal data structures that map each owner to an indexed list of their tokens, such as _ownedTokens[owner][index] -> tokenId and a reverse index mapping. This structure supports efficient access to a user’s tokens without iterating over all tokens in the contract.

Use cases include wallets, explorers, and marketplaces that need to display or iterate over the tokens owned by a given address, or that need to support user-centric token views. tokenOfOwnerByIndex works alongside tokenByIndex and totalSupply as part of the ERC-721 Enumerable extension, enabling both per-owner and global enumeration.

Considerations include gas and performance implications for on-chain calls that enumerate large collections; since the function is view, calls from off-chain clients do not incur on-chain gas costs, but reading large indexes can still be resource-intensive for nodes. The extension is optional in ERC-721 and must be implemented to provide per-owner enumeration.