From 9800fd8f11c9141b2173b78d7f67dc2e2a7ca8fc Mon Sep 17 00:00:00 2001 From: Stefan Thomas Date: Mon, 25 Aug 2014 15:17:02 -0700 Subject: [PATCH 1/3] [TEST] Previous test cases were using the functionality being tested. The previous version of these tests was using `get_address` just like the code being tested. It's better to check if the code in question has actually been able to correctly find the public key (which means it also found the correct private key.) --- test/seed-test.js | 68 ++++++++++++++++++++--------------------------- 1 file changed, 29 insertions(+), 39 deletions(-) diff --git a/test/seed-test.js b/test/seed-test.js index d3785197..972de19c 100644 --- a/test/seed-test.js +++ b/test/seed-test.js @@ -7,55 +7,45 @@ describe('Seed', function() { it('can generate many addresses', function () { var seed = Seed.from_json("masterpassphrase"); - // Note: Created with jRippleAPI code - // Link: https://github.com/pmarches/jRippleAPI/blob/master/src/jrippleapi/keys/RippleDeterministicKeyGenerator.java + var test_data = [ + // Format: + // [passphrase, address, nth-for-seed, expected-public-key] + ["masterpassphrase", "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh", 0, + "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020"], + ["masterpassphrase", "r4bYF7SLUMD7QgSLLpgJx38WJSY12ViRjP", 1, + "02CD8C4CE87F86AAD1D9D18B03DE28E6E756F040BD72A9C127862833EB90D60BAD"], + ["masterpassphrase", "rLpAd4peHUMBPbVJASMYK5GTBUSwXRD9nx", 2, + "0259A57642A6F4AEFC9B8062AF453FDEEEAC5572BA602BB1DBD5EF011394C6F9FC"], + ["otherpassphrase", "rpe3YWSVwGU2PmUzebAPg2deBXHtmba7hJ", 0, + "022235A3DB2CAE57C60B7831929611D58867F86D28C0AD3C82473CC4A84990D01B"], + ["otherpassphrase", "raAPC2gALSmsTkXR4wUwQcPgX66kJuLv2S", 5, + "03F0619AFABE08D22D98C8721895FE3673B6174168949976F2573CE1138C124994"], + ["yetanotherpassphrase", "rKnM44fS48qrGiDxB5fB5u64vHVJwjDPUo", 0, + "0385AD049327EF7E5EC429350A15CEB23955037DE99660F6E70C11C5ABF4407036"], + ["yetanotherpassphrase", "rMvkT1RHPfsZwTFbKDKBEisa5U4d2a9V8n", 1, + "023A2876EA130CBE7BBA0573C2DB4C4CEB9A7547666915BD40366CDC6150CF54DC"] + ]; - // To reviewer/merger: Even generating keypairs for thi this small amount of - // addresses makes the test suite run SO SLOW. Consider cutting at the tail. - var first_nth_addresses = [ - // 0th implied - "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh", - // 1th implied - "r4bYF7SLUMD7QgSLLpgJx38WJSY12ViRjP", - // 2th implied - "rLpAd4peHUMBPbVJASMYK5GTBUSwXRD9nx", - // ... - "rN9HWHPAftXC6xNxJRqgVr1HexpUi6FBUa", - "rhwPfeEkeQh2vqoKGPBpPyS9nKmKZdpypu", - "rKdNfPfrzfisDCPCqK67YhDLezuVKGKXNm", - "rsn4NeGzMRvMn5ABQxmt9VNEkSknVneBK4", - "rUSJGFH1kQnaKpoAhkArfyw6HZVe8GT5w3", - "r3EYp6isx2Row5pu19C4Ujvp68oEEabhuA", - "rGiYpnAn9DTXiM78CCJcYAuL6QHEDdazHA", - "rVrRVeqqEJHAove5B9TqBAHEXBTzMi5eu", - "rJbarThDXYXxtCgDxRoTCDf2NoYdgSjuVk", - "rfuWNJ1TkQzoZZcc4K8wmtsUiGwURFbed1", - "rpuTqebfbZZdKEUV3bjecoViNL4W4gepWZ", - "r42ywHUco4C2AjgaSmYM7uX13Kbz6GdDKp", - "rnWb45MLd5hQiB6Arr94DdY2z95quL7XNf", - "rMukaQ87bfAeddcT16RtgS3RbFmaQWrSGu", - "rN6dMHU51K9y8eVMhjQMsQVp5gPwt3eYYx", - "rfRFyeJDNqpfZVFmjNj9tNzFVsCNAWKtNc", - "rMoGSX48KrT31HKx9KfMSnYhjvRw3YYzQW", - "rfTiEfbeVsYU7QEe1Zfogiz7h43x6ChKGC" - ] - - function assert_helper(account_id, expected) { - var keypair = seed.get_key(account_id); - assert.strictEqual(keypair.get_address().to_json(), + function assert_helper(seed_json, address_or_nth, expected) { + var seed = Seed.from_json(seed_json); + var keypair = seed.get_key(address_or_nth); + assert.strictEqual(keypair.to_hex_pub(), expected); } - for (var nth = 0; nth < first_nth_addresses.length; nth++) { - var expected = first_nth_addresses[nth], looking_for; + for (var nth = 0; nth < test_data.length; nth++) { + var seed_json = test_data[nth][0]; + var address = test_data[nth][1]; + var nth_for_seed = test_data[nth][2]; + var expected = test_data[nth][3]; //`seed.get_key($ripple_address)` is arguably an ill concieved feature // as it needs to generate `nth` many keypairs and generate hashed public // keys (addresses) for equality tests ?? // Would need remote.set_secret(address, private_key_not_seed) ?? - assert_helper((looking_for = expected), expected) + assert_helper(seed_json, address, expected); // This isn't too bad as it only needs to generate one keypair `seq` - assert_helper((looking_for = nth), expected) + assert_helper(seed_json, nth_for_seed, expected); }; }); }); From 2e2ab6bffc23b80780f03d3c5a6b4b669b1c91f1 Mon Sep 17 00:00:00 2001 From: wltsmrz Date: Tue, 26 Aug 2014 13:41:27 -0700 Subject: [PATCH 2/3] Update docs --- README.md | 11 +- docs/GUIDES.md | 140 +++++++++++++------------ docs/REFERENCE.md | 262 +++++++++++++++++++++++++++------------------- 3 files changed, 229 insertions(+), 184 deletions(-) diff --git a/README.md b/README.md index 4151ea72..433fab8d 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ #ripple-lib +JavaScript client for [rippled](https://github.com/ripple/rippled) + [![Build Status](https://travis-ci.org/ripple/ripple-lib.svg?branch=develop)](https://travis-ci.org/ripple/ripple-lib) [![Coverage Status](https://coveralls.io/repos/ripple/ripple-lib/badge.png?branch=develop)](https://coveralls.io/r/ripple/ripple-lib?branch=develop) [![NPM](https://nodei.co/npm/ripple-lib.png)](https://www.npmjs.org/package/ripple-lib) -JavaScript client for [rippled](https://github.com/ripple/rippled) - ###Features + Connect to a rippled server in JavaScript (Node.js or browser) @@ -15,10 +15,9 @@ JavaScript client for [rippled](https://github.com/ripple/rippled) ###In this file -1. Overview -2. [Installation](README.md#installation) -3. [Quickstart](README.md#quickstart) -4. [Running tests](https://github.com/ripple/ripple-lib#running-tests) +1. [Installation](README.md#installation) +2. [Quickstart](README.md#quickstart) +3. [Running tests](https://github.com/ripple/ripple-lib#running-tests) ###Additional documentation diff --git a/docs/GUIDES.md b/docs/GUIDES.md index 908a35f8..c966612f 100644 --- a/docs/GUIDES.md +++ b/docs/GUIDES.md @@ -1,26 +1,25 @@ -#`ripple-lib` Guides +#Guides This file provides step-by-step walkthroughs for some of the most common usages of `ripple-lib`. -###Guides in this document: +###In this document -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 payment to the network](GUIDES.md#3-submitting-a-payment-to-the-network) +1. [Connecting to the Ripple network with `Remote`](GUIDES.md#connecting-to-the-ripple-network) +2. [Using `Remote` functions and `Request` objects](GUIDES.md#sending-rippled-API-requests) +3. [Listening to the network](GUIDES.md#listening-to-the-network) +4. [Submitting a payment to the network](GUIDES.md#submitting-a-payment-to-the-network) * [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees) -4. [Submitting a trade offer to the network](GUIDES.md#4-submitting-a-trade-offer-to-the-network) -5. [Listening to the network](GUIDES.md#5-listening-to-the-network) +5. [Submitting a trade offer to the network](GUIDES.md#submitting-a-trade-offer-to-the-network) +###Also see -###Also see: +1. [The ripple-lib README](../README.md) +2. [The ripple-lib API Reference](REFERENCE.md) -1. [The `ripple-lib` README](../README.md) -2. [The `ripple-lib` API Reference](REFERENCE.md) +##Connecting to the Ripple network -##1. Connecting to the Ripple network with `Remote` - -1. [Get `ripple-lib`](README.md#getting-ripple-lib) -2. Load the `ripple-lib` module into a Node.js file or webpage: +1. [Get ripple-lib](README.md#getting-ripple-lib) +2. Load the ripple-lib module into a Node.js file or webpage: ```js /* Loading ripple-lib with Node.js */ var Remote = require('ripple-lib').Remote; @@ -37,32 +36,36 @@ This file provides step-by-step walkthroughs for some of the most common usages }); ``` __NOTE:__ See the API Reference for available [`Remote` options](REFERENCE.md#1-remote-options) + 4. You're connected! Read on to see what to do now. -##2. Using `Remote` functions and `Request` objects +##Sending rippled API requests -All `Remote` functions return a `Request` object. +`Remote` contains functions for constructing a `Request` object. -A `Request` is an `EventEmitter` so you can listen for success or failure events -- or, instead, you can provide a callback to the `Remote` function. +A `Request` is an `EventEmitter` so you can listen for success or failure events -- or, instead, you can provide a callback. -Here is an example, using `request_server_info()`, of how `Remote` functions can be used with event listeners (the first code block) or with a callback (the second block): +Here is an example, using [request_server_info](https://ripple.com/wiki/JSON_Messages#server_info). -+ Using a `Remote` function with `Request` event listeners: ++ Constructing a `Request` with event listeners ```js -var request = remote.request_server_info(); -request.on('success', function(res) { +var request = remote.request('server_info'); + +request.on('success', function onSuccess(res) { //handle success }); -request.on('error', function(err) { + +request.on('error', function onError(err) { //handle error }); -request.request(); // this triggers the request if it has not already been sent to the server + +request.request(); ``` -+ Using a `Remote` function with a callback: ++ Using a callback: ```js -remote.request_server_info(function(err, res) { +remote.request('server_info', function(err, res) { if (err) { //handle error } else { @@ -74,9 +77,44 @@ remote.request_server_info(function(err, res) { __NOTE:__ See the API Reference for available [`Remote` functions](REFERENCE.md#2-remote-functions) +##Listening to the network +See the [wiki](https://ripple.com/wiki/JSON_Messages#subscribe) for details on subscription requests. -##3. Submitting a payment to the network +```js + /* Loading ripple-lib with Node.js */ + var Remote = require('ripple-lib').Remote; + + /* Loading ripple-lib in a webpage */ + // var Remote = ripple.Remote; + + var remote = new Remote({options}); + + remote.connect(function() { + var request = remote.request('subscribe'); + + request.addStream('ledger'); //remote will emit `ledger_closed` + request.addStream('transactions'); //remote will emit `transaction` + + request.on('ledger_closed', function onLedgerClosed(ledgerData) { + //handle ledger + }); + + remote.on('transaction', function onTransacstion(transaction) { + //handle transaction + }); + + remote.request(function(err) { + if (err) { + } else { + } + }); + }); +``` +* https://ripple.com/wiki/RPC_API#transactions_stream_messages +* https://ripple.com/wiki/RPC_API#ledger_stream_messages + +##Submitting a payment to the network Submitting a payment transaction to the Ripple network involves connecting to a `Remote`, creating a transaction, signing it with the user's secret, and submitting it to the `rippled` server. Note that the `Amount` module is used to convert human-readable amounts like '1XRP' or '10.50USD' to the type of Amount object used by the Ripple network. @@ -97,13 +135,11 @@ var AMOUNT = Amount.from_human('1XRP'); var remote = new Remote({ /* Remote options */ }); remote.connect(function() { - remote.set_secret(MY_ADDRESS, MY_SECRET); + remote.setSecret(MY_ADDRESS, MY_SECRET); - var transaction = remote.transaction(); - - transaction.payment({ - from: MY_ADDRESS, - to: RECIPIENT, + var transaction = remote.createTransaction('Payment', { + account: MY_ADDRESS, + destination: RECIPIENT, amount: AMOUNT }); @@ -151,12 +187,10 @@ var EXPIRATION = tomorrow; var remote = new Remote({ /* Remote options */ }); remote.connect(function() { - remote.set_secret(MY_ADDRESS, MY_SECRET); + remote.setSecret(MY_ADDRESS, MY_SECRET); - var transaction = remote.transaction(); - - transaction.offer_create({ - from: MY_ADDRESS, + var transaction = remote.createTransaction('OfferCreate', { + account: MY_ADDRESS, buy: BUY_AMOUNT, sell: SELL_AMOUNT, expiration: EXPIRATION @@ -167,35 +201,3 @@ remote.connect(function() { }); }); ``` - -##5. Listening to the network - -In some (relatively rare) cases you may want to subscribe to the network event feed and listen for transactions and the ledger closings. [Ripple.com](http://www.ripple.com) uses this feature of `ripple-lib` to display the live feed on the top of each page and the ledger closing visualization on the [Developers page](http://ripple.com/devs). - -```js - /* Loading ripple-lib with Node.js */ - var Remote = require('ripple-lib').Remote; - - /* Loading ripple-lib in a webpage */ - // var Remote = ripple.Remote; - - var remote = new Remote({options}); - - remote.connect(function() { - remote.on('transaction_all', transactionListener); - remote.on('ledger_closed', ledgerListener); - }); - - function transactionListener (transaction_data) { - // handle transaction_data - // see https://ripple.com/wiki/RPC_API#transactions_stream_messages for the format of transaction_data - } - - function ledgerListener (ledger_data) { - // handle ledger_data - // see https://ripple.com/wiki/RPC_API#ledger_stream_messages for the format of ledger_data - } -``` -* https://ripple.com/wiki/RPC_API#transactions_stream_messages -* https://ripple.com/wiki/RPC_API#ledger_stream_messages - diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 87ce0903..866b6f10 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -1,28 +1,26 @@ -#`ripple-lib` API Reference +#API Reference __(More examples coming soon!)__ ###In this document: -1. [`Remote` options](REFERENCE.md#1-remote-options) -2. [`Remote` functions](REFERENCE.md#2-remote-functions) - + [Server info functions](REFERENCE.md#server-info-functions) - + [Ledger query functions](REFERENCE.md#ledger-query-functions) - + [Transaction query functions](REFERENCE.md#transaction-query-functions) - + [Account query functions](REFERENCE.md#account-query-functions) - + [Order book query functions](REFERENCE.md#order-book-query-functions) - + [Transaction submission functions](REFERENCE.md#transaction-submission-functions) -3. [`Transaction` events](REFERENCE.md#3-transaction-events) -4. [`Amount` objects](REFERENCE.md#4-amount-objects) - +1. [`Remote` options](REFERENCE.md#remote-options) +2. [`Request` constructors](REFERENCE.md#request-constructor-functions) + + [Server requests](REFERENCE.md#server-requests) + + [Ledger requests](REFERENCE.md#ledger-requests) + + [Transaction requests](REFERENCE.md#transaction-requests) + + [Account requests](REFERENCE.md#account-requests) + + [Orderbook requests](REFERENCE.md#orderbook-requests) + + [Transaction requests](REFERENCE.md#transaction-requests) +3. [`Transaction` constructors](REFERENCE.md#transaction-constructors) + + [Transaction events](REFERENCE.md#transaction-events) ###Also see: -1. [The `ripple-lib` README](../README.md) -2. [The `ripple-lib` GUIDES](GUIDES.md) +1. [The ripple-lib README](../README.md) +2. [The ripple-lib GUIDES](GUIDES.md) - -#1. `Remote` options +#Remote options ```js /* Loading ripple-lib with Node.js */ @@ -31,98 +29,86 @@ var Remote = require('ripple-lib').Remote; /* Loading ripple-lib in a webpage */ // var Remote = ripple.Remote; -var remote = new Remote({options}); +var options = { }; + +var remote = new Remote(options); ``` A new `Remote` can be created with the following options: -+ `trace` Log all of the events emitted (boolean) -+ `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) -+ `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: ++ `trace` *boolean default: false* Log all of the events emitted ++ `max_listeners` *number default: 0* Set maxListeners for servers ++ `trusted` *boolean default: false*, if remote is trusted (boolean) ++ `local_signing` *boolean default: true* ++ `local_fee` *boolean default: true* Set whether the transaction fee range will be set locally, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees)) ++ `fee_cushion` *number default: 1.2* Extra fee multiplier to account for async fee changes, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees)) ++ `max_fee` *number default: Infinity* Maximum acceptable transaction fee, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees) ++ `servers` *array* Array of server objects of the following form: ```js -{ - host: - , port: - , secure: +{ + host: , + port: , + secure: } ``` -+ `local_signing` -#2. `Remote` functions - - - -##Server info functions - -**[requestServerInfo([callback])](https://ripple.com/wiki/RPC_API#server_info)** - -Returns information about the state of the server. If you are connected to multiple servers and want to select by a particular host, use `request.set_server`. Example: +or ```js -var request = remote.request_server_info(); -request.set_server('my.hostname'); -request.callback(function(err, res) { - -}); -request.request(); + 'wss://host:port' ``` -**[requestUnlList([callback])](https://ripple.com/wiki/RPC_API#unl_list)** +#Request constructor functions -**[requestUnlAdd(addr, comment, [callback])](https://ripple.com/wiki/RPC_API#unl_add)** +##Server requests -**[requestUnlDelete(node, [callback])](https://ripple.com/wiki/RPC_API#unl_delete)** +**[server_info([callback])](https://ripple.com/wiki/JSON_Messages#server_info)** -**[requestPeers([callback])](https://ripple.com/wiki/RPC_API#peers)** +Returns information about the state of the server. If you are connected to multiple servers and want to select by a particular host, use `request.setServer`. Example: + +```js +var request = remote.request('server_info'); + +request.setServer('wss://s1.ripple.com'); + +request.request(function(err, res) { + +}); +``` + +**[unl_list([callback])](https://ripple.com/wiki/JSON_Messages#unl_list)** + +**[unl_add(addr, comment, [callback])](https://ripple.com/wiki/JSON_Messages#unl_add)** + +**[unl_delete(node, [callback])](https://ripple.com/wiki/JSON_Messages#unl_delete)** + +**[requestPeers([callback])](https://ripple.com/wiki/JSON_Messages#peers)** -**[requestConnect(ip, port, [callback])](https://ripple.com/wiki/RPC_API#connect)** +**[connect(ip, port, [callback])](https://ripple.com/wiki/JSON_Messages#connect)** +##Ledger requests +**[ledger(ledger, [opts], [callback])](https://ripple.com/wiki/JSON_Messages#ledger)** -##Ledger query functions +**ledger_header([callback])** -**[requestLedger(ledger, [opts], [callback])](https://ripple.com/wiki/RPC_API#ledger)** +**[ledger_current([callback])](https://ripple.com/wiki/JSON_Messages#ledger_current)** -**requestLedgerHeader([callback])** +**[ledger_entry(type, [callback])](https://ripple.com/wiki/JSON_Messages#ledger_entry)** -**[requestLedgerCurrent([callback])](https://ripple.com/wiki/RPC_API#ledger_current)** - -**[requestLedgerEntry(type, [callback])](https://ripple.com/wiki/RPC_API#ledger_entry)** - -**[requestSubscribe(streams, [callback])](https://ripple.com/wiki/RPC_API#subscribe)** +**[subscribe([streams], [callback])](https://ripple.com/wiki/JSON_Messages#subscribe)** Start receiving selected streams from the server. -**[requestUnsubscribe(streams, [callback])](https://ripple.com/wiki/RPC_API#unsubscribe)** +**[unsubscribe([streams], [callback])](https://ripple.com/wiki/JSON_Messages#unsubscribe)** Stop receiving selected streams from the server. +##Account requests - - -##Transaction query functions - -**[requestTransactionEntry(hash, [ledger_hash], [callback])](https://ripple.com/wiki/RPC_API#transaction_entry)** - -Searches a particular ledger for a transaction hash. Default ledger is the open ledger. - -**[requestTx(hash, [callback])](https://ripple.com/wiki/RPC_API#tx)** - -Searches ledger history for validated transaction hashes. - - - - -##Account query functions - -**[requestAccountInfo(account, [callback])](https://ripple.com/wiki/RPC_API#account_info)** +**[account_info(account, [callback])](https://ripple.com/wiki/JSON_Messages#account_info)** Return information about the specified account. @@ -143,13 +129,13 @@ Return information about the specified account. } ``` -**[requestAccountLines(accountID, account_index, current, [callback])](https://ripple.com/wiki/RPC_API#account_lines)** +**[account_lines(accountID, [account_index], [ledger], [callback])](https://ripple.com/wiki/JSON_Messages#account_lines)** -**[requestAccountOffers(accountID, account_index, current, [callback])](https://ripple.com/wiki/RPC_API#account_offers)** +**[account_offers(accountID, [account_index], [ledger], [callback])](https://ripple.com/wiki/JSON_Messages#account_offers)** Return the specified account's outstanding offers. -**[requestAccountTx(opts, [callback])](https://ripple.com/wiki/RPC_API#account_tx)** +**[account_tx(options, [callback])](https://ripple.com/wiki/JSON_Messages#account_tx)** Fetch a list of transactions that applied to this account. @@ -167,92 +153,150 @@ Options: + `fwd_marker` + `rev_marker` -**[requestWalletAccounts(seed, [callback])](https://ripple.com/wiki/RPC_API#wallet_accounts)** +**[wallet_accounts(seed, [callback])](https://ripple.com/wiki/JSON_Messages#wallet_accounts)** -Return a list of accounts for a wallet. +Return a list of accounts for a wallet. *Requires trusted remote* -+ requires trusted remote - -**requestAccountBalance(account, ledger, [callback])** +**account_balance(account, [ledger], [callback])** Get the balance for an account. Returns an [Amount](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/amount.js) object. -**requestAccountFlags(account, current, [callback])** +**account_flags(account, [ledger], [callback])** Return the flags for an account. -**requestOwnerCount(account, current, [callback])** +**owner_count(account, [ledger], [callback])** Return the owner count for an account. -**requestRippleBalance(account, issuer, currency, current, [callback])** +**ripple_balance(account, issuer, currency, [ledger], [callback])** Return a request to get a ripple balance +##Orderbook requests +**[book_offers(options, [callback])](https://ripple.com/wiki/JSON_Messages#book_offers)** - -##Order book query functions - -**[requestBookOffers(gets, pays, taker, [callback])](https://ripple.com/wiki/RPC_API#book_offers)** - -Return the offers for an order book as one or more pages. +Return the offers for an order book, also called a *snapshot* ```js -var request = remote.request_book_offers({ - gets: { +var request = remote.request('book_offers', { + taker_gets: { 'currency':'XRP' }, - pays: { + taker_pays: { 'currency':'USD', 'issuer': 'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' } }); -request.request(); +request.request(function(err, offers) { + //handle offers +}); ``` +##Transaction requests +**[transaction_entry(hash, [ledger_hash], [callback])](https://ripple.com/wiki/JSON_Messages#transaction_entry)** +Searches a particular ledger for a transaction hash. Default ledger is the open ledger. -##Transaction submission functions +**[tx(hash, [callback])](https://ripple.com/wiki/JSON_Messages#tx)** -**[requestSign(secret, tx_json, [callback])](https://ripple.com/wiki/RPC_API#sign)** +Searches ledger history for validated transaction hashes. -Sign a transaction. +**[sign(secret, tx_json, [callback])](https://ripple.com/wiki/JSON_Messages#sign)** -+ requires trusted remote +Sign a transaction. *Requires trusted remote* -**[requestSubmit([callback])](https://ripple.com/wiki/RPC_API#submit)** +**[submit([callback])](https://ripple.com/wiki/JSON_Messages#submit)** Submit a transaction to the network. This command is used internally to submit transactions with a greater degree of reliability. See [Submitting a payment to the network](GUIDES.md#3-submitting-a-payment-to-the-network) for details. +**[ripple_path_find(src_account, dst_account, dst_amount, src_currencies, [callback])](https://ripple.com/wiki/JSON_Messages#path_find)** -**[requestRipplePathFind(src_account, dst_account, dst_amount, src_currencies, [callback])](https://ripple.com/wiki/RPC_API#path_find)** +#Transaction constructors +Use `remote.createTransaction('TransactionType', [options])` to construct a transaction. To submit, use `transaction.submit([callback])`. -**transaction([destination], [source], [amount], [callback])** +**Payment** -Returns a [Transaction](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/transaction.js) object +```js +var transaction = remote.createTransaction('Payment', { + account: MY_ADDRESS, + destination: DEST_ADDRESS, + amount: AMOUNT +}); +``` +**AccountSet** -#3. Transaction events +```js +var transaction = remote.createTransaction('AccountSet', { + account: MY_ADDRESS, + set: 'RequireDest', + clear: 'RequireAuth' +}); +``` + +**TrustSet** + +```js +var transaction = remote.createTransaction('TrustSet', { + account: MY_ADDRESS, + limit: '1/USD/rrrrrrrrrrrrrrrrrrrrBZbvji' +}); +``` + +**OfferCreate** + +```js +var transaction = remote.createTransaction('OfferCreate', { + account: MY_ADDRESS, + taker_pays: '1', + taker_gets: '1/USD/rrrrrrrrrrrrrrrrrrrrBZbvji' +}); +``` + +##Transaction events [Transaction](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/transaction.js) objects are EventEmitters. They may emit the following events. + `final` Transaction has erred or succeeded. This event indicates that the transaction has finished processing. + `error` Transaction has erred. This event is a final state. + `success` Transaction succeeded. This event is a final state. ++ `presubmit` Immediately before transaction is submitted ++ `postsubmit` Immediately after transaction is submitted + `submitted` Transaction has been submitted to the network. The submission may result in a remote error or success. ++ `resubmitted` Transaction is beginning resubmission. + `proposed` Transaction has been submitted *successfully* to the network. The transaction at this point is awaiting validation in a ledger. + `timeout` Transaction submission timed out. The transaction will be resubmitted. -+ `resubmit` Transaction is beginning resubmission. + `fee_adjusted` Transaction fee has been adjusted during its pending state. The transaction fee will only be adjusted if the remote is configured for local fees, which it is by default. + `abort` Transaction has been aborted. Transactions are only aborted by manual calls to `#abort`. + `missing` Four ledgers have closed without detecting validated transaction + `lost` Eight ledgers have closed without detecting validated transaction. Consider the transaction lost and err/finalize. +##Complete payment example -#4. Amount objects +```js +remote.setSecret(MY_ADDRESS, MY_SECRET); + +var transaction = remote.createTransaction('Payment', { + account: MY_ADDRESS, + destination: DEST_ADDRESS, + amount: AMOUNT +}); + +transaction.on('resubmitted', function() { + // initial submission failed, resubmitting +}); + +transaction.submit(function(err, res) { + // submission has finalized with either an error or success. + // the transaction will not be retried after this point +}); +``` + +#Amount objects Coming Soon From dd04177f83d6d04ee5753ffbd39cf43c505d81b8 Mon Sep 17 00:00:00 2001 From: wltsmrz Date: Wed, 27 Aug 2014 13:05:54 -0700 Subject: [PATCH 3/3] Update owner_funds --- src/js/ripple/orderbook.js | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/src/js/ripple/orderbook.js b/src/js/ripple/orderbook.js index 56bf00d4..c27d46fd 100644 --- a/src/js/ripple/orderbook.js +++ b/src/js/ripple/orderbook.js @@ -632,12 +632,8 @@ OrderBook.prototype.updateFundedAmounts = function(message) { var result = this.getBalanceChange(node); if (result.isValid) { - var account = result.account; - var balance = result.balance; - - if (this.hasCachedFunds(account)) { - var fundedAmount = this.applyTransferRate(balance); - this.updateOfferFunds(account, fundedAmount); + if (this.hasCachedFunds(result.account)) { + this.updateOfferFunds(result.account, result.balance); } } } @@ -919,14 +915,16 @@ OrderBook.prototype.modifyOffer = function(node, isDeletedNode) { * @param {String|Object} offer funds */ -OrderBook.prototype.updateOfferFunds = function(account, fundedAmount) { +OrderBook.prototype.updateOfferFunds = function(account, balance) { assert(UInt160.is_valid(account), 'Account is invalid'); - assert(!isNaN(fundedAmount), 'Funded amount is invalid'); + assert(!isNaN(balance), 'Funded amount is invalid'); if (this._remote.trace) { log.info('updating offer funds', this._key, account, fundedAmount); } + var fundedAmount = this.applyTransferRate(balance); + // Update cached account funds this.addCachedFunds(account, fundedAmount); @@ -941,6 +939,7 @@ OrderBook.prototype.updateOfferFunds = function(account, fundedAmount) { var previousOffer = extend({}, offer); var previousFundedGets = Amount.from_json(offer.taker_gets_funded + suffix); + offer.owner_funds = balance; this.setFundedAmount(offer, fundedAmount); var hasChangedFunds = !previousFundedGets.equals(