@lodestar/beacon-node 1.40.0-dev.9defa5c09b → 1.40.0-dev.b87b37f4d0

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);
@@ -158,7 +157,7 @@ export async function validateGossipBlock(
 
   // [REJECT] The proposer signature, signed_beacon_block.signature, is valid with respect to the proposer_index pubkey.
   if (!chain.seenBlockInputCache.isVerifiedProposerSignature(blockSlot, blockRoot, signedBlock.signature)) {
-    const signatureSet = getBlockProposerSignatureSet(chain.config, chain.index2pubkey, signedBlock);
+    const signatureSet = getBlockProposerSignatureSet(chain.config, signedBlock);
     // Don't batch so verification is not delayed
     if (!(await chain.bls.verifySignatureSets([signatureSet], {verifyOnMainThread: true}))) {
       throw new BlockGossipError(GossipAction.REJECT, {

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 {
@@ -136,7 +136,6 @@ export async function validateGossipDataColumnSidecar(
   if (!chain.seenBlockInputCache.isVerifiedProposerSignature(blockHeader.slot, blockRootHex, signature)) {
     const signatureSet = getBlockHeaderProposerSignatureSetByParentStateSlot(
       chain.config,
-      chain.index2pubkey,
       blockState.slot,
       dataColumnSidecar.signedBlockHeader
     );
@@ -319,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,
@@ -337,11 +336,7 @@ export async function validateBlockDataColumnSidecars(
     const slot = firstSidecarSignedBlockHeader.message.slot;
     const signature = firstSidecarSignedBlockHeader.signature;
     if (!chain.seenBlockInputCache.isVerifiedProposerSignature(slot, rootHex, signature)) {
-      const signatureSet = getBlockHeaderProposerSignatureSetByHeaderSlot(
-        chain.config,
-        chain.index2pubkey,
-        firstSidecarSignedBlockHeader
-      );
+      const signatureSet = getBlockHeaderProposerSignatureSetByHeaderSlot(chain.config, firstSidecarSignedBlockHeader);
 
       if (
         !(await chain.bls.verifySignatureSets([signatureSet], {

package/src/chain/validation/executionPayloadBid.ts

@@ -53,7 +53,8 @@ async function validateExecutionPayloadBid(
 
   // [REJECT] `bid.builder_index` is a valid/active builder index -- i.e.
   // `is_active_builder(state, bid.builder_index)` returns `True`.
-  if (!isActiveBuilder(state, bid.builderIndex)) {
+  const builder = state.builders.getReadonly(bid.builderIndex);
+  if (!isActiveBuilder(builder, state.finalizedCheckpoint.epoch)) {
     throw new ExecutionPayloadBidError(GossipAction.REJECT, {
       code: ExecutionPayloadBidErrorCode.BUILDER_NOT_ELIGIBLE,
       builderIndex: bid.builderIndex,
@@ -102,7 +103,7 @@ async function validateExecutionPayloadBid(
     throw new ExecutionPayloadBidError(GossipAction.IGNORE, {
       code: ExecutionPayloadBidErrorCode.BID_TOO_HIGH,
       bidValue: bid.value,
-      builderBalance: state.builders.getReadonly(bid.builderIndex).balance,
+      builderBalance: builder.balance,
     });
   }
 
@@ -122,8 +123,8 @@ async function validateExecutionPayloadBid(
 
   // [REJECT] `signed_execution_payload_bid.signature` is valid with respect to the `bid.builder_index`.
   const signatureSet = createSingleSignatureSetFromComponents(
-    PublicKey.fromBytes(state.builders.getReadonly(bid.builderIndex).pubkey),
-    getExecutionPayloadBidSigningRoot(chain.config, state as CachedBeaconStateGloas, bid),
+    PublicKey.fromBytes(builder.pubkey),
+    getExecutionPayloadBidSigningRoot(chain.config, state.slot, bid),
     signedExecutionPayloadBid.signature
   );
 

package/src/chain/validation/payloadAttestationMessage.ts

@@ -89,7 +89,7 @@ async function validatePayloadAttestationMessage(
   // [REJECT] `payload_attestation_message.signature` is valid with respect to the validator's public key.
   const signatureSet = createSingleSignatureSetFromComponents(
     chain.index2pubkey[validatorIndex],
-    getPayloadAttestationDataSigningRoot(state, data),
+    getPayloadAttestationDataSigningRoot(chain.config, state.slot, data),
     payloadAttestationMessage.signature
   );
 

package/src/chain/validation/proposerSlashing.ts

@@ -45,12 +45,7 @@ async function validateProposerSlashing(
     });
   }
 
-  const signatureSets = getProposerSlashingSignatureSets(
-    chain.config,
-    chain.index2pubkey,
-    state.slot,
-    proposerSlashing
-  );
+  const signatureSets = getProposerSlashingSignatureSets(chain.config, state.slot, proposerSlashing);
   if (!(await chain.bls.verifySignatureSets(signatureSets, {batchable: true, priority: prioritizeBls}))) {
     throw new ProposerSlashingError(GossipAction.REJECT, {
       code: ProposerSlashingErrorCode.INVALID,

package/src/chain/validation/signatureSets/aggregateAndProof.ts

@@ -1,13 +1,7 @@
-import {PublicKey} from "@chainsafe/blst";
 import {BeaconConfig} from "@lodestar/config";
 import {DOMAIN_AGGREGATE_AND_PROOF, ForkSeq} from "@lodestar/params";
-import {
-  ISignatureSet,
-  computeSigningRoot,
-  computeStartSlotAtEpoch,
-  createSingleSignatureSetFromComponents,
-} from "@lodestar/state-transition";
-import {Epoch, SignedAggregateAndProof, ssz} from "@lodestar/types";
+import {ISignatureSet, SignatureSetType, computeSigningRoot, computeStartSlotAtEpoch} from "@lodestar/state-transition";
+import {Epoch, SignedAggregateAndProof, ValidatorIndex, ssz} from "@lodestar/types";
 
 export function getAggregateAndProofSigningRoot(
   config: BeaconConfig,
@@ -27,12 +21,13 @@ export function getAggregateAndProofSigningRoot(
 export function getAggregateAndProofSignatureSet(
   config: BeaconConfig,
   epoch: Epoch,
-  aggregator: PublicKey,
+  aggregatorIndex: ValidatorIndex,
   aggregateAndProof: SignedAggregateAndProof
 ): ISignatureSet {
-  return createSingleSignatureSetFromComponents(
-    aggregator,
-    getAggregateAndProofSigningRoot(config, epoch, aggregateAndProof),
-    aggregateAndProof.signature
-  );
+  return {
+    type: SignatureSetType.indexed,
+    index: aggregatorIndex,
+    signingRoot: getAggregateAndProofSigningRoot(config, epoch, aggregateAndProof),
+    signature: aggregateAndProof.signature,
+  };
 }

package/src/chain/validation/signatureSets/contributionAndProof.ts

@@ -3,7 +3,6 @@ import {DOMAIN_CONTRIBUTION_AND_PROOF} from "@lodestar/params";
 import {
   CachedBeaconStateAllForks,
   ISignatureSet,
-  Index2PubkeyCache,
   SignatureSetType,
   computeSigningRoot,
 } from "@lodestar/state-transition";
@@ -11,7 +10,6 @@ import {altair, ssz} from "@lodestar/types";
 
 export function getContributionAndProofSignatureSet(
   config: BeaconConfig,
-  index2pubkey: Index2PubkeyCache,
   state: CachedBeaconStateAllForks,
   signedContributionAndProof: altair.SignedContributionAndProof
 ): ISignatureSet {
@@ -22,8 +20,8 @@ export function getContributionAndProofSignatureSet(
   );
   const signingData = signedContributionAndProof.message;
   return {
-    type: SignatureSetType.single,
-    pubkey: index2pubkey[signedContributionAndProof.message.aggregatorIndex],
+    type: SignatureSetType.indexed,
+    index: signedContributionAndProof.message.aggregatorIndex,
     signingRoot: computeSigningRoot(ssz.altair.ContributionAndProof, signingData, domain),
     signature: signedContributionAndProof.signature,
   };

package/src/chain/validation/signatureSets/selectionProof.ts

@@ -1,8 +1,7 @@
-import {PublicKey} from "@chainsafe/blst";
 import {BeaconConfig} from "@lodestar/config";
 import {DOMAIN_SELECTION_PROOF} from "@lodestar/params";
-import {ISignatureSet, computeSigningRoot, createSingleSignatureSetFromComponents} from "@lodestar/state-transition";
-import {Slot, phase0, ssz} from "@lodestar/types";
+import {ISignatureSet, SignatureSetType, computeSigningRoot} from "@lodestar/state-transition";
+import {Slot, ValidatorIndex, phase0, ssz} from "@lodestar/types";
 
 export function getSelectionProofSigningRoot(config: BeaconConfig, slot: Slot): Uint8Array {
   // previously, we call `const selectionProofDomain = config.getDomain(state.slot, DOMAIN_SELECTION_PROOF, slot)`
@@ -16,12 +15,13 @@ export function getSelectionProofSigningRoot(config: BeaconConfig, slot: Slot):
 export function getSelectionProofSignatureSet(
   config: BeaconConfig,
   slot: Slot,
-  aggregator: PublicKey,
+  aggregatorIndex: ValidatorIndex,
   aggregateAndProof: phase0.SignedAggregateAndProof
 ): ISignatureSet {
-  return createSingleSignatureSetFromComponents(
-    aggregator,
-    getSelectionProofSigningRoot(config, slot),
-    aggregateAndProof.message.selectionProof
-  );
+  return {
+    type: SignatureSetType.indexed,
+    index: aggregatorIndex,
+    signingRoot: getSelectionProofSigningRoot(config, slot),
+    signature: aggregateAndProof.message.selectionProof,
+  };
 }

package/src/chain/validation/signatureSets/syncCommittee.ts

@@ -3,7 +3,6 @@ import {DOMAIN_SYNC_COMMITTEE} from "@lodestar/params";
 import {
   CachedBeaconStateAllForks,
   ISignatureSet,
-  Index2PubkeyCache,
   SignatureSetType,
   computeSigningRoot,
 } from "@lodestar/state-transition";
@@ -11,15 +10,14 @@ import {altair, ssz} from "@lodestar/types";
 
 export function getSyncCommitteeSignatureSet(
   config: BeaconConfig,
-  index2pubkey: Index2PubkeyCache,
   state: CachedBeaconStateAllForks,
   syncCommittee: altair.SyncCommitteeMessage
 ): ISignatureSet {
   const domain = config.getDomain(state.slot, DOMAIN_SYNC_COMMITTEE, syncCommittee.slot);
 
   return {
-    type: SignatureSetType.single,
-    pubkey: index2pubkey[syncCommittee.validatorIndex],
+    type: SignatureSetType.indexed,
+    index: syncCommittee.validatorIndex,
     signingRoot: computeSigningRoot(ssz.Root, syncCommittee.beaconBlockRoot, domain),
     signature: syncCommittee.signature,
   };

package/src/chain/validation/signatureSets/syncCommitteeContribution.ts

@@ -1,4 +1,3 @@
-import {PublicKey} from "@chainsafe/blst";
 import {BeaconConfig} from "@lodestar/config";
 import {DOMAIN_SYNC_COMMITTEE} from "@lodestar/params";
 import {CachedBeaconStateAltair, ISignatureSet, SignatureSetType, computeSigningRoot} from "@lodestar/state-transition";
@@ -8,12 +7,12 @@ export function getSyncCommitteeContributionSignatureSet(
   config: BeaconConfig,
   state: CachedBeaconStateAltair,
   contribution: altair.SyncCommitteeContribution,
-  pubkeys: PublicKey[]
+  participantIndices: number[]
 ): ISignatureSet {
   const domain = config.getDomain(state.slot, DOMAIN_SYNC_COMMITTEE, contribution.slot);
   return {
     type: SignatureSetType.aggregate,
-    pubkeys,
+    indices: participantIndices,
     signingRoot: computeSigningRoot(ssz.Root, contribution.beaconBlockRoot, domain),
     signature: contribution.signature,
   };

package/src/chain/validation/signatureSets/syncCommitteeSelectionProof.ts

@@ -3,7 +3,6 @@ import {DOMAIN_SYNC_COMMITTEE_SELECTION_PROOF} from "@lodestar/params";
 import {
   CachedBeaconStateAllForks,
   ISignatureSet,
-  Index2PubkeyCache,
   SignatureSetType,
   computeSigningRoot,
 } from "@lodestar/state-transition";
@@ -11,7 +10,6 @@ import {altair, ssz} from "@lodestar/types";
 
 export function getSyncCommitteeSelectionProofSignatureSet(
   config: BeaconConfig,
-  index2pubkey: Index2PubkeyCache,
   state: CachedBeaconStateAllForks,
   contributionAndProof: altair.ContributionAndProof
 ): ISignatureSet {
@@ -22,8 +20,8 @@ export function getSyncCommitteeSelectionProofSignatureSet(
     subcommitteeIndex: contributionAndProof.contribution.subcommitteeIndex,
   };
   return {
-    type: SignatureSetType.single,
-    pubkey: index2pubkey[contributionAndProof.aggregatorIndex],
+    type: SignatureSetType.indexed,
+    index: contributionAndProof.aggregatorIndex,
     signingRoot: computeSigningRoot(ssz.altair.SyncAggregatorSelectionData, signingData, domain),
     signature: contributionAndProof.selectionProof,
   };

package/src/chain/validation/syncCommittee.ts

@@ -89,7 +89,7 @@ async function validateSyncCommitteeSigOnly(
   syncCommittee: altair.SyncCommitteeMessage,
   prioritizeBls = false
 ): Promise<void> {
-  const signatureSet = getSyncCommitteeSignatureSet(chain.config, chain.index2pubkey, headState, syncCommittee);
+  const signatureSet = getSyncCommitteeSignatureSet(chain.config, headState, syncCommittee);
   if (!(await chain.bls.verifySignatureSets([signatureSet], {batchable: true, priority: prioritizeBls}))) {
     throw new SyncCommitteeError(GossipAction.REJECT, {
       code: SyncCommitteeErrorCode.INVALID_SIGNATURE,

package/src/chain/validation/syncCommitteeContributionAndProof.ts

@@ -21,7 +21,6 @@ export async function validateSyncCommitteeGossipContributionAndProof(
   const contributionAndProof = signedContributionAndProof.message;
   const {contribution, aggregatorIndex} = contributionAndProof;
   const {subcommitteeIndex, slot} = contribution;
-  const {index2pubkey} = chain;
 
   const headState = chain.getHeadState();
   validateGossipSyncCommitteeExceptSig(chain, headState, subcommitteeIndex, {
@@ -74,14 +73,13 @@ export async function validateSyncCommitteeGossipContributionAndProof(
   // i.e. state.validators[contribution_and_proof.aggregator_index].pubkey in get_sync_subcommittee_pubkeys(state, contribution.subcommittee_index).
   // > Checked in validateGossipSyncCommitteeExceptSig()
 
-  const participantPubkeys = syncCommitteeParticipantIndices.map((validatorIndex) => index2pubkey[validatorIndex]);
   const signatureSets = [
     // [REJECT] The contribution_and_proof.selection_proof is a valid signature of the SyncAggregatorSelectionData
     // derived from the contribution by the validator with index contribution_and_proof.aggregator_index.
-    getSyncCommitteeSelectionProofSignatureSet(chain.config, index2pubkey, headState, contributionAndProof),
+    getSyncCommitteeSelectionProofSignatureSet(chain.config, headState, contributionAndProof),
 
     // [REJECT] The aggregator signature, signed_contribution_and_proof.signature, is valid.
-    getContributionAndProofSignatureSet(chain.config, index2pubkey, headState, signedContributionAndProof),
+    getContributionAndProofSignatureSet(chain.config, headState, signedContributionAndProof),
 
     // [REJECT] The aggregate signature is valid for the message beacon_block_root and aggregate pubkey derived from
     // the participation info in aggregation_bits for the subcommittee specified by the contribution.subcommittee_index.
@@ -89,7 +87,7 @@ export async function validateSyncCommitteeGossipContributionAndProof(
       chain.config,
       headState as CachedBeaconStateAltair,
       contribution,
-      participantPubkeys
+      syncCommitteeParticipantIndices
     ),
   ];
 

package/src/chain/validation/voluntaryExit.ts

@@ -59,7 +59,7 @@ async function validateVoluntaryExit(
     });
   }
 
-  const signatureSet = getVoluntaryExitSignatureSet(chain.config, chain.index2pubkey, state.slot, voluntaryExit);
+  const signatureSet = getVoluntaryExitSignatureSet(chain.config, state.slot, voluntaryExit);
   if (!(await chain.bls.verifySignatureSets([signatureSet], {batchable: true, priority: prioritizeBls}))) {
     throw new VoluntaryExitError(GossipAction.REJECT, {
       code: VoluntaryExitErrorCode.INVALID_SIGNATURE,

package/src/chain/validatorMonitor.ts

@@ -347,6 +347,9 @@ export function createValidatorMonitor(
         return;
       }
 
+      // Track total balance instead of per-validator balance to reduce metric cardinality
+      let totalBalance = 0;
+
       for (const [index, monitoredValidator] of validators.entries()) {
         // We subtract two from the state of the epoch that generated these summaries.
         //
@@ -405,7 +408,7 @@ export function createValidatorMonitor(
 
         const balance = balances?.[index];
         if (balance !== undefined) {
-          validatorMonitorMetrics?.prevEpochOnChainBalance.set({index}, balance);
+          totalBalance += balance;
         }
 
         if (!summary.isPrevSourceAttester || !summary.isPrevTargetAttester || !summary.isPrevHeadAttester) {
@@ -420,6 +423,10 @@ export function createValidatorMonitor(
           });
         }
       }
+
+      if (balances !== undefined) {
+        validatorMonitorMetrics?.prevEpochOnChainBalance.set(totalBalance);
+      }
     },
 
     registerBeaconBlock(src, delaySec, block) {
@@ -1153,11 +1160,9 @@ function createValidatorMonitorMetrics(register: RegistryMetricCreator) {
     }),
 
     // Validator Monitor Metrics (per-epoch summaries)
-    // Only track prevEpochOnChainBalance per index
-    prevEpochOnChainBalance: register.gauge<{index: number}>({
+    prevEpochOnChainBalance: register.gauge({
       name: "validator_monitor_prev_epoch_on_chain_balance",
-      help: "Balance of validator after an epoch",
-      labelNames: ["index"],
+      help: "Total balance of all monitored validators after an epoch",
     }),
     prevEpochOnChainAttesterHit: register.gauge({
       name: "validator_monitor_prev_epoch_on_chain_attester_hit_total",

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);
   }