@lodestar/beacon-node 1.43.0-dev.6b7eebbf6d → 1.43.0-dev.6f485b1b61

package/lib/sync/unknownBlock.js

@@ -1,19 +1,24 @@
+import { routes } from "@lodestar/api";
 import { ForkSeq } from "@lodestar/params";
 import { RequestError, RequestErrorCode } from "@lodestar/reqresp";
 import { computeTimeAtSlot } from "@lodestar/state-transition";
-import { prettyPrintIndices, pruneSetToMax, sleep } from "@lodestar/utils";
+import { fromHex, prettyPrintIndices, pruneSetToMax, sleep, toRootHex } from "@lodestar/utils";
 import { isBlockInputBlobs, isBlockInputColumns } from "../chain/blocks/blockInput/blockInput.js";
 import { BlockInputSource } from "../chain/blocks/blockInput/types.js";
+import { PayloadError, PayloadErrorCode } from "../chain/blocks/importExecutionPayload.js";
+import { PayloadEnvelopeInputSource } from "../chain/blocks/payloadEnvelopeInput/index.js";
 import { BlockError, BlockErrorCode } from "../chain/errors/index.js";
 import { ChainEvent } from "../chain/index.js";
+import { validateGloasBlockDataColumnSidecars } from "../chain/validation/dataColumnSidecar.js";
+import { validateGossipExecutionPayloadEnvelope } from "../chain/validation/executionPayloadEnvelope.js";
 import { NetworkEvent, prettyPrintPeerIdStr } from "../network/index.js";
 import { shuffle } from "../util/shuffle.js";
 import { sortBy } from "../util/sortBy.js";
 import { wrapError } from "../util/wrapError.js";
 import { MAX_CONCURRENT_REQUESTS } from "./constants.js";
-import { PendingBlockInputStatus, PendingBlockType, getBlockInputSyncCacheItemRootHex, getBlockInputSyncCacheItemSlot, isPendingBlockInput, } from "./types.js";
+import { PendingBlockInputStatus, PendingBlockType, PendingPayloadInputStatus, getBlockInputSyncCacheItemRootHex, getBlockInputSyncCacheItemSlot, getPayloadSyncCacheItemRootHex, getPayloadSyncCacheItemSlot, isPendingBlockInput, isPendingPayloadEnvelope, isPendingPayloadInput, } from "./types.js";
 import { DownloadByRootError, downloadByRoot } from "./utils/downloadByRoot.js";
-import { getAllDescendantBlocks, getDescendantBlocks, getUnknownAndAncestorBlocks } from "./utils/pendingBlocksTree.js";
+import { getAllDescendantBlocks, getUnknownAndAncestorBlocks } from "./utils/pendingBlocksTree.js";
 const MAX_ATTEMPTS_PER_BLOCK = 5;
 const MAX_KNOWN_BAD_BLOCKS = 500;
 const MAX_PENDING_BLOCKS = 100;
@@ -25,6 +30,24 @@ var FetchResult;
     FetchResult["FailureTriedAllPeers"] = "failure_tried_all_peers";
     FetchResult["FailureMaxAttempts"] = "failure_max_attempts";
 })(FetchResult || (FetchResult = {}));
+class UnknownBlockRateLimitedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnknownBlockRateLimitedError";
+    }
+}
+function getRateLimitedUntilMs(e) {
+    if (!(e instanceof RequestError)) {
+        return null;
+    }
+    switch (e.type.code) {
+        case RequestErrorCode.RESP_RATE_LIMITED:
+        case RequestErrorCode.REQUEST_SELF_RATE_LIMITED:
+            return e.type.rateLimitedUntilMs ?? null;
+        default:
+            return null;
+    }
+}
 /**
  * BlockInputSync is a class that handles ReqResp to find blocks and data related to a specific blockRoot.  The
  * blockRoot may have been found via object gossip, or the API.  Gossip objects that can trigger a search are block,
@@ -68,10 +91,13 @@ export class BlockInputSync {
      * block RootHex -> PendingBlock. To avoid finding same root at the same time
      */
     pendingBlocks = new Map();
+    // Payload sync is keyed by beacon block root as well, so block and payload queues can unblock each other.
+    pendingPayloads = new Map();
     knownBadBlocks = new Set();
     maxPendingBlocks;
     subscribedToNetworkEvents = false;
     peerBalancer;
+    rateLimitBackoffTimeout;
     constructor(config, network, chain, logger, metrics, opts) {
         this.config = config;
         this.network = network;
@@ -83,6 +109,7 @@ export class BlockInputSync {
         this.peerBalancer = new UnknownBlockPeerBalancer();
         if (metrics) {
             metrics.blockInputSync.pendingBlocks.addCollect(() => metrics.blockInputSync.pendingBlocks.set(this.pendingBlocks.size));
+            metrics.blockInputSync.pendingPayloads.addCollect(() => metrics.blockInputSync.pendingPayloads.set(this.pendingPayloads.size));
             metrics.blockInputSync.knownBadBlocks.addCollect(() => metrics.blockInputSync.knownBadBlocks.set(this.knownBadBlocks.size));
         }
     }
@@ -95,8 +122,12 @@ export class BlockInputSync {
         if (!this.subscribedToNetworkEvents) {
             this.logger.verbose("BlockInputSync enabled.");
             this.chain.emitter.on(ChainEvent.unknownBlockRoot, this.onUnknownBlockRoot);
+            this.chain.emitter.on(ChainEvent.unknownEnvelopeBlockRoot, this.onUnknownEnvelopeBlockRoot);
             this.chain.emitter.on(ChainEvent.incompleteBlockInput, this.onIncompleteBlockInput);
+            this.chain.emitter.on(ChainEvent.incompletePayloadEnvelope, this.onIncompletePayloadEnvelope);
             this.chain.emitter.on(ChainEvent.blockUnknownParent, this.onUnknownParent);
+            this.chain.emitter.on(routes.events.EventType.block, this.onBlockImported);
+            this.chain.emitter.on(routes.events.EventType.executionPayload, this.onPayloadImported);
             this.network.events.on(NetworkEvent.peerConnected, this.onPeerConnected);
             this.network.events.on(NetworkEvent.peerDisconnected, this.onPeerDisconnected);
             this.subscribedToNetworkEvents = true;
@@ -104,9 +135,14 @@ export class BlockInputSync {
     }
     unsubscribeFromNetwork() {
         this.logger.verbose("BlockInputSync disabled.");
+        this.clearRateLimitBackoffTimer();
         this.chain.emitter.off(ChainEvent.unknownBlockRoot, this.onUnknownBlockRoot);
+        this.chain.emitter.off(ChainEvent.unknownEnvelopeBlockRoot, this.onUnknownEnvelopeBlockRoot);
         this.chain.emitter.off(ChainEvent.incompleteBlockInput, this.onIncompleteBlockInput);
+        this.chain.emitter.off(ChainEvent.incompletePayloadEnvelope, this.onIncompletePayloadEnvelope);
         this.chain.emitter.off(ChainEvent.blockUnknownParent, this.onUnknownParent);
+        this.chain.emitter.off(routes.events.EventType.block, this.onBlockImported);
+        this.chain.emitter.off(routes.events.EventType.executionPayload, this.onPayloadImported);
         this.network.events.off(NetworkEvent.peerConnected, this.onPeerConnected);
         this.network.events.off(NetworkEvent.peerDisconnected, this.onPeerDisconnected);
         this.subscribedToNetworkEvents = false;
@@ -145,12 +181,54 @@ export class BlockInputSync {
             this.logger.debug("Error handling incompleteBlockInput event", {}, e);
         }
     };
+    onUnknownEnvelopeBlockRoot = (data) => {
+        try {
+            this.addByPayloadRootHex(data.rootHex, data.peer);
+            this.triggerUnknownBlockSearch();
+            this.metrics?.blockInputSync.requests.inc({ type: PendingBlockType.UNKNOWN_DATA });
+            this.metrics?.blockInputSync.source.inc({ source: data.source });
+        }
+        catch (e) {
+            this.logger.debug("Error handling unknownEnvelopeBlockRoot event", {}, e);
+        }
+    };
+    onIncompletePayloadEnvelope = (data) => {
+        try {
+            this.addByPayloadInput(data.payloadInput, data.peer);
+            this.triggerUnknownBlockSearch();
+            this.metrics?.blockInputSync.requests.inc({ type: PendingBlockType.UNKNOWN_DATA });
+            this.metrics?.blockInputSync.source.inc({ source: data.source });
+        }
+        catch (e) {
+            this.logger.debug("Error handling incompletePayloadEnvelope event", {}, e);
+        }
+    };
     /**
      * Process an unknownBlockParent event and register the block in `pendingBlocks` Map.
      */
     onUnknownParent = (data) => {
         try {
-            this.addByRootHex(data.blockInput.parentRootHex, data.peer);
+            const missingDependency = this.getMissingBlockDependency(data.blockInput);
+            if (missingDependency.kind === "invalidParentPayload") {
+                this.addByBlockInput(data.blockInput, data.peer);
+                const pendingBlock = this.pendingBlocks.get(data.blockInput.blockRootHex);
+                if (pendingBlock && isPendingBlockInput(pendingBlock)) {
+                    this.logger.debug("Ignoring block with conflicting parent payload hash", {
+                        slot: pendingBlock.blockInput.slot,
+                        root: pendingBlock.blockInput.blockRootHex,
+                        parentRoot: missingDependency.parentRootHex,
+                        parentBlockHash: missingDependency.parentBlockHashHex,
+                    });
+                    this.removeAndDownScoreAllDescendants(pendingBlock);
+                }
+                return;
+            }
+            if (missingDependency.kind === "parentPayload") {
+                this.addByPayloadRootHex(missingDependency.rootHex, data.peer);
+            }
+            else if (missingDependency.kind === "parentBlock") {
+                this.addByRootHex(missingDependency.rootHex, data.peer);
+            }
             this.addByBlockInput(data.blockInput, data.peer);
             this.triggerUnknownBlockSearch();
             this.metrics?.blockInputSync.requests.inc({ type: PendingBlockType.UNKNOWN_PARENT });
@@ -160,8 +238,18 @@ export class BlockInputSync {
             this.logger.debug("Error handling unknownParent event", {}, e);
         }
     };
+    onBlockImported = () => {
+        if (this.pendingPayloads.size > 0) {
+            this.triggerUnknownBlockSearch();
+        }
+    };
+    onPayloadImported = ({ blockRoot, }) => {
+        this.pendingPayloads.delete(blockRoot);
+        this.triggerUnknownBlockSearch();
+    };
     addByRootHex = (rootHex, peerIdStr) => {
         let pendingBlock = this.pendingBlocks.get(rootHex);
+        let added = false;
         if (!pendingBlock) {
             pendingBlock = {
                 status: PendingBlockInputStatus.pending,
@@ -170,6 +258,7 @@ export class BlockInputSync {
                 timeAddedSec: Date.now() / 1000,
             };
             this.pendingBlocks.set(rootHex, pendingBlock);
+            added = true;
             this.logger.verbose("Added new rootHex to BlockInputSync.pendingBlocks", {
                 root: pendingBlock.rootHex,
                 peerIdStr: peerIdStr ?? "unknown peer",
@@ -184,6 +273,7 @@ export class BlockInputSync {
         if (prunedItemCount > 0) {
             this.logger.verbose(`Pruned ${prunedItemCount} items from BlockInputSync.pendingBlocks`);
         }
+        return added;
     };
     addByBlockInput = (blockInput, peerIdStr) => {
         let pendingBlock = this.pendingBlocks.get(blockInput.blockRootHex);
@@ -211,6 +301,43 @@ export class BlockInputSync {
             this.logger.verbose(`Pruned ${prunedItemCount} items from BlockInputSync.pendingBlocks`);
         }
     };
+    addByPayloadRootHex = (rootHex, peerIdStr) => {
+        let pendingPayload = this.pendingPayloads.get(rootHex);
+        let added = false;
+        if (!pendingPayload) {
+            pendingPayload = {
+                status: PendingPayloadInputStatus.pending,
+                rootHex,
+                peerIdStrings: new Set(),
+                timeAddedSec: Date.now() / 1000,
+            };
+            this.pendingPayloads.set(rootHex, pendingPayload);
+            added = true;
+            this.logger.verbose("Added new payload rootHex to BlockInputSync.pendingPayloads", {
+                root: rootHex,
+                peerIdStr: peerIdStr ?? "unknown peer",
+            });
+        }
+        if (peerIdStr) {
+            pendingPayload.peerIdStrings.add(peerIdStr);
+        }
+        const prunedItemCount = pruneSetToMax(this.pendingPayloads, this.maxPendingBlocks);
+        if (prunedItemCount > 0) {
+            this.logger.verbose(`Pruned ${prunedItemCount} items from BlockInputSync.pendingPayloads`);
+        }
+        return added;
+    };
+    addByPayloadInput = (payloadInput, peerIdStr, envelope) => {
+        const pendingPayload = this.toPendingPayloadInput(payloadInput, this.pendingPayloads.get(payloadInput.blockRootHex), envelope);
+        if (peerIdStr) {
+            pendingPayload.peerIdStrings.add(peerIdStr);
+        }
+        this.pendingPayloads.set(payloadInput.blockRootHex, pendingPayload);
+        const prunedItemCount = pruneSetToMax(this.pendingPayloads, this.maxPendingBlocks);
+        if (prunedItemCount > 0) {
+            this.logger.verbose(`Pruned ${prunedItemCount} items from BlockInputSync.pendingPayloads`);
+        }
+    };
     onPeerConnected = (data) => {
         try {
             const peerId = data.peer;
@@ -225,49 +352,197 @@ export class BlockInputSync {
     onPeerDisconnected = (data) => {
         const peerId = data.peer;
         this.peerBalancer.onPeerDisconnected(peerId);
+        this.scheduleRateLimitBackoffRetry();
     };
+    /**
+     * Post-gloas, a locally complete block can still be blocked on its parent's execution payload lineage.
+     * Distinguish which dependency is missing so the scheduler can enqueue the right follow-up work.
+     */
+    getMissingBlockDependency(blockInput) {
+        const parentRootHex = blockInput.parentRootHex;
+        if (!this.chain.forkChoice.hasBlockHex(parentRootHex)) {
+            return { kind: "parentBlock", rootHex: parentRootHex };
+        }
+        if (!blockInput.hasBlock()) {
+            return { kind: "block", rootHex: blockInput.blockRootHex };
+        }
+        if (this.config.getForkSeq(blockInput.slot) < ForkSeq.gloas) {
+            return { kind: "ready" };
+        }
+        const block = blockInput.getBlock();
+        const parentBlockHashHex = toRootHex(block.message.body.signedExecutionPayloadBid.message.parentBlockHash);
+        if (this.chain.forkChoice.getBlockHexAndBlockHash(parentRootHex, parentBlockHashHex) !== null) {
+            return { kind: "ready" };
+        }
+        if (this.chain.forkChoice.hasPayloadHexUnsafe(parentRootHex)) {
+            return { kind: "invalidParentPayload", parentRootHex, parentBlockHashHex };
+        }
+        const parentPayloadInput = this.chain.seenPayloadEnvelopeInputCache.get(parentRootHex);
+        if (parentPayloadInput) {
+            if (parentPayloadInput.getBlockHashHex() === parentBlockHashHex) {
+                return { kind: "parentPayload", rootHex: parentRootHex };
+            }
+            return { kind: "invalidParentPayload", parentRootHex, parentBlockHashHex };
+        }
+        return { kind: "parentPayload", rootHex: parentRootHex };
+    }
+    advancePendingBlock(pendingBlock) {
+        const missingDependency = this.getMissingBlockDependency(pendingBlock.blockInput);
+        switch (missingDependency.kind) {
+            case "ready":
+                return "ready";
+            case "block":
+                pendingBlock.status = PendingBlockInputStatus.pending;
+                return "queued_block";
+            case "parentBlock": {
+                let added = this.addByRootHex(missingDependency.rootHex);
+                for (const peerIdStr of pendingBlock.peerIdStrings) {
+                    added = this.addByRootHex(missingDependency.rootHex, peerIdStr) || added;
+                }
+                return added ? "queued_parent_block" : "blocked";
+            }
+            case "parentPayload": {
+                let added = this.addByPayloadRootHex(missingDependency.rootHex);
+                for (const peerIdStr of pendingBlock.peerIdStrings) {
+                    added = this.addByPayloadRootHex(missingDependency.rootHex, peerIdStr) || added;
+                }
+                return added ? "queued_parent_payload" : "blocked";
+            }
+            case "invalidParentPayload":
+                this.logger.debug("Removing block with conflicting parent payload hash", {
+                    slot: pendingBlock.blockInput.slot,
+                    root: pendingBlock.blockInput.blockRootHex,
+                    parentRoot: missingDependency.parentRootHex,
+                    parentBlockHash: missingDependency.parentBlockHashHex,
+                });
+                this.removeAndDownScoreAllDescendants(pendingBlock);
+                return "removed";
+        }
+    }
+    toPendingPayloadInput(payloadInput, previous, envelope) {
+        // Normalize every payload queueing path into the same cache shape while preserving first-seen
+        // timing and peer provenance from any earlier by-root or envelope-only entry.
+        const queuedEnvelope = envelope ?? (previous && isPendingPayloadEnvelope(previous) ? previous.envelope : undefined);
+        if (queuedEnvelope && !payloadInput.hasPayloadEnvelope()) {
+            payloadInput.addPayloadEnvelope({
+                envelope: queuedEnvelope,
+                source: PayloadEnvelopeInputSource.byRoot,
+                seenTimestampSec: Date.now() / 1000,
+            });
+        }
+        return {
+            status: payloadInput.isComplete() ? PendingPayloadInputStatus.downloaded : PendingPayloadInputStatus.pending,
+            payloadInput,
+            timeAddedSec: previous?.timeAddedSec ?? Date.now() / 1000,
+            timeSyncedSec: payloadInput.isComplete() ? Date.now() / 1000 : undefined,
+            peerIdStrings: new Set(previous?.peerIdStrings ?? []),
+        };
+    }
     /**
      * Gather tip parent blocks with unknown parent and do a search for all of them
      */
     triggerUnknownBlockSearch = () => {
         // Cheap early stop to prevent calling the network.getConnectedPeers()
-        if (this.pendingBlocks.size === 0) {
+        if (!this.subscribedToNetworkEvents || (this.pendingBlocks.size === 0 && this.pendingPayloads.size === 0)) {
             return;
         }
-        // If the node loses all peers with pending unknown blocks, the sync will stall
+        // If the node loses all peers with pending unknown blocks or payloads, the sync will stall
         const connectedPeers = this.network.getConnectedPeers();
-        if (connectedPeers.length === 0) {
-            this.logger.debug("No connected peers, skipping unknown block search.");
-            return;
-        }
+        const hasConnectedPeers = connectedPeers.length > 0;
         const { unknowns, ancestors } = getUnknownAndAncestorBlocks(this.pendingBlocks);
-        // it's rare when there is no unknown block
-        // see https://github.com/ChainSafe/lodestar/issues/5649#issuecomment-1594213550
-        if (unknowns.length === 0) {
-            let processedBlocks = 0;
-            for (const block of ancestors) {
-                // when this happens, it's likely the block and parent block are processed by head sync
-                if (this.chain.forkChoice.hasBlockHex(block.blockInput.parentRootHex)) {
+        let processedBlocks = 0;
+        let shouldRerunBlockSearch = false;
+        for (const block of ancestors) {
+            const advanceResult = this.advancePendingBlock(block);
+            switch (advanceResult) {
+                case "ready":
                     processedBlocks++;
-                    this.processBlock(block).catch((e) => {
+                    this.processReadyBlock(block).catch((e) => {
                         this.logger.debug("Unexpected error - process old downloaded block", {}, e);
                     });
+                    break;
+                case "queued_block":
+                case "queued_parent_block":
+                    shouldRerunBlockSearch = true;
+                    break;
+                case "queued_parent_payload":
+                case "blocked":
+                case "removed":
+                    break;
+            }
+        }
+        if (unknowns.length > 0) {
+            if (!hasConnectedPeers) {
+                this.logger.debug("No connected peers, skipping unknown block download.");
+            }
+            else {
+                // Most of the time there is exactly 1 unknown block
+                for (const block of unknowns) {
+                    this.downloadBlock(block).catch((e) => {
+                        this.logger.debug("Unexpected error - downloadBlock", { root: getBlockInputSyncCacheItemRootHex(block) }, e);
+                    });
                 }
             }
+        }
+        else if (ancestors.length > 0) {
+            // It's rare when there is no unknown block
+            // see https://github.com/ChainSafe/lodestar/issues/5649#issuecomment-1594213550
             this.logger.verbose("No unknown block, process ancestor downloaded blocks", {
                 pendingBlocks: this.pendingBlocks.size,
                 ancestorBlocks: ancestors.length,
                 processedBlocks,
             });
-            return;
         }
-        // most of the time there is exactly 1 unknown block
-        for (const block of unknowns) {
-            this.downloadBlock(block).catch((e) => {
-                this.logger.debug("Unexpected error - downloadBlock", { root: getBlockInputSyncCacheItemRootHex(block) }, e);
+        // Blocks can unblock payloads and payloads can unblock blocks, so every scheduler pass services both queues.
+        for (const payload of Array.from(this.pendingPayloads.values())) {
+            if (isPendingPayloadInput(payload) && payload.status === PendingPayloadInputStatus.downloaded) {
+                this.processPayload(payload).catch((e) => {
+                    this.logger.debug("Unexpected error - process downloaded payload", {}, e);
+                });
+                continue;
+            }
+            if (isPendingPayloadEnvelope(payload)) {
+                this.reconcilePayloadEnvelope(payload).catch((e) => {
+                    this.logger.debug("Unexpected error - reconcile pending payload envelope", {}, e);
+                });
+                continue;
+            }
+            if (!hasConnectedPeers) {
+                this.logger.debug("No connected peers, skipping unknown payload download.", {
+                    root: getPayloadSyncCacheItemRootHex(payload),
+                });
+                continue;
+            }
+            this.downloadPayload(payload).catch((e) => {
+                this.logger.debug("Unexpected error - downloadPayload", { root: getPayloadSyncCacheItemRootHex(payload) }, e);
             });
         }
+        if (shouldRerunBlockSearch) {
+            this.triggerUnknownBlockSearch();
+        }
     };
+    scheduleRateLimitBackoffRetry() {
+        this.clearRateLimitBackoffTimer();
+        if (!this.subscribedToNetworkEvents || (this.pendingBlocks.size === 0 && this.pendingPayloads.size === 0)) {
+            return;
+        }
+        const now = Date.now();
+        const retryAt = this.peerBalancer.getNextRateLimitRetryAt();
+        if (retryAt === null) {
+            return;
+        }
+        this.rateLimitBackoffTimeout = setTimeout(() => {
+            this.rateLimitBackoffTimeout = undefined;
+            this.triggerUnknownBlockSearch();
+            this.scheduleRateLimitBackoffRetry();
+        }, Math.max(0, retryAt - now));
+    }
+    clearRateLimitBackoffTimer() {
+        if (this.rateLimitBackoffTimeout !== undefined) {
+            clearTimeout(this.rateLimitBackoffTimeout);
+            this.rateLimitBackoffTimeout = undefined;
+        }
+    }
     async downloadBlock(block) {
         if (block.status !== PendingBlockInputStatus.pending) {
             return;
@@ -297,10 +572,24 @@ export class BlockInputSync {
             };
             this.logger.verbose("Downloaded unknown block", logCtx2);
             if (parentInForkChoice) {
-                // Bingo! Process block. Add to pending blocks anyway for recycle the cache that prevents duplicate processing
-                this.processBlock(pending).catch((e) => {
-                    this.logger.debug("Unexpected error - process newly downloaded block", logCtx2, e);
-                });
+                // If the direct parent is already in fork choice, let the block state machine decide if
+                // the next step is block import, parent payload download, or branch removal.
+                const advanceResult = this.advancePendingBlock(pending);
+                switch (advanceResult) {
+                    case "ready":
+                        this.processReadyBlock(pending).catch((e) => {
+                            this.logger.debug("Unexpected error - process newly downloaded block", logCtx2, e);
+                        });
+                        break;
+                    case "queued_block":
+                    case "queued_parent_block":
+                    case "queued_parent_payload":
+                        this.triggerUnknownBlockSearch();
+                        break;
+                    case "blocked":
+                    case "removed":
+                        break;
+                }
             }
             else if (blockSlot <= finalizedSlot) {
                 // the common ancestor of the downloading chain and canonical chain should be at least the finalized slot and
@@ -319,32 +608,26 @@ export class BlockInputSync {
             }
         }
         else {
+            if (res.err instanceof UnknownBlockRateLimitedError) {
+                const pendingBlock = this.pendingBlocks.get(rootHex);
+                if (pendingBlock) {
+                    pendingBlock.status = PendingBlockInputStatus.pending;
+                }
+                this.logger.debug("Deferring unknown block download due to peer rate limit", logCtx, res.err);
+                this.scheduleRateLimitBackoffRetry();
+                return;
+            }
             this.metrics?.blockInputSync.downloadedBlocksError.inc();
             this.logger.debug("Ignoring unknown block root after many failed downloads", logCtx, res.err);
             this.removeAndDownScoreAllDescendants(block);
         }
     }
     /**
-     * Send block to the processor awaiting completition. If processed successfully, send all children to the processor.
-     * On error, remove and downscore all descendants.
-     * This function could run recursively for all descendant blocks
+     * Import a block that has already passed the local dependency checks in BlockInputSync.
+     * On error, remove and downscore descendants as appropriate for the failure type.
      */
-    async processBlock(pendingBlock) {
-        // pending block status is `downloaded` right after `downloadBlock`
-        // but could be `pending` if added by `onUnknownBlockParent` event and this function is called recursively
+    async processReadyBlock(pendingBlock) {
         if (pendingBlock.status !== PendingBlockInputStatus.downloaded) {
-            if (pendingBlock.status === PendingBlockInputStatus.pending) {
-                const connectedPeers = this.network.getConnectedPeers();
-                if (connectedPeers.length === 0) {
-                    this.logger.debug("No connected peers, skipping download block", {
-                        slot: pendingBlock.blockInput.slot,
-                        blockRoot: pendingBlock.blockInput.blockRootHex,
-                    });
-                    return;
-                }
-                // if the download is a success we'll call `processBlock()` for this block
-                await this.downloadBlock(pendingBlock);
-            }
             return;
         }
         pendingBlock.status = PendingBlockInputStatus.processing;
@@ -384,14 +667,9 @@ export class BlockInputSync {
         if (!res.err) {
             // no need to update status to "processed", delete anyway
             this.pendingBlocks.delete(pendingBlock.blockInput.blockRootHex);
-            // Send child blocks to the processor
-            for (const descendantBlock of getDescendantBlocks(pendingBlock.blockInput.blockRootHex, this.pendingBlocks)) {
-                if (isPendingBlockInput(descendantBlock)) {
-                    this.processBlock(descendantBlock).catch((e) => {
-                        this.logger.debug("Unexpected error - process descendant block", {}, e);
-                    });
-                }
-            }
+            // Re-enter the scheduler so descendants blocked on either parent blocks or parent payloads
+            // are advanced through the same dependency checks as every other pending item.
+            this.triggerUnknownBlockSearch();
         }
         else {
             const errorData = { slot: pendingBlock.blockInput.slot, root: pendingBlock.blockInput.blockRootHex };
@@ -406,6 +684,14 @@ export class BlockInputSync {
                         this.logger.debug("Attempted to process block but its parent was still unknown", errorData, res.err);
                         pendingBlock.status = PendingBlockInputStatus.downloaded;
                         break;
+                    case BlockErrorCode.PARENT_PAYLOAD_UNKNOWN:
+                        this.logger.error("processReadyBlock() hit unexpected parent payload dependency after readiness checks", {
+                            ...errorData,
+                            parentRoot: pendingBlock.blockInput.parentRootHex,
+                            parentBlockHash: res.err.type.parentBlockHash,
+                        }, res.err);
+                        pendingBlock.status = PendingBlockInputStatus.downloaded;
+                        break;
                     case BlockErrorCode.EXECUTION_ENGINE_ERROR:
                         // Removing the block(s) without penalizing the peers, hoping for EL to
                         // recover on a latter download + verify attempt
@@ -424,6 +710,312 @@ export class BlockInputSync {
             }
         }
     }
+    /**
+     * Reconcile an envelope-first payload entry once the block import path has seeded its
+     * PayloadEnvelopeInput. This may queue block download, validate the speculative envelope, or
+     * downgrade back to by-root fetching when the cached envelope does not match the imported block.
+     */
+    async reconcilePayloadEnvelope(pendingPayload) {
+        const rootHex = getPayloadSyncCacheItemRootHex(pendingPayload);
+        if (this.chain.forkChoice.hasPayloadHexUnsafe(rootHex)) {
+            this.pendingPayloads.delete(rootHex);
+            return;
+        }
+        const payloadInput = this.chain.seenPayloadEnvelopeInputCache.get(rootHex);
+        if (!payloadInput) {
+            if (!this.chain.forkChoice.hasBlockHex(rootHex)) {
+                // Column commitments live on the block body, so an envelope-only entry has to pull the block first.
+                if (!this.pendingBlocks.has(rootHex)) {
+                    this.addByRootHex(rootHex);
+                }
+                const pendingBlock = this.pendingBlocks.get(rootHex);
+                if (pendingBlock && this.network.getConnectedPeers().length > 0) {
+                    await this.downloadBlock(pendingBlock);
+                }
+            }
+            else {
+                this.logger.debug("Missing PayloadEnvelopeInput for known block while reconciling payload envelope", {
+                    root: rootHex,
+                });
+            }
+            return;
+        }
+        if (!payloadInput.hasPayloadEnvelope()) {
+            const validationResult = await wrapError(validateGossipExecutionPayloadEnvelope(this.chain, pendingPayload.envelope));
+            if (validationResult.err) {
+                this.logger.debug("Pending payload envelope failed validation after block import, refetching by root", { slot: pendingPayload.envelope.message.payload.slotNumber, root: rootHex }, validationResult.err);
+                const pendingPayloadByRoot = {
+                    status: PendingPayloadInputStatus.pending,
+                    rootHex,
+                    timeAddedSec: pendingPayload.timeAddedSec,
+                    peerIdStrings: new Set(pendingPayload.peerIdStrings),
+                };
+                this.pendingPayloads.set(rootHex, pendingPayloadByRoot);
+                if (this.network.getConnectedPeers().length > 0) {
+                    await this.downloadPayload(pendingPayloadByRoot);
+                }
+                return;
+            }
+        }
+        const upgradedPayload = this.toPendingPayloadInput(payloadInput, pendingPayload, pendingPayload.envelope);
+        this.pendingPayloads.set(rootHex, upgradedPayload);
+        if (upgradedPayload.status === PendingPayloadInputStatus.downloaded) {
+            await this.processPayload(upgradedPayload);
+            return;
+        }
+        await this.downloadPayload(upgradedPayload);
+    }
+    async downloadPayload(payload) {
+        if (isPendingPayloadEnvelope(payload)) {
+            await this.reconcilePayloadEnvelope(payload);
+            return;
+        }
+        const rootHex = getPayloadSyncCacheItemRootHex(payload);
+        if (this.chain.forkChoice.hasPayloadHexUnsafe(rootHex)) {
+            this.pendingPayloads.delete(rootHex);
+            return;
+        }
+        if (payload.status !== PendingPayloadInputStatus.pending) {
+            return;
+        }
+        const logCtx = {
+            slot: getPayloadSyncCacheItemSlot(payload),
+            root: rootHex,
+            pendingPayloads: this.pendingPayloads.size,
+        };
+        this.logger.verbose("BlockInputSync.downloadPayload()", logCtx);
+        payload.status = PendingPayloadInputStatus.fetching;
+        const res = await wrapError(this.fetchPayloadInput(payload));
+        if (!res.err) {
+            const pendingPayload = res.result;
+            this.pendingPayloads.set(getPayloadSyncCacheItemRootHex(pendingPayload), pendingPayload);
+            if (isPendingPayloadEnvelope(pendingPayload)) {
+                await this.reconcilePayloadEnvelope(pendingPayload);
+            }
+            else if (pendingPayload.status === PendingPayloadInputStatus.downloaded) {
+                await this.processPayload(pendingPayload);
+            }
+            return;
+        }
+        this.logger.debug("Ignoring unknown payload root after failed download", logCtx, res.err);
+        if (!isPendingPayloadEnvelope(payload)) {
+            payload.status = PendingPayloadInputStatus.pending;
+        }
+    }
+    async processPayload(pendingPayload) {
+        const rootHex = pendingPayload.payloadInput.blockRootHex;
+        const logCtx = { slot: pendingPayload.payloadInput.slot, root: rootHex };
+        if (pendingPayload.status !== PendingPayloadInputStatus.downloaded) {
+            this.logger.debug("Skipping payload processing before payload input is downloaded", {
+                ...logCtx,
+                status: pendingPayload.status,
+            });
+            return;
+        }
+        if (this.chain.forkChoice.hasPayloadHexUnsafe(rootHex)) {
+            this.logger.debug("Payload already imported while processing unknown payload", logCtx);
+            this.pendingPayloads.delete(rootHex);
+            return;
+        }
+        if (!this.chain.forkChoice.hasBlockHex(rootHex)) {
+            this.logger.debug("Payload input is ready before its block is in fork choice", logCtx);
+            const added = this.addByRootHex(rootHex);
+            pendingPayload.status = PendingPayloadInputStatus.downloaded;
+            if (added) {
+                this.triggerUnknownBlockSearch();
+            }
+            return;
+        }
+        pendingPayload.status = PendingPayloadInputStatus.processing;
+        const res = await wrapError(this.chain.processExecutionPayload(pendingPayload.payloadInput));
+        if (!res.err) {
+            this.logger.debug("Processed payload from unknown sync", logCtx);
+            this.pendingPayloads.delete(rootHex);
+            this.triggerUnknownBlockSearch();
+            return;
+        }
+        if (res.err instanceof PayloadError) {
+            switch (res.err.type.code) {
+                case PayloadErrorCode.BLOCK_NOT_IN_FORK_CHOICE:
+                    // Payload sync discovered the block dependency before the block queue did. Re-enqueue the
+                    // block and keep the payload ready so the scheduler can retry once the block reaches fork choice.
+                    if (this.addByRootHex(rootHex)) {
+                        this.triggerUnknownBlockSearch();
+                    }
+                    // Keep the payload out of any synchronous requeue pass; a later scheduler pass will retry it.
+                    pendingPayload.status = PendingPayloadInputStatus.downloaded;
+                    break;
+                case PayloadErrorCode.EXECUTION_ENGINE_ERROR:
+                    this.logger.debug("Execution engine error while processing payload from unknown sync", logCtx, res.err);
+                    pendingPayload.status = PendingPayloadInputStatus.downloaded;
+                    break;
+                case PayloadErrorCode.EXECUTION_ENGINE_INVALID:
+                case PayloadErrorCode.ENVELOPE_VERIFICATION_ERROR:
+                case PayloadErrorCode.INVALID_SIGNATURE:
+                    // TODO GLOAS: Decide how invalid payload inputs should eventually leave memory without
+                    // reintroducing envelope replacement / recreation flows.
+                    this.logger.debug("Error processing payload from unknown sync", logCtx, res.err);
+                    this.removePendingPayloadAndDescendants(rootHex);
+                    break;
+                default:
+                    this.logger.debug("Error processing payload from unknown sync", logCtx, res.err);
+                    this.pendingPayloads.delete(rootHex);
+            }
+            return;
+        }
+        this.logger.debug("Unknown error processing payload from unknown sync", logCtx, res.err);
+        pendingPayload.status = PendingPayloadInputStatus.downloaded;
+    }
+    /**
+     * Download payload material keyed by beacon block root. Unlike block download, payload sync may
+     * already have a locally cached envelope or partial columns, so each attempt starts from local state
+     * and only asks peers for the remaining pieces.
+     */
+    async fetchPayloadInput(cacheItem) {
+        const rootHex = getPayloadSyncCacheItemRootHex(cacheItem);
+        const blockRoot = fromHex(rootHex);
+        const excludedPeers = new Set();
+        let slot = getPayloadSyncCacheItemSlot(cacheItem);
+        let payloadInput = isPendingPayloadInput(cacheItem)
+            ? cacheItem.payloadInput
+            : this.chain.seenPayloadEnvelopeInputCache.get(rootHex);
+        let envelope = payloadInput?.hasPayloadEnvelope() ? payloadInput.getPayloadEnvelope() : undefined;
+        let i = 0;
+        let deferredByRateLimit = false;
+        while (i++ < this.getMaxDownloadAttempts()) {
+            const pendingColumns = payloadInput?.hasAllData()
+                ? new Set()
+                : new Set(payloadInput?.getMissingSampledColumnMeta().missing ?? []);
+            const peerMeta = this.peerBalancer.bestPeerForPendingColumns(pendingColumns, excludedPeers);
+            if (peerMeta === null) {
+                if (this.peerBalancer.getNextRateLimitRetryAt(pendingColumns, excludedPeers) !== null) {
+                    throw new UnknownBlockRateLimitedError(`Error fetching payload by root slot=${slot} root=${rootHex} after ${i}: peers with needed columns are rate-limited`);
+                }
+                throw Error(`Error fetching payload by root slot=${slot} root=${rootHex} after ${i}: cannot find peer with needed columns=${prettyPrintIndices(Array.from(pendingColumns))}`);
+            }
+            const { peerId, client: peerClient } = peerMeta;
+            cacheItem.peerIdStrings.add(peerId);
+            try {
+                if (!envelope) {
+                    envelope = await this.fetchExecutionPayloadEnvelope(peerId, blockRoot, rootHex);
+                    slot = envelope.message.payload.slotNumber;
+                }
+                payloadInput ??= this.chain.seenPayloadEnvelopeInputCache.get(rootHex);
+                if (!payloadInput) {
+                    if (this.chain.forkChoice.hasBlockHex(rootHex)) {
+                        throw new Error(`Missing PayloadEnvelopeInput for known block ${rootHex}`);
+                    }
+                    // Keep the validated envelope around, but wait for the block body before turning it into a full payload input.
+                    return {
+                        status: PendingPayloadInputStatus.waitingForBlock,
+                        envelope,
+                        timeAddedSec: cacheItem.timeAddedSec,
+                        peerIdStrings: cacheItem.peerIdStrings,
+                    };
+                }
+                if (!payloadInput.hasPayloadEnvelope()) {
+                    await validateGossipExecutionPayloadEnvelope(this.chain, envelope);
+                }
+                let pendingPayload = this.toPendingPayloadInput(payloadInput, cacheItem, envelope);
+                if (!pendingPayload.payloadInput.hasAllData()) {
+                    const missing = pendingPayload.payloadInput.getMissingSampledColumnMeta().missing;
+                    if (missing.length > 0) {
+                        const columnSidecars = await this.fetchPayloadColumns(peerMeta, pendingPayload.payloadInput, missing);
+                        const seenTimestampSec = Date.now() / 1000;
+                        for (const columnSidecar of columnSidecars) {
+                            if (pendingPayload.payloadInput.hasColumn(columnSidecar.index)) {
+                                continue;
+                            }
+                            pendingPayload.payloadInput.addColumn({
+                                columnSidecar,
+                                source: PayloadEnvelopeInputSource.byRoot,
+                                seenTimestampSec,
+                                peerIdStr: peerId,
+                            });
+                        }
+                        pendingPayload = this.toPendingPayloadInput(pendingPayload.payloadInput, pendingPayload);
+                    }
+                }
+                this.logger.verbose("BlockInputSync.fetchPayloadInput: successful download", {
+                    slot,
+                    rootHex,
+                    peerId,
+                    peerClient,
+                    hasPayload: pendingPayload.payloadInput.hasPayloadEnvelope(),
+                    hasAllData: pendingPayload.payloadInput.hasAllData(),
+                });
+                if (pendingPayload.status === PendingPayloadInputStatus.downloaded) {
+                    return pendingPayload;
+                }
+                cacheItem = pendingPayload;
+                payloadInput = pendingPayload.payloadInput;
+            }
+            catch (e) {
+                this.logger.debug("Error downloading payload in BlockInputSync.fetchPayloadInput", { slot, rootHex, attempt: i, peer: peerId, peerClient }, e);
+                const rateLimitedUntilMs = getRateLimitedUntilMs(e);
+                if (rateLimitedUntilMs !== null) {
+                    deferredByRateLimit = true;
+                    this.peerBalancer.onRateLimited(peerId, rateLimitedUntilMs);
+                    this.scheduleRateLimitBackoffRetry();
+                }
+                else if (e instanceof RequestError) {
+                    switch (e.type.code) {
+                        case RequestErrorCode.REQUEST_RATE_LIMITED:
+                        case RequestErrorCode.REQUEST_TIMEOUT:
+                            break;
+                        default:
+                            excludedPeers.add(peerId);
+                            break;
+                    }
+                }
+                else {
+                    excludedPeers.add(peerId);
+                }
+            }
+            finally {
+                this.peerBalancer.onRequestCompleted(peerId);
+            }
+        }
+        if (deferredByRateLimit && this.peerBalancer.getNextRateLimitRetryAt() !== null) {
+            throw new UnknownBlockRateLimitedError(`Error fetching payload with slot=${slot} root=${rootHex} after ${i - 1} attempts: peers are rate-limited`);
+        }
+        throw Error(`Error fetching payload with slot=${slot} root=${rootHex} after ${i - 1} attempts.`);
+    }
+    async fetchExecutionPayloadEnvelope(peerIdStr, blockRoot, rootHex) {
+        const response = await this.network.sendExecutionPayloadEnvelopesByRoot(peerIdStr, [blockRoot]);
+        const envelope = response.at(0);
+        if (!envelope) {
+            throw new Error(`Missing execution payload envelope for root=${rootHex}`);
+        }
+        const receivedRootHex = toRootHex(envelope.message.beaconBlockRoot);
+        if (receivedRootHex !== rootHex) {
+            throw new Error(`Execution payload envelope root mismatch requested=${rootHex} received=${receivedRootHex}`);
+        }
+        return envelope;
+    }
+    async fetchPayloadColumns(peerMeta, payloadInput, missing) {
+        const { peerId: peerIdStr } = peerMeta;
+        const peerColumns = new Set(peerMeta.custodyColumns ?? []);
+        const requestedColumns = missing.filter((columnIndex) => peerColumns.has(columnIndex));
+        if (requestedColumns.length === 0) {
+            return [];
+        }
+        const columnSidecars = (await this.network.sendDataColumnSidecarsByRoot(peerIdStr, [
+            { blockRoot: fromHex(payloadInput.blockRootHex), columns: requestedColumns },
+        ]));
+        if (columnSidecars.length === 0) {
+            throw new Error(`No data column sidecars returned for payload root=${payloadInput.blockRootHex}`);
+        }
+        const requestedColumnsSet = new Set(requestedColumns);
+        const extraColumns = columnSidecars.filter((columnSidecar) => !requestedColumnsSet.has(columnSidecar.index));
+        if (extraColumns.length > 0) {
+            throw new Error(`Received unexpected payload data columns indices=${prettyPrintIndices(extraColumns.map((column) => column.index))}`);
+        }
+        // PayloadEnvelopeInput already carries the block slot, root, and commitments, so reuse the
+        // block-based Gloas validator rather than maintaining a second payload-specific variant.
+        await validateGloasBlockDataColumnSidecars(payloadInput.slot, fromHex(payloadInput.blockRootHex), payloadInput.getBlobKzgCommitments(), columnSidecars, this.chain.metrics?.peerDas);
+        return columnSidecars;
+    }
     /**
      * From a set of shuffled peers:
      *   - fetch the block
@@ -443,12 +1035,16 @@ export class BlockInputSync {
             this.metrics?.blockInputSync.fetchBegin.observe(this.chain.clock.secFromSlot(slot, fetchStartSec));
         }
         let i = 0;
+        let deferredByRateLimit = false;
         while (i++ < this.getMaxDownloadAttempts()) {
             const pendingColumns = isPendingBlockInput(cacheItem) && isBlockInputColumns(cacheItem.blockInput)
                 ? new Set(cacheItem.blockInput.getMissingSampledColumnMeta().missing)
                 : defaultPendingColumns;
             const peerMeta = this.peerBalancer.bestPeerForPendingColumns(pendingColumns, excludedPeers);
             if (peerMeta === null) {
+                if (this.peerBalancer.getNextRateLimitRetryAt(pendingColumns, excludedPeers) !== null) {
+                    throw new UnknownBlockRateLimitedError(`Error fetching UnknownBlockRoot slot=${slot} root=${rootHex} after ${i}: peers with needed columns are rate-limited`);
+                }
                 // no more peer with needed columns to try, throw error
                 const message = `Error fetching UnknownBlockRoot slot=${slot} root=${rootHex} after ${i}: cannot find peer with needed columns=${prettyPrintIndices(Array.from(pendingColumns))}`;
                 this.metrics?.blockInputSync.fetchTimeSec.observe({ result: FetchResult.FailureTriedAllPeers }, Date.now() / 1000 - fetchStartSec);
@@ -496,14 +1092,24 @@ export class BlockInputSync {
                 else if (e instanceof RequestError) {
                     // should look into req_resp metrics in this case
                     downloadByRootMetrics?.error.inc({ code: "req_resp", client: peerClient });
-                    switch (e.type.code) {
-                        case RequestErrorCode.REQUEST_RATE_LIMITED:
-                        case RequestErrorCode.REQUEST_TIMEOUT:
-                            // do not exclude peer for these errors
-                            break;
-                        default:
-                            excludedPeers.add(peerId);
-                            break;
+                    const rateLimitedUntilMs = getRateLimitedUntilMs(e);
+                    if (rateLimitedUntilMs !== null) {
+                        deferredByRateLimit = true;
+                        this.peerBalancer.onRateLimited(peerId, rateLimitedUntilMs);
+                        this.scheduleRateLimitBackoffRetry();
+                    }
+                    else {
+                        switch (e.type.code) {
+                            case RequestErrorCode.REQUEST_RATE_LIMITED:
+                            case RequestErrorCode.RESP_RATE_LIMITED:
+                            case RequestErrorCode.REQUEST_SELF_RATE_LIMITED:
+                            case RequestErrorCode.REQUEST_TIMEOUT:
+                                // do not exclude peer for these errors
+                                break;
+                            default:
+                                excludedPeers.add(peerId);
+                                break;
+                        }
                     }
                 }
                 else {
@@ -529,6 +1135,9 @@ export class BlockInputSync {
             }
         } // end while loop over peers
         const message = `Error fetching BlockInput with slot=${slot} root=${rootHex} after ${i - 1} attempts.`;
+        if (deferredByRateLimit && this.peerBalancer.getNextRateLimitRetryAt() !== null) {
+            throw new UnknownBlockRateLimitedError(`${message} Peers are rate-limited.`);
+        }
         if (!isPendingBlockInput(cacheItem)) {
             throw Error(`${message} No block and no data was found.`);
         }
@@ -582,6 +1191,25 @@ export class BlockInputSync {
         // Prune knownBadBlocks
         pruneSetToMax(this.knownBadBlocks, MAX_KNOWN_BAD_BLOCKS);
     }
+    // Once a parent payload is invalid, every descendant waiting on that payload lineage becomes unrecoverable too.
+    removePendingPayloadAndDescendants(rootHex) {
+        // Keep PayloadEnvelopeInput resident in the seen cache. importBlock() owns that object and
+        // later validation/finalization logic decides when it can leave memory.
+        this.pendingPayloads.delete(rootHex);
+        const badPendingBlocks = getAllDescendantBlocks(rootHex, this.pendingBlocks);
+        this.metrics?.blockInputSync.removedBlocks.inc(badPendingBlocks.length);
+        for (const block of badPendingBlocks) {
+            const descendantRootHex = getBlockInputSyncCacheItemRootHex(block);
+            this.pendingBlocks.delete(descendantRootHex);
+            this.pendingPayloads.delete(descendantRootHex);
+            this.chain.seenBlockInputCache.prune(descendantRootHex);
+            this.logger.debug("Removing pending descendant after invalid parent payload", {
+                slot: getBlockInputSyncCacheItemSlot(block),
+                blockRoot: descendantRootHex,
+                parentPayloadRoot: rootHex,
+            });
+        }
+    }
     removeAllDescendants(block) {
         const rootHex = getBlockInputSyncCacheItemRootHex(block);
         const slot = getBlockInputSyncCacheItemSlot(block);
@@ -591,7 +1219,10 @@ export class BlockInputSync {
         for (const block of badPendingBlocks) {
             const rootHex = getBlockInputSyncCacheItemRootHex(block);
             this.pendingBlocks.delete(rootHex);
+            this.pendingPayloads.delete(rootHex);
             this.chain.seenBlockInputCache.prune(rootHex);
+            // Keep PayloadEnvelopeInput resident in the seen cache for consistency with the
+            // importBlock()-owned lifecycle.
             this.logger.debug("Removing bad/unknown/incomplete BlockInputSyncCacheItem", {
                 slot,
                 blockRoot: rootHex,
@@ -614,9 +1245,11 @@ export class BlockInputSync {
 export class UnknownBlockPeerBalancer {
     peersMeta;
     activeRequests;
+    rateLimitedUntilByPeer;
     constructor() {
         this.peersMeta = new Map();
         this.activeRequests = new Map();
+        this.rateLimitedUntilByPeer = new Map();
     }
     /** Trigger on each peer re-status */
     onPeerConnected(peerId, syncMeta) {
@@ -628,6 +1261,33 @@ export class UnknownBlockPeerBalancer {
     onPeerDisconnected(peerId) {
         this.peersMeta.delete(peerId);
         this.activeRequests.delete(peerId);
+        this.rateLimitedUntilByPeer.delete(peerId);
+    }
+    onRateLimited(peerId, rateLimitedUntilMs) {
+        this.rateLimitedUntilByPeer.set(peerId, rateLimitedUntilMs);
+    }
+    getNextRateLimitRetryAt(pendingColumns, excludedPeers) {
+        const now = Date.now();
+        let retryAt = null;
+        for (const [peerId, rateLimitedUntil] of this.rateLimitedUntilByPeer.entries()) {
+            if (rateLimitedUntil <= now) {
+                this.rateLimitedUntilByPeer.delete(peerId);
+                continue;
+            }
+            if (excludedPeers?.has(peerId)) {
+                continue;
+            }
+            const syncMeta = this.peersMeta.get(peerId);
+            if (syncMeta === undefined) {
+                this.rateLimitedUntilByPeer.delete(peerId);
+                continue;
+            }
+            if (pendingColumns !== undefined && !this.peerHasPendingColumns(syncMeta, pendingColumns)) {
+                continue;
+            }
+            retryAt = Math.min(retryAt ?? rateLimitedUntil, rateLimitedUntil);
+        }
+        return retryAt;
     }
     /**
      * called from fetchBlockInput() where we only have block root and nothing else
@@ -667,6 +1327,7 @@ export class UnknownBlockPeerBalancer {
         return totalActiveRequests;
     }
     filterPeers(pendingDataColumns, excludedPeers) {
+        const now = Date.now();
         let maxColumnCount = 0;
         const considerPeers = [];
         for (const [peerId, syncMeta] of this.peersMeta.entries()) {
@@ -674,11 +1335,21 @@ export class UnknownBlockPeerBalancer {
                 // made request to this peer already
                 continue;
             }
+            const rateLimitedUntil = this.rateLimitedUntilByPeer.get(peerId);
+            if (rateLimitedUntil !== undefined) {
+                if (now < rateLimitedUntil) {
+                    continue;
+                }
+                this.rateLimitedUntilByPeer.delete(peerId);
+            }
             const activeRequests = this.activeRequests.get(peerId) ?? 0;
             if (activeRequests >= MAX_CONCURRENT_REQUESTS) {
                 // should return peer with no more than MAX_CONCURRENT_REQUESTS active requests
                 continue;
             }
+            if (!this.peerHasPendingColumns(syncMeta, pendingDataColumns)) {
+                continue;
+            }
             if (pendingDataColumns.size === 0) {
                 considerPeers.push({ peerId, columnCount: 0 });
                 continue;
@@ -708,5 +1379,11 @@ export class UnknownBlockPeerBalancer {
         }
         return eligiblePeers;
     }
+    peerHasPendingColumns(syncMeta, pendingDataColumns) {
+        if (pendingDataColumns.size === 0) {
+            return true;
+        }
+        return syncMeta.custodyColumns.some((column) => pendingDataColumns.has(column));
+    }
 }
 //# sourceMappingURL=unknownBlock.js.map