APIv2(DeliverMax): add alias for Amount in Payment transactions (XRPL…

…F#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 XRPLF#3484

Fix XRPLF#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:/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:/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