Obtaining the list of ERC721 tokenIds owned by an account

[frangio]

ERC721 has no way to retrieve all tokenIds owned by an account, such as the tokensOf function that was at some point part of the draft but removed before becoming final. We discussed bringing that function back in #856 but decided against it.

There is a function tokenOfOwnerByIndex that allows iterating the owned tokens one by one, but this will probably result in terrible performance and also suffers race conditions.

It's not clear what is the correct way for programs, including dapps, to retrieve all of the tokens owned by an account. It would be very useful if OpenZeppelin included documentation or helpers related to this task.

There was already a few proposals in the comments of #856, which I encourage those interested to read. There was mention of events, off-chain indexing (e.g. gnarly), JSON-RPC batching (apparently a non-solution), an auxiliary querier contract (#856 (comment)), and even using said contract via eth_call.

We need some research done on the feasiblity of those approaches, their performance, as well as other alternatives, with the objective of making a recommendation to OpenZeppelin users and the ERC721 ecosystem in general. There may already be a solution out there that we haven't heard about!

[arpu]

Hey is there any recommendation now for this problem?

[frangio]

@arpu I'd suggest looking into The Graph.

[arpu]

@arpu I'd suggest looking into The Graph.

but this is not client side and dezentral ?

[frangio]

@arpu No, it isn't decentralized, at least not yet.

[frangio]

I recently put together a script to show how this can be done by inspecting the events of the ERC721 contract, originally posted in #2563 (comment). The code is for Ethers but can be easily ported to Web3.js.

async function listTokensOfOwner({ token: tokenAddress, account }) {
  const token = await ethers.getContractAt(ERC721.abi, tokenAddress, ethers.provider);

  console.error(await token.name(), 'tokens owned by', account);

  const sentLogs = await token.queryFilter(
    token.filters.Transfer(account, null),
  );
  const receivedLogs = await token.queryFilter(
    token.filters.Transfer(null, account),
  );

  const logs = sentLogs.concat(receivedLogs)
    .sort(
      (a, b) =>
        a.blockNumber - b.blockNumber ||
        a.transactionIndex - b.TransactionIndex,
    );

  const owned = new Set();

  for (const log of logs) {
    const { from, to, tokenId } = log.args;
    
    if (addressEqual(to, account)) {
      owned.add(tokenId.toString());
    } else if (addressEqual(from, account)) {
      owned.delete(tokenId.toString());
    }
  }

  console.log([...owned].join('\n'));
};

The code is in frangio/erc721-list.

[frangio]

@Amxx Is there a subgraph already made for this purpose?

[Amxx]

@Amxx Is there a subgraph already made for this purpose?

For sure! https://thegraph.com/explorer/subgraph/amxx/eip721-subgraph

All token in a registry:

{
  tokenRegistry(id: "0x22c1f6050e56d2876009903609a2cc3fef83b415") {
    tokens {
      identifier
      owner {
        id
      }
    }
  }
}

All tokens held by a user (across all registries) :

{
  account(id: "0x7859821024e633c5dc8a4fcf86fc52e7720ce525") {
    tokens {
      identifier
      registry {
        id
      }
    }
  }
}

and many more ...

[gsyndromes]

thanks for the code! i'm new around this ecosystem and I was wondering if you could give a quick rundown on how do I use the script?

[frangio]

@garysyndromes You can run it in a Hardhat script. Take a look at the guides in the Hardhat documentation if you need to learn more about it. If you need more help please ask in the OpenZeppelin forum.