@aztec/p2p 0.0.1-commit.c7c42ec → 0.0.1-commit.c949de6bc

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) {

package/src/msg_validators/tx_validator/block_header_validator.ts

@@ -1,23 +1,36 @@
-import type { Fr } from '@aztec/foundation/curves/bn254';
-import { createLogger } from '@aztec/foundation/log';
-import { type AnyTx, TX_ERROR_BLOCK_HEADER, type TxValidationResult, type TxValidator } from '@aztec/stdlib/tx';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import type { BlockHash } from '@aztec/stdlib/block';
+import { TX_ERROR_BLOCK_HEADER, type TxValidationResult, type TxValidator } from '@aztec/stdlib/tx';
 
 export interface ArchiveSource {
-  getArchiveIndices: (archives: Fr[]) => Promise<(bigint | undefined)[]>;
+  getArchiveIndices: (archives: BlockHash[]) => Promise<(bigint | undefined)[]>;
 }
 
-export class BlockHeaderTxValidator<T extends AnyTx> implements TxValidator<T> {
-  #log = createLogger('p2p:tx_validator:tx_block_header');
+/** Structural interface for block header validation. */
+export interface HasBlockHeaderData {
+  txHash: { toString(): string };
+  data: {
+    constants: {
+      anchorBlockHeader: {
+        hash(): Promise<BlockHash>;
+      };
+    };
+  };
+}
+
+export class BlockHeaderTxValidator<T extends HasBlockHeaderData> implements TxValidator<T> {
+  #log: Logger;
   #archiveSource: ArchiveSource;
 
-  constructor(archiveSource: ArchiveSource) {
+  constructor(archiveSource: ArchiveSource, bindings?: LoggerBindings) {
     this.#archiveSource = archiveSource;
+    this.#log = createLogger('p2p:tx_validator:tx_block_header', bindings);
   }
 
   async validateTx(tx: T): Promise<TxValidationResult> {
     const [index] = await this.#archiveSource.getArchiveIndices([await tx.data.constants.anchorBlockHeader.hash()]);
     if (index === undefined) {
-      this.#log.verbose(`Rejecting tx ${'txHash' in tx ? tx.txHash : tx.hash} for referencing an unknown block header`);
+      this.#log.verbose(`Rejecting tx ${tx.txHash} for referencing an unknown block header`);
       return { result: 'invalid', reason: [TX_ERROR_BLOCK_HEADER] };
     }
     return { result: 'valid' };

package/src/msg_validators/tx_validator/data_validator.ts

@@ -1,5 +1,5 @@
 import { MAX_FR_CALLDATA_TO_ALL_ENQUEUED_CALLS } from '@aztec/constants';
-import { createLogger } from '@aztec/foundation/log';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
 import { computeCalldataHash } from '@aztec/stdlib/hash';
 import {
   TX_ERROR_CALLDATA_COUNT_MISMATCH,
@@ -16,7 +16,11 @@ import {
 } from '@aztec/stdlib/tx';
 
 export class DataTxValidator implements TxValidator<Tx> {
-  #log = createLogger('p2p:tx_validator:tx_data');
+  #log: Logger;
+
+  constructor(bindings?: LoggerBindings) {
+    this.#log = createLogger('p2p:tx_validator:tx_data', bindings);
+  }
 
   async validateTx(tx: Tx): Promise<TxValidationResult> {
     const reason =
@@ -31,7 +35,9 @@ export class DataTxValidator implements TxValidator<Tx> {
     if (!tx.getTxHash().equals(expected)) {
       const reason = TX_ERROR_INCORRECT_HASH;
       this.#log.verbose(
-        `Rejecting tx ${tx.getTxHash().toString()}. Reason: ${reason}. Expected hash ${expected.toString()}. Got ${tx.getTxHash().toString()}.`,
+        `Rejecting tx ${tx.getTxHash().toString()}. Reason: ${reason}. Expected hash ${expected.toString()}. Got ${tx
+          .getTxHash()
+          .toString()}.`,
       );
       return reason;
     }
@@ -52,7 +58,9 @@ export class DataTxValidator implements TxValidator<Tx> {
     if (tx.getTotalPublicCalldataCount() > MAX_FR_CALLDATA_TO_ALL_ENQUEUED_CALLS) {
       const reason = TX_ERROR_CALLDATA_COUNT_TOO_LARGE;
       this.#log.verbose(
-        `Rejecting tx ${tx.getTxHash().toString()}. Reason: ${reason}. Expected no greater than ${MAX_FR_CALLDATA_TO_ALL_ENQUEUED_CALLS} fields. Got ${tx.getTotalPublicCalldataCount()}.`,
+        `Rejecting tx ${tx
+          .getTxHash()
+          .toString()}. Reason: ${reason}. Expected no greater than ${MAX_FR_CALLDATA_TO_ALL_ENQUEUED_CALLS} fields. Got ${tx.getTotalPublicCalldataCount()}.`,
       );
       return reason;
     }
@@ -89,7 +97,9 @@ export class DataTxValidator implements TxValidator<Tx> {
         if (expectedHashes.some(h => logHash.value.equals(h))) {
           const matchingLogIndex = expectedHashes.findIndex(l => logHash.value.equals(l));
           this.#log.verbose(
-            `Rejecting tx ${tx.getTxHash().toString()} because of mismatched contract class logs indices. Expected ${i} from the kernel's log hashes. Got ${matchingLogIndex} in the tx.`,
+            `Rejecting tx ${tx
+              .getTxHash()
+              .toString()} because of mismatched contract class logs indices. Expected ${i} from the kernel's log hashes. Got ${matchingLogIndex} in the tx.`,
           );
           return TX_ERROR_CONTRACT_CLASS_LOG_SORTING;
         } else {
@@ -105,7 +115,9 @@ export class DataTxValidator implements TxValidator<Tx> {
       const expectedMinLength = 1 + tx.contractClassLogFields[i].fields.findLastIndex(f => !f.isZero());
       if (logHash.logHash.length < expectedMinLength) {
         this.#log.verbose(
-          `Rejecting tx ${tx.getTxHash().toString()} because of incorrect contract class log length. Expected the length to be at least ${expectedMinLength}. Got ${
+          `Rejecting tx ${tx
+            .getTxHash()
+            .toString()} because of incorrect contract class log length. Expected the length to be at least ${expectedMinLength}. Got ${
             logHash.logHash.length
           }.`,
         );

package/src/msg_validators/tx_validator/double_spend_validator.ts

@@ -1,9 +1,8 @@
-import { createLogger } from '@aztec/foundation/log';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
 import {
-  type AnyTx,
   TX_ERROR_DUPLICATE_NULLIFIER_IN_TX,
   TX_ERROR_EXISTING_NULLIFIER,
-  Tx,
   type TxValidationResult,
   type TxValidator,
 } from '@aztec/stdlib/tx';
@@ -12,26 +11,33 @@ export interface NullifierSource {
   nullifiersExist: (nullifiers: Buffer[]) => Promise<boolean[]>;
 }
 
-export class DoubleSpendTxValidator<T extends AnyTx> implements TxValidator<T> {
-  #log = createLogger('p2p:tx_validator:tx_double_spend');
+/** Structural interface for double-spend validation. */
+export interface HasNullifierData {
+  txHash: { toString(): string };
+  data: { getNonEmptyNullifiers(): Fr[] };
+}
+
+export class DoubleSpendTxValidator<T extends HasNullifierData> implements TxValidator<T> {
+  #log: Logger;
   #nullifierSource: NullifierSource;
 
-  constructor(nullifierSource: NullifierSource) {
+  constructor(nullifierSource: NullifierSource, bindings?: LoggerBindings) {
     this.#nullifierSource = nullifierSource;
+    this.#log = createLogger('p2p:tx_validator:tx_double_spend', bindings);
   }
 
   async validateTx(tx: T): Promise<TxValidationResult> {
-    const nullifiers = tx instanceof Tx ? tx.data.getNonEmptyNullifiers() : tx.txEffect.nullifiers;
+    const nullifiers = tx.data.getNonEmptyNullifiers();
 
     // Ditch this tx if it has repeated nullifiers
     const uniqueNullifiers = new Set(nullifiers.map(n => n.toBigInt()));
     if (uniqueNullifiers.size !== nullifiers.length) {
-      this.#log.verbose(`Rejecting tx ${'txHash' in tx ? tx.txHash : tx.hash} for emitting duplicate nullifiers`);
+      this.#log.verbose(`Rejecting tx ${tx.txHash} for emitting duplicate nullifiers`);
       return { result: 'invalid', reason: [TX_ERROR_DUPLICATE_NULLIFIER_IN_TX] };
     }
 
     if ((await this.#nullifierSource.nullifiersExist(nullifiers.map(n => n.toBuffer()))).some(Boolean)) {
-      this.#log.verbose(`Rejecting tx ${'txHash' in tx ? tx.txHash : tx.hash} for repeating a nullifier`);
+      this.#log.verbose(`Rejecting tx ${tx.txHash} for repeating a nullifier`);
       return { result: 'invalid', reason: [TX_ERROR_EXISTING_NULLIFIER] };
     }