@aztec/p2p 4.0.0-rc.5 → 4.0.0-rc.7

package/src/mem_pools/tx_pool_v2/tx_pool_v2_impl.ts

@@ -187,6 +187,30 @@ 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;
@@ -202,22 +226,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 +254,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 +284,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'}`);
@@ -317,11 +336,11 @@ export class TxPoolV2Impl {
     }
 
     // Add the transaction
-    await this.#addTx(tx, 'pending', opts);
+    await this.#addTx(tx, 'pending', opts, precomputedMeta);
     return { status: 'accepted' };
   }
 
-  async canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored' | 'rejected'> {
+  async canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored'> {
     const txHashStr = tx.getTxHash().toString();
 
     // Check if already in pool
@@ -329,14 +348,8 @@ export class TxPoolV2Impl {
       return 'ignored';
     }
 
-    // Build metadata and validate using metadata
+    // Build metadata and check pre-add rules
     const meta = await buildTxMetaData(tx);
-    const validationResult = await this.#validateMeta(meta, undefined, 'can add pending');
-    if (validationResult !== true) {
-      return 'rejected';
-    }
-
-    // Use pre-add rules
     const poolAccess = this.#createPreAddPoolAccess();
     const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess);
 
@@ -765,9 +778,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());

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 { TxValidationResult, TxValidator } from '@aztec/stdlib/tx';
 
 export class AggregateTxValidator<T> implements TxValidator<T> {
-  #validators: 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';