@aztec/p2p 0.0.1-commit.4d79d1f2d → 0.0.1-commit.4eabbdb

package/src/mem_pools/tx_pool_v2/tx_pool_v2_impl.ts

@@ -1,5 +1,6 @@
 import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import type { Logger } from '@aztec/foundation/log';
+import type { DateProvider } from '@aztec/foundation/timer';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
 import { ProtocolContractAddress } from '@aztec/protocol-contracts';
 import { computeFeePayerBalanceStorageSlot } from '@aztec/protocol-contracts/fee-juice';
@@ -8,6 +9,7 @@ import type { L2Block, L2BlockId, L2BlockSource } from '@aztec/stdlib/block';
 import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
 import { DatabasePublicStateSource } from '@aztec/stdlib/trees';
 import { BlockHeader, Tx, TxHash, type TxValidator } from '@aztec/stdlib/tx';
+import type { TelemetryClient } from '@aztec/telemetry-client';
 
 import { TxArchive } from './archive/index.js';
 import { DeletedPool } from './deleted_pool.js';
@@ -21,8 +23,12 @@ import {
   LowPriorityPreAddRule,
   NullifierConflictRule,
   type PoolOperations,
+  type PreAddContext,
   type PreAddPoolAccess,
+  TxPoolRejectionCode,
+  type TxPoolRejectionError,
 } from './eviction/index.js';
+import { TxPoolV2Instrumentation } from './instrumentation.js';
 import {
   type AddTxsResult,
   DEFAULT_TX_POOL_V2_CONFIG,
@@ -64,6 +70,9 @@ export class TxPoolV2Impl {
   #archive: TxArchive;
   #deletedPool: DeletedPool;
   #evictionManager: EvictionManager;
+  #dateProvider: DateProvider;
+  #instrumentation: TxPoolV2Instrumentation;
+  #evictedTxHashes: Set<string> = new Set();
   #log: Logger;
   #callbacks: TxPoolV2Callbacks;
 
@@ -72,7 +81,9 @@ export class TxPoolV2Impl {
     archiveStore: AztecAsyncKVStore,
     deps: TxPoolV2Dependencies,
     callbacks: TxPoolV2Callbacks,
+    telemetry: TelemetryClient,
     config: Partial<TxPoolV2Config> = {},
+    dateProvider: DateProvider,
     log: Logger,
   ) {
     this.#store = store;
@@ -85,6 +96,8 @@ export class TxPoolV2Impl {
     this.#config = { ...DEFAULT_TX_POOL_V2_CONFIG, ...config };
     this.#archive = new TxArchive(archiveStore, this.#config.archivedTxLimit, log);
     this.#deletedPool = new DeletedPool(store, this.#txsDB, log);
+    this.#dateProvider = dateProvider;
+    this.#instrumentation = new TxPoolV2Instrumentation(telemetry, () => this.#indices.getTotalMetadataBytes());
     this.#log = log;
     this.#callbacks = callbacks;
 
@@ -164,16 +177,19 @@ export class TxPoolV2Impl {
         await this.#txsDB.delete(txHashStr);
       }
     });
-    this.#log.info(`Deleted ${toDelete.length} invalid/rejected transactions on startup`);
+    this.#log.info(`Deleted ${toDelete.length} invalid/rejected transactions on startup`, { txHashes: toDelete });
   }
 
-  async addPendingTxs(txs: Tx[], opts: { source?: string }): Promise<AddTxsResult> {
+  async addPendingTxs(txs: Tx[], opts: { source?: string; feeComparisonOnly?: boolean }): Promise<AddTxsResult> {
     const accepted: TxHash[] = [];
     const ignored: TxHash[] = [];
     const rejected: TxHash[] = [];
+    const errors = new Map<string, TxPoolRejectionError>();
     const acceptedPending = new Set<string>();
 
     const poolAccess = this.#createPreAddPoolAccess();
+    const preAddContext: PreAddContext | undefined =
+      opts.feeComparisonOnly !== undefined ? { feeComparisonOnly: opts.feeComparisonOnly } : undefined;
 
     await this.#store.transactionAsync(async () => {
       for (const tx of txs) {
@@ -200,7 +216,15 @@ export class TxPoolV2Impl {
           accepted.push(txHash);
         } else {
           // Regular pending tx - validate and run pre-add rules
-          const result = await this.#tryAddRegularPendingTx(tx, opts, poolAccess, acceptedPending, ignored);
+          const result = await this.#tryAddRegularPendingTx(
+            tx,
+            opts,
+            poolAccess,
+            acceptedPending,
+            ignored,
+            errors,
+            preAddContext,
+          );
           if (result.status === 'accepted') {
             acceptedPending.add(txHashStr);
           } else if (result.status === 'rejected') {
@@ -217,6 +241,14 @@ export class TxPoolV2Impl {
       accepted.push(TxHash.fromString(txHashStr));
     }
 
+    // Record metrics
+    if (ignored.length > 0) {
+      this.#instrumentation.recordIgnored(ignored.length);
+    }
+    if (rejected.length > 0) {
+      this.#instrumentation.recordRejected(rejected.length);
+    }
+
     // Run post-add eviction rules for pending txs
     if (acceptedPending.size > 0) {
       const feePayers = Array.from(acceptedPending).map(txHash => this.#indices.getMetadata(txHash)!.feePayer);
@@ -224,7 +256,7 @@ export class TxPoolV2Impl {
       await this.#evictionManager.evictAfterNewTxs(Array.from(acceptedPending), [...uniqueFeePayers]);
     }
 
-    return { accepted, ignored, rejected };
+    return { accepted, ignored, rejected, ...(errors.size > 0 ? { errors } : {}) };
   }
 
   /** Validates and adds a regular pending tx. Returns status. */
@@ -234,6 +266,8 @@ export class TxPoolV2Impl {
     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();
@@ -245,21 +279,40 @@ export class TxPoolV2Impl {
     }
 
     // Run pre-add rules
-    const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess);
+    const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess, preAddContext);
 
     if (preAddResult.shouldIgnore) {
-      this.#log.debug(`Ignoring tx ${txHashStr}: ${preAddResult.reason}`);
+      this.#log.debug(`Ignoring tx ${txHashStr}: ${preAddResult.reason?.message ?? 'unknown reason'}`);
+      if (preAddResult.reason && preAddResult.reason.code !== TxPoolRejectionCode.INTERNAL_ERROR) {
+        errors.set(txHashStr, preAddResult.reason);
+      }
       return { status: 'ignored' };
     }
 
-    // Evict conflicts
-    for (const evictHashStr of preAddResult.txHashesToEvict) {
-      await this.#deleteTx(evictHashStr);
-      this.#log.debug(`Evicted tx ${evictHashStr} due to higher-fee tx ${txHashStr}`);
-      if (acceptedPending.has(evictHashStr)) {
-        // Evicted tx was from this batch - mark as ignored in result
-        acceptedPending.delete(evictHashStr);
-        ignored.push(TxHash.fromString(evictHashStr));
+    // Evict conflicts, grouped by rule name for metrics
+    if (preAddResult.evictions && preAddResult.evictions.length > 0) {
+      const byReason = new Map<string, string[]>();
+      for (const { txHash: evictHash, reason } of preAddResult.evictions) {
+        const group = byReason.get(reason);
+        if (group) {
+          group.push(evictHash);
+        } else {
+          byReason.set(reason, [evictHash]);
+        }
+      }
+      for (const [reason, hashes] of byReason) {
+        await this.#evictTxs(hashes, reason);
+      }
+      for (const evictHashStr of preAddResult.txHashesToEvict) {
+        this.#log.debug(`Evicted tx ${evictHashStr} due to higher-fee tx ${txHashStr}`, {
+          evictedTxHash: evictHashStr,
+          replacementTxHash: txHashStr,
+        });
+        if (acceptedPending.has(evictHashStr)) {
+          // Evicted tx was from this batch - mark as ignored in result
+          acceptedPending.delete(evictHashStr);
+          ignored.push(TxHash.fromString(evictHashStr));
+        }
       }
     }
 
@@ -320,9 +373,11 @@ export class TxPoolV2Impl {
     });
   }
 
-  protectTxs(txHashes: TxHash[], block: BlockHeader): TxHash[] {
+  async protectTxs(txHashes: TxHash[], block: BlockHeader): Promise<TxHash[]> {
     const slotNumber = block.globalVariables.slotNumber;
     const missing: TxHash[] = [];
+    let softDeletedHits = 0;
+    let missingPreviouslyEvicted = 0;
 
     for (const txHash of txHashes) {
       const txHashStr = txHash.toString();
@@ -330,13 +385,44 @@ export class TxPoolV2Impl {
       if (this.#indices.has(txHashStr)) {
         // Update protection for existing tx
         this.#indices.updateProtection(txHashStr, slotNumber);
+      } else if (this.#deletedPool.isSoftDeleted(txHashStr)) {
+        // Resurrect soft-deleted tx as protected
+        const buffer = await this.#txsDB.getAsync(txHashStr);
+        if (buffer) {
+          const tx = Tx.fromBuffer(buffer);
+          await this.#addTx(tx, { protected: slotNumber });
+          softDeletedHits++;
+        } else {
+          // Data missing despite soft-delete flag — treat as truly missing
+          this.#indices.setProtection(txHashStr, slotNumber);
+          missing.push(txHash);
+        }
       } else {
-        // Pre-record protection for tx we don't have yet
+        // Truly missing — pre-record protection for tx we don't have yet
         this.#indices.setProtection(txHashStr, slotNumber);
         missing.push(txHash);
+        if (this.#evictedTxHashes.has(txHashStr)) {
+          missingPreviouslyEvicted++;
+        }
       }
     }
 
+    // Record metrics
+    if (softDeletedHits > 0) {
+      this.#instrumentation.recordSoftDeletedHits(softDeletedHits);
+    }
+    if (missing.length > 0) {
+      this.#log.debug(`protectTxs missing tx hashes: ${missing.map(h => h.toString()).join(', ')}`);
+      this.#instrumentation.recordMissingOnProtect(missing.length);
+    }
+    if (missingPreviouslyEvicted > 0) {
+      this.#instrumentation.recordMissingPreviouslyEvicted(missingPreviouslyEvicted);
+    }
+
+    this.#log.info(
+      `Protected ${txHashes.length} txs, missing: ${missing.length}, soft-deleted hits: ${softDeletedHits}`,
+    );
+
     return missing;
   }
 
@@ -393,6 +479,9 @@ export class TxPoolV2Impl {
   }
 
   async prepareForSlot(slotNumber: SlotNumber): Promise<void> {
+    // Step 0: Clean up slot-deleted txs from previous slots
+    await this.#deletedPool.cleanupSlotDeleted(slotNumber);
+
     // Step 1: Find expired protected txs
     const expiredProtected = this.#indices.findExpiredProtectedTxs(slotNumber);
 
@@ -402,6 +491,7 @@ export class TxPoolV2Impl {
     // Step 3: Filter to only txs that have metadata and are not mined
     const txsToRestore = this.#indices.filterRestorable(expiredProtected);
     if (txsToRestore.length === 0) {
+      this.#log.debug(`Preparing for slot ${slotNumber}, no txs to unprotect`);
       return;
     }
 
@@ -413,8 +503,9 @@ export class TxPoolV2Impl {
     // Step 5: Resolve nullifier conflicts and add winners to pending indices
     const { added, toEvict } = this.#applyNullifierConflictResolution(valid);
 
-    // Step 6: Delete invalid and evicted txs
-    await this.#deleteTxsBatch([...invalid, ...toEvict]);
+    // Step 6: Delete invalid txs and evict conflict losers
+    await this.#deleteTxsBatch(invalid);
+    await this.#evictTxs(toEvict, 'NullifierConflict');
 
     // Step 7: Run eviction rules (enforce pool size limit)
     if (added.length > 0) {
@@ -427,7 +518,7 @@ export class TxPoolV2Impl {
     }
   }
 
-  async handlePrunedBlocks(latestBlock: L2BlockId): Promise<void> {
+  async handlePrunedBlocks(latestBlock: L2BlockId, options?: { deleteAllTxs?: boolean }): Promise<void> {
     // Step 1: Find transactions mined after the prune point
     const txsToUnmine = this.#indices.findTxsMinedAfter(latestBlock.number);
     if (txsToUnmine.length === 0) {
@@ -452,17 +543,33 @@ export class TxPoolV2Impl {
       this.#indices.markAsUnmined(meta);
     }
 
+    // If deleteAllTxs is set (epoch prune), delete all un-mined txs and return early
+    if (options?.deleteAllTxs) {
+      const allTxHashes = txsToUnmine.map(m => m.txHash);
+      await this.#deleteTxsBatch(allTxHashes);
+      this.#log.info(
+        `Handled prune to block ${latestBlock.number} with deleteAllTxs: deleted ${allTxHashes.length} txs`,
+      );
+      return;
+    }
+
     // Step 4: Filter out protected txs (they'll be handled by prepareForSlot)
     const unprotectedTxs = this.#indices.filterUnprotected(txsToUnmine);
 
-    // Step 4: Validate for pending pool
+    // Step 5: Validate for pending pool
     const { valid, invalid } = await this.#revalidateMetadata(unprotectedTxs, 'during handlePrunedBlocks');
 
     // Step 6: Resolve nullifier conflicts and add winners to pending indices
     const { toEvict } = this.#applyNullifierConflictResolution(valid);
 
-    // Step 7: Delete invalid and evicted txs
-    await this.#deleteTxsBatch([...invalid, ...toEvict]);
+    // Step 7: Delete invalid txs and evict conflict losers
+    await this.#deleteTxsBatch(invalid);
+    await this.#evictTxs(toEvict, 'NullifierConflict');
+
+    this.#log.info(
+      `Handled prune to block ${latestBlock.number}: ${valid.length} txs restored to pending, ${invalid.length} invalid, ${toEvict.length} evicted due to nullifier conflicts`,
+      { txHashesRestored: valid.map(m => m.txHash), txHashesInvalid: invalid, txHashesEvicted: toEvict },
+    );
 
     // Step 8: Run eviction rules for ALL pending txs (not just restored ones)
     // This handles cases like existing pending txs with invalid fee payer balances
@@ -473,7 +580,7 @@ export class TxPoolV2Impl {
     // Delete failed txs
     await this.#deleteTxsBatch(txHashes.map(h => h.toString()));
 
-    this.#log.info(`Deleted ${txHashes.length} failed txs`);
+    this.#log.info(`Deleted ${txHashes.length} failed txs`, { txHashes: txHashes.map(h => h.toString()) });
   }
 
   async handleFinalizedBlock(block: BlockHeader): Promise<void> {
@@ -505,7 +612,9 @@ export class TxPoolV2Impl {
     }
 
     if (minedTxsToFinalize.length > 0) {
-      this.#log.info(`Finalized ${minedTxsToFinalize.length} mined txs from blocks up to ${blockNumber}`);
+      this.#log.info(`Finalized ${minedTxsToFinalize.length} mined txs from blocks up to ${blockNumber}`, {
+        txHashes: minedTxsToFinalize,
+      });
     }
   }
 
@@ -549,6 +658,13 @@ export class TxPoolV2Impl {
     return [...this.#indices.iteratePendingByPriority('desc')].map(hash => TxHash.fromString(hash));
   }
 
+  getEligiblePendingTxHashes(): TxHash[] {
+    const maxReceivedAt = this.#dateProvider.now() - this.#config.minTxPoolAgeMs;
+    return [...this.#indices.iterateEligiblePendingByPriority('desc', maxReceivedAt)].map(hash =>
+      TxHash.fromString(hash),
+    );
+  }
+
   getPendingTxCount(): number {
     return this.#indices.getPendingTxCount();
   }
@@ -593,6 +709,9 @@ export class TxPoolV2Impl {
       this.#config.archivedTxLimit = config.archivedTxLimit;
       this.#archive.updateLimit(config.archivedTxLimit);
     }
+    if (config.minTxPoolAgeMs !== undefined) {
+      this.#config.minTxPoolAgeMs = config.minTxPoolAgeMs;
+    }
     // Update eviction rules with new config
     this.#evictionManager.updateConfig(config);
   }
@@ -610,8 +729,17 @@ export class TxPoolV2Impl {
 
   // === Metrics ===
 
-  countTxs(): { pending: number; protected: number; mined: number } {
-    return this.#indices.countTxs();
+  countTxs(): {
+    pending: number;
+    protected: number;
+    mined: number;
+    softDeleted: number;
+    totalMetadataBytes: number;
+  } {
+    return {
+      ...this.#indices.countTxs(),
+      softDeleted: this.#deletedPool.getSoftDeletedCount(),
+    };
   }
 
   // ============================================================================
@@ -629,8 +757,10 @@ export class TxPoolV2Impl {
   ): Promise<TxMetaData> {
     const txHashStr = tx.getTxHash().toString();
     const meta = await buildTxMetaData(tx);
+    meta.receivedAt = this.#dateProvider.now();
 
     await this.#txsDB.set(txHashStr, tx.toBuffer());
+    await this.#deletedPool.clearSoftDeleted(txHashStr);
     this.#callbacks.onTxsAdded([tx], opts);
 
     if (state === 'pending') {
@@ -643,9 +773,11 @@ export class TxPoolV2Impl {
     }
 
     const stateStr = typeof state === 'string' ? state : Object.keys(state)[0];
-    this.#log.verbose(`Added ${stateStr} tx ${txHashStr}`, {
+    this.#log.debug(`Added tx ${txHashStr} as ${stateStr}`, {
       eventName: 'tx-added-to-pool',
+      txHash: txHashStr,
       state: stateStr,
+      source: opts.source,
     });
 
     return meta;
@@ -673,6 +805,29 @@ export class TxPoolV2Impl {
     }
   }
 
+  /** Evicts transactions: records eviction metric with reason, caches hashes, then deletes. */
+  async #evictTxs(txHashes: string[], reason: string): Promise<void> {
+    if (txHashes.length === 0) {
+      return;
+    }
+    this.#instrumentation.recordEvictions(txHashes.length, reason);
+    for (const txHashStr of txHashes) {
+      this.#log.debug(`Evicting tx ${txHashStr}`, { txHash: txHashStr, reason });
+      this.#addToEvictedCache(txHashStr);
+    }
+    await this.#deleteTxsBatch(txHashes);
+  }
+
+  /** Adds a tx hash to the bounded evicted cache, evicting the oldest entry if at capacity. */
+  #addToEvictedCache(txHashStr: string): void {
+    if (this.#evictedTxHashes.size >= this.#config.evictedTxCacheSize) {
+      // FIFO eviction: remove the first (oldest) entry
+      const oldest = this.#evictedTxHashes.values().next().value!;
+      this.#evictedTxHashes.delete(oldest);
+    }
+    this.#evictedTxHashes.add(txHashStr);
+  }
+
   // ============================================================================
   // PRIVATE HELPERS - Validation & Conflict Resolution
   // ============================================================================
@@ -828,7 +983,9 @@ export class TxPoolV2Impl {
       if (preAddResult.shouldIgnore) {
         // Transaction rejected - mark for deletion from DB
         rejected.push(meta.txHash);
-        this.#log.debug(`Rejected tx ${meta.txHash} during rebuild: ${preAddResult.reason}`);
+        this.#log.debug(
+          `Rejected tx ${meta.txHash} during rebuild: ${preAddResult.reason?.message ?? 'unknown reason'}`,
+        );
         continue;
       }
 
@@ -864,7 +1021,7 @@ export class TxPoolV2Impl {
       getFeePayerPendingTxs: (feePayer: string) => this.#indices.getFeePayerPendingTxs(feePayer),
       getPendingTxCount: () => this.#indices.getPendingTxCount(),
       getLowestPriorityPending: (limit: number) => this.#indices.getLowestPriorityPending(limit),
-      deleteTxs: (txHashes: string[]) => this.#deleteTxsBatch(txHashes),
+      deleteTxs: (txHashes: string[], reason?: string) => this.#evictTxs(txHashes, reason ?? 'unknown'),
     };
   }
 

package/src/msg_validators/tx_validator/timestamp_validator.ts

@@ -1,13 +1,13 @@
 import type { BlockNumber } from '@aztec/foundation/branded-types';
 import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
-import { TX_ERROR_INVALID_INCLUDE_BY_TIMESTAMP, type TxValidationResult, type TxValidator } from '@aztec/stdlib/tx';
+import { TX_ERROR_INVALID_EXPIRATION_TIMESTAMP, type TxValidationResult, type TxValidator } from '@aztec/stdlib/tx';
 import type { UInt64 } from '@aztec/stdlib/types';
 
 /** Structural interface for timestamp validation. */
 export interface HasTimestampData {
   txHash: { toString(): string };
   data: {
-    includeByTimestamp: bigint;
+    expirationTimestamp: bigint;
     constants: {
       anchorBlockHeader: {
         globalVariables: {
@@ -35,21 +35,21 @@ export class TimestampTxValidator<T extends HasTimestampData> implements TxValid
   }
 
   validateTx(tx: T): Promise<TxValidationResult> {
-    const includeByTimestamp = tx.data.includeByTimestamp;
-    // If building block 1, we skip the expiration check. For details on why see the `validate_include_by_timestamp`
+    const expirationTimestamp = tx.data.expirationTimestamp;
+    // If building block 1, we skip the expiration check. For details on why see the `validate_expiration_timestamp`
     // function in `noir-projects/noir-protocol-circuits/crates/rollup-lib/src/base/components/validation_requests.nr`.
     const buildingBlock1 = this.values.blockNumber === 1;
 
-    if (!buildingBlock1 && includeByTimestamp < this.values.timestamp) {
+    if (!buildingBlock1 && expirationTimestamp < this.values.timestamp) {
       if (tx.data.constants.anchorBlockHeader.globalVariables.blockNumber === 0) {
         this.#log.warn(
           `A tx built against a genesis block failed to be included in block 1 which is the only block in which txs built against a genesis block are allowed to be included.`,
         );
       }
       this.#log.verbose(
-        `Rejecting tx ${tx.txHash} for low expiration timestamp. Tx expiration timestamp: ${includeByTimestamp}, timestamp: ${this.values.timestamp}.`,
+        `Rejecting tx ${tx.txHash} for low expiration timestamp. Tx expiration timestamp: ${expirationTimestamp}, timestamp: ${this.values.timestamp}.`,
       );
-      return Promise.resolve({ result: 'invalid', reason: [TX_ERROR_INVALID_INCLUDE_BY_TIMESTAMP] });
+      return Promise.resolve({ result: 'invalid', reason: [TX_ERROR_INVALID_EXPIRATION_TIMESTAMP] });
     } else {
       return Promise.resolve({ result: 'valid' });
     }

package/src/services/dummy_service.ts

@@ -1,6 +1,6 @@
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { PeerInfo } from '@aztec/stdlib/interfaces/server';
-import type { Gossipable, PeerErrorSeverity } from '@aztec/stdlib/p2p';
+import type { Gossipable, PeerErrorSeverity, TopicType } from '@aztec/stdlib/p2p';
 import { Tx, TxHash } from '@aztec/stdlib/tx';
 
 import type { PeerId } from '@libp2p/interface';
@@ -44,6 +44,10 @@ export class DummyP2PService implements P2PService {
     return [];
   }
 
+  getGossipMeshPeerCount(_topicType: TopicType): number {
+    return 0;
+  }
+
   /**
    * Starts the dummy implementation.
    * @returns A resolved promise.

package/src/services/encoding.ts

@@ -58,7 +58,8 @@ const DefaultMaxSizesKb: Record<TopicType, number> = {
   // Proposals may carry some tx objects, so we allow a larger size capped at 10mb
   // Note this may not be enough for carrying all tx objects in a block
   [TopicType.block_proposal]: 1024 * 10,
-  // TODO(palla/mbps): Check size for checkpoint proposal
+  // Checkpoint proposals carry almost the same data as a block proposal (see the lastBlockProposal)
+  // Only diff is an additional header, which is pretty small compared to the 10mb limit
   [TopicType.checkpoint_proposal]: 1024 * 10,
 };
 

package/src/services/gossipsub/README.md

@@ -40,7 +40,7 @@ We configure all parameters (P1-P4) with values calculated dynamically from netw
 | P3b: meshFailurePenalty | -34 per topic | Sticky penalty after pruning |
 | P4: invalidMessageDeliveries | -20 per message | Attack detection |
 
-**Important:** P1 and P2 are only enabled on topics with P3 enabled (block_proposal, checkpoint_proposal, checkpoint_attestation). The tx topic has all scoring disabled except P4, to prevent free positive score accumulation that would offset penalties from other topics.
+**Important:** P1 and P2 are only enabled on topics with P3 enabled. By default, P3 is enabled for checkpoint_proposal and checkpoint_attestation (2 topics). Block proposal scoring is controlled by `expectedBlockProposalsPerSlot` (current default: `0`, including when env var is unset, so disabled) - see [Block Proposals](#block-proposals-block_proposal) for details. The tx topic has all scoring disabled except P4, to prevent free positive score accumulation that would offset penalties from other topics.
 
 ## Exponential Decay
 
@@ -217,7 +217,21 @@ Transactions are submitted unpredictably by users, so we cannot set meaningful d
 
 ### Block Proposals (block_proposal)
 
-In Multi-Block-Per-Slot (MBPS) mode, N-1 block proposals are gossiped per slot (the last block is bundled with the checkpoint). In single-block mode, this is 0.
+Block proposal scoring is controlled by the `expectedBlockProposalsPerSlot` config (`SEQ_EXPECTED_BLOCK_PROPOSALS_PER_SLOT` env var):
+
+| Config Value | Behavior |
+|-------------|----------|
+| `0` (current default) | Block proposal P3 scoring is **disabled** |
+| Positive number | Uses the provided value as expected proposals per slot |
+| `undefined` | Falls back to `blocksPerSlot - 1` (MBPS mode: N-1, single block: 0) |
+
+**Current behavior note:** In the current implementation, if `SEQ_EXPECTED_BLOCK_PROPOSALS_PER_SLOT` is not set, config mapping applies `0` by default (scoring disabled). The `undefined` fallback above is currently reachable only if the value is explicitly provided as `undefined` in code.
+
+**Future intent:** Once throughput is stable, we may change env parsing/defaults so an unset env var resolves to `undefined` again (re-enabling automatic fallback to `blocksPerSlot - 1`).
+
+**Why disabled by default?** In MBPS mode, gossipsub expects N-1 block proposals per slot. When transaction throughput is low (as expected at launch), fewer blocks are actually built, causing peers to be incorrectly penalized for under-delivering block proposals. The default of 0 disables this scoring. Set to a positive value when throughput increases and block production is consistent.
+
+In MBPS mode (when enabled), N-1 block proposals are gossiped per slot (the last block is bundled with the checkpoint). In single-block mode, this is 0.
 
 ### Checkpoint Proposals (checkpoint_proposal)
 
@@ -241,6 +255,7 @@ The scoring parameters depend on:
 | `targetCommitteeSize` | L1RollupConstants | 48 |
 | `heartbeatInterval` | P2PConfig.gossipsubInterval | 700ms |
 | `blockDurationMs` | P2PConfig.blockDurationMs | undefined (single block) |
+| `expectedBlockProposalsPerSlot` | P2PConfig.expectedBlockProposalsPerSlot | 0 (disabled; current unset-env behavior) |
 
 ## Invalid Message Handling (P4)
 
@@ -320,9 +335,9 @@ Conversely, if topic scores are low, a peer slightly above the disconnect thresh
 
 Topic scores provide **burst response** to attacks, while app score provides **stable baseline**:
 
-- P1 (time in mesh): Max +8 per topic (+24 across 3 topics)
-- P2 (first deliveries): Max +25 per topic (+75 across 3 topics, but decays fast)
-- P3 (under-delivery): Max -34 per topic (-102 across 3 topics in MBPS; -68 in single-block mode)
+- P1 (time in mesh): Max +8 per topic (+16 default, +24 with block proposal scoring enabled)
+- P2 (first deliveries): Max +25 per topic (+50 default, +75 with block proposal scoring, but decays fast)
+- P3 (under-delivery): Max -34 per topic (-68 default with 2 topics, -102 with block proposal scoring enabled)
 - P4 (invalid messages): -20 per invalid message, can spike to -2000+ during attacks
 
 Example attack scenario:
@@ -373,21 +388,21 @@ When a peer is pruned from the mesh:
 3. **P3b captures the penalty**: The P3 deficit at prune time becomes P3b, which decays slowly
 
 After pruning, the peer's score consists mainly of P3b:
-- **Total P3b across 3 topics: -102** (max)
+- **Total P3b: -68** (default, 2 topics) or **-102** (with block proposal scoring enabled, 3 topics)
 - **Recovery time**: P3b decays to ~1% over one decay window (2-5 slots = 2-6 minutes)
 - **Grafting eligibility**: Peer can be grafted when score ≥ 0, but asymptotic decay means recovery is slow
 
 ### Why Non-Contributors Aren't Disconnected
 
-With P3b capped at -102 total after pruning (MBPS mode). In single-block mode, the cap is -68:
+With P3b capped at -68 (default, 2 topics) or -102 (with block proposal scoring, 3 topics) after pruning:
 
 | Threshold | Value | P3b Score | Triggered? |
 |-----------|-------|-----------|------------|
-| gossipThreshold | -500 | -102 (MBPS) / -68 (single) | No |
-| publishThreshold | -1000 | -102 (MBPS) / -68 (single) | No |
-| graylistThreshold | -2000 | -102 (MBPS) / -68 (single) | No |
+| gossipThreshold | -500 | -68 (default) / -102 (block scoring on) | No |
+| publishThreshold | -1000 | -68 (default) / -102 (block scoring on) | No |
+| graylistThreshold | -2000 | -68 (default) / -102 (block scoring on) | No |
 
-**A score of -102 (MBPS) or -68 (single-block) is well above -500**, so non-contributing peers:
+**A score of -68 or -102 is well above -500**, so non-contributing peers:
 - Are pruned from mesh (good - stops them slowing propagation)
 - Still receive gossip (can recover by reconnecting/restarting)
 - Are NOT disconnected unless they also have application-level penalties
@@ -547,7 +562,7 @@ What happens when a peer experiences a network outage and stops delivering messa
 While the peer is disconnected:
 
 1. **P3 penalty accumulates**: The message delivery counter decays toward 0, causing increasing P3 penalty
-2. **Max P3 penalty reached**: Once counter drops below threshold, penalty hits -34 per topic (-102 total in MBPS; -68 single-block)
+2. **Max P3 penalty reached**: Once counter drops below threshold, penalty hits -34 per topic (-68 default, -102 with block proposal scoring)
 3. **Mesh pruning**: Topic score goes negative → peer is pruned from mesh
 4. **P3b captures penalty**: The P3 deficit at prune time becomes P3b (sticky penalty)
 
@@ -569,13 +584,13 @@ Note: If the peer just joined the mesh, P3 penalties only start after
 During a network outage, the peer:
 - **Does NOT send invalid messages** → No P4 penalty
 - **Does NOT violate protocols** → No application-level penalty
-- **Only accumulates topic-level penalties** → Max -102 (P3b, MBPS) or -68 (single-block)
+- **Only accumulates topic-level penalties** → Max -68 (default) or -102 (with block proposal scoring)
 
 This is the crucial difference from malicious behavior:
 
 | Scenario | App Score | Topic Score | Total | Threshold Hit |
 |----------|-----------|-------------|-------|---------------|
-| Network outage | 0 | -102 (MBPS) / -68 (single) | -102 / -68 | None |
+| Network outage | 0 | -68 (default) / -102 (block scoring on) | -68 / -102 | None |
 | Validation failure | -50 | -20 | -520 | gossipThreshold |
 | Malicious peer | -100 | -2000+ | -2100+ | graylistThreshold |