From 7a70fbc854532a46b4c80c3c3405ffea3b14cfe4 Mon Sep 17 00:00:00 2001
From: Daniel Liu <139250065@qq.com>
Date: Fri, 13 Mar 2026 18:16:54 +0800
Subject: [PATCH] docs(core/txpool): notice ` Clear` is not for production
 #31567

---
 core/txpool/legacypool/legacypool.go | 7 +++++--
 core/txpool/txpool.go                | 9 +++++----
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/core/txpool/legacypool/legacypool.go b/core/txpool/legacypool/legacypool.go
index 1448f9017976..99055a24cc35 100644
--- a/core/txpool/legacypool/legacypool.go
+++ b/core/txpool/legacypool/legacypool.go
@@ -1052,8 +1052,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 (
@@ -2003,6 +2003,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()
diff --git a/core/txpool/txpool.go b/core/txpool/txpool.go
index b97137551db3..bfd44e0452d3 100644
--- a/core/txpool/txpool.go
+++ b/core/txpool/txpool.go
@@ -275,8 +275,9 @@ func (p *TxPool) Get(hash common.Hash) *types.Transaction {
 }
 
 // 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
@@ -456,8 +457,8 @@ func (pool *TxPool) IsSigner(addr common.Address) bool {
 // 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 {