Add block quarantine to ForkedChain

execution_chain/core/chain/forked_chain.nim

@@ -12,14 +12,19 @@
 
 import
   chronicles,
+  results,
   std/[tables, algorithm],
   ../../common,
   ../../db/core_db,
   ../../evm/types,
   ../../evm/state,
   ../validate,
   ../executor/process_block,
-  ./forked_chain/[chain_desc, chain_header_cache, chain_branch]
+  ./forked_chain/[chain_desc,
+    chain_header_cache,
+    chain_branch,
+    block_quarantine
+  ]
 
 from std/sequtils import mapIt
 
@@ -105,12 +110,12 @@ proc writeBaggage(c: ForkedChainRef,
 
 proc validateBlock(c: ForkedChainRef,
           parent: BlockPos,
-          blk: Block): Result[void, string] =
+          blk: Block): Result[Hash32, string] =
   let blkHash = blk.header.blockHash
 
   if c.hashToBlock.hasKey(blkHash):
     # Block exists, just return
-    return ok()
+    return ok(blkHash)
 
   let
     parentFrame = parent.txFrame
@@ -162,7 +167,7 @@ proc validateBlock(c: ForkedChainRef,
   for i, tx in blk.transactions:
     c.txRecords[rlpHash(tx)] = (blkHash, uint64(i))
 
-  ok()
+  ok(blkHash)
 
 func findHeadPos(c: ForkedChainRef, hash: Hash32): Result[BlockPos, string] =
   ## Find the `BlockPos` that contains the block relative to the
@@ -497,28 +502,46 @@ proc init*(
     hashToBlock:     {baseHash: baseBranch.lastBlockPos}.toTable,
     baseTxFrame:     baseTxFrame,
     extraValidation: extraValidation,
-    baseDistance:    baseDistance)
+    baseDistance:    baseDistance,
+    quarantine:      Quarantine.init())
 
 proc importBlock*(c: ForkedChainRef, blk: Block): Result[void, string] =
   ## Try to import block to canonical or side chain.
   ## return error if the block is invalid
   template header(): Header =
     blk.header
 
-  c.hashToBlock.withValue(header.parentHash, bd) do:
+  c.hashToBlock.withValue(header.parentHash, parentPos) do:
     # TODO: If engine API keep importing blocks
     # but not finalized it, e.g. current chain length > StagedBlocksThreshold
     # We need to persist some of the in-memory stuff
     # to a "staging area" or disk-backed memory but it must not afect `base`.
     # `base` is the point of no return, we only update it on finality.
 
-    ?c.validateBlock(bd[], blk)
+    var parentHash = ?c.validateBlock(parentPos[], blk)
+
+    while c.quarantine.hasOrphans():
+      let orphan = c.quarantine.popOrphan(parentHash).valueOr:
+        break
+
+      c.hashToBlock.withValue(parentHash, parentCandidatePos) do:
+        parentHash = c.validateBlock(parentCandidatePos[], orphan).valueOr:
+          # Silent?
+          # We don't return error here because the import is still ok()
+          # but the quarantined blocks may not linked
+          break
+      do:
+        break
+
   do:
     # If it's parent is an invalid block
     # there is no hope the descendant is valid
     debug "Parent block not found",
       blockHash = header.blockHash.short,
       parentHash = header.parentHash.short
+
+    # Put into quarantine and hope we receive the parent block
+    c.quarantine.addOrphan(blk)
     return err("Block is not part of valid chain")
 
   ok()

execution_chain/core/chain/forked_chain/block_quarantine.nim

@@ -0,0 +1,45 @@
+# Nimbus
+# Copyright (c) 2025 Status Research & Development GmbH
+# Licensed under either of
+#  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+#    http://www.apache.org/licenses/LICENSE-2.0)
+#  * MIT license ([LICENSE-MIT](LICENSE-MIT) or
+#    http://opensource.org/licenses/MIT)
+# at your option. This file may not be copied, modified, or distributed except
+# according to those terms.
+
+import
+  std/tables,
+  results,
+  minilru,
+  eth/common/blocks
+
+const
+  MaxOrphans = 32
+
+type
+  Quarantine* = object
+    ## Keeps track of unvalidated blocks coming from the network
+    ## and that cannot yet be added to the chain
+    ##
+    ## This only stores blocks that cannot be linked to the
+    ## ForkedChain due to missing ancestor(s).
+
+    orphans: LruCache[Hash32, Block]
+      ## Blocks that we don't have a parent for - when we resolve the
+      ## parent, we can proceed to resolving the block as well - we
+      ## index this by parentHash.
+
+func init*(T: type Quarantine): T =
+  T(
+    orphans: LruCache[Hash32, Block].init(MaxOrphans)
+  )
+
+func addOrphan*(quarantine: var Quarantine, blk: Block) =
+  quarantine.orphans.put(blk.header.parentHash, blk)
+
+func popOrphan*(quarantine: var Quarantine, parentHash: Hash32): Opt[Block] =
+  quarantine.orphans.pop(parentHash)
+
+func hasOrphans*(quarantine: Quarantine): bool =
+  quarantine.orphans.len > 0

execution_chain/core/chain/forked_chain/chain_desc.nim

@@ -13,6 +13,7 @@
 import
   std/[deques, tables],
   ./chain_branch,
+  ./block_quarantine,
   ../../../common,
   ../../../db/core_db
 
@@ -25,6 +26,7 @@ type
     branches*    : seq[BranchRef]
     baseBranch*  : BranchRef
     activeBranch*: BranchRef
+    quarantine*  : Quarantine
 
     txRecords    : Table[Hash32, (Hash32, uint64)]
     baseTxFrame* : CoreDbTxRef