NFTokenPage

Non-fungible token functionality is part of the NonFungibleTokensV1 amendment to the XRP Ledger protocol. You can use these functions on the NFT-Devnet now, but they are not yet available on the production Mainnet.

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.

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:

TokenPage ID Format

NFTokenPage identifiers are constructed so as to specifically allow for the adoption of a more efficient paging structure, ideally suited for NFTokens.

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, and assuming that the function low96(x) returns the low 96 bits of a 256-bit value, an NFT with NFTokenID A can be included in a page with NFTokenPageID B if and only if low96(A) >= low96(B).

For example, applying the low96 function to the NFT described before, which had an ID of 000B013A95F14B0044F78A264E41713C64B5F89242540EE208C3098E00000D65 the function low96 would return 42540EE208C3098E00000D65.

This curious construct exploits the structure of the SHAMap to allow for efficient lookups of individual NFToken objects without requiring iteration of the doubly-linked list of NFTokenPages.

Searching for an NFToken object

To search for a specific NFToken, compute the NFTokenPageID using the account of the owner and the NFTokenID of the token, as described above. Search for a ledger entry where the identifier is less than or equal to that value. If that entry does not exist or is not an NFTokenPage, the NFToken is not held by the given account.

Adding an NFToken object

You add an NFToken object by finding the NFTokenPage it should be in (using the same technique as searching for an NFToken object) and adding it to that page. If the page overflows after you add the NFToken, find the next and previous pages (if any) and balance those three pages, inserting a new page as needed.

Removing an NFToken object

An NFToken can be removed by using the same approach. If the number of NFTokens in the page goes below a certain threshold, the server attempts to consolidate the page with a previous or subsequent page to recover the reserve.

Reserve for NFTokenPage object

Each NFTokenPage costs an incremental reserve to the owner account. This specification allows up to 32 NFToken entries per page, which means that for accounts that hold multiple NFTs the effective reserve cost per NFT can be as low as R/32 where R is the incremental reserve.

The reserve in practice

The value of the incremental reserve is, as of this writing, 2 XRP. The table below shows what the effective reserve per token is, if a given page contains 1, 8, 16 and 32 NFTs.