Partial Payments protections

[mDuo13]

Messing up Partial Payments is one of the costliest, common mistakes people make when building on the XRP Ledger.

People look at the "Amount" field of a successful transaction and assume that's how much it delivered, when actually, it may have delivered a minuscule amount instead.

ripple-lib attempts to protect against this in a couple ways, which we should adapt or improve on:

• getTransaction() and getTransactions() remove the field (specification.destination.amount in the ripple-lib specific format) from the parsed transaction response. You have to pass an option (includeRawTransaction) to get the original version with the potentially-misleading raw field.
• The outcome of getTransaction() shows a balance_changes object that parses through the metadata to show how much currency (of varying types) was actually delivered.
• It doesn't have any protections when calling the rippled APIs directly using .request(methodname, options).

One thing we could do fairly safely is to rename the field from Amount field of Payments to DeliverMax in some or all cases. The JSON format is not really "canonical" anyway, only the binary format, so you can call the fields whatever you want as long as you know what they correspond to.

See also: XRPLF/rippled#3484