docs/finality-of-results.html at master · xagfans/docs · GitHub

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
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width">

    <title>Finality of Results - XAG Ledger Dev Portal</title>

    <!-- favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="assets/favicons/apple-touch-icon.png">
    <link rel="icon" type="image/png" sizes="16x16" href="assets/favicons/favicon-16x16.png">
    <link rel="icon" type="image/png" sizes="32x32" href="assets/favicons/favicon-32x32.png">
    <link rel="manifest" href="assets/favicons/site.webmanifest">
    <link rel="shortcut icon" href="favicon.ico">
    <meta name="msapplication-TileColor" content="#25A768">
    <meta name="msapplication-config" content="assets/favicons/browserconfig.xml">
    <meta name="theme-color" content="#25A768">

    <!-- jQuery -->
    <script src="assets/vendor/jquery-1.11.1.min.js"></script>

    <!-- Stylesheet -->
    <link href="assets/css/devportal.css" rel="stylesheet" />

    <!-- Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-45576805-2"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-45576805-2');
      gtag('config', 'UA-157720658-3', { 'linker': {
        'domains': ['blog.xpring.io', 'forum.xpring.io', 'xpring.io',
                    'XAGl.org', 'explorer.XAGl.org', 'testnet.XAGl.org']
        } }
      );
    </script>

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />


    <!-- syntax highlighting -->
    <link rel="stylesheet" href="assets/vendor/docco.min.css" />
    <script src="assets/vendor/highlight.min.js"></script>

    <!-- expandable code samples -->
    <script src="assets/js/expandcode.js"></script>
    <!-- multi-code selection tabs -->
    <script src="assets/js/multicodetab.js"></script>
    <script>
        $(document).ready(function() {
            $(".multicode").minitabs();
            hljs.initHighlighting();
            make_code_expandable();
        });
    </script>


</head>

<body class="xrp-ledger-dev-portal sidebar-primary lang-en ">

  <nav class="navbar fixed-top navbar-expand-lg navbar-light bg-white">
    <a href="index.html" class="navbar-brand"><img src="assets/img/logo.png" class="logo"  height="44" alt="XAG Ledger Dev Portal" /></a>
    <button class="navbar-toggler" type="button" data-toggle="slide-collapse" data-target="#navbarHolder" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse justify-content-end" id="navbarHolder">

<ul class="nav navbar-nav">
  <li class="nav-item">
    <a class="nav-link" href="dev-tools.html">Dev Tools</a>
  </li>

<li class="nav-item">
  <a class="nav-link" href="http://xagfans.com/" target="blank">BBS</a>
</li>
</ul><!-- /.navbar-nav -->

      <div class="nav navbar-nav language-selector">
        <div class="dropdown">
          <button class="btn btn-outline-secondary dropdown-toggle" type="button" id="language_selector_header_btn" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
            English
          </button>
          <div class="dropdown-menu" aria-labelledby="language_selector_header_btn">
            <a class="dropdown-item" href="/finality-of-results.html">English</a>
            <a class="dropdown-item" href="/cn/finality-of-results.html">中文</a>
          </div><!--/.dropdown-menu-->
        </div><!--/.dropdown-->
      </div><!--/.language-selector-->
    </div><!--/#navbarHolder-->
    <div class="menu-overlay"></div>
  </nav>

  <div class="container-fluid" role="document" id="main_content_wrapper">
    <div class="row">
      <!-- Right sidebar first so it's at the beginning for mobile layouts -->


      <!-- main column -->
      <main class="main col-md-7 col-lg-6 order-md-3  " role="main" id="main_content_body">
<nav class="breadcrumbs-wrap p-0 p-md-3" aria-label="breadcrumb">
  <ul class="breadcrumb bg-white">
    <li class="breadcrumb-item"><a href="index.html">Home</a></li>
    <li class="active breadcrumb-item"><a href="docs.html">Docs</a></li>
    <li class="active breadcrumb-item"><a href="concepts.html">Concepts</a></li>
    <li class="active breadcrumb-item"><a href="payment-system-basics.html">Payment System Basics</a></li>
    <li class="active breadcrumb-item"><a href="transaction-basics.html">Transaction Basics</a></li>
    <li class="active breadcrumb-item">Finality of Results</li>
  </ul>
</nav><!--/.breadcrumbs-wrap-->  <article class="pt-3 p-md-3">
    <div class="content">
        <h1 id="finality-of-results">Finality of Results</h1>
<p>The order in which transactions apply to the consensus <a href="ledgers.html">ledger</a> is not final until a ledger is closed and the exact transaction set is approved by the <a href="intro-to-consensus.html">consensus process</a>. A transaction that succeeded initially could still fail, and a transaction that failed initially could still succeed. Additionally, a transaction that was rejected by the consensus process in one round could achieve consensus in a later round.</p>
<p>A validated ledger can include successful transactions (<code>tes</code> result codes) as well as failed transactions (<code>tec</code> result codes). No transaction with any other result is included in a ledger.</p>
<p>For any other result code, it can be difficult to determine if the result is final. The following table summarizes when a transaction's outcome is final, based on the result code from submitting the transaction:</p>
<table>
<thead>
<tr>
<th align="left">Result Code</th>
<th align="left">Finality</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>tesSUCCESS</code></td>
<td align="left">Final when included in a validated ledger</td>
</tr>
<tr>
<td align="left">Any <code>tec</code> code</td>
<td align="left">Final when included in a validated ledger</td>
</tr>
<tr>
<td align="left">Any <code>tem</code> code</td>
<td align="left">Final unless the protocol changes to make the transaction valid</td>
</tr>
<tr>
<td align="left"><code>tefPAST_SEQ</code></td>
<td align="left">Final when another transaction with the same sequence number is included in a validated ledger</td>
</tr>
<tr>
<td align="left"><code>tefMAX_LEDGER</code></td>
<td align="left">Final when a validated ledger has a <a href="basic-data-types.html#ledger-index">ledger index</a> higher than the transaction's <code>LastLedgerSequence</code> field, and no validated ledger includes the transaction</td>
</tr>
</tbody>
</table>
<p>Any other transaction result is potentially not final. In that case, the transaction could still succeed or fail later, especially if conditions change such that the transaction is no longer prevented from applying. For example, trying to send a non-XAG currency to an account that does not exist yet would fail, but it could succeed if another transaction sends enough XAG to create the destination account. A server might even store a temporarily-failed, signed transaction and then successfully apply it later without asking first.</p>
<h2 id="how-can-non-final-results-change">How can non-final results change?</h2>
<p>When you initially submit a transaction, the <code>rippled</code> server tentatively applies that transaction to its current open ledger, then returns the tentative <a href="transaction-results.html">transaction results</a> from doing so. However, the transaction's final result may be very different than its tentative results, for several reasons:</p>
<ul>
<li>
<p>The transaction may be delayed until a later ledger version, or may never be included in a validated ledger. For the most part, the XAG Ledger follows a principle that all valid transactions should be processed as soon as possible. However, there are exceptions, including:</p>
<ul>
<li>
<p>If a proposed transaction has not been relayed to a majority of validators by the time a <a href="consensus.html">consensus round</a> begins, it may be postponed until the next ledger version, to give the remaining validators time to fetch the transaction and confirm that it is valid.</p>
</li>
<li>
<p>If an address sends two different transactions using the same sequence number, at most one of those transactions can become validated. If those transactions are relayed through the network in different paths, a tentatively-successful transaction that some servers saw first may end up failing because the other, conflicting transaction reached a majority of servers first.</p>
</li>
<li>
<p>To protect the network from spam, all transactions must destroy a <a href="transaction-cost.html">transaction cost</a> in XAG to be relayed throughout the XAG Ledger peer-to-peer network. If heavy load on the peer-to-peer network causes the transaction cost to increase, a transaction that tentatively succeeded may not get relayed to enough servers to achieve a consensus, or may be <a href="transaction-queue.html">queued</a> for later.</p>
</li>
<li>
<p>Temporary internet outages or delays may prevent a proposed transaction from being successfully relayed before the transaction's intended expiration, as set by the <code>LastLedgerSequence</code> field. (If the transaction does not have an expiration, then it remains valid and could succeed any amount of time later, which can be undesirable in its own way. See <a href="reliable-transaction-submission.html">Reliable Transaction Submission</a> for details.)</p>
</li>
<li>
<p>Combinations of two or more of these factors can also occur.</p>
</li>
</ul>
</li>
<li>
<p>The <a href="ledgers.html#open-closed-and-validated-ledgers">order transactions apply in a closed ledger</a> is usually different than the order those transactions were tentatively applied to a current open ledger; depending on the transactions involved, this can cause a tentatively-successful transaction to fail or a tentatively-failed transaction to succeed. Some examples include:</p>
<ul>
<li>
<p>If two transactions would each fully consume the same <a href="offers.html">Offer</a> in the <a href="decentralized-exchange.html">decentralized exchange</a>, whichever one comes first succeeds, and the other fails. Since the order in which those transactions apply may change, the one that succeeded can fail and the one that failed can succeed. Since offers can be partially executed, they could also still succeed, but to a greater or lesser extent.</p>
</li>
<li>
<p>If a <a href="cross-currency-payments.html">cross-currency payment</a> succeeds by consuming an <a href="offers.html">Offer</a> in the <a href="decentralized-exchange.html">decentralized exchange</a>, but a different transaction consumes or creates offers in the same order book, the cross-currency payment may succeed with a different exchange rate than it had when it executed tentatively. If it was a <a href="partial-payments.html">partial payment</a>, it could also deliver a different amount.</p>
</li>
<li>
<p>A <a href="payment.html">Payment transaction</a> that tentatively failed because the sender did not have enough funds may later succeed because another transaction delivering the necessary funds came first in the canonical order. The reverse is also possible: a transaction that tentatively succeeded may fail because a transaction delivering the necessary funds did not come first after being put into canonical order.</p>
</li>
</ul>
<p class="devportal-callout tip"><strong>Tip:</strong> For this reason, when running tests against the XAG Ledger, be sure to wait for a ledger close in between transactions if you have several accounts affecting the same data. If you are testing against a server in <a href="rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode">stand-alone-mode</a>, you must <a href="advance-the-ledger-in-stand-alone-mode.html">manually close the ledger</a> in such cases.</p>
</li>
</ul>

<!-- -->
<!-- -->
<!-- API object types -->
<!-- -->
<!-- -->
<!-- -->
<!-- rippled release notes links -->
    </div>
  </article>
      </main>
      <!-- Left sidebar last so it's at the end for mobile -->
      <aside class="sidebar col-md-5 col-lg-3 p-0 order-md-1" role="complementary">
<div class="tree_nav">

  <!---->
    <div class="sidenav_parent">
      <a href="concepts.html"> Concepts</a>
    </div>

  <!---->

    <!---->
    <div id="sidenav" role="tablist" aria-multiselectable="true">
        <!---->
          <div class="card">
            <div class="card-header" role="tab" id="sidenav_cat_head_2">
                <a class="collapsed sidenav_cat_toggler" role="button" data-toggle="collapse" href="#sidenav_collapse_2" aria-expanded="true" aria-controls="sidenav_collapse_2"></a>
              <h5 class="card-title">
                  <a class="sidenav_cat_title" href="introduction.html">Introduction</a>
                <!-- <a class="sidenav_cat_title" href="introduction.html">Introduction</a> -->
              </h5>
            </div><!-- /.card-header -->

            <div id="sidenav_collapse_2" class="collapse" role="tabpanel" aria-labelledby="sidenav_cat_head_2">
              <div class="card-body">
                <ul class="sidebar_pagelist">
                      <li><a class="nosubcat-page" href="XAG-ledger-overview.html">XAG Ledger Overview</a></li>
                      <li><a class="nosubcat-page" href="intro-to-consensus.html">Introduction to Consensus</a></li>
                      <li><a class="nosubcat-page" href="XAG.html">XAG</a></li>
                      <li><a class="nosubcat-page" href="software-ecosystem.html">Software Ecosystem</a></li>
                      <li><a class="nosubcat-page" href="technical-faq.html">Technical FAQ</a></li>

                </ul>
              </div><!-- /.card-body -->
            </div><!-- /#sidenav_collapse2 -->

          </div><!-- /.card -->

        <!---->
          <div class="card active">
            <div class="card-header" role="tab" id="sidenav_cat_head_8">
                <a class="sidenav_cat_toggler" role="button" data-toggle="collapse" href="#sidenav_collapse_8" aria-expanded="true" aria-controls="sidenav_collapse_8"></a>
              <h5 class="card-title">
                  <a class="sidenav_cat_title active-parent" href="payment-system-basics.html">Payment System Basics</a>
                <!-- <a class="sidenav_cat_title" href="payment-system-basics.html">Payment System Basics</a> -->
              </h5>
            </div><!-- /.card-header -->

            <div id="sidenav_collapse_8" class="collapse show" role="tabpanel" aria-labelledby="sidenav_cat_head_8">
              <div class="card-body">
                <ul class="sidebar_pagelist">
                      <li><a class="subcat-title" href="accounts.html">Accounts</a></li>

                          <li><a class="subpage" href="cryptographic-keys.html">Cryptographic Keys</a></li>
                          <li><a class="subpage" href="multi-signing.html">Multi-Signing</a></li>

                      <li><a class="nosubcat-page" href="ledgers.html">Ledgers</a></li>
                      <li><a class="subcat-title active-parent" href="transaction-basics.html">Transaction Basics</a></li>

                          <li><a class="subpage" href="transaction-cost.html">Transaction Cost</a></li>
                          <li><a class="active subpage" href="#main_content_body">Finality of Results</a></li>
                          <li><a class="subpage" href="source-and-destination-tags.html">Source and Destination Tags</a></li>


                </ul>
              </div><!-- /.card-body -->
            </div><!-- /#sidenav_collapse8 -->

          </div><!-- /.card -->

        <!---->


        <!---->
          <div class="card">
            <div class="card-header" role="tab" id="sidenav_cat_head_28">
                <a class="collapsed sidenav_cat_toggler" role="button" data-toggle="collapse" href="#sidenav_collapse_28" aria-expanded="true" aria-controls="sidenav_collapse_28"></a>
              <h5 class="card-title">
                  <a class="sidenav_cat_title" href="issued-currencies.html">Issued Currencies</a>
                <!-- <a class="sidenav_cat_title" href="issued-currencies.html">Issued Currencies</a> -->
              </h5>
            </div><!-- /.card-header -->

            <div id="sidenav_collapse_28" class="collapse" role="tabpanel" aria-labelledby="sidenav_cat_head_28">
              <div class="card-body">
                <ul class="sidebar_pagelist">
                      <li><a class="nosubcat-page" href="issued-currencies-overview.html">Issued Currencies Overview</a></li>
                      <li><a class="nosubcat-page" href="trust-lines-and-issuing.html">Trust Lines and Issuing</a></li>
                      <li><a class="nosubcat-page" href="authorized-trust-lines.html">Authorized Trust Lines</a></li>
                      <li><a class="nosubcat-page" href="freezes.html">Freezing Issued Currencies</a></li>
                      <li><a class="nosubcat-page" href="rippling.html">Rippling</a></li>
                      <li><a class="nosubcat-page" href="transfer-fees.html">Transfer Fees</a></li>
                      <li><a class="nosubcat-page" href="issuing-and-operational-addresses.html">Issuing and Operational Addresses</a></li>
                      <li><a class="nosubcat-page" href="paths.html">Paths</a></li>
                      <li><a class="nosubcat-page" href="demurrage.html">Demurrage</a></li>

                </ul>
              </div><!-- /.card-body -->
            </div><!-- /#sidenav_collapse28 -->

          </div><!-- /.card -->

        <!---->

        <!---->


        <!---->


    </div><!-- /#sidenav -->
</div><!-- /.tree_nav -->      </aside>
    </div><!--/.row (main layout)-->
  </div>


<!-- Jump to top button -->
<a href="#main_content_wrapper" class="jump-to-top btn btn-primary btn-lg" role="button" title="Jump to top of page">Top</a>
<script type="text/javascript" src="assets/js/jump-to-top.js"></script>

<!-- Non-blocking resources -->
<!-- Bootstrap JS -->
<script src="assets/vendor/bootstrap.min.js"></script>
<!-- fontawesome icons -->
<link rel="stylesheet" href="assets/vendor/fontawesome/css/font-awesome.min.css" />

<!-- Algolia DocSearch -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
apiKey: '70de5b9b8ef95460f3c6e04054b325b2',
indexName: 'XAGl',
inputSelector: '#topsearchbar',
algoliaOptions: { 'facetFilters': ["lang:en"] },
debug: false
});
</script>

<script type="application/javascript">
  gtag('set', {'content_group1': 'Content Docs'});
</script>
</body>
</html>