Merge pull request #79 from ripple/gh-pages

Dev Portal from Staging to Master for 10/8 second push

css/main.css

@@ -152,7 +152,7 @@
   -moz-box-sizing: border-box;
 }
 body {
-  color: #898788;
+  color: #393738;
   font-family: 'Open Sans', sans-serif;
 }
 body .content-root {

css/mod.css

@@ -1,14 +1,15 @@
 .draft-comment {background: #faa; border: 1px solid #d88; padding: 2px;}
 
 td {border: 1px solid #DBDDE2 !important; padding: .2em;}
-table { border-collapse: collapse; clear: left; width: 550px}
-th { padding: .2em; }
+table { border-collapse: collapse; clear: left; }
+th { padding: .2em; font-weight: bold; }
 
 body .content-root {
     background-color: #F3F6FB;
     box-shadow: 930px 0 #FFFFFF inset, 931px 0 #DFE2E7 inset, 940px 0 5px -10px rgba(0, 0, 0, 0.1) inset;
 }
 code { max-height: 14em; overflow: auto;}
+.content code { color: #111; }
 .expanded { max-height: none; overflow: none;}
 
 .content h2, .menu a.level-2 {

css/style.css

@@ -125,7 +125,6 @@ a {
   text-decoration: none;
 }
 a:hover {
-  color: #228a8a;
 }
 /* ----------------------------------------------------------------------------
  * Content styling
@@ -666,12 +665,8 @@ a.big.button {
 }
 a.big.button,
 a.big.button:visited {
-  color: #2badad;
   text-decoration: none;
 }
-a.big.button:hover {
-  background: #2badad;
-}
 a.big.button:hover,
 a.big.button:hover:visited {
   color: #fff;
@@ -742,9 +737,6 @@ a.big.button:hover:visited {
 .menu a:visited {
   color: #2badad;
 }
-.menu a:hover {
-  color: #228a8a;
-}
 .menu a.level-1 {
   font-family: montserrat, sans-serif;
   text-transform: uppercase;

js/apitool-rest.js

@@ -69,16 +69,17 @@ Request('Generate Account', {
     method: GET,
     path: "/v1/accounts/new",
     description: 'Generate the keys for a potential new account',
-    link: '#generating-accounts'
+    link: '#generate-account'
 });
 
 Request('Get Account Balances', {
     method: GET,
-    path: '/v1/accounts/{:address}/balances',
+    path: '/v1/accounts/{:address}/balances?{:query_params}',
     description: 'Retrieve the current balances for the given Ripple account',
-    link: '#account-balances',
+    link: '#get-account-balances',
     params: {
-        "{:address}": DEFAULT_ADDRESS_1
+        "{:address}": DEFAULT_ADDRESS_1,
+        "{:query_params}": "currency=USD"
     }
 });
 
@@ -86,7 +87,7 @@ Request('Get Account Settings', {
     method: GET,
     path: '/v1/accounts/{:address}/settings',
     description: 'Retrieve the current settings for the given Ripple account',
-    link: '#account-settings',
+    link: '#get-account-settings',
     params: {
         "{:address}": DEFAULT_ADDRESS_1
     }
@@ -96,7 +97,7 @@ Request('Update Account Settings', {
     method: POST,
     path: '/v1/accounts/{:address}/settings',
     description: 'Change the current settings for the given Ripple account.',
-    link: '#updating-account-settings',
+    link: '#update-account-settings',
     test_only: true,
     params: {
         "{:address}": DEFAULT_ADDRESS_1
@@ -130,7 +131,7 @@ Request('Submit Payment', {
     method: POST,
     path: '/v1/payments',
     description: 'Send a prepared payment to the network.',
-    link: '#submitting-a-payment',
+    link: '#submit-payment',
     test_only: true,
     body: {
       "secret": "sssssssssssssssssssssssssssss",
@@ -163,7 +164,7 @@ Request("Confirm Payment", {
     method: GET,
     path: "/v1/accounts/{:address}/payments/{:hash}",
     description: "Retrieve details of a payment and its status",
-    link: "#confirming-a-payment",
+    link: "#confirm-payment",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
         "{:hash}": DEFAULT_HASH
@@ -174,7 +175,7 @@ Request("Get Payment History", {
     method: GET,
     path: "/v1/accounts/{:address}/payments?{:query_params}",
     description: "Browse through the history of payments sent and received by an account",
-    link: "#payment-history",
+    link: "#get-payment-history",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
         "{:query_params}": "direction=incoming&exclude_failed=true"

ripple-rest.html

@@ -61,11 +61,12 @@ mixpanel.init("132d42885e094171f34467fc54da6fab");
 
   
   <!-- syntax selection js -->
-  <script src='js/multicodetab.js'></script>
+  <script src="js/multicodetab.js"></script>
   <script>
     Flatdoc.run({
       fetcher: Flatdoc.file('ripplerest_api.md')
     });
+    $(document).on('flatdoc:ready', $().multicode_tabs);
   </script>
   <link type='text/css' rel='stylesheet' href='css/mod.css' />
   <script src="js/fixsidebarscroll.js"></script>
@@ -107,18 +108,6 @@ mixpanel.init("132d42885e094171f34467fc54da6fab");
         </div><!--/.nav-collapse -->
       </div>
     </div>
-<!-- 
-  <div class="header-subnav-wrapper">
-  <div class='header-subnav navbar-fixed-top'>
-    <ul>
-        <li><a href='?p=introduction' id='subnav-intro'>Introduction</a></li>
-        <li><a href='?p=ripple-rest-api' id='subnav-rest'>Ripple-REST API</a></li>
-        <li><a href='?p=web-sockets-api' id='subnav-websocket'>WebSocket &amp; JSON-RPC APIs</a></li>
-    </ul>
-    <div class='clearer'>&nbsp;</div>
-  </div>
-</div>
- -->
   <div class='content-root'>
     <div class='menubar'>
       <div class='menu section' role='flatdoc-menu'></div>

tx_format.md

@@ -163,7 +163,7 @@ Every transaction type has the same set of fundamental fields:
 | Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
 |-------|-----------|---------------|-------------|
 | Account | String | Account | The unique address of the account that initiated the transaction. |
-| [AccountTxnID](#accounttxnid) | String | Hash256 | (Optional) Hash value identifying another transaction. This transaction is only valid if the sending account's previous transaction matches the provided hash. |
+| [AccountTxnID](#accounttxnid) | String | Hash256 | (Optional) Hash value identifying another transaction. This transaction is only valid if the sending account's previously-sent transaction matches the provided hash. |
 | [Fee](#transaction-fees) | String | Amount | (Required, but [auto-fillable](#auto-fillable-fields)) Integer amount of XRP, in drops, to be destroyed as a fee for redistributing this transaction to the network. |
 | [Flags](#flags) | Unsigned Integer | UInt32 | (Optional) Set of bit-flags for this transaction. |
 | [LastLedgerSequence](#lastledgersequence) | Number | UInt32 | (Optional, but strongly recommended) Highest ledger sequence number that a transaction can appear in. |
@@ -174,13 +174,13 @@ Every transaction type has the same set of fundamental fields:
 | TransactionType | String | UInt16 | The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, and `SetRegularKey`. |
 | TxnSignature | String | VariableLength | (Automatically added when signing) The signature that verifies this transaction as originating from the account it says it is from. |
 
-The field `PreviousTxnID` is a **DEPRECATED** alias for [AccountTxnID](#accounttxnid). Always use `AccountTxnID` instead.
+The field `PreviousTxnID` is **DEPRECATED**. It has been replaced by [AccountTxnID](#accounttxnid). Always use `AccountTxnID` instead.
 
 ### Auto-fillable Fields ###
 
 Some fields can be automatically filled in before the transaction is signed, either by a `rippled` server or by the library used for offline signing. Both [ripple-lib](https://github.com/ripple/ripple-lib) and `rippled` can automatically provide the following values:
 
-* `Fee` - Automatically use the current base network fee.
+* `Fee` - Automatically use the current base network fee. (*Note:* `rippled`'s [sign command](rippled-apis.html#sign) supports limits on how high the filled-in-value is, using the `fee_mult_max` parameter.)
 * `Sequence` - Automatically use the next sequence number for the account sending the transaction.
 
 For a production system, we recommend *not* leaving these fields to be filled by the server. For example if fees become temporarily high, you may want to wait for fees to decrease before sending some transactions, instead of continuing regardless of fee.
@@ -332,21 +332,26 @@ Transactions of the Payment type support additional values in the [`Flags` field
 | Flag Name | Hex Value | Decimal Value | Description |
 |-----------|-----------|---------------|-------------|
 | tfNoDirectRipple | 0x00010000 | 65536 | Do not use a direct path, if available. This is intended to force the transaction to take arbitrage opportunities. Most clients will not need this. |
-| tfPartialPayment | 0x00020000 | 131072 | Instead of deducting transfer and exchange fees from the sending account's balance, reduce the received amount by the fee amounts. See [Partial Payments](#partial-payments) for more details. |
+| tfPartialPayment | 0x00020000 | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](#partial-payments) for more details. |
 
 ### Partial Payments ###
 
-A partial payment subtracts fees from the amount received instead of adding to the amount sent. Partial payments are useful for [returning payments](https://wiki.ripple.com/Returning_payments) without incurring additional costs to oneself.
+A partial payment allows a payment to succeed by reducing the amount received, instead of increasing the `SendMax`. Partial payments are useful for [returning payments](https://wiki.ripple.com/Returning_payments) without incurring additional costs to oneself.
 
-By default, the `Amount` field of a Payment transaction specifies the amount of currency that is *received* 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, up to the `SendMax` amount. (If `SendMax` is not specified, and fees are necessary to make the transaction the transaction fails.)
+By default, the `Amount` field of a Payment transaction specifies the amount of currency that is *received* 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 `SendMax` amount. (If `SendMax` is not specified, that is equivalent to setting the `SendMax` to the `Amount` field.) If the amount needed in order to make the payment exceeds the `SendMax` parameter, or the full amount cannot be delivered for any other reason, the transaction fails.
 
-The [*tfPartialPayment* flag](#payment-flags) allows you to make a "partial payment" instead. When this flag is enabled for a transaction, the costs of transaction fees and exchanging currencies are deducted from the amount sent instead of from the sender's balance. Consequently, the `Amount` field __*is not guaranteed to be the amount received*__. In fact, __*there is no minimum guaranteed amount*__ that a partial payment actually delivers.
+The [*tfPartialPayment* flag](#payment-flags) 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 `Amount` value, without exceeding the `SendMax` 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 `SendMax`. The transaction is always considered successful as long as it delivers any positive amount. This means that partial payments can succeed at sending *some* of the intended value despite limitations including fees, lack of liquidity, insufficient space in the receiving account's trustlines, or other reasons.
 
-Validated partial payment transactions have a `meta.DeliveredAmount` field, which indicates the amount of currency actually received by the destination account. *Note:* Early partial payments in historical ledgers do not have this field.
+A partial payment cannot provide the initial XRP to fund an account; this case returns the error code `telNO_DST_PARTIAL`. Direct XRP-to-XRP payments also cannot be partial payments `temBAD_SEND_XRP_PARTIAL`.
 
-A partial payment cannot provide the initial XRP to fund an account; this case returns the error code telNO_DST_PARTIAL. Direct XRP-to-XRP payments also cannot be partial payments temBAD_SEND_XRP_PARTIAL.
+The amount of XRP used for the [transaction fee](#transaction-fees) is always deducted from the sender’s account, regardless of the *tfPartialPayment* flag.
+
+#### Partial Payments Warning ####
+
+When the [*tfPartialPayment* flag](#payment-flags) is enabled, the `Amount` field __*is not guaranteed to be the amount received*__. In fact, __*there is no minimum guaranteed amount*__ that a partial payment actually delivers. Validated partial payment transactions have a `meta.DeliveredAmount` field, which indicates the amount of currency actually received by the destination account. When receiving a payment, you should confirm that, if the `meta.DeliveredAmount` field exists, you use that to determine how much your account received instead of relying on the `Amount` field. 
+
+*Note:* Early partial payments in historical ledgers do not have this field. If necessary, you can check the balance changes in the `meta` field to determine how much the destination account actually received.
 
-*Note:* The amount of XRP used for the [transaction fee](#transaction-fee) is always deducted from the sender's account, regardless of the *tfPartialPayment* flag.
 
 
 

websocket_api.md

@@ -5294,7 +5294,7 @@ The following fields are deprecated, and may be omitted: `paths_canonical`, and
 ## sign ##
 [[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/module/rpc/handlers/Sign.cpp "Source")
 
-The `sign` method takes a transaction, specified as JSON, and a secret key, and returns a signed binary representation of the transaction that can be submitted. The result is always different, even when you provide the same transaction and secret key.
+The `sign` method takes a transaction, specified as JSON, and a secret key, and returns a signed binary representation of the transaction that can be submitted. The result is always different, even when you provide the same transaction JSON and secret key.
 
 *Note:* It is possible and preferable to sign a transaction without connecting to a server instead of using this command. For example, [ripple-lib's rsign.js](https://github.com/ripple/ripple-lib/blob/develop/bin/rsign.js) demonstrates offline signing of a transaction. You should prefer to do offline signing of a transaction, especially when you do not control the server you are sending a transaction to. An untrustworthy server can abuse its position to change the transaction before signing it, or worse, use your secret to sign additional arbitrary transactions as if they came from you.
 
@@ -5352,6 +5352,8 @@ rippled -- sign sssssssssssssssssssssssssssss '{"TransactionType": "Payment", "A
 ```
 </div>
 
+[Try it! >](ripple-api-tool.html#sign)
+
 The request includes the following parameters:
 
 | Field | Type | Description |
@@ -5360,11 +5362,13 @@ The request includes the following parameters:
 | secret | String | Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections. |
 | offline | Boolean | (Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values. |
 | build_path | Boolean | (Optional) If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. *Caution:* The server looks for the presence or absence of this field, not its value. This behavior may change. (See [RIPD-173](https://ripplelabs.atlassian.net/browse/RIPD-173) for status.) |
+| fee\_mult\_max | Integer | (Optional) If the transaction `Fee` is omitted, this field limits the `Fee` value that is automatically filled so that it is less than or equal to the long-term base fee times this value. |
 
 The server automatically attempts to fill in certain fields from the `tx_json` object if they are omitted, unless you specified `offline` as true. Otherwise, the following fields from the [transaction format](transactions.html) are automatically filled in:
 
 * `Sequence` - The server automatically uses the next Sequence number from the sender's account information. Be careful: the next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must provide the correct sequence numbers in the request. Automatically filled unless `offline` is true.
 * `Fee` - The server can automatically fill in an appropriate transaction fee (in drops of XRP) unless you specified `offline` as true. Otherwise, you must fill in the appropriate fee. Be careful: a malicious server can specify an excessively high fee. Automatically filled unless `offline` is true.
+    * If `fee_mult_max` is included, and the automatically generated Fee is greater than the long-term base fee times `fee_mult_max`, then the transaction fails with the error `rpcHIGH_FEE`. This way, you can let the server fill in the current minimum `Fee` value as long as the current load fee is not too high.
 * `Paths` - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a [ripple_path_find](#ripple-path-find). Only filled if `build_path` is provided. 
 
 #### Response Format ####
@@ -5493,6 +5497,8 @@ submit 1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534
 ```
 </div>
 
+[Try it! >](ripple-api-tool.html#submit)
+
 
 ### Sign-and-Submit Mode ###
 
@@ -5505,6 +5511,9 @@ A sign-and-submit request includes the following parameters:
 | fail_hard | Boolean | (Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers |
 | offline | Boolean | (Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values. |
 | build_path | Boolean | (Optional) If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. You must omit this field if the transaction is a direct XRP-to-XRP transfer. *Caution:* The server looks for the presence or absence of this field, not its value. This behavior may change. (See [RIPD-173](https://ripplelabs.atlassian.net/browse/RIPD-173) for status.) |
+| fee\_mult\_max | Integer | (Optional) If the transaction `Fee` is omitted, this field limits the `Fee` value that is automatically filled so that it is less than or equal to the long-term base fee times this value. |
+
+See the [sign command](#sign) for detailed information on how the server automatically fills in certain fields.
 
 #### Request Format ####
 An example of the request format: