Skip to content

Add concept for owner directories #3322

@mDuo13

Description

@mDuo13

We should probably have a page or at least a section that explains the concept of owner directories and describes some of their properties.

Some information is in the DirectoryNode ledger entry reference and some other information is in the Reserves page but we don't have a dedicated place to explain the basic idea behind owner directories or some of their important properties.

Some ideas you might cover in the topic:

  • Each account has an owner directory, which is broken down into pages, and doesn't separately count towards their reserve

  • The point of an owner directory is to make it efficient (that is, possible without searching the entire ledger data) for an account to find all ledger entries that are associated with it.

  • An account doesn't necessarily "own" everything in its owner directory, especially in the sense that items you own count towards your owner reserve.

    • Trust lines, for example, are recorded in both parties' owner directories but typically only count towards the holder's owner reserve and not the issuer's. If both sides set non-default values, then both sides can own (and owe a reserve for) the trust line.
    • Escrows and payment channels are only "owned" by the sender but are tracked in both the sender and recipient's owner directories. (With possible exception of very old payment channels that were grandfathered in prior to the fixPayChanRecipientOwnerDir amendment.)
  • Some API methods, like account_lines, account_offers, rely on the owner directory to work. Also, the account_objects method gives an exact list of the items in an account's owner directory.

  • Like all ledger data, owner directories are public knowledge.

  • The reason some transactions and API methods are the way they are is that iterating over an account's owner directory to look for something specific can be resource-intensive. You might have to page through thousands of trust lines and/or offers to find the one signer list or something that you're looking for. That's why filtering by ledger entry type on account_objects can return less than the limit or even empty pages before it finds everything.

  • Owner directories have a large but finite cap of the number of items you can own. Per @ximinez:

    NFT pages work differently, and I don't think they're counted against the directory page count. [...] There are max of 32 items per regular directory page, giving a theoretical maximum of 262144*32 = 8388608 entries. However, in reality, an account is unlikely to ever get that many because the directory pages can fewer than 32 items and there can be gaps in the pages, because holes are frequently left when items deleted, and there is currently no way to "defrag" them.

    (Source code link where these constants come from: https://github.com/XRPLF/rippled/blob/a12f5de68d0acd2641829fdc144404e1ad1ff9e3/include/xrpl/protocol/Protocol.h#L56-L59 )

Metadata

Metadata

Assignees

No one assigned

    Labels

    new topicDescribes a detailed document to be added or expanded in detail

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions