From 7f75543cc680509d411c35a3044aa30eee0434c8 Mon Sep 17 00:00:00 2001 From: Rome Reginelli Date: Wed, 8 Jun 2016 19:18:27 -0700 Subject: [PATCH] rippled / tx format - clarify scientific notation and case sensitivity of field names (DOC-406, GitHub#155) (#194) --- content/reference-rippled.md | 12 ++++++++---- content/reference-transaction-format.md | 8 ++++---- reference-rippled.html | 12 +++++++----- reference-transaction-format.html | 8 ++++---- 4 files changed, 23 insertions(+), 17 deletions(-) diff --git a/content/reference-rippled.md b/content/reference-rippled.md index e05045fe0c..d4820842f0 100755 --- a/content/reference-rippled.md +++ b/content/reference-rippled.md @@ -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: -*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][]. @@ -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` | | 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 ### 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 | |-------|------|-------------| -| currency | String - [Currency Code][] | Arbitrary code for currency to issue. Cannot be `XRP`. | -| value | String | Quoted decimal representation of the amount of currency | -| issuer | String | Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed. | +| `currency` | String - [Currency Code][] | Arbitrary code for currency to issue. Cannot be `XRP`. | +| `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. | + +**Caution:** These field names are case-sensitive. For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59`, you would specify: diff --git a/content/reference-transaction-format.md b/content/reference-transaction-format.md index 3e6f65bdef..71029136f3 100644 --- a/content/reference-transaction-format.md +++ b/content/reference-transaction-format.md @@ -230,7 +230,7 @@ The transaction hash can be used as a "proof of payment" since anyone can [look ## 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 | |-------|-----------|---------------|-------------| @@ -388,13 +388,13 @@ Example payment: | Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description | |-------|-----------|--------------------------------------------------------|-------------| -| Amount | String (XRP)
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)
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. | | 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. | | 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. | -| 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.)_ | +| 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). For non-XRP amounts, the nested field names are lower-case. | ### Special issuer Values for SendMax and Amount ### diff --git a/reference-rippled.html b/reference-rippled.html index d20140696e..778b01b595 100644 --- a/reference-rippled.html +++ b/reference-rippled.html @@ -613,7 +613,7 @@ Null method

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.

Basic Data Types

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.

Each closed Ledger has a Ledger Index and a Hash value. When Specifying a Ledger Instance you can use either one.

Addresses

@@ -741,6 +741,7 @@ Null method +

Caution: Ripple uses decimal math with different precision than typical floating-point numbers, so currency amounts are always presented as strings.

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.

XRP

@@ -761,22 +762,23 @@ Null method -currency +currency String - Currency Code Arbitrary code for currency to issue. Cannot be XRP. -value +value String -Quoted decimal representation of the amount of currency +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 +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:

{
     "currency": "USD",
diff --git a/reference-transaction-format.html b/reference-transaction-format.html
index 206b927a11..b4a3c821f1 100644
--- a/reference-transaction-format.html
+++ b/reference-transaction-format.html
@@ -409,7 +409,7 @@
 
The "hash" is the unique value that identifies a particular transaction. The server provides the hash in the response when you submit the transaction; you can also look up a transaction in an account's transaction history with the account_tx command.

 
The transaction hash can be used as a "proof of payment" since anyone can look up the transaction by its hash to verify its final status.

 
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:

 
@@ -659,7 +659,7 @@
 
-
+
@@ -689,13 +689,13 @@
 
-
+
-
+

 
 
Amount
 String (XRP)
Object (Otherwise)		
 AmountThe amount of currency to deliver. Note: If the tfPartialPayment flag is set, this is not the amount actually received. (Formatted as per Specifying Currency Amounts.)The amount of currency to deliver. Formatted as per Specifying Currency Amounts. For non-XRP amounts, the nested field names are lower-case. If the tfPartialPayment flag is set, deliver up to this amount instead.
 

 

 DestinationSendMax
 String/Object
 Amount(Optional) Highest amount of source currency this transaction is allowed to cost, including transfer fees, exchange rates, and slippage. Does not include the XRP destroyed as a cost for submitting the transaction. (Also see Specifying Currency Amounts) Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments.(Optional) Highest amount of source currency this transaction is allowed to cost, including transfer fees, exchange rates, and slippage. Does not include the XRP destroyed as a cost for submitting the transaction. See also: 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. (This field is part of rippled 0.29.0, and becomes valid August 17 at 17:00 UTC.)(Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a partial payment. For non-XRP amounts, the nested field names are lower-case.