Merge pull request #447 from stellar/txEndpointForce

marta-lokhova · web-flow · commit bb195c49dda3 · 2026-02-25T12:29:32.000-08:00
Add `force` flag to tx endpoint
diff --git a/docs/software/commands.md b/docs/software/commands.md
@@ -364,6 +364,12 @@ Most commands return their results in JSON format.
         The network is under high load and the fee is too low.
     * "FILTERED" - transaction rejected because it contains an operation type that Stellar Core filters out. See Stellar Core configuration `EXCLUDE_TRANSACTIONS_CONTAINING_OPERATION_TYPE` for more details.
 
+  Optional parameters:
+    * `force=true` - bypasses banned account filtering (see `banaccounts`),
+      allowing the transaction into the mempool even if its source account or
+      fee source is on the ban list. Other filtering (operation type, Soroban
+      key filtering) still applies. Example: `tx?blob=Base64&force=true`
+
 * **upgrades**
   * `upgrades?mode=get`<br>
     Retrieves the currently configured upgrade settings.<br>
diff --git a/src/herder/Herder.h b/src/herder/Herder.h
@@ -139,10 +139,11 @@ class Herder
     // generator, and therefore can skip certain expensive validity checks
     virtual TransactionQueue::AddResult
     recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf,
-                    bool isLoadgenTx = false) = 0;
+                    bool force = false, bool isLoadgenTx = false) = 0;
 #else
     virtual TransactionQueue::AddResult
-    recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf) = 0;
+    recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf,
+                    bool force = false) = 0;
 #endif
     virtual void peerDoesntHave(stellar::MessageType type,
                                 uint256 const& itemID, Peer::pointer peer) = 0;
diff --git a/src/herder/HerderImpl.cpp b/src/herder/HerderImpl.cpp
@@ -612,7 +612,8 @@ HerderImpl::emitEnvelope(SCPEnvelope const& envelope)
 }
 
 TransactionQueue::AddResult
-HerderImpl::recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf
+HerderImpl::recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf,
+                            bool force
 #ifdef BUILD_TESTS
                             ,
                             bool isLoadgenTx
@@ -644,7 +645,7 @@ HerderImpl::recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf
     }
     else if (!tx->isSoroban())
     {
-        result = mTransactionQueue.tryAdd(tx, submittedFromSelf
+        result = mTransactionQueue.tryAdd(tx, submittedFromSelf, force
 #ifdef BUILD_TESTS
                                           ,
                                           isLoadgenTx
@@ -653,7 +654,7 @@ HerderImpl::recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf
     }
     else if (mSorobanTransactionQueue)
     {
-        result = mSorobanTransactionQueue->tryAdd(tx, submittedFromSelf
+        result = mSorobanTransactionQueue->tryAdd(tx, submittedFromSelf, force
 #ifdef BUILD_TESTS
                                                   ,
                                                   isLoadgenTx
diff --git a/src/herder/HerderImpl.h b/src/herder/HerderImpl.h
@@ -101,11 +101,11 @@ class HerderImpl : public Herder
 #ifdef BUILD_TESTS
     TransactionQueue::AddResult
     recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf,
-                    bool isLoadgenTx = false) override;
+                    bool force = false, bool isLoadgenTx = false) override;
 #else
-    TransactionQueue::AddResult
-    recvTransaction(TransactionFrameBasePtr tx,
-                    bool submittedFromSelf) override;
+    TransactionQueue::AddResult recvTransaction(TransactionFrameBasePtr tx,
+                                                bool submittedFromSelf,
+                                                bool force = false) override;
 #endif
 
     EnvelopeStatus recvSCPEnvelope(SCPEnvelope const& envelope) override;
diff --git a/src/herder/TransactionQueue.cpp b/src/herder/TransactionQueue.cpp
@@ -315,7 +315,8 @@ TransactionQueue::sourceAccountPending(AccountID const& accountID) const
 TransactionQueue::AddResult
 TransactionQueue::canAdd(
     TransactionFrameBasePtr tx, AccountStates::iterator& stateIter,
-    std::vector<std::pair<TransactionFrameBasePtr, bool>>& txsToEvict
+    std::vector<std::pair<TransactionFrameBasePtr, bool>>& txsToEvict,
+    bool force
 #ifdef BUILD_TESTS
     ,
     bool isLoadgenTx
@@ -342,7 +343,7 @@ TransactionQueue::canAdd(
         mQueueMetrics->mTxsFilteredDueToFootprintKeys.inc();
         return AddResult(TransactionQueue::AddResultCode::ADD_STATUS_FILTERED);
     }
-    if (!tx->validateAccountFilterForFlooding(mFilteredAccounts))
+    if (!force && !tx->validateAccountFilterForFlooding(mFilteredAccounts))
     {
         mQueueMetrics->mTxsFilteredDueToAccountKeys.inc();
         return AddResult(TransactionQueue::AddResultCode::ADD_STATUS_FILTERED);
@@ -669,7 +670,8 @@ TransactionQueue::findAllAssetPairsInvolvedInPaymentLoops(
 }
 
 TransactionQueue::AddResult
-TransactionQueue::tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf
+TransactionQueue::tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf,
+                         bool force
 #ifdef BUILD_TESTS
                          ,
                          bool isLoadgenTx
@@ -687,7 +689,7 @@ TransactionQueue::tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf
     AccountStates::iterator stateIter;
 
     std::vector<std::pair<TransactionFrameBasePtr, bool>> txsToEvict;
-    auto res = canAdd(tx, stateIter, txsToEvict
+    auto res = canAdd(tx, stateIter, txsToEvict, force
 #ifdef BUILD_TESTS
                       ,
                       isLoadgenTx
diff --git a/src/herder/TransactionQueue.h b/src/herder/TransactionQueue.h
@@ -138,9 +138,10 @@ class TransactionQueue
 
 #ifdef BUILD_TESTS
     AddResult tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf,
-                     bool isLoadgenTx = false);
+                     bool force = false, bool isLoadgenTx = false);
 #else
-    AddResult tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf);
+    AddResult tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf,
+                     bool force = false);
 #endif
     void removeApplied(Transactions const& txs);
     // Ban transactions that are no longer valid or have insufficient fee;
@@ -274,11 +275,12 @@ class TransactionQueue
     TransactionQueue::AddResult
     canAdd(TransactionFrameBasePtr tx, AccountStates::iterator& stateIter,
            std::vector<std::pair<TransactionFrameBasePtr, bool>>& txsToEvict,
-           bool isLoadgenTx = false);
+           bool force = false, bool isLoadgenTx = false);
 #else
     TransactionQueue::AddResult
     canAdd(TransactionFrameBasePtr tx, AccountStates::iterator& stateIter,
-           std::vector<std::pair<TransactionFrameBasePtr, bool>>& txsToEvict);
+           std::vector<std::pair<TransactionFrameBasePtr, bool>>& txsToEvict,
+           bool force = false);
 #endif
 
     void releaseFeeMaybeEraseAccountState(TransactionFrameBasePtr tx);
diff --git a/src/main/CommandHandler.cpp b/src/main/CommandHandler.cpp
@@ -1145,6 +1145,7 @@ CommandHandler::tx(std::string const& params, std::string& retStr)
     std::map<std::string, std::string> paramMap;
     http::server::server::parseParams(params, paramMap);
     std::string blob = paramMap["blob"];
+    bool force = paramMap["force"] == "true";
 
     if (!blob.empty())
     {
@@ -1168,7 +1169,7 @@ CommandHandler::tx(std::string const& params, std::string& retStr)
         {
             // Add it to our current set and make sure it is valid.
             auto addResult =
-                mApp.getHerder().recvTransaction(transaction, true);
+                mApp.getHerder().recvTransaction(transaction, true, force);
 
             root["status"] = TX_STATUS_STRING[static_cast<int>(addResult.code)];
             if (addResult.code ==
diff --git a/src/main/test/BannedAccountsPersistorTests.cpp b/src/main/test/BannedAccountsPersistorTests.cpp
@@ -158,6 +158,64 @@ TEST_CASE("FILTERED_G_ADDRESSES migration", "[banaccounts]")
 
 TEST_CASE("banaccounts HTTP command with persistence", "[banaccounts]")
 {
+    SECTION("force flag bypasses banned account filtering")
+    {
+        VirtualClock clock;
+        auto cfg = getTestConfig();
+        cfg.FILTERED_G_ADDRESSES = {};
+        Application::pointer app = createTestApplication(clock, cfg);
+
+        auto root = app->getRoot();
+        auto srcKey = SecretKey::pseudoRandomForTesting();
+        auto src = root->create(srcKey, 1000000000);
+
+        // Ban the source account
+        auto addr = KeyUtils::toStrKey(srcKey.getPublicKey());
+        app->getCommandHandler().manualCmd("banaccounts?accountids=" + addr);
+
+        auto acc = getAccount("forceAcc");
+        auto tx = src.tx({createAccount(acc.getPublicKey(), 1)});
+
+        // Without force: filtered
+        REQUIRE(
+            app->getHerder().recvTransaction(tx, false, /*force=*/false).code ==
+            TransactionQueue::AddResultCode::ADD_STATUS_FILTERED);
+
+        // With force: bypasses account filter
+        REQUIRE(
+            app->getHerder().recvTransaction(tx, false, /*force=*/true).code ==
+            TransactionQueue::AddResultCode::ADD_STATUS_PENDING);
+    }
+
+    SECTION("force flag bypasses ban for fee-bump with banned fee source")
+    {
+        VirtualClock clock;
+        auto cfg = getTestConfig();
+        cfg.FILTERED_G_ADDRESSES = {};
+        Application::pointer app = createTestApplication(clock, cfg);
+
+        auto root = app->getRoot();
+        auto filteredKey = SecretKey::pseudoRandomForTesting();
+        auto feeSourceAcct = root->create(filteredKey, 1000000000);
+
+        // Ban the fee source account
+        auto addr = KeyUtils::toStrKey(filteredKey.getPublicKey());
+        app->getCommandHandler().manualCmd("banaccounts?accountids=" + addr);
+
+        auto innerTx = root->tx({payment(root->getPublicKey(), 1)});
+        auto fb = feeBump(*app, feeSourceAcct, innerTx, 200);
+
+        // Without force: filtered
+        REQUIRE(
+            app->getHerder().recvTransaction(fb, false, /*force=*/false).code ==
+            TransactionQueue::AddResultCode::ADD_STATUS_FILTERED);
+
+        // With force: bypasses account filter
+        REQUIRE(
+            app->getHerder().recvTransaction(fb, false, /*force=*/true).code ==
+            TransactionQueue::AddResultCode::ADD_STATUS_PENDING);
+    }
+
     SECTION("ban via command persists and filters transactions")
     {
         VirtualClock clock;
@@ -178,8 +236,9 @@ TEST_CASE("banaccounts HTTP command with persistence", "[banaccounts]")
         // Transaction from the banned source should be filtered
         auto acc = getAccount("acc");
         auto tx = src.tx({createAccount(acc.getPublicKey(), 1)});
-        REQUIRE(app->getHerder().recvTransaction(tx, false).code ==
-                TransactionQueue::AddResultCode::ADD_STATUS_FILTERED);
+        REQUIRE(
+            app->getHerder().recvTransaction(tx, false, /*force=*/false).code ==
+            TransactionQueue::AddResultCode::ADD_STATUS_FILTERED);
 
         // Verify persisted
         REQUIRE(app->getBannedAccountsPersistor().getBannedAccounts().size() ==
diff --git a/src/main/test/CommandHandlerTests.cpp b/src/main/test/CommandHandlerTests.cpp
@@ -2,6 +2,7 @@
 // under the Apache License, Version 2.0. See the COPYING file at the root
 // of this distribution or at http://www.apache.org/licenses/LICENSE-2.0
 
+#include "crypto/KeyUtils.h"
 #include "ledger/LedgerTxn.h"
 #include "ledger/test/LedgerTestUtils.h"
 #include "main/Application.h"
@@ -603,3 +604,41 @@ TEST_CASE("toggleoverlayonlymode", "[commandhandler]")
         REQUIRE(root["overlay_only_mode"].asBool() == expectedMode);
     }
 }
+
+TEST_CASE("tx force flag bypasses banned account filter", "[commandhandler]")
+{
+    VirtualClock clock;
+    auto cfg = getTestConfig();
+    cfg.FILTERED_G_ADDRESSES = {};
+    auto app = createTestApplication(clock, cfg);
+    auto& ch = app->getCommandHandler();
+
+    closeLedgerOn(*app, 2, 1, 1, 2017);
+
+    auto root = app->getRoot();
+    auto srcKey = SecretKey::pseudoRandomForTesting();
+    auto src = root->create(srcKey, 1000000000);
+
+    // Ban the source account
+    auto addr = KeyUtils::toStrKey(srcKey.getPublicKey());
+    ch.manualCmd("banaccounts?accountids=" + addr);
+
+    // Build a valid transaction from the banned account
+    auto acc = getAccount("forceTestAcc");
+    auto tx = src.tx({createAccount(acc.getPublicKey(), 1)});
+    auto blob = decoder::encode_b64(xdr::xdr_to_opaque(tx->getEnvelope()));
+
+    SECTION("without force flag, tx is filtered")
+    {
+        std::string ret;
+        ch.tx("?blob=" + blob, ret);
+        REQUIRE(ret.find("FILTERED") != std::string::npos);
+    }
+
+    SECTION("with force=true, tx bypasses account ban")
+    {
+        std::string ret;
+        ch.tx("?blob=" + blob + "&force=true", ret);
+        REQUIRE(ret.find("PENDING") != std::string::npos);
+    }
+}
diff --git a/src/simulation/LoadGenerator.cpp b/src/simulation/LoadGenerator.cpp
@@ -1418,8 +1418,8 @@ LoadGenerator::execute(TransactionFrameBasePtr txf, LoadGenMode mode,
 
     // Skip certain checks for pregenerated transactions
     bool isPregeneratedTx = (mode == LoadGenMode::PAY_PREGENERATED);
-    auto addResult =
-        mApp.getHerder().recvTransaction(txf, true, isPregeneratedTx);
+    auto addResult = mApp.getHerder().recvTransaction(
+        txf, true, /*force=*/false, /*isLoadgenTx=*/isPregeneratedTx);
     if (addResult.code != TransactionQueue::AddResultCode::ADD_STATUS_PENDING)
     {
 

Original file line number	Diff line number	Diff line change
`@@ -612,7 +612,8 @@ HerderImpl::emitEnvelope(SCPEnvelope const& envelope)`
`612`	`612`	`}`
`613`	`613`
`614`	`614`	`TransactionQueue::AddResult`
`615`		`-HerderImpl::recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf`
	`615`	`+HerderImpl::recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf,`
	`616`	`+ bool force`
`616`	`617`	`#ifdef BUILD_TESTS`
`617`	`618`	`,`
`618`	`619`	`bool isLoadgenTx`
`@@ -644,7 +645,7 @@ HerderImpl::recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf`
`644`	`645`	`}`
`645`	`646`	`else if (!tx->isSoroban())`
`646`	`647`	`{`
`647`		`- result = mTransactionQueue.tryAdd(tx, submittedFromSelf`
	`648`	`+ result = mTransactionQueue.tryAdd(tx, submittedFromSelf, force`
`648`	`649`	`#ifdef BUILD_TESTS`
`649`	`650`	`,`
`650`	`651`	`isLoadgenTx`
`@@ -653,7 +654,7 @@ HerderImpl::recvTransaction(TransactionFrameBasePtr tx, bool submittedFromSelf`
`653`	`654`	`}`
`654`	`655`	`else if (mSorobanTransactionQueue)`
`655`	`656`	`{`
`656`		`- result = mSorobanTransactionQueue->tryAdd(tx, submittedFromSelf`
	`657`	`+ result = mSorobanTransactionQueue->tryAdd(tx, submittedFromSelf, force`
`657`	`658`	`#ifdef BUILD_TESTS`
`658`	`659`	`,`
`659`	`660`	`isLoadgenTx`
Original file line number	Diff line number	Diff line change
`@@ -315,7 +315,8 @@ TransactionQueue::sourceAccountPending(AccountID const& accountID) const`
`315`	`315`	`TransactionQueue::AddResult`
`316`	`316`	`TransactionQueue::canAdd(`
`317`	`317`	`TransactionFrameBasePtr tx, AccountStates::iterator& stateIter,`
`318`		`- std::vector<std::pair<TransactionFrameBasePtr, bool>>& txsToEvict`
	`318`	`+ std::vector<std::pair<TransactionFrameBasePtr, bool>>& txsToEvict,`
	`319`	`+ bool force`
`319`	`320`	`#ifdef BUILD_TESTS`
`320`	`321`	`,`
`321`	`322`	`bool isLoadgenTx`
`@@ -342,7 +343,7 @@ TransactionQueue::canAdd(`
`342`	`343`	`mQueueMetrics->mTxsFilteredDueToFootprintKeys.inc();`
`343`	`344`	`return AddResult(TransactionQueue::AddResultCode::ADD_STATUS_FILTERED);`
`344`	`345`	`}`
`345`		`- if (!tx->validateAccountFilterForFlooding(mFilteredAccounts))`
	`346`	`+ if (!force && !tx->validateAccountFilterForFlooding(mFilteredAccounts))`
`346`	`347`	`{`
`347`	`348`	`mQueueMetrics->mTxsFilteredDueToAccountKeys.inc();`
`348`	`349`	`return AddResult(TransactionQueue::AddResultCode::ADD_STATUS_FILTERED);`
`@@ -669,7 +670,8 @@ TransactionQueue::findAllAssetPairsInvolvedInPaymentLoops(`
`669`	`670`	`}`
`670`	`671`
`671`	`672`	`TransactionQueue::AddResult`
`672`		`-TransactionQueue::tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf`
	`673`	`+TransactionQueue::tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf,`
	`674`	`+ bool force`
`673`	`675`	`#ifdef BUILD_TESTS`
`674`	`676`	`,`
`675`	`677`	`bool isLoadgenTx`
`@@ -687,7 +689,7 @@ TransactionQueue::tryAdd(TransactionFrameBasePtr tx, bool submittedFromSelf`
`687`	`689`	`AccountStates::iterator stateIter;`
`688`	`690`
`689`	`691`	`std::vector<std::pair<TransactionFrameBasePtr, bool>> txsToEvict;`
`690`		`- auto res = canAdd(tx, stateIter, txsToEvict`
	`692`	`+ auto res = canAdd(tx, stateIter, txsToEvict, force`
`691`	`693`	`#ifdef BUILD_TESTS`
`692`	`694`	`,`
`693`	`695`	`isLoadgenTx`
Original file line number	Diff line number	Diff line change
`@@ -1145,6 +1145,7 @@ CommandHandler::tx(std::string const& params, std::string& retStr)`
`1145`	`1145`	`std::map<std::string, std::string> paramMap;`
`1146`	`1146`	`http::server::server::parseParams(params, paramMap);`
`1147`	`1147`	`std::string blob = paramMap["blob"];`
	`1148`	`+ bool force = paramMap["force"] == "true";`
`1148`	`1149`
`1149`	`1150`	`if (!blob.empty())`
`1150`	`1151`	`{`
`@@ -1168,7 +1169,7 @@ CommandHandler::tx(std::string const& params, std::string& retStr)`
`1168`	`1169`	`{`
`1169`	`1170`	`// Add it to our current set and make sure it is valid.`
`1170`	`1171`	`auto addResult =`
`1171`		`- mApp.getHerder().recvTransaction(transaction, true);`
	`1172`	`+ mApp.getHerder().recvTransaction(transaction, true, force);`
`1172`	`1173`
`1173`	`1174`	`root["status"] = TX_STATUS_STRING[static_cast<int>(addResult.code)];`
`1174`	`1175`	`if (addResult.code ==`
Original file line number	Diff line number	Diff line change
`@@ -1418,8 +1418,8 @@ LoadGenerator::execute(TransactionFrameBasePtr txf, LoadGenMode mode,`
`1418`	`1418`
`1419`	`1419`	`// Skip certain checks for pregenerated transactions`
`1420`	`1420`	`bool isPregeneratedTx = (mode == LoadGenMode::PAY_PREGENERATED);`
`1421`		`- auto addResult =`
`1422`		`- mApp.getHerder().recvTransaction(txf, true, isPregeneratedTx);`
	`1421`	`+ auto addResult = mApp.getHerder().recvTransaction(`
	`1422`	`+ txf, true, /force=/false, /isLoadgenTx=/isPregeneratedTx);`
`1423`	`1423`	`if (addResult.code != TransactionQueue::AddResultCode::ADD_STATUS_PENDING)`
`1424`	`1424`	`{`
`1425`	`1425`