forked from XRPLF/xrpl-dev-portal
-
Notifications
You must be signed in to change notification settings - Fork 0
/
paths.html
315 lines (301 loc) · 19.3 KB
/
paths.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width">
<title>Paths - Ripple Developer Portal</title>
<!-- favicon -->
<link rel="icon" href="favicon.ico" type="image/x-icon">
<link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
<!-- jQuery -->
<script src="vendor/jquery-1.11.1.min.js"></script>
<!-- Bootstrap -->
<link href="css/bootstrap.min.css" rel="stylesheet">
<script src="js/bootstrap.min.js"></script>
<!-- Flatdoc theme -->
<link href='vendor/flatdoc/v/0.8.0/theme-white/style.css' rel='stylesheet'>
<script src="vendor/flatdoc/v/0.8.0/theme-white/script.js"></script>
<!-- syntax highlighting -->
<link rel="stylesheet" href="vendor/docco.min.css">
<script src="vendor/highlight.min.js"></script>
<!-- syntax selection js -->
<script src="js/multicodetab.js"></script>
<!-- Markdown content already parsed+included; just do the code tab stuff -->
<script>
$(document).ready(function() {
$().multicode_tabs_pandoc();
hljs.initHighlighting();
make_code_expandable();
});
</script>
<script src="js/expandcode.js"></script>
<script src="js/fixsidebarscroll.js"></script>
<!-- Custom Stylesheets -->
<link href="font/fonts.css" rel="stylesheet" type="text/css" />
<link href="css/main.css" rel="stylesheet" />
<link href="css/custom.css" rel="stylesheet" />
<link rel="shortcut icon" href="favicon.ico?v=2" type="image/x-icon" />
<link rel="icon" href="favicon.ico?v=2" type="image/x-icon" />
</head>
<body class='no-literate'>
<div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="./"><img class="small_logo" src="assets/img/ripple_logo_small.png"></a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="paths.html">Paths</a></li>
<li><a href="fees.html">Fees (Disambiguation)</a></li>
<li><a href="transfer_fees.html">Transfer Fees</a></li>
<li><a href="tx-cost.html">Transaction Cost</a></li>
<li><a href="fee-voting.html">Fee Voting</a></li>
<li><a href="reserves.html">Reserves</a></li>
<li><a href="freeze.html">Freeze</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ripple Consensus Ledger</a></li>
<li><a href="historical_data.html">Historical Data API</a></li>
<li><a href="charts_api.html">Ripple Charts API</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
<li><a href="rippleapi.html">RippleAPI</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
<li><a href="gateway_guide.html">Gateway Guide</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="historicaldb-api-tool.html">Historical Database API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="charts-api-tool.html">Charts API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Resources <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="https://forum.ripple.com/viewforum.php?f=2">Forums</a></li>
<li><a href="https://www.bountysource.com/teams/ripple/bounties">Bounties</a></li>
<li><a href="https://ripplelabs.atlassian.net/">Bug Tracking</a></li>
<li><a href="https://ripple.com/category/dev-blog/">Dev Blog</a></li>
<li><a href="https://ripple.com/press-releases/">Press Center</a></li>
<li><a href="https://ripple.com/brand-guidelines/">Brand Guidelines</a></li>
</ul>
<li><a href="https://github.com/ripple/ripple-dev-portal" title="GitHub">Site Source</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
<script type="text/javascript">
if (window.location.host.indexOf("github.io") > -1) {
document.write("<div style='background-color:red; color:white; position:fixed; top: 50px; right: 150px; padding: 10px 20px;'>DRAFT</div>");
}
</script>
<div class='wrapper'>
<div class='content-root'>
<div class='menubar'>
<div class='menu section' role='flatdoc-menu'>
<script type="text/javascript" src="js/jquery.gensidebar.js"></script>
<script type="text/javascript">
</script>
</div>
</div>
<div class='content'>
<h1 id="paths">Paths</h1>
<p>In the Ripple Consensus Ledger, paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver via market makers. Paths also enable complex settlement of offsetting debts.</p>
<p>A single Payment transaction in the Ripple Consensus Ledger can use multiple paths, combining liquidity from different sources to deliver the desired amount. Thus, a transaction includes a <em>path set</em>, which is a collection of possible paths to take. The paths in a path set must start and end with the same currency.</p>
<p>Since XRP can be sent directly to any address, an XRP-to-XRP transaction does not use any paths.</p>
<h2 id="path-steps">Path Steps</h2>
<p>A path is made of steps that connect the sender to the receiver of the payment. Every step is either:</p>
<ul>
<li>Rippling through another account in the same currency</li>
<li>Exchanging currency at an order book</li>
</ul>
<p>Rippling through another account is the process of moving debt around. In the typical case, this involves reducing a gateway's obligation to one party and increasing the gateway's obligation to another party. Rippling can occur between any accounts that are connected by trust lines. See <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">Understanding the NoRipple Flag</a> for more examples of rippling.</p>
<p>In the case of a currency exchange step, the path step specifies which currency to change to, but does not record the state of the orders in the order book. Since the order of transactions is not finalized until a ledger is validated, it is impossible to determine for certain which offers a transaction will execute, until after the transaction has been validated. Consequently, you cannot know in advance which offers a transaction will take: only which order books the transaction will use. (You can make an educated guess, since each transaction takes the best available offers at the time it executes in the final ledger.)</p>
<p>In both types of steps, each intermediate account gains and loses approximately equal value: either a balance ripples from a trust line to another trust line in the same currency, or they exchange currencies according to a previously-placed order. In some cases, the amounts gained and lost may not be exactly equivalent, due to <a href="https://ripple.com/knowledge_center/transfer-fees/">transfer fees</a>, trust line quality, or rounding.</p>
<p><a href="img/paths-examples.png"><img alt="Diagram of three example paths" src="img/paths-examples.png"/></a></p>
<h1 id="technical-details">Technical Details</h1>
<h2 id="pathfinding">Pathfinding</h2>
<p>The <code>rippled</code> API has two methods that can be used for pathfinding. The <a href="rippled-apis.html#ripple-path-find"><code>ripple_path_find</code> command</a> does a one-time lookup of possible path sets. The <a href="rippled-apis.html#path-find"><code>path_find</code> command</a> (WebSocket only) expands on the initial search with follow-up responses whenever a ledger closes or the server finds a better path.</p>
<p>You can have <code>rippled</code> automatically fill in paths when you sign it, by including the <code>build_path</code> field in a request to the <a href="rippled-apis.html#sign"><code>sign</code> command</a> or <a href="rippled-apis.html#sign-and-submit-mode"><code>submit</code> command (sign-and-submit mode)</a>. However, we recommend pathfinding separately and confirming the results prior to signing, in order to avoid surprises. There are no guarantees on how expensive the paths the server finds will be at the time of submission. (Although <code>rippled</code> is designed to search for the cheapest paths possible, it may not always find them. Untrustworthy <code>rippled</code> instances could also be modified to change this behavior for profit.)</p>
<p>Finding paths is a very challenging problem that changes slightly every few seconds as new ledgers are validated, so <code>rippled</code> is not designed to find the absolute best path. Still, you can find several possible paths and estimate the cost of delivering a particular amount.</p>
<h2 id="implied-steps">Implied Steps</h2>
<p>By convention, several steps of a path are implied by the <a href="transactions.html#payment">fields of the Payment transaction</a>: specifically, the <code>Account</code> (sender), <code>Destination</code> (receiver), <code>Amount</code> (currency and amount to be delivered) and <code>SendMax</code> (currency and amount to be sent, if specified). The implied steps are as follows:</p>
<ul>
<li>The first step of a path is always implied to be the sender of the transaction, as defined by the transaction's <code>Account</code> field.</li>
<li>If the transaction includes a <code>SendMax</code> field with an <code>issuer</code> that is not the sender of the transaction, that issuer is implied to be the second step of the path.<ul>
<li>If <code>issuer</code> of the <code>SendMax</code> <em>is</em> the sending account, then the path starts at the sending account, and may use any of that account's trust lines in the given currency. See <a href="transactions.html#special-issuer-values-for-sendmax-and-amount">special values for SendMax and Amount</a> for details.</li>
</ul>
</li>
<li>If the <code>Amount</code> field of the transaction includes an <code>issuer</code> that is not the same as the <code>Destination</code> of the transaction, that issuer is implied to be the second-to-last step of the path.</li>
<li>Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's <code>Destination</code> field.</li>
</ul>
<h2 id="default-paths">Default Paths</h2>
<p>In addition to any paths that are specified in the transaction, a transaction can also execute along the <em>default path</em>. The default path is the simplest possible way to connect the <a href="#implied-steps">implied steps</a> of the transaction.</p>
<p>The default path could be any of the following:</p>
<ul>
<li>If the transaction is uses only one currency (regardless of issuer), then the default path assumes the payment will ripple through the accounts involved. This path will only work if there are trust lines connecting those accounts.<ul>
<li>If <code>SendMax</code> is omitted, or the <code>issuer</code> of the <code>SendMax</code> is the sender, the default path needs a trust line from the sending <code>Account</code> to the <code>issuer</code> of the destination <code>Amount</code> in order to work.</li>
<li>If the <code>SendMax</code> and <code>Amount</code> have different <code>issuer</code> values, and neither are the sender or receiver, the default path is probably not useful because it would need to ripple across a trust line between the two issuers. Ripple, Inc. typically discourages issuers from trusting one another directly.</li>
</ul>
</li>
<li>For cross-currency transactions, the default path uses the order book between the source currency (as specified in the <code>SendMax</code> field) and the destination currency (as specified in the <code>Amount</code> field).</li>
</ul>
<p>The following diagram enumerates all possible default paths:
<a href="img/paths-default_paths.png"><img alt="Diagram of default paths" src="img/paths-default_paths.png"/></a></p>
<p>You can use the <a href="transactions.html#payment-flags"><code>tfNoDirectRipple</code> flag</a> to disable the default path. In this case, the transaction can only execute using the paths explicitly included in the transaction. Traders can use this option to take arbitrage opportunities.</p>
<h2 id="path-specifications">Path Specifications</h2>
<p>A path set is an array. Each member of the path set is another array that represents an individual <em>path</em>. Each member of a path is an object that specifies the step. A step has the following fields:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>account</td>
<td>String - Address</td>
<td>(Optional) If present, this path step represents rippling through the specified account.</td>
</tr>
<tr>
<td>currency</td>
<td>String - currency code</td>
<td>(Optional) If present, this path step represents changing currencies through an order book. The currency specified indicates the new currency.</td>
</tr>
<tr>
<td>issuer</td>
<td>String - Address</td>
<td>(Optional) If the path step represents changing currencies through an order book, this field indicates the issuer of the new currency. This field is not present when changing to XRP.</td>
</tr>
<tr>
<td>type</td>
<td>Integer</td>
<td><strong>DEPRECATED</strong> (Optional) An indicator of which other fields are present.</td>
</tr>
<tr>
<td>type_hex</td>
<td>String</td>
<td><strong>DEPRECATED</strong>: (Optional) A hexadecimal representation of the <code>type</code> field.</td>
</tr>
</tbody>
</table>
<p>The <code>type</code> field, used for the binary serialization of a path set, is actually constructed through bitwise operations on a single integer. The bits are defined as follows:</p>
<table>
<thead>
<tr>
<th>Value (Hex)</th>
<th>Value (Decimal)</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>0x01</td>
<td>1</td>
<td>A change of account (rippling): the <code>account</code> field is present.</td>
</tr>
<tr>
<td>0x10</td>
<td>16</td>
<td>A change of currency: the <code>currency</code> field is present.</td>
</tr>
<tr>
<td>0x20</td>
<td>32</td>
<td>A change of issuer: the <code>issuer</code> field is present.</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<div class="row">
<div class="col-md-3">
<h4>Documentation</h4>
<ul class="footer_links">
<li><a href="paths.html">Paths</a></li>
<li><a href="fees.html">Fees (Disambiguation)</a></li>
<li><a href="transfer_fees.html">Transfer Fees</a></li>
<li><a href="tx-cost.html">Transaction Cost</a></li>
<li><a href="fee-voting.html">Fee Voting</a></li>
<li><a href="reserves.html">Reserves</a></li>
<li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ripple Consensus Ledger</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
<li><a href="gateway_guide.html">Gateway Guide</a></li>
<li><a href="historical_data.html">Historical Data API</a></li>
<li><a href="charts_api.html">Ripple Charts API</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
<li><a href="rippleapi.html">RippleAPI</a></li>
</ul>
</div>
<div class="col-md-3">
<h4>Resources</h4>
<ul class="footer_links">
<li><a href="https://ripple.com/press-releases/">Press Center</a></li>
<li><a href="https://ripple.com/brand-guidelines/">Brand Use and Guidelines</a></li>
<li><a href="https://forum.ripple.com/viewforum.php?f=2">Forums</a></li>
<li><a href="https://ripple.com/category/dev-blog/">Dev Blog</a></li>
</ul>
</div>
<div class="col-md-3">
<h4>Ripple Projects</h4>
<ul class="footer_links">
<li><a href="https://www.rippletrade.com">Ripple Trade</a>
<li><a href="https://www.ripplecharts.com">Ripple Charts</a>
<li><a href="https://ripple.com/graph">Ripple Graph</a>
<li><a href="http://codius.org/">Codius</a>
</ul>
</div>
<div class="col-md-3">
<h4>Ripple Labs</h4>
<ul class="footer_links">
<li><a href="https://www.ripplelabs.com/wp-content/uploads/2014/10/ripple_labs_bylaws.pdf">Corporate Bylaws</a></li>
<li><a href="https://www.ripplelabs.com/wp-content/uploads/2014/09/ripple_labs_code_of_conduct1.pdf">Code of Conduct</a></li>
<li><a href="https://www.ripplelabs.com/team/">Team</a></li>
<li><a href="https://www.ripplelabs.com/careers/">Careers</a></li>
<li><a href="https://www.ripplelabs.com/investors/">Investors</a></li>
<li><a href="https://www.ripplelabs.com/advisors/">Advisors</a></li>
<li><a href="https://www.ripplelabs.com/xrp-distribution/">XRP Distribution</a></li>
<li><a href="https://www.ripplelabs.com/contact/">Contact</a></li>
</ul>
</div>
</div>
</div>
</footer>
</body>
</html>