cmd, eth, internal: introduce debug_sync (#32177)

Alternative implementation of https://github.com/ethereum/go-ethereum/pull/32159

cmd/geth/config.go

@@ -262,14 +262,16 @@ func makeFullNode(ctx *cli.Context) *node.Node {
 	if cfg.Ethstats.URL != "" {
 		utils.RegisterEthStatsService(stack, backend, cfg.Ethstats.URL)
 	}
-	// Configure full-sync tester service if requested
+	// Configure synchronization override service
+	var synctarget common.Hash
 	if ctx.IsSet(utils.SyncTargetFlag.Name) {
 		hex := hexutil.MustDecode(ctx.String(utils.SyncTargetFlag.Name))
 		if len(hex) != common.HashLength {
 			utils.Fatalf("invalid sync target length: have %d, want %d", len(hex), common.HashLength)
 		}
-		utils.RegisterFullSyncTester(stack, eth, common.BytesToHash(hex), ctx.Bool(utils.ExitWhenSyncedFlag.Name))
+		synctarget = common.BytesToHash(hex)
 	}
+	utils.RegisterSyncOverrideService(stack, eth, synctarget, ctx.Bool(utils.ExitWhenSyncedFlag.Name))
 
 	if ctx.IsSet(utils.DeveloperFlag.Name) {
 		// Start dev mode.

cmd/utils/flags.go

@@ -49,10 +49,10 @@ import (
 	"github.com/ethereum/go-ethereum/crypto"
 	"github.com/ethereum/go-ethereum/crypto/kzg4844"
 	"github.com/ethereum/go-ethereum/eth"
-	"github.com/ethereum/go-ethereum/eth/catalyst"
 	"github.com/ethereum/go-ethereum/eth/ethconfig"
 	"github.com/ethereum/go-ethereum/eth/filters"
 	"github.com/ethereum/go-ethereum/eth/gasprice"
+	"github.com/ethereum/go-ethereum/eth/syncer"
 	"github.com/ethereum/go-ethereum/eth/tracers"
 	"github.com/ethereum/go-ethereum/ethdb"
 	"github.com/ethereum/go-ethereum/ethdb/remotedb"
@@ -1997,10 +1997,14 @@ func RegisterFilterAPI(stack *node.Node, backend ethapi.Backend, ethcfg *ethconf
 	return filterSystem
 }
 
-// RegisterFullSyncTester adds the full-sync tester service into node.
+// RegisterSyncOverrideService adds the synchronization override service into node.
-func RegisterFullSyncTester(stack *node.Node, eth *eth.Ethereum, target common.Hash, exitWhenSynced bool) {
+func RegisterSyncOverrideService(stack *node.Node, eth *eth.Ethereum, target common.Hash, exitWhenSynced bool) {
-	catalyst.RegisterFullSyncTester(stack, eth, target, exitWhenSynced)
+	if target != (common.Hash{}) {
-	log.Info("Registered full-sync tester", "hash", target, "exitWhenSynced", exitWhenSynced)
+		log.Info("Registered sync override service", "hash", target, "exitWhenSynced", exitWhenSynced)
+	} else {
+		log.Info("Registered sync override service")
+	}
+	syncer.Register(stack, eth, target, exitWhenSynced)
 }
 
 // SetupMetrics configures the metrics system.

eth/catalyst/tester.go

@@ -1,103 +0,0 @@
-// Copyright 2022 The go-ethereum Authors
-// This file is part of the go-ethereum library.
-//
-// The go-ethereum library is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Lesser General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// The go-ethereum library is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-// GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License
-// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
-
-package catalyst
-
-import (
-	"sync"
-	"time"
-
-	"github.com/ethereum/go-ethereum/common"
-	"github.com/ethereum/go-ethereum/eth"
-	"github.com/ethereum/go-ethereum/eth/ethconfig"
-	"github.com/ethereum/go-ethereum/log"
-	"github.com/ethereum/go-ethereum/node"
-)
-
-// FullSyncTester is an auxiliary service that allows Geth to perform full sync
-// alone without consensus-layer attached. Users must specify a valid block hash
-// as the sync target.
-//
-// This tester can be applied to different networks, no matter it's pre-merge or
-// post-merge, but only for full-sync.
-type FullSyncTester struct {
-	stack          *node.Node
-	backend        *eth.Ethereum
-	target         common.Hash
-	closed         chan struct{}
-	wg             sync.WaitGroup
-	exitWhenSynced bool
-}
-
-// RegisterFullSyncTester registers the full-sync tester service into the node
-// stack for launching and stopping the service controlled by node.
-func RegisterFullSyncTester(stack *node.Node, backend *eth.Ethereum, target common.Hash, exitWhenSynced bool) (*FullSyncTester, error) {
-	cl := &FullSyncTester{
-		stack:          stack,
-		backend:        backend,
-		target:         target,
-		closed:         make(chan struct{}),
-		exitWhenSynced: exitWhenSynced,
-	}
-	stack.RegisterLifecycle(cl)
-	return cl, nil
-}
-
-// Start launches the beacon sync with provided sync target.
-func (tester *FullSyncTester) Start() error {
-	tester.wg.Add(1)
-	go func() {
-		defer tester.wg.Done()
-
-		// Trigger beacon sync with the provided block hash as trusted
-		// chain head.
-		err := tester.backend.Downloader().BeaconDevSync(ethconfig.FullSync, tester.target, tester.closed)
-		if err != nil {
-			log.Info("Failed to trigger beacon sync", "err", err)
-		}
-
-		ticker := time.NewTicker(time.Second * 5)
-		defer ticker.Stop()
-
-		for {
-			select {
-			case <-ticker.C:
-				// Stop in case the target block is already stored locally.
-				if block := tester.backend.BlockChain().GetBlockByHash(tester.target); block != nil {
-					log.Info("Full-sync target reached", "number", block.NumberU64(), "hash", block.Hash())
-
-					if tester.exitWhenSynced {
-						go tester.stack.Close() // async since we need to close ourselves
-						log.Info("Terminating the node")
-					}
-					return
-				}
-
-			case <-tester.closed:
-				return
-			}
-		}
-	}()
-	return nil
-}
-
-// Stop stops the full-sync tester to stop all background activities.
-// This function can only be called for one time.
-func (tester *FullSyncTester) Stop() error {
-	close(tester.closed)
-	tester.wg.Wait()
-	return nil
-}

eth/downloader/beacondevsync.go

@@ -18,7 +18,6 @@ package downloader
 
 import (
 	"errors"
-	"time"
 
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/core/types"
@@ -34,28 +33,14 @@ import (
 // Note, this must not be used in live code. If the forkchcoice endpoint where
 // to use this instead of giving us the payload first, then essentially nobody
 // in the network would have the block yet that we'd attempt to retrieve.
-func (d *Downloader) BeaconDevSync(mode SyncMode, hash common.Hash, stop chan struct{}) error {
+func (d *Downloader) BeaconDevSync(mode SyncMode, header *types.Header) error {
 	// Be very loud that this code should not be used in a live node
 	log.Warn("----------------------------------")
-	log.Warn("Beacon syncing with hash as target", "hash", hash)
+	log.Warn("Beacon syncing with hash as target", "number", header.Number, "hash", header.Hash())
 	log.Warn("This is unhealthy for a live node!")
+	log.Warn("This is incompatible with the consensus layer!")
 	log.Warn("----------------------------------")
-
+	return d.BeaconSync(mode, header, header)
-	log.Info("Waiting for peers to retrieve sync target")
-	for {
-		// If the node is going down, unblock
-		select {
-		case <-stop:
-			return errors.New("stop requested")
-		default:
-		}
-		header, err := d.GetHeader(hash)
-		if err != nil {
-			time.Sleep(time.Second)
-			continue
-		}
-		return d.BeaconSync(mode, header, header)
-	}
 }
 
 // GetHeader tries to retrieve the header with a given hash from a random peer.

eth/downloader/fetchers.go

@@ -45,9 +45,6 @@ func (d *Downloader) fetchHeadersByHash(p *peerConnection, hash common.Hash, amo
 	defer timeoutTimer.Stop()
 
 	select {
-	case <-d.cancelCh:
-		return nil, nil, errCanceled
-
 	case <-timeoutTimer.C:
 		// Header retrieval timed out, update the metrics
 		p.log.Debug("Header request timed out", "elapsed", ttl)

eth/syncer/syncer.go

@@ -0,0 +1,197 @@
+// Copyright 2025 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// The go-ethereum library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+package syncer
+
+import (
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/eth"
+	"github.com/ethereum/go-ethereum/eth/ethconfig"
+	"github.com/ethereum/go-ethereum/log"
+	"github.com/ethereum/go-ethereum/node"
+	"github.com/ethereum/go-ethereum/rpc"
+)
+
+type syncReq struct {
+	hash common.Hash
+	errc chan error
+}
+
+// Syncer is an auxiliary service that allows Geth to perform full sync
+// alone without consensus-layer attached. Users must specify a valid block hash
+// as the sync target.
+//
+// This tool can be applied to different networks, no matter it's pre-merge or
+// post-merge, but only for full-sync.
+type Syncer struct {
+	stack          *node.Node
+	backend        *eth.Ethereum
+	target         common.Hash
+	request        chan *syncReq
+	closed         chan struct{}
+	wg             sync.WaitGroup
+	exitWhenSynced bool
+}
+
+// Register registers the synchronization override service into the node
+// stack for launching and stopping the service controlled by node.
+func Register(stack *node.Node, backend *eth.Ethereum, target common.Hash, exitWhenSynced bool) (*Syncer, error) {
+	s := &Syncer{
+		stack:          stack,
+		backend:        backend,
+		target:         target,
+		request:        make(chan *syncReq),
+		closed:         make(chan struct{}),
+		exitWhenSynced: exitWhenSynced,
+	}
+	stack.RegisterAPIs(s.APIs())
+	stack.RegisterLifecycle(s)
+	return s, nil
+}
+
+// APIs return the collection of RPC services the ethereum package offers.
+// NOTE, some of these services probably need to be moved to somewhere else.
+func (s *Syncer) APIs() []rpc.API {
+	return []rpc.API{
+		{
+			Namespace: "debug",
+			Service:   NewAPI(s),
+		},
+	}
+}
+
+// run is the main loop that monitors sync requests from users and initiates
+// sync operations when necessary. It also checks whether the specified target
+// has been reached and shuts down Geth if requested by the user.
+func (s *Syncer) run() {
+	defer s.wg.Done()
+
+	var (
+		target *types.Header
+		ticker = time.NewTicker(time.Second * 5)
+	)
+	for {
+		select {
+		case req := <-s.request:
+			var (
+				resync  bool
+				retries int
+				logged  bool
+			)
+			for {
+				if retries >= 10 {
+					req.errc <- fmt.Errorf("sync target is not avaibale, %x", req.hash)
+					break
+				}
+				select {
+				case <-s.closed:
+					req.errc <- errors.New("syncer closed")
+					return
+				default:
+				}
+
+				header, err := s.backend.Downloader().GetHeader(req.hash)
+				if err != nil {
+					if !logged {
+						logged = true
+						log.Info("Waiting for peers to retrieve sync target", "hash", req.hash)
+					}
+					time.Sleep(time.Second * time.Duration(retries+1))
+					retries++
+					continue
+				}
+				if target != nil && header.Number.Cmp(target.Number) <= 0 {
+					req.errc <- fmt.Errorf("stale sync target, current: %d, received: %d", target.Number, header.Number)
+					break
+				}
+				target = header
+				resync = true
+				break
+			}
+			if resync {
+				req.errc <- s.backend.Downloader().BeaconDevSync(ethconfig.FullSync, target)
+			}
+
+		case <-ticker.C:
+			if target == nil || !s.exitWhenSynced {
+				continue
+			}
+			if block := s.backend.BlockChain().GetBlockByHash(target.Hash()); block != nil {
+				log.Info("Sync target reached", "number", block.NumberU64(), "hash", block.Hash())
+				go s.stack.Close() // async since we need to close ourselves
+				return
+			}
+
+		case <-s.closed:
+			return
+		}
+	}
+}
+
+// Start launches the synchronization service.
+func (s *Syncer) Start() error {
+	s.wg.Add(1)
+	go s.run()
+	if s.target == (common.Hash{}) {
+		return nil
+	}
+	return s.Sync(s.target)
+}
+
+// Stop terminates the synchronization service and stop all background activities.
+// This function can only be called for one time.
+func (s *Syncer) Stop() error {
+	close(s.closed)
+	s.wg.Wait()
+	return nil
+}
+
+// Sync sets the synchronization target. Notably, setting a target lower than the
+// previous one is not allowed, as backward synchronization is not supported.
+func (s *Syncer) Sync(hash common.Hash) error {
+	req := &syncReq{
+		hash: hash,
+		errc: make(chan error, 1),
+	}
+	select {
+	case s.request <- req:
+		return <-req.errc
+	case <-s.closed:
+		return errors.New("syncer is closed")
+	}
+}
+
+// API is the collection of synchronization service APIs for debugging the
+// protocol.
+type API struct {
+	s *Syncer
+}
+
+// NewAPI creates a new debug API instance.
+func NewAPI(s *Syncer) *API {
+	return &API{s: s}
+}
+
+// Sync initiates a full sync to the target block hash.
+func (api *API) Sync(target common.Hash) error {
+	return api.s.Sync(target)
+}

internal/web3ext/web3ext.go

@@ -468,6 +468,11 @@ web3._extend({
 			call: 'debug_getTrieFlushInterval',
 			params: 0
 		}),
+		new web3._extend.Method({
+			name: 'sync',
+			call: 'debug_sync',
+			params: 1
+		}),
 	],
 	properties: []
 });