@aztec/p2p 0.0.1-commit.934299a21 → 0.0.1-commit.949a33fd8

package/src/mem_pools/tx_pool_v2/tx_pool_v2.ts

@@ -11,7 +11,14 @@ import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-clien
 import EventEmitter from 'node:events';
 
 import { PoolInstrumentation, PoolName } from '../instrumentation.js';
-import type { AddTxsResult, TxPoolV2, TxPoolV2Config, TxPoolV2Dependencies, TxPoolV2Events } from './interfaces.js';
+import type {
+  AddTxsResult,
+  PoolReadAccess,
+  TxPoolV2,
+  TxPoolV2Config,
+  TxPoolV2Dependencies,
+  TxPoolV2Events,
+} from './interfaces.js';
 import type { TxState } from './tx_metadata.js';
 import { TxPoolV2Impl } from './tx_pool_v2_impl.js';
 
@@ -58,6 +65,9 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
         const hashes = txHashes.map(h => (typeof h === 'string' ? TxHash.fromString(h) : TxHash.fromBigInt(h)));
         this.emit('txs-removed', { txHashes: hashes });
       },
+      onTxsMined: (txHashes: string[]) => {
+        this.#metrics?.transactionsRemoved(txHashes);
+      },
     };
 
     // Create the implementation
@@ -162,6 +172,11 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
     return this.#queue.put(() => Promise.resolve(this.#impl.getLowestPriorityPending(limit)));
   }
 
+  /** Returns read-only access to the pool. Used for testing. */
+  getPoolReadAccess(): PoolReadAccess {
+    return this.#impl.getPoolReadAccess();
+  }
+
   // === Configuration ===
 
   updateConfig(config: Partial<TxPoolV2Config>): Promise<void> {

package/src/mem_pools/tx_pool_v2/tx_pool_v2_impl.ts

@@ -17,6 +17,7 @@ import {
   EvictionManager,
   FeePayerBalanceEvictionRule,
   FeePayerBalancePreAddRule,
+  InsufficientFeePerGasEvictionRule,
   InvalidTxsAfterMiningRule,
   InvalidTxsAfterReorgRule,
   LowPriorityEvictionRule,
@@ -45,6 +46,7 @@ import { TxPoolIndices } from './tx_pool_indices.js';
 export interface TxPoolV2Callbacks {
   onTxsAdded: (txs: Tx[], opts: { source?: string }) => void;
   onTxsRemoved: (txHashes: string[] | bigint[]) => void;
+  onTxsMined: (txHashes: string[]) => void;
 }
 
 /**
@@ -61,6 +63,7 @@ export class TxPoolV2Impl {
   #l2BlockSource: L2BlockSource;
   #worldStateSynchronizer: WorldStateSynchronizer;
   #createTxValidator: TxPoolV2Dependencies['createTxValidator'];
+  #checkAllowedSetupCalls: TxPoolV2Dependencies['checkAllowedSetupCalls'];
 
   // === In-Memory Indices ===
   #indices: TxPoolIndices = new TxPoolIndices();
@@ -92,6 +95,7 @@ export class TxPoolV2Impl {
     this.#l2BlockSource = deps.l2BlockSource;
     this.#worldStateSynchronizer = deps.worldStateSynchronizer;
     this.#createTxValidator = deps.createTxValidator;
+    this.#checkAllowedSetupCalls = deps.checkAllowedSetupCalls;
 
     this.#config = { ...DEFAULT_TX_POOL_V2_CONFIG, ...config };
     this.#archive = new TxArchive(archiveStore, this.#config.archivedTxLimit, log);
@@ -113,6 +117,7 @@ export class TxPoolV2Impl {
 
     // Post-event eviction rules (run after events to check ALL pending txs)
     this.#evictionManager.registerRule(new InvalidTxsAfterMiningRule());
+    this.#evictionManager.registerRule(new InsufficientFeePerGasEvictionRule(deps.blockMinFeesProvider));
     this.#evictionManager.registerRule(new InvalidTxsAfterReorgRule(deps.worldStateSynchronizer));
     this.#evictionManager.registerRule(new FeePayerBalanceEvictionRule(deps.worldStateSynchronizer));
     // LowPriorityEvictionRule handles cases where txs become pending via prepareForSlot (unprotect)
@@ -187,9 +192,35 @@ export class TxPoolV2Impl {
     const errors = new Map<string, TxPoolRejectionError>();
     const acceptedPending = new Set<string>();
 
+    // Phase 1: Pre-compute all throwable I/O outside the transaction.
+    // If any pre-computation throws, the entire call fails before mutations happen.
+    const precomputed = new Map<string, { meta: TxMetaData; minedBlockId: L2BlockId | undefined; isValid: boolean }>();
+
+    const validator = await this.#createTxValidator();
+
+    for (const tx of txs) {
+      const txHash = tx.getTxHash();
+      const txHashStr = txHash.toString();
+
+      const meta = await buildTxMetaData(tx);
+      const minedBlockId = await this.#getMinedBlockId(txHash);
+
+      // Validate non-mined txs (mined and pre-protected txs bypass validation inside the transaction)
+      let isValid = true;
+      if (!minedBlockId) {
+        isValid = await this.#validateMeta(meta, validator);
+      }
+
+      precomputed.set(txHashStr, { meta, minedBlockId, isValid });
+    }
+
+    // Phase 2: Apply mutations inside the transaction using only pre-computed results,
+    // in-memory reads, and buffered DB writes. Nothing here can throw an unhandled exception.
     const poolAccess = this.#createPreAddPoolAccess();
     const preAddContext: PreAddContext | undefined =
-      opts.feeComparisonOnly !== undefined ? { feeComparisonOnly: opts.feeComparisonOnly } : undefined;
+      opts.feeComparisonOnly !== undefined
+        ? { feeComparisonOnly: opts.feeComparisonOnly, priceBumpPercentage: this.#config.priceBumpPercentage }
+        : undefined;
 
     await this.#store.transactionAsync(async () => {
       for (const tx of txs) {
@@ -202,22 +233,25 @@ export class TxPoolV2Impl {
           continue;
         }
 
-        // Check mined status first (applies to all paths)
-        const minedBlockId = await this.#getMinedBlockId(txHash);
+        const { meta, minedBlockId, isValid } = precomputed.get(txHashStr)!;
         const preProtectedSlot = this.#indices.getProtectionSlot(txHashStr);
 
         if (minedBlockId) {
           // Already mined - add directly (protection already set if pre-protected)
-          await this.#addTx(tx, { mined: minedBlockId }, opts);
+          await this.#addTx(tx, { mined: minedBlockId }, opts, meta);
           accepted.push(txHash);
         } else if (preProtectedSlot !== undefined) {
           // Pre-protected and not mined - add as protected (bypass validation)
-          await this.#addTx(tx, { protected: preProtectedSlot }, opts);
+          await this.#addTx(tx, { protected: preProtectedSlot }, opts, meta);
           accepted.push(txHash);
+        } else if (!isValid) {
+          // Failed pre-computed validation
+          rejected.push(txHash);
         } else {
-          // Regular pending tx - validate and run pre-add rules
+          // Regular pending tx - run pre-add rules using pre-computed metadata
           const result = await this.#tryAddRegularPendingTx(
             tx,
+            meta,
             opts,
             poolAccess,
             acceptedPending,
@@ -227,8 +261,6 @@ export class TxPoolV2Impl {
           );
           if (result.status === 'accepted') {
             acceptedPending.add(txHashStr);
-          } else if (result.status === 'rejected') {
-            rejected.push(txHash);
           } else {
             ignored.push(txHash);
           }
@@ -259,27 +291,21 @@ export class TxPoolV2Impl {
     return { accepted, ignored, rejected, ...(errors.size > 0 ? { errors } : {}) };
   }
 
-  /** Validates and adds a regular pending tx. Returns status. */
+  /** Adds a validated pending tx, running pre-add rules and evicting conflicts. */
   async #tryAddRegularPendingTx(
     tx: Tx,
+    precomputedMeta: TxMetaData,
     opts: { source?: string },
     poolAccess: PreAddPoolAccess,
     acceptedPending: Set<string>,
     ignored: TxHash[],
     errors: Map<string, TxPoolRejectionError>,
     preAddContext?: PreAddContext,
-  ): Promise<{ status: 'accepted' | 'ignored' | 'rejected' }> {
-    const txHash = tx.getTxHash();
-    const txHashStr = txHash.toString();
-
-    // Build metadata and validate using metadata
-    const meta = await buildTxMetaData(tx);
-    if (!(await this.#validateMeta(meta))) {
-      return { status: 'rejected' };
-    }
+  ): Promise<{ status: 'accepted' | 'ignored' }> {
+    const txHashStr = tx.getTxHash().toString();
 
     // Run pre-add rules
-    const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess, preAddContext);
+    const preAddResult = await this.#evictionManager.runPreAddRules(precomputedMeta, poolAccess, preAddContext);
 
     if (preAddResult.shouldIgnore) {
       this.#log.debug(`Ignoring tx ${txHashStr}: ${preAddResult.reason?.message ?? 'unknown reason'}`);
@@ -323,7 +349,7 @@ export class TxPoolV2Impl {
     }
 
     // Add the transaction
-    await this.#addTx(tx, 'pending', opts);
+    await this.#addTx(tx, 'pending', opts, precomputedMeta);
     return { status: 'accepted' };
   }
 
@@ -332,6 +358,7 @@ export class TxPoolV2Impl {
 
     // Check if already in pool
     if (this.#indices.has(txHashStr)) {
+      this.#log.verbose(`canAddPendingTx: tx ${txHashStr} already in pool`);
       return 'ignored';
     }
 
@@ -340,26 +367,37 @@ export class TxPoolV2Impl {
     const poolAccess = this.#createPreAddPoolAccess();
     const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess);
 
-    return preAddResult.shouldIgnore ? 'ignored' : 'accepted';
+    if (preAddResult.shouldIgnore) {
+      this.#log.verbose(`canAddPendingTx: tx ${txHashStr} ignored by pre-add rule`, {
+        reason: preAddResult.reason?.message ?? 'no reason provided',
+      });
+      return 'ignored';
+    }
+    return 'accepted';
   }
 
   async addProtectedTxs(txs: Tx[], block: BlockHeader, opts: { source?: string }): Promise<void> {
     const slotNumber = block.globalVariables.slotNumber;
 
+    // Precompute setup-call allow-list flags outside the store transaction
+    const allowedFlags = await Promise.all(txs.map(tx => this.#checkAllowedSetupCalls(tx)));
+
     await this.#store.transactionAsync(async () => {
-      for (const tx of txs) {
+      for (let i = 0; i < txs.length; i++) {
+        const tx = txs[i];
         const txHash = tx.getTxHash();
         const txHashStr = txHash.toString();
         const isNew = !this.#indices.has(txHashStr);
         const minedBlockId = await this.#getMinedBlockId(txHash);
 
         if (isNew) {
+          const meta = await buildTxMetaData(tx, allowedFlags[i]);
           // New tx - add as mined or protected (callback emitted by #addTx)
           if (minedBlockId) {
-            await this.#addTx(tx, { mined: minedBlockId }, opts);
+            await this.#addTx(tx, { mined: minedBlockId }, opts, meta);
             this.#indices.setProtection(txHashStr, slotNumber);
           } else {
-            await this.#addTx(tx, { protected: slotNumber }, opts);
+            await this.#addTx(tx, { protected: slotNumber }, opts, meta);
           }
         } else {
           // Existing tx - update protection and mined status
@@ -479,6 +517,10 @@ export class TxPoolV2Impl {
       await this.#evictionManager.evictAfterNewBlock(block.header, nullifiers, feePayers);
     });
 
+    if (found.length > 0) {
+      this.#callbacks.onTxsMined(found.map(m => m.txHash));
+    }
+
     this.#log.info(`Marked ${found.length} txs as mined in block ${blockId.number}`);
   }
 
@@ -765,9 +807,10 @@ export class TxPoolV2Impl {
     tx: Tx,
     state: 'pending' | { protected: SlotNumber } | { mined: L2BlockId },
     opts: { source?: string } = {},
+    precomputedMeta?: TxMetaData,
   ): Promise<TxMetaData> {
     const txHashStr = tx.getTxHash().toString();
-    const meta = await buildTxMetaData(tx);
+    const meta = precomputedMeta ?? (await buildTxMetaData(tx));
     meta.receivedAt = this.#dateProvider.now();
 
     await this.#txsDB.set(txHashStr, tx.toBuffer());
@@ -949,7 +992,8 @@ export class TxPoolV2Impl {
 
       try {
         const tx = Tx.fromBuffer(buffer);
-        const meta = await buildTxMetaData(tx);
+        const allowedSetupCalls = await this.#checkAllowedSetupCalls(tx);
+        const meta = await buildTxMetaData(tx, allowedSetupCalls);
         loaded.push({ tx, meta });
       } catch (err) {
         this.#log.warn(`Failed to deserialize tx ${txHashStr}, deleting`, { err });

package/src/msg_validators/attestation_validator/README.md

@@ -0,0 +1,49 @@
+# Attestation Validation
+
+This module validates `CheckpointAttestation` gossipsub messages. Attestations are signatures from committee members endorsing a checkpoint proposal.
+
+**Topic**: `checkpoint_attestation` | **Snappy size limit**: 5 KB
+
+## Stage 1: AttestationValidator (Gossipsub Validation)
+
+| # | Rule | Consequence | Severity | File |
+|---|------|-------------|----------|------|
+| 1 | **Slot timeliness**: `currentSlot` or `nextSlot`. Previous slot within 500ms: IGNORE. Older: REJECT. | REJECT or IGNORE | HighToleranceError | `attestation_validator.ts` |
+| 2 | **Attester signature**: `getSender()` must recover valid address | REJECT | LowToleranceError | same |
+| 3 | **Attester in committee**: recovered address in committee for slot | REJECT | HighToleranceError | same |
+| 4 | **Proposer exists**: `getProposerAttesterAddressInSlot` must return defined | REJECT | HighToleranceError | same |
+| 5 | **Proposer signature**: `getProposer()` must recover valid address | REJECT | LowToleranceError | same |
+| 6 | **Proposer matches expected**: recovered proposer = expected for slot | REJECT | HighToleranceError | same |
+| 7 | **NoCommitteeError**: committee unavailable | REJECT | LowToleranceError | same |
+
+**Fisherman mode extension** (`FishermanAttestationValidator`): if a checkpoint proposal for the same archive exists in pool, the attestation's `ConsensusPayload` must `.equals()` the stored proposal's payload. On mismatch: REJECT + LowToleranceError.
+
+## Stage 2: Pool Admission
+
+| # | Rule | Consequence |
+|---|------|-------------|
+| 8 | Sender recoverable (pool-side) | Silent drop |
+| 9 | Not a duplicate (same slot + proposalId + signer) | IGNORE |
+| 10 | Per-signer cap: `MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER` = 2 | IGNORE |
+
+Own attestations added via `addOwnCheckpointAttestations` bypass the per-signer cap.
+
+## Stage 3: Equivocation Detection
+
+When a signer's attestation count for a slot reaches exactly 2 (different proposals): `duplicateAttestationCallback` fires -> `WANT_TO_SLASH_EVENT` with `OffenseType.DUPLICATE_ATTESTATION`. Attestation still ACCEPTED and rebroadcast. Callback fires once (not again at count 3+).
+
+## Validation at L1 Checkpoint Submission (Archiver)
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Each attestation must have recoverable signature (or address-only is allowed but does not count toward quorum) | Checkpoint rejected as invalid | `archiver/src/modules/validation.ts` |
+| Attestation at index `i` must correspond to committee member at index `i` | Checkpoint rejected as invalid | same |
+| Valid attestation count >= floor(committee * 2/3) + 1 | Checkpoint rejected as invalid | same |
+| No committee / escape hatch open | Accepted unconditionally | same |
+
+Note: `skipValidateCheckpointAttestations` config flag bypasses all archiver attestation validation.
+
+## Gossipsub Topic Scoring
+
+P3 enabled with expected messages per slot = `targetCommitteeSize`. Conservative threshold (30% of convergence value). Max P3 penalty = -34 per topic.
+

package/src/msg_validators/attestation_validator/attestation_validator.ts

@@ -3,19 +3,35 @@ import { NoCommitteeError } from '@aztec/ethereum/contracts';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import {
   type CheckpointAttestation,
+  type CoordinationSignatureContext,
   type P2PValidator,
   PeerErrorSeverity,
   type ValidationResult,
+  hasValidSignatureContext,
 } from '@aztec/stdlib/p2p';
 
-import { isWithinClockTolerance } from '../clock_tolerance.js';
+import { PipeliningWindow, isWithinClockTolerance } from '../clock_tolerance.js';
 
 export class CheckpointAttestationValidator implements P2PValidator<CheckpointAttestation> {
   protected epochCache: EpochCacheInterface;
   protected logger: Logger;
+  private readonly pipeliningWindow: PipeliningWindow;
+  protected readonly signatureContext: CoordinationSignatureContext;
 
-  constructor(epochCache: EpochCacheInterface) {
+  constructor(
+    epochCache: EpochCacheInterface,
+    opts: {
+      l1PublishingTime?: number;
+      p2pPropagationTime?: number;
+      signatureContext: CoordinationSignatureContext;
+    },
+  ) {
     this.epochCache = epochCache;
+    this.pipeliningWindow = new PipeliningWindow(epochCache, {
+      l1PublishingTime: opts.l1PublishingTime,
+      p2pPropagationTime: opts.p2pPropagationTime,
+    });
+    this.signatureContext = opts.signatureContext;
     this.logger = createLogger('p2p:checkpoint-attestation-validator');
   }
 
@@ -23,18 +39,34 @@ export class CheckpointAttestationValidator implements P2PValidator<CheckpointAt
     const slotNumber = message.payload.header.slotNumber;
 
     try {
-      const { currentSlot, nextSlot } = this.epochCache.getCurrentAndNextSlot();
+      // Cross-chain replay check: reject attestations that carry a foreign signing domain.
+      if (!hasValidSignatureContext(message.payload, this.signatureContext)) {
+        this.logger.warn(`Rejecting checkpoint attestation with foreign signature context for slot ${slotNumber}`, {
+          chainId: message.payload.signatureContext.chainId,
+          rollupAddress: message.payload.signatureContext.rollupAddress.toString(),
+          expectedChainId: this.signatureContext.chainId,
+          expectedRollupAddress: this.signatureContext.rollupAddress.toString(),
+        });
+        return { result: 'reject', severity: PeerErrorSeverity.LowToleranceError };
+      }
+
+      // Use target slots since proposals target pipeline slots (slot + 1 when pipelining).
+      const { targetSlot, nextSlot } = this.epochCache.getTargetAndNextSlot();
 
-      if (slotNumber !== currentSlot && slotNumber !== nextSlot) {
-        // Check if message is for previous slot and within clock tolerance
-        if (!isWithinClockTolerance(slotNumber, currentSlot, this.epochCache)) {
+      if (slotNumber !== targetSlot && slotNumber !== nextSlot) {
+        // When pipelining, accept attestations for the current slot (built in the previous slot)
+        // until the target slot reaches its L1 publish cutoff.
+        if (this.pipeliningWindow.acceptsAttestation(slotNumber)) {
+          // Fall through to remaining validation (signature, committee, etc.)
+        } else if (!isWithinClockTolerance(slotNumber, targetSlot, this.epochCache)) {
           this.logger.warn(
-            `Checkpoint attestation slot ${slotNumber} is not current (${currentSlot}) or next (${nextSlot}) slot`,
+            `Checkpoint attestation slot ${slotNumber} is not current (${targetSlot}) or next (${nextSlot}) slot`,
           );
           return { result: 'reject', severity: PeerErrorSeverity.HighToleranceError };
+        } else {
+          this.logger.debug(`Ignoring checkpoint attestation for previous slot ${slotNumber} within clock tolerance`);
+          return { result: 'ignore' };
         }
-        this.logger.debug(`Ignoring checkpoint attestation for previous slot ${slotNumber} within clock tolerance`);
-        return { result: 'ignore' };
       }
 
       // Verify the signature is valid

package/src/msg_validators/attestation_validator/fisherman_attestation_validator.ts

@@ -1,5 +1,10 @@
 import type { EpochCacheInterface } from '@aztec/epoch-cache';
-import { type CheckpointAttestation, PeerErrorSeverity, type ValidationResult } from '@aztec/stdlib/p2p';
+import {
+  type CheckpointAttestation,
+  type CoordinationSignatureContext,
+  PeerErrorSeverity,
+  type ValidationResult,
+} from '@aztec/stdlib/p2p';
 import { Attributes, Metrics, type TelemetryClient, createUpDownCounterWithDefault } from '@aztec/telemetry-client';
 
 import type { AttestationPoolApi } from '../../mem_pools/attestation_pool/attestation_pool.js';
@@ -20,8 +25,13 @@ export class FishermanAttestationValidator extends CheckpointAttestationValidato
     epochCache: EpochCacheInterface,
     private attestationPool: AttestationPoolApi,
     telemetryClient: TelemetryClient,
+    opts: {
+      l1PublishingTime?: number;
+      p2pPropagationTime?: number;
+      signatureContext: CoordinationSignatureContext;
+    },
   ) {
-    super(epochCache);
+    super(epochCache, opts);
     this.logger = this.logger.createChild('[FISHERMAN]');
 
     const meter = telemetryClient.getMeter('FishermanAttestationValidator');

package/src/msg_validators/clock_tolerance.ts

@@ -1,5 +1,6 @@
 import type { EpochCacheInterface } from '@aztec/epoch-cache';
 import { SlotNumber } from '@aztec/foundation/branded-types';
+import { DEFAULT_P2P_PROPAGATION_TIME, createPipelinedCheckpointTimingModel } from '@aztec/stdlib/timetable';
 
 /**
  * Maximum clock disparity tolerance for P2P message validation (in milliseconds).
@@ -36,10 +37,11 @@ export function isWithinClockTolerance(
   }
 
   // Check how far we are into the current slot (in milliseconds)
-  const { ts: slotStartTs, nowMs, slot } = epochCache.getEpochAndSlotNow();
+  const { ts: slotStartTs, nowMs } = epochCache.getEpochAndSlotNow();
+  const targetSlot = epochCache.getTargetSlot();
 
-  // Sanity check: ensure the epoch cache's current slot matches the expected current slot
-  if (slot !== currentSlot) {
+  // Sanity check: ensure the epoch cache's target slot matches the expected current slot
+  if (targetSlot !== currentSlot) {
     return false;
   }
 
@@ -49,3 +51,77 @@ export function isWithinClockTolerance(
 
   return elapsedMs < MAXIMUM_GOSSIP_CLOCK_DISPARITY_MS;
 }
+
+/**
+ * Checks if a straggler message for the previous target slot should be accepted.
+ *
+ * Under pipelining, proposals and attestations carry the target slot N. Most of the
+ * time the receiver is either still in the build slot N-1 (accepted via the main
+ * `slotNumber === targetSlot` match) or in the target slot N (accepted via
+ * `slotNumber === nextSlot` when pipelining is disabled, or again via `targetSlot`
+ * when the receiver itself is pipelining). Stragglers that arrive after the receiver
+ * has rolled past the target slot fall to this check: accept `messageSlot === slotNow`
+ * while we're still within the first `windowSeconds + clock-disparity` of the slot.
+ *
+ * Under the early-pipelining schedule `windowSeconds` is small (0 for proposals,
+ * `2*p2pPropagationTime` for attestations) since the proposer collects everything
+ * before the slot boundary.
+ *
+ * @param messageSlot - The slot number from the received message
+ * @param epochCache - EpochCache to get timing and pipelining state
+ * @param windowSeconds - How far into the current slot we still accept previous-target messages
+ * @returns true if pipelining is enabled, the message is for the current wallclock slot, and we're within the grace period
+ */
+function isWithinPipeliningWindow(
+  messageSlot: SlotNumber,
+  epochCache: EpochCacheInterface,
+  windowSeconds: number,
+): boolean {
+  if (!epochCache.isProposerPipeliningEnabled()) {
+    return false;
+  }
+
+  const currentSlot = epochCache.getSlotNow();
+  if (messageSlot !== currentSlot) {
+    return false;
+  }
+
+  const { ts: slotStartTs, nowMs } = epochCache.getEpochAndSlotNow();
+  const slotStartMs = slotStartTs * 1000n;
+  const elapsedMs = Number(nowMs - slotStartMs);
+  const windowMs = windowSeconds * 1000 + MAXIMUM_GOSSIP_CLOCK_DISPARITY_MS;
+
+  return elapsedMs < windowMs;
+}
+
+export class PipeliningWindow {
+  private readonly proposalWindowIntoTargetSlot: number;
+  private readonly attestationWindowIntoTargetSlot: number;
+
+  constructor(
+    private readonly epochCache: EpochCacheInterface,
+    opts: {
+      p2pPropagationTime?: number;
+      l1PublishingTime?: number;
+    } = {},
+  ) {
+    const l1Constants = epochCache.getL1Constants();
+    const checkpointTiming = createPipelinedCheckpointTimingModel({
+      aztecSlotDuration: l1Constants.slotDuration,
+      ethereumSlotDuration: l1Constants.ethereumSlotDuration,
+      l1PublishingTime: opts.l1PublishingTime ?? l1Constants.ethereumSlotDuration,
+      p2pPropagationTime: opts.p2pPropagationTime ?? DEFAULT_P2P_PROPAGATION_TIME,
+    });
+
+    this.proposalWindowIntoTargetSlot = checkpointTiming.proposalWindowIntoTargetSlot;
+    this.attestationWindowIntoTargetSlot = checkpointTiming.attestationWindowIntoTargetSlot;
+  }
+
+  public acceptsProposal(messageSlot: SlotNumber): boolean {
+    return isWithinPipeliningWindow(messageSlot, this.epochCache, this.proposalWindowIntoTargetSlot);
+  }
+
+  public acceptsAttestation(messageSlot: SlotNumber): boolean {
+    return isWithinPipeliningWindow(messageSlot, this.epochCache, this.attestationWindowIntoTargetSlot);
+  }
+}

package/src/msg_validators/proposal_validator/README.md

@@ -0,0 +1,123 @@
+# Proposal Validation
+
+This module validates `BlockProposal` and `CheckpointProposal` gossipsub messages. Both share the same base `ProposalValidator` (neither subclass overrides `validate()`), with checkpoint-specific logic layered on top in the gossipsub handler.
+
+## BlockProposal
+
+**Topic**: `block_proposal` | **Snappy size limit**: 10 MB
+
+### Stage 1: Gossipsub Validation (ProposalValidator)
+
+File: `proposal_validator.ts`
+
+| # | Rule | Consequence | Severity |
+|---|------|-------------|----------|
+| 1 | **Slot check**: must be `currentSlot` or `nextSlot`. Previous slot within 500ms tolerance: IGNORE. | REJECT | HighToleranceError |
+| 2 | **Signature**: `getSender()` must recover a valid address. If `signedTxs` present, its recovered sender must match. | REJECT | MidToleranceError |
+| 3 | **Txs permitted**: if `disableTransactions`, must have 0 txHashes and 0 embedded txs | REJECT | MidToleranceError |
+| 4 | **Max txs**: `txHashes.length <= maxTxsPerBlock` | REJECT | MidToleranceError |
+| 5 | **Embedded txs in txHashes**: every embedded tx's hash must appear in `txHashes` | REJECT | MidToleranceError |
+| 6 | **Proposer check**: signer must match expected proposer for slot (skipped if committee size = 0) | REJECT | MidToleranceError |
+| 7 | **Tx hash integrity**: each embedded tx's recomputed hash must match declared hash | REJECT | LowToleranceError |
+| 8 | **NoCommitteeError**: epoch cache cannot determine committee | REJECT | LowToleranceError |
+
+Deserialization guards: `BlockProposal.fromBuffer` and `SignedTxs.fromBuffer` both enforce `txCount <= MAX_TXS_PER_BLOCK` (65536). Violation -> REJECT + LowToleranceError.
+
+### Stage 2: Mempool (Attestation Pool)
+
+| # | Rule | Consequence |
+|---|------|-------------|
+| 9 | **Duplicate**: same archive root already stored | IGNORE (no penalty) |
+| 10 | **Per-position cap**: max 2 proposals per (slot, indexWithinCheckpoint) | REJECT + HighToleranceError |
+| 11 | **Equivocation**: >1 distinct proposal for same (slot, index) | ACCEPT (rebroadcast for detection). At count=2: `duplicateProposalCallback` fires -> slash event (`OffenseType.DUPLICATE_PROPOSAL`, configured via `slashDuplicateProposalPenalty`) |
+
+### Stage 3: Validator-Client Processing (BlockProposalHandler)
+
+Only runs on validator nodes. Non-validator nodes use a default handler that triggers tx collection without deep validation.
+
+| # | Rule | Failure Reason |
+|---|------|----------------|
+| 12 | Signature re-check | `invalid_proposal` |
+| 13 | ProposalValidator re-run | `invalid_proposal` |
+| 14 | Self-proposal filter | Ignored silently |
+| 15 | Parent block exists (`lastArchive.root` matches known block or genesis) | `parent_block_not_found` |
+| 16 | Parent block slot <= proposal slot | `parent_block_wrong_slot` |
+| 17 | Block number not already in archiver | `block_number_already_exists` |
+| 18 | Checkpoint number consistency (multiple sub-rules for first/non-first blocks) | `invalid_proposal` |
+| 19 | Global variables consistency (non-first block: chainId, version, slot, timestamp, coinbase, feeRecipient, gasFees match parent) | `global_variables_mismatch` |
+| 20 | L1-to-L2 message hash matches `proposal.inHash` | `in_hash_mismatch` |
+| 21 | All txs referenced by `txHashes` obtainable | `txs_not_available` |
+| 22 | **Re-execution**: processed tx count matches `txHashes.length` | `timeout` (ReExTimeoutError) |
+| 23 | **Re-execution**: no failed txs | `failed_txs` (ReExFailedTxsError) -- **SLASHABLE** |
+| 24 | **Re-execution**: archive root and header match proposal | `state_mismatch` (ReExStateMismatchError) -- **SLASHABLE** |
+
+**Escape hatch**: during escape hatch periods (`isEscapeHatchOpenAtSlot`), re-execution and slashing are both disabled, and the proposal is rejected locally.
+
+**Conditional re-execution**: rules 22-24 only run when at least one condition is true: `fishermanMode` enabled, `slashBroadcastedInvalidBlockPenalty > 0`, committee membership, `alwaysReexecuteBlockProposals`, or `blobClient.canUpload()`.
+
+**Slashing**: only `state_mismatch` and `failed_txs` trigger on-chain slashing (`OffenseType.BROADCASTED_INVALID_BLOCK_PROPOSAL`, gated by `slashBroadcastedInvalidBlockPenalty > 0`). Unknown errors during re-execution do NOT slash.
+
+**Embedded tx validation**: txs in `signedTxs` are validated via `createTxValidatorForBlockProposalReceivedTxs` (well-formedness only) when stored in the tx pool. Invalid embedded txs are rejected from the pool but do not cause the block proposal itself to be rejected at gossipsub level.
+
+### Gossipsub Topic Scoring
+
+| Parameter | Effect |
+|-----------|--------|
+| P4 (invalidMessageDeliveries) | weight = -20, decay over 4 slots |
+| P3 (meshMessageDeliveries) | Enabled only when `expectedBlockProposalsPerSlot > 0` (MBPS mode) |
+| P1/P2 | Only active when P3 is enabled |
+
+---
+
+## CheckpointProposal
+
+**Topic**: `checkpoint_proposal` | **Snappy size limit**: 10 MB
+
+### Stage 1: Gossipsub Validation (ProposalValidator)
+
+Same `ProposalValidator.validate()` as BlockProposal (shared implementation, neither subclass overrides it). See BlockProposal Stage 1 rules 1-8.
+
+### Stage 2: Embedded Block Proposal Validation (if `lastBlock` present)
+
+The checkpoint's embedded `lastBlock` is extracted via `getBlockProposal()` and validated through `BlockProposalValidator.validate()` plus block mempool checks.
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Block proposal must pass `BlockProposalValidator.validate()` | If REJECT: entire checkpoint REJECTED | `libp2p_service.ts` |
+| Block proposal must not exceed per-position cap (2) | Checkpoint REJECTED + HighToleranceError | same |
+| Block equivocation detected (>1 proposals for same slot+index) | Checkpoint REJECTED (block itself is ACCEPT for re-broadcast) | same |
+
+### Stage 3: Mempool (Attestation Pool)
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Duplicate (same archive ID) | IGNORE (no penalty). Embedded block still processed if valid. | `attestation_pool.ts` |
+| Per-slot cap: `MAX_CHECKPOINT_PROPOSALS_PER_SLOT` = 2 | REJECT + HighToleranceError. Embedded block still processed. | same |
+
+### Stage 4: Equivocation Detection
+
+When >1 checkpoint proposals exist for same slot (count > 1): ACCEPT (re-broadcast). At count == 2 (exactly): `duplicateProposalCallback` fires. Proposal NOT further processed. Callback fires only once per equivocation pair.
+
+### Stage 5: Validator-Client Consensus Validation
+
+Determines whether the validator signs an attestation.
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Escape hatch open | No attestation | `validator-client/src/validator.ts` |
+| Signature invalid (re-check) | No attestation | same |
+| Self-proposal | No attestation (ignored) | same |
+| `feeAssetPriceModifier` outside [-100, +100] bps | No attestation | same |
+| Not in committee (unless fisherman mode) | No attestation | same |
+| Checkpoint header mismatch (computed vs proposal) | No attestation | same |
+| Archive root mismatch | No attestation | same |
+| Epoch out hash mismatch | No attestation | same |
+| Last block not found / not matching | No attestation | same |
+| Already attested to this or earlier slot | No attestation (unless `attestToEquivocatedProposals`) | same |
+
+**`skipCheckpointProposalValidation` config**: when true, the re-execution checks (header/archive/epoch hash) are all skipped. Signature, fee modifier, committee, escape hatch, and equivocation checks still apply.
+
+### Gossipsub Topic Scoring
+
+P3 enabled with expected rate of 1 message per slot. P4 weight = -20, max P3 penalty = -34 per topic.
+