feat: Add delegate filter param's to account_tx RPC

src/rpc/CMakeLists.txt

@@ -21,6 +21,7 @@ target_sources(
         common/MetaProcessors.cpp
         common/impl/APIVersionParser.cpp
         common/impl/HandlerProvider.cpp
+        filters/impl/DelegateTransactionsFilter.cpp
         handlers/AccountChannels.cpp
         handlers/AccountCurrencies.cpp
         handlers/AccountInfo.cpp

src/rpc/RPCHelpers.cpp

@@ -1653,4 +1653,48 @@ toJsonWithBinaryTx(data::TransactionAndMetadata const& txnPlusMeta, std::uint32_
     return obj;
 }
 
+std::optional<DelegateFilter::Role>
+parseDelegateType(boost::json::value const& delegateType)
+{
+    if (not delegateType.is_string())
+        return {};
+
+    auto const& type = delegateType.as_string();
+
+    if (type == JS(authorizer))
+        return DelegateFilter::Role::Authorizer;
+    if (type == JS(actor))
+        return DelegateFilter::Role::Actor;
+
+    return {};
+}
+
+std::optional<DelegateFilter>
+parseDelegateFilter(boost::json::object const& delegateObject)
+{
+    DelegateFilter delegate{};
+    if (!delegateObject.contains(JS(delegate_filter)))
+        return {};
+
+    auto const& filterVal = delegateObject.at(JS(delegate_filter));
+    if (!filterVal.is_string())
+        return {};
+
+    auto const delegateTypeOpt = parseDelegateType(filterVal.as_string());
+    if (!delegateTypeOpt.has_value())
+        return {};
+
+    delegate.delegateType = *delegateTypeOpt;
+    if (delegateObject.contains(JS(counter_party))) {
+        auto const& counterpartyVal = delegateObject.at(JS(counter_party));
+
+        if (!counterpartyVal.is_string())
+            return {};
+
+        delegate.counterParty = counterpartyVal.as_string();
+    }
+
+    return delegate;
+}
+
 }  // namespace rpc

src/rpc/RPCHelpers.hpp

@@ -853,4 +853,22 @@ getDeliveredAmount(
     uint32_t date
 );
 
+/**
+ * @brief Parse the delegate type from a JSON value
+ *
+ * @param delegateType The JSON value containing the delegate type string
+ * @return The parsed delegate type or std::nullopt if the input is invalid or not a string
+ */
+std::optional<DelegateFilter::Role>
+parseDelegateType(boost::json::value const& delegateType);
+
+/**
+ * @brief Parse a delegate filter object from JSON
+ *
+ * @param delegateObject The JSON object containing the delegate filter input from user
+ * @return The constructed DelegateFilter or std::nullopt if parsing fails
+ */
+std::optional<DelegateFilter>
+parseDelegateFilter(boost::json::object const& delegateObject);
+
 }  // namespace rpc

src/rpc/common/Types.hpp

@@ -14,9 +14,9 @@
 
 #include <cstdint>
 #include <expected>
+#include <optional>
 #include <string>
 #include <utility>
-#include <variant>
 
 namespace etl {
 class LoadBalancer;
@@ -175,6 +175,25 @@ struct AccountCursor {
     }
 };
 
+/**
+ * @brief A delegate object used filter account_tx by specific delegate accounts
+ */
+struct DelegateFilter {
+    /**
+     * @brief A delegate type used in delegate filter
+     */
+    enum class Role {
+        Actor, /**< This account is the *active* sender, acting on behalf of another party.
+                * e.g., Account A in "A sends payment to B on behalf of C." */
+
+        Authorizer /**< This account is the *passive* party whose funds are being moved from.
+                    * e.g., Account C in "A sends payment to B on behalf of C." */
+    };
+
+    Role delegateType = Role::Actor;
+    std::optional<std::string> counterParty;
+};
+
 /**
  * @brief Convert an empty output to a JSON object
  *

src/rpc/common/Validators.cpp

@@ -1,6 +1,7 @@
 #include "rpc/common/Validators.hpp"
 
 #include "rpc/Errors.hpp"
+#include "rpc/JS.hpp"
 #include "rpc/RPCHelpers.hpp"
 #include "rpc/common/Types.hpp"
 #include "util/AccountUtils.hpp"
@@ -17,6 +18,7 @@
 #include <xrpl/protocol/LedgerFormats.h>
 #include <xrpl/protocol/Protocol.h>
 #include <xrpl/protocol/UintTypes.h>
+#include <xrpl/protocol/jss.h>
 
 #include <charconv>
 #include <cstdint>
@@ -383,4 +385,34 @@ CustomValidator CustomValidators::authorizeCredentialValidator =
         return MaybeError{};
     }};
 
+CustomValidator CustomValidators::delegateValidator =
+    CustomValidator{[](boost::json::value const& value, std::string_view key) -> MaybeError {
+        if (!value.is_object())
+            return Error{Status{RippledError::RpcInvalidParams, std::string(key) + "NotObject"}};
+
+        auto const& delegate = value.as_object();
+        if (!delegate.contains(JS(delegate_filter))) {
+            return Error{Status{
+                RippledError::RpcInvalidParams, "Field 'delegate_filter' is required but missing."
+            }};
+        }
+
+        if (!parseDelegateType(delegate.at(JS(delegate_filter))).has_value()) {
+            return Error{Status{
+                RippledError::RpcInvalidParams,
+                "Field 'delegate_filter' value must be 'actor' or 'authorizer'."
+            }};
+        }
+
+        if (delegate.contains(JS(counter_party)) &&
+            !accountValidator.verify(delegate, JS(counter_party))) {
+            return Error{Status{
+                RippledError::RpcActMalformed,
+                "Field 'counter_party' value must be a valid account."
+            }};
+        }
+
+        return MaybeError{};
+    }};
+
 }  // namespace rpc::validation

src/rpc/common/Validators.hpp

@@ -593,6 +593,13 @@ struct CustomValidators final {
      * Used by AuthorizeCredentialValidator in deposit_preauth.
      */
     static CustomValidator credentialTypeValidator;
+
+    /**
+     * @brief Provides a validator for validating filtering by delegation.
+     *
+     * Used by account_tx if user wants to filter by delegation.
+     */
+    static CustomValidator delegateValidator;
 };
 
 /**

src/rpc/filters/TransactionFilter.hpp

@@ -0,0 +1,54 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and 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.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "data/Types.hpp"
+
+#include <xrpl/protocol/AccountID.h>
+
+#include <optional>
+
+namespace rpc {
+
+/**
+ * @brief Result of a filter check.
+ */
+struct FilterResult {
+    bool shouldInclude = false;
+    std::optional<xrpl::AccountID> relevantAccount;
+};
+
+/**
+ * @brief Interface for filtering transactions.
+ */
+class TransactionFilter {
+public:
+    virtual ~TransactionFilter() = default;
+
+    /**
+     * @brief Check if a transaction blob matches the filter criteria.
+     * @param txnPlusMeta The transaction and metadata blob from the backend.
+     * @return FilterResult indicating if the txn should be included in the output Json or not
+     */
+    [[nodiscard]] virtual FilterResult
+    check(data::TransactionAndMetadata const& txnPlusMeta) const = 0;
+};
+
+}  // namespace rpc

src/rpc/filters/impl/DelegateTransactionsFilter.cpp

@@ -0,0 +1,85 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and 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 "rpc/filters/impl/DelegateTransactionsFilter.hpp"
+
+#include "data/Types.hpp"
+#include "rpc/common/Types.hpp"
+#include "rpc/filters/TransactionFilter.hpp"
+
+#include <xrpl/protocol/AccountID.h>
+#include <xrpl/protocol/SField.h>
+#include <xrpl/protocol/STTx.h>
+#include <xrpl/protocol/Serializer.h>
+
+#include <optional>
+#include <utility>
+
+namespace rpc {
+
+DelegateTransactionFilter::DelegateTransactionFilter(
+    rpc::DelegateFilter filter,
+    xrpl::AccountID queriedAccount
+)
+    : delegateFilter_(std::move(filter)), queriedAccount_(queriedAccount)
+{
+    if (delegateFilter_.counterParty)
+        counterparty_ = xrpl::parseBase58<xrpl::AccountID>(*delegateFilter_.counterParty);
+}
+
+FilterResult
+DelegateTransactionFilter::check(data::TransactionAndMetadata const& txnPlusMeta) const
+{
+    xrpl::SerialIter sit{txnPlusMeta.transaction.data(), txnPlusMeta.transaction.size()};
+    xrpl::STTx const sttx{sit};
+
+    // The account is always the owner whose funds move; when sfDelegate is present, sfAccount is
+    // the "authorizer" and sfDelegate is the "actor" that signed on its behalf.
+    auto const txAccount = sttx.getAccountID(xrpl::sfAccount);
+
+    std::optional<xrpl::AccountID> txDelegate;
+    if (sttx.isFieldPresent(xrpl::sfDelegate))
+        txDelegate = sttx.getAccountID(xrpl::sfDelegate);
+
+    // Transactions without an sfDelegate field are not delegated; exclude them immediately.
+    if (not txDelegate.has_value())
+        return {.shouldInclude = false, .relevantAccount = std::nullopt};
+
+    // Filter by "authorizer" ie. the queried account is the actor (signer) and the user wants to
+    // find the authorizer (owner) it acted for.
+    if (delegateFilter_.delegateType == rpc::DelegateFilter::Role::Authorizer) {
+        if (*txDelegate == queriedAccount_) {
+            if (!counterparty_ || *counterparty_ == txAccount)
+                return {.shouldInclude = true, .relevantAccount = txAccount};
+        }
+    }
+
+    // Filter by "actor" ie. the queried account is the authorizer (owner) and the user wants to
+    // find the actor (signer) that acted on its behalf.
+    else if (delegateFilter_.delegateType == rpc::DelegateFilter::Role::Actor) {
+        if (txAccount == queriedAccount_) {
+            if (!counterparty_ || *counterparty_ == *txDelegate)
+                return {.shouldInclude = true, .relevantAccount = txDelegate};
+        }
+    }
+
+    return {.shouldInclude = false, .relevantAccount = std::nullopt};
+}
+
+}  // namespace rpc

src/rpc/filters/impl/DelegateTransactionsFilter.hpp

@@ -0,0 +1,54 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and 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.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "data/Types.hpp"
+#include "rpc/common/Types.hpp"
+#include "rpc/filters/TransactionFilter.hpp"
+
+#include <xrpl/protocol/AccountID.h>
+
+#include <optional>
+
+namespace rpc {
+
+/**
+ * @brief Delegate transaction filter to filter txn based on permission delegate
+ */
+class DelegateTransactionFilter : public TransactionFilter {
+public:
+    /**
+     * @brief Construct a new delegate transaction filter
+     * @param filter The filter parameters from the JSON request (role, counterparty string)
+     * @param queriedAccount The account currently being queried in account_tx (input from
+     * account_tx handler)
+     */
+    DelegateTransactionFilter(rpc::DelegateFilter filter, xrpl::AccountID queriedAccount);
+
+    [[nodiscard]] FilterResult
+    check(data::TransactionAndMetadata const& txnPlusMeta) const override;
+
+private:
+    rpc::DelegateFilter delegateFilter_;
+    xrpl::AccountID queriedAccount_;
+    std::optional<xrpl::AccountID> counterparty_;
+};
+
+}  // namespace rpc