From af8e152501aa80d335cda8a2cdf4a1ac601e863c Mon Sep 17 00:00:00 2001
From: Gary Rong <garyrong0905@gmail.com>
Date: Wed, 17 Dec 2025 12:12:10 +0800
Subject: [PATCH] eth: re-schedule skeleton sync if it's not linked with local
 chain

---
 eth/catalyst/metrics.go    |  2 +-
 eth/downloader/skeleton.go | 28 +++++++++++++++++++++++++++-
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/eth/catalyst/metrics.go b/eth/catalyst/metrics.go
index d14d0d9832..d0a733a22b 100644
--- a/eth/catalyst/metrics.go
+++ b/eth/catalyst/metrics.go
@@ -1,4 +1,4 @@
-// Copyright 20222 The go-ethereum Authors
+// 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
diff --git a/eth/downloader/skeleton.go b/eth/downloader/skeleton.go
index 2cf9c4672b..69e2b8522b 100644
--- a/eth/downloader/skeleton.go
+++ b/eth/downloader/skeleton.go
@@ -64,6 +64,12 @@ var errSyncMerged = errors.New("sync merged")
 // should abort and restart with the new state.
 var errSyncReorged = errors.New("sync reorged")
 
+// errSyncTrimmed is an internal helper error to signal that the local chain
+// has been trimmed (e.g, via debug_setHead explicitly) and the skeleton chain
+// is no longer linked with the local chain. In this case, the skeleton sync
+// should be re-scheduled again.
+var errSyncTrimmed = errors.New("sync trimmed")
+
 // errTerminated is returned if the sync mechanism was terminated for this run of
 // the process. This is usually the case when Geth is shutting down and some events
 // might still be propagating.
@@ -296,6 +302,11 @@ func (s *skeleton) startup() {
 					// head to force a cleanup.
 					head = newhead
 
+				case err == errSyncTrimmed:
+					// The skeleton chain is not linked with the local chain anymore,
+					// restart the sync.
+					head = nil
+
 				case err == errTerminated:
 					// Sync was requested to be terminated from within, stop and
 					// return (no need to pass a message, was already done internally)
@@ -486,7 +497,21 @@ func (s *skeleton) sync(head *types.Header) (*types.Header, error) {
 			// is still running, it will pick it up. If it already terminated,
 			// a new cycle needs to be spun up.
 			if linked {
-				s.filler.resume()
+				linked = len(s.progress.Subchains) == 1 &&
+					rawdb.HasHeader(s.db, s.progress.Subchains[0].Next, s.scratchHead) &&
+					rawdb.HasBody(s.db, s.progress.Subchains[0].Next, s.scratchHead) &&
+					rawdb.HasReceipts(s.db, s.progress.Subchains[0].Next, s.scratchHead)
+
+				if linked {
+					// The skeleton chain has been extended and is still linked with the local
+					// chain, try to re-schedule the backfiller if it's already terminated.
+					s.filler.resume()
+				} else {
+					// The skeleton chain is no longer linked to the local chain for some reason
+					// (e.g. debug_setHead was used to trim the local chain). Re-schedule the
+					// skeleton sync to fill the chain gap.
+					return nil, errSyncTrimmed
+				}
 			}
 
 		case req := <-requestFails:
@@ -669,6 +694,7 @@ func (s *skeleton) processNewHead(head *types.Header, final *types.Header) error
 	if err := batch.Write(); err != nil {
 		log.Crit("Failed to write skeleton sync status", "err", err)
 	}
+	log.Debug("Extended beacon header chain", "number", head.Number, "hash", head.Hash())
 	return nil
 }