feat: Add delegate filter param's to account_tx RPC

src/data/Types.hpp

@@ -70,6 +70,7 @@ struct TransactionAndMetadata {
     Blob metadata;
     std::uint32_t ledgerSequence = 0;
     std::uint32_t date = 0;
+    std::optional<ripple::AccountID> delegatedAccount;
 
     TransactionAndMetadata() = default;
 

src/data/cassandra/CassandraBackendFamily.hpp

@@ -40,12 +40,18 @@
 #include <cassandra.h>
 #include <fmt/format.h>
 #include <xrpl/basics/Blob.h>
+#include <xrpl/basics/Slice.h>
 #include <xrpl/basics/base_uint.h>
 #include <xrpl/basics/strHex.h>
 #include <xrpl/protocol/AccountID.h>
 #include <xrpl/protocol/Indexes.h>
 #include <xrpl/protocol/LedgerHeader.h>
+#include <xrpl/protocol/PublicKey.h>
+#include <xrpl/protocol/SField.h>
+#include <xrpl/protocol/STTx.h>
+#include <xrpl/protocol/Serializer.h>
 #include <xrpl/protocol/nft.h>
+#include <xrpl/protocol/tokens.h>
 
 #include <algorithm>
 #include <atomic>

src/rpc/CMakeLists.txt

@@ -20,6 +20,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

@@ -1567,4 +1567,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 == "delegator")
+        return DelegateFilter::Role::Delegator;
+    if (type == "delegatee")
+        return DelegateFilter::Role::Delegatee;
+
+    return {};
+}
+
+std::optional<DelegateFilter>
+parseDelegateFilter(boost::json::object const& delegateObject)
+{
+    DelegateFilter delegate{};
+    if (!delegateObject.contains("delegate_filter"))
+        return {};
+
+    auto const& filterVal = delegateObject.at("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("counterparty")) {
+        auto const& counterpartyVal = delegateObject.at("counterparty");
+
+        if (!counterpartyVal.is_string())
+            return {};
+
+        delegate.counterParty = counterpartyVal.as_string();
+    }
+
+    return delegate;
+}
+
 }  // namespace rpc

src/rpc/RPCHelpers.hpp

@@ -861,4 +861,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

@@ -33,9 +33,9 @@
 
 #include <cstdint>
 #include <expected>
+#include <optional>
 #include <string>
 #include <utility>
-#include <variant>
 
 namespace etl {
 class LoadBalancer;
@@ -194,6 +194,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 {
+        Delegatee, /**< 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." */
+
+        Delegator /**< 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;
+    std::optional<std::string> counterParty;
+};
+
 /**
  * @brief Convert an empty output to a JSON object
  *

src/rpc/common/Validators.cpp

@@ -357,4 +357,26 @@ 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::rpcINVALID_PARAMS, std::string(key) + " not object"}};
+
+        auto const& delegate = value.as_object();
+        if (!delegate.contains("delegate_filter"))
+            return Error{Status{RippledError::rpcINVALID_PARAMS, "Field 'delegate_filter' is required but missing."}};
+
+        if (!parseDelegateType(delegate.at("delegate_filter")).has_value())
+            return Error{Status{
+                RippledError::rpcINVALID_PARAMS, "Field 'delegate_filter' value must be 'delegator' or 'delegatee'."
+            }};
+
+        if (delegate.contains("counterparty") && !accountValidator.verify(delegate, "counterparty"))
+            return Error{
+                Status{RippledError::rpcINVALID_PARAMS, "Field 'counterparty' value must be a valid account."}
+            };
+
+        return MaybeError{};
+    }};
+
 }  // namespace rpc::validation

src/rpc/common/Validators.hpp

@@ -592,6 +592,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;
+    std::optional<ripple::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,84 @@
+//------------------------------------------------------------------------------
+/*
+    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 <ripple/basics/Log.h>
+#include <ripple/protocol/SField.h>
+#include <ripple/protocol/STTx.h>
+#include <ripple/protocol/TxFlags.h>
+#include <xrpl/protocol/AccountID.h>
+#include <xrpl/protocol/Serializer.h>
+
+#include <optional>
+#include <utility>
+
+namespace rpc {
+
+DelegateTransactionFilter::DelegateTransactionFilter(rpc::DelegateFilter filter, ripple::AccountID queriedAccount)
+    : delegateFilter_(std::move(filter)), queriedAccount_(queriedAccount)
+{
+    if (delegateFilter_.counterParty)
+        counterparty_ = ripple::parseBase58<ripple::AccountID>(*delegateFilter_.counterParty);
+}
+
+FilterResult
+DelegateTransactionFilter::check(data::TransactionAndMetadata const& txnPlusMeta) const
+{
+    ripple::SerialIter sit{txnPlusMeta.transaction.data(), txnPlusMeta.transaction.size()};
+    ripple::STTx const sttx{sit};
+
+    // The account where the funds are withdrawn is always delegator
+    auto const txAccount = sttx.getAccountID(ripple::sfAccount);
+
+    std::optional<ripple::AccountID> txDelegate;
+    if (sttx.isFieldPresent(ripple::sfDelegate))
+        txDelegate = sttx.getAccountID(ripple::sfDelegate);
+
+    // txn with no delegate filter should return immediately
+    // Note: should already have been checked in handler code before calling this function though
+    if (not txDelegate.has_value())
+        return {.shouldInclude = false, .relevantAccount = std::nullopt};
+
+    // Filter by "Delegator" ie. User wants to find the Owner.
+    // This implies the user must be the Delegatee that acted on someone's behalf.
+    if (delegateFilter_.delegateType == rpc::DelegateFilter::Role::Delegator) {
+        if (*txDelegate == queriedAccount_) {
+            if (!counterparty_ || *counterparty_ == txAccount)
+                return {.shouldInclude = true, .relevantAccount = txAccount};
+        }
+    }
+
+    // Filter by "Delegatee" ie. User wants to find the Signer who acted on behalf of the user.
+    // This implies the user must be the delegator.
+    else if (delegateFilter_.delegateType == rpc::DelegateFilter::Role::Delegatee) {
+        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,53 @@
+//------------------------------------------------------------------------------
+/*
+    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, ripple::AccountID queriedAccount);
+
+    FilterResult
+    check(data::TransactionAndMetadata const& txnPlusMeta) const override;
+
+private:
+    rpc::DelegateFilter delegateFilter_;
+    ripple::AccountID queriedAccount_;
+    std::optional<ripple::AccountID> counterparty_;
+};
+
+}  // namespace rpc