@aztec/p2p 0.0.1-commit.1bb068fb5 → 0.0.1-commit.1dcfe2301

package/src/config.ts

@@ -1,6 +1,7 @@
 import {
   type ConfigMappingsType,
   SecretValue,
+  bigintConfigHelper,
   booleanConfigHelper,
   getConfigFromMappings,
   getDefaultConfig,
@@ -10,7 +11,6 @@ import {
   secretStringConfigHelper,
 } from '@aztec/foundation/config';
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { type DataStoreConfig, dataConfigMappings } from '@aztec/kv-store/config';
 import { FunctionSelector } from '@aztec/stdlib/abi/function-selector';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
@@ -20,6 +20,7 @@ import {
   chainConfigMappings,
   sharedSequencerConfigMappings,
 } from '@aztec/stdlib/config';
+import { type DataStoreConfig, dataConfigMappings } from '@aztec/stdlib/kv-store';
 
 import {
   type BatchTxRequesterConfig,
@@ -38,7 +39,26 @@ export interface P2PConfig
     ChainConfig,
     TxCollectionConfig,
     TxFileStoreConfig,
-    Pick<SequencerConfig, 'blockDurationMs'> {
+    Pick<
+      SequencerConfig,
+      | 'blockDurationMs'
+      | 'expectedBlockProposalsPerSlot'
+      | 'l1PublishingTime'
+      | 'maxTxsPerBlock'
+      | 'attestationPropagationTime'
+    > {
+  /** Maximum transactions per block for validation. Overrides maxTxsPerBlock for gossip validation when set. */
+  validateMaxTxsPerBlock?: number;
+
+  /** Maximum transactions per checkpoint for validation. Used as fallback for maxTxsPerBlock when that is not set. */
+  validateMaxTxsPerCheckpoint?: number;
+
+  /** Maximum L2 gas per block for validation. When set, txs exceeding this limit are rejected. */
+  validateMaxL2BlockGas?: number;
+
+  /** Maximum DA gas per block for validation. When set, txs exceeding this limit are rejected. */
+  validateMaxDABlockGas?: number;
+
   /** A flag dictating whether the P2P subsystem should be enabled. */
   p2pEnabled: boolean;
 
@@ -57,6 +77,9 @@ export interface P2PConfig
   /** The frequency in which to check for new peers. */
   peerCheckIntervalMS: number;
 
+  /** How long to ban a peer after it fails MAX_DIAL_ATTEMPTS dials. */
+  peerFailedBanTimeMs: number;
+
   /** Size of queue of L2 blocks to store. */
   l2QueueSize: number;
 
@@ -150,8 +173,8 @@ export interface P2PConfig
   /** The maximum possible size of the P2P DB in KB. Overwrites the general dataStoreMapSizeKb. */
   p2pStoreMapSizeKb?: number;
 
-  /** Which calls are allowed in the public setup phase of a tx. */
-  txPublicSetupAllowList: AllowedElement[];
+  /** Additional entries to extend the default setup allow list. */
+  txPublicSetupAllowListExtend: AllowedElement[];
 
   /** The maximum number of pending txs before evicting lower priority txs. */
   maxPendingTxCount: number;
@@ -173,10 +196,7 @@ export interface P2PConfig
   /** Whether transactions are disabled for this node. This means transactions will be rejected at the RPC and P2P layers. */
   disableTransactions: boolean;
 
-  /** True to simulate discarding transactions. - For testing purposes only*/
-  dropTransactions: boolean;
-
-  /** The probability that a transaction is discarded. - For testing purposes only */
+  /** The probability that a transaction is discarded (0 = disabled). - For testing purposes only */
   dropTransactionsProbability: number;
 
   /** Whether to delete transactions from the pool after a reorg instead of moving them back to pending. */
@@ -193,11 +213,36 @@ export interface P2PConfig
 
   /** Minimum age (ms) a transaction must have been in the pool before it's eligible for block building. */
   minTxPoolAgeMs: number;
+
+  /** Minimum percentage fee increase required to replace an existing tx via RPC (0 = no bump). */
+  priceBumpPercentage: bigint;
 }
 
 export const DEFAULT_P2P_PORT = 40400;
 
 export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
+  validateMaxTxsPerBlock: {
+    env: 'VALIDATOR_MAX_TX_PER_BLOCK',
+    description:
+      'Maximum transactions per block for validation. Overrides maxTxsPerBlock for gossip validation when set.',
+    parseEnv: (val: string) => parseInt(val, 10),
+  },
+  validateMaxTxsPerCheckpoint: {
+    env: 'VALIDATOR_MAX_TX_PER_CHECKPOINT',
+    description:
+      'Maximum transactions per checkpoint for validation. Used as fallback for maxTxsPerBlock when that is not set.',
+    parseEnv: (val: string) => parseInt(val, 10),
+  },
+  validateMaxL2BlockGas: {
+    env: 'VALIDATOR_MAX_L2_BLOCK_GAS',
+    description: 'Maximum L2 gas per block for validation. When set, txs exceeding this limit are rejected.',
+    parseEnv: (val: string) => parseInt(val, 10),
+  },
+  validateMaxDABlockGas: {
+    env: 'VALIDATOR_MAX_DA_BLOCK_GAS',
+    description: 'Maximum DA gas per block for validation. When set, txs exceeding this limit are rejected.',
+    parseEnv: (val: string) => parseInt(val, 10),
+  },
   p2pEnabled: {
     env: 'P2P_ENABLED',
     description: 'A flag dictating whether the P2P subsystem should be enabled.',
@@ -228,6 +273,11 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
     description: 'The frequency in which to check for new peers.',
     ...numberConfigHelper(30_000),
   },
+  peerFailedBanTimeMs: {
+    env: 'P2P_PEER_FAILED_BAN_TIME_MS',
+    description: 'How long to ban a peer after it fails maximum dial attempts.',
+    ...numberConfigHelper(5 * 60 * 1000),
+  },
   l2QueueSize: {
     env: 'P2P_L2_QUEUE_SIZE',
     description: 'Size of queue of L2 blocks to store.',
@@ -321,7 +371,7 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
   gossipsubMcacheLength: {
     env: 'P2P_GOSSIPSUB_MCACHE_LENGTH',
     description: 'The number of gossipsub interval message cache windows to keep.',
-    ...numberConfigHelper(6),
+    ...numberConfigHelper(12),
   },
   gossipsubMcacheGossip: {
     env: 'P2P_GOSSIPSUB_MCACHE_GOSSIP',
@@ -393,15 +443,16 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
   },
   p2pStoreMapSizeKb: {
     env: 'P2P_STORE_MAP_SIZE_KB',
-    parseEnv: (val: string | undefined) => (val ? +val : undefined),
+    parseEnv: (val: string) => +val,
     description: 'The maximum possible size of the P2P DB in KB. Overwrites the general dataStoreMapSizeKb.',
   },
-  txPublicSetupAllowList: {
+  txPublicSetupAllowListExtend: {
     env: 'TX_PUBLIC_SETUP_ALLOWLIST',
     parseEnv: (val: string) => parseAllowList(val),
-    description: 'The list of functions calls allowed to run in setup',
+    description:
+      'Additional entries to extend the default setup allow list. Format: I:address:selector[:flags],C:classId:selector[:flags]. Flags: os (onlySelf), rn (rejectNullMsgSender), cl=N (calldataLength), joined with +.',
     printDefault: () =>
-      'AuthRegistry, FeeJuice.increase_public_balance, Token.increase_public_balance, FPC.prepare_fee',
+      'Default: AuthRegistry._set_authorized, AuthRegistry.set_authorized, FeeJuice._increase_public_balance',
   },
   maxPendingTxCount: {
     env: 'P2P_MAX_PENDING_TX_COUNT',
@@ -430,11 +481,6 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
     description: 'Number of auth attempts to allow before peer is banned. Number is inclusive',
     ...numberConfigHelper(3),
   },
-  dropTransactions: {
-    env: 'P2P_DROP_TX',
-    description: 'True to simulate discarding transactions. - For testing purposes only',
-    ...booleanConfigHelper(false),
-  },
   dropTransactionsProbability: {
     env: 'P2P_DROP_TX_CHANCE',
     description: 'The probability that a transaction is discarded (0 - 1). - For testing purposes only',
@@ -456,6 +502,11 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
     description: 'Alters the format of p2p messages to include things like broadcast timestamp FOR TESTING ONLY',
     ...booleanConfigHelper(false),
   },
+  l1PublishingTime: {
+    env: 'SEQ_L1_PUBLISHING_TIME_ALLOWANCE_IN_SLOT',
+    description: 'How much time (in seconds) we allow in the slot for publishing the L1 tx (defaults to 1 L1 slot).',
+    parseEnv: (val: string) => parseInt(val, 10),
+  },
   fishermanMode: {
     env: 'FISHERMAN_MODE',
     description:
@@ -472,6 +523,12 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
     description: 'Minimum age (ms) a transaction must have been in the pool before it is eligible for block building.',
     ...numberConfigHelper(2_000),
   },
+  priceBumpPercentage: {
+    env: 'P2P_RPC_PRICE_BUMP_PERCENTAGE',
+    description:
+      'Minimum percentage fee increase required to replace an existing tx via RPC. Even at 0%, replacement still requires paying at least 1 unit more.',
+    ...bigintConfigHelper(10n),
+  },
   ...sharedSequencerConfigMappings,
   ...p2pReqRespConfigMappings,
   ...batchTxRequesterConfigMappings,
@@ -529,13 +586,44 @@ export const bootnodeConfigMappings = pickConfigMappings(
   bootnodeConfigKeys,
 );
 
+/**
+ * Parses a `+`-separated flags string into validation properties for an allow list entry.
+ * Supported flags: `os` (onlySelf), `rn` (rejectNullMsgSender), `cl=N` (calldataLength).
+ */
+function parseFlags(
+  flags: string,
+  entry: string,
+): { onlySelf?: boolean; rejectNullMsgSender?: boolean; calldataLength?: number } {
+  const result: { onlySelf?: boolean; rejectNullMsgSender?: boolean; calldataLength?: number } = {};
+  for (const flag of flags.split('+')) {
+    if (flag === 'os') {
+      result.onlySelf = true;
+    } else if (flag === 'rn') {
+      result.rejectNullMsgSender = true;
+    } else if (flag.startsWith('cl=')) {
+      const n = parseInt(flag.slice(3), 10);
+      if (isNaN(n) || n < 0) {
+        throw new Error(
+          `Invalid allow list entry "${entry}": invalid calldataLength in flag "${flag}". Expected a non-negative integer.`,
+        );
+      }
+      result.calldataLength = n;
+    } else {
+      throw new Error(`Invalid allow list entry "${entry}": unknown flag "${flag}". Supported flags: os, rn, cl=N.`);
+    }
+  }
+  return result;
+}
+
 /**
  * Parses a string to a list of allowed elements.
- * Each encoded is expected to be of one of the following formats
- * `I:${address}`
- * `I:${address}:${selector}`
- * `C:${classId}`
- * `C:${classId}:${selector}`
+ * Each entry is expected to be of one of the following formats:
+ * `I:${address}:${selector}` — instance (contract address) with function selector
+ * `C:${classId}:${selector}` — class with function selector
+ *
+ * An optional flags segment can be appended after the selector:
+ * `I:${address}:${selector}:${flags}` or `C:${classId}:${selector}:${flags}`
+ * where flags is a `+`-separated list of: `os` (onlySelf), `rn` (rejectNullMsgSender), `cl=N` (calldataLength).
  *
  * @param value The string to parse
  * @returns A list of allowed elements
@@ -548,31 +636,37 @@ export function parseAllowList(value: string): AllowedElement[] {
   }
 
   for (const val of value.split(',')) {
-    const [typeString, identifierString, selectorString] = val.split(':');
-    const selector = selectorString !== undefined ? FunctionSelector.fromString(selectorString) : undefined;
+    const trimmed = val.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const [typeString, identifierString, selectorString, flagsString] = trimmed.split(':');
+
+    if (!selectorString) {
+      throw new Error(
+        `Invalid allow list entry "${trimmed}": selector is required. Expected format: I:address:selector or C:classId:selector`,
+      );
+    }
+
+    const selector = FunctionSelector.fromString(selectorString);
+    const flags = flagsString ? parseFlags(flagsString, trimmed) : {};
 
     if (typeString === 'I') {
-      if (selector) {
-        entries.push({
-          address: AztecAddress.fromString(identifierString),
-          selector,
-        });
-      } else {
-        entries.push({
-          address: AztecAddress.fromString(identifierString),
-        });
-      }
+      entries.push({
+        address: AztecAddress.fromString(identifierString),
+        selector,
+        ...flags,
+      });
     } else if (typeString === 'C') {
-      if (selector) {
-        entries.push({
-          classId: Fr.fromHexString(identifierString),
-          selector,
-        });
-      } else {
-        entries.push({
-          classId: Fr.fromHexString(identifierString),
-        });
-      }
+      entries.push({
+        classId: Fr.fromHexString(identifierString),
+        selector,
+        ...flags,
+      });
+    } else {
+      throw new Error(
+        `Invalid allow list entry "${trimmed}": unknown type "${typeString}". Expected "I" (instance) or "C" (class).`,
+      );
     }
   }
 

package/src/errors/p2p-service.error.ts

@@ -0,0 +1,11 @@
+/** Checkpoint Proposal Received Callback Not Registered Error
+ *
+ * Error triggered if the allNodesCheckpointReceivedCallback is not registered
+ * @category Errors
+ */
+export class CheckpointProposalReceivedCallbackNotRegisteredError extends Error {
+  constructor() {
+    super('FATAL (allNodesCheckpointReceivedCallback): All nodes should register a checkpoint proposal handler');
+    this.name = 'CheckpointProposalReceivedCallbackNotRegisteredError';
+  }
+}

package/src/errors/tx-pool.error.ts

@@ -0,0 +1,12 @@
+import type { TxPoolRejectionError } from '../mem_pools/tx_pool_v2/eviction/interfaces.js';
+
+/** Error thrown when a transaction is not added to the mempool. */
+export class TxPoolError extends Error {
+  public readonly data: TxPoolRejectionError;
+
+  constructor(public readonly reason: TxPoolRejectionError) {
+    super(reason.message);
+    this.name = 'TxPoolError';
+    this.data = reason;
+  }
+}

package/src/index.ts

@@ -6,7 +6,6 @@ export * from './client/index.js';
 export * from './enr/index.js';
 export * from './config.js';
 export * from './mem_pools/attestation_pool/index.js';
-export * from './mem_pools/tx_pool/index.js';
 export * from './mem_pools/tx_pool_v2/index.js';
 export * from './msg_validators/index.js';
 export * from './services/index.js';

package/src/mem_pools/attestation_pool/attestation_pool.ts

@@ -26,10 +26,10 @@ export type TryAddResult = {
   count: number;
 };
 
-export const MAX_CHECKPOINT_PROPOSALS_PER_SLOT = 5;
-export const MAX_BLOCK_PROPOSALS_PER_POSITION = 3;
+export const MAX_CHECKPOINT_PROPOSALS_PER_SLOT = 2;
+export const MAX_BLOCK_PROPOSALS_PER_POSITION = 2;
 /** Maximum attestations a single signer can make per slot before being rejected. */
-export const MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER = 3;
+export const MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER = 2;
 
 /** Public API interface for attestation pools. Used for typing mocks and test implementations. */
 export type AttestationPoolApi = Pick<
@@ -154,14 +154,16 @@ export class AttestationPool {
   /** Maximum indexWithinCheckpoint value (2^10 - 1 = 1023). */
   private static readonly MAX_INDEX = (1 << AttestationPool.INDEX_BITS) - 1;
 
-  /** Creates a position key for block proposals: (slot << 10) | indexWithinCheckpoint. */
+  /** Creates a position key for block proposals: slot * 1024 + indexWithinCheckpoint.
+   * Uses multiplication instead of bit-shift to avoid 32-bit signed integer overflow
+   * (bit-shift overflows after slot ~2^21, roughly 278 days of uptime). */
   private getBlockPositionKey(slot: number, indexWithinCheckpoint: number): number {
     if (indexWithinCheckpoint > AttestationPool.MAX_INDEX) {
       throw new Error(
         `Value for indexWithinCheckpoint ${indexWithinCheckpoint} exceeds maximum ${AttestationPool.MAX_INDEX}`,
       );
     }
-    return (slot << AttestationPool.INDEX_BITS) | indexWithinCheckpoint;
+    return slot * (1 << AttestationPool.INDEX_BITS) + indexWithinCheckpoint;
   }
 
   /**
@@ -278,7 +280,7 @@ export class AttestationPool {
    * @returns Result indicating whether the proposal was added and duplicate detection info
    */
   public async tryAddCheckpointProposal(proposal: CheckpointProposalCore): Promise<TryAddResult> {
-    return await this.store.transactionAsync(async () => {
+    const result = await this.store.transactionAsync(async () => {
       const proposalId = proposal.archive.toString();
 
       // Check if already exists
@@ -304,6 +306,8 @@ export class AttestationPool {
 
       return { added: true, alreadyExists: false, count: count + 1 };
     });
+
+    return result;
   }
 
   /** Internal method - must be called within a transaction. */
@@ -345,7 +349,7 @@ export class AttestationPool {
     await this.store.transactionAsync(async () => {
       for (const attestation of attestations) {
         const slotNumber = attestation.payload.header.slotNumber;
-        const proposalId = attestation.archive;
+        const proposalId = attestation.archive.toString();
         const sender = attestation.getSender();
 
         // Skip attestations with invalid signatures
@@ -359,11 +363,10 @@ export class AttestationPool {
         }
 
         const address = sender.toString();
+        const ownKey = this.getAttestationKey(slotNumber, proposalId, address);
 
-        await this.checkpointAttestations.set(
-          this.getAttestationKey(slotNumber, proposalId, address),
-          attestation.toBuffer(),
-        );
+        await this.checkpointAttestations.set(ownKey, attestation.toBuffer());
+        this.metrics.trackMempoolItemAdded(ownKey);
 
         this.log.debug(`Added own checkpoint attestation for slot ${slotNumber} from ${address}`, {
           signature: attestation.signature.toString(),
@@ -429,6 +432,7 @@ export class AttestationPool {
       const attestationEndKey = new Fr(oldestSlot).toString();
       for await (const key of this.checkpointAttestations.keysAsync({ end: attestationEndKey })) {
         await this.checkpointAttestations.delete(key);
+        this.metrics.trackMempoolItemRemoved(key);
         numberOfAttestations++;
       }
 
@@ -452,7 +456,7 @@ export class AttestationPool {
 
       // Delete block proposals for slots < oldestSlot, using blockProposalsForSlotAndIndex as index
       // Key format: (slot << INDEX_BITS) | indexWithinCheckpoint
-      const blockPositionEndKey = oldestSlot << AttestationPool.INDEX_BITS;
+      const blockPositionEndKey = oldestSlot * (1 << AttestationPool.INDEX_BITS);
       for await (const positionKey of this.blockProposalsForSlotAndIndex.keysAsync({ end: blockPositionEndKey })) {
         const proposalIds = await toArray(this.blockProposalsForSlotAndIndex.getValuesAsync(positionKey));
         for (const proposalId of proposalIds) {
@@ -526,6 +530,7 @@ export class AttestationPool {
 
       // Add the attestation
       await this.checkpointAttestations.set(key, attestation.toBuffer());
+      this.metrics.trackMempoolItemAdded(key);
 
       // Track this attestation in the per-signer-per-slot index for duplicate detection
       const slotSignerKey = this.getSlotSignerKey(slotNumber, signerAddress);

package/src/mem_pools/attestation_pool/attestation_pool_test_suite.ts

@@ -446,12 +446,12 @@ export function describeAttestationPool(getAttestationPool: () => AttestationPoo
         const result2 = await ap.tryAddBlockProposal(proposal2);
         expect(result2.count).toBe(2);
 
-        // Add a third proposal for same position
+        // Third proposal for same position should be rejected (cap is 2)
         const proposal3 = await mockBlockProposalWithIndex(signers[2], slotNumber, indexWithinCheckpoint);
         const result3 = await ap.tryAddBlockProposal(proposal3);
 
-        expect(result3.added).toBe(true);
-        expect(result3.count).toBe(3);
+        expect(result3.added).toBe(false);
+        expect(result3.count).toBe(2);
       });
 
       it('should return added=false when exceeding capacity', async () => {
@@ -666,12 +666,12 @@ export function describeAttestationPool(getAttestationPool: () => AttestationPoo
         const result2 = await ap.tryAddCheckpointProposal(proposal2);
         expect(result2.count).toBe(2);
 
-        // Add a third proposal for same slot
+        // Third proposal for same slot should be rejected (cap is 2)
         const proposal3 = await mockCheckpointProposalCoreForPool(signers[2], slotNumber);
         const result3 = await ap.tryAddCheckpointProposal(proposal3);
 
-        expect(result3.added).toBe(true);
-        expect(result3.count).toBe(3);
+        expect(result3.added).toBe(false);
+        expect(result3.count).toBe(2);
       });
 
       it('should not count attestations as proposals for duplicate detection', async () => {

package/src/mem_pools/index.ts

@@ -1,6 +1,3 @@
 export { AttestationPool, type AttestationPoolApi } from './attestation_pool/attestation_pool.js';
 export { type MemPools } from './interface.js';
-// Old TxPool exports - kept temporarily for external consumers
-export { type TxPool } from './tx_pool/tx_pool.js';
-// New TxPoolV2 exports
 export { type TxPoolV2, type TxPoolV2Config, type TxPoolV2Events, type AddTxsResult } from './tx_pool_v2/index.js';

package/src/mem_pools/instrumentation.ts

@@ -73,7 +73,7 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
   private defaultAttributes;
   private meter: Meter;
 
-  private txAddedTimestamp: Map<bigint, number> = new Map<bigint, number>();
+  private mempoolItemAddedTimestamp: Map<bigint | string, number> = new Map<bigint | string, number>();
 
   constructor(
     telemetry: TelemetryClient,
@@ -114,22 +114,26 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
   }
 
   public transactionsAdded(transactions: Tx[]) {
-    const timestamp = Date.now();
-    for (const transaction of transactions) {
-      this.txAddedTimestamp.set(transaction.txHash.toBigInt(), timestamp);
-    }
+    transactions.forEach(tx => this.trackMempoolItemAdded(tx.txHash.toBigInt()));
   }
 
   public transactionsRemoved(hashes: Iterable<bigint> | Iterable<string>) {
-    const timestamp = Date.now();
     for (const hash of hashes) {
-      const key = BigInt(hash);
-      const addedAt = this.txAddedTimestamp.get(key);
-      if (addedAt !== undefined) {
-        this.txAddedTimestamp.delete(key);
-        if (addedAt < timestamp) {
-          this.minedDelay.record(timestamp - addedAt);
-        }
+      this.trackMempoolItemRemoved(BigInt(hash));
+    }
+  }
+
+  public trackMempoolItemAdded(key: bigint | string): void {
+    this.mempoolItemAddedTimestamp.set(key, Date.now());
+  }
+
+  public trackMempoolItemRemoved(key: bigint | string): void {
+    const timestamp = Date.now();
+    const addedAt = this.mempoolItemAddedTimestamp.get(key);
+    if (addedAt !== undefined) {
+      this.mempoolItemAddedTimestamp.delete(key);
+      if (addedAt < timestamp) {
+        this.minedDelay.record(timestamp - addedAt);
       }
     }
   }

package/src/mem_pools/tx_pool_v2/README.md

@@ -79,7 +79,7 @@ Lightweight metadata stored alongside each transaction:
 - `claimAmount`: Fee payer's claim from bridging
 - `feeLimit`: Maximum fee the tx can pay
 - `nullifiers`: For conflict detection
-- `includeByTimestamp`: Expiration timestamp
+- `expirationTimestamp`: Expiration timestamp
 - `minedL2BlockId`: Set when mined (undefined otherwise)
 
 State is derived by TxPoolIndices:
@@ -158,7 +158,7 @@ Checked before adding a transaction to the pending pool:
 
 | Rule | Purpose |
 |------|---------|
-| `NullifierConflictRule` | Handles transactions with conflicting nullifiers. Higher priority tx wins. |
+| `NullifierConflictRule` | Handles transactions with conflicting nullifiers. Higher priority tx wins. For RPC submissions, a configurable price bump percentage is required. |
 | `FeePayerBalancePreAddRule` | Ensures fee payer has sufficient balance for all their pending txs. |
 | `LowPriorityPreAddRule` | Rejects txs when pool is full and new tx has lowest priority. |
 
@@ -233,6 +233,14 @@ await pool.updateConfig({
 });
 ```
 
+### Price Bump (RPC Transaction Replacement)
+
+When a transaction is submitted via RPC and clashes on nullifiers with an existing pool transaction, the incoming tx must pay at least `priceBumpPercentage`% more in priority fee (i.e. `>= existingFee + existingFee * bump / 100`) to replace it. This prevents spam via small fee increments. The same bump applies when the pool is full and the incoming tx needs to evict the lowest-priority tx.
+
+- **Env var**: `P2P_RPC_PRICE_BUMP_PERCENTAGE` (default: 10)
+- **Scope**: RPC submissions only. P2P gossip uses `comparePriority` (fee + hash tiebreaker) with no bump.
+- Even with a 0% bump, a replacement tx must pay at least 1 unit more than the existing fee.
+
 ## Return Values
 
 ### AddTxsResult

package/src/mem_pools/tx_pool_v2/deleted_pool.ts

@@ -301,6 +301,17 @@ export class DeletedPool {
     return this.#state.size;
   }
 
+  /** Gets the count of soft-deleted transactions (both prune-based and slot-based). */
+  getSoftDeletedCount(): number {
+    let count = this.#slotDeletedTxs.size;
+    for (const state of this.#state.values()) {
+      if (state.softDeleted) {
+        count++;
+      }
+    }
+    return count;
+  }
+
   /**
    * Gets all transaction hashes from pruned blocks.
    */

package/src/mem_pools/tx_pool_v2/eviction/eviction_manager.ts

@@ -9,9 +9,12 @@ import {
   EvictionEvent,
   type EvictionRule,
   type PoolOperations,
+  type PreAddContext,
   type PreAddPoolAccess,
   type PreAddResult,
   type PreAddRule,
+  type TaggedEviction,
+  TxPoolRejectionCode,
 } from './interfaces.js';
 
 /**
@@ -47,21 +50,27 @@ export class EvictionManager {
    * Runs all pre-add rules for an incoming transaction.
    * Returns combined result of all rules.
    */
-  async runPreAddRules(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult> {
-    const allTxHashesToEvict: string[] = [];
+  async runPreAddRules(
+    incomingMeta: TxMetaData,
+    poolAccess: PreAddPoolAccess,
+    context?: PreAddContext,
+  ): Promise<PreAddResult> {
+    const evictions: TaggedEviction[] = [];
+    const seen = new Set<string>();
 
     for (const rule of this.preAddRules) {
       try {
-        const result = await rule.check(incomingMeta, poolAccess);
+        const result = await rule.check(incomingMeta, poolAccess, context);
 
         if (result.shouldIgnore) {
           return result;
         }
 
-        // Collect txs to evict from all rules
+        // Collect txs to evict from all rules, tagged with the rule name
         for (const txHash of result.txHashesToEvict) {
-          if (!allTxHashesToEvict.includes(txHash)) {
-            allTxHashesToEvict.push(txHash);
+          if (!seen.has(txHash)) {
+            seen.add(txHash);
+            evictions.push({ txHash, reason: rule.name });
           }
         }
       } catch (err) {
@@ -70,14 +79,18 @@ export class EvictionManager {
         return {
           shouldIgnore: true,
           txHashesToEvict: [],
-          reason: `pre-add rule ${rule.name} error: ${err}`,
+          reason: {
+            code: TxPoolRejectionCode.INTERNAL_ERROR,
+            message: `Pre-add rule ${rule.name} error: ${err}`,
+          },
         };
       }
     }
 
     return {
       shouldIgnore: false,
-      txHashesToEvict: allTxHashesToEvict,
+      txHashesToEvict: evictions.map(e => e.txHash),
+      evictions,
     };
   }