NFTokenPage

[Source]

An NFTokenPage entry represents a collection of NFTs owned by the same account. An account can have multiple NFTokenPage entries, which form a doubly linked list. NFT directories are automatically updated when an account mints, burns, buys, or sells NFTs.

(Added by the NonFungibleTokensV1_1 amendment.)

Example NFTokenPage JSON

{
  "LedgerEntryType": "NFTokenPage",
  "PreviousPageMin":
    "8A244DD75DAF4AC1EEF7D99253A7B83D2297818B2297818B70E264D2000002F2",
  "NextPageMin":
    "8A244DD75DAF4AC1EEF7D99253A7B83D2297818B2297818BE223B0AE0000010B",
  "PreviousTxnID":
    "95C8761B22894E328646F7A70035E9DFBECC90EDD83E43B7B973F626D21A0822",
  "PreviousTxnLgrSeq":
    42891441,
  "NFTokens": [
    {
      "NFToken": {
        "NFTokenID":
          "000B013A95F14B0044F78A264E41713C64B5F89242540EE208C3098E00000D65",
        "URI": "697066733A2F2F62616679626569676479727A74357366703775646D37687537367568377932366E6634646675796C71616266336F636C67747179353566627A6469"
      }
    },
    /* potentially more objects */
  ]
}

NFTokenPage Fields

In addition to the common fields, NFTokenPage entries have the following fields:

NFTokenPage ID Format

NFTokenPage identifiers are constructed to allow a more efficient paging structure, ideally suited for NFToken objects.

The identifier of an NFTokenPage is derived by concatenating the 160-bit AccountID of the owner of the page, followed by a 96 bit value that indicates whether a particular NFTokenID can be contained in this page.

More specifically, a NFToken with the NFTokenID value A can be included in a page with NFTokenPage ID B if and only if low96(A) >= low96(B).

This uses a function low96(x) which returns the low 96 bits of a 256-bit value, For example, applying the low96 function to the NFTokenID of 000B013A95F14B0044F78A264E41713C64B5F89242540EE208C3098E00000D65 returns the value 42540EE208C3098E00000D65.

This design allows for efficient lookups of individual NFToken objects without needing to check each NFTokenPage in a list.

Finding NFTokens

To find a specific NFToken, you need to know its NFTokenID and current owner. Compute the NFTokenPage ID as described above. Search for a ledger entry whose identifier is less than or equal to that value. If that entry does not exist or is not an NFTokenPage, that account does not own that NFToken.

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.

NFTokenPage Reserve

Each NFTokenPage counts as one item towards its owner's owner reserve. Burning or trading away enough NFTs to remove the page frees up the reserve.

Since each page can hold up to 32 entries, the effective reserve cost per NFT can be as low as R/32 where R is the incremental owner reserve for one item.

The reserve in practice

Because of the way splitting and combining pages works, the actual number of NFToken objects per page is somewhat unpredictable and depends on the actual NFTokenID values involved. In practice, after minting or receiving a large number of NFTs, each page can have as few as 16 items, or as many as 32, with the typical case being around 24 NFToken objects per page.

Currently, the reserve per item is 0.2 XRP. The table below shows how much the total owner reserve is for various numbers of NFTs owned under various scenarios:

These numbers are estimates; the actual numbers may vary.