mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-19 11:15:49 +00:00
255 lines
20 KiB
HTML
255 lines
20 KiB
HTML
<!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>Transaction Cost - 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="transaction-cost">Transaction Cost</h1>
|
||
<p>In order to protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of <a href="https://ripple.com/knowledge_center/math-based-currency-2/">XRP</a>. This <em>transaction cost</em> is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.</p>
|
||
<p>Every transaction must <a href="#specifying-the-transaction-cost">specify how much XRP it will destroy</a> in order to pay the transaction cost.</p>
|
||
<h2 id="current-transaction-cost">Current Transaction Cost</h2>
|
||
<p>The current transaction cost required by the network is typically <strong>0.01 XRP</strong> (10,000 drops), although it sometimes increases due to network load.</p>
|
||
<p>You can also <a href="#querying-the-transaction-cost">query <code>rippled</code> for the current transaction cost</a>.</p>
|
||
<h2 id="beneficiaries-of-the-transaction-cost">Beneficiaries of the Transaction Cost</h2>
|
||
<p>The transaction cost is not paid to any party: the XRP is irrevocably destroyed. Since no new XRP can ever be created, this makes XRP more scarce, and consequently benefits all holders of XRP by making XRP more valuable.</p>
|
||
<h2 id="load-scaling">Load Scaling</h2>
|
||
<p>Each <code>rippled</code> server independently scales the transaction cost based on its current load. If you submit a transaction with a <code>Fee</code> value that is lower than current load-based transaction cost of the <code>rippled</code> server, that server neither applies nor relays the transaction. (<strong>Note:</strong> If you submit a transaction through an <a href="rippled-apis.html#connecting-to-rippled">admin connection</a>, the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive <a href="https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">the consensus process</a> unless its <code>Fee</code> value meets the requirements of a majority of servers.</p>
|
||
<h2 id="querying-the-transaction-cost">Querying the Transaction Cost</h2>
|
||
<p>The <code>rippled</code> APIs have two ways to query the transaction cost: the <code>server_info</code> command (intended for humans) and the <code>server_state</code> command (intended for machines).</p>
|
||
<h3 id="server-info">server_info</h3>
|
||
<p>The <a href="rippled-apis.html#server-info"><code>server_info</code> command</a> reports the unscaled minimum XRP cost, as of the previous ledger, as <code>validated_ledger.base_fee_xrp</code>, in the form of decimal XRP. The actual cost necessary to relay a transaction is scaled by multiplying that <code>base_fee_xrp</code> value by the <code>load_factor</code> parameter in the same response, which represents the server's current load level. In other words:</p>
|
||
<p><strong>Current Transaction Cost in XRP = <code>base_fee_xrp</code> × <code>load_factor</code></strong></p>
|
||
<h3 id="server-state">server_state</h3>
|
||
<p>The <a href="rippled-apis.html#server-state"><code>server_state</code> command</a> returns a direct representation of <code>rippled</code>'s internal load calculations. In this case, the effective load rate is the ratio of the current <code>load_factor</code> to the <code>load_base</code>. The <code>validated_ledger.base_fee</code> parameter reports the minimum transaction cost in <a href="rippled-apis.html#specifying-currency-amounts">drops of XRP</a>. This design enables <code>rippled</code> to calculate the transaction cost using only integer math, while still allowing a reasonable amount of fine-tuning for server load. The actual calculation of the transaction cost is as follows:</p>
|
||
<p><strong>Current Transaction Cost in Drops = (<code>base_fee</code> × <code>load_factor</code>) ÷ <code>load_base</code></strong></p>
|
||
<h2 id="specifying-the-transaction-cost">Specifying the Transaction Cost</h2>
|
||
<p>Every signed transaction must include the transaction cost in the <a href="transactions.html#common-fields"><code>Fee</code> field</a>. Like all fields of a signed transaction, this field cannot be changed without invalidating the signature.</p>
|
||
<p>As a rule, the Ripple Consensus Ledger executes transactions <em>exactly</em> as they are signed. (To do anything else would be difficult to coordinate across a decentralized consensus network, at the least.) As a consequence of this, every transaction destroys the exact amount of XRP specified by the <code>Fee</code> field, even if it is much more than the current minimum transaction cost for any part of the network. The transaction cost can even destroy XRP that would otherwise be set aside for an account's reserve requirement.</p>
|
||
<p>Before signing a transaction, we recommend <a href="#querying-the-transaction-cost">looking up the current load-based transaction cost</a>. If the transaction cost is currently high due to load scaling, you may want to wait for it to decrease. If you do not plan on submitting the transaction immediately, we recommend specifying a slightly higher transaction cost to account for future load-based fluctuations in the transaction cost.</p>
|
||
<h3 id="automatically-specifying-the-transaction-cost">Automatically Specifying the Transaction Cost</h3>
|
||
<p>When you sign a transaction online, you can omit the <code>Fee</code> field. In this case, <code>rippled</code> or ripple-lib looks up an appropriate value based on the state of the peer-to-peer network, and includes it before signing the transaction. However, there are several drawbacks and limitations to automatically filling in the transaction cost in this manner:</p>
|
||
<ul>
|
||
<li>If the network's transaction cost goes up between signing and distributing the transaction, the transaction may not be confirmed.<ul>
|
||
<li>In the worst case, the transaction may be stuck in a state of being neither definitively confirmed or rejected, unless it included a <code>LastLedgerSequence</code> parameter or until you cancel it with a new transaction that uses the same <code>Sequence</code> number. See <a href="reliable_tx.html">reliable transaction submission</a> for best practices.</li>
|
||
</ul>
|
||
</li>
|
||
<li>You do not know in advance exactly what value you are signing for the <code>Fee</code> field.<ul>
|
||
<li>If you are using <code>rippled</code>, you can also use the <code>fee_mult_max</code> parameter of the <a href="rippled-apis.html#sign"><code>sign</code> command</a> to set a limit to the load scaling you are willing to sign.</li>
|
||
</ul>
|
||
</li>
|
||
<li>You cannot look up the current transaction cost from an offline machine.</li>
|
||
</ul>
|
||
<h2 id="transaction-costs-and-failed-transactions">Transaction Costs and Failed Transactions</h2>
|
||
<p>Since the purpose of the transaction cost is to protect the peer-to-peer Ripple network from excessive load, it should apply to any transaction that gets distributed to the network, regardless of whether or not that transaction succeeds. However, in order to affect the shared global ledger, a transaction must be included in a validated ledger. Thus, <code>rippled</code> servers attempt to include failed transactions in ledgers, with <a href="transactions.html#result-categories"><code>tec</code> status codes</a> ("tec" stands for "Transaction Engine - Claimed fee only").</p>
|
||
<p>The transaction cost is only debited from the sender's XRP balance when the transaction actually becomes included in a validated ledger. This is true whether the transaction is considered successful or fails with a <code>tec</code> code.</p>
|
||
<p>If a transaction's failure is <a href="transactions.html#finality-of-results">final</a>, the <code>rippled</code> server does not relay it to the network. Consequently, that transaction does not get included in a validated ledger, and it cannot have any effect on anyone's XRP balance.</p>
|
||
<h3 id="insufficient-xrp">Insufficient XRP</h3>
|
||
<p>When a <code>rippled</code> server initially evaluates a transaction, it rejects the transaction with the error code <code>terINSUF_FEE_B</code> if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a <code>ter</code> (Retry) code, the <code>rippled</code> server retries the transaction without relaying it to the network, until the transaction's outcome is <a href="transactions.html#finality-of-results">final</a>.</p>
|
||
<p>When a transaction has already been distributed to the network, but the account does not have sufficient XRP to pay the transaction cost, the result code <code>tecINSUFF_FEE</code> occurs instead. In this case, the account pays all the XRP it can, ending with 0 XRP. This can occur because <code>rippled</code> decides whether to relay the transaction to the network based on its in-progress ledger, but transactions may be dropped or reordered when building the consensus ledger.</p>
|
||
<h2 id="key-reset-transaction">Key Reset Transaction</h2>
|
||
<p>As a special case, an account can send a <a href="transactions.html#setregularkey">SetRegularKey</a> transaction with a transaction cost of <code>0</code>, as long as the account's <a href="ripple-ledger.html#accountroot-flags">lsfPasswordSpent flag</a> is disabled. This transaction must be signed by the account's <em>master key</em>. Sending this transaction enables the lsfPasswordSpent flag.</p>
|
||
<p>This feature is designed to allow you to recover an account if the regular key is compromised, without worrying about whether the compromised account has any XRP available. This way, you can regain control of the account before you send additional XRP to it.</p>
|
||
<p>The <a href="ripple-ledger.html#accountroot-flags">lsfPasswordSpent flag</a> starts out disabled. If enabled, it gets disabled again when the account receives a <a href="transactions.html#payment">Payment</a> of XRP.</p>
|
||
<h2 id="changing-the-transaction-cost">Changing the Transaction Cost</h2>
|
||
<p>In addition to short-term scaling to account for load, the Ripple Consensus Ledger has a mechanism for changing the minimum transaction cost in order to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See <a href="fee-voting.html">Fee Voting</a> for more information.</p>
|
||
</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>
|