@aztec/p2p 4.0.0-devnet.2-patch.3 → 4.0.0-devnet.3-patch.0

package/src/mem_pools/tx_pool_v2/tx_pool_v2_impl.ts

@@ -61,6 +61,7 @@ export class TxPoolV2Impl {
   #l2BlockSource: L2BlockSource;
   #worldStateSynchronizer: WorldStateSynchronizer;
   #createTxValidator: TxPoolV2Dependencies['createTxValidator'];
+  #checkAllowedSetupCalls: TxPoolV2Dependencies['checkAllowedSetupCalls'];
 
   // === In-Memory Indices ===
   #indices: TxPoolIndices = new TxPoolIndices();
@@ -92,6 +93,7 @@ export class TxPoolV2Impl {
     this.#l2BlockSource = deps.l2BlockSource;
     this.#worldStateSynchronizer = deps.worldStateSynchronizer;
     this.#createTxValidator = deps.createTxValidator;
+    this.#checkAllowedSetupCalls = deps.checkAllowedSetupCalls;
 
     this.#config = { ...DEFAULT_TX_POOL_V2_CONFIG, ...config };
     this.#archive = new TxArchive(archiveStore, this.#config.archivedTxLimit, log);
@@ -187,9 +189,35 @@ 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;
+      opts.feeComparisonOnly !== undefined
+        ? { feeComparisonOnly: opts.feeComparisonOnly, priceBumpPercentage: this.#config.priceBumpPercentage }
+        : undefined;
 
     await this.#store.transactionAsync(async () => {
       for (const tx of txs) {
@@ -202,22 +230,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,13 +258,18 @@ export class TxPoolV2Impl {
           );
           if (result.status === 'accepted') {
             acceptedPending.add(txHashStr);
-          } else if (result.status === 'rejected') {
-            rejected.push(txHash);
           } else {
             ignored.push(txHash);
           }
         }
       }
+
+      // Run post-add eviction rules for pending txs (inside transaction for atomicity)
+      if (acceptedPending.size > 0) {
+        const feePayers = Array.from(acceptedPending).map(txHash => this.#indices.getMetadata(txHash)!.feePayer);
+        const uniqueFeePayers = new Set<string>(feePayers);
+        await this.#evictionManager.evictAfterNewTxs(Array.from(acceptedPending), [...uniqueFeePayers]);
+      }
     });
 
     // Build final accepted list for pending txs (excludes intra-batch evictions)
@@ -249,37 +285,24 @@ export class TxPoolV2Impl {
       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);
-      const uniqueFeePayers = new Set<string>(feePayers);
-      await this.#evictionManager.evictAfterNewTxs(Array.from(acceptedPending), [...uniqueFeePayers]);
-    }
-
     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 +340,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 +352,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);
 
@@ -346,20 +363,25 @@ export class TxPoolV2Impl {
   async addProtectedTxs(txs: Tx[], block: BlockHeader, opts: { source?: string }): Promise<void> {
     const slotNumber = block.globalVariables.slotNumber;
 
+    // Precompute setup-call allow-list flags outside the store transaction
+    const allowedFlags = await Promise.all(txs.map(tx => this.#checkAllowedSetupCalls(tx)));
+
     await this.#store.transactionAsync(async () => {
-      for (const tx of txs) {
+      for (let i = 0; i < txs.length; i++) {
+        const tx = txs[i];
         const txHash = tx.getTxHash();
         const txHashStr = txHash.toString();
         const isNew = !this.#indices.has(txHashStr);
         const minedBlockId = await this.#getMinedBlockId(txHash);
 
         if (isNew) {
+          const meta = await buildTxMetaData(tx, allowedFlags[i]);
           // New tx - add as mined or protected (callback emitted by #addTx)
           if (minedBlockId) {
-            await this.#addTx(tx, { mined: minedBlockId }, opts);
+            await this.#addTx(tx, { mined: minedBlockId }, opts, meta);
             this.#indices.setProtection(txHashStr, slotNumber);
           } else {
-            await this.#addTx(tx, { protected: slotNumber }, opts);
+            await this.#addTx(tx, { protected: slotNumber }, opts, meta);
           }
         } else {
           // Existing tx - update protection and mined status
@@ -379,33 +401,35 @@ export class TxPoolV2Impl {
     let softDeletedHits = 0;
     let missingPreviouslyEvicted = 0;
 
-    for (const txHash of txHashes) {
-      const txHashStr = txHash.toString();
+    await this.#store.transactionAsync(async () => {
+      for (const txHash of txHashes) {
+        const txHashStr = txHash.toString();
 
-      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++;
+        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 {
-          // Data missing despite soft-delete flag — treat as truly missing
+          // Truly missing — pre-record protection for tx we don't have yet
           this.#indices.setProtection(txHashStr, slotNumber);
           missing.push(txHash);
-        }
-      } else {
-        // 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++;
+          if (this.#evictedTxHashes.has(txHashStr)) {
+            missingPreviouslyEvicted++;
+          }
         }
       }
-    }
+    });
 
     // Record metrics
     if (softDeletedHits > 0) {
@@ -466,56 +490,60 @@ export class TxPoolV2Impl {
       }
     }
 
-    // Step 4: Mark txs as mined (only those we have in the pool)
-    for (const meta of found) {
-      this.#indices.markAsMined(meta, blockId);
-      await this.#deletedPool.clearIfMinedHigher(meta.txHash, blockId.number);
-    }
+    await this.#store.transactionAsync(async () => {
+      // Step 4: Mark txs as mined (only those we have in the pool)
+      for (const meta of found) {
+        this.#indices.markAsMined(meta, blockId);
+        await this.#deletedPool.clearIfMinedHigher(meta.txHash, blockId.number);
+      }
 
-    // Step 5: Run eviction rules (remove pending txs with conflicting nullifiers/expired timestamps)
-    await this.#evictionManager.evictAfterNewBlock(block.header, nullifiers, feePayers);
+      // Step 5: Run post-event eviction rules (inside transaction for atomicity)
+      await this.#evictionManager.evictAfterNewBlock(block.header, nullifiers, feePayers);
+    });
 
     this.#log.info(`Marked ${found.length} txs as mined in block ${blockId.number}`);
   }
 
   async prepareForSlot(slotNumber: SlotNumber): Promise<void> {
-    // Step 0: Clean up slot-deleted txs from previous slots
-    await this.#deletedPool.cleanupSlotDeleted(slotNumber);
+    await this.#store.transactionAsync(async () => {
+      // 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);
+      // Step 1: Find expired protected txs
+      const expiredProtected = this.#indices.findExpiredProtectedTxs(slotNumber);
 
-    // Step 2: Clear protection for all expired entries (including those without metadata)
-    this.#indices.clearProtection(expiredProtected);
+      // Step 2: Clear protection for all expired entries (including those without metadata)
+      this.#indices.clearProtection(expiredProtected);
 
-    // 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;
-    }
+      // 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;
+      }
 
-    this.#log.info(`Preparing for slot ${slotNumber}: unprotecting ${txsToRestore.length} txs`);
+      this.#log.info(`Preparing for slot ${slotNumber}: unprotecting ${txsToRestore.length} txs`);
 
-    // Step 4: Validate for pending pool
-    const { valid, invalid } = await this.#revalidateMetadata(txsToRestore, 'during prepareForSlot');
+      // Step 4: Validate for pending pool
+      const { valid, invalid } = await this.#revalidateMetadata(txsToRestore, 'during prepareForSlot');
 
-    // Step 5: Resolve nullifier conflicts and add winners to pending indices
-    const { added, toEvict } = this.#applyNullifierConflictResolution(valid);
+      // Step 5: Resolve nullifier conflicts and add winners to pending indices
+      const { added, toEvict } = this.#applyNullifierConflictResolution(valid);
 
-    // Step 6: Delete invalid txs and evict conflict losers
-    await this.#deleteTxsBatch(invalid);
-    await this.#evictTxs(toEvict, 'NullifierConflict');
+      // 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) {
-      const feePayers = added.map(meta => meta.feePayer);
-      const uniqueFeePayers = new Set<string>(feePayers);
-      await this.#evictionManager.evictAfterNewTxs(
-        added.map(m => m.txHash),
-        [...uniqueFeePayers],
-      );
-    }
+      // Step 7: Run eviction rules (enforce pool size limit)
+      if (added.length > 0) {
+        const feePayers = added.map(meta => meta.feePayer);
+        const uniqueFeePayers = new Set<string>(feePayers);
+        await this.#evictionManager.evictAfterNewTxs(
+          added.map(m => m.txHash),
+          [...uniqueFeePayers],
+        );
+      }
+    });
   }
 
   async handlePrunedBlocks(latestBlock: L2BlockId, options?: { deleteAllTxs?: boolean }): Promise<void> {
@@ -528,57 +556,60 @@ export class TxPoolV2Impl {
 
     this.#log.info(`Handling prune to block ${latestBlock.number}: un-mining ${txsToUnmine.length} txs`);
 
-    // Step 2: Mark ALL un-mined txs with their original mined block number
-    // This ensures they get soft-deleted if removed later, and only hard-deleted
-    // when their original mined block is finalized
-    await this.#deletedPool.markFromPrunedBlock(
-      txsToUnmine.map(m => ({
-        txHash: m.txHash,
-        minedAtBlock: BlockNumber(m.minedL2BlockId!.number),
-      })),
-    );
+    await this.#store.transactionAsync(async () => {
+      // Step 2: Mark ALL un-mined txs with their original mined block number
+      // This ensures they get soft-deleted if removed later, and only hard-deleted
+      // when their original mined block is finalized
+      await this.#deletedPool.markFromPrunedBlock(
+        txsToUnmine.map(m => ({
+          txHash: m.txHash,
+          minedAtBlock: BlockNumber(m.minedL2BlockId!.number),
+        })),
+      );
 
-    // Step 3: Unmine - clear mined status from metadata
-    for (const meta of txsToUnmine) {
-      this.#indices.markAsUnmined(meta);
-    }
+      // Step 3: Unmine - clear mined status from metadata
+      for (const meta of txsToUnmine) {
+        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;
-    }
+      // 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: Filter out protected txs (they'll be handled by prepareForSlot)
+      const unprotectedTxs = this.#indices.filterUnprotected(txsToUnmine);
 
-    // Step 5: Validate for pending pool
-    const { valid, invalid } = await this.#revalidateMetadata(unprotectedTxs, 'during handlePrunedBlocks');
+      // 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 6: Resolve nullifier conflicts and add winners to pending indices
+      const { toEvict } = this.#applyNullifierConflictResolution(valid);
 
-    // Step 7: Delete invalid txs and evict conflict losers
-    await this.#deleteTxsBatch(invalid);
-    await this.#evictTxs(toEvict, 'NullifierConflict');
+      // 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 },
-    );
+      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
-    await this.#evictionManager.evictAfterChainPrune(latestBlock.number);
+      // 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
+      await this.#evictionManager.evictAfterChainPrune(latestBlock.number);
+    });
   }
 
   async handleFailedExecution(txHashes: TxHash[]): Promise<void> {
-    // Delete failed txs
-    await this.#deleteTxsBatch(txHashes.map(h => h.toString()));
+    await this.#store.transactionAsync(async () => {
+      await this.#deleteTxsBatch(txHashes.map(h => h.toString()));
+    });
 
     this.#log.info(`Deleted ${txHashes.length} failed txs`, { txHashes: txHashes.map(h => h.toString()) });
   }
@@ -589,27 +620,29 @@ export class TxPoolV2Impl {
     // Step 1: Find mined txs at or before finalized block
     const minedTxsToFinalize = this.#indices.findTxsMinedAtOrBefore(blockNumber);
 
-    // Step 2: Collect mined txs for archiving (before deletion)
-    const txsToArchive: Tx[] = [];
-    if (this.#archive.isEnabled()) {
-      for (const txHashStr of minedTxsToFinalize) {
-        const buffer = await this.#txsDB.getAsync(txHashStr);
-        if (buffer) {
-          txsToArchive.push(Tx.fromBuffer(buffer));
+    await this.#store.transactionAsync(async () => {
+      // Step 2: Collect mined txs for archiving (before deletion)
+      const txsToArchive: Tx[] = [];
+      if (this.#archive.isEnabled()) {
+        for (const txHashStr of minedTxsToFinalize) {
+          const buffer = await this.#txsDB.getAsync(txHashStr);
+          if (buffer) {
+            txsToArchive.push(Tx.fromBuffer(buffer));
+          }
         }
       }
-    }
 
-    // Step 3: Delete mined txs from active pool
-    await this.#deleteTxsBatch(minedTxsToFinalize);
+      // Step 3: Delete mined txs from active pool
+      await this.#deleteTxsBatch(minedTxsToFinalize);
 
-    // Step 4: Finalize soft-deleted txs
-    await this.#deletedPool.finalizeBlock(blockNumber);
+      // Step 4: Finalize soft-deleted txs
+      await this.#deletedPool.finalizeBlock(blockNumber);
 
-    // Step 5: Archive mined txs
-    if (txsToArchive.length > 0) {
-      await this.#archive.archiveTxs(txsToArchive);
-    }
+      // Step 5: Archive mined txs
+      if (txsToArchive.length > 0) {
+        await this.#archive.archiveTxs(txsToArchive);
+      }
+    });
 
     if (minedTxsToFinalize.length > 0) {
       this.#log.info(`Finalized ${minedTxsToFinalize.length} mined txs from blocks up to ${blockNumber}`, {
@@ -754,9 +787,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());
@@ -938,7 +972,8 @@ export class TxPoolV2Impl {
 
       try {
         const tx = Tx.fromBuffer(buffer);
-        const meta = await buildTxMetaData(tx);
+        const allowedSetupCalls = await this.#checkAllowedSetupCalls(tx);
+        const meta = await buildTxMetaData(tx, allowedSetupCalls);
         loaded.push({ tx, meta });
       } catch (err) {
         this.#log.warn(`Failed to deserialize tx ${txHashStr}, deleting`, { err });

package/src/msg_validators/attestation_validator/README.md

@@ -0,0 +1,49 @@
+# Attestation Validation
+
+This module validates `CheckpointAttestation` gossipsub messages. Attestations are signatures from committee members endorsing a checkpoint proposal.
+
+**Topic**: `checkpoint_attestation` | **Snappy size limit**: 5 KB
+
+## Stage 1: AttestationValidator (Gossipsub Validation)
+
+| # | Rule | Consequence | Severity | File |
+|---|------|-------------|----------|------|
+| 1 | **Slot timeliness**: `currentSlot` or `nextSlot`. Previous slot within 500ms: IGNORE. Older: REJECT. | REJECT or IGNORE | HighToleranceError | `attestation_validator.ts` |
+| 2 | **Attester signature**: `getSender()` must recover valid address | REJECT | LowToleranceError | same |
+| 3 | **Attester in committee**: recovered address in committee for slot | REJECT | HighToleranceError | same |
+| 4 | **Proposer exists**: `getProposerAttesterAddressInSlot` must return defined | REJECT | HighToleranceError | same |
+| 5 | **Proposer signature**: `getProposer()` must recover valid address | REJECT | LowToleranceError | same |
+| 6 | **Proposer matches expected**: recovered proposer = expected for slot | REJECT | HighToleranceError | same |
+| 7 | **NoCommitteeError**: committee unavailable | REJECT | LowToleranceError | same |
+
+**Fisherman mode extension** (`FishermanAttestationValidator`): if a checkpoint proposal for the same archive exists in pool, the attestation's `ConsensusPayload` must `.equals()` the stored proposal's payload. On mismatch: REJECT + LowToleranceError.
+
+## Stage 2: Pool Admission
+
+| # | Rule | Consequence |
+|---|------|-------------|
+| 8 | Sender recoverable (pool-side) | Silent drop |
+| 9 | Not a duplicate (same slot + proposalId + signer) | IGNORE |
+| 10 | Per-signer cap: `MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER` = 3 | IGNORE |
+
+Own attestations added via `addOwnCheckpointAttestations` bypass the per-signer cap.
+
+## Stage 3: Equivocation Detection
+
+When a signer's attestation count for a slot reaches exactly 2 (different proposals): `duplicateAttestationCallback` fires -> `WANT_TO_SLASH_EVENT` with `OffenseType.DUPLICATE_ATTESTATION`. Attestation still ACCEPTED and rebroadcast. Callback fires once (not again at count 3+).
+
+## Validation at L1 Checkpoint Submission (Archiver)
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Each attestation must have recoverable signature (or address-only is allowed but does not count toward quorum) | Checkpoint rejected as invalid | `archiver/src/modules/validation.ts` |
+| Attestation at index `i` must correspond to committee member at index `i` | Checkpoint rejected as invalid | same |
+| Valid attestation count >= floor(committee * 2/3) + 1 | Checkpoint rejected as invalid | same |
+| No committee / escape hatch open | Accepted unconditionally | same |
+
+Note: `skipValidateCheckpointAttestations` config flag bypasses all archiver attestation validation.
+
+## Gossipsub Topic Scoring
+
+P3 enabled with expected messages per slot = `targetCommitteeSize`. Conservative threshold (30% of convergence value). Max P3 penalty = -34 per topic.
+