From 92464495907c2c163cc0db0cdcc10c555b82c9aa Mon Sep 17 00:00:00 2001 From: Evan Schwartz Date: Fri, 6 Sep 2013 17:05:21 -0700 Subject: [PATCH] editing docs --- README.md | 11 ++++++++--- docs/GUIDES.md | 22 ++++++++++++++++++---- docs/REFERENCE.md | 8 ++++++-- 3 files changed, 32 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6ee7b3d3..725e1c4e 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,13 @@ `ripple-lib` connects to the Ripple network via the WebSocket protocol and runs in Node.js as well as in the browser. -This file contains installation and quickstart instructions. For the full documentation see: +This file contains installation and quickstart instructions. + +For additional documentation see: 1. [The `ripple-lib` Guides](docs/REFERENCE.md) 2. [The `ripple-lib` API Reference](docs/REFERENCE.md) -3. Additional documentation resources can be found at: +3. The Ripple Wiki: + https://ripple.com/wiki/Ripple_JavaScript_library + https://ripple.com/wiki + https://ripple.com @@ -19,7 +21,7 @@ This file contains installation and quickstart instructions. For the full docume ##Quickstart -`Remote` ([remote.js](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/remote.js)) is the module responsible for managing connections to `rippled` servers. +`Remote` ([remote.js](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/remote.js)) is the module responsible for managing connections to `rippled` servers: ```js /* Loading ripple-lib with Node.js */ @@ -33,6 +35,7 @@ var remote = new Remote({ trusted: true, local_signing: true, local_fee: true, + fee_cusion: 1.5, servers: [ { host: 's1.ripple.com' @@ -48,3 +51,5 @@ remote.connect(function() { // see the API Reference for available functions }); ``` + +See [The `ripple-lib` Guides](docs/REFERENCE.md) and [The `ripple-lib` API Reference](docs/REFERENCE.md) for walkthroughs and details about all of the available functions and options. diff --git a/docs/GUIDES.md b/docs/GUIDES.md index 1b8f9b4c..b6e14788 100644 --- a/docs/GUIDES.md +++ b/docs/GUIDES.md @@ -2,7 +2,7 @@ ###In this document: -1. [Connecting to the Ripple network with the `Remote` module](GUIDES.md#1-connecting-to-the-ripple-network-with-the-remote-module) +1. [Connecting to the Ripple network with `Remote`](GUIDES.md#1-connecting-to-the-ripple-network-with-remote) 2. [Using `Remote` functions and `Request` objects](GUIDES.md#2-using-remote-functions-and-request-objects) 3. [Submitting a transaction](GUIDES.md#3-submitting-a-transaction) 4. [Listening to the network](GUIDES.md#4-listening-to-the-network) @@ -13,9 +13,9 @@ 1. [The `ripple-lib` README](../README.md) 2. [The `ripple-lib` API Reference](REFERENCE.md) -##1. Connecting to the Ripple network with the `Remote` module - +##1. Connecting to the Ripple network with `Remote` +Coming Soon ##2. Using `Remote` functions and `Request` objects @@ -78,4 +78,18 @@ remote.connect(function() { }); ``` -##4. Listening to the network \ No newline at end of file +###A note on transaction fees + +A full description of network transaction fees can be found on the [Ripple Wiki](https://ripple.com/wiki/Transaction_Fee). + +In short, transaction fees are very small amounts (on the order of ~10) of [XRP drops](https://ripple.com/wiki/Ripple_credits#Notes_on_drops) spent and destroyed with every transaction. They are largely used to account for network load and prevent spam. With `ripple-lib`, transaction fees are calculated locally by default and the fee you are willing to pay is submitted along with your transaction. + +Since the fee required for a transaction may change between the time when the original fee was calculated and the time when the transaction is submitted, it is wise to use the [`fee_cushion`](REFERENCE.md#1-remote-options) to ensure that the transaction will go through. For example, suppose the original fee calculated for a transaction was 10 XRP drops but at the instant the transaction is submitted the server is experiencing a higher load and it has raised its minimum fee to 12 XRP drops. Without a `fee_cusion`, this transaction would not be processed by the server, but with a `fee_cusion` of, say, 1.5 it would be processed and you would just pay the 2 extra XRP drops. + +The [`max_fee`](REFERENCE.md#1-remote-options) option can be used to avoid submitting a transaction to a server that is charging unreasonably high fees. + + + +##4. Listening to the network + +Coming Soon \ No newline at end of file diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 630b2c1d..060b2382 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -1,5 +1,7 @@ #`ripple-lib` API Reference +__(More examples coming soon!)__ + ###In this document: 1. [`Remote` options](REFERENCE.md#1-remote-options) @@ -38,8 +40,9 @@ A new `Remote` can be created with the following options: + `max_listeners` Set maxListeners for remote; prevents EventEmitter warnings (number) + `connection_offset` Connect to remote servers on supplied interval (number in seconds) + `trusted` truthy, if remote is trusted (boolean) -+ `max_fee` Maximum acceptable transaction fee (number in XRP or drops?) -+ `fee_cushion` Extra fee multiplier to account for async fee changes (?) ++ `local_fee` Set whether the transaction fee range will be set locally (boolean, default is true, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees)) ++ `fee_cushion` Extra fee multiplier to account for async fee changes (number, e.g. 1.5, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees)) ++ `max_fee` Maximum acceptable transaction fee (number in [XRP drops](https://ripple.com/wiki/Ripple_credits#Notes_on_drops), see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees)) + `servers` Array of server objects of the following form: ```js @@ -238,3 +241,4 @@ Returns a [Transaction](https://github.com/ripple/ripple-lib/blob/develop/src/js #4. Amount objects +Coming Soon