0.16.8

Documentation fixes

docs/index.md

@@ -811,7 +811,7 @@ Name | Type | Description
 id | [id](#transaction-id) | A hash of the transaction that can be used to identify it.
 address | [address](#ripple-address) | The address of the account that initiated the transaction.
 sequence | [sequence](#account-sequence-number) | The account sequence number of the transaction for the account that initiated it.
-type | [transactionType](#transaction-types) | The type of the tranasction.
+type | [transactionType](#transaction-types) | The type of the transaction.
 specification | object | A specification that would produce the same outcome as this transaction. The structure of the specification depends on the value of the `type` field (see [Transaction Types](#transaction-types) for details). *Note:* This is **not** necessarily the same as the original specification.
 outcome | object | The outcome of the transaction (what effects it had).
 *outcome.* result | string | Result code returned by rippled. See [Transaction Results](https://ripple.com/build/transactions/#full-transaction-response-list) for a complete list.
@@ -828,6 +828,7 @@ outcome | object | The outcome of the transaction (what effects it had).
 *outcome.orderbookChanges.\*[].* makerExchangeRate | [value](#value) | *Optional* The exchange rate between the `quantity` currency and the `totalPrice` currency from the point of view of the maker.
 *outcome.* ledgerVersion | integer | The ledger version that the transaction was validated in.
 *outcome.* indexInLedger | integer | The ordering index of the transaction in the ledger.
+*outcome.* deliveredAmount | [amount](#amount) | *Optional* For payment transactions, it is impossible to reliably compute the actual delivered amount from the balanceChanges due to fixed precision. If the payment is not a partial payment and the transaction succeeded, the deliveredAmount should always be considered to be the amount specified in the transaction.
 *outcome.* timestamp | date-time string | *Optional* The timestamp when the transaction was validated. (May be missing when requesting transactions in binary mode.)
 
 ### Example
@@ -867,6 +868,11 @@ return api.getTransaction(id).then(transaction => {
     "result": "tesSUCCESS",
     "timestamp": "2013-03-12T23:56:50.000Z",
     "fee": "0.00001",
+    "deliveredAmount": {
+      "currency": "USD",
+      "value": "0.001",
+      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
+    },
     "balanceChanges": {
       "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
         {
@@ -1001,6 +1007,11 @@ return api.getTransactions(address).then(transaction => {
     "outcome": {
       "result": "tesSUCCESS",
       "fee": "0.00001",
+      "deliveredAmount": {
+        "currency": "USD",
+        "value": "0.001",
+        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
+      },
       "balanceChanges": {
         "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
           {
@@ -1093,6 +1104,11 @@ return api.getTransactions(address).then(transaction => {
     "outcome": {
       "result": "tesSUCCESS",
       "fee": "0.00001",
+      "deliveredAmount": {
+        "currency": "USD",
+        "value": "0.001",
+        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
+      },
       "balanceChanges": {
         "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
           {
@@ -2908,7 +2924,7 @@ const trustline = {
     }
   ]
 };
-return api.preparePayment(address, trustline).then(prepared =>
+return api.prepareTrustline(address, trustline).then(prepared =>
   {/* ... */});
 ```
 
@@ -3391,7 +3407,7 @@ This method returns an object with the following structure:
 
 Name | Type | Description
 ---- | ---- | -----------
-resultCode | string | The result code returned by rippled. [List of tranasction responses](http://pages.lightthenight.org/gba/SanFran15/ripple)
+resultCode | string | The result code returned by rippled. [List of transaction responses](https://ripple.com/build/transactions/#full-transaction-response-list)
 resultMessage | string | Human-readable explanation of the status of the transaction.
 
 ### Example

docs/src/prepareTrustline.md.ejs

@@ -23,7 +23,7 @@ All "prepare*" methods have the same return type.
 ```javascript
 const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
 const trustline = <%- importFile('test/fixtures/requests/prepare-trustline.json') %>;
-return api.preparePayment(address, trustline).then(prepared =>
+return api.prepareTrustline(address, trustline).then(prepared =>
   {/* ... */});
 ```
 

npm-shrinkwrap.json

@@ -1,6 +1,6 @@
 {
   "name": "ripple-lib",
-  "version": "0.16.6",
+  "version": "0.16.8",
   "dependencies": {
     "ajv": {
       "version": "1.4.10",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ripple-lib",
-  "version": "0.16.6",
+  "version": "0.16.8",
   "license": "ISC",
   "description": "A JavaScript API for interacting with Ripple in Node.js and the browser",
   "files": [
@@ -43,7 +43,7 @@
     "coveralls": "^2.10.0",
     "doctoc": "^0.15.0",
     "ejs": "^2.3.4",
-    "eslint": "^1.3.0",
+    "eslint": "^2.1.0",
     "eventemitter2": "^0.4.14",
     "flow-bin": "^0.14",
     "gulp": "^3.8.10",

src/common/connection.js

@@ -1,4 +1,3 @@
-'use strict';
 const _ = require('lodash');
 const {EventEmitter} = require('events');
 const WebSocket = require('ws');
@@ -97,6 +96,10 @@ class Connection extends EventEmitter {
   }
 
   _onUnexpectedClose(resolve = function() {}, reject = function() {}) {
+    if (this._onOpenErrorBound) {
+      this._ws.removeListener('error', this._onOpenErrorBound);
+      this._onOpenErrorBound = null;
+    }
     this._ws = null;
     this._isReady = false;
     this.connect().then(resolve, reject);
@@ -107,6 +110,11 @@ class Connection extends EventEmitter {
     this._onUnexpectedCloseBound = this._onUnexpectedClose.bind(this);
     this._ws.once('close', this._onUnexpectedCloseBound);
 
+    this._ws.removeListener('error', this._onOpenErrorBound);
+    this._onOpenErrorBound = null;
+    this._ws.on('error', error =>
+      this.emit('error', 'websocket', error.message, error));
+
     const request = {
       command: 'subscribe',
       streams: ['ledger']
@@ -118,6 +126,10 @@ class Connection extends EventEmitter {
     });
   }
 
+  _onOpenError(reject, error) {
+    reject(new NotConnectedError(error && error.message));
+  }
+
   _createWebSocket() {
     const options = {};
     if (this._proxyURL !== undefined) {
@@ -177,8 +189,11 @@ class Connection extends EventEmitter {
         // should still be emitted; the "ws" documentation says: "The close
         // event is also emitted when then underlying net.Socket closes the
         // connection (end or close)."
-        this._ws.on('error', error =>
-          this.emit('error', 'websocket', error.message, error));
+        // In case if there is connection error (say, server is not responding)
+        // we must return this error to connection's caller. After successful
+        // opening, we will forward all errors to main api object.
+        this._onOpenErrorBound = this._onOpenError.bind(this, reject);
+        this._ws.once('error', this._onOpenErrorBound);
         this._ws.on('message', this._onMessage.bind(this));
         // in browser close event can came before open event, so we must
         // resolve connect's promise after reconnect in that case.

src/common/schemas/objects/amount.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-04/schema#",
   "title": "amount",
   "link": "amount",
-  "description": "An Amount on the Ripple Protocol, used also for XRP in the ripple-rest API",
+  "description": "An Amount on the Ripple Protocol",
   "allOf": [
     {"$ref": "amountbase"},
     {"required": ["value"]}

src/common/schemas/objects/tx-type.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-04/schema#",
   "title": "transactionType",
   "link": "transaction-types",
-  "description": "The type of the tranasction.",
+  "description": "The type of the transaction.",
   "type": "string",
   "enum": ["payment", "order", "orderCancellation", "trustline", "settings",
            "suspendedPaymentCreation", "suspendedPaymentCancellation",

src/common/schemas/output/outcome.json

@@ -17,6 +17,10 @@
       "$ref": "value",
       "description": "The XRP fee that was charged for the transaction."
     },
+    "deliveredAmount": {
+      "$ref": "amount",
+      "description": "For payment transactions, it is impossible to reliably compute the actual delivered amount from the balanceChanges due to fixed precision. If the payment is not a partial payment and the transaction succeeded, the deliveredAmount should always be considered to be the amount specified in the transaction."
+    },
     "balanceChanges": {
       "type": "object",
       "additionalProperties": {

src/common/schemas/output/submit.json

@@ -5,7 +5,7 @@
   "properties": {
     "resultCode": {
       "type": "string",
-      "description": "The result code returned by rippled. [List of tranasction responses](http://pages.lightthenight.org/gba/SanFran15/ripple)"
+      "description": "The result code returned by rippled. [List of transaction responses](https://ripple.com/build/transactions/#full-transaction-response-list)"
     },
     "resultMessage": {
       "type": "string",

src/ledger/parse/amount.js

@@ -1,6 +1,6 @@
 /* @flow */
 'use strict';
-const utils = require('./utils');
+const utils = require('../utils');
 import type {Amount, RippledAmount} from '../../common/types.js';
 
 
@@ -8,7 +8,7 @@ function parseAmount(amount: RippledAmount): Amount {
   if (typeof amount === 'string') {
     return {
       currency: 'XRP',
-      value: utils.dropsToXrp(amount)
+      value: utils.common.dropsToXrp(amount)
     };
   }
   return {

src/ledger/parse/payment.js

@@ -6,10 +6,6 @@ const utils = require('./utils');
 const parseAmount = require('./amount');
 const txFlags = utils.txFlags;
 
-function isPartialPayment(tx) {
-  return (tx.Flags & txFlags.Payment.PartialPayment) !== 0;
-}
-
 function isNoDirectRipple(tx) {
   return (tx.Flags & txFlags.Payment.NoRippleDirect) !== 0;
 }
@@ -45,7 +41,7 @@ function parsePayment(tx: Object): Object {
     memos: utils.parseMemos(tx),
     invoiceID: tx.InvoiceID,
     paths: tx.Paths ? JSON.stringify(tx.Paths) : undefined,
-    allowPartialPayment: isPartialPayment(tx) || undefined,
+    allowPartialPayment: utils.isPartialPayment(tx) || undefined,
     noDirectRipple: isNoDirectRipple(tx) || undefined,
     limitQuality: isQualityLimited(tx) || undefined
   });

src/ledger/parse/utils.js

@@ -4,6 +4,9 @@ const _ = require('lodash');
 const transactionParser = require('ripple-lib-transactionparser');
 const utils = require('../utils');
 const BigNumber = require('bignumber.js');
+const parseAmount = require('./amount');
+
+import type {Amount} from '../common/types.js';
 
 function adjustQualityForXRP(
   quality: string, takerGetsCurrency: string, takerPaysCurrency: string
@@ -35,19 +38,39 @@ function removeEmptyCounterparty(amount) {
 }
 
 function removeEmptyCounterpartyInBalanceChanges(balanceChanges) {
-  _.forEach(balanceChanges, (changes) => {
+  _.forEach(balanceChanges, changes => {
     _.forEach(changes, removeEmptyCounterparty);
   });
 }
 
 function removeEmptyCounterpartyInOrderbookChanges(orderbookChanges) {
-  _.forEach(orderbookChanges, (changes) => {
-    _.forEach(changes, (change) => {
+  _.forEach(orderbookChanges, changes => {
+    _.forEach(changes, change => {
       _.forEach(change, removeEmptyCounterparty);
     });
   });
 }
 
+function isPartialPayment(tx) {
+  return (tx.Flags & utils.common.txFlags.Payment.PartialPayment) !== 0;
+}
+
+function parseDeliveredAmount(tx: Object): Amount | void {
+  let deliveredAmount;
+
+  // TODO: Workaround for existing rippled bug where delivered_amount may not be
+  // provided for account_tx
+  if (tx.TransactionType === 'Payment') {
+    if (tx.meta.delivered_amount) {
+      deliveredAmount = parseAmount(tx.meta.delivered_amount);
+    } else if (tx.Amount && !isPartialPayment(tx)) {
+      deliveredAmount = parseAmount(tx.Amount);
+    }
+  }
+
+  return deliveredAmount;
+}
+
 function parseOutcome(tx: Object): ?Object {
   const metadata = tx.meta || tx.metaData;
   if (!metadata) {
@@ -58,15 +81,16 @@ function parseOutcome(tx: Object): ?Object {
   removeEmptyCounterpartyInBalanceChanges(balanceChanges);
   removeEmptyCounterpartyInOrderbookChanges(orderbookChanges);
 
-  return {
+  return utils.common.removeUndefined({
     result: tx.meta.TransactionResult,
     timestamp: parseTimestamp(tx.date),
     fee: utils.common.dropsToXrp(tx.Fee),
     balanceChanges: balanceChanges,
     orderbookChanges: orderbookChanges,
     ledgerVersion: tx.ledger_index,
-    indexInLedger: tx.meta.TransactionIndex
-  };
+    indexInLedger: tx.meta.TransactionIndex,
+    deliveredAmount: parseDeliveredAmount(tx)
+  });
 }
 
 function hexToString(hex: string): ?string {
@@ -77,7 +101,7 @@ function parseMemos(tx: Object): ?Array<Object> {
   if (!Array.isArray(tx.Memos) || tx.Memos.length === 0) {
     return undefined;
   }
-  return tx.Memos.map((m) => {
+  return tx.Memos.map(m => {
     return utils.common.removeUndefined({
       type: m.Memo.parsed_memo_type || hexToString(m.Memo.MemoType),
       format: m.Memo.parsed_memo_format || hexToString(m.Memo.MemoFormat),
@@ -93,6 +117,7 @@ module.exports = {
   hexToString,
   parseTimestamp,
   adjustQualityForXRP,
+  isPartialPayment,
   dropsToXrp: utils.common.dropsToXrp,
   constants: utils.common.constants,
   txFlags: utils.common.txFlags,

test/connection-test.js

@@ -1,5 +1,4 @@
 /* eslint-disable max-nested-callbacks */
-'use strict';
 
 const _ = require('lodash');
 const net = require('net');
@@ -106,6 +105,26 @@ describe('Connection', function() {
     });
   });
 
+  it('should throw NotConnectedError if server not responding ', function(
+    done
+  ) {
+    if (process.browser) {
+      const phantomTest = /PhantomJS/;
+      if (phantomTest.test(navigator.userAgent)) {
+        // inside PhantomJS this one just hangs, so skip as not very relevant
+        done();
+        return;
+      }
+    }
+
+    const connection = new utils.common.Connection('ws://127.0.0.1:321');
+    connection.on('error', done);
+    connection.connect().catch(error => {
+      assert(error instanceof this.api.errors.NotConnectedError);
+      done();
+    });
+  });
+
   it('DisconnectedError', function() {
     this.api.connection._send(JSON.stringify({
       command: 'config',

test/fixtures/responses/get-ledger-full.json

@@ -34,6 +34,10 @@
       "outcome": {
         "result": "tesSUCCESS",
         "fee": "0.00001",
+        "deliveredAmount": {
+          "currency": "XRP",
+          "value": "10000"
+        },
         "balanceChanges": {
           "rLQBHVhFnaC5gLEkgr6HgBJJ3bgeZHg9cj": [
             {

test/fixtures/responses/get-transaction-payment.json

@@ -24,6 +24,11 @@
     "result": "tesSUCCESS",
     "timestamp": "2013-03-12T23:56:50.000Z",
     "fee": "0.00001",
+    "deliveredAmount": {
+      "currency": "USD",
+      "value": "0.001",
+      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
+    },
     "balanceChanges": {
       "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
         {

test/fixtures/responses/get-transactions.json

@@ -30,6 +30,11 @@
     "outcome": {
       "result": "tesSUCCESS",
       "fee": "0.00001",
+      "deliveredAmount": {
+        "currency": "USD",
+        "value": "0.001",
+        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
+      },
       "balanceChanges": {
         "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
           {
@@ -122,6 +127,11 @@
     "outcome": {
       "result": "tesSUCCESS",
       "fee": "0.00001",
+      "deliveredAmount": {
+        "currency": "USD",
+        "value": "0.001",
+        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
+      },
       "balanceChanges": {
         "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
           {