Suggestion: Change "index" to "LedgerEntryID" for ledger objects

[mDuo13]

Summary

Change the fields index and LedgerIndex to LedgerEntryID to reduce confusion about what a "ledger index" means.

Motivation

"Index" is one of the most confusing terms in understanding the XRP Ledger:

• ledger_index is how you specify a particular version of a ledger by its ledger index (also called a "ledger sequence", though I have been phasing out the term "ledger sequence" to reduce the number of redundant terms.)
• index is the unique ID of an object in the ledger's state tree (a "ledger entry")
• LedgerIndex is a synonym for index that is used in transaction metadata

The ledger_index and LedgerIndex fields often appear very close to one another in a single API response despite having different data types and referring to totally different things. Example:

Meanwhile, in the most egregious cases (e.g. the ledger command with "full": true) a single API response may use both LedgerIndex and index to refer to the same thing, on top of using ledger_index to mean something different.

As an aside, a "transaction index" and a "transaction sequence" are unrelated things and neither of them is the transaction's ID:

Term	Transaction	Ledger
Sequence	The account sequence number this transaction consumed.	The sequence number of the ledger. (Deprecated usage.)
Index	The order a transaction was executed within a ledger.	The ID of an object within the ledger; or the sequence number of the ledger.

Solution

We can change the names of fields in the JSON formats without changing those fields' canonical binary meanings or values. I suggest making the following changes in APIv2 or later:

Old name	New Name	Used In
index	LedgerEntryID	Serialization of ledger entry objects, including from API responses from account_info, account_objects, ledger (in the state data returned with accounts: true or full: true), ledger_data¹, ledger_entry, and book_offers.
LedgerIndex	LedgerEntryID	Serialization of transaction metadata in all places that occurs.
index²	entry_id	In ledger_entry requests

Some relevant source code links:

• sfLedgerIndex
• JSS(index)
• Indexes.cpp - the actual values here don't need to change, but the comments should be updated to use the preferred term "Ledger Entry ID" (or some shortening of that) and maybe the file should be renamed.

¹ In the case of ledger_data with "binary": true, it may be aesthetically displeasing to see lowercase data next to upper-CamelCase LedgerEntryID but I think it's OK. I would also accept entry_id there. ² The field index is a shared definition with index as used in the download_shard request to refer to a Shard Index. I suggest leaving download_shard's usage of index unchanged or perhaps changing it to shard_index.

Paths Not Taken

• id as the field name: this field name is used to refer to WebSocket request IDs
• bringing back "ledger sequence" as a term: I'd rather try not to overload the word "sequence" with too many uses. At least account sequence, transaction sequence, and offer sequence numbers are pretty closely related. (There are also "key sequence" numbers in secp256k1 key derivation and in manifests and validator lists, but those are pretty obscure so you usually don't need to worry about them.)
  • It might be a narrower change from a code perspective to change ledger_index to ledger_sequence, but ledger_index is so widespread in both requests and responses that I think it would be a bigger change for API consumers.

[cjcobb23]

What about using key instead of id? We could use LedgerEntryKey, or something like that. key-value is a widely used terminology, is easily understood and accurately describes what's going on here. The ledger is just a map, and maps use the key-value terminology; in the code, we call the ledger a "state map". We also use key in the codebase in various places, as well as Keylet: https://github.com/ripple/rippled/blob/0b4e34b03b72196510998375fd28622c8b63aaa7/src/ripple/app/ledger/Ledger.h#L176 https://github.com/ripple/rippled/blob/0b4e34b03b72196510998375fd28622c8b63aaa7/src/ripple/app/ledger/Ledger.h#L198 https://github.com/ripple/rippled/blob/0b4e34b03b72196510998375fd28622c8b63aaa7/src/ripple/app/ledger/Ledger.h#L173

https://github.com/ripple/rippled/blob/0b4e34b03b72196510998375fd28622c8b63aaa7/src/ripple/protocol/Keylet.h#L43 https://github.com/ripple/rippled/blob/0b4e34b03b72196510998375fd28622c8b63aaa7/src/ripple/ledger/ReadView.h#L198

I find the use of key to be clearer than index or id.

[mDuo13]

"Key" kind of makes sense but I worry it would be confused for a cryptographic key...

[intelliot]

I like both options. Either would be a good improvement over the status quo. Just for fun, let's try taking a (very) informal poll right here.

Term	Reaction
LedgerEntryID	❤️
LedgerEntryKey	🚀

React to this comment with the emoji of your preferred term.

[sublimator]

AccountStateIndex

[sublimator]

LedgerEntryID Yeah ^