@aztec/p2p 0.0.1-commit.d431d1c → 0.0.1-commit.dbf9cec

package/src/msg_validators/attestation_validator/attestation_validator.ts

@@ -1,7 +1,14 @@
 import type { EpochCacheInterface } from '@aztec/epoch-cache';
 import { NoCommitteeError } from '@aztec/ethereum/contracts';
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import { type CheckpointAttestation, type P2PValidator, PeerErrorSeverity } from '@aztec/stdlib/p2p';
+import {
+  type CheckpointAttestation,
+  type P2PValidator,
+  PeerErrorSeverity,
+  type ValidationResult,
+} from '@aztec/stdlib/p2p';
+
+import { isWithinClockTolerance } from '../clock_tolerance.js';
 
 export class CheckpointAttestationValidator implements P2PValidator<CheckpointAttestation> {
   protected epochCache: EpochCacheInterface;
@@ -12,30 +19,35 @@ export class CheckpointAttestationValidator implements P2PValidator<CheckpointAt
     this.logger = createLogger('p2p:checkpoint-attestation-validator');
   }
 
-  async validate(message: CheckpointAttestation): Promise<PeerErrorSeverity | undefined> {
+  async validate(message: CheckpointAttestation): Promise<ValidationResult> {
     const slotNumber = message.payload.header.slotNumber;
 
     try {
       const { currentSlot, nextSlot } = this.epochCache.getCurrentAndNextSlot();
 
       if (slotNumber !== currentSlot && slotNumber !== nextSlot) {
-        this.logger.warn(
-          `Checkpoint attestation slot ${slotNumber} is not current (${currentSlot}) or next (${nextSlot}) slot`,
-        );
-        return PeerErrorSeverity.HighToleranceError;
+        // Check if message is for previous slot and within clock tolerance
+        if (!isWithinClockTolerance(slotNumber, currentSlot, this.epochCache)) {
+          this.logger.warn(
+            `Checkpoint attestation slot ${slotNumber} is not current (${currentSlot}) or next (${nextSlot}) slot`,
+          );
+          return { result: 'reject', severity: PeerErrorSeverity.HighToleranceError };
+        }
+        this.logger.debug(`Ignoring checkpoint attestation for previous slot ${slotNumber} within clock tolerance`);
+        return { result: 'ignore' };
       }
 
       // Verify the signature is valid
       const attester = message.getSender();
       if (attester === undefined) {
         this.logger.warn(`Invalid signature in checkpoint attestation for slot ${slotNumber}`);
-        return PeerErrorSeverity.LowToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.LowToleranceError };
       }
 
       // Verify the attester is in the committee for this slot
       if (!(await this.epochCache.isInCommittee(slotNumber, attester))) {
         this.logger.warn(`Attester ${attester.toString()} is not in committee for slot ${slotNumber}`);
-        return PeerErrorSeverity.HighToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.HighToleranceError };
       }
 
       // Verify the proposer signature matches the expected proposer for the attestation's slot
@@ -45,26 +57,26 @@ export class CheckpointAttestationValidator implements P2PValidator<CheckpointAt
       const expectedProposer = await this.epochCache.getProposerAttesterAddressInSlot(slotNumber);
       if (!expectedProposer) {
         this.logger.warn(`No proposer defined for slot ${slotNumber}`);
-        return PeerErrorSeverity.HighToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.HighToleranceError };
       }
       if (!proposer) {
         this.logger.warn(`Invalid proposer signature in checkpoint attestation for slot ${slotNumber}`);
-        return PeerErrorSeverity.LowToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.LowToleranceError };
       }
       if (!proposer.equals(expectedProposer)) {
         this.logger.warn(
           `Proposer signature mismatch in checkpoint attestation. ` +
             `Expected ${expectedProposer?.toString() ?? 'none'} but got ${proposer.toString()} for slot ${slotNumber}`,
         );
-        return PeerErrorSeverity.HighToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.HighToleranceError };
       }
 
-      return undefined;
+      return { result: 'accept' };
     } catch (e) {
       // People shouldn't be sending us attestations if the committee doesn't exist
       if (e instanceof NoCommitteeError) {
         this.logger.warn(`No committee exists for checkpoint attestation for slot ${slotNumber}`);
-        return PeerErrorSeverity.LowToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.LowToleranceError };
       }
       throw e;
     }

package/src/msg_validators/attestation_validator/fisherman_attestation_validator.ts

@@ -1,8 +1,8 @@
 import type { EpochCacheInterface } from '@aztec/epoch-cache';
-import { type CheckpointAttestation, PeerErrorSeverity } from '@aztec/stdlib/p2p';
-import { Attributes, Metrics, type TelemetryClient } from '@aztec/telemetry-client';
+import { type CheckpointAttestation, PeerErrorSeverity, type ValidationResult } from '@aztec/stdlib/p2p';
+import { Attributes, Metrics, type TelemetryClient, createUpDownCounterWithDefault } from '@aztec/telemetry-client';
 
-import type { AttestationPool } from '../../mem_pools/attestation_pool/attestation_pool.js';
+import type { AttestationPoolApi } from '../../mem_pools/attestation_pool/attestation_pool.js';
 import { CheckpointAttestationValidator } from './attestation_validator.js';
 
 /**
@@ -18,20 +18,26 @@ export class FishermanAttestationValidator extends CheckpointAttestationValidato
 
   constructor(
     epochCache: EpochCacheInterface,
-    private attestationPool: AttestationPool,
+    private attestationPool: AttestationPoolApi,
     telemetryClient: TelemetryClient,
   ) {
     super(epochCache);
     this.logger = this.logger.createChild('[FISHERMAN]');
 
     const meter = telemetryClient.getMeter('FishermanAttestationValidator');
-    this.invalidAttestationCounter = meter.createUpDownCounter(Metrics.VALIDATOR_INVALID_ATTESTATION_RECEIVED_COUNT);
+    this.invalidAttestationCounter = createUpDownCounterWithDefault(
+      meter,
+      Metrics.VALIDATOR_INVALID_ATTESTATION_RECEIVED_COUNT,
+      {
+        [Attributes.ERROR_TYPE]: ['base_validation_failed', 'payload_mismatch'],
+      },
+    );
   }
 
-  override async validate(message: CheckpointAttestation): Promise<PeerErrorSeverity | undefined> {
+  override async validate(message: CheckpointAttestation): Promise<ValidationResult> {
     // First run the standard validation
     const baseValidationResult = await super.validate(message);
-    if (baseValidationResult !== undefined) {
+    if (baseValidationResult.result !== 'accept') {
       // Track base validation failures (invalid signature, wrong committee, etc.)
       this.invalidAttestationCounter.add(1, {
         [Attributes.ERROR_TYPE]: 'base_validation_failed',
@@ -45,7 +51,7 @@ export class FishermanAttestationValidator extends CheckpointAttestationValidato
     const proposer = message.getProposer();
 
     if (!attester || !proposer) {
-      return undefined;
+      return { result: 'accept' };
     }
 
     const proposalId = message.archive.toString();
@@ -74,7 +80,7 @@ export class FishermanAttestationValidator extends CheckpointAttestationValidato
         });
 
         // Return error to reject the message, but LibP2PService won't penalize in fisherman mode
-        return PeerErrorSeverity.LowToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.LowToleranceError };
       }
     } else {
       // We might receive attestations before proposals in some cases
@@ -83,6 +89,6 @@ export class FishermanAttestationValidator extends CheckpointAttestationValidato
       );
     }
 
-    return undefined;
+    return { result: 'accept' };
   }
 }

package/src/msg_validators/clock_tolerance.ts

@@ -0,0 +1,51 @@
+import type { EpochCacheInterface } from '@aztec/epoch-cache';
+import { SlotNumber } from '@aztec/foundation/branded-types';
+
+/**
+ * Maximum clock disparity tolerance for P2P message validation (in milliseconds).
+ * Messages for the previous slot are accepted if we're within this many milliseconds
+ * of the current slot start. This prevents penalizing peers for messages that
+ * were valid when sent but arrived slightly late due to network latency.
+ *
+ * This follows Ethereum's MAXIMUM_GOSSIP_CLOCK_DISPARITY approach.
+ */
+export const MAXIMUM_GOSSIP_CLOCK_DISPARITY_MS = 500;
+
+/**
+ * Checks if a message for the previous slot should be accepted due to clock tolerance.
+ *
+ * @param messageSlot - The slot number from the received message
+ * @param currentSlot - The current slot number
+ * @param epochCache - EpochCache to get timing information
+ * @returns true if the message is for the previous slot AND we're within the clock tolerance window
+ */
+export function isWithinClockTolerance(
+  messageSlot: SlotNumber,
+  currentSlot: SlotNumber,
+  epochCache: EpochCacheInterface,
+): boolean {
+  // Guard against slot 0 edge case (genesis)
+  if (currentSlot === SlotNumber.ZERO) {
+    return false;
+  }
+
+  // Only apply tolerance to messages for the previous slot
+  const previousSlot = SlotNumber(currentSlot - 1);
+  if (messageSlot !== previousSlot) {
+    return false;
+  }
+
+  // Check how far we are into the current slot (in milliseconds)
+  const { ts: slotStartTs, nowMs, slot } = epochCache.getEpochAndSlotNow();
+
+  // Sanity check: ensure the epoch cache's current slot matches the expected current slot
+  if (slot !== currentSlot) {
+    return false;
+  }
+
+  // ts is in seconds, convert to ms; nowMs is already in milliseconds
+  const slotStartMs = slotStartTs * 1000n;
+  const elapsedMs = Number(nowMs - slotStartMs);
+
+  return elapsedMs < MAXIMUM_GOSSIP_CLOCK_DISPARITY_MS;
+}

package/src/msg_validators/proposal_validator/proposal_validator.ts

@@ -1,7 +1,9 @@
 import type { EpochCacheInterface } from '@aztec/epoch-cache';
 import { NoCommitteeError } from '@aztec/ethereum/contracts';
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import { BlockProposal, CheckpointProposal, PeerErrorSeverity } from '@aztec/stdlib/p2p';
+import { BlockProposal, CheckpointProposal, PeerErrorSeverity, type ValidationResult } from '@aztec/stdlib/p2p';
+
+import { isWithinClockTolerance } from '../clock_tolerance.js';
 
 export abstract class ProposalValidator<TProposal extends BlockProposal | CheckpointProposal> {
   protected epochCache: EpochCacheInterface;
@@ -14,30 +16,35 @@ export abstract class ProposalValidator<TProposal extends BlockProposal | Checkp
     this.logger = createLogger(loggerName);
   }
 
-  public async validate(proposal: TProposal): Promise<PeerErrorSeverity | undefined> {
+  public async validate(proposal: TProposal): Promise<ValidationResult> {
     try {
       // Slot check
       const { currentSlot, nextSlot } = this.epochCache.getCurrentAndNextSlot();
       const slotNumber = proposal.slotNumber;
       if (slotNumber !== currentSlot && slotNumber !== nextSlot) {
-        this.logger.debug(`Penalizing peer for invalid slot number ${slotNumber}`, { currentSlot, nextSlot });
-        return PeerErrorSeverity.HighToleranceError;
+        // Check if message is for previous slot and within clock tolerance
+        if (!isWithinClockTolerance(slotNumber, currentSlot, this.epochCache)) {
+          this.logger.warn(`Penalizing peer for invalid slot number ${slotNumber}`, { currentSlot, nextSlot });
+          return { result: 'reject', severity: PeerErrorSeverity.HighToleranceError };
+        }
+        this.logger.verbose(`Ignoring proposal for previous slot ${slotNumber} within clock tolerance`);
+        return { result: 'ignore' };
       }
 
       // Signature validity
       const proposer = proposal.getSender();
       if (!proposer) {
-        this.logger.debug(`Penalizing peer for proposal with invalid signature`);
-        return PeerErrorSeverity.MidToleranceError;
+        this.logger.warn(`Penalizing peer for proposal with invalid signature`);
+        return { result: 'reject', severity: PeerErrorSeverity.MidToleranceError };
       }
 
       // Transactions permitted check
       const embeddedTxCount = proposal.txs?.length ?? 0;
       if (!this.txsPermitted && (proposal.txHashes.length > 0 || embeddedTxCount > 0)) {
-        this.logger.debug(
+        this.logger.warn(
           `Penalizing peer for proposal with ${proposal.txHashes.length} transaction(s) when transactions are not permitted`,
         );
-        return PeerErrorSeverity.MidToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.MidToleranceError };
       }
 
       // Embedded txs must be listed in txHashes
@@ -52,17 +59,17 @@ export abstract class ProposalValidator<TProposal extends BlockProposal | Checkp
           txHashesLength: proposal.txHashes.length,
           missingTxHashes,
         });
-        return PeerErrorSeverity.MidToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.MidToleranceError };
       }
 
       // Proposer check
       const expectedProposer = await this.epochCache.getProposerAttesterAddressInSlot(slotNumber);
       if (expectedProposer !== undefined && !proposer.equals(expectedProposer)) {
-        this.logger.debug(`Penalizing peer for invalid proposer for current slot ${slotNumber}`, {
+        this.logger.warn(`Penalizing peer for invalid proposer for current slot ${slotNumber}`, {
           expectedProposer,
           proposer: proposer.toString(),
         });
-        return PeerErrorSeverity.MidToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.MidToleranceError };
       }
 
       // Validate tx hashes for all txs embedded in the proposal
@@ -71,13 +78,13 @@ export abstract class ProposalValidator<TProposal extends BlockProposal | Checkp
           proposer,
           slotNumber,
         });
-        return PeerErrorSeverity.LowToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.LowToleranceError };
       }
 
-      return undefined;
+      return { result: 'accept' };
     } catch (e) {
       if (e instanceof NoCommitteeError) {
-        return PeerErrorSeverity.LowToleranceError;
+        return { result: 'reject', severity: PeerErrorSeverity.LowToleranceError };
       }
       throw e;
     }

package/src/msg_validators/proposal_validator/proposal_validator_test_suite.ts

@@ -1,7 +1,12 @@
 import type { EpochCacheInterface } from '@aztec/epoch-cache';
 import type { Secp256k1Signer } from '@aztec/foundation/crypto/secp256k1-signer';
 import type { EthAddress } from '@aztec/foundation/eth-address';
-import { type BlockProposal, type CheckpointProposal, PeerErrorSeverity } from '@aztec/stdlib/p2p';
+import {
+  type BlockProposal,
+  type CheckpointProposal,
+  PeerErrorSeverity,
+  type ValidationResult,
+} from '@aztec/stdlib/p2p';
 import type { TxHash } from '@aztec/stdlib/tx';
 
 import type { MockProxy } from 'jest-mock-extended';
@@ -10,7 +15,7 @@ export interface ProposalValidatorTestParams<TProposal extends BlockProposal | C
   validatorFactory: (
     epochCache: EpochCacheInterface,
     opts: { txsPermitted: boolean },
-  ) => { validate: (proposal: TProposal) => Promise<PeerErrorSeverity | undefined> };
+  ) => { validate: (proposal: TProposal) => Promise<ValidationResult> };
   makeProposal: (options?: any) => Promise<TProposal>;
   makeHeader: (epochNumber: number | bigint, slotNumber: number | bigint, blockNumber: number | bigint) => any;
   getSigner: () => Secp256k1Signer;
@@ -29,11 +34,12 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
   describe('shared proposal validation logic', () => {
     let epochCache: MockProxy<EpochCacheInterface>;
-    let validator: { validate: (proposal: TProposal) => Promise<PeerErrorSeverity | undefined> };
+    let validator: { validate: (proposal: TProposal) => Promise<ValidationResult> };
+    const previousSlot = getSlot(99);
     const currentSlot = getSlot(100);
     const nextSlot = getSlot(101);
 
-    function mockGetProposer(currentProposer: EthAddress, nextProposer: EthAddress) {
+    function mockGetProposer(currentProposer: EthAddress, nextProposer: EthAddress, previousProposer?: EthAddress) {
       epochCache.getProposerAttesterAddressInSlot.mockImplementation(slot => {
         if (slot === currentSlot) {
           return Promise.resolve(currentProposer);
@@ -41,6 +47,9 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
         if (slot === nextSlot) {
           return Promise.resolve(nextProposer);
         }
+        if (slot === previousSlot && previousProposer) {
+          return Promise.resolve(previousProposer);
+        }
         throw new Error('Unexpected argument');
       });
     }
@@ -54,18 +63,48 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
       });
     });
 
-    it('returns high tolerance error if slot number is not current or next slot', async () => {
+    it('returns high tolerance error if slot number is not current or next slot (outside clock tolerance)', async () => {
       const header = makeHeader(1, 99, 99);
       const mockProposal = await makeProposal({ blockHeader: header, lastBlockHeader: header });
 
+      // Mock getEpochAndSlotNow to return time OUTSIDE clock tolerance (1000ms elapsed)
+      epochCache.getEpochAndSlotNow.mockReturnValue({
+        epoch: 1 as any,
+        slot: currentSlot,
+        ts: 1000n, // slot started at 1000 seconds
+        nowMs: 1001000n, // 1000ms elapsed, outside 500ms tolerance
+      });
+
       epochCache.getProposerAttesterAddressInSlot.mockResolvedValue(getAddress());
       const result = await validator.validate(mockProposal);
-      expect(result).toBe(PeerErrorSeverity.HighToleranceError);
+      expect(result).toEqual({ result: 'reject', severity: PeerErrorSeverity.HighToleranceError });
 
       // Should not try to resolve proposers if base validation fails
       expect(epochCache.getProposerAttesterAddressInSlot).not.toHaveBeenCalled();
     });
 
+    it('returns ignore if previous slot proposal is within clock tolerance', async () => {
+      const previousProposer = getSigner();
+      const header = makeHeader(1, 99, 99);
+      const mockProposal = await makeProposal({
+        blockHeader: header,
+        lastBlockHeader: header,
+        signer: previousProposer,
+      });
+
+      // Mock getEpochAndSlotNow to return time WITHIN clock tolerance (100ms elapsed)
+      epochCache.getEpochAndSlotNow.mockReturnValue({
+        epoch: 1 as any,
+        slot: currentSlot,
+        ts: 1000n, // slot started at 1000 seconds
+        nowMs: 1000100n, // 100ms elapsed, within 500ms tolerance
+      });
+
+      mockGetProposer(getAddress(), getAddress(), getAddress(previousProposer));
+      const result = await validator.validate(mockProposal);
+      expect(result).toEqual({ result: 'ignore' });
+    });
+
     it('returns mid tolerance error if proposer is not current proposer for current slot', async () => {
       const currentProposer = getSigner();
       const nextProposer = getSigner();
@@ -79,7 +118,7 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
       mockGetProposer(getAddress(currentProposer), getAddress(nextProposer));
       const result = await validator.validate(mockProposal);
-      expect(result).toBe(PeerErrorSeverity.MidToleranceError);
+      expect(result).toEqual({ result: 'reject', severity: PeerErrorSeverity.MidToleranceError });
     });
 
     it('returns mid tolerance error if proposer is not next proposer for next slot', async () => {
@@ -95,7 +134,7 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
       mockGetProposer(getAddress(currentProposer), getAddress(nextProposer));
       const result = await validator.validate(mockProposal);
-      expect(result).toBe(PeerErrorSeverity.MidToleranceError);
+      expect(result).toEqual({ result: 'reject', severity: PeerErrorSeverity.MidToleranceError });
     });
 
     it('returns mid tolerance error if proposer is current proposer but proposal is for next slot', async () => {
@@ -110,7 +149,7 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
       mockGetProposer(getAddress(currentProposer), getAddress(nextProposer));
       const result = await validator.validate(mockProposal);
-      expect(result).toBe(PeerErrorSeverity.MidToleranceError);
+      expect(result).toEqual({ result: 'reject', severity: PeerErrorSeverity.MidToleranceError });
     });
 
     it('returns undefined if proposal is valid for current slot and proposer', async () => {
@@ -125,7 +164,7 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
       mockGetProposer(getAddress(currentProposer), getAddress(nextProposer));
       const result = await validator.validate(mockProposal);
-      expect(result).toBeUndefined();
+      expect(result).toEqual({ result: 'accept' });
     });
 
     it('returns undefined if proposal is valid for next slot and proposer', async () => {
@@ -136,7 +175,7 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
       mockGetProposer(getAddress(currentProposer), getAddress(nextProposer));
       const result = await validator.validate(mockProposal);
-      expect(result).toBeUndefined();
+      expect(result).toEqual({ result: 'accept' });
     });
 
     describe('transaction permission validation', () => {
@@ -153,7 +192,7 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
         mockGetProposer(getAddress(currentProposer), getAddress());
         const result = await validatorWithTxsDisabled.validate(mockProposal);
-        expect(result).toBe(PeerErrorSeverity.MidToleranceError);
+        expect(result).toEqual({ result: 'reject', severity: PeerErrorSeverity.MidToleranceError });
       });
 
       it('returns undefined if txs not permitted but proposal has no txHashes', async () => {
@@ -169,7 +208,7 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
         mockGetProposer(getAddress(currentProposer), getAddress());
         const result = await validatorWithTxsDisabled.validate(mockProposal);
-        expect(result).toBeUndefined();
+        expect(result).toEqual({ result: 'accept' });
       });
 
       it('returns undefined if txs permitted and proposal contains txHashes', async () => {
@@ -184,7 +223,7 @@ export function sharedProposalValidatorTests<TProposal extends BlockProposal | C
 
         mockGetProposer(getAddress(currentProposer), getAddress());
         const result = await validator.validate(mockProposal);
-        expect(result).toBeUndefined();
+        expect(result).toEqual({ result: 'accept' });
       });
     });
   });

package/src/msg_validators/tx_validator/README.md

@@ -0,0 +1,115 @@
+# Transaction Validation
+
+This module defines the transaction validators and the factory functions that assemble them for each entry point into the system.
+
+## Validation Strategy
+
+Transactions enter the system through different paths. **Unsolicited** transactions (gossip and RPC) are fully validated before acceptance. **Solicited** transactions (req/resp and block proposals) are only checked for well-formedness because we must store them for block re-execution — they may ultimately be invalid, which is caught during block building and reported as part of block validation/attestation.
+
+When solicited transactions fail to be mined, they may be migrated to the pending pool. At that point, the pool runs the state-dependent checks that were skipped on initial receipt.
+
+## Entry Points
+
+### 1. Gossip (libp2p pubsub)
+
+**Factory**: `createFirstStageTxValidationsForGossipedTransactions` + `createSecondStageTxValidationsForGossipedTransactions`
+**Called from**: `LibP2PService.handleGossipedTx()` in `libp2p_service.ts`
+
+Unsolicited transactions from any peer. Fully validated in two stages with a pool pre-check in between to avoid wasting CPU on proof verification for transactions the pool would reject:
+
+| Step | What runs | On failure |
+|------|-----------|------------|
+| **Stage 1** (fast) | TxPermitted, Data, Metadata, Timestamp, DoubleSpend, Gas, Phases, BlockHeader | Penalize peer, reject tx |
+| **Pool pre-check** | `canAddPendingTx` — checks for duplicates, pool capacity | Ignore tx (no penalty) |
+| **Stage 2** (slow) | Proof verification | Penalize peer, reject tx |
+| **Pool add** | `addPendingTxs` | Accept, ignore, or reject |
+
+Each stage-1 and stage-2 validator is paired with a `PeerErrorSeverity`. If a validator fails, the sending peer is penalized with that severity. The `doubleSpendValidator` has special handling: its severity is determined by how recently the nullifier appeared (recent = high tolerance, old = low tolerance).
+
+### 2. JSON-RPC
+
+**Factory**: `createTxValidatorForAcceptingTxsOverRPC`
+**Called from**: `AztecNodeService.isValidTx()` in `aztec-node/server.ts`
+
+Unsolicited transactions from a local wallet/PXE. Runs the full set of checks as a single aggregate validator:
+
+- TxPermitted, Size, Data, Metadata, Timestamp, DoubleSpend, Phases, BlockHeader
+- Gas (optional — skipped when `skipFeeEnforcement` is set)
+- Proof verification (optional — skipped for simulations when no verifier is provided)
+
+### 3. Req/resp and block proposals
+
+**Factories**: `createTxValidatorForReqResponseReceivedTxs`, `createTxValidatorForBlockProposalReceivedTxs`
+**Called from**: `LibP2PService.validateRequestedTx()`, `LibP2PService.validateTxsReceivedInBlockProposal()`, and `BatchRequestTxValidator` in `batch-tx-requester/tx_validator.ts`
+
+Solicited transactions — we requested these from peers or received them as part of a block proposal we need to validate. We must accept them for re-execution even if they are invalid against the current state. Only well-formedness is checked:
+
+- Metadata, Size, Data, Proof
+
+State-dependent checks are deferred to either the block building validator (for txs included in blocks) or the pending pool migration validator (for unmined txs migrating to pending).
+
+### 4. Block building
+
+**Factory**: `createTxValidatorForBlockBuilding`
+**Called from**: `CheckpointBuilder.makeBlockBuilderDeps()` in `validator-client/checkpoint_builder.ts`
+
+Transactions already in the pool, about to be sequenced into a block. Re-validates against the current state of the block being built. **This is where invalid txs that entered via req/resp or block proposals are caught** — their invalidity is reported as part of block validation/attestation.
+
+Runs:
+- Timestamp, DoubleSpend, Phases, Gas, BlockHeader
+
+Does **not** run:
+- Proof, Data — already verified on entry (by gossip, RPC, or req/resp validators)
+
+### 5. Pending pool migration
+
+**Factory**: `createTxValidatorForTransactionsEnteringPendingTxPool`
+**Called from**: `TxPoolV2Impl` (injected as the `createTxValidator` factory via `TxPoolV2Dependencies`)
+
+When transactions that arrived via req/resp or block proposals fail to be mined, they may need to be included in our pending pool. These txs only had well-formedness checks on receipt, so the pool runs the state-dependent checks they missed before accepting them.
+
+This validator is invoked on **every** transaction potentially entering the pending pool:
+- `addPendingTxs` — validating each tx before adding
+- `prepareForSlot` — unprotecting txs back to pending after a slot ends
+- `handlePrunedBlocks` — unmining txs from pruned blocks back to pending
+- Startup hydration — revalidating persisted non-mined txs on node restart
+
+Runs:
+- DoubleSpend, BlockHeader, GasLimits, Timestamp
+
+Operates on `TxMetaData` (pre-built by the pool) rather than full `Tx` objects.
+
+## Individual Validators
+
+| Validator | What it checks | Benchmarked verification duration |
+|-----------|---------------|---------------|
+| `TxPermittedValidator` | Whether the system is accepting transactions (controlled by config flag) | 1.56 us |
+| `DataTxValidator` | Transaction data integrity — correct structure, non-empty fields | 4.10–18.18 ms |
+| `SizeTxValidator` | Transaction does not exceed maximum size limits | 2.28 us |
+| `MetadataTxValidator` | Chain ID, rollup version, protocol contracts hash, VK tree root | 4.18 us |
+| `TimestampTxValidator` | Transaction has not expired (expiration timestamp vs next slot) | 1.56 us |
+| `DoubleSpendTxValidator` | Nullifiers do not already exist in the nullifier tree | 106.08 us |
+| `GasTxValidator` | Gas limits are within bounds (delegates to `GasLimitsValidator`), max fee per gas meets current block fees, and fee payer has sufficient FeeJuice balance | 1.02 ms |
+| `GasLimitsValidator` | Gas limits are >= fixed minimums and <= AVM max processable L2 gas. Used standalone in pool migration; also called internally by `GasTxValidator` | 3–10 us |
+| `PhasesTxValidator` | Public function calls in setup phase are on the allow list | 10.12–13.12 us |
+| `BlockHeaderTxValidator` | Transaction's anchor block hash exists in the archive tree | 98.88 us |
+| `TxProofValidator` | Client proof verifies correctly | ~250ms |
+
+## Validator Coverage by Entry Point
+
+| Validator | Gossip | RPC | Req/resp | Block building | Pool migration |
+|-----------|--------|-----|----------|----------------|----------------|
+| TxPermitted | Stage 1 | Yes | — | — | — |
+| Data | Stage 1 | Yes | Yes | — | — |
+| Size | — | Yes | Yes | — | — |
+| Metadata | Stage 1 | Yes | Yes | — | — |
+| Timestamp | Stage 1 | Yes | — | Yes | Yes |
+| DoubleSpend | Stage 1 | Yes | — | Yes | Yes |
+| Gas (balance + limits) | Stage 1 | Optional* | — | Yes | — |
+| GasLimits (standalone) | — | — | — | — | Yes |
+| Phases | Stage 1 | Yes | — | Yes | — |
+| BlockHeader | Stage 1 | Yes | — | Yes | Yes |
+| Proof | Stage 2 | Optional** | Yes | — | — |
+
+\* Gas balance check is skipped when `skipFeeEnforcement` is set (testing/dev). `GasTxValidator` internally delegates to `GasLimitsValidator` as its first step, so gas limits are checked wherever `GasTxValidator` runs. Pool migration uses `GasLimitsValidator` standalone because it doesn't need the balance or fee-per-gas checks.
+\** Proof verification is skipped for simulations (no verifier provided).

package/src/msg_validators/tx_validator/aggregate_tx_validator.ts

@@ -1,18 +1,18 @@
-import type { ProcessedTx, Tx, TxValidationResult, TxValidator } from '@aztec/stdlib/tx';
+import type { TxValidationResult, TxValidator } from '@aztec/stdlib/tx';
 
-export class AggregateTxValidator<T extends Tx | ProcessedTx> implements TxValidator<T> {
-  #validators: TxValidator<T>[];
+export class AggregateTxValidator<T> implements TxValidator<T> {
+  readonly validators: TxValidator<T>[];
   constructor(...validators: TxValidator<T>[]) {
     if (validators.length === 0) {
       throw new Error('At least one validator must be provided');
     }
 
-    this.#validators = validators;
+    this.validators = validators;
   }
 
   async validateTx(tx: T): Promise<TxValidationResult> {
     const aggregate: { result: string; reason?: string[] } = { result: 'valid', reason: [] };
-    for (const validator of this.#validators) {
+    for (const validator of this.validators) {
       const result = await validator.validateTx(tx);
       if (result.result === 'invalid') {
         aggregate.result = 'invalid';

package/src/msg_validators/tx_validator/archive_cache.ts

@@ -1,5 +1,5 @@
-import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { ArchiveSource } from '@aztec/p2p';
+import type { BlockHash } from '@aztec/stdlib/block';
 import type { MerkleTreeReadOperations } from '@aztec/stdlib/interfaces/server';
 import { MerkleTreeId } from '@aztec/stdlib/trees';
 
@@ -14,8 +14,8 @@ export class ArchiveCache implements ArchiveSource {
     this.archives = new Map<string, bigint>();
   }
 
-  public async getArchiveIndices(archives: Fr[]): Promise<(bigint | undefined)[]> {
-    const toCheckDb = archives.filter(n => !this.archives.has(n.toString()));
+  public async getArchiveIndices(archives: BlockHash[]): Promise<(bigint | undefined)[]> {
+    const toCheckDb = archives.filter(n => !this.archives.has(n.toString())).map(n => n.toFr());
     const dbHits = await this.db.findLeafIndices(MerkleTreeId.ARCHIVE, toCheckDb);
     dbHits.forEach((x, index) => {
       if (x !== undefined) {