ownedTokensIndex

ownedTokensIndex is a data structure used in the ERC721Enumerable extension of the ERC-721 standard to support on-chain enumeration of tokens owned by an address. It is defined as a mapping from a token's identifier (tokenId) to the index at which that token appears in the owner's array of tokens. This index enables constant-time updates when tokens are added to or removed from an owner's balance and makes enumeration efficient.

In typical implementations, each owner maintains an array of their token IDs called _ownedTokens. When a token is transferred to a new owner or burned, the contract uses the ownedTokensIndex mapping to locate the token's position in the old owner's _ownedTokens array, swap it with the last token in that array if necessary, update the moved token's index, and then remove the last element. The update logic is performed in functions such as _addTokenToOwnerEnumeration and _removeTokenFromOwnerEnumeration. Specifically, when a token is first assigned to an owner, _ownedTokensIndex[tokenId] records the index where the token is placed in _ownedTokens[owner]. Conversely, during removal, the mapping entry for tokenId is deleted after the swap.

The visibility of ownedTokensIndex is typically private or internal, and it is used in conjunction with _ownedTokens and other enumeration structures provided by ERC721Enumerable. A caveat in Solidity is that mappings return a default value (zero) for keys that have not been set, so the implementation relies on invariants that tokenId is actually present in the owner's enumeration before querying its index.

Related concepts include ERC721Enumerable, _ownedTokens, and the internal update routines that maintain consistent enumeration data across transfers and burns.