mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-14 16:55:50 +00:00
1994 lines
112 KiB
HTML
1994 lines
112 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
|
||
<meta content="width=device-width" name="viewport">
|
||
<title>Transaction Format - Ripple Developer Portal</title>
|
||
<!-- favicon -->
|
||
<link href="favicon.ico" rel="icon" type="image/x-icon">
|
||
<link href="favicon.ico" rel="shortcut icon" 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 href="assets/vendor/docco.min.css" rel="stylesheet">
|
||
<script src="assets/vendor/highlight.min.js"></script>
|
||
<!-- syntax selection js -->
|
||
<script src="assets/js/multicodetab.js"></script>
|
||
<script>
|
||
$(document).ready(function() {
|
||
$().multicode_tabs();
|
||
hljs.initHighlighting();
|
||
make_code_expandable();
|
||
});
|
||
</script>
|
||
<script src="assets/js/expandcode.js"></script>
|
||
<script src="assets/js/fixsidebarscroll.js"></script>
|
||
</link></link></link></meta></meta></meta></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 class="banner navbar navbar-default navbar-fixed-top initial_header" role="banner">
|
||
<div class="container">
|
||
<div class="navbar-header">
|
||
<a class="navbar-brand" href="index.html"><img class="logo" src="assets/img/ripple-logo-color.png"/></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 class="menu" id="menu-dev-menu">
|
||
<li class="dropdown">
|
||
<a class="dropdown-toggle" data-toggle="dropdown" href="#">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 class="dropdown-toggle" data-toggle="dropdown" href="#">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 class="dropdown-toggle" data-toggle="dropdown" href="#">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 class="dropdown-toggle" data-toggle="dropdown" href="#">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 class="dropdown-toggle" data-toggle="dropdown" href="#">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>
|
||
<li><a href="tool-jsonrpc.html">rippled JSON-RPC Tool</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="dropdown">
|
||
<a class="dropdown-toggle" data-toggle="dropdown" href="#">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>
|
||
</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">
|
||
<div id="cont">
|
||
<ul class="dev_nav_sidebar">
|
||
<li class="level-1"><a href="index.html">Category: References</a></li>
|
||
<li class="level-2"><a href="reference-rippled.html">rippled</a></li>
|
||
<li class="level-2"><a href="reference-transaction-format.html">Transaction Format</a></li>
|
||
<li class="level-2"><a href="reference-ledger-format.html">Ledger Format</a></li>
|
||
<li class="level-2"><a href="reference-rippleapi.html">RippleAPI</a></li>
|
||
<li class="level-2"><a href="reference-data-api.html">Ripple Data API v2</a></li>
|
||
</ul>
|
||
<hr/>
|
||
<h5>In this page:</h5>
|
||
</div>
|
||
<script src="assets/js/jquery.gensidebar.js" type="text/javascript"></script>
|
||
</div>
|
||
</aside>
|
||
<main class="main" role="main">
|
||
<div class="content">
|
||
<h1 id="transactions">Transactions</h1>
|
||
<p>A <em>Transaction</em> is the only way to modify the Ripple Ledger. All transactions have certain fields in common:</p>
|
||
<ul>
|
||
<li><a href="#common-fields">Common Fields</a></li>
|
||
</ul>
|
||
<p>There are several different types of transactions that perform different actions, each with additional fields relevant to that type of action:</p>
|
||
<ul>
|
||
<li><a href="#payment">Payment - Send funds from one account to another</a></li>
|
||
<li><a href="#accountset">AccountSet - Set options on an account</a></li>
|
||
<li><a href="#setregularkey">SetRegularKey - Set an account's regular key</a></li>
|
||
<li><a href="#offercreate">OfferCreate - Submit an order to exchange currency</a></li>
|
||
<li><a href="#offercancel">OfferCancel - Withdraw a currency-exchange order</a></li>
|
||
<li><a href="#trustset">TrustSet - Add or modify a trust line</a></li>
|
||
</ul>
|
||
<p>Additionally, there are <em>Psuedo-Transactions</em> that are not created and submitted in the usual way, but may appear in ledgers:</p>
|
||
<ul>
|
||
<li><a href="#setfee">SetFee - Adjust the minimum transaction cost or account reserve</a></li>
|
||
</ul>
|
||
<p>Transactions are only valid if signed, submitted, and accepted into a validated ledger version. There are many ways a transaction can fail.</p>
|
||
<ul>
|
||
<li><a href="#signing-and-sending-transactions">Signing and Sending Transactions</a></li>
|
||
<li><a href="#reliable-transaction-submission">Reliable Transaction Submission</a></li>
|
||
<li><a href="#transaction-results">Transaction Results - How to find and interpret transaction results</a></li>
|
||
<li><a href="#full-transaction-response-list">Full Transaction Response List - Complete table of all error codes</a></li>
|
||
</ul>
|
||
<h2 id="signing-and-sending-transactions">Signing and Sending Transactions</h2>
|
||
<p>Signing a transaction cryptographically proves that the person in charge of the account sending the transaction is authorized to do so. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction.</p>
|
||
<p>You can sign a transaction using a secret key: either the master secret, or a regular secret if the account has a regular key pair associated with it. (See <a href="#setregularkey">SetRegularKey</a> for details.)</p>
|
||
<p>Multi-signature transactions are <a href="https://wiki.ripple.com/Multisign">in development</a>.</p>
|
||
<p>Typically, you create a transaction in JSON format first. Here is an example of an unsigned Payment-type transaction in JSON:</p>
|
||
<pre><code>{
|
||
"TransactionType" : "Payment",
|
||
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||
"Amount" : {
|
||
"currency" : "USD",
|
||
"value" : "1",
|
||
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
|
||
},
|
||
"Fee": "10",
|
||
"Flags": 2147483648,
|
||
"Sequence": 2,
|
||
}
|
||
</code></pre>
|
||
<p>After doing that, you generate the signed binary format for the transaction. There are two ways to do this:</p>
|
||
<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.<ul>
|
||
<li>You can use <a href="reference-rippleapi.html#sign">RippleAPI</a> to perform offline signing.</li>
|
||
</ul>
|
||
</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.)<ul>
|
||
<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>
|
||
</ul>
|
||
</li>
|
||
</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="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>{
|
||
"id": 2,
|
||
"command": "submit",
|
||
"tx_blob" : "120000240000000461D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000F732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74483046022100982064CDD3F052D22788DB30B52EEA8956A32A51375E72274E417328EBA31E480221008F522C9DB4B0F31E695AA013843958A10DE8F6BA7D6759BEE645F71A7EB240BE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754"
|
||
}
|
||
</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="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>{
|
||
"id": 6,
|
||
"status": "success",
|
||
"type": "response",
|
||
"result": {
|
||
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||
"Amount": {
|
||
"currency": "USD",
|
||
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||
"value": "1"
|
||
},
|
||
"Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||
"Fee": "10",
|
||
"Flags": 2147483648,
|
||
"Sequence": 2,
|
||
"SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
|
||
"TransactionType": "Payment",
|
||
"TxnSignature": "3045022100D64A32A506B86E880480CCB846EFA3F9665C9B11FDCA35D7124F53C486CC1D0402206EC8663308D91C928D1FDA498C3A2F8DD105211B9D90F4ECFD75172BAE733340",
|
||
"date": 455224610,
|
||
"hash": "33EA42FC7A06F062A7B843AF4DC7C0AB00D6644DFDF4C5D354A87C035813D321",
|
||
"inLedger": 7013674,
|
||
"ledger_index": 7013674,
|
||
"meta": {
|
||
"AffectedNodes": [
|
||
{
|
||
"ModifiedNode": {
|
||
"FinalFields": {
|
||
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||
"Balance": "99999980",
|
||
"Flags": 0,
|
||
"OwnerCount": 0,
|
||
"Sequence": 3
|
||
},
|
||
"LedgerEntryType": "AccountRoot",
|
||
"LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
|
||
"PreviousFields": {
|
||
"Balance": "99999990",
|
||
"Sequence": 2
|
||
},
|
||
"PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
|
||
"PreviousTxnLgrSeq": 6979192
|
||
}
|
||
},
|
||
{
|
||
"ModifiedNode": {
|
||
"FinalFields": {
|
||
"Balance": {
|
||
"currency": "USD",
|
||
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
|
||
"value": "2"
|
||
},
|
||
"Flags": 65536,
|
||
"HighLimit": {
|
||
"currency": "USD",
|
||
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||
"value": "0"
|
||
},
|
||
"HighNode": "0000000000000000",
|
||
"LowLimit": {
|
||
"currency": "USD",
|
||
"issuer": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||
"value": "100"
|
||
},
|
||
"LowNode": "0000000000000000"
|
||
},
|
||
"LedgerEntryType": "RippleState",
|
||
"LedgerIndex": "96D2F43BA7AE7193EC59E5E7DDB26A9D786AB1F7C580E030E7D2FF5233DA01E9",
|
||
"PreviousFields": {
|
||
"Balance": {
|
||
"currency": "USD",
|
||
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
|
||
"value": "1"
|
||
}
|
||
},
|
||
"PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
|
||
"PreviousTxnLgrSeq": 6979192
|
||
}
|
||
}
|
||
],
|
||
"TransactionIndex": 0,
|
||
"TransactionResult": "tesSUCCESS"
|
||
},
|
||
"validated": true
|
||
}
|
||
}
|
||
</code></pre>
|
||
<h3 id="reliable-transaction-submission">Reliable Transaction Submission</h3>
|
||
<p>Reliably submitting transactions is the process of achieving both of the following:</p>
|
||
<ul>
|
||
<li>Idempotency - A transaction will be processed once and only once, or not at all.</li>
|
||
<li>Verifiability - Applications can determine the final result of a transaction.</li>
|
||
</ul>
|
||
<p>To accomplish both of these, your application should:</p>
|
||
<ol>
|
||
<li>Construct and sign the transaction first, including a <a href="#lastledgersequence"><code>LastLedgerSequence</code></a> parameter that gives the transaction a limited viable lifespan.</li>
|
||
<li>Persist details of the transaction before submitting.</li>
|
||
<li>Submit the transaction.</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>
|
||
</ol>
|
||
<p>Main article: <a href="tutorial-reliable-transaction-submission.html">Reliable Transaction Submission</a></p>
|
||
<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="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>
|
||
<h2 id="common-fields">Common Fields</h2>
|
||
<p>Every transaction type has the same set of fundamental fields:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>JSON Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Account</td>
|
||
<td>String</td>
|
||
<td>Account</td>
|
||
<td>The unique address of the account that initiated the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#accounttxnid">AccountTxnID</a></td>
|
||
<td>String</td>
|
||
<td>Hash256</td>
|
||
<td>(Optional) Hash value identifying another transaction. This transaction is only valid if the sending account's previously-sent transaction matches the provided hash.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#transaction-cost">Fee</a></td>
|
||
<td>String</td>
|
||
<td>Amount</td>
|
||
<td>(Required, but <a href="#auto-fillable-fields">auto-fillable</a>) Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#flags">Flags</a></td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) Set of bit-flags for this transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#lastledgersequence">LastLedgerSequence</a></td>
|
||
<td>Number</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional, but strongly recommended) Highest ledger sequence number that a transaction can appear in.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#memos">Memos</a></td>
|
||
<td>Array of Objects</td>
|
||
<td>Array</td>
|
||
<td>(Optional) Additional arbitrary information used to identify this transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#canceling-or-skipping-a-transaction">Sequence</a></td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Required, but <a href="#auto-fillable-fields">auto-fillable</a>) The sequence number, relative to the initiating account, of this transaction. A transaction is only valid if the <code>Sequence</code> number is exactly 1 greater than the last-valided transaction from the same account.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>SigningPubKey</td>
|
||
<td>String</td>
|
||
<td>PubKey</td>
|
||
<td>(Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>SourceTag</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) Arbitrary integer used to identify the reason for this payment, or the hosted wallet on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's <code>SourceTag</code> as the refund payment's <code>DestinationTag</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TransactionType</td>
|
||
<td>String</td>
|
||
<td>UInt16</td>
|
||
<td>The type of transaction. Valid types include: <code>Payment</code>, <code>OfferCreate</code>, <code>OfferCancel</code>, <code>TrustSet</code>, <code>AccountSet</code>, and <code>SetRegularKey</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TxnSignature</td>
|
||
<td>String</td>
|
||
<td>VariableLength</td>
|
||
<td>(Automatically added when signing) The signature that verifies this transaction as originating from the account it says it is from.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p><strong>Note:</strong> The deprecated <code>PreviousTxnID</code> transaction parameter was removed entirely in <a href="https://github.com/ripple/rippled/releases/tag/0.28.0-rc1">rippled 0.28.0</a>. Use <code>AccountTxnID</code> instead.</p>
|
||
<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>
|
||
<ul>
|
||
<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>
|
||
</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>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>
|
||
<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="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>
|
||
<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>For example, if you attempted to submit 3 transactions with sequence numbers 11, 12, and 13, but transaction 11 gets lost somehow or does not have a high enough <a href="#transaction-cost">transaction cost</a> to be propagated to the network, then you can cancel transaction 11 by submitting an AccountSet transaction with no options and sequence number 11. This does nothing (except destroying the transaction cost for the new transaction 11), but it allows transactions 12 and 13 to become valid.</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>
|
||
<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="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>
|
||
<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>One situation in which this is useful is if you have a primary system for submitting transactions and a passive backup system. If the passive backup system becomes disconnected from the primary, but the primary is not fully dead, and they both begin operating at the same time, you could potentially encounter serious problems like some transactions sending twice and others not at all. Chaining your transactions together with <code>AccountTxnID</code> ensures that, even if both systems are active, only one of them can submit valid transactions at a time.</p>
|
||
<p>In order to use AccountTxnID, you must first set the <a href="#accountset-flags">asfAccountTxnID</a> flag, so that the ledger keeps track of the ID for the account's previous transaction.</p>
|
||
<h3 id="memos">Memos</h3>
|
||
<p>The Memos field allows for arbitrary messaging data that can accompany the transaction. It is presented as an array of objects. Each object has only one field, <code>Memo</code>, which in turn contains another object with <em>one or more</em> of the following fields:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>MemoData</td>
|
||
<td>String</td>
|
||
<td>VariableLength</td>
|
||
<td>Arbitrary hex value, conventionally containing the content of the memo.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>MemoFormat</td>
|
||
<td>String</td>
|
||
<td>VariableLength</td>
|
||
<td>Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a <a href="http://www.iana.org/assignments/media-types/media-types.xhtml">MIME type</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>MemoType</td>
|
||
<td>String</td>
|
||
<td>VariableLength</td>
|
||
<td>Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to <a href="http://tools.ietf.org/html/rfc5988#section-4">RFC 5988</a>) that defines the format of this memo.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The MemoType and MemoFormat fields should only consist of the following characters: <code>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%</code></p>
|
||
<p>The <code>Memos</code> field is currently limited to no more than 1KB in size (when serialized in binary format).</p>
|
||
<p>Example of a transaction with a Memos field:</p>
|
||
<pre><code>{
|
||
"TransactionType": "Payment",
|
||
"Account": "rMmTCjGFRWPz8S2zAUUoNVSQHxtRQD4eCx",
|
||
"Destination": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
|
||
"Memos": [
|
||
{
|
||
"Memo": {
|
||
"MemoType": "687474703a2f2f6578616d706c652e636f6d2f6d656d6f2f67656e65726963",
|
||
"MemoData": "72656e74"
|
||
}
|
||
}
|
||
],
|
||
"Amount": "1"
|
||
}
|
||
</code></pre>
|
||
<h3 id="flags">Flags</h3>
|
||
<p>The Flags field allows for additional boolean options regarding the behavior of a transaction. They are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.</p>
|
||
<p>Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the <code>TransactionType</code> field when setting and reading flags.</p>
|
||
<p>The only flag that applies globally to all transactions is as follows:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Flag Name</th>
|
||
<th>Hex Value</th>
|
||
<th>Decimal Value</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tfFullyCanonicalSig</td>
|
||
<td>0x80000000</td>
|
||
<td>2147483648</td>
|
||
<td>Require a fully-canonical signature, to protect a transaction from <a href="https://wiki.ripple.com/Transaction_Malleability">transaction malleability</a> exploits.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h2 id="payment">Payment</h2>
|
||
<p><a href="https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp" title="Source">[Source]<br/></a></p>
|
||
<p>A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, additional exchanges of value may occur atomically to facilitate the payment.)</p>
|
||
<p>Payments are also the only way to <a href="#creating-accounts">create accounts</a>.</p>
|
||
<p>Example payment:</p>
|
||
<pre><code>{
|
||
"TransactionType" : "Payment",
|
||
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||
"Amount" : {
|
||
"currency" : "USD",
|
||
"value" : "1",
|
||
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
|
||
},
|
||
"Fee": "10",
|
||
"Flags": 2147483648,
|
||
"Sequence": 2,
|
||
}
|
||
</code></pre>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>JSON Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Amount</td>
|
||
<td>String (XRP)<br/>Object (Otherwise)</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="reference-rippled.html#specifying-currency-amounts">Specifying Currency Amounts</a>.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Destination</td>
|
||
<td>String</td>
|
||
<td>Account</td>
|
||
<td>The unique address of the account receiving the payment.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>DestinationTag</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) Arbitrary tag that identifies the reason for the payment to the destination, or the hosted wallet to make a payment to.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>InvoiceID</td>
|
||
<td>String</td>
|
||
<td>Hash256</td>
|
||
<td>(Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Paths</td>
|
||
<td>Array of path arrays</td>
|
||
<td>PathSet</td>
|
||
<td>(Optional, auto-fillable) Array of <a href="https://ripple.com/wiki/Payment_paths">payment paths</a> to be used for this transaction. Must be omitted for XRP-to-XRP transactions.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>SendMax</td>
|
||
<td>String/Object</td>
|
||
<td>Amount</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>
|
||
<td>DeliverMin</td>
|
||
<td>String/Object</td>
|
||
<td>Amount</td>
|
||
<td>(Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a <a href="#partial-payments">partial payment</a>. <em>(This field is part of <a href="https://github.com/ripple/rippled/releases/tag/0.29.0">rippled 0.29.0</a>, and becomes valid August 17 at 17:00 UTC.)</em></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<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="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>
|
||
<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 <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>
|
||
<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="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>
|
||
<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>You must omit the <code>Paths</code> field for direct payments, including:</p>
|
||
<ul>
|
||
<li>An XRP-to-XRP transfer.</li>
|
||
<li>A simple transfer on a trust line that connects the sender and receiver.</li>
|
||
</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>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="concept-paths.html">Paths</a>.</p>
|
||
<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>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Flag Name</th>
|
||
<th>Hex Value</th>
|
||
<th>Decimal Value</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tfNoDirectRipple</td>
|
||
<td>0x00010000</td>
|
||
<td>65536</td>
|
||
<td>Do not use the default path; only use paths included in the <code>Paths</code> field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfPartialPayment</td>
|
||
<td>0x00020000</td>
|
||
<td>131072</td>
|
||
<td>If the specified <code>Amount</code> cannot be sent without spending more than <code>SendMax</code>, reduce the received amount instead of failing outright. See <a href="#partial-payments">Partial Payments</a> for more details.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfLimitQuality</td>
|
||
<td>0x00040000</td>
|
||
<td>262144</td>
|
||
<td>Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of <code>Amount</code>:<code>SendMax</code>. See <a href="#limit-quality">Limit Quality</a> for details.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="partial-payments">Partial Payments</h3>
|
||
<p>A partial payment allows a payment to succeed by reducing the amount received, instead of increasing the <code>SendMax</code>. Partial payments are useful for <a href="https://wiki.ripple.com/Returning_payments">returning payments</a> without incurring additional costs to oneself.</p>
|
||
<p>By default, the <code>Amount</code> field of a Payment transaction specifies the amount of currency that is <em>received</em> by the account that is the destination of the payment. Any additional amount needed for fees or currency exchange is deducted from the sending account's balances, up to the <code>SendMax</code> amount. (If <code>SendMax</code> is not specified, that is equivalent to setting the <code>SendMax</code> to the <code>Amount</code> field.) If the amount needed in order to make the payment exceeds the <code>SendMax</code> parameter, or the full amount cannot be delivered for any other reason, the transaction fails.</p>
|
||
<p>The <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> allows you to make a "partial payment" instead. When this flag is enabled for a payment, it delivers as much as possible, up to the <code>Amount</code> value, without exceeding the <code>SendMax</code> value. Fees and currency exchange rates are calculated the same way, but the amount being sent automatically scales down until the total amount deducted from the sending account's balances is within <code>SendMax</code>. The transaction is considered successful as long as it delivers equal or more than the <code>DeliverMin</code> value; if DeliverMin is omitted, then any positive amount is considered a success. This means that partial payments can succeed at sending <em>some</em> of the intended value despite limitations including fees, lack of liquidity, insufficient space in the receiving account's trustlines, or other reasons.</p>
|
||
<p>A partial payment cannot provide the initial XRP to fund an account; this case returns the error code <code>telNO_DST_PARTIAL</code>. Direct XRP-to-XRP payments also cannot be partial payments <code>temBAD_SEND_XRP_PARTIAL</code>.</p>
|
||
<p>The amount of XRP used for the <a href="#transaction-cost">transaction cost</a> is always deducted from the sender’s account, regardless of the <em>tfPartialPayment</em> flag.</p>
|
||
<h4 id="partial-payments-warning">Partial Payments Warning</h4>
|
||
<p>When the <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> is enabled, the <code>Amount</code> field <strong><em>is not guaranteed to be the amount received</em></strong>. The <a href="#delivered-amount"><code>delivered_amount</code></a> field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use <code>delivered_amount</code> instead of the <code>Amount</code> field to determine how much your account received instead.</p>
|
||
<h3 id="limit-quality">Limit Quality</h3>
|
||
<p>Ripple defines the "quality" of a currency exchange as the ratio of the numeric amount in to the numeric amount out. For example, if you spend $2 USD to receive £1 GBP, then the "quality" of that exchange is <code>0.5</code>.</p>
|
||
<p>The <a href="#payment-flags"><em>tfLimitQuality</em> flag</a> allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination <code>Amount</code> divided by the <code>SendMax</code> amount (just the numeric amounts, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality. </p>
|
||
<p>By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average <em>average</em> quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the <a href="#transaction-results">transaction result</a> is <code>tecPATH_DRY</code>.</p>
|
||
<p>Consider the following example. If I am trying to send you 100 Chinese Yuan (<code>Amount</code> = 100 CNY) for 20 United States dollars (<code>SendMax</code> = 20 USD) or less, then the limit quality is <code>5</code>. Imagine one market maker is offering ¥95 for $15 (a ratio of about <code>6.3</code> CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of <code>2.5</code> CNY per USD). If I were to take both offers in order to send you 100 CNY, then it would cost me 17 USD, for an average quality of about <code>5.9</code>. </p>
|
||
<p>Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified <code>SendMax</code>. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of <code>2.5</code>, which is worse than the limit quality of <code>5</code>.</p>
|
||
<p>The tfLimitQuality flag is most useful when combined with <a href="#partial-payments">partial payments</a>. When both <em>tfPartialPayment</em> and <em>tfLimitQuality</em> are set on a transaction, then the transaction delivers as much of the destination <code>Amount</code> as it can, without using any conversions that are worse than the limit quality.</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>
|
||
<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="reference-ledger-format.html#accountroot">account in the Ripple Consensus Ledger</a>.</p>
|
||
<p>Example AccountSet:</p>
|
||
<pre><code>{
|
||
"TransactionType": "AccountSet",
|
||
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||
"Fee": "10000",
|
||
"Sequence": 5,
|
||
"Domain": "6D64756F31332E636F6D",
|
||
"SetFlag": 5,
|
||
"MessageKey": "rQD4SqHJtDxn5DDL7xNnojNa3vxS1Jx5gv"
|
||
}
|
||
</code></pre>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>JSON Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><a href="#accountset-flags">ClearFlag</a></td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) Unique identifier of a flag to disable for this account.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#domain">Domain</a></td>
|
||
<td>String</td>
|
||
<td>VariableLength</td>
|
||
<td>(Optional) The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>EmailHash</td>
|
||
<td>String</td>
|
||
<td>Hash128</td>
|
||
<td>(Optional) Hash of an email address to be used for generating an avatar image. Conventionally, clients use <a href="http://en.gravatar.com/site/implement/hash/">Gravatar</a> to display this image.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>MessageKey</td>
|
||
<td>String</td>
|
||
<td>PubKey</td>
|
||
<td>(Optional) Public key for sending encrypted messages to this account. Conventionally, it should be a secp256k1 key, the same encryption that is used by the rest of Ripple.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#accountset-flags">SetFlag</a></td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) Integer flag to enable for this account.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#transferrate">TransferRate</a></td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) The fee to charge when users transfer this account's issuances, represented as billionths of a unit. Use <code>0</code> to set no fee.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>WalletLocator</td>
|
||
<td>String</td>
|
||
<td>Hash256</td>
|
||
<td>(Optional) Not used.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>WalletSize</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) Not used.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>If none of these options are provided, then the AccountSet transaction has no effect (beyond destroying the transaction cost). See <a href="#canceling-or-skipping-a-transaction">Canceling or Skipping a Transaction</a> for more details.</p>
|
||
<h3 id="domain">Domain</h3>
|
||
<p>The <code>Domain</code> field is represented as the hex string of the lowercase ASCII of the domain. For example, the domain <em>example.com</em> would be represented as <code>"6578616d706c652e636f6d"</code>.</p>
|
||
<p>To remove the <code>Domain</code> field from an account, send an AccountSet with the Domain set to an empty string.</p>
|
||
<p>Client applications can use the <a href="https://ripple.com/wiki/Ripple.txt">ripple.txt</a> file hosted by the domain to confirm that the account is actually operated by that domain.</p>
|
||
<h3 id="accountset-flags">AccountSet Flags</h3>
|
||
<p>There are several options which can be either enabled or disabled for an account. Account options are represented by different types of flags depending on the situation:</p>
|
||
<ul>
|
||
<li>The <code>AccountSet</code> transaction type has several "AccountSet Flags" (prefixed <em>asf</em>) that can enable an option when passed as the <code>SetFlag</code> parameter, or disable an option when passed as the <code>ClearFlag</code> parameter.</li>
|
||
<li>The <code>AccountSet</code> transaction type has several transaction flags (prefixed <em>tf</em>) that can be used to enable or disable specific account options when passed in the <code>Flags</code> parameter. This style is discouraged, and new account options will not have new corresponding transaction flags.</li>
|
||
<li>The <code>AccountRoot</code> ledger node type has several ledger-specific-flags (prefixed <em>lsf</em>) which represent the state of particular account options within a particular ledger. Naturally, the values apply until a later ledger version changes them.</li>
|
||
</ul>
|
||
<p>The preferred way to enable and disable Account Flags is using the <code>SetFlag</code> and <code>ClearFlag</code> parameters of an AccountSet transaction. AccountSet flags have names that begin with <em>asf</em>.</p>
|
||
<p>All flags are off by default.</p>
|
||
<p>The available AccountSet flags are:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Flag Name</th>
|
||
<th>Decimal Value</th>
|
||
<th>Description</th>
|
||
<th>Corresponding Ledger Flag</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>asfRequireDest</td>
|
||
<td>1</td>
|
||
<td>Require a destination tag to send transactions to this account.</td>
|
||
<td>lsfRequireDestTag</td>
|
||
</tr>
|
||
<tr>
|
||
<td>asfRequireAuth</td>
|
||
<td>2</td>
|
||
<td>Require authorization for users to hold balances issued by this account. (This prevents users unknown to a gateway from holding funds issued by that gateway.)</td>
|
||
<td>lsfRequireAuth</td>
|
||
</tr>
|
||
<tr>
|
||
<td>asfDisallowXRP</td>
|
||
<td>3</td>
|
||
<td>XRP should not be sent to this account. (Enforced by client applications, not by <code>rippled</code>)</td>
|
||
<td>lsfDisallowXRP</td>
|
||
</tr>
|
||
<tr>
|
||
<td>asfDisableMaster</td>
|
||
<td>4</td>
|
||
<td>Disallow use of the master key. Can only be enabled if the account has a <a href="#setregularkey">RegularKey</a> configured.</td>
|
||
<td>lsfDisableMaster</td>
|
||
</tr>
|
||
<tr>
|
||
<td>asfAccountTxnID</td>
|
||
<td>5</td>
|
||
<td>Track the ID of this account's most recent transaction. Required for <a href="#accounttxnid">AccountTxnID</a></td>
|
||
<td>(None)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>asfNoFreeze</td>
|
||
<td>6</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>
|
||
</tr>
|
||
<tr>
|
||
<td>asfGlobalFreeze</td>
|
||
<td>7</td>
|
||
<td><a href="concept-freeze.html">Freeze</a> all assets issued by this account.</td>
|
||
<td>lsfGlobalFreeze</td>
|
||
</tr>
|
||
<tr>
|
||
<td>asfDefaultRipple</td>
|
||
<td>8</td>
|
||
<td>Enable <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">rippling</a> on this account's trust lines by default. <em>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.27.3">rippled 0.27.3</a>)</em></td>
|
||
<td>lsfDefaultRipple</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p><em>New in <a href="https://github.com/ripple/rippled/releases/tag/0.28.0-rc1">rippled 0.28.0</a>:</em> You cannot send a transaction that enables <code>asfDisableMaster</code> or <code>asfNoFreeze</code> using a <a href="#setregularkey">regular key</a>. You must use the master key to sign the transaction.</p>
|
||
<p>The following <a href="#flags">Transaction flags</a>, specific to the AccountSet transaction type, serve the same purpose, but are discouraged:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Flag Name</th>
|
||
<th>Hex Value</th>
|
||
<th>Decimal Value</th>
|
||
<th>Replaced by AccountSet Flag</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tfRequireDestTag</td>
|
||
<td>0x00010000</td>
|
||
<td>65536</td>
|
||
<td>asfRequireDest (SetFlag)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfOptionalDestTag</td>
|
||
<td>0x00020000</td>
|
||
<td>131072</td>
|
||
<td>asfRequireDest (ClearFlag)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfRequireAuth</td>
|
||
<td>0x00040000</td>
|
||
<td>262144</td>
|
||
<td>asfRequireAuth (SetFlag)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfOptionalAuth</td>
|
||
<td>0x00080000</td>
|
||
<td>524288</td>
|
||
<td>asfRequireAuth (ClearFlag)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfDisallowXRP</td>
|
||
<td>0x00100000</td>
|
||
<td>1048576</td>
|
||
<td>asfDisallowXRP (SetFlag)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfAllowXRP</td>
|
||
<td>0x00200000</td>
|
||
<td>2097152</td>
|
||
<td>asfDisallowXRP (ClearFlag)</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h4 id="blocking-incoming-transactions">Blocking Incoming Transactions</h4>
|
||
<p>Incoming transactions with unclear purposes may be an inconvenience for some gateways, which would have to identify whether a mistake was made, and then potentially refund accounts or adjust balances depending on the mistake. The <code>asfRequireDest</code> and <code>asfDisallowXRP</code> flags are intended to protect users from accidentally sending funds to a gateway in a way that is unclear about the reason the funds were sent.</p>
|
||
<p>For example, a destination tag is typically used to identify which hosted balance should be credited when the gateway receives a payment. If the destination tag is omitted, it may be unclear which account should be credited, creating a need for refunds, among other problems. By using the <code>asfRequireDest</code> tag, the gateway (or any account) can ensure that every incoming payment has a destination tag, which makes it harder to send an ambiguous payment by accident.</p>
|
||
<p>Accounts can protect against unwanted incoming payments for non-XRP currencies simply by not creating trust lines in those currencies. Since XRP does not require trust, the <code>asfDisallowXRP</code> flag is used to discourage users from sending XRP to an account. However, this flag is not enforced in <code>rippled</code> because it could potentially cause accounts to become unusable. (If an account did not have enough XRP to send a transaction that disabled the flag, the account would be completely unusable.) Instead, client applications should disallow or discourage XRP payments to accounts with the <code>asfDisallowXRP</code> flag enabled.</p>
|
||
<h3 id="transferrate">TransferRate</h3>
|
||
<p>The TransferRate field specifies a fee to charge whenever a gateway's issuances change hands. See <a href="https://ripple.com/knowledge_center/transfer-fees/">Transfer Fees article</a> in the Knowledge Center for more information.</p>
|
||
<p>In rippled's WebSocket and JSON-RPC APIs, the TransferRate is represented as an integer, the amount that must be sent in order for 1 billion units to arrive. For example, a 20% transfer fee is represented as the value <code>1200000000</code>. The value cannot be less than 1000000000. (Less than that would indicate giving away money for sending transactions, which is exploitable.) You can specify 0 as a shortcut for 1000000000, meaning no fee.</p>
|
||
<h2 id="setregularkey">SetRegularKey</h2>
|
||
<p><a href="https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp" title="Source">[Source]<br/></a></p>
|
||
<p>A SetRegularKey transaction changes the regular key used by the account to sign future transactions.</p>
|
||
<pre><code>{
|
||
"Flags": 0,
|
||
"TransactionType": "SetRegularKey",
|
||
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||
"Fee": "12",
|
||
"RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD"
|
||
}
|
||
</code></pre>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>JSON Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>RegularKey</td>
|
||
<td>String</td>
|
||
<td>Account</td>
|
||
<td>(Optional) The public key of a new keypair, to use as the regular key to this account, as a base-58-encoded string in the same format as an account address. If omitted, removes the existing regular key.</td>
|
||
</tr>
|
||
</tbody>
|
||
</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>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="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>
|
||
<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>
|
||
<pre><code>{
|
||
"TransactionType": "OfferCreate",
|
||
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||
"Fee": "12",
|
||
"Flags": 0,
|
||
"LastLedgerSequence": 7108682,
|
||
"Sequence": 8,
|
||
"TakerGets": "6000000",
|
||
"TakerPays": {
|
||
"currency": "GKO",
|
||
"issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc",
|
||
"value": "2"
|
||
}
|
||
}
|
||
</code></pre>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>JSON Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><a href="#expiration">Expiration</a></td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</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>
|
||
<td>OfferSequence</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) An offer to delete first, specified in the same way as <a href="#offercancel">OfferCancel</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TakerGets</td>
|
||
<td>Object (Non-XRP), or <br/>String (XRP)</td>
|
||
<td>Amount</td>
|
||
<td>The amount and type of currency being provided by the offer creator.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TakerPays</td>
|
||
<td>Object (Non-XRP), or <br/>String (XRP)</td>
|
||
<td>Amount</td>
|
||
<td>The amount and type of currency being requested by the offer creator.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="lifecycle-of-an-offer">Lifecycle of an Offer</h3>
|
||
<p>When an OfferCreate transaction is processed, it automatically consumes matching or crossing offers to the extent possible. (If existing offers provide a better rate than requested, the offer creator could pay less than the full <code>TakerGets</code> amount in order to receive the entire <code>TakerPays</code> amount.) If that does not completely fulfill the <code>TakerPays</code> amount, then the offer becomes an Offer node in the ledger. (You can use <a href="#offercreate-flags">OfferCreate Flags</a> to modify this behavior.)</p>
|
||
<p>An offer in the ledger can be fulfilled either by additional OfferCreate transactions that match up with the existing offers, or by <a href="#payment">Payments</a> that use the offer to connect the payment path. Offers can be partially fulfilled and partially funded. A single transaction can consume up to 850 Offers from the ledger. (Any more than that, and the metadata becomes too large, resulting in <a href="#tec-codes"><code>tecOVERSIZE</code></a>.)</p>
|
||
<p>You can create an offer so long as you have at least some (any positive, nonzero amount) of the currency specified by the <code>TakerGets</code> parameter of the offer. Any amount of that currency you have, up to the <code>TakerGets</code> amount, will be sold until the <code>TakerPays</code> amount is satisfied. An offer cannot place anyone in debt.</p>
|
||
<p>It is possible for an offer to become temporarily or permanently <em>unfunded</em>:</p>
|
||
<ul>
|
||
<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>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>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>If the Expiration time included in the offer is before the close time of the most recently-closed ledger. (See <a href="#expiration">Expiration</a>.)</li>
|
||
</ul>
|
||
<p>An unfunded offer can remain on the ledger indefinitely, but it does not have any effect. The only ways an offer can be <em>permanently</em> removed from the ledger are:</p>
|
||
<ul>
|
||
<li>It becomes fully claimed by a Payment or a matching OfferCreate transaction.</li>
|
||
<li>A subsequent OfferCancel or OfferCreate transaction explicitly cancels the offer.</li>
|
||
<li>A subsequent OfferCreate from the same account crosses the earlier offer. (In this case, the older offer is automatically canceled.)</li>
|
||
<li>An offer is found to be unfunded during transaction processing, typically because it was at the tip of the orderbook.</li>
|
||
<li>This includes cases where one side or the other of an offer is found to be closer to 0 than <code>rippled</code>'s precision supports.</li>
|
||
<li><em>Note:</em> there is a bug that can cause offers to be removed incorrectly in rare circumstances. (See <a href="https://ripplelabs.atlassian.net/browse/RIPD-456">RIPD-456</a> for status.)</li>
|
||
</ul>
|
||
<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>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>
|
||
<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="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>
|
||
<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>When offers of the same quality are placed in the same ledger version, the order in which they are taken is determined by the <a href="https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/misc/CanonicalTXSet.cpp" title="Source: Transaction ordering">canonical order</a> in which the transactions were <a href="https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/consensus/LedgerConsensus.cpp#L1435-L1538" title="Source: Applying transactions">applied to the ledger</a>. This behavior is designed to be deterministic, efficient, and hard to game.</p>
|
||
<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>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="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>
|
||
<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>Auto-bridging happens automatically on any OfferCreate transaction. <a href="#payment">Payment transactions</a> <em>do not</em> autobridge by default, but path-finding can find paths that have the same effect.</p>
|
||
<h3 id="offercreate-flags">OfferCreate Flags</h3>
|
||
<p>Transactions of the OfferCreate type support additional values in the <a href="#flags"><code>Flags</code> field</a>, as follows:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Flag Name</th>
|
||
<th>Hex Value</th>
|
||
<th>Decimal Value</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tfPassive</td>
|
||
<td>0x00010000</td>
|
||
<td>65536</td>
|
||
<td>If enabled, the offer will not consume offers that exactly match it, and instead becomes an Offer node in the ledger. It will still consume offers that cross it.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfImmediateOrCancel</td>
|
||
<td>0x00020000</td>
|
||
<td>131072</td>
|
||
<td>Treat the offer as an <a href="http://en.wikipedia.org/wiki/Immediate_or_cancel">Immediate or Cancel order</a>. If enabled, the offer will never become a ledger node: it only attempts to match existing offers in the ledger.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfFillOrKill</td>
|
||
<td>0x00040000</td>
|
||
<td>262144</td>
|
||
<td>Treat the offer as a <a href="http://en.wikipedia.org/wiki/Fill_or_kill">Fill or Kill order</a>. Only attempt to match existing offers in the ledger, and only do so if the entire <code>TakerPays</code> quantity can be obtained.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfSell</td>
|
||
<td>0x00080000</td>
|
||
<td>524288</td>
|
||
<td>Exchange the entire <code>TakerGets</code> amount, even if it means obtaining more than the <code>TakerPays</code> amount in exchange.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The following invalid flag combination prompts a temINVALID_FLAG error:</p>
|
||
<ul>
|
||
<li>tfImmediateOrCancel and tfFillOrKill</li>
|
||
</ul>
|
||
<h2 id="offercancel">OfferCancel</h2>
|
||
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp" title="Source">[Source]<br/></a></p>
|
||
<p>An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger.</p>
|
||
<pre><code>{
|
||
"TransactionType": "OfferCancel",
|
||
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||
"Fee": "12",
|
||
"Flags": 0,
|
||
"LastLedgerSequence": 7108629,
|
||
"OfferSequence": 6,
|
||
"Sequence": 7
|
||
}
|
||
</code></pre>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>JSON Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>OfferSequence</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>The sequence number of a previous OfferCreate transaction. If specified, cancel any offer node in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist.</td>
|
||
</tr>
|
||
</tbody>
|
||
</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>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>
|
||
<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>
|
||
<pre><code>{
|
||
"TransactionType": "TrustSet",
|
||
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||
"Fee": "12",
|
||
"Flags": 262144,
|
||
"LastLedgerSequence": 8007750,
|
||
"LimitAmount": {
|
||
"currency": "USD",
|
||
"issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
|
||
"value": "100"
|
||
},
|
||
"Sequence": 12
|
||
}
|
||
</code></pre>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>JSON Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><a href="#trust-limits">LimitAmount</a></td>
|
||
<td>Object</td>
|
||
<td>Amount</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>
|
||
<td>LimitAmount.currency</td>
|
||
<td>String</td>
|
||
<td>(Amount.currency)</td>
|
||
<td>The currency to this trust line applies to, as a three-letter <a href="http://www.xe.com/iso4217.php">ISO 4217 Currency Code</a> or a 160-bit hex value according to <a href="https://wiki.ripple.com/Currency_format">currency format</a>. "XRP" is invalid.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>LimitAmount.value</td>
|
||
<td>String</td>
|
||
<td>(Amount.value)</td>
|
||
<td>Quoted decimal representation of the limit to set on this trust line.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>LimitAmount.issuer</td>
|
||
<td>String</td>
|
||
<td>(Amount.issuer)</td>
|
||
<td>The address of the account to extend trust to.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>QualityIn</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of <code>0</code> is shorthand for treating balances at face value.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>QualityOut</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>(Optional) Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of <code>0</code> is shorthand for treating balances at face value.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="trust-limits">Trust Limits</h3>
|
||
<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>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="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>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>
|
||
<h3 id="trustset-flags">TrustSet Flags</h3>
|
||
<p>Transactions of the TrustSet type support additional values in the <a href="#flags"><code>Flags</code> field</a>, as follows:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Flag Name</th>
|
||
<th>Hex Value</th>
|
||
<th>Decimal Value</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tfSetfAuth</td>
|
||
<td>0x00010000</td>
|
||
<td>65536</td>
|
||
<td>Authorize the other party to hold issuances from this account. (No effect unless using the <a href="#accountset-flags"><em>asfRequireAuth</em> AccountSet flag</a>.) Cannot be unset.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfSetNoRipple</td>
|
||
<td>0x00020000</td>
|
||
<td>131072</td>
|
||
<td>Blocks rippling between two trustlines of the same currency, if this flag is set on both. (See <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">No Ripple</a> for details.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfClearNoRipple</td>
|
||
<td>0x00040000</td>
|
||
<td>262144</td>
|
||
<td>Clears the No-Rippling flag. (See <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">No Ripple</a> for details.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfSetFreeze</td>
|
||
<td>0x00100000</td>
|
||
<td>1048576</td>
|
||
<td><a href="concept-freeze.html">Freeze</a> the trustline.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tfClearFreeze</td>
|
||
<td>0x00200000</td>
|
||
<td>2097152</td>
|
||
<td><a href="concept-freeze.html">Unfreeze</a> the trustline.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h1 id="pseudo-transactions">Pseudo-Transactions</h1>
|
||
<p>Pseudo-Transactions are never submitted by users, nor propagated through the network. Instead, a server may choose to inject them in a proposed ledger directly. If enough servers inject an equivalent pseudo-transaction for it to pass consensus, then it becomes included in the ledger, and appears in ledger data thereafter.</p>
|
||
<p>Some of the fields that are mandatory for normal transactions do not make sense for pseudo-transactions. In those cases, the pseudo-transaction has the following default values:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>Default Value</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Account</td>
|
||
<td><a href="https://wiki.ripple.com/Accounts#ACCOUNT_ZERO">ACCOUNT_ZERO</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Sequence</td>
|
||
<td>0</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Fee</td>
|
||
<td>0</td>
|
||
</tr>
|
||
<tr>
|
||
<td>SigningPubKey</td>
|
||
<td>""</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Signature</td>
|
||
<td>""</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h2 id="setfee">SetFee</h2>
|
||
<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>
|
||
<pre><code>{
|
||
"Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
|
||
"BaseFee": "000000000000000A",
|
||
"Fee": "0",
|
||
"ReferenceFeeUnits": 10,
|
||
"ReserveBase": 20000000,
|
||
"ReserveIncrement": 5000000,
|
||
"Sequence": 0,
|
||
"SigningPubKey": "",
|
||
"TransactionType": "SetFee",
|
||
"date": 439578860,
|
||
"hash": "1C15FEA3E1D50F96B6598607FC773FF1F6E0125F30160144BE0C5CBC52F5151B",
|
||
"ledger_index": 3721729,
|
||
}
|
||
</code></pre>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>JSON Type</th>
|
||
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>BaseFee</td>
|
||
<td>String</td>
|
||
<td>UInt64</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>
|
||
<td>ReferenceFeeUnits</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>The cost, in fee units, of the reference transaction</td>
|
||
</tr>
|
||
<tr>
|
||
<td>ReserveBase</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>The base reserve, in drops</td>
|
||
</tr>
|
||
<tr>
|
||
<td>ReserveIncrement</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>UInt32</td>
|
||
<td>The incremental reserve, in drops</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h1 id="transaction-results">Transaction Results</h1>
|
||
<h2 id="immediate-response">Immediate Response</h2>
|
||
<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>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>Value</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>engine_result</td>
|
||
<td>String</td>
|
||
<td>A code that categorizes the result, such as <code>tecPATH_DRY</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>engine_result_code</td>
|
||
<td>Signed Integer</td>
|
||
<td>A number that corresponds to the <code>engine_result</code>, although exact values are subject to change.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>engine_result_message</td>
|
||
<td>String</td>
|
||
<td>A human-readable message explaining what happened. This message is intended for developers to diagnose problems, and is subject to change without notice.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>If nothing went wrong in the process of submitting and applying the transaction locally, the response looks like this:</p>
|
||
<pre><code class="js"> "engine_result": "tesSUCCESS",
|
||
"engine_result_code": 0,
|
||
"engine_result_message": "The transaction was applied. Only final in a validated ledger."
|
||
</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>
|
||
<h2 id="looking-up-transaction-results">Looking up Transaction Results</h2>
|
||
<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>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>Value</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>meta.TransactionResult</td>
|
||
<td>String</td>
|
||
<td>A code that categorizes the result, such as <code>tecPATH_DRY</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>validated</td>
|
||
<td>Boolean</td>
|
||
<td>Whether or not this result comes from a validated ledger. If <code>false</code>, then the result is provisional. If <code>true</code>, then the result is final.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<pre><code class="js"> "hash": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7",
|
||
"meta": {
|
||
...
|
||
"TransactionResult": "tesSUCCESS"
|
||
},
|
||
"validated": true
|
||
</code></pre>
|
||
<h2 id="result-categories">Result Categories</h2>
|
||
<p>Both the <code>engine_result</code> and the <code>meta.TransactionResult</code> use standard codes to identify the results of transactions, as follows:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Category</th>
|
||
<th>Prefix</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Local error</td>
|
||
<td><a href="#tel-codes">tel</a></td>
|
||
<td>The rippled server had an error due to local conditions, such as high load. You may get a different response if you resubmit to a different server or at a different time.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Malformed transaction</td>
|
||
<td><a href="#tem-codes">tem</a></td>
|
||
<td>The transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Failure</td>
|
||
<td><a href="#tef-codes">tef</a></td>
|
||
<td>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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Retry</td>
|
||
<td><a href="#ter-codes">ter</a></td>
|
||
<td>The transaction could not be applied, but it might be possible to apply later.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Success</td>
|
||
<td><a href="#tes-success">tes</a></td>
|
||
<td>(Not an error) The transaction succeeded. This result is not final unless it appears in a validated ledger.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Claimed cost only</td>
|
||
<td><a href="#tec-codes">tec</a></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>
|
||
<td>Client library error</td>
|
||
<td><a href="#tej-codes">tej</a></td>
|
||
<td>(ripple-lib only) The transaction was not submitted, because the client library blocked it, as part of its additional error checking.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<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>
|
||
<h2 id="claimed-cost-justification">Claimed Cost Justification</h2>
|
||
<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>
|
||
<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>The transaction cost is generally very small in real-world value, so it should not harm users unless they are sending large quantities of transactions.</li>
|
||
</ul>
|
||
<h2 id="finality-of-results">Finality of Results</h2>
|
||
<p>The order in which transactions apply to the consensus ledger is not final until a ledger is closed and the exact transaction set is approved by the consensus process. Therefore, a transaction that succeeded initially could still fail, and a transaction that failed initially could still succeed. Additionally, a transaction that was rejected by the consensus process in one round could achieve consensus in a subsequent round.</p>
|
||
<p>A validated ledger can include successful transactions (<code>tes</code> result codes) as well as failed transactions (<code>tec</code> result codes). No transaction with any other result is included in a ledger.</p>
|
||
<p>For any other result code, it can be difficult to determine if the result is final. The following table summarizes when a transaction's outcome is final, based on the result code from submitting the transaction:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Error Code</th>
|
||
<th>Finality</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>tesSUCCESS</code></td>
|
||
<td>Final when included in a validated ledger</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Any <code>tec</code> code</td>
|
||
<td>Final when included in a validated ledger</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Any <code>tem</code> code</td>
|
||
<td>Final unless the protocol changes to make the transaction valid</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>tefPAST_SEQ</code></td>
|
||
<td>Final when another transaction with the same sequence number is included in a validated ledger</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>tefMAX_LEDGER</code></td>
|
||
<td>Final when a validated ledger has a sequence number higher than the transaction's <code>LastLedgerSequence</code> field, and no validated ledger includes the transaction</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Any other transaction result is potentially not final. In that case, the transaction could still succeed or fail later, especially if conditions change such that the transaction is no longer prevented from applying. For example, attempting to send a non-XRP currency to an account that does not exist yet would fail, but it could succeed if another transaction sends enough XRP to create the destination account. A server might even store a temporarily-failed, signed transaction and then successfully apply it later without asking first.</p>
|
||
<h2 id="understanding-transaction-metadata">Understanding Transaction Metadata</h2>
|
||
<p>The metadata section of a transaction includes detailed information about all the changes to the shared Ripple Consensus Ledger that the transaction caused. This is true of any transaction that gets included in a ledger, whether or not it is successful. Naturally, the changes are only final if the transaction is validated.</p>
|
||
<p>Some fields that may appear in transaction metadata include:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>Value</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>AffectedNodes</td>
|
||
<td>Array</td>
|
||
<td>List of nodes that were created, deleted, or modified by this transaction, and specific changes to each.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>DeliveredAmount</td>
|
||
<td>String or Object</td>
|
||
<td><strong>DEPRECATED.</strong> Replaced by <code>delivered_amount</code>. Omitted if not a partial payment.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TransactionIndex</td>
|
||
<td>Unsigned Integer</td>
|
||
<td>The transaction's position within the ledger that included it. (For example, the value <code>2</code> means it was the 2nd transaction in that ledger.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TransactionResult</td>
|
||
<td>String</td>
|
||
<td>A <a href="#result-categories">result code</a> indicating whether the transaction succeeded or how it failed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="#delivered-amount">delivered_amount</a></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="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>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="delivered-amount">delivered_amount</h3>
|
||
<p>The <code>Amount</code> of a <a href="#payment">Payment transaction</a> indicates the amount to deliver to the <code>Destination</code>, so if the transaction was successful, then the destination received that much -- <strong>except if the transaction was a <a href="#partial-payments">partial payment</a></strong>. (In that case, any positive amount up to <code>Amount</code> might have arrived.) Rather than choosing whether or not to trust the <code>Amount</code> field, you should use the <code>delivered_amount</code> field of the metadata to see how much actually reached its destination.</p>
|
||
<p>The <code>delivered_amount</code> field of transaction metadata is included in all successful Payment transactions, and is formatted like a normal currency amount. However, the delivered amount is not available for transactions that meet both of the following criteria:</p>
|
||
<ul>
|
||
<li>Is a partial payment, and</li>
|
||
<li>Included in a validated ledger prior to 2014-01-20</li>
|
||
</ul>
|
||
<p>If both conditions are true, then <code>delivered_amount</code> contains the string value <code>unavailable</code> instead of an actual amount. If this happens, you can only figure out the actual delivered amount by reading the AffectedNodes in the transaction's metadata.</p>
|
||
<h2 id="full-transaction-response-list">Full Transaction Response List</h2>
|
||
<p><a href="https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/TER.h" title="Source">[Source]<br/></a></p>
|
||
<h3 id="tel-codes">tel Codes</h3>
|
||
<p>These codes indicate an error in the local server processing the transaction; it is possible that another server with a different configuration or load level could process the transaction successfully. They have numerical values in the range -399 to -300. The exact code for any given error is subject to change, so don't rely on it.</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Code</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>telLOCAL_ERROR</td>
|
||
<td>Unspecified local error.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>telBAD_DOMAIN</td>
|
||
<td>The transaction specified a domain value (for example, the <code>Domain</code> field of an <a href="#accountset">AccountSet transaction</a>) that cannot be used, probably because it is too long to store in the ledger.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>telBAD_PATH_COUNT</td>
|
||
<td>The transaction contains too many paths for the local server to process.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>telBAD_PUBLIC_KEY</td>
|
||
<td>The transaction specified a public key value (for example, as the <code>MessageKey</code> field of an <a href="#accountset">AccountSet transaction</a>) that cannot be used, probably because it is too long.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>telFAILED_PROCESSING</td>
|
||
<td>An unspecified error occurred when processing the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<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="concept-transaction-cost.html">transaction cost</a> requirement, which is derived from its load level.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>telNO_DST_PARTIAL</td>
|
||
<td>The transaction is an XRP payment that would fund a new account, but the <a href="#partial-payments">tfPartialPayment flag</a> was enabled. This is disallowed.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="tem-codes">tem Codes</h3>
|
||
<p>These codes indicate that the transaction was malformed, and cannot succeed according to the Ripple protocol. They have numerical values in the range -299 to -200. The exact code for any given error is subject to change, so don't rely on it.</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Code</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>temMALFORMED</td>
|
||
<td>Unspecified problem with the format of the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_AMOUNT</td>
|
||
<td>An amount specified by the transaction (for example the destination <code>Amount</code> or <code>SendMax</code> values of a <a href="#payment">Payment</a>) was invalid, possibly because it was a negative number.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_AUTH_MASTER</td>
|
||
<td>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 <a href="#setregularkey">Regular Key</a> set.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_CURRENCY</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>
|
||
<td>temBAD_EXPIRATION</td>
|
||
<td>The transaction improperly specified an expiration value, for example as part of an <a href="#offercreate">OfferCreate transaction</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_FEE</td>
|
||
<td>The transaction improperly specified its <code>Fee</code> value, for example by listing a non-XRP currency or some negative amount of XRP.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_ISSUER</td>
|
||
<td>The transaction improperly specified the <code>issuer</code> field of some currency included in the request.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_LIMIT</td>
|
||
<td>The <a href="#trustset">TrustSet</a> transaction improperly specified the <code>LimitAmount</code> value of a trustline.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_OFFER</td>
|
||
<td>The <a href="#offercreate">OfferCreate</a> transaction specifies an invalid offer, such as offering to trade XRP for itself, or offering a negative amount.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_PATH</td>
|
||
<td>The <a href="#payment">Payment</a> transaction specifies one or more <a href="#paths">Paths</a> improperly, for example including an issuer for XRP, or specifying an account differently.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_PATH_LOOP</td>
|
||
<td>One of the <a href="#paths">Paths</a> in the <a href="#payment">Payment</a> transaction was flagged as a loop, so it cannot be processed in a bounded amount of time.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_SEND_XRP_LIMIT</td>
|
||
<td>The <a href="#payment">Payment</a> transaction used the <a href="#limit-quality">tfLimitQuality</a> flag in a direct XRP-to-XRP payment, even though XRP-to-XRP payments do not involve any conversions.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_SEND_XRP_MAX</td>
|
||
<td>The <a href="#payment">Payment</a> transaction included a <code>SendMax</code> field in a direct XRP-to-XRP payment, even though sending XRP should never require SendMax. (XRP is only valid in SendMax if the destination <code>Amount</code> is not XRP.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_SEND_XRP_NO_DIRECT</td>
|
||
<td>The <a href="#payment">Payment</a> transaction used the <a href="#payment-flags">tfNoDirectRipple</a> flag for a direct XRP-to-XRP payment, even though XRP-to-XRP payments are always direct.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_SEND_XRP_PARTIAL</td>
|
||
<td>The <a href="#payment">Payment</a> transaction used the <a href="#partial-payments">tfPartialPayment</a> flag for a direct XRP-to-XRP payment, even though XRP-to-XRP payments should always deliver the full amount.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_SEND_XRP_PATHS</td>
|
||
<td>The <a href="#payment">Payment</a> transaction included <code>Paths</code> while sending XRP, even though XRP-to-XRP payments should always be direct.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_SEQUENCE</td>
|
||
<td>The transaction is references a sequence number that is higher than its own <code>Sequence</code> number, for example trying to cancel an offer that would have to be placed after the transaction that cancels it.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_SIGNATURE</td>
|
||
<td>The signature to authorize this transaction is either missing, or formed in a way that is not a properly-formed signature. (See <a href="#tec-codes">tecNO_PERMISSION</a> for the case where the signature is properly formed, but not authorized for this account.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_SRC_ACCOUNT</td>
|
||
<td>The <code>Account</code> on whose behalf this transaction is being sent (the "source account") is not a properly-formed Ripple account.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temBAD_TRANSFER_RATE</td>
|
||
<td>The <a href="#transferrate"><code>TransferRate</code> field of an AccountSet transaction</a> is not properly formatted.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temDST_IS_SRC</td>
|
||
<td>The <a href="#trustset">TrustSet</a> transaction improperly specified the destination of the trustline (the <code>issuer</code> field of <code>LimitAmount</code>) as the <code>Account</code> sending the transaction. You cannot extend a trustline to yourself. (In the future, this code could also apply to other cases where the destination of a transaction is not allowed to be the account sending it.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temDST_NEEDED</td>
|
||
<td>The transaction improperly omitted a destination. This could be the <code>Destination</code> field of a <a href="#payment">Payment</a> transaction, or the <code>issuer</code> sub-field of the <code>LimitAmount</code> field fo a <code>TrustSet</code> transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temINVALID</td>
|
||
<td>The transaction is otherwise invalid. For example, the transaction ID may not be the right format, the signature may not be formed properly, or something else went wrong in understanding the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temINVALID_FLAG</td>
|
||
<td>The transaction includes a <a href="#flags">Flag</a> that does not exist, or includes a contradictory combination of flags.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temREDUNDANT</td>
|
||
<td>The transaction would accomplish nothing; for example, it is sending a payment directly to the sending account, or creating an offer to buy and sell the same currency from the same issuer.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>temREDUNDANT_SEND_MAX</td>
|
||
<td><em>(Removed in <a href="https://github.com/ripple/rippled/releases/tag/0.28.0-rc1">rippled 0.28.0</a>)</em></td>
|
||
</tr>
|
||
<tr>
|
||
<td>temRIPPLE_EMPTY</td>
|
||
<td>The <a href="#payment">Payment</a> transaction includes an empty <code>Paths</code> field, but paths are necessary to complete this payment.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="tef-codes">tef Codes</h3>
|
||
<p>These codes indicate that the transaction failed to apply, but the transaction could have succeeded in some theoretical ledger. Typically this means that the transaction can no longer succeed in any future ledger. They have numerical values in the range -199 to -100. The exact code for any given error is subject to change, so don't rely on it.</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Code</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tefFAILURE</td>
|
||
<td>Unspecified failure in applying the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefALREADY</td>
|
||
<td>The same exact transaction has already been applied.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefBAD_ADD_AUTH</td>
|
||
<td>Deprecated. This code should never be returned.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefBAD_AUTH</td>
|
||
<td>The key used to sign this account is not authorized to modify this account. (It could be authorized if the account had the same key set as the <a href="#setregularkey">Regular Key</a>.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefBAD_LEDGER</td>
|
||
<td>While processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please <a href="https://ripplelabs.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10800&issuetype=1">file a bug</a> to get it fixed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefCREATED</td>
|
||
<td>Deprecated. This code should never be returned.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefEXCEPTION</td>
|
||
<td>While processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please <a href="https://ripplelabs.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10800&issuetype=1">file a bug</a> to get it fixed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefINTERNAL</td>
|
||
<td>While attempting to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please <a href="https://ripplelabs.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10800&issuetype=1">file a bug</a> to get it fixed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefNO_AUTH_REQUIRED</td>
|
||
<td>The <a href="#trustset">TrustSet</a> transaction attempted to mark a trustline as authorized, but the <code>lsfRequireAuth</code> flag is not enabled for the corresponding account, so authorization is not necessary.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefPAST_SEQ</td>
|
||
<td>The sequence number of the transaction is lower than the current sequence number of the account sending the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefWRONG_PRIOR</td>
|
||
<td>The transaction contained an <code>AccountTxnID</code> field (or the deprecated <code>PreviousTxnID</code> field), but the transaction specified there does not match the account's previous transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefMASTER_DISABLED</td>
|
||
<td>The transaction was signed with the account's master key, but the account has the <code>lsfDisableMaster</code> field set.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tefMAX_LEDGER</td>
|
||
<td>The transaction included a <a href="#lastledgersequence"><code>LastLedgerSequence</code></a> parameter, but the current ledger's sequence number is already higher than the specified value.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="ter-codes">ter Codes</h3>
|
||
<p>These codes indicate that the transaction failed to apply, but it could apply successfully if some other transaction was applied first. They have numerical values in the range -99 to -1. The exact code for any given error is subject to change, so don't rely on it.</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Code</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>terRETRY</td>
|
||
<td>Unspecified retriable error.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terFUNDS_SPENT</td>
|
||
<td>Deprecated. This code should never be returned.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terINSUF_FEE_B</td>
|
||
<td>The account sending the transaction does not have enough XRP to pay the <code>Fee</code> specified in the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terNO_ACCOUNT</td>
|
||
<td>The account sending the transaction does not exist in the ledger (yet).</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terNO_AUTH</td>
|
||
<td>The transaction would involve adding currency issued by an account with <code>lsfRequireAuth</code> enabled to a trustline that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terNO_LINE</td>
|
||
<td>Used internally only. This code should never be returned.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terOWNERS</td>
|
||
<td>The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the <a href="#accountset-flags"><code>lsfRequireAuth</code></a> flag if it has any trust lines or available offers.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terPRE_SEQ</td>
|
||
<td>The <code>Sequence</code> number of the current transaction is higher than the current sequence number of the account sending the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terLAST</td>
|
||
<td>Used internally only. This code should never be returned.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>terNO_RIPPLE</td>
|
||
<td>Used internally only. This code should never be returned.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="tes-success">tes Success</h3>
|
||
<p>The code <code>tesSUCCESS</code> is the only code that indicates a transaction succeeded. This does not necessarily mean it accomplished its goal (for example, an <a href="#offercancel">OfferCancel</a> can "succeed" if there is no offer for it to cancel). Success uses the numerical value 0.</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Code</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tesSUCCESS</td>
|
||
<td>The transaction was applied and forwarded to other servers. If this appears in a validated ledger, then the transaction's success is final.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<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="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>
|
||
<thead>
|
||
<tr>
|
||
<th>Code</th>
|
||
<th>Value</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tecCLAIM</td>
|
||
<td>100</td>
|
||
<td>Unspecified failure, with transaction cost destroyed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecPATH_PARTIAL</td>
|
||
<td>101</td>
|
||
<td>The transaction failed because the provided paths did not have enough liquidity to send the full amount.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecUNFUNDED_ADD</td>
|
||
<td>102</td>
|
||
<td><strong>DEPRECATED.</strong></td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecUNFUNDED_OFFER</td>
|
||
<td>103</td>
|
||
<td>The <a href="#offercreate">OfferCreate transaction</a> failed because the account creating the offer does not have any of the <code>TakerGets</code> currency.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecUNFUNDED_PAYMENT</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="concept-reserves.html">Reserves</a>)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecFAILED_PROCESSING</td>
|
||
<td>105</td>
|
||
<td>An unspecified error occurred when processing the transaction.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecDIR_FULL</td>
|
||
<td>121</td>
|
||
<td>The "owners count" of the account sending the transaction is already maxed out.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecINSUF_RESERVE_LINE</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="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>
|
||
<td>tecINSUF_RESERVE_OFFER</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="concept-reserves.html">Reserves</a>)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_DST</td>
|
||
<td>124</td>
|
||
<td>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.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_DST_INSUF_XRP</td>
|
||
<td>125</td>
|
||
<td>The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_LINE_INSUF_RESERVE</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="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>
|
||
<td>tecNO_LINE_REDUNDANT</td>
|
||
<td>127</td>
|
||
<td>The transaction failed because it attempted to set a trust line to its default state, but the trust line did not exist.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecPATH_DRY</td>
|
||
<td>128</td>
|
||
<td>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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecUNFUNDED</td>
|
||
<td>129</td>
|
||
<td><strong>DEPRECATED.</strong> Replaced by tecUNFUNDED_OFFER and tecUNFUNDED_PAYMENT.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecMASTER_DISABLED</td>
|
||
<td>130</td>
|
||
<td>The <a href="#setregularkey">SetRegularKey transaction</a> tried to unset the Regular Key, but the account has the <code>lsfDisableMaster</code> flag enabled. (Unsetting the Regular Key while also leaving the Master Key disabled would make the account unusable.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_REGULAR_KEY</td>
|
||
<td>131</td>
|
||
<td>The <a href="#accountset">AccountSet transaction</a> tried to disable the Master Key, but the account does not have a Regular Key set. (Disabling the Master Key without having a Regular Key configured would make the account unusable.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecOWNERS</td>
|
||
<td>132</td>
|
||
<td>The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the <a href="#accountset-flags"><code>lsfRequireAuth</code></a> flag if it has any trust lines or available offers.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_ISSUER</td>
|
||
<td>133</td>
|
||
<td>The account specified in the <code>issuer</code> field of a currency amount does not exist.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_AUTH</td>
|
||
<td>134</td>
|
||
<td>The transaction failed because it needs to add a balance on a trust line to an account with the <code>lsfRequireAuth</code> flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, tecNO_LINE occurs instead.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_LINE</td>
|
||
<td>135</td>
|
||
<td>The <code>TakerPays</code> field of the <a href="#offercreate">OfferCreate transaction</a> specifies an asset whose issuer has <code>lsfRequireAuth</code> 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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecINSUFF_FEE</td>
|
||
<td>136</td>
|
||
<td>The account sending the transaction does not possess enough XRP to pay the specified <code>Fee</code>. This error only occurs if the transaction has already been propagated through the network to achieve consensus,</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecFROZEN</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="concept-freeze.html">global freeze</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_TARGET</td>
|
||
<td>138</td>
|
||
<td><strong>FORTHCOMING</strong> Part of multi-signature transactions.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_PERMISSION</td>
|
||
<td>139</td>
|
||
<td><strong>FORTHCOMING</strong> Part of multi-signature transactions.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNO_ENTRY</td>
|
||
<td>140</td>
|
||
<td><strong>FORTHCOMING</strong> Part of multi-signature transactions.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecINSUFFICIENT_RESERVE</td>
|
||
<td>141</td>
|
||
<td><strong>FORTHCOMING</strong> Part of multi-signature transactions. (Code may change; see <a href="https://ripplelabs.atlassian.net/browse/RIPD-743">RIPD-743</a> for status.)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecNEED_MASTER_KEY</td>
|
||
<td>142</td>
|
||
<td>This transaction attempted to cause changes that require the master key, such as <a href="#accountset-flags">disabling the master key or giving up the ability to freeze balances</a>. <em>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.28.0-rc1">rippled 0.28.0</a>)</em></td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecDST_TAG_NEEDED</td>
|
||
<td>143</td>
|
||
<td>The <a href="#payment">Payment</a> transaction omitted a destination tag, but the destination account has the <code>lsfRequireDestTag</code> flag enabled. <em>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.28.0-rc1">rippled 0.28.0</a>)</em></td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecINTERNAL</td>
|
||
<td>144</td>
|
||
<td>Unspecified internal error, with transaction cost applied. This error code should not normally be returned.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tecOVERSIZE</td>
|
||
<td>145</td>
|
||
<td>This transaction could not be processed, because attempted transaction processing created an excessively large amount of metadata. <em>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.29.0-hf1">rippled 0.29.0-hf1</a> )</em></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="tej-codes">tej Codes</h3>
|
||
<p>These codes are only ever returned by the <code>ripple-lib</code> client library, not by <code>rippled</code> itself. </p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Code</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tejAbort</td>
|
||
<td>The transaction was manually canceled by calling <code>transaction.abort()</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tejAttemptsExceeded</td>
|
||
<td>The transaction was submitted multiple times, up to a total equal to the max attempts setting, without being successfully included in a ledger.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tejInvalidFlag</td>
|
||
<td>One of the flags specified was invalid, or does not apply to this transaction type.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tejLocalSigningRequired</td>
|
||
<td>The transaction could not be resubmitted because local signing is disabled.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tejMaxFeeExceeded</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>
|
||
<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="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>
|
||
<td>tejSecretInvalid</td>
|
||
<td>The secret included for signing this transaction was not a properly-formatted secret.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tejSecretUnknown</td>
|
||
<td>The secret for a given account was omitted from the transaction, and ripple-lib was unable to automatically fill it in from saved data.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tejServerUntrusted</td>
|
||
<td>The application attempted to submit an account secret to an untrusted server for transaction signing.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>tejUnconnected</td>
|
||
<td>The application is not connected to a <code>rippled</code> server, but it needs to be in order to process the transaction.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</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 class="menu" id="menu-resources">
|
||
<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 class="menu" id="menu-compliance-regulatory-relations"><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 class="menu" id="menu-dev-footer-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 href="https://forum.ripple.com/" target="_blank">Ripple Forum</a></li>
|
||
</ul>
|
||
</section>
|
||
<section class="col-sm-3 widget nav_menu-2 widget_nav_menu">
|
||
<h4>About<hr/></h4>
|
||
<ul class="menu" id="menu-company-footer">
|
||
<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>
|