mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-21 12:15:50 +00:00
reorg - great file renaming
This commit is contained in:
mDuo13
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -118,13 +124,13 @@
|
|||||||
<div id="cont">
|
<div id="cont">
|
||||||
<ul id="dev_nav_sidebar">
|
<ul id="dev_nav_sidebar">
|
||||||
<li class="level-1">Concepts</li>
|
<li class="level-1">Concepts</li>
|
||||||
<li class="level-2"><a href="paths.html">Paths</a></li>
|
<li class="level-2"><a href="concept-paths.html">Paths</a></li>
|
||||||
<li class="level-2"><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li class="level-2"><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li class="level-2"><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li class="level-2"><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li class="level-2"><a href="tx-cost.html">Transaction Cost</a></li>
|
<li class="level-2"><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li class="level-2"><a href="fee-voting.html">Fee Voting</a></li>
|
<li class="level-2"><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
<li class="level-2"><a href="reserves.html">Reserves</a></li>
|
<li class="level-2"><a href="concept-reserves.html">Reserves</a></li>
|
||||||
<li class="level-2"><a href="freeze.html">Freeze</a></li>
|
<li class="level-2"><a href="concept-freeze.html">Freeze</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
@@ -132,8 +138,8 @@
|
|||||||
<main class="main" role="main">
|
<main class="main" role="main">
|
||||||
<div class='content'>
|
<div class='content'>
|
||||||
<h1 id="fee-voting">Fee Voting</h1>
|
<h1 id="fee-voting">Fee Voting</h1>
|
||||||
<p>Validators can vote for changes to basic <a href="tx-cost.html">transaction cost</a> as well as <a href="reserves.html">reserve requirements</a>. If the preferences in a validator's configuration are different than the network's current settings, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a change that takes effect thereafter. Validators may do this for various reasons, especially to reflect long-term changes in the value of XRP.</p>
|
<p>Validators can vote for changes to basic <a href="concept-transaction-cost.html">transaction cost</a> as well as <a href="concept-reserves.html">reserve requirements</a>. If the preferences in a validator's configuration are different than the network's current settings, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a change that takes effect thereafter. Validators may do this for various reasons, especially to reflect long-term changes in the value of XRP.</p>
|
||||||
<p>Operators of <a href="rippled-setup.html#running-a-validator"><code>rippled</code> validators</a> can set their preferences for the transaction cost and reserve requirements in the <code>[voting]</code> stanza of the <code>rippled.cfg</code> file. <strong>Caution:</strong> insufficient requirements could expose the Ripple peer-to-peer network to denial-of-service attacks. The parameters you can set are as follows:</p>
|
<p>Operators of <a href="tutorial-rippled-setup.html#running-a-validator"><code>rippled</code> validators</a> can set their preferences for the transaction cost and reserve requirements in the <code>[voting]</code> stanza of the <code>rippled.cfg</code> file. <strong>Caution:</strong> insufficient requirements could expose the Ripple peer-to-peer network to denial-of-service attacks. The parameters you can set are as follows:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -163,7 +169,7 @@
|
|||||||
<h3 id="voting-process">Voting Process</h3>
|
<h3 id="voting-process">Voting Process</h3>
|
||||||
<p>Every 256th ledger is called a "flag" ledger. (A flag ledger is defined such that the <code>ledger_index</code> <a href="https://en.wikipedia.org/wiki/Modulo_operation">modulo</a> <code>256</code> is equal to <code>0</code>.) In the ledger immediately before the flag ledger, each validator whose account reserve or transaction cost preferences are different than the current network setting distributes a "vote" message alongside its ledger validation, indicating the values that validator prefers.</p>
|
<p>Every 256th ledger is called a "flag" ledger. (A flag ledger is defined such that the <code>ledger_index</code> <a href="https://en.wikipedia.org/wiki/Modulo_operation">modulo</a> <code>256</code> is equal to <code>0</code>.) In the ledger immediately before the flag ledger, each validator whose account reserve or transaction cost preferences are different than the current network setting distributes a "vote" message alongside its ledger validation, indicating the values that validator prefers.</p>
|
||||||
<p>In the flag ledger itself, nothing happens, but validators receive and take note of the votes from other validators they trust. </p>
|
<p>In the flag ledger itself, nothing happens, but validators receive and take note of the votes from other validators they trust. </p>
|
||||||
<p>After counting the votes of other validators, each validator attempts to compromise between its own preferences and the preferences of a majority of validators it trusts. (For example, if one validator wants to raise the minimum transaction cost from 10 to 100, but most validators only want to raise it from 10 to 20, the one validator settles on the change to raise the cost to 20. However, the one validator never settles on a value lower than 10 or higher than 100.) If a compromise is possible, the validator inserts a <a href="transactions.html#setfee">SetFee pseudo-transaction</a> into its proposal for the ledger following the flag ledger. Other validators who want the same change insert an identical SetFee pseudo-transaction into their proposals for the same ledger. (Validators whose preferences match the existing network settings do nothing.) If a SetFee psuedo-transaction survives the consensus process to be included in a validated ledger, then the new transaction cost and reserve settings denoted by the SetFee pseudo-transaction take effect starting with the following ledger.</p>
|
<p>After counting the votes of other validators, each validator attempts to compromise between its own preferences and the preferences of a majority of validators it trusts. (For example, if one validator wants to raise the minimum transaction cost from 10 to 100, but most validators only want to raise it from 10 to 20, the one validator settles on the change to raise the cost to 20. However, the one validator never settles on a value lower than 10 or higher than 100.) If a compromise is possible, the validator inserts a <a href="reference-transaction-format.html#setfee">SetFee pseudo-transaction</a> into its proposal for the ledger following the flag ledger. Other validators who want the same change insert an identical SetFee pseudo-transaction into their proposals for the same ledger. (Validators whose preferences match the existing network settings do nothing.) If a SetFee psuedo-transaction survives the consensus process to be included in a validated ledger, then the new transaction cost and reserve settings denoted by the SetFee pseudo-transaction take effect starting with the following ledger.</p>
|
||||||
<p>In short:</p>
|
<p>In short:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li><strong>Flag ledger -1</strong>: Validators submit votes.</li>
|
<li><strong>Flag ledger -1</strong>: Validators submit votes.</li>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -118,13 +124,13 @@
|
|||||||
<div id="cont">
|
<div id="cont">
|
||||||
<ul id="dev_nav_sidebar">
|
<ul id="dev_nav_sidebar">
|
||||||
<li class="level-1">Concepts</li>
|
<li class="level-1">Concepts</li>
|
||||||
<li class="level-2"><a href="paths.html">Paths</a></li>
|
<li class="level-2"><a href="concept-paths.html">Paths</a></li>
|
||||||
<li class="level-2"><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li class="level-2"><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li class="level-2"><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li class="level-2"><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li class="level-2"><a href="tx-cost.html">Transaction Cost</a></li>
|
<li class="level-2"><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li class="level-2"><a href="fee-voting.html">Fee Voting</a></li>
|
<li class="level-2"><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
<li class="level-2"><a href="reserves.html">Reserves</a></li>
|
<li class="level-2"><a href="concept-reserves.html">Reserves</a></li>
|
||||||
<li class="level-2"><a href="freeze.html">Freeze</a></li>
|
<li class="level-2"><a href="concept-freeze.html">Freeze</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
@@ -133,11 +139,11 @@
|
|||||||
<div class='content'>
|
<div class='content'>
|
||||||
<h1 id="fees-disambiguation">Fees (Disambiguation)</h1>
|
<h1 id="fees-disambiguation">Fees (Disambiguation)</h1>
|
||||||
<p>The Ripple Consensus Ledger is a decentralized ledger, secured by cryptography, and operated by a distributed peer-to-peer network of servers. This means that no one party, not even the Ripple, Inc., can charge a fee for access to the network.</p>
|
<p>The Ripple Consensus Ledger is a decentralized ledger, secured by cryptography, and operated by a distributed peer-to-peer network of servers. This means that no one party, not even the Ripple, Inc., can charge a fee for access to the network.</p>
|
||||||
<p>However, the rules of the Ripple Consensus Ledger include several types of fees, including the <a href="tx-cost.html"><em>transaction cost</em></a> and <a href="reserves.html"><em>reserve requirement</em></a>, which protect the ledger against abuse. (These neutral fees are not paid to anyone.) There are also several optional ways that users of the Consensus Ledger can collect fees from each other, both inside and outside the Ripple Consensus Ledger.</p>
|
<p>However, the rules of the Ripple Consensus Ledger include several types of fees, including the <a href="concept-transaction-cost.html"><em>transaction cost</em></a> and <a href="concept-reserves.html"><em>reserve requirement</em></a>, which protect the ledger against abuse. (These neutral fees are not paid to anyone.) There are also several optional ways that users of the Consensus Ledger can collect fees from each other, both inside and outside the Ripple Consensus Ledger.</p>
|
||||||
<h2 id="in-the-ledger">In the Ledger</h2>
|
<h2 id="in-the-ledger">In the Ledger</h2>
|
||||||
<p>The <em><strong>transaction cost</strong></em> (sometimes called the transaction fee) is a miniscule amount of XRP destroyed in order to send a transaction. This cost scales with the load of the network, which protects the peer-to-peer network from spam. See <a href="tx-cost.html">Transaction Cost</a> for more information.</p>
|
<p>The <em><strong>transaction cost</strong></em> (sometimes called the transaction fee) is a miniscule amount of XRP destroyed in order to send a transaction. This cost scales with the load of the network, which protects the peer-to-peer network from spam. See <a href="concept-transaction-cost.html">Transaction Cost</a> for more information.</p>
|
||||||
<p>The <em><strong>account reserve</strong></em> is a minimum amount of XRP that an account must possess. It scales with the number of objects the account owns in the ledger. This disincentivizes users from increasing the size of the ledger needlessly. See <a href="reserves.html">Reserves</a> for more information.</p>
|
<p>The <em><strong>account reserve</strong></em> is a minimum amount of XRP that an account must possess. It scales with the number of objects the account owns in the ledger. This disincentivizes users from increasing the size of the ledger needlessly. See <a href="concept-reserves.html">Reserves</a> for more information.</p>
|
||||||
<p><em><strong>Transfer fees</strong></em> are optional percentage fees that gateways can charge to transfer the currencies they issue to other accounts within the Ripple Consensus Ledger. See <a href="https://ripple.com/knowledge_center/transfer-fees/">Transfer Fees</a> for more information.</p>
|
<p><em><strong>Transfer fees</strong></em> are optional percentage fees that gateways can charge to transfer the currencies they issue to other accounts within the Ripple Consensus Ledger. See <a href="concept-transfer-fees.html">Transfer Fees</a> for more information.</p>
|
||||||
<p><em><strong>Trust line quality</strong></em> is a setting that allows an account to value balances on a trust line at higher or lower than face value. This can lead to situations that are similar to charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line.</p>
|
<p><em><strong>Trust line quality</strong></em> is a setting that allows an account to value balances on a trust line at higher or lower than face value. This can lead to situations that are similar to charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line.</p>
|
||||||
<h2 id="outside-the-ledger">Outside the Ledger</h2>
|
<h2 id="outside-the-ledger">Outside the Ledger</h2>
|
||||||
<p>While the above values are the only fees built into the Ripple Consensus Ledger, people can still invent ways to charge fees associated with the ledger. A common example is withdrawal or deposit fees charged by gateways, which are assessed when you use the gateway to get money into or out of the Ripple Consensus Ledger. This may cover the costs of transferring balances on traditional payment rails, or it may be in addition to those costs.</p>
|
<p>While the above values are the only fees built into the Ripple Consensus Ledger, people can still invent ways to charge fees associated with the ledger. A common example is withdrawal or deposit fees charged by gateways, which are assessed when you use the gateway to get money into or out of the Ripple Consensus Ledger. This may cover the costs of transferring balances on traditional payment rails, or it may be in addition to those costs.</p>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -118,13 +124,13 @@
|
|||||||
<div id="cont">
|
<div id="cont">
|
||||||
<ul id="dev_nav_sidebar">
|
<ul id="dev_nav_sidebar">
|
||||||
<li class="level-1">Concepts</li>
|
<li class="level-1">Concepts</li>
|
||||||
<li class="level-2"><a href="paths.html">Paths</a></li>
|
<li class="level-2"><a href="concept-paths.html">Paths</a></li>
|
||||||
<li class="level-2"><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li class="level-2"><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li class="level-2"><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li class="level-2"><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li class="level-2"><a href="tx-cost.html">Transaction Cost</a></li>
|
<li class="level-2"><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li class="level-2"><a href="fee-voting.html">Fee Voting</a></li>
|
<li class="level-2"><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
<li class="level-2"><a href="reserves.html">Reserves</a></li>
|
<li class="level-2"><a href="concept-reserves.html">Reserves</a></li>
|
||||||
<li class="level-2"><a href="freeze.html">Freeze</a></li>
|
<li class="level-2"><a href="concept-freeze.html">Freeze</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
@@ -146,21 +152,21 @@
|
|||||||
<li>Payments can still occur directly between the two parties of the frozen trust line.</li>
|
<li>Payments can still occur directly between the two parties of the frozen trust line.</li>
|
||||||
<li>The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen issuances directly to the issuer.</li>
|
<li>The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen issuances directly to the issuer.</li>
|
||||||
<li>The counterparty can still receive payments from others on the frozen trust line.</li>
|
<li>The counterparty can still receive payments from others on the frozen trust line.</li>
|
||||||
<li>The counterparty's offers to sell the currency issued on the frozen trust line are <a href="transactions.html#lifecycle-of-an-offer">considered unfunded</a>.</li>
|
<li>The counterparty's offers to sell the currency issued on the frozen trust line are <a href="reference-transaction-format.html#lifecycle-of-an-offer">considered unfunded</a>.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>A gateway can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the gateway's terms of use. The gateway should also freeze the counterparty in any other systems the gateway operates that are connected to the Ripple Consensus Ledger. (Otherwise, an account might still be able to engage in undesired activity by sending payments through the gateway.)</p>
|
<p>A gateway can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the gateway's terms of use. The gateway should also freeze the counterparty in any other systems the gateway operates that are connected to the Ripple Consensus Ledger. (Otherwise, an account might still be able to engage in undesired activity by sending payments through the gateway.)</p>
|
||||||
<p>An individual account can freeze its trust line to a gateway. This has no effect on transactions between the gateway and other users. It does, however, prevent other accounts, including <a href="gateway_guide.html#hot-and-cold-wallets">hot wallets</a>, from sending that gateway's issued currency to the individual account. This type of individual freeze has no effect on offers.</p>
|
<p>An individual account can freeze its trust line to a gateway. This has no effect on transactions between the gateway and other users. It does, however, prevent other accounts, including <a href="concept-issuing-and-operational-accounts.html">operational accounts</a>, from sending that gateway's issued currency to the individual account. This type of individual freeze has no effect on offers.</p>
|
||||||
<p>The Individual Freeze applies to a single currency only. In order to freeze multiple currencies with a particular counterparty, the account must enable Individual Freeze on the trust lines for each currency individually.</p>
|
<p>The Individual Freeze applies to a single currency only. In order to freeze multiple currencies with a particular counterparty, the account must enable Individual Freeze on the trust lines for each currency individually.</p>
|
||||||
<p>An account cannot enable the Individual Freeze setting if it has previously enabled the <a href="#no-freeze">No Freeze</a> setting.</p>
|
<p>An account cannot enable the Individual Freeze setting if it has previously enabled the <a href="#no-freeze">No Freeze</a> setting.</p>
|
||||||
<h2 id="global-freeze">Global Freeze</h2>
|
<h2 id="global-freeze">Global Freeze</h2>
|
||||||
<p>The <strong>Global Freeze</strong> feature is a setting on an account. When an issuing account enables the Global Freeze feature, the following rules apply:</p>
|
<p>The <strong>Global Freeze</strong> feature is a setting on an account. When an issuing account enables the Global Freeze feature, the following rules apply:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>All counterparties of the frozen issuing account can no longer decrease the balances in their trust lines to the frozen account, except in direct payments to the issuer. (This also affects any <a href="gateway_guide.html#hot-and-cold-wallets">hot wallet</a> accounts.)</li>
|
<li>All counterparties of the frozen issuing account can no longer decrease the balances in their trust lines to the frozen account, except in direct payments to the issuer. (This also affects any <a href="concept-issuing-and-operational-accounts.html">operational accounts</a>.)</li>
|
||||||
<li>Counterparties of the frozen issuing account can still send and receive payments directly to and from the issuing account.</li>
|
<li>Counterparties of the frozen issuing account can still send and receive payments directly to and from the issuing account.</li>
|
||||||
<li>All offers to sell currencies issued by the frozen account are <a href="transactions.html#lifecycle-of-an-offer">considered unfunded</a>.</li>
|
<li>All offers to sell currencies issued by the frozen account are <a href="reference-transaction-format.html#lifecycle-of-an-offer">considered unfunded</a>.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>It can be useful to enable Global Freeze on a gateway's <a href="gateway_guide.html#hot-and-cold-wallets">cold wallet</a> if a hot wallet is compromised, or immediately after regaining control of a compromised issuing account. This stops the flow of funds, preventing attackers from getting away with any more money or at least making it easier to track what happened. In addition to enacting a Global Freeze in the Ripple Consensus Ledger, a financial institution should also suspend activities in its connectors to outside systems.</p>
|
<p>It can be useful to enable Global Freeze on a gateway's <a href="concept-issuing-and-operational-accounts.html">issuing account</a> if an operational account is compromised, or immediately after regaining control of a compromised issuing account. This stops the flow of funds, preventing attackers from getting away with any more money or at least making it easier to track what happened. In addition to enacting a Global Freeze in the Ripple Consensus Ledger, a financial institution should also suspend activities in its connectors to outside systems.</p>
|
||||||
<p>It can also be useful to enable Global Freeze if a gateway intends to migrate its cold wallet to a new Ripple account, or if the gateway intends to cease doing business. This locks the funds at a specific point in time, so users cannot trade them away for other currencies.</p>
|
<p>It can also be useful to enable Global Freeze if a gateway intends to migrate to a new <a href="concept-issuing-and-operational-accounts.html">issuing account</a>, or if the gateway intends to cease doing business. This locks the funds at a specific point in time, so users cannot trade them away for other currencies.</p>
|
||||||
<p>Global Freeze applies to <em>all</em> currencies issued and held by the account. You cannot enable Global Freeze for only one currency. If you want to have the ability to freeze some currencies and not others, you should use different accounts for each currency.</p>
|
<p>Global Freeze applies to <em>all</em> currencies issued and held by the account. You cannot enable Global Freeze for only one currency. If you want to have the ability to freeze some currencies and not others, you should use different accounts for each currency.</p>
|
||||||
<p>An account can always enable the Global Freeze setting. However, if the account has previously enabled the <a href="#no-freeze">No Freeze</a> setting, it can never <em>disable</em> Global Freeze.</p>
|
<p>An account can always enable the Global Freeze setting. However, if the account has previously enabled the <a href="#no-freeze">No Freeze</a> setting, it can never <em>disable</em> Global Freeze.</p>
|
||||||
<h2 id="no-freeze">No Freeze</h2>
|
<h2 id="no-freeze">No Freeze</h2>
|
||||||
@@ -171,11 +177,11 @@
|
|||||||
</ul>
|
</ul>
|
||||||
<p>The Ripple Consensus Ledger cannot force a gateway to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to <em>disable</em> a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers.</p>
|
<p>The Ripple Consensus Ledger cannot force a gateway to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to <em>disable</em> a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers.</p>
|
||||||
<p>The No Freeze setting applies to all currencies issued to and from an account. If you want to be able to freeze some currencies but not others, you should use different accounts for each currency.</p>
|
<p>The No Freeze setting applies to all currencies issued to and from an account. If you want to be able to freeze some currencies but not others, you should use different accounts for each currency.</p>
|
||||||
<p>You can only enable the No Freeze setting with a transaction signed by your account's master key. You cannot use a <a href="transactions.html#setregularkey">Regular Key</a> or a <a href="https://wiki.ripple.com/Multisign">multi-signed transaction</a> to enable No Freeze.</p>
|
<p>You can only enable the No Freeze setting with a transaction signed by your account's master key. You cannot use a <a href="reference-transaction-format.html#setregularkey">Regular Key</a> or a <a href="https://wiki.ripple.com/Multisign">multi-signed transaction</a> to enable No Freeze.</p>
|
||||||
<h1 id="technical-details">Technical Details</h1>
|
<h1 id="technical-details">Technical Details</h1>
|
||||||
<h2 id="enabling-or-disabling-individual-freeze">Enabling or Disabling Individual Freeze</h2>
|
<h2 id="enabling-or-disabling-individual-freeze">Enabling or Disabling Individual Freeze</h2>
|
||||||
<h3 id="using-rippled">Using <code>rippled</code></h3>
|
<h3 id="using-rippled">Using <code>rippled</code></h3>
|
||||||
<p>To enable or disable Individual Freeze on a specific trust line, send a <code>TrustSet</code> transaction. Use the <a href="transactions.html#trustset-flags"><code>tfSetFreeze</code> flag</a> to enable a freeze, and the <code>tfClearFreeze</code> flag to disable it. The fields of the transaction should be as follows:</p>
|
<p>To enable or disable Individual Freeze on a specific trust line, send a <code>TrustSet</code> transaction. Use the <a href="reference-transaction-format.html#trustset-flags"><code>tfSetFreeze</code> flag</a> to enable a freeze, and the <code>tfClearFreeze</code> flag to disable it. The fields of the transaction should be as follows:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -222,8 +228,8 @@
|
|||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>Set the <code>Fee</code>, <code>Sequence</code>, and <code>LastLedgerSequence</code> parameters <a href="transactions.html#signing-and-sending-transactions">in the typical way</a>.</p>
|
<p>Set the <code>Fee</code>, <code>Sequence</code>, and <code>LastLedgerSequence</code> parameters <a href="reference-transaction-format.html#signing-and-sending-transactions">in the typical way</a>.</p>
|
||||||
<p>Example of submitting a TrustSet transaction to enable an individual freeze using the <a href="rippled-apis.html#websocket-api">WebSocket API</a>:</p>
|
<p>Example of submitting a TrustSet transaction to enable an individual freeze using the <a href="reference-rippled.html#websocket-api">WebSocket API</a>:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"id": 12,
|
"id": 12,
|
||||||
"command": "submit",
|
"command": "submit",
|
||||||
@@ -247,7 +253,7 @@
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p>(<strong>Reminder</strong>: Never transmit your account secret to an untrusted server or over an insecure channel.)</p>
|
<p>(<strong>Reminder</strong>: Never transmit your account secret to an untrusted server or over an insecure channel.)</p>
|
||||||
<h3 id="using-rippleapi">Using RippleAPI</h3>
|
<h3 id="using-rippleapi">Using RippleAPI</h3>
|
||||||
<p>To enable or disable Individual Freeze on a specific trust line, prepare a <em>Trustline</em> transaction using the <a href="rippleapi.html#preparetrustline">prepareTrustline</a> method. The fields of the <code>trustline</code> parameter should be set as follows:</p>
|
<p>To enable or disable Individual Freeze on a specific trust line, prepare a <em>Trustline</em> transaction using the <a href="reference-rippleapi.html#preparetrustline">prepareTrustline</a> method. The fields of the <code>trustline</code> parameter should be set as follows:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -260,12 +266,12 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>currency</td>
|
<td>currency</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>The <a href="rippleapi.html#currency">currency</a> of the trust line to freeze</td>
|
<td>The <a href="reference-rippleapi.html#currency">currency</a> of the trust line to freeze</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>counterparty</td>
|
<td>counterparty</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>The <a href="rippleapi.html#ripple-address">Ripple address</a> of the counterparty</td>
|
<td>The <a href="reference-rippleapi.html#ripple-address">Ripple address</a> of the counterparty</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>limit</td>
|
<td>limit</td>
|
||||||
@@ -279,7 +285,7 @@
|
|||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>The rest of the <a href="rippleapi.html#transaction-flow">transaction flow</a> is the same as any other transaction.</p>
|
<p>The rest of the <a href="reference-rippleapi.html#transaction-flow">transaction flow</a> is the same as any other transaction.</p>
|
||||||
<p>Example JavaScript (ECMAScript 6) code to enable Individual Freeze on a trust line:</p>
|
<p>Example JavaScript (ECMAScript 6) code to enable Individual Freeze on a trust line:</p>
|
||||||
<pre><code class="js">const {RippleAPI} = require('ripple-lib');
|
<pre><code class="js">const {RippleAPI} = require('ripple-lib');
|
||||||
|
|
||||||
@@ -341,8 +347,8 @@ api.connect().then(() => {
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<h2 id="enabling-or-disabling-global-freeze">Enabling or Disabling Global Freeze</h2>
|
<h2 id="enabling-or-disabling-global-freeze">Enabling or Disabling Global Freeze</h2>
|
||||||
<h3 id="using-rippled-1">Using <code>rippled</code></h3>
|
<h3 id="using-rippled-1">Using <code>rippled</code></h3>
|
||||||
<p>To enable Global Freeze on an account, send an <code>AccountSet</code> transaction with the <a href="transactions.html#accountset-flags">asfGlobalFreeze flag value</a> in the <code>SetFlag</code> field. To disable Global Freeze, put the asfGlobalFreeze flag value in the <code>ClearFlag</code> field instead.</p>
|
<p>To enable Global Freeze on an account, send an <code>AccountSet</code> transaction with the <a href="reference-transaction-format.html#accountset-flags">asfGlobalFreeze flag value</a> in the <code>SetFlag</code> field. To disable Global Freeze, put the asfGlobalFreeze flag value in the <code>ClearFlag</code> field instead.</p>
|
||||||
<p>Example of submitting an AccountSet transaction to enable Global Freeze using the <a href="rippled-apis.html#websocket-api">WebSocket API</a>:</p>
|
<p>Example of submitting an AccountSet transaction to enable Global Freeze using the <a href="reference-rippled.html#websocket-api">WebSocket API</a>:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"id": 12,
|
"id": 12,
|
||||||
"command": "submit",
|
"command": "submit",
|
||||||
@@ -362,7 +368,7 @@ api.connect().then(() => {
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p>(<strong>Reminder</strong>: Never transmit your account secret to an untrusted server or over an insecure channel.)</p>
|
<p>(<strong>Reminder</strong>: Never transmit your account secret to an untrusted server or over an insecure channel.)</p>
|
||||||
<h3 id="using-rippleapi-1">Using RippleAPI</h3>
|
<h3 id="using-rippleapi-1">Using RippleAPI</h3>
|
||||||
<p>To enable or disable Global Freeze on an account, prepare a <strong>Settings</strong> transaction using the <a href="rippleapi.html#preparesettings">prepareSettings</a> method. The <code>settings</code> parameter should be an object set as follows:</p>
|
<p>To enable or disable Global Freeze on an account, prepare a <strong>Settings</strong> transaction using the <a href="reference-rippleapi.html#preparesettings">prepareSettings</a> method. The <code>settings</code> parameter should be an object set as follows:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -379,7 +385,7 @@ api.connect().then(() => {
|
|||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>The rest of the <a href="rippleapi.html#transaction-flow">transaction flow</a> is the same as any other transaction.</p>
|
<p>The rest of the <a href="reference-rippleapi.html#transaction-flow">transaction flow</a> is the same as any other transaction.</p>
|
||||||
<p>Example JavaScript (ECMAScript 6) code to enable Global Freeze on an account:</p>
|
<p>Example JavaScript (ECMAScript 6) code to enable Global Freeze on an account:</p>
|
||||||
<pre><code class="js">const {RippleAPI} = require('ripple-lib');
|
<pre><code class="js">const {RippleAPI} = require('ripple-lib');
|
||||||
|
|
||||||
@@ -421,8 +427,8 @@ api.connect().then(() => {
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<h2 id="enabling-no-freeze">Enabling No Freeze</h2>
|
<h2 id="enabling-no-freeze">Enabling No Freeze</h2>
|
||||||
<h3 id="using-rippled-2">Using <code>rippled</code></h3>
|
<h3 id="using-rippled-2">Using <code>rippled</code></h3>
|
||||||
<p>To enable No Freeze on an account, send an <code>AccountSet</code> transaction with the <a href="transactions.html#accountset-flags">asfNoFreeze flag value</a> in the <code>SetFlag</code> field. You must sign this transaction using the master key. Once enabled, you cannot disable No Freeze.</p>
|
<p>To enable No Freeze on an account, send an <code>AccountSet</code> transaction with the <a href="reference-transaction-format.html#accountset-flags">asfNoFreeze flag value</a> in the <code>SetFlag</code> field. You must sign this transaction using the master key. Once enabled, you cannot disable No Freeze.</p>
|
||||||
<p>Example of submitting an AccountSet transaction to enable No Freeze using the <a href="rippled-apis.html#websocket-api">WebSocket API</a>:</p>
|
<p>Example of submitting an AccountSet transaction to enable No Freeze using the <a href="reference-rippled.html#websocket-api">WebSocket API</a>:</p>
|
||||||
<p>WebSocket request:</p>
|
<p>WebSocket request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"id": 12,
|
"id": 12,
|
||||||
@@ -443,7 +449,7 @@ api.connect().then(() => {
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p>(<strong>Reminder</strong>: Never transmit your account secret to an untrusted server or over an insecure channel.)</p>
|
<p>(<strong>Reminder</strong>: Never transmit your account secret to an untrusted server or over an insecure channel.)</p>
|
||||||
<h3 id="using-rippleapi-2">Using RippleAPI</h3>
|
<h3 id="using-rippleapi-2">Using RippleAPI</h3>
|
||||||
<p>To enable No Freeze on an account, prepare a <strong>Settings</strong> transaction using the <a href="rippleapi.html#preparesettings">prepareSettings</a> method. Once enabled, you cannot disable No Freeze. The <code>settings</code> parameter should be an object set as follows:</p>
|
<p>To enable No Freeze on an account, prepare a <strong>Settings</strong> transaction using the <a href="reference-rippleapi.html#preparesettings">prepareSettings</a> method. Once enabled, you cannot disable No Freeze. The <code>settings</code> parameter should be an object set as follows:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -460,7 +466,7 @@ api.connect().then(() => {
|
|||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>You must <a href="rippleapi.html#sign">sign</a> this transaction using the master key. The rest of the <a href="rippleapi.html#transaction-flow">transaction flow</a> is the same as any other transaction.</p>
|
<p>You must <a href="reference-rippleapi.html#sign">sign</a> this transaction using the master key. The rest of the <a href="reference-rippleapi.html#transaction-flow">transaction flow</a> is the same as any other transaction.</p>
|
||||||
<p>Example JavaScript (ECMAScript 6) code to enable No Freeze on an account:</p>
|
<p>Example JavaScript (ECMAScript 6) code to enable No Freeze on an account:</p>
|
||||||
<pre><code class="js">const {RippleAPI} = require('ripple-lib');
|
<pre><code class="js">const {RippleAPI} = require('ripple-lib');
|
||||||
|
|
||||||
@@ -501,7 +507,7 @@ api.connect().then(() => {
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<h2 id="checking-for-individual-freeze">Checking for Individual Freeze</h2>
|
<h2 id="checking-for-individual-freeze">Checking for Individual Freeze</h2>
|
||||||
<h3 id="using-rippled-3">Using <code>rippled</code></h3>
|
<h3 id="using-rippled-3">Using <code>rippled</code></h3>
|
||||||
<p>To see if a trust line has an Individual Freeze enabled, use the <a href="rippled-apis.html#account-lines"><code>account_lines</code> method</a> with the following parameters:</p>
|
<p>To see if a trust line has an Individual Freeze enabled, use the <a href="reference-rippled.html#account-lines"><code>account_lines</code> method</a> with the following parameters:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -541,12 +547,12 @@ api.connect().then(() => {
|
|||||||
<tr>
|
<tr>
|
||||||
<td>freeze</td>
|
<td>freeze</td>
|
||||||
<td>Boolean</td>
|
<td>Boolean</td>
|
||||||
<td>(May be omitted) <code>true</code> if the issuing account has <a href="freeze.html">frozen</a> this trust line. If omitted, that is the same as <code>false</code>.</td>
|
<td>(May be omitted) <code>true</code> if the issuing account has frozen this trust line. If omitted, that is the same as <code>false</code>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>freeze_peer</td>
|
<td>freeze_peer</td>
|
||||||
<td>Boolean</td>
|
<td>Boolean</td>
|
||||||
<td>(May be omitted) <code>true</code> if the counterparty has <a href="freeze.html">frozen</a> this trust line. If omitted, that is the same as <code>false</code>.</td>
|
<td>(May be omitted) <code>true</code> if the counterparty has frozen this trust line. If omitted, that is the same as <code>false</code>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -584,7 +590,7 @@ api.connect().then(() => {
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p>The field <code>"freeze": true</code> indicates that rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn has enabled Individual Freeze on the USD trust line to rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. The lack of a field <code>"freeze_peer": true</code> indicates that the counterparty has <em>not</em> frozen the trust line.</p>
|
<p>The field <code>"freeze": true</code> indicates that rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn has enabled Individual Freeze on the USD trust line to rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. The lack of a field <code>"freeze_peer": true</code> indicates that the counterparty has <em>not</em> frozen the trust line.</p>
|
||||||
<h3 id="using-rippleapi-3">Using RippleAPI</h3>
|
<h3 id="using-rippleapi-3">Using RippleAPI</h3>
|
||||||
<p>To see if a trust line has an Individual Freeze enabled, use the <a href="rippleapi.html#gettrustlines"><code>getTrustlines</code> method</a> with the following parameters:</p>
|
<p>To see if a trust line has an Individual Freeze enabled, use the <a href="reference-rippleapi.html#gettrustlines"><code>getTrustlines</code> method</a> with the following parameters:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -669,7 +675,7 @@ api.connect().then(() => {
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<h2 id="checking-for-global-freeze-and-no-freeze">Checking for Global Freeze and No Freeze</h2>
|
<h2 id="checking-for-global-freeze-and-no-freeze">Checking for Global Freeze and No Freeze</h2>
|
||||||
<h3 id="using-rippled-4">Using <code>rippled</code></h3>
|
<h3 id="using-rippled-4">Using <code>rippled</code></h3>
|
||||||
<p>To see if an account has Global Freeze and/or No Freeze enabled, use the <a href="rippled-apis.html#account-lines"><code>account_info</code> method</a> with the following parameters:</p>
|
<p>To see if an account has Global Freeze and/or No Freeze enabled, use the <a href="reference-rippled.html#account-lines"><code>account_info</code> method</a> with the following parameters:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -693,8 +699,8 @@ api.connect().then(() => {
|
|||||||
</table>
|
</table>
|
||||||
<p>Check the value of the <code>account_data.Flags</code> field of the response using the <a href="https://en.wikipedia.org/wiki/Bitwise_operation#AND">bitwise-AND</a> operator:</p>
|
<p>Check the value of the <code>account_data.Flags</code> field of the response using the <a href="https://en.wikipedia.org/wiki/Bitwise_operation#AND">bitwise-AND</a> operator:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>If <code>Flags</code> AND <code>0x00400000</code> (<a href="ripple-ledger.html#accountroot-flags">lsfGlobalFreeze</a>) is <em>nonzero</em>: Global Freeze is enabled.</li>
|
<li>If <code>Flags</code> AND <code>0x00400000</code> (<a href="reference-ledger-format.html#accountroot-flags">lsfGlobalFreeze</a>) is <em>nonzero</em>: Global Freeze is enabled.</li>
|
||||||
<li>If <code>Flags</code> AND <code>0x00200000</code> (<a href="ripple-ledger.html#accountroot-flags">lsfNoFreeze</a>) is <em>nonzero</em>: No Freeze is enabled.</li>
|
<li>If <code>Flags</code> AND <code>0x00200000</code> (<a href="reference-ledger-format.html#accountroot-flags">lsfNoFreeze</a>) is <em>nonzero</em>: No Freeze is enabled.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>Example WebSocket request:</p>
|
<p>Example WebSocket request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
@@ -746,7 +752,7 @@ console.log(currentFlags & lsfNoFreeze); //0
|
|||||||
//therefore, No Freeze is not enabled
|
//therefore, No Freeze is not enabled
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<h3 id="using-rippleapi-4">Using RippleAPI</h3>
|
<h3 id="using-rippleapi-4">Using RippleAPI</h3>
|
||||||
<p>To see if an account has Global Freeze and/or No Freeze enabled, use the <a href="rippleapi.html#getsettings"><code>getSettings</code> method</a> with the following parameters:</p>
|
<p>To see if an account has Global Freeze and/or No Freeze enabled, use the <a href="reference-rippleapi.html#getsettings"><code>getSettings</code> method</a> with the following parameters:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
206
concept-issuing-and-operational-accounts.html
Normal file
206
concept-issuing-and-operational-accounts.html
Normal file
@@ -0,0 +1,206 @@
|
|||||||
|
<!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>Issuing and Operational Acounts - 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="assets/vendor/jquery-1.11.1.min.js"></script>
|
||||||
|
|
||||||
|
<!-- Custom Stylesheets. ripple.css includes bootstrap, font stuff -->
|
||||||
|
<link href="assets/css/ripple.css" rel="stylesheet" />
|
||||||
|
<link href="assets/css/devportal.css" rel="stylesheet" />
|
||||||
|
|
||||||
|
<!-- Bootstrap JS -->
|
||||||
|
<script src="assets/vendor/bootstrap.min.js"></script>
|
||||||
|
|
||||||
|
|
||||||
|
<!-- syntax highlighting -->
|
||||||
|
<link rel="stylesheet" href="assets/vendor/docco.min.css">
|
||||||
|
<script src="assets/vendor/highlight.min.js"></script>
|
||||||
|
|
||||||
|
<!-- syntax selection js -->
|
||||||
|
<script src="assets/js/multicodetab.js"></script>
|
||||||
|
<script>
|
||||||
|
$(document).ready(function() {
|
||||||
|
$().multicode_tabs_pandoc();
|
||||||
|
hljs.initHighlighting();
|
||||||
|
make_code_expandable();
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<script src="assets/js/expandcode.js"></script>
|
||||||
|
<script src="assets/js/fixsidebarscroll.js"></script>
|
||||||
|
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body class="page page-template page-template-template-dev-portal page-template-template-dev-portal-php sidebar-primary wpb-js-composer js-comp-ver-3.6.2 vc_responsive">
|
||||||
|
<header role="banner" class="banner navbar navbar-default navbar-fixed-top initial_header">
|
||||||
|
<div class="container">
|
||||||
|
<div class="navbar-header">
|
||||||
|
<a href="index.html" class="navbar-brand"><img src="assets/img/ripple-logo-color.png" class="logo"></a>
|
||||||
|
</div><!-- /.navbar-header -->
|
||||||
|
<div class="nav">
|
||||||
|
<div class="draft-warning">DRAFT PAGE</div>
|
||||||
|
</div><!-- /.nav -->
|
||||||
|
|
||||||
|
</div><!-- /.container -->
|
||||||
|
|
||||||
|
<div class="subnav dev_nav">
|
||||||
|
<div class="container">
|
||||||
|
<ul id="menu-dev-menu" class="menu">
|
||||||
|
<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="reference-rippled.html">rippled</a></li>
|
||||||
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
|
<li><a href="reference-data-api.html">Ripple Data API v2</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="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<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="concept-paths.html">Paths</a></li>
|
||||||
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-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="ripple-api-tool.html">WebSocket 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><!-- /#dev-menu -->
|
||||||
|
</div><!-- /.subnav .container -->
|
||||||
|
</div><!-- /.subnav -->
|
||||||
|
</header>
|
||||||
|
|
||||||
|
|
||||||
|
<div class="wrap container" role="document">
|
||||||
|
<aside class="sidebar" role="complementary">
|
||||||
|
<div class="dev_nav_wrapper" style="margin-bottom: 0px;">
|
||||||
|
<div id="cont">
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<script type="text/javascript" src="assets/js/jquery.gensidebar.js"></script>
|
||||||
|
</aside>
|
||||||
|
<main class="main" role="main">
|
||||||
|
<div class='content'>
|
||||||
|
<h1 id="issuing-and-operational-accounts">Issuing and Operational Accounts</h1>
|
||||||
|
<p>For any financial institution doing business using the Ripple Consensus Ledger, we strongly recommend that the institution use multiple Ripple ledger accounts with a separation of roles. This promotes strong security and minimizes risk. We recommend the following setup:</p>
|
||||||
|
<ul>
|
||||||
|
<li>An <strong>issuing account</strong> (also known as a "cold wallet") with high value, used as rarely as possible.</li>
|
||||||
|
<li>One or more <strong>operational accounts</strong> (also known as a "hot wallets") with low value, used frequently by automated processes.</li>
|
||||||
|
<li>Optional <strong>standby accounts</strong> (also known as "warm wallets"), used infrequently by human operators.</li>
|
||||||
|
</ul>
|
||||||
|
<h2 id="the-risk">The Risk</h2>
|
||||||
|
<p>If a malicious person compromises a institution's issuing account (cold wallet), that person could create an unlimited amount of new issuances and trade them in the decentralized exchange. This would make it difficult to distinguish legitimately-obtained issuances and redeem them fairly. In this case, the institution must create a new issuing account, and all users with trust lines to the old issuing account must create new trust lines to the new account. Thus, it's best to keep your issuing account as secure as possible.</p>
|
||||||
|
<h2 id="separation-of-roles">Separation of Roles</h2>
|
||||||
|
<p>The issuing account is like a vault. It serves as the asset issuer, and should remain offline. The secret key that is used for this account is kept offline, accessible to only a few trusted operators. Periodically, a human operator creates and signs a transaction (preferably from an entirely offline machine) in order to refill the operational account's balance. Because the issuing account is creating the issuances, customer accounts holding those issuances must create trust lines to the issuing account.</p>
|
||||||
|
<p>An operational account is like a cash register. It makes payments on behalf of the institution by sending issuances created by the issuing account. The secret key for an operational account is, by necessity, stored on a server that is connected to the outside internet, usually in a configuration file on a public-facing server. Because it holds issuances created by the issuing account, each operational account must create a trust line to the issuing account. Customers do not, and should not, trust operational accounts. An institution can use one or more operational accounts, but it's easiest to configure the financial institution's software to use just a single operational account.</p>
|
||||||
|
<p>(Unlike a cash register, an operational account does not have to handle incoming payments from users, because the issuing account can receive and monitor payments without using its secret key. To make things simple for your users, we recommend treating incoming payments to the operational and issuing accounts as the same.)</p>
|
||||||
|
<p>Each operational account has a limited balance of the issuances. If an operational account is compromised, the financial institution only loses as much currency as that operational account holds. Customers do not need to change any configuration in order to receive funds from a new operational account. However, the institution must monitor operational accounts balances so that those accounts don't run out of funds during ordinary operation.</p>
|
||||||
|
<h3 id="standby-accounts">Standby Accounts</h3>
|
||||||
|
<p>Another optional step that an institution can take to balance risk and convenience is to use "standby accounts" as an intermediate step between the issuing account and operational accounts. The institution can operate additional accounts as standby accounts, whose keys not stored online, but are entrusted to different trusted users.</p>
|
||||||
|
<p>When an operational account is running low on funds, a trusted user can use a standby accountto refill the operational account's balance. When the standby accounts run low on funds, the institution can use the issuing account to send more currency to a standby account in a single transaction, and the standby accounts can distribute that currency among themselves if necessary. This improves security of the issuing account, allowing it to make fewer total transactions, without leaving too much money in the control of a single automated system.</p>
|
||||||
|
<p>As with operational accounts, standby accounts must trust the issuing account, and should not be trusted by users. All precautions that apply to operational accounts also apply to standby accounts.</p>
|
||||||
|
</div>
|
||||||
|
</main>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<footer class="content-info" role="contentinfo">
|
||||||
|
<div class="container">
|
||||||
|
<div class="row">
|
||||||
|
|
||||||
|
<section class="col-sm-3 widget nav_menu-3 widget_nav_menu">
|
||||||
|
<h4>Resources<hr></h4>
|
||||||
|
<ul id="menu-resources" class="menu">
|
||||||
|
<li class="menu-insights"><a href="https://ripple.com/insights/">Insights</a></li>
|
||||||
|
<li class="menu-press-center"><a href="https://ripple.com/press-center/">Press Center</a></li>
|
||||||
|
<li class="menu-media-resources"><a href="https://ripple.com/media-resources/">Media Resources</a></li>
|
||||||
|
<li class="menu-videos"><a href="https://ripple.com/videos/">Videos</a></li>
|
||||||
|
<li class="menu-whitepapers-reports"><a href="https://ripple.com/whitepapers-reports/">Whitepapers & Reports</a></li>
|
||||||
|
<li class="menu-xrp-portal"><a href="https://ripple.com/xrp-portal/">XRP Portal</a></li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section class="col-sm-3 widget nav_menu-5 widget_nav_menu">
|
||||||
|
<h4>Regulators<hr></h4>
|
||||||
|
<ul id="menu-compliance-regulatory-relations" class="menu"><li class="menu-compliance"><a href="https://ripple.com/compliance/">Compliance</a></li>
|
||||||
|
<li class="menu-policy-framework"><a href="https://ripple.com/policy-framework/">Policy Framework</a></li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section class="col-sm-3 widget nav_menu-4 widget_nav_menu">
|
||||||
|
<h4>Support<hr></h4>
|
||||||
|
<ul id="menu-dev-footer-menu" class="menu">
|
||||||
|
<li class="menu-contact-us"><a href="https://ripple.com/contact/">Contact Us</a></li>
|
||||||
|
<li class="active menu-developer-center"><a href="https://ripple.com/build/">Developer Center</a></li>
|
||||||
|
<li class="menu-knowledge-center"><a href="https://ripple.com/learn/">Knowledge Center</a></li>
|
||||||
|
<li class="menu-ripple-forum"><a target="_blank" href="https://forum.ripple.com/">Ripple Forum</a></li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section class="col-sm-3 widget nav_menu-2 widget_nav_menu">
|
||||||
|
<h4>About<hr></h4>
|
||||||
|
<ul id="menu-company-footer" class="menu">
|
||||||
|
<li class="menu-our-company"><a href="https://ripple.com/company/">Our Company</a></li>
|
||||||
|
<li class="menu-careers"><a href="https://ripple.com/company/careers/">Careers</a></li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<div class="col-sm-12 absolute_bottom_footer">
|
||||||
|
<div class="col-sm-8">
|
||||||
|
<span>© 2013-2015 Ripple Labs, Inc. All Rights Reserved.</span>
|
||||||
|
<span><a href="https://ripple.com/terms-of-use/">Terms</a></span>
|
||||||
|
<span><a href="https://ripple.com/privacy-policy/">Privacy</a></span>
|
||||||
|
</div>
|
||||||
|
</div><!-- /.absolute_bottom_footer -->
|
||||||
|
|
||||||
|
</div><!-- /.row -->
|
||||||
|
</div><!-- /.container -->
|
||||||
|
</footer>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -118,13 +124,13 @@
|
|||||||
<div id="cont">
|
<div id="cont">
|
||||||
<ul id="dev_nav_sidebar">
|
<ul id="dev_nav_sidebar">
|
||||||
<li class="level-1">Concepts</li>
|
<li class="level-1">Concepts</li>
|
||||||
<li class="level-2"><a href="paths.html">Paths</a></li>
|
<li class="level-2"><a href="concept-paths.html">Paths</a></li>
|
||||||
<li class="level-2"><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li class="level-2"><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li class="level-2"><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li class="level-2"><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li class="level-2"><a href="tx-cost.html">Transaction Cost</a></li>
|
<li class="level-2"><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li class="level-2"><a href="fee-voting.html">Fee Voting</a></li>
|
<li class="level-2"><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
<li class="level-2"><a href="reserves.html">Reserves</a></li>
|
<li class="level-2"><a href="concept-reserves.html">Reserves</a></li>
|
||||||
<li class="level-2"><a href="freeze.html">Freeze</a></li>
|
<li class="level-2"><a href="concept-freeze.html">Freeze</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
@@ -147,15 +153,15 @@
|
|||||||
<p><a href="img/paths-examples.png"><img alt="Diagram of three example paths" src="img/paths-examples.png"/></a></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>
|
<h1 id="technical-details">Technical Details</h1>
|
||||||
<h2 id="pathfinding">Pathfinding</h2>
|
<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>The <code>rippled</code> API has two methods that can be used for pathfinding. The <a href="reference-rippled.html#ripple-path-find"><code>ripple_path_find</code> command</a> does a one-time lookup of possible path sets. The <a href="reference-rippled.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>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="reference-rippled.html#sign"><code>sign</code> command</a> or <a href="reference-rippled.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>
|
<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>
|
<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>
|
<p>By convention, several steps of a path are implied by the <a href="reference-transaction-format.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>
|
<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>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 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>
|
<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="reference-transaction-format.html#special-issuer-values-for-sendmax-and-amount">special values for SendMax and Amount</a> for details.</li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</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>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>
|
||||||
@@ -174,7 +180,7 @@
|
|||||||
</ul>
|
</ul>
|
||||||
<p>The following diagram enumerates all possible default paths:
|
<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>
|
<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>
|
<p>You can use the <a href="reference-transaction-format.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>
|
<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>
|
<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>
|
<table>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -118,13 +124,13 @@
|
|||||||
<div id="cont">
|
<div id="cont">
|
||||||
<ul id="dev_nav_sidebar">
|
<ul id="dev_nav_sidebar">
|
||||||
<li class="level-1">Concepts</li>
|
<li class="level-1">Concepts</li>
|
||||||
<li class="level-2"><a href="paths.html">Paths</a></li>
|
<li class="level-2"><a href="concept-paths.html">Paths</a></li>
|
||||||
<li class="level-2"><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li class="level-2"><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li class="level-2"><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li class="level-2"><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li class="level-2"><a href="tx-cost.html">Transaction Cost</a></li>
|
<li class="level-2"><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li class="level-2"><a href="fee-voting.html">Fee Voting</a></li>
|
<li class="level-2"><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
<li class="level-2"><a href="reserves.html">Reserves</a></li>
|
<li class="level-2"><a href="concept-reserves.html">Reserves</a></li>
|
||||||
<li class="level-2"><a href="freeze.html">Freeze</a></li>
|
<li class="level-2"><a href="concept-freeze.html">Freeze</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
@@ -144,18 +150,18 @@
|
|||||||
<h3 id="owner-reserves">Owner Reserves</h3>
|
<h3 id="owner-reserves">Owner Reserves</h3>
|
||||||
<p>Many objects in the ledger are owned by a particular account, and therefore count toward the reserve requirement of that account. When objects are removed from the ledger, they no longer count against their owner's reserve requirement.</p>
|
<p>Many objects in the ledger are owned by a particular account, and therefore count toward the reserve requirement of that account. When objects are removed from the ledger, they no longer count against their owner's reserve requirement.</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="ripple-ledger.html#offer">Offers</a> are owned by the account that placed them. An Offer can be automatically removed from the ledger if it is fully consumed or if it is found unfunded during transaction processing. Alternatively, the owner can cancel an offer by sending an <a href="transactions.html#offercancel">OfferCancel transaction</a>, or by sending an <a href="transactions.html#offercreate">OfferCreate transaction</a> that contains an <code>OfferSequence</code> parameter.</li>
|
<li><a href="reference-ledger-format.html#offer">Offers</a> are owned by the account that placed them. An Offer can be automatically removed from the ledger if it is fully consumed or if it is found unfunded during transaction processing. Alternatively, the owner can cancel an offer by sending an <a href="reference-transaction-format.html#offercancel">OfferCancel transaction</a>, or by sending an <a href="reference-transaction-format.html#offercreate">OfferCreate transaction</a> that contains an <code>OfferSequence</code> parameter.</li>
|
||||||
<li><a href="ripple-ledger.html#ripplestate">Trust lines</a> are shared between two accounts. The owner reserve can apply to one or both of the accounts, depending on whether the fields that account controls are in their default state. See <a href="ripple-ledger.html#contributing-to-the-owner-reserve">Contributing to the Owner Reserve</a> for details.</li>
|
<li><a href="reference-ledger-format.html#ripplestate">Trust lines</a> are shared between two accounts. The owner reserve can apply to one or both of the accounts, depending on whether the fields that account controls are in their default state. See <a href="reference-ledger-format.html#contributing-to-the-owner-reserve">Contributing to the Owner Reserve</a> for details.</li>
|
||||||
<li><a href="ripple-ledger.html#directorynode">Owner directories</a> list all the ledger nodes that contribute to an account's owner reserve. However, the owner directory itself does not count towards the reserve.</li>
|
<li><a href="reference-ledger-format.html#directorynode">Owner directories</a> list all the ledger nodes that contribute to an account's owner reserve. However, the owner directory itself does not count towards the reserve.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h4 id="owner-reserve-edge-cases">Owner Reserve Edge Cases</h4>
|
<h4 id="owner-reserve-edge-cases">Owner Reserve Edge Cases</h4>
|
||||||
<p>The Ripple Consensus Ledger considers an <a href="transactions.html#offercreate">OfferCreate transaction</a> to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the <code>taker_pays</code> currency if such a trust line does not exist. However, if the offer's owner does not possess enough XRP to meet the additional reserve requirement of the new trust line, the offer is considered unfunded. See also: <a href="transactions.html#lifecycle-of-an-offer">Lifecycle of an Offer</a>.</p>
|
<p>The Ripple Consensus Ledger considers an <a href="reference-transaction-format.html#offercreate">OfferCreate transaction</a> to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the <code>taker_pays</code> currency if such a trust line does not exist. However, if the offer's owner does not possess enough XRP to meet the additional reserve requirement of the new trust line, the offer is considered unfunded. See also: <a href="reference-transaction-format.html#lifecycle-of-an-offer">Lifecycle of an Offer</a>.</p>
|
||||||
<h2 id="going-below-the-reserve-requirement">Going Below the Reserve Requirement</h2>
|
<h2 id="going-below-the-reserve-requirement">Going Below the Reserve Requirement</h2>
|
||||||
<p>During transaction processing, a transaction can only be successful if the sending account possesses at least the reserve requirement in XRP. In the process, the <a href="tx-cost.html">transaction cost</a> destroys some of the sending account's XRP balance. This can cause an account to go below the reserve requirement.</p>
|
<p>During transaction processing, a transaction can only be successful if the sending account possesses at least the reserve requirement in XRP. In the process, the <a href="concept-transaction-cost.html">transaction cost</a> destroys some of the sending account's XRP balance. This can cause an account to go below the reserve requirement.</p>
|
||||||
<p>When an account has less XRP than its current reserve requirement, it cannot send new transactions. Even so, it continues to exist in the ledger, as all accounts do. Unless the reserve requirements decrease, the only way for the account to become able to send transactions again is for it to receive enough XRP that it meets the reserve requirement.</p>
|
<p>When an account has less XRP than its current reserve requirement, it cannot send new transactions. Even so, it continues to exist in the ledger, as all accounts do. Unless the reserve requirements decrease, the only way for the account to become able to send transactions again is for it to receive enough XRP that it meets the reserve requirement.</p>
|
||||||
<p><strong>Exception:</strong> When an account is below the reserve requirement, it can send new <a href="transactions.html#offercreate">OfferCreate transactions</a> to acquire more XRP, or other currencies on its existing trust lines. These transactions cannot create new <a href="ripple-ledger.html#ripplestate">trust lines</a>, or <a href="ripple-ledger.html#offer">Offer nodes in the ledger</a>, so they can only execute trades that consume Offers that are already in the order books.</p>
|
<p><strong>Exception:</strong> When an account is below the reserve requirement, it can send new <a href="reference-transaction-format.html#offercreate">OfferCreate transactions</a> to acquire more XRP, or other currencies on its existing trust lines. These transactions cannot create new <a href="reference-ledger-format.html#ripplestate">trust lines</a>, or <a href="reference-ledger-format.html#offer">Offer nodes in the ledger</a>, so they can only execute trades that consume Offers that are already in the order books.</p>
|
||||||
<h2 id="changing-the-reserve-requirements">Changing the Reserve Requirements</h2>
|
<h2 id="changing-the-reserve-requirements">Changing the Reserve Requirements</h2>
|
||||||
<p>The Ripple Consensus Ledger has a mechanism for changing the reserve requirements 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>
|
<p>The Ripple Consensus Ledger has a mechanism for changing the reserve requirements 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="concept-fee-voting.html">Fee Voting</a> for more information.</p>
|
||||||
</div>
|
</div>
|
||||||
</main>
|
</main>
|
||||||
</div>
|
</div>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -118,13 +124,13 @@
|
|||||||
<div id="cont">
|
<div id="cont">
|
||||||
<ul id="dev_nav_sidebar">
|
<ul id="dev_nav_sidebar">
|
||||||
<li class="level-1">Concepts</li>
|
<li class="level-1">Concepts</li>
|
||||||
<li class="level-2"><a href="paths.html">Paths</a></li>
|
<li class="level-2"><a href="concept-paths.html">Paths</a></li>
|
||||||
<li class="level-2"><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li class="level-2"><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li class="level-2"><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li class="level-2"><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li class="level-2"><a href="tx-cost.html">Transaction Cost</a></li>
|
<li class="level-2"><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li class="level-2"><a href="fee-voting.html">Fee Voting</a></li>
|
<li class="level-2"><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
<li class="level-2"><a href="reserves.html">Reserves</a></li>
|
<li class="level-2"><a href="concept-reserves.html">Reserves</a></li>
|
||||||
<li class="level-2"><a href="freeze.html">Freeze</a></li>
|
<li class="level-2"><a href="concept-freeze.html">Freeze</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
@@ -140,45 +146,45 @@
|
|||||||
<h2 id="beneficiaries-of-the-transaction-cost">Beneficiaries of the Transaction Cost</h2>
|
<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>
|
<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>
|
<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>
|
<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="reference-rippled.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>
|
<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>
|
<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>
|
<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>The <a href="reference-rippled.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>
|
<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>
|
<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>The <a href="reference-rippled.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="reference-rippled.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>
|
<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>
|
<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>Every signed transaction must include the transaction cost in the <a href="reference-transaction-format.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>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>
|
<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>
|
<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>
|
<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>
|
<ul>
|
||||||
<li>If the network's transaction cost goes up between signing and distributing the transaction, the transaction may not be confirmed.<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>
|
<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="tutorial-reliable-transaction-submission.html">reliable transaction submission</a> for best practices.</li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li>You do not know in advance exactly what value you are signing for the <code>Fee</code> field.<ul>
|
<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>
|
<li>If you are using <code>rippled</code>, you can also use the <code>fee_mult_max</code> parameter of the <a href="reference-rippled.html#sign"><code>sign</code> command</a> to set a limit to the load scaling you are willing to sign.</li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li>You cannot look up the current transaction cost from an offline machine.</li>
|
<li>You cannot look up the current transaction cost from an offline machine.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h2 id="transaction-costs-and-failed-transactions">Transaction Costs and Failed Transactions</h2>
|
<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>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="reference-transaction-format.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>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>
|
<p>If a transaction's failure is <a href="reference-transaction-format.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>
|
<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 <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="reference-transaction-format.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>
|
<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>
|
<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>As a special case, an account can send a <a href="reference-transaction-format.html#setregularkey">SetRegularKey</a> transaction with a transaction cost of <code>0</code>, as long as the account's <a href="reference-ledger-format.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>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>
|
<p>The <a href="reference-ledger-format.html#accountroot-flags">lsfPasswordSpent flag</a> starts out disabled. If enabled, it gets disabled again when the account receives a <a href="reference-transaction-format.html#payment">Payment</a> of XRP.</p>
|
||||||
<h2 id="changing-the-transaction-cost">Changing the Transaction Cost</h2>
|
<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>
|
<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="concept-fee-voting.html">Fee Voting</a> for more information.</p>
|
||||||
</div>
|
</div>
|
||||||
</main>
|
</main>
|
||||||
</div>
|
</div>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -118,13 +124,13 @@
|
|||||||
<div id="cont">
|
<div id="cont">
|
||||||
<ul id="dev_nav_sidebar">
|
<ul id="dev_nav_sidebar">
|
||||||
<li class="level-1">Concepts</li>
|
<li class="level-1">Concepts</li>
|
||||||
<li class="level-2"><a href="paths.html">Paths</a></li>
|
<li class="level-2"><a href="concept-paths.html">Paths</a></li>
|
||||||
<li class="level-2"><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li class="level-2"><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li class="level-2"><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li class="level-2"><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li class="level-2"><a href="tx-cost.html">Transaction Cost</a></li>
|
<li class="level-2"><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li class="level-2"><a href="fee-voting.html">Fee Voting</a></li>
|
<li class="level-2"><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
<li class="level-2"><a href="reserves.html">Reserves</a></li>
|
<li class="level-2"><a href="concept-reserves.html">Reserves</a></li>
|
||||||
<li class="level-2"><a href="freeze.html">Freeze</a></li>
|
<li class="level-2"><a href="concept-freeze.html">Freeze</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
@@ -150,12 +156,12 @@
|
|||||||
<p>The transfer fee is represented by a setting on the issuing (<strong>cold wallet</strong>) account. The transfer fee has a maximum precision of 9 digits, and cannot be less than 0% or greater than 100%. The TransferRate setting applies to all currencies issued by the same account. If you want to have different transfer fee percentages for different currencies, use different cold wallets to issue each currency.</p>
|
<p>The transfer fee is represented by a setting on the issuing (<strong>cold wallet</strong>) account. The transfer fee has a maximum precision of 9 digits, and cannot be less than 0% or greater than 100%. The TransferRate setting applies to all currencies issued by the same account. If you want to have different transfer fee percentages for different currencies, use different cold wallets to issue each currency.</p>
|
||||||
<h2 id="rippleapi">RippleAPI</h2>
|
<h2 id="rippleapi">RippleAPI</h2>
|
||||||
<p>In RippleAPI, the transfer fee is specified in the <code>transferRate</code> field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A <code>transferRate</code> of <code>1005000000</code> is equivalent to a transfer fee of 0.5%. By default, the <code>transferRate</code> is set to no fee. The value of <code>transferRate</code> cannot be less than <code>1000000000</code> or more than <code>2000000000</code>. The value <code>null</code> is special: it is equivalent to <code>1000000000</code>, meaning no fee.</p>
|
<p>In RippleAPI, the transfer fee is specified in the <code>transferRate</code> field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A <code>transferRate</code> of <code>1005000000</code> is equivalent to a transfer fee of 0.5%. By default, the <code>transferRate</code> is set to no fee. The value of <code>transferRate</code> cannot be less than <code>1000000000</code> or more than <code>2000000000</code>. The value <code>null</code> is special: it is equivalent to <code>1000000000</code>, meaning no fee.</p>
|
||||||
<p>A gateway can send a <a href="rippleapi.html#settings">Settings transaction</a> with its cold wallet to change the <code>transferRate</code> for its issuances.</p>
|
<p>A gateway can send a <a href="reference-rippleapi.html#settings">Settings transaction</a> with its cold wallet to change the <code>transferRate</code> for its issuances.</p>
|
||||||
<p>You can check an account's <code>transferRate</code> with the <a href="rippleapi.html#getsettings">getSettings method</a>.</p>
|
<p>You can check an account's <code>transferRate</code> with the <a href="reference-rippleapi.html#getsettings">getSettings method</a>.</p>
|
||||||
<h2 id="rippled">rippled</h2>
|
<h2 id="rippled">rippled</h2>
|
||||||
<p>In <code>rippled</code>'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the <code>TransferRate</code> field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A <code>TransferRate</code> of <code>1005000000</code> is equivalent to a transfer fee of 0.5%. By default, the <code>TransferRate</code> is set at <code>1000000000</code>, indicating no fee. The value of <code>TransferRate</code> cannot be less than <code>1000000000</code> or more than <code>2000000000</code>. However, value <code>0</code> is special: it is equivalent to <code>1000000000</code>, meaning no fee.</p>
|
<p>In <code>rippled</code>'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the <code>TransferRate</code> field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A <code>TransferRate</code> of <code>1005000000</code> is equivalent to a transfer fee of 0.5%. By default, the <code>TransferRate</code> is set at <code>1000000000</code>, indicating no fee. The value of <code>TransferRate</code> cannot be less than <code>1000000000</code> or more than <code>2000000000</code>. However, value <code>0</code> is special: it is equivalent to <code>1000000000</code>, meaning no fee.</p>
|
||||||
<p>A gateway can submit an <a href="transactions.html#accountset">AccountSet transaction</a> from its cold wallet to change the <code>TransferRate</code> for its issuances. </p>
|
<p>A gateway can submit an <a href="reference-transaction-format.html#accountset">AccountSet transaction</a> from its cold wallet to change the <code>TransferRate</code> for its issuances. </p>
|
||||||
<p>You can check an account's <code>TransferRate</code> with the <a href="rippled-apis.html#account-info"><code>account_info</code> command</a>. If the <code>TransferRate</code> is omitted, then that indicates no fee.</p>
|
<p>You can check an account's <code>TransferRate</code> with the <a href="reference-rippled.html#account-info"><code>account_info</code> command</a>. If the <code>TransferRate</code> is omitted, then that indicates no fee.</p>
|
||||||
</div>
|
</div>
|
||||||
</main>
|
</main>
|
||||||
</div>
|
</div>
|
||||||
@@ -1,8 +1,8 @@
|
|||||||
# Fee Voting #
|
# Fee Voting #
|
||||||
|
|
||||||
Validators can vote for changes to basic [transaction cost](tx-cost.html) as well as [reserve requirements](reserves.html). If the preferences in a validator's configuration are different than the network's current settings, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a change that takes effect thereafter. Validators may do this for various reasons, especially to reflect long-term changes in the value of XRP.
|
Validators can vote for changes to basic [transaction cost](concept-transaction-cost.html) as well as [reserve requirements](concept-reserves.html). If the preferences in a validator's configuration are different than the network's current settings, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a change that takes effect thereafter. Validators may do this for various reasons, especially to reflect long-term changes in the value of XRP.
|
||||||
|
|
||||||
Operators of [`rippled` validators](rippled-setup.html#running-a-validator) can set their preferences for the transaction cost and reserve requirements in the `[voting]` stanza of the `rippled.cfg` file. **Caution:** insufficient requirements could expose the Ripple peer-to-peer network to denial-of-service attacks. The parameters you can set are as follows:
|
Operators of [`rippled` validators](tutorial-rippled-setup.html#running-a-validator) can set their preferences for the transaction cost and reserve requirements in the `[voting]` stanza of the `rippled.cfg` file. **Caution:** insufficient requirements could expose the Ripple peer-to-peer network to denial-of-service attacks. The parameters you can set are as follows:
|
||||||
|
|
||||||
| Parameter | Description | Recommended Value |
|
| Parameter | Description | Recommended Value |
|
||||||
|-----------|-------------|-------------------|
|
|-----------|-------------|-------------------|
|
||||||
@@ -16,7 +16,7 @@ Every 256th ledger is called a "flag" ledger. (A flag ledger is defined such tha
|
|||||||
|
|
||||||
In the flag ledger itself, nothing happens, but validators receive and take note of the votes from other validators they trust.
|
In the flag ledger itself, nothing happens, but validators receive and take note of the votes from other validators they trust.
|
||||||
|
|
||||||
After counting the votes of other validators, each validator attempts to compromise between its own preferences and the preferences of a majority of validators it trusts. (For example, if one validator wants to raise the minimum transaction cost from 10 to 100, but most validators only want to raise it from 10 to 20, the one validator settles on the change to raise the cost to 20. However, the one validator never settles on a value lower than 10 or higher than 100.) If a compromise is possible, the validator inserts a [SetFee pseudo-transaction](transactions.html#setfee) into its proposal for the ledger following the flag ledger. Other validators who want the same change insert an identical SetFee pseudo-transaction into their proposals for the same ledger. (Validators whose preferences match the existing network settings do nothing.) If a SetFee psuedo-transaction survives the consensus process to be included in a validated ledger, then the new transaction cost and reserve settings denoted by the SetFee pseudo-transaction take effect starting with the following ledger.
|
After counting the votes of other validators, each validator attempts to compromise between its own preferences and the preferences of a majority of validators it trusts. (For example, if one validator wants to raise the minimum transaction cost from 10 to 100, but most validators only want to raise it from 10 to 20, the one validator settles on the change to raise the cost to 20. However, the one validator never settles on a value lower than 10 or higher than 100.) If a compromise is possible, the validator inserts a [SetFee pseudo-transaction](reference-transaction-format.html#setfee) into its proposal for the ledger following the flag ledger. Other validators who want the same change insert an identical SetFee pseudo-transaction into their proposals for the same ledger. (Validators whose preferences match the existing network settings do nothing.) If a SetFee psuedo-transaction survives the consensus process to be included in a validated ledger, then the new transaction cost and reserve settings denoted by the SetFee pseudo-transaction take effect starting with the following ledger.
|
||||||
|
|
||||||
In short:
|
In short:
|
||||||
|
|
||||||
@@ -2,15 +2,15 @@
|
|||||||
|
|
||||||
The Ripple Consensus Ledger is a decentralized ledger, secured by cryptography, and operated by a distributed peer-to-peer network of servers. This means that no one party, not even the Ripple, Inc., can charge a fee for access to the network.
|
The Ripple Consensus Ledger is a decentralized ledger, secured by cryptography, and operated by a distributed peer-to-peer network of servers. This means that no one party, not even the Ripple, Inc., can charge a fee for access to the network.
|
||||||
|
|
||||||
However, the rules of the Ripple Consensus Ledger include several types of fees, including the [_transaction cost_](tx-cost.html) and [_reserve requirement_](reserves.html), which protect the ledger against abuse. (These neutral fees are not paid to anyone.) There are also several optional ways that users of the Consensus Ledger can collect fees from each other, both inside and outside the Ripple Consensus Ledger.
|
However, the rules of the Ripple Consensus Ledger include several types of fees, including the [_transaction cost_](concept-transaction-cost.html) and [_reserve requirement_](concept-reserves.html), which protect the ledger against abuse. (These neutral fees are not paid to anyone.) There are also several optional ways that users of the Consensus Ledger can collect fees from each other, both inside and outside the Ripple Consensus Ledger.
|
||||||
|
|
||||||
## In the Ledger ##
|
## In the Ledger ##
|
||||||
|
|
||||||
The _**transaction cost**_ (sometimes called the transaction fee) is a miniscule amount of XRP destroyed in order to send a transaction. This cost scales with the load of the network, which protects the peer-to-peer network from spam. See [Transaction Cost](tx-cost.html) for more information.
|
The _**transaction cost**_ (sometimes called the transaction fee) is a miniscule amount of XRP destroyed in order to send a transaction. This cost scales with the load of the network, which protects the peer-to-peer network from spam. See [Transaction Cost](concept-transaction-cost.html) for more information.
|
||||||
|
|
||||||
The _**account reserve**_ is a minimum amount of XRP that an account must possess. It scales with the number of objects the account owns in the ledger. This disincentivizes users from increasing the size of the ledger needlessly. See [Reserves](reserves.html) for more information.
|
The _**account reserve**_ is a minimum amount of XRP that an account must possess. It scales with the number of objects the account owns in the ledger. This disincentivizes users from increasing the size of the ledger needlessly. See [Reserves](concept-reserves.html) for more information.
|
||||||
|
|
||||||
_**Transfer fees**_ are optional percentage fees that gateways can charge to transfer the currencies they issue to other accounts within the Ripple Consensus Ledger. See [Transfer Fees](https://ripple.com/knowledge_center/transfer-fees/) for more information.
|
_**Transfer fees**_ are optional percentage fees that gateways can charge to transfer the currencies they issue to other accounts within the Ripple Consensus Ledger. See [Transfer Fees](concept-transfer-fees.html) for more information.
|
||||||
|
|
||||||
_**Trust line quality**_ is a setting that allows an account to value balances on a trust line at higher or lower than face value. This can lead to situations that are similar to charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line.
|
_**Trust line quality**_ is a setting that allows an account to value balances on a trust line at higher or lower than face value. This can lead to situations that are similar to charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line.
|
||||||
|
|
||||||
@@ -20,11 +20,11 @@ The **Individual Freeze** feature is a setting on a trust line. When an issuing
|
|||||||
* Payments can still occur directly between the two parties of the frozen trust line.
|
* Payments can still occur directly between the two parties of the frozen trust line.
|
||||||
* The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen issuances directly to the issuer.
|
* The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen issuances directly to the issuer.
|
||||||
* The counterparty can still receive payments from others on the frozen trust line.
|
* The counterparty can still receive payments from others on the frozen trust line.
|
||||||
* The counterparty's offers to sell the currency issued on the frozen trust line are [considered unfunded](transactions.html#lifecycle-of-an-offer).
|
* The counterparty's offers to sell the currency issued on the frozen trust line are [considered unfunded](reference-transaction-format.html#lifecycle-of-an-offer).
|
||||||
|
|
||||||
A gateway can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the gateway's terms of use. The gateway should also freeze the counterparty in any other systems the gateway operates that are connected to the Ripple Consensus Ledger. (Otherwise, an account might still be able to engage in undesired activity by sending payments through the gateway.)
|
A gateway can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the gateway's terms of use. The gateway should also freeze the counterparty in any other systems the gateway operates that are connected to the Ripple Consensus Ledger. (Otherwise, an account might still be able to engage in undesired activity by sending payments through the gateway.)
|
||||||
|
|
||||||
An individual account can freeze its trust line to a gateway. This has no effect on transactions between the gateway and other users. It does, however, prevent other accounts, including [hot wallets](gateway_guide.html#hot-and-cold-wallets), from sending that gateway's issued currency to the individual account. This type of individual freeze has no effect on offers.
|
An individual account can freeze its trust line to a gateway. This has no effect on transactions between the gateway and other users. It does, however, prevent other accounts, including [operational accounts](concept-issuing-and-operational-accounts.html), from sending that gateway's issued currency to the individual account. This type of individual freeze has no effect on offers.
|
||||||
|
|
||||||
The Individual Freeze applies to a single currency only. In order to freeze multiple currencies with a particular counterparty, the account must enable Individual Freeze on the trust lines for each currency individually.
|
The Individual Freeze applies to a single currency only. In order to freeze multiple currencies with a particular counterparty, the account must enable Individual Freeze on the trust lines for each currency individually.
|
||||||
|
|
||||||
@@ -36,13 +36,13 @@ Global Freeze
|
|||||||
|
|
||||||
The **Global Freeze** feature is a setting on an account. When an issuing account enables the Global Freeze feature, the following rules apply:
|
The **Global Freeze** feature is a setting on an account. When an issuing account enables the Global Freeze feature, the following rules apply:
|
||||||
|
|
||||||
* All counterparties of the frozen issuing account can no longer decrease the balances in their trust lines to the frozen account, except in direct payments to the issuer. (This also affects any [hot wallet](gateway_guide.html#hot-and-cold-wallets) accounts.)
|
* All counterparties of the frozen issuing account can no longer decrease the balances in their trust lines to the frozen account, except in direct payments to the issuer. (This also affects any [operational accounts](concept-issuing-and-operational-accounts.html).)
|
||||||
* Counterparties of the frozen issuing account can still send and receive payments directly to and from the issuing account.
|
* Counterparties of the frozen issuing account can still send and receive payments directly to and from the issuing account.
|
||||||
* All offers to sell currencies issued by the frozen account are [considered unfunded](transactions.html#lifecycle-of-an-offer).
|
* All offers to sell currencies issued by the frozen account are [considered unfunded](reference-transaction-format.html#lifecycle-of-an-offer).
|
||||||
|
|
||||||
It can be useful to enable Global Freeze on a gateway's [cold wallet](gateway_guide.html#hot-and-cold-wallets) if a hot wallet is compromised, or immediately after regaining control of a compromised issuing account. This stops the flow of funds, preventing attackers from getting away with any more money or at least making it easier to track what happened. In addition to enacting a Global Freeze in the Ripple Consensus Ledger, a financial institution should also suspend activities in its connectors to outside systems.
|
It can be useful to enable Global Freeze on a gateway's [issuing account](concept-issuing-and-operational-accounts.html) if an operational account is compromised, or immediately after regaining control of a compromised issuing account. This stops the flow of funds, preventing attackers from getting away with any more money or at least making it easier to track what happened. In addition to enacting a Global Freeze in the Ripple Consensus Ledger, a financial institution should also suspend activities in its connectors to outside systems.
|
||||||
|
|
||||||
It can also be useful to enable Global Freeze if a gateway intends to migrate its cold wallet to a new Ripple account, or if the gateway intends to cease doing business. This locks the funds at a specific point in time, so users cannot trade them away for other currencies.
|
It can also be useful to enable Global Freeze if a gateway intends to migrate to a new [issuing account](concept-issuing-and-operational-accounts.html), or if the gateway intends to cease doing business. This locks the funds at a specific point in time, so users cannot trade them away for other currencies.
|
||||||
|
|
||||||
Global Freeze applies to _all_ currencies issued and held by the account. You cannot enable Global Freeze for only one currency. If you want to have the ability to freeze some currencies and not others, you should use different accounts for each currency.
|
Global Freeze applies to _all_ currencies issued and held by the account. You cannot enable Global Freeze for only one currency. If you want to have the ability to freeze some currencies and not others, you should use different accounts for each currency.
|
||||||
|
|
||||||
@@ -61,7 +61,7 @@ The Ripple Consensus Ledger cannot force a gateway to honor the obligations that
|
|||||||
|
|
||||||
The No Freeze setting applies to all currencies issued to and from an account. If you want to be able to freeze some currencies but not others, you should use different accounts for each currency.
|
The No Freeze setting applies to all currencies issued to and from an account. If you want to be able to freeze some currencies but not others, you should use different accounts for each currency.
|
||||||
|
|
||||||
You can only enable the No Freeze setting with a transaction signed by your account's master key. You cannot use a [Regular Key](transactions.html#setregularkey) or a [multi-signed transaction](https://wiki.ripple.com/Multisign) to enable No Freeze.
|
You can only enable the No Freeze setting with a transaction signed by your account's master key. You cannot use a [Regular Key](reference-transaction-format.html#setregularkey) or a [multi-signed transaction](https://wiki.ripple.com/Multisign) to enable No Freeze.
|
||||||
|
|
||||||
|
|
||||||
# Technical Details #
|
# Technical Details #
|
||||||
@@ -70,7 +70,7 @@ You can only enable the No Freeze setting with a transaction signed by your acco
|
|||||||
|
|
||||||
### Using `rippled` ###
|
### Using `rippled` ###
|
||||||
|
|
||||||
To enable or disable Individual Freeze on a specific trust line, send a `TrustSet` transaction. Use the [`tfSetFreeze` flag](transactions.html#trustset-flags) to enable a freeze, and the `tfClearFreeze` flag to disable it. The fields of the transaction should be as follows:
|
To enable or disable Individual Freeze on a specific trust line, send a `TrustSet` transaction. Use the [`tfSetFreeze` flag](reference-transaction-format.html#trustset-flags) to enable a freeze, and the `tfClearFreeze` flag to disable it. The fields of the transaction should be as follows:
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|----------------------|--------|-------------|
|
|----------------------|--------|-------------|
|
||||||
@@ -82,9 +82,9 @@ To enable or disable Individual Freeze on a specific trust line, send a `TrustSe
|
|||||||
| LimitAmount.value | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a gateway, this is typically `"0"`. |
|
| LimitAmount.value | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a gateway, this is typically `"0"`. |
|
||||||
| Flags | Number | To enable a freeze, use a value with the bit `0x00100000` (tfSetFreeze) enabled. To disable a freeze, use a value with the bit `0x00200000` (tfClearFreeze) enabled instead. |
|
| Flags | Number | To enable a freeze, use a value with the bit `0x00100000` (tfSetFreeze) enabled. To disable a freeze, use a value with the bit `0x00200000` (tfClearFreeze) enabled instead. |
|
||||||
|
|
||||||
Set the `Fee`, `Sequence`, and `LastLedgerSequence` parameters [in the typical way](transactions.html#signing-and-sending-transactions).
|
Set the `Fee`, `Sequence`, and `LastLedgerSequence` parameters [in the typical way](reference-transaction-format.html#signing-and-sending-transactions).
|
||||||
|
|
||||||
Example of submitting a TrustSet transaction to enable an individual freeze using the [WebSocket API](rippled-apis.html#websocket-api):
|
Example of submitting a TrustSet transaction to enable an individual freeze using the [WebSocket API](reference-rippled.html#websocket-api):
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
@@ -114,16 +114,16 @@ Example of submitting a TrustSet transaction to enable an individual freeze usin
|
|||||||
|
|
||||||
### Using RippleAPI ###
|
### Using RippleAPI ###
|
||||||
|
|
||||||
To enable or disable Individual Freeze on a specific trust line, prepare a *Trustline* transaction using the [prepareTrustline](rippleapi.html#preparetrustline) method. The fields of the `trustline` parameter should be set as follows:
|
To enable or disable Individual Freeze on a specific trust line, prepare a *Trustline* transaction using the [prepareTrustline](reference-rippleapi.html#preparetrustline) method. The fields of the `trustline` parameter should be set as follows:
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|--------------|--------|-------------|
|
|--------------|--------|-------------|
|
||||||
| currency | String | The [currency](rippleapi.html#currency) of the trust line to freeze |
|
| currency | String | The [currency](reference-rippleapi.html#currency) of the trust line to freeze |
|
||||||
| counterparty | String | The [Ripple address](rippleapi.html#ripple-address) of the counterparty |
|
| counterparty | String | The [Ripple address](reference-rippleapi.html#ripple-address) of the counterparty |
|
||||||
| limit | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a gateway, this is typically `"0"`. |
|
| limit | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a gateway, this is typically `"0"`. |
|
||||||
| frozen | Boolean | `true` to enable Individual Freeze on this trust line. `false` to disable Individual Freeze. |
|
| frozen | Boolean | `true` to enable Individual Freeze on this trust line. `false` to disable Individual Freeze. |
|
||||||
|
|
||||||
The rest of the [transaction flow](rippleapi.html#transaction-flow) is the same as any other transaction.
|
The rest of the [transaction flow](reference-rippleapi.html#transaction-flow) is the same as any other transaction.
|
||||||
|
|
||||||
Example JavaScript (ECMAScript 6) code to enable Individual Freeze on a trust line:
|
Example JavaScript (ECMAScript 6) code to enable Individual Freeze on a trust line:
|
||||||
|
|
||||||
@@ -136,9 +136,9 @@ Example JavaScript (ECMAScript 6) code to enable Individual Freeze on a trust li
|
|||||||
|
|
||||||
### Using `rippled` ###
|
### Using `rippled` ###
|
||||||
|
|
||||||
To enable Global Freeze on an account, send an `AccountSet` transaction with the [asfGlobalFreeze flag value](transactions.html#accountset-flags) in the `SetFlag` field. To disable Global Freeze, put the asfGlobalFreeze flag value in the `ClearFlag` field instead.
|
To enable Global Freeze on an account, send an `AccountSet` transaction with the [asfGlobalFreeze flag value](reference-transaction-format.html#accountset-flags) in the `SetFlag` field. To disable Global Freeze, put the asfGlobalFreeze flag value in the `ClearFlag` field instead.
|
||||||
|
|
||||||
Example of submitting an AccountSet transaction to enable Global Freeze using the [WebSocket API](rippled-apis.html#websocket-api):
|
Example of submitting an AccountSet transaction to enable Global Freeze using the [WebSocket API](reference-rippled.html#websocket-api):
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
@@ -164,13 +164,13 @@ Example of submitting an AccountSet transaction to enable Global Freeze using th
|
|||||||
|
|
||||||
### Using RippleAPI ###
|
### Using RippleAPI ###
|
||||||
|
|
||||||
To enable or disable Global Freeze on an account, prepare a **Settings** transaction using the [prepareSettings](rippleapi.html#preparesettings) method. The `settings` parameter should be an object set as follows:
|
To enable or disable Global Freeze on an account, prepare a **Settings** transaction using the [prepareSettings](reference-rippleapi.html#preparesettings) method. The `settings` parameter should be an object set as follows:
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|--------------|--------|-------------|
|
|--------------|--------|-------------|
|
||||||
| globalFreeze | Boolean | `true` to enable a Global Freeze on this account. `false` to disable Global Freeze. |
|
| globalFreeze | Boolean | `true` to enable a Global Freeze on this account. `false` to disable Global Freeze. |
|
||||||
|
|
||||||
The rest of the [transaction flow](rippleapi.html#transaction-flow) is the same as any other transaction.
|
The rest of the [transaction flow](reference-rippleapi.html#transaction-flow) is the same as any other transaction.
|
||||||
|
|
||||||
Example JavaScript (ECMAScript 6) code to enable Global Freeze on an account:
|
Example JavaScript (ECMAScript 6) code to enable Global Freeze on an account:
|
||||||
|
|
||||||
@@ -184,9 +184,9 @@ Example JavaScript (ECMAScript 6) code to enable Global Freeze on an account:
|
|||||||
|
|
||||||
### Using `rippled` ###
|
### Using `rippled` ###
|
||||||
|
|
||||||
To enable No Freeze on an account, send an `AccountSet` transaction with the [asfNoFreeze flag value](transactions.html#accountset-flags) in the `SetFlag` field. You must sign this transaction using the master key. Once enabled, you cannot disable No Freeze.
|
To enable No Freeze on an account, send an `AccountSet` transaction with the [asfNoFreeze flag value](reference-transaction-format.html#accountset-flags) in the `SetFlag` field. You must sign this transaction using the master key. Once enabled, you cannot disable No Freeze.
|
||||||
|
|
||||||
Example of submitting an AccountSet transaction to enable No Freeze using the [WebSocket API](rippled-apis.html#websocket-api):
|
Example of submitting an AccountSet transaction to enable No Freeze using the [WebSocket API](reference-rippled.html#websocket-api):
|
||||||
|
|
||||||
WebSocket request:
|
WebSocket request:
|
||||||
|
|
||||||
@@ -213,13 +213,13 @@ WebSocket request:
|
|||||||
|
|
||||||
### Using RippleAPI ###
|
### Using RippleAPI ###
|
||||||
|
|
||||||
To enable No Freeze on an account, prepare a **Settings** transaction using the [prepareSettings](rippleapi.html#preparesettings) method. Once enabled, you cannot disable No Freeze. The `settings` parameter should be an object set as follows:
|
To enable No Freeze on an account, prepare a **Settings** transaction using the [prepareSettings](reference-rippleapi.html#preparesettings) method. Once enabled, you cannot disable No Freeze. The `settings` parameter should be an object set as follows:
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|----------|---------|-------------|
|
|----------|---------|-------------|
|
||||||
| noFreeze | Boolean | `true` |
|
| noFreeze | Boolean | `true` |
|
||||||
|
|
||||||
You must [sign](rippleapi.html#sign) this transaction using the master key. The rest of the [transaction flow](rippleapi.html#transaction-flow) is the same as any other transaction.
|
You must [sign](reference-rippleapi.html#sign) this transaction using the master key. The rest of the [transaction flow](reference-rippleapi.html#transaction-flow) is the same as any other transaction.
|
||||||
|
|
||||||
Example JavaScript (ECMAScript 6) code to enable No Freeze on an account:
|
Example JavaScript (ECMAScript 6) code to enable No Freeze on an account:
|
||||||
|
|
||||||
@@ -232,7 +232,7 @@ Example JavaScript (ECMAScript 6) code to enable No Freeze on an account:
|
|||||||
|
|
||||||
### Using `rippled` ###
|
### Using `rippled` ###
|
||||||
|
|
||||||
To see if a trust line has an Individual Freeze enabled, use the [`account_lines` method](rippled-apis.html#account-lines) with the following parameters:
|
To see if a trust line has an Individual Freeze enabled, use the [`account_lines` method](reference-rippled.html#account-lines) with the following parameters:
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|----------|---------|-------------|
|
|----------|---------|-------------|
|
||||||
@@ -244,8 +244,8 @@ The response contains an array of trust lines, for each currency in which the is
|
|||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|--------------|---------|-------------|
|
|--------------|---------|-------------|
|
||||||
| freeze | Boolean | (May be omitted) `true` if the issuing account has [frozen](freeze.html) this trust line. If omitted, that is the same as `false`. |
|
| freeze | Boolean | (May be omitted) `true` if the issuing account has frozen this trust line. If omitted, that is the same as `false`. |
|
||||||
| freeze\_peer | Boolean | (May be omitted) `true` if the counterparty has [frozen](freeze.html) this trust line. If omitted, that is the same as `false`. |
|
| freeze\_peer | Boolean | (May be omitted) `true` if the counterparty has frozen this trust line. If omitted, that is the same as `false`. |
|
||||||
|
|
||||||
Example WebSocket request to check for individual freeze:
|
Example WebSocket request to check for individual freeze:
|
||||||
|
|
||||||
@@ -290,7 +290,7 @@ The field `"freeze": true` indicates that rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn has
|
|||||||
|
|
||||||
### Using RippleAPI ###
|
### Using RippleAPI ###
|
||||||
|
|
||||||
To see if a trust line has an Individual Freeze enabled, use the [`getTrustlines` method](rippleapi.html#gettrustlines) with the following parameters:
|
To see if a trust line has an Individual Freeze enabled, use the [`getTrustlines` method](reference-rippleapi.html#gettrustlines) with the following parameters:
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|---------------|---------|-------------|
|
|---------------|---------|-------------|
|
||||||
@@ -315,7 +315,7 @@ Example JavaScript (ECMAScript 6) code to check whether a trust line is frozen:
|
|||||||
|
|
||||||
### Using `rippled` ###
|
### Using `rippled` ###
|
||||||
|
|
||||||
To see if an account has Global Freeze and/or No Freeze enabled, use the [`account_info` method](rippled-apis.html#account-lines) with the following parameters:
|
To see if an account has Global Freeze and/or No Freeze enabled, use the [`account_info` method](reference-rippled.html#account-lines) with the following parameters:
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|----------|---------|-------------|
|
|----------|---------|-------------|
|
||||||
@@ -324,8 +324,8 @@ To see if an account has Global Freeze and/or No Freeze enabled, use the [`accou
|
|||||||
|
|
||||||
Check the value of the `account_data.Flags` field of the response using the [bitwise-AND](https://en.wikipedia.org/wiki/Bitwise_operation#AND) operator:
|
Check the value of the `account_data.Flags` field of the response using the [bitwise-AND](https://en.wikipedia.org/wiki/Bitwise_operation#AND) operator:
|
||||||
|
|
||||||
* If `Flags` AND `0x00400000` ([lsfGlobalFreeze](ripple-ledger.html#accountroot-flags)) is _nonzero_: Global Freeze is enabled.
|
* If `Flags` AND `0x00400000` ([lsfGlobalFreeze](reference-ledger-format.html#accountroot-flags)) is _nonzero_: Global Freeze is enabled.
|
||||||
* If `Flags` AND `0x00200000` ([lsfNoFreeze](ripple-ledger.html#accountroot-flags)) is _nonzero_: No Freeze is enabled.
|
* If `Flags` AND `0x00200000` ([lsfNoFreeze](reference-ledger-format.html#accountroot-flags)) is _nonzero_: No Freeze is enabled.
|
||||||
|
|
||||||
Example WebSocket request:
|
Example WebSocket request:
|
||||||
|
|
||||||
@@ -387,7 +387,7 @@ console.log(currentFlags & lsfNoFreeze); //0
|
|||||||
|
|
||||||
### Using RippleAPI ###
|
### Using RippleAPI ###
|
||||||
|
|
||||||
To see if an account has Global Freeze and/or No Freeze enabled, use the [`getSettings` method](rippleapi.html#getsettings) with the following parameters:
|
To see if an account has Global Freeze and/or No Freeze enabled, use the [`getSettings` method](reference-rippleapi.html#getsettings) with the following parameters:
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|---------------|---------|-------------|
|
|---------------|---------|-------------|
|
||||||
32
content/concept-issuing-and-operational-accounts.md
Normal file
32
content/concept-issuing-and-operational-accounts.md
Normal file
@@ -0,0 +1,32 @@
|
|||||||
|
# Issuing and Operational Accounts #
|
||||||
|
|
||||||
|
For any financial institution doing business using the Ripple Consensus Ledger, we strongly recommend that the institution use multiple Ripple ledger accounts with a separation of roles. This promotes strong security and minimizes risk. We recommend the following setup:
|
||||||
|
|
||||||
|
* An **issuing account** (also known as a "cold wallet") with high value, used as rarely as possible.
|
||||||
|
* One or more **operational accounts** (also known as a "hot wallets") with low value, used frequently by automated processes.
|
||||||
|
* Optional **standby accounts** (also known as "warm wallets"), used infrequently by human operators.
|
||||||
|
|
||||||
|
|
||||||
|
## The Risk ##
|
||||||
|
|
||||||
|
If a malicious person compromises a institution's issuing account (cold wallet), that person could create an unlimited amount of new issuances and trade them in the decentralized exchange. This would make it difficult to distinguish legitimately-obtained issuances and redeem them fairly. In this case, the institution must create a new issuing account, and all users with trust lines to the old issuing account must create new trust lines to the new account. Thus, it's best to keep your issuing account as secure as possible.
|
||||||
|
|
||||||
|
|
||||||
|
## Separation of Roles ##
|
||||||
|
|
||||||
|
The issuing account is like a vault. It serves as the asset issuer, and should remain offline. The secret key that is used for this account is kept offline, accessible to only a few trusted operators. Periodically, a human operator creates and signs a transaction (preferably from an entirely offline machine) in order to refill the operational account's balance. Because the issuing account is creating the issuances, customer accounts holding those issuances must create trust lines to the issuing account.
|
||||||
|
|
||||||
|
An operational account is like a cash register. It makes payments on behalf of the institution by sending issuances created by the issuing account. The secret key for an operational account is, by necessity, stored on a server that is connected to the outside internet, usually in a configuration file on a public-facing server. Because it holds issuances created by the issuing account, each operational account must create a trust line to the issuing account. Customers do not, and should not, trust operational accounts. An institution can use one or more operational accounts, but it's easiest to configure the financial institution's software to use just a single operational account.
|
||||||
|
|
||||||
|
(Unlike a cash register, an operational account does not have to handle incoming payments from users, because the issuing account can receive and monitor payments without using its secret key. To make things simple for your users, we recommend treating incoming payments to the operational and issuing accounts as the same.)
|
||||||
|
|
||||||
|
Each operational account has a limited balance of the issuances. If an operational account is compromised, the financial institution only loses as much currency as that operational account holds. Customers do not need to change any configuration in order to receive funds from a new operational account. However, the institution must monitor operational accounts balances so that those accounts don't run out of funds during ordinary operation.
|
||||||
|
|
||||||
|
|
||||||
|
### Standby Accounts ###
|
||||||
|
|
||||||
|
Another optional step that an institution can take to balance risk and convenience is to use "standby accounts" as an intermediate step between the issuing account and operational accounts. The institution can operate additional accounts as standby accounts, whose keys not stored online, but are entrusted to different trusted users.
|
||||||
|
|
||||||
|
When an operational account is running low on funds, a trusted user can use a standby accountto refill the operational account's balance. When the standby accounts run low on funds, the institution can use the issuing account to send more currency to a standby account in a single transaction, and the standby accounts can distribute that currency among themselves if necessary. This improves security of the issuing account, allowing it to make fewer total transactions, without leaving too much money in the control of a single automated system.
|
||||||
|
|
||||||
|
As with operational accounts, standby accounts must trust the issuing account, and should not be trusted by users. All precautions that apply to operational accounts also apply to standby accounts.
|
||||||
@@ -27,20 +27,20 @@ In both types of steps, each intermediate account gains and loses approximately
|
|||||||
|
|
||||||
## Pathfinding ##
|
## Pathfinding ##
|
||||||
|
|
||||||
The `rippled` API has two methods that can be used for pathfinding. The [`ripple_path_find` command](rippled-apis.html#ripple-path-find) does a one-time lookup of possible path sets. The [`path_find` command](rippled-apis.html#path-find) (WebSocket only) expands on the initial search with follow-up responses whenever a ledger closes or the server finds a better path.
|
The `rippled` API has two methods that can be used for pathfinding. The [`ripple_path_find` command](reference-rippled.html#ripple-path-find) does a one-time lookup of possible path sets. The [`path_find` command](reference-rippled.html#path-find) (WebSocket only) expands on the initial search with follow-up responses whenever a ledger closes or the server finds a better path.
|
||||||
|
|
||||||
You can have `rippled` automatically fill in paths when you sign it, by including the `build_path` field in a request to the [`sign` command](rippled-apis.html#sign) or [`submit` command (sign-and-submit mode)](rippled-apis.html#sign-and-submit-mode). 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 `rippled` is designed to search for the cheapest paths possible, it may not always find them. Untrustworthy `rippled` instances could also be modified to change this behavior for profit.)
|
You can have `rippled` automatically fill in paths when you sign it, by including the `build_path` field in a request to the [`sign` command](reference-rippled.html#sign) or [`submit` command (sign-and-submit mode)](reference-rippled.html#sign-and-submit-mode). 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 `rippled` is designed to search for the cheapest paths possible, it may not always find them. Untrustworthy `rippled` instances could also be modified to change this behavior for profit.)
|
||||||
|
|
||||||
Finding paths is a very challenging problem that changes slightly every few seconds as new ledgers are validated, so `rippled` 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.
|
Finding paths is a very challenging problem that changes slightly every few seconds as new ledgers are validated, so `rippled` 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.
|
||||||
|
|
||||||
|
|
||||||
## Implied Steps ##
|
## Implied Steps ##
|
||||||
|
|
||||||
By convention, several steps of a path are implied by the [fields of the Payment transaction](transactions.html#payment): specifically, the `Account` (sender), `Destination` (receiver), `Amount` (currency and amount to be delivered) and `SendMax` (currency and amount to be sent, if specified). The implied steps are as follows:
|
By convention, several steps of a path are implied by the [fields of the Payment transaction](reference-transaction-format.html#payment): specifically, the `Account` (sender), `Destination` (receiver), `Amount` (currency and amount to be delivered) and `SendMax` (currency and amount to be sent, if specified). The implied steps are as follows:
|
||||||
|
|
||||||
* The first step of a path is always implied to be the sender of the transaction, as defined by the transaction's `Account` field.
|
* The first step of a path is always implied to be the sender of the transaction, as defined by the transaction's `Account` field.
|
||||||
* If the transaction includes a `SendMax` field with an `issuer` that is not the sender of the transaction, that issuer is implied to be the second step of the path.
|
* If the transaction includes a `SendMax` field with an `issuer` that is not the sender of the transaction, that issuer is implied to be the second step of the path.
|
||||||
* If `issuer` of the `SendMax` _is_ 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 [special values for SendMax and Amount](transactions.html#special-issuer-values-for-sendmax-and-amount) for details.
|
* If `issuer` of the `SendMax` _is_ 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 [special values for SendMax and Amount](reference-transaction-format.html#special-issuer-values-for-sendmax-and-amount) for details.
|
||||||
* If the `Amount` field of the transaction includes an `issuer` that is not the same as the `Destination` of the transaction, that issuer is implied to be the second-to-last step of the path.
|
* If the `Amount` field of the transaction includes an `issuer` that is not the same as the `Destination` of the transaction, that issuer is implied to be the second-to-last step of the path.
|
||||||
* Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's `Destination` field.
|
* Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's `Destination` field.
|
||||||
|
|
||||||
@@ -59,7 +59,7 @@ The default path could be any of the following:
|
|||||||
The following diagram enumerates all possible default paths:
|
The following diagram enumerates all possible default paths:
|
||||||
[](img/paths-default_paths.png)
|
[](img/paths-default_paths.png)
|
||||||
|
|
||||||
You can use the [`tfNoDirectRipple` flag](transactions.html#payment-flags) 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.
|
You can use the [`tfNoDirectRipple` flag](reference-transaction-format.html#payment-flags) 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.
|
||||||
|
|
||||||
|
|
||||||
## Path Specifications ##
|
## Path Specifications ##
|
||||||
@@ -19,25 +19,25 @@ The reserve requirement is divided into two parts:
|
|||||||
|
|
||||||
Many objects in the ledger are owned by a particular account, and therefore count toward the reserve requirement of that account. When objects are removed from the ledger, they no longer count against their owner's reserve requirement.
|
Many objects in the ledger are owned by a particular account, and therefore count toward the reserve requirement of that account. When objects are removed from the ledger, they no longer count against their owner's reserve requirement.
|
||||||
|
|
||||||
* [Offers](ripple-ledger.html#offer) are owned by the account that placed them. An Offer can be automatically removed from the ledger if it is fully consumed or if it is found unfunded during transaction processing. Alternatively, the owner can cancel an offer by sending an [OfferCancel transaction](transactions.html#offercancel), or by sending an [OfferCreate transaction](transactions.html#offercreate) that contains an `OfferSequence` parameter.
|
* [Offers](reference-ledger-format.html#offer) are owned by the account that placed them. An Offer can be automatically removed from the ledger if it is fully consumed or if it is found unfunded during transaction processing. Alternatively, the owner can cancel an offer by sending an [OfferCancel transaction](reference-transaction-format.html#offercancel), or by sending an [OfferCreate transaction](reference-transaction-format.html#offercreate) that contains an `OfferSequence` parameter.
|
||||||
* [Trust lines](ripple-ledger.html#ripplestate) are shared between two accounts. The owner reserve can apply to one or both of the accounts, depending on whether the fields that account controls are in their default state. See [Contributing to the Owner Reserve](ripple-ledger.html#contributing-to-the-owner-reserve) for details.
|
* [Trust lines](reference-ledger-format.html#ripplestate) are shared between two accounts. The owner reserve can apply to one or both of the accounts, depending on whether the fields that account controls are in their default state. See [Contributing to the Owner Reserve](reference-ledger-format.html#contributing-to-the-owner-reserve) for details.
|
||||||
* [Owner directories](ripple-ledger.html#directorynode) list all the ledger nodes that contribute to an account's owner reserve. However, the owner directory itself does not count towards the reserve.
|
* [Owner directories](reference-ledger-format.html#directorynode) list all the ledger nodes that contribute to an account's owner reserve. However, the owner directory itself does not count towards the reserve.
|
||||||
|
|
||||||
#### Owner Reserve Edge Cases ####
|
#### Owner Reserve Edge Cases ####
|
||||||
|
|
||||||
The Ripple Consensus Ledger considers an [OfferCreate transaction](transactions.html#offercreate) to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the `taker_pays` currency if such a trust line does not exist. However, if the offer's owner does not possess enough XRP to meet the additional reserve requirement of the new trust line, the offer is considered unfunded. See also: [Lifecycle of an Offer](transactions.html#lifecycle-of-an-offer).
|
The Ripple Consensus Ledger considers an [OfferCreate transaction](reference-transaction-format.html#offercreate) to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the `taker_pays` currency if such a trust line does not exist. However, if the offer's owner does not possess enough XRP to meet the additional reserve requirement of the new trust line, the offer is considered unfunded. See also: [Lifecycle of an Offer](reference-transaction-format.html#lifecycle-of-an-offer).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Going Below the Reserve Requirement ##
|
## Going Below the Reserve Requirement ##
|
||||||
|
|
||||||
During transaction processing, a transaction can only be successful if the sending account possesses at least the reserve requirement in XRP. In the process, the [transaction cost](tx-cost.html) destroys some of the sending account's XRP balance. This can cause an account to go below the reserve requirement.
|
During transaction processing, a transaction can only be successful if the sending account possesses at least the reserve requirement in XRP. In the process, the [transaction cost](concept-transaction-cost.html) destroys some of the sending account's XRP balance. This can cause an account to go below the reserve requirement.
|
||||||
|
|
||||||
When an account has less XRP than its current reserve requirement, it cannot send new transactions. Even so, it continues to exist in the ledger, as all accounts do. Unless the reserve requirements decrease, the only way for the account to become able to send transactions again is for it to receive enough XRP that it meets the reserve requirement.
|
When an account has less XRP than its current reserve requirement, it cannot send new transactions. Even so, it continues to exist in the ledger, as all accounts do. Unless the reserve requirements decrease, the only way for the account to become able to send transactions again is for it to receive enough XRP that it meets the reserve requirement.
|
||||||
|
|
||||||
**Exception:** When an account is below the reserve requirement, it can send new [OfferCreate transactions](transactions.html#offercreate) to acquire more XRP, or other currencies on its existing trust lines. These transactions cannot create new [trust lines](ripple-ledger.html#ripplestate), or [Offer nodes in the ledger](ripple-ledger.html#offer), so they can only execute trades that consume Offers that are already in the order books.
|
**Exception:** When an account is below the reserve requirement, it can send new [OfferCreate transactions](reference-transaction-format.html#offercreate) to acquire more XRP, or other currencies on its existing trust lines. These transactions cannot create new [trust lines](reference-ledger-format.html#ripplestate), or [Offer nodes in the ledger](reference-ledger-format.html#offer), so they can only execute trades that consume Offers that are already in the order books.
|
||||||
|
|
||||||
## Changing the Reserve Requirements ##
|
## Changing the Reserve Requirements ##
|
||||||
|
|
||||||
The Ripple Consensus Ledger has a mechanism for changing the reserve requirements in order to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](fee-voting.html) for more information.
|
The Ripple Consensus Ledger has a mechanism for changing the reserve requirements in order to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](concept-fee-voting.html) for more information.
|
||||||
|
|
||||||
@@ -19,7 +19,7 @@ The transaction cost is not paid to any party: the XRP is irrevocably destroyed.
|
|||||||
|
|
||||||
## Load Scaling ##
|
## Load Scaling ##
|
||||||
|
|
||||||
Each `rippled` server independently scales the transaction cost based on its current load. If you submit a transaction with a `Fee` value that is lower than current load-based transaction cost of the `rippled` server, that server neither applies nor relays the transaction. (**Note:** If you submit a transaction through an [admin connection](rippled-apis.html#connecting-to-rippled), the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive [the consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) unless its `Fee` value meets the requirements of a majority of servers.
|
Each `rippled` server independently scales the transaction cost based on its current load. If you submit a transaction with a `Fee` value that is lower than current load-based transaction cost of the `rippled` server, that server neither applies nor relays the transaction. (**Note:** If you submit a transaction through an [admin connection](reference-rippled.html#connecting-to-rippled), the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive [the consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) unless its `Fee` value meets the requirements of a majority of servers.
|
||||||
|
|
||||||
|
|
||||||
## Querying the Transaction Cost ##
|
## Querying the Transaction Cost ##
|
||||||
@@ -28,14 +28,14 @@ The `rippled` APIs have two ways to query the transaction cost: the `server_info
|
|||||||
|
|
||||||
### server_info ###
|
### server_info ###
|
||||||
|
|
||||||
The [`server_info` command](rippled-apis.html#server-info) reports the unscaled minimum XRP cost, as of the previous ledger, as `validated_ledger.base_fee_xrp`, in the form of decimal XRP. The actual cost necessary to relay a transaction is scaled by multiplying that `base_fee_xrp` value by the `load_factor` parameter in the same response, which represents the server's current load level. In other words:
|
The [`server_info` command](reference-rippled.html#server-info) reports the unscaled minimum XRP cost, as of the previous ledger, as `validated_ledger.base_fee_xrp`, in the form of decimal XRP. The actual cost necessary to relay a transaction is scaled by multiplying that `base_fee_xrp` value by the `load_factor` parameter in the same response, which represents the server's current load level. In other words:
|
||||||
|
|
||||||
**Current Transaction Cost in XRP = `base_fee_xrp` × `load_factor`**
|
**Current Transaction Cost in XRP = `base_fee_xrp` × `load_factor`**
|
||||||
|
|
||||||
|
|
||||||
### server_state ###
|
### server_state ###
|
||||||
|
|
||||||
The [`server_state` command](rippled-apis.html#server-state) returns a direct representation of `rippled`'s internal load calculations. In this case, the effective load rate is the ratio of the current `load_factor` to the `load_base`. The `validated_ledger.base_fee` parameter reports the minimum transaction cost in [drops of XRP](rippled-apis.html#specifying-currency-amounts). This design enables `rippled` 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:
|
The [`server_state` command](reference-rippled.html#server-state) returns a direct representation of `rippled`'s internal load calculations. In this case, the effective load rate is the ratio of the current `load_factor` to the `load_base`. The `validated_ledger.base_fee` parameter reports the minimum transaction cost in [drops of XRP](reference-rippled.html#specifying-currency-amounts). This design enables `rippled` 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:
|
||||||
|
|
||||||
**Current Transaction Cost in Drops = (`base_fee` × `load_factor`) ÷ `load_base`**
|
**Current Transaction Cost in Drops = (`base_fee` × `load_factor`) ÷ `load_base`**
|
||||||
|
|
||||||
@@ -43,7 +43,7 @@ The [`server_state` command](rippled-apis.html#server-state) returns a direct re
|
|||||||
|
|
||||||
## Specifying the Transaction Cost ##
|
## Specifying the Transaction Cost ##
|
||||||
|
|
||||||
Every signed transaction must include the transaction cost in the [`Fee` field](transactions.html#common-fields). Like all fields of a signed transaction, this field cannot be changed without invalidating the signature.
|
Every signed transaction must include the transaction cost in the [`Fee` field](reference-transaction-format.html#common-fields). Like all fields of a signed transaction, this field cannot be changed without invalidating the signature.
|
||||||
|
|
||||||
As a rule, the Ripple Consensus Ledger executes transactions _exactly_ 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 `Fee` 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.
|
As a rule, the Ripple Consensus Ledger executes transactions _exactly_ 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 `Fee` 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.
|
||||||
|
|
||||||
@@ -55,37 +55,37 @@ Before signing a transaction, we recommend [looking up the current load-based tr
|
|||||||
When you sign a transaction online, you can omit the `Fee` field. In this case, `rippled` 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:
|
When you sign a transaction online, you can omit the `Fee` field. In this case, `rippled` 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:
|
||||||
|
|
||||||
* If the network's transaction cost goes up between signing and distributing the transaction, the transaction may not be confirmed.
|
* If the network's transaction cost goes up between signing and distributing the transaction, the transaction may not be confirmed.
|
||||||
* In the worst case, the transaction may be stuck in a state of being neither definitively confirmed or rejected, unless it included a `LastLedgerSequence` parameter or until you cancel it with a new transaction that uses the same `Sequence` number. See [reliable transaction submission](reliable_tx.html) for best practices.
|
* In the worst case, the transaction may be stuck in a state of being neither definitively confirmed or rejected, unless it included a `LastLedgerSequence` parameter or until you cancel it with a new transaction that uses the same `Sequence` number. See [reliable transaction submission](tutorial-reliable-transaction-submission.html) for best practices.
|
||||||
* You do not know in advance exactly what value you are signing for the `Fee` field.
|
* You do not know in advance exactly what value you are signing for the `Fee` field.
|
||||||
* If you are using `rippled`, you can also use the `fee_mult_max` parameter of the [`sign` command](rippled-apis.html#sign) to set a limit to the load scaling you are willing to sign.
|
* If you are using `rippled`, you can also use the `fee_mult_max` parameter of the [`sign` command](reference-rippled.html#sign) to set a limit to the load scaling you are willing to sign.
|
||||||
* You cannot look up the current transaction cost from an offline machine.
|
* You cannot look up the current transaction cost from an offline machine.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Transaction Costs and Failed Transactions ##
|
## Transaction Costs and Failed Transactions ##
|
||||||
|
|
||||||
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, `rippled` servers attempt to include failed transactions in ledgers, with [`tec` status codes](transactions.html#result-categories) ("tec" stands for "Transaction Engine - Claimed fee only").
|
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, `rippled` servers attempt to include failed transactions in ledgers, with [`tec` status codes](reference-transaction-format.html#result-categories) ("tec" stands for "Transaction Engine - Claimed fee only").
|
||||||
|
|
||||||
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 `tec` code.
|
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 `tec` code.
|
||||||
|
|
||||||
If a transaction's failure is [final](transactions.html#finality-of-results), the `rippled` 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.
|
If a transaction's failure is [final](reference-transaction-format.html#finality-of-results), the `rippled` 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.
|
||||||
|
|
||||||
### Insufficient XRP ###
|
### Insufficient XRP ###
|
||||||
|
|
||||||
When a `rippled` server initially evaluates a transaction, it rejects the transaction with the error code `terINSUF_FEE_B` if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a `ter` (Retry) code, the `rippled` server retries the transaction without relaying it to the network, until the transaction's outcome is [final](transactions.html#finality-of-results).
|
When a `rippled` server initially evaluates a transaction, it rejects the transaction with the error code `terINSUF_FEE_B` if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a `ter` (Retry) code, the `rippled` server retries the transaction without relaying it to the network, until the transaction's outcome is [final](reference-transaction-format.html#finality-of-results).
|
||||||
|
|
||||||
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 `tecINSUFF_FEE` occurs instead. In this case, the account pays all the XRP it can, ending with 0 XRP. This can occur because `rippled` 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.
|
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 `tecINSUFF_FEE` occurs instead. In this case, the account pays all the XRP it can, ending with 0 XRP. This can occur because `rippled` 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.
|
||||||
|
|
||||||
|
|
||||||
## Key Reset Transaction ##
|
## Key Reset Transaction ##
|
||||||
|
|
||||||
As a special case, an account can send a [SetRegularKey](transactions.html#setregularkey) transaction with a transaction cost of `0`, as long as the account's [lsfPasswordSpent flag](ripple-ledger.html#accountroot-flags) is disabled. This transaction must be signed by the account's _master key_. Sending this transaction enables the lsfPasswordSpent flag.
|
As a special case, an account can send a [SetRegularKey](reference-transaction-format.html#setregularkey) transaction with a transaction cost of `0`, as long as the account's [lsfPasswordSpent flag](reference-ledger-format.html#accountroot-flags) is disabled. This transaction must be signed by the account's _master key_. Sending this transaction enables the lsfPasswordSpent flag.
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
The [lsfPasswordSpent flag](ripple-ledger.html#accountroot-flags) starts out disabled. If enabled, it gets disabled again when the account receives a [Payment](transactions.html#payment) of XRP.
|
The [lsfPasswordSpent flag](reference-ledger-format.html#accountroot-flags) starts out disabled. If enabled, it gets disabled again when the account receives a [Payment](reference-transaction-format.html#payment) of XRP.
|
||||||
|
|
||||||
|
|
||||||
## Changing the Transaction Cost ##
|
## Changing the Transaction Cost ##
|
||||||
|
|
||||||
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 [Fee Voting](fee-voting.html) for more information.
|
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 [Fee Voting](concept-fee-voting.html) for more information.
|
||||||
@@ -30,15 +30,15 @@ The transfer fee is represented by a setting on the issuing (**cold wallet**) ac
|
|||||||
|
|
||||||
In RippleAPI, the transfer fee is specified in the `transferRate` field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A `transferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `transferRate` is set to no fee. The value of `transferRate` cannot be less than `1000000000` or more than `2000000000`. The value `null` is special: it is equivalent to `1000000000`, meaning no fee.
|
In RippleAPI, the transfer fee is specified in the `transferRate` field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A `transferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `transferRate` is set to no fee. The value of `transferRate` cannot be less than `1000000000` or more than `2000000000`. The value `null` is special: it is equivalent to `1000000000`, meaning no fee.
|
||||||
|
|
||||||
A gateway can send a [Settings transaction](rippleapi.html#settings) with its cold wallet to change the `transferRate` for its issuances.
|
A gateway can send a [Settings transaction](reference-rippleapi.html#settings) with its cold wallet to change the `transferRate` for its issuances.
|
||||||
|
|
||||||
You can check an account's `transferRate` with the [getSettings method](rippleapi.html#getsettings).
|
You can check an account's `transferRate` with the [getSettings method](reference-rippleapi.html#getsettings).
|
||||||
|
|
||||||
## rippled ##
|
## rippled ##
|
||||||
|
|
||||||
In `rippled`'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `TransferRate` is set at `1000000000`, indicating no fee. The value of `TransferRate` cannot be less than `1000000000` or more than `2000000000`. However, value `0` is special: it is equivalent to `1000000000`, meaning no fee.
|
In `rippled`'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `TransferRate` is set at `1000000000`, indicating no fee. The value of `TransferRate` cannot be less than `1000000000` or more than `2000000000`. However, value `0` is special: it is equivalent to `1000000000`, meaning no fee.
|
||||||
|
|
||||||
A gateway can submit an [AccountSet transaction](transactions.html#accountset) from its cold wallet to change the `TransferRate` for its issuances.
|
A gateway can submit an [AccountSet transaction](reference-transaction-format.html#accountset) from its cold wallet to change the `TransferRate` for its issuances.
|
||||||
|
|
||||||
You can check an account's `TransferRate` with the [`account_info` command](rippled-apis.html#account-info). If the `TransferRate` is omitted, then that indicates no fee.
|
You can check an account's `TransferRate` with the [`account_info` command](reference-rippled.html#account-info). If the `TransferRate` is omitted, then that indicates no fee.
|
||||||
|
|
||||||
@@ -1,5 +1,5 @@
|
|||||||
A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.
|
A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.
|
||||||
|
|
||||||
Every [account object in the Ripple Consensus Ledger](ripple-ledger.html#accountroot) has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a `Sequence` field that matches the sending account's current `Sequence` number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be identical.
|
Every [account object in the Ripple Consensus Ledger](reference-ledger-format.html#accountroot) has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a `Sequence` field that matches the sending account's current `Sequence` number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be identical.
|
||||||
|
|
||||||
Every [Offer node in the Ripple Consensus Ledger](ripple-ledger.html#offer) is marked with the sending `Account` [Address][] and the `Sequence` value of the [OfferCreate transaction](transactions.html#offercreate) that created it. These two fields, together, uniquely identify the Offer.
|
Every [Offer node in the Ripple Consensus Ledger](reference-ledger-format.html#offer) is marked with the sending `Account` [Address][] and the `Sequence` value of the [OfferCreate transaction](reference-transaction-format.html#offercreate) that created it. These two fields, together, uniquely identify the Offer.
|
||||||
|
|||||||
@@ -15,7 +15,7 @@ Some addresses have special meaning, or historical uses, in the Ripple Consensus
|
|||||||
| Address | Name | Meaning | Black Hole? |
|
| Address | Name | Meaning | Black Hole? |
|
||||||
|-----------------------------|------|---------|-------------|
|
|-----------------------------|------|---------|-------------|
|
||||||
| rrrrrrrrrrrrrrrrrrrrrhoLvTp | ACCOUNT\_ZERO | An address that is the base-58 encoding of the value `0`. In peer-to-peer communications, `rippled` uses this address as the issuer for XRP. | Yes |
|
| rrrrrrrrrrrrrrrrrrrrrhoLvTp | ACCOUNT\_ZERO | An address that is the base-58 encoding of the value `0`. In peer-to-peer communications, `rippled` uses this address as the issuer for XRP. | Yes |
|
||||||
| rrrrrrrrrrrrrrrrrrrrBZbvji | ACCOUNT\_ONE | An address that is the base-58 encoding of the value `1`. In the ledger, [RippleState entries](ripple-ledger.html#ripplestate) use this address as a placeholder for the issuer of a trust line balance. | Yes |
|
| rrrrrrrrrrrrrrrrrrrrBZbvji | ACCOUNT\_ONE | An address that is the base-58 encoding of the value `1`. In the ledger, [RippleState entries](reference-ledger-format.html#ripplestate) use this address as a placeholder for the issuer of a trust line balance. | Yes |
|
||||||
| rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh | The genesis account | When `rippled` starts a new genesis ledger from scratch (for example, in stand-alone mode), this account holds all the XRP. This address is generated from the seed value "masterpassphrase" which is [hard-coded](https://github.com/ripple/rippled/blob/94ed5b3a53077d815ad0dd65d490c8d37a147361/src/ripple/app/ledger/Ledger.cpp#L184). | No |
|
| rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh | The genesis account | When `rippled` starts a new genesis ledger from scratch (for example, in stand-alone mode), this account holds all the XRP. This address is generated from the seed value "masterpassphrase" which is [hard-coded](https://github.com/ripple/rippled/blob/94ed5b3a53077d815ad0dd65d490c8d37a147361/src/ripple/app/ledger/Ledger.cpp#L184). | No |
|
||||||
| rrrrrrrrrrrrrrrrrNAMEtxvNvQ | Ripple Name reservation black-hole | In the past, Ripple asked users to send XRP to this account to reserve Ripple Names.| Yes |
|
| rrrrrrrrrrrrrrrrrNAMEtxvNvQ | Ripple Name reservation black-hole | In the past, Ripple asked users to send XRP to this account to reserve Ripple Names.| Yes |
|
||||||
| rrrrrrrrrrrrrrrrrrrn5RM1rHd | NaN Address | Previous versions of [ripple-lib](https://github.com/ripple/ripple-lib) generated this address when base-58 encoding the value [NaN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN). | Yes |
|
| rrrrrrrrrrrrrrrrrrrn5RM1rHd | NaN Address | Previous versions of [ripple-lib](https://github.com/ripple/ripple-lib) generated this address when base-58 encoding the value [NaN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN). | Yes |
|
||||||
|
|||||||
@@ -258,8 +258,8 @@ Optionally, you can include the following query parameters:
|
|||||||
| start | String - [Timestamp][] | Filter results to this time and later. |
|
| start | String - [Timestamp][] | Filter results to this time and later. |
|
||||||
| end | String - [Timestamp][] | Filter results to this time and earlier. |
|
| end | String - [Timestamp][] | Filter results to this time and earlier. |
|
||||||
| descending | Boolean | If true, return results in reverse chronological order. Defaults to false. |
|
| descending | Boolean | If true, return results in reverse chronological order. Defaults to false. |
|
||||||
| type | String | Filter transactions to a specific [transaction type](transactions.html). |
|
| type | String | Filter transactions to a specific [transaction type](reference-transaction-format.html). |
|
||||||
| result | String | Filter transactions for a specific [transaction result](transactions.html#transaction-results). |
|
| result | String | Filter transactions for a specific [transaction result](reference-transaction-format.html#transaction-results). |
|
||||||
| binary | Boolean | If true, return transactions in binary form. Defaults to false. |
|
| binary | Boolean | If true, return transactions in binary form. Defaults to false. |
|
||||||
| limit | Integer | Max results per page (defaults to 20). Cannot be more than 100. |
|
| limit | Integer | Max results per page (defaults to 20). Cannot be more than 100. |
|
||||||
| marker | String | [Pagination](#pagination) marker from a previous response. |
|
| marker | String | [Pagination](#pagination) marker from a previous response. |
|
||||||
@@ -997,8 +997,8 @@ The `family` and `metrics` query parameters provide a way to filter results to a
|
|||||||
|
|
||||||
| Family | Included Metrics | Meaning |
|
| Family | Included Metrics | Meaning |
|
||||||
|--------|------------------|---------|
|
|--------|------------------|---------|
|
||||||
| type | All Ripple [transaction types](transactions.html), including `Payment`, `AccountSet`, `SetRegularKey`, `OfferCreate`, `OfferCancel`, `TrustSet`. | Number of transactions of the given type that occurred during the interval. |
|
| type | All Ripple [transaction types](reference-transaction-format.html), including `Payment`, `AccountSet`, `SetRegularKey`, `OfferCreate`, `OfferCancel`, `TrustSet`. | Number of transactions of the given type that occurred during the interval. |
|
||||||
| result | All [transaction result codes](transactions.html#transaction-results) (string codes, not the numeric codes), including `tesSUCCESS`, `tecPATH_DRY`, and many others. | Number of transactions that resulted in the given code during the interval. |
|
| result | All [transaction result codes](reference-transaction-format.html#transaction-results) (string codes, not the numeric codes), including `tesSUCCESS`, `tecPATH_DRY`, and many others. | Number of transactions that resulted in the given code during the interval. |
|
||||||
| metric | Data-API defined Special Transaction Metrics. | (Varies) |
|
| metric | Data-API defined Special Transaction Metrics. | (Varies) |
|
||||||
|
|
||||||
##### Special Transaction Metrics #####
|
##### Special Transaction Metrics #####
|
||||||
@@ -1843,8 +1843,8 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the
|
|||||||
|-------------|--------|-------------|
|
|-------------|--------|-------------|
|
||||||
| name | String | Human-readable name of the gateway
|
| name | String | Human-readable name of the gateway
|
||||||
| start\_date | String - [Timestamp][] | The approximate date of the first time exchanges for this gateway's currencies appeared in the ledger. |
|
| start\_date | String - [Timestamp][] | The approximate date of the first time exchanges for this gateway's currencies appeared in the ledger. |
|
||||||
| accounts | Array | A list of [issuing accounts](gateway_guide.html#hot-and-cold-wallets) (cold wallets) used by this gateway. (Gateways may use different issuing accounts for different currencies.) |
|
| accounts | Array | A list of [issuing accounts](concept-issuing-and-operational-accounts.html) (cold wallets) used by this gateway. (Gateways may use different issuing accounts for different currencies.) |
|
||||||
| hotwallets | Array of [Address][]es | The addresses of the Ripple accounts this gateway uses as [hot wallets](gateway_guide.html#hot-and-cold-wallets). |
|
| hotwallets | Array of [Address][]es | The addresses of the Ripple accounts this gateway uses as [operational accounts](concept-issuing-and-operational-accounts.html). |
|
||||||
| domain | String | The domain name where this gateway does business. Typically the gateway hosts a [`ripple.txt`](https://wiki.ripple.com/Ripple.txt) there. |
|
| domain | String | The domain name where this gateway does business. Typically the gateway hosts a [`ripple.txt`](https://wiki.ripple.com/Ripple.txt) there. |
|
||||||
| normalized | String | A normalized version of the `name` field suitable for including in URLs. |
|
| normalized | String | A normalized version of the `name` field suitable for including in URLs. |
|
||||||
| assets | Array of Strings | Graphics filenames available for this gateway, if any. (Mostly, these are logos used by Ripple Charts.) |
|
| assets | Array of Strings | Graphics filenames available for this gateway, if any. (Mostly, these are logos used by Ripple Charts.) |
|
||||||
@@ -1853,7 +1853,7 @@ Each object in the `accounts` field array has the following fields:
|
|||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|------------|--------|-------------|
|
|------------|--------|-------------|
|
||||||
| address | String | The [Address][] of an [issuing account](gateway_guide.html#hot-and-cold-wallets) (cold wallet) used by this gateway. |
|
| address | String | The [Address][] of an [issuing account](concept-issuing-and-operational-accounts.html) (cold wallet) used by this gateway. |
|
||||||
| currencies | Object | Each field in this object is a [Currency Code][] corresponding to a currency issued from this address. Each value is an object with a `featured` boolean indicating whether that currency is featured. Ripple, Inc. decides which currencies and gateways to feature based on responsible business practices, volume, and other measures. |
|
| currencies | Object | Each field in this object is a [Currency Code][] corresponding to a currency issued from this address. Each value is an object with a `featured` boolean indicating whether that currency is featured. Ripple, Inc. decides which currencies and gateways to feature based on responsible business practices, volume, and other measures. |
|
||||||
|
|
||||||
#### Example ####
|
#### Example ####
|
||||||
@@ -2367,7 +2367,7 @@ Optionally, you can also include the following query parameters:
|
|||||||
| end | String | UTC end time of query range |
|
| end | String | UTC end time of query range |
|
||||||
| min_sequence | String | Minimum sequence number to query |
|
| min_sequence | String | Minimum sequence number to query |
|
||||||
| max_sequence | String | Max sequence number to query |
|
| max_sequence | String | Max sequence number to query |
|
||||||
| type | String | Restrict results to a specified [transaction type](transactions.html) |
|
| type | String | Restrict results to a specified [transaction type](reference-transaction-format.html) |
|
||||||
| result | String | Restrict results to specified transaction result |
|
| result | String | Restrict results to specified transaction result |
|
||||||
| binary | Boolean | Return results in binary format |
|
| binary | Boolean | Return results in binary format |
|
||||||
| descending | Boolean | Reverse chronological order |
|
| descending | Boolean | Reverse chronological order |
|
||||||
@@ -3058,7 +3058,7 @@ Transactions have two formats - a compact "binary" format where the defining fie
|
|||||||
| hash | String - [Hash][] | An identifying hash value unique to this transaction, as a hex string. |
|
| hash | String - [Hash][] | An identifying hash value unique to this transaction, as a hex string. |
|
||||||
| date | String - [Timestamp][] | The time when this transaction was included in a validated ledger. |
|
| date | String - [Timestamp][] | The time when this transaction was included in a validated ledger. |
|
||||||
| ledger_index | Number - [Ledger Index][] | The sequence number of the ledger that included this ledger. |
|
| ledger_index | Number - [Ledger Index][] | The sequence number of the ledger that included this ledger. |
|
||||||
| tx | Object | The fields of this transaction object, as defined by the [Transaction Format](https://ripple.com/build/transactions) |
|
| tx | Object | The fields of this transaction object, as defined by the [Transaction Format](reference-transaction-format.html) |
|
||||||
| meta | Object | Metadata about the results of this transaction. |
|
| meta | Object | Metadata about the results of this transaction. |
|
||||||
|
|
||||||
### Binary Format ###
|
### Binary Format ###
|
||||||
@@ -3176,7 +3176,7 @@ A Payment Summary Object contains a reduced amount of information about a single
|
|||||||
## Payment Objects ##
|
## Payment Objects ##
|
||||||
[Payment Objects]: #payment-objects
|
[Payment Objects]: #payment-objects
|
||||||
|
|
||||||
In the Data API, a Payment Object represents an event where one account sent value to another account. This mostly lines up with Ripple transactions of the `Payment` [transaction type](transactions.html), except that the Data API does not consider a transaction to be a payment if the sending `Account` and the `Destination` account are the same, or if the transaction failed.
|
In the Data API, a Payment Object represents an event where one account sent value to another account. This mostly lines up with Ripple transactions of the `Payment` [transaction type](reference-transaction-format.html), except that the Data API does not consider a transaction to be a payment if the sending `Account` and the `Destination` account are the same, or if the transaction failed.
|
||||||
|
|
||||||
Payment objects have the following fields:
|
Payment objects have the following fields:
|
||||||
|
|
||||||
@@ -11,7 +11,7 @@ A single ledger version consists of several components:
|
|||||||
|
|
||||||
|
|
||||||
* A **header** - The ledger's unique index (sequence number), hashes of the other contents, and other metadata.
|
* A **header** - The ledger's unique index (sequence number), hashes of the other contents, and other metadata.
|
||||||
* A **transaction tree** - The [transactions](transactions.html) that were applied to the previous ledger to make this one. Transactions are the _only_ way to modify the ledger.
|
* A **transaction tree** - The [transactions](reference-transaction-format.html) that were applied to the previous ledger to make this one. Transactions are the _only_ way to modify the ledger.
|
||||||
* A **state tree** - All the [ledger nodes](#ledger-node-types) that contain the settings, balances, and objects in the ledger as of this version.
|
* A **state tree** - All the [ledger nodes](#ledger-node-types) that contain the settings, balances, and objects in the ledger as of this version.
|
||||||
|
|
||||||
|
|
||||||
@@ -29,7 +29,7 @@ In the case of state nodes, `rippled` usually includes the `index` of the node a
|
|||||||
## Header Format ##
|
## Header Format ##
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/ledger/ReadView.h#L68 "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/ledger/ReadView.h#L68 "Source")
|
||||||
|
|
||||||
Every ledger version has a unique header that describes the contents. You can look up a ledger's header information with the [`ledger` command](rippled-apis.html#ledger). The contents of the ledger header are as follows:
|
Every ledger version has a unique header that describes the contents. You can look up a ledger's header information with the [`ledger` command](reference-rippled.html#ledger). The contents of the ledger header are as follows:
|
||||||
|
|
||||||
| Field | JSON Type | [Internal Type][] | Description |
|
| Field | JSON Type | [Internal Type][] | Description |
|
||||||
|-----------------|-----------|-------------------|-------------|
|
|-----------------|-----------|-------------------|-------------|
|
||||||
@@ -63,7 +63,7 @@ There are several different kinds of nodes that can appear in the ledger's state
|
|||||||
* [**Offer** - An offer to exchange currencies, known in finance as an _order_.](#offer)
|
* [**Offer** - An offer to exchange currencies, known in finance as an _order_.](#offer)
|
||||||
* [**RippleState** - Links two accounts, tracking the balance of one currency between them. The concept of a _trust line_ is really an abstraction of this node type.](#ripplestate)
|
* [**RippleState** - Links two accounts, tracking the balance of one currency between them. The concept of a _trust line_ is really an abstraction of this node type.](#ripplestate)
|
||||||
|
|
||||||
Each ledger node consists of several fields. In the peer protocol that `rippled` servers use to communicate with each other, ledger nodes are represented in their raw binary format. In other [`rippled` APIs](rippled-apis.html), ledger nodes are represented as JSON objects.
|
Each ledger node consists of several fields. In the peer protocol that `rippled` servers use to communicate with each other, ledger nodes are represented in their raw binary format. In other [`rippled` APIs](reference-rippled.html), ledger nodes are represented as JSON objects.
|
||||||
|
|
||||||
## AccountRoot ##
|
## AccountRoot ##
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L27 "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L27 "Source")
|
||||||
@@ -102,7 +102,7 @@ The `AccountRoot` node has the following fields:
|
|||||||
| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
|
| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
|
||||||
| PreviousTxnLgrSeq | Number | UInt32 | The sequence number (`ledger_index`) of the ledger that contains the transaction that most recently modified this node. |
|
| PreviousTxnLgrSeq | Number | UInt32 | The sequence number (`ledger_index`) of the ledger that contains the transaction that most recently modified this node. |
|
||||||
| AccountTxnID | String | Hash256 | (Optional) The identifying hash of the transaction most recently submitted by this account. |
|
| AccountTxnID | String | Hash256 | (Optional) The identifying hash of the transaction most recently submitted by this account. |
|
||||||
| RegularKey | String | AccountID | (Optional) The address of a keypair that can be used to sign transactions for this account instead of the master key. Use a [SetRegularKey transaction](transactions.html#setregularkey) to change this value. |
|
| RegularKey | String | AccountID | (Optional) The address of a keypair that can be used to sign transactions for this account instead of the master key. Use a [SetRegularKey transaction](reference-transaction-format.html#setregularkey) to change this value. |
|
||||||
| EmailHash | String | Hash128 | (Optional) The md5 hash of an email address. Clients can use this to look up an avatar through services such as [Gravatar](https://en.gravatar.com/). |
|
| EmailHash | String | Hash128 | (Optional) The md5 hash of an email address. Clients can use this to look up an avatar through services such as [Gravatar](https://en.gravatar.com/). |
|
||||||
| WalletLocator | String | Hash256 | (Optional) **DEPRECATED**. Do not use. |
|
| WalletLocator | String | Hash256 | (Optional) **DEPRECATED**. Do not use. |
|
||||||
| WalletSize | Number | UInt32 | (Optional) **DEPRECATED**. Do not use. |
|
| WalletSize | Number | UInt32 | (Optional) **DEPRECATED**. Do not use. |
|
||||||
@@ -112,11 +112,11 @@ The `AccountRoot` node has the following fields:
|
|||||||
|
|
||||||
### AccountRoot Flags ###
|
### AccountRoot Flags ###
|
||||||
|
|
||||||
There are several options which can be either enabled or disabled for an account. These options can be changed with an [AccountSet transaction](transactions.html#accountset). In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_.
|
There are several options which can be either enabled or disabled for an account. These options can be changed with an [AccountSet transaction](reference-transaction-format.html#accountset). In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_.
|
||||||
|
|
||||||
AccountRoot nodes can have the following flag values:
|
AccountRoot nodes can have the following flag values:
|
||||||
|
|
||||||
| Flag Name | Hex Value | Decimal Value | Description | Corresponding [AccountSet Flag](transactions.html#accountset-flags) |
|
| Flag Name | Hex Value | Decimal Value | Description | Corresponding [AccountSet Flag](reference-transaction-format.html#accountset-flags) |
|
||||||
|-----------|-----------|---------------|-------------|-------------------------------|
|
|-----------|-----------|---------------|-------------|-------------------------------|
|
||||||
| lsfPasswordSpent | 0x00010000 | 65536 | Indicates that the account has used its free SetRegularKey transaction. | (None) |
|
| lsfPasswordSpent | 0x00010000 | 65536 | Indicates that the account has used its free SetRegularKey transaction. | (None) |
|
||||||
| lsfRequireDestTag | 0x00020000 | 131072 | Requires incoming payments to specify a Destination Tag. | asfRequireDest |
|
| lsfRequireDestTag | 0x00020000 | 131072 | Requires incoming payments to specify a Destination Tag. | asfRequireDest |
|
||||||
@@ -234,9 +234,9 @@ The lower 64 bits of an Offer Directory's index represent the TakerPays amount d
|
|||||||
## Offer ##
|
## Offer ##
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L57 "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L57 "Source")
|
||||||
|
|
||||||
The `Offer` node type describes an offer to exchange currencies, more traditionally known as an _order_, which is currently in an order book in Ripple's distributed exchange. An [OfferCreate transaction](transactions.html#offercreate) only creates an Offer node in the ledger when the offer cannot be fully executed immediately by consuming other offers already in the ledger.
|
The `Offer` node type describes an offer to exchange currencies, more traditionally known as an _order_, which is currently in an order book in Ripple's distributed exchange. An [OfferCreate transaction](reference-transaction-format.html#offercreate) only creates an Offer node in the ledger when the offer cannot be fully executed immediately by consuming other offers already in the ledger.
|
||||||
|
|
||||||
An offer can become unfunded through other activities in the network, while remaining in the ledger. However, `rippled` will automatically prune any unfunded offers it happens across in the course of transaction processing (and _only_ transaction processing, because the ledger state must only be changed by transactions). For more information, see [lifecycle of an offer](transactions.html#lifecycle-of-an-offer).
|
An offer can become unfunded through other activities in the network, while remaining in the ledger. However, `rippled` will automatically prune any unfunded offers it happens across in the course of transaction processing (and _only_ transaction processing, because the ledger state must only be changed by transactions). For more information, see [lifecycle of an offer](reference-transaction-format.html#lifecycle-of-an-offer).
|
||||||
|
|
||||||
Example Offer node:
|
Example Offer node:
|
||||||
|
|
||||||
@@ -268,7 +268,7 @@ An Offer node has the following fields:
|
|||||||
| LedgerEntryType | String | UInt16 | The value `0x6F`, mapped to the string `Offer`, indicates that this node is an Offer object. |
|
| LedgerEntryType | String | UInt16 | The value `0x6F`, mapped to the string `Offer`, indicates that this node is an Offer object. |
|
||||||
| Flags | Number | UInt32 | A bit-map of boolean flags enabled for this offer. |
|
| Flags | Number | UInt32 | A bit-map of boolean flags enabled for this offer. |
|
||||||
| Account | String | AccountID | The address of the account that owns this offer. |
|
| Account | String | AccountID | The address of the account that owns this offer. |
|
||||||
| Sequence | Number | UInt32 | The `Sequence` value of the [OfferCreate](transactions.html#offercreate) transaction that created this Offer node. Used in combination with the `Account` to identify this Offer. |
|
| Sequence | Number | UInt32 | The `Sequence` value of the [OfferCreate](reference-transaction-format.html#offercreate) transaction that created this Offer node. Used in combination with the `Account` to identify this Offer. |
|
||||||
| TakerPays | String or Object | Amount | The remaining amount and type of currency requested by the offer creator. |
|
| TakerPays | String or Object | Amount | The remaining amount and type of currency requested by the offer creator. |
|
||||||
| TakerGets | String or Object | Amount | The remaining amount and type of currency being provided by the offer creator. |
|
| TakerGets | String or Object | Amount | The remaining amount and type of currency being provided by the offer creator. |
|
||||||
| BookDirectory | String | UInt256 | The index of the [Offer Directory](#directorynode) that links to this offer. |
|
| BookDirectory | String | UInt256 | The index of the [Offer Directory](#directorynode) that links to this offer. |
|
||||||
@@ -276,15 +276,15 @@ An Offer node has the following fields:
|
|||||||
| OwnerNode | String | UInt64 | A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple nodes. **Note:** The offer does not contain a direct link to the owner directory containing it, since that value can be derived from the `Account`. |
|
| OwnerNode | String | UInt64 | A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple nodes. **Note:** The offer does not contain a direct link to the owner directory containing it, since that value can be derived from the `Account`. |
|
||||||
| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
|
| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
|
||||||
| PreviousTxnLgrSeq | Number | UInt32 | The sequence number (`ledger_index`) of the ledger that contains the transaction that most recently modified this node. |
|
| PreviousTxnLgrSeq | Number | UInt32 | The sequence number (`ledger_index`) of the ledger that contains the transaction that most recently modified this node. |
|
||||||
| Expiration | Number | UInt32 | (Optional) Indicates the time after which this offer will be considered unfunded. See [Specifying Time](rippled-apis.html#specifying-time) for details. |
|
| Expiration | Number | UInt32 | (Optional) Indicates the time after which this offer will be considered unfunded. See [Specifying Time](reference-rippled.html#specifying-time) for details. |
|
||||||
|
|
||||||
### Offer Flags ###
|
### Offer Flags ###
|
||||||
|
|
||||||
There are several options which can be either enabled or disabled when an [OfferCreate transaction](transactions.html#offercreate) creates an offer node. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_.
|
There are several options which can be either enabled or disabled when an [OfferCreate transaction](reference-transaction-format.html#offercreate) creates an offer node. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_.
|
||||||
|
|
||||||
Offer nodes can have the following flag values:
|
Offer nodes can have the following flag values:
|
||||||
|
|
||||||
| Flag Name | Hex Value | Decimal Value | Description | Corresponding [OfferCreate Flag](transactions.html#offercreate-flags) |
|
| Flag Name | Hex Value | Decimal Value | Description | Corresponding [OfferCreate Flag](reference-transaction-format.html#offercreate-flags) |
|
||||||
|-----------|-----------|---------------|-------------|------------------------|
|
|-----------|-----------|---------------|-------------|------------------------|
|
||||||
| lsfPassive | 0x00010000 | 65536 | The node was placed as a passive offer. This has no effect on the node in the ledger. | tfPassive |
|
| lsfPassive | 0x00010000 | 65536 | The node was placed as a passive offer. This has no effect on the node in the ledger. | tfPassive |
|
||||||
| lsfSell | 0x00020000 | 131072 | The node was placed as a sell offer. This has no effect on the node in the ledger (because tfSell only matters if you get a better rate than you asked for, which cannot happen after the node enters the ledger). | tfSell |
|
| lsfSell | 0x00020000 | 131072 | The node was placed as a sell offer. This has no effect on the node in the ledger (because tfSell only matters if you get a better rate than you asked for, which cannot happen after the node enters the ledger). | tfSell |
|
||||||
@@ -354,11 +354,11 @@ A RippleState node has the following fields:
|
|||||||
|
|
||||||
### RippleState Flags ###
|
### RippleState Flags ###
|
||||||
|
|
||||||
There are several options which can be either enabled or disabled for a trust line. These options can be changed with a [TrustSet transaction](transactions.html#trustset). In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_.
|
There are several options which can be either enabled or disabled for a trust line. These options can be changed with a [TrustSet transaction](reference-transaction-format.html#trustset). In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_.
|
||||||
|
|
||||||
RippleState nodes can have the following flag values:
|
RippleState nodes can have the following flag values:
|
||||||
|
|
||||||
| Flag Name | Hex Value | Decimal Value | Description | Corresponding [TrustSet Flag](transactions.html#trustset-flags) |
|
| Flag Name | Hex Value | Decimal Value | Description | Corresponding [TrustSet Flag](reference-transaction-format.html#trustset-flags) |
|
||||||
|-----------|-----------|---------------|-------------|------------------------|
|
|-----------|-----------|---------------|-------------|------------------------|
|
||||||
| lsfLowReserve | 0x00010000 | 65536 | This RippleState node [contributes to the low account's owner reserve](#contributing-to-the-owner-reserve). | (None) |
|
| lsfLowReserve | 0x00010000 | 65536 | This RippleState node [contributes to the low account's owner reserve](#contributing-to-the-owner-reserve). | (None) |
|
||||||
| lsfHighReserve | 0x00020000 |131072 | This RippleState node [contributes to the high account's owner reserve](#contributing-to-the-owner-reserve). | (None) |
|
| lsfHighReserve | 0x00020000 |131072 | This RippleState node [contributes to the high account's owner reserve](#contributing-to-the-owner-reserve). | (None) |
|
||||||
@@ -371,7 +371,7 @@ RippleState nodes can have the following flag values:
|
|||||||
|
|
||||||
### Contributing to the Owner Reserve ###
|
### Contributing to the Owner Reserve ###
|
||||||
|
|
||||||
If an account modifies a trust line to put it in a non-default state, then that trust line counts towards the account's [owner reserve](reserves.html#owner-reserves). In a RippleState node, the `lsfLowReserve` and `lsfHighReserve` flags indicate which account(s) are responsible for the owner reserve. The `rippled` server automatically sets these flags when it modifies a trust line.
|
If an account modifies a trust line to put it in a non-default state, then that trust line counts towards the account's [owner reserve](concept-reserves.html#owner-reserves). In a RippleState node, the `lsfLowReserve` and `lsfHighReserve` flags indicate which account(s) are responsible for the owner reserve. The `rippled` server automatically sets these flags when it modifies a trust line.
|
||||||
|
|
||||||
The values that count towards a trust line's non-default state are as follows:
|
The values that count towards a trust line's non-default state are as follows:
|
||||||
|
|
||||||
@@ -2,13 +2,13 @@
|
|||||||
|
|
||||||
The core peer-to-peer server that operates the Ripple Network is called `rippled`. Each `rippled` server connects to the Ripple Network, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code for `rippled` is written in C++, and is [available on GitHub under an open-source license](https://github.com/ripple/rippled).
|
The core peer-to-peer server that operates the Ripple Network is called `rippled`. Each `rippled` server connects to the Ripple Network, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code for `rippled` is written in C++, and is [available on GitHub under an open-source license](https://github.com/ripple/rippled).
|
||||||
|
|
||||||
* [`rippled` Setup](rippled-setup.html)
|
* [`rippled` Setup](tutorial-rippled-setup.html)
|
||||||
* [API Reference](#api-methods)
|
* [API Reference](#api-methods)
|
||||||
* [Transaction Reference](transactions.html)
|
* [Transaction Reference](reference-transaction-format.html)
|
||||||
* JavaScript Client Library - [RippleAPI](rippleapi.html)
|
* JavaScript Client Library - [RippleAPI](reference-rippleapi.html)
|
||||||
|
|
||||||
# WebSocket and JSON-RPC APIs #
|
# WebSocket and JSON-RPC APIs #
|
||||||
If you want to communicate directly with a `rippled` server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Alternatively, you can use [RippleAPI](rippleapi.html), which is a simplified JavaScript client library, which communicates directly with a `rippled` server from [Node.js](http://nodejs.org/) or a web browser.
|
If you want to communicate directly with a `rippled` server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Alternatively, you can use [RippleAPI](reference-rippleapi.html), which is a simplified JavaScript client library, which communicates directly with a `rippled` server from [Node.js](http://nodejs.org/) or a web browser.
|
||||||
|
|
||||||
* The WebSocket API uses the [WebSocket protocol](http://www.html5rocks.com/en/tutorials/websockets/basics/), available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The `rippled` server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.
|
* The WebSocket API uses the [WebSocket protocol](http://www.html5rocks.com/en/tutorials/websockets/basics/), available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The `rippled` server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.
|
||||||
* The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The `rippled` server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL.
|
* The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The `rippled` server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL.
|
||||||
@@ -26,7 +26,7 @@ The WebSocket and JSON-RPC APIs are still in development, and are subject to cha
|
|||||||
|
|
||||||
Before you can run any commands against a `rippled` server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network.
|
Before you can run any commands against a `rippled` server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network.
|
||||||
|
|
||||||
Alternatively, you can [run your own local copy of `rippled`](rippled-setup.html). This is required if you want to access any of the [Admin Commands](#list-of-admin-commands). In this case, you should use whatever IP and port you configured the server to bind. (For example, `127.0.0.1:54321`) Additionally, in order to access admin functionality, you must connect from a port/IP address marked as admin in the config file.
|
Alternatively, you can [run your own local copy of `rippled`](tutorial-rippled-setup.html). This is required if you want to access any of the [Admin Commands](#list-of-admin-commands). In this case, you should use whatever IP and port you configured the server to bind. (For example, `127.0.0.1:54321`) Additionally, in order to access admin functionality, you must connect from a port/IP address marked as admin in the config file.
|
||||||
|
|
||||||
The [example config file](https://github.com/ripple/rippled/blob/d7def5509d8338b1e46c0adf309b5912e5168af0/doc/rippled-example.cfg#L831-L854) listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.
|
The [example config file](https://github.com/ripple/rippled/blob/d7def5509d8338b1e46c0adf309b5912e5168af0/doc/rippled-example.cfg#L831-L854) listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.
|
||||||
|
|
||||||
@@ -396,7 +396,7 @@ There are two kinds of currencies in the Ripple Consensus Ledger: XRP, and every
|
|||||||
|-------------------|-------------------|
|
|-------------------|-------------------|
|
||||||
| Has no issuer. | Always issued by a Ripple account |
|
| Has no issuer. | Always issued by a Ripple account |
|
||||||
| Specified as a string | Specified as an object |
|
| Specified as a string | Specified as an object |
|
||||||
| Tracked in [accounts](ripple-ledger.html#accountroot) | Tracked in [trust lines](ripple-ledger.html#ripplestate) |
|
| Tracked in [accounts](reference-ledger-format.html#accountroot) | Tracked in [trust lines](reference-ledger-format.html#ripplestate) |
|
||||||
| Can never be created; can only be destroyed | Can be issued or redeemed freely |
|
| Can never be created; can only be destroyed | Can be issued or redeemed freely |
|
||||||
| Maximum value `100000000000` (`1e11`) | Maximum value `9999999999999999e80` |
|
| Maximum value `100000000000` (`1e11`) | Maximum value `9999999999999999e80` |
|
||||||
| Precise to the nearest ["drop"](#xrp) (0.000001 XRP) | 15 decimal digits of precision, with a minimum nonzero absolute value of `1000000000000000e-96` |
|
| Precise to the nearest ["drop"](#xrp) (0.000001 XRP) | 15 decimal digits of precision, with a minimum nonzero absolute value of `1000000000000000e-96` |
|
||||||
@@ -487,7 +487,7 @@ The format of the `marker` field is intentionally undefined. Each server can def
|
|||||||
|
|
||||||
All changes to Ripple's global shared ledger happen as the result of transactions. Consequently, this means that there is *only one* public API method that causes a change in the state of the Ripple Network at all: the [*submit*](#submit) command. Most of the other methods represent different ways to view the data represented in the Ripple Network, and the remaining ones just generate data for your convenience. (The [wallet_propose](#wallet-propose), [path_find](#path-find), and [random](#random) commands fall into this category.)
|
All changes to Ripple's global shared ledger happen as the result of transactions. Consequently, this means that there is *only one* public API method that causes a change in the state of the Ripple Network at all: the [*submit*](#submit) command. Most of the other methods represent different ways to view the data represented in the Ripple Network, and the remaining ones just generate data for your convenience. (The [wallet_propose](#wallet-propose), [path_find](#path-find), and [random](#random) commands fall into this category.)
|
||||||
|
|
||||||
For more information on the various transactions you can submit, consult the [Transaction Format](transactions.html).
|
For more information on the various transactions you can submit, consult the [Transaction Format](reference-transaction-format.html).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -564,7 +564,7 @@ The `rippled` application, in addition to acting as a server, can be run (as a s
|
|||||||
|
|
||||||
|
|
||||||
# Account Information #
|
# Account Information #
|
||||||
Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The [reserve for an account](reserves.html) increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.
|
Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The [reserve for an account](concept-reserves.html) increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.
|
||||||
|
|
||||||
|
|
||||||
## account_currencies ##
|
## account_currencies ##
|
||||||
@@ -707,7 +707,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
| send\_currencies | Array of Strings | Array of [Currency Code][]s for currencies that this account can send. |
|
| send\_currencies | Array of Strings | Array of [Currency Code][]s for currencies that this account can send. |
|
||||||
| validated | Boolean | If `true`, this data comes from a validated ledger. |
|
| validated | Boolean | If `true`, this data comes from a validated ledger. |
|
||||||
|
|
||||||
*Note:* The currencies that an account can send or receive are defined based on a simple check of its trust lines. If an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trust line's balance can go down, the account can send that currency. This method *doesn't* check whether the trust line is [frozen](freeze.html) or authorized.
|
*Note:* The currencies that an account can send or receive are defined based on a simple check of its trust lines. If an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trust line's balance can go down, the account can send that currency. This method *doesn't* check whether the trust line is [frozen](concept-freeze.html) or authorized.
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
|
|
||||||
@@ -810,7 +810,7 @@ The response follows the [standard format](#response-formatting), with the resul
|
|||||||
|
|
||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| account_data | Object | The [AccountRoot ledger node](ripple-ledger.html#accountroot) with this account's information, as stored in the ledger. |
|
| account_data | Object | The [AccountRoot ledger node](reference-ledger-format.html#accountroot) with this account's information, as stored in the ledger. |
|
||||||
| ledger\_current\_index | Integer | (Omitted if `ledger_index` is provided instead) The sequence number of the most-current ledger, which was used when retrieving this information. The information does not contain any changes from ledgers newer than this one. |
|
| ledger\_current\_index | Integer | (Omitted if `ledger_index` is provided instead) The sequence number of the most-current ledger, which was used when retrieving this information. The information does not contain any changes from ledgers newer than this one. |
|
||||||
| ledger\_index | Integer | (Omitted if `ledger_current_index` is provided instead) The sequence number of the ledger used when retrieving this information. The information does not contain any changes from ledgers newer than this one. |
|
| ledger\_index | Integer | (Omitted if `ledger_current_index` is provided instead) The sequence number of the ledger used when retrieving this information. The information does not contain any changes from ledgers newer than this one. |
|
||||||
| validated | Boolean | True if this data is from a validated ledger version; if omitted or set to false, this data is not final. _(New in [version 0.26.0][])_ |
|
| validated | Boolean | True if this data is from a validated ledger version; if omitted or set to false, this data is not final. _(New in [version 0.26.0][])_ |
|
||||||
@@ -997,8 +997,8 @@ Each trust-line object has some combination of the following fields:
|
|||||||
| quality\_out | Unsigned Integer | Rate at which the account values outgoing balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio. |
|
| quality\_out | Unsigned Integer | Rate at which the account values outgoing balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio. |
|
||||||
| no\_ripple | Boolean | (May be omitted) `true` if this account has enabled the [NoRipple flag](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) for this line. If omitted, that is the same as `false`. |
|
| no\_ripple | Boolean | (May be omitted) `true` if this account has enabled the [NoRipple flag](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) for this line. If omitted, that is the same as `false`. |
|
||||||
| no\_ripple\_peer | Boolean | (May be omitted) `true` if the peer account has enabled the [NoRipple flag](https://ripple.com/knowledge_center/understanding-the-noripple-flag/). If omitted, that is the same as `false`. |
|
| no\_ripple\_peer | Boolean | (May be omitted) `true` if the peer account has enabled the [NoRipple flag](https://ripple.com/knowledge_center/understanding-the-noripple-flag/). If omitted, that is the same as `false`. |
|
||||||
| freeze | Boolean | (May be omitted) `true` if this account has [frozen](freeze.html) this trust line. If omitted, that is the same as `false`. |
|
| freeze | Boolean | (May be omitted) `true` if this account has [frozen](concept-freeze.html) this trust line. If omitted, that is the same as `false`. |
|
||||||
| freeze\_peer | Boolean | (May be omitted) `true` if the peer account has [frozen](freeze.html) this trust line. If omitted, that is the same as `false`. |
|
| freeze\_peer | Boolean | (May be omitted) `true` if the peer account has [frozen](concept-freeze.html) this trust line. If omitted, that is the same as `false`. |
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
|
|
||||||
@@ -1189,7 +1189,7 @@ Each offer object contains the following fields:
|
|||||||
| taker_gets | String or Object | The amount the account accepting the offer receives, as a String representing an amount in XRP, or a currency specification object. (See [Specifying Currency Amounts](#specifying-currency-amounts)) |
|
| taker_gets | String or Object | The amount the account accepting the offer receives, as a String representing an amount in XRP, or a currency specification object. (See [Specifying Currency Amounts](#specifying-currency-amounts)) |
|
||||||
| taker_pays | String or Object | The amount the account accepting the offer provides, as a String representing an amount in XRP, or a currency specification object. (See [Specifying Currency Amounts](#specifying-currency-amounts)) |
|
| taker_pays | String or Object | The amount the account accepting the offer provides, as a String representing an amount in XRP, or a currency specification object. (See [Specifying Currency Amounts](#specifying-currency-amounts)) |
|
||||||
| quality | Number | The exchange rate of the offer, as the ratio of the original `taker_pays` divided by the original `taker_gets`. When executing offers, the offer with the most favorable (lowest) quality is consumed first; offers with the same quality are executed from oldest to newest. _(New in [version 0.29.0][])_ |
|
| quality | Number | The exchange rate of the offer, as the ratio of the original `taker_pays` divided by the original `taker_gets`. When executing offers, the offer with the most favorable (lowest) quality is consumed first; offers with the same quality are executed from oldest to newest. _(New in [version 0.29.0][])_ |
|
||||||
| expiration | Unsigned integer | (May be omitted) A time after which this offer is considered unfunded, as [the number of seconds since the Ripple Epoch](#specifying-time). See also: [Offer Expiration](transactions.html#expiration). _(New in [version 0.30.1][])_ |
|
| expiration | Unsigned integer | (May be omitted) A time after which this offer is considered unfunded, as [the number of seconds since the Ripple Epoch](#specifying-time). See also: [Offer Expiration](reference-transaction-format.html#expiration). _(New in [version 0.30.1][])_ |
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
|
|
||||||
@@ -1203,9 +1203,9 @@ Each offer object contains the following fields:
|
|||||||
## account_objects ##
|
## account_objects ##
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/399c43cae6e90a428e9ce6a988123972b0f03c99/src/ripple/rpc/handlers/AccountObjects.cpp "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/399c43cae6e90a428e9ce6a988123972b0f03c99/src/ripple/rpc/handlers/AccountObjects.cpp "Source")
|
||||||
|
|
||||||
The `account_objects` command returns the raw [ledger format][] for all objects owned by an account, such as [outstanding offers](transactions.html#lifecycle-of-an-offer), trust lines in non-default state, and tickets (which are part of forthcoming multi-sign code). For getting the balance of an account's trust lines, we recommend [`account_lines`](#account-lines) instead.
|
The `account_objects` command returns the raw [ledger format][] for all objects owned by an account, such as [outstanding offers](reference-transaction-format.html#lifecycle-of-an-offer), trust lines in non-default state, and tickets (which are part of forthcoming multi-sign code). For getting the balance of an account's trust lines, we recommend [`account_lines`](#account-lines) instead.
|
||||||
|
|
||||||
[ledger format]: ripple-ledger.html
|
[ledger format]: reference-ledger-format.html
|
||||||
|
|
||||||
#### Request Format ####
|
#### Request Format ####
|
||||||
An example of the request format:
|
An example of the request format:
|
||||||
@@ -2454,7 +2454,7 @@ The request includes the following parameters:
|
|||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| account | String | A unique identifier for the account, most commonly the account's address. |
|
| account | String | A unique identifier for the account, most commonly the account's address. |
|
||||||
| role | String | Whether the account refers to a `gateway` or `user`. Recommendations depend on the role of the account. Gateways must have DefaultRipple enabled and must disable NoRipple on all trust lines. Users should have DefaultRipple disabled, and should enable NoRipple on all trust lines. |
|
| role | String | Whether the account refers to a `gateway` or `user`. Recommendations depend on the role of the account. Gateways must have DefaultRipple enabled and must disable NoRipple on all trust lines. Users should have DefaultRipple disabled, and should enable NoRipple on all trust lines. |
|
||||||
| transactions | Boolean | (Optional) If `true`, include an array of suggested [transactions](transactions.html), as JSON objects, that you can sign and submit to fix the problems. Defaults to false. |
|
| transactions | Boolean | (Optional) If `true`, include an array of suggested [transactions](reference-transaction-format.html), as JSON objects, that you can sign and submit to fix the problems. Defaults to false. |
|
||||||
| limit | Unsigned Integer | (Optional) The maximum number of trust line problems to include in the results. Defaults to 300. |
|
| limit | Unsigned Integer | (Optional) The maximum number of trust line problems to include in the results. Defaults to 300. |
|
||||||
| ledger_hash | String | (Optional) A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) |
|
| ledger_hash | String | (Optional) A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) |
|
||||||
| ledger_index | String or Unsigned Integer| (Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers))|
|
| ledger_index | String or Unsigned Integer| (Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers))|
|
||||||
@@ -2576,7 +2576,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| ledger\_current\_index | Number | The sequence number of the ledger used to calculate these results. |
|
| ledger\_current\_index | Number | The sequence number of the ledger used to calculate these results. |
|
||||||
| problems | Array | Array of strings with human-readable descriptions of the problems. This includes up to one entry if the account's DefaultRipple setting is not as recommended, plus up to `limit` entries for trust lines whose NoRipple setting is not as recommended. |
|
| problems | Array | Array of strings with human-readable descriptions of the problems. This includes up to one entry if the account's DefaultRipple setting is not as recommended, plus up to `limit` entries for trust lines whose NoRipple setting is not as recommended. |
|
||||||
| transactions | Array | (May be omitted) If the request specified `transactions` as `true`, this is an array of JSON objects, each of which is the JSON form of a [transaction](transactions.html) that should fix one of the described problems. The length of this array is the same as the `problems` array, and each entry is intended to fix the problem described at the same index into that array. |
|
| transactions | Array | (May be omitted) If the request specified `transactions` as `true`, this is an array of JSON objects, each of which is the JSON form of a [transaction](reference-transaction-format.html) that should fix one of the described problems. The length of this array is the same as the `problems` array, and each entry is intended to fix the problem described at the same index into that array. |
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
|
|
||||||
@@ -2887,7 +2887,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
| public\_key | String | The public key of the account, in encoded string format. |
|
| public\_key | String | The public key of the account, in encoded string format. |
|
||||||
| public\_key\_hex | String | The public key of the account, in hex format. |
|
| public\_key\_hex | String | The public key of the account, in hex format. |
|
||||||
|
|
||||||
The key generated by this method can also be used as a regular key for an account if you use the [SetRegularKey transaction type](transactions.html#setregularkey) to do so.
|
The key generated by this method can also be used as a regular key for an account if you use the [SetRegularKey transaction type](reference-transaction-format.html#setregularkey) to do so.
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
|
|
||||||
@@ -3048,7 +3048,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| ledger | Object | The complete header data of this ledger. |
|
| ledger | Object | The complete header data of this ledger. |
|
||||||
| ledger.account\_hash | String | Hash of all account state information in this ledger, as hex |
|
| ledger.account\_hash | String | Hash of all account state information in this ledger, as hex |
|
||||||
| ledger.accounts | Array | (Omitted unless requested) All the [account-state information](ripple-ledger.html) in this ledger. |
|
| ledger.accounts | Array | (Omitted unless requested) All the [account-state information](reference-ledger-format.html) in this ledger. |
|
||||||
| ledger.close\_time | Integer | The time this ledger was closed, in seconds since the [Ripple Epoch](#specifying-time) |
|
| ledger.close\_time | Integer | The time this ledger was closed, in seconds since the [Ripple Epoch](#specifying-time) |
|
||||||
| ledger.close\_time_human | String | The time this ledger was closed, in human-readable format |
|
| ledger.close\_time_human | String | The time this ledger was closed, in human-readable format |
|
||||||
| ledger.close\_time\_resolution | Integer | Ledger close times are rounded to within this many seconds. |
|
| ledger.close\_time\_resolution | Integer | Ledger close times are rounded to within this many seconds. |
|
||||||
@@ -3064,11 +3064,11 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
|
|
||||||
The following fields are deprecated and may be removed without further notice: `accepted`, `hash`, `seqNum`, `totalCoins`.
|
The following fields are deprecated and may be removed without further notice: `accepted`, `hash`, `seqNum`, `totalCoins`.
|
||||||
|
|
||||||
**Note on `owner_funds`:** If the request specified `"owner_funds": true` and expanded transactions, the response has a field `owner_funds` in the `metaData` object of each [OfferCreate-type transaction](transactions.html#offercreate). The purpose of this field is to make it easier to track the [funding status of offers](transactions.html#lifecycle-of-an-offer) with each new validated ledger. This field is defined slightly different than the version of this field in [Order Book subscription streams](#order-book-streams):
|
**Note on `owner_funds`:** If the request specified `"owner_funds": true` and expanded transactions, the response has a field `owner_funds` in the `metaData` object of each [OfferCreate-type transaction](reference-transaction-format.html#offercreate). The purpose of this field is to make it easier to track the [funding status of offers](reference-transaction-format.html#lifecycle-of-an-offer) with each new validated ledger. This field is defined slightly different than the version of this field in [Order Book subscription streams](#order-book-streams):
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|--------------|--------|-------------|
|
|--------------|--------|-------------|
|
||||||
| owner\_funds | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is [frozen](freeze.html). |
|
| owner\_funds | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is [frozen](concept-freeze.html). |
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
|
|
||||||
@@ -3546,10 +3546,10 @@ An example of the request format:
|
|||||||
This method can retrieve several different types of data. You can select which type of item to retrieve by passing the appropriate parameters. Specifically, you should provide exactly one of the following fields:
|
This method can retrieve several different types of data. You can select which type of item to retrieve by passing the appropriate parameters. Specifically, you should provide exactly one of the following fields:
|
||||||
|
|
||||||
1. `index` - Retrieve any type of ledger node by its unique index
|
1. `index` - Retrieve any type of ledger node by its unique index
|
||||||
2. `account_root` - Retrieve an [AccountRoot node](ripple-ledger.html#accountroot), similar to the [account_info](#account-info) command
|
2. `account_root` - Retrieve an [AccountRoot node](reference-ledger-format.html#accountroot), similar to the [account_info](#account-info) command
|
||||||
3. `directory` - Retrieve a [DirectoryNode](ripple-ledger.html#directorynode), which contains a list of other nodes
|
3. `directory` - Retrieve a [DirectoryNode](reference-ledger-format.html#directorynode), which contains a list of other nodes
|
||||||
4. `offer` - Retrieve an [Offer node](ripple-ledger.html#offer), which defines an offer to exchange currency
|
4. `offer` - Retrieve an [Offer node](reference-ledger-format.html#offer), which defines an offer to exchange currency
|
||||||
5. `ripple_state` - Retrieve a [RippleState node](ripple-ledger.html#ripplestate), which tracks a (non-XRP) currency balance between two accounts.
|
5. `ripple_state` - Retrieve a [RippleState node](reference-ledger-format.html#ripplestate), which tracks a (non-XRP) currency balance between two accounts.
|
||||||
|
|
||||||
If you specify more than one of the above items, the server will retrieve only of them; it is undefined which one will be chosen.
|
If you specify more than one of the above items, the server will retrieve only of them; it is undefined which one will be chosen.
|
||||||
|
|
||||||
@@ -3558,17 +3558,17 @@ The full list of parameters recognized by this method is as follows:
|
|||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| index | String | (Optional) Specify the unique identifier of a single ledger entry to retrieve. |
|
| index | String | (Optional) Specify the unique identifier of a single ledger entry to retrieve. |
|
||||||
| account\_root | String - [Address][] | (Optional) Specify an [AccountRoot node](ripple-ledger.html#accountroot) to retrieve. |
|
| account\_root | String - [Address][] | (Optional) Specify an [AccountRoot node](reference-ledger-format.html#accountroot) to retrieve. |
|
||||||
| directory | Object or String | (Optional) Specify a [DirectoryNode](ripple-ledger.html#directorynode). (Directory nodes each contain a list of IDs for things contained in them.) If a string, interpret as the [unique index](ripple-ledger.html#tree-format) to the directory, in hex. If an object, requires either `dir_root` or `owner` as a sub-field, plus optionally a `sub_index` sub-field. |
|
| directory | Object or String | (Optional) Specify a [DirectoryNode](reference-ledger-format.html#directorynode). (Directory nodes each contain a list of IDs for things contained in them.) If a string, interpret as the [unique index](reference-ledger-format.html#tree-format) to the directory, in hex. If an object, requires either `dir_root` or `owner` as a sub-field, plus optionally a `sub_index` sub-field. |
|
||||||
| directory.sub\_index | Unsigned Integer | (Optional) If provided, jumps to a further sub-node in the [DirectoryNode](ripple-ledger.html#directorynode). |
|
| directory.sub\_index | Unsigned Integer | (Optional) If provided, jumps to a further sub-node in the [DirectoryNode](reference-ledger-format.html#directorynode). |
|
||||||
| directory.dir\_root | String | (Required if `directory` is specified as an object and `directory.owner` is not provided) Unique index identifying the directory to retrieve, as a hex string. |
|
| directory.dir\_root | String | (Required if `directory` is specified as an object and `directory.owner` is not provided) Unique index identifying the directory to retrieve, as a hex string. |
|
||||||
| directory.owner | String | (Required if `directory` is specified as an object and `directory.dir_root` is not provided) Unique address of the account associated with this directory |
|
| directory.owner | String | (Required if `directory` is specified as an object and `directory.dir_root` is not provided) Unique address of the account associated with this directory |
|
||||||
| offer | Object or String | (Optional) Specify an [Offer node](ripple-ledger.html#offer) to retrieve. If a string, interpret as the [unique index](ripple-ledger.html#tree-format) to the Offer. If an object, requires the sub-fields `account` and `seq` to uniquely identify the offer. |
|
| offer | Object or String | (Optional) Specify an [Offer node](reference-ledger-format.html#offer) to retrieve. If a string, interpret as the [unique index](reference-ledger-format.html#tree-format) to the Offer. If an object, requires the sub-fields `account` and `seq` to uniquely identify the offer. |
|
||||||
| offer.account | String - [Address][] | (Required if `offer` specified) The account that placed the offer. |
|
| offer.account | String - [Address][] | (Required if `offer` specified) The account that placed the offer. |
|
||||||
| offer.seq | Unsigned Integer | (Required if `offer` specified) The sequence number of the transaction that created the Offer node. |
|
| offer.seq | Unsigned Integer | (Required if `offer` specified) The sequence number of the transaction that created the Offer node. |
|
||||||
| ripple\_state | Object | (Optional) Object specifying the RippleState (trust line) node to retrieve. The `accounts` and `currency` sub-fields are required to uniquely specify the RippleState entry to retrieve. |
|
| ripple\_state | Object | (Optional) Object specifying the RippleState (trust line) node to retrieve. The `accounts` and `currency` sub-fields are required to uniquely specify the RippleState entry to retrieve. |
|
||||||
| ripple\_state.accounts | Array | (Required if `ripple_state` specified) 2-length array of account [Address][]es, defining the two accounts linked by this [RippleState node](ripple-ledger.html#ripplestate) |
|
| ripple\_state.accounts | Array | (Required if `ripple_state` specified) 2-length array of account [Address][]es, defining the two accounts linked by this [RippleState node](reference-ledger-format.html#ripplestate) |
|
||||||
| ripple\_state.currency | String | (Required if `ripple_state` specified) [Currency Code][] of the [RippleState node](ripple-ledger.html#ripplestate) to retrieve. |
|
| ripple\_state.currency | String | (Required if `ripple_state` specified) [Currency Code][] of the [RippleState node](reference-ledger-format.html#ripplestate) to retrieve. |
|
||||||
| binary | Boolean | (Optional, defaults to false) If true, return the requested ledger node's contents as a hex string. Otherwise, return data in JSON format. |
|
| binary | Boolean | (Optional, defaults to false) If true, return the requested ledger node's contents as a hex string. Otherwise, return data in JSON format. |
|
||||||
| ledger\_hash | String | (Optional) A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) |
|
| ledger\_hash | String | (Optional) A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) |
|
||||||
| ledger\_index | String or Unsigned Integer| (Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers))|
|
| ledger\_index | String or Unsigned Integer| (Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers))|
|
||||||
@@ -3802,7 +3802,7 @@ The three possible response formats are as follows:
|
|||||||
|
|
||||||
1. When returning a `lgrNotFound` error, the response has a field, `acquiring` with a [Ledger Request Object](#ledger-request-object) indicating the progress of fetching the ledger from the peer-to-peer network.
|
1. When returning a `lgrNotFound` error, the response has a field, `acquiring` with a [Ledger Request Object](#ledger-request-object) indicating the progress of fetching the ledger from the peer-to-peer network.
|
||||||
2. When the response represents an in-progress attempt to acquire the ledger, the body of the result is a [Ledger Request Object](#ledger-request-object) indicating the progress of fetching the ledger from the peer-to-peer network.
|
2. When the response represents an in-progress attempt to acquire the ledger, the body of the result is a [Ledger Request Object](#ledger-request-object) indicating the progress of fetching the ledger from the peer-to-peer network.
|
||||||
3. When the ledger is fully available, the response is a representation of the [ledger header](ripple-ledger.html#header-format).
|
3. When the ledger is fully available, the response is a representation of the [ledger header](reference-ledger-format.html#header-format).
|
||||||
|
|
||||||
#### Ledger Request Object ####
|
#### Ledger Request Object ####
|
||||||
|
|
||||||
@@ -3812,9 +3812,9 @@ When the server is in the progress of fetching a ledger, but has not yet finishe
|
|||||||
|-----------------------------|---------|-------------|
|
|-----------------------------|---------|-------------|
|
||||||
| hash | String | (May be omitted) The [Hash][] of the requested ledger, if the server knows it. |
|
| hash | String | (May be omitted) The [Hash][] of the requested ledger, if the server knows it. |
|
||||||
| have\_header | Boolean | Whether the server has the header section of the requested ledger. |
|
| have\_header | Boolean | Whether the server has the header section of the requested ledger. |
|
||||||
| have\_state | Boolean | (May be omitted) Whether the server has the [account-state section](ripple-ledger.html#tree-format) of the requested ledger. |
|
| have\_state | Boolean | (May be omitted) Whether the server has the [account-state section](reference-ledger-format.html#tree-format) of the requested ledger. |
|
||||||
| have\_transactions | Boolean | (May be omitted) Whether the server has the transaction section of the requested ledger. |
|
| have\_transactions | Boolean | (May be omitted) Whether the server has the transaction section of the requested ledger. |
|
||||||
| needed\_state\_hashes | Array of Strings | (May be omitted) Up to 16 hashes of nodes in the [state tree](ripple-ledger.html#tree-format) that the server still needs to retrieve. |
|
| needed\_state\_hashes | Array of Strings | (May be omitted) Up to 16 hashes of nodes in the [state tree](reference-ledger-format.html#tree-format) that the server still needs to retrieve. |
|
||||||
| needed\_transaction\_hashes | Array of Strings | (May be omitted) Up to 16 hashes of nodes in the transaction tree that the server still needs to retrieve. |
|
| needed\_transaction\_hashes | Array of Strings | (May be omitted) Up to 16 hashes of nodes in the transaction tree that the server still needs to retrieve. |
|
||||||
| peers | Number | How many peers the server is querying in its attempt to find this ledger. |
|
| peers | Number | How many peers the server is querying in its attempt to find this ledger. |
|
||||||
| timeouts | Number | Number of times this attempt to fetch the ledger has timed out so far. |
|
| timeouts | Number | Number of times this attempt to fetch the ledger has timed out so far. |
|
||||||
@@ -4076,7 +4076,7 @@ An example of a successful response:
|
|||||||
|
|
||||||
<!-- </div> -->
|
<!-- </div> -->
|
||||||
|
|
||||||
The response follows the [standard format](#response-formatting), with a successful result containing the fields of the [Transaction object](transactions.html) as well as the following additional fields:
|
The response follows the [standard format](#response-formatting), with a successful result containing the fields of the [Transaction object](reference-transaction-format.html) as well as the following additional fields:
|
||||||
|
|
||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
@@ -4085,7 +4085,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
| ledger_index | Unsigned Integer | The sequence number of the ledger that includes this transaction. |
|
| ledger_index | Unsigned Integer | The sequence number of the ledger that includes this transaction. |
|
||||||
| meta | Object | Various metadata about the transaction. |
|
| meta | Object | Various metadata about the transaction. |
|
||||||
| validated | Boolean | True if this data is from a validated ledger version; if omitted or set to false, this data is not final. |
|
| validated | Boolean | True if this data is from a validated ledger version; if omitted or set to false, this data is not final. |
|
||||||
| (Various) | (Various) | Other fields from the [Transaction object](transactions.html) |
|
| (Various) | (Various) | Other fields from the [Transaction object](reference-transaction-format.html) |
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
|
|
||||||
@@ -4296,7 +4296,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
| ledger_index | Unsigned Integer | Sequence number of the ledger version the transaction was found in; this is the same as the one from the request. |
|
| ledger_index | Unsigned Integer | Sequence number of the ledger version the transaction was found in; this is the same as the one from the request. |
|
||||||
| ledger_hash | String | (May be omitted) Unique hash of the ledger version the transaction was found in; this is the same as the one from the request. |
|
| ledger_hash | String | (May be omitted) Unique hash of the ledger version the transaction was found in; this is the same as the one from the request. |
|
||||||
| metadata | Object | Various metadata about the transaction. |
|
| metadata | Object | Various metadata about the transaction. |
|
||||||
| tx_json | Object | JSON representation of the [Transaction object](transactions.html) |
|
| tx_json | Object | JSON representation of the [Transaction object](reference-transaction-format.html) |
|
||||||
|
|
||||||
There are a couple possible reasons the server may fail to find the transaction:
|
There are a couple possible reasons the server may fail to find the transaction:
|
||||||
|
|
||||||
@@ -5197,7 +5197,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
| index | Unsigned Integer | The value of `start` used in the request. |
|
| index | Unsigned Integer | The value of `start` used in the request. |
|
||||||
| txs | Array | Array of transaction objects. |
|
| txs | Array | Array of transaction objects. |
|
||||||
|
|
||||||
The fields included in each transaction object vary slightly depending on the type of transaction. See [Transaction Format](transactions.html) for details.
|
The fields included in each transaction object vary slightly depending on the type of transaction. See [Transaction Format](reference-transaction-format.html) for details.
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
|
|
||||||
@@ -5209,7 +5209,7 @@ The fields included in each transaction object vary slightly depending on the ty
|
|||||||
## path_find ##
|
## path_find ##
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp "Source")
|
||||||
|
|
||||||
*WebSocket API only!* The `path_find` method searches for a [path](paths.html) along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see [`ripple_path_find`](#ripple-path-find). For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
|
*WebSocket API only!* The `path_find` method searches for a [path](concept-paths.html) along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see [`ripple_path_find`](#ripple-path-find). For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
|
||||||
|
|
||||||
There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the `subcommand` parameter:
|
There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the `subcommand` parameter:
|
||||||
|
|
||||||
@@ -5260,7 +5260,7 @@ The request includes the following parameters:
|
|||||||
| destination\_account | String | Unique address of the account to find a path to. (In other words, the account that would receive a payment.) |
|
| destination\_account | String | Unique address of the account to find a path to. (In other words, the account that would receive a payment.) |
|
||||||
| destination\_amount | String or Object | [Currency amount](#specifying-currency-amounts) that the destination account would receive in a transaction. **Special case:** _(New in [version 0.30.0][])_ You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). |
|
| destination\_amount | String or Object | [Currency amount](#specifying-currency-amounts) that the destination account would receive in a transaction. **Special case:** _(New in [version 0.30.0][])_ You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). |
|
||||||
| send\_max | String or Object | (Optional) [Currency amount](#specifying-currency-amounts) that would be spent in the transaction. Not compatible with `source_currencies`. _(New in [version 0.30.0][])_ |
|
| send\_max | String or Object | (Optional) [Currency amount](#specifying-currency-amounts) that would be spent in the transaction. Not compatible with `source_currencies`. _(New in [version 0.30.0][])_ |
|
||||||
| paths | Array | (Optional) Array of arrays of objects, representing [payment paths](paths.html) to check. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path. |
|
| paths | Array | (Optional) Array of arrays of objects, representing [payment paths](concept-paths.html) to check. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path. |
|
||||||
|
|
||||||
The server also recognizes the following fields, but the results of using them are not guaranteed: `source_currencies`, `bridges`. These fields should be considered reserved for future use.
|
The server also recognizes the following fields, but the results of using them are not guaranteed: `source_currencies`, `bridges`. These fields should be considered reserved for future use.
|
||||||
|
|
||||||
@@ -5643,7 +5643,7 @@ The initial response follows the [standard format](#response-formatting), with a
|
|||||||
|
|
||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| alternatives | Array | Array of objects with suggested [paths](paths.html) to take, as described below. If empty, then no paths were found connecting the source and destination accounts. |
|
| alternatives | Array | Array of objects with suggested [paths](concept-paths.html) to take, as described below. If empty, then no paths were found connecting the source and destination accounts. |
|
||||||
| destination\_account | String | Unique address of the account that would receive a transaction |
|
| destination\_account | String | Unique address of the account that would receive a transaction |
|
||||||
| destination\_amount | String or Object | [Currency amount](#specifying-currency-amounts) that the destination would receive in a transaction |
|
| destination\_amount | String or Object | [Currency amount](#specifying-currency-amounts) that the destination would receive in a transaction |
|
||||||
| id | (Various) | (WebSocket only) The ID provided in the WebSocket request is included again at this level. |
|
| id | (Various) | (WebSocket only) The ID provided in the WebSocket request is included again at this level. |
|
||||||
@@ -5654,7 +5654,7 @@ Each element in the `alternatives` array is an object that represents a path fro
|
|||||||
|
|
||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| paths\_computed | Array | Array of arrays of objects defining [payment paths](paths.html) |
|
| paths\_computed | Array | Array of arrays of objects defining [payment paths](concept-paths.html) |
|
||||||
| source\_amount | String or Object | [Currency amount](#specifying-currency-amounts) that the source would have to send along this path in order for the destination to receive the desired amount |
|
| source\_amount | String or Object | [Currency amount](#specifying-currency-amounts) that the source would have to send along this path in order for the destination to receive the desired amount |
|
||||||
|
|
||||||
#### Possible Errors ####
|
#### Possible Errors ####
|
||||||
@@ -5665,7 +5665,7 @@ Each element in the `alternatives` array is an object that represents a path fro
|
|||||||
|
|
||||||
#### Asynchronous Follow-ups ####
|
#### Asynchronous Follow-ups ####
|
||||||
|
|
||||||
In addition to the initial response, the server sends more messages in a similar format to update on the status of [payment paths](paths.html) over time. These messages include the `id` of the original WebSocket request so you can tell which request prompted them, and the field `"type": "path_find"` at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response.
|
In addition to the initial response, the server sends more messages in a similar format to update on the status of [payment paths](concept-paths.html) over time. These messages include the `id` of the original WebSocket request so you can tell which request prompted them, and the field `"type": "path_find"` at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response.
|
||||||
|
|
||||||
If the follow-up includes `"full_reply": true`, then this is the best path that rippled can find as of the current ledger.
|
If the follow-up includes `"full_reply": true`, then this is the best path that rippled can find as of the current ledger.
|
||||||
|
|
||||||
@@ -5785,7 +5785,7 @@ If there was no outstanding pathfinding request, an error is returned instead.
|
|||||||
## ripple_path_find ##
|
## ripple_path_find ##
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/RipplePathFind.cpp "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/RipplePathFind.cpp "Source")
|
||||||
|
|
||||||
The `ripple_path_find` method is a simplified version of [`path_find`](#path-find) that provides a single response with a [payment path](paths.html) you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making many subsequent calls, you should use [`path_find`](#path-find) instead where possible.
|
The `ripple_path_find` method is a simplified version of [`path_find`](#path-find) that provides a single response with a [payment path](concept-paths.html) you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making many subsequent calls, you should use [`path_find`](#path-find) instead where possible.
|
||||||
|
|
||||||
Although the `rippled` server attempts to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths in order to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers operated by different parties, to minimize the risk of a single server returning poor results. (__*Note:*__ A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.)
|
Although the `rippled` server attempts to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths in order to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers operated by different parties, to minimize the risk of a single server returning poor results. (__*Note:*__ A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.)
|
||||||
|
|
||||||
@@ -6105,7 +6105,7 @@ Each element in the `alternatives` array is an object that represents a path fro
|
|||||||
|
|
||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| paths\_computed | Array | Array of arrays of objects defining [payment paths](paths.html) |
|
| paths\_computed | Array | Array of arrays of objects defining [payment paths](concept-paths.html) |
|
||||||
| source\_amount | String or Object | [Currency amount](#specifying-currency-amounts) that the source would have to send along this path in order for the destination to receive the desired amount |
|
| source\_amount | String or Object | [Currency amount](#specifying-currency-amounts) that the source would have to send along this path in order for the destination to receive the desired amount |
|
||||||
|
|
||||||
The following fields are deprecated, and may be omitted: `paths_canonical`, and `paths_expanded`. If they appear, you should disregard them.
|
The following fields are deprecated, and may be omitted: `paths_canonical`, and `paths_expanded`. If they appear, you should disregard them.
|
||||||
@@ -6194,17 +6194,17 @@ The request includes the following parameters:
|
|||||||
|
|
||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| tx_json | Object | [Transaction definition](transactions.html) in JSON format |
|
| tx_json | Object | [Transaction definition](reference-transaction-format.html) in JSON format |
|
||||||
| secret | String | Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections. |
|
| secret | String | Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections. |
|
||||||
| offline | Boolean | (Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values. |
|
| offline | Boolean | (Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values. |
|
||||||
| build_path | Boolean | (Optional) If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. __*Caution:*__ The server looks for the presence or absence of this field, not its value. This behavior may change. |
|
| build_path | Boolean | (Optional) If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. __*Caution:*__ The server looks for the presence or absence of this field, not its value. This behavior may change. |
|
||||||
| fee\_mult\_max | Integer | (Optional) If the `Fee` parameter ([transaction cost](tx-cost.html)) is omitted, this field limits the automatically-provided value so that it is less than or equal to the base transaction cost times this value. |
|
| fee\_mult\_max | Integer | (Optional) If the `Fee` parameter ([transaction cost](concept-transaction-cost.html)) is omitted, this field limits the automatically-provided value so that it is less than or equal to the base transaction cost times this value. |
|
||||||
| fee\_div\_max | Integer | (Optional) Used with `fee_mult_max` to create a fractional multiplier for the limit. Specifically, the server multiplies its base [transaction cost](tx-cost.html) by `fee_mult_max`, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided `Fee` value would be over the limit, signing fails. _(New in [version 0.30.1][])_ |
|
| fee\_div\_max | Integer | (Optional) Used with `fee_mult_max` to create a fractional multiplier for the limit. Specifically, the server multiplies its base [transaction cost](concept-transaction-cost.html) by `fee_mult_max`, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided `Fee` value would be over the limit, signing fails. _(New in [version 0.30.1][])_ |
|
||||||
|
|
||||||
The server automatically attempts to fill in certain fields from the `tx_json` object if they are omitted, unless you specified `offline` as true. Otherwise, the following fields from the [transaction format](transactions.html) are automatically filled in:
|
The server automatically attempts to fill in certain fields from the `tx_json` object if they are omitted, unless you specified `offline` as true. Otherwise, the following fields from the [transaction format](reference-transaction-format.html) are automatically filled in:
|
||||||
|
|
||||||
* `Sequence` - The server automatically uses the next Sequence number from the sender's account information. Be careful: the next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must provide the correct sequence numbers in the request. Automatically filled unless `offline` is true.
|
* `Sequence` - The server automatically uses the next Sequence number from the sender's account information. Be careful: the next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must provide the correct sequence numbers in the request. Automatically filled unless `offline` is true.
|
||||||
* `Fee` - If you omit the `Fee` parameter, the server [automatically provides an appropriate transaction cost](tx-cost.html#automatically-specifying-the-transaction-cost) unless you specified `offline` as true. If you specify `offline` as true, you must fill in the transaction cost in the `Fee` parameter. Be careful: a malicious server can specify an excessively high transaction cost.
|
* `Fee` - If you omit the `Fee` parameter, the server [automatically provides an appropriate transaction cost](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) unless you specified `offline` as true. If you specify `offline` as true, you must fill in the transaction cost in the `Fee` parameter. Be careful: a malicious server can specify an excessively high transaction cost.
|
||||||
* If `fee_mult_max` is included, and the automatically provided `Fee` value is greater than the long-term base transaction cost times `fee_mult_max`, then the transaction fails with the error `rpcHIGH_FEE`. This way, you can let the server fill in the current minimum `Fee` value as long as the current load-based transaction cost is not too high.
|
* If `fee_mult_max` is included, and the automatically provided `Fee` value is greater than the long-term base transaction cost times `fee_mult_max`, then the transaction fails with the error `rpcHIGH_FEE`. This way, you can let the server fill in the current minimum `Fee` value as long as the current load-based transaction cost is not too high.
|
||||||
* `Paths` - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a [ripple_path_find](#ripple-path-find). Only filled if `build_path` is provided.
|
* `Paths` - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a [ripple_path_find](#ripple-path-find). Only filled if `build_path` is provided.
|
||||||
|
|
||||||
@@ -6276,7 +6276,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| tx_blob | String | Binary representation of the fully-qualified, signed transaction, as hex |
|
| tx_blob | String | Binary representation of the fully-qualified, signed transaction, as hex |
|
||||||
| tx_json | Object | JSON specification of the [complete transaction](transactions.html) as signed, including any fields that were automatically filled in |
|
| tx_json | Object | JSON specification of the [complete transaction](reference-transaction-format.html) as signed, including any fields that were automatically filled in |
|
||||||
|
|
||||||
__*Caution:*__ If this command results in an error messages, the message can contain the account secret from the request. Make sure that these errors are not visible to others, including:
|
__*Caution:*__ If this command results in an error messages, the message can contain the account secret from the request. Make sure that these errors are not visible to others, including:
|
||||||
|
|
||||||
@@ -6296,7 +6296,7 @@ __*Caution:*__ If this command results in an error messages, the message can con
|
|||||||
## submit ##
|
## submit ##
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Submit.cpp "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Submit.cpp "Source")
|
||||||
|
|
||||||
The `submit` method sends a [transaction](transactions.html) to the network to be confirmed and included in future ledgers.
|
The `submit` method sends a [transaction](reference-transaction-format.html) to the network to be confirmed and included in future ledgers.
|
||||||
|
|
||||||
This command has two modes:
|
This command has two modes:
|
||||||
|
|
||||||
@@ -6357,13 +6357,13 @@ A sign-and-submit request includes the following parameters:
|
|||||||
|
|
||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| tx_json | Object | [Transaction definition](transactions.html) in JSON format, optionally omitting any auto-fillable fields. |
|
| tx_json | Object | [Transaction definition](reference-transaction-format.html) in JSON format, optionally omitting any auto-fillable fields. |
|
||||||
| secret | String | (Required if `tx_json` is supplied) Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections. |
|
| secret | String | (Required if `tx_json` is supplied) Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections. |
|
||||||
| fail_hard | Boolean | (Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers |
|
| fail_hard | Boolean | (Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers |
|
||||||
| offline | Boolean | (Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values. |
|
| offline | Boolean | (Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values. |
|
||||||
| build_path | Boolean | (Optional) If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. You must omit this field if the transaction is a direct XRP-to-XRP transfer. __*Caution:*__ The server looks for the presence or absence of this field, not its value. This behavior may change. |
|
| build_path | Boolean | (Optional) If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. You must omit this field if the transaction is a direct XRP-to-XRP transfer. __*Caution:*__ The server looks for the presence or absence of this field, not its value. This behavior may change. |
|
||||||
| fee\_mult\_max | Integer | (Optional) If the `Fee` parameter is omitted, this field limits the automatically-provided `Fee` value so that it is less than or equal to the long-term base transaction cost times this value. |
|
| fee\_mult\_max | Integer | (Optional) If the `Fee` parameter is omitted, this field limits the automatically-provided `Fee` value so that it is less than or equal to the long-term base transaction cost times this value. |
|
||||||
| fee\_div\_max | Integer | (Optional) Used with `fee_mult_max` to create a fractional multiplier for the limit. Specifically, the server multiplies its base [transaction cost](tx-cost.html) by `fee_mult_max`, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided `Fee` value would be over the limit, the submit command fails. _(New in [version 0.30.1][])_ |
|
| fee\_div\_max | Integer | (Optional) Used with `fee_mult_max` to create a fractional multiplier for the limit. Specifically, the server multiplies its base [transaction cost](concept-transaction-cost.html) by `fee_mult_max`, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided `Fee` value would be over the limit, the submit command fails. _(New in [version 0.30.1][])_ |
|
||||||
|
|
||||||
See the [sign command](#sign) for detailed information on how the server automatically fills in certain fields.
|
See the [sign command](#sign) for detailed information on how the server automatically fills in certain fields.
|
||||||
|
|
||||||
@@ -6501,7 +6501,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
| tx_blob | String | The complete transaction in hex string format |
|
| tx_blob | String | The complete transaction in hex string format |
|
||||||
| tx_json | Object | The complete transaction in JSON format |
|
| tx_json | Object | The complete transaction in JSON format |
|
||||||
|
|
||||||
__*Caution:*__ Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does not necessarily indicate that the transaction has taken place. There are many cases that can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the network since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](transactions.html#full-transaction-response-list) for details, and do not consider the transaction's results final until they appear in a validated ledger version.
|
__*Caution:*__ Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does not necessarily indicate that the transaction has taken place. There are many cases that can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the network since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](reference-transaction-format.html#full-transaction-response-list) for details, and do not consider the transaction's results final until they appear in a validated ledger version.
|
||||||
|
|
||||||
__*Caution:*__ If this command results in an error messages, the message can contain an account secret, if one was provided in the request. (This is not a problem if the request contained a signed tx_blob instead.) Make sure that these errors are not visible to others, including:
|
__*Caution:*__ If this command results in an error messages, the message can contain an account secret, if one was provided in the request. (This is not a problem if the request contained a signed tx_blob instead.) Make sure that these errors are not visible to others, including:
|
||||||
|
|
||||||
@@ -6684,7 +6684,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
| ledger\_current\_index | Integer | (Omitted if ledger version provided) Sequence number of the ledger version used when retrieving this data. |
|
| ledger\_current\_index | Integer | (Omitted if ledger version provided) Sequence number of the ledger version used when retrieving this data. |
|
||||||
| ledger\_index | Integer | (Omitted if ledger\_current\_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data. |
|
| ledger\_index | Integer | (Omitted if ledger\_current\_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data. |
|
||||||
| ledger\_hash | String | (May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data. |
|
| ledger\_hash | String | (May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data. |
|
||||||
| offers | Array | Array of offer objects, each of which has the fields of an [OfferCreate transaction](transactions.html#offercreate) |
|
| offers | Array | Array of offer objects, each of which has the fields of an [OfferCreate transaction](reference-transaction-format.html#offercreate) |
|
||||||
|
|
||||||
In addition to the standard Offer fields, the following fields may be included in members of the `offers` array:
|
In addition to the standard Offer fields, the following fields may be included in members of the `offers` array:
|
||||||
|
|
||||||
@@ -6788,7 +6788,7 @@ The `streams` parameter provides access to the following default streams of info
|
|||||||
* `server` - Sends a message whenever the status of the `rippled` server (for example, network connectivity) changes
|
* `server` - Sends a message whenever the status of the `rippled` server (for example, network connectivity) changes
|
||||||
* `ledger` - Sends a message whenever the consensus process declares a new validated ledger
|
* `ledger` - Sends a message whenever the consensus process declares a new validated ledger
|
||||||
* `transactions` - Sends a message whenever a transaction is included in a closed ledger
|
* `transactions` - Sends a message whenever a transaction is included in a closed ledger
|
||||||
* `transactions_proposed` - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation, however. (__*Note:*__ [Even some transactions that don't succeed are included](transactions.html#result-categories) in validated ledgers, because they take the anti-spam transaction fee.)
|
* `transactions_proposed` - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation, however. (__*Note:*__ [Even some transactions that don't succeed are included](reference-transaction-format.html#result-categories) in validated ledgers, because they take the anti-spam transaction fee.)
|
||||||
* `validations` - Sends a message whenever the server receives a validation message from a server it trusts. (An individual `rippled` declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.)
|
* `validations` - Sends a message whenever the server receives a validation message from a server it trusts. (An individual `rippled` declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.)
|
||||||
* `peer_status` - **(Admin only)** Information about connected peer `rippled` servers, especially with regards to the consensus process.
|
* `peer_status` - **(Admin only)** Information about connected peer `rippled` servers, especially with regards to the consensus process.
|
||||||
|
|
||||||
@@ -6868,13 +6868,13 @@ The fields from a ledger stream message are as follows:
|
|||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| type | String | `ledgerClosed` indicates this is from the ledger stream |
|
| type | String | `ledgerClosed` indicates this is from the ledger stream |
|
||||||
| fee\_base | Unsigned Integer | Cost of the 'reference transaction' in drops of XRP. (See [Transaction Cost](tx-cost.html) If the ledger includes a [SetFee pseudo-transaction](transactions.html#setfee) the new transaction cost applies to all transactions after this ledger. |
|
| fee\_base | Unsigned Integer | Cost of the 'reference transaction' in drops of XRP. (See [Transaction Cost](concept-transaction-cost.html) If the ledger includes a [SetFee pseudo-transaction](reference-transaction-format.html#setfee) the new transaction cost applies to all transactions after this ledger. |
|
||||||
| fee\_ref | Unsigned Integer | Cost of the 'reference transaction' in 'fee units'. |
|
| fee\_ref | Unsigned Integer | Cost of the 'reference transaction' in 'fee units'. |
|
||||||
| ledger\_hash | String | Unique hash of the ledger that was closed, as hex |
|
| ledger\_hash | String | Unique hash of the ledger that was closed, as hex |
|
||||||
| ledger\_index | Unsigned Integer | Sequence number of the ledger that was closed |
|
| ledger\_index | Unsigned Integer | Sequence number of the ledger that was closed |
|
||||||
| ledger\_time | Unsigned Integer | The time this ledger was closed, in seconds since the [Ripple Epoch](#specifying-time) |
|
| ledger\_time | Unsigned Integer | The time this ledger was closed, in seconds since the [Ripple Epoch](#specifying-time) |
|
||||||
| reserve\_base | Unsigned Integer | The minimum reserve, in drops of XRP, that is required for an account. If the ledger includes a [SetFee pseudo-transaction](transactions.html#setfee) the new base reserve applies after this ledger. |
|
| reserve\_base | Unsigned Integer | The minimum reserve, in drops of XRP, that is required for an account. If the ledger includes a [SetFee pseudo-transaction](reference-transaction-format.html#setfee) the new base reserve applies after this ledger. |
|
||||||
| reserve\_inc | Unsigned Integer | The increase in account reserve that is added for each item the account owns, such as offers or trust lines. If the ledger includes a [SetFee pseudo-transaction](transactions.html#setfee) the new owner reserve applies after this ledger. |
|
| reserve\_inc | Unsigned Integer | The increase in account reserve that is added for each item the account owns, such as offers or trust lines. If the ledger includes a [SetFee pseudo-transaction](reference-transaction-format.html#setfee) the new owner reserve applies after this ledger. |
|
||||||
| txn\_count | Unsigned Integer | Number of new transactions included in this ledger |
|
| txn\_count | Unsigned Integer | Number of new transactions included in this ledger |
|
||||||
| validated\_ledgers | String | (May be omitted) Range of ledgers that the server has available. This may be discontiguous. This field is not returned if the server is not connected to the network, or if it is connected but has not yet obtained a ledger from the network. |
|
| validated\_ledgers | String | (May be omitted) Range of ledgers that the server has available. This may be discontiguous. This field is not returned if the server is not connected to the network, or if it is connected but has not yet obtained a ledger from the network. |
|
||||||
|
|
||||||
@@ -7030,14 +7030,14 @@ Transaction stream messages have the following fields:
|
|||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| type | String | `transaction` indicates this is the notification of a transaction, which could come from several possible streams. |
|
| type | String | `transaction` indicates this is the notification of a transaction, which could come from several possible streams. |
|
||||||
| engine_result | String | String [Transaction result code](transactions.html#result-categories) |
|
| engine_result | String | String [Transaction result code](reference-transaction-format.html#result-categories) |
|
||||||
| engine_result_code | Number | Numeric [transaction response code](transactions.html#result-categories), if applicable. |
|
| engine_result_code | Number | Numeric [transaction response code](reference-transaction-format.html#result-categories), if applicable. |
|
||||||
| engine_result_message | String | Human-readable explanation for the transaction response |
|
| engine_result_message | String | Human-readable explanation for the transaction response |
|
||||||
| ledger_current_index | Unsigned Integer | (Omitted for validated transactions) Sequence number of the current ledger version for which this transaction is currently proposed |
|
| ledger_current_index | Unsigned Integer | (Omitted for validated transactions) Sequence number of the current ledger version for which this transaction is currently proposed |
|
||||||
| ledger_hash | String | (Omitted for unvalidated transactions) Unique hash of the ledger version that includes this transaction, as hex |
|
| ledger_hash | String | (Omitted for unvalidated transactions) Unique hash of the ledger version that includes this transaction, as hex |
|
||||||
| ledger_index | Unsigned Integer | (Omitted for unvalidated transactions) Sequence number of the ledger version that includes this transaction |
|
| ledger_index | Unsigned Integer | (Omitted for unvalidated transactions) Sequence number of the ledger version that includes this transaction |
|
||||||
| meta | Object | (Omitted for unvalidated transactions) Various metadata about the transaction, including which ledger entries it affected |
|
| meta | Object | (Omitted for unvalidated transactions) Various metadata about the transaction, including which ledger entries it affected |
|
||||||
| transaction | Object | The [definition of the transaction](transactions.html) in JSON format |
|
| transaction | Object | The [definition of the transaction](reference-transaction-format.html) in JSON format |
|
||||||
| validated | Boolean | If true, this transaction is included in a validated ledger. Responses from the `transaction` stream should always be validated. |
|
| validated | Boolean | If true, this transaction is included in a validated ledger. Responses from the `transaction` stream should always be validated. |
|
||||||
|
|
||||||
|
|
||||||
@@ -7218,7 +7218,7 @@ The format of an order book stream message is the same as that of [transaction s
|
|||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|--------------|--------|-------------|
|
|--------------|--------|-------------|
|
||||||
| transaction.owner\_funds | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after executing this transaction. This does not check whether the currency amount is [frozen](freeze.html). |
|
| transaction.owner\_funds | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after executing this transaction. This does not check whether the currency amount is [frozen](concept-freeze.html). |
|
||||||
|
|
||||||
|
|
||||||
## unsubscribe ##
|
## unsubscribe ##
|
||||||
@@ -8774,7 +8774,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
## validation_create ##
|
## validation_create ##
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/315a8b6b602798a4cff4d8e1911936011e12abdb/src/ripple/rpc/handlers/ValidationCreate.cpp "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/315a8b6b602798a4cff4d8e1911936011e12abdb/src/ripple/rpc/handlers/ValidationCreate.cpp "Source")
|
||||||
|
|
||||||
Use the `validation_create` command to generate the keys for a rippled [validating node](rippled-setup.html#validator-setup). Similar to the [wallet_propose](#wallet-propose) command, this command makes no real changes, but only generates a set of keys in the proper format.
|
Use the `validation_create` command to generate the keys for a rippled [validating node](tutorial-rippled-setup.html#validator-setup). Similar to the [wallet_propose](#wallet-propose) command, this command makes no real changes, but only generates a set of keys in the proper format.
|
||||||
|
|
||||||
_The `validation_create` method is an [admin command](#connecting-to-rippled) that cannot be run by unpriviledged users._
|
_The `validation_create` method is an [admin command](#connecting-to-rippled) that cannot be run by unpriviledged users._
|
||||||
|
|
||||||
@@ -9338,7 +9338,7 @@ The response follows the [standard format](#response-formatting), with a success
|
|||||||
|
|
||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|---------|--------|-------------|
|
|---------|--------|-------------|
|
||||||
| cluster | Object | Summary of other `rippled` servers in the same cluster, if [configured as a cluster](rippled-setup.html#clustering). _(New in [version 0.30.1][])_ |
|
| cluster | Object | Summary of other `rippled` servers in the same cluster, if [configured as a cluster](tutorial-rippled-setup.html#clustering). _(New in [version 0.30.1][])_ |
|
||||||
| peers | Array | Array of peer objects. |
|
| peers | Array | Array of peer objects. |
|
||||||
|
|
||||||
Each field of the `cluster` object is the public key of that `rippled` server's identifying keypair. (This is the same value that that server returns as `pubkey_node` in the [`server_info` command](#server-info).) The contents of that field are an object with the following fields:
|
Each field of the `cluster` object is the public key of that `rippled` server's identifying keypair. (This is the same value that that server returns as `pubkey_node` in the [`server_info` command](#server-info).) The contents of that field are an object with the following fields:
|
||||||
@@ -9346,7 +9346,7 @@ Each field of the `cluster` object is the public key of that `rippled` server's
|
|||||||
| Field | Type | Description |
|
| Field | Type | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| tag | String | The display name for this cluster member as defined in the config file. |
|
| tag | String | The display name for this cluster member as defined in the config file. |
|
||||||
| fee | Number | (May be omitted) The load multiplier this cluster member is applying to the [transaction cost](tx-cost.html) |
|
| fee | Number | (May be omitted) The load multiplier this cluster member is applying to the [transaction cost](concept-transaction-cost.html) |
|
||||||
| age | Number | The number of seconds since the last cluster report from this cluster member. |
|
| age | Number | The number of seconds since the last cluster report from this cluster member. |
|
||||||
|
|
||||||
Each member of the `peers` array is a peer object with the following fields:
|
Each member of the `peers` array is a peer object with the following fields:
|
||||||
@@ -54,10 +54,10 @@ After doing that, you generate the signed binary format for the transaction. The
|
|||||||
|
|
||||||
1. Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection.
|
1. Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection.
|
||||||
* [ripple-lib](https://github.com/ripple/ripple-lib) has an implementation of offline signing.
|
* [ripple-lib](https://github.com/ripple/ripple-lib) has an implementation of offline signing.
|
||||||
2. Have a `rippled` server sign the transaction for you. The [sign command](rippled-apis.html#sign) takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted sub-net, to a server you control.)
|
2. Have a `rippled` server sign the transaction for you. The [sign command](reference-rippled.html#sign) takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted sub-net, to a server you control.)
|
||||||
* As a shortcut, you can use the [submit command](rippled-apis.html#submit) with a `tx_json` object to sign and submit a transaction all at once. This is only recommended for testing and development purposes.
|
* As a shortcut, you can use the [submit command](reference-rippled.html#submit) with a `tx_json` object to sign and submit a transaction all at once. This is only recommended for testing and development purposes.
|
||||||
|
|
||||||
In either case, signing a transaction generates a binary blob that can be submitted to the network. This means using `rippled`'s [submit command](rippled-apis.html#submit). Here is an example of the same transaction, as a signed blob, being submitted with the WebSocket API:
|
In either case, signing a transaction generates a binary blob that can be submitted to the network. This means using `rippled`'s [submit command](reference-rippled.html#submit). Here is an example of the same transaction, as a signed blob, being submitted with the WebSocket API:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
@@ -67,7 +67,7 @@ In either case, signing a transaction generates a binary blob that can be submit
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
After a transaction has been submitted, if it gets accepted into a validated ledger, you can view the final transaction using the API. For example, here is what the WebSocket API [tx command](rippled-apis.html#tx) shows for the same transaction. The field names that begin with capital letters are part of the ledger object; the fields that begin with lower-case letters are additional information generated by the server for the request:
|
After a transaction has been submitted, if it gets accepted into a validated ledger, you can view the final transaction using the API. For example, here is what the WebSocket API [tx command](reference-rippled.html#tx) shows for the same transaction. The field names that begin with capital letters are part of the ledger object; the fields that begin with lower-case letters are additional information generated by the server for the request:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
@@ -172,11 +172,11 @@ To accomplish both of these, your application should:
|
|||||||
4. Confirm that the transaction was either included in a validated ledger, or that it has expired due to `LastLedgerSequence`.
|
4. Confirm that the transaction was either included in a validated ledger, or that it has expired due to `LastLedgerSequence`.
|
||||||
5. If a transaction fails or expires, you can modify and resubmit it.
|
5. If a transaction fails or expires, you can modify and resubmit it.
|
||||||
|
|
||||||
Main article: [Reliable Transaction Submission](reliable_tx.html)
|
Main article: [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html)
|
||||||
|
|
||||||
### Identifying Transactions ###
|
### Identifying Transactions ###
|
||||||
|
|
||||||
The `"hash"` is the unique value that identifies a particular transaction. The server provides the hash in the response when you submit the transaction; you can also look up a transaction in an account's transaction history with the [account_tx command](rippled-apis.html#account-tx).
|
The `"hash"` is the unique value that identifies a particular transaction. The server provides the hash in the response when you submit the transaction; you can also look up a transaction in an account's transaction history with the [account_tx command](reference-rippled.html#account-tx).
|
||||||
|
|
||||||
The transaction hash can be used as a "proof of payment" since anyone can [look up the transaction by its hash](#looking-up-transaction-results) in order to verify its final status.
|
The transaction hash can be used as a "proof of payment" since anyone can [look up the transaction by its hash](#looking-up-transaction-results) in order to verify its final status.
|
||||||
|
|
||||||
@@ -206,7 +206,7 @@ Every transaction type has the same set of fundamental fields:
|
|||||||
|
|
||||||
Some fields can be automatically filled in before the transaction is signed, either by a `rippled` server or by the library used for offline signing. Both [ripple-lib](https://github.com/ripple/ripple-lib) and `rippled` can automatically provide the following values:
|
Some fields can be automatically filled in before the transaction is signed, either by a `rippled` server or by the library used for offline signing. Both [ripple-lib](https://github.com/ripple/ripple-lib) and `rippled` can automatically provide the following values:
|
||||||
|
|
||||||
* `Fee` - Automatically fill in the [transaction cost](tx-cost.html) based on the network. (*Note:* `rippled`'s [sign command](rippled-apis.html#sign) supports limits on how high the filled-in-value is, using the `fee_mult_max` parameter.)
|
* `Fee` - Automatically fill in the [transaction cost](concept-transaction-cost.html) based on the network. (*Note:* `rippled`'s [sign command](reference-rippled.html#sign) supports limits on how high the filled-in-value is, using the `fee_mult_max` parameter.)
|
||||||
* `Sequence` - Automatically use the next sequence number for the account sending the transaction.
|
* `Sequence` - Automatically use the next sequence number for the account sending the transaction.
|
||||||
|
|
||||||
For a production system, we recommend *not* leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.
|
For a production system, we recommend *not* leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.
|
||||||
@@ -217,7 +217,7 @@ The [`Paths` field](#paths) of the [Payment](#payment) transaction type can also
|
|||||||
|
|
||||||
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 XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
|
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 XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
|
||||||
|
|
||||||
The `Fee` field specifies an amount, in [drops of XRP](rippled-apis.html#specifying-currency-amounts), to destroy as the cost for this transaction. If the transaction is included in a validated leger (whether or not it achieves its intended purpose), then the amount of XRP specified in the `Fee` parameter is destroyed forever. You can [look up the transaction cost](tx-cost.html#querying-the-transaction-cost) in advance, or [let `rippled` set it automatically](tx-cost.html#automatically-specifying-the-transaction-cost) when you sign a transaction.
|
The `Fee` field specifies an amount, in [drops of XRP](reference-rippled.html#specifying-currency-amounts), to destroy as the cost for this transaction. If the transaction is included in a validated leger (whether or not it achieves its intended purpose), then the amount of XRP specified in the `Fee` parameter is destroyed forever. You can [look up the transaction cost](concept-transaction-cost.html#querying-the-transaction-cost) in advance, or [let `rippled` set it automatically](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) when you sign a transaction.
|
||||||
|
|
||||||
|
|
||||||
### Canceling or Skipping a Transaction ###
|
### Canceling or Skipping a Transaction ###
|
||||||
@@ -234,7 +234,7 @@ In this way, an AccountSet transaction with no options is the canonical "[no-op]
|
|||||||
|
|
||||||
### LastLedgerSequence ###
|
### LastLedgerSequence ###
|
||||||
|
|
||||||
We strongly recommend that you specify the `LastLedgerSequence` parameter on every transaction. Provide a value of about 3 higher than [the most recent ledger index](rippled-apis.html#ledger) to ensure that your transaction is either validated or rejected within a matter of seconds.
|
We strongly recommend that you specify the `LastLedgerSequence` parameter on every transaction. Provide a value of about 3 higher than [the most recent ledger index](reference-rippled.html#ledger) to ensure that your transaction is either validated or rejected within a matter of seconds.
|
||||||
|
|
||||||
Without the `LastLedgerSequence` parameter, there is a particular situation that can occur and cause your transaction to be stuck in an undesirable state where it is neither validated nor rejected for a long time. Specifically, if the load-based [transaction cost](#transaction-cost) of the network increases after you send a transaction, your transaction may not get propagated enough to be included in a validated ledger, but you would have to pay the (increased) transaction cost in order to send another transaction canceling it. Later, if the transaction cost decreases again, the transaction may become viable again. The `LastLedgerSequence` places a hard upper limit on how long the transaction can wait to be validated or rejected.
|
Without the `LastLedgerSequence` parameter, there is a particular situation that can occur and cause your transaction to be stuck in an undesirable state where it is neither validated nor rejected for a long time. Specifically, if the load-based [transaction cost](#transaction-cost) of the network increases after you send a transaction, your transaction may not get propagated enough to be included in a validated ledger, but you would have to pay the (increased) transaction cost in order to send another transaction canceling it. Later, if the transaction cost decreases again, the transaction may become viable again. The `LastLedgerSequence` places a hard upper limit on how long the transaction can wait to be validated or rejected.
|
||||||
|
|
||||||
@@ -321,17 +321,17 @@ Example payment:
|
|||||||
|
|
||||||
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|
||||||
|-------|-----------|--------------------------------------------------------|-------------|
|
|-------|-----------|--------------------------------------------------------|-------------|
|
||||||
| Amount | String (XRP)<br/>Object (Otherwise) | Amount | The amount of currency to deliver. *Note:* If the [*tfPartialPayment* flag](#payment-flags) is set, this is not the amount actually received. (Formatted as per [Specifying Currency Amounts](rippled-apis.html#specifying-currency-amounts).) |
|
| Amount | String (XRP)<br/>Object (Otherwise) | Amount | The amount of currency to deliver. *Note:* If the [*tfPartialPayment* flag](#payment-flags) is set, this is not the amount actually received. (Formatted as per [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts).) |
|
||||||
| Destination | String | Account | The unique address of the account receiving the payment. |
|
| Destination | String | Account | The unique address of the account receiving the payment. |
|
||||||
| DestinationTag | Unsigned Integer | UInt32 | (Optional) Arbitrary tag that identifies the reason for the payment to the destination, or the hosted wallet to make a payment to. |
|
| DestinationTag | Unsigned Integer | UInt32 | (Optional) Arbitrary tag that identifies the reason for the payment to the destination, or the hosted wallet to make a payment to. |
|
||||||
| InvoiceID | String | Hash256 | (Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment. |
|
| InvoiceID | String | Hash256 | (Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment. |
|
||||||
| Paths | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](https://ripple.com/wiki/Payment_paths) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. |
|
| Paths | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](https://ripple.com/wiki/Payment_paths) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. |
|
||||||
| SendMax | String/Object | Amount | (Optional) Highest amount of source currency this transaction is allowed to cost, including [transfer fees](transfer_fees.html), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](#transaction-cost). (Also see [Specifying Currency Amounts](rippled-apis.html#specifying-currency-amounts)) Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. |
|
| SendMax | String/Object | Amount | (Optional) Highest amount of source currency this transaction is allowed to cost, including [transfer fees](concept-transfer-fees.html), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](#transaction-cost). (Also see [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts)) Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. |
|
||||||
| DeliverMin | String/Object | Amount | (Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](#partial-payments). _(This field is part of [rippled 0.29.0](https://github.com/ripple/rippled/releases/tag/0.29.0), and becomes valid August 17 at 17:00 UTC.)_ |
|
| DeliverMin | String/Object | Amount | (Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](#partial-payments). _(This field is part of [rippled 0.29.0](https://github.com/ripple/rippled/releases/tag/0.29.0), and becomes valid August 17 at 17:00 UTC.)_ |
|
||||||
|
|
||||||
### Special issuer Values for SendMax and Amount ###
|
### Special issuer Values for SendMax and Amount ###
|
||||||
|
|
||||||
Most of the time, the `issuer` field of a non-XRP [currency amount](rippled-apis.html#specifying-currency-amounts) indicates the account of the gateway that issues that currency. However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment.
|
Most of the time, the `issuer` field of a non-XRP [currency amount](reference-rippled.html#specifying-currency-amounts) indicates the account of the gateway that issues that currency. However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment.
|
||||||
|
|
||||||
* There is only ever one balance for the same currency between two accounts. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming issuances, instead of the account that created the issuances.
|
* There is only ever one balance for the same currency between two accounts. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming issuances, instead of the account that created the issuances.
|
||||||
* When the `issuer` field of the destination `Amount` field matches the `Destination` account address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines.
|
* When the `issuer` field of the destination `Amount` field matches the `Destination` account address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines.
|
||||||
@@ -339,7 +339,7 @@ Most of the time, the `issuer` field of a non-XRP [currency amount](rippled-apis
|
|||||||
|
|
||||||
### Creating Accounts ###
|
### Creating Accounts ###
|
||||||
|
|
||||||
The Payment transaction type is the only way to create new accounts in the shared Ripple ledger. To do so, send an amount of XRP that is equal or greater than the [account reserve](reserves.html) to a mathematically-valid account address that does not exist yet. When the payment is processed, a new [AccountRoot node](ripple-ledger.html#accountroot) will be added to the ledger to reflect the newly-created account.
|
The Payment transaction type is the only way to create new accounts in the shared Ripple ledger. To do so, send an amount of XRP that is equal or greater than the [account reserve](concept-reserves.html) to a mathematically-valid account address that does not exist yet. When the payment is processed, a new [AccountRoot node](reference-ledger-format.html#accountroot) will be added to the ledger to reflect the newly-created account.
|
||||||
|
|
||||||
If you attempt to send an insufficient amount of XRP, or any other currency, the Payment will fail.
|
If you attempt to send an insufficient amount of XRP, or any other currency, the Payment will fail.
|
||||||
|
|
||||||
@@ -356,7 +356,7 @@ If the `Paths` field is provided, the server decides at transaction processing t
|
|||||||
|
|
||||||
The `Paths` field must not be an empty array, nor an array whose members are all empty arrays.
|
The `Paths` field must not be an empty array, nor an array whose members are all empty arrays.
|
||||||
|
|
||||||
For more information, see [Paths](paths.html).
|
For more information, see [Paths](concept-paths.html).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -409,7 +409,7 @@ In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is
|
|||||||
|
|
||||||
[[Source]<br>](https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp "Source")
|
[[Source]<br>](https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp "Source")
|
||||||
|
|
||||||
An AccountSet transaction modifies the properties of an [account in the Ripple Consensus Ledger](ripple-ledger.html#accountroot).
|
An AccountSet transaction modifies the properties of an [account in the Ripple Consensus Ledger](reference-ledger-format.html#accountroot).
|
||||||
|
|
||||||
Example AccountSet:
|
Example AccountSet:
|
||||||
|
|
||||||
@@ -467,8 +467,8 @@ The available AccountSet flags are:
|
|||||||
| asfDisallowXRP | 3 | XRP should not be sent to this account. (Enforced by client applications, not by `rippled`) | lsfDisallowXRP |
|
| asfDisallowXRP | 3 | XRP should not be sent to this account. (Enforced by client applications, not by `rippled`) | lsfDisallowXRP |
|
||||||
| asfDisableMaster | 4 | Disallow use of the master key. Can only be enabled if the account has a [RegularKey](#setregularkey) configured. | lsfDisableMaster |
|
| asfDisableMaster | 4 | Disallow use of the master key. Can only be enabled if the account has a [RegularKey](#setregularkey) configured. | lsfDisableMaster |
|
||||||
| asfAccountTxnID | 5 | Track the ID of this account's most recent transaction. Required for [AccountTxnID](#accounttxnid) | (None) |
|
| asfAccountTxnID | 5 | Track the ID of this account's most recent transaction. Required for [AccountTxnID](#accounttxnid) | (None) |
|
||||||
| asfNoFreeze | 6 | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](freeze.html). This flag can never be disabled after being enabled. | lsfNoFreeze |
|
| asfNoFreeze | 6 | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](concept-freeze.html). This flag can never be disabled after being enabled. | lsfNoFreeze |
|
||||||
| asfGlobalFreeze | 7 | [Freeze](freeze.html) all assets issued by this account. | lsfGlobalFreeze |
|
| asfGlobalFreeze | 7 | [Freeze](concept-freeze.html) all assets issued by this account. | lsfGlobalFreeze |
|
||||||
| asfDefaultRipple | 8 | Enable [rippling](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) on this account's trust lines by default. _(New in [rippled 0.27.3](https://github.com/ripple/rippled/releases/tag/0.27.3))_ | lsfDefaultRipple |
|
| asfDefaultRipple | 8 | Enable [rippling](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) on this account's trust lines by default. _(New in [rippled 0.27.3](https://github.com/ripple/rippled/releases/tag/0.27.3))_ | lsfDefaultRipple |
|
||||||
|
|
||||||
_New in [rippled 0.28.0][]:_ You cannot send a transaction that enables `asfDisableMaster` or `asfNoFreeze` using a [regular key](#setregularkey). You must use the master key to sign the transaction.
|
_New in [rippled 0.28.0][]:_ You cannot send a transaction that enables `asfDisableMaster` or `asfNoFreeze` using a [regular key](#setregularkey). You must use the master key to sign the transaction.
|
||||||
@@ -524,9 +524,9 @@ A SetRegularKey transaction changes the regular key used by the account to sign
|
|||||||
|
|
||||||
Instead of using an account's master key to sign transactions, you can set an alternate key pair, called the "Regular Key". As long as the public key for this key pair is set in the `RegularKey` field of an account this way, then the secret of the Regular Key pair can be used to sign transactions. (The master secret can still be used, too, unless you set the [asfDisableMaster account flag](#accountset-flags).)
|
Instead of using an account's master key to sign transactions, you can set an alternate key pair, called the "Regular Key". As long as the public key for this key pair is set in the `RegularKey` field of an account this way, then the secret of the Regular Key pair can be used to sign transactions. (The master secret can still be used, too, unless you set the [asfDisableMaster account flag](#accountset-flags).)
|
||||||
|
|
||||||
A Regular Key pair is generated in the same way as any other Ripple keys (for example, with [wallet_propose](rippled-apis.html#wallet-propose)), but it can be changed. A Master Key pair is an intrinsic part of the account's identity (the address is derived from the master public key) so the Master Key cannot be changed. Therefore, using a Regular Key to sign transactions instead of the master key whenever possible is beneficial to security.
|
A Regular Key pair is generated in the same way as any other Ripple keys (for example, with [wallet_propose](reference-rippled.html#wallet-propose)), but it can be changed. A Master Key pair is an intrinsic part of the account's identity (the address is derived from the master public key) so the Master Key cannot be changed. Therefore, using a Regular Key to sign transactions instead of the master key whenever possible is beneficial to security.
|
||||||
|
|
||||||
If your regular key is compromised, but the master key is not, you can use this method to regain control of your account. In some cases, you can even send a [key reset transaction](tx-cost.html#key-reset-transaction) without paying the [transaction cost](#transaction-cost).
|
If your regular key is compromised, but the master key is not, you can use this method to regain control of your account. In some cases, you can even send a [key reset transaction](concept-transaction-cost.html#key-reset-transaction) without paying the [transaction cost](#transaction-cost).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -555,7 +555,7 @@ An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.or
|
|||||||
|
|
||||||
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|
||||||
|-------|-----------|--------------------------------------------------------|-------------|
|
|-------|-----------|--------------------------------------------------------|-------------|
|
||||||
| [Expiration](#expiration) | Unsigned Integer | UInt32 | (Optional) Time after which the offer is no longer active, in [seconds since the Ripple Epoch](rippled-apis.html#specifying-time). |
|
| [Expiration](#expiration) | Unsigned Integer | UInt32 | (Optional) Time after which the offer is no longer active, in [seconds since the Ripple Epoch](reference-rippled.html#specifying-time). |
|
||||||
| OfferSequence | Unsigned Integer | UInt32 | (Optional) An offer to delete first, specified in the same way as [OfferCancel](#offercancel). |
|
| OfferSequence | Unsigned Integer | UInt32 | (Optional) An offer to delete first, specified in the same way as [OfferCancel](#offercancel). |
|
||||||
| TakerGets | Object (Non-XRP), or <br/>String (XRP) | Amount | The amount and type of currency being provided by the offer creator. |
|
| TakerGets | Object (Non-XRP), or <br/>String (XRP) | Amount | The amount and type of currency being provided by the offer creator. |
|
||||||
| TakerPays | Object (Non-XRP), or <br/>String (XRP) | Amount | The amount and type of currency being requested by the offer creator. |
|
| TakerPays | Object (Non-XRP), or <br/>String (XRP) | Amount | The amount and type of currency being requested by the offer creator. |
|
||||||
@@ -572,7 +572,7 @@ It is possible for an offer to become temporarily or permanently *unfunded*:
|
|||||||
|
|
||||||
* If the creator no longer has any of the `TakerGets` currency.
|
* If the creator no longer has any of the `TakerGets` currency.
|
||||||
* The offer becomes funded again when the creator obtains more of that currency.
|
* The offer becomes funded again when the creator obtains more of that currency.
|
||||||
* If the currency required to fund the offer is held in a [frozen trust line](freeze.html).
|
* If the currency required to fund the offer is held in a [frozen trust line](concept-freeze.html).
|
||||||
* The offer becomes funded again when the trust line is no longer frozen.
|
* The offer becomes funded again when the trust line is no longer frozen.
|
||||||
* If the creator does not have enough XRP for the reserve amount of a new trust line required by the offer. (See [Offers and Trust](#offers-and-trust).)
|
* If the creator does not have enough XRP for the reserve amount of a new trust line required by the offer. (See [Offers and Trust](#offers-and-trust).)
|
||||||
* The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease.
|
* The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease.
|
||||||
@@ -591,14 +591,14 @@ An unfunded offer can remain on the ledger indefinitely, but it does not have an
|
|||||||
|
|
||||||
Tracking the funding status of all offers can be computationally taxing. In particular, accounts that are actively trading may have a large number of offers open and be frequently involved in transactions that affect the funding status of their offers. Because of this, `rippled` does not proactively find and remove offers.
|
Tracking the funding status of all offers can be computationally taxing. In particular, accounts that are actively trading may have a large number of offers open and be frequently involved in transactions that affect the funding status of their offers. Because of this, `rippled` does not proactively find and remove offers.
|
||||||
|
|
||||||
A client application can locally track the funding status of offers. To do this, first retreive an order book using the [`book_offers` command](rippled-apis.html#book-offers) and check the `taker_gets_funded` field of offers. Then, [subscribe](rippled-apis.html#subscribe) to the `transactions` stream and watch the transaction metadata to see which offers are modified.
|
A client application can locally track the funding status of offers. To do this, first retreive an order book using the [`book_offers` command](reference-rippled.html#book-offers) and check the `taker_gets_funded` field of offers. Then, [subscribe](reference-rippled.html#subscribe) to the `transactions` stream and watch the transaction metadata to see which offers are modified.
|
||||||
|
|
||||||
|
|
||||||
### Offers and Trust ###
|
### Offers and Trust ###
|
||||||
|
|
||||||
The limit values of trust lines (See [TrustSet](#trustset)) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuing gateway to redeem.
|
The limit values of trust lines (See [TrustSet](#trustset)) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuing gateway to redeem.
|
||||||
|
|
||||||
However, possessing non-XRP balances still requires a trust line to the account issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because [trust lines increase the reserve an account must hold](reserves.html), any offers that would require a new trust line also require the account to have the necessary XRP to pay the reserve for that trust line.
|
However, possessing non-XRP balances still requires a trust line to the account issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because [trust lines increase the reserve an account must hold](concept-reserves.html), any offers that would require a new trust line also require the account to have the necessary XRP to pay the reserve for that trust line.
|
||||||
|
|
||||||
A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits.
|
A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits.
|
||||||
|
|
||||||
@@ -614,7 +614,7 @@ Since transactions can take time to propagate and confirm, the timestamp of a le
|
|||||||
|
|
||||||
You can determine the final disposition of an offer with an `Expiration` as soon as you see a fully-validated ledger with a close time equal to or greater than the expiration time.
|
You can determine the final disposition of an offer with an `Expiration` as soon as you see a fully-validated ledger with a close time equal to or greater than the expiration time.
|
||||||
|
|
||||||
*Note:* Since only new transactions can modify the ledger, an expired offer can remain on the ledger after it becomes inactive. The offer is treated as unfunded and has no effect, but it can continue to appear in results (for example, from the [ledger_entry](rippled-apis.html#ledger-entry) command). Later on, the expired offer can get finally deleted as a result of another transaction (such as another OfferCreate) if the server encounters it while processing.
|
*Note:* Since only new transactions can modify the ledger, an expired offer can remain on the ledger after it becomes inactive. The offer is treated as unfunded and has no effect, but it can continue to appear in results (for example, from the [ledger_entry](reference-rippled.html#ledger-entry) command). Later on, the expired offer can get finally deleted as a result of another transaction (such as another OfferCreate) if the server encounters it while processing.
|
||||||
|
|
||||||
### Auto-Bridging ###
|
### Auto-Bridging ###
|
||||||
|
|
||||||
@@ -667,7 +667,7 @@ An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledge
|
|||||||
|
|
||||||
*Tip:* To remove an old offer and replace it with a new one, you can use an [OfferCreate](#offercreate) transaction with an `OfferSequence` parameter, instead of using OfferCancel and another OfferCreate.
|
*Tip:* To remove an old offer and replace it with a new one, you can use an [OfferCreate](#offercreate) transaction with an `OfferSequence` parameter, instead of using OfferCancel and another OfferCreate.
|
||||||
|
|
||||||
The OfferCancel method returns [tesSUCCESS](transactions.html#transaction-results) even if it did not find an offer with the matching sequence number.
|
The OfferCancel method returns [tesSUCCESS](#transaction-results) even if it did not find an offer with the matching sequence number.
|
||||||
|
|
||||||
|
|
||||||
## TrustSet ##
|
## TrustSet ##
|
||||||
@@ -694,7 +694,7 @@ Create or modify a trust line linking two accounts.
|
|||||||
|
|
||||||
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|
||||||
|-------|-----------|---------------|-------------|
|
|-------|-----------|---------------|-------------|
|
||||||
| [LimitAmount](#trust-limits) | Object | Amount | Object defining the trust line to create or modify, in the same format as [currency amounts](rippled-apis.html#specifying-currency-amounts). |
|
| [LimitAmount](#trust-limits) | Object | Amount | Object defining the trust line to create or modify, in the same format as [currency amounts](reference-rippled.html#specifying-currency-amounts). |
|
||||||
| LimitAmount.currency | String | (Amount.currency) | The currency to this trust line applies to, as a three-letter [ISO 4217 Currency Code](http://www.xe.com/iso4217.php) or a 160-bit hex value according to [currency format](https://wiki.ripple.com/Currency_format). "XRP" is invalid. |
|
| LimitAmount.currency | String | (Amount.currency) | The currency to this trust line applies to, as a three-letter [ISO 4217 Currency Code](http://www.xe.com/iso4217.php) or a 160-bit hex value according to [currency format](https://wiki.ripple.com/Currency_format). "XRP" is invalid. |
|
||||||
| LimitAmount.value | String | (Amount.value) | Quoted decimal representation of the limit to set on this trust line. |
|
| LimitAmount.value | String | (Amount.value) | Quoted decimal representation of the limit to set on this trust line. |
|
||||||
| LimitAmount.issuer | String | (Amount.issuer) | The address of the account to extend trust to. |
|
| LimitAmount.issuer | String | (Amount.issuer) | The address of the account to extend trust to. |
|
||||||
@@ -709,7 +709,7 @@ Since a computer program cannot force the gateway to keep its promise and not de
|
|||||||
|
|
||||||
There are two cases where you can hold a balance on a trust line that is *greater* than your limit: when you acquire more of that currency through [trading](#offercreate), or when you decrease the limit on your trust line.
|
There are two cases where you can hold a balance on a trust line that is *greater* than your limit: when you acquire more of that currency through [trading](#offercreate), or when you decrease the limit on your trust line.
|
||||||
|
|
||||||
Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](reserves.html). This applies to the account extending trust, not to the account receiving it.
|
Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](concept-reserves.html). This applies to the account extending trust, not to the account receiving it.
|
||||||
|
|
||||||
A trust line with settings in the default state is equivalent to no trust line.
|
A trust line with settings in the default state is equivalent to no trust line.
|
||||||
|
|
||||||
@@ -726,8 +726,8 @@ Transactions of the TrustSet type support additional values in the [`Flags` fiel
|
|||||||
| tfSetfAuth | 0x00010000 | 65536 | Authorize the other party to hold issuances from this account. (No effect unless using the [*asfRequireAuth* AccountSet flag](#accountset-flags).) Cannot be unset. |
|
| tfSetfAuth | 0x00010000 | 65536 | Authorize the other party to hold issuances from this account. (No effect unless using the [*asfRequireAuth* AccountSet flag](#accountset-flags).) Cannot be unset. |
|
||||||
| tfSetNoRipple | 0x00020000 | 131072 | Blocks rippling between two trustlines of the same currency, if this flag is set on both. (See [No Ripple](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) for details.) |
|
| tfSetNoRipple | 0x00020000 | 131072 | Blocks rippling between two trustlines of the same currency, if this flag is set on both. (See [No Ripple](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) for details.) |
|
||||||
| tfClearNoRipple | 0x00040000 | 262144 | Clears the No-Rippling flag. (See [No Ripple](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) for details.) |
|
| tfClearNoRipple | 0x00040000 | 262144 | Clears the No-Rippling flag. (See [No Ripple](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) for details.) |
|
||||||
| tfSetFreeze | 0x00100000 | 1048576 | [Freeze](freeze.html) the trustline.
|
| tfSetFreeze | 0x00100000 | 1048576 | [Freeze](concept-freeze.html) the trustline.
|
||||||
| tfClearFreeze | 0x00200000 | 2097152 | [Unfreeze](freeze.html) the trustline. |
|
| tfClearFreeze | 0x00200000 | 2097152 | [Unfreeze](concept-freeze.html) the trustline. |
|
||||||
|
|
||||||
|
|
||||||
# Pseudo-Transactions #
|
# Pseudo-Transactions #
|
||||||
@@ -746,7 +746,7 @@ Some of the fields that are mandatory for normal transactions do not make sense
|
|||||||
|
|
||||||
## SetFee ##
|
## SetFee ##
|
||||||
|
|
||||||
A change in [transaction cost](tx-cost.html) or [account reserve](reserves.html) requirements. This is typically in response to changes in the load on the network.
|
A change in [transaction cost](concept-transaction-cost.html) or [account reserve](concept-reserves.html) requirements. This is typically in response to changes in the load on the network.
|
||||||
|
|
||||||
*Note:* You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.
|
*Note:* You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.
|
||||||
|
|
||||||
@@ -769,7 +769,7 @@ A change in [transaction cost](tx-cost.html) or [account reserve](reserves.html)
|
|||||||
|
|
||||||
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|
||||||
|-------|-----------|--------------------------------------------------------|-------------|
|
|-------|-----------|--------------------------------------------------------|-------------|
|
||||||
| BaseFee | String | UInt64 | The charge, in drops of XRP, for the reference transaction, as hex. (This is the [transaction cost](tx-cost.html) before scaling for load.) |
|
| BaseFee | String | UInt64 | The charge, in drops of XRP, for the reference transaction, as hex. (This is the [transaction cost](concept-transaction-cost.html) before scaling for load.) |
|
||||||
| ReferenceFeeUnits | Unsigned Integer | UInt32 | The cost, in fee units, of the reference transaction |
|
| ReferenceFeeUnits | Unsigned Integer | UInt32 | The cost, in fee units, of the reference transaction |
|
||||||
| ReserveBase | Unsigned Integer | UInt32 | The base reserve, in drops |
|
| ReserveBase | Unsigned Integer | UInt32 | The base reserve, in drops |
|
||||||
| ReserveIncrement | Unsigned Integer | UInt32 | The incremental reserve, in drops |
|
| ReserveIncrement | Unsigned Integer | UInt32 | The incremental reserve, in drops |
|
||||||
@@ -780,7 +780,7 @@ A change in [transaction cost](tx-cost.html) or [account reserve](reserves.html)
|
|||||||
|
|
||||||
## Immediate Response ##
|
## Immediate Response ##
|
||||||
|
|
||||||
The response from the [`submit` command](rippled-apis.html#submit) contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction.
|
The response from the [`submit` command](reference-rippled.html#submit) contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction.
|
||||||
|
|
||||||
The response from `submit` contains the following fields:
|
The response from `submit` contains the following fields:
|
||||||
|
|
||||||
@@ -802,7 +802,7 @@ __*Note:*__ A successful result at this stage does not indicate that the transac
|
|||||||
|
|
||||||
## Looking up Transaction Results ##
|
## Looking up Transaction Results ##
|
||||||
|
|
||||||
To see the final result of a transaction, use the [`tx` command](rippled-apis.html#tx), [`account_tx` command](rippled-apis.html#account-tx), or other response from `rippled`. Look for `"validated": true` to indicate that this response uses a ledger version that has been validated by consensus.
|
To see the final result of a transaction, use the [`tx` command](reference-rippled.html#tx), [`account_tx` command](reference-rippled.html#account-tx), or other response from `rippled`. Look for `"validated": true` to indicate that this response uses a ledger version that has been validated by consensus.
|
||||||
|
|
||||||
| Field | Value | Description |
|
| Field | Value | Description |
|
||||||
|-------|-------|-------------|
|
|-------|-------|-------------|
|
||||||
@@ -829,7 +829,7 @@ Both the `engine_result` and the `meta.TransactionResult` use standard codes to
|
|||||||
| Failure | [tef](#tef-codes) | The transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future. |
|
| Failure | [tef](#tef-codes) | The transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future. |
|
||||||
| Retry | [ter](#ter-codes) | The transaction could not be applied, but it might be possible to apply later. |
|
| Retry | [ter](#ter-codes) | The transaction could not be applied, but it might be possible to apply later. |
|
||||||
| Success | [tes](#tes-success) | (Not an error) The transaction succeeded. This result is not final unless it appears in a validated ledger. |
|
| Success | [tes](#tes-success) | (Not an error) The transaction succeeded. This result is not final unless it appears in a validated ledger. |
|
||||||
| Claimed cost only | [tec](#tec-codes) | The transaction did not achieve its intended purpose, but the [transaction cost](tx-cost.html) was destroyed. This result is not final unless it appears in a validated ledger. |
|
| Claimed cost only | [tec](#tec-codes) | The transaction did not achieve its intended purpose, but the [transaction cost](concept-transaction-cost.html) was destroyed. This result is not final unless it appears in a validated ledger. |
|
||||||
| Client library error | [tej](#tej-codes) | (ripple-lib only) The transaction was not submitted, because the client library blocked it, as part of its additional error checking. |
|
| Client library error | [tej](#tej-codes) | (ripple-lib only) The transaction was not submitted, because the client library blocked it, as part of its additional error checking. |
|
||||||
|
|
||||||
The distinction between a local error (`tel`) and a malformed transaction (`tem`) is a matter of protocol-level rules. For example, the protocol sets no limit on the maximum number of paths that can be included in a transaction. However, a server may define a finite limit of paths it can process. If two different servers are configured differently, then one of them may return a `tel` error for a transaction with many paths, while the other server could successfully process the transaction. If enough servers are able to process the transaction that it survives consensus, then it can still be included in a validated ledger.
|
The distinction between a local error (`tel`) and a malformed transaction (`tem`) is a matter of protocol-level rules. For example, the protocol sets no limit on the maximum number of paths that can be included in a transaction. However, a server may define a finite limit of paths it can process. If two different servers are configured differently, then one of them may return a `tel` error for a transaction with many paths, while the other server could successfully process the transaction. If enough servers are able to process the transaction that it survives consensus, then it can still be included in a validated ledger.
|
||||||
@@ -838,7 +838,7 @@ By contrast, a `tem` error implies that no server anywhere can apply the transac
|
|||||||
|
|
||||||
## Claimed Cost Justification ##
|
## Claimed Cost Justification ##
|
||||||
|
|
||||||
Although it may seem unfair to charge a [transaction cost](tx-cost.html) for a failed transaction, the `tec` class of errors exists for good reasons:
|
Although it may seem unfair to charge a [transaction cost](concept-transaction-cost.html) for a failed transaction, the `tec` class of errors exists for good reasons:
|
||||||
|
|
||||||
* Transactions submitted after the failed one do not have to have their Sequence values renumbered. Incorporating the failed transaction into a ledger uses up the transaction's sequence number, preserving the expected sequence.
|
* Transactions submitted after the failed one do not have to have their Sequence values renumbered. Incorporating the failed transaction into a ledger uses up the transaction's sequence number, preserving the expected sequence.
|
||||||
* Distributing the transaction throughout the network increases network load. Enforcing a cost makes it harder for attackers to abuse the network with failed transactions.
|
* Distributing the transaction throughout the network increases network load. Enforcing a cost makes it harder for attackers to abuse the network with failed transactions.
|
||||||
@@ -876,7 +876,7 @@ Some fields that may appear in transaction metadata include:
|
|||||||
| DeliveredAmount | String or Object | **DEPRECATED.** Replaced by `delivered_amount`. Omitted if not a partial payment. |
|
| DeliveredAmount | String or Object | **DEPRECATED.** Replaced by `delivered_amount`. Omitted if not a partial payment. |
|
||||||
| TransactionIndex | Unsigned Integer | The transaction's position within the ledger that included it. (For example, the value `2` means it was the 2nd transaction in that ledger.) |
|
| TransactionIndex | Unsigned Integer | The transaction's position within the ledger that included it. (For example, the value `2` means it was the 2nd transaction in that ledger.) |
|
||||||
| TransactionResult | String | A [result code](#result-categories) indicating whether the transaction succeeded or how it failed. |
|
| TransactionResult | String | A [result code](#result-categories) indicating whether the transaction succeeded or how it failed. |
|
||||||
| [delivered_amount](#delivered-amount) | Object or String | (New in [rippled 0.27.0](https://github.com/ripple/rippled/releases/tag/0.27.0)) The [amount](rippled-apis.html#specifying-currency-amounts) actually received by the `Destination` account. Use this field to determine how much was delivered, regardless of whether the transaction is a [partial payment](#partial-payments). |
|
| [delivered_amount](#delivered-amount) | Object or String | (New in [rippled 0.27.0](https://github.com/ripple/rippled/releases/tag/0.27.0)) The [amount](reference-rippled.html#specifying-currency-amounts) actually received by the `Destination` account. Use this field to determine how much was delivered, regardless of whether the transaction is a [partial payment](#partial-payments). |
|
||||||
|
|
||||||
### delivered_amount ###
|
### delivered_amount ###
|
||||||
|
|
||||||
@@ -906,7 +906,7 @@ These codes indicate an error in the local server processing the transaction; it
|
|||||||
| telBAD\_PATH_COUNT | The transaction contains too many paths for the local server to process. |
|
| telBAD\_PATH_COUNT | The transaction contains too many paths for the local server to process. |
|
||||||
| telBAD\_PUBLIC\_KEY | The transaction specified a public key value (for example, as the `MessageKey` field of an [AccountSet transaction](#accountset)) that cannot be used, probably because it is too long. |
|
| telBAD\_PUBLIC\_KEY | The transaction specified a public key value (for example, as the `MessageKey` field of an [AccountSet transaction](#accountset)) that cannot be used, probably because it is too long. |
|
||||||
| telFAILED\_PROCESSING | An unspecified error occurred when processing the transaction. |
|
| telFAILED\_PROCESSING | An unspecified error occurred when processing the transaction. |
|
||||||
| telINSUF\_FEE_P | The `Fee` from the transaction is not high enough to meet the server's current [transaction cost](tx-cost.html) requirement, which is derived from its load level. |
|
| telINSUF\_FEE_P | The `Fee` from the transaction is not high enough to meet the server's current [transaction cost](concept-transaction-cost.html) requirement, which is derived from its load level. |
|
||||||
| telNO\_DST\_PARTIAL | The transaction is an XRP payment that would fund a new account, but the [tfPartialPayment flag](#partial-payments) was enabled. This is disallowed. |
|
| telNO\_DST\_PARTIAL | The transaction is an XRP payment that would fund a new account, but the [tfPartialPayment flag](#partial-payments) was enabled. This is disallowed. |
|
||||||
|
|
||||||
### tem Codes ###
|
### tem Codes ###
|
||||||
@@ -918,7 +918,7 @@ These codes indicate that the transaction was malformed, and cannot succeed acco
|
|||||||
| temMALFORMED | Unspecified problem with the format of the transaction. |
|
| temMALFORMED | Unspecified problem with the format of the transaction. |
|
||||||
| temBAD\_AMOUNT | An amount specified by the transaction (for example the destination `Amount` or `SendMax` values of a [Payment](#payment)) was invalid, possibly because it was a negative number. |
|
| temBAD\_AMOUNT | An amount specified by the transaction (for example the destination `Amount` or `SendMax` values of a [Payment](#payment)) was invalid, possibly because it was a negative number. |
|
||||||
| temBAD\_AUTH\_MASTER | The key used to sign this transaction does not match the master key for the account sending it, and the account does not have a [Regular Key](#setregularkey) set. |
|
| temBAD\_AUTH\_MASTER | The key used to sign this transaction does not match the master key for the account sending it, and the account does not have a [Regular Key](#setregularkey) set. |
|
||||||
| temBAD\_CURRENCY | The transaction improperly specified a currency field. See [Specifying Currency Amounts](rippled-apis.html#specifying-currency-amounts) for the correct format. |
|
| temBAD\_CURRENCY | The transaction improperly specified a currency field. See [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts) for the correct format. |
|
||||||
| temBAD\_EXPIRATION | The transaction improperly specified an expiration value, for example as part of an [OfferCreate transaction](#offercreate). |
|
| temBAD\_EXPIRATION | The transaction improperly specified an expiration value, for example as part of an [OfferCreate transaction](#offercreate). |
|
||||||
| temBAD\_FEE | The transaction improperly specified its `Fee` value, for example by listing a non-XRP currency or some negative amount of XRP. |
|
| temBAD\_FEE | The transaction improperly specified its `Fee` value, for example by listing a non-XRP currency or some negative amount of XRP. |
|
||||||
| temBAD\_ISSUER | The transaction improperly specified the `issuer` field of some currency included in the request. |
|
| temBAD\_ISSUER | The transaction improperly specified the `issuer` field of some currency included in the request. |
|
||||||
@@ -990,7 +990,7 @@ The code `tesSUCCESS` is the only code that indicates a transaction succeeded. T
|
|||||||
|
|
||||||
### tec Codes ###
|
### tec Codes ###
|
||||||
|
|
||||||
These codes indicate that the transaction failed, but it was applied to a ledger in order to apply the [transaction cost](tx-cost.html). They have numerical values in the range 100 to 199. The exact codes sometimes appear in ledger data, so they do not change, but we recommend not relying on the numeric value regardless.
|
These codes indicate that the transaction failed, but it was applied to a ledger in order to apply the [transaction cost](concept-transaction-cost.html). They have numerical values in the range 100 to 199. The exact codes sometimes appear in ledger data, so they do not change, but we recommend not relying on the numeric value regardless.
|
||||||
|
|
||||||
| Code | Value | Explanation |
|
| Code | Value | Explanation |
|
||||||
|------|-------|-------------|
|
|------|-------|-------------|
|
||||||
@@ -998,14 +998,14 @@ These codes indicate that the transaction failed, but it was applied to a ledger
|
|||||||
| tecPATH\_PARTIAL | 101 | The transaction failed because the provided paths did not have enough liquidity to send the full amount. |
|
| tecPATH\_PARTIAL | 101 | The transaction failed because the provided paths did not have enough liquidity to send the full amount. |
|
||||||
| tecUNFUNDED\_ADD | 102 | **DEPRECATED.** |
|
| tecUNFUNDED\_ADD | 102 | **DEPRECATED.** |
|
||||||
| tecUNFUNDED\_OFFER | 103 | The [OfferCreate transaction](#offercreate) failed because the account creating the offer does not have any of the `TakerGets` currency. |
|
| tecUNFUNDED\_OFFER | 103 | The [OfferCreate transaction](#offercreate) failed because the account creating the offer does not have any of the `TakerGets` currency. |
|
||||||
| tecUNFUNDED\_PAYMENT | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the reserve. (See: [Reserves](reserves.html)) |
|
| tecUNFUNDED\_PAYMENT | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the reserve. (See: [Reserves](concept-reserves.html)) |
|
||||||
| tecFAILED\_PROCESSING | 105 | An unspecified error occurred when processing the transaction. |
|
| tecFAILED\_PROCESSING | 105 | An unspecified error occurred when processing the transaction. |
|
||||||
| tecDIR\_FULL | 121 | The "owners count" of the account sending the transaction is already maxed out. |
|
| tecDIR\_FULL | 121 | The "owners count" of the account sending the transaction is already maxed out. |
|
||||||
| tecINSUF\_RESERVE\_LINE | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](reserves.html)) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See tecNO\_LINE\_INSUF\_RESERVE for the other case.) |
|
| tecINSUF\_RESERVE\_LINE | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](concept-reserves.html)) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See tecNO\_LINE\_INSUF\_RESERVE for the other case.) |
|
||||||
| tecINSUF\_RESERVE\_OFFER | 123 | The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: [Reserves](reserves.html)) |
|
| tecINSUF\_RESERVE\_OFFER | 123 | The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: [Reserves](concept-reserves.html)) |
|
||||||
| tecNO\_DST | 124 | The account on the receiving end of the transaction does not exist. This includes Payment and TrustSet transaction types. (It could be created if it received sufficient XRP.) |
|
| tecNO\_DST | 124 | The account on the receiving end of the transaction does not exist. This includes Payment and TrustSet transaction types. (It could be created if it received sufficient XRP.) |
|
||||||
| tecNO\_DST\_INSUF_XRP | 125 | The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it. |
|
| tecNO\_DST\_INSUF_XRP | 125 | The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it. |
|
||||||
| tecNO\_LINE\_INSUF\_RESERVE | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](reserves.html)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See tecINSUF\_RESERVE\_LINE for the other case.) |
|
| tecNO\_LINE\_INSUF\_RESERVE | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](concept-reserves.html)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See tecINSUF\_RESERVE\_LINE for the other case.) |
|
||||||
| tecNO\_LINE\_REDUNDANT | 127 | The transaction failed because it attempted to set a trust line to its default state, but the trust line did not exist. |
|
| tecNO\_LINE\_REDUNDANT | 127 | The transaction failed because it attempted to set a trust line to its default state, but the trust line did not exist. |
|
||||||
| tecPATH\_DRY | 128 | The transaction failed because the provided paths did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by trust lines. |
|
| tecPATH\_DRY | 128 | The transaction failed because the provided paths did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by trust lines. |
|
||||||
| tecUNFUNDED | 129 | **DEPRECATED.** Replaced by tecUNFUNDED\_OFFER and tecUNFUNDED\_PAYMENT. |
|
| tecUNFUNDED | 129 | **DEPRECATED.** Replaced by tecUNFUNDED\_OFFER and tecUNFUNDED\_PAYMENT. |
|
||||||
@@ -1016,7 +1016,7 @@ These codes indicate that the transaction failed, but it was applied to a ledger
|
|||||||
| tecNO\_AUTH | 134 | The transaction failed because it needs to add a balance on a trust line to an account with the `lsfRequireAuth` flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, tecNO\_LINE occurs instead. |
|
| tecNO\_AUTH | 134 | The transaction failed because it needs to add a balance on a trust line to an account with the `lsfRequireAuth` flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, tecNO\_LINE occurs instead. |
|
||||||
| tecNO\_LINE | 135 | The `TakerPays` field of the [OfferCreate transaction](#offercreate) specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, tecNO\_AUTH occurs instead. |
|
| tecNO\_LINE | 135 | The `TakerPays` field of the [OfferCreate transaction](#offercreate) specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, tecNO\_AUTH occurs instead. |
|
||||||
| tecINSUFF\_FEE | 136 | The account sending the transaction does not possess enough XRP to pay the specified `Fee`. This error only occurs if the transaction has already been propagated through the network to achieve consensus, |
|
| tecINSUFF\_FEE | 136 | The account sending the transaction does not possess enough XRP to pay the specified `Fee`. This error only occurs if the transaction has already been propagated through the network to achieve consensus, |
|
||||||
| tecFROZEN | 137 | The [OfferCreate transaction](#offercreate) failed because one or both of the assets involved are subject to a [global freeze](freeze.html). |
|
| tecFROZEN | 137 | The [OfferCreate transaction](#offercreate) failed because one or both of the assets involved are subject to a [global freeze](concept-freeze.html). |
|
||||||
| tecNO\_TARGET | 138 | **FORTHCOMING** Part of multi-signature transactions. |
|
| tecNO\_TARGET | 138 | **FORTHCOMING** Part of multi-signature transactions. |
|
||||||
| tecNO\_PERMISSION | 139 | **FORTHCOMING** Part of multi-signature transactions. |
|
| tecNO\_PERMISSION | 139 | **FORTHCOMING** Part of multi-signature transactions. |
|
||||||
| tecNO\_ENTRY | 140 | **FORTHCOMING** Part of multi-signature transactions. |
|
| tecNO\_ENTRY | 140 | **FORTHCOMING** Part of multi-signature transactions. |
|
||||||
@@ -1036,8 +1036,8 @@ These codes are only ever returned by the `ripple-lib` client library, not by `r
|
|||||||
| tejAttemptsExceeded | The transaction was submitted multiple times, up to a total equal to the max attempts setting, without being successfully included in a ledger. |
|
| tejAttemptsExceeded | The transaction was submitted multiple times, up to a total equal to the max attempts setting, without being successfully included in a ledger. |
|
||||||
| tejInvalidFlag | One of the flags specified was invalid, or does not apply to this transaction type. |
|
| tejInvalidFlag | One of the flags specified was invalid, or does not apply to this transaction type. |
|
||||||
| tejLocalSigningRequired | The transaction could not be resubmitted because local signing is disabled. |
|
| tejLocalSigningRequired | The transaction could not be resubmitted because local signing is disabled. |
|
||||||
| tejMaxFeeExceeded | The [transaction cost](tx-cost.html) that would be necessary to send the transaction is higher than the maximum transaction cost setting, which is either the `_MaxFee` parameter of the Transaction (if provided) or the maximum transaction cost configured for the remote. The default value is 1 XRP (100000 drops). |
|
| tejMaxFeeExceeded | The [transaction cost](concept-transaction-cost.html) that would be necessary to send the transaction is higher than the maximum transaction cost setting, which is either the `_MaxFee` parameter of the Transaction (if provided) or the maximum transaction cost configured for the remote. The default value is 1 XRP (100000 drops). |
|
||||||
| tejMaxLedger | Currently-validated ledgers have surpassed the `LastLedgerSequence` parameter of the transaction without including it, so it can no longer succeed. (Also see [Reliable Transaction Submission](reliable_tx.html).) When using ripple-lib, this error effectively replaces all non-final errors, including tel-, tef-, and ter-class response codes. |
|
| tejMaxLedger | Currently-validated ledgers have surpassed the `LastLedgerSequence` parameter of the transaction without including it, so it can no longer succeed. (Also see [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html).) When using ripple-lib, this error effectively replaces all non-final errors, including tel-, tef-, and ter-class response codes. |
|
||||||
| tejSecretInvalid | The secret included for signing this transaction was not a properly-formatted secret. |
|
| tejSecretInvalid | The secret included for signing this transaction was not a properly-formatted secret. |
|
||||||
| tejSecretUnknown | The secret for a given account was omitted from the transaction, and ripple-lib was unable to automatically fill it in from saved data. |
|
| tejSecretUnknown | The secret for a given account was omitted from the transaction, and ripple-lib was unable to automatically fill it in from saved data. |
|
||||||
| tejServerUntrusted | The application attempted to submit an account secret to an untrusted server for transaction signing. |
|
| tejServerUntrusted | The application attempted to submit an account secret to an untrusted server for transaction signing. |
|
||||||
@@ -65,25 +65,14 @@ The value of a gateway's issuances in Ripple comes directly from users' trust th
|
|||||||
|
|
||||||
### Hot and Cold Wallets ###
|
### Hot and Cold Wallets ###
|
||||||
|
|
||||||
It is strongly recommended that Ripple gateways employ a "hot wallet / cold wallet" strategy. This enforces a separation of roles that promotes strong security. ("Wallets" in Ripple are equivalent to Accounts.)
|
We strongly recommend that gateways use multiple Ripple ledger accounts with a separation of roles. This promotes strong security and minimizes risk. We recommend the following setup:
|
||||||
|
|
||||||
If a malicious person compromises a gateway's issuing account (cold wallet), that person could create an unlimited amount of new issuances, which makes it very difficult to redeem legitimately-held issuances fairly. In this case, the gateway must create a new issuing account, and all users with trust lines to the old gateway must create new trust lines to the new account. Thus, it's best to keep your issuing account as secure as possible.
|
* An **issuing account** (also known as a "cold wallet") with high value, used as rarely as possible.
|
||||||
|
* One or more **operational accounts** (also known as a "hot wallets") with low value, used frequently by automated processes.
|
||||||
|
* Optional **standby accounts** (also known as "warm wallets"), used infrequently by human operators.
|
||||||
|
|
||||||
The cold wallet is like a vault. It serves as the asset issuer, and should remain offline. The secret key that is used for this wallet is kept offline, accessible to only a few trusted operators. Periodically, a human operator creates and signs a transaction (preferably from an entirely offline machine) in order to refill the hot wallet's balance. Because the cold wallet is the account creating the issuances, customer accounts holding those issuances must trust the cold wallet.
|
For more information, see [Issuing and Operational Accounts](concept-issuing-and-operational-accounts.html)
|
||||||
|
|
||||||
A hot wallet is like a cash register. It makes payments to the gateway's users in Ripple by sending them issuances created by the cold wallet. The secret key for a hot wallet is, by necessity, stored on a server that is connected to the outside internet, usually in a configuration file on a public-facing server. Because it holds issuances created by the cold walet, each hot wallet needs a trust line to the cold wallet. Customers do not, and should not, trust hot wallet accounts.
|
|
||||||
|
|
||||||
(Unlike a cash register, the hot wallet does not have to handle incoming payments from users, because the cold wallet can receive and monitor payments without using its secret key. To make things simple for your users, we recommend treating incoming payments to the hot and cold wallets as the same.)
|
|
||||||
|
|
||||||
A gateway can use one or more "hot wallet" accounts, but each hot wallet has a limited balance of the gateway's issuances. If a hot wallet is compromised, the gateway only loses as much currency as that account holds. Customers do not need to change any configuration in order to receive funds from a new hot wallet. However, the gateway must monitor the hot wallet's balance so that it doesn't run out of funds during ordinary operation.
|
|
||||||
|
|
||||||
### Warm Wallets ###
|
|
||||||
|
|
||||||
Another optional step that a gateway can take to balance risk and convenience is to use "warm wallets" as an intermediate step between cold wallet and hot wallet. Frequently, the software that runs a gateway's daily operations uses a single hot wallet. The gateway can operate additional accounts as warm wallets, whose keys are entrusted to different trusted users and whose keys are also not stored for use by the gateway software.
|
|
||||||
|
|
||||||
When the hot wallet is running low on funds, the warm wallets can be used to refill it. When the warm wallets run low on funds, the cold wallet can issue more currency to a warm wallet in a single transaction, and the warm wallets can distribute that currency among themselves if necessary. This improves security of the cold wallet, since it makes as few transactions as possible, without leaving too much money in the control of a single automated hot wallet.
|
|
||||||
|
|
||||||
As with hot wallets, warm wallets must trust the cold wallet, and should not be trusted by users. All precautions that apply to hot wallets also apply to warm wallets.
|
|
||||||
|
|
||||||
### Funds Lifecycle ###
|
### Funds Lifecycle ###
|
||||||
|
|
||||||
@@ -195,7 +184,7 @@ Processing payments to and from Ripple naturally comes with some risks, so a gat
|
|||||||
- Before sending a payment into Ripple, double check the cost of the payment. A simple payment from your hot wallet to a customer should not cost more than the destination amount plus any [transfer fee](#transferrate) you have set.
|
- Before sending a payment into Ripple, double check the cost of the payment. A simple payment from your hot wallet to a customer should not cost more than the destination amount plus any [transfer fee](#transferrate) you have set.
|
||||||
- Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you, and it is also an important element of most anti-money-laundering regulations. This is especially important because the users sending money from Ripple could be different than the ones that initially received the money in Ripple.
|
- Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you, and it is also an important element of most anti-money-laundering regulations. This is especially important because the users sending money from Ripple could be different than the ones that initially received the money in Ripple.
|
||||||
- Follow the guidelines for [reliable transaction submission](#reliable-transaction-submission) when sending Ripple transactions.
|
- Follow the guidelines for [reliable transaction submission](#reliable-transaction-submission) when sending Ripple transactions.
|
||||||
- [Robustly monitor for incoming payments](#robustly-monitoring-for-payments), and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](transactions.html#partial-payments).
|
- [Robustly monitor for incoming payments](#robustly-monitoring-for-payments), and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](reference-transaction-format.html#partial-payments).
|
||||||
- Track your obligations and balances within the Ripple network, and compare with your assets off the network. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy.
|
- Track your obligations and balances within the Ripple network, and compare with your assets off the network. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy.
|
||||||
- Proactively avoid ambiguous situations. We recommend the following:
|
- Proactively avoid ambiguous situations. We recommend the following:
|
||||||
- Enable the [`DisallowXRP` flag](#disallowxrp) for the cold wallet account and all hot wallet accounts, so users do not accidentally send you XRP. (Private exchanges should *not* set this flag, since they trade XRP normally.)
|
- Enable the [`DisallowXRP` flag](#disallowxrp) for the cold wallet account and all hot wallet accounts, so users do not accidentally send you XRP. (Private exchanges should *not* set this flag, since they trade XRP normally.)
|
||||||
@@ -237,7 +226,7 @@ Ripple provides the ability to freeze assets issued by the gateway in Ripple as
|
|||||||
* Gateways can freeze all issuances created by their cold wallet, in case of a compromised gateway account or for migrating cold wallets.
|
* Gateways can freeze all issuances created by their cold wallet, in case of a compromised gateway account or for migrating cold wallets.
|
||||||
* Furthermore, gateways can permanently opt out of their ability to freeze issuances at all. This allows a gateway to assure its users that it will continue to provide "physical-money-like" services.
|
* Furthermore, gateways can permanently opt out of their ability to freeze issuances at all. This allows a gateway to assure its users that it will continue to provide "physical-money-like" services.
|
||||||
|
|
||||||
For more information, see the [Freeze article](freeze.html).
|
For more information, see the [Freeze article](concept-freeze.html).
|
||||||
|
|
||||||
|
|
||||||
## Authorized Accounts ##
|
## Authorized Accounts ##
|
||||||
@@ -283,15 +272,15 @@ Contact [partners@ripple.com](mailto:partners@ripple.com) to see how Ripple Labs
|
|||||||
|
|
||||||
There are several interfaces you can use to connect to Ripple, depending on your needs and your existing software:
|
There are several interfaces you can use to connect to Ripple, depending on your needs and your existing software:
|
||||||
|
|
||||||
* [`rippled`](rippled-apis.html) provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality.
|
* [`rippled`](reference-rippled.html) provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality.
|
||||||
* [RippleAPI](rippleapi.html) provides a simple API for JavaScript applications.
|
* [RippleAPI](reference-rippleapi.html) provides a simple API for JavaScript applications.
|
||||||
|
|
||||||
|
|
||||||
## Tool Security ##
|
## Tool Security ##
|
||||||
|
|
||||||
Any time you submit a Ripple transaction, it must be signed using your secret. However, having your secret means having full control over your account. Therefore, you should never transmit your secret to a server operated by someone else. Instead, use your own server or client application to sign the transactions before sending them out.
|
Any time you submit a Ripple transaction, it must be signed using your secret. However, having your secret means having full control over your account. Therefore, you should never transmit your secret to a server operated by someone else. Instead, use your own server or client application to sign the transactions before sending them out.
|
||||||
|
|
||||||
The examples in this document show API methods that include an account secret. This is only safe if you control `rippled` server yourself, *and* you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use [RippleAPI](rippleapi.html) to perform local signing before submitting your transactions to a third-party server.
|
The examples in this document show API methods that include an account secret. This is only safe if you control `rippled` server yourself, *and* you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use [RippleAPI](reference-rippleapi.html) to perform local signing before submitting your transactions to a third-party server.
|
||||||
|
|
||||||
|
|
||||||
## DefaultRipple ##
|
## DefaultRipple ##
|
||||||
@@ -300,7 +289,7 @@ The DefaultRipple flag controls whether the balances held in an account's trust
|
|||||||
|
|
||||||
Before asking users to trust its issuing account, a gateway should enable the DefaultRipple flag on that account. Otherwise, the gateway must individually disable the NoRipple flag for each trust line that other accounts extend to it.
|
Before asking users to trust its issuing account, a gateway should enable the DefaultRipple flag on that account. Otherwise, the gateway must individually disable the NoRipple flag for each trust line that other accounts extend to it.
|
||||||
|
|
||||||
The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) to send an AccountSet transaction to enable the DefaultRipple flag:
|
The following is an example of using a locally-hosted `rippled`'s [`submit` command](reference-rippled.html#submit) to send an AccountSet transaction to enable the DefaultRipple flag:
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -350,7 +339,7 @@ Response:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
To confirm that an account has DefaultRipple enabled, look up the account using the [account_info command](rippled-apis.html#account-info), specifying a validated ledger version. Use [a bitwise-AND operator](https://en.wikipedia.org/wiki/Bitwise_operation#AND) to compare the `Flags` field with 0x00800000 (the [ledger flag lsfDefaultRipple](ripple-ledger.html#accountroot-flags)). If the result of the bitwise-AND operation is nonzero, then the account has DefaultRipple enabled.
|
To confirm that an account has DefaultRipple enabled, look up the account using the [account_info command](reference-rippled.html#account-info), specifying a validated ledger version. Use [a bitwise-AND operator](https://en.wikipedia.org/wiki/Bitwise_operation#AND) to compare the `Flags` field with 0x00800000 (the [ledger flag lsfDefaultRipple](reference-ledger-format.html#accountroot-flags)). If the result of the bitwise-AND operation is nonzero, then the account has DefaultRipple enabled.
|
||||||
|
|
||||||
|
|
||||||
## Generating Source and Destination Tags ##
|
## Generating Source and Destination Tags ##
|
||||||
@@ -372,7 +361,7 @@ The DisallowXRP setting (`disallowIncomingXRP` in RippleAPI) is designed to disc
|
|||||||
|
|
||||||
An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP.
|
An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP.
|
||||||
|
|
||||||
The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) to send an AccountSet transaction to enable the DisallowXRP flag:
|
The following is an example of using a locally-hosted `rippled`'s [`submit` command](reference-rippled.html#submit) to send an AccountSet transaction to enable the DisallowXRP flag:
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -429,7 +418,7 @@ The `RequireDest` setting (`requireDestinationTag` in RippleAPI) is designed to
|
|||||||
|
|
||||||
We recommend enabling the `RequireDest` flag on all gateway hot and cold wallets.
|
We recommend enabling the `RequireDest` flag on all gateway hot and cold wallets.
|
||||||
|
|
||||||
The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) to send an AccountSet transaction to enable the `RequireDest` flag:
|
The following is an example of using a locally-hosted `rippled`'s [`submit` command](reference-rippled.html#submit) to send an AccountSet transaction to enable the `RequireDest` flag:
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -493,7 +482,7 @@ You can only enable `RequireAuth` if the account owns no trust lines and no offe
|
|||||||
|
|
||||||
### Enabling RequireAuth ###
|
### Enabling RequireAuth ###
|
||||||
|
|
||||||
The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) to send an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the account is used as a hot wallet or cold wallet.)
|
The following is an example of using a locally-hosted `rippled`'s [`submit` command](reference-rippled.html#submit) to send an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the account is used as a hot wallet or cold wallet.)
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -522,9 +511,9 @@ _(**Reminder:** Don't send your secret to a server you do not control.)_
|
|||||||
|
|
||||||
If you are using the [Authorized Accounts](#authorized-accounts) feature, then after enabling the `RequireAuth` setting for your cold wallet, users cannot hold balances issued by your cold wallet unless you first authorize their trust lines.
|
If you are using the [Authorized Accounts](#authorized-accounts) feature, then after enabling the `RequireAuth` setting for your cold wallet, users cannot hold balances issued by your cold wallet unless you first authorize their trust lines.
|
||||||
|
|
||||||
To authorize a trust line, submit a TrustSet transaction from your cold wallet, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [tfSetfAuth](transactions.html#trustset-flags) flag for the transaction.
|
To authorize a trust line, submit a TrustSet transaction from your cold wallet, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [tfSetfAuth](reference-transaction-format.html#trustset-flags) flag for the transaction.
|
||||||
|
|
||||||
The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) to send a TrustSet transaction authorizing the (customer) account rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the (cold wallet) account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:
|
The following is an example of using a locally-hosted `rippled`'s [`submit` command](reference-rippled.html#submit) to send a TrustSet transaction authorizing the (customer) account rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the (cold wallet) account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -569,7 +558,7 @@ To make things simpler for your users, we recommend monitoring for incoming paym
|
|||||||
|
|
||||||
As an added precaution, we recommend comparing the balances of your Ripple cold wallet account with the Ripple-backing funds in your internal accounting system each time there is a new Ripple ledger. The cold wallet shows all outstanding issuances as negative balances, which should match the positive assets you have allocated to Ripple outside the network. If the two do not match up, then you should suspend processing payments in and out of Ripple until you have resolved the discrepancy.
|
As an added precaution, we recommend comparing the balances of your Ripple cold wallet account with the Ripple-backing funds in your internal accounting system each time there is a new Ripple ledger. The cold wallet shows all outstanding issuances as negative balances, which should match the positive assets you have allocated to Ripple outside the network. If the two do not match up, then you should suspend processing payments in and out of Ripple until you have resolved the discrepancy.
|
||||||
|
|
||||||
* Use [`rippled`'s `account_lines` command](rippled-apis.html#account-lines) or [RippleAPI's `getTrustlines` method](rippleapi.html#gettrustlines) to check your balances.
|
* Use [`rippled`'s `account_lines` command](reference-rippled.html#account-lines) or [RippleAPI's `getTrustlines` method](reference-rippleapi.html#gettrustlines) to check your balances.
|
||||||
* If you have a [TransferRate](#transferrate) set, then your obligations within the Ripple network decrease slightly whenever other users transfer your issuances among themselves.
|
* If you have a [TransferRate](#transferrate) set, then your obligations within the Ripple network decrease slightly whenever other users transfer your issuances among themselves.
|
||||||
|
|
||||||
|
|
||||||
@@ -577,7 +566,7 @@ As an added precaution, we recommend comparing the balances of your Ripple cold
|
|||||||
|
|
||||||
The *TransferRate* setting (`transferRate` in RippleAPI) defines a fee to charge for transferring issuances from one Ripple account to another. See [Transfer Fees](https://ripple.com/knowledge_center/transfer-fees/) in the Knowledge Center for more information.
|
The *TransferRate* setting (`transferRate` in RippleAPI) defines a fee to charge for transferring issuances from one Ripple account to another. See [Transfer Fees](https://ripple.com/knowledge_center/transfer-fees/) in the Knowledge Center for more information.
|
||||||
|
|
||||||
The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) to send an AccountSet transaction for cold wallet account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW, setting the TransferRate to charge a fee of 0.5%.
|
The following is an example of using a locally-hosted `rippled`'s [`submit` command](reference-rippled.html#submit) to send an AccountSet transaction for cold wallet account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW, setting the TransferRate to charge a fee of 0.5%.
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -629,7 +618,7 @@ Response:
|
|||||||
|
|
||||||
All Ripple Accounts, including the hot wallet, are subject to the TransferRate. If you set a nonzero TransferRate, then you must send extra (to pay the TransferRate) when making payments to users from your hot wallet. In other words, your hot wallet must pay back a little of the money your cold wallet issued it each time you make a payment.
|
All Ripple Accounts, including the hot wallet, are subject to the TransferRate. If you set a nonzero TransferRate, then you must send extra (to pay the TransferRate) when making payments to users from your hot wallet. In other words, your hot wallet must pay back a little of the money your cold wallet issued it each time you make a payment.
|
||||||
|
|
||||||
* In `rippled`'s APIs, you can accomplish this by setting the [`SendMax` transaction parameter](transactions.html#payment) higher than the destination `Amount` parameter.
|
* In `rippled`'s APIs, you can accomplish this by setting the [`SendMax` transaction parameter](reference-transaction-format.html#payment) higher than the destination `Amount` parameter.
|
||||||
* In RippleAPI, you can accomplish this by setting the `source.maxAmount` parameter higher than the `destination.amount` parameter; or, by setting the `source.amount` parameter higher than the `destination.minAmount` parameter.
|
* In RippleAPI, you can accomplish this by setting the `source.maxAmount` parameter higher than the `destination.amount` parameter; or, by setting the `source.amount` parameter higher than the `destination.minAmount` parameter.
|
||||||
|
|
||||||
**Note:** The TransferRate does not apply when sending issuances back to the account that created them. The account that created issuances must always accept them at face value on Ripple. This means that users don't have to pay the TransferRate if they send payments to the cold wallet directly, but they do when sending to the hot wallet. (For example, if ACME sets a TransferRate of 1%, a Ripple payment to deliver 5 EUR.ACME from a user account to ACME's cold wallet would still only cost 5 EUR.ACME. However, the user would need to send 5.05 EUR.ACME in order to deliver 5 EUR.ACME to the hot wallet.) If you accept payments out of Ripple through both accounts, you may want to adjust the amount you credit users in your external system when customers send payments through the hot wallet, to compensate for the TransferRate the customer pays.
|
**Note:** The TransferRate does not apply when sending issuances back to the account that created them. The account that created issuances must always accept them at face value on Ripple. This means that users don't have to pay the TransferRate if they send payments to the cold wallet directly, but they do when sending to the hot wallet. (For example, if ACME sets a TransferRate of 1%, a Ripple payment to deliver 5 EUR.ACME from a user account to ACME's cold wallet would still only cost 5 EUR.ACME. However, the user would need to send 5.05 EUR.ACME in order to deliver 5 EUR.ACME to the hot wallet.) If you accept payments out of Ripple through both accounts, you may want to adjust the amount you credit users in your external system when customers send payments through the hot wallet, to compensate for the TransferRate the customer pays.
|
||||||
@@ -639,9 +628,9 @@ All Ripple Accounts, including the hot wallet, are subject to the TransferRate.
|
|||||||
|
|
||||||
When you build an automated system to send payments into Ripple for your users, you must ensure that it constructs payments carefully. Malicious users are constantly trying to find ways to trick a system into paying them more money than it should.
|
When you build an automated system to send payments into Ripple for your users, you must ensure that it constructs payments carefully. Malicious users are constantly trying to find ways to trick a system into paying them more money than it should.
|
||||||
|
|
||||||
One common pitfall is performing pathfinding before sending sending a payment to users in Ripple. If you specify the issuers correctly, the [default paths](paths.html#default-paths) are sufficient to deliver the currency as intended.
|
One common pitfall is performing pathfinding before sending sending a payment to users in Ripple. If you specify the issuers correctly, the [default paths](concept-paths.html#default-paths) are sufficient to deliver the currency as intended.
|
||||||
|
|
||||||
The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) to send a payment from the hot wallet rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to the user account raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n, sending and delivering funds issued by the cold wallet rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW.
|
The following is an example of using a locally-hosted `rippled`'s [`submit` command](reference-rippled.html#submit) to send a payment from the hot wallet rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to the user account raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n, sending and delivering funds issued by the cold wallet rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW.
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -707,9 +696,9 @@ Response:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
In particular, note the following features of the [Payment Transaction](transactions.html#payment):
|
In particular, note the following features of the [Payment Transaction](reference-transaction-format.html#payment):
|
||||||
|
|
||||||
- No `Paths` field. The payment will only succeed if it can use a [default path](paths.html#default-paths), which is preferable. Using less direct paths can become much more expensive.
|
- No `Paths` field. The payment will only succeed if it can use a [default path](concept-paths.html#default-paths), which is preferable. Using less direct paths can become much more expensive.
|
||||||
- The `issuer` of both the `SendMax` and the `Amount` is the cold wallet. This ensures that the transaction sends and delivers issuances from the cold wallet account, and not from some other gateway.
|
- The `issuer` of both the `SendMax` and the `Amount` is the cold wallet. This ensures that the transaction sends and delivers issuances from the cold wallet account, and not from some other gateway.
|
||||||
- The `value` of the `SendMax` amount is slightly higher than the destination `Amount`, in order to compensate for the [transfer fee](#transferrate). In this case, the transfer fee is 0.5%, so the `SendMax` amount is exactly 1.005 times the destination `Amount`.
|
- The `value` of the `SendMax` amount is slightly higher than the destination `Amount`, in order to compensate for the [transfer fee](#transferrate). In this case, the transfer fee is 0.5%, so the `SendMax` amount is exactly 1.005 times the destination `Amount`.
|
||||||
|
|
||||||
@@ -722,8 +711,8 @@ The first requirement to bouncing payments is [robustly monitoring for incoming
|
|||||||
|
|
||||||
Second, you should send bounced payments as Partial Payments. Since other Ripple users can manipulate the cost of pathways between your accounts, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the Ripple Consensus Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from an automated hot wallet or a human-operated warm wallet.
|
Second, you should send bounced payments as Partial Payments. Since other Ripple users can manipulate the cost of pathways between your accounts, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the Ripple Consensus Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from an automated hot wallet or a human-operated warm wallet.
|
||||||
|
|
||||||
* To send a Partial Payment using `rippled`, enable the [tfPartialPayment flag](transactions.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field.
|
* To send a Partial Payment using `rippled`, enable the [tfPartialPayment flag](reference-transaction-format.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field.
|
||||||
* To send a Partial Payment using RippleAPI, set the `allowPartialPayment` field of the [Payment object](rippleapi.html#payment) to `true`. Set the `source.maxAmount` and `destination.amount` both equal to the amount you received.
|
* To send a Partial Payment using RippleAPI, set the `allowPartialPayment` field of the [Payment object](reference-rippleapi.html#payment) to `true`. Set the `source.maxAmount` and `destination.amount` both equal to the amount you received.
|
||||||
|
|
||||||
It is conventional that you take the `SourceTag` field from the incoming payment (`source.tag` in RippleAPI) and use that value as the `DestinationTag` field (`destination.tag` in RippleAPI) for the return payment.
|
It is conventional that you take the `SourceTag` field from the incoming payment (`source.tag` in RippleAPI) and use that value as the `DestinationTag` field (`destination.tag` in RippleAPI) for the return payment.
|
||||||
|
|
||||||
@@ -743,7 +732,7 @@ In order to achieve this, there are several steps you can take when submitting t
|
|||||||
* Use the `LastLedgerSequence` parameter. (RippleAPI does this by default.)
|
* Use the `LastLedgerSequence` parameter. (RippleAPI does this by default.)
|
||||||
* Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's `LastLedgerSequence` parameter.
|
* Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's `LastLedgerSequence` parameter.
|
||||||
|
|
||||||
For additional information, consult the [Reliable Transaction Submission](reliable_tx.html) guide.
|
For additional information, consult the [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html) guide.
|
||||||
|
|
||||||
|
|
||||||
## ripple.txt ##
|
## ripple.txt ##
|
||||||
@@ -19,7 +19,7 @@ These types of errors can potentially lead to serious problems. For example, an
|
|||||||
|
|
||||||
The Ripple protocol provides a ledger shared across all nodes in the network. Through a [process of consensus and validation](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/), the network agrees on order in which transactions are applied to (or omitted from) the ledger.
|
The Ripple protocol provides a ledger shared across all nodes in the network. Through a [process of consensus and validation](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/), the network agrees on order in which transactions are applied to (or omitted from) the ledger.
|
||||||
|
|
||||||
Well-formed transactions submitted to trusted Ripple network nodes are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global [transaction cost](tx-cost.html) increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction will not be included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction may become viable again. If the transaction does not include expiration, there is no limit to how much later this can occur.
|
Well-formed transactions submitted to trusted Ripple network nodes are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global [transaction cost](concept-transaction-cost.html) increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction will not be included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction may become viable again. If the transaction does not include expiration, there is no limit to how much later this can occur.
|
||||||
|
|
||||||
Applications face additional challenges, in the event of power or network loss, ascertaining the status of submitted transactions. Applications must take care both to properly submit a transaction and later to properly ascertain its authoritative results.
|
Applications face additional challenges, in the event of power or network loss, ascertaining the status of submitted transactions. Applications must take care both to properly submit a transaction and later to properly ascertain its authoritative results.
|
||||||
|
|
||||||
@@ -28,7 +28,7 @@ Applications face additional challenges, in the event of power or network loss,
|
|||||||
|
|
||||||
### Transaction Timeline
|
### Transaction Timeline
|
||||||
|
|
||||||
Ripple provides several APIs for submitting transactions, including [`rippled`](rippled-apis.html), and [RippleAPI](rippleapi.html). Regardless of the API used, the transaction is applied to the ledger as follows.
|
Ripple provides several APIs for submitting transactions, including [`rippled`](reference-rippled.html), and [RippleAPI](reference-rippleapi.html). Regardless of the API used, the transaction is applied to the ledger as follows.
|
||||||
|
|
||||||
1. An account owner creates and signs a transaction.
|
1. An account owner creates and signs a transaction.
|
||||||
2. The owner submits the transaction to the network as a candidate transaction.
|
2. The owner submits the transaction to the network as a candidate transaction.
|
||||||
@@ -54,11 +54,11 @@ Each validated ledger has a canonical order in which transactions apply. This or
|
|||||||
|
|
||||||
### LastLedgerSequence
|
### LastLedgerSequence
|
||||||
|
|
||||||
[`LastLedgerSequence`](transactions.html#lastledgersequence) is an optional parameter of all transactions. This instructs the Ripple Consensus Ledger that a transaction must be validated on or before a specific ledger instance. The Ripple Consensus Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's `LastLedgerSequence` parameter.
|
[`LastLedgerSequence`](reference-transaction-format.html#lastledgersequence) is an optional parameter of all transactions. This instructs the Ripple Consensus Ledger that a transaction must be validated on or before a specific ledger instance. The Ripple Consensus Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's `LastLedgerSequence` parameter.
|
||||||
|
|
||||||
Use the `LastLedgerSequence` parameter to prevent undesirable cases where a transaction is not promptly validated yet could become viable at some point in the future. Gateways and other back-end applications should specify the `LastLedgerSequence` parameter on every transaction. Automated processes should use a value of 4 greater than the sequence number of the last validated ledger[1] to ensure that a transaction is validated or rejected in a predictable and timely fashion.
|
Use the `LastLedgerSequence` parameter to prevent undesirable cases where a transaction is not promptly validated yet could become viable at some point in the future. Gateways and other back-end applications should specify the `LastLedgerSequence` parameter on every transaction. Automated processes should use a value of 4 greater than the sequence number of the last validated ledger[1] to ensure that a transaction is validated or rejected in a predictable and timely fashion.
|
||||||
|
|
||||||
Applications using rippled APIs should explicitly specify a `LastLedgerSequence` when submitting transactions. RippleAPI uses the `maxLedgerVersion` field of [Transaction Instructions](rippleapi.html#transaction-instructions) to specify the `LastLedgerSequence`. RippleAPI automatically provides an appropriate value by default. You can specify `maxLedgerVersion` as `null` to intentionally omit `LastLedgerSequence`, in case you want a transaction that can be executed after an unlimited amount of time.
|
Applications using rippled APIs should explicitly specify a `LastLedgerSequence` when submitting transactions. RippleAPI uses the `maxLedgerVersion` field of [Transaction Instructions](reference-rippleapi.html#transaction-instructions) to specify the `LastLedgerSequence`. RippleAPI automatically provides an appropriate value by default. You can specify `maxLedgerVersion` as `null` to intentionally omit `LastLedgerSequence`, in case you want a transaction that can be executed after an unlimited amount of time.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -138,8 +138,8 @@ In order to implement the transaction submission and verification best practices
|
|||||||
|
|
||||||
An application's means of performing these actions depends on the API the application uses. An application may use any of the following interfaces:
|
An application's means of performing these actions depends on the API the application uses. An application may use any of the following interfaces:
|
||||||
|
|
||||||
1. [`rippled`'s internal APIs](rippled-apis.html)
|
1. [`rippled`'s internal APIs](reference-rippled.html)
|
||||||
2. [RippleAPI](rippleapi.html)
|
2. [RippleAPI](reference-rippleapi.html)
|
||||||
3. Any number of other software APIs layered on top of `rippled`
|
3. Any number of other software APIs layered on top of `rippled`
|
||||||
|
|
||||||
|
|
||||||
@@ -147,7 +147,7 @@ An application's means of performing these actions depends on the API the applic
|
|||||||
|
|
||||||
#### Determine the Account Sequence
|
#### Determine the Account Sequence
|
||||||
|
|
||||||
`rippled` provides the [account_info](rippled-apis.html#account-info) method to learn an account's sequence number in the last validated ledger.
|
`rippled` provides the [account_info](reference-rippled.html#account-info) method to learn an account's sequence number in the last validated ledger.
|
||||||
|
|
||||||
JSON-RPC Request:
|
JSON-RPC Request:
|
||||||
|
|
||||||
@@ -193,7 +193,7 @@ If an application were to submit three transactions signed by this account, they
|
|||||||
|
|
||||||
#### Determine the Last Validated Ledger
|
#### Determine the Last Validated Ledger
|
||||||
|
|
||||||
`rippled` provides the [server_state](rippled-apis.html#server-state) command which returns the ledger sequence number of the last validated ledger.
|
`rippled` provides the [server_state](reference-rippled.html#server-state) command which returns the ledger sequence number of the last validated ledger.
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -244,7 +244,7 @@ In this example the last validated ledger sequence number is 10268596 (found und
|
|||||||
|
|
||||||
#### Construct the Transaction
|
#### Construct the Transaction
|
||||||
|
|
||||||
`rippled` provides the [sign method](rippled-apis.html#sign) to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted `rippled` instances. This example issues 10 FOO (a made-up currency) from a gateway to another Ripple account.
|
`rippled` provides the [sign method](reference-rippled.html#sign) to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted `rippled` instances. This example issues 10 FOO (a made-up currency) from a gateway to another Ripple account.
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -311,7 +311,7 @@ Applications should persist the transaction's hash before submitting. The resul
|
|||||||
|
|
||||||
#### Submit the transaction
|
#### Submit the transaction
|
||||||
|
|
||||||
`rippled` provides the [`submit` method](rippled-apis.html#submit), allowing us to submit the signed transaction. This uses the `tx_blob` parameter that was returned by the `sign` method.
|
`rippled` provides the [`submit` method](reference-rippled.html#submit), allowing us to submit the signed transaction. This uses the `tx_blob` parameter that was returned by the `sign` method.
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -362,7 +362,7 @@ This a **preliminary** result. Final results are only available from validated
|
|||||||
|
|
||||||
#### Verify the Transaction
|
#### Verify the Transaction
|
||||||
|
|
||||||
The transaction hash, generated when the transaction was signed, is passed to the [`tx` method](rippled-apis.html#tx) to retrieve the result of a transaction.
|
The transaction hash, generated when the transaction was signed, is passed to the [`tx` method](reference-rippled.html#tx) to retrieve the result of a transaction.
|
||||||
|
|
||||||
Request:
|
Request:
|
||||||
|
|
||||||
@@ -419,7 +419,7 @@ If the response does not include `"validated": true`, the result is provisional
|
|||||||
|
|
||||||
#### Verify Missing Transaction
|
#### Verify Missing Transaction
|
||||||
|
|
||||||
Applications must handle cases where a call to the [`tx` method](rippled-apis.html#tx) returns a `txnNotFound` error.
|
Applications must handle cases where a call to the [`tx` method](reference-rippled.html#tx) returns a `txnNotFound` error.
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
@@ -439,7 +439,7 @@ Applications must handle cases where a call to the [`tx` method](rippled-apis.ht
|
|||||||
|
|
||||||
The `txnNotFound` result code occurs in cases where the transaction has failed to be included in any ledger. However, it could also occur when a rippled instance does not have a complete ledger history, or if the transaction has not yet propagated to the rippled instance. Applications should make further queries to determine how to react.
|
The `txnNotFound` result code occurs in cases where the transaction has failed to be included in any ledger. However, it could also occur when a rippled instance does not have a complete ledger history, or if the transaction has not yet propagated to the rippled instance. Applications should make further queries to determine how to react.
|
||||||
|
|
||||||
The [`server_state` method](rippled-apis.html#server-state) (used earlier to determine the last validated ledger) indicates how complete the ledger history is, under `result.state.complete_ledgers`.
|
The [`server_state` method](reference-rippled.html#server-state) (used earlier to determine the last validated ledger) indicates how complete the ledger history is, under `result.state.complete_ledgers`.
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
@@ -481,8 +481,8 @@ Finally the server state might indicate one or more gaps in the transaction hist
|
|||||||
|
|
||||||
## Additional Resources
|
## Additional Resources
|
||||||
|
|
||||||
- [Transaction Format](transactions.html)
|
- [Transaction Format](reference-transaction-format.html)
|
||||||
- [Transaction Cost](tx-cost.html)
|
- [Transaction Cost](concept-transaction-cost.html)
|
||||||
- Documentation of [`LastLedgerSequence`](transactions.html#lastledgersequence)
|
- Documentation of [`LastLedgerSequence`](reference-transaction-format.html#lastledgersequence)
|
||||||
- [Overview of Ripple Ledger Consensus Process](http://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/)
|
- [Overview of Ripple Ledger Consensus Process](http://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/)
|
||||||
- [Reaching Consensus in Ripple](https://ripple.com/knowledge_center/reaching-consensus-in-ripple/)
|
- [Reaching Consensus in Ripple](https://ripple.com/knowledge_center/reaching-consensus-in-ripple/)
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# RippleAPI Beginners Guide #
|
# RippleAPI Beginners Guide #
|
||||||
|
|
||||||
This tutorial guides you through the basics of building a simple Ripple-connected application using [Node.js](http://nodejs.org/) and [RippleAPI](rippleapi.html), a simple JavaScript API for accessing the Ripple Consensus Ledger.
|
This tutorial guides you through the basics of building a simple Ripple-connected application using [Node.js](http://nodejs.org/) and [RippleAPI](reference-rippleapi.html), a simple JavaScript API for accessing the Ripple Consensus Ledger.
|
||||||
|
|
||||||
# Environment Setup #
|
# Environment Setup #
|
||||||
|
|
||||||
@@ -141,12 +141,12 @@ const api = new RippleAPI({
|
|||||||
|
|
||||||
This section creates a new instance of the RippleAPI class, assigning it to the variable `api`. (The [`const` keyword](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) means you can't reassign the value `api` to some other value. The internal state of the object can still change, though.)
|
This section creates a new instance of the RippleAPI class, assigning it to the variable `api`. (The [`const` keyword](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) means you can't reassign the value `api` to some other value. The internal state of the object can still change, though.)
|
||||||
|
|
||||||
The one argument to the constructor is an options object, which has [a variety of options](rippleapi.html#parameters). The `server` parameter tells it where it should connect to a `rippled` server.
|
The one argument to the constructor is an options object, which has [a variety of options](reference-rippleapi.html#parameters). The `server` parameter tells it where it should connect to a `rippled` server.
|
||||||
|
|
||||||
* The example `server` setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) operates.
|
* The example `server` setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) operates.
|
||||||
* If you don't include the `server` option, RippleAPI runs in [offline mode](rippleapi.html#offline-functionality) instead, which only provides methods that don't need network connectivity.
|
* If you don't include the `server` option, RippleAPI runs in [offline mode](reference-rippleapi.html#offline-functionality) instead, which only provides methods that don't need network connectivity.
|
||||||
* You can specify a [Ripple Test Net](https://ripple.com/build/ripple-test-net/) server instead to connect to the parallel-world Test Network instead of the production Ripple Consensus Ledger.
|
* You can specify a [Ripple Test Net](https://ripple.com/build/ripple-test-net/) server instead to connect to the parallel-world Test Network instead of the production Ripple Consensus Ledger.
|
||||||
* If you [run your own `rippled`](rippled-setup.html), you can instruct it to connect to your local server. For example, you might say `server: 'ws://localhost:5005'` instead.
|
* If you [run your own `rippled`](tutorial-rippled-setup.html), you can instruct it to connect to your local server. For example, you might say `server: 'ws://localhost:5005'` instead.
|
||||||
|
|
||||||
### Connecting and Promises ###
|
### Connecting and Promises ###
|
||||||
|
|
||||||
@@ -154,7 +154,7 @@ The one argument to the constructor is an options object, which has [a variety o
|
|||||||
api.connect().then(() => {
|
api.connect().then(() => {
|
||||||
```
|
```
|
||||||
|
|
||||||
The [connect() method](rippleapi.html#connect) is one of many RippleAPI methods that returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), which is a special kind of JavaScript object. A Promise is designed to perform some asynchronous operation, like querying a the Ripple Consensus Ledger.
|
The [connect() method](reference-rippleapi.html#connect) is one of many RippleAPI methods that returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), which is a special kind of JavaScript object. A Promise is designed to perform some asynchronous operation, like querying a the Ripple Consensus Ledger.
|
||||||
|
|
||||||
When you get a Promise back from some expression (like `api.connect()`), you call the Promise's `then` method and pass in a callback function. Passing a function as an argument is conventional in JavaScript, taking advantage of how JavaScript functions are [first-class objects](https://en.wikipedia.org/wiki/First-class_function).
|
When you get a Promise back from some expression (like `api.connect()`), you call the Promise's `then` method and pass in a callback function. Passing a function as an argument is conventional in JavaScript, taking advantage of how JavaScript functions are [first-class objects](https://en.wikipedia.org/wiki/First-class_function).
|
||||||
|
|
||||||
@@ -184,7 +184,7 @@ The example code looks up a Ripple account (belonging to [this writer](https://g
|
|||||||
|
|
||||||
The `console.log()` function is a built-in tool in both Node.js and web browsers, which writes out to the console; this example includes lots of console output to make it easier to understand what the code is doing.
|
The `console.log()` function is a built-in tool in both Node.js and web browsers, which writes out to the console; this example includes lots of console output to make it easier to understand what the code is doing.
|
||||||
|
|
||||||
Keep in mind that the example code starts in the middle of a callback function (called when RippleAPI finishes connecting). That function calls RippleAPI's [`getAccountInfo`](rippleapi.html#getaccountinfo) method, and returns the results.
|
Keep in mind that the example code starts in the middle of a callback function (called when RippleAPI finishes connecting). That function calls RippleAPI's [`getAccountInfo`](reference-rippleapi.html#getaccountinfo) method, and returns the results.
|
||||||
|
|
||||||
The results of that API method are another Promise, so the line `}).then( info => {` passes in another anonymous callback function to run when the second Promise's asynchronous work is done. Unlike the previous case, this callback function takes one argument, called `info`, which holds the -- actual -- return value from the `getAccountInfo` API method. The rest of this callback function just outputs that return value to the console.
|
The results of that API method are another Promise, so the line `}).then( info => {` passes in another anonymous callback function to run when the second Promise's asynchronous work is done. Unlike the previous case, this callback function takes one argument, called `info`, which holds the -- actual -- return value from the `getAccountInfo` API method. The rest of this callback function just outputs that return value to the console.
|
||||||
|
|
||||||
@@ -198,13 +198,13 @@ The results of that API method are another Promise, so the line `}).then( info =
|
|||||||
}).catch(console.error);
|
}).catch(console.error);
|
||||||
```
|
```
|
||||||
|
|
||||||
The remainder of the sample code is mostly more [boilerplate code](rippleapi.html#boilerplate). The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the Ripple Consensus Ledger, and has yet another callback which writes to the console when it finishes.
|
The remainder of the sample code is mostly more [boilerplate code](reference-rippleapi.html#boilerplate). The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the Ripple Consensus Ledger, and has yet another callback which writes to the console when it finishes.
|
||||||
|
|
||||||
Finally, we get to the `catch` method of this entire long Promise chain. If any of the Promises or their callback functions encounters an error, the callback provided here will run. One thing worth noting: instead of defining a new anonymous callback function here, we can just pass in the standard `console.error` function, which writes whatever arguments it gets out to the console. If you so desired, you could define a smarter callback function here which might intelligently catch certain error types.
|
Finally, we get to the `catch` method of this entire long Promise chain. If any of the Promises or their callback functions encounters an error, the callback provided here will run. One thing worth noting: instead of defining a new anonymous callback function here, we can just pass in the standard `console.error` function, which writes whatever arguments it gets out to the console. If you so desired, you could define a smarter callback function here which might intelligently catch certain error types.
|
||||||
|
|
||||||
# Waiting for Validation #
|
# Waiting for Validation #
|
||||||
|
|
||||||
One of the biggest challenges in using the Ripple Consensus Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you [follow the best practices](reliable_tx.html) you still have to wait for the [consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction:
|
One of the biggest challenges in using the Ripple Consensus Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you [follow the best practices](tutorial-reliable-transaction-submission.html) you still have to wait for the [consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction:
|
||||||
|
|
||||||
```
|
```
|
||||||
{% include 'code_samples/rippleapi_quickstart/submit-and-verify.js' %}
|
{% include 'code_samples/rippleapi_quickstart/submit-and-verify.js' %}
|
||||||
@@ -214,9 +214,9 @@ This code creates and submits an order transaction, although the same principles
|
|||||||
|
|
||||||
In rare cases (particularly with a large delay or a loss of power), the `rippled` server may be missing a ledger version between when you submitted the transaction and when you determined that the network has passed the `maxLedgerVersion`. In this case, you cannot be definitively sure whether the transaction has failed, or has been included in one of the missing ledger versions. RippleAPI returns `MissingLedgerHistoryError` in this case.
|
In rare cases (particularly with a large delay or a loss of power), the `rippled` server may be missing a ledger version between when you submitted the transaction and when you determined that the network has passed the `maxLedgerVersion`. In this case, you cannot be definitively sure whether the transaction has failed, or has been included in one of the missing ledger versions. RippleAPI returns `MissingLedgerHistoryError` in this case.
|
||||||
|
|
||||||
If you are the administrator of the `rippled` server, you can [manually request the missing ledger(s)](rippled-apis.html#ledger-request). Otherwise, you can try checking the ledger history using a different server. (Ripple runs a public full-history server at `s2.ripple.com` for this purpose.)
|
If you are the administrator of the `rippled` server, you can [manually request the missing ledger(s)](reference-rippled.html#ledger-request). Otherwise, you can try checking the ledger history using a different server. (Ripple runs a public full-history server at `s2.ripple.com` for this purpose.)
|
||||||
|
|
||||||
See [Reliable Transaction Submission](reliable_tx.html) for a more thorough explanation.
|
See [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html) for a more thorough explanation.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# Operating rippled Servers #
|
# Operating rippled Servers #
|
||||||
|
|
||||||
The core server of the Ripple peer-to-peer network is [`rippled`](rippled-apis.html). Anyone can run their own `rippled` server that follows the network and keeps a complete copy of the Ripple ledger. You can even have your server perform validations and participate in the consensus process.
|
The core server of the Ripple peer-to-peer network is [`rippled`](reference-rippled.html). Anyone can run their own `rippled` server that follows the network and keeps a complete copy of the Ripple ledger. You can even have your server perform validations and participate in the consensus process.
|
||||||
|
|
||||||
This page contains instructions for:
|
This page contains instructions for:
|
||||||
|
|
||||||
@@ -16,7 +16,7 @@ The `rippled` server software can run in several modes depending on its configur
|
|||||||
* Validating server, or _validator_ for short - participates in consensus.
|
* Validating server, or _validator_ for short - participates in consensus.
|
||||||
* `rippled` server in stand-alone mode - for basic testing. Does not communicate to other `rippled` servers.
|
* `rippled` server in stand-alone mode - for basic testing. Does not communicate to other `rippled` servers.
|
||||||
|
|
||||||
You can also run the `rippled` executable as a client application for accessing [`rippled` APIs](rippled-apis.html) locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.)
|
You can also run the `rippled` executable as a client application for accessing [`rippled` APIs](reference-rippled.html) locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.)
|
||||||
|
|
||||||
|
|
||||||
## Reasons to Run a Stock Server ##
|
## Reasons to Run a Stock Server ##
|
||||||
@@ -101,7 +101,7 @@ This section assumes that you are using CentOS 7 or Red Hat Enterprise Linux 7.
|
|||||||
|
|
||||||
It can take several minutes for `rippled` to sync with the rest of the network, during which time it outputs warnings about missing ledgers. After that, you have a fully functional stock `rippled` server that you can use for local signing and API access to the Ripple peer-to-peer network.
|
It can take several minutes for `rippled` to sync with the rest of the network, during which time it outputs warnings about missing ledgers. After that, you have a fully functional stock `rippled` server that you can use for local signing and API access to the Ripple peer-to-peer network.
|
||||||
|
|
||||||
[rippled commands](https://ripple.com/build/rippled-apis/#list-of-public-commands) can be run with:
|
[rippled commands](reference-rippled.html#list-of-public-commands) can be run with:
|
||||||
|
|
||||||
$ /opt/ripple/bin/rippled --conf /opt/ripple/etc/rippled.cfg <command>
|
$ /opt/ripple/bin/rippled --conf /opt/ripple/etc/rippled.cfg <command>
|
||||||
|
|
||||||
@@ -212,7 +212,7 @@ The steps below describe how to set the domain field of a validator's Ripple acc
|
|||||||
2. Fund the account by sending it at least 25 XRP.
|
2. Fund the account by sending it at least 25 XRP.
|
||||||
* See [How to Get XRP](https://ripple.com/knowledge_center/how-to-get-xrp/)
|
* See [How to Get XRP](https://ripple.com/knowledge_center/how-to-get-xrp/)
|
||||||
|
|
||||||
3. Set the [`Domain` field](https://ripple.com/build/transactions/#domain) of the account to match the domain hosting your ripple.txt
|
3. Set the [`Domain` field](reference-transaction-format.html#domain) of the account to match the domain hosting your ripple.txt
|
||||||
|
|
||||||
$ /opt/ripple/bin/rippled --conf /opt/ripple/etc/rippled.cfg submit <your-secret-key> '{"TransactionType": "AccountSet", "Account": "<your-account-id>", "Domain": "<your-hex-encoded-domain>", "Fee": "10000"}'
|
$ /opt/ripple/bin/rippled --conf /opt/ripple/etc/rippled.cfg submit <your-secret-key> '{"TransactionType": "AccountSet", "Account": "<your-account-id>", "Domain": "<your-hex-encoded-domain>", "Fee": "10000"}'
|
||||||
|
|
||||||
@@ -266,7 +266,7 @@ To enable clustering, modify the following sections of your [config file](https:
|
|||||||
192.168.0.1 51235
|
192.168.0.1 51235
|
||||||
192.168.0.2 51235
|
192.168.0.2 51235
|
||||||
|
|
||||||
* Generate a unique seed (using the [`validation_create` command](rippled-apis.html#validation-seed)) for each of your servers, and configure it under the `[node_seed]` section. The `rippled` server uses this key to sign its messages to other servers in the peer-to-peer network. **Note:** This is a different key than the one `rippled` uses to sign ledger proposals for consensus, but it is in the same format.
|
* Generate a unique seed (using the [`validation_create` command](reference-rippled.html#validation-seed)) for each of your servers, and configure it under the `[node_seed]` section. The `rippled` server uses this key to sign its messages to other servers in the peer-to-peer network. **Note:** This is a different key than the one `rippled` uses to sign ledger proposals for consensus, but it is in the same format.
|
||||||
* Add the public keys (for peer communication) of each of your other servers under the `[cluster_nodes]` section.
|
* Add the public keys (for peer communication) of each of your other servers under the `[cluster_nodes]` section.
|
||||||
|
|
||||||
|
|
||||||
@@ -41,34 +41,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
|
|||||||
84
index.html
84
index.html
@@ -51,34 +51,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -134,33 +140,39 @@ Ripple’s distributed settlement network is built on open-source technology tha
|
|||||||
<div class="row">
|
<div class="row">
|
||||||
<div class="col-md-3">
|
<div class="col-md-3">
|
||||||
<ul>
|
<ul>
|
||||||
<li class="top"><h5 class="dev_heading">Concepts</h5></li>
|
<li class="top"><h5 class="dev_heading">References</h5></li>
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
<div class="col-md-3">
|
<div class="col-md-3">
|
||||||
<ul>
|
<ul>
|
||||||
<li class="top"><h5 class="dev_heading">Tutorials</h5></li>
|
<li class="top"><h5 class="dev_heading">Tutorials</h5></li>
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
<div class="col-md-3">
|
<div class="col-md-3">
|
||||||
<ul>
|
<ul>
|
||||||
<li class="top"><h5 class="dev_heading">References</h5></li>
|
<li class="top"><h5 class="dev_heading">Concepts</h5></li>
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<div class="col-md-3">
|
||||||
|
<ul>
|
||||||
|
<li class="top"><h5 class="dev_heading">Best Practices</h5></li>
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
<div class="col-md-3">
|
<div class="col-md-3">
|
||||||
|
|||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -427,12 +433,12 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>type</td>
|
<td>type</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>Filter transactions to a specific <a href="transactions.html">transaction type</a>.</td>
|
<td>Filter transactions to a specific <a href="reference-transaction-format.html">transaction type</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>result</td>
|
<td>result</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>Filter transactions for a specific <a href="transactions.html#transaction-results">transaction result</a>.</td>
|
<td>Filter transactions for a specific <a href="reference-transaction-format.html#transaction-results">transaction result</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>binary</td>
|
<td>binary</td>
|
||||||
@@ -1483,12 +1489,12 @@
|
|||||||
<tbody>
|
<tbody>
|
||||||
<tr>
|
<tr>
|
||||||
<td>type</td>
|
<td>type</td>
|
||||||
<td>All Ripple <a href="transactions.html">transaction types</a>, including <code>Payment</code>, <code>AccountSet</code>, <code>SetRegularKey</code>, <code>OfferCreate</code>, <code>OfferCancel</code>, <code>TrustSet</code>.</td>
|
<td>All Ripple <a href="reference-transaction-format.html">transaction types</a>, including <code>Payment</code>, <code>AccountSet</code>, <code>SetRegularKey</code>, <code>OfferCreate</code>, <code>OfferCancel</code>, <code>TrustSet</code>.</td>
|
||||||
<td>Number of transactions of the given type that occurred during the interval.</td>
|
<td>Number of transactions of the given type that occurred during the interval.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>result</td>
|
<td>result</td>
|
||||||
<td>All <a href="transactions.html#transaction-results">transaction result codes</a> (string codes, not the numeric codes), including <code>tesSUCCESS</code>, <code>tecPATH_DRY</code>, and many others.</td>
|
<td>All <a href="reference-transaction-format.html#transaction-results">transaction result codes</a> (string codes, not the numeric codes), including <code>tesSUCCESS</code>, <code>tecPATH_DRY</code>, and many others.</td>
|
||||||
<td>Number of transactions that resulted in the given code during the interval.</td>
|
<td>Number of transactions that resulted in the given code during the interval.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -2780,12 +2786,12 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>accounts</td>
|
<td>accounts</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>A list of <a href="gateway_guide.html#hot-and-cold-wallets">issuing accounts</a> (cold wallets) used by this gateway. (Gateways may use different issuing accounts for different currencies.)</td>
|
<td>A list of <a href="concept-issuing-and-operational-accounts.html">issuing accounts</a> (cold wallets) used by this gateway. (Gateways may use different issuing accounts for different currencies.)</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>hotwallets</td>
|
<td>hotwallets</td>
|
||||||
<td>Array of <a href="#addresses">Address</a>es</td>
|
<td>Array of <a href="#addresses">Address</a>es</td>
|
||||||
<td>The addresses of the Ripple accounts this gateway uses as <a href="gateway_guide.html#hot-and-cold-wallets">hot wallets</a>.</td>
|
<td>The addresses of the Ripple accounts this gateway uses as <a href="concept-issuing-and-operational-accounts.html">operational accounts</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>domain</td>
|
<td>domain</td>
|
||||||
@@ -2817,7 +2823,7 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>address</td>
|
<td>address</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>The <a href="#addresses">Address</a> of an <a href="gateway_guide.html#hot-and-cold-wallets">issuing account</a> (cold wallet) used by this gateway.</td>
|
<td>The <a href="#addresses">Address</a> of an <a href="concept-issuing-and-operational-accounts.html">issuing account</a> (cold wallet) used by this gateway.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>currencies</td>
|
<td>currencies</td>
|
||||||
@@ -3563,7 +3569,7 @@ Content-Type: image/svg+xml
|
|||||||
<tr>
|
<tr>
|
||||||
<td>type</td>
|
<td>type</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>Restrict results to a specified <a href="transactions.html">transaction type</a></td>
|
<td>Restrict results to a specified <a href="reference-transaction-format.html">transaction type</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>result</td>
|
<td>result</td>
|
||||||
@@ -4473,7 +4479,7 @@ Content-Type: image/svg+xml
|
|||||||
<tr>
|
<tr>
|
||||||
<td>rrrrrrrrrrrrrrrrrrrrBZbvji</td>
|
<td>rrrrrrrrrrrrrrrrrrrrBZbvji</td>
|
||||||
<td>ACCOUNT_ONE</td>
|
<td>ACCOUNT_ONE</td>
|
||||||
<td>An address that is the base-58 encoding of the value <code>1</code>. In the ledger, <a href="ripple-ledger.html#ripplestate">RippleState entries</a> use this address as a placeholder for the issuer of a trust line balance.</td>
|
<td>An address that is the base-58 encoding of the value <code>1</code>. In the ledger, <a href="reference-ledger-format.html#ripplestate">RippleState entries</a> use this address as a placeholder for the issuer of a trust line balance.</td>
|
||||||
<td>Yes</td>
|
<td>Yes</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -4527,8 +4533,8 @@ Content-Type: image/svg+xml
|
|||||||
</ul>
|
</ul>
|
||||||
<h3 id="account-sequence">Account Sequence</h3>
|
<h3 id="account-sequence">Account Sequence</h3>
|
||||||
<p>A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.</p>
|
<p>A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.</p>
|
||||||
<p>Every <a href="ripple-ledger.html#accountroot">account object in the Ripple Consensus Ledger</a> has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a <code>Sequence</code> field that matches the sending account's current <code>Sequence</code> number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be identical.</p>
|
<p>Every <a href="reference-ledger-format.html#accountroot">account object in the Ripple Consensus Ledger</a> has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a <code>Sequence</code> field that matches the sending account's current <code>Sequence</code> number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be identical.</p>
|
||||||
<p>Every <a href="ripple-ledger.html#offer">Offer node in the Ripple Consensus Ledger</a> is marked with the sending <code>Account</code> <a href="#addresses">Address</a> and the <code>Sequence</code> value of the <a href="transactions.html#offercreate">OfferCreate transaction</a> that created it. These two fields, together, uniquely identify the Offer.</p>
|
<p>Every <a href="reference-ledger-format.html#offer">Offer node in the Ripple Consensus Ledger</a> is marked with the sending <code>Account</code> <a href="#addresses">Address</a> and the <code>Sequence</code> value of the <a href="reference-transaction-format.html#offercreate">OfferCreate transaction</a> that created it. These two fields, together, uniquely identify the Offer.</p>
|
||||||
<h3 id="currency-code">Currency Code</h3>
|
<h3 id="currency-code">Currency Code</h3>
|
||||||
<p>There are two kinds of currency code in the Ripple Consensus Ledger:</p>
|
<p>There are two kinds of currency code in the Ripple Consensus Ledger:</p>
|
||||||
<ul>
|
<ul>
|
||||||
@@ -4570,7 +4576,7 @@ Content-Type: image/svg+xml
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tx</td>
|
<td>tx</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td>The fields of this transaction object, as defined by the <a href="https://ripple.com/build/transactions">Transaction Format</a></td>
|
<td>The fields of this transaction object, as defined by the <a href="reference-transaction-format.html">Transaction Format</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>meta</td>
|
<td>meta</td>
|
||||||
@@ -4951,7 +4957,7 @@ Content-Type: image/svg+xml
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<h2 id="payment-objects">Payment Objects</h2>
|
<h2 id="payment-objects">Payment Objects</h2>
|
||||||
<p>In the Data API, a Payment Object represents an event where one account sent value to another account. This mostly lines up with Ripple transactions of the <code>Payment</code> <a href="transactions.html">transaction type</a>, except that the Data API does not consider a transaction to be a payment if the sending <code>Account</code> and the <code>Destination</code> account are the same, or if the transaction failed.</p>
|
<p>In the Data API, a Payment Object represents an event where one account sent value to another account. This mostly lines up with Ripple transactions of the <code>Payment</code> <a href="reference-transaction-format.html">transaction type</a>, except that the Data API does not consider a transaction to be a payment if the sending <code>Account</code> and the <code>Destination</code> account are the same, or if the transaction failed.</p>
|
||||||
<p>Payment objects have the following fields:</p>
|
<p>Payment objects have the following fields:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -130,7 +136,7 @@
|
|||||||
<p><img alt="Diagram: A ledger has transactions, a state node, and a header with the close time and validation info" src="img/ledger-components.png"/></p>
|
<p><img alt="Diagram: A ledger has transactions, a state node, and a header with the close time and validation info" src="img/ledger-components.png"/></p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>A <strong>header</strong> - The ledger's unique index (sequence number), hashes of the other contents, and other metadata.</li>
|
<li>A <strong>header</strong> - The ledger's unique index (sequence number), hashes of the other contents, and other metadata.</li>
|
||||||
<li>A <strong>transaction tree</strong> - The <a href="transactions.html">transactions</a> that were applied to the previous ledger to make this one. Transactions are the <em>only</em> way to modify the ledger.</li>
|
<li>A <strong>transaction tree</strong> - The <a href="reference-transaction-format.html">transactions</a> that were applied to the previous ledger to make this one. Transactions are the <em>only</em> way to modify the ledger.</li>
|
||||||
<li>A <strong>state tree</strong> - All the <a href="#ledger-node-types">ledger nodes</a> that contain the settings, balances, and objects in the ledger as of this version.</li>
|
<li>A <strong>state tree</strong> - All the <a href="#ledger-node-types">ledger nodes</a> that contain the settings, balances, and objects in the ledger as of this version.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h2 id="tree-format">Tree Format</h2>
|
<h2 id="tree-format">Tree Format</h2>
|
||||||
@@ -140,7 +146,7 @@
|
|||||||
<p><img alt="Diagram: rippled uses SHA-512Half to generate indexes for ledger nodes. The space key prevents indexes for different node types from colliding." src="img/ledger-indexes.png"/></p>
|
<p><img alt="Diagram: rippled uses SHA-512Half to generate indexes for ledger nodes. The space key prevents indexes for different node types from colliding." src="img/ledger-indexes.png"/></p>
|
||||||
<h2 id="header-format">Header Format</h2>
|
<h2 id="header-format">Header Format</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/ledger/ReadView.h#L68" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/ledger/ReadView.h#L68" title="Source">[Source]<br/></a></p>
|
||||||
<p>Every ledger version has a unique header that describes the contents. You can look up a ledger's header information with the <a href="rippled-apis.html#ledger"><code>ledger</code> command</a>. The contents of the ledger header are as follows:</p>
|
<p>Every ledger version has a unique header that describes the contents. You can look up a ledger's header information with the <a href="reference-rippled.html#ledger"><code>ledger</code> command</a>. The contents of the ledger header are as follows:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -224,7 +230,7 @@
|
|||||||
<li><a href="#offer"><strong>Offer</strong> - An offer to exchange currencies, known in finance as an <em>order</em>.</a></li>
|
<li><a href="#offer"><strong>Offer</strong> - An offer to exchange currencies, known in finance as an <em>order</em>.</a></li>
|
||||||
<li><a href="#ripplestate"><strong>RippleState</strong> - Links two accounts, tracking the balance of one currency between them. The concept of a <em>trust line</em> is really an abstraction of this node type.</a></li>
|
<li><a href="#ripplestate"><strong>RippleState</strong> - Links two accounts, tracking the balance of one currency between them. The concept of a <em>trust line</em> is really an abstraction of this node type.</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>Each ledger node consists of several fields. In the peer protocol that <code>rippled</code> servers use to communicate with each other, ledger nodes are represented in their raw binary format. In other <a href="rippled-apis.html"><code>rippled</code> APIs</a>, ledger nodes are represented as JSON objects.</p>
|
<p>Each ledger node consists of several fields. In the peer protocol that <code>rippled</code> servers use to communicate with each other, ledger nodes are represented in their raw binary format. In other <a href="reference-rippled.html"><code>rippled</code> APIs</a>, ledger nodes are represented as JSON objects.</p>
|
||||||
<h2 id="accountroot">AccountRoot</h2>
|
<h2 id="accountroot">AccountRoot</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L27" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L27" title="Source">[Source]<br/></a></p>
|
||||||
<p>The <code>AccountRoot</code> node type describes a single <em>account</em> object. Example <code>AccountRoot</code> node:</p>
|
<p>The <code>AccountRoot</code> node type describes a single <em>account</em> object. Example <code>AccountRoot</code> node:</p>
|
||||||
@@ -314,7 +320,7 @@
|
|||||||
<td>RegularKey</td>
|
<td>RegularKey</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>AccountID</td>
|
<td>AccountID</td>
|
||||||
<td>(Optional) The address of a keypair that can be used to sign transactions for this account instead of the master key. Use a <a href="transactions.html#setregularkey">SetRegularKey transaction</a> to change this value.</td>
|
<td>(Optional) The address of a keypair that can be used to sign transactions for this account instead of the master key. Use a <a href="reference-transaction-format.html#setregularkey">SetRegularKey transaction</a> to change this value.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>EmailHash</td>
|
<td>EmailHash</td>
|
||||||
@@ -355,7 +361,7 @@
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<h3 id="accountroot-flags">AccountRoot Flags</h3>
|
<h3 id="accountroot-flags">AccountRoot Flags</h3>
|
||||||
<p>There are several options which can be either enabled or disabled for an account. These options can be changed with an <a href="transactions.html#accountset">AccountSet transaction</a>. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with <em>lsf</em>.</p>
|
<p>There are several options which can be either enabled or disabled for an account. These options can be changed with an <a href="reference-transaction-format.html#accountset">AccountSet transaction</a>. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with <em>lsf</em>.</p>
|
||||||
<p>AccountRoot nodes can have the following flag values:</p>
|
<p>AccountRoot nodes can have the following flag values:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
@@ -364,7 +370,7 @@
|
|||||||
<th>Hex Value</th>
|
<th>Hex Value</th>
|
||||||
<th>Decimal Value</th>
|
<th>Decimal Value</th>
|
||||||
<th>Description</th>
|
<th>Description</th>
|
||||||
<th>Corresponding <a href="transactions.html#accountset-flags">AccountSet Flag</a></th>
|
<th>Corresponding <a href="reference-transaction-format.html#accountset-flags">AccountSet Flag</a></th>
|
||||||
</tr>
|
</tr>
|
||||||
</thead>
|
</thead>
|
||||||
<tbody>
|
<tbody>
|
||||||
@@ -585,8 +591,8 @@
|
|||||||
</ul>
|
</ul>
|
||||||
<h2 id="offer">Offer</h2>
|
<h2 id="offer">Offer</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L57" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L57" title="Source">[Source]<br/></a></p>
|
||||||
<p>The <code>Offer</code> node type describes an offer to exchange currencies, more traditionally known as an <em>order</em>, which is currently in an order book in Ripple's distributed exchange. An <a href="transactions.html#offercreate">OfferCreate transaction</a> only creates an Offer node in the ledger when the offer cannot be fully executed immediately by consuming other offers already in the ledger.</p>
|
<p>The <code>Offer</code> node type describes an offer to exchange currencies, more traditionally known as an <em>order</em>, which is currently in an order book in Ripple's distributed exchange. An <a href="reference-transaction-format.html#offercreate">OfferCreate transaction</a> only creates an Offer node in the ledger when the offer cannot be fully executed immediately by consuming other offers already in the ledger.</p>
|
||||||
<p>An offer can become unfunded through other activities in the network, while remaining in the ledger. However, <code>rippled</code> will automatically prune any unfunded offers it happens across in the course of transaction processing (and <em>only</em> transaction processing, because the ledger state must only be changed by transactions). For more information, see <a href="transactions.html#lifecycle-of-an-offer">lifecycle of an offer</a>.</p>
|
<p>An offer can become unfunded through other activities in the network, while remaining in the ledger. However, <code>rippled</code> will automatically prune any unfunded offers it happens across in the course of transaction processing (and <em>only</em> transaction processing, because the ledger state must only be changed by transactions). For more information, see <a href="reference-transaction-format.html#lifecycle-of-an-offer">lifecycle of an offer</a>.</p>
|
||||||
<p>Example Offer node:</p>
|
<p>Example Offer node:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"Account": "rBqb89MRQJnMPq8wTwEbtz4kvxrEDfcYvt",
|
"Account": "rBqb89MRQJnMPq8wTwEbtz4kvxrEDfcYvt",
|
||||||
@@ -640,7 +646,7 @@
|
|||||||
<td>Sequence</td>
|
<td>Sequence</td>
|
||||||
<td>Number</td>
|
<td>Number</td>
|
||||||
<td>UInt32</td>
|
<td>UInt32</td>
|
||||||
<td>The <code>Sequence</code> value of the <a href="transactions.html#offercreate">OfferCreate</a> transaction that created this Offer node. Used in combination with the <code>Account</code> to identify this Offer.</td>
|
<td>The <code>Sequence</code> value of the <a href="reference-transaction-format.html#offercreate">OfferCreate</a> transaction that created this Offer node. Used in combination with the <code>Account</code> to identify this Offer.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>TakerPays</td>
|
<td>TakerPays</td>
|
||||||
@@ -688,12 +694,12 @@
|
|||||||
<td>Expiration</td>
|
<td>Expiration</td>
|
||||||
<td>Number</td>
|
<td>Number</td>
|
||||||
<td>UInt32</td>
|
<td>UInt32</td>
|
||||||
<td>(Optional) Indicates the time after which this offer will be considered unfunded. See <a href="rippled-apis.html#specifying-time">Specifying Time</a> for details.</td>
|
<td>(Optional) Indicates the time after which this offer will be considered unfunded. See <a href="reference-rippled.html#specifying-time">Specifying Time</a> for details.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<h3 id="offer-flags">Offer Flags</h3>
|
<h3 id="offer-flags">Offer Flags</h3>
|
||||||
<p>There are several options which can be either enabled or disabled when an <a href="transactions.html#offercreate">OfferCreate transaction</a> creates an offer node. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with <em>lsf</em>.</p>
|
<p>There are several options which can be either enabled or disabled when an <a href="reference-transaction-format.html#offercreate">OfferCreate transaction</a> creates an offer node. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with <em>lsf</em>.</p>
|
||||||
<p>Offer nodes can have the following flag values:</p>
|
<p>Offer nodes can have the following flag values:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
@@ -702,7 +708,7 @@
|
|||||||
<th>Hex Value</th>
|
<th>Hex Value</th>
|
||||||
<th>Decimal Value</th>
|
<th>Decimal Value</th>
|
||||||
<th>Description</th>
|
<th>Description</th>
|
||||||
<th>Corresponding <a href="transactions.html#offercreate-flags">OfferCreate Flag</a></th>
|
<th>Corresponding <a href="reference-transaction-format.html#offercreate-flags">OfferCreate Flag</a></th>
|
||||||
</tr>
|
</tr>
|
||||||
</thead>
|
</thead>
|
||||||
<tbody>
|
<tbody>
|
||||||
@@ -851,7 +857,7 @@
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<h3 id="ripplestate-flags">RippleState Flags</h3>
|
<h3 id="ripplestate-flags">RippleState Flags</h3>
|
||||||
<p>There are several options which can be either enabled or disabled for a trust line. These options can be changed with a <a href="transactions.html#trustset">TrustSet transaction</a>. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with <em>lsf</em>.</p>
|
<p>There are several options which can be either enabled or disabled for a trust line. These options can be changed with a <a href="reference-transaction-format.html#trustset">TrustSet transaction</a>. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with <em>lsf</em>.</p>
|
||||||
<p>RippleState nodes can have the following flag values:</p>
|
<p>RippleState nodes can have the following flag values:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
@@ -860,7 +866,7 @@
|
|||||||
<th>Hex Value</th>
|
<th>Hex Value</th>
|
||||||
<th>Decimal Value</th>
|
<th>Decimal Value</th>
|
||||||
<th>Description</th>
|
<th>Description</th>
|
||||||
<th>Corresponding <a href="transactions.html#trustset-flags">TrustSet Flag</a></th>
|
<th>Corresponding <a href="reference-transaction-format.html#trustset-flags">TrustSet Flag</a></th>
|
||||||
</tr>
|
</tr>
|
||||||
</thead>
|
</thead>
|
||||||
<tbody>
|
<tbody>
|
||||||
@@ -923,7 +929,7 @@
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<h3 id="contributing-to-the-owner-reserve">Contributing to the Owner Reserve</h3>
|
<h3 id="contributing-to-the-owner-reserve">Contributing to the Owner Reserve</h3>
|
||||||
<p>If an account modifies a trust line to put it in a non-default state, then that trust line counts towards the account's <a href="reserves.html#owner-reserves">owner reserve</a>. In a RippleState node, the <code>lsfLowReserve</code> and <code>lsfHighReserve</code> flags indicate which account(s) are responsible for the owner reserve. The <code>rippled</code> server automatically sets these flags when it modifies a trust line.</p>
|
<p>If an account modifies a trust line to put it in a non-default state, then that trust line counts towards the account's <a href="concept-reserves.html#owner-reserves">owner reserve</a>. In a RippleState node, the <code>lsfLowReserve</code> and <code>lsfHighReserve</code> flags indicate which account(s) are responsible for the owner reserve. The <code>rippled</code> server automatically sets these flags when it modifies a trust line.</p>
|
||||||
<p>The values that count towards a trust line's non-default state are as follows:</p>
|
<p>The values that count towards a trust line's non-default state are as follows:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -125,13 +131,13 @@
|
|||||||
<h1 id="rippled">rippled</h1>
|
<h1 id="rippled">rippled</h1>
|
||||||
<p>The core peer-to-peer server that operates the Ripple Network is called <code>rippled</code>. Each <code>rippled</code> server connects to the Ripple Network, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code for <code>rippled</code> is written in C++, and is <a href="https://github.com/ripple/rippled">available on GitHub under an open-source license</a>.</p>
|
<p>The core peer-to-peer server that operates the Ripple Network is called <code>rippled</code>. Each <code>rippled</code> server connects to the Ripple Network, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code for <code>rippled</code> is written in C++, and is <a href="https://github.com/ripple/rippled">available on GitHub under an open-source license</a>.</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="rippled-setup.html"><code>rippled</code> Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html"><code>rippled</code> Setup</a></li>
|
||||||
<li><a href="#api-methods">API Reference</a></li>
|
<li><a href="#api-methods">API Reference</a></li>
|
||||||
<li><a href="transactions.html">Transaction Reference</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Reference</a></li>
|
||||||
<li>JavaScript Client Library - <a href="rippleapi.html">RippleAPI</a></li>
|
<li>JavaScript Client Library - <a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
<h1 id="websocket-and-json-rpc-apis">WebSocket and JSON-RPC APIs</h1>
|
<h1 id="websocket-and-json-rpc-apis">WebSocket and JSON-RPC APIs</h1>
|
||||||
<p>If you want to communicate directly with a <code>rippled</code> server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Alternatively, you can use <a href="rippleapi.html">RippleAPI</a>, which is a simplified JavaScript client library, which communicates directly with a <code>rippled</code> server from <a href="http://nodejs.org/">Node.js</a> or a web browser.</p>
|
<p>If you want to communicate directly with a <code>rippled</code> server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Alternatively, you can use <a href="reference-rippleapi.html">RippleAPI</a>, which is a simplified JavaScript client library, which communicates directly with a <code>rippled</code> server from <a href="http://nodejs.org/">Node.js</a> or a web browser.</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>The WebSocket API uses the <a href="http://www.html5rocks.com/en/tutorials/websockets/basics/">WebSocket protocol</a>, available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The <code>rippled</code> server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.</li>
|
<li>The WebSocket API uses the <a href="http://www.html5rocks.com/en/tutorials/websockets/basics/">WebSocket protocol</a>, available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The <code>rippled</code> server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.</li>
|
||||||
<li>The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The <code>rippled</code> server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL.</li>
|
<li>The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The <code>rippled</code> server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL.</li>
|
||||||
@@ -143,7 +149,7 @@
|
|||||||
<p><a href="https://groups.google.com/forum/#!forum/ripple-server">https://groups.google.com/forum/#!forum/ripple-server</a></p>
|
<p><a href="https://groups.google.com/forum/#!forum/ripple-server">https://groups.google.com/forum/#!forum/ripple-server</a></p>
|
||||||
<h2 id="connecting-to-rippled">Connecting to rippled</h2>
|
<h2 id="connecting-to-rippled">Connecting to rippled</h2>
|
||||||
<p>Before you can run any commands against a <code>rippled</code> server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network.</p>
|
<p>Before you can run any commands against a <code>rippled</code> server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network.</p>
|
||||||
<p>Alternatively, you can <a href="rippled-setup.html">run your own local copy of <code>rippled</code></a>. This is required if you want to access any of the <a href="#list-of-admin-commands">Admin Commands</a>. In this case, you should use whatever IP and port you configured the server to bind. (For example, <code>127.0.0.1:54321</code>) Additionally, in order to access admin functionality, you must connect from a port/IP address marked as admin in the config file.</p>
|
<p>Alternatively, you can <a href="tutorial-rippled-setup.html">run your own local copy of <code>rippled</code></a>. This is required if you want to access any of the <a href="#list-of-admin-commands">Admin Commands</a>. In this case, you should use whatever IP and port you configured the server to bind. (For example, <code>127.0.0.1:54321</code>) Additionally, in order to access admin functionality, you must connect from a port/IP address marked as admin in the config file.</p>
|
||||||
<p>The <a href="https://github.com/ripple/rippled/blob/d7def5509d8338b1e46c0adf309b5912e5168af0/doc/rippled-example.cfg#L831-L854">example config file</a> listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.</p>
|
<p>The <a href="https://github.com/ripple/rippled/blob/d7def5509d8338b1e46c0adf309b5912e5168af0/doc/rippled-example.cfg#L831-L854">example config file</a> listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.</p>
|
||||||
<h3 id="websocket-api">WebSocket API</h3>
|
<h3 id="websocket-api">WebSocket API</h3>
|
||||||
<p>If you are just looking to try out some methods on the Ripple network, you can skip writing your own WebSocket code and go straight to using the API at the <a href="ripple-api-tool.html">Ripple WebSocket API Tool</a>. Later on, when you want to connect to your own <code>rippled</code> server, you can build your own client in Javascript to run in a browser (See <a href="http://www.websocket.org/echo.html">this example</a> ) or possibly <a href="https://github.com/einaros/ws">Node.js</a>.</p>
|
<p>If you are just looking to try out some methods on the Ripple network, you can skip writing your own WebSocket code and go straight to using the API at the <a href="ripple-api-tool.html">Ripple WebSocket API Tool</a>. Later on, when you want to connect to your own <code>rippled</code> server, you can build your own client in Javascript to run in a browser (See <a href="http://www.websocket.org/echo.html">this example</a> ) or possibly <a href="https://github.com/einaros/ws">Node.js</a>.</p>
|
||||||
@@ -528,7 +534,7 @@ Null method
|
|||||||
<tr>
|
<tr>
|
||||||
<td>rrrrrrrrrrrrrrrrrrrrBZbvji</td>
|
<td>rrrrrrrrrrrrrrrrrrrrBZbvji</td>
|
||||||
<td>ACCOUNT_ONE</td>
|
<td>ACCOUNT_ONE</td>
|
||||||
<td>An address that is the base-58 encoding of the value <code>1</code>. In the ledger, <a href="ripple-ledger.html#ripplestate">RippleState entries</a> use this address as a placeholder for the issuer of a trust line balance.</td>
|
<td>An address that is the base-58 encoding of the value <code>1</code>. In the ledger, <a href="reference-ledger-format.html#ripplestate">RippleState entries</a> use this address as a placeholder for the issuer of a trust line balance.</td>
|
||||||
<td>Yes</td>
|
<td>Yes</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -562,8 +568,8 @@ Null method
|
|||||||
<p><strong>Note:</strong> SHA-512Half has similar security to the officially-defined <em>SHA-512/256</em> hash function. However, Ripple's usage predates SHA-512/256 and is also easier to implement on top of an existing SHA-512 function. (As of this writing, SHA-512 support in cryptographic libraries is much more common than for SHA-512/256.)</p>
|
<p><strong>Note:</strong> SHA-512Half has similar security to the officially-defined <em>SHA-512/256</em> hash function. However, Ripple's usage predates SHA-512/256 and is also easier to implement on top of an existing SHA-512 function. (As of this writing, SHA-512 support in cryptographic libraries is much more common than for SHA-512/256.)</p>
|
||||||
<h3 id="account-sequence">Account Sequence</h3>
|
<h3 id="account-sequence">Account Sequence</h3>
|
||||||
<p>A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.</p>
|
<p>A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.</p>
|
||||||
<p>Every <a href="ripple-ledger.html#accountroot">account object in the Ripple Consensus Ledger</a> has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a <code>Sequence</code> field that matches the sending account's current <code>Sequence</code> number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be identical.</p>
|
<p>Every <a href="reference-ledger-format.html#accountroot">account object in the Ripple Consensus Ledger</a> has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a <code>Sequence</code> field that matches the sending account's current <code>Sequence</code> number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be identical.</p>
|
||||||
<p>Every <a href="ripple-ledger.html#offer">Offer node in the Ripple Consensus Ledger</a> is marked with the sending <code>Account</code> <a href="#addresses">Address</a> and the <code>Sequence</code> value of the <a href="transactions.html#offercreate">OfferCreate transaction</a> that created it. These two fields, together, uniquely identify the Offer.</p>
|
<p>Every <a href="reference-ledger-format.html#offer">Offer node in the Ripple Consensus Ledger</a> is marked with the sending <code>Account</code> <a href="#addresses">Address</a> and the <code>Sequence</code> value of the <a href="reference-transaction-format.html#offercreate">OfferCreate transaction</a> that created it. These two fields, together, uniquely identify the Offer.</p>
|
||||||
<h3 id="ledger-index">Ledger Index</h3>
|
<h3 id="ledger-index">Ledger Index</h3>
|
||||||
<p>A ledger index is a 32-bit unsigned integer used to identify a ledger. The ledger index is also known as the ledger's sequence number. The very first ledger was ledger index 1, and each subsequent ledger has a ledger index 1 higher than that of the ledger immediately before it.</p>
|
<p>A ledger index is a 32-bit unsigned integer used to identify a ledger. The ledger index is also known as the ledger's sequence number. The very first ledger was ledger index 1, and each subsequent ledger has a ledger index 1 higher than that of the ledger immediately before it.</p>
|
||||||
<p>The ledger index indicates the order of the ledgers; the <a href="#hashes">Hash</a> value identifies the exact contents of the ledger. Two ledgers with the same hash are always identical. For closed ledgers, hash values and sequence numbers are equally valid and correlate 1:1. However, this is not true for in-progress ledgers:</p>
|
<p>The ledger index indicates the order of the ledgers; the <a href="#hashes">Hash</a> value identifies the exact contents of the ledger. Two ledgers with the same hash are always identical. For closed ledgers, hash values and sequence numbers are equally valid and correlate 1:1. However, this is not true for in-progress ledgers:</p>
|
||||||
@@ -604,8 +610,8 @@ Null method
|
|||||||
<td>Specified as an object</td>
|
<td>Specified as an object</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>Tracked in <a href="ripple-ledger.html#accountroot">accounts</a></td>
|
<td>Tracked in <a href="reference-ledger-format.html#accountroot">accounts</a></td>
|
||||||
<td>Tracked in <a href="ripple-ledger.html#ripplestate">trust lines</a></td>
|
<td>Tracked in <a href="reference-ledger-format.html#ripplestate">trust lines</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>Can never be created; can only be destroyed</td>
|
<td>Can never be created; can only be destroyed</td>
|
||||||
@@ -724,7 +730,7 @@ Null method
|
|||||||
<p>The format of the <code>marker</code> field is intentionally undefined. Each server can define a <code>marker</code> field as desired, so it may take the form of a string, a nested object, or another type. Different servers, and different methods provided by the same server, can have different <code>marker</code> definitions. Each <code>marker</code> is ephemeral, and may not work as expected after 10 minutes.</p>
|
<p>The format of the <code>marker</code> field is intentionally undefined. Each server can define a <code>marker</code> field as desired, so it may take the form of a string, a nested object, or another type. Different servers, and different methods provided by the same server, can have different <code>marker</code> definitions. Each <code>marker</code> is ephemeral, and may not work as expected after 10 minutes.</p>
|
||||||
<h2 id="modifying-the-ledger">Modifying the Ledger</h2>
|
<h2 id="modifying-the-ledger">Modifying the Ledger</h2>
|
||||||
<p>All changes to Ripple's global shared ledger happen as the result of transactions. Consequently, this means that there is <em>only one</em> public API method that causes a change in the state of the Ripple Network at all: the <a href="#submit"><em>submit</em></a> command. Most of the other methods represent different ways to view the data represented in the Ripple Network, and the remaining ones just generate data for your convenience. (The <a href="#wallet-propose">wallet_propose</a>, <a href="#path-find">path_find</a>, and <a href="#random">random</a> commands fall into this category.)</p>
|
<p>All changes to Ripple's global shared ledger happen as the result of transactions. Consequently, this means that there is <em>only one</em> public API method that causes a change in the state of the Ripple Network at all: the <a href="#submit"><em>submit</em></a> command. Most of the other methods represent different ways to view the data represented in the Ripple Network, and the remaining ones just generate data for your convenience. (The <a href="#wallet-propose">wallet_propose</a>, <a href="#path-find">path_find</a>, and <a href="#random">random</a> commands fall into this category.)</p>
|
||||||
<p>For more information on the various transactions you can submit, consult the <a href="transactions.html">Transaction Format</a>.</p>
|
<p>For more information on the various transactions you can submit, consult the <a href="reference-transaction-format.html">Transaction Format</a>.</p>
|
||||||
<h1 id="api-methods">API Methods</h1>
|
<h1 id="api-methods">API Methods</h1>
|
||||||
<p>API methods for the Websocket and JSON-RPC APIs are defined by command names, and are divided into Public Commands and Admin Commands. Public Commands are not necessarily meant for the general public, but they are used by any client attached to the server. (Think of Public Commands as being for members or customers of the organization running the server, while the Admin Commands are for the personnel in charge of keeping the server operational.) Public Commands include the general operations for Ripple use, including checking the state of the ledger, finding a path to connecting users, and submitting a transaction, among others. Admin Commands, on the other hand, are meant only for the operators of the server, and include commands for managing the state of the server, the nodes it uses for validation, and other administrative features.</p>
|
<p>API methods for the Websocket and JSON-RPC APIs are defined by command names, and are divided into Public Commands and Admin Commands. Public Commands are not necessarily meant for the general public, but they are used by any client attached to the server. (Think of Public Commands as being for members or customers of the organization running the server, while the Admin Commands are for the personnel in charge of keeping the server operational.) Public Commands include the general operations for Ripple use, including checking the state of the ledger, finding a path to connecting users, and submitting a transaction, among others. Admin Commands, on the other hand, are meant only for the operators of the server, and include commands for managing the state of the server, the nodes it uses for validation, and other administrative features.</p>
|
||||||
<h2 id="list-of-public-commands">List of Public Commands</h2>
|
<h2 id="list-of-public-commands">List of Public Commands</h2>
|
||||||
@@ -789,7 +795,7 @@ Null method
|
|||||||
<li><a href="#json"><code>json</code> - Pass JSON through the commandline</a></li>
|
<li><a href="#json"><code>json</code> - Pass JSON through the commandline</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
<h1 id="account-information">Account Information</h1>
|
<h1 id="account-information">Account Information</h1>
|
||||||
<p>Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The <a href="reserves.html">reserve for an account</a> increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users. </p>
|
<p>Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The <a href="concept-reserves.html">reserve for an account</a> increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users. </p>
|
||||||
<h2 id="account-currencies">account_currencies</h2>
|
<h2 id="account-currencies">account_currencies</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/df966a9ac6dd986585ecccb206aff24452e41a30/src/ripple/rpc/handlers/AccountCurrencies.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/df966a9ac6dd986585ecccb206aff24452e41a30/src/ripple/rpc/handlers/AccountCurrencies.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>The <code>account_currencies</code> command retrieves a simple list of currencies that an account can send or receive, based on its trust lines. (This is not a thoroughly confirmed list, but it can be used to populate user interfaces.)</p>
|
<p>The <code>account_currencies</code> command retrieves a simple list of currencies that an account can send or receive, based on its trust lines. (This is not a thoroughly confirmed list, but it can be used to populate user interfaces.)</p>
|
||||||
@@ -957,7 +963,7 @@ Null method
|
|||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p><em>Note:</em> The currencies that an account can send or receive are defined based on a simple check of its trust lines. If an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trust line's balance can go down, the account can send that currency. This method <em>doesn't</em> check whether the trust line is <a href="freeze.html">frozen</a> or authorized.</p>
|
<p><em>Note:</em> The currencies that an account can send or receive are defined based on a simple check of its trust lines. If an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trust line's balance can go down, the account can send that currency. This method <em>doesn't</em> check whether the trust line is <a href="concept-freeze.html">frozen</a> or authorized.</p>
|
||||||
<h4 id="possible-errors">Possible Errors</h4>
|
<h4 id="possible-errors">Possible Errors</h4>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Any of the <a href="#universal-errors">universal error types</a>.</li>
|
<li>Any of the <a href="#universal-errors">universal error types</a>.</li>
|
||||||
@@ -1069,7 +1075,7 @@ rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 true
|
|||||||
<tr>
|
<tr>
|
||||||
<td>account_data</td>
|
<td>account_data</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td>The <a href="ripple-ledger.html#accountroot">AccountRoot ledger node</a> with this account's information, as stored in the ledger.</td>
|
<td>The <a href="reference-ledger-format.html#accountroot">AccountRoot ledger node</a> with this account's information, as stored in the ledger.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>ledger_current_index</td>
|
<td>ledger_current_index</td>
|
||||||
@@ -1352,12 +1358,12 @@ rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 true
|
|||||||
<tr>
|
<tr>
|
||||||
<td>freeze</td>
|
<td>freeze</td>
|
||||||
<td>Boolean</td>
|
<td>Boolean</td>
|
||||||
<td>(May be omitted) <code>true</code> if this account has <a href="freeze.html">frozen</a> this trust line. If omitted, that is the same as <code>false</code>.</td>
|
<td>(May be omitted) <code>true</code> if this account has <a href="concept-freeze.html">frozen</a> this trust line. If omitted, that is the same as <code>false</code>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>freeze_peer</td>
|
<td>freeze_peer</td>
|
||||||
<td>Boolean</td>
|
<td>Boolean</td>
|
||||||
<td>(May be omitted) <code>true</code> if the peer account has <a href="freeze.html">frozen</a> this trust line. If omitted, that is the same as <code>false</code>.</td>
|
<td>(May be omitted) <code>true</code> if the peer account has <a href="concept-freeze.html">frozen</a> this trust line. If omitted, that is the same as <code>false</code>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -1612,7 +1618,7 @@ rippled account_offers r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 current
|
|||||||
<tr>
|
<tr>
|
||||||
<td>expiration</td>
|
<td>expiration</td>
|
||||||
<td>Unsigned integer</td>
|
<td>Unsigned integer</td>
|
||||||
<td>(May be omitted) A time after which this offer is considered unfunded, as <a href="#specifying-time">the number of seconds since the Ripple Epoch</a>. See also: <a href="transactions.html#expiration">Offer Expiration</a>. <em>(New in <a href="https://wiki.ripple.com/Rippled-0.30.1">version 0.30.1</a>)</em></td>
|
<td>(May be omitted) A time after which this offer is considered unfunded, as <a href="#specifying-time">the number of seconds since the Ripple Epoch</a>. See also: <a href="reference-transaction-format.html#expiration">Offer Expiration</a>. <em>(New in <a href="https://wiki.ripple.com/Rippled-0.30.1">version 0.30.1</a>)</em></td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -1626,7 +1632,7 @@ rippled account_offers r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 current
|
|||||||
</ul>
|
</ul>
|
||||||
<h2 id="account-objects">account_objects</h2>
|
<h2 id="account-objects">account_objects</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/399c43cae6e90a428e9ce6a988123972b0f03c99/src/ripple/rpc/handlers/AccountObjects.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/399c43cae6e90a428e9ce6a988123972b0f03c99/src/ripple/rpc/handlers/AccountObjects.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>The <code>account_objects</code> command returns the raw <a href="ripple-ledger.html">ledger format</a> for all objects owned by an account, such as <a href="transactions.html#lifecycle-of-an-offer">outstanding offers</a>, trust lines in non-default state, and tickets (which are part of forthcoming multi-sign code). For getting the balance of an account's trust lines, we recommend <a href="#account-lines"><code>account_lines</code></a> instead.</p>
|
<p>The <code>account_objects</code> command returns the raw <a href="reference-ledger-format.html">ledger format</a> for all objects owned by an account, such as <a href="reference-transaction-format.html#lifecycle-of-an-offer">outstanding offers</a>, trust lines in non-default state, and tickets (which are part of forthcoming multi-sign code). For getting the balance of an account's trust lines, we recommend <a href="#account-lines"><code>account_lines</code></a> instead.</p>
|
||||||
<h4 id="request-format-4">Request Format</h4>
|
<h4 id="request-format-4">Request Format</h4>
|
||||||
<p>An example of the request format:</p>
|
<p>An example of the request format:</p>
|
||||||
<div class="multicode">
|
<div class="multicode">
|
||||||
@@ -2235,7 +2241,7 @@ rippled account_objects r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated
|
|||||||
<tr>
|
<tr>
|
||||||
<td>account_objects</td>
|
<td>account_objects</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>Array of objects owned by this account. Each object is in its raw <a href="ripple-ledger.html">ledger format</a>.</td>
|
<td>Array of objects owned by this account. Each object is in its raw <a href="reference-ledger-format.html">ledger format</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>ledger_hash</td>
|
<td>ledger_hash</td>
|
||||||
@@ -3006,7 +3012,7 @@ There is also a deprecated legacy variation of the <code>account_tx</code> metho
|
|||||||
<tr>
|
<tr>
|
||||||
<td>transactions</td>
|
<td>transactions</td>
|
||||||
<td>Boolean</td>
|
<td>Boolean</td>
|
||||||
<td>(Optional) If <code>true</code>, include an array of suggested <a href="transactions.html">transactions</a>, as JSON objects, that you can sign and submit to fix the problems. Defaults to false.</td>
|
<td>(Optional) If <code>true</code>, include an array of suggested <a href="reference-transaction-format.html">transactions</a>, as JSON objects, that you can sign and submit to fix the problems. Defaults to false.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>limit</td>
|
<td>limit</td>
|
||||||
@@ -3149,7 +3155,7 @@ There is also a deprecated legacy variation of the <code>account_tx</code> metho
|
|||||||
<tr>
|
<tr>
|
||||||
<td>transactions</td>
|
<td>transactions</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>(May be omitted) If the request specified <code>transactions</code> as <code>true</code>, this is an array of JSON objects, each of which is the JSON form of a <a href="transactions.html">transaction</a> that should fix one of the described problems. The length of this array is the same as the <code>problems</code> array, and each entry is intended to fix the problem described at the same index into that array.</td>
|
<td>(May be omitted) If the request specified <code>transactions</code> as <code>true</code>, this is an array of JSON objects, each of which is the JSON form of a <a href="reference-transaction-format.html">transaction</a> that should fix one of the described problems. The length of this array is the same as the <code>problems</code> array, and each entry is intended to fix the problem described at the same index into that array.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -3518,7 +3524,7 @@ rippled wallet_propose test
|
|||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>The key generated by this method can also be used as a regular key for an account if you use the <a href="transactions.html#setregularkey">SetRegularKey transaction type</a> to do so.</p>
|
<p>The key generated by this method can also be used as a regular key for an account if you use the <a href="reference-transaction-format.html#setregularkey">SetRegularKey transaction type</a> to do so.</p>
|
||||||
<h4 id="possible-errors-8">Possible Errors</h4>
|
<h4 id="possible-errors-8">Possible Errors</h4>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Any of the <a href="#universal-errors">universal error types</a>.</li>
|
<li>Any of the <a href="#universal-errors">universal error types</a>.</li>
|
||||||
@@ -3706,7 +3712,7 @@ rippled ledger current
|
|||||||
<tr>
|
<tr>
|
||||||
<td>ledger.accounts</td>
|
<td>ledger.accounts</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>(Omitted unless requested) All the <a href="ripple-ledger.html">account-state information</a> in this ledger.</td>
|
<td>(Omitted unless requested) All the <a href="reference-ledger-format.html">account-state information</a> in this ledger.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>ledger.close_time</td>
|
<td>ledger.close_time</td>
|
||||||
@@ -3771,7 +3777,7 @@ rippled ledger current
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>The following fields are deprecated and may be removed without further notice: <code>accepted</code>, <code>hash</code>, <code>seqNum</code>, <code>totalCoins</code>.</p>
|
<p>The following fields are deprecated and may be removed without further notice: <code>accepted</code>, <code>hash</code>, <code>seqNum</code>, <code>totalCoins</code>.</p>
|
||||||
<p><strong>Note on <code>owner_funds</code>:</strong> If the request specified <code>"owner_funds": true</code> and expanded transactions, the response has a field <code>owner_funds</code> in the <code>metaData</code> object of each <a href="transactions.html#offercreate">OfferCreate-type transaction</a>. The purpose of this field is to make it easier to track the <a href="transactions.html#lifecycle-of-an-offer">funding status of offers</a> with each new validated ledger. This field is defined slightly different than the version of this field in <a href="#order-book-streams">Order Book subscription streams</a>:</p>
|
<p><strong>Note on <code>owner_funds</code>:</strong> If the request specified <code>"owner_funds": true</code> and expanded transactions, the response has a field <code>owner_funds</code> in the <code>metaData</code> object of each <a href="reference-transaction-format.html#offercreate">OfferCreate-type transaction</a>. The purpose of this field is to make it easier to track the <a href="reference-transaction-format.html#lifecycle-of-an-offer">funding status of offers</a> with each new validated ledger. This field is defined slightly different than the version of this field in <a href="#order-book-streams">Order Book subscription streams</a>:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -3784,7 +3790,7 @@ rippled ledger current
|
|||||||
<tr>
|
<tr>
|
||||||
<td>owner_funds</td>
|
<td>owner_funds</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>Numeric amount of the <code>TakerGets</code> currency that the <code>Account</code> sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is <a href="freeze.html">frozen</a>.</td>
|
<td>Numeric amount of the <code>TakerGets</code> currency that the <code>Account</code> sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is <a href="concept-freeze.html">frozen</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -4234,7 +4240,7 @@ rippled ledger_current
|
|||||||
<tr>
|
<tr>
|
||||||
<td>LedgerEntryType</td>
|
<td>LedgerEntryType</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>(Only included if <code>"binary":false</code>) String indicating what type of ledger node this object represents. See <a href="ripple-ledger.html">ledger format</a> for the full list.</td>
|
<td>(Only included if <code>"binary":false</code>) String indicating what type of ledger node this object represents. See <a href="reference-ledger-format.html">ledger format</a> for the full list.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>(Additional fields)</td>
|
<td>(Additional fields)</td>
|
||||||
@@ -4256,7 +4262,7 @@ rippled ledger_current
|
|||||||
</ul>
|
</ul>
|
||||||
<h2 id="ledger-entry">ledger_entry</h2>
|
<h2 id="ledger-entry">ledger_entry</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/LedgerEntry.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/LedgerEntry.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>The <code>ledger_entry</code> method returns a single ledger node from the Ripple Consensus Ledger in its raw format. See <a href="ripple-ledger.html">ledger format</a> for information on the different types of objects you can retrieve.</p>
|
<p>The <code>ledger_entry</code> method returns a single ledger node from the Ripple Consensus Ledger in its raw format. See <a href="reference-ledger-format.html">ledger format</a> for information on the different types of objects you can retrieve.</p>
|
||||||
<p><strong><em>Note:</em></strong> There is no commandline version of this method. You can use the <a href="#json"><code>json</code> command</a> to access this method from the commandline instead.</p>
|
<p><strong><em>Note:</em></strong> There is no commandline version of this method. You can use the <a href="#json"><code>json</code> command</a> to access this method from the commandline instead.</p>
|
||||||
<h4 id="request-format-13">Request Format</h4>
|
<h4 id="request-format-13">Request Format</h4>
|
||||||
<p>An example of the request format:</p>
|
<p>An example of the request format:</p>
|
||||||
@@ -4287,10 +4293,10 @@ rippled ledger_current
|
|||||||
<p>This method can retrieve several different types of data. You can select which type of item to retrieve by passing the appropriate parameters. Specifically, you should provide exactly one of the following fields:</p>
|
<p>This method can retrieve several different types of data. You can select which type of item to retrieve by passing the appropriate parameters. Specifically, you should provide exactly one of the following fields:</p>
|
||||||
<ol>
|
<ol>
|
||||||
<li><code>index</code> - Retrieve any type of ledger node by its unique index</li>
|
<li><code>index</code> - Retrieve any type of ledger node by its unique index</li>
|
||||||
<li><code>account_root</code> - Retrieve an <a href="ripple-ledger.html#accountroot">AccountRoot node</a>, similar to the <a href="#account-info">account_info</a> command</li>
|
<li><code>account_root</code> - Retrieve an <a href="reference-ledger-format.html#accountroot">AccountRoot node</a>, similar to the <a href="#account-info">account_info</a> command</li>
|
||||||
<li><code>directory</code> - Retrieve a <a href="ripple-ledger.html#directorynode">DirectoryNode</a>, which contains a list of other nodes</li>
|
<li><code>directory</code> - Retrieve a <a href="reference-ledger-format.html#directorynode">DirectoryNode</a>, which contains a list of other nodes</li>
|
||||||
<li><code>offer</code> - Retrieve an <a href="ripple-ledger.html#offer">Offer node</a>, which defines an offer to exchange currency</li>
|
<li><code>offer</code> - Retrieve an <a href="reference-ledger-format.html#offer">Offer node</a>, which defines an offer to exchange currency</li>
|
||||||
<li><code>ripple_state</code> - Retrieve a <a href="ripple-ledger.html#ripplestate">RippleState node</a>, which tracks a (non-XRP) currency balance between two accounts.</li>
|
<li><code>ripple_state</code> - Retrieve a <a href="reference-ledger-format.html#ripplestate">RippleState node</a>, which tracks a (non-XRP) currency balance between two accounts.</li>
|
||||||
</ol>
|
</ol>
|
||||||
<p>If you specify more than one of the above items, the server will retrieve only of them; it is undefined which one will be chosen.</p>
|
<p>If you specify more than one of the above items, the server will retrieve only of them; it is undefined which one will be chosen.</p>
|
||||||
<p>The full list of parameters recognized by this method is as follows:</p>
|
<p>The full list of parameters recognized by this method is as follows:</p>
|
||||||
@@ -4311,17 +4317,17 @@ rippled ledger_current
|
|||||||
<tr>
|
<tr>
|
||||||
<td>account_root</td>
|
<td>account_root</td>
|
||||||
<td>String - <a href="#addresses">Address</a></td>
|
<td>String - <a href="#addresses">Address</a></td>
|
||||||
<td>(Optional) Specify an <a href="ripple-ledger.html#accountroot">AccountRoot node</a> to retrieve.</td>
|
<td>(Optional) Specify an <a href="reference-ledger-format.html#accountroot">AccountRoot node</a> to retrieve.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>directory</td>
|
<td>directory</td>
|
||||||
<td>Object or String</td>
|
<td>Object or String</td>
|
||||||
<td>(Optional) Specify a <a href="ripple-ledger.html#directorynode">DirectoryNode</a>. (Directory nodes each contain a list of IDs for things contained in them.) If a string, interpret as the <a href="ripple-ledger.html#tree-format">unique index</a> to the directory, in hex. If an object, requires either <code>dir_root</code> or <code>owner</code> as a sub-field, plus optionally a <code>sub_index</code> sub-field.</td>
|
<td>(Optional) Specify a <a href="reference-ledger-format.html#directorynode">DirectoryNode</a>. (Directory nodes each contain a list of IDs for things contained in them.) If a string, interpret as the <a href="reference-ledger-format.html#tree-format">unique index</a> to the directory, in hex. If an object, requires either <code>dir_root</code> or <code>owner</code> as a sub-field, plus optionally a <code>sub_index</code> sub-field.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>directory.sub_index</td>
|
<td>directory.sub_index</td>
|
||||||
<td>Unsigned Integer</td>
|
<td>Unsigned Integer</td>
|
||||||
<td>(Optional) If provided, jumps to a further sub-node in the <a href="ripple-ledger.html#directorynode">DirectoryNode</a>.</td>
|
<td>(Optional) If provided, jumps to a further sub-node in the <a href="reference-ledger-format.html#directorynode">DirectoryNode</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>directory.dir_root</td>
|
<td>directory.dir_root</td>
|
||||||
@@ -4336,7 +4342,7 @@ rippled ledger_current
|
|||||||
<tr>
|
<tr>
|
||||||
<td>offer</td>
|
<td>offer</td>
|
||||||
<td>Object or String</td>
|
<td>Object or String</td>
|
||||||
<td>(Optional) Specify an <a href="ripple-ledger.html#offer">Offer node</a> to retrieve. If a string, interpret as the <a href="ripple-ledger.html#tree-format">unique index</a> to the Offer. If an object, requires the sub-fields <code>account</code> and <code>seq</code> to uniquely identify the offer.</td>
|
<td>(Optional) Specify an <a href="reference-ledger-format.html#offer">Offer node</a> to retrieve. If a string, interpret as the <a href="reference-ledger-format.html#tree-format">unique index</a> to the Offer. If an object, requires the sub-fields <code>account</code> and <code>seq</code> to uniquely identify the offer.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>offer.account</td>
|
<td>offer.account</td>
|
||||||
@@ -4356,12 +4362,12 @@ rippled ledger_current
|
|||||||
<tr>
|
<tr>
|
||||||
<td>ripple_state.accounts</td>
|
<td>ripple_state.accounts</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>(Required if <code>ripple_state</code> specified) 2-length array of account <a href="#addresses">Address</a>es, defining the two accounts linked by this <a href="ripple-ledger.html#ripplestate">RippleState node</a></td>
|
<td>(Required if <code>ripple_state</code> specified) 2-length array of account <a href="#addresses">Address</a>es, defining the two accounts linked by this <a href="reference-ledger-format.html#ripplestate">RippleState node</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>ripple_state.currency</td>
|
<td>ripple_state.currency</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>(Required if <code>ripple_state</code> specified) <a href="#currency-codes">Currency Code</a> of the <a href="ripple-ledger.html#ripplestate">RippleState node</a> to retrieve.</td>
|
<td>(Required if <code>ripple_state</code> specified) <a href="#currency-codes">Currency Code</a> of the <a href="reference-ledger-format.html#ripplestate">RippleState node</a> to retrieve.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>binary</td>
|
<td>binary</td>
|
||||||
@@ -4451,7 +4457,7 @@ rippled ledger_current
|
|||||||
<tr>
|
<tr>
|
||||||
<td>node</td>
|
<td>node</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td>(Omitted if <code>"binary": true</code> specified.) Object containing the data of this ledger node, according to the <a href="ripple-ledger.html">ledger format</a>.</td>
|
<td>(Omitted if <code>"binary": true</code> specified.) Object containing the data of this ledger node, according to the <a href="reference-ledger-format.html">ledger format</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>node_binary</td>
|
<td>node_binary</td>
|
||||||
@@ -4609,7 +4615,7 @@ Connecting to 127.0.0.1:5005
|
|||||||
<ol>
|
<ol>
|
||||||
<li>When returning a <code>lgrNotFound</code> error, the response has a field, <code>acquiring</code> with a <a href="#ledger-request-object">Ledger Request Object</a> indicating the progress of fetching the ledger from the peer-to-peer network.</li>
|
<li>When returning a <code>lgrNotFound</code> error, the response has a field, <code>acquiring</code> with a <a href="#ledger-request-object">Ledger Request Object</a> indicating the progress of fetching the ledger from the peer-to-peer network.</li>
|
||||||
<li>When the response represents an in-progress attempt to acquire the ledger, the body of the result is a <a href="#ledger-request-object">Ledger Request Object</a> indicating the progress of fetching the ledger from the peer-to-peer network.</li>
|
<li>When the response represents an in-progress attempt to acquire the ledger, the body of the result is a <a href="#ledger-request-object">Ledger Request Object</a> indicating the progress of fetching the ledger from the peer-to-peer network.</li>
|
||||||
<li>When the ledger is fully available, the response is a representation of the <a href="ripple-ledger.html#header-format">ledger header</a>.</li>
|
<li>When the ledger is fully available, the response is a representation of the <a href="reference-ledger-format.html#header-format">ledger header</a>.</li>
|
||||||
</ol>
|
</ol>
|
||||||
<h4 id="ledger-request-object">Ledger Request Object</h4>
|
<h4 id="ledger-request-object">Ledger Request Object</h4>
|
||||||
<p>When the server is in the progress of fetching a ledger, but has not yet finished, the <code>rippled</code> server returns a ledger request object indicating its progress towards fetching the ledger. This object has the following fields:</p>
|
<p>When the server is in the progress of fetching a ledger, but has not yet finished, the <code>rippled</code> server returns a ledger request object indicating its progress towards fetching the ledger. This object has the following fields:</p>
|
||||||
@@ -4635,7 +4641,7 @@ Connecting to 127.0.0.1:5005
|
|||||||
<tr>
|
<tr>
|
||||||
<td>have_state</td>
|
<td>have_state</td>
|
||||||
<td>Boolean</td>
|
<td>Boolean</td>
|
||||||
<td>(May be omitted) Whether the server has the <a href="ripple-ledger.html#tree-format">account-state section</a> of the requested ledger.</td>
|
<td>(May be omitted) Whether the server has the <a href="reference-ledger-format.html#tree-format">account-state section</a> of the requested ledger.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>have_transactions</td>
|
<td>have_transactions</td>
|
||||||
@@ -4645,7 +4651,7 @@ Connecting to 127.0.0.1:5005
|
|||||||
<tr>
|
<tr>
|
||||||
<td>needed_state_hashes</td>
|
<td>needed_state_hashes</td>
|
||||||
<td>Array of Strings</td>
|
<td>Array of Strings</td>
|
||||||
<td>(May be omitted) Up to 16 hashes of nodes in the <a href="ripple-ledger.html#tree-format">state tree</a> that the server still needs to retrieve.</td>
|
<td>(May be omitted) Up to 16 hashes of nodes in the <a href="reference-ledger-format.html#tree-format">state tree</a> that the server still needs to retrieve.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>needed_transaction_hashes</td>
|
<td>needed_transaction_hashes</td>
|
||||||
@@ -4908,7 +4914,7 @@ rippled tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 fals
|
|||||||
}
|
}
|
||||||
</code></pre>
|
</code></pre>
|
||||||
</div>
|
</div>
|
||||||
<p>The response follows the <a href="#response-formatting">standard format</a>, with a successful result containing the fields of the <a href="transactions.html">Transaction object</a> as well as the following additional fields:</p>
|
<p>The response follows the <a href="#response-formatting">standard format</a>, with a successful result containing the fields of the <a href="reference-transaction-format.html">Transaction object</a> as well as the following additional fields:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -4946,7 +4952,7 @@ rippled tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 fals
|
|||||||
<tr>
|
<tr>
|
||||||
<td>(Various)</td>
|
<td>(Various)</td>
|
||||||
<td>(Various)</td>
|
<td>(Various)</td>
|
||||||
<td>Other fields from the <a href="transactions.html">Transaction object</a></td>
|
<td>Other fields from the <a href="reference-transaction-format.html">Transaction object</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -5174,7 +5180,7 @@ rippled transaction_entry E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDA
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tx_json</td>
|
<td>tx_json</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td>JSON representation of the <a href="transactions.html">Transaction object</a></td>
|
<td>JSON representation of the <a href="reference-transaction-format.html">Transaction object</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -6080,7 +6086,7 @@ rippled tx_history 0
|
|||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>The fields included in each transaction object vary slightly depending on the type of transaction. See <a href="transactions.html">Transaction Format</a> for details.</p>
|
<p>The fields included in each transaction object vary slightly depending on the type of transaction. See <a href="reference-transaction-format.html">Transaction Format</a> for details.</p>
|
||||||
<h4 id="possible-errors-18">Possible Errors</h4>
|
<h4 id="possible-errors-18">Possible Errors</h4>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Any of the <a href="#universal-errors">universal error types</a>.</li>
|
<li>Any of the <a href="#universal-errors">universal error types</a>.</li>
|
||||||
@@ -6089,7 +6095,7 @@ rippled tx_history 0
|
|||||||
</ul>
|
</ul>
|
||||||
<h2 id="path-find">path_find</h2>
|
<h2 id="path-find">path_find</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p><em>WebSocket API only!</em> The <code>path_find</code> method searches for a <a href="paths.html">path</a> along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see <a href="#ripple-path-find"><code>ripple_path_find</code></a>. For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account. </p>
|
<p><em>WebSocket API only!</em> The <code>path_find</code> method searches for a <a href="concept-paths.html">path</a> along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see <a href="#ripple-path-find"><code>ripple_path_find</code></a>. For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account. </p>
|
||||||
<p>There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the <code>subcommand</code> parameter:</p>
|
<p>There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the <code>subcommand</code> parameter:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li><code>create</code> - Start sending pathfinding information </li>
|
<li><code>create</code> - Start sending pathfinding information </li>
|
||||||
@@ -6158,7 +6164,7 @@ rippled tx_history 0
|
|||||||
<tr>
|
<tr>
|
||||||
<td>paths</td>
|
<td>paths</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>(Optional) Array of arrays of objects, representing <a href="paths.html">payment paths</a> to check. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path.</td>
|
<td>(Optional) Array of arrays of objects, representing <a href="concept-paths.html">payment paths</a> to check. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -6545,7 +6551,7 @@ rippled tx_history 0
|
|||||||
<tr>
|
<tr>
|
||||||
<td>alternatives</td>
|
<td>alternatives</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>Array of objects with suggested <a href="paths.html">paths</a> to take, as described below. If empty, then no paths were found connecting the source and destination accounts.</td>
|
<td>Array of objects with suggested <a href="concept-paths.html">paths</a> to take, as described below. If empty, then no paths were found connecting the source and destination accounts.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>destination_account</td>
|
<td>destination_account</td>
|
||||||
@@ -6587,7 +6593,7 @@ rippled tx_history 0
|
|||||||
<tr>
|
<tr>
|
||||||
<td>paths_computed</td>
|
<td>paths_computed</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>Array of arrays of objects defining <a href="paths.html">payment paths</a></td>
|
<td>Array of arrays of objects defining <a href="concept-paths.html">payment paths</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>source_amount</td>
|
<td>source_amount</td>
|
||||||
@@ -6603,7 +6609,7 @@ rippled tx_history 0
|
|||||||
<li><code>noEvents</code> - You are using a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See <a href="#ripple-path-find">ripple_path_find</a> for a pathfinding method that <em>is</em> compatible with JSON-RPC.)</li>
|
<li><code>noEvents</code> - You are using a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See <a href="#ripple-path-find">ripple_path_find</a> for a pathfinding method that <em>is</em> compatible with JSON-RPC.)</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h4 id="asynchronous-follow-ups">Asynchronous Follow-ups</h4>
|
<h4 id="asynchronous-follow-ups">Asynchronous Follow-ups</h4>
|
||||||
<p>In addition to the initial response, the server sends more messages in a similar format to update on the status of <a href="paths.html">payment paths</a> over time. These messages include the <code>id</code> of the original WebSocket request so you can tell which request prompted them, and the field <code>"type": "path_find"</code> at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response.</p>
|
<p>In addition to the initial response, the server sends more messages in a similar format to update on the status of <a href="concept-paths.html">payment paths</a> over time. These messages include the <code>id</code> of the original WebSocket request so you can tell which request prompted them, and the field <code>"type": "path_find"</code> at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response.</p>
|
||||||
<p>If the follow-up includes <code>"full_reply": true</code>, then this is the best path that rippled can find as of the current ledger.</p>
|
<p>If the follow-up includes <code>"full_reply": true</code>, then this is the best path that rippled can find as of the current ledger.</p>
|
||||||
<p>Here is an example of an asychronous follow-up from a path_find create request:</p>
|
<p>Here is an example of an asychronous follow-up from a path_find create request:</p>
|
||||||
<div class="multicode">
|
<div class="multicode">
|
||||||
@@ -6740,7 +6746,7 @@ rippled tx_history 0
|
|||||||
</ul>
|
</ul>
|
||||||
<h2 id="ripple-path-find">ripple_path_find</h2>
|
<h2 id="ripple-path-find">ripple_path_find</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/RipplePathFind.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/RipplePathFind.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>The <code>ripple_path_find</code> method is a simplified version of <a href="#path-find"><code>path_find</code></a> that provides a single response with a <a href="paths.html">payment path</a> you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making many subsequent calls, you should use <a href="#path-find"><code>path_find</code></a> instead where possible.</p>
|
<p>The <code>ripple_path_find</code> method is a simplified version of <a href="#path-find"><code>path_find</code></a> that provides a single response with a <a href="concept-paths.html">payment path</a> you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making many subsequent calls, you should use <a href="#path-find"><code>path_find</code></a> instead where possible.</p>
|
||||||
<p>Although the <code>rippled</code> server attempts to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths in order to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers operated by different parties, to minimize the risk of a single server returning poor results. (<strong><em>Note:</em></strong> A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.)</p>
|
<p>Although the <code>rippled</code> server attempts to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths in order to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers operated by different parties, to minimize the risk of a single server returning poor results. (<strong><em>Note:</em></strong> A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.)</p>
|
||||||
<h4 id="request-format-22">Request Format</h4>
|
<h4 id="request-format-22">Request Format</h4>
|
||||||
<p>An example of the request format:</p>
|
<p>An example of the request format:</p>
|
||||||
@@ -7098,7 +7104,7 @@ rippled ripple_path_find '{"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59
|
|||||||
<tr>
|
<tr>
|
||||||
<td>paths_computed</td>
|
<td>paths_computed</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>Array of arrays of objects defining <a href="paths.html">payment paths</a></td>
|
<td>Array of arrays of objects defining <a href="concept-paths.html">payment paths</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>source_amount</td>
|
<td>source_amount</td>
|
||||||
@@ -7185,7 +7191,7 @@ rippled sign sssssssssssssssssssssssssssss '{"TransactionType": "Payment", "Acco
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tx_json</td>
|
<td>tx_json</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td><a href="transactions.html">Transaction definition</a> in JSON format</td>
|
<td><a href="reference-transaction-format.html">Transaction definition</a> in JSON format</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>secret</td>
|
<td>secret</td>
|
||||||
@@ -7205,19 +7211,19 @@ rippled sign sssssssssssssssssssssssssssss '{"TransactionType": "Payment", "Acco
|
|||||||
<tr>
|
<tr>
|
||||||
<td>fee_mult_max</td>
|
<td>fee_mult_max</td>
|
||||||
<td>Integer</td>
|
<td>Integer</td>
|
||||||
<td>(Optional) If the <code>Fee</code> parameter (<a href="tx-cost.html">transaction cost</a>) is omitted, this field limits the automatically-provided value so that it is less than or equal to the base transaction cost times this value.</td>
|
<td>(Optional) If the <code>Fee</code> parameter (<a href="concept-transaction-cost.html">transaction cost</a>) is omitted, this field limits the automatically-provided value so that it is less than or equal to the base transaction cost times this value.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>fee_div_max</td>
|
<td>fee_div_max</td>
|
||||||
<td>Integer</td>
|
<td>Integer</td>
|
||||||
<td>(Optional) Used with <code>fee_mult_max</code> to create a fractional multiplier for the limit. Specifically, the server multiplies its base <a href="tx-cost.html">transaction cost</a> by <code>fee_mult_max</code>, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided <code>Fee</code> value would be over the limit, signing fails. <em>(New in <a href="https://wiki.ripple.com/Rippled-0.30.1">version 0.30.1</a>)</em></td>
|
<td>(Optional) Used with <code>fee_mult_max</code> to create a fractional multiplier for the limit. Specifically, the server multiplies its base <a href="concept-transaction-cost.html">transaction cost</a> by <code>fee_mult_max</code>, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided <code>Fee</code> value would be over the limit, signing fails. <em>(New in <a href="https://wiki.ripple.com/Rippled-0.30.1">version 0.30.1</a>)</em></td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>The server automatically attempts to fill in certain fields from the <code>tx_json</code> object if they are omitted, unless you specified <code>offline</code> as true. Otherwise, the following fields from the <a href="transactions.html">transaction format</a> are automatically filled in:</p>
|
<p>The server automatically attempts to fill in certain fields from the <code>tx_json</code> object if they are omitted, unless you specified <code>offline</code> as true. Otherwise, the following fields from the <a href="reference-transaction-format.html">transaction format</a> are automatically filled in:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li><code>Sequence</code> - The server automatically uses the next Sequence number from the sender's account information. Be careful: the next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must provide the correct sequence numbers in the request. Automatically filled unless <code>offline</code> is true.</li>
|
<li><code>Sequence</code> - The server automatically uses the next Sequence number from the sender's account information. Be careful: the next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must provide the correct sequence numbers in the request. Automatically filled unless <code>offline</code> is true.</li>
|
||||||
<li><code>Fee</code> - If you omit the <code>Fee</code> parameter, the server <a href="tx-cost.html#automatically-specifying-the-transaction-cost">automatically provides an appropriate transaction cost</a> unless you specified <code>offline</code> as true. If you specify <code>offline</code> as true, you must fill in the transaction cost in the <code>Fee</code> parameter. Be careful: a malicious server can specify an excessively high transaction cost.<ul>
|
<li><code>Fee</code> - If you omit the <code>Fee</code> parameter, the server <a href="concept-transaction-cost.html#automatically-specifying-the-transaction-cost">automatically provides an appropriate transaction cost</a> unless you specified <code>offline</code> as true. If you specify <code>offline</code> as true, you must fill in the transaction cost in the <code>Fee</code> parameter. Be careful: a malicious server can specify an excessively high transaction cost.<ul>
|
||||||
<li>If <code>fee_mult_max</code> is included, and the automatically provided <code>Fee</code> value is greater than the long-term base transaction cost times <code>fee_mult_max</code>, then the transaction fails with the error <code>rpcHIGH_FEE</code>. This way, you can let the server fill in the current minimum <code>Fee</code> value as long as the current load-based transaction cost is not too high.</li>
|
<li>If <code>fee_mult_max</code> is included, and the automatically provided <code>Fee</code> value is greater than the long-term base transaction cost times <code>fee_mult_max</code>, then the transaction fails with the error <code>rpcHIGH_FEE</code>. This way, you can let the server fill in the current minimum <code>Fee</code> value as long as the current load-based transaction cost is not too high.</li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
@@ -7296,7 +7302,7 @@ rippled sign sssssssssssssssssssssssssssss '{"TransactionType": "Payment", "Acco
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tx_json</td>
|
<td>tx_json</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td>JSON specification of the <a href="transactions.html">complete transaction</a> as signed, including any fields that were automatically filled in</td>
|
<td>JSON specification of the <a href="reference-transaction-format.html">complete transaction</a> as signed, including any fields that were automatically filled in</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -7316,7 +7322,7 @@ rippled sign sssssssssssssssssssssssssssss '{"TransactionType": "Payment", "Acco
|
|||||||
</ul>
|
</ul>
|
||||||
<h2 id="submit">submit</h2>
|
<h2 id="submit">submit</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Submit.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Submit.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>The <code>submit</code> method sends a <a href="transactions.html">transaction</a> to the network to be confirmed and included in future ledgers. </p>
|
<p>The <code>submit</code> method sends a <a href="reference-transaction-format.html">transaction</a> to the network to be confirmed and included in future ledgers. </p>
|
||||||
<p>This command has two modes:</p>
|
<p>This command has two modes:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Submit-only mode takes a signed, serialized transaction as a binary blob, and submits it to the network as-is. Since signed transaction objects are immutable, no portion of the transaction can be modified or automatically filled in after submission.</li>
|
<li>Submit-only mode takes a signed, serialized transaction as a binary blob, and submits it to the network as-is. Since signed transaction objects are immutable, no portion of the transaction can be modified or automatically filled in after submission.</li>
|
||||||
@@ -7385,7 +7391,7 @@ submit 1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tx_json</td>
|
<td>tx_json</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td><a href="transactions.html">Transaction definition</a> in JSON format, optionally omitting any auto-fillable fields.</td>
|
<td><a href="reference-transaction-format.html">Transaction definition</a> in JSON format, optionally omitting any auto-fillable fields.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>secret</td>
|
<td>secret</td>
|
||||||
@@ -7415,7 +7421,7 @@ submit 1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534
|
|||||||
<tr>
|
<tr>
|
||||||
<td>fee_div_max</td>
|
<td>fee_div_max</td>
|
||||||
<td>Integer</td>
|
<td>Integer</td>
|
||||||
<td>(Optional) Used with <code>fee_mult_max</code> to create a fractional multiplier for the limit. Specifically, the server multiplies its base <a href="tx-cost.html">transaction cost</a> by <code>fee_mult_max</code>, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided <code>Fee</code> value would be over the limit, the submit command fails. <em>(New in <a href="https://wiki.ripple.com/Rippled-0.30.1">version 0.30.1</a>)</em></td>
|
<td>(Optional) Used with <code>fee_mult_max</code> to create a fractional multiplier for the limit. Specifically, the server multiplies its base <a href="concept-transaction-cost.html">transaction cost</a> by <code>fee_mult_max</code>, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided <code>Fee</code> value would be over the limit, the submit command fails. <em>(New in <a href="https://wiki.ripple.com/Rippled-0.30.1">version 0.30.1</a>)</em></td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -7563,7 +7569,7 @@ submit sssssssssssssssssssssssssssss '{"TransactionType":"Payment", "Account":"r
|
|||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p><strong><em>Caution:</em></strong> Even if the WebSocket response has <code>"status":"success"</code>, indicating that the command was successfully received, that does not necessarily indicate that the transaction has taken place. There are many cases that can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the network since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the <a href="transactions.html#full-transaction-response-list">full list of transaction responses</a> for details, and do not consider the transaction's results final until they appear in a validated ledger version.</p>
|
<p><strong><em>Caution:</em></strong> Even if the WebSocket response has <code>"status":"success"</code>, indicating that the command was successfully received, that does not necessarily indicate that the transaction has taken place. There are many cases that can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the network since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the <a href="reference-transaction-format.html#full-transaction-response-list">full list of transaction responses</a> for details, and do not consider the transaction's results final until they appear in a validated ledger version.</p>
|
||||||
<p><strong><em>Caution:</em></strong> If this command results in an error messages, the message can contain an account secret, if one was provided in the request. (This is not a problem if the request contained a signed tx_blob instead.) Make sure that these errors are not visible to others, including:</p>
|
<p><strong><em>Caution:</em></strong> If this command results in an error messages, the message can contain an account secret, if one was provided in the request. (This is not a problem if the request contained a signed tx_blob instead.) Make sure that these errors are not visible to others, including:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Do not write an error including your secret to a log file that can be seen by multiple people</li>
|
<li>Do not write an error including your secret to a log file that can be seen by multiple people</li>
|
||||||
@@ -7771,7 +7777,7 @@ rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6
|
|||||||
<tr>
|
<tr>
|
||||||
<td>offers</td>
|
<td>offers</td>
|
||||||
<td>Array</td>
|
<td>Array</td>
|
||||||
<td>Array of offer objects, each of which has the fields of an <a href="transactions.html#offercreate">OfferCreate transaction</a></td>
|
<td>Array of offer objects, each of which has the fields of an <a href="reference-transaction-format.html#offercreate">OfferCreate transaction</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -7909,7 +7915,7 @@ rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6
|
|||||||
<li><code>server</code> - Sends a message whenever the status of the <code>rippled</code> server (for example, network connectivity) changes</li>
|
<li><code>server</code> - Sends a message whenever the status of the <code>rippled</code> server (for example, network connectivity) changes</li>
|
||||||
<li><code>ledger</code> - Sends a message whenever the consensus process declares a new validated ledger</li>
|
<li><code>ledger</code> - Sends a message whenever the consensus process declares a new validated ledger</li>
|
||||||
<li><code>transactions</code> - Sends a message whenever a transaction is included in a closed ledger</li>
|
<li><code>transactions</code> - Sends a message whenever a transaction is included in a closed ledger</li>
|
||||||
<li><code>transactions_proposed</code> - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation, however. (<strong><em>Note:</em></strong> <a href="transactions.html#result-categories">Even some transactions that don't succeed are included</a> in validated ledgers, because they take the anti-spam transaction fee.)</li>
|
<li><code>transactions_proposed</code> - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation, however. (<strong><em>Note:</em></strong> <a href="reference-transaction-format.html#result-categories">Even some transactions that don't succeed are included</a> in validated ledgers, because they take the anti-spam transaction fee.)</li>
|
||||||
<li><code>validations</code> - Sends a message whenever the server receives a validation message from a server it trusts. (An individual <code>rippled</code> declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.)</li>
|
<li><code>validations</code> - Sends a message whenever the server receives a validation message from a server it trusts. (An individual <code>rippled</code> declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.)</li>
|
||||||
<li><code>peer_status</code> - <strong>(Admin only)</strong> Information about connected peer <code>rippled</code> servers, especially with regards to the consensus process.</li>
|
<li><code>peer_status</code> - <strong>(Admin only)</strong> Information about connected peer <code>rippled</code> servers, especially with regards to the consensus process.</li>
|
||||||
</ul>
|
</ul>
|
||||||
@@ -8018,7 +8024,7 @@ rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6
|
|||||||
<tr>
|
<tr>
|
||||||
<td>fee_base</td>
|
<td>fee_base</td>
|
||||||
<td>Unsigned Integer</td>
|
<td>Unsigned Integer</td>
|
||||||
<td>Cost of the 'reference transaction' in drops of XRP. (See <a href="tx-cost.html">Transaction Cost</a> If the ledger includes a <a href="transactions.html#setfee">SetFee pseudo-transaction</a> the new transaction cost applies to all transactions after this ledger.</td>
|
<td>Cost of the 'reference transaction' in drops of XRP. (See <a href="concept-transaction-cost.html">Transaction Cost</a> If the ledger includes a <a href="reference-transaction-format.html#setfee">SetFee pseudo-transaction</a> the new transaction cost applies to all transactions after this ledger.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>fee_ref</td>
|
<td>fee_ref</td>
|
||||||
@@ -8043,12 +8049,12 @@ rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6
|
|||||||
<tr>
|
<tr>
|
||||||
<td>reserve_base</td>
|
<td>reserve_base</td>
|
||||||
<td>Unsigned Integer</td>
|
<td>Unsigned Integer</td>
|
||||||
<td>The minimum reserve, in drops of XRP, that is required for an account. If the ledger includes a <a href="transactions.html#setfee">SetFee pseudo-transaction</a> the new base reserve applies after this ledger.</td>
|
<td>The minimum reserve, in drops of XRP, that is required for an account. If the ledger includes a <a href="reference-transaction-format.html#setfee">SetFee pseudo-transaction</a> the new base reserve applies after this ledger.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>reserve_inc</td>
|
<td>reserve_inc</td>
|
||||||
<td>Unsigned Integer</td>
|
<td>Unsigned Integer</td>
|
||||||
<td>The increase in account reserve that is added for each item the account owns, such as offers or trust lines. If the ledger includes a <a href="transactions.html#setfee">SetFee pseudo-transaction</a> the new owner reserve applies after this ledger.</td>
|
<td>The increase in account reserve that is added for each item the account owns, such as offers or trust lines. If the ledger includes a <a href="reference-transaction-format.html#setfee">SetFee pseudo-transaction</a> the new owner reserve applies after this ledger.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>txn_count</td>
|
<td>txn_count</td>
|
||||||
@@ -8237,12 +8243,12 @@ rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6
|
|||||||
<tr>
|
<tr>
|
||||||
<td>engine_result</td>
|
<td>engine_result</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>String <a href="transactions.html#result-categories">Transaction result code</a></td>
|
<td>String <a href="reference-transaction-format.html#result-categories">Transaction result code</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>engine_result_code</td>
|
<td>engine_result_code</td>
|
||||||
<td>Number</td>
|
<td>Number</td>
|
||||||
<td>Numeric <a href="transactions.html#result-categories">transaction response code</a>, if applicable.</td>
|
<td>Numeric <a href="reference-transaction-format.html#result-categories">transaction response code</a>, if applicable.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>engine_result_message</td>
|
<td>engine_result_message</td>
|
||||||
@@ -8272,7 +8278,7 @@ rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6
|
|||||||
<tr>
|
<tr>
|
||||||
<td>transaction</td>
|
<td>transaction</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td>The <a href="transactions.html">definition of the transaction</a> in JSON format</td>
|
<td>The <a href="reference-transaction-format.html">definition of the transaction</a> in JSON format</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>validated</td>
|
<td>validated</td>
|
||||||
@@ -8508,7 +8514,7 @@ rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6
|
|||||||
<tr>
|
<tr>
|
||||||
<td>transaction.owner_funds</td>
|
<td>transaction.owner_funds</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>Numeric amount of the <code>TakerGets</code> currency that the <code>Account</code> sending this OfferCreate transaction has after executing this transaction. This does not check whether the currency amount is <a href="freeze.html">frozen</a>.</td>
|
<td>Numeric amount of the <code>TakerGets</code> currency that the <code>Account</code> sending this OfferCreate transaction has after executing this transaction. This does not check whether the currency amount is <a href="concept-freeze.html">frozen</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -10305,7 +10311,7 @@ Connecting to 127.0.0.1:5005
|
|||||||
</ul>
|
</ul>
|
||||||
<h2 id="validation-create">validation_create</h2>
|
<h2 id="validation-create">validation_create</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/315a8b6b602798a4cff4d8e1911936011e12abdb/src/ripple/rpc/handlers/ValidationCreate.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/315a8b6b602798a4cff4d8e1911936011e12abdb/src/ripple/rpc/handlers/ValidationCreate.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>Use the <code>validation_create</code> command to generate the keys for a rippled <a href="rippled-setup.html#validator-setup">validating node</a>. Similar to the <a href="#wallet-propose">wallet_propose</a> command, this command makes no real changes, but only generates a set of keys in the proper format.</p>
|
<p>Use the <code>validation_create</code> command to generate the keys for a rippled <a href="tutorial-rippled-setup.html#validator-setup">validating node</a>. Similar to the <a href="#wallet-propose">wallet_propose</a> command, this command makes no real changes, but only generates a set of keys in the proper format.</p>
|
||||||
<p><em>The <code>validation_create</code> method is an <a href="#connecting-to-rippled">admin command</a> that cannot be run by unpriviledged users.</em></p>
|
<p><em>The <code>validation_create</code> method is an <a href="#connecting-to-rippled">admin command</a> that cannot be run by unpriviledged users.</em></p>
|
||||||
<h4 id="request-format-38">Request Format</h4>
|
<h4 id="request-format-38">Request Format</h4>
|
||||||
<p>An example of the request format:</p>
|
<p>An example of the request format:</p>
|
||||||
@@ -10863,7 +10869,7 @@ Connecting to 127.0.0.1:5005
|
|||||||
<tr>
|
<tr>
|
||||||
<td>cluster</td>
|
<td>cluster</td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td>Summary of other <code>rippled</code> servers in the same cluster, if <a href="rippled-setup.html#clustering">configured as a cluster</a>. <em>(New in <a href="https://wiki.ripple.com/Rippled-0.30.1">version 0.30.1</a>)</em></td>
|
<td>Summary of other <code>rippled</code> servers in the same cluster, if <a href="tutorial-rippled-setup.html#clustering">configured as a cluster</a>. <em>(New in <a href="https://wiki.ripple.com/Rippled-0.30.1">version 0.30.1</a>)</em></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>peers</td>
|
<td>peers</td>
|
||||||
@@ -10890,7 +10896,7 @@ Connecting to 127.0.0.1:5005
|
|||||||
<tr>
|
<tr>
|
||||||
<td>fee</td>
|
<td>fee</td>
|
||||||
<td>Number</td>
|
<td>Number</td>
|
||||||
<td>(May be omitted) The load multiplier this cluster member is applying to the <a href="tx-cost.html">transaction cost</a></td>
|
<td>(May be omitted) The load multiplier this cluster member is applying to the <a href="concept-transaction-cost.html">transaction cost</a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>age</td>
|
<td>age</td>
|
||||||
@@ -5,7 +5,7 @@
|
|||||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||||||
<meta name="viewport" content="width=device-width">
|
<meta name="viewport" content="width=device-width">
|
||||||
|
|
||||||
<title>Transactions - Ripple Developer Portal</title>
|
<title>Transaction Format - Ripple Developer Portal</title>
|
||||||
|
|
||||||
<!-- favicon -->
|
<!-- favicon -->
|
||||||
<link rel="icon" href="favicon.ico" type="image/x-icon">
|
<link rel="icon" href="favicon.ico" type="image/x-icon">
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -170,17 +176,17 @@
|
|||||||
<ol>
|
<ol>
|
||||||
<li>Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection.</li>
|
<li>Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection.</li>
|
||||||
<li><a href="https://github.com/ripple/ripple-lib">ripple-lib</a> has an implementation of offline signing.</li>
|
<li><a href="https://github.com/ripple/ripple-lib">ripple-lib</a> has an implementation of offline signing.</li>
|
||||||
<li>Have a <code>rippled</code> server sign the transaction for you. The <a href="rippled-apis.html#sign">sign command</a> takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted sub-net, to a server you control.)</li>
|
<li>Have a <code>rippled</code> server sign the transaction for you. The <a href="reference-rippled.html#sign">sign command</a> takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted sub-net, to a server you control.)</li>
|
||||||
<li>As a shortcut, you can use the <a href="rippled-apis.html#submit">submit command</a> with a <code>tx_json</code> object to sign and submit a transaction all at once. This is only recommended for testing and development purposes.</li>
|
<li>As a shortcut, you can use the <a href="reference-rippled.html#submit">submit command</a> with a <code>tx_json</code> object to sign and submit a transaction all at once. This is only recommended for testing and development purposes.</li>
|
||||||
</ol>
|
</ol>
|
||||||
<p>In either case, signing a transaction generates a binary blob that can be submitted to the network. This means using <code>rippled</code>'s <a href="rippled-apis.html#submit">submit command</a>. Here is an example of the same transaction, as a signed blob, being submitted with the WebSocket API:</p>
|
<p>In either case, signing a transaction generates a binary blob that can be submitted to the network. This means using <code>rippled</code>'s <a href="reference-rippled.html#submit">submit command</a>. Here is an example of the same transaction, as a signed blob, being submitted with the WebSocket API:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"id": 2,
|
"id": 2,
|
||||||
"command": "submit",
|
"command": "submit",
|
||||||
"tx_blob" : "120000240000000461D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000F732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74483046022100982064CDD3F052D22788DB30B52EEA8956A32A51375E72274E417328EBA31E480221008F522C9DB4B0F31E695AA013843958A10DE8F6BA7D6759BEE645F71A7EB240BE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754"
|
"tx_blob" : "120000240000000461D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000F732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74483046022100982064CDD3F052D22788DB30B52EEA8956A32A51375E72274E417328EBA31E480221008F522C9DB4B0F31E695AA013843958A10DE8F6BA7D6759BEE645F71A7EB240BE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754"
|
||||||
}
|
}
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<p>After a transaction has been submitted, if it gets accepted into a validated ledger, you can view the final transaction using the API. For example, here is what the WebSocket API <a href="rippled-apis.html#tx">tx command</a> shows for the same transaction. The field names that begin with capital letters are part of the ledger object; the fields that begin with lower-case letters are additional information generated by the server for the request:</p>
|
<p>After a transaction has been submitted, if it gets accepted into a validated ledger, you can view the final transaction using the API. For example, here is what the WebSocket API <a href="reference-rippled.html#tx">tx command</a> shows for the same transaction. The field names that begin with capital letters are part of the ledger object; the fields that begin with lower-case letters are additional information generated by the server for the request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"id": 6,
|
"id": 6,
|
||||||
"status": "success",
|
"status": "success",
|
||||||
@@ -281,9 +287,9 @@
|
|||||||
<li>Confirm that the transaction was either included in a validated ledger, or that it has expired due to <code>LastLedgerSequence</code>. </li>
|
<li>Confirm that the transaction was either included in a validated ledger, or that it has expired due to <code>LastLedgerSequence</code>. </li>
|
||||||
<li>If a transaction fails or expires, you can modify and resubmit it.</li>
|
<li>If a transaction fails or expires, you can modify and resubmit it.</li>
|
||||||
</ol>
|
</ol>
|
||||||
<p>Main article: <a href="reliable_tx.html">Reliable Transaction Submission</a></p>
|
<p>Main article: <a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></p>
|
||||||
<h3 id="identifying-transactions">Identifying Transactions</h3>
|
<h3 id="identifying-transactions">Identifying Transactions</h3>
|
||||||
<p>The <code>"hash"</code> is the unique value that identifies a particular transaction. The server provides the hash in the response when you submit the transaction; you can also look up a transaction in an account's transaction history with the <a href="rippled-apis.html#account-tx">account_tx command</a>.</p>
|
<p>The <code>"hash"</code> is the unique value that identifies a particular transaction. The server provides the hash in the response when you submit the transaction; you can also look up a transaction in an account's transaction history with the <a href="reference-rippled.html#account-tx">account_tx command</a>.</p>
|
||||||
<p>The transaction hash can be used as a "proof of payment" since anyone can <a href="#looking-up-transaction-results">look up the transaction by its hash</a> in order to verify its final status.</p>
|
<p>The transaction hash can be used as a "proof of payment" since anyone can <a href="#looking-up-transaction-results">look up the transaction by its hash</a> in order to verify its final status.</p>
|
||||||
<h2 id="common-fields">Common Fields</h2>
|
<h2 id="common-fields">Common Fields</h2>
|
||||||
<p>Every transaction type has the same set of fundamental fields:</p>
|
<p>Every transaction type has the same set of fundamental fields:</p>
|
||||||
@@ -369,14 +375,14 @@
|
|||||||
<h3 id="auto-fillable-fields">Auto-fillable Fields</h3>
|
<h3 id="auto-fillable-fields">Auto-fillable Fields</h3>
|
||||||
<p>Some fields can be automatically filled in before the transaction is signed, either by a <code>rippled</code> server or by the library used for offline signing. Both <a href="https://github.com/ripple/ripple-lib">ripple-lib</a> and <code>rippled</code> can automatically provide the following values:</p>
|
<p>Some fields can be automatically filled in before the transaction is signed, either by a <code>rippled</code> server or by the library used for offline signing. Both <a href="https://github.com/ripple/ripple-lib">ripple-lib</a> and <code>rippled</code> can automatically provide the following values:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li><code>Fee</code> - Automatically fill in the <a href="tx-cost.html">transaction cost</a> based on the network. (<em>Note:</em> <code>rippled</code>'s <a href="rippled-apis.html#sign">sign command</a> supports limits on how high the filled-in-value is, using the <code>fee_mult_max</code> parameter.)</li>
|
<li><code>Fee</code> - Automatically fill in the <a href="concept-transaction-cost.html">transaction cost</a> based on the network. (<em>Note:</em> <code>rippled</code>'s <a href="reference-rippled.html#sign">sign command</a> supports limits on how high the filled-in-value is, using the <code>fee_mult_max</code> parameter.)</li>
|
||||||
<li><code>Sequence</code> - Automatically use the next sequence number for the account sending the transaction.</li>
|
<li><code>Sequence</code> - Automatically use the next sequence number for the account sending the transaction.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>For a production system, we recommend <em>not</em> leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.</p>
|
<p>For a production system, we recommend <em>not</em> leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.</p>
|
||||||
<p>The <a href="#paths"><code>Paths</code> field</a> of the <a href="#payment">Payment</a> transaction type can also be automatically filled in. </p>
|
<p>The <a href="#paths"><code>Paths</code> field</a> of the <a href="#payment">Payment</a> transaction type can also be automatically filled in. </p>
|
||||||
<h3 id="transaction-cost">Transaction Cost</h3>
|
<h3 id="transaction-cost">Transaction Cost</h3>
|
||||||
<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 XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.</p>
|
<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 XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.</p>
|
||||||
<p>The <code>Fee</code> field specifies an amount, in <a href="rippled-apis.html#specifying-currency-amounts">drops of XRP</a>, to destroy as the cost for this transaction. If the transaction is included in a validated leger (whether or not it achieves its intended purpose), then the amount of XRP specified in the <code>Fee</code> parameter is destroyed forever. You can <a href="tx-cost.html#querying-the-transaction-cost">look up the transaction cost</a> in advance, or <a href="tx-cost.html#automatically-specifying-the-transaction-cost">let <code>rippled</code> set it automatically</a> when you sign a transaction.</p>
|
<p>The <code>Fee</code> field specifies an amount, in <a href="reference-rippled.html#specifying-currency-amounts">drops of XRP</a>, to destroy as the cost for this transaction. If the transaction is included in a validated leger (whether or not it achieves its intended purpose), then the amount of XRP specified in the <code>Fee</code> parameter is destroyed forever. You can <a href="concept-transaction-cost.html#querying-the-transaction-cost">look up the transaction cost</a> in advance, or <a href="concept-transaction-cost.html#automatically-specifying-the-transaction-cost">let <code>rippled</code> set it automatically</a> when you sign a transaction.</p>
|
||||||
<h3 id="canceling-or-skipping-a-transaction">Canceling or Skipping a Transaction</h3>
|
<h3 id="canceling-or-skipping-a-transaction">Canceling or Skipping a Transaction</h3>
|
||||||
<p>An important and intentional feature of the Ripple Network is that a transaction is final as soon as it has been incorporated in a validated ledger.</p>
|
<p>An important and intentional feature of the Ripple Network is that a transaction is final as soon as it has been incorporated in a validated ledger.</p>
|
||||||
<p>However, if a transaction has not yet been included in a validated ledger, you can effectively cancel it by rendering it invalid. Typically, this means sending another transaction with the same <code>Sequence</code> value from the same account. If you do not want to perform the same transaction again, you can perform an <a href="#accountset">AccountSet</a> transaction with no options.</p>
|
<p>However, if a transaction has not yet been included in a validated ledger, you can effectively cancel it by rendering it invalid. Typically, this means sending another transaction with the same <code>Sequence</code> value from the same account. If you do not want to perform the same transaction again, you can perform an <a href="#accountset">AccountSet</a> transaction with no options.</p>
|
||||||
@@ -384,7 +390,7 @@
|
|||||||
<p>This approach is preferable to renumbering and resubmitting transactions 12 and 13, because it prevents transactions from being effectively duplicated under different sequence numbers.</p>
|
<p>This approach is preferable to renumbering and resubmitting transactions 12 and 13, because it prevents transactions from being effectively duplicated under different sequence numbers.</p>
|
||||||
<p>In this way, an AccountSet transaction with no options is the canonical "<a href="http://en.wikipedia.org/wiki/NOP">no-op</a>" transaction.</p>
|
<p>In this way, an AccountSet transaction with no options is the canonical "<a href="http://en.wikipedia.org/wiki/NOP">no-op</a>" transaction.</p>
|
||||||
<h3 id="lastledgersequence">LastLedgerSequence</h3>
|
<h3 id="lastledgersequence">LastLedgerSequence</h3>
|
||||||
<p>We strongly recommend that you specify the <code>LastLedgerSequence</code> parameter on every transaction. Provide a value of about 3 higher than <a href="rippled-apis.html#ledger">the most recent ledger index</a> to ensure that your transaction is either validated or rejected within a matter of seconds.</p>
|
<p>We strongly recommend that you specify the <code>LastLedgerSequence</code> parameter on every transaction. Provide a value of about 3 higher than <a href="reference-rippled.html#ledger">the most recent ledger index</a> to ensure that your transaction is either validated or rejected within a matter of seconds.</p>
|
||||||
<p>Without the <code>LastLedgerSequence</code> parameter, there is a particular situation that can occur and cause your transaction to be stuck in an undesirable state where it is neither validated nor rejected for a long time. Specifically, if the load-based <a href="#transaction-cost">transaction cost</a> of the network increases after you send a transaction, your transaction may not get propagated enough to be included in a validated ledger, but you would have to pay the (increased) transaction cost in order to send another transaction canceling it. Later, if the transaction cost decreases again, the transaction may become viable again. The <code>LastLedgerSequence</code> places a hard upper limit on how long the transaction can wait to be validated or rejected.</p>
|
<p>Without the <code>LastLedgerSequence</code> parameter, there is a particular situation that can occur and cause your transaction to be stuck in an undesirable state where it is neither validated nor rejected for a long time. Specifically, if the load-based <a href="#transaction-cost">transaction cost</a> of the network increases after you send a transaction, your transaction may not get propagated enough to be included in a validated ledger, but you would have to pay the (increased) transaction cost in order to send another transaction canceling it. Later, if the transaction cost decreases again, the transaction may become viable again. The <code>LastLedgerSequence</code> places a hard upper limit on how long the transaction can wait to be validated or rejected.</p>
|
||||||
<h3 id="accounttxnid">AccountTxnID</h3>
|
<h3 id="accounttxnid">AccountTxnID</h3>
|
||||||
<p>The <code>AccountTxnID</code> field lets you chain your transactions together, so that a current transaction is not valid unless the previous one (by Sequence Number) is also valid and matches the transaction you expected.</p>
|
<p>The <code>AccountTxnID</code> field lets you chain your transactions together, so that a current transaction is not valid unless the previous one (by Sequence Number) is also valid and matches the transaction you expected.</p>
|
||||||
@@ -495,7 +501,7 @@
|
|||||||
<td>Amount</td>
|
<td>Amount</td>
|
||||||
<td>String (XRP)<br/>Object (Otherwise)</td>
|
<td>String (XRP)<br/>Object (Otherwise)</td>
|
||||||
<td>Amount</td>
|
<td>Amount</td>
|
||||||
<td>The amount of currency to deliver. <em>Note:</em> If the <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> is set, this is not the amount actually received. (Formatted as per <a href="rippled-apis.html#specifying-currency-amounts">Specifying Currency Amounts</a>.)</td>
|
<td>The amount of currency to deliver. <em>Note:</em> If the <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> is set, this is not the amount actually received. (Formatted as per <a href="reference-rippled.html#specifying-currency-amounts">Specifying Currency Amounts</a>.)</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>Destination</td>
|
<td>Destination</td>
|
||||||
@@ -525,7 +531,7 @@
|
|||||||
<td>SendMax</td>
|
<td>SendMax</td>
|
||||||
<td>String/Object</td>
|
<td>String/Object</td>
|
||||||
<td>Amount</td>
|
<td>Amount</td>
|
||||||
<td>(Optional) Highest amount of source currency this transaction is allowed to cost, including <a href="transfer_fees.html">transfer fees</a>, exchange rates, and <a href="http://en.wikipedia.org/wiki/Slippage_%28finance%29">slippage</a>. Does not include the <a href="#transaction-cost">XRP destroyed as a cost for submitting the transaction</a>. (Also see <a href="rippled-apis.html#specifying-currency-amounts">Specifying Currency Amounts</a>) Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments.</td>
|
<td>(Optional) Highest amount of source currency this transaction is allowed to cost, including <a href="concept-transfer-fees.html">transfer fees</a>, exchange rates, and <a href="http://en.wikipedia.org/wiki/Slippage_%28finance%29">slippage</a>. Does not include the <a href="#transaction-cost">XRP destroyed as a cost for submitting the transaction</a>. (Also see <a href="reference-rippled.html#specifying-currency-amounts">Specifying Currency Amounts</a>) Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>DeliverMin</td>
|
<td>DeliverMin</td>
|
||||||
@@ -536,14 +542,14 @@
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<h3 id="special-issuer-values-for-sendmax-and-amount">Special issuer Values for SendMax and Amount</h3>
|
<h3 id="special-issuer-values-for-sendmax-and-amount">Special issuer Values for SendMax and Amount</h3>
|
||||||
<p>Most of the time, the <code>issuer</code> field of a non-XRP <a href="rippled-apis.html#specifying-currency-amounts">currency amount</a> indicates the account of the gateway that issues that currency. However, when describing payments, there are special rules for the <code>issuer</code> field in the <code>Amount</code> and <code>SendMax</code> fields of a payment.</p>
|
<p>Most of the time, the <code>issuer</code> field of a non-XRP <a href="reference-rippled.html#specifying-currency-amounts">currency amount</a> indicates the account of the gateway that issues that currency. However, when describing payments, there are special rules for the <code>issuer</code> field in the <code>Amount</code> and <code>SendMax</code> fields of a payment.</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>There is only ever one balance for the same currency between two accounts. This means that, sometimes, the <code>issuer</code> field of an amount actually refers to a counterparty that is redeeming issuances, instead of the account that created the issuances.</li>
|
<li>There is only ever one balance for the same currency between two accounts. This means that, sometimes, the <code>issuer</code> field of an amount actually refers to a counterparty that is redeeming issuances, instead of the account that created the issuances.</li>
|
||||||
<li>When the <code>issuer</code> field of the destination <code>Amount</code> field matches the <code>Destination</code> account address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines. </li>
|
<li>When the <code>issuer</code> field of the destination <code>Amount</code> field matches the <code>Destination</code> account address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines. </li>
|
||||||
<li>When the <code>issuer</code> field of the <code>SendMax</code> field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issuances on trust lines that other accounts have extended to the source account, as well as issuances from other accounts that the source account possesses.</li>
|
<li>When the <code>issuer</code> field of the <code>SendMax</code> field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issuances on trust lines that other accounts have extended to the source account, as well as issuances from other accounts that the source account possesses.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h3 id="creating-accounts">Creating Accounts</h3>
|
<h3 id="creating-accounts">Creating Accounts</h3>
|
||||||
<p>The Payment transaction type is the only way to create new accounts in the shared Ripple ledger. To do so, send an amount of XRP that is equal or greater than the <a href="reserves.html">account reserve</a> to a mathematically-valid account address that does not exist yet. When the payment is processed, a new <a href="ripple-ledger.html#accountroot">AccountRoot node</a> will be added to the ledger to reflect the newly-created account.</p>
|
<p>The Payment transaction type is the only way to create new accounts in the shared Ripple ledger. To do so, send an amount of XRP that is equal or greater than the <a href="concept-reserves.html">account reserve</a> to a mathematically-valid account address that does not exist yet. When the payment is processed, a new <a href="reference-ledger-format.html#accountroot">AccountRoot node</a> will be added to the ledger to reflect the newly-created account.</p>
|
||||||
<p>If you attempt to send an insufficient amount of XRP, or any other currency, the Payment will fail.</p>
|
<p>If you attempt to send an insufficient amount of XRP, or any other currency, the Payment will fail.</p>
|
||||||
<h3 id="paths">Paths</h3>
|
<h3 id="paths">Paths</h3>
|
||||||
<p>If present, the <code>Paths</code> field must contain a <em>path set</em> - an array of path arrays. Each individual path represents one way value can flow from the sender to receiver through various intermediary accounts and order books. A single transaction can potentially use multiple paths, for example if the transaction exchanges currency using several different order books in order to achieve the best rate.</p>
|
<p>If present, the <code>Paths</code> field must contain a <em>path set</em> - an array of path arrays. Each individual path represents one way value can flow from the sender to receiver through various intermediary accounts and order books. A single transaction can potentially use multiple paths, for example if the transaction exchanges currency using several different order books in order to achieve the best rate.</p>
|
||||||
@@ -554,7 +560,7 @@
|
|||||||
</ul>
|
</ul>
|
||||||
<p>If the <code>Paths</code> field is provided, the server decides at transaction processing time which paths to use, from the provided set plus a <em>default path</em> (the simplest possible way to connect the specified accounts). This decision is deterministic and attempts to minimize costs, but it is not guaranteed to be perfect.</p>
|
<p>If the <code>Paths</code> field is provided, the server decides at transaction processing time which paths to use, from the provided set plus a <em>default path</em> (the simplest possible way to connect the specified accounts). This decision is deterministic and attempts to minimize costs, but it is not guaranteed to be perfect.</p>
|
||||||
<p>The <code>Paths</code> field must not be an empty array, nor an array whose members are all empty arrays.</p>
|
<p>The <code>Paths</code> field must not be an empty array, nor an array whose members are all empty arrays.</p>
|
||||||
<p>For more information, see <a href="paths.html">Paths</a>.</p>
|
<p>For more information, see <a href="concept-paths.html">Paths</a>.</p>
|
||||||
<h3 id="payment-flags">Payment Flags</h3>
|
<h3 id="payment-flags">Payment Flags</h3>
|
||||||
<p>Transactions of the Payment type support additional values in the <a href="#flags"><code>Flags</code> field</a>, as follows:</p>
|
<p>Transactions of the Payment type support additional values in the <a href="#flags"><code>Flags</code> field</a>, as follows:</p>
|
||||||
<table>
|
<table>
|
||||||
@@ -605,7 +611,7 @@
|
|||||||
<p>In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both tfPartialPayment and tfLimitQuality enabled. If we keep my <code>SendMax</code> of 20 USD and a destination <code>Amount</code> of 100 CNY, then the limit quality is still <code>5</code>. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about <code>6.3</code>, but it rejects the ¥5/$2 offer because that offer's quality of <code>2.5</code> is worse than the quality limit of <code>5</code>. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.</p>
|
<p>In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both tfPartialPayment and tfLimitQuality enabled. If we keep my <code>SendMax</code> of 20 USD and a destination <code>Amount</code> of 100 CNY, then the limit quality is still <code>5</code>. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about <code>6.3</code>, but it rejects the ¥5/$2 offer because that offer's quality of <code>2.5</code> is worse than the quality limit of <code>5</code>. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.</p>
|
||||||
<h2 id="accountset">AccountSet</h2>
|
<h2 id="accountset">AccountSet</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>An AccountSet transaction modifies the properties of an <a href="ripple-ledger.html#accountroot">account in the Ripple Consensus Ledger</a>.</p>
|
<p>An AccountSet transaction modifies the properties of an <a href="reference-ledger-format.html#accountroot">account in the Ripple Consensus Ledger</a>.</p>
|
||||||
<p>Example AccountSet:</p>
|
<p>Example AccountSet:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"TransactionType": "AccountSet",
|
"TransactionType": "AccountSet",
|
||||||
@@ -735,13 +741,13 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>asfNoFreeze</td>
|
<td>asfNoFreeze</td>
|
||||||
<td>6</td>
|
<td>6</td>
|
||||||
<td>Permanently give up the ability to <a href="freeze.html">freeze individual trust lines or disable Global Freeze</a>. This flag can never be disabled after being enabled.</td>
|
<td>Permanently give up the ability to <a href="concept-freeze.html">freeze individual trust lines or disable Global Freeze</a>. This flag can never be disabled after being enabled.</td>
|
||||||
<td>lsfNoFreeze</td>
|
<td>lsfNoFreeze</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>asfGlobalFreeze</td>
|
<td>asfGlobalFreeze</td>
|
||||||
<td>7</td>
|
<td>7</td>
|
||||||
<td><a href="freeze.html">Freeze</a> all assets issued by this account.</td>
|
<td><a href="concept-freeze.html">Freeze</a> all assets issued by this account.</td>
|
||||||
<td>lsfGlobalFreeze</td>
|
<td>lsfGlobalFreeze</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -839,8 +845,8 @@
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p>Instead of using an account's master key to sign transactions, you can set an alternate key pair, called the "Regular Key". As long as the public key for this key pair is set in the <code>RegularKey</code> field of an account this way, then the secret of the Regular Key pair can be used to sign transactions. (The master secret can still be used, too, unless you set the <a href="#accountset-flags">asfDisableMaster account flag</a>.)</p>
|
<p>Instead of using an account's master key to sign transactions, you can set an alternate key pair, called the "Regular Key". As long as the public key for this key pair is set in the <code>RegularKey</code> field of an account this way, then the secret of the Regular Key pair can be used to sign transactions. (The master secret can still be used, too, unless you set the <a href="#accountset-flags">asfDisableMaster account flag</a>.)</p>
|
||||||
<p>A Regular Key pair is generated in the same way as any other Ripple keys (for example, with <a href="rippled-apis.html#wallet-propose">wallet_propose</a>), but it can be changed. A Master Key pair is an intrinsic part of the account's identity (the address is derived from the master public key) so the Master Key cannot be changed. Therefore, using a Regular Key to sign transactions instead of the master key whenever possible is beneficial to security.</p>
|
<p>A Regular Key pair is generated in the same way as any other Ripple keys (for example, with <a href="reference-rippled.html#wallet-propose">wallet_propose</a>), but it can be changed. A Master Key pair is an intrinsic part of the account's identity (the address is derived from the master public key) so the Master Key cannot be changed. Therefore, using a Regular Key to sign transactions instead of the master key whenever possible is beneficial to security.</p>
|
||||||
<p>If your regular key is compromised, but the master key is not, you can use this method to regain control of your account. In some cases, you can even send a <a href="tx-cost.html#key-reset-transaction">key reset transaction</a> without paying the <a href="#transaction-cost">transaction cost</a>.</p>
|
<p>If your regular key is compromised, but the master key is not, you can use this method to regain control of your account. In some cases, you can even send a <a href="concept-transaction-cost.html#key-reset-transaction">key reset transaction</a> without paying the <a href="#transaction-cost">transaction cost</a>.</p>
|
||||||
<h2 id="offercreate">OfferCreate</h2>
|
<h2 id="offercreate">OfferCreate</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>An OfferCreate transaction is effectively a <a href="http://en.wikipedia.org/wiki/limit_order">limit order</a>. It defines an intent to exchange currencies, and creates an Offer node in the Ripple Consensus Ledger if not completely fulfilled when placed. Offers can be partially fulfilled.</p>
|
<p>An OfferCreate transaction is effectively a <a href="http://en.wikipedia.org/wiki/limit_order">limit order</a>. It defines an intent to exchange currencies, and creates an Offer node in the Ripple Consensus Ledger if not completely fulfilled when placed. Offers can be partially fulfilled.</p>
|
||||||
@@ -873,7 +879,7 @@
|
|||||||
<td><a href="#expiration">Expiration</a></td>
|
<td><a href="#expiration">Expiration</a></td>
|
||||||
<td>Unsigned Integer</td>
|
<td>Unsigned Integer</td>
|
||||||
<td>UInt32</td>
|
<td>UInt32</td>
|
||||||
<td>(Optional) Time after which the offer is no longer active, in <a href="rippled-apis.html#specifying-time">seconds since the Ripple Epoch</a>.</td>
|
<td>(Optional) Time after which the offer is no longer active, in <a href="reference-rippled.html#specifying-time">seconds since the Ripple Epoch</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>OfferSequence</td>
|
<td>OfferSequence</td>
|
||||||
@@ -903,7 +909,7 @@
|
|||||||
<ul>
|
<ul>
|
||||||
<li>If the creator no longer has any of the <code>TakerGets</code> currency.</li>
|
<li>If the creator no longer has any of the <code>TakerGets</code> currency.</li>
|
||||||
<li>The offer becomes funded again when the creator obtains more of that currency.</li>
|
<li>The offer becomes funded again when the creator obtains more of that currency.</li>
|
||||||
<li>If the currency required to fund the offer is held in a <a href="freeze.html">frozen trust line</a>.</li>
|
<li>If the currency required to fund the offer is held in a <a href="concept-freeze.html">frozen trust line</a>.</li>
|
||||||
<li>The offer becomes funded again when the trust line is no longer frozen.</li>
|
<li>The offer becomes funded again when the trust line is no longer frozen.</li>
|
||||||
<li>If the creator does not have enough XRP for the reserve amount of a new trust line required by the offer. (See <a href="#offers-and-trust">Offers and Trust</a>.)</li>
|
<li>If the creator does not have enough XRP for the reserve amount of a new trust line required by the offer. (See <a href="#offers-and-trust">Offers and Trust</a>.)</li>
|
||||||
<li>The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease.</li>
|
<li>The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease.</li>
|
||||||
@@ -920,10 +926,10 @@
|
|||||||
</ul>
|
</ul>
|
||||||
<h4 id="tracking-unfunded-offers">Tracking Unfunded Offers</h4>
|
<h4 id="tracking-unfunded-offers">Tracking Unfunded Offers</h4>
|
||||||
<p>Tracking the funding status of all offers can be computationally taxing. In particular, accounts that are actively trading may have a large number of offers open and be frequently involved in transactions that affect the funding status of their offers. Because of this, <code>rippled</code> does not proactively find and remove offers.</p>
|
<p>Tracking the funding status of all offers can be computationally taxing. In particular, accounts that are actively trading may have a large number of offers open and be frequently involved in transactions that affect the funding status of their offers. Because of this, <code>rippled</code> does not proactively find and remove offers.</p>
|
||||||
<p>A client application can locally track the funding status of offers. To do this, first retreive an order book using the <a href="rippled-apis.html#book-offers"><code>book_offers</code> command</a> and check the <code>taker_gets_funded</code> field of offers. Then, <a href="rippled-apis.html#subscribe">subscribe</a> to the <code>transactions</code> stream and watch the transaction metadata to see which offers are modified.</p>
|
<p>A client application can locally track the funding status of offers. To do this, first retreive an order book using the <a href="reference-rippled.html#book-offers"><code>book_offers</code> command</a> and check the <code>taker_gets_funded</code> field of offers. Then, <a href="reference-rippled.html#subscribe">subscribe</a> to the <code>transactions</code> stream and watch the transaction metadata to see which offers are modified.</p>
|
||||||
<h3 id="offers-and-trust">Offers and Trust</h3>
|
<h3 id="offers-and-trust">Offers and Trust</h3>
|
||||||
<p>The limit values of trust lines (See <a href="#trustset">TrustSet</a>) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuing gateway to redeem.</p>
|
<p>The limit values of trust lines (See <a href="#trustset">TrustSet</a>) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuing gateway to redeem.</p>
|
||||||
<p>However, possessing non-XRP balances still requires a trust line to the account issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because <a href="reserves.html">trust lines increase the reserve an account must hold</a>, any offers that would require a new trust line also require the account to have the necessary XRP to pay the reserve for that trust line.</p>
|
<p>However, possessing non-XRP balances still requires a trust line to the account issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because <a href="concept-reserves.html">trust lines increase the reserve an account must hold</a>, any offers that would require a new trust line also require the account to have the necessary XRP to pay the reserve for that trust line.</p>
|
||||||
<p>A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits.</p>
|
<p>A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits.</p>
|
||||||
<h3 id="offer-preference">Offer Preference</h3>
|
<h3 id="offer-preference">Offer Preference</h3>
|
||||||
<p>Existing offers are grouped by "quality", which is measured as the ratio between <code>TakerGets</code> and <code>TakerPays</code>. Offers with a higher quality are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same quality are taken on the basis of which offer was placed in the earliest ledger version.</p>
|
<p>Existing offers are grouped by "quality", which is measured as the ratio between <code>TakerGets</code> and <code>TakerPays</code>. Offers with a higher quality are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same quality are taken on the basis of which offer was placed in the earliest ledger version.</p>
|
||||||
@@ -931,7 +937,7 @@
|
|||||||
<h3 id="expiration">Expiration</h3>
|
<h3 id="expiration">Expiration</h3>
|
||||||
<p>Since transactions can take time to propagate and confirm, the timestamp of a ledger is used to determine offer validity. An offer only expires when its Expiration time occurs prior to the most-recently validated ledger. In other words, an offer with an <code>Expiration</code> field is still considered "active" if its expiration time is later than the timestamp of the most-recently validated ledger, regardless of what your local clock says.</p>
|
<p>Since transactions can take time to propagate and confirm, the timestamp of a ledger is used to determine offer validity. An offer only expires when its Expiration time occurs prior to the most-recently validated ledger. In other words, an offer with an <code>Expiration</code> field is still considered "active" if its expiration time is later than the timestamp of the most-recently validated ledger, regardless of what your local clock says.</p>
|
||||||
<p>You can determine the final disposition of an offer with an <code>Expiration</code> as soon as you see a fully-validated ledger with a close time equal to or greater than the expiration time.</p>
|
<p>You can determine the final disposition of an offer with an <code>Expiration</code> as soon as you see a fully-validated ledger with a close time equal to or greater than the expiration time.</p>
|
||||||
<p><em>Note:</em> Since only new transactions can modify the ledger, an expired offer can remain on the ledger after it becomes inactive. The offer is treated as unfunded and has no effect, but it can continue to appear in results (for example, from the <a href="rippled-apis.html#ledger-entry">ledger_entry</a> command). Later on, the expired offer can get finally deleted as a result of another transaction (such as another OfferCreate) if the server encounters it while processing.</p>
|
<p><em>Note:</em> Since only new transactions can modify the ledger, an expired offer can remain on the ledger after it becomes inactive. The offer is treated as unfunded and has no effect, but it can continue to appear in results (for example, from the <a href="reference-rippled.html#ledger-entry">ledger_entry</a> command). Later on, the expired offer can get finally deleted as a result of another transaction (such as another OfferCreate) if the server encounters it while processing.</p>
|
||||||
<h3 id="auto-bridging">Auto-Bridging</h3>
|
<h3 id="auto-bridging">Auto-Bridging</h3>
|
||||||
<p>Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the Ripple Consensus Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate.</p>
|
<p>Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the Ripple Consensus Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate.</p>
|
||||||
<p>Example: <em>Anita places an offer to sell GBP and buy BRL. She might fund that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. Auto-bridging software finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader in order to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers.</em></p>
|
<p>Example: <em>Anita places an offer to sell GBP and buy BRL. She might fund that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. Auto-bridging software finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader in order to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers.</em></p>
|
||||||
@@ -1010,7 +1016,7 @@
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<p><em>Tip:</em> To remove an old offer and replace it with a new one, you can use an <a href="#offercreate">OfferCreate</a> transaction with an <code>OfferSequence</code> parameter, instead of using OfferCancel and another OfferCreate.</p>
|
<p><em>Tip:</em> To remove an old offer and replace it with a new one, you can use an <a href="#offercreate">OfferCreate</a> transaction with an <code>OfferSequence</code> parameter, instead of using OfferCancel and another OfferCreate.</p>
|
||||||
<p>The OfferCancel method returns <a href="transactions.html#transaction-results">tesSUCCESS</a> even if it did not find an offer with the matching sequence number.</p>
|
<p>The OfferCancel method returns <a href="#transaction-results">tesSUCCESS</a> even if it did not find an offer with the matching sequence number.</p>
|
||||||
<h2 id="trustset">TrustSet</h2>
|
<h2 id="trustset">TrustSet</h2>
|
||||||
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/SetTrust.cpp" title="Source">[Source]<br/></a></p>
|
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/SetTrust.cpp" title="Source">[Source]<br/></a></p>
|
||||||
<p>Create or modify a trust line linking two accounts.</p>
|
<p>Create or modify a trust line linking two accounts.</p>
|
||||||
@@ -1042,7 +1048,7 @@
|
|||||||
<td><a href="#trust-limits">LimitAmount</a></td>
|
<td><a href="#trust-limits">LimitAmount</a></td>
|
||||||
<td>Object</td>
|
<td>Object</td>
|
||||||
<td>Amount</td>
|
<td>Amount</td>
|
||||||
<td>Object defining the trust line to create or modify, in the same format as <a href="rippled-apis.html#specifying-currency-amounts">currency amounts</a>.</td>
|
<td>Object defining the trust line to create or modify, in the same format as <a href="reference-rippled.html#specifying-currency-amounts">currency amounts</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>LimitAmount.currency</td>
|
<td>LimitAmount.currency</td>
|
||||||
@@ -1080,7 +1086,7 @@
|
|||||||
<p>All balances on the Ripple Network, except for XRP, represent value owed in the world outside the Ripple Ledger. The account that issues those funds in Ripple (identified by the <code>issuer</code> field of the <code>LimitAmount</code> object) is responsible for paying the balance back, outside of the Ripple Network, when users redeem their Ripple balances by returning them to the issuing account.</p>
|
<p>All balances on the Ripple Network, except for XRP, represent value owed in the world outside the Ripple Ledger. The account that issues those funds in Ripple (identified by the <code>issuer</code> field of the <code>LimitAmount</code> object) is responsible for paying the balance back, outside of the Ripple Network, when users redeem their Ripple balances by returning them to the issuing account.</p>
|
||||||
<p>Since a computer program cannot force the gateway to keep its promise and not default in real life, trust lines represent a way of configuring how much you are willing to trust the issuing account to hold on your behalf. Since a large, reputable issuing gateway is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuing account "owe" you (off the network) for the funds that you hold on the network. In the case that the issuing gateway defaults or goes out of business, you can lose up to that much money because the balances you hold in the Ripple Network can no longer be exchanged for equivalent balances off the network. (The Ripple Ledger will still reflect that you possess the same balance with that issuing gateway, but you won't be able to redeem, making it unlikely to be worth anything.)</p>
|
<p>Since a computer program cannot force the gateway to keep its promise and not default in real life, trust lines represent a way of configuring how much you are willing to trust the issuing account to hold on your behalf. Since a large, reputable issuing gateway is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuing account "owe" you (off the network) for the funds that you hold on the network. In the case that the issuing gateway defaults or goes out of business, you can lose up to that much money because the balances you hold in the Ripple Network can no longer be exchanged for equivalent balances off the network. (The Ripple Ledger will still reflect that you possess the same balance with that issuing gateway, but you won't be able to redeem, making it unlikely to be worth anything.)</p>
|
||||||
<p>There are two cases where you can hold a balance on a trust line that is <em>greater</em> than your limit: when you acquire more of that currency through <a href="#offercreate">trading</a>, or when you decrease the limit on your trust line.</p>
|
<p>There are two cases where you can hold a balance on a trust line that is <em>greater</em> than your limit: when you acquire more of that currency through <a href="#offercreate">trading</a>, or when you decrease the limit on your trust line.</p>
|
||||||
<p>Since a trust line occupies space in the ledger, <a href="reserves.html">a trust line increases the XRP your account must hold in reserve</a>. This applies to the account extending trust, not to the account receiving it.</p>
|
<p>Since a trust line occupies space in the ledger, <a href="concept-reserves.html">a trust line increases the XRP your account must hold in reserve</a>. This applies to the account extending trust, not to the account receiving it.</p>
|
||||||
<p>A trust line with settings in the default state is equivalent to no trust line.</p>
|
<p>A trust line with settings in the default state is equivalent to no trust line.</p>
|
||||||
<p>The default state of all flags is off, except for the <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">NoRipple flag</a>, whose default state depends on the DefaultRipple flag.</p>
|
<p>The default state of all flags is off, except for the <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">NoRipple flag</a>, whose default state depends on the DefaultRipple flag.</p>
|
||||||
<p>The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. <em>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.30.0">rippled 0.30.0</a>)</em>: You can pre-authorize a trust line with the <code>tfSetfAuth</code> flag only, even if the limit and balance of the trust line are 0.</p>
|
<p>The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. <em>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.30.0">rippled 0.30.0</a>)</em>: You can pre-authorize a trust line with the <code>tfSetfAuth</code> flag only, even if the limit and balance of the trust line are 0.</p>
|
||||||
@@ -1118,13 +1124,13 @@
|
|||||||
<td>tfSetFreeze</td>
|
<td>tfSetFreeze</td>
|
||||||
<td>0x00100000</td>
|
<td>0x00100000</td>
|
||||||
<td>1048576</td>
|
<td>1048576</td>
|
||||||
<td><a href="freeze.html">Freeze</a> the trustline.</td>
|
<td><a href="concept-freeze.html">Freeze</a> the trustline.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tfClearFreeze</td>
|
<td>tfClearFreeze</td>
|
||||||
<td>0x00200000</td>
|
<td>0x00200000</td>
|
||||||
<td>2097152</td>
|
<td>2097152</td>
|
||||||
<td><a href="freeze.html">Unfreeze</a> the trustline.</td>
|
<td><a href="concept-freeze.html">Unfreeze</a> the trustline.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -1162,7 +1168,7 @@
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<h2 id="setfee">SetFee</h2>
|
<h2 id="setfee">SetFee</h2>
|
||||||
<p>A change in <a href="tx-cost.html">transaction cost</a> or <a href="reserves.html">account reserve</a> requirements. This is typically in response to changes in the load on the network.</p>
|
<p>A change in <a href="concept-transaction-cost.html">transaction cost</a> or <a href="concept-reserves.html">account reserve</a> requirements. This is typically in response to changes in the load on the network.</p>
|
||||||
<p><em>Note:</em> You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.</p>
|
<p><em>Note:</em> You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
|
"Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
|
||||||
@@ -1193,7 +1199,7 @@
|
|||||||
<td>BaseFee</td>
|
<td>BaseFee</td>
|
||||||
<td>String</td>
|
<td>String</td>
|
||||||
<td>UInt64</td>
|
<td>UInt64</td>
|
||||||
<td>The charge, in drops of XRP, for the reference transaction, as hex. (This is the <a href="tx-cost.html">transaction cost</a> before scaling for load.)</td>
|
<td>The charge, in drops of XRP, for the reference transaction, as hex. (This is the <a href="concept-transaction-cost.html">transaction cost</a> before scaling for load.)</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>ReferenceFeeUnits</td>
|
<td>ReferenceFeeUnits</td>
|
||||||
@@ -1217,7 +1223,7 @@
|
|||||||
</table>
|
</table>
|
||||||
<h1 id="transaction-results">Transaction Results</h1>
|
<h1 id="transaction-results">Transaction Results</h1>
|
||||||
<h2 id="immediate-response">Immediate Response</h2>
|
<h2 id="immediate-response">Immediate Response</h2>
|
||||||
<p>The response from the <a href="rippled-apis.html#submit"><code>submit</code> command</a> contains a provisional result from the <code>rippled</code> server indicating what happened during local processing of the transaction. </p>
|
<p>The response from the <a href="reference-rippled.html#submit"><code>submit</code> command</a> contains a provisional result from the <code>rippled</code> server indicating what happened during local processing of the transaction. </p>
|
||||||
<p>The response from <code>submit</code> contains the following fields:</p>
|
<p>The response from <code>submit</code> contains the following fields:</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
@@ -1252,7 +1258,7 @@
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p><strong><em>Note:</em></strong> A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. See <a href="#finality-of-results">Finality of Results</a> for details.</p>
|
<p><strong><em>Note:</em></strong> A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. See <a href="#finality-of-results">Finality of Results</a> for details.</p>
|
||||||
<h2 id="looking-up-transaction-results">Looking up Transaction Results</h2>
|
<h2 id="looking-up-transaction-results">Looking up Transaction Results</h2>
|
||||||
<p>To see the final result of a transaction, use the <a href="rippled-apis.html#tx"><code>tx</code> command</a>, <a href="rippled-apis.html#account-tx"><code>account_tx</code> command</a>, or other response from <code>rippled</code>. Look for <code>"validated": true</code> to indicate that this response uses a ledger version that has been validated by consensus. </p>
|
<p>To see the final result of a transaction, use the <a href="reference-rippled.html#tx"><code>tx</code> command</a>, <a href="reference-rippled.html#account-tx"><code>account_tx</code> command</a>, or other response from <code>rippled</code>. Look for <code>"validated": true</code> to indicate that this response uses a ledger version that has been validated by consensus. </p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -1320,7 +1326,7 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>Claimed cost only</td>
|
<td>Claimed cost only</td>
|
||||||
<td><a href="#tec-codes">tec</a></td>
|
<td><a href="#tec-codes">tec</a></td>
|
||||||
<td>The transaction did not achieve its intended purpose, but the <a href="tx-cost.html">transaction cost</a> was destroyed. This result is not final unless it appears in a validated ledger.</td>
|
<td>The transaction did not achieve its intended purpose, but the <a href="concept-transaction-cost.html">transaction cost</a> was destroyed. This result is not final unless it appears in a validated ledger.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>Client library error</td>
|
<td>Client library error</td>
|
||||||
@@ -1332,7 +1338,7 @@
|
|||||||
<p>The distinction between a local error (<code>tel</code>) and a malformed transaction (<code>tem</code>) is a matter of protocol-level rules. For example, the protocol sets no limit on the maximum number of paths that can be included in a transaction. However, a server may define a finite limit of paths it can process. If two different servers are configured differently, then one of them may return a <code>tel</code> error for a transaction with many paths, while the other server could successfully process the transaction. If enough servers are able to process the transaction that it survives consensus, then it can still be included in a validated ledger.</p>
|
<p>The distinction between a local error (<code>tel</code>) and a malformed transaction (<code>tem</code>) is a matter of protocol-level rules. For example, the protocol sets no limit on the maximum number of paths that can be included in a transaction. However, a server may define a finite limit of paths it can process. If two different servers are configured differently, then one of them may return a <code>tel</code> error for a transaction with many paths, while the other server could successfully process the transaction. If enough servers are able to process the transaction that it survives consensus, then it can still be included in a validated ledger.</p>
|
||||||
<p>By contrast, a <code>tem</code> error implies that no server anywhere can apply the transaction, regardless of settings. Either the transaction breaks the rules of the protocol, it is unacceptably ambiguous, or it is completely nonsensical. The only way a malformed transaction could become valid is through changes in the protocol; for example, if a new feature is adopted, then transactions using that feature could be considered malformed by servers that are running older software which predates that feature.</p>
|
<p>By contrast, a <code>tem</code> error implies that no server anywhere can apply the transaction, regardless of settings. Either the transaction breaks the rules of the protocol, it is unacceptably ambiguous, or it is completely nonsensical. The only way a malformed transaction could become valid is through changes in the protocol; for example, if a new feature is adopted, then transactions using that feature could be considered malformed by servers that are running older software which predates that feature.</p>
|
||||||
<h2 id="claimed-cost-justification">Claimed Cost Justification</h2>
|
<h2 id="claimed-cost-justification">Claimed Cost Justification</h2>
|
||||||
<p>Although it may seem unfair to charge a <a href="tx-cost.html">transaction cost</a> for a failed transaction, the <code>tec</code> class of errors exists for good reasons:</p>
|
<p>Although it may seem unfair to charge a <a href="concept-transaction-cost.html">transaction cost</a> for a failed transaction, the <code>tec</code> class of errors exists for good reasons:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Transactions submitted after the failed one do not have to have their Sequence values renumbered. Incorporating the failed transaction into a ledger uses up the transaction's sequence number, preserving the expected sequence.</li>
|
<li>Transactions submitted after the failed one do not have to have their Sequence values renumbered. Incorporating the failed transaction into a ledger uses up the transaction's sequence number, preserving the expected sequence.</li>
|
||||||
<li>Distributing the transaction throughout the network increases network load. Enforcing a cost makes it harder for attackers to abuse the network with failed transactions.</li>
|
<li>Distributing the transaction throughout the network increases network load. Enforcing a cost makes it harder for attackers to abuse the network with failed transactions.</li>
|
||||||
@@ -1408,7 +1414,7 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td><a href="#delivered-amount">delivered_amount</a></td>
|
<td><a href="#delivered-amount">delivered_amount</a></td>
|
||||||
<td>Object or String</td>
|
<td>Object or String</td>
|
||||||
<td>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.27.0">rippled 0.27.0</a>) The <a href="rippled-apis.html#specifying-currency-amounts">amount</a> actually received by the <code>Destination</code> account. Use this field to determine how much was delivered, regardless of whether the transaction is a <a href="#partial-payments">partial payment</a>.</td>
|
<td>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.27.0">rippled 0.27.0</a>) The <a href="reference-rippled.html#specifying-currency-amounts">amount</a> actually received by the <code>Destination</code> account. Use this field to determine how much was delivered, regardless of whether the transaction is a <a href="#partial-payments">partial payment</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
@@ -1454,7 +1460,7 @@
|
|||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>telINSUF_FEE_P</td>
|
<td>telINSUF_FEE_P</td>
|
||||||
<td>The <code>Fee</code> from the transaction is not high enough to meet the server's current <a href="tx-cost.html">transaction cost</a> requirement, which is derived from its load level.</td>
|
<td>The <code>Fee</code> from the transaction is not high enough to meet the server's current <a href="concept-transaction-cost.html">transaction cost</a> requirement, which is derived from its load level.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>telNO_DST_PARTIAL</td>
|
<td>telNO_DST_PARTIAL</td>
|
||||||
@@ -1486,7 +1492,7 @@
|
|||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>temBAD_CURRENCY</td>
|
<td>temBAD_CURRENCY</td>
|
||||||
<td>The transaction improperly specified a currency field. See <a href="rippled-apis.html#specifying-currency-amounts">Specifying Currency Amounts</a> for the correct format.</td>
|
<td>The transaction improperly specified a currency field. See <a href="reference-rippled.html#specifying-currency-amounts">Specifying Currency Amounts</a> for the correct format.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>temBAD_EXPIRATION</td>
|
<td>temBAD_EXPIRATION</td>
|
||||||
@@ -1715,7 +1721,7 @@
|
|||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
<h3 id="tec-codes">tec Codes</h3>
|
<h3 id="tec-codes">tec Codes</h3>
|
||||||
<p>These codes indicate that the transaction failed, but it was applied to a ledger in order to apply the <a href="tx-cost.html">transaction cost</a>. They have numerical values in the range 100 to 199. The exact codes sometimes appear in ledger data, so they do not change, but we recommend not relying on the numeric value regardless.</p>
|
<p>These codes indicate that the transaction failed, but it was applied to a ledger in order to apply the <a href="concept-transaction-cost.html">transaction cost</a>. They have numerical values in the range 100 to 199. The exact codes sometimes appear in ledger data, so they do not change, but we recommend not relying on the numeric value regardless.</p>
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
@@ -1748,7 +1754,7 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tecUNFUNDED_PAYMENT</td>
|
<td>tecUNFUNDED_PAYMENT</td>
|
||||||
<td>104</td>
|
<td>104</td>
|
||||||
<td>The transaction failed because the sending account is trying to send more XRP than it holds, not counting the reserve. (See: <a href="reserves.html">Reserves</a>)</td>
|
<td>The transaction failed because the sending account is trying to send more XRP than it holds, not counting the reserve. (See: <a href="concept-reserves.html">Reserves</a>)</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tecFAILED_PROCESSING</td>
|
<td>tecFAILED_PROCESSING</td>
|
||||||
@@ -1763,12 +1769,12 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tecINSUF_RESERVE_LINE</td>
|
<td>tecINSUF_RESERVE_LINE</td>
|
||||||
<td>122</td>
|
<td>122</td>
|
||||||
<td>The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: <a href="reserves.html">Reserves</a>) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See tecNO_LINE_INSUF_RESERVE for the other case.)</td>
|
<td>The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: <a href="concept-reserves.html">Reserves</a>) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See tecNO_LINE_INSUF_RESERVE for the other case.)</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tecINSUF_RESERVE_OFFER</td>
|
<td>tecINSUF_RESERVE_OFFER</td>
|
||||||
<td>123</td>
|
<td>123</td>
|
||||||
<td>The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: <a href="reserves.html">Reserves</a>)</td>
|
<td>The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: <a href="concept-reserves.html">Reserves</a>)</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tecNO_DST</td>
|
<td>tecNO_DST</td>
|
||||||
@@ -1783,7 +1789,7 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tecNO_LINE_INSUF_RESERVE</td>
|
<td>tecNO_LINE_INSUF_RESERVE</td>
|
||||||
<td>126</td>
|
<td>126</td>
|
||||||
<td>The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: <a href="reserves.html">Reserves</a>) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See tecINSUF_RESERVE_LINE for the other case.)</td>
|
<td>The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: <a href="concept-reserves.html">Reserves</a>) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See tecINSUF_RESERVE_LINE for the other case.)</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tecNO_LINE_REDUNDANT</td>
|
<td>tecNO_LINE_REDUNDANT</td>
|
||||||
@@ -1838,7 +1844,7 @@
|
|||||||
<tr>
|
<tr>
|
||||||
<td>tecFROZEN</td>
|
<td>tecFROZEN</td>
|
||||||
<td>137</td>
|
<td>137</td>
|
||||||
<td>The <a href="#offercreate">OfferCreate transaction</a> failed because one or both of the assets involved are subject to a <a href="freeze.html">global freeze</a>.</td>
|
<td>The <a href="#offercreate">OfferCreate transaction</a> failed because one or both of the assets involved are subject to a <a href="concept-freeze.html">global freeze</a>.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tecNO_TARGET</td>
|
<td>tecNO_TARGET</td>
|
||||||
@@ -1910,11 +1916,11 @@
|
|||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tejMaxFeeExceeded</td>
|
<td>tejMaxFeeExceeded</td>
|
||||||
<td>The <a href="tx-cost.html">transaction cost</a> that would be necessary to send the transaction is higher than the maximum transaction cost setting, which is either the <code>_MaxFee</code> parameter of the Transaction (if provided) or the maximum transaction cost configured for the remote. The default value is 1 XRP (100000 drops).</td>
|
<td>The <a href="concept-transaction-cost.html">transaction cost</a> that would be necessary to send the transaction is higher than the maximum transaction cost setting, which is either the <code>_MaxFee</code> parameter of the Transaction (if provided) or the maximum transaction cost configured for the remote. The default value is 1 XRP (100000 drops).</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tejMaxLedger</td>
|
<td>tejMaxLedger</td>
|
||||||
<td>Currently-validated ledgers have surpassed the <code>LastLedgerSequence</code> parameter of the transaction without including it, so it can no longer succeed. (Also see <a href="reliable_tx.html">Reliable Transaction Submission</a>.) When using ripple-lib, this error effectively replaces all non-final errors, including tel-, tef-, and ter-class response codes.</td>
|
<td>Currently-validated ledgers have surpassed the <code>LastLedgerSequence</code> parameter of the transaction without including it, so it can no longer succeed. (Also see <a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a>.) When using ripple-lib, this error effectively replaces all non-final errors, including tel-, tef-, and ter-class response codes.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>tejSecretInvalid</td>
|
<td>tejSecretInvalid</td>
|
||||||
@@ -41,34 +41,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
|
|||||||
@@ -1,25 +0,0 @@
|
|||||||
#!/usr/bin/env python3
|
|
||||||
|
|
||||||
"""
|
|
||||||
Pandoc filter to make output more like Flatdoc's parser:
|
|
||||||
* convert links ending in > to button-class links without the >
|
|
||||||
* convert underscores to dashes in header IDs
|
|
||||||
"""
|
|
||||||
|
|
||||||
from pandocfilters import toJSONFilter, Link, Str, RawInline, Header, stringify
|
|
||||||
|
|
||||||
def buttonize(key, value, format, meta):
|
|
||||||
if key == 'Link':
|
|
||||||
inlines, (href, title) = value
|
|
||||||
linktext = stringify(inlines).strip()
|
|
||||||
if (format == "html" or format == "html5") and linktext[-1] == ">":
|
|
||||||
html = "<a class='button' title='%s' href='%s'>%s</a>" % (title, href, linktext[:-1])
|
|
||||||
newlink = RawInline("html", html)
|
|
||||||
return newlink
|
|
||||||
elif key == 'Header':
|
|
||||||
level, (identifier, classes, kv), inlines = value
|
|
||||||
identifier = identifier.replace("_","-")
|
|
||||||
return Header(level, (identifier, classes, kv), inlines)
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
toJSONFilter(buttonize)
|
|
||||||
@@ -28,129 +28,145 @@ targets:
|
|||||||
multicode_tabs: true
|
multicode_tabs: true
|
||||||
- name: ripple.com
|
- name: ripple.com
|
||||||
multicode_tabs: true
|
multicode_tabs: true
|
||||||
- name: pdf
|
|
||||||
multicode_tabs: false
|
|
||||||
|
|
||||||
pages:
|
pages:
|
||||||
|
# Intro pages is not directly replicated on ripple.com at this time
|
||||||
- name: Overview
|
- name: Overview
|
||||||
html: index.html
|
html: index.html
|
||||||
sidebar: false
|
sidebar: false
|
||||||
template: template-index.html
|
template: template-index.html
|
||||||
|
|
||||||
|
# References are exhaustive lists of commands and options
|
||||||
|
- name: rippled
|
||||||
|
category: References
|
||||||
|
html: reference-rippled.html
|
||||||
|
md: reference-rippled.md
|
||||||
|
ripple.com: https://ripple.com/build/rippled-apis/
|
||||||
|
sidebar: page-toc
|
||||||
|
|
||||||
|
- name: Transaction Format
|
||||||
|
category: References
|
||||||
|
html: reference-transaction-format.html
|
||||||
|
md: reference-transaction-format.md
|
||||||
|
ripple.com: https://ripple.com/build/transactions/
|
||||||
|
sidebar: page-toc
|
||||||
|
|
||||||
|
- name: Ledger Format
|
||||||
|
category: References
|
||||||
|
html: reference-ledger-format.html
|
||||||
|
md: reference-ledger-format.md
|
||||||
|
ripple.com: https://ripple.com/build/ledger-format/
|
||||||
|
sidebar: page-toc
|
||||||
|
|
||||||
|
- name: RippleAPI
|
||||||
|
category: References
|
||||||
|
html: reference-rippleapi.html
|
||||||
|
# Currently this is the only page that's fetched remotely.
|
||||||
|
md: https://raw.githubusercontent.com/ripple/ripple-lib/0.16.7/docs/index.md
|
||||||
|
ripple.com: https://ripple.com/build/rippleapi/
|
||||||
|
sidebar: page-toc
|
||||||
|
|
||||||
|
- name: Ripple Data API v2
|
||||||
|
category: References
|
||||||
|
html: reference-data-api.html
|
||||||
|
md: reference-data-api.md
|
||||||
|
ripple.com: https://ripple.com/build/data-api-v2/
|
||||||
|
sidebar: page-toc
|
||||||
|
|
||||||
|
# Tutorials are step-by-step guides to a specific goal
|
||||||
|
- name: RippleAPI Beginners Guide
|
||||||
|
category: Tutorials
|
||||||
|
html: tutorial-rippleapi-beginners-guide.html
|
||||||
|
md: tutorial-rippleapi-beginners-guide.md
|
||||||
|
ripple.com: https://ripple.com/build/rippleapi-beginners-guide/
|
||||||
|
sidebar: page-toc
|
||||||
|
|
||||||
|
- name: rippled Setup
|
||||||
|
category: Tutorials
|
||||||
|
html: tutorial-rippled-setup.html
|
||||||
|
md: tutorial-rippled-setup.md
|
||||||
|
ripple.com: https://ripple.com/build/rippled-setup/
|
||||||
|
sidebar: page-toc
|
||||||
|
|
||||||
|
- name: Reliable Transaction Submission
|
||||||
|
category: Tutorials
|
||||||
|
html: tutorial-reliable-transaction-submission.html
|
||||||
|
md: tutorial-reliable-transaction-submission.md
|
||||||
|
ripple.com: https://ripple.com/build/reliable-transaction-submission/
|
||||||
|
sidebar: page-toc
|
||||||
|
|
||||||
|
# Concepts are introductions that explain a topic.
|
||||||
|
# In the Dev Portal, these are mostly summaries of RCL features.
|
||||||
- name: Paths
|
- name: Paths
|
||||||
category: Concepts
|
category: Concepts
|
||||||
html: paths.html
|
html: concept-paths.html
|
||||||
md: paths.md
|
md: concept-paths.md
|
||||||
ripple.com: https://ripple.com/build/paths/
|
ripple.com: https://ripple.com/build/paths/
|
||||||
sidebar: category-toc
|
sidebar: category-toc
|
||||||
|
|
||||||
- name: Fees (Disambiguation)
|
- name: Fees (Disambiguation)
|
||||||
category: Concepts
|
category: Concepts
|
||||||
html: fees.html
|
html: concept-fees.html
|
||||||
md: fees.md
|
md: concept-fees.md
|
||||||
ripple.com: https://ripple.com/knowledge_center/fees-disambiguation/
|
ripple.com: https://ripple.com/knowledge_center/fees-disambiguation/
|
||||||
sidebar: category-toc
|
sidebar: category-toc
|
||||||
|
|
||||||
- name: Transfer Fees
|
- name: Transfer Fees
|
||||||
category: Concepts
|
category: Concepts
|
||||||
html: transfer_fees.html
|
html: concept-transfer-fees.html
|
||||||
md: transferrate.md
|
md: concept-transfer-fees.md
|
||||||
ripple.com: https://ripple.com/knowledge_center/transfer-fees/
|
ripple.com: https://ripple.com/knowledge_center/transfer-fees/
|
||||||
sidebar: category-toc
|
sidebar: category-toc
|
||||||
|
|
||||||
- name: Transaction Cost
|
- name: Transaction Cost
|
||||||
category: Concepts
|
category: Concepts
|
||||||
html: tx-cost.html
|
html: concept-transaction-cost.html
|
||||||
md: tx-cost.md
|
md: concept-transaction-cost.md
|
||||||
ripple.com: https://ripple.com/build/transaction-cost/
|
ripple.com: https://ripple.com/build/transaction-cost/
|
||||||
sidebar: category-toc
|
sidebar: category-toc
|
||||||
|
|
||||||
- category: Concepts
|
- name: Fee Voting
|
||||||
html: fee-voting.html
|
category: Concepts
|
||||||
md: fee-voting.md
|
html: concept-fee-voting.html
|
||||||
name: Fee Voting
|
md: concept-fee-voting.md
|
||||||
ripple.com: https://ripple.com/build/fee-voting/
|
ripple.com: https://ripple.com/build/fee-voting/
|
||||||
sidebar: category-toc
|
sidebar: category-toc
|
||||||
|
|
||||||
- category: Concepts
|
- name: Reserves
|
||||||
html: reserves.html
|
category: Concepts
|
||||||
md: reserves.md
|
html: concept-reserves.html
|
||||||
name: Reserves
|
md: concept-reserves.md
|
||||||
ripple.com: https://ripple.com/build/reserves/
|
ripple.com: https://ripple.com/build/reserves/
|
||||||
sidebar: category-toc
|
sidebar: category-toc
|
||||||
|
|
||||||
- category: Concepts
|
- name: Freeze
|
||||||
html: freeze.html
|
category: Concepts
|
||||||
md: freeze.md
|
html: concept-freeze.html
|
||||||
name: Freeze
|
md: concept-freeze.md
|
||||||
ripple.com: https://ripple.com/build/freeze/
|
ripple.com: https://ripple.com/build/freeze/
|
||||||
sidebar: category-toc
|
sidebar: category-toc
|
||||||
|
|
||||||
- category: Tutorials
|
# "Best Practices" documents are mostly in the same category as tutorials
|
||||||
html: rippleapi_quickstart.html
|
- name: Issuing and Operational Acounts
|
||||||
md: rippleapi_quickstart.md
|
category: Best Practices
|
||||||
name: RippleAPI Quick Start Guide
|
html: concept-issuing-and-operational-accounts.html
|
||||||
|
md: concept-issuing-and-operational-accounts.md
|
||||||
|
# TODO publish this article separately on the website
|
||||||
|
ripple.com: https://ripple.com/build/gateway-guide/#hot-and-cold-wallets
|
||||||
sidebar: page-toc
|
sidebar: page-toc
|
||||||
|
|
||||||
- category: References
|
# The Gateway Guide is kind of a poor fit for the "tutorials" category
|
||||||
html: rippled-apis.html
|
- name: Gateway Guide
|
||||||
md: rippled.md
|
category: Best Practices
|
||||||
name: rippled
|
html: tutorial-gateway-guide.html
|
||||||
ripple.com: https://ripple.com/build/rippled-apis/
|
md: tutorial-gateway-guide.md
|
||||||
sidebar: page-toc
|
|
||||||
|
|
||||||
- category: Tutorials
|
|
||||||
html: rippled-setup.html
|
|
||||||
md: rippled-setup.md
|
|
||||||
name: rippled Setup
|
|
||||||
ripple.com: https://ripple.com/build/rippled-setup/
|
|
||||||
sidebar: page-toc
|
|
||||||
|
|
||||||
- category: References
|
|
||||||
html: transactions.html
|
|
||||||
md: tx_format.md
|
|
||||||
name: Transactions
|
|
||||||
ripple.com: https://ripple.com/build/transactions/
|
|
||||||
sidebar: page-toc
|
|
||||||
|
|
||||||
- category: References
|
|
||||||
html: ripple-ledger.html
|
|
||||||
md: ledger_format.md
|
|
||||||
name: Ledger Format
|
|
||||||
ripple.com: https://ripple.com/build/ledger-format/
|
|
||||||
sidebar: page-toc
|
|
||||||
|
|
||||||
- category: Tutorials
|
|
||||||
html: reliable_tx.html
|
|
||||||
md: reliable_tx.md
|
|
||||||
name: Reliable Transaction Submission
|
|
||||||
ripple.com: https://ripple.com/build/reliable-transaction-submission/
|
|
||||||
sidebar: page-toc
|
|
||||||
|
|
||||||
- category: Tutorials
|
|
||||||
html: gateway_guide.html
|
|
||||||
md: gateway_guide.md
|
|
||||||
name: Gateway Guide
|
|
||||||
ripple.com: https://ripple.com/build/gateway-guide/
|
ripple.com: https://ripple.com/build/gateway-guide/
|
||||||
sidebar: page-toc
|
sidebar: page-toc
|
||||||
|
|
||||||
- category: References
|
# API tools are interactive software for interfacing with real APIs
|
||||||
html: data_api_v2.html
|
- name: WebSocket API Tool
|
||||||
md: data_v2.md
|
category: API Tools
|
||||||
name: Ripple Data API v2
|
|
||||||
ripple.com: https://ripple.com/build/data-api-v2/
|
|
||||||
sidebar: page-toc
|
|
||||||
|
|
||||||
- category: References
|
|
||||||
html: rippleapi.html
|
|
||||||
md: https://raw.githubusercontent.com/ripple/ripple-lib/0.16.7/docs/index.md
|
|
||||||
name: RippleAPI
|
|
||||||
ripple.com: https://ripple.com/build/rippleapi/
|
|
||||||
sidebar: page-toc
|
|
||||||
|
|
||||||
- category: API Tools
|
|
||||||
html: ripple-api-tool.html
|
html: ripple-api-tool.html
|
||||||
name: WebSocket API Tool
|
|
||||||
ripple.com: https://ripple.com/build/websocket-tool/
|
ripple.com: https://ripple.com/build/websocket-tool/
|
||||||
sidebar: custom
|
sidebar: custom
|
||||||
targets:
|
targets:
|
||||||
@@ -158,10 +174,10 @@ pages:
|
|||||||
- ripple.com
|
- ripple.com
|
||||||
template: template-ripple-api-tool.html
|
template: template-ripple-api-tool.html
|
||||||
|
|
||||||
- category: API Tools
|
- name: Data API v2 Tool
|
||||||
|
category: API Tools
|
||||||
html: data-api-v2-tool.html
|
html: data-api-v2-tool.html
|
||||||
methods_js: js/apitool-methods-data_v2.js
|
methods_js: js/apitool-methods-data_v2.js
|
||||||
name: Data API v2 Tool
|
|
||||||
rest_host: https://data.ripple.com
|
rest_host: https://data.ripple.com
|
||||||
sidebar: custom
|
sidebar: custom
|
||||||
targets:
|
targets:
|
||||||
|
|||||||
@@ -499,7 +499,7 @@ if __name__ == "__main__":
|
|||||||
if cli_args.pdf[-4:] != ".pdf":
|
if cli_args.pdf[-4:] != ".pdf":
|
||||||
exit("PDF filename must end in .pdf")
|
exit("PDF filename must end in .pdf")
|
||||||
logging.info("making a pdf...")
|
logging.info("making a pdf...")
|
||||||
make_pdf(cli_args.pdf)
|
make_pdf(cli_args.pdf, target=cli_args.target)
|
||||||
logging.info("pdf done")
|
logging.info("pdf done")
|
||||||
|
|
||||||
else:
|
else:
|
||||||
|
|||||||
@@ -1,69 +0,0 @@
|
|||||||
## method_name ##
|
|
||||||
[[Source]<br>](https://github.com/ripple/source_code/for_your_method/if_available "Source")
|
|
||||||
|
|
||||||
blurb
|
|
||||||
|
|
||||||
#### Request Format ####
|
|
||||||
|
|
||||||
<div class='multicode'>
|
|
||||||
|
|
||||||
*REST*
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
[Try it! >](your-api-tool.html#method_name)
|
|
||||||
|
|
||||||
|
|
||||||
##### URL Parameters #####
|
|
||||||
|
|
||||||
| Field | Value | Description |
|
|
||||||
|-------|-------|-------------|
|
|
||||||
|
|
||||||
|
|
||||||
##### Optional Query Parameters #####
|
|
||||||
|
|
||||||
| Field | Value | Description |
|
|
||||||
|-------|-------|-------------|
|
|
||||||
|
|
||||||
|
|
||||||
##### Body Parameters #####
|
|
||||||
|
|
||||||
| Field | Value | Description |
|
|
||||||
|-------|-------|-------------|
|
|
||||||
|
|
||||||
|
|
||||||
Further description
|
|
||||||
|
|
||||||
#### Response Format ####
|
|
||||||
|
|
||||||
A successful result uses the HTTP response code **200 OK** and contains a JSON body with the following fields:
|
|
||||||
|
|
||||||
| Field | Type | Description |
|
|
||||||
|-------|------|-------------|
|
|
||||||
|
|
||||||
|
|
||||||
#### Example ####
|
|
||||||
|
|
||||||
Request:
|
|
||||||
|
|
||||||
```
|
|
||||||
GET /example/request?params=included
|
|
||||||
```
|
|
||||||
|
|
||||||
Response:
|
|
||||||
|
|
||||||
```js
|
|
||||||
200 OK
|
|
||||||
{
|
|
||||||
//some JSON here
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Errors ####
|
|
||||||
|
|
||||||
* **error_code** - The problem exists between keyboard and chair
|
|
||||||
|
|
||||||
@@ -1,71 +0,0 @@
|
|||||||
## command ##
|
|
||||||
[[Source]<br>](githuburl "Source")
|
|
||||||
|
|
||||||
blurb
|
|
||||||
|
|
||||||
#### Request Format ####
|
|
||||||
An example of the request format:
|
|
||||||
|
|
||||||
<div class='multicode'>
|
|
||||||
|
|
||||||
*WebSocket*
|
|
||||||
|
|
||||||
```
|
|
||||||
//actual example here
|
|
||||||
```
|
|
||||||
|
|
||||||
*Second tab*
|
|
||||||
|
|
||||||
```
|
|
||||||
//second example here
|
|
||||||
```
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
The request includes the following parameters:
|
|
||||||
|
|
||||||
| Field | Type | Description |
|
|
||||||
|-------|------|-------------|
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
#### Response Format ####
|
|
||||||
|
|
||||||
An example of a successful response:
|
|
||||||
|
|
||||||
<div class='multicode'>
|
|
||||||
|
|
||||||
*WebSocket*
|
|
||||||
|
|
||||||
```
|
|
||||||
//actual example here
|
|
||||||
```
|
|
||||||
|
|
||||||
*Second tab*
|
|
||||||
|
|
||||||
```
|
|
||||||
//second example here
|
|
||||||
```
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
The response follows the [standard format](#response-formatting), with a successful result containing the following fields:
|
|
||||||
|
|
||||||
| Field | Type | Description |
|
|
||||||
|-------|------|-------------|
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
#### Possible Errors ####
|
|
||||||
|
|
||||||
* Any of the [universal error types](#universal-errors).
|
|
||||||
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
|
|
||||||
* `actNotFound` - The address specified in the `account` field of the request does not correspond to an account in the ledger.
|
|
||||||
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
|
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -165,16 +171,13 @@
|
|||||||
<li>Clearly publicize all your policies and fees.</li>
|
<li>Clearly publicize all your policies and fees.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h3 id="hot-and-cold-wallets">Hot and Cold Wallets</h3>
|
<h3 id="hot-and-cold-wallets">Hot and Cold Wallets</h3>
|
||||||
<p>It is strongly recommended that Ripple gateways employ a "hot wallet / cold wallet" strategy. This enforces a separation of roles that promotes strong security. ("Wallets" in Ripple are equivalent to Accounts.)</p>
|
<p>We strongly recommend that gateways use multiple Ripple ledger accounts with a separation of roles. This promotes strong security and minimizes risk. We recommend the following setup:</p>
|
||||||
<p>If a malicious person compromises a gateway's issuing account (cold wallet), that person could create an unlimited amount of new issuances, which makes it very difficult to redeem legitimately-held issuances fairly. In this case, the gateway must create a new issuing account, and all users with trust lines to the old gateway must create new trust lines to the new account. Thus, it's best to keep your issuing account as secure as possible.</p>
|
<ul>
|
||||||
<p>The cold wallet is like a vault. It serves as the asset issuer, and should remain offline. The secret key that is used for this wallet is kept offline, accessible to only a few trusted operators. Periodically, a human operator creates and signs a transaction (preferably from an entirely offline machine) in order to refill the hot wallet's balance. Because the cold wallet is the account creating the issuances, customer accounts holding those issuances must trust the cold wallet. </p>
|
<li>An <strong>issuing account</strong> (also known as a "cold wallet") with high value, used as rarely as possible.</li>
|
||||||
<p>A hot wallet is like a cash register. It makes payments to the gateway's users in Ripple by sending them issuances created by the cold wallet. The secret key for a hot wallet is, by necessity, stored on a server that is connected to the outside internet, usually in a configuration file on a public-facing server. Because it holds issuances created by the cold walet, each hot wallet needs a trust line to the cold wallet. Customers do not, and should not, trust hot wallet accounts.</p>
|
<li>One or more <strong>operational accounts</strong> (also known as a "hot wallets") with low value, used frequently by automated processes.</li>
|
||||||
<p>(Unlike a cash register, the hot wallet does not have to handle incoming payments from users, because the cold wallet can receive and monitor payments without using its secret key. To make things simple for your users, we recommend treating incoming payments to the hot and cold wallets as the same.)</p>
|
<li>Optional <strong>standby accounts</strong> (also known as "warm wallets"), used infrequently by human operators.</li>
|
||||||
<p>A gateway can use one or more "hot wallet" accounts, but each hot wallet has a limited balance of the gateway's issuances. If a hot wallet is compromised, the gateway only loses as much currency as that account holds. Customers do not need to change any configuration in order to receive funds from a new hot wallet. However, the gateway must monitor the hot wallet's balance so that it doesn't run out of funds during ordinary operation.</p>
|
</ul>
|
||||||
<h3 id="warm-wallets">Warm Wallets</h3>
|
<p>For more information, see <a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Accounts</a></p>
|
||||||
<p>Another optional step that a gateway can take to balance risk and convenience is to use "warm wallets" as an intermediate step between cold wallet and hot wallet. Frequently, the software that runs a gateway's daily operations uses a single hot wallet. The gateway can operate additional accounts as warm wallets, whose keys are entrusted to different trusted users and whose keys are also not stored for use by the gateway software. </p>
|
|
||||||
<p>When the hot wallet is running low on funds, the warm wallets can be used to refill it. When the warm wallets run low on funds, the cold wallet can issue more currency to a warm wallet in a single transaction, and the warm wallets can distribute that currency among themselves if necessary. This improves security of the cold wallet, since it makes as few transactions as possible, without leaving too much money in the control of a single automated hot wallet.</p>
|
|
||||||
<p>As with hot wallets, warm wallets must trust the cold wallet, and should not be trusted by users. All precautions that apply to hot wallets also apply to warm wallets.</p>
|
|
||||||
<h3 id="funds-lifecycle">Funds Lifecycle</h3>
|
<h3 id="funds-lifecycle">Funds Lifecycle</h3>
|
||||||
<p>Funds in Ripple tend to flow in a cycle, from the cold wallet to the warm wallets, then the warm wallets, to customers, and eventually from customers back to the cold wallet. Issuances (any non-XRP balance in Ripple) are always tied to a trust line, so each payment "ripples" through ACME's issuing account on the trust lines connected to it. Ultimately, the lifecycle of issuances in Ripple looks something like this:</p>
|
<p>Funds in Ripple tend to flow in a cycle, from the cold wallet to the warm wallets, then the warm wallets, to customers, and eventually from customers back to the cold wallet. Issuances (any non-XRP balance in Ripple) are always tied to a trust line, so each payment "ripples" through ACME's issuing account on the trust lines connected to it. Ultimately, the lifecycle of issuances in Ripple looks something like this:</p>
|
||||||
<p><img alt="Funds flow diagram" src="img/e2g-funds_flow.png"/></p>
|
<p><img alt="Funds flow diagram" src="img/e2g-funds_flow.png"/></p>
|
||||||
@@ -269,7 +272,7 @@
|
|||||||
<li>Before sending a payment into Ripple, double check the cost of the payment. A simple payment from your hot wallet to a customer should not cost more than the destination amount plus any <a href="#transferrate">transfer fee</a> you have set.</li>
|
<li>Before sending a payment into Ripple, double check the cost of the payment. A simple payment from your hot wallet to a customer should not cost more than the destination amount plus any <a href="#transferrate">transfer fee</a> you have set.</li>
|
||||||
<li>Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you, and it is also an important element of most anti-money-laundering regulations. This is especially important because the users sending money from Ripple could be different than the ones that initially received the money in Ripple.</li>
|
<li>Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you, and it is also an important element of most anti-money-laundering regulations. This is especially important because the users sending money from Ripple could be different than the ones that initially received the money in Ripple.</li>
|
||||||
<li>Follow the guidelines for <a href="#reliable-transaction-submission">reliable transaction submission</a> when sending Ripple transactions.</li>
|
<li>Follow the guidelines for <a href="#reliable-transaction-submission">reliable transaction submission</a> when sending Ripple transactions.</li>
|
||||||
<li><a href="#robustly-monitoring-for-payments">Robustly monitor for incoming payments</a>, and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a <a href="transactions.html#partial-payments">partial payment</a>.</li>
|
<li><a href="#robustly-monitoring-for-payments">Robustly monitor for incoming payments</a>, and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a <a href="reference-transaction-format.html#partial-payments">partial payment</a>.</li>
|
||||||
<li>Track your obligations and balances within the Ripple network, and compare with your assets off the network. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy.</li>
|
<li>Track your obligations and balances within the Ripple network, and compare with your assets off the network. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy.</li>
|
||||||
<li>Proactively avoid ambiguous situations. We recommend the following:<ul>
|
<li>Proactively avoid ambiguous situations. We recommend the following:<ul>
|
||||||
<li>Enable the <a href="#disallowxrp"><code>DisallowXRP</code> flag</a> for the cold wallet account and all hot wallet accounts, so users do not accidentally send you XRP. (Private exchanges should <em>not</em> set this flag, since they trade XRP normally.)</li>
|
<li>Enable the <a href="#disallowxrp"><code>DisallowXRP</code> flag</a> for the cold wallet account and all hot wallet accounts, so users do not accidentally send you XRP. (Private exchanges should <em>not</em> set this flag, since they trade XRP normally.)</li>
|
||||||
@@ -304,7 +307,7 @@
|
|||||||
<li>Gateways can freeze all issuances created by their cold wallet, in case of a compromised gateway account or for migrating cold wallets.</li>
|
<li>Gateways can freeze all issuances created by their cold wallet, in case of a compromised gateway account or for migrating cold wallets.</li>
|
||||||
<li>Furthermore, gateways can permanently opt out of their ability to freeze issuances at all. This allows a gateway to assure its users that it will continue to provide "physical-money-like" services.</li>
|
<li>Furthermore, gateways can permanently opt out of their ability to freeze issuances at all. This allows a gateway to assure its users that it will continue to provide "physical-money-like" services.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>For more information, see the <a href="freeze.html">Freeze article</a>.</p>
|
<p>For more information, see the <a href="concept-freeze.html">Freeze article</a>.</p>
|
||||||
<h2 id="authorized-accounts">Authorized Accounts</h2>
|
<h2 id="authorized-accounts">Authorized Accounts</h2>
|
||||||
<p>Ripple's Authorized Accounts feature enables a gateway to limit who can hold that gateway's issuances, so that unknown Ripple accounts cannot hold the currency your gateway issues. We feel this is <em>not necessary</em> in most cases, since gateways have full control over the process of redeeming Ripple balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the Ripple network.)</p>
|
<p>Ripple's Authorized Accounts feature enables a gateway to limit who can hold that gateway's issuances, so that unknown Ripple accounts cannot hold the currency your gateway issues. We feel this is <em>not necessary</em> in most cases, since gateways have full control over the process of redeeming Ripple balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the Ripple network.)</p>
|
||||||
<p>To use the Authorized Accounts feature, a gateway enables the <code>RequireAuth</code> flag for its cold wallet account, and then individually approves each user account's trust line before sending issuances in Ripple to that account.</p>
|
<p>To use the Authorized Accounts feature, a gateway enables the <code>RequireAuth</code> flag for its cold wallet account, and then individually approves each user account's trust line before sending issuances in Ripple to that account.</p>
|
||||||
@@ -333,16 +336,16 @@
|
|||||||
<h3 id="apis-and-middleware">APIs and Middleware</h3>
|
<h3 id="apis-and-middleware">APIs and Middleware</h3>
|
||||||
<p>There are several interfaces you can use to connect to Ripple, depending on your needs and your existing software:</p>
|
<p>There are several interfaces you can use to connect to Ripple, depending on your needs and your existing software:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="rippled-apis.html"><code>rippled</code></a> provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality.</li>
|
<li><a href="reference-rippled.html"><code>rippled</code></a> provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality.</li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a> provides a simple API for JavaScript applications.</li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a> provides a simple API for JavaScript applications.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h2 id="tool-security">Tool Security</h2>
|
<h2 id="tool-security">Tool Security</h2>
|
||||||
<p>Any time you submit a Ripple transaction, it must be signed using your secret. However, having your secret means having full control over your account. Therefore, you should never transmit your secret to a server operated by someone else. Instead, use your own server or client application to sign the transactions before sending them out.</p>
|
<p>Any time you submit a Ripple transaction, it must be signed using your secret. However, having your secret means having full control over your account. Therefore, you should never transmit your secret to a server operated by someone else. Instead, use your own server or client application to sign the transactions before sending them out.</p>
|
||||||
<p>The examples in this document show API methods that include an account secret. This is only safe if you control <code>rippled</code> server yourself, <em>and</em> you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use <a href="rippleapi.html">RippleAPI</a> to perform local signing before submitting your transactions to a third-party server.</p>
|
<p>The examples in this document show API methods that include an account secret. This is only safe if you control <code>rippled</code> server yourself, <em>and</em> you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use <a href="reference-rippleapi.html">RippleAPI</a> to perform local signing before submitting your transactions to a third-party server.</p>
|
||||||
<h2 id="defaultripple">DefaultRipple</h2>
|
<h2 id="defaultripple">DefaultRipple</h2>
|
||||||
<p>The DefaultRipple flag controls whether the balances held in an account's trust lines are <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">allowed to ripple</a> by default. Rippling is what allows users to trade issuances, so a gateway must allow rippling on all the trust lines connected to its issuing (cold wallet) account.</p>
|
<p>The DefaultRipple flag controls whether the balances held in an account's trust lines are <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">allowed to ripple</a> by default. Rippling is what allows users to trade issuances, so a gateway must allow rippling on all the trust lines connected to its issuing (cold wallet) account.</p>
|
||||||
<p>Before asking users to trust its issuing account, a gateway should enable the DefaultRipple flag on that account. Otherwise, the gateway must individually disable the NoRipple flag for each trust line that other accounts extend to it.</p>
|
<p>Before asking users to trust its issuing account, a gateway should enable the DefaultRipple flag on that account. Otherwise, the gateway must individually disable the NoRipple flag for each trust line that other accounts extend to it.</p>
|
||||||
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> to send an AccountSet transaction to enable the DefaultRipple flag:</p>
|
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="reference-rippled.html#submit"><code>submit</code> command</a> to send an AccountSet transaction to enable the DefaultRipple flag:</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>POST http://localhost:8088/
|
<pre><code>POST http://localhost:8088/
|
||||||
{
|
{
|
||||||
@@ -384,7 +387,7 @@
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<p>To confirm that an account has DefaultRipple enabled, look up the account using the <a href="rippled-apis.html#account-info">account_info command</a>, specifying a validated ledger version. Use <a href="https://en.wikipedia.org/wiki/Bitwise_operation#AND">a bitwise-AND operator</a> to compare the <code>Flags</code> field with 0x00800000 (the <a href="ripple-ledger.html#accountroot-flags">ledger flag lsfDefaultRipple</a>). If the result of the bitwise-AND operation is nonzero, then the account has DefaultRipple enabled.</p>
|
<p>To confirm that an account has DefaultRipple enabled, look up the account using the <a href="reference-rippled.html#account-info">account_info command</a>, specifying a validated ledger version. Use <a href="https://en.wikipedia.org/wiki/Bitwise_operation#AND">a bitwise-AND operator</a> to compare the <code>Flags</code> field with 0x00800000 (the <a href="reference-ledger-format.html#accountroot-flags">ledger flag lsfDefaultRipple</a>). If the result of the bitwise-AND operation is nonzero, then the account has DefaultRipple enabled.</p>
|
||||||
<h2 id="generating-source-and-destination-tags">Generating Source and Destination Tags</h2>
|
<h2 id="generating-source-and-destination-tags">Generating Source and Destination Tags</h2>
|
||||||
<p>You need a scheme to create Source and Destination tags for your users and payments. (See <a href="#source-and-destination-tags">Source and Destination Tags</a> for an explanation of what Source and Destination Tags are.)</p>
|
<p>You need a scheme to create Source and Destination tags for your users and payments. (See <a href="#source-and-destination-tags">Source and Destination Tags</a> for an explanation of what Source and Destination Tags are.)</p>
|
||||||
<p>For greater privacy and security, we recommend <em>not</em> using monotonically-incrementing numbers as destination tags that correlate 1:1 with users. Instead, we recommend using convenient internal IDs, but mapping those to destination tags through the use of a quick hash or cipher function such as <a href="http://en.wikipedia.org/wiki/Hasty_Pudding_cipher">Hasty Pudding</a>. You should set aside ranges of internal numbers for different uses of destination tags.</p>
|
<p>For greater privacy and security, we recommend <em>not</em> using monotonically-incrementing numbers as destination tags that correlate 1:1 with users. Instead, we recommend using convenient internal IDs, but mapping those to destination tags through the use of a quick hash or cipher function such as <a href="http://en.wikipedia.org/wiki/Hasty_Pudding_cipher">Hasty Pudding</a>. You should set aside ranges of internal numbers for different uses of destination tags.</p>
|
||||||
@@ -394,7 +397,7 @@
|
|||||||
<h2 id="disallowxrp">DisallowXRP</h2>
|
<h2 id="disallowxrp">DisallowXRP</h2>
|
||||||
<p>The DisallowXRP setting (<code>disallowIncomingXRP</code> in RippleAPI) is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around.</p>
|
<p>The DisallowXRP setting (<code>disallowIncomingXRP</code> in RippleAPI) is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around.</p>
|
||||||
<p>An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP.</p>
|
<p>An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP.</p>
|
||||||
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> to send an AccountSet transaction to enable the DisallowXRP flag:</p>
|
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="reference-rippled.html#submit"><code>submit</code> command</a> to send an AccountSet transaction to enable the DisallowXRP flag:</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>POST http://localhost:8088/
|
<pre><code>POST http://localhost:8088/
|
||||||
{
|
{
|
||||||
@@ -439,7 +442,7 @@
|
|||||||
<h2 id="requiredest">RequireDest</h2>
|
<h2 id="requiredest">RequireDest</h2>
|
||||||
<p>The <code>RequireDest</code> setting (<code>requireDestinationTag</code> in RippleAPI) is designed to prevent users from sending payments to your account while accidentally forgetting the <a href="#source-and-destination-tags">destination tag</a> that identifies who should be credited for the payment. When enabled, the Ripple Consensus Ledger rejects any payment to your account that does not specify a destination tag.</p>
|
<p>The <code>RequireDest</code> setting (<code>requireDestinationTag</code> in RippleAPI) is designed to prevent users from sending payments to your account while accidentally forgetting the <a href="#source-and-destination-tags">destination tag</a> that identifies who should be credited for the payment. When enabled, the Ripple Consensus Ledger rejects any payment to your account that does not specify a destination tag.</p>
|
||||||
<p>We recommend enabling the <code>RequireDest</code> flag on all gateway hot and cold wallets.</p>
|
<p>We recommend enabling the <code>RequireDest</code> flag on all gateway hot and cold wallets.</p>
|
||||||
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> to send an AccountSet transaction to enable the <code>RequireDest</code> flag:</p>
|
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="reference-rippled.html#submit"><code>submit</code> command</a> to send an AccountSet transaction to enable the <code>RequireDest</code> flag:</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>POST http://localhost:5005/
|
<pre><code>POST http://localhost:5005/
|
||||||
Content-Type: application/json
|
Content-Type: application/json
|
||||||
@@ -489,7 +492,7 @@ Content-Type: application/json
|
|||||||
<p>If you want to use the <a href="#authorized-accounts">Authorized Accounts</a> feature, you must also enable <code>RequireAuth</code> on your cold wallet. When using Authorized Accounts, your cold wallet must <a href="#authorizing-trust-lines">submit a <code>TrustSet</code> transaction to approve each trust line</a> that customers open to your cold wallet.</p>
|
<p>If you want to use the <a href="#authorized-accounts">Authorized Accounts</a> feature, you must also enable <code>RequireAuth</code> on your cold wallet. When using Authorized Accounts, your cold wallet must <a href="#authorizing-trust-lines">submit a <code>TrustSet</code> transaction to approve each trust line</a> that customers open to your cold wallet.</p>
|
||||||
<p>You can only enable <code>RequireAuth</code> if the account owns no trust lines and no offers in the Ripple ledger, so you must decide whether or not to use it before you start doing business in the Ripple Consensus Ledger.</p>
|
<p>You can only enable <code>RequireAuth</code> if the account owns no trust lines and no offers in the Ripple ledger, so you must decide whether or not to use it before you start doing business in the Ripple Consensus Ledger.</p>
|
||||||
<h3 id="enabling-requireauth">Enabling RequireAuth</h3>
|
<h3 id="enabling-requireauth">Enabling RequireAuth</h3>
|
||||||
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> to send an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the account is used as a hot wallet or cold wallet.)</p>
|
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="reference-rippled.html#submit"><code>submit</code> command</a> to send an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the account is used as a hot wallet or cold wallet.)</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>POST http://localhost:5005/
|
<pre><code>POST http://localhost:5005/
|
||||||
{
|
{
|
||||||
@@ -511,8 +514,8 @@ Content-Type: application/json
|
|||||||
<p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p>
|
<p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p>
|
||||||
<h3 id="authorizing-trust-lines">Authorizing Trust Lines</h3>
|
<h3 id="authorizing-trust-lines">Authorizing Trust Lines</h3>
|
||||||
<p>If you are using the <a href="#authorized-accounts">Authorized Accounts</a> feature, then after enabling the <code>RequireAuth</code> setting for your cold wallet, users cannot hold balances issued by your cold wallet unless you first authorize their trust lines.</p>
|
<p>If you are using the <a href="#authorized-accounts">Authorized Accounts</a> feature, then after enabling the <code>RequireAuth</code> setting for your cold wallet, users cannot hold balances issued by your cold wallet unless you first authorize their trust lines.</p>
|
||||||
<p>To authorize a trust line, submit a TrustSet transaction from your cold wallet, with the user to trust as the <code>issuer</code> of the <code>LimitAmount</code>. Leave the <code>value</code> (the amount to trust them for) as <strong>0</strong>, and enable the <a href="transactions.html#trustset-flags">tfSetfAuth</a> flag for the transaction.</p>
|
<p>To authorize a trust line, submit a TrustSet transaction from your cold wallet, with the user to trust as the <code>issuer</code> of the <code>LimitAmount</code>. Leave the <code>value</code> (the amount to trust them for) as <strong>0</strong>, and enable the <a href="reference-transaction-format.html#trustset-flags">tfSetfAuth</a> flag for the transaction.</p>
|
||||||
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> to send a TrustSet transaction authorizing the (customer) account rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the (cold wallet) account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:</p>
|
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="reference-rippled.html#submit"><code>submit</code> command</a> to send a TrustSet transaction authorizing the (customer) account rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the (cold wallet) account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>POST http://localhost:8088/
|
<pre><code>POST http://localhost:8088/
|
||||||
{
|
{
|
||||||
@@ -551,12 +554,12 @@ Content-Type: application/json
|
|||||||
<p>To make things simpler for your users, we recommend monitoring for incoming payments to hot wallets and the cold wallet, and treating the two equivalently.</p>
|
<p>To make things simpler for your users, we recommend monitoring for incoming payments to hot wallets and the cold wallet, and treating the two equivalently.</p>
|
||||||
<p>As an added precaution, we recommend comparing the balances of your Ripple cold wallet account with the Ripple-backing funds in your internal accounting system each time there is a new Ripple ledger. The cold wallet shows all outstanding issuances as negative balances, which should match the positive assets you have allocated to Ripple outside the network. If the two do not match up, then you should suspend processing payments in and out of Ripple until you have resolved the discrepancy. </p>
|
<p>As an added precaution, we recommend comparing the balances of your Ripple cold wallet account with the Ripple-backing funds in your internal accounting system each time there is a new Ripple ledger. The cold wallet shows all outstanding issuances as negative balances, which should match the positive assets you have allocated to Ripple outside the network. If the two do not match up, then you should suspend processing payments in and out of Ripple until you have resolved the discrepancy. </p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Use <a href="rippled-apis.html#account-lines"><code>rippled</code>'s <code>account_lines</code> command</a> or <a href="rippleapi.html#gettrustlines">RippleAPI's <code>getTrustlines</code> method</a> to check your balances.</li>
|
<li>Use <a href="reference-rippled.html#account-lines"><code>rippled</code>'s <code>account_lines</code> command</a> or <a href="reference-rippleapi.html#gettrustlines">RippleAPI's <code>getTrustlines</code> method</a> to check your balances.</li>
|
||||||
<li>If you have a <a href="#transferrate">TransferRate</a> set, then your obligations within the Ripple network decrease slightly whenever other users transfer your issuances among themselves.</li>
|
<li>If you have a <a href="#transferrate">TransferRate</a> set, then your obligations within the Ripple network decrease slightly whenever other users transfer your issuances among themselves.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h2 id="transferrate">TransferRate</h2>
|
<h2 id="transferrate">TransferRate</h2>
|
||||||
<p>The <em>TransferRate</em> setting (<code>transferRate</code> in RippleAPI) defines a fee to charge for transferring issuances from one Ripple account to another. See <a href="https://ripple.com/knowledge_center/transfer-fees/">Transfer Fees</a> in the Knowledge Center for more information.</p>
|
<p>The <em>TransferRate</em> setting (<code>transferRate</code> in RippleAPI) defines a fee to charge for transferring issuances from one Ripple account to another. See <a href="https://ripple.com/knowledge_center/transfer-fees/">Transfer Fees</a> in the Knowledge Center for more information.</p>
|
||||||
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> to send an AccountSet transaction for cold wallet account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW, setting the TransferRate to charge a fee of 0.5%.</p>
|
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="reference-rippled.html#submit"><code>submit</code> command</a> to send an AccountSet transaction for cold wallet account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW, setting the TransferRate to charge a fee of 0.5%.</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>
|
<pre><code>
|
||||||
{
|
{
|
||||||
@@ -600,14 +603,14 @@ Content-Type: application/json
|
|||||||
<h3 id="transferrate-with-hot-and-warm-wallets">TransferRate with Hot and Warm Wallets</h3>
|
<h3 id="transferrate-with-hot-and-warm-wallets">TransferRate with Hot and Warm Wallets</h3>
|
||||||
<p>All Ripple Accounts, including the hot wallet, are subject to the TransferRate. If you set a nonzero TransferRate, then you must send extra (to pay the TransferRate) when making payments to users from your hot wallet. In other words, your hot wallet must pay back a little of the money your cold wallet issued it each time you make a payment.</p>
|
<p>All Ripple Accounts, including the hot wallet, are subject to the TransferRate. If you set a nonzero TransferRate, then you must send extra (to pay the TransferRate) when making payments to users from your hot wallet. In other words, your hot wallet must pay back a little of the money your cold wallet issued it each time you make a payment.</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>In <code>rippled</code>'s APIs, you can accomplish this by setting the <a href="transactions.html#payment"><code>SendMax</code> transaction parameter</a> higher than the destination <code>Amount</code> parameter.</li>
|
<li>In <code>rippled</code>'s APIs, you can accomplish this by setting the <a href="reference-transaction-format.html#payment"><code>SendMax</code> transaction parameter</a> higher than the destination <code>Amount</code> parameter.</li>
|
||||||
<li>In RippleAPI, you can accomplish this by setting the <code>source.maxAmount</code> parameter higher than the <code>destination.amount</code> parameter; or, by setting the <code>source.amount</code> parameter higher than the <code>destination.minAmount</code> parameter.</li>
|
<li>In RippleAPI, you can accomplish this by setting the <code>source.maxAmount</code> parameter higher than the <code>destination.amount</code> parameter; or, by setting the <code>source.amount</code> parameter higher than the <code>destination.minAmount</code> parameter.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p><strong>Note:</strong> The TransferRate does not apply when sending issuances back to the account that created them. The account that created issuances must always accept them at face value on Ripple. This means that users don't have to pay the TransferRate if they send payments to the cold wallet directly, but they do when sending to the hot wallet. (For example, if ACME sets a TransferRate of 1%, a Ripple payment to deliver 5 EUR.ACME from a user account to ACME's cold wallet would still only cost 5 EUR.ACME. However, the user would need to send 5.05 EUR.ACME in order to deliver 5 EUR.ACME to the hot wallet.) If you accept payments out of Ripple through both accounts, you may want to adjust the amount you credit users in your external system when customers send payments through the hot wallet, to compensate for the TransferRate the customer pays.</p>
|
<p><strong>Note:</strong> The TransferRate does not apply when sending issuances back to the account that created them. The account that created issuances must always accept them at face value on Ripple. This means that users don't have to pay the TransferRate if they send payments to the cold wallet directly, but they do when sending to the hot wallet. (For example, if ACME sets a TransferRate of 1%, a Ripple payment to deliver 5 EUR.ACME from a user account to ACME's cold wallet would still only cost 5 EUR.ACME. However, the user would need to send 5.05 EUR.ACME in order to deliver 5 EUR.ACME to the hot wallet.) If you accept payments out of Ripple through both accounts, you may want to adjust the amount you credit users in your external system when customers send payments through the hot wallet, to compensate for the TransferRate the customer pays.</p>
|
||||||
<h2 id="sending-payments-to-users">Sending Payments to Users</h2>
|
<h2 id="sending-payments-to-users">Sending Payments to Users</h2>
|
||||||
<p>When you build an automated system to send payments into Ripple for your users, you must ensure that it constructs payments carefully. Malicious users are constantly trying to find ways to trick a system into paying them more money than it should.</p>
|
<p>When you build an automated system to send payments into Ripple for your users, you must ensure that it constructs payments carefully. Malicious users are constantly trying to find ways to trick a system into paying them more money than it should.</p>
|
||||||
<p>One common pitfall is performing pathfinding before sending sending a payment to users in Ripple. If you specify the issuers correctly, the <a href="paths.html#default-paths">default paths</a> are sufficient to deliver the currency as intended. </p>
|
<p>One common pitfall is performing pathfinding before sending sending a payment to users in Ripple. If you specify the issuers correctly, the <a href="concept-paths.html#default-paths">default paths</a> are sufficient to deliver the currency as intended. </p>
|
||||||
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> to send a payment from the hot wallet rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to the user account raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n, sending and delivering funds issued by the cold wallet rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW.</p>
|
<p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="reference-rippled.html#submit"><code>submit</code> command</a> to send a payment from the hot wallet rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to the user account raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n, sending and delivering funds issued by the cold wallet rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW.</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"method": "submit",
|
"method": "submit",
|
||||||
@@ -665,9 +668,9 @@ Content-Type: application/json
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<p>In particular, note the following features of the <a href="transactions.html#payment">Payment Transaction</a>:</p>
|
<p>In particular, note the following features of the <a href="reference-transaction-format.html#payment">Payment Transaction</a>:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>No <code>Paths</code> field. The payment will only succeed if it can use a <a href="paths.html#default-paths">default path</a>, which is preferable. Using less direct paths can become much more expensive.</li>
|
<li>No <code>Paths</code> field. The payment will only succeed if it can use a <a href="concept-paths.html#default-paths">default path</a>, which is preferable. Using less direct paths can become much more expensive.</li>
|
||||||
<li>The <code>issuer</code> of both the <code>SendMax</code> and the <code>Amount</code> is the cold wallet. This ensures that the transaction sends and delivers issuances from the cold wallet account, and not from some other gateway.</li>
|
<li>The <code>issuer</code> of both the <code>SendMax</code> and the <code>Amount</code> is the cold wallet. This ensures that the transaction sends and delivers issuances from the cold wallet account, and not from some other gateway.</li>
|
||||||
<li>The <code>value</code> of the <code>SendMax</code> amount is slightly higher than the destination <code>Amount</code>, in order to compensate for the <a href="#transferrate">transfer fee</a>. In this case, the transfer fee is 0.5%, so the <code>SendMax</code> amount is exactly 1.005 times the destination <code>Amount</code>.</li>
|
<li>The <code>value</code> of the <code>SendMax</code> amount is slightly higher than the destination <code>Amount</code>, in order to compensate for the <a href="#transferrate">transfer fee</a>. In this case, the transfer fee is 0.5%, so the <code>SendMax</code> amount is exactly 1.005 times the destination <code>Amount</code>.</li>
|
||||||
</ul>
|
</ul>
|
||||||
@@ -676,8 +679,8 @@ Content-Type: application/json
|
|||||||
<p>The first requirement to bouncing payments is <a href="#robustly-monitoring-for-payments">robustly monitoring for incoming payments</a>. You do not want to accidentally refund a user for more than they sent you! (This is particularly important if your bounce process is automated.) The <a href="https://ripple.com/knowledge_center/partial-payment-flag/">Partial Payment Flag Gateway Bulletin</a> explains how to avoid a common problem.</p>
|
<p>The first requirement to bouncing payments is <a href="#robustly-monitoring-for-payments">robustly monitoring for incoming payments</a>. You do not want to accidentally refund a user for more than they sent you! (This is particularly important if your bounce process is automated.) The <a href="https://ripple.com/knowledge_center/partial-payment-flag/">Partial Payment Flag Gateway Bulletin</a> explains how to avoid a common problem.</p>
|
||||||
<p>Second, you should send bounced payments as Partial Payments. Since other Ripple users can manipulate the cost of pathways between your accounts, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the Ripple Consensus Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from an automated hot wallet or a human-operated warm wallet.</p>
|
<p>Second, you should send bounced payments as Partial Payments. Since other Ripple users can manipulate the cost of pathways between your accounts, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the Ripple Consensus Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from an automated hot wallet or a human-operated warm wallet.</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>To send a Partial Payment using <code>rippled</code>, enable the <a href="transactions.html#payment-flags">tfPartialPayment flag</a> on the transaction. Set the <code>Amount</code> field to the amount you received and omit the <code>SendMax</code> field.</li>
|
<li>To send a Partial Payment using <code>rippled</code>, enable the <a href="reference-transaction-format.html#payment-flags">tfPartialPayment flag</a> on the transaction. Set the <code>Amount</code> field to the amount you received and omit the <code>SendMax</code> field.</li>
|
||||||
<li>To send a Partial Payment using RippleAPI, set the <code>allowPartialPayment</code> field of the <a href="rippleapi.html#payment">Payment object</a> to <code>true</code>. Set the <code>source.maxAmount</code> and <code>destination.amount</code> both equal to the amount you received.</li>
|
<li>To send a Partial Payment using RippleAPI, set the <code>allowPartialPayment</code> field of the <a href="reference-rippleapi.html#payment">Payment object</a> to <code>true</code>. Set the <code>source.maxAmount</code> and <code>destination.amount</code> both equal to the amount you received.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>It is conventional that you take the <code>SourceTag</code> field from the incoming payment (<code>source.tag</code> in RippleAPI) and use that value as the <code>DestinationTag</code> field (<code>destination.tag</code> in RippleAPI) for the return payment.</p>
|
<p>It is conventional that you take the <code>SourceTag</code> field from the incoming payment (<code>source.tag</code> in RippleAPI) and use that value as the <code>DestinationTag</code> field (<code>destination.tag</code> in RippleAPI) for the return payment.</p>
|
||||||
<p>To prevent two systems from bouncing payments back and forth indefinitely, you can set a new Source Tag for the outgoing return payment. If you receive an unexpected payment whose Destination Tag matches the Source Tag of a return you sent, then do not bounce it back again. </p>
|
<p>To prevent two systems from bouncing payments back and forth indefinitely, you can set a new Source Tag for the outgoing return payment. If you receive an unexpected payment whose Destination Tag matches the Source Tag of a return you sent, then do not bounce it back again. </p>
|
||||||
@@ -693,7 +696,7 @@ Content-Type: application/json
|
|||||||
<li>Use the <code>LastLedgerSequence</code> parameter. (RippleAPI does this by default.)</li>
|
<li>Use the <code>LastLedgerSequence</code> parameter. (RippleAPI does this by default.)</li>
|
||||||
<li>Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's <code>LastLedgerSequence</code> parameter.</li>
|
<li>Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's <code>LastLedgerSequence</code> parameter.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>For additional information, consult the <a href="reliable_tx.html">Reliable Transaction Submission</a> guide.</p>
|
<p>For additional information, consult the <a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a> guide.</p>
|
||||||
<h2 id="rippletxt">ripple.txt</h2>
|
<h2 id="rippletxt">ripple.txt</h2>
|
||||||
<p>The <a href="https://wiki.ripple.com/Ripple.txt">ripple.txt</a> standard provides a way to publish information about your gateway so that automated tools and applications can read and understand it.</p>
|
<p>The <a href="https://wiki.ripple.com/Ripple.txt">ripple.txt</a> standard provides a way to publish information about your gateway so that automated tools and applications can read and understand it.</p>
|
||||||
<p>For example, if you run a validating <code>rippled</code> server, you can use ripple.txt to publish the public key of your validating server. You can also publish information about what currencies your gateway issues, and which Ripple account addresses you control, to protect against impostors or confusion.</p>
|
<p>For example, if you run a validating <code>rippled</code> server, you can use ripple.txt to publish the public key of your validating server. You can also publish information about what currencies your gateway issues, and which Ripple account addresses you control, to protect against impostors or confusion.</p>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -138,10 +144,10 @@
|
|||||||
<p>These types of errors can potentially lead to serious problems. For example, an application that fails to find a prior successful payment transaction might erroneously submit another transaction, duplicating the original payment. This underscores the importance that applications base their actions on authoritive transaction results, using the techniques described in this document.</p>
|
<p>These types of errors can potentially lead to serious problems. For example, an application that fails to find a prior successful payment transaction might erroneously submit another transaction, duplicating the original payment. This underscores the importance that applications base their actions on authoritive transaction results, using the techniques described in this document.</p>
|
||||||
<h2 id="background">Background</h2>
|
<h2 id="background">Background</h2>
|
||||||
<p>The Ripple protocol provides a ledger shared across all nodes in the network. Through a <a href="https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">process of consensus and validation</a>, the network agrees on order in which transactions are applied to (or omitted from) the ledger.</p>
|
<p>The Ripple protocol provides a ledger shared across all nodes in the network. Through a <a href="https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">process of consensus and validation</a>, the network agrees on order in which transactions are applied to (or omitted from) the ledger.</p>
|
||||||
<p>Well-formed transactions submitted to trusted Ripple network nodes are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global <a href="tx-cost.html">transaction cost</a> increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction will not be included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction may become viable again. If the transaction does not include expiration, there is no limit to how much later this can occur.</p>
|
<p>Well-formed transactions submitted to trusted Ripple network nodes are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global <a href="concept-transaction-cost.html">transaction cost</a> increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction will not be included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction may become viable again. If the transaction does not include expiration, there is no limit to how much later this can occur.</p>
|
||||||
<p>Applications face additional challenges, in the event of power or network loss, ascertaining the status of submitted transactions. Applications must take care both to properly submit a transaction and later to properly ascertain its authoritative results.</p>
|
<p>Applications face additional challenges, in the event of power or network loss, ascertaining the status of submitted transactions. Applications must take care both to properly submit a transaction and later to properly ascertain its authoritative results.</p>
|
||||||
<h3 id="transaction-timeline">Transaction Timeline</h3>
|
<h3 id="transaction-timeline">Transaction Timeline</h3>
|
||||||
<p>Ripple provides several APIs for submitting transactions, including <a href="rippled-apis.html"><code>rippled</code></a>, and <a href="rippleapi.html">RippleAPI</a>. Regardless of the API used, the transaction is applied to the ledger as follows.</p>
|
<p>Ripple provides several APIs for submitting transactions, including <a href="reference-rippled.html"><code>rippled</code></a>, and <a href="reference-rippleapi.html">RippleAPI</a>. Regardless of the API used, the transaction is applied to the ledger as follows.</p>
|
||||||
<ol>
|
<ol>
|
||||||
<li>An account owner creates and signs a transaction.</li>
|
<li>An account owner creates and signs a transaction.</li>
|
||||||
<li>The owner submits the transaction to the network as a candidate transaction.</li>
|
<li>The owner submits the transaction to the network as a candidate transaction.</li>
|
||||||
@@ -159,9 +165,9 @@
|
|||||||
<p>Each validated ledger instance has a sequence number, which is one greater than the sequence number of the preceding instance. Each ledger also has an identifying hash value, which is uniquely determined from its contents. There may be many different versions of in-progress ledgers, which have the same sequence number but different hash values. Only one version can ever be validated.</p>
|
<p>Each validated ledger instance has a sequence number, which is one greater than the sequence number of the preceding instance. Each ledger also has an identifying hash value, which is uniquely determined from its contents. There may be many different versions of in-progress ledgers, which have the same sequence number but different hash values. Only one version can ever be validated.</p>
|
||||||
<p>Each validated ledger has a canonical order in which transactions apply. This order is deterministic based on the final transaction set of the ledger. In contrast, each <code>rippled</code> server's in-progress ledger is calculated incrementally, as transactions are received. The order in which transactions execute provisionally is usually not the same as the order in which transactions execute to build a new validated ledger. This is one reason why the provisional outcome of a transaction may be different than the final result. For example, a payment may achieve a different final exchange rate depending on whether it executes before or after another payment that would consume the same offer.</p>
|
<p>Each validated ledger has a canonical order in which transactions apply. This order is deterministic based on the final transaction set of the ledger. In contrast, each <code>rippled</code> server's in-progress ledger is calculated incrementally, as transactions are received. The order in which transactions execute provisionally is usually not the same as the order in which transactions execute to build a new validated ledger. This is one reason why the provisional outcome of a transaction may be different than the final result. For example, a payment may achieve a different final exchange rate depending on whether it executes before or after another payment that would consume the same offer.</p>
|
||||||
<h3 id="lastledgersequence">LastLedgerSequence</h3>
|
<h3 id="lastledgersequence">LastLedgerSequence</h3>
|
||||||
<p><a href="transactions.html#lastledgersequence"><code>LastLedgerSequence</code></a> is an optional parameter of all transactions. This instructs the Ripple Consensus Ledger that a transaction must be validated on or before a specific ledger instance. The Ripple Consensus Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's <code>LastLedgerSequence</code> parameter.</p>
|
<p><a href="reference-transaction-format.html#lastledgersequence"><code>LastLedgerSequence</code></a> is an optional parameter of all transactions. This instructs the Ripple Consensus Ledger that a transaction must be validated on or before a specific ledger instance. The Ripple Consensus Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's <code>LastLedgerSequence</code> parameter.</p>
|
||||||
<p>Use the <code>LastLedgerSequence</code> parameter to prevent undesirable cases where a transaction is not promptly validated yet could become viable at some point in the future. Gateways and other back-end applications should specify the <code>LastLedgerSequence</code> parameter on every transaction. Automated processes should use a value of 4 greater than the sequence number of the last validated ledger[1] to ensure that a transaction is validated or rejected in a predictable and timely fashion.</p>
|
<p>Use the <code>LastLedgerSequence</code> parameter to prevent undesirable cases where a transaction is not promptly validated yet could become viable at some point in the future. Gateways and other back-end applications should specify the <code>LastLedgerSequence</code> parameter on every transaction. Automated processes should use a value of 4 greater than the sequence number of the last validated ledger[1] to ensure that a transaction is validated or rejected in a predictable and timely fashion.</p>
|
||||||
<p>Applications using rippled APIs should explicitly specify a <code>LastLedgerSequence</code> when submitting transactions. RippleAPI uses the <code>maxLedgerVersion</code> field of <a href="rippleapi.html#transaction-instructions">Transaction Instructions</a> to specify the <code>LastLedgerSequence</code>. RippleAPI automatically provides an appropriate value by default. You can specify <code>maxLedgerVersion</code> as <code>null</code> to intentionally omit <code>LastLedgerSequence</code>, in case you want a transaction that can be executed after an unlimited amount of time.</p>
|
<p>Applications using rippled APIs should explicitly specify a <code>LastLedgerSequence</code> when submitting transactions. RippleAPI uses the <code>maxLedgerVersion</code> field of <a href="reference-rippleapi.html#transaction-instructions">Transaction Instructions</a> to specify the <code>LastLedgerSequence</code>. RippleAPI automatically provides an appropriate value by default. You can specify <code>maxLedgerVersion</code> as <code>null</code> to intentionally omit <code>LastLedgerSequence</code>, in case you want a transaction that can be executed after an unlimited amount of time.</p>
|
||||||
<h2 id="best-practices">Best Practices</h2>
|
<h2 id="best-practices">Best Practices</h2>
|
||||||
<h3 id="reliable-transactions-submission">Reliable Transactions Submission</h3>
|
<h3 id="reliable-transactions-submission">Reliable Transactions Submission</h3>
|
||||||
<p>Applications submitting transactions should employ the following practices in order to submit reliably even in the event that a process dies or other failure occurs. Application transaction results must be verified so that applications can act on the final, validated results.</p>
|
<p>Applications submitting transactions should employ the following practices in order to submit reliably even in the event that a process dies or other failure occurs. Application transaction results must be verified so that applications can act on the final, validated results.</p>
|
||||||
@@ -231,13 +237,13 @@
|
|||||||
</ol>
|
</ol>
|
||||||
<p>An application's means of performing these actions depends on the API the application uses. An application may use any of the following interfaces:</p>
|
<p>An application's means of performing these actions depends on the API the application uses. An application may use any of the following interfaces:</p>
|
||||||
<ol>
|
<ol>
|
||||||
<li><a href="rippled-apis.html"><code>rippled</code>'s internal APIs</a></li>
|
<li><a href="reference-rippled.html"><code>rippled</code>'s internal APIs</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li>Any number of other software APIs layered on top of <code>rippled</code></li>
|
<li>Any number of other software APIs layered on top of <code>rippled</code></li>
|
||||||
</ol>
|
</ol>
|
||||||
<h3 id="rippled-submitting-and-verifying-transactions">rippled - Submitting and Verifying Transactions</h3>
|
<h3 id="rippled-submitting-and-verifying-transactions">rippled - Submitting and Verifying Transactions</h3>
|
||||||
<h4 id="determine-the-account-sequence">Determine the Account Sequence</h4>
|
<h4 id="determine-the-account-sequence">Determine the Account Sequence</h4>
|
||||||
<p><code>rippled</code> provides the <a href="rippled-apis.html#account-info">account_info</a> method to learn an account's sequence number in the last validated ledger.</p>
|
<p><code>rippled</code> provides the <a href="reference-rippled.html#account-info">account_info</a> method to learn an account's sequence number in the last validated ledger.</p>
|
||||||
<p>JSON-RPC Request:</p>
|
<p>JSON-RPC Request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"method": "account_info",
|
"method": "account_info",
|
||||||
@@ -272,7 +278,7 @@
|
|||||||
<p>In this example, the account's sequence is <strong>4</strong> (note <code>"Sequence": 4</code>, in <code>"account_data"</code>) as of the last validated ledger (note <code>"ledger": "validated"</code> in the request, and <code>"validated": "true"</code> in the response).</p>
|
<p>In this example, the account's sequence is <strong>4</strong> (note <code>"Sequence": 4</code>, in <code>"account_data"</code>) as of the last validated ledger (note <code>"ledger": "validated"</code> in the request, and <code>"validated": "true"</code> in the response).</p>
|
||||||
<p>If an application were to submit three transactions signed by this account, they would use sequence numbers 4, 5, and 6. In order to submit multiple transactions without waiting for validation of each, an application should keep a running account sequence number.</p>
|
<p>If an application were to submit three transactions signed by this account, they would use sequence numbers 4, 5, and 6. In order to submit multiple transactions without waiting for validation of each, an application should keep a running account sequence number.</p>
|
||||||
<h4 id="determine-the-last-validated-ledger">Determine the Last Validated Ledger</h4>
|
<h4 id="determine-the-last-validated-ledger">Determine the Last Validated Ledger</h4>
|
||||||
<p><code>rippled</code> provides the <a href="rippled-apis.html#server-state">server_state</a> command which returns the ledger sequence number of the last validated ledger.</p>
|
<p><code>rippled</code> provides the <a href="reference-rippled.html#server-state">server_state</a> command which returns the ledger sequence number of the last validated ledger.</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"id": "client id 1",
|
"id": "client id 1",
|
||||||
@@ -313,7 +319,7 @@
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p>In this example the last validated ledger sequence number is 10268596 (found under <code>result.state.validated_ledger</code> in the response). Note also this example indicates a gap in ledger history. The server used here would not be able to provide information about the transactions applied during that gap (ledgers 10256383 through 10256411). If configured to do so, the server will eventually retrieve that portion of the ledger history.</p>
|
<p>In this example the last validated ledger sequence number is 10268596 (found under <code>result.state.validated_ledger</code> in the response). Note also this example indicates a gap in ledger history. The server used here would not be able to provide information about the transactions applied during that gap (ledgers 10256383 through 10256411). If configured to do so, the server will eventually retrieve that portion of the ledger history.</p>
|
||||||
<h4 id="construct-the-transaction">Construct the Transaction</h4>
|
<h4 id="construct-the-transaction">Construct the Transaction</h4>
|
||||||
<p><code>rippled</code> provides the <a href="rippled-apis.html#sign">sign method</a> to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted <code>rippled</code> instances. This example issues 10 FOO (a made-up currency) from a gateway to another Ripple account.</p>
|
<p><code>rippled</code> provides the <a href="reference-rippled.html#sign">sign method</a> to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted <code>rippled</code> instances. This example issues 10 FOO (a made-up currency) from a gateway to another Ripple account.</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"method": "sign",
|
"method": "sign",
|
||||||
@@ -367,7 +373,7 @@
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p>Applications should persist the transaction's hash before submitting. The result of the <code>sign</code> method includes the hash under <code>tx_json</code>.</p>
|
<p>Applications should persist the transaction's hash before submitting. The result of the <code>sign</code> method includes the hash under <code>tx_json</code>.</p>
|
||||||
<h4 id="submit-the-transaction">Submit the transaction</h4>
|
<h4 id="submit-the-transaction">Submit the transaction</h4>
|
||||||
<p><code>rippled</code> provides the <a href="rippled-apis.html#submit"><code>submit</code> method</a>, allowing us to submit the signed transaction. This uses the <code>tx_blob</code> parameter that was returned by the <code>sign</code> method.</p>
|
<p><code>rippled</code> provides the <a href="reference-rippled.html#submit"><code>submit</code> method</a>, allowing us to submit the signed transaction. This uses the <code>tx_blob</code> parameter that was returned by the <code>sign</code> method.</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"method": "submit",
|
"method": "submit",
|
||||||
@@ -408,7 +414,7 @@
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p>This a <strong>preliminary</strong> result. Final results are only available from validated ledgers. The lack of a <code>"validated": true</code> field indicates that this is <strong>not an immutable result</strong>.</p>
|
<p>This a <strong>preliminary</strong> result. Final results are only available from validated ledgers. The lack of a <code>"validated": true</code> field indicates that this is <strong>not an immutable result</strong>.</p>
|
||||||
<h4 id="verify-the-transaction">Verify the Transaction</h4>
|
<h4 id="verify-the-transaction">Verify the Transaction</h4>
|
||||||
<p>The transaction hash, generated when the transaction was signed, is passed to the <a href="rippled-apis.html#tx"><code>tx</code> method</a> to retrieve the result of a transaction.</p>
|
<p>The transaction hash, generated when the transaction was signed, is passed to the <a href="reference-rippled.html#tx"><code>tx</code> method</a> to retrieve the result of a transaction.</p>
|
||||||
<p>Request:</p>
|
<p>Request:</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"method": "tx",
|
"method": "tx",
|
||||||
@@ -454,7 +460,7 @@
|
|||||||
<p>This example response shows <code>"validated": true</code>, indicating the transaction has been included in a validated ledger and therefore the result of the transaction is immutable. Further, the metadata includes <code>"TransactionResult": "tesSUCCESS"</code>, indicating the transaction was applied to the ledger.</p>
|
<p>This example response shows <code>"validated": true</code>, indicating the transaction has been included in a validated ledger and therefore the result of the transaction is immutable. Further, the metadata includes <code>"TransactionResult": "tesSUCCESS"</code>, indicating the transaction was applied to the ledger.</p>
|
||||||
<p>If the response does not include <code>"validated": true</code>, the result is provisional and subject to change. To retrieve a final result, applications must invoke the <code>tx</code> method again, allowing enough time for the network to validate subsequent ledger instances. It may be necessary to wait for the ledger specified in <code>LastLedgerSequence</code> to be validated, although if the transaction is included in an earlier validated ledger the result become immutable at that time.</p>
|
<p>If the response does not include <code>"validated": true</code>, the result is provisional and subject to change. To retrieve a final result, applications must invoke the <code>tx</code> method again, allowing enough time for the network to validate subsequent ledger instances. It may be necessary to wait for the ledger specified in <code>LastLedgerSequence</code> to be validated, although if the transaction is included in an earlier validated ledger the result become immutable at that time.</p>
|
||||||
<h4 id="verify-missing-transaction">Verify Missing Transaction</h4>
|
<h4 id="verify-missing-transaction">Verify Missing Transaction</h4>
|
||||||
<p>Applications must handle cases where a call to the <a href="rippled-apis.html#tx"><code>tx</code> method</a> returns a <code>txnNotFound</code> error.</p>
|
<p>Applications must handle cases where a call to the <a href="reference-rippled.html#tx"><code>tx</code> method</a> returns a <code>txnNotFound</code> error.</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"result": {
|
"result": {
|
||||||
"status": "error",
|
"status": "error",
|
||||||
@@ -470,7 +476,7 @@
|
|||||||
}
|
}
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<p>The <code>txnNotFound</code> result code occurs in cases where the transaction has failed to be included in any ledger. However, it could also occur when a rippled instance does not have a complete ledger history, or if the transaction has not yet propagated to the rippled instance. Applications should make further queries to determine how to react.</p>
|
<p>The <code>txnNotFound</code> result code occurs in cases where the transaction has failed to be included in any ledger. However, it could also occur when a rippled instance does not have a complete ledger history, or if the transaction has not yet propagated to the rippled instance. Applications should make further queries to determine how to react.</p>
|
||||||
<p>The <a href="rippled-apis.html#server-state"><code>server_state</code> method</a> (used earlier to determine the last validated ledger) indicates how complete the ledger history is, under <code>result.state.complete_ledgers</code>.</p>
|
<p>The <a href="reference-rippled.html#server-state"><code>server_state</code> method</a> (used earlier to determine the last validated ledger) indicates how complete the ledger history is, under <code>result.state.complete_ledgers</code>.</p>
|
||||||
<pre><code>{
|
<pre><code>{
|
||||||
"result": {
|
"result": {
|
||||||
"status": "success",
|
"status": "success",
|
||||||
@@ -505,9 +511,9 @@
|
|||||||
<p>Finally the server state might indicate one or more gaps in the transaction history. The <code>completed_ledgers</code> field shown in the response above indicates that ledgers 10256383 through 10256411 are missing from this rippled instance. Our example transaction can only appear in ledgers 10268597 - 10268600 (based on when it was submitted and <code>LastLedgerSequence</code>), so the gap shown here is not relevant. However, if the gap indicated a ledger in that range was missing, then an application would need to query another rippled server (or wait for this one to retrieve the missing ledgers) in order to determine that a <code>txnNotFound</code> result is immutable.</p>
|
<p>Finally the server state might indicate one or more gaps in the transaction history. The <code>completed_ledgers</code> field shown in the response above indicates that ledgers 10256383 through 10256411 are missing from this rippled instance. Our example transaction can only appear in ledgers 10268597 - 10268600 (based on when it was submitted and <code>LastLedgerSequence</code>), so the gap shown here is not relevant. However, if the gap indicated a ledger in that range was missing, then an application would need to query another rippled server (or wait for this one to retrieve the missing ledgers) in order to determine that a <code>txnNotFound</code> result is immutable.</p>
|
||||||
<h2 id="additional-resources">Additional Resources</h2>
|
<h2 id="additional-resources">Additional Resources</h2>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="transactions.html">Transaction Format</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li>Documentation of <a href="transactions.html#lastledgersequence"><code>LastLedgerSequence</code></a></li>
|
<li>Documentation of <a href="reference-transaction-format.html#lastledgersequence"><code>LastLedgerSequence</code></a></li>
|
||||||
<li><a href="http://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">Overview of Ripple Ledger Consensus Process</a></li>
|
<li><a href="http://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">Overview of Ripple Ledger Consensus Process</a></li>
|
||||||
<li><a href="https://ripple.com/knowledge_center/reaching-consensus-in-ripple/">Reaching Consensus in Ripple</a></li>
|
<li><a href="https://ripple.com/knowledge_center/reaching-consensus-in-ripple/">Reaching Consensus in Ripple</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
@@ -5,7 +5,7 @@
|
|||||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||||||
<meta name="viewport" content="width=device-width">
|
<meta name="viewport" content="width=device-width">
|
||||||
|
|
||||||
<title>RippleAPI Quick Start Guide - Ripple Developer Portal</title>
|
<title>RippleAPI Beginners Guide - Ripple Developer Portal</title>
|
||||||
|
|
||||||
<!-- favicon -->
|
<!-- favicon -->
|
||||||
<link rel="icon" href="favicon.ico" type="image/x-icon">
|
<link rel="icon" href="favicon.ico" type="image/x-icon">
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -123,7 +129,7 @@
|
|||||||
<main class="main" role="main">
|
<main class="main" role="main">
|
||||||
<div class='content'>
|
<div class='content'>
|
||||||
<h1 id="rippleapi-beginners-guide">RippleAPI Beginners Guide</h1>
|
<h1 id="rippleapi-beginners-guide">RippleAPI Beginners Guide</h1>
|
||||||
<p>This tutorial guides you through the basics of building a simple Ripple-connected application using <a href="http://nodejs.org/">Node.js</a> and <a href="rippleapi.html">RippleAPI</a>, a simple JavaScript API for accessing the Ripple Consensus Ledger.</p>
|
<p>This tutorial guides you through the basics of building a simple Ripple-connected application using <a href="http://nodejs.org/">Node.js</a> and <a href="reference-rippleapi.html">RippleAPI</a>, a simple JavaScript API for accessing the Ripple Consensus Ledger.</p>
|
||||||
<h1 id="environment-setup">Environment Setup</h1>
|
<h1 id="environment-setup">Environment Setup</h1>
|
||||||
<p>The first step to using RippleAPI successfully is setting up your development environment.</p>
|
<p>The first step to using RippleAPI successfully is setting up your development environment.</p>
|
||||||
<h2 id="install-nodejs-and-npm">Install Node.js and npm</h2>
|
<h2 id="install-nodejs-and-npm">Install Node.js and npm</h2>
|
||||||
@@ -239,17 +245,17 @@ const RippleAPI = require('ripple-lib').RippleAPI;
|
|||||||
});
|
});
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<p>This section creates a new instance of the RippleAPI class, assigning it to the variable <code>api</code>. (The <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const"><code>const</code> keyword</a> means you can't reassign the value <code>api</code> to some other value. The internal state of the object can still change, though.)</p>
|
<p>This section creates a new instance of the RippleAPI class, assigning it to the variable <code>api</code>. (The <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const"><code>const</code> keyword</a> means you can't reassign the value <code>api</code> to some other value. The internal state of the object can still change, though.)</p>
|
||||||
<p>The one argument to the constructor is an options object, which has <a href="rippleapi.html#parameters">a variety of options</a>. The <code>server</code> parameter tells it where it should connect to a <code>rippled</code> server.</p>
|
<p>The one argument to the constructor is an options object, which has <a href="reference-rippleapi.html#parameters">a variety of options</a>. The <code>server</code> parameter tells it where it should connect to a <code>rippled</code> server.</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>The example <code>server</code> setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) operates.</li>
|
<li>The example <code>server</code> setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) operates.</li>
|
||||||
<li>If you don't include the <code>server</code> option, RippleAPI runs in <a href="rippleapi.html#offline-functionality">offline mode</a> instead, which only provides methods that don't need network connectivity.</li>
|
<li>If you don't include the <code>server</code> option, RippleAPI runs in <a href="reference-rippleapi.html#offline-functionality">offline mode</a> instead, which only provides methods that don't need network connectivity.</li>
|
||||||
<li>You can specify a <a href="https://ripple.com/build/ripple-test-net/">Ripple Test Net</a> server instead to connect to the parallel-world Test Network instead of the production Ripple Consensus Ledger.</li>
|
<li>You can specify a <a href="https://ripple.com/build/ripple-test-net/">Ripple Test Net</a> server instead to connect to the parallel-world Test Network instead of the production Ripple Consensus Ledger.</li>
|
||||||
<li>If you <a href="rippled-setup.html">run your own <code>rippled</code></a>, you can instruct it to connect to your local server. For example, you might say <code>server: 'ws://localhost:5005'</code> instead.</li>
|
<li>If you <a href="tutorial-rippled-setup.html">run your own <code>rippled</code></a>, you can instruct it to connect to your local server. For example, you might say <code>server: 'ws://localhost:5005'</code> instead.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<h3 id="connecting-and-promises">Connecting and Promises</h3>
|
<h3 id="connecting-and-promises">Connecting and Promises</h3>
|
||||||
<pre><code>api.connect().then(() => {
|
<pre><code>api.connect().then(() => {
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<p>The <a href="rippleapi.html#connect">connect() method</a> is one of many RippleAPI methods that returns a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>, which is a special kind of JavaScript object. A Promise is designed to perform some asynchronous operation, like querying a the Ripple Consensus Ledger.</p>
|
<p>The <a href="reference-rippleapi.html#connect">connect() method</a> is one of many RippleAPI methods that returns a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>, which is a special kind of JavaScript object. A Promise is designed to perform some asynchronous operation, like querying a the Ripple Consensus Ledger.</p>
|
||||||
<p>When you get a Promise back from some expression (like <code>api.connect()</code>), you call the Promise's <code>then</code> method and pass in a callback function. Passing a function as an argument is conventional in JavaScript, taking advantage of how JavaScript functions are <a href="https://en.wikipedia.org/wiki/First-class_function">first-class objects</a>.</p>
|
<p>When you get a Promise back from some expression (like <code>api.connect()</code>), you call the Promise's <code>then</code> method and pass in a callback function. Passing a function as an argument is conventional in JavaScript, taking advantage of how JavaScript functions are <a href="https://en.wikipedia.org/wiki/First-class_function">first-class objects</a>.</p>
|
||||||
<p>When a Promise finishes with its asynchronous operations, the Promise runs the callback function you passed it. The return value from the <code>then</code> method is another Promise object, so you can "chain" that into another <code>then</code> method, or the Promise's <code>catch</code> method, which also takes a callback. The callback you provide to <code>catch</code> gets called if something goes wrong.</p>
|
<p>When a Promise finishes with its asynchronous operations, the Promise runs the callback function you passed it. The return value from the <code>then</code> method is another Promise object, so you can "chain" that into another <code>then</code> method, or the Promise's <code>catch</code> method, which also takes a callback. The callback you provide to <code>catch</code> gets called if something goes wrong.</p>
|
||||||
<p>Finally, we have more new ECMAScript 6 syntax - an <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">arrow function</a>. Arrow functions are just a shorter way of defining anonymous functions, which is pretty convenient when you're defining lots of one-off functions as callbacks, like we are here. The syntax <code>()=> {...}</code> is mostly equivalent to <code>function() {...}</code>. If you want an anonymous function with one parameter, you can use a syntax like <code>info => {...}</code> instead, which is basically just <code>function(info) {...}</code> as well.</p>
|
<p>Finally, we have more new ECMAScript 6 syntax - an <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">arrow function</a>. Arrow functions are just a shorter way of defining anonymous functions, which is pretty convenient when you're defining lots of one-off functions as callbacks, like we are here. The syntax <code>()=> {...}</code> is mostly equivalent to <code>function() {...}</code>. If you want an anonymous function with one parameter, you can use a syntax like <code>info => {...}</code> instead, which is basically just <code>function(info) {...}</code> as well.</p>
|
||||||
@@ -269,7 +275,7 @@ const RippleAPI = require('ripple-lib').RippleAPI;
|
|||||||
<p>This is the part that really defines what this script does, so this is the part you will probably spend the most time customizing.</p>
|
<p>This is the part that really defines what this script does, so this is the part you will probably spend the most time customizing.</p>
|
||||||
<p>The example code looks up a Ripple account (belonging to <a href="https://github.com/mDuo13/">this writer</a>) by its address. You can substitute your own address, if you want.</p>
|
<p>The example code looks up a Ripple account (belonging to <a href="https://github.com/mDuo13/">this writer</a>) by its address. You can substitute your own address, if you want.</p>
|
||||||
<p>The <code>console.log()</code> function is a built-in tool in both Node.js and web browsers, which writes out to the console; this example includes lots of console output to make it easier to understand what the code is doing.</p>
|
<p>The <code>console.log()</code> function is a built-in tool in both Node.js and web browsers, which writes out to the console; this example includes lots of console output to make it easier to understand what the code is doing.</p>
|
||||||
<p>Keep in mind that the example code starts in the middle of a callback function (called when RippleAPI finishes connecting). That function calls RippleAPI's <a href="rippleapi.html#getaccountinfo"><code>getAccountInfo</code></a> method, and returns the results.</p>
|
<p>Keep in mind that the example code starts in the middle of a callback function (called when RippleAPI finishes connecting). That function calls RippleAPI's <a href="reference-rippleapi.html#getaccountinfo"><code>getAccountInfo</code></a> method, and returns the results.</p>
|
||||||
<p>The results of that API method are another Promise, so the line <code>}).then( info => {</code> passes in another anonymous callback function to run when the second Promise's asynchronous work is done. Unlike the previous case, this callback function takes one argument, called <code>info</code>, which holds the -- actual -- return value from the <code>getAccountInfo</code> API method. The rest of this callback function just outputs that return value to the console.</p>
|
<p>The results of that API method are another Promise, so the line <code>}).then( info => {</code> passes in another anonymous callback function to run when the second Promise's asynchronous work is done. Unlike the previous case, this callback function takes one argument, called <code>info</code>, which holds the -- actual -- return value from the <code>getAccountInfo</code> API method. The rest of this callback function just outputs that return value to the console.</p>
|
||||||
<h3 id="cleanup">Cleanup</h3>
|
<h3 id="cleanup">Cleanup</h3>
|
||||||
<pre><code>}).then(() => {
|
<pre><code>}).then(() => {
|
||||||
@@ -278,10 +284,10 @@ const RippleAPI = require('ripple-lib').RippleAPI;
|
|||||||
console.log('done and disconnected.');
|
console.log('done and disconnected.');
|
||||||
}).catch(console.error);
|
}).catch(console.error);
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<p>The remainder of the sample code is mostly more <a href="rippleapi.html#boilerplate">boilerplate code</a>. The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the Ripple Consensus Ledger, and has yet another callback which writes to the console when it finishes.</p>
|
<p>The remainder of the sample code is mostly more <a href="reference-rippleapi.html#boilerplate">boilerplate code</a>. The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the Ripple Consensus Ledger, and has yet another callback which writes to the console when it finishes.</p>
|
||||||
<p>Finally, we get to the <code>catch</code> method of this entire long Promise chain. If any of the Promises or their callback functions encounters an error, the callback provided here will run. One thing worth noting: instead of defining a new anonymous callback function here, we can just pass in the standard <code>console.error</code> function, which writes whatever arguments it gets out to the console. If you so desired, you could define a smarter callback function here which might intelligently catch certain error types.</p>
|
<p>Finally, we get to the <code>catch</code> method of this entire long Promise chain. If any of the Promises or their callback functions encounters an error, the callback provided here will run. One thing worth noting: instead of defining a new anonymous callback function here, we can just pass in the standard <code>console.error</code> function, which writes whatever arguments it gets out to the console. If you so desired, you could define a smarter callback function here which might intelligently catch certain error types.</p>
|
||||||
<h1 id="waiting-for-validation">Waiting for Validation</h1>
|
<h1 id="waiting-for-validation">Waiting for Validation</h1>
|
||||||
<p>One of the biggest challenges in using the Ripple Consensus Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you <a href="reliable_tx.html">follow the best practices</a> you still have to wait for the <a href="https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">consensus process</a> to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction:</p>
|
<p>One of the biggest challenges in using the Ripple Consensus Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you <a href="tutorial-reliable-transaction-submission.html">follow the best practices</a> you still have to wait for the <a href="https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">consensus process</a> to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction:</p>
|
||||||
<pre><code>'use strict';
|
<pre><code>'use strict';
|
||||||
/* import RippleAPI and support libraies*/
|
/* import RippleAPI and support libraies*/
|
||||||
const RippleAPI = require('ripple-lib').RippleAPI;
|
const RippleAPI = require('ripple-lib').RippleAPI;
|
||||||
@@ -378,8 +384,8 @@ api.connect().then(() => {
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
<p>This code creates and submits an order transaction, although the same principles apply to other types of transactions as well. After submitting the transaction, the code uses a new Promise, which queries the ledger again after using setTimeout to wait a fixed amount of time, to see if the transaction has been verified. If it hasn't been verified, the process repeats until either the transaction is found in a validated ledger or the returned ledger is higher than the LastLedgerSequence parameter.</p>
|
<p>This code creates and submits an order transaction, although the same principles apply to other types of transactions as well. After submitting the transaction, the code uses a new Promise, which queries the ledger again after using setTimeout to wait a fixed amount of time, to see if the transaction has been verified. If it hasn't been verified, the process repeats until either the transaction is found in a validated ledger or the returned ledger is higher than the LastLedgerSequence parameter.</p>
|
||||||
<p>In rare cases (particularly with a large delay or a loss of power), the <code>rippled</code> server may be missing a ledger version between when you submitted the transaction and when you determined that the network has passed the <code>maxLedgerVersion</code>. In this case, you cannot be definitively sure whether the transaction has failed, or has been included in one of the missing ledger versions. RippleAPI returns <code>MissingLedgerHistoryError</code> in this case.</p>
|
<p>In rare cases (particularly with a large delay or a loss of power), the <code>rippled</code> server may be missing a ledger version between when you submitted the transaction and when you determined that the network has passed the <code>maxLedgerVersion</code>. In this case, you cannot be definitively sure whether the transaction has failed, or has been included in one of the missing ledger versions. RippleAPI returns <code>MissingLedgerHistoryError</code> in this case.</p>
|
||||||
<p>If you are the administrator of the <code>rippled</code> server, you can <a href="rippled-apis.html#ledger-request">manually request the missing ledger(s)</a>. Otherwise, you can try checking the ledger history using a different server. (Ripple runs a public full-history server at <code>s2.ripple.com</code> for this purpose.)</p>
|
<p>If you are the administrator of the <code>rippled</code> server, you can <a href="reference-rippled.html#ledger-request">manually request the missing ledger(s)</a>. Otherwise, you can try checking the ledger history using a different server. (Ripple runs a public full-history server at <code>s2.ripple.com</code> for this purpose.)</p>
|
||||||
<p>See <a href="reliable_tx.html">Reliable Transaction Submission</a> for a more thorough explanation.</p>
|
<p>See <a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a> for a more thorough explanation.</p>
|
||||||
<h1 id="rippleapi-in-web-browsers">RippleAPI in Web Browsers</h1>
|
<h1 id="rippleapi-in-web-browsers">RippleAPI in Web Browsers</h1>
|
||||||
<p>The process of using RippleAPI in a web browser is slightly different.</p>
|
<p>The process of using RippleAPI in a web browser is slightly different.</p>
|
||||||
<h2 id="build-instructions">Build Instructions</h2>
|
<h2 id="build-instructions">Build Instructions</h2>
|
||||||
@@ -57,34 +57,40 @@
|
|||||||
<div class="container">
|
<div class="container">
|
||||||
<ul id="menu-dev-menu" class="menu">
|
<ul id="menu-dev-menu" class="menu">
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="paths.html">Paths</a></li>
|
<li><a href="reference-rippled.html">rippled</a></li>
|
||||||
<li><a href="fees.html">Fees (Disambiguation)</a></li>
|
<li><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||||||
<li><a href="transfer_fees.html">Transfer Fees</a></li>
|
<li><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||||||
<li><a href="tx-cost.html">Transaction Cost</a></li>
|
<li><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||||||
<li><a href="fee-voting.html">Fee Voting</a></li>
|
<li><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||||||
<li><a href="reserves.html">Reserves</a></li>
|
|
||||||
<li><a href="freeze.html">Freeze</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippleapi_quickstart.html">RippleAPI Quick Start Guide</a></li>
|
<li><a href="tutorial-rippleapi-beginners-guide.html">RippleAPI Beginners Guide</a></li>
|
||||||
<li><a href="rippled-setup.html">rippled Setup</a></li>
|
<li><a href="tutorial-rippled-setup.html">rippled Setup</a></li>
|
||||||
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
|
<li><a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></li>
|
||||||
<li><a href="gateway_guide.html">Gateway Guide</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
|
||||||
<ul class="dropdown-menu" role="menu">
|
<ul class="dropdown-menu" role="menu">
|
||||||
<li><a href="rippled-apis.html">rippled</a></li>
|
<li><a href="concept-paths.html">Paths</a></li>
|
||||||
<li><a href="transactions.html">Transactions</a></li>
|
<li><a href="concept-fees.html">Fees (Disambiguation)</a></li>
|
||||||
<li><a href="ripple-ledger.html">Ledger Format</a></li>
|
<li><a href="concept-transfer-fees.html">Transfer Fees</a></li>
|
||||||
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
|
<li><a href="concept-transaction-cost.html">Transaction Cost</a></li>
|
||||||
<li><a href="rippleapi.html">RippleAPI</a></li>
|
<li><a href="concept-fee-voting.html">Fee Voting</a></li>
|
||||||
|
<li><a href="concept-reserves.html">Reserves</a></li>
|
||||||
|
<li><a href="concept-freeze.html">Freeze</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li class="dropdown">
|
||||||
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Best Practices <span class="caret"></span></a>
|
||||||
|
<ul class="dropdown-menu" role="menu">
|
||||||
|
<li><a href="concept-issuing-and-operational-accounts.html">Issuing and Operational Acounts</a></li>
|
||||||
|
<li><a href="tutorial-gateway-guide.html">Gateway Guide</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="dropdown">
|
<li class="dropdown">
|
||||||
@@ -123,7 +129,7 @@
|
|||||||
<main class="main" role="main">
|
<main class="main" role="main">
|
||||||
<div class='content'>
|
<div class='content'>
|
||||||
<h1 id="operating-rippled-servers">Operating rippled Servers</h1>
|
<h1 id="operating-rippled-servers">Operating rippled Servers</h1>
|
||||||
<p>The core server of the Ripple peer-to-peer network is <a href="rippled-apis.html"><code>rippled</code></a>. Anyone can run their own <code>rippled</code> server that follows the network and keeps a complete copy of the Ripple ledger. You can even have your server perform validations and participate in the consensus process.</p>
|
<p>The core server of the Ripple peer-to-peer network is <a href="reference-rippled.html"><code>rippled</code></a>. Anyone can run their own <code>rippled</code> server that follows the network and keeps a complete copy of the Ripple ledger. You can even have your server perform validations and participate in the consensus process.</p>
|
||||||
<p>This page contains instructions for:</p>
|
<p>This page contains instructions for:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="#installing-rippled">Installing <code>rippled</code></a></li>
|
<li><a href="#installing-rippled">Installing <code>rippled</code></a></li>
|
||||||
@@ -136,7 +142,7 @@
|
|||||||
<li>Validating server, or <em>validator</em> for short - participates in consensus.</li>
|
<li>Validating server, or <em>validator</em> for short - participates in consensus.</li>
|
||||||
<li><code>rippled</code> server in stand-alone mode - for basic testing. Does not communicate to other <code>rippled</code> servers.</li>
|
<li><code>rippled</code> server in stand-alone mode - for basic testing. Does not communicate to other <code>rippled</code> servers.</li>
|
||||||
</ul>
|
</ul>
|
||||||
<p>You can also run the <code>rippled</code> executable as a client application for accessing <a href="rippled-apis.html"><code>rippled</code> APIs</a> locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.)</p>
|
<p>You can also run the <code>rippled</code> executable as a client application for accessing <a href="reference-rippled.html"><code>rippled</code> APIs</a> locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.)</p>
|
||||||
<h2 id="reasons-to-run-a-stock-server">Reasons to Run a Stock Server</h2>
|
<h2 id="reasons-to-run-a-stock-server">Reasons to Run a Stock Server</h2>
|
||||||
<p>There are lots of reasons you might want to run your own <code>rippled</code> server, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it.</p>
|
<p>There are lots of reasons you might want to run your own <code>rippled</code> server, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it.</p>
|
||||||
<p>It is important that you can trust the <code>rippled</code> you use, so you can be certain that the software you are running will behave in the manner specified in its source code. Of course, you must also practice good network security to protect your server from malicious hackers. If you connect to a malicious server, there are myriad ways that it can take advantage of you or cause you to lose money. For example:</p>
|
<p>It is important that you can trust the <code>rippled</code> you use, so you can be certain that the software you are running will behave in the manner specified in its source code. Of course, you must also practice good network security to protect your server from malicious hackers. If you connect to a malicious server, there are myriad ways that it can take advantage of you or cause you to lose money. For example:</p>
|
||||||
@@ -214,7 +220,7 @@
|
|||||||
</li>
|
</li>
|
||||||
</ol>
|
</ol>
|
||||||
<p>It can take several minutes for <code>rippled</code> to sync with the rest of the network, during which time it outputs warnings about missing ledgers. After that, you have a fully functional stock <code>rippled</code> server that you can use for local signing and API access to the Ripple peer-to-peer network.</p>
|
<p>It can take several minutes for <code>rippled</code> to sync with the rest of the network, during which time it outputs warnings about missing ledgers. After that, you have a fully functional stock <code>rippled</code> server that you can use for local signing and API access to the Ripple peer-to-peer network.</p>
|
||||||
<p><a href="https://ripple.com/build/rippled-apis/#list-of-public-commands">rippled commands</a> can be run with:</p>
|
<p><a href="reference-rippled.html#list-of-public-commands">rippled commands</a> can be run with:</p>
|
||||||
<pre><code> $ /opt/ripple/bin/rippled --conf /opt/ripple/etc/rippled.cfg <command>
|
<pre><code> $ /opt/ripple/bin/rippled --conf /opt/ripple/etc/rippled.cfg <command>
|
||||||
</code></pre>
|
</code></pre>
|
||||||
<h2 id="updating-rippled">Updating rippled</h2>
|
<h2 id="updating-rippled">Updating rippled</h2>
|
||||||
@@ -328,7 +334,7 @@ ssdecohJMDPFuUPDkmG1w4objZyp4
|
|||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
<p>Set the <a href="https://ripple.com/build/transactions/#domain"><code>Domain</code> field</a> of the account to match the domain hosting your ripple.txt</p>
|
<p>Set the <a href="reference-transaction-format.html#domain"><code>Domain</code> field</a> of the account to match the domain hosting your ripple.txt</p>
|
||||||
<pre><code>$ /opt/ripple/bin/rippled --conf /opt/ripple/etc/rippled.cfg submit <your-secret-key> '{"TransactionType": "AccountSet", "Account": "<your-account-id>", "Domain": "<your-hex-encoded-domain>", "Fee": "10000"}'
|
<pre><code>$ /opt/ripple/bin/rippled --conf /opt/ripple/etc/rippled.cfg submit <your-secret-key> '{"TransactionType": "AccountSet", "Account": "<your-account-id>", "Domain": "<your-hex-encoded-domain>", "Fee": "10000"}'
|
||||||
</code></pre>
|
</code></pre>
|
||||||
</li>
|
</li>
|
||||||
@@ -371,7 +377,7 @@ ssdecohJMDPFuUPDkmG1w4objZyp4
|
|||||||
</code></pre>
|
</code></pre>
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
<p>Generate a unique seed (using the <a href="rippled-apis.html#validation-seed"><code>validation_create</code> command</a>) for each of your servers, and configure it under the <code>[node_seed]</code> section. The <code>rippled</code> server uses this key to sign its messages to other servers in the peer-to-peer network. <strong>Note:</strong> This is a different key than the one <code>rippled</code> uses to sign ledger proposals for consensus, but it is in the same format.</p>
|
<p>Generate a unique seed (using the <a href="reference-rippled.html#validation-seed"><code>validation_create</code> command</a>) for each of your servers, and configure it under the <code>[node_seed]</code> section. The <code>rippled</code> server uses this key to sign its messages to other servers in the peer-to-peer network. <strong>Note:</strong> This is a different key than the one <code>rippled</code> uses to sign ledger proposals for consensus, but it is in the same format.</p>
|
||||||
</li>
|
</li>
|
||||||
<li>Add the public keys (for peer communication) of each of your other servers under the <code>[cluster_nodes]</code> section.</li>
|
<li>Add the public keys (for peer communication) of each of your other servers under the <code>[cluster_nodes]</code> section.</li>
|
||||||
</ul>
|
</ul>
|
||||||
Reference in New Issue
Block a user