core/txpool: add notice to Clear that is not meant for production code (#31567)

The `Sync(..)` function explicitly says not to rely on in production
code, but it is used in `Clear(..)` so should add a similar mention.

core/txpool/blobpool/blobpool.go

@@ -1349,6 +1349,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))
@@ -1792,6 +1795,9 @@ func (p *BlobPool) Status(hash common.Hash) txpool.TxStatus {
 
 // Clear implements txpool.SubPool, removing all tracked transactions
 // from the blob pool and persistent store.
+//
+// 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.
 func (p *BlobPool) Clear() {
 	p.lock.Lock()
 	defer p.lock.Unlock()

core/txpool/legacypool/legacypool.go

@@ -927,8 +927,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
+// Note, if sync is set the method will block until all internal maintenance
-// to the add is finished. Only use this during tests for determinism!
+// 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 (
@@ -1886,6 +1886,9 @@ func numSlots(tx *types.Transaction) int {
 
 // Clear implements txpool.SubPool, removing all tracked txs from the pool
 // and rotating the journal.
+//
+// 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.
 func (pool *LegacyPool) Clear() {
 	pool.mu.Lock()
 	defer pool.mu.Unlock()

core/txpool/txpool.go

@@ -350,6 +350,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
@@ -503,8 +506,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
+// Note, this method is only used for testing and is susceptible to DoS vectors.
-// meant to reset on a separate thread to avoid 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 {
@@ -516,6 +519,10 @@ func (p *TxPool) Sync() error {
 }
 
 // Clear removes all tracked txs from the subpools.
+//
+// Note, this method invokes Sync() and is only used for testing, because it 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