NFTokenPage

The NFTokenPage object represents a collection of NFToken objects owned by the same account. An account can have multiple NFTokenPage ledger objects, which form a doubly linked list.

(Added by the NonFungibleTokensV1_1 amendment.)

Example NFTokenPage JSON

{
  "LedgerEntryType": "NFTokenPage",
  "PreviousTokenPage":
    "598EDFD7CF73460FB8C695d6a9397E907378C8A841F7204C793DCBEF5406",
  "PreviousTokenNext":
    "598EDFD7CF73460FB8C695d6a9397E9073781BA3B78198904F659AAA252A",
  "PreviousTxnID":
    "95C8761B22894E328646F7A70035E9DFBECC90EDD83E43B7B973F626D21A0822",
  "PreviousTxnLgrSeq":
    42891441,
  "NFTokens": [
    {
      "NFTokenID":
          "000B013A95F14B0044F78A264E41713C64B5F89242540EE208C3098E00000D65",
        "URI": "697066733A2F2F62616679626569676479727A74357366703775646D37687537367568377932366E6634646675796C71616266336F636C67747179353566627A6469"
    },
    /* potentially more objects */
  ]
}

In the interest of minimizing the size of a page and optimizing storage, the Owner field is not present, since it is encoded as part of the object's ledger identifier.

NFTokenPage Fields

An NFTokenPage object can have the following required and optional 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.

Reserve for NFTokenPage objects

Each NFTokenPage counts as one item towards an account's owner reserve. Since each page can hold up to 32 NFToken entries, the effective reserve cost per NFToken can be as low as R/32 where R is the incremental reserve.

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 NFToken objects, each page can have as few as 16 NFToken objects, or as many as 32, with the typical case being around 24 NFToken objects per page.

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

These numbers are estimates; the actual numbers may vary.