rippled/docs/consensus.qbk

[section Consensus and Validation]

[*This section is a work in progress!!]

Consensus is the task of reaching agreement within a distributed system in the
presence of faulty or even malicious participants.  This document outlines the
[@https://ripple.com/files/ripple/consensus/whitepaper.pdf Ripple Consensus
Algorithm] as implemented in [@https://github.com/ripple/rippled rippled], but
focuses on its utility as a generic consensus algorithm independent of the
detailed mechanics of the Ripple Consensus Ledger. Most notably, the algorithm
does not require fully synchronous communication between all nodes in the
network, or even a fixed network topology, but instead achieves consensus via
collectively trusted subnetworks.

[heading Distributed Agreement]

A challenge for distributed systems is reaching agreement on changes in shared
state.  For the Ripple network, the shared state is the current ledger--account
information, account balances, order books and other financial data.  We will
refer to shared distributed state as a /ledger/ throughout the remainder of this
document.

[$images/consensus/ledger_chain.png [width 50%] [height 50%] ]

As shown above, new ledgers are made by applying a set of transactions to the
prior ledger.  For the Ripple network, transactions include payments,
modification of account settings, updates to offers and more.

In a centralized system, generating the next ledger is trivial since there is a
single unique arbiter of which transactions to include and how to apply them to
a ledger.  For decentralized systems, participants must resolve disagreements on
the set of transactions to include, the order to apply those transactions, and
even the resulting ledger after applying the transactions.  This is even more
difficult when some participants are faulty or malicious.

The Ripple network is a decentralized and _trust-full_ network.  Anyone is free
to join and participants are free to choose a subset of peers that are
collectively trusted to not collude in an attempt to defraud the participant.
Leveraging this network of trust, the Ripple algorithm has two main components.

* /Consensus/ in which network participants agree on the transactions to apply
  to a prior ledger, based on the positions of their chosen peers.
* /Validation/ in which network participants agree on what ledger was
  generated, based on the ledgers generated by chosen peers.

These phases are continually repeated to process transactions submitted to the
network, generating successive ledgers and giving rise to the blockchain ledger
history depicted below.  In this diagram, time is flowing to the right, but
links between ledgers point backward to the parent.  Also note the alternate
Ledger 2 that was generated by some participants, but which failed validation
and was abandoned.

[$images/consensus/block_chain.png]

The remainder of this section describes the Consensus and Validation algorithms
in more detail and is meant as a companion guide to understanding the generic
implementation in =rippled=.  The document *does not* discuss correctness,
fault-tolerance or liveness properties of the algorithms or the full details of
how they integrate within =rippled= to support the Ripple Consensus Ledger.

[section Consensus Overview]

[heading Definitions]

* The /ledger/ is the shared distributed state.  Each ledger has a unique ID to
  distinguish it from all other ledgers.  During consensus, the /previous/,
  /prior/ or /last-closed/ ledger is the most recent ledger seen by consensus
  and is the basis upon which it will build the next ledger.
* A /transaction/ is an instruction for an atomic change in the ledger state.  A
  unique ID distinguishes a transaction from other transactions.
* A /transaction set/ is a set of transactions under consideration by consensus.
  The goal of consensus is to reach agreement on this set.  The generic
  consensus algorithm does not rely on an ordering of transactions within the
  set, nor does it specify how to apply a transaction set to a ledger to
  generate a new ledger.  A unique ID distinguishes a set of transactions from
  all other sets of transactions.
* A /node/ is one of the distributed actors running the consensus algorithm.  It
  has a unique ID to distinguish it from all other nodes.
* A /peer/  of a node is another node that it has chosen to follow and which it
  believes will not collude with other chosen peers.  The choice of peers is not
  symmetric, since participants can decide on their chosen sets independently.
* A /position/ is the current belief of the next ledger's transaction set and
  close time. Position can refer to the node's own position or the position of a
  peer.
* A /proposal/ is one of a sequence of positions a node shares during consensus.
  An initial proposal contains the starting position taken by a node before it
  considers any peer positions.  If a node subsequently updates its position in
  response to its peers, it will issue an updated proposal.  A proposal is
  uniquely identified by the ID of the proposing node, the ID of the position
  taken, the ID of the prior ledger the proposal is for, and the sequence number
  of the proposal.
* A /dispute/ is a transaction that is either not part of a node's position or
  not in a peer's position. During consensus, the node will add or remove
  disputed transactions from its position based on that transaction's support
  amongst its peers.

Note that most types have an ID as a lightweight identifier of instances of that
type.  Consensus often operates on the IDs directly since the underlying type is
potentially expensive to share over the network.  For example, proposal's only
contain the ID of the position of a peer.  Since many peers likely have the same
position, this reduces the need to send the full transaction set multiple times.
Instead, a node can request the transaction set from the network if necessary.

[heading Overview ]
[$images/consensus/consensus_overview.png  [width 50%] [height 50%] ]

The diagram above is an overview of the consensus process from the perspective
of a single participant.  Recall that during a single consensus round, a node is
trying to agree with its peers on which transactions to apply to its prior
ledger when generating the next ledger.  It also attempts to agree on the
[link effective_close_time network time when the ledger closed].  There are
3 main phases to a consensus round:

* A call to =startRound= places the node in the =Open= phase.  In this phase,
the node is waiting for transactions to include in its open ledger.
* At some point, the node will =Close= the open ledger and transition to the
=Establish= phase.  In this phase, the node shares/receives peer proposals on
which transactions should be accepted in the closed ledger.
* At some point, the node determines it has reached consensus with its peers on
which transactions to include. It transitions to the =Accept= phase. In this
phase, the node works on applying the transactions to the prior ledger to
generate a new closed ledger. Once the new ledger is completed, the node shares
the validated ledger hash with the network and makes a call to =startRound= to
start the cycle again for the next ledger.

Throughout, a heartbeat timer calls =timerEntry= at a regular frequency to drive
the process forward. Although the =startRound= call occurs at arbitrary times
based on when the initial round began and the time it takes to apply
transactions, the transitions from =Open= to =Establish= and =Establish= to
=Accept= only occur during calls to =timerEntry=.  Similarly, transactions can
arrive at arbitrary times, independent of the heartbeat timer. Transactions
received after the =Open= to =Close= transition and not part of peer proposals
won't be considered until the next consensus round.  They are represented above
by the light green triangles.

Peer proposals are issued by a node during a =timerEntry= call, but since peers
do not synchronize =timerEntry= calls, they are received by other peers at
arbitrary times. Peer proposals are only considered if received prior to the
=Establish= to =Accept= transition, and only if the peer is working on the same
prior ledger. Peer proposals received after consensus is reached will not be
meaningful and are represented above by the circle with the X in it.  Only
proposals from chosen peers are considered.

[#effective_close_time]
[heading Effective Close Time]

In addition to agreeing on a transaction set, each consensus round tries to
agree on the time the ledger closed.  Each node calculates its own close time
when it closes the open ledger.  This exact close time is rounded to the nearest
multiple of the current /effective close time resolution/.  It is this
/effective close time/ that nodes seek to agree on. This allows servers to
derive a common time for a ledger without the need for perfectly synchronized
clocks. As depicted below, the 3 pink arrows represent exact close times from 3
consensus nodes that round to the same effective close time given the current
resolution. The purple arrow represents a peer whose estimate rounds to a
different effective close time given the current resolution.

[$images/consensus/EffCloseTime.png]

The effective close time is part of the node's position and is shared with peers
in its proposals.  Just like the position on the consensus transaction set, a
node will update its close time position in response to its peers' effective
close time positions.  Peers can agree to disagree on the close time, in which
case the effective close time is taken as 1 second past the prior close.

The close time resolution is itself dynamic, decreasing (coarser) resolution in
subsequent consensus rounds if nodes are unable to reach consensus on an
effective close time and increasing (finer) resolution if nodes consistently
reach close time consensus.

[heading Modes]

Internally, a node operates under one of the following consensus modes. Either
of the first two modes may be chosen when a consensus round starts.

* /Proposing/ indicates the node is a full-fledged consensus participant.  It
  takes on positions and sends proposals to its peers.
* /Observing/ indicates the node is a passive consensus participant.  It
  maintains a position internally, but does not propose that position to its
  peers. Instead, it receives peer proposals and updates its position
  to track the majority of its peers.  This may be preferred if the node is only
  being used to track the state of the network or during a start-up phase while
  it is still synchronizing with the network.

The other two modes are set internally during the consensus round when the node
believes it is no longer working on the dominant ledger chain based on peer
validations. It checks this on every call to =timerEntry=.

* /Wrong Ledger/ indicates the node is not working on the correct prior ledger
  and does not have it available.  It requests that ledger from the network, but
  continues to work towards consensus this round while waiting.  If it had been
  /proposing/, it will send a special "bowout" proposal to its peers to indicate
  its change in mode for the rest of this round. For the duration of the round,
  it defers to peer positions for determining the consensus outcome as if it
  were just /observing/.
* /Switch Ledger/ indicates that the node has acquired the correct prior ledger
  from the network. Although it now has the correct prior ledger, the fact that
  it had the wrong one at some point during this round means it is likely behind
  and should defer to peer positions for determining the consensus outcome.

[$images/consensus/consensus_modes.png]

Once either wrong ledger or switch ledger are reached, the node cannot
return to proposing or observing until the next consensus round.  However,
the node could change its view of the correct prior ledger, so going from
switch ledger to wrong ledger and back again is possible.

The distinction between the wrong and switched ledger modes arises because a
ledger's unique identifier may be known by a node before the ledger itself. This
reflects that fact that the data corresponding to a ledger may be large and take
time to share over the network, whereas the smaller ID could be shared in a peer
validation much more quickly. Distinguishing the two states allows the node to
decide how best to generate the next ledger once it declares consensus.

[heading Phases]

As depicted in the overview diagram, consensus is best viewed as a progression
through 3 phases.  There are 4 public methods of the generic consensus algorithm
that determine this progression

* =startRound= begins a consensus round.
* =timerEntry= is called at a regular frequency (=LEDGER_MIN_CLOSE=) and is the
  only call to consensus that can change the  phase from =Open= to =Establish=
  or =Accept=.
* =peerProposal= is called whenever a peer proposal is received and is what
  allows a node to update its position in a subsequent =timerEntry= call.
* =gotTxSet= is called when a transaction set is received from the network. This
  is typically in response to a prior request from the node to acquire the
  transaction set corresponding to a disagreeing peer's position.

The following subsections describe each consensus phase in more detail and what
actions are taken in response to these calls.

[h6 Open]

The =Open= phase is a quiescent period to allow transactions to build up in the
node's open ledger.  The duration is a trade-off between latency and throughput.
A shorter window reduces the latency to generating the next ledger, but also
reduces transaction throughput due to fewer transactions accepted into the
ledger.

A call to =startRound= would forcibly begin the next consensus round, skipping
completion of the current round.  This is not expected during normal operation.
Calls to =peerProposal= or =gotTxSet= simply store the proposal or transaction
set for use in the coming =Establish= phase.

A call to =timerEntry= first checks that the node is working on the correct
prior ledger. If not, it will update the mode and request the correct ledger.
Otherwise, the node checks whether to switch to the =Establish= phase and close
the ledger.

['Ledger Close]

Under normal circumstances, the open ledger period ends when one of the following
is true

* if there are transactions in the open ledger and more than =LEDGER_MIN_CLOSE=
  have elapsed.  This is the typical behavior.
* if there are no open transactions and a suitably longer idle interval has
  elapsed.  This increases the opportunity to get some transaction into
  the next ledger and avoids doing useless work closing an empty ledger.
* if more than half the number of prior round peers have already closed or finished
  this round. This indicates the node is falling behind and needs to catch up.


When closing the ledger, the node takes its initial position based on the
transactions in the open ledger and uses the current time as
its initial close time estimate.  If in the proposing mode, the node shares its
initial position with peers.  Now that the node has taken a position, it will
consider any peer positions for this round that arrived earlier.  The node
generates disputed transactions for each transaction not in common with a peer's
position.  The node also records the vote of each peer for each disputed
transaction.

In the example below, we suppose our node has closed with transactions 1,2 and 3.  It creates disputes
for transactions 2,3 and 4, since at least one peer position differs on each.

[#disputes_image]
[$images/consensus/disputes.png  [width 20%] [height 20%]]


[h6 Establish]

The establish phase is the active period of consensus in which the node
exchanges proposals with peers in an attempt to reach agreement on the consensus
transactions and effective close time.

A call to =startRound= would forcibly begin the next consensus round, skipping
completion of the current round.  This is not expected during normal operation.
Calls to =peerProposal= or =gotTxSet= that reflect new positions will generate
disputed transactions for any new disagreements and will update the peer's vote
for all disputed transactions.

A call to =timerEntry= first checks that the node is working from the correct
prior ledger. If not, the node  will update the mode and request the correct
ledger.  Otherwise, the node updates the node's position and considers whether
to switch to the =Accepted= phase and declare consensus reached.  However, at
least =LEDGER_MIN_CONSENSUS= time must have elapsed before doing either.  This
allows peers an opportunity to take an initial position and share it.

['Update Position]

In order to achieve consensus, the node is looking for a transaction set that is
supported by a super-majority of peers.  The node works towards this set by
adding or removing disputed transactions from its position based on an
increasing threshold for inclusion.

[$images/consensus/threshold.png  [width 50%] [height 50%]]

By starting with a lower threshold, a node initially allows a wide set of
transactions into its position. If the establish round continues and the node is
"stuck", a higher threshold can focus on accepting transactions with the most
support.  The constants that define the thresholds and durations at which the
thresholds change are given by `AV_XXX_CONSENSUS_PCT` and
`AV_XXX_CONSENSUS_TIME` respectively, where =XXX= is =INIT=,=MID=,=LATE= and
=STUCK=.  The effective close time position is updated using the same
thresholds.

Given the [link disputes_image example disputes above] and an initial threshold
of 50%, our node would retain its position since transaction 1 was not in
dispute and transactions 2 and 3 have 75% support.  Since its position did not
change, it would not need to send a new proposal to peers.  Peer C would not
change either. Peer A would add transaction 3 to its position and Peer B would
remove transaction 4 from its position; both would then send an updated
position.

Conversely, if the diagram reflected a later call to =timerEntry= that occurs in
the stuck region with a threshold of say 95%, our node would remove transactions
2 and 3 from its candidate set and send an updated position.  Likewise, all the
other peers would end up with only transaction 1 in their position.

Lastly, if our node were not in the proposing mode, it would not include its own
vote and just take the majority (>50%) position of its peers. In this example,
our node would maintain its position of transactions 1, 2 and 3.

['Checking Consensus]

After updating its position, the node checks for supermajority agreement with
its peers on its current position.  This agreement is of the exact transaction
set, not just the support of individual transactions. That is, if our position
is a subset of a peer's position, that counts as a disagreement. Also recall
that effective close time agreement allows a supermajority of participants
agreeing to disagree.

Consensus is declared when the following 3 clauses are true:

* `LEDGER_MIN_CONSENSUS` time has elapsed in the establish phase
* At least 75% of the prior round proposers have proposed OR this establish
  phase is `LEDGER_MIN_CONSENSUS` longer than the last round's establish phase
* =minimumConsensusPercentage= of ourself and our peers share the same position

The middle condition ensures slower peers have a chance to share positions, but
prevents waiting too long on peers that have disconnected. Additionally, a node
can declare that consensus has moved on if =minimumConsensusPercentage= peers
have sent validations and moved on to the next ledger. This outcome indicates
the node has fallen behind its peers and needs to catch up.

If a node is not proposing, it does not include its own position when
calculating the percent of agreeing participants but otherwise follows the above
logic.

['Accepting Consensus]

Once consensus is reached (or moved on), the node switches to the =Accept= phase
and signals to the implementing code that the round is complete. That code is
responsible for using the consensus transaction set to generate the next ledger
and calling =startRound= to begin the next round.  The implementation has total
freedom on ordering transactions, deciding what to do if consensus moved on,
determining whether to retry or abandon local transactions that did not make the
consensus set and updating any internal state based on the consensus progress.


[h6 Accept]

The =Accept= phase is the terminal phase of the consensus algorithm.  Calls to
=timerEntry=, =peerProposal= and =gotTxSet= will not change the internal
consensus state while in the accept phase.  The expectation is that the
application specific code is working to generate the new ledger based on the
consensus outcome. Once complete, that code should make a call to =startRound=
to kick off the next consensus round. The =startRound= call includes the new
prior ledger, prior ledger ID and whether the round should begin in the
proposing or observing mode.  After setting some initial state, the phase
transitions to =Open=.  The node will also check if the provided prior ledger
and ID are correct, updating the mode and requesting the proper ledger from the
network if necessary.

[endsect] [/Consensus Overview]

[section Consensus Type Requirements]

The consensus type requirements are given below as minimal implementation stubs.
Actual implementations would augment these stubs with members appropriate for
managing the details of transactions and ledgers within the larger application
framework.

[heading Transaction]
The transaction type =Tx= encapsulates a single transaction under consideration
by consensus.

```
struct Tx
{
   using ID = ...;
   ID const & id() const;

   //... implementation specific
};
```

[heading Transaction Set]
The transaction set type =TxSet= represents a set of [^Tx]s that are collectively
under consideration by consensus. A =TxSet= can be compared against other [^TxSet]s
(typically from peers) and can be modified to add or remove transactions via
the mutable subtype.

```
struct TxSet
{
  using Tx = Tx;
  using ID = ...;

  ID const & id() const;

  bool exists(Tx::ID const &) const;
  Tx const * find(Tx::ID const &) const ;

  // Return set of transactions that are not common with another set
  // Bool in map is true if in our set, false if in other
  std::map<Tx::ID, bool> compare(TxSet const & other) const;

  // A mutable view that allows changing transactions in the set
  struct MutableTxSet
  {
      MutableTxSet(TxSet const &);
      bool insert(Tx const &);
      bool erase(Tx::ID const &);
  };

  // Construct from a mutable view.
  TxSet(MutableTxSet const &);

  // Alternatively, if the TxSet is itself mutable
  // just alias MutableTxSet = TxSet

  //... implementation specific
};
```

[heading Ledger] The =Ledger= type represents the state shared amongst the
distributed participants.  Notice that the details of how the next ledger is
generated from the prior ledger and the consensus accepted transaction set is
not part of the interface.  Within the generic code, this type is primarily used
to know that peers are working on the same tip of the ledger chain and to
provide some basic timing data for consensus.

```
struct Ledger
{
  using ID = ...;

  ID const & id() const;

  // Sequence number that is 1 more than the parent ledger's seq()
  std::size_t seq() const;

  // Whether the ledger's close time was a non-trivial consensus result
  bool closeAgree() const;

  // The close time resolution used in determing the close time
  NetClock::duration closeTimeResolution() const;

  // The (effective) close time, based on the closeTimeResolution
  NetClock::time_point closeTime() const;

  // The parent ledger's close time
  NetClock::time_point parentCloseTime() const;

  Json::Value getJson() const;

  //... implementation specific
};
```
[heading Generic Consensus Interface]

Following the
[@https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern CRTP]
idiom, generic =Consensus= relies on a deriving class implementing a set of
helpers and callbacks that encapsulate implementation specific details of the
algorithm. Below are excerpts of the generic consensus implementation and of
helper types that will interact with the concrete implementing class.

```

// Represents our proposed position or a peer's proposed position
template <class NodeID_t, class LedgerID_t, class Position_t> class ConsensusProposal;

// Represents a transction under dispute this round
template <class Tx_t, class NodeID_t> class DisputedTx;

template <class Derived, class Traits> class Consensus
{
protected:
    enum class Mode { proposing, observing, wrongLedger, switchedLedger};

    // Measure duration of phases of consensus
    class Stopwatch
    {
    public:
        std::chrono::milliseconds read() const;
        // details omitted ...
    };

    // Initial ledger close times, not rounded by closeTimeResolution
    // Used to gauge degree of synchronization between a node and its peers
    struct CloseTimes
    {
        std::map<NetClock::time_point, int> peers;
        NetClock::time_point self;
    };

    // Encapsulates the result of consensus.
    struct Result
    {
        //! The set of transactions consensus agrees go in the ledger
        TxSet_t set;

        //! Our proposed position on transactions/close time
        Proposal_t position;

        //! Transactions which are under dispute with our peers
        using Dispute_t = DisputedTx<Tx_t, NodeID_t>;
        hash_map<typename Tx_t::ID, Dispute_t> disputes;

        // Set of TxSet ids we have already compared/created disputes
        hash_set<typename TxSet_t::ID> compares;

        // Measures the duration of the establish phase for this consensus round
        Stopwatch roundTime;

        // Indicates state in which consensus ended.  Once in the accept phase
        // will be either Yes or MovedOn
        ConsensusState state = ConsensusState::No;
    };

public:
    // Kick-off the next round of consensus.
    void startRound(
        NetClock::time_point const& now,
        typename Ledger_t::ID const& prevLedgerID,
        Ledger_t const& prevLedger,
        bool proposing);

    // Call periodically to drive consensus forward.
    void timerEntry(NetClock::time_point const& now);

    // A peer has proposed a new position, adjust our tracking.  Return true if the proposal
    // was used.
    bool peerProposal(NetClock::time_point const& now, Proposal_t const& newProposal);

    // Process a transaction set acquired from the network
    void gotTxSet(NetClock::time_point const& now, TxSet_t const& txSet);

    // ... details
};
```
[heading Adapting Generic Consensus]

The stub below shows the set of callback/helper functions required in the implementing class.

```
struct Traits
{
  using Ledger_t = Ledger;
  using TxSet_t = TxSet;
  using NodeID_t = ...; // Integer-like std::uint32_t to uniquely identify a node

};

class ConsensusImp : public Consensus<ConsensusImp, Traits>
{
    // Attempt to acquire a specific ledger from the network.
    boost::optional<Ledger> acquireLedger(Ledger::ID const & ledgerID);

    // Acquire the transaction set associated with a proposed position.
    boost::optional<TxSet> acquireTxSet(TxSet::ID const & setID);

    // Get peers' proposed positions. Returns an iterable
    // with value_type convertable to ConsensusPosition<...>
    auto const & proposals(Ledger::ID const & ledgerID);

    // Whether any transactions are in the open ledger
    bool hasOpenTransactions() const;

    // Number of proposers that have validated the given ledger
    std::size_t proposersValidated(Ledger::ID const & prevLedger) const;

    // Number of proposers that have validated a ledger descended from the
    // given ledger
    std::size_t proposersFinished(Ledger::ID const & prevLedger) const;

    // Return the ID of the last closed (and validated) ledger that the
    // application thinks consensus should use as the prior ledger.
    Ledger::ID getPrevLedger(Ledger::ID const & prevLedgerID,
                    Ledger const & prevLedger,
                    Mode mode);

    // Called when ledger closes.  Implementation should generate an initial Result
    // with position based on the current open ledger's transactions.
    Result onClose(Ledger const &, Ledger const & prev, Mode mode);

    // Called when ledger is accepted by consensus
    void onAccept(Result const & result,
      RCLCxLedger const & prevLedger,
      NetClock::duration closeResolution,
      CloseTimes const & rawCloseTimes,
      Mode const & mode);

    // Propose the position to peers.
    void propose(ConsensusProposal<...> const & pos);

    // Relay a received peer proposal on to other peer's.
    void relay(ConsensusProposal<...> const & pos);

    // Relay a disputed transaction to peers
    void relay(TxSet::Tx const & tx);

    // Realy given transaction set with peers
    void relay(TxSet const &s);

    //... implementation specific
};
```

The implementing class hides many details of the peer communication
model from the generic code.

* The =relay= member functions are responsible for sharing the given type with a
  node's peers, but are agnostic to the mechanism. Ideally, messages are delivered
  faster than =LEDGER_GRANULARITY=.
* The generic code does not specify how transactions are submitted by clients,
  propagated through the network or stored in the open ledger. Indeed, the open
  ledger is only conceptual from the perspective of the generic code---the
  initial position and transaction set are opaquely generated in a
  `Consensus::Result` instance returned from the =onClose= callback.
* The calls to =acquireLedger= and =acquireTxSet= only have non-trivial return
  if the ledger or transaction set of interest is available.  The implementing
  class is free to block while acquiring, or return the empty option while
  servicing the request asynchronously.  Due to legacy reasons, the two calls
  are not symmetric. =acquireTxSet= requires the host application to call
  =gotTxSet= when an asynchronous =acquire= completes. Conversely,
  =acquireLedger= will be called again later by the consensus code if it still
  desires the ledger with the hope that the asynchronous acquisition is
  complete.

[endsect] [/Consensus Type Requirements]

[section Validation]

Coming Soon!

[endsect] [/Validation]

[endsect] [/Consensus and Validation]