@lodestar/beacon-node 1.40.0-dev.f016f9d123 → 1.40.0-dev.f58ab9b042

package/src/chain/blocks/verifyBlocksStateTransitionOnly.ts

@@ -5,9 +5,8 @@ import {
   StateHashTreeRootSource,
   stateTransition,
 } from "@lodestar/state-transition";
-import {ErrorAborted, Logger} from "@lodestar/utils";
+import {ErrorAborted, Logger, byteArrayEquals} from "@lodestar/utils";
 import {Metrics} from "../../metrics/index.js";
-import {byteArrayEquals} from "../../util/bytes.js";
 import {nextEventLoop} from "../../util/eventLoop.js";
 import {BlockError, BlockErrorCode} from "../errors/index.js";
 import {BlockProcessOpts} from "../options.js";

package/src/chain/blocks/writeBlockInputToDb.ts

@@ -44,6 +44,15 @@ export async function writeBlockInputToDb(this: BeaconChain, blocksInputs: IBloc
 
     // NOTE: Old data is pruned on archive
     if (isBlockInputColumns(blockInput)) {
+      if (!blockInput.hasComputedAllData()) {
+        // Supernodes may only have a subset of the data columns by the time the block begins to be imported
+        // because full data availability can be assumed after NUMBER_OF_COLUMNS / 2 columns are available.
+        // Here, however, all data columns must be fully available/reconstructed before persisting to the DB.
+        await blockInput.waitForComputedAllData(BLOB_AVAILABILITY_TIMEOUT).catch(() => {
+          this.logger.debug("Failed to wait for computed all data", {slot, blockRoot: blockRootHex});
+        });
+      }
+
       const {custodyColumns} = this.custodyConfig;
       const blobsLen = (block.message as fulu.BeaconBlock).body.blobKzgCommitments.length;
       let dataColumnsLen: number;

package/src/chain/chain.ts

@@ -107,12 +107,10 @@ import {SeenAttestationDatas} from "./seenCache/seenAttestationData.js";
 import {SeenBlockAttesters} from "./seenCache/seenBlockAttesters.js";
 import {SeenBlockInput} from "./seenCache/seenGossipBlockInput.js";
 import {ShufflingCache} from "./shufflingCache.js";
-import {BlockStateCacheImpl} from "./stateCache/blockStateCacheImpl.js";
 import {DbCPStateDatastore, checkpointToDatastoreKey} from "./stateCache/datastore/db.js";
 import {FileCPStateDatastore} from "./stateCache/datastore/file.js";
 import {CPStateDatastore} from "./stateCache/datastore/types.js";
 import {FIFOBlockStateCache} from "./stateCache/fifoBlockStateCache.js";
-import {InMemoryCheckpointStateCache} from "./stateCache/inMemoryCheckpointsCache.js";
 import {PersistentCheckpointStateCache} from "./stateCache/persistentCheckpointsCache.js";
 import {CheckpointStateCache} from "./stateCache/types.js";
 import {ValidatorMonitor} from "./validatorMonitor.js";
@@ -142,7 +140,7 @@ export class BeaconChain implements IBeaconChain {
   readonly logger: Logger;
   readonly metrics: Metrics | null;
   readonly validatorMonitor: ValidatorMonitor | null;
-  readonly bufferPool: BufferPool | null;
+  readonly bufferPool: BufferPool;
 
   readonly anchorStateLatestBlockSlot: Slot;
 
@@ -339,32 +337,22 @@ export class BeaconChain implements IBeaconChain {
     this.index2pubkey = index2pubkey;
 
     const fileDataStore = opts.nHistoricalStatesFileDataStore ?? true;
-    const blockStateCache = this.opts.nHistoricalStates
-      ? new FIFOBlockStateCache(this.opts, {metrics})
-      : new BlockStateCacheImpl({metrics});
-    this.bufferPool = this.opts.nHistoricalStates
-      ? new BufferPool(anchorState.type.tree_serializedSize(anchorState.node), metrics)
-      : null;
-
-    let checkpointStateCache: CheckpointStateCache;
-    this.cpStateDatastore = undefined;
-    if (this.opts.nHistoricalStates) {
-      this.cpStateDatastore = fileDataStore ? new FileCPStateDatastore(dataDir) : new DbCPStateDatastore(this.db);
-      checkpointStateCache = new PersistentCheckpointStateCache(
-        {
-          config,
-          metrics,
-          logger,
-          clock,
-          blockStateCache,
-          bufferPool: this.bufferPool,
-          datastore: this.cpStateDatastore,
-        },
-        this.opts
-      );
-    } else {
-      checkpointStateCache = new InMemoryCheckpointStateCache({metrics});
-    }
+    const blockStateCache = new FIFOBlockStateCache(this.opts, {metrics});
+    this.bufferPool = new BufferPool(anchorState.type.tree_serializedSize(anchorState.node), metrics);
+
+    this.cpStateDatastore = fileDataStore ? new FileCPStateDatastore(dataDir) : new DbCPStateDatastore(this.db);
+    const checkpointStateCache: CheckpointStateCache = new PersistentCheckpointStateCache(
+      {
+        config,
+        metrics,
+        logger,
+        clock,
+        blockStateCache,
+        bufferPool: this.bufferPool,
+        datastore: this.cpStateDatastore,
+      },
+      this.opts
+    );
 
     const {checkpoint} = computeAnchorCheckpoint(config, anchorState);
     blockStateCache.add(anchorState);
@@ -387,6 +375,7 @@ export class BeaconChain implements IBeaconChain {
       forkChoice,
       blockStateCache,
       checkpointStateCache,
+      seenBlockInputCache: this.seenBlockInputCache,
       db,
       metrics,
       validatorMonitor,
@@ -1368,13 +1357,13 @@ export class BeaconChain implements IBeaconChain {
     // TODO: Improve using regen here
     const {blockRoot, stateRoot, slot} = this.forkChoice.getHead();
     const headState = this.regen.getStateSync(stateRoot);
-    const headBlock = await this.db.block.get(fromHex(blockRoot));
-    if (headBlock == null) {
-      throw Error(`Head block ${slot} ${headBlock} is not available in database`);
+    const blockResult = await this.getBlockByRoot(blockRoot);
+    if (blockResult == null) {
+      throw Error(`Head block for ${slot} is not available in cache or database`);
     }
 
     if (headState) {
-      this.opPool.pruneAll(headBlock, headState);
+      this.opPool.pruneAll(blockResult.block, headState);
     }
 
     if (headState === null) {

package/src/chain/initState.ts

@@ -2,7 +2,7 @@ import {ChainForkConfig} from "@lodestar/config";
 import {ZERO_HASH} from "@lodestar/params";
 import {BeaconStateAllForks, computeEpochAtSlot, computeStartSlotAtEpoch} from "@lodestar/state-transition";
 import {SignedBeaconBlock, ssz} from "@lodestar/types";
-import {Logger, toHex, toRootHex} from "@lodestar/utils";
+import {Logger, byteArrayEquals, toHex, toRootHex} from "@lodestar/utils";
 import {GENESIS_SLOT} from "../constants/index.js";
 import {IBeaconDb} from "../db/index.js";
 import {Metrics} from "../metrics/index.js";
@@ -26,7 +26,7 @@ export async function persistAnchorState(
 
     const latestBlockRoot = ssz.phase0.BeaconBlockHeader.hashTreeRoot(latestBlockHeader);
 
-    if (Buffer.compare(blockRoot, latestBlockRoot) !== 0) {
+    if (!byteArrayEquals(blockRoot, latestBlockRoot)) {
       throw Error(
         `Genesis block root ${toRootHex(blockRoot)} does not match genesis state latest block root ${toRootHex(latestBlockRoot)}`
       );

package/src/chain/lightClient/index.ts

@@ -46,12 +46,11 @@ import {
   ssz,
   sszTypesFor,
 } from "@lodestar/types";
-import {Logger, MapDef, pruneSetToMax, toRootHex} from "@lodestar/utils";
+import {Logger, MapDef, byteArrayEquals, pruneSetToMax, toRootHex} from "@lodestar/utils";
 import {ZERO_HASH} from "../../constants/index.js";
 import {IBeaconDb} from "../../db/index.js";
 import {NUM_WITNESS, NUM_WITNESS_ELECTRA} from "../../db/repositories/lightclientSyncCommitteeWitness.js";
 import {Metrics} from "../../metrics/index.js";
-import {byteArrayEquals} from "../../util/bytes.js";
 import {IClock} from "../../util/clock.js";
 import {ChainEventEmitter} from "../emitter.js";
 import {LightClientServerError, LightClientServerErrorCode} from "../errors/lightClientError.js";

package/src/chain/options.ts

@@ -45,7 +45,6 @@ export type IChainOptions = BlockProcessOpts &
     broadcastValidationStrictness?: string;
     minSameMessageSignatureSetsToBatch: number;
     archiveDateEpochs?: number;
-    nHistoricalStates?: boolean;
     nHistoricalStatesFileDataStore?: boolean;
   };
 
@@ -119,7 +118,6 @@ export const defaultChainOptions: IChainOptions = {
   // batching too much may block the I/O thread so if useWorker=false, suggest this value to be 32
   // since this batch attestation work is designed to work with useWorker=true, make this the lowest value
   minSameMessageSignatureSetsToBatch: 2,
-  nHistoricalStates: true,
   // as of Feb 2025, this option turned out to be very useful:
   //   - it allows to share a persisted checkpoint state to other nodes
   //   - users can prune the persisted checkpoint state files manually to save disc space

package/src/chain/regen/interface.ts

@@ -2,7 +2,7 @@ import {routes} from "@lodestar/api";
 import {ProtoBlock} from "@lodestar/fork-choice";
 import {CachedBeaconStateAllForks} from "@lodestar/state-transition";
 import {BeaconBlock, Epoch, RootHex, Slot, phase0} from "@lodestar/types";
-import {CheckpointHex} from "../stateCache/index.js";
+import {CheckpointHex} from "../stateCache/types.js";
 
 export enum RegenCaller {
   getDuties = "getDuties",

package/src/chain/regen/queued.ts

@@ -5,8 +5,7 @@ import {BeaconBlock, Epoch, RootHex, Slot, phase0} from "@lodestar/types";
 import {Logger, toRootHex} from "@lodestar/utils";
 import {Metrics} from "../../metrics/index.js";
 import {JobItemQueue} from "../../util/queue/index.js";
-import {CheckpointHex} from "../stateCache/index.js";
-import {BlockStateCache, CheckpointStateCache} from "../stateCache/types.js";
+import {BlockStateCache, CheckpointHex, CheckpointStateCache} from "../stateCache/types.js";
 import {RegenError, RegenErrorCode} from "./errors.js";
 import {
   IStateRegenerator,

package/src/chain/regen/regen.ts

@@ -18,6 +18,7 @@ import {Metrics} from "../../metrics/index.js";
 import {nextEventLoop} from "../../util/eventLoop.js";
 import {getCheckpointFromState} from "../blocks/utils/checkpoint.js";
 import {ChainEvent, ChainEventEmitter} from "../emitter.js";
+import {SeenBlockInput} from "../seenCache/seenGossipBlockInput.js";
 import {BlockStateCache, CheckpointStateCache} from "../stateCache/types.js";
 import {ValidatorMonitor} from "../validatorMonitor.js";
 import {RegenError, RegenErrorCode} from "./errors.js";
@@ -28,6 +29,7 @@ export type RegenModules = {
   forkChoice: IForkChoice;
   blockStateCache: BlockStateCache;
   checkpointStateCache: CheckpointStateCache;
+  seenBlockInputCache: SeenBlockInput;
   config: ChainForkConfig;
   emitter: ChainEventEmitter;
   logger: Logger;
@@ -191,7 +193,10 @@ export class StateRegenerator implements IStateRegeneratorInternal {
     const protoBlocksAsc = blocksToReplay.reverse();
     for (const [i, protoBlock] of protoBlocksAsc.entries()) {
       replaySlots[i] = protoBlock.slot;
-      blockPromises[i] = this.modules.db.block.get(fromHex(protoBlock.blockRoot));
+      const blockInput = this.modules.seenBlockInputCache.get(protoBlock.blockRoot);
+      blockPromises[i] = blockInput?.hasBlock()
+        ? Promise.resolve(blockInput.getBlock())
+        : this.modules.db.block.get(fromHex(protoBlock.blockRoot));
     }
 
     const logCtx = {stateRoot, caller, replaySlots: replaySlots.join(",")};

package/src/chain/seenCache/seenGossipBlockInput.ts

@@ -3,7 +3,7 @@ import {CheckpointWithHex} from "@lodestar/fork-choice";
 import {ForkName, ForkPostFulu, ForkPreGloas, isForkPostDeneb, isForkPostFulu, isForkPostGloas} from "@lodestar/params";
 import {computeStartSlotAtEpoch} from "@lodestar/state-transition";
 import {BLSSignature, RootHex, SignedBeaconBlock, Slot, deneb, fulu} from "@lodestar/types";
-import {LodestarError, Logger, pruneSetToMax} from "@lodestar/utils";
+import {LodestarError, Logger, byteArrayEquals, pruneSetToMax} from "@lodestar/utils";
 import {Metrics} from "../../metrics/metrics.js";
 import {IClock} from "../../util/clock.js";
 import {CustodyConfig} from "../../util/dataColumns.js";
@@ -344,7 +344,7 @@ export class SeenBlockInput {
       return false;
     }
     // Only consider verified if the signature matches
-    return Buffer.compare(cachedSignature, signature) === 0;
+    return byteArrayEquals(cachedSignature, signature);
   }
 
   /**
@@ -379,7 +379,7 @@ export class SeenBlockInput {
     let itemsToDelete = this.blockInputs.size - MAX_BLOCK_INPUT_CACHE_SIZE;
 
     if (itemsToDelete > 0) {
-      const sorted = [...this.blockInputs.entries()].sort((a, b) => b[1].slot - a[1].slot);
+      const sorted = [...this.blockInputs.entries()].sort((a, b) => a[1].slot - b[1].slot);
       for (const [rootHex] of sorted) {
         this.blockInputs.delete(rootHex);
         itemsToDelete--;

package/src/chain/serializeState.ts

@@ -20,7 +20,8 @@ export async function serializeState<T>(
       stateBytes = bufferWithKey.buffer;
       const dataView = new DataView(stateBytes.buffer, stateBytes.byteOffset, stateBytes.byteLength);
       state.serializeToBytes({uint8Array: stateBytes, dataView}, 0);
-      return processFn(stateBytes);
+      // Await to ensure buffer is not released back to pool until processFn completes
+      return await processFn(stateBytes);
     }
     // release the buffer back to the pool automatically
   }

package/src/chain/stateCache/index.ts

@@ -1,3 +1 @@
-export * from "./blockStateCacheImpl.js";
 export * from "./fifoBlockStateCache.js";
-export * from "./inMemoryCheckpointsCache.js";

package/src/chain/stateCache/persistentCheckpointsCache.ts

@@ -31,7 +31,7 @@ type PersistentCheckpointStateCacheModules = {
   signal?: AbortSignal;
   datastore: CPStateDatastore;
   blockStateCache: BlockStateCache;
-  bufferPool?: BufferPool | null;
+  bufferPool?: BufferPool;
 };
 
 /** checkpoint serialized as a string */
@@ -119,7 +119,7 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
   private readonly maxEpochsOnDisk: number;
   private readonly datastore: CPStateDatastore;
   private readonly blockStateCache: BlockStateCache;
-  private readonly bufferPool?: BufferPool | null;
+  private readonly bufferPool?: BufferPool;
 
   constructor(
     {
@@ -851,6 +851,10 @@ export function toCheckpointHex(checkpoint: phase0.Checkpoint): CheckpointHex {
   };
 }
 
+export function toCheckpointKey(cp: CheckpointHex): string {
+  return `${cp.rootHex}:${cp.epoch}`;
+}
+
 function toCacheKey(cp: CheckpointHex | phase0.Checkpoint): CacheKey {
   if (isCheckpointHex(cp)) {
     return `${cp.rootHex}_${cp.epoch}`;

package/src/chain/validation/blobSidecar.ts

@@ -12,7 +12,7 @@ import {
   getBlockHeaderProposerSignatureSetByParentStateSlot,
 } from "@lodestar/state-transition";
 import {BlobIndex, Root, Slot, SubnetID, deneb, ssz} from "@lodestar/types";
-import {toRootHex, verifyMerkleBranch} from "@lodestar/utils";
+import {byteArrayEquals, toRootHex, verifyMerkleBranch} from "@lodestar/utils";
 import {kzg} from "../../util/kzg.js";
 import {BlobSidecarErrorCode, BlobSidecarGossipError, BlobSidecarValidationError} from "../errors/blobSidecarError.js";
 import {GossipAction} from "../errors/gossipValidation.js";
@@ -226,7 +226,7 @@ export async function validateBlockBlobSidecars(
   const firstSidecarSignedBlockHeader = blobSidecars[0].signedBlockHeader;
   const firstSidecarBlockHeader = firstSidecarSignedBlockHeader.message;
   const firstBlockRoot = ssz.phase0.BeaconBlockHeader.hashTreeRoot(firstSidecarBlockHeader);
-  if (Buffer.compare(blockRoot, firstBlockRoot) !== 0) {
+  if (!byteArrayEquals(blockRoot, firstBlockRoot)) {
     throw new BlobSidecarValidationError(
       {
         code: BlobSidecarErrorCode.INCORRECT_BLOCK,

package/src/chain/validation/block.ts

@@ -138,11 +138,10 @@ export async function validateGossipBlock(
   // in forky condition, make sure to populate ShufflingCache with regened state
   chain.shufflingCache.processState(blockState);
 
-  // Extra conditions for merge fork blocks
   // [REJECT] The block's execution payload timestamp is correct with respect to the slot
   // -- i.e. execution_payload.timestamp == compute_timestamp_at_slot(state, block.slot).
   if (isForkPostBellatrix(fork) && !isForkPostGloas(fork)) {
-    if (!isExecutionBlockBodyType(block.body)) throw Error("Not merge block type");
+    if (!isExecutionBlockBodyType(block.body)) throw Error("Not execution block body type");
     const executionPayload = block.body.executionPayload;
     if (isExecutionStateType(blockState) && isExecutionEnabled(blockState, block)) {
       const expectedTimestamp = computeTimeAtSlot(config, blockSlot, chain.genesisTime);

package/src/chain/validation/dataColumnSidecar.ts

@@ -11,7 +11,7 @@ import {
   getBlockHeaderProposerSignatureSetByParentStateSlot,
 } from "@lodestar/state-transition";
 import {Root, Slot, SubnetID, fulu, ssz} from "@lodestar/types";
-import {toRootHex, verifyMerkleBranch} from "@lodestar/utils";
+import {byteArrayEquals, toRootHex, verifyMerkleBranch} from "@lodestar/utils";
 import {Metrics} from "../../metrics/metrics.js";
 import {kzg} from "../../util/kzg.js";
 import {
@@ -318,7 +318,7 @@ export async function validateBlockDataColumnSidecars(
   const firstSidecarSignedBlockHeader = dataColumnSidecars[0].signedBlockHeader;
   const firstSidecarBlockHeader = firstSidecarSignedBlockHeader.message;
   const firstBlockRoot = ssz.phase0.BeaconBlockHeader.hashTreeRoot(firstSidecarBlockHeader);
-  if (Buffer.compare(blockRoot, firstBlockRoot) !== 0) {
+  if (!byteArrayEquals(blockRoot, firstBlockRoot)) {
     throw new DataColumnSidecarValidationError(
       {
         code: DataColumnSidecarErrorCode.INCORRECT_BLOCK,

package/src/network/core/networkCore.ts

@@ -454,6 +454,18 @@ export class NetworkCore implements INetworkCore {
     await this.libp2p.hangUp(peerIdFromString(peerIdStr));
   }
 
+  async addDirectPeer(peer: routes.lodestar.DirectPeer): Promise<string | null> {
+    return this.gossip.addDirectPeer(peer);
+  }
+
+  async removeDirectPeer(peerIdStr: PeerIdStr): Promise<boolean> {
+    return this.gossip.removeDirectPeer(peerIdStr);
+  }
+
+  async getDirectPeers(): Promise<string[]> {
+    return this.gossip.getDirectPeers();
+  }
+
   private _dumpPeer(peerIdStr: string, connections: Connection[]): routes.lodestar.LodestarNodePeer {
     const peerData = this.peersData.connectedPeers.get(peerIdStr);
     const fork = this.config.getForkName(this.clock.currentSlot);

package/src/network/core/networkCoreWorker.ts

@@ -153,6 +153,9 @@ const libp2pWorkerApi: NetworkWorkerApi = {
   getConnectedPeerCount: () => core.getConnectedPeerCount(),
   connectToPeer: (peer, multiaddr) => core.connectToPeer(peer, multiaddr),
   disconnectPeer: (peer) => core.disconnectPeer(peer),
+  addDirectPeer: (peer) => core.addDirectPeer(peer),
+  removeDirectPeer: (peerId) => core.removeDirectPeer(peerId),
+  getDirectPeers: () => core.getDirectPeers(),
   dumpPeers: () => core.dumpPeers(),
   dumpPeer: (peerIdStr) => core.dumpPeer(peerIdStr),
   dumpPeerScoreStats: () => core.dumpPeerScoreStats(),

package/src/network/core/networkCoreWorkerHandler.ts

@@ -247,6 +247,15 @@ export class WorkerNetworkCore implements INetworkCore {
   disconnectPeer(peer: PeerIdStr): Promise<void> {
     return this.getApi().disconnectPeer(peer);
   }
+  addDirectPeer(peer: routes.lodestar.DirectPeer): Promise<string | null> {
+    return this.getApi().addDirectPeer(peer);
+  }
+  removeDirectPeer(peerId: PeerIdStr): Promise<boolean> {
+    return this.getApi().removeDirectPeer(peerId);
+  }
+  getDirectPeers(): Promise<string[]> {
+    return this.getApi().getDirectPeers();
+  }
   dumpPeers(): Promise<routes.lodestar.LodestarNodePeer[]> {
     return this.getApi().dumpPeers();
   }

package/src/network/core/types.ts

@@ -30,6 +30,12 @@ export interface INetworkCorePublic {
   // Debug
   connectToPeer(peer: PeerIdStr, multiaddr: MultiaddrStr[]): Promise<void>;
   disconnectPeer(peer: PeerIdStr): Promise<void>;
+
+  // Direct peers management
+  addDirectPeer(peer: routes.lodestar.DirectPeer): Promise<string | null>;
+  removeDirectPeer(peerId: PeerIdStr): Promise<boolean>;
+  getDirectPeers(): Promise<string[]>;
+
   dumpPeers(): Promise<routes.lodestar.LodestarNodePeer[]>;
   dumpPeer(peerIdStr: PeerIdStr): Promise<routes.lodestar.LodestarNodePeer | undefined>;
   dumpPeerScoreStats(): Promise<PeerScoreStats>;

package/src/network/gossip/gossipsub.ts

@@ -1,7 +1,11 @@
+import {peerIdFromString} from "@libp2p/peer-id";
+import {multiaddr} from "@multiformats/multiaddr";
+import {ENR} from "@chainsafe/enr";
 import {GossipSub, GossipsubEvents} from "@chainsafe/libp2p-gossipsub";
 import {MetricsRegister, TopicLabel, TopicStrToLabel} from "@chainsafe/libp2p-gossipsub/metrics";
 import {PeerScoreParams} from "@chainsafe/libp2p-gossipsub/score";
-import {SignaturePolicy, TopicStr} from "@chainsafe/libp2p-gossipsub/types";
+import {AddrInfo, SignaturePolicy, TopicStr} from "@chainsafe/libp2p-gossipsub/types";
+import {routes} from "@lodestar/api";
 import {BeaconConfig, ForkBoundary} from "@lodestar/config";
 import {ATTESTATION_SUBNET_COUNT, SLOTS_PER_EPOCH, SYNC_COMMITTEE_SUBNET_COUNT} from "@lodestar/params";
 import {SubnetID} from "@lodestar/types";
@@ -55,6 +59,12 @@ export type Eth2GossipsubOpts = {
   disableFloodPublish?: boolean;
   skipParamsLog?: boolean;
   disableLightClientServer?: boolean;
+  /**
+   * Direct peers for GossipSub - these peers maintain permanent mesh connections without GRAFT/PRUNE.
+   * Supports multiaddr strings with peer ID (e.g., "/ip4/192.168.1.1/tcp/9000/p2p/16Uiu2HAmKLhW7...")
+   * or ENR strings (e.g., "enr:-IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOo...")
+   */
+  directPeers?: string[];
 };
 
 export type ForkBoundaryLabel = string;
@@ -78,6 +88,7 @@ export class Eth2Gossipsub extends GossipSub {
   private readonly logger: Logger;
   private readonly peersData: PeersData;
   private readonly events: NetworkEventBus;
+  private readonly libp2p: Libp2p;
 
   // Internal caches
   private readonly gossipTopicCache: GossipTopicCache;
@@ -97,6 +108,9 @@ export class Eth2Gossipsub extends GossipSub {
       );
     }
 
+    // Parse direct peers from multiaddr strings to AddrInfo objects
+    const directPeers = parseDirectPeers(opts.directPeers ?? [], logger);
+
     // Gossipsub parameters defined here:
     // https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/p2p-interface.md#the-gossip-domain-gossipsub
     super(modules.libp2p.services.components, {
@@ -106,6 +120,7 @@ export class Eth2Gossipsub extends GossipSub {
       Dlo: gossipsubDLow ?? GOSSIP_D_LOW,
       Dhi: gossipsubDHigh ?? GOSSIP_D_HIGH,
       Dlazy: 6,
+      directPeers,
       heartbeatInterval: GOSSIPSUB_HEARTBEAT_INTERVAL,
       fanoutTTL: 60 * 1000,
       mcacheLength: 6,
@@ -146,6 +161,7 @@ export class Eth2Gossipsub extends GossipSub {
     this.logger = logger;
     this.peersData = peersData;
     this.events = events;
+    this.libp2p = modules.libp2p;
     this.gossipTopicCache = gossipTopicCache;
 
     this.addEventListener("gossipsub:message", this.onGossipsubMessage.bind(this));
@@ -328,6 +344,64 @@ export class Eth2Gossipsub extends GossipSub {
       this.reportMessageValidationResult(data.msgId, data.propagationSource, data.acceptance);
     });
   }
+
+  /**
+   * Add a peer as a direct peer at runtime. Accepts multiaddr with peer ID or ENR string.
+   * Direct peers maintain permanent mesh connections without GRAFT/PRUNE negotiation.
+   */
+  async addDirectPeer(peerStr: routes.lodestar.DirectPeer): Promise<string | null> {
+    const parsed = parseDirectPeers([peerStr], this.logger);
+    if (parsed.length === 0) {
+      return null;
+    }
+
+    const {id: peerId, addrs} = parsed[0];
+    const peerIdStr = peerId.toString();
+
+    // Prevent adding self as a direct peer
+    if (peerId.equals(this.libp2p.peerId)) {
+      this.logger.warn("Cannot add self as a direct peer", {peerId: peerIdStr});
+      return null;
+    }
+
+    // Direct peers need addresses to connect - reject if none provided
+    if (addrs.length === 0) {
+      this.logger.warn("Cannot add direct peer without addresses", {peerId: peerIdStr});
+      return null;
+    }
+
+    // Add addresses to peer store first so we can connect
+    try {
+      await this.libp2p.peerStore.merge(peerId, {multiaddrs: addrs});
+    } catch (e) {
+      this.logger.warn("Failed to add direct peer addresses to peer store", {peerId: peerIdStr}, e as Error);
+      return null;
+    }
+
+    // Add to direct peers set only after addresses are stored
+    this.direct.add(peerIdStr);
+
+    this.logger.info("Added direct peer via API", {peerId: peerIdStr});
+    return peerIdStr;
+  }
+
+  /**
+   * Remove a peer from direct peers.
+   */
+  removeDirectPeer(peerIdStr: string): boolean {
+    const removed = this.direct.delete(peerIdStr);
+    if (removed) {
+      this.logger.info("Removed direct peer via API", {peerId: peerIdStr});
+    }
+    return removed;
+  }
+
+  /**
+   * Get list of current direct peer IDs.
+   */
+  getDirectPeers(): string[] {
+    return Array.from(this.direct);
+  }
 }
 
 /**
@@ -381,3 +455,75 @@ function getForkBoundaryLabel(boundary: ForkBoundary): ForkBoundaryLabel {
 
   return label;
 }
+
+/**
+ * Parse direct peer strings into AddrInfo objects for GossipSub.
+ * Direct peers maintain permanent mesh connections without GRAFT/PRUNE negotiation.
+ *
+ * Supported formats:
+ * - Multiaddr with peer ID: `/ip4/192.168.1.1/tcp/9000/p2p/16Uiu2HAmKLhW7...`
+ * - ENR: `enr:-IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOo...`
+ *
+ * For multiaddrs, the string must contain a /p2p/ component with the peer ID.
+ * For ENRs, the TCP multiaddr and peer ID are extracted from the encoded record.
+ */
+export function parseDirectPeers(directPeerStrs: routes.lodestar.DirectPeer[], logger: Logger): AddrInfo[] {
+  const directPeers: AddrInfo[] = [];
+
+  for (const peerStr of directPeerStrs) {
+    // Check if this is an ENR (starts with "enr:")
+    if (peerStr.startsWith("enr:")) {
+      try {
+        const enr = ENR.decodeTxt(peerStr);
+        const peerId = enr.peerId;
+
+        // Get TCP multiaddr from ENR
+        const multiaddrTCP = enr.getLocationMultiaddr("tcp");
+        if (!multiaddrTCP) {
+          logger.warn("ENR does not contain TCP multiaddr", {enr: peerStr});
+          continue;
+        }
+
+        directPeers.push({
+          id: peerId,
+          addrs: [multiaddrTCP],
+        });
+
+        logger.info("Added direct peer from ENR", {peerId: peerId.toString(), addr: multiaddrTCP.toString()});
+      } catch (e) {
+        logger.warn("Failed to parse direct peer ENR", {enr: peerStr}, e as Error);
+      }
+    } else {
+      // Parse as multiaddr
+      try {
+        const ma = multiaddr(peerStr);
+
+        const peerIdStr = ma.getPeerId();
+        if (!peerIdStr) {
+          logger.warn("Direct peer multiaddr must contain /p2p/ component with peer ID", {multiaddr: peerStr});
+          continue;
+        }
+
+        try {
+          const peerId = peerIdFromString(peerIdStr);
+
+          // Get the address without the /p2p/ component
+          const addr = ma.decapsulate("/p2p/" + peerIdStr);
+
+          directPeers.push({
+            id: peerId,
+            addrs: [addr],
+          });
+
+          logger.info("Added direct peer", {peerId: peerIdStr, addr: addr.toString()});
+        } catch (e) {
+          logger.warn("Invalid peer ID in direct peer multiaddr", {multiaddr: peerStr, peerId: peerIdStr}, e as Error);
+        }
+      } catch (e) {
+        logger.warn("Failed to parse direct peer multiaddr", {multiaddr: peerStr}, e as Error);
+      }
+    }
+  }
+
+  return directPeers;
+}

package/src/network/network.ts

@@ -641,6 +641,18 @@ export class Network implements INetwork {
     return this.core.disconnectPeer(peer);
   }
 
+  addDirectPeer(peer: routes.lodestar.DirectPeer): Promise<string | null> {
+    return this.core.addDirectPeer(peer);
+  }
+
+  removeDirectPeer(peerId: string): Promise<boolean> {
+    return this.core.removeDirectPeer(peerId);
+  }
+
+  getDirectPeers(): Promise<string[]> {
+    return this.core.getDirectPeers();
+  }
+
   dumpPeer(peerIdStr: string): Promise<routes.lodestar.LodestarNodePeer | undefined> {
     return this.core.dumpPeer(peerIdStr);
   }

package/src/network/options.ts

@@ -15,6 +15,12 @@ export interface NetworkOptions
     Omit<Eth2GossipsubOpts, "disableLightClientServer"> {
   localMultiaddrs: string[];
   bootMultiaddrs?: string[];
+  /**
+   * Direct peers for GossipSub - these peers maintain permanent mesh connections without GRAFT/PRUNE.
+   * Format: multiaddr strings with peer ID, e.g., "/ip4/192.168.1.1/tcp/9000/p2p/16Uiu2HAmKLhW7..."
+   * Both peers must configure each other as direct peers for the feature to work properly.
+   */
+  directPeers?: string[];
   subscribeAllSubnets?: boolean;
   mdns?: boolean;
   connectToDiscv5Bootnodes?: boolean;