Calculating NFTokenPage ID and finding an NFToken docs are ambiguous and hard to apply

[crtag]

I'm building a POC that requires NFT "search", and according to the documentation such a routine would require the calculation of a page id being a combination of the owner account ID and the lower 96 bits of the NFT ID. Page reference: https://xrpl.org/nftokenpage.html#nftokenpage-id-format

This is quite straightforward, however, does not work in reality (testnet)

The reference in the following paragraph states that "Search for a ledger entry whose identifier is less than or equal to that value". Page reference: https://xrpl.org/nftokenpage.html#finding-nftokens

In reality, there's a "zero" page with the ID comprised of the owner account ID and 96 high bits (12 bytes of FF) and as soon the number of NFTs exceeds 32, a new page is created and referenced through that "zero" page PreviousPageMin property.

Problems:

1. The documentation is not relevant in terms of "zero" page existence and usage.
2. It's not clear how to build a proper page ID to search for a particular NFT. Ie if we need to iterate to find a smaller value than calculated, then what's the logic, and how far?
3. Examples, please.

My example in testnet: Account: rs2HK4v88nabm2wnRZ7M4DfRerheF1KeVC It has more than 32 NFTs now and here's its "zero" page ID: 1C3B9953FFB1ED77E4BAB6E892631A0E7D964773FFFFFFFFFFFFFFFFFFFFFFFF Test: https://xrpl.org/websocket-api-tool.html?server=wss%3A%2F%2Fs.altnet.rippletest.net%3A51233%2F&req=%7B%22command%22%3A%22ledger_entry%22%2C%22nft_page%22%3A%221C3B9953FFB1ED77E4BAB6E892631A0E7D964773FFFFFFFFFFFFFFFFFFFFFFFF%22%2C%22ledger_index%22%3A%22validated%22%7D

If I wanted to search for a NFT with ID 000809C41C3B9953FFB1ED77E4BAB6E892631A0E7D964773F39FFABC00000021 the page ID would be 1C3B9953FFB1ED77E4BAB6E892631A0E7D9647737D964773F39FFABC00000021 or smaller. Using that ID results in not found entry. Test: https://xrpl.org/websocket-api-tool.html?server=wss%3A%2F%2Fs.altnet.rippletest.net%3A51233%2F&req=%7B%22command%22%3A%22ledger_entry%22%2C%22nft_page%22%3A%221C3B9953FFB1ED77E4BAB6E892631A0E7D9647737D964773F39FFABC00000021%22%2C%22ledger_index%22%3A%22validated%22%7D

[intelliot]

@ledhed2222 could you take a look at this? 🙏

[crtag]

Chances this could be clarified and I can update docs? It's getting critical to have this mechanism clarified as NFTs gain popularity.

[haoliangwu]

I have also encountered this issue in a recent R&D project and am curious about how to add or remove an NFToken to/from a specific NFTokenPage based on the official documentation.

As per documentation:

Adding NFTokens

To add an NFToken, find the NFTokenPage it should be in (using the same technique as searching for an NFToken object) and add it to that page. If the NFTokenPage is already full, find the previous and next pages (if any) and balance those three pages, inserting a new NFTokenPage as needed.

Removing NFTokens

Removing NFToken objects works like adding them. If the number of NFToken objects in the page goes below a certain threshold, the ledger combines the page with a previous or next page if possible.

It seems we should add an NFToken manually but the removing workflow was finished by ledger automatically.

In a searching scenario, it appears that the solution is to iteratively traverse the doubly-linked list of the entire NFTokenPage from the zero-page until the corresponding NFToken is found.

[shawnxie999]

@crtag The behavior is expected. When you have a NFT with ID 000809C41C3B9953FFB1ED77E4BAB6E892631A0E7D964773F39FFABC00000021, it is not guareented to be in a page with the ID of 1C3B9953FFB1ED77E4BAB6E892631A0E7D9647737D964773F39FFABC00000021. How it works that a NFT can be in any page as long as low96bits(NFTokenID) <= low96bits(NFTokenPageID). So there isn't really a way to search for this NFT beside traversing the doubly-linked list from the zero-page, because there are many pages that could possibly hold onto this particular NFT.

@haoliangwu The ledger is able to add/remove/find a NFToken in constant time for a transaction. However, it's not possible for a client to be able to do that. So you are right that the only way to find an NFT is to start traversing the doubly linked list from the zero-page.

Because of these limitation, an nft_info APi is made available on the clio server to allow one to lookup for an NFT