Open mDuo13 opened 3 years ago
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
.
"Key" kind of makes sense but I worry it would be confused for a cryptographic key...
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.
AccountStateIndex
LedgerEntryID Yeah ^
Summary
Change the fields
index
andLedgerIndex
toLedgerEntryID
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 forindex
that is used in transaction metadataThe
ledger_index
andLedgerIndex
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 bothLedgerIndex
andindex
to refer to the same thing, on top of usingledger_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:
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:
index
LedgerEntryID
accounts: true
orfull: true
), ledger_data¹, ledger_entry, and book_offers.LedgerIndex
LedgerEntryID
index
²entry_id
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 lowercasedata
next to upper-CamelCaseLedgerEntryID
but I think it's OK. I would also acceptentry_id
there. ² The fieldindex
is a shared definition withindex
as used in the download_shard request to refer to a Shard Index. I suggest leavingdownload_shard
's usage ofindex
unchanged or perhaps changing it toshard_index
.Paths Not Taken
id
as the field name: this field name is used to refer to WebSocket request IDsledger_index
toledger_sequence
, butledger_index
is so widespread in both requests and responses that I think it would be a bigger change for API consumers.