@aztec/p2p 0.0.1-commit.03f7ef2 → 0.0.1-commit.0658669b3

package/src/test-helpers/mock-pubsub.ts

@@ -19,8 +19,20 @@ import {
 
 import type { P2PConfig } from '../config.js';
 import type { MemPools } from '../mem_pools/interface.js';
-import { DummyPeerDiscoveryService, DummyPeerManager, DummyReqResp, LibP2PService } from '../services/index.js';
-import type { ReqRespInterface } from '../services/reqresp/interface.js';
+import { DummyPeerDiscoveryService, DummyPeerManager, LibP2PService } from '../services/index.js';
+import type { P2PReqRespConfig } from '../services/reqresp/config.js';
+import type { ConnectionSampler } from '../services/reqresp/connection-sampler/connection_sampler.js';
+import {
+  type ReqRespInterface,
+  type ReqRespResponse,
+  type ReqRespSubProtocol,
+  type ReqRespSubProtocolHandler,
+  type ReqRespSubProtocolHandlers,
+  type ReqRespSubProtocolValidators,
+  type SubProtocolMap,
+  responseFromBuffer,
+} from '../services/reqresp/interface.js';
+import { ReqRespStatus } from '../services/reqresp/status.js';
 import { GossipSubEvent } from '../types/index.js';
 import type { PubSubLibp2p } from '../util.js';
 
@@ -52,7 +64,7 @@ export function getMockPubSubP2PServiceFactory<T extends P2PClientType>(
     deps.logger.verbose('Creating mock PubSub service');
     const libp2p = new MockPubSub(peerId, network);
     const peerManager = new DummyPeerManager(peerId, network);
-    const reqresp: ReqRespInterface = new DummyReqResp();
+    const reqresp: ReqRespInterface = new MockReqResp(peerId, network);
     const peerDiscoveryService = new DummyPeerDiscoveryService();
     const service = new LibP2PService<T>(
       clientType as T,
@@ -74,6 +86,115 @@ export function getMockPubSubP2PServiceFactory<T extends P2PClientType>(
   };
 }
 
+/**
+ * Mock implementation of ReqRespInterface that routes requests to other peers' handlers through the mock network.
+ * When a peer calls sendBatchRequest, the mock iterates over network peers and invokes their registered handler
+ * for the sub-protocol, simulating the request-response protocol without actual libp2p streams.
+ */
+class MockReqResp implements ReqRespInterface {
+  private handlers: Partial<ReqRespSubProtocolHandlers> = {};
+  private logger = createLogger('p2p:test:mock-reqresp');
+
+  constructor(
+    private peerId: PeerId,
+    private network: MockGossipSubNetwork,
+  ) {
+    network.registerReqRespPeer(this);
+  }
+
+  updateConfig(_config: Partial<P2PReqRespConfig>): void {}
+
+  start(
+    subProtocolHandlers: Partial<ReqRespSubProtocolHandlers>,
+    _subProtocolValidators: ReqRespSubProtocolValidators,
+  ): Promise<void> {
+    Object.assign(this.handlers, subProtocolHandlers);
+    return Promise.resolve();
+  }
+
+  addSubProtocol(
+    subProtocol: ReqRespSubProtocol,
+    handler: ReqRespSubProtocolHandler,
+    _validator?: ReqRespSubProtocolValidators[ReqRespSubProtocol],
+  ): Promise<void> {
+    this.handlers[subProtocol] = handler;
+    return Promise.resolve();
+  }
+
+  stop(): Promise<void> {
+    this.handlers = {};
+    return Promise.resolve();
+  }
+
+  getHandler(subProtocol: ReqRespSubProtocol): ReqRespSubProtocolHandler | undefined {
+    return this.handlers[subProtocol];
+  }
+
+  async sendBatchRequest<SubProtocol extends ReqRespSubProtocol>(
+    subProtocol: SubProtocol,
+    requests: InstanceType<SubProtocolMap[SubProtocol]['request']>[],
+    pinnedPeer: PeerId | undefined,
+    _timeoutMs?: number,
+    _maxPeers?: number,
+    _maxRetryAttempts?: number,
+  ): Promise<InstanceType<SubProtocolMap[SubProtocol]['response']>[]> {
+    const responses: InstanceType<SubProtocolMap[SubProtocol]['response']>[] = [];
+    const peers = this.network.getReqRespPeers().filter(p => !p.peerId.equals(this.peerId));
+    const targetPeers = pinnedPeer ? peers.filter(p => p.peerId.equals(pinnedPeer)) : peers;
+
+    for (const request of requests) {
+      const requestBuffer = request.toBuffer();
+      for (const peer of targetPeers) {
+        const handler = peer.getHandler(subProtocol);
+        if (!handler) {
+          continue;
+        }
+        try {
+          const responseBuffer = await handler(this.peerId, requestBuffer);
+          if (responseBuffer.length > 0) {
+            const response = responseFromBuffer(subProtocol, responseBuffer);
+            responses.push(response as InstanceType<SubProtocolMap[SubProtocol]['response']>);
+            break;
+          }
+        } catch (err) {
+          this.logger.debug(`Mock reqresp handler error from peer ${peer.peerId}`, { err });
+        }
+      }
+    }
+
+    return responses;
+  }
+
+  async sendRequestToPeer(
+    peerId: PeerId,
+    subProtocol: ReqRespSubProtocol,
+    payload: Buffer,
+    _dialTimeout?: number,
+  ): Promise<ReqRespResponse> {
+    const peer = this.network.getReqRespPeers().find(p => p.peerId.equals(peerId));
+    const handler = peer?.getHandler(subProtocol);
+    if (!handler) {
+      return { status: ReqRespStatus.SUCCESS, data: Buffer.from([]) };
+    }
+    try {
+      const data = await handler(this.peerId, payload);
+      return { status: ReqRespStatus.SUCCESS, data };
+    } catch {
+      return { status: ReqRespStatus.FAILURE };
+    }
+  }
+
+  getConnectionSampler(): Pick<ConnectionSampler, 'getPeerListSortedByConnectionCountAsc'> {
+    return {
+      getPeerListSortedByConnectionCountAsc: () =>
+        this.network
+          .getReqRespPeers()
+          .filter(p => !p.peerId.equals(this.peerId))
+          .map(p => p.peerId),
+    };
+  }
+}
+
 /**
  * Implementation of PubSub services that relies on a mock gossip sub network.
  * This is used in tests to simulate a gossip sub network without needing a real P2P network.
@@ -149,6 +270,16 @@ class MockGossipSubService extends TypedEventEmitter<GossipsubEvents> implements
       { msgId, propagationSource, acceptance },
     );
   }
+
+  getMeshPeers(topic?: TopicStr): PeerIdStr[] {
+    if (topic && !this.subscribedTopics.has(topic)) {
+      return [];
+    }
+    return this.network
+      .getPeers()
+      .filter(peer => !this.peerId.equals(peer))
+      .map(peer => peer.toString());
+  }
 }
 
 /**
@@ -157,6 +288,7 @@ class MockGossipSubService extends TypedEventEmitter<GossipsubEvents> implements
  */
 export class MockGossipSubNetwork {
   private peers: MockGossipSubService[] = [];
+  private reqRespPeers: MockReqResp[] = [];
   private nextMsgId = 0;
 
   private logger = createLogger('p2p:test:mock-gossipsub-network');
@@ -169,6 +301,14 @@ export class MockGossipSubNetwork {
     this.peers.push(peer);
   }
 
+  public registerReqRespPeer(peer: MockReqResp): void {
+    this.reqRespPeers.push(peer);
+  }
+
+  public getReqRespPeers(): MockReqResp[] {
+    return this.reqRespPeers;
+  }
+
   public publishToPeers(topic: TopicStr, data: Uint8Array, sender: PeerId): void {
     const msgId = (this.nextMsgId++).toString();
     this.logger.debug(`Network is distributing message on topic ${topic}`, {

package/src/test-helpers/reqresp-nodes.ts

@@ -34,6 +34,7 @@ import { BootstrapNode } from '../bootstrap/bootstrap.js';
 import type { BootnodeConfig, P2PConfig } from '../config.js';
 import type { MemPools } from '../mem_pools/interface.js';
 import { DiscV5Service } from '../services/discv5/discV5_service.js';
+import { APP_SPECIFIC_WEIGHT } from '../services/gossipsub/scoring.js';
 import { LibP2PService } from '../services/libp2p/libp2p_service.js';
 import { PeerManager } from '../services/peer-manager/peer_manager.js';
 import { PeerScoring } from '../services/peer-manager/peer_scoring.js';
@@ -154,7 +155,7 @@ export async function createTestLibP2PService<T extends P2PClientType>(
     epochCache,
   );
 
-  p2pNode.services.pubsub.score.params.appSpecificWeight = 10;
+  p2pNode.services.pubsub.score.params.appSpecificWeight = APP_SPECIFIC_WEIGHT;
   p2pNode.services.pubsub.score.params.appSpecificScore = (peerId: string) =>
     peerManager.shouldDisableP2PGossip(peerId) ? -Infinity : peerManager.getPeerScore(peerId);
 

package/src/test-helpers/test_tx_provider.ts

@@ -0,0 +1,64 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+import type { L2Block } from '@aztec/stdlib/block';
+import type { ITxProvider } from '@aztec/stdlib/interfaces/server';
+import type { BlockProposal } from '@aztec/stdlib/p2p';
+import { type Tx, TxHash } from '@aztec/stdlib/tx';
+
+import type { PeerId } from '@libp2p/interface';
+
+/**
+ * Test transaction provider that can be seeded with transactions.
+ * Returns seeded txs when requested by hash, useful for testing block
+ * proposal handling without requiring a full P2P network.
+ */
+export class TestTxProvider implements ITxProvider {
+  private txs: Map<string, Tx> = new Map();
+
+  /** Seed transactions that will be returned when requested. */
+  seed(txs: Tx[]) {
+    for (const tx of txs) {
+      this.txs.set(tx.getTxHash().toString(), tx);
+    }
+  }
+
+  /** Clear all seeded transactions. */
+  clear() {
+    this.txs.clear();
+  }
+
+  /** Returns txs from the seeded collection given their hashes. */
+  getAvailableTxs(txHashes: TxHash[]): Promise<{ txs: Tx[]; missingTxs: TxHash[] }> {
+    return this.getTxsByHashes(txHashes);
+  }
+
+  /** Get txs for a block proposal, returning any seeded txs that match the requested hashes. */
+  getTxsForBlockProposal(
+    blockProposal: BlockProposal,
+    _blockNumber: BlockNumber,
+    _opts: { pinnedPeer: PeerId | undefined; deadline: Date },
+  ): Promise<{ txs: Tx[]; missingTxs: TxHash[] }> {
+    return this.getTxsByHashes(blockProposal.txHashes);
+  }
+
+  /** Get txs for a block, returning any seeded txs that match the tx effects in the block. */
+  getTxsForBlock(block: L2Block, _opts: { deadline: Date }): Promise<{ txs: Tx[]; missingTxs: TxHash[] }> {
+    const txHashes = block.body.txEffects.map(txEffect => txEffect.txHash);
+    return this.getTxsByHashes(txHashes);
+  }
+
+  private getTxsByHashes(txHashes: TxHash[]): Promise<{ txs: Tx[]; missingTxs: TxHash[] }> {
+    const txs: Tx[] = [];
+    const missingTxs: TxHash[] = [];
+
+    for (const txHash of txHashes) {
+      const tx = this.txs.get(txHash.toString());
+      if (tx) {
+        txs.push(tx);
+      } else {
+        missingTxs.push(txHash);
+      }
+    }
+
+    return Promise.resolve({ txs, missingTxs });
+  }
+}

package/src/test-helpers/testbench-utils.ts

@@ -0,0 +1,430 @@
+import type { EpochCacheInterface } from '@aztec/epoch-cache';
+import { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { Logger } from '@aztec/foundation/log';
+import type { L2Block, L2BlockId } from '@aztec/stdlib/block';
+import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+import type {
+  BlockProposal,
+  CheckpointAttestation,
+  CheckpointProposal,
+  CheckpointProposalCore,
+} from '@aztec/stdlib/p2p';
+import { type BlockHeader, Tx, TxHash } from '@aztec/stdlib/tx';
+
+import EventEmitter from 'events';
+
+import type { TryAddResult } from '../mem_pools/attestation_pool/attestation_pool.js';
+import type { AddTxsResult, TxPoolV2, TxPoolV2Config } from '../mem_pools/tx_pool_v2/interfaces.js';
+import type { TxState } from '../mem_pools/tx_pool_v2/tx_metadata.js';
+import { RateLimitStatus } from '../services/reqresp/rate-limiter/rate_limiter.js';
+
+/**
+ * In-memory TxPool implementation for testing.
+ * Provides basic tx storage without persistence.
+ * Implements TxPoolV2 interface with stub implementations for testing.
+ */
+export class InMemoryTxPool extends EventEmitter implements TxPoolV2 {
+  private txsByHash = new Map<string, Tx>();
+  private logger: Logger | null = null;
+
+  setLogger(logger: Logger): void {
+    this.logger = logger;
+  }
+
+  setTxs(txs: Tx[]): number {
+    this.txsByHash.clear();
+    return this.appendTxs(txs);
+  }
+
+  appendTxs(txs: Tx[]): number {
+    let added = 0;
+    for (const tx of txs) {
+      const key = tx.getTxHash().toString();
+      if (!this.txsByHash.has(key)) {
+        added += 1;
+      }
+      this.txsByHash.set(key, tx);
+    }
+    return added;
+  }
+
+  clearTxs(): void {
+    this.txsByHash.clear();
+  }
+
+  resetState(): void {
+    this.txsByHash.clear();
+    this.removeAllListeners();
+  }
+
+  // === Core Operations (TxPoolV2) ===
+
+  addPendingTxs(txs: Tx[], opts?: { source?: string; feeComparisonOnly?: boolean }): Promise<AddTxsResult> {
+    const accepted: TxHash[] = [];
+    const newTxs: Tx[] = [];
+    for (const tx of txs) {
+      const key = tx.getTxHash().toString();
+      if (!this.txsByHash.has(key)) {
+        newTxs.push(tx);
+        accepted.push(tx.getTxHash());
+      }
+      this.txsByHash.set(key, tx);
+    }
+    if (newTxs.length > 0) {
+      this.emit('txs-added', { txs: newTxs, source: opts?.source });
+    }
+    return Promise.resolve({ accepted, ignored: [], rejected: [] });
+  }
+
+  canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored'> {
+    const key = tx.getTxHash().toString();
+    if (this.txsByHash.has(key)) {
+      return Promise.resolve('ignored');
+    }
+    return Promise.resolve('accepted');
+  }
+
+  addProtectedTxs(txs: Tx[], _block: BlockHeader, opts?: { source?: string }): Promise<void> {
+    for (const tx of txs) {
+      const key = tx.getTxHash().toString();
+      this.txsByHash.set(key, tx);
+    }
+    if (txs.length > 0) {
+      this.emit('txs-added', { txs, source: opts?.source });
+    }
+    return Promise.resolve();
+  }
+
+  protectTxs(txHashes: TxHash[], _block: BlockHeader): Promise<TxHash[]> {
+    const notFound: TxHash[] = [];
+    for (const txHash of txHashes) {
+      if (!this.txsByHash.has(txHash.toString())) {
+        notFound.push(txHash);
+      }
+    }
+    return Promise.resolve(notFound);
+  }
+
+  addMinedTxs(txs: Tx[], _block: BlockHeader, _opts?: { source?: string }): Promise<void> {
+    for (const tx of txs) {
+      const key = tx.getTxHash().toString();
+      this.txsByHash.set(key, tx);
+    }
+    return Promise.resolve();
+  }
+
+  // === State Transition Handlers (TxPoolV2) ===
+
+  handleMinedBlock(_block: L2Block): Promise<void> {
+    return Promise.resolve();
+  }
+
+  prepareForSlot(_slotNumber: SlotNumber): Promise<void> {
+    return Promise.resolve();
+  }
+
+  handlePrunedBlocks(_latestBlock: L2BlockId, _options?: { deleteAllTxs?: boolean }): Promise<void> {
+    return Promise.resolve();
+  }
+
+  handleFailedExecution(txHashes: TxHash[]): Promise<void> {
+    for (const txHash of txHashes) {
+      this.txsByHash.delete(txHash.toString());
+    }
+    return Promise.resolve();
+  }
+
+  handleFinalizedBlock(_block: BlockHeader): Promise<void> {
+    return Promise.resolve();
+  }
+
+  // === Query Operations (TxPoolV2) ===
+
+  getTxByHash(hash: TxHash): Promise<Tx | undefined> {
+    return Promise.resolve(this.txsByHash.get(hash.toString()));
+  }
+
+  getTxsByHash(hashes: TxHash[]): Promise<(Tx | undefined)[]> {
+    const result = hashes.map(h => this.txsByHash.get(h.toString()));
+    const found = result.filter(tx => tx !== undefined).length;
+    this.logger?.debug(`[TxPool] getTxsByHash: requested ${hashes.length}, found ${found}`);
+    return Promise.resolve(result);
+  }
+
+  hasTxs(hashes: TxHash[]): Promise<boolean[]> {
+    return Promise.resolve(hashes.map(h => this.txsByHash.has(h.toString())));
+  }
+
+  getArchivedTxByHash(_hash: TxHash): Promise<Tx | undefined> {
+    return Promise.resolve(undefined);
+  }
+
+  getPendingTxHashes(): Promise<TxHash[]> {
+    return Promise.resolve([...this.txsByHash.keys()].map(key => TxHash.fromString(key)));
+  }
+
+  getEligiblePendingTxHashes(): Promise<TxHash[]> {
+    return this.getPendingTxHashes();
+  }
+
+  getPendingTxCount(): Promise<number> {
+    return Promise.resolve(this.txsByHash.size);
+  }
+
+  getMinedTxHashes(): Promise<[TxHash, L2BlockId][]> {
+    return Promise.resolve([]);
+  }
+
+  getMinedTxCount(): Promise<number> {
+    return Promise.resolve(0);
+  }
+
+  getTxStatus(hash: TxHash): Promise<TxState | 'deleted' | undefined> {
+    return Promise.resolve(this.txsByHash.has(hash.toString()) ? 'pending' : undefined);
+  }
+
+  isEmpty(): Promise<boolean> {
+    return Promise.resolve(this.txsByHash.size === 0);
+  }
+
+  getLowestPriorityPending(_limit: number): Promise<TxHash[]> {
+    return Promise.resolve([]);
+  }
+
+  // === Configuration (TxPoolV2) ===
+
+  updateConfig(_config: Partial<TxPoolV2Config>): Promise<void> {
+    return Promise.resolve();
+  }
+
+  // === Lifecycle (TxPoolV2) ===
+
+  start(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  stop(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+/**
+ * In-memory AttestationPool mock for testing/benchmarking.
+ * Provides minimal implementation without persistence.
+ */
+export class InMemoryAttestationPool {
+  private proposals = new Map<string, BlockProposal>();
+
+  tryAddBlockProposal(blockProposal: BlockProposal): Promise<TryAddResult> {
+    const id = blockProposal.archive.toString();
+    const alreadyExists = this.proposals.has(id);
+    if (alreadyExists) {
+      return Promise.resolve({ added: false, alreadyExists: true, count: 1 });
+    }
+    this.proposals.set(id, blockProposal);
+    return Promise.resolve({ added: true, alreadyExists: false, count: 1 });
+  }
+
+  getBlockProposal(id: string): Promise<BlockProposal | undefined> {
+    return Promise.resolve(this.proposals.get(id));
+  }
+
+  tryAddCheckpointProposal(_proposal: CheckpointProposal): Promise<TryAddResult> {
+    return Promise.resolve({ added: true, alreadyExists: false, count: 1 });
+  }
+
+  getCheckpointProposal(_id: string): Promise<CheckpointProposalCore | undefined> {
+    return Promise.resolve(undefined);
+  }
+
+  async addOwnCheckpointAttestations(_attestations: CheckpointAttestation[]): Promise<void> {}
+
+  async deleteOlderThan(_slot: SlotNumber): Promise<void> {}
+
+  getCheckpointAttestationsForSlot(_slot: SlotNumber): Promise<CheckpointAttestation[]> {
+    return Promise.resolve([]);
+  }
+
+  getCheckpointAttestationsForSlotAndProposal(
+    _slot: SlotNumber,
+    _proposalId: string,
+  ): Promise<CheckpointAttestation[]> {
+    return Promise.resolve([]);
+  }
+
+  tryAddCheckpointAttestation(_attestation: CheckpointAttestation): Promise<TryAddResult> {
+    return Promise.resolve({ added: true, alreadyExists: false, count: 1 });
+  }
+
+  hasBlockProposalsForSlot(_slot: SlotNumber): Promise<boolean> {
+    return Promise.resolve(false);
+  }
+
+  isEmpty(): Promise<boolean> {
+    return Promise.resolve(this.proposals.size === 0);
+  }
+
+  resetState(): void {
+    this.proposals.clear();
+  }
+}
+
+/**
+ * Creates a mock EpochCache for testing.
+ */
+export function createMockEpochCache(): EpochCacheInterface {
+  return {
+    getCommittee: () => Promise.resolve({ committee: [], seed: 1n, epoch: EpochNumber.ZERO, isEscapeHatchOpen: false }),
+    getProposerIndexEncoding: () => '0x' as `0x${string}`,
+    getEpochAndSlotNow: () => ({ epoch: EpochNumber.ZERO, slot: SlotNumber.ZERO, ts: 0n, nowMs: 0n }),
+    computeProposerIndex: () => 0n,
+    getCurrentAndNextSlot: () => ({ currentSlot: SlotNumber.ZERO, nextSlot: SlotNumber.ZERO }),
+    getProposerAttesterAddressInSlot: () => Promise.resolve(undefined),
+    getEpochAndSlotInNextL1Slot: () => ({ epoch: EpochNumber.ZERO, slot: SlotNumber.ZERO, ts: 0n, now: 0n }),
+    isInCommittee: () => Promise.resolve(false),
+    getRegisteredValidators: () => Promise.resolve([]),
+    filterInCommittee: () => Promise.resolve([]),
+    getL1Constants: () => ({
+      l1StartBlock: 0n,
+      l1GenesisTime: 0n,
+      epochDuration: 1,
+      slotDuration: 1,
+      ethereumSlotDuration: 1,
+      proofSubmissionEpochs: 1,
+      targetCommitteeSize: 48,
+    }),
+  };
+}
+
+/**
+ * Creates a mock WorldStateSynchronizer for testing.
+ */
+export function createMockWorldStateSynchronizer(): WorldStateSynchronizer {
+  return {
+    status: () =>
+      Promise.resolve({
+        syncSummary: {
+          latestBlockNumber: 0,
+          latestBlockHash: '',
+          finalizedBlockNumber: 0,
+          treesAreSynched: false,
+          oldestHistoricBlockNumber: 0,
+        },
+      }),
+  } as WorldStateSynchronizer;
+}
+
+/**
+ * Unlimited rate limit configuration for benchmarks.
+ */
+export const UNLIMITED_RATE_LIMIT_QUOTA = {
+  peerLimit: { quotaTimeMs: 1000, quotaCount: 10_000 },
+  globalLimit: { quotaTimeMs: 1000, quotaCount: 100_000 },
+};
+
+/**
+ * Installs unlimited rate limits on a ReqResp instance.
+ * Used in benchmarks to avoid rate limiting affecting results.
+ *
+ * Note: Uses `as any` because rateLimiter is private. This is acceptable
+ * in test code where we need to override internal behavior.
+ */
+export function installUnlimitedRateLimitsOnReqResp(reqResp: any): void {
+  const rateLimiter = reqResp.rateLimiter;
+  rateLimiter.getRateLimits = () => UNLIMITED_RATE_LIMIT_QUOTA;
+  rateLimiter.allow = () => RateLimitStatus.Allowed;
+}
+
+/**
+ * Distribution patterns for benchmark transaction distribution.
+ */
+export type DistributionPattern = 'uniform' | 'sparse' | 'pinned-only';
+
+/**
+ * Collector implementation types for benchmarking.
+ */
+export type CollectorType = 'batch-requester' | 'send-batch-request';
+
+/**
+ * Display names for collector types (for output/logging only).
+ */
+export const COLLECTOR_DISPLAY_NAMES: Record<CollectorType, string> = {
+  'batch-requester': 'batch-requester (new)',
+  'send-batch-request': 'send-batch-request (old)',
+};
+
+/**
+ * Benchmark timing constants.
+ */
+export const BENCHMARK_CONSTANTS = {
+  /** Time to wait for peers to connect before starting benchmark */
+  PEER_DISCOVERY_WAIT_MS: 10_000,
+  /** Maximum time to wait for peer connections */
+  MAX_PEER_WAIT_MS: 60_000,
+  /** Interval between peer connection checks */
+  PEER_CHECK_INTERVAL_MS: 500,
+  /** Default worker ready timeout */
+  WORKER_READY_TIMEOUT_MS: 30_000,
+  /** Graceful shutdown timeout before force kill */
+  GRACEFUL_SHUTDOWN_TIMEOUT_MS: 5_000,
+  /** Overall cleanup timeout */
+  CLEANUP_TIMEOUT_MS: 10_000,
+  /** Buffer time for internal timeout to ensure we return before outer timeout */
+  TIMEOUT_BUFFER_MS: 5_000,
+  /** Minimum internal timeout regardless of buffer */
+  MIN_INTERNAL_TIMEOUT_MS: 1_000,
+  /** Fixed max peers for fair benchmarking */
+  FIXED_MAX_PEERS: 10,
+  /** Fixed max retry attempts for fair benchmarking */
+  FIXED_MAX_RETRY_ATTEMPTS: 3,
+  /** LMDB map size for temp stores used in benchmarks (in KB). */
+  KV_STORE_MAP_SIZE_KB: 256 * 1024,
+} as const;
+
+/**
+ * Filters transactions based on distribution pattern for benchmark responders.
+ *
+ * @param allTxs - All transactions to filter
+ * @param peerIndex - Index of the current peer (0 = aggregator)
+ * @param peerCount - Total number of peers
+ * @param distribution - Distribution pattern to apply
+ * @param pinnedPeerIndex - Index of the pinned peer (for pinned-only distribution)
+ * @returns Filtered transactions for this peer
+ */
+export function filterTxsByDistribution(
+  allTxs: Tx[],
+  peerIndex: number,
+  peerCount: number,
+  distribution: DistributionPattern,
+  pinnedPeerIndex: number = 1,
+): Tx[] {
+  if (peerIndex === 0) {
+    return [];
+  }
+
+  const responderCount = peerCount - 1;
+
+  switch (distribution) {
+    case 'uniform':
+      return allTxs;
+
+    case 'sparse': {
+      const responderIndex = peerIndex - 1;
+      return allTxs.filter((_, txIndex) => {
+        const bucket = txIndex % responderCount;
+        return bucket === responderIndex || bucket === (responderIndex + 1) % responderCount;
+      });
+    }
+
+    case 'pinned-only':
+      return peerIndex === pinnedPeerIndex ? allTxs : [];
+  }
+}
+
+/**
+ * Calculates the internal timeout for collector operations.
+ * Ensures we return before the outer timeout while maintaining a minimum.
+ */
+export function calculateInternalTimeout(timeoutMs: number): number {
+  return Math.max(timeoutMs - BENCHMARK_CONSTANTS.TIMEOUT_BUFFER_MS, BENCHMARK_CONSTANTS.MIN_INTERNAL_TIMEOUT_MS);
+}