Docs: SusPay warnings, offline mode, and other tweaks

docs/src/boilerplate.md.ejs

@@ -6,7 +6,7 @@ Use the following [boilerplate code](https://en.wikipedia.org/wiki/Boilerplate_c
 const {RippleAPI} = require('ripple-lib');
 
 const api = new RippleAPI({
-  servers: ['wss://s1.ripple.com'] //Public rippled server hosted by Ripple, Inc.
+  server: 'wss://s1.ripple.com' // Public rippled server hosted by Ripple, Inc.
 });
 api.connect().then(() => {
   /* insert code here */
@@ -17,7 +17,7 @@ api.connect().then(() => {
 
 RippleAPI is designed to work in [NodeJS](https://nodejs.org) (version `0.12.0` or greater) using [Babel](https://babeljs.io/) for [ECMAScript 6](https://babeljs.io/docs/learn-es2015/) support.
 
-The code samples in this documentation are written in ES6, but `RippleAPI` will work with ES5 also. Regardless of whether you use ES5 or ES6, the methods that return promises will return [ES6-style promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise_).
+The code samples in this documentation are written in ES6, but `RippleAPI` will work with ES5 also. Regardless of whether you use ES5 or ES6, the methods that return promises will return [ES6-style promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 
 <aside class="notice">
 All the code snippets in this documentation assume that you have surrounded them with this boilerplate.
@@ -29,8 +29,12 @@ If you omit the "catch" section, errors may not be visible.
 
 ### Parameters
 
+The RippleAPI constructor optionally takes one argument, an object with the following options:
+
 <%- renderSchema('input/api-options.json') %>
 
+If you omit the `server` parameter, RippleAPI operates [offline](#offline-functionality).
+
 
 ### Installation ###
 

docs/src/connect.md.ejs

@@ -2,7 +2,7 @@
 
 `connect(): Promise<void>`
 
-Tells the RippleAPI instance to connect to its server(s).
+Tells the RippleAPI instance to connect to its rippled server.
 
 ### Parameters
 

docs/src/disconnect.md.ejs

@@ -2,7 +2,7 @@
 
 `disconnect(): Promise<void>`
 
-Tells the RippleAPI instance to disconnect from its server(s).
+Tells the RippleAPI instance to disconnect from its rippled server.
 
 ### Parameters
 

docs/src/getFee.md.ejs

@@ -2,7 +2,7 @@
 
 `getFee(): Promise<number>`
 
-Returns the estimated transaction fee for the server(s) the RippleAPI instance is connected to.
+Returns the estimated transaction fee for the rippled server the RippleAPI instance is connected to.
 
 ### Parameters
 

docs/src/index.md.ejs

@@ -1,5 +1,6 @@
 <% include introduction.md.ejs %>
 <% include boilerplate.md.ejs %>
+<% include offline.md.ejs %>
 <% include basictypes.md.ejs %>
 <% include transactions.md.ejs %>
 <% include specifications.md.ejs %>

docs/src/isConnected.md.ejs

@@ -2,7 +2,7 @@
 
 `isConnected(): boolean`
 
-Checks if the RippleAPI instance is connected to its server(s).
+Checks if the RippleAPI instance is connected to its rippled server.
 
 ### Parameters
 

docs/src/offline.md.ejs

@@ -0,0 +1,27 @@
+## Offline functionality
+
+RippleAPI can also function without internet connectivity. This can be useful in order to generate secrets and sign transactions from a secure, isolated machine.
+
+To instantiate RippleAPI in offline mode, use the following boilerplate code:
+
+```javascript
+const {RippleAPI} = require('ripple-lib');
+
+const api = new RippleAPI();
+/* insert code here */
+```
+
+Methods that depend on the state of the Ripple Consensus Ledger are unavailable in offline mode. To prepare transactions offline, you **must** specify  the `fee`, `sequence`, and `maxLedgerVersion` parameters in the [transaction instructions](#transaction-instructions). The following methods should work offline:
+
+* [preparePayment](#preparepayment)
+* [prepareTrustline](#preparetrustline)
+* [prepareOrder](#prepareorder)
+* [prepareOrderCancellation](#prepareordercancellation)
+* [prepareSettings](#preparesettings)
+* [prepareSuspendedPaymentCreation](#preparesuspendedpaymentcreation)
+* [prepareSuspendedPaymentCancellation](#preparesuspendedpaymentcancellation)
+* [prepareSuspendedPaymentExecution](#preparesuspendedpaymentexecution)
+* [sign](#sign)
+* [generateAddress](#generateaddress)
+* [computeLedgerHash](#computeledgerhash)
+

docs/src/prepareSuspendedPaymentCancellation.md.ejs

@@ -4,6 +4,8 @@
 
 Prepare a suspended payment cancellation transaction. The prepared transaction must subsequently be [signed](#sign) and [submitted](#submit).
 
+**Caution:** Suspended Payments are currently available on the [Ripple Test Net](https://ripple.com/build/ripple-test-net/) only.
+
 ### Parameters
 
 <%- renderSchema('input/prepare-suspended-payment-cancellation.json') %>

docs/src/prepareSuspendedPaymentCreation.md.ejs

@@ -4,6 +4,8 @@
 
 Prepare a suspended payment creation transaction. The prepared transaction must subsequently be [signed](#sign) and [submitted](#submit).
 
+**Caution:** Suspended Payments are currently available on the [Ripple Test Net](https://ripple.com/build/ripple-test-net/) only.
+
 ### Parameters
 
 <%- renderSchema('input/prepare-suspended-payment-creation.json') %>

docs/src/prepareSuspendedPaymentExecution.md.ejs

@@ -4,6 +4,8 @@
 
 Prepare a suspended payment execution transaction. The prepared transaction must subsequently be [signed](#sign) and [submitted](#submit).
 
+**Caution:** Suspended Payments are currently available on the [Ripple Test Net](https://ripple.com/build/ripple-test-net/) only.
+
 ### Parameters
 
 <%- renderSchema('input/prepare-suspended-payment-execution.json') %>

docs/src/transactions.md.ejs

@@ -15,6 +15,8 @@ Type | Description
 [suspendedPaymentCancellation](#suspended-payment-cancellation) | A `suspendedPaymentCancellation` transaction unlocks the funds in a suspended payment and sends them back to the creator of the suspended payment, but it will only work after the suspended payment expires.
 [suspendedPaymentExecution](#suspended-payment-execution) | A `suspendedPaymentExecution` transaction unlocks the funds in a suspended payment and sends them to the destination of the suspended payment, but it will only work if the cryptographic condition is provided.
 
+The three "suspended payment" transaction types are not supported by the production Ripple peer-to-peer network at this time. They are available for testing purposes if you [configure RippleAPI](#boilerplate) to connect to the [Ripple Test Net](https://ripple.com/build/ripple-test-net/) instead.
+
 ## Transaction Flow
 
 Executing a transaction with `RippleAPI` requires the following four steps:
@@ -44,7 +46,7 @@ Transaction instructions indicate how to execute a transaction, complementary wi
 
 <%- renderSchema("objects/instructions.json") %>
 
-We recommended that you specify a `maxLedgerVersion` because without it there is no way to know that a failed transaction will never succeeed in the future. It is impossible for a transaction to succeed after the network ledger version exceeds the transaction's `maxLedgerVersion`.
+We recommended that you specify a `maxLedgerVersion` so that you can quickly determine that a failed transaction will never succeeed in the future. It is impossible for a transaction to succeed after the network ledger version exceeds the transaction's `maxLedgerVersion`. If you omit `maxLedgerVersion`, the "prepare*" method automatically supplies a `maxLedgerVersion` equal to the current ledger plus 3, which it includes in the return value from the "prepare*" method.
 
 ## Transaction ID