feat: simulate RPC to dry-run a tx (XLS-69d)

API-CHANGELOG.md

@@ -85,34 +85,37 @@ The `network_id` field was added in the `server_info` response in version 1.5.0
 
 ## XRP Ledger server version 2.4.0
 
-### Addition in 2.4
+### Additions in 2.4
 
+- `simulate`: A new RPC that executes a dry run of a transaction submission without actually submitting it to the network for inclusion.
 - `ledger_entry`: `state` is added an alias for `ripple_state`.
 
 ## XRP Ledger server version 2.3.0
 
-### Breaking change in 2.3
+### BREAKING CHANGES
 
-- `book_changes`: If the requested ledger version is not available on this node, a `ledgerNotFound` error is returned and the node does not attempt to acquire the ledger from the p2p network (as with other non-admin RPCs).
+- `book_changes`: If the requested ledger version is not available on this node, a `ledgerNotFound` error is returned and the node does not attempt to acquire the ledger from the p2p network (as with other non-admin RPCs). Admins can still attempt to retrieve old ledgers with the `ledger_request` RPC.
 
-Admins can still attempt to retrieve old ledgers with the `ledger_request` RPC.
+### Additions
 
-### Addition in 2.3
+Additions are intended to be non-breaking (because they are purely additive).
 
 - `book_changes`: Returns a `validated` field in its response, which was missing in prior versions.
 
-The following additions are non-breaking (because they are purely additive).
-
-- `server_definitions`: A new RPC that generates a `definitions.json`-like output that can be used in XRPL libraries.
-- In `Payment` transactions, `DeliverMax` has been added. This is a replacement for the `Amount` field, which should not be used. Typically, the `delivered_amount` (in transaction metadata) should be used. To ease the transition, `DeliverMax` is present regardless of API version, since adding a field is non-breaking.
-- API version 2 has been moved from beta to supported, meaning that it is generally available (regardless of the `beta_rpc_api` setting).
-
 ## XRP Ledger server version 2.2.0
 
 The following is a non-breaking addition to the API.
 
 - The `feature` method now has a non-admin mode for users. (It was previously only available to admin connections.) The method returns an updated list of amendments, including their names and other information. ([#4781](https://github.com/XRPLF/rippled/pull/4781))
 
+## XRP Ledger server version 2.0.0
+
+The following additions are non-breaking (because they are purely additive).
+
+- `server_definitions`: A new RPC that generates a `definitions.json`-like output that can be used in XRPL libraries.
+- In `Payment` transactions, `DeliverMax` has been added. This is a replacement for the `Amount` field, which should not be used. Typically, the `delivered_amount` (in transaction metadata) should be used. To ease the transition, `DeliverMax` is present regardless of API version, since adding a field is non-breaking.
+- API version 2 has been moved from beta to supported, meaning that it is generally available (regardless of the `beta_rpc_api` setting).
+
 ## XRP Ledger server version 1.12.0
 
 [Version 1.12.0](https://github.com/XRPLF/rippled/releases/tag/1.12.0) was released on Sep 6, 2023. The following additions are non-breaking (because they are purely additive).
@@ -155,7 +158,7 @@ The following is a non-breaking addition to the API.
 
 [Version 1.11.0](https://github.com/XRPLF/rippled/releases/tag/1.11.0) was released on Jun 20, 2023.
 
-### Breaking changes in 1.11
+### Breaking changes
 
 - Added the ability to mark amendments as obsolete. For the `feature` admin API, there is a new possible value for the `vetoed` field. (https://github.com/XRPLF/rippled/pull/4291)
   - The value of `vetoed` can now be `true`, `false`, or `"Obsolete"`.
@@ -174,7 +177,7 @@ The following is a non-breaking addition to the API.
     - `telREQUIRES_NETWORK_ID`: a `NetworkID` is required, but is not present. Add the field to the transaction, and try again.
     - `telWRONG_NETWORK`: a `NetworkID` is specified, but it is for a different network. Submit the transaction to a different server which is connected to the correct network.
 
-### Additions and bug fixes in 1.11
+### Additions and bug fixes
 
 - Added `nftoken_id`, `nftoken_ids` and `offer_id` meta fields into NFT `tx` and `account_tx` responses. (https://github.com/XRPLF/rippled/pull/4447)
 - Added an `account_flags` object to the `account_info` method response. (https://github.com/XRPLF/rippled/pull/4459)
@@ -186,7 +189,7 @@ The following is a non-breaking addition to the API.
 [Version 1.10.0](https://github.com/XRPLF/rippled/releases/tag/1.10.0)
 was released on Mar 14, 2023.
 
-### Breaking changes in 1.10
+### Breaking changes
 
 - If the `XRPFees` feature is enabled, the `fee_ref` field will be
   removed from the [ledger subscription stream](https://xrpl.org/subscribe.html#ledger-stream), because it will no longer

include/xrpl/protocol/ErrorCodes.h

@@ -151,7 +151,10 @@ enum error_code_i {
     // deposit_authorized + credentials
     rpcBAD_CREDENTIALS = 95,
 
-    rpcLAST = rpcBAD_CREDENTIALS  // rpcLAST should always equal the last code.
+    // Simulate
+    rpcTX_SIGNED = 96,
+
+    rpcLAST = rpcTX_SIGNED  // rpcLAST should always equal the last code.
 };
 
 /** Codes returned in the `warnings` array of certain RPC commands.

include/xrpl/protocol/jss.h

@@ -107,7 +107,9 @@ JSS(SettleDelay);                        // in: TransactionSign
 JSS(SendMax);                            // in: TransactionSign
 JSS(Sequence);                           // in/out: TransactionSign; field.
 JSS(SetFlag);                            // field.
+JSS(Signer);                             // field.
 JSS(SignerList);                         // ledger type.
+JSS(Signers);                            // field.
 JSS(SigningPubKey);                      // field.
 JSS(Subject);                            // in: Credential transactions
 JSS(TakerGets);                          // field.

src/libxrpl/protocol/ErrorCodes.cpp

@@ -109,7 +109,8 @@ constexpr static ErrorInfo unorderedErrorInfos[]{
     {rpcTXN_NOT_FOUND,          "txnNotFound",          "Transaction not found.", 404},
     {rpcUNKNOWN_COMMAND,        "unknownCmd",           "Unknown method.", 405},
     {rpcORACLE_MALFORMED,       "oracleMalformed",      "Oracle request is malformed.", 400},
-    {rpcBAD_CREDENTIALS,        "badCredentials",       "Credentials do not exist, are not accepted, or have expired.", 400}};
+    {rpcBAD_CREDENTIALS,        "badCredentials",       "Credentials do not exist, are not accepted, or have expired.", 400},
+    {rpcTX_SIGNED,              "transactionSigned",    "Transaction should not be signed.", 400}};
 // clang-format on
 
 // Sort and validate unorderedErrorInfos at compile time.  Should be

src/libxrpl/protocol/InnerObjectFormats.cpp

@@ -36,7 +36,7 @@ InnerObjectFormats::InnerObjectFormats()
             {sfWalletLocator, soeOPTIONAL},
         });
 
-    add(sfSigner.jsonName.c_str(),
+    add(sfSigner.jsonName,
         sfSigner.getCode(),
         {
             {sfAccount, soeREQUIRED},

src/test/app/PseudoTx_test.cpp

@@ -92,8 +92,8 @@ struct PseudoTx_test : public beast::unit_test::suite
                 [&](OpenView& view, beast::Journal j) {
                     auto const result =
                         ripple::apply(env.app(), view, stx, tapNONE, j);
-                    BEAST_EXPECT(!result.second && result.first == temINVALID);
-                    return result.second;
+                    BEAST_EXPECT(!result.applied && result.ter == temINVALID);
+                    return result.applied;
                 });
         }
     }

src/test/app/Regression_test.cpp

@@ -76,8 +76,8 @@ struct Regression_test : public beast::unit_test::suite
 
             auto const result =
                 ripple::apply(env.app(), accum, *jt.stx, tapNONE, env.journal);
-            BEAST_EXPECT(result.first == tesSUCCESS);
-            BEAST_EXPECT(result.second);
+            BEAST_EXPECT(result.ter == tesSUCCESS);
+            BEAST_EXPECT(result.applied);
 
             accum.apply(*next);
         }
@@ -100,8 +100,8 @@ struct Regression_test : public beast::unit_test::suite
 
             auto const result =
                 ripple::apply(env.app(), accum, *jt.stx, tapNONE, env.journal);
-            BEAST_EXPECT(result.first == tecINSUFF_FEE);
-            BEAST_EXPECT(result.second);
+            BEAST_EXPECT(result.ter == tecINSUFF_FEE);
+            BEAST_EXPECT(result.applied);
 
             accum.apply(*next);
         }

src/test/app/TxQ_test.cpp

@@ -1062,11 +1062,10 @@ class TxQPosNegFlows_test : public beast::unit_test::suite
 
             env.app().openLedger().modify(
                 [&](OpenView& view, beast::Journal j) {
-                    // No need to initialize, since it's about to get set
-                    bool didApply;
-                    std::tie(parsed.ter, didApply) = ripple::apply(
+                    auto const result = ripple::apply(
                         env.app(), view, *jt.stx, tapNONE, env.journal);
-                    return didApply;
+                    parsed.ter = result.ter;
+                    return result.applied;
                 });
             env.postconditions(jt, parsed);
         }
@@ -4174,8 +4173,8 @@ class TxQPosNegFlows_test : public beast::unit_test::suite
                 env.jt(noop(alice), seq(aliceSeq), openLedgerFee(env));
             auto const result =
                 ripple::apply(env.app(), view, *tx.stx, tapUNLIMITED, j);
-            BEAST_EXPECT(result.first == tesSUCCESS && result.second);
-            return result.second;
+            BEAST_EXPECT(result.ter == tesSUCCESS && result.applied);
+            return result.applied;
         });
         // the queued transaction is still there
         checkMetrics(__LINE__, env, 1, std::nullopt, 5, 3, 256);
@@ -4246,8 +4245,8 @@ class TxQPosNegFlows_test : public beast::unit_test::suite
                 noop(alice), ticket::use(tktSeq0 + 1), openLedgerFee(env));
             auto const result =
                 ripple::apply(env.app(), view, *tx.stx, tapUNLIMITED, j);
-            BEAST_EXPECT(result.first == tesSUCCESS && result.second);
-            return result.second;
+            BEAST_EXPECT(result.ter == tesSUCCESS && result.applied);
+            return result.applied;
         });
         // the queued transaction is still there
         checkMetrics(__LINE__, env, 1, std::nullopt, 5, 3, 256);

src/test/consensus/NegativeUNL_test.cpp

@@ -1922,11 +1922,12 @@ negUnlSizeTest(
 bool
 applyAndTestResult(jtx::Env& env, OpenView& view, STTx const& tx, bool pass)
 {
-    auto res = apply(env.app(), view, tx, ApplyFlags::tapNONE, env.journal);
+    auto const res =
+        apply(env.app(), view, tx, ApplyFlags::tapNONE, env.journal);
     if (pass)
-        return res.first == tesSUCCESS;
+        return res.ter == tesSUCCESS;
     else
-        return res.first == tefFAILURE || res.first == temDISABLED;
+        return res.ter == tefFAILURE || res.ter == temDISABLED;
 }
 
 bool

src/test/rpc/JSONRPC_test.cpp

@@ -2160,6 +2160,31 @@ class JSONRPC_test : public beast::unit_test::suite
             BEAST_EXPECT(RPC::contains_error(result));
             BEAST_EXPECT(!req[jss::tx_json].isMember(jss::Fee));
         }
+
+        {
+            // transaction with a higher base fee
+            Json::Value req;
+            test::jtx::Account const alice("alice");
+            Json::Reader().parse(
+                "{ \"tx_json\" : { \"TransactionType\": \"AccountDelete\", "
+                "\"Account\": \"" +
+                    env.master.human() + "\", \"Destination\": \"" +
+                    alice.human() + "\" } } ",
+                req);
+            Json::Value result = checkFee(
+                req,
+                Role::ADMIN,
+                true,
+                env.app().config(),
+                feeTrack,
+                env.app().getTxQ(),
+                env.app());
+
+            BEAST_EXPECT(!RPC::contains_error(result));
+            BEAST_EXPECT(
+                req[jss::tx_json].isMember(jss::Fee) &&
+                req[jss::tx_json][jss::Fee] == 50000000);
+        }
     }
 
     void