From 66883c13e323c5c78c2711923765cf91afa7303d Mon Sep 17 00:00:00 2001
From: lightclient <lightclient@protonmail.com>
Date: Tue, 8 Apr 2025 10:38:22 -0600
Subject: [PATCH] core/txpool: add notice to Add(..)

---
 core/txpool/blobpool/blobpool.go     |  3 +++
 core/txpool/legacypool/legacypool.go |  4 ++--
 core/txpool/txpool.go                | 12 ++++++++----
 3 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/core/txpool/blobpool/blobpool.go b/core/txpool/blobpool/blobpool.go
index 6ba185f63c..f09cef4c0f 100644
--- a/core/txpool/blobpool/blobpool.go
+++ b/core/txpool/blobpool/blobpool.go
@@ -1311,6 +1311,9 @@ func (p *BlobPool) GetBlobs(vhashes []common.Hash) ([]*kzg4844.Blob, []*kzg4844.
 
 // Add inserts a set of blob transactions into the pool if they pass validation (both
 // consensus validity and pool restrictions).
+//
+// Note, if sync is set the method will block until all internal maintenance
+// related to the add is finished. Only use this during tests for determinism.
 func (p *BlobPool) Add(txs []*types.Transaction, sync bool) []error {
 	var (
 		adds = make([]*types.Transaction, 0, len(txs))
diff --git a/core/txpool/legacypool/legacypool.go b/core/txpool/legacypool/legacypool.go
index 77e3368f0c..75d39bd559 100644
--- a/core/txpool/legacypool/legacypool.go
+++ b/core/txpool/legacypool/legacypool.go
@@ -919,8 +919,8 @@ func (pool *LegacyPool) addRemoteSync(tx *types.Transaction) error {
 
 // Add enqueues a batch of transactions into the pool if they are valid.
 //
-// If sync is set, the method will block until all internal maintenance related
-// to the add is finished. Only use this during tests for determinism!
+// Note, if sync is set the method will block until all internal maintenance
+// related to the add is finished. Only use this during tests for determinism.
 func (pool *LegacyPool) Add(txs []*types.Transaction, sync bool) []error {
 	// Filter out known ones without obtaining the pool lock or recovering signatures
 	var (
diff --git a/core/txpool/txpool.go b/core/txpool/txpool.go
index 65895a9f28..3c3aa2fefe 100644
--- a/core/txpool/txpool.go
+++ b/core/txpool/txpool.go
@@ -409,6 +409,9 @@ func (p *TxPool) ValidateTxBasics(tx *types.Transaction) error {
 // Add enqueues a batch of transactions into the pool if they are valid. Due
 // to the large transaction churn, add may postpone fully integrating the tx
 // to a later point to batch multiple ones together.
+//
+// Note, if sync is set the method will block until all internal maintenance
+// related to the add is finished. Only use this during tests for determinism.
 func (p *TxPool) Add(txs []*types.Transaction, sync bool) []error {
 	// Split the input transactions between the subpools. It shouldn't really
 	// happen that we receive merged batches, but better graceful than strange
@@ -562,8 +565,8 @@ func (p *TxPool) Status(hash common.Hash) TxStatus {
 // internal background reset operations. This method will run an explicit reset
 // operation to ensure the pool stabilises, thus avoiding flakey behavior.
 //
-// Note, do not use this in production / live code. In live code, the pool is
-// meant to reset on a separate thread to avoid DoS vectors.
+// Note, this method is only used for testing and is susceptible to DoS vectors.
+// In production code, the pool is meant to reset on a separate thread.
 func (p *TxPool) Sync() error {
 	sync := make(chan error)
 	select {
@@ -576,8 +579,9 @@ func (p *TxPool) Sync() error {
 
 // Clear removes all tracked txs from the subpools.
 //
-// Note, do not use this in production / live code. In live code, the pool is
-// meant to reset on a separate thread to avoid DoS vectors.
+// Note, this method invokes Sync() is only used for testing and is susceptible
+// to DoS vectors. In production code, the pool is meant to reset on a separate
+// thread.
 func (p *TxPool) Clear() {
 	// Invoke Sync to ensure that txs pending addition don't get added to the pool after
 	// the subpools are subsequently cleared