Refactor ledger_entry RPC source code and tests (#5237)

This is a major refactor of LedgerEntry.cpp. It adds a number of helper functions to make the code easier to maintain.

It also splits up the ledger and ledger_entry tests into different files, and cleans up the ledger_entry tests to make them easier to write and maintain.

This refactor also caught a few bugs in some of the other RPC processing, so those are fixed along the way.

Xahau: the Xahau ledger entry parsers (app_loader, cron, emitted_txn, hook, hook_definition, hook_state, import_vlseq, manifest_entry, random, uri_token) are ported to the new helpers; rpcENTRY_NOT_FOUND and rpcUNEXPECTED_LEDGER_TYPE take upstream's codes 98 and 99. A non-string permissioned_domain account now returns malformedAddress, matching upstream after #5344. `maxURITokenURILength` is introduced in Protocol.h and used in URIToken.cpp and the tests (taken from Xahau sync commit 9ff0d3c7c3; no behaviour change). requiredUInt256 reports "hex string" instead of upstream's "Hash256" (sync-branch choice; it only affects the hook_state key/namespace_id error text). The Vault_test.cpp hunk and the Delegate test are dropped because Xahau has neither feature.

include/xrpl/protocol/ErrorCodes.h

@@ -157,7 +157,12 @@ enum error_code_i {
     // Simulate
     rpcTX_SIGNED = 97,
 
-    rpcLAST = rpcTX_SIGNED  // rpcLAST should always equal the last code.
+    // ledger_entry
+    rpcENTRY_NOT_FOUND = 98,
+    rpcUNEXPECTED_LEDGER_TYPE = 99,
+
+    rpcLAST =
+        rpcUNEXPECTED_LEDGER_TYPE  // rpcLAST should always equal the last code.
 };
 
 /** Codes returned in the `warnings` array of certain RPC commands.

include/xrpl/protocol/Protocol.h

@@ -84,6 +84,9 @@ std::uint16_t constexpr maxTransferFee = 50000;
 /** The maximum length of a URI inside an NFT */
 std::size_t constexpr maxTokenURILength = 256;
 
+/** The maximum length of a URI inside an URIToken */
+std::size_t constexpr maxURITokenURILength = 256;
+
 /** The maximum length of a Data element inside a DID */
 std::size_t constexpr maxDIDDocumentLength = 256;
 

include/xrpl/protocol/jss.h

@@ -100,11 +100,15 @@ JSS(isVLEncoded);         // out: RPC server_definitions
                           // matches definitions.json format
 JSS(Invalid);                  //
 JSS(Issuer);                   // in: Credential transactions
+JSS(IssuingChainDoor);         // field.
+JSS(IssuingChainIssue);        // field.
 JSS(InvoiceID);                // field
 JSS(LastLedgerSequence);       // in: TransactionSign; field
 JSS(FirstLedgerSequence);      // in: TransactionSign; field
 JSS(LastUpdateTime);           // field.
 JSS(LimitAmount);              // field.
+JSS(LockingChainDoor);         // field.
+JSS(LockingChainIssue);        // field.
 JSS(NetworkID);                // field.
 JSS(LPTokenOut);               // in: AMM Liquidity Provider deposit tokens
 JSS(LPTokenIn);                // in: AMM Liquidity Provider withdraw tokens

src/libxrpl/json/json_value.cpp

@@ -23,6 +23,8 @@
 #include <xrpl/json/json_writer.h>
 #include <xrpl/json/to_string.h>
 
+#include <cmath>
+
 namespace Json {
 
 const Value Value::null;
@@ -672,7 +674,9 @@ Value::isConvertibleTo(ValueType other) const
                 (other == intValue && value_.real_ >= minInt &&
                  value_.real_ <= maxInt) ||
                 (other == uintValue && value_.real_ >= 0 &&
-                 value_.real_ <= maxUInt) ||
+                 value_.real_ <= maxUInt &&
+                 std::fabs(round(value_.real_) - value_.real_) <
+                     std::numeric_limits<double>::epsilon()) ||
                 other == realValue || other == stringValue ||
                 other == booleanValue;
 

src/libxrpl/protocol/ErrorCodes.cpp

@@ -113,7 +113,10 @@ constexpr static ErrorInfo unorderedErrorInfos[]{
     {rpcLEDGER_MISSING,         "ledgerMissing",        "One or more ledgers in the specified range is missing", 406},
     {rpcORACLE_MALFORMED,       "oracleMalformed",      "Oracle request is malformed.", 400},
     {rpcBAD_CREDENTIALS,        "badCredentials",       "Credentials do not exist, are not accepted, or have expired.", 400},
-    {rpcTX_SIGNED,              "transactionSigned",    "Transaction should not be signed.", 400}};
+    {rpcTX_SIGNED,              "transactionSigned",    "Transaction should not be signed.", 400},
+    {rpcENTRY_NOT_FOUND,        "entryNotFound",        "Entry not found.", 400},
+    {rpcUNEXPECTED_LEDGER_TYPE, "unexpectedLedgerType", "Unexpected ledger type.", 400},
+};
 // clang-format on
 
 // Sort and validate unorderedErrorInfos at compile time.  Should be

src/libxrpl/protocol/STXChainBridge.cpp

@@ -95,12 +95,10 @@ STXChainBridge::STXChainBridge(SField const& name, Json::Value const& v)
     };
     checkExtra(v);
 
-    Json::Value const& lockingChainDoorStr =
-        v[sfLockingChainDoor.getJsonName()];
-    Json::Value const& lockingChainIssue = v[sfLockingChainIssue.getJsonName()];
-    Json::Value const& issuingChainDoorStr =
-        v[sfIssuingChainDoor.getJsonName()];
-    Json::Value const& issuingChainIssue = v[sfIssuingChainIssue.getJsonName()];
+    Json::Value const& lockingChainDoorStr = v[jss::LockingChainDoor];
+    Json::Value const& lockingChainIssue = v[jss::LockingChainIssue];
+    Json::Value const& issuingChainDoorStr = v[jss::IssuingChainDoor];
+    Json::Value const& issuingChainIssue = v[jss::IssuingChainIssue];
 
     if (!lockingChainDoorStr.isString())
     {
@@ -158,10 +156,10 @@ Json::Value
 STXChainBridge::getJson(JsonOptions jo) const
 {
     Json::Value v;
-    v[sfLockingChainDoor.getJsonName()] = lockingChainDoor_.getJson(jo);
-    v[sfLockingChainIssue.getJsonName()] = lockingChainIssue_.getJson(jo);
-    v[sfIssuingChainDoor.getJsonName()] = issuingChainDoor_.getJson(jo);
-    v[sfIssuingChainIssue.getJsonName()] = issuingChainIssue_.getJson(jo);
+    v[jss::LockingChainDoor] = lockingChainDoor_.getJson(jo);
+    v[jss::LockingChainIssue] = lockingChainIssue_.getJson(jo);
+    v[jss::IssuingChainDoor] = issuingChainDoor_.getJson(jo);
+    v[jss::IssuingChainIssue] = issuingChainIssue_.getJson(jo);
     return v;
 }
 

src/test/jtx/impl/xchain_bridge.cpp

@@ -44,10 +44,10 @@ bridge(
     Issue const& issuingChainIssue)
 {
     Json::Value jv;
-    jv[sfLockingChainDoor.getJsonName()] = lockingChainDoor.human();
-    jv[sfLockingChainIssue.getJsonName()] = to_json(lockingChainIssue);
-    jv[sfIssuingChainDoor.getJsonName()] = issuingChainDoor.human();
-    jv[sfIssuingChainIssue.getJsonName()] = to_json(issuingChainIssue);
+    jv[jss::LockingChainDoor] = lockingChainDoor.human();
+    jv[jss::LockingChainIssue] = to_json(lockingChainIssue);
+    jv[jss::IssuingChainDoor] = issuingChainDoor.human();
+    jv[jss::IssuingChainIssue] = to_json(issuingChainIssue);
     return jv;
 }
 
@@ -60,10 +60,10 @@ bridge_rpc(
     Issue const& issuingChainIssue)
 {
     Json::Value jv;
-    jv[sfLockingChainDoor.getJsonName()] = lockingChainDoor.human();
-    jv[sfLockingChainIssue.getJsonName()] = to_json(lockingChainIssue);
-    jv[sfIssuingChainDoor.getJsonName()] = issuingChainDoor.human();
-    jv[sfIssuingChainIssue.getJsonName()] = to_json(issuingChainIssue);
+    jv[jss::LockingChainDoor] = lockingChainDoor.human();
+    jv[jss::LockingChainIssue] = to_json(lockingChainIssue);
+    jv[jss::IssuingChainDoor] = issuingChainDoor.human();
+    jv[jss::IssuingChainIssue] = to_json(issuingChainIssue);
     return jv;
 }
 

src/xrpld/app/tx/detail/URIToken.cpp

@@ -91,7 +91,7 @@ URIToken::preflight(PreflightContext const& ctx)
     {
         auto const uri = ctx.tx.getFieldVL(sfURI);
 
-        if (uri.size() < 1 || uri.size() > 256)
+        if (uri.size() < 1 || uri.size() > maxURITokenURILength)
         {
             JLOG(ctx.j.warn())
                 << "Malformed transaction. URI must be at least 1 "

src/xrpld/rpc/detail/RPCHelpers.cpp

@@ -193,7 +193,7 @@ getAccountObjects(
 
     auto& jvObjects = (jvResult[jss::account_objects] = Json::arrayValue);
 
-    // this is a mutable version of limit, used to seemlessly switch
+    // this is a mutable version of limit, used to seamlessly switch
     // to iterating directory entries when nftokenpages are exhausted
     uint32_t mlimit = limit;
 
@@ -459,7 +459,7 @@ ledgerFromRequest(T& ledger, JsonContext& context)
             indexValue = legacyLedger;
     }
 
-    if (hashValue)
+    if (!hashValue.isNull())
     {
         if (!hashValue.isString())
             return {rpcINVALID_PARAMS, "ledgerHashNotString"};
@@ -470,6 +470,9 @@ ledgerFromRequest(T& ledger, JsonContext& context)
         return getLedger(ledger, ledgerHash, context);
     }
 
+    if (!indexValue.isConvertibleTo(Json::stringValue))
+        return {rpcINVALID_PARAMS, "ledgerIndexMalformed"};
+
     auto const index = indexValue.asString();
 
     if (index == "current" || index.empty())
@@ -481,11 +484,11 @@ ledgerFromRequest(T& ledger, JsonContext& context)
     if (index == "closed")
         return getLedger(ledger, LedgerShortcut::CLOSED, context);
 
-    std::uint32_t iVal;
-    if (beast::lexicalCastChecked(iVal, index))
-        return getLedger(ledger, iVal, context);
+    std::uint32_t val;
+    if (!beast::lexicalCastChecked(val, index))
+        return {rpcINVALID_PARAMS, "ledgerIndexMalformed"};
 
-    return {rpcINVALID_PARAMS, "ledgerIndexMalformed"};
+    return getLedger(ledger, val, context);
 }
 }  // namespace
 
@@ -701,7 +704,7 @@ getLedger(T& ledger, LedgerShortcut shortcut, Context& context)
     return Status::OK;
 }
 
-// Explicit instantiaion of above three functions
+// Explicit instantiation of above three functions
 template Status
 getLedger<>(std::shared_ptr<ReadView const>&, uint32_t, Context&);
 

src/xrpld/rpc/handlers/LedgerEntryHelpers.h

@@ -0,0 +1,299 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of rippled: https://github.com/ripple/rippled
+    Copyright (c) 2012-2025 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.
+*/
+//==============================================================================
+
+#include <xrpld/rpc/detail/RPCHelpers.h>
+
+#include <xrpl/basics/StringUtilities.h>
+#include <xrpl/basics/strHex.h>
+#include <xrpl/beast/core/LexicalCast.h>
+#include <xrpl/json/json_errors.h>
+#include <xrpl/protocol/ErrorCodes.h>
+#include <xrpl/protocol/Indexes.h>
+#include <xrpl/protocol/RPCErr.h>
+#include <xrpl/protocol/STXChainBridge.h>
+#include <xrpl/protocol/jss.h>
+
+#include <functional>
+
+namespace ripple {
+
+namespace LedgerEntryHelpers {
+
+Unexpected<Json::Value>
+missingFieldError(
+    Json::StaticString const field,
+    std::optional<std::string> err = std::nullopt)
+{
+    Json::Value json = Json::objectValue;
+    auto error = RPC::missing_field_message(std::string(field.c_str()));
+    json[jss::error] = err.value_or("malformedRequest");
+    json[jss::error_code] = rpcINVALID_PARAMS;
+    json[jss::error_message] = std::move(error);
+    return Unexpected(json);
+}
+
+Unexpected<Json::Value>
+invalidFieldError(
+    std::string const& err,
+    Json::StaticString const field,
+    std::string const& type)
+{
+    Json::Value json = Json::objectValue;
+    auto error = RPC::expected_field_message(field, type);
+    json[jss::error] = err;
+    json[jss::error_code] = rpcINVALID_PARAMS;
+    json[jss::error_message] = std::move(error);
+    return Unexpected(json);
+}
+
+Unexpected<Json::Value>
+malformedError(std::string const& err, std::string const& message)
+{
+    Json::Value json = Json::objectValue;
+    json[jss::error] = err;
+    json[jss::error_code] = rpcINVALID_PARAMS;
+    json[jss::error_message] = message;
+    return Unexpected(json);
+}
+
+Expected<bool, Json::Value>
+hasRequired(
+    Json::Value const& params,
+    std::initializer_list<Json::StaticString> fields,
+    std::optional<std::string> err = std::nullopt)
+{
+    for (auto const field : fields)
+    {
+        if (!params.isMember(field) || params[field].isNull())
+        {
+            return missingFieldError(field, err);
+        }
+    }
+    return true;
+}
+
+template <class T>
+std::optional<T>
+parse(Json::Value const& param);
+
+template <class T>
+Expected<T, Json::Value>
+required(
+    Json::Value const& params,
+    Json::StaticString const fieldName,
+    std::string const& err,
+    std::string const& expectedType)
+{
+    if (!params.isMember(fieldName) || params[fieldName].isNull())
+    {
+        return missingFieldError(fieldName);
+    }
+    if (auto obj = parse<T>(params[fieldName]))
+    {
+        return *obj;
+    }
+    return invalidFieldError(err, fieldName, expectedType);
+}
+
+template <>
+std::optional<AccountID>
+parse(Json::Value const& param)
+{
+    if (!param.isString())
+        return std::nullopt;
+
+    auto const account = parseBase58<AccountID>(param.asString());
+    if (!account || account->isZero())
+    {
+        return std::nullopt;
+    }
+
+    return account;
+}
+
+Expected<AccountID, Json::Value>
+requiredAccountID(
+    Json::Value const& params,
+    Json::StaticString const fieldName,
+    std::string const& err)
+{
+    return required<AccountID>(params, fieldName, err, "AccountID");
+}
+
+std::optional<Blob>
+parseHexBlob(Json::Value const& param, std::size_t maxLength)
+{
+    if (!param.isString())
+        return std::nullopt;
+
+    auto const blob = strUnHex(param.asString());
+    if (!blob || blob->empty() || blob->size() > maxLength)
+        return std::nullopt;
+
+    return blob;
+}
+
+Expected<Blob, Json::Value>
+requiredHexBlob(
+    Json::Value const& params,
+    Json::StaticString const fieldName,
+    std::size_t maxLength,
+    std::string const& err)
+{
+    if (!params.isMember(fieldName) || params[fieldName].isNull())
+    {
+        return missingFieldError(fieldName);
+    }
+    if (auto blob = parseHexBlob(params[fieldName], maxLength))
+    {
+        return *blob;
+    }
+    return invalidFieldError(err, fieldName, "hex string");
+}
+
+template <>
+std::optional<std::uint32_t>
+parse(Json::Value const& param)
+{
+    if (param.isUInt() || (param.isInt() && param.asInt() >= 0))
+        return param.asUInt();
+
+    if (param.isString())
+    {
+        std::uint32_t v;
+        if (beast::lexicalCastChecked(v, param.asString()))
+            return v;
+    }
+
+    return std::nullopt;
+}
+
+Expected<std::uint32_t, Json::Value>
+requiredUInt32(
+    Json::Value const& params,
+    Json::StaticString const fieldName,
+    std::string const& err)
+{
+    return required<std::uint32_t>(params, fieldName, err, "number");
+}
+
+template <>
+std::optional<uint256>
+parse(Json::Value const& param)
+{
+    uint256 uNodeIndex;
+    if (!param.isString() || !uNodeIndex.parseHex(param.asString()))
+    {
+        return std::nullopt;
+    }
+
+    return uNodeIndex;
+}
+
+Expected<uint256, Json::Value>
+requiredUInt256(
+    Json::Value const& params,
+    Json::StaticString const fieldName,
+    std::string const& err)
+{
+    return required<uint256>(params, fieldName, err, "hex string");
+}
+
+template <>
+std::optional<uint192>
+parse(Json::Value const& param)
+{
+    uint192 field;
+    if (!param.isString() || !field.parseHex(param.asString()))
+    {
+        return std::nullopt;
+    }
+
+    return field;
+}
+
+Expected<uint192, Json::Value>
+requiredUInt192(
+    Json::Value const& params,
+    Json::StaticString const fieldName,
+    std::string const& err)
+{
+    return required<uint192>(params, fieldName, err, "Hash192");
+}
+
+Expected<STXChainBridge, Json::Value>
+parseBridgeFields(Json::Value const& params)
+{
+    if (auto const value = hasRequired(
+            params,
+            {jss::LockingChainDoor,
+             jss::LockingChainIssue,
+             jss::IssuingChainDoor,
+             jss::IssuingChainIssue});
+        !value)
+    {
+        return Unexpected(value.error());
+    }
+
+    auto const lockingChainDoor = requiredAccountID(
+        params, jss::LockingChainDoor, "malformedLockingChainDoor");
+    if (!lockingChainDoor)
+    {
+        return Unexpected(lockingChainDoor.error());
+    }
+
+    auto const issuingChainDoor = requiredAccountID(
+        params, jss::IssuingChainDoor, "malformedIssuingChainDoor");
+    if (!issuingChainDoor)
+    {
+        return Unexpected(issuingChainDoor.error());
+    }
+
+    Issue lockingChainIssue;
+    try
+    {
+        lockingChainIssue = issueFromJson(params[jss::LockingChainIssue]);
+    }
+    catch (std::runtime_error const& ex)
+    {
+        return invalidFieldError(
+            "malformedIssue", jss::LockingChainIssue, "Issue");
+    }
+
+    Issue issuingChainIssue;
+    try
+    {
+        issuingChainIssue = issueFromJson(params[jss::IssuingChainIssue]);
+    }
+    catch (std::runtime_error const& ex)
+    {
+        return invalidFieldError(
+            "malformedIssue", jss::IssuingChainIssue, "Issue");
+    }
+
+    return STXChainBridge(
+        *lockingChainDoor,
+        lockingChainIssue,
+        *issuingChainDoor,
+        issuingChainIssue);
+}
+
+}  // namespace LedgerEntryHelpers
+
+}  // namespace ripple