ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 11:45:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

rippled / tx format - clarify scientific notation and case sensitivity of field names (DOC-406, GitHub#155) (#194)

Browse Source
This commit is contained in:
Rome Reginelli
2016-06-08 19:18:27 -07:00
parent 029b009d54
commit 7f75543cc6
4 changed files with 23 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
content/reference-rippled.md
View File

@@ -348,7 +348,7 @@ All field names are case-sensitive. In responses, fields that are taken directly
Different types of objects are uniquely identified in different ways: Different types of objects are uniquely identified in different ways:
*Accounts* are identified by their [Address][], for example `"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"`. Addresses always start with "r". Many `rippled` methods also accept an un-encoded hex representation. *Accounts* are identified by their base-58 [Address][], for example `"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"`. Addresses always start with "r". Many `rippled` methods also accept a hexadecimal representation.
*Transactions* are identified by a [Hash][] of the transaction's binary format. You can also identify a transaction by its sending account and [Sequence Number][]. *Transactions* are identified by a [Hash][] of the transaction's binary format. You can also identify a transaction by its sending account and [Sequence Number][].
@@ -409,6 +409,8 @@ There are two kinds of currencies in the Ripple Consensus Ledger: XRP, and every
| Maximum value `100000000000` (`1e11`) | Maximum value `9999999999999999e80` | | Maximum value `100000000000` (`1e11`) | Maximum value `9999999999999999e80` |
| Precise to the nearest ["drop"](#xrp) (0.000001 XRP) | 15 decimal digits of precision, with a minimum nonzero absolute value of `1000000000000000e-96` | | Precise to the nearest ["drop"](#xrp) (0.000001 XRP) | 15 decimal digits of precision, with a minimum nonzero absolute value of `1000000000000000e-96` |
**Caution:** Ripple uses decimal math with different precision than typical floating-point numbers, so currency amounts are always presented as strings.
### Specifying Currency Amounts ### ### Specifying Currency Amounts ###
Some API methods require you to specify an amount of currency. Depending on whether you are dealing in the network's native XRP currency or other currency units (called _issuances_), the style for specifying it is very different. Some API methods require you to specify an amount of currency. Depending on whether you are dealing in the network's native XRP currency or other currency units (called _issuances_), the style for specifying it is very different.
@@ -432,9 +434,11 @@ If you are specifying non-XRP currency (including fiat dollars, precious metals,
| Field | Type | Description | | Field | Type | Description |
|-------|------|-------------| |-------|------|-------------|
| currency | String - [Currency Code][] | Arbitrary code for currency to issue. Cannot be `XRP`. | | `currency` | String - [Currency Code][] | Arbitrary code for currency to issue. Cannot be `XRP`. |
| value | String | Quoted decimal representation of the amount of currency | | `value` | String | Quoted decimal representation of the amount of currency. This can include scientific notation, such as `1.23e11` meaning 123,000,000,000. Both `e` and `E` may be used. |
| issuer | String | Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed. | | `issuer` | String | Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed. |
**Caution:** These field names are case-sensitive.
For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59`, you would specify: For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59`, you would specify:

8
content/reference-transaction-format.md
View File

@@ -230,7 +230,7 @@ The transaction hash can be used as a "proof of payment" since anyone can [look
## Common Fields ## ## Common Fields ##
Every transaction type has the same set of fundamental fields: Every transaction type has the same set of fundamental fields. Field names are case-sensitive. The common fields for all transactions are:
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description | | Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|-------|-----------|---------------|-------------| |-------|-----------|---------------|-------------|
@@ -388,13 +388,13 @@ Example payment:
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description | | Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|-------|-----------|--------------------------------------------------------|-------------| |-------|-----------|--------------------------------------------------------|-------------|
| Amount | String (XRP)<br/>Object (Otherwise) | Amount | The amount of currency to deliver. *Note:* If the [*tfPartialPayment* flag](#payment-flags) is set, this is not the amount actually received. (Formatted as per [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts).) | | Amount | String (XRP)<br/>Object (Otherwise) | Amount | The amount of currency to deliver. Formatted as per [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts). For non-XRP amounts, the nested field names are lower-case. If the [*tfPartialPayment* flag](#payment-flags) is set, deliver _up to_ this amount instead. |
| Destination | String | Account | The unique address of the account receiving the payment. | | Destination | String | Account | The unique address of the account receiving the payment. |
| DestinationTag | Unsigned Integer | UInt32 | (Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. | | DestinationTag | Unsigned Integer | UInt32 | (Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. |
| InvoiceID | String | Hash256 | (Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment. | | InvoiceID | String | Hash256 | (Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment. |
| Paths | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](https://ripple.com/wiki/Payment_paths) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. | | Paths | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](https://ripple.com/wiki/Payment_paths) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. |
| SendMax | String/Object | Amount | (Optional) Highest amount of source currency this transaction is allowed to cost, including [transfer fees](concept-transfer-fees.html), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](#transaction-cost). (Also see [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts)) Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. | | SendMax | String/Object | Amount | (Optional) Highest amount of source currency this transaction is allowed to cost, including [transfer fees](concept-transfer-fees.html), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](#transaction-cost). See also: [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts). For non-XRP amounts, the nested field names are lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. |
| DeliverMin | String/Object | Amount | (Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](#partial-payments). _(This field is part of [rippled 0.29.0](https://github.com/ripple/rippled/releases/tag/0.29.0), and becomes valid August 17 at 17:00 UTC.)_ | | DeliverMin | String/Object | Amount | (Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](#partial-payments). For non-XRP amounts, the nested field names are lower-case. |
### Special issuer Values for SendMax and Amount ### ### Special issuer Values for SendMax and Amount ###

12
reference-rippled.html
View File

@@ -613,7 +613,7 @@ Null method
<p>All field names are case-sensitive. In responses, fields that are taken directly from Ledger Node or Transaction objects start with upper-case letters. Other fields, including ones that are dynamically generated for a response, are lower case.</p> <p>All field names are case-sensitive. In responses, fields that are taken directly from Ledger Node or Transaction objects start with upper-case letters. Other fields, including ones that are dynamically generated for a response, are lower case.</p>
<h2 id="basic-data-types">Basic Data Types</h2> <h2 id="basic-data-types">Basic Data Types</h2>
<p>Different types of objects are uniquely identified in different ways:</p> <p>Different types of objects are uniquely identified in different ways:</p>
<p><em>Accounts</em> are identified by their <a href="#addresses">Address</a>, for example <code>"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"</code>. Addresses always start with "r". Many <code>rippled</code> methods also accept an un-encoded hex representation.</p> <p><em>Accounts</em> are identified by their base-58 <a href="#addresses">Address</a>, for example <code>"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"</code>. Addresses always start with "r". Many <code>rippled</code> methods also accept a hexadecimal representation.</p>
<p><em>Transactions</em> are identified by a <a href="#hashes">Hash</a> of the transaction's binary format. You can also identify a transaction by its sending account and <a href="#account-sequence">Sequence Number</a>.</p> <p><em>Transactions</em> are identified by a <a href="#hashes">Hash</a> of the transaction's binary format. You can also identify a transaction by its sending account and <a href="#account-sequence">Sequence Number</a>.</p>
<p>Each closed <em>Ledger</em> has a <a href="#ledger-index">Ledger Index</a> and a <a href="#hashes">Hash</a> value. When <a href="#specifying-ledgers">Specifying a Ledger Instance</a> you can use either one.</p> <p>Each closed <em>Ledger</em> has a <a href="#ledger-index">Ledger Index</a> and a <a href="#hashes">Hash</a> value. When <a href="#specifying-ledgers">Specifying a Ledger Instance</a> you can use either one.</p>
<h3 id="addresses">Addresses</h3> <h3 id="addresses">Addresses</h3>
@@ -741,6 +741,7 @@ Null method
</tr> </tr>
</tbody> </tbody>
</table> </table>
<p><strong>Caution:</strong> Ripple uses decimal math with different precision than typical floating-point numbers, so currency amounts are always presented as strings.</p>
<h3 id="specifying-currency-amounts">Specifying Currency Amounts</h3> <h3 id="specifying-currency-amounts">Specifying Currency Amounts</h3>
<p>Some API methods require you to specify an amount of currency. Depending on whether you are dealing in the network's native XRP currency or other currency units (called <em>issuances</em>), the style for specifying it is very different.</p> <p>Some API methods require you to specify an amount of currency. Depending on whether you are dealing in the network's native XRP currency or other currency units (called <em>issuances</em>), the style for specifying it is very different.</p>
<h4 id="xrp">XRP</h4> <h4 id="xrp">XRP</h4>
@@ -761,22 +762,23 @@ Null method
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td>currency</td> <td><code>currency</code></td>
<td>String - <a href="#currency-codes">Currency Code</a></td> <td>String - <a href="#currency-codes">Currency Code</a></td>
<td>Arbitrary code for currency to issue. Cannot be <code>XRP</code>.</td> <td>Arbitrary code for currency to issue. Cannot be <code>XRP</code>.</td>
</tr> </tr>
<tr> <tr>
<td>value</td> <td><code>value</code></td>
<td>String</td> <td>String</td>
<td>Quoted decimal representation of the amount of currency</td> <td>Quoted decimal representation of the amount of currency. This can include scientific notation, such as <code>1.23e11</code> meaning 123,000,000,000. Both <code>e</code> and <code>E</code> may be used.</td>
</tr> </tr>
<tr> <tr>
<td>issuer</td> <td><code>issuer</code></td>
<td>String</td> <td>String</td>
<td>Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed.</td> <td>Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<p><strong>Caution:</strong> These field names are case-sensitive.</p>
<p>For example, to represent $153.75 US dollars issued by account <code>r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59</code>, you would specify:</p> <p>For example, to represent $153.75 US dollars issued by account <code>r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59</code>, you would specify:</p>
<pre><code>{ <pre><code>{
"currency": "USD", "currency": "USD",

8
reference-transaction-format.html
View File

@@ -409,7 +409,7 @@
<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 <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> to verify its final status.</p> <p>The transaction hash can be used as a "proof of payment" since anyone can <a href="#looking-up-transaction-results">look up the transaction by its hash</a> to verify its final status.</p>
<h2 id="common-fields">Common Fields</h2> <h2 id="common-fields">Common Fields</h2>
<p>Every transaction type has the same set of fundamental fields:</p> <p>Every transaction type has the same set of fundamental fields. Field names are case-sensitive. The common fields for all transactions are:</p>
<table> <table>
<thead> <thead>
<tr> <tr>
@@ -659,7 +659,7 @@
<td>Amount</td> <td>Amount</td>
<td>String (XRP)<br/>Object (Otherwise)</td> <td>String (XRP)<br/>Object (Otherwise)</td>
<td>Amount</td> <td>Amount</td>
<td>The amount of currency to deliver. <em>Note:</em> If the <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> is set, this is not the amount actually received. (Formatted as per <a href="reference-rippled.html#specifying-currency-amounts">Specifying Currency Amounts</a>.)</td> <td>The amount of currency to deliver. Formatted as per <a href="reference-rippled.html#specifying-currency-amounts">Specifying Currency Amounts</a>. For non-XRP amounts, the nested field names are lower-case. If the <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> is set, deliver <em>up to</em> this amount instead.</td>
</tr> </tr>
<tr> <tr>
<td>Destination</td> <td>Destination</td>
@@ -689,13 +689,13 @@
<td>SendMax</td> <td>SendMax</td>
<td>String/Object</td> <td>String/Object</td>
<td>Amount</td> <td>Amount</td>
<td>(Optional) Highest amount of source currency this transaction is allowed to cost, including <a href="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> <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>. See also: <a href="reference-rippled.html#specifying-currency-amounts">Specifying Currency Amounts</a>. For non-XRP amounts, the nested field names are lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments.</td>
</tr> </tr>
<tr> <tr>
<td>DeliverMin</td> <td>DeliverMin</td>
<td>String/Object</td> <td>String/Object</td>
<td>Amount</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> <td>(Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a <a href="#partial-payments">partial payment</a>. For non-XRP amounts, the nested field names are lower-case.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>