@aztec/p2p 0.0.1-commit.f504929 → 0.0.1-commit.f5d02921e

package/src/mem_pools/tx_pool_v2/tx_metadata.ts

@@ -1,3 +1,4 @@
+import { minBigint } from '@aztec/foundation/bigint';
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { ProtocolContractAddress } from '@aztec/protocol-contracts';
@@ -6,7 +7,6 @@ import { Gas } from '@aztec/stdlib/gas';
 import { type Tx, TxHash } from '@aztec/stdlib/tx';
 
 import { getFeePayerBalanceDelta } from '../../msg_validators/tx_validator/fee_payer_balance.js';
-import { getTxPriorityFee } from '../tx_pool/priority.js';
 import { type PreAddResult, TxPoolRejectionCode } from './eviction/interfaces.js';
 
 /** Validator-compatible data interface, mirroring the subset of PrivateKernelTailCircuitPublicInputs used by validators. */
@@ -67,6 +67,9 @@ export type TxMetaData = {
   /** Timestamp by which the transaction must be included (for expiration checks) */
   readonly expirationTimestamp: bigint;
 
+  /** Whether the tx's setup-phase calls pass the allow list check. Computed at receipt time. */
+  readonly allowedSetupCalls: boolean;
+
   /** Validator-compatible data, providing the same access patterns as Tx.data */
   readonly data: TxMetaValidationData;
 
@@ -84,8 +87,12 @@ export type TxState = 'pending' | 'protected' | 'mined' | 'deleted';
  * Builds TxMetaData from a full Tx object.
  * Extracts all relevant fields for efficient in-memory storage and querying.
  * Fr values are captured in closures for zero-cost re-validation.
+ *
+ * @param allowedSetupCalls - Whether the tx's setup-phase calls pass the allow list.
+ *   For gossip/RPC txs this is always `true` (already validated by PhasesTxValidator).
+ *   For req/resp txs this should be computed by the caller using the phases validator.
  */
-export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
+export async function buildTxMetaData(tx: Tx, allowedSetupCalls: boolean = true): Promise<TxMetaData> {
   const txHashObj = tx.getTxHash();
   const txHash = txHashObj.toString();
   const txHashBigInt = txHashObj.toBigInt();
@@ -112,6 +119,7 @@ export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
     feeLimit,
     nullifiers,
     expirationTimestamp,
+    allowedSetupCalls,
     receivedAt: 0,
     estimatedSizeBytes,
     data: {
@@ -158,13 +166,13 @@ export function txHashFromBigInt(value: bigint): string {
 }
 
 /** Minimal fields required for priority comparison. */
-type PriorityComparable = Pick<TxMetaData, 'txHashBigInt' | 'priorityFee'>;
+export type PriorityComparable = Pick<TxMetaData, 'txHash' | 'txHashBigInt' | 'priorityFee'>;
 
 /**
  * Compares two priority fees in ascending order.
  * Returns negative if a < b, positive if a > b, 0 if equal.
  */
-export function compareFee(a: bigint, b: bigint): number {
+export function compareFee(a: bigint, b: bigint): -1 | 0 | 1 {
   return a < b ? -1 : a > b ? 1 : 0;
 }
 
@@ -173,7 +181,7 @@ export function compareFee(a: bigint, b: bigint): number {
  * Uses field element comparison for deterministic ordering.
  * Returns negative if a < b, positive if a > b, 0 if equal.
  */
-export function compareTxHash(a: bigint, b: bigint): number {
+export function compareTxHash(a: bigint, b: bigint): -1 | 0 | 1 {
   return Fr.cmpAsBigInt(a, b);
 }
 
@@ -182,7 +190,7 @@ export function compareTxHash(a: bigint, b: bigint): number {
  * Returns negative if a < b, positive if a > b, 0 if equal.
  * Use with sort() for ascending order, or negate/reverse for descending.
  */
-export function comparePriority(a: PriorityComparable, b: PriorityComparable): number {
+export function comparePriority(a: PriorityComparable, b: PriorityComparable): -1 | 0 | 1 {
   const feeComparison = compareFee(a.priorityFee, b.priorityFee);
   if (feeComparison !== 0) {
     return feeComparison;
@@ -190,21 +198,38 @@ export function comparePriority(a: PriorityComparable, b: PriorityComparable): n
   return compareTxHash(a.txHashBigInt, b.txHashBigInt);
 }
 
+/**
+ * Returns the minimum fee required to replace an existing tx with the given price bump percentage.
+ * Uses integer arithmetic: `existingFee + existingFee * priceBumpPercentage / 100`.
+ */
+export function getMinimumPriceBumpFee(existingFee: bigint, priceBumpPercentage: bigint): bigint {
+  const bump = (existingFee * priceBumpPercentage) / 100n;
+  // Ensure the minimum bump is at least 1, so that replacement always requires
+  // paying strictly more — even with 0% bump or zero existing fee.
+  const effectiveBump = bump > 0n ? bump : 1n;
+  return existingFee + effectiveBump;
+}
+
 /**
  * Checks for nullifier conflicts between an incoming transaction and existing pool state.
  *
  * When the incoming tx shares nullifiers with existing pending txs:
- * - If the incoming tx has strictly higher priority, mark conflicting txs for eviction
- * - If any conflicting tx has equal or higher priority, ignore the incoming tx
+ * - If the incoming tx meets or exceeds the required priority, mark conflicting txs for eviction
+ * - Otherwise, ignore the incoming tx
+ *
+ * When `priceBumpPercentage` is provided (RPC path), uses fee-only comparison with the
+ * percentage bump instead of `comparePriority`.
  *
  * @param incomingMeta - Metadata for the incoming transaction
  * @param getTxHashByNullifier - Accessor to find which tx uses a nullifier
  * @param getMetadata - Accessor to get metadata for a tx hash
+ * @param priceBumpPercentage - Optional percentage bump required for fee-based replacement
  */
 export function checkNullifierConflict(
   incomingMeta: TxMetaData,
   getTxHashByNullifier: (nullifier: string) => string | undefined,
   getMetadata: (txHash: string) => TxMetaData | undefined,
+  priceBumpPercentage?: bigint,
 ): PreAddResult {
   const txHashesToEvict: string[] = [];
 
@@ -225,19 +250,32 @@ export function checkNullifierConflict(
       continue;
     }
 
-    // If incoming tx has strictly higher priority, mark for eviction
-    // Otherwise, ignore incoming tx (ties go to existing tx)
-    // Use comparePriority for deterministic ordering (includes txHash as tiebreaker)
-    if (comparePriority(incomingMeta, conflictingMeta) > 0) {
+    // When price bump is set (RPC path), require the incoming fee to meet the bumped threshold.
+    // Otherwise (P2P path), use full comparePriority with tx hash tiebreaker.
+    const isHigherPriority =
+      priceBumpPercentage !== undefined
+        ? incomingMeta.priorityFee >= getMinimumPriceBumpFee(conflictingMeta.priorityFee, priceBumpPercentage)
+        : comparePriority(incomingMeta, conflictingMeta) > 0;
+
+    if (isHigherPriority) {
       txHashesToEvict.push(conflictingHashStr);
     } else {
+      const minimumFee =
+        priceBumpPercentage !== undefined
+          ? getMinimumPriceBumpFee(conflictingMeta.priorityFee, priceBumpPercentage)
+          : undefined;
       return {
         shouldIgnore: true,
         txHashesToEvict: [],
         reason: {
           code: TxPoolRejectionCode.NULLIFIER_CONFLICT,
-          message: `Nullifier conflict with existing tx ${conflictingHashStr}`,
+          message:
+            minimumFee !== undefined
+              ? `Nullifier conflict with existing tx ${conflictingHashStr}. Minimum required fee: ${minimumFee}, got: ${incomingMeta.priorityFee}`
+              : `Nullifier conflict with existing tx ${conflictingHashStr}`,
           conflictingTxHash: conflictingHashStr,
+          minimumPriceBumpFee: minimumFee,
+          txPriorityFee: minimumFee !== undefined ? incomingMeta.priorityFee : undefined,
         },
       };
     }
@@ -274,6 +312,7 @@ export function stubTxMetaData(
     nullifiers?: string[];
     expirationTimestamp?: bigint;
     anchorBlockHeaderHash?: string;
+    allowedSetupCalls?: boolean;
   } = {},
 ): TxMetaData {
   const txHashBigInt = Fr.fromHexString(txHash).toBigInt();
@@ -290,8 +329,15 @@ export function stubTxMetaData(
     feeLimit: overrides.feeLimit ?? 100n,
     nullifiers: overrides.nullifiers ?? [`0x${normalizedTxHash.slice(2)}null1`],
     expirationTimestamp,
+    allowedSetupCalls: overrides.allowedSetupCalls ?? true,
     receivedAt: 0,
     estimatedSizeBytes: 0,
     data: stubTxMetaValidationData({ expirationTimestamp }),
   };
 }
+
+/** Returns the priority fee for a tx, based on the L2 priority fee capped by the max fee per gas. */
+function getTxPriorityFee(tx: Tx): bigint {
+  const { maxPriorityFeesPerGas: priorityFees, maxFeesPerGas } = tx.getGasSettings();
+  return minBigint(maxFeesPerGas.feePerL2Gas, priorityFees.feePerL2Gas);
+}

package/src/mem_pools/tx_pool_v2/tx_pool_indices.ts

@@ -1,7 +1,8 @@
+import { insertIntoSortedArray, removeFromSortedArray } from '@aztec/foundation/array';
 import { SlotNumber } from '@aztec/foundation/branded-types';
 import type { L2BlockId } from '@aztec/stdlib/block';
 
-import { type TxMetaData, type TxState, compareFee, compareTxHash, txHashFromBigInt } from './tx_metadata.js';
+import { type PriorityComparable, type TxMetaData, type TxState, comparePriority } from './tx_metadata.js';
 
 /**
  * Manages in-memory indices for the transaction pool.
@@ -22,8 +23,8 @@ export class TxPoolIndices {
   #nullifierToTxHash: Map<string, string> = new Map();
   /** Fee payer to txHashes index (pending txs only) */
   #feePayerToTxHashes: Map<string, Set<string>> = new Map();
-  /** Pending txHash bigints grouped by priority fee */
-  #pendingByPriority: Map<bigint, Set<bigint>> = new Map();
+  /** Pending transactions sorted ascending by priority fee, ties broken by txHash */
+  #pendingByPriority: PriorityComparable[] = [];
   /** Protected transactions: txHash -> slotNumber */
   #protectedTransactions: Map<string, SlotNumber> = new Map();
 
@@ -73,20 +74,14 @@ export class TxPoolIndices {
    * @param order - 'desc' for highest priority first, 'asc' for lowest priority first
    */
   *iteratePendingByPriority(order: 'asc' | 'desc', filter?: (hash: string) => boolean): Generator<string> {
-    const feeCompareFn = order === 'desc' ? (a: bigint, b: bigint) => compareFee(b, a) : compareFee;
-    const hashCompareFn =
-      order === 'desc' ? (a: bigint, b: bigint) => compareTxHash(b, a) : (a: bigint, b: bigint) => compareTxHash(a, b);
-
-    const sortedFees = [...this.#pendingByPriority.keys()].sort(feeCompareFn);
-
-    for (const fee of sortedFees) {
-      const hashesAtFee = this.#pendingByPriority.get(fee)!;
-      const sortedHashes = [...hashesAtFee].sort(hashCompareFn);
-      for (const hashBigInt of sortedHashes) {
-        const hash = txHashFromBigInt(hashBigInt);
-        if (filter === undefined || filter(hash)) {
-          yield hash;
-        }
+    const arr = this.#pendingByPriority;
+    const start = order === 'asc' ? 0 : arr.length - 1;
+    const step = order === 'asc' ? 1 : -1;
+    const inBounds = order === 'asc' ? (i: number) => i < arr.length : (i: number) => i >= 0;
+
+    for (let i = start; inBounds(i); i += step) {
+      if (filter === undefined || filter(arr[i].txHash)) {
+        yield arr[i].txHash;
       }
     }
   }
@@ -227,11 +222,7 @@ export class TxPoolIndices {
 
   /** Gets the count of pending transactions */
   getPendingTxCount(): number {
-    let count = 0;
-    for (const hashes of this.#pendingByPriority.values()) {
-      count += hashes.size;
-    }
-    return count;
+    return this.#pendingByPriority.length;
   }
 
   /** Gets the lowest priority pending transaction hashes (up to limit) */
@@ -264,12 +255,10 @@ export class TxPoolIndices {
   /** Gets all pending transactions */
   getPendingTxs(): TxMetaData[] {
     const result: TxMetaData[] = [];
-    for (const hashSet of this.#pendingByPriority.values()) {
-      for (const txHashBigInt of hashSet) {
-        const meta = this.#metadata.get(txHashFromBigInt(txHashBigInt));
-        if (meta) {
-          result.push(meta);
-        }
+    for (const entry of this.#pendingByPriority) {
+      const meta = this.#metadata.get(entry.txHash);
+      if (meta) {
+        result.push(meta);
       }
     }
     return result;
@@ -408,13 +397,12 @@ export class TxPoolIndices {
     }
     feePayerSet.add(meta.txHash);
 
-    // Add to priority bucket
-    let prioritySet = this.#pendingByPriority.get(meta.priorityFee);
-    if (!prioritySet) {
-      prioritySet = new Set();
-      this.#pendingByPriority.set(meta.priorityFee, prioritySet);
-    }
-    prioritySet.add(meta.txHashBigInt);
+    insertIntoSortedArray(
+      this.#pendingByPriority,
+      { txHash: meta.txHash, priorityFee: meta.priorityFee, txHashBigInt: meta.txHashBigInt },
+      comparePriority,
+      false,
+    );
   }
 
   #removeFromPendingIndices(meta: TxMetaData): void {
@@ -432,13 +420,11 @@ export class TxPoolIndices {
       }
     }
 
-    // Remove from priority map
-    const hashSet = this.#pendingByPriority.get(meta.priorityFee);
-    if (hashSet) {
-      hashSet.delete(meta.txHashBigInt);
-      if (hashSet.size === 0) {
-        this.#pendingByPriority.delete(meta.priorityFee);
-      }
-    }
+    // Remove from priority array
+    removeFromSortedArray(
+      this.#pendingByPriority,
+      { txHash: meta.txHash, priorityFee: meta.priorityFee, txHashBigInt: meta.txHashBigInt },
+      comparePriority,
+    );
   }
 }

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';
 
@@ -165,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

@@ -62,6 +62,7 @@ export class TxPoolV2Impl {
   #l2BlockSource: L2BlockSource;
   #worldStateSynchronizer: WorldStateSynchronizer;
   #createTxValidator: TxPoolV2Dependencies['createTxValidator'];
+  #checkAllowedSetupCalls: TxPoolV2Dependencies['checkAllowedSetupCalls'];
 
   // === In-Memory Indices ===
   #indices: TxPoolIndices = new TxPoolIndices();
@@ -93,6 +94,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);
@@ -214,7 +216,9 @@ export class TxPoolV2Impl {
     // 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) {
@@ -352,6 +356,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';
     }
 
@@ -360,26 +365,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
@@ -974,7 +990,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

@@ -23,13 +23,14 @@ export class CheckpointAttestationValidator implements P2PValidator<CheckpointAt
     const slotNumber = message.payload.header.slotNumber;
 
     try {
-      const { currentSlot, nextSlot } = this.epochCache.getCurrentAndNextSlot();
+      // Use target slots since proposals target pipeline slots (slot + 1 when pipelining)
+      const { targetSlot, nextSlot } = this.epochCache.getTargetAndNextSlot();
 
-      if (slotNumber !== currentSlot && slotNumber !== nextSlot) {
+      if (slotNumber !== targetSlot && slotNumber !== nextSlot) {
         // Check if message is for previous slot and within clock tolerance
-        if (!isWithinClockTolerance(slotNumber, currentSlot, this.epochCache)) {
+        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 };
         }

package/src/msg_validators/clock_tolerance.ts

@@ -36,10 +36,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;
   }
 

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.
+

package/src/msg_validators/proposal_validator/block_proposal_validator.ts

@@ -1,10 +1,20 @@
 import type { EpochCacheInterface } from '@aztec/epoch-cache';
-import type { BlockProposal, P2PValidator } from '@aztec/stdlib/p2p';
+import type { BlockProposal, P2PValidator, ValidationResult } from '@aztec/stdlib/p2p';
 
 import { ProposalValidator } from '../proposal_validator/proposal_validator.js';
 
-export class BlockProposalValidator extends ProposalValidator<BlockProposal> implements P2PValidator<BlockProposal> {
+export class BlockProposalValidator implements P2PValidator<BlockProposal> {
+  private proposalValidator: ProposalValidator;
+
   constructor(epochCache: EpochCacheInterface, opts: { txsPermitted: boolean; maxTxsPerBlock?: number }) {
-    super(epochCache, opts, 'p2p:block_proposal_validator');
+    this.proposalValidator = new ProposalValidator(epochCache, opts, 'p2p:block_proposal_validator');
+  }
+
+  async validate(proposal: BlockProposal): Promise<ValidationResult> {
+    const headerResult = await this.proposalValidator.validate(proposal);
+    if (headerResult.result !== 'accept') {
+      return headerResult;
+    }
+    return this.proposalValidator.validateTxs(proposal);
   }
 }