Add tests for skipping reorg only if ancestor of finalised block (#11439)

* engine api changes as per ethereum/execution-apis#770
                          ethereum/execution-apis#760

* fix comment

* improve test

* improve tests matching the specs

* cleaner design

* taiko fix

* claude review

* claude review

* more fixes

* conflicts fix

* fix tests

* fix taiko tests

* remove unused import

* update per 786

* fixes

* fix tests

* fixes

* claude review again

* fix tests

* test fix

* fixes

* test fixes

* minor fixes

* Cleanup mess

* remove test

* fixing

* cleanups

* revert formatting changes and zero hash stuff

* remove tests

* fix lint

* delete old tests

* add tests

* refactor tests

* fix test

* add comment

---------

Co-authored-by: stavrosvl7 <stavrosvl7@gmail.com>
Co-authored-by: Stavros Vlachakis <89769224+svlachakis@users.noreply.github.com>
Co-authored-by: MarekM25 <marekm2504@gmail.com>
Co-authored-by: Marc Harvey-Hill <10379486+Marchhill@users.noreply.github.com>

Author: 3 people

src/Nethermind/Nethermind.Merge.Plugin.Test/EngineModuleTests.V1.cs

@@ -1553,6 +1553,87 @@ public async Task forkchoiceUpdated_safe_block_that_is_real_ancestor_of_current_
         result.Data.PayloadStatus.Status.Should().Be(PayloadStatus.Valid);
     }
 
+    private async Task<IReadOnlyList<ExecutionPayload>> BuildChainWithLoweredFinalized(
+        MergeTestBlockchain chain, IEngineRpcModule rpc, int oldHead, int lastFinalized)
+    {
+        IReadOnlyList<ExecutionPayload> blocks = await ProduceBranchV1(rpc, chain, oldHead + 1, CreateParentBlockRequestOnHead(chain.BlockTree), setHead: true);
+
+        // Lower the finalized marker to blocks[lastFinalized] while keeping the head at blocks[oldHead].
+        Hash256 finalized = blocks[lastFinalized].BlockHash;
+        ForkchoiceStateV1 setFinalized = new(headBlockHash: blocks[oldHead].BlockHash, finalizedBlockHash: finalized, safeBlockHash: finalized);
+        (await rpc.engine_forkchoiceUpdatedV1(setFinalized)).Data.PayloadStatus.Status.Should().Be(PayloadStatus.Valid);
+        chain.BlockTree.Head!.Hash.Should().Be(blocks[oldHead].BlockHash);
+        return blocks;
+    }
+
+    [TestCase(-1, TestName = "Behind finalized")]
+    [TestCase(0, TestName = "Last finalized")]
+    [TestCase(1, TestName = "After finalized")]
+    public async Task forkchoiceUpdatedV1_processed_skips_reorg_only_when_head_is_ancestor_of_finalized(int offset)
+    {
+        using MergeTestBlockchain chain =
+            await CreateBlockchain(null, new MergeConfig() { TerminalTotalDifficulty = "0" });
+        IEngineRpcModule rpc = chain.EngineRpcModule;
+
+        const int oldHead = 4;
+        const int lastFinalized = 2;
+        IReadOnlyList<ExecutionPayload> blocks = await BuildChainWithLoweredFinalized(chain, rpc, oldHead, lastFinalized);
+
+        // Zero request-level finalized/safe so RejectIfInconsistent (which runs before the skip
+        // check) does not reject the offset < 0 case where finalized > head. The skip check still
+        // fires via the BlockTree's internal FinalizedHash set by the helper.
+        int newHead = lastFinalized + offset;
+        ForkchoiceStateV1 fcu = new(headBlockHash: blocks[newHead].BlockHash, finalizedBlockHash: Keccak.Zero, safeBlockHash: Keccak.Zero);
+        ResultWrapper<ForkchoiceUpdatedV1Result> result = await rpc.engine_forkchoiceUpdatedV1(fcu);
+        result.Data.PayloadStatus.Status.Should().Be(PayloadStatus.Valid);
+
+        if (offset < 0)
+        {
+            // Skip path: the FCU returns Valid without reorging; the head stays at blocks[oldHead].
+            chain.BlockTree.Head!.Hash.Should().Be(blocks[oldHead].BlockHash);
+        }
+        else
+        {
+            // No skip: the regular reorg path runs and the head is updated to blocks[newHead].
+            chain.BlockTree.Head!.Hash.Should().Be(blocks[newHead].BlockHash);
+        }
+    }
+
+    [TestCase(-1, TestName = "Behind finalized")]
+    [TestCase(0, TestName = "Last finalized")]
+    [TestCase(1, TestName = "After finalized")]
+    public async Task forkchoiceUpdatedV1_unprocessed_skips_reorg_only_when_head_is_ancestor_of_finalized(int offset)
+    {
+        using MergeTestBlockchain chain =
+            await CreateBlockchain(null, new MergeConfig() { TerminalTotalDifficulty = "0" });
+        IEngineRpcModule rpc = chain.EngineRpcModule;
+
+        const int oldHead = 4;
+        const int lastFinalized = 2;
+        IReadOnlyList<ExecutionPayload> blocks = await BuildChainWithLoweredFinalized(chain, rpc, oldHead, lastFinalized);
+        Hash256 finalized = blocks[lastFinalized].BlockHash;
+
+        int newHead = lastFinalized + offset;
+        // Reset the candidate's WasProcessed flag (the block stays on the main chain) so the
+        // FCU enters the unprocessed branch where the first skip check lives.
+        FlipCanonicalMarkerTo(chain, blocks[newHead]);
+
+        ForkchoiceStateV1 fcu = new(headBlockHash: blocks[newHead].BlockHash, finalizedBlockHash: finalized, safeBlockHash: finalized);
+        ResultWrapper<ForkchoiceUpdatedV1Result> result = await rpc.engine_forkchoiceUpdatedV1(fcu);
+
+        if (offset < 0)
+        {
+            // Skip path: the unprocessed branch returns Valid early without falling through
+            // to the sync logic.
+            result.Data.PayloadStatus.Status.Should().Be(PayloadStatus.Valid);
+        }
+        else
+        {
+            // No skip: the unprocessed branch falls through and returns Syncing.
+            result.Data.PayloadStatus.Status.Should().Be(PayloadStatus.Syncing);
+        }
+    }
+
     [Test]
     public async Task forkchoiceUpdated_accepts_lower_finalized_than_previous_but_rejects_safe_before_finalized()
     {

src/Nethermind/Nethermind.Merge.Plugin/Handlers/ForkchoiceUpdatedHandler.cs

@@ -64,6 +64,12 @@ public async Task<ResultWrapper<ForkchoiceUpdatedV1Result>> Handle(ForkchoiceSta
             ?? StartBuildingPayload(newHeadHeader!, forkchoiceState, payloadAttributes);
     }
 
+    /// <summary>
+    /// MAY-skip clause from
+    /// <see href="https://github.com/ethereum/execution-apis/pull/786">execution-apis#786</see>:
+    /// returns Valid when <paramref name="newHeadHeader"/> is a canonical ancestor of the latest
+    /// known finalized block, so the FCU is answered without performing a reorg.
+    /// </summary>
     protected virtual bool IsOnMainChainBehindFinalized(BlockHeader newHeadHeader, ForkchoiceStateV1 forkchoiceState,
         [NotNullWhen(true)] out ResultWrapper<ForkchoiceUpdatedV1Result>? result)
     {