ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2025-11-24 04:55:52 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
a84d06b17d69754eb8af364182d5865ac35a05bc
rippled/md_test_csf_README.html
intelliot b905804594 deploy: 1f417764c3
2023-04-13 17:45:50 +00:00

172 lines
14 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>rippled: Consensus Simulation Framework</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">rippled
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Consensus Simulation Framework </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The Consensus Simulation Framework is a set of software components for describing, running and analyzing simulations of the consensus algorithm in a controlled manner. It is also used to unit test the generic Ripple consensus algorithm implementation. The framework is in its early stages, so the design and supported features are subject to change.</p>
<h1><a class="anchor" id="autotoc_md302"></a>
Overview</h1>
<p>The simulation framework focuses on simulating the core consensus and validation algorithms as a <a href="https://en.wikipedia.org/wiki/Discrete_event_simulation">discrete event simulation</a>. It is completely abstracted from the details of the XRP ledger and transactions. In the simulation, a ledger is simply a set of observed integers and transactions are single integers. The consensus process works to agree on the set of integers to include in the next ledger.</p>
<div class="image">
<img src="csf_overview.png" alt=""/>
<div class="caption">
CSF Overview</div></div>
<p>The diagram above gives a stylized overview of the components provided by the framework. These are combined by the simulation author into the simulation specification, which defines the configuration of the system and the data to collect when running the simulation. The specification includes:</p>
<ul>
<li>A collection of <a href="./Peer.h"><code>Peer</code>s</a> that represent the participants in the network, with each independently running the consensus algorithm.</li>
<li>The <code>Peer</code> trust relationships as a <code>TrustGraph</code>. This is a directed graph whose edges define what other <code>Peer</code>s a given <code>Peer</code> trusts. In other words, the set of out edges for a <code>Peer</code> in the graph correspond to the UNL of that <code>Peer</code>.</li>
<li>The network communication layer as a <code>BasicNetwork</code>. This models the overlay network topology in which messages are routed between <code>Peer</code>s. This graph topology can be configured independently from the <code>TrustGraph</code>.</li>
<li>Transaction <code>Submitter</code>s that model the submission of client transactions to the network.</li>
<li><code>Collector</code>s that aggregate, filter and analyze data from the simulation. Typically, this is used to monitor invariants or generate reports.</li>
</ul>
<p>Once specified, the simulation runs using a single <code>Scheduler</code> that manages the global clock and sequencing of activity. During the course of simulation, <code>Peer</code>s generate <code>Ledger</code>s and <code>Validation</code>s as a result of consensus, eventually fully validating the consensus history of accepted transactions. Each <code>Peer</code> also issues various <code>Event</code>s during the simulation, which are analyzed by the registered <code>Collector</code>s.</p>
<h1><a class="anchor" id="autotoc_md303"></a>
Example Simulation</h1>
<p>Below is a basic simulation we can walk through to get an understanding of the framework. This simulation is for a set of 5 validators that aren't directly connected but rely on a single hub node for communication.</p>
<div class="image">
<img src="csf_graph.png" alt=""/>
<div class="caption">
Example Sim</div></div>
<p>Each Peer has a unique transaction submitted, then runs one round of the consensus algorithm.</p>
<div class="fragment"><div class="line"> {c++}</div>
<div class="line">Sim sim;</div>
<div class="line">PeerGroup validators = sim.createGroup(5);</div>
<div class="line">PeerGroup center = sim.createGroup(1);</div>
<div class="line">PeerGroup network = validators + center;</div>
<div class="line">center[0]-&gt;runAsValidator = false;</div>
<div class="line"> </div>
<div class="line">validators.trust(validators);</div>
<div class="line">center.trust(validators);</div>
<div class="line"> </div>
<div class="line">using namespace std::chrono;</div>
<div class="line">SimDuration delay = 200ms;</div>
<div class="line">validators.connect(center, delay);</div>
<div class="line"> </div>
<div class="line">SimDurationCollector simDur;</div>
<div class="line">sim.collectors.add(simDur);</div>
<div class="line"> </div>
<div class="line">// prep round to set initial state.</div>
<div class="line">sim.run(1);</div>
<div class="line"> </div>
<div class="line">// everyone submits their own ID as a TX and relay it to peers</div>
<div class="line">for (Peer * p : validators)</div>
<div class="line"> p-&gt;submit(Tx(static_cast&lt;std::uint32_t&gt;(p-&gt;id)));</div>
<div class="line"> </div>
<div class="line">sim.run(1);</div>
<div class="line"> </div>
<div class="line">std::cout &lt;&lt; (simDur.stop - simDur.start).count() &lt;&lt; std::endl;</div>
<div class="line">assert(sim.synchronized());</div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md304"></a>
&lt;tt&gt;Sim&lt;/tt&gt; and &lt;tt&gt;PeerGroup&lt;/tt&gt;</h2>
<div class="fragment"><div class="line"> {c++}</div>
<div class="line">Sim sim;</div>
<div class="line">PeerGroup validators = sim.createGroup(5);</div>
<div class="line">PeerGroup center = sim.createGroup(1);</div>
<div class="line">PeerGroup network = validators + center;</div>
<div class="line">center[0]-&gt;runAsValidator = false;</div>
</div><!-- fragment --><p>The simulation code starts by creating a single instance of the <a href="./Sim.h"><code>Sim</code> class</a>. This class is used to manage the overall simulation and internally owns most other components, including the <code>Peer</code>s, <code>Scheduler</code>, <code>BasicNetwork</code> and <code>TrustGraph</code>. The next two lines create two differ <code>PeerGroup</code>s of size 5 and 1 . A <a href="./PeerGroup.h"><code>PeerGroup</code></a> is a convenient way for configuring a set of related peers together and internally has a vector of pointers to the <code>Peer</code>s which are owned by the <code>Sim</code>. <code>PeerGroup</code>s can be combined using <code>+/-</code> operators to configure more complex relationships of nodes as shown by <code>PeerGroup network</code>. Note that each call to <code>createGroup</code> adds that many new <code>Peer</code>s to the simulation, but does not specify any trust or network relationships for the new <code>Peer</code>s.</p>
<p>Lastly, the single <code>Peer</code> in the size 1 <code>center</code> group is switched from running as a validator (the default) to running as a tracking peer. The <a href="./Peer.h"><code>Peer</code> class</a> has a variety of configurable parameters that control how it behaves during the simulation.</p>
<h1><a class="anchor" id="autotoc_md305"></a>
&lt;tt&gt;trust&lt;/tt&gt; and &lt;tt&gt;connect&lt;/tt&gt;</h1>
<div class="fragment"><div class="line"> {c++}</div>
<div class="line">validators.trust(validators);</div>
<div class="line">center.trust(validators);</div>
<div class="line"> </div>
<div class="line">using namespace std::chrono;</div>
<div class="line">SimDuration delay = 200ms;</div>
<div class="line">validators.connect(center, delay);</div>
</div><!-- fragment --><p>Although the <code>sim</code> object has accessible instances of <a href="./TrustGraph.h">TrustGraph</a> and <a href="./BasicNetwork.h">BasicNetwork</a>, it is more convenient to manage the graphs via the <code>PeerGroup</code>s. The first two lines create a trust topology in which all <code>Peer</code>s trust the 5 validating <code>Peer</code>s. Or in the UNL perspective, all <code>Peer</code>s are configured with the same UNL listing the 5 validating <code>Peer</code>s. The two lines could've been rewritten as <code>network.trust(validators)</code>.</p>
<p>The next lines create the network communication topology. Each of the validating <code>Peer</code>s connects to the central hub <code>Peer</code> with a fixed delay of 200ms. Note that the network connections are really undirected, but are represented internally in a directed graph using edge pairs of inbound and outbound connections.</p>
<h1><a class="anchor" id="autotoc_md306"></a>
Collectors</h1>
<div class="fragment"><div class="line"> {c++}</div>
<div class="line">SimDurationCollector simDur;</div>
<div class="line">sim.collectors.add(simDur);</div>
</div><!-- fragment --><p>The next lines add a single collector to the simulation. The <code>SimDurationCollector</code> is a a simple example collector which tracks the total duration of the simulation. More generally, a collector is any class that implements <code>void on(NodeID, SimTime, Event)</code> for all <a href="./events.h">Events</a> emitted by a Peer. Events are arbitrary types used to indicate some action or change of state of a <code>Peer</code>. Other <a href="./collectors.h">existing collectors</a> measure latencies of transaction submission to validation or the rate of ledger closing and monitor any jumps in ledger history.</p>
<p>Note that the collector lifetime is independent of the simulation and is added to the simulation by reference. This is intentional, since collectors might be used across several simulations to collect more complex combinations of data. At the end of the simulation, we print out the total duration by subtracting <code>simDur</code> members.</p>
<div class="fragment"><div class="line"> {c++}</div>
<div class="line">std::cout &lt;&lt; (simDur.stop - simDur.start).count() &lt;&lt; std::endl;</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md307"></a>
Transaction submission</h1>
<div class="fragment"><div class="line"> {c++}</div>
<div class="line">// everyone submits their own ID as a TX and relay it to peers</div>
<div class="line">for (Peer * p : validators)</div>
<div class="line"> p-&gt;submit(Tx(static_cast&lt;std::uint32_t&gt;(p-&gt;id)));</div>
</div><!-- fragment --><p>In this basic example, we explicitly submit a single transaction to each validator. For larger simulations, clients can use a <a href="./submitters.h">Submitter</a> to send transactions in at fixed or random intervals to fixed or random <code>Peer</code>s.</p>
<h1><a class="anchor" id="autotoc_md308"></a>
Run</h1>
<p>The example has two calls to <code>sim.run(1)</code>. This call runs the simulation until each <code>Peer</code> has closed one additional ledger. After closing the additional ledger, the <code>Peer</code> stops participating in consensus. The first call is used to ensure a more useful prior state of all <code>Peer</code>s. After the transaction submission, the second call to <code>run</code> results in one additional ledger that accepts those transactions.</p>
<p>Alternatively, you can specify a duration to run the simulation, e.g. <code>sim.run(10s)</code> which would have <code>Peer</code>s continuously run consensus until the scheduler has elapsed 10 additional seconds. The <code>sim.scheduler.in</code> or <code>sim.scheduler.at</code> methods can schedule arbitrary code to execute at a later time in the simulation, for example removing a network connection or modifying the trust graph. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink