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

package/src/mem_pools/attestation_pool/memory_attestation_pool.ts

@@ -1,71 +1,120 @@
 import type { SlotNumber } from '@aztec/foundation/branded-types';
 import { createLogger } from '@aztec/foundation/log';
-import type { BlockAttestation, BlockProposal } from '@aztec/stdlib/p2p';
+import type {
+  BlockProposal,
+  CheckpointAttestation,
+  CheckpointProposal,
+  CheckpointProposalCore,
+} from '@aztec/stdlib/p2p';
 import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
 
+import { ProposalSlotCapExceededError } from '../../errors/attestation-pool.error.js';
 import { PoolInstrumentation, PoolName, type PoolStatsCallback } from '../instrumentation.js';
 import type { AttestationPool } from './attestation_pool.js';
 import { ATTESTATION_CAP_BUFFER, MAX_PROPOSALS_PER_SLOT } from './kv_attestation_pool.js';
 
 export class InMemoryAttestationPool implements AttestationPool {
-  private metrics: PoolInstrumentation<BlockAttestation>;
+  private metrics: PoolInstrumentation<CheckpointAttestation>;
 
+  private proposals: Map<string, BlockProposal>;
+
+  // Checkpoint attestations
   // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
-  private attestations: Map<
+  private checkpointAttestations: Map<
     /*slot=*/ SlotNumber,
-    Map</*proposalId*/ string, Map</*address=*/ string, BlockAttestation>>
+    Map</*proposalId*/ string, Map</*address=*/ string, CheckpointAttestation>>
   >;
-  private proposals: Map<string, BlockProposal>;
+  private checkpointProposals: Map<string, CheckpointProposalCore>;
 
   constructor(
     telemetry: TelemetryClient = getTelemetryClient(),
     private log = createLogger('p2p:attestation_pool'),
   ) {
-    this.attestations = new Map();
     this.proposals = new Map();
+    this.checkpointAttestations = new Map();
+    this.checkpointProposals = new Map();
     this.metrics = new PoolInstrumentation(telemetry, PoolName.ATTESTATION_POOL, this.poolStats);
   }
 
   private poolStats: PoolStatsCallback = () => {
     return Promise.resolve({
-      itemCount: this.attestations.size,
+      itemCount: this.checkpointAttestations.size,
     });
   };
 
   public isEmpty(): Promise<boolean> {
-    return Promise.resolve(this.attestations.size === 0);
+    return Promise.resolve(this.checkpointAttestations.size === 0 && this.proposals.size === 0);
   }
 
-  public getAttestationsForSlot(slot: SlotNumber): Promise<BlockAttestation[]> {
-    return Promise.resolve(
-      Array.from(this.attestations.get(slot)?.values() ?? []).flatMap(proposalAttestationMap =>
-        Array.from(proposalAttestationMap.values()),
-      ),
-    );
+  public addBlockProposal(blockProposal: BlockProposal): Promise<void> {
+    // Strip signedTxs before storing to avoid holding full tx data in memory
+    this.proposals.set(blockProposal.archive.toString(), blockProposal.withoutSignedTxs());
+    return Promise.resolve();
   }
 
-  public getAttestationsForSlotAndProposal(slot: SlotNumber, proposalId: string): Promise<BlockAttestation[]> {
-    const slotAttestationMap = this.attestations.get(slot);
-    if (slotAttestationMap) {
-      const proposalAttestationMap = slotAttestationMap.get(proposalId);
-      if (proposalAttestationMap) {
-        return Promise.resolve(Array.from(proposalAttestationMap.values()));
-      }
+  public getBlockProposal(id: string): Promise<BlockProposal | undefined> {
+    return Promise.resolve(this.proposals.get(id));
+  }
+
+  public hasBlockProposal(idOrProposal: string | BlockProposal): Promise<boolean> {
+    const id = typeof idOrProposal === 'string' ? idOrProposal : idOrProposal.archive.toString();
+    return Promise.resolve(this.proposals.has(id));
+  }
+
+  public canAddProposal(_block: BlockProposal): Promise<boolean> {
+    // TODO(palla/mbps): See when to allow
+    return Promise.resolve(true);
+  }
+
+  // Checkpoint attestation methods
+
+  public async addCheckpointProposal(proposal: CheckpointProposal): Promise<void> {
+    if (!(await this.canAddCheckpointProposal(proposal))) {
+      throw new ProposalSlotCapExceededError(
+        `Maximum checkpoint proposals per slot reached: slot=${proposal.slotNumber} cap=${MAX_PROPOSALS_PER_SLOT} proposal=${proposal.archive.toString()}`,
+      );
     }
-    return Promise.resolve([]);
+
+    // Extract and validate the block proposal if present
+    const blockProposal = proposal.getBlockProposal();
+    if (blockProposal && !(await this.canAddProposal(blockProposal))) {
+      throw new ProposalSlotCapExceededError(
+        `Maximum block proposals per slot reached when extracting from checkpoint: slot=${proposal.slotNumber} proposal=${blockProposal.archive.toString()}`,
+      );
+    }
+
+    const slotProposalMapping = getCheckpointSlotOrDefault(this.checkpointAttestations, proposal.slotNumber);
+    slotProposalMapping.set(proposal.archive.toString(), new Map<string, CheckpointAttestation>());
+
+    // Store the checkpoint proposal as core (without lastBlock) to avoid duplication
+    this.checkpointProposals.set(proposal.archive.toString(), proposal.toCore());
+
+    // Store the extracted block proposal separately
+    if (blockProposal) {
+      this.proposals.set(blockProposal.archive.toString(), blockProposal.withoutSignedTxs());
+    }
+
+    return Promise.resolve();
+  }
+
+  public getCheckpointProposal(id: string): Promise<CheckpointProposalCore | undefined> {
+    return Promise.resolve(this.checkpointProposals.get(id));
+  }
+
+  public hasCheckpointProposal(idOrProposal: string | CheckpointProposal): Promise<boolean> {
+    const id = typeof idOrProposal === 'string' ? idOrProposal : idOrProposal.archive.toString();
+    return Promise.resolve(this.checkpointProposals.has(id));
   }
 
-  public addAttestations(attestations: BlockAttestation[]): Promise<void> {
+  public addCheckpointAttestations(attestations: CheckpointAttestation[]): Promise<void> {
     for (const attestation of attestations) {
-      // Perf: order and group by slot before insertion
       const slotNumber = attestation.payload.header.slotNumber;
-
       const proposalId = attestation.archive.toString();
       const sender = attestation.getSender();
 
       // Skip attestations with invalid signatures
       if (!sender) {
-        this.log.warn(`Skipping attestation with invalid signature for slot ${slotNumber}`, {
+        this.log.warn(`Skipping checkpoint attestation with invalid signature for slot ${slotNumber}`, {
           signature: attestation.signature.toString(),
           slotNumber,
           proposalId,
@@ -73,11 +122,11 @@ export class InMemoryAttestationPool implements AttestationPool {
         continue;
       }
 
-      const slotAttestationMap = getSlotOrDefault(this.attestations, slotNumber);
-      const proposalAttestationMap = getProposalOrDefault(slotAttestationMap, proposalId);
+      const slotAttestationMap = getCheckpointSlotOrDefault(this.checkpointAttestations, slotNumber);
+      const proposalAttestationMap = getCheckpointProposalOrDefault(slotAttestationMap, proposalId);
       proposalAttestationMap.set(sender.toString(), attestation);
 
-      this.log.verbose(`Added attestation for slot ${slotNumber} from ${sender}`, {
+      this.log.verbose(`Added checkpoint attestation for slot ${slotNumber} from ${sender}`, {
         signature: attestation.signature.toString(),
         slotNumber,
         address: sender,
@@ -88,25 +137,32 @@ export class InMemoryAttestationPool implements AttestationPool {
     return Promise.resolve();
   }
 
-  #getNumberOfAttestationsInSlot(slot: SlotNumber): number {
-    let total = 0;
-    const slotAttestationMap = getSlotOrDefault(this.attestations, slot);
+  public getCheckpointAttestationsForSlot(slot: SlotNumber): Promise<CheckpointAttestation[]> {
+    return Promise.resolve(
+      Array.from(this.checkpointAttestations.get(slot)?.values() ?? []).flatMap(proposalAttestationMap =>
+        Array.from(proposalAttestationMap.values()),
+      ),
+    );
+  }
 
+  public getCheckpointAttestationsForSlotAndProposal(
+    slot: SlotNumber,
+    proposalId: string,
+  ): Promise<CheckpointAttestation[]> {
+    const slotAttestationMap = this.checkpointAttestations.get(slot);
     if (slotAttestationMap) {
-      for (const proposalAttestationMap of slotAttestationMap.values() ?? []) {
-        total += proposalAttestationMap.size;
+      const proposalAttestationMap = slotAttestationMap.get(proposalId);
+      if (proposalAttestationMap) {
+        return Promise.resolve(Array.from(proposalAttestationMap.values()));
       }
     }
-    return total;
+    return Promise.resolve([]);
   }
 
-  public async deleteAttestationsOlderThan(oldestSlot: SlotNumber): Promise<void> {
+  public deleteCheckpointAttestationsOlderThan(oldestSlot: SlotNumber): Promise<void> {
     const olderThan = [];
 
-    // Entries are iterated in insertion order, so we can break as soon as we find a slot that is older than the oldestSlot.
-    // Note: this will only prune correctly if attestations are added in order of rising slot, it is important that we do not allow
-    // insertion of attestations that are old. #(https://github.com/AztecProtocol/aztec-packages/issues/10322)
-    const slots = this.attestations.keys();
+    const slots = this.checkpointAttestations.keys();
     for (const slot of slots) {
       if (slot < oldestSlot) {
         olderThan.push(slot);
@@ -116,70 +172,51 @@ export class InMemoryAttestationPool implements AttestationPool {
     }
 
     for (const oldSlot of olderThan) {
-      await this.deleteAttestationsForSlot(oldSlot);
+      const proposalIds = this.checkpointAttestations.get(oldSlot)?.keys();
+      proposalIds?.forEach(proposalId => this.checkpointProposals.delete(proposalId));
+      this.checkpointAttestations.delete(oldSlot);
     }
     return Promise.resolve();
   }
 
-  public deleteAttestationsForSlot(slot: SlotNumber): Promise<void> {
-    // We count the number of attestations we are removing
-    const numberOfAttestations = this.#getNumberOfAttestationsInSlot(slot);
-    const proposalIdsToDelete = this.attestations.get(slot)?.keys();
-    let proposalIdsToDeleteCount = 0;
-    proposalIdsToDelete?.forEach(proposalId => {
-      this.proposals.delete(proposalId);
-      proposalIdsToDeleteCount++;
-    });
-
-    this.attestations.delete(slot);
-    this.log.verbose(
-      `Removed ${numberOfAttestations} attestations and ${proposalIdsToDeleteCount} proposals for slot ${slot}`,
-    );
-
-    return Promise.resolve();
+  public hasReachedCheckpointProposalCap(slot: SlotNumber): Promise<boolean> {
+    const slotAttestationMap = this.checkpointAttestations.get(slot);
+    const proposalCount = slotAttestationMap?.size ?? 0;
+    return Promise.resolve(proposalCount >= MAX_PROPOSALS_PER_SLOT);
   }
 
-  public deleteAttestationsForSlotAndProposal(slot: SlotNumber, proposalId: string): Promise<void> {
-    const slotAttestationMap = getSlotOrDefault(this.attestations, slot);
-    if (slotAttestationMap) {
-      if (slotAttestationMap.has(proposalId)) {
-        const numberOfAttestations = slotAttestationMap.get(proposalId)?.size ?? 0;
-
-        slotAttestationMap.delete(proposalId);
-
-        this.log.verbose(`Removed ${numberOfAttestations} attestations for slot ${slot} and proposal ${proposalId}`);
-      }
-    }
+  public hasReachedCheckpointAttestationCap(
+    slot: SlotNumber,
+    proposalId: string,
+    committeeSize: number,
+  ): Promise<boolean> {
+    const limit = committeeSize + ATTESTATION_CAP_BUFFER;
+    const count = this.checkpointAttestations.get(slot)?.get(proposalId)?.size ?? 0;
+    return Promise.resolve(limit <= 0 || count >= limit);
+  }
 
-    this.proposals.delete(proposalId);
-    return Promise.resolve();
+  public async canAddCheckpointProposal(proposal: CheckpointProposal): Promise<boolean> {
+    return (
+      this.checkpointProposals.has(proposal.archive.toString()) ||
+      !(await this.hasReachedCheckpointProposalCap(proposal.slotNumber))
+    );
   }
 
-  public deleteAttestations(attestations: BlockAttestation[]): Promise<void> {
-    for (const attestation of attestations) {
-      const slotNumber = attestation.payload.header.slotNumber;
-      const slotAttestationMap = this.attestations.get(slotNumber);
-      if (slotAttestationMap) {
-        const proposalId = attestation.archive.toString();
-        const proposalAttestationMap = getProposalOrDefault(slotAttestationMap, proposalId);
-        if (proposalAttestationMap) {
-          const sender = attestation.getSender();
-
-          // Skip attestations with invalid signatures
-          if (!sender) {
-            this.log.warn(`Skipping deletion of attestation with invalid signature for slot ${slotNumber}`);
-            continue;
-          }
-
-          proposalAttestationMap.delete(sender.toString());
-          this.log.debug(`Deleted attestation for slot ${slotNumber} from ${sender}`);
-        }
-      }
-    }
-    return Promise.resolve();
+  public async canAddCheckpointAttestation(
+    attestation: CheckpointAttestation,
+    committeeSize: number,
+  ): Promise<boolean> {
+    const sender = attestation.getSender();
+    const slot = attestation.payload.header.slotNumber;
+    const pid = attestation.archive.toString();
+    return (
+      !!sender &&
+      ((this.checkpointAttestations.get(slot)?.get(pid)?.has(sender.toString()) ?? false) ||
+        !(await this.hasReachedCheckpointAttestationCap(slot, pid, committeeSize)))
+    );
   }
 
-  public hasAttestation(attestation: BlockAttestation): Promise<boolean> {
+  public hasCheckpointAttestation(attestation: CheckpointAttestation): Promise<boolean> {
     const slotNumber = attestation.payload.header.slotNumber;
     const proposalId = attestation.archive.toString();
     const sender = attestation.getSender();
@@ -189,7 +226,7 @@ export class InMemoryAttestationPool implements AttestationPool {
       return Promise.resolve(false);
     }
 
-    const slotAttestationMap = this.attestations.get(slotNumber);
+    const slotAttestationMap = this.checkpointAttestations.get(slotNumber);
     if (!slotAttestationMap) {
       return Promise.resolve(false);
     }
@@ -201,87 +238,27 @@ export class InMemoryAttestationPool implements AttestationPool {
 
     return Promise.resolve(proposalAttestationMap.has(sender.toString()));
   }
-
-  public addBlockProposal(blockProposal: BlockProposal): Promise<void> {
-    // We initialize slot-proposal mapping if it does not exist
-    // This is important to ensure we can delete this proposal if there were not attestations for it
-    const slotProposalMapping = getSlotOrDefault(this.attestations, blockProposal.slotNumber);
-    slotProposalMapping.set(blockProposal.payload.archive.toString(), new Map<string, BlockAttestation>());
-
-    this.proposals.set(blockProposal.payload.archive.toString(), blockProposal);
-    return Promise.resolve();
-  }
-
-  public getBlockProposal(id: string): Promise<BlockProposal | undefined> {
-    return Promise.resolve(this.proposals.get(id));
-  }
-
-  public hasBlockProposal(idOrProposal: string | BlockProposal): Promise<boolean> {
-    const id = typeof idOrProposal === 'string' ? idOrProposal : idOrProposal.payload.archive.toString();
-    return Promise.resolve(this.proposals.has(id));
-  }
-
-  public hasReachedProposalCap(slot: SlotNumber): Promise<boolean> {
-    const slotAttestationMap = this.attestations.get(slot);
-    const proposalCount = slotAttestationMap?.size ?? 0;
-    return Promise.resolve(proposalCount >= MAX_PROPOSALS_PER_SLOT);
-  }
-
-  public hasReachedAttestationCap(slot: SlotNumber, proposalId: string, committeeSize: number): Promise<boolean> {
-    const limit = committeeSize + ATTESTATION_CAP_BUFFER;
-    const count = this.attestations.get(slot)?.get(proposalId)?.size ?? 0;
-    return Promise.resolve(limit <= 0 || count >= limit);
-  }
-
-  public async canAddProposal(block: BlockProposal): Promise<boolean> {
-    return this.proposals.has(block.archive.toString()) || !(await this.hasReachedProposalCap(block.slotNumber));
-  }
-
-  public async canAddAttestation(attestation: BlockAttestation, committeeSize: number): Promise<boolean> {
-    const sender = attestation.getSender();
-    const slot = attestation.payload.header.slotNumber;
-    const pid = attestation.archive.toString();
-    return (
-      !!sender &&
-      ((this.attestations.get(slot)?.get(pid)?.has(sender.toString()) ?? false) ||
-        !(await this.hasReachedAttestationCap(slot, pid, committeeSize)))
-    );
-  }
 }
 
-/**
- * Get Slot or Default
- *
- * Fetch the slot mapping, if it does not exist, then create a mapping and return it
- * @param map - The map to fetch from
- * @param slot - The slot to fetch
- * @returns The slot mapping
- */
-function getSlotOrDefault(
+// Checkpoint attestation helper functions
+
+function getCheckpointSlotOrDefault(
   // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
-  map: Map<SlotNumber, Map<string, Map<string, BlockAttestation>>>,
+  map: Map<SlotNumber, Map<string, Map<string, CheckpointAttestation>>>,
   slot: SlotNumber,
-): Map<string, Map<string, BlockAttestation>> {
+): Map<string, Map<string, CheckpointAttestation>> {
   if (!map.has(slot)) {
-    map.set(slot, new Map<string, Map<string, BlockAttestation>>());
+    map.set(slot, new Map<string, Map<string, CheckpointAttestation>>());
   }
   return map.get(slot)!;
 }
 
-/**
- * Get Proposal or Default
- *
- * Fetch the proposal mapping, if it does not exist, then create a mapping and return it
- * @param map - The map to fetch from
- * @param proposalId - The proposal id to fetch
- * @returns The proposal mapping
- */
-function getProposalOrDefault(
-  map: Map<string, Map<string, BlockAttestation>>,
+function getCheckpointProposalOrDefault(
+  map: Map<string, Map<string, CheckpointAttestation>>,
   proposalId: string,
-): Map<string, BlockAttestation> {
+): Map<string, CheckpointAttestation> {
   if (!map.has(proposalId)) {
-    map.set(proposalId, new Map<string, BlockAttestation>());
+    map.set(proposalId, new Map<string, CheckpointAttestation>());
   }
   return map.get(proposalId)!;
 }

package/src/mem_pools/attestation_pool/mocks.ts

@@ -1,12 +1,13 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
 import type { Secp256k1Signer } from '@aztec/foundation/crypto/secp256k1-signer';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import {
-  BlockAttestation,
+  CheckpointAttestation,
   ConsensusPayload,
   SignatureDomainSeparator,
   getHashedSignaturePayloadEthSignedMessage,
 } from '@aztec/stdlib/p2p';
-import { makeL2BlockHeader } from '@aztec/stdlib/testing';
+import { CheckpointHeader } from '@aztec/stdlib/rollup';
 
 import { type LocalAccount, generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 
@@ -20,26 +21,31 @@ export const generateAccount = (): LocalAccount => {
   return privateKeyToAccount(privateKey);
 };
 
-/** Mock Attestation
+/** Mock Checkpoint Attestation
  *
- * @param signer A viem signer to create a signature
+ * @param signer A Secp256k1Signer to create a signature
  * @param slot The slot number the attestation is for
- * @returns A Block Attestation
+ * @param archive The archive root (defaults to random)
+ * @param header The checkpoint header (defaults to random with given slot)
+ * @returns A Checkpoint Attestation
  */
-export const mockAttestation = (
+export const mockCheckpointAttestation = (
   signer: Secp256k1Signer,
   slot: number = 0,
   archive: Fr = Fr.random(),
-): BlockAttestation => {
-  // Use arbitrary numbers for all other than slot
-  const header = makeL2BlockHeader(1, 2, slot);
-  const payload = new ConsensusPayload(header.toCheckpointHeader(), archive);
+  header?: CheckpointHeader,
+): CheckpointAttestation => {
+  header = header ?? CheckpointHeader.random({ slotNumber: SlotNumber(slot) });
+  const payload = new ConsensusPayload(header, archive);
 
-  const attestationHash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockAttestation);
+  const attestationHash = getHashedSignaturePayloadEthSignedMessage(
+    payload,
+    SignatureDomainSeparator.checkpointAttestation,
+  );
   const attestationSignature = signer.sign(attestationHash);
 
-  const proposalHash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockProposal);
+  const proposalHash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.checkpointProposal);
   const proposerSignature = signer.sign(proposalHash);
 
-  return new BlockAttestation(payload, attestationSignature, proposerSignature);
+  return new CheckpointAttestation(payload, attestationSignature, proposerSignature);
 };

package/src/mem_pools/instrumentation.ts

@@ -7,8 +7,8 @@ import {
   LmdbMetrics,
   type LmdbStatsCallback,
   type Meter,
+  type MetricDefinition,
   Metrics,
-  type MetricsType,
   type ObservableGauge,
   type TelemetryClient,
   type UpDownCounter,
@@ -20,10 +20,10 @@ export enum PoolName {
 }
 
 type MetricsLabels = {
-  objectInMempool: MetricsType;
-  objectSize: MetricsType;
-  itemsAdded: MetricsType;
-  itemMinedDelay: MetricsType;
+  objectInMempool: MetricDefinition;
+  objectSize: MetricDefinition;
+  itemsAdded: MetricDefinition;
+  itemMinedDelay: MetricDefinition;
 };
 
 /**
@@ -85,14 +85,9 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
 
     const metricsLabels = getMetricsLabels(name);
 
-    this.objectsInMempool = this.meter.createObservableGauge(metricsLabels.objectInMempool, {
-      description: 'The current number of transactions in the mempool',
-    });
+    this.objectsInMempool = this.meter.createObservableGauge(metricsLabels.objectInMempool);
 
-    this.objectSize = this.meter.createHistogram(metricsLabels.objectSize, {
-      unit: 'By',
-      description: 'The size of transactions in the mempool',
-    });
+    this.objectSize = this.meter.createHistogram(metricsLabels.objectSize);
 
     this.dbMetrics = new LmdbMetrics(
       this.meter,
@@ -102,13 +97,9 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
       dbStats,
     );
 
-    this.addObjectCounter = this.meter.createUpDownCounter(metricsLabels.itemsAdded, {
-      description: 'The number of transactions added to the mempool',
-    });
+    this.addObjectCounter = this.meter.createUpDownCounter(metricsLabels.itemsAdded);
 
-    this.minedDelay = this.meter.createHistogram(metricsLabels.itemMinedDelay, {
-      description: 'Delay between transaction added and evicted from the mempool',
-    });
+    this.minedDelay = this.meter.createHistogram(metricsLabels.itemMinedDelay);
 
     this.meter.addBatchObservableCallback(this.observeStats, [this.objectsInMempool]);
   }

package/src/mem_pools/tx_pool/README.md

@@ -24,7 +24,7 @@ The lifecycle of transactions in the pool is summarised in the following table:
 
 **Note on why Soft Delete:**
 Mined transactions are soft-deleted rather than permanently removed to support:
-1. Reorg handling — If a chain reorganization occurs, soft-deleted transactions are still available in the mempool 
+1. Reorg handling — If a chain reorganization occurs, soft-deleted transactions are still available in the mempool
 2. Slash condition detection — The epoch prune watcher needs access to transactions from pruned epochs to correctly identify data withholding slash conditions. Without soft-delete, transactions invalidated by reorgs (e.g., built on removed blocks) would be lost, causing false positives for data withholding violations.
 
 Mined transactions are permanently deleted via `cleanupDeletedMinedTxs()` once their original block is finalized on L1, ensuring theyremain available during the uncertainty window.
@@ -34,7 +34,7 @@ Alternatively, mined transactions can be permanently deleted immediately by pass
 
 | Method | Description |
 |--------|-------------|
-| `addTxs(txs, opts?)` | Adds transactions to the pool. Duplicates are ignored. Returns count of newly added txs. |
+| `addTxs(txs, opts?)` | Adds transactions to the pool. Duplicates and nullifier conflicts are handled. Returns count of newly added txs. |
 | `deleteTxs(txHashes, opts?)` | Removes transactions from the pool. Supports soft-delete for mined txs. |
 | `markAsMined(txHashes, blockHeader)` | Marks transactions as included in a block. |
 | `markMinedAsPending(txHashes, blockNumber)` | Reverts mined transactions to pending (used during reorgs). |
@@ -91,6 +91,7 @@ The pool maintains several KV maps and indexes:
 | `#txHashToHistoricalBlockHeaderHash` | Anchor block reference for each tx |
 | `#historicalHeaderToTxHash` | Index from historical block → tx hashes |
 | `#feePayerToTxHash` | Index from fee payer address → tx hashes |
+| `#pendingNullifierToTxHash` | Index from nullifier → tx hash |
 | `#archivedTxs` | Archived transactions for historical lookup |
 
 #### In-Memory Caches
@@ -117,15 +118,17 @@ The priority is stored as a hex string derived from a 32-byte buffer representat
 When `addTxs()` is called:
 
 1. Check for duplicates (skip if tx already exists)
-2. Store the serialized tx in `#txs`
-3. Index the tx by its anchor block hash
-4. If not already mined, add to pending indexes:
+2. Check for nullifier conflicts (see Nullifier Deduplication below)
+3. Store the serialized tx in `#txs`
+4. Index the tx by its anchor block hash
+5. If not already mined, add to pending indexes:
    - Priority-to-hash index (for ordering)
    - Historical header index (for reorg handling)
    - Fee payer index (for balance validation)
-5. Record metrics
-6. Trigger eviction rules for `TXS_ADDED` event
-7. Emit `txs-added` event
+   - Nullifier-to-tx-hash index (for conflict detection)
+6. Record metrics
+7. Trigger eviction rules for `TXS_ADDED` event
+8. Emit `txs-added` event
 
 ### 2. Marking as Mined
 
@@ -152,6 +155,16 @@ The `deleteTxs()` method handles two cases:
 
 Soft-deleted mined transactions are retained for potential future reference and can be permanently cleaned up later via `cleanupDeletedMinedTxs()`.
 
+### Nullifier Deduplication
+
+The pool prevents nullifier spam attacks by ensuring only one pending transaction can reference each unique nullifier. When an incoming transaction shares nullifiers with existing pending transactions:
+
+- **Higher fee wins**: If the incoming tx has a higher priority fee than ALL conflicting txs, those conflicting txs are replaced
+- **Existing tx wins on tie**: If any conflicting tx has an equal or higher fee, the incoming tx is rejected
+- **Partial overlap counts**: Even a single shared nullifier triggers conflict resolution
+
+This is enforced at entry time via the `#pendingNullifierToTxHash` index, which maps each nullifier to the tx hash that references it. The index is maintained atomically with tx additions and removals.
+
 ## Eviction System
 
 The eviction system automatically removes invalid or low-priority transactions based on configurable rules. See the [`eviction/`](eviction/) subdirectory for implementation details.
@@ -189,7 +202,7 @@ The [`EvictionManager`](eviction/eviction_manager.ts) coordinates eviction by:
 |-------|---------|---------|
 | `TXS_ADDED` | New transactions added | Enforce pool size limits |
 | `BLOCK_MINED` | Block finalized | Remove invalidated transactions |
-| `CHAIN_PRUNED` | Chain reorganization | Remove txs referencing pruned blocks |
+| `CHAIN_PRUNED` | Chain reorganization | Remove txs referencing pruned blocks and re-evaluate fee payer balances |
 
 ### Eviction Rules
 
@@ -211,13 +224,15 @@ Evicts transactions that reference blocks no longer in the canonical chain:
 - Checks each pending tx's anchor block hash against the archive tree
 - Removes txs whose anchor blocks are not found (pruned)
 
-#### 3. `InsufficientFeePayerBalanceRule`
+#### 3. `FeePayerBalanceEvictionRule`
 
-**Triggers on:** `BLOCK_MINED`, `CHAIN_PRUNED`
+**Triggers on:** `TXS_ADDED`, `BLOCK_MINED`, `CHAIN_PRUNED`
 
-Evicts transactions whose fee payer no longer has sufficient balance:
+Evicts low-priority transactions when a fee payer's pending fee limits exceed their Fee Juice balance:
 
-- Uses `GasTxValidator` to check fee payer balances against current world state
+- Evaluates transactions in priority order so higher-priority claims can fund lower-priority spends
+- Accounts for self-funding claims made during setup
+- Removes evictable txs that do not fit within the running balance
 
 #### 4. `LowPriorityEvictionRule`