Merge branch 'develop' into nft-reserve

API-CHANGELOG.md

@@ -134,6 +134,13 @@ Currently (prior to the release of 2.0), it is available as a "beta" version, me
 
 Since `api_version` 2 is in "beta", breaking changes to V2 can currently be made at any time.
 
+#### Removed methods
+
+In API version 2, the following methods are no longer available:
+
+- `tx_history` - Instead, use other methods such as `account_tx` or `ledger` with the `transactions` field set to `true`.
+- `ledger_header` - Instead, use the `ledger` method.
+
 #### Modifications to account_info response in V2
 
 - `signer_lists` is returned in the root of the response. Previously, in API version 1, it was nested under `account_data`. (https://github.com/XRPLF/rippled/pull/3770)
@@ -158,6 +165,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
@@ -1059,6 +1062,7 @@ if (tests)
     src/test/rpc/KeyGeneration_test.cpp
     src/test/rpc/LedgerClosed_test.cpp
     src/test/rpc/LedgerData_test.cpp
+    src/test/rpc/LedgerHeader_test.cpp
     src/test/rpc/LedgerRPC_test.cpp
     src/test/rpc/LedgerRequestRPC_test.cpp
     src/test/rpc/ManifestRPC_test.cpp
@@ -1082,6 +1086,7 @@ if (tests)
     src/test/rpc/ValidatorInfo_test.cpp
     src/test/rpc/ValidatorRPC_test.cpp
     src/test/rpc/Version_test.cpp
+    src/test/rpc/Handler_test.cpp
     #[===============================[
        test sources:
          subdir: server

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

src/ripple/app/misc/FeeEscalation.md

@@ -190,11 +190,27 @@ lower) fee to get into the same position as a reference transaction.
 
 ### Consensus Health
 
-For consensus to be considered healthy, the consensus process must take
-less than 5 seconds. This time limit was chosen based on observed past
-behavior of the network. Note that this is not necessarily the time between
-ledger closings, as consensus usually starts some amount of time after
-a ledger opens.
+For consensus to be considered healthy, the peers on the network
+should largely remain in sync with one another. It is particularly
+important for the validators to remain in sync, because that is required
+for participation in consensus. However, the network tolerates some
+validators being out of sync.  Fundamentally, network health is a
+function of validators reaching consensus on sets of recently submitted
+transactions.
+
+Another factor to consider is
+the duration of the consensus process itself. This generally takes
+under 5 seconds on the main network under low volume. This is based on
+historical observations. However factors such as transaction volume
+can increase consensus duration. This is because rippled performs
+more work as transaction volume increases. Under sufficient load this
+tends to increase consensus duration. It's possible that relatively high
+consensus duration indicates a problem, but it is not appropriate to
+conclude so without investigation. The upper limit for consensus
+duration should be roughly 20 seconds. That is far above the normal.
+If the network takes this long to close ledgers, then it is almost
+certain that there is a problem with the network. This circumstance
+often coincides with new ledgers with zero transactions.
 
 ### Other Constants