Sound Protocol
Erc721a Queryable Upgradeable


erc721a-upgradeable/contracts/extensions/ERC721AQueryableUpgradeable.sol (opens in a new tab)

ERC721A subclass with convenience query functions.

Read-only Functions


function explicitOwnershipOf(
    uint256 tokenId
) public view returns (TokenOwnership memory)

Returns the TokenOwnership struct at tokenId without reverting.

This is useful for on-chain and off-chain querying of ownership data for tokenomics.

The returned struct will contain the following values:

  • If the tokenId is out of bounds:

    • addr = address(0)
    • startTimestamp = 0
    • burned = false
  • If the tokenId is burned:

    • addr = <Address of owner before token was burned>
    • startTimestamp = <Timestamp when token was burned>
    • burned = true
  • Otherwise:

    • addr = <Address of owner>
    • startTimestamp = <Timestamp of start of ownership>
    • burned = false
tokenIdThe token ID to query.


function explicitOwnershipsOf(
    uint256[] memory tokenIds
) external view returns (TokenOwnership[] memory)

Returns an array of TokenOwnership structs at tokenIds in order.

See explicitOwnershipOf.

tokenIdsAn array of tokenIds to query.


function tokensOfOwner(address owner) external view returns (uint256[] memory)

Returns an array of token IDs owned by owner.

This function scans the ownership mapping and is O(totalSupply) in complexity.
It is meant to be called off-chain.

See tokensOfOwnerIn for splitting the scan into multiple smaller scans if the collection is large enough to cause an out-of-gas error.

This function should work fine for collections up to 50k items.

ownerThe owner of the tokens.


function tokensOfOwnerIn(
    address owner,
    uint256 start,
    uint256 stop
) external view returns (uint256[] memory)

Returns an array of token IDs owned by owner, in the range [start, stop)
(i.e. starttokenId < stop).

This function allows for tokens to be queried if the collection grows too big for a single call of tokensOfOwner.

Calling conditions:

  • start < stop.
ownerThe owner of the tokens.
startThe starting token ID.
stopThe ending token ID (exclusive).



error InvalidQueryRange()

Invalid query range (start >= stop).