APIv2(DeliverMax): add alias for Amount in Payment transactions (#4733)

Using the "Amount" field in Payment transactions can cause incorrect
interpretation. There continue to be problems from the use of this
field. "Amount" is rarely the correct field to use; instead,
"delivered_amount" (or "DeliveredAmount") should be used.

Rename the "Amount" field to "DeliverMax", a less misleading name. With
api_version: 2, remove the "Amount" field from Payment transactions.

- Input: "DeliverMax" in `tx_json` is an alias for "Amount"
  - sign
  - submit (in sign-and-submit mode)
  - submit_multisigned
  - sign_for
- Output: Add "DeliverMax" where transactions are provided by the API
  - ledger
  - tx
  - tx_history
  - account_tx
  - transaction_entry
  - subscribe (transactions stream)
- Output: Remove "Amount" from API version 2

Fix #3484

Fix #3902

API-CHANGELOG.md

@@ -158,6 +158,15 @@ Since `api_version` 2 is in "beta", breaking changes to V2 can currently be made
 
 - Attempting to use a non-boolean value (such as a string) for the `transactions` parameter returns `invalidParams` (`rpcINVALID_PARAMS`). Previously, in API version 1, no error was returned. (https://github.com/XRPLF/rippled/pull/4620)
 
+##### In progress
+
+- In `Payment` transaction type, JSON RPC field `Amount` is renamed to `DeliverMax`. To enable smooth client transition, `Amount` is still handled, as described below:
+  - On JSON RPC input (e.g. `submit_multisigned` etc. methods), `Amount` is recognized as an alias to `DeliverMax` for both API version 1 and version 2 clients.
+  - On JSON RPC input, submitting both `Amount` and `DeliverMax` fields is allowed _only_ if they are identical; otherwise such input is rejected with `rpcINVALID_PARAMS` error.
+  - On JSON RPC output (e.g. `subscribe`, `account_tx` etc. methods), `DeliverMax` is present in both API version 1 and version 2.
+  - On JSON RPC output, `Amount` is only present in API version 1 and _not_ in version 2.
+
+
 # Unit tests for API changes
 
 The following information is useful to developers contributing to this project:

Builds/CMake/RippledCore.cmake

@@ -217,6 +217,7 @@ install (
 install (
   FILES
     src/ripple/json/JsonPropertyStream.h
+    src/ripple/json/MultivarJson.h
     src/ripple/json/Object.h
     src/ripple/json/Output.h
     src/ripple/json/Writer.h
@@ -467,6 +468,7 @@ target_sources (rippled PRIVATE
   src/ripple/app/misc/detail/impl/WorkSSL.cpp
   src/ripple/app/misc/impl/AccountTxPaging.cpp
   src/ripple/app/misc/impl/AmendmentTable.cpp
+  src/ripple/app/misc/impl/DeliverMax.cpp
   src/ripple/app/misc/impl/LoadFeeTrack.cpp
   src/ripple/app/misc/impl/Manifest.cpp
   src/ripple/app/misc/impl/Transaction.cpp
@@ -918,6 +920,7 @@ if (tests)
     src/test/json/Output_test.cpp
     src/test/json/Writer_test.cpp
     src/test/json/json_value_test.cpp
+    src/test/json/MultivarJson_test.cpp
     #[===============================[
        test sources:
          subdir: jtx

Builds/levelization/results/ordering.txt

@@ -135,6 +135,7 @@ test.csf > ripple.protocol
 test.csf > test.jtx
 test.json > ripple.beast
 test.json > ripple.json
+test.json > ripple.rpc
 test.json > test.jtx
 test.jtx > ripple.app
 test.jtx > ripple.basics

src/ripple/app/ledger/BookListeners.cpp

@@ -39,7 +39,7 @@ BookListeners::removeSubscriber(std::uint64_t seq)
 
 void
 BookListeners::publish(
-    Json::Value const& jvObj,
+    MultiApiJson const& jvObj,
     hash_set<std::uint64_t>& havePublished)
 {
     std::lock_guard sl(mLock);
@@ -54,7 +54,8 @@ BookListeners::publish(
             // Only publish jvObj if this is the first occurence
             if (havePublished.emplace(p->getSeq()).second)
             {
-                p->send(jvObj, true);
+                p->send(
+                    jvObj.select(apiVersionSelector(p->getApiVersion())), true);
             }
             ++it;
         }

src/ripple/app/ledger/BookListeners.h

@@ -20,7 +20,9 @@
 #ifndef RIPPLE_APP_LEDGER_BOOKLISTENERS_H_INCLUDED
 #define RIPPLE_APP_LEDGER_BOOKLISTENERS_H_INCLUDED
 
+#include <ripple/json/MultivarJson.h>
 #include <ripple/net/InfoSub.h>
+
 #include <memory>
 #include <mutex>
 
@@ -58,7 +60,7 @@ class BookListeners
 
     */
     void
-    publish(Json::Value const& jvObj, hash_set<std::uint64_t>& havePublished);
+    publish(MultiApiJson const& jvObj, hash_set<std::uint64_t>& havePublished);
 
 private:
     std::recursive_mutex mLock;

src/ripple/app/ledger/OrderBookDB.cpp

@@ -250,7 +250,7 @@ void
 OrderBookDB::processTxn(
     std::shared_ptr<ReadView const> const& ledger,
     const AcceptedLedgerTx& alTx,
-    Json::Value const& jvObj)
+    MultiApiJson const& jvObj)
 {
     std::lock_guard sl(mLock);
 

src/ripple/app/ledger/OrderBookDB.h

@@ -23,6 +23,8 @@
 #include <ripple/app/ledger/AcceptedLedgerTx.h>
 #include <ripple/app/ledger/BookListeners.h>
 #include <ripple/app/main/Application.h>
+#include <ripple/json/MultivarJson.h>
+
 #include <mutex>
 
 namespace ripple {
@@ -63,7 +65,7 @@ class OrderBookDB
     processTxn(
         std::shared_ptr<ReadView const> const& ledger,
         const AcceptedLedgerTx& alTx,
-        Json::Value const& jvObj);
+        MultiApiJson const& jvObj);
 
 private:
     Application& app_;

src/ripple/app/ledger/impl/LedgerToJson.cpp

@@ -19,6 +19,7 @@
 
 #include <ripple/app/ledger/LedgerToJson.h>
 #include <ripple/app/main/Application.h>
+#include <ripple/app/misc/DeliverMax.h>
 #include <ripple/app/misc/TxQ.h>
 #include <ripple/basics/base_uint.h>
 #include <ripple/core/Pg.h>
@@ -123,6 +124,7 @@ fillJsonTx(
     else
     {
         copyFrom(txJson, txn->getJson(JsonOptions::none));
+        RPC::insertDeliverMax(txJson, txnType, fill.context->apiVersion);
         if (stMeta)
         {
             txJson[jss::metaData] = stMeta->getJson(JsonOptions::none);

src/ripple/app/misc/DeliverMax.h

@@ -0,0 +1,53 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of rippled: https://github.com/ripple/rippled
+    Copyright (c) 2023 Ripple Labs Inc.
+
+    Permission to use, copy, modify, and/or distribute this software for any
+    purpose  with  or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL ,  DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#ifndef RIPPLE_APP_MISC_DELIVERMAX_H_INCLUDED
+#define RIPPLE_APP_MISC_DELIVERMAX_H_INCLUDED
+
+#include <ripple/protocol/TxFormats.h>
+
+#include <functional>
+#include <memory>
+
+namespace Json {
+class Value;
+}
+
+namespace ripple {
+
+namespace RPC {
+
+/**
+   Copy `Amount` field to `DeliverMax` field in transaction output JSON.
+   This only applies to Payment transaction type, all others are ignored.
+
+   When apiVersion > 1 will also remove `Amount` field, forcing users
+   to access this value using new `DeliverMax` field only.
+   @{
+ */
+
+void
+insertDeliverMax(Json::Value& tx_json, TxType txnType, unsigned int apiVersion);
+
+/** @} */
+
+}  // namespace RPC
+}  // namespace ripple
+
+#endif