Add deliveredAmount to payment outcome

It is impossible to reliably compute the delivered amount from the metadata due
to fixed precision. If the partial payment flag is not set and the transaction
succeeded, the delivered amount should always be considered to be the amount
specified in the transaction.

docs/index.md

@@ -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": [
           {

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/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/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
@@ -48,6 +51,24 @@ function removeEmptyCounterpartyInOrderbookChanges(orderbookChanges) {
   });
 }
 
+function isPartialPayment(tx) {
+  return (tx.Flags & utils.common.txFlags.Payment.PartialPayment) !== 0;
+}
+
+function parseDeliveredAmount(tx: Object): Amount | void {
+  let deliveredAmount;
+
+  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 +79,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 {
@@ -93,6 +115,7 @@ module.exports = {
   hexToString,
   parseTimestamp,
   adjustQualityForXRP,
+  isPartialPayment,
   dropsToXrp: utils.common.dropsToXrp,
   constants: utils.common.constants,
   txFlags: utils.common.txFlags,

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": [
           {