Ambiguous definition of `closed` ledger

[FrancisBehnen]

After reading the ledger_closed method and its accompanying ledger_current, I was convinced it would return me the last ledger that was submitted for validation. Possibly (probably) not yet validated because validations from others are still in transit.

However, then someone showed me the consensus explanation in the rippled repo. At "overview" this documentation describes that after the Open phase the node will Close the ledger and the node receives proposals from trusted nodes to accept in the closed ledger during the Establish phase. When the node determines it has reached consensus it transitions to the Accept phase where it builds and shares this validated ledger. Then the cycle starts again.

This convinced me that the closed ledger is the last ledger on which nodes are deliberating which transactions to include without proposing new ones, because the API documentation doesn't exclude this interpretation (at ledger_closed "This ledger is not necessarily immutable yet", without mentioning at what level it is mutable).

However, while typing this I found the table on ledger states. From that I deduce that my first interpretation is correct. I suppose this is more up-to-date than the docs in rippled?

[mDuo13]

The short answer is, "it's complicated" and depends on what you mean when you say that a ledger is immutable. The table on ledger states is accurate to the best of my knowledge.

There's a good chance that the consensus overview in the rippled repo uses some misleading / confusing language. I think it is probably out of date.

The data structure for a closed ledger is immutable, in the sense that it can't be changed in-place. However, a closed ledger can be replaced by another closed ledger that's different but has the same sequence number. The cases in which that would happen are basically all, "the server's view of the network's consensus changed."

In most circumstances a server has approximately 1 "closed" ledger which is the server's best guess at what the next validated ledger will be based on the ongoing consensus process. However, as the consensus process occurs, transactions may be added or removed from the proposed consensus set, which prompts the "closed" ledger to be re-generated with the new set.

In rare circumstances a server may decide that consensus has failed, and move on to creating another ledger (the child of the previous closed ledger) and trying to get that one validated instead. (Validation can skip a ledger index; validating a specific index implicitly validates everything prior in the chain.) In exceptional circumstances (network instability/disconnects, mostly), this can continue several times, to the point where a server has hundreds of closed, unvalidated ledgers. The so-called "lag ratchet" code slows down the rate of creating new ledgers if a server notices it has branched off from the rest of its UNL and the "preferred branch" code controls how servers converge back to a single validated chain when they are able to communicate again. These are complicated, advanced topics, though.

I am not sure what part of the xrpl.org docs is ambiguous per what you are saying, though.

[FrancisBehnen]

From your explanation I understand that a closed ledger is not necessarily sent out as vote, but merely reflects the last (current) view of the server on transaction consensus in the current deliberation round. I had understood it as "the ledger sent as validation vote".

This may partly be because of Chase and MacBrough their phrasing in their analysis paper[1]: "When a node believes enough proposals agree, it applies the corresponding transactions to the prior ledger according to the ledger protocol rules. It then issues a validation for the generated ledger." This doesn't speak of multiple generated ledgers.

In my view this, in combination with the explanation in the rippled repository, shows ambiguity. None of the described interpretations are refuted by the xrpl docs, while only one can be correct.

My suggestion would be to add an explicit description of every situation that triggers a new closed ledger to be generated (and hence change the result of the api call) to the ledger_closed method reference.

I hope this is helpful feedback, xrpl docs has mainly been a great resource for understanding how the XRP network works!

[1] http://arxiv.org/abs/1802.07242v1

[q411]

http://arxiv.org/abs/1802.07242v1