feat: price bump for RPC transaction replacement

docs/docs-operate/operators/reference/changelog/v4.md

@@ -137,6 +137,18 @@ Transaction submission via RPC now returns structured rejection codes when a tra
 
 **Impact**: Improved developer experience — callers can now programmatically handle specific rejection reasons.
 
+### RPC transaction replacement price bump
+
+Transactions submitted via RPC that clash on nullifiers with existing pool transactions must now pay at least X% more in priority fee to replace them. The same bump applies when the pool is full and the incoming tx needs to evict the lowest-priority tx. P2P gossip behavior is unchanged.
+
+**Configuration:**
+
+```bash
+P2P_RPC_PRICE_BUMP_PERCENTAGE=10     # default: 10 (percent)
+```
+
+Set to `0` to disable the percentage-based bump (still requires strictly higher fee).
+
 ## Changed defaults
 
 ## Troubleshooting

yarn-project/foundation/src/config/env_var.ts

@@ -152,6 +152,7 @@ export type EnvVar =
   | 'P2P_DROP_TX_CHANCE'
   | 'P2P_TX_POOL_DELETE_TXS_AFTER_REORG'
   | 'P2P_MIN_TX_POOL_AGE_MS'
+  | 'P2P_RPC_PRICE_BUMP_PERCENTAGE'
   | 'DEBUG_P2P_INSTRUMENT_MESSAGES'
   | 'PEER_ID_PRIVATE_KEY'
   | 'PEER_ID_PRIVATE_KEY_PATH'

yarn-project/p2p/src/client/factory.ts

@@ -102,6 +102,7 @@ export async function createP2PClient<T extends P2PClientType>(
         archivedTxLimit: config.archivedTxLimit,
         minTxPoolAgeMs: config.minTxPoolAgeMs,
         dropTransactionsProbability: config.dropTransactionsProbability,
+        priceBumpPercentage: config.priceBumpPercentage,
       },
       dateProvider,
     );

yarn-project/p2p/src/config.ts

@@ -190,6 +190,9 @@ 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: number;
 }
 
 export const DEFAULT_P2P_PORT = 40400;
@@ -464,6 +467,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. Set to 0 to disable price bumps.',
+    ...numberConfigHelper(10),
+  },
   ...sharedSequencerConfigMappings,
   ...p2pReqRespConfigMappings,
   ...batchTxRequesterConfigMappings,

yarn-project/p2p/src/mem_pools/tx_pool_v2/README.md

@@ -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 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.
+- Set to 0 to disable the percentage-based bump (still requires strictly higher fee).
+
 ## Return Values
 
 ### AddTxsResult

yarn-project/p2p/src/mem_pools/tx_pool_v2/eviction/interfaces.ts

@@ -100,7 +100,15 @@ export type TxPoolRejectionError =
       availableBalance: bigint;
       feeLimit: bigint;
     }
-  | { code: typeof TxPoolRejectionCode.NULLIFIER_CONFLICT; message: string; conflictingTxHash: string }
+  | {
+      code: typeof TxPoolRejectionCode.NULLIFIER_CONFLICT;
+      message: string;
+      conflictingTxHash: string;
+      /** Minimum fee needed to replace the conflicting tx (only set when price bump applies). */
+      minimumPriceBumpFee?: bigint;
+      /** Incoming tx's priority fee. */
+      txPriorityFee?: bigint;
+    }
   | { code: typeof TxPoolRejectionCode.INTERNAL_ERROR; message: string };
 
 /**
@@ -121,6 +129,8 @@ export interface PreAddResult {
 export interface PreAddContext {
   /** If true, compare priority fee only (no tx hash tiebreaker). Used for RPC submissions. */
   feeComparisonOnly?: boolean;
+  /** Percentage-based price bump required for tx replacement. Only set for RPC submissions. */
+  priceBumpPercentage?: number;
 }
 
 /**

yarn-project/p2p/src/mem_pools/tx_pool_v2/eviction/low_priority_pre_add_rule.test.ts

@@ -221,5 +221,75 @@ describe('LowPriorityPreAddRule', () => {
         expect(result2.shouldIgnore).toBe(true);
       });
     });
+
+    describe('with priceBumpPercentage', () => {
+      it('evicts when incoming fee exceeds the bump threshold', async () => {
+        const lowestPriorityMeta = createMeta('0x2222', 100n);
+        const poolAccess = createPoolAccess(100, lowestPriorityMeta);
+        const incomingMeta = createMeta('0x1111', 111n); // Above 10% bump
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 10 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(false);
+        expect(result.txHashesToEvict).toContain('0x2222');
+      });
+
+      it('ignores when incoming fee is exactly at the bump threshold', async () => {
+        const lowestPriorityMeta = createMeta('0x2222', 100n);
+        const poolAccess = createPoolAccess(100, lowestPriorityMeta);
+        const incomingMeta = createMeta('0x1111', 110n); // Exactly 10% bump — not enough
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 10 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(true);
+        expect(result.reason?.code).toBe(TxPoolRejectionCode.LOW_PRIORITY_FEE);
+        if (result.reason?.code === TxPoolRejectionCode.LOW_PRIORITY_FEE) {
+          expect(result.reason.minimumPriorityFee).toBe(111n);
+          expect(result.reason.txPriorityFee).toBe(110n);
+        }
+      });
+
+      it('ignores when incoming fee is below the bump threshold', async () => {
+        const lowestPriorityMeta = createMeta('0x2222', 100n);
+        const poolAccess = createPoolAccess(100, lowestPriorityMeta);
+        const incomingMeta = createMeta('0x1111', 109n); // Below 10% bump
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 10 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(true);
+        expect(result.reason?.code).toBe(TxPoolRejectionCode.LOW_PRIORITY_FEE);
+        if (result.reason?.code === TxPoolRejectionCode.LOW_PRIORITY_FEE) {
+          expect(result.reason.minimumPriorityFee).toBe(111n);
+          expect(result.reason.txPriorityFee).toBe(109n);
+        }
+      });
+
+      it('without price bump (P2P path), behavior unchanged', async () => {
+        const lowestPriorityMeta = createMeta('0x2222', 100n);
+        const poolAccess = createPoolAccess(100, lowestPriorityMeta);
+        const incomingMeta = createMeta('0x1111', 101n);
+
+        // No context — uses comparePriority, 101 > 100 so incoming wins
+        const result = await rule.check(incomingMeta, poolAccess);
+
+        expect(result.shouldIgnore).toBe(false);
+        expect(result.txHashesToEvict).toContain('0x2222');
+      });
+
+      it('with 0% bump, rejects equal fee (strict >)', async () => {
+        const lowestPriorityMeta = createMeta('0x2222', 100n);
+        const poolAccess = createPoolAccess(100, lowestPriorityMeta);
+        const incomingMeta = createMeta('0x1111', 100n);
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 0 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(true);
+        expect(result.txHashesToEvict).toHaveLength(0);
+      });
+    });
   });
 });

yarn-project/p2p/src/mem_pools/tx_pool_v2/eviction/low_priority_pre_add_rule.ts

@@ -1,6 +1,6 @@
 import { createLogger } from '@aztec/foundation/log';
 
-import { type TxMetaData, comparePriority } from '../tx_metadata.js';
+import { type TxMetaData, comparePriority, getMinimumPriceBumpFee } from '../tx_metadata.js';
 import {
   type EvictionConfig,
   type PreAddContext,
@@ -48,10 +48,13 @@ export class LowPriorityPreAddRule implements PreAddRule {
     }
 
     // Compare incoming tx against lowest priority tx.
-    // feeOnly mode (RPC): use strict fee comparison only — avoids churn from hash ordering
-    // Default (gossip): use full comparePriority (fee + tx hash tiebreaker) for determinism
+    // feeOnly mode (RPC): use strict fee comparison only — avoids churn from hash ordering.
+    // When price bump is also set, require the bumped fee threshold.
+    // Default (gossip): use full comparePriority (fee + tx hash tiebreaker) for determinism.
     const isHigherPriority = context?.feeComparisonOnly
-      ? incomingMeta.priorityFee > lowestPriorityMeta.priorityFee
+      ? context.priceBumpPercentage !== undefined
+        ? incomingMeta.priorityFee > getMinimumPriceBumpFee(lowestPriorityMeta.priorityFee, context.priceBumpPercentage)
+        : incomingMeta.priorityFee > lowestPriorityMeta.priorityFee
       : comparePriority(incomingMeta, lowestPriorityMeta) > 0;
 
     if (isHigherPriority) {
@@ -66,6 +69,11 @@ export class LowPriorityPreAddRule implements PreAddRule {
     }
 
     // Incoming tx has equal or lower priority - ignore it (it would be evicted anyway)
+    const minimumFee =
+      context?.feeComparisonOnly && context.priceBumpPercentage !== undefined
+        ? getMinimumPriceBumpFee(lowestPriorityMeta.priorityFee, context.priceBumpPercentage) + 1n
+        : lowestPriorityMeta.priorityFee + 1n;
+
     this.log.debug(
       `Pool at capacity (${currentCount}/${this.maxPoolSize}), ignoring ${incomingMeta.txHash} ` +
         `(priority ${incomingMeta.priorityFee}) - lower than existing minimum (priority ${lowestPriorityMeta.priorityFee})`,
@@ -75,8 +83,8 @@ export class LowPriorityPreAddRule implements PreAddRule {
       txHashesToEvict: [],
       reason: {
         code: TxPoolRejectionCode.LOW_PRIORITY_FEE,
-        message: `Tx does not meet minimum priority fee. Required: ${lowestPriorityMeta.priorityFee + 1n}, got: ${incomingMeta.priorityFee}`,
-        minimumPriorityFee: lowestPriorityMeta.priorityFee + 1n,
+        message: `Tx does not meet minimum priority fee. Required: ${minimumFee}, got: ${incomingMeta.priorityFee}`,
+        minimumPriorityFee: minimumFee,
         txPriorityFee: incomingMeta.priorityFee,
       },
     });

yarn-project/p2p/src/mem_pools/tx_pool_v2/eviction/nullifier_conflict_rule.test.ts

@@ -1,5 +1,5 @@
 import { type TxMetaData, stubTxMetaValidationData } from '../tx_metadata.js';
-import type { PreAddPoolAccess } from './interfaces.js';
+import { type PreAddContext, type PreAddPoolAccess, TxPoolRejectionCode } from './interfaces.js';
 import { NullifierConflictRule } from './nullifier_conflict_rule.js';
 
 describe('NullifierConflictRule', () => {
@@ -270,6 +270,112 @@ describe('NullifierConflictRule', () => {
       });
     });
 
+    describe('with priceBumpPercentage context', () => {
+      it('accepts tx when fee exceeds 10% bump threshold', async () => {
+        const sharedNullifier = '0xshared_null';
+        const existingMeta = createMeta('0x2222', 100n, [sharedNullifier]);
+        const incomingMeta = createMeta('0x1111', 111n, [sharedNullifier]); // Above 10%
+
+        const metadataMap = new Map<string, TxMetaData>([['0x2222', existingMeta]]);
+        const nullifierMap = new Map<string, string>([[sharedNullifier, '0x2222']]);
+        poolAccess = createPoolAccess(nullifierMap, metadataMap);
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 10 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(false);
+        expect(result.txHashesToEvict).toContain('0x2222');
+      });
+
+      it('rejects tx when fee is exactly at 10% bump threshold', async () => {
+        const sharedNullifier = '0xshared_null';
+        const existingMeta = createMeta('0x2222', 100n, [sharedNullifier]);
+        const incomingMeta = createMeta('0x1111', 110n, [sharedNullifier]); // Exactly 10% — not enough
+
+        const metadataMap = new Map<string, TxMetaData>([['0x2222', existingMeta]]);
+        const nullifierMap = new Map<string, string>([[sharedNullifier, '0x2222']]);
+        poolAccess = createPoolAccess(nullifierMap, metadataMap);
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 10 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(true);
+        expect(result.reason?.code).toBe(TxPoolRejectionCode.NULLIFIER_CONFLICT);
+        if (result.reason?.code === TxPoolRejectionCode.NULLIFIER_CONFLICT) {
+          expect(result.reason.minimumPriceBumpFee).toBe(110n);
+          expect(result.reason.txPriorityFee).toBe(110n);
+        }
+      });
+
+      it('rejects tx when fee is below 10% bump threshold', async () => {
+        const sharedNullifier = '0xshared_null';
+        const existingMeta = createMeta('0x2222', 100n, [sharedNullifier]);
+        const incomingMeta = createMeta('0x1111', 109n, [sharedNullifier]); // Below 10%
+
+        const metadataMap = new Map<string, TxMetaData>([['0x2222', existingMeta]]);
+        const nullifierMap = new Map<string, string>([[sharedNullifier, '0x2222']]);
+        poolAccess = createPoolAccess(nullifierMap, metadataMap);
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 10 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(true);
+        expect(result.reason?.code).toBe(TxPoolRejectionCode.NULLIFIER_CONFLICT);
+        if (result.reason?.code === TxPoolRejectionCode.NULLIFIER_CONFLICT) {
+          expect(result.reason.minimumPriceBumpFee).toBe(110n);
+          expect(result.reason.txPriorityFee).toBe(109n);
+        }
+      });
+
+      it('accepts tx well above bump threshold', async () => {
+        const sharedNullifier = '0xshared_null';
+        const existingMeta = createMeta('0x2222', 100n, [sharedNullifier]);
+        const incomingMeta = createMeta('0x1111', 200n, [sharedNullifier]);
+
+        const metadataMap = new Map<string, TxMetaData>([['0x2222', existingMeta]]);
+        const nullifierMap = new Map<string, string>([[sharedNullifier, '0x2222']]);
+        poolAccess = createPoolAccess(nullifierMap, metadataMap);
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 10 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(false);
+        expect(result.txHashesToEvict).toContain('0x2222');
+      });
+
+      it('without price bump (P2P path), behavior is unchanged', async () => {
+        const sharedNullifier = '0xshared_null';
+        const existingMeta = createMeta('0x2222', 100n, [sharedNullifier]);
+        const incomingMeta = createMeta('0x1111', 101n, [sharedNullifier]); // 1% above, not enough for 10% bump
+
+        const metadataMap = new Map<string, TxMetaData>([['0x2222', existingMeta]]);
+        const nullifierMap = new Map<string, string>([[sharedNullifier, '0x2222']]);
+        poolAccess = createPoolAccess(nullifierMap, metadataMap);
+
+        // No context (P2P) — uses comparePriority, 101 > 100 means incoming wins
+        const result = await rule.check(incomingMeta, poolAccess);
+
+        expect(result.shouldIgnore).toBe(false);
+        expect(result.txHashesToEvict).toContain('0x2222');
+      });
+
+      it('with 0% price bump, rejects equal fee (strict >)', async () => {
+        const sharedNullifier = '0xshared_null';
+        const existingMeta = createMeta('0x2222', 100n, [sharedNullifier]);
+        const incomingMeta = createMeta('0x1111', 100n, [sharedNullifier]);
+
+        const metadataMap = new Map<string, TxMetaData>([['0x2222', existingMeta]]);
+        const nullifierMap = new Map<string, string>([[sharedNullifier, '0x2222']]);
+        poolAccess = createPoolAccess(nullifierMap, metadataMap);
+
+        const context: PreAddContext = { feeComparisonOnly: true, priceBumpPercentage: 0 };
+        const result = await rule.check(incomingMeta, poolAccess, context);
+
+        expect(result.shouldIgnore).toBe(true);
+        expect(result.txHashesToEvict).toHaveLength(0);
+      });
+    });
+
     describe('edge cases', () => {
       it('skips self-reference (incoming tx hash in conflict list)', async () => {
         const nullifier = '0xnull1';

yarn-project/p2p/src/mem_pools/tx_pool_v2/eviction/nullifier_conflict_rule.ts

@@ -15,11 +15,12 @@ export class NullifierConflictRule implements PreAddRule {
 
   private log = createLogger('p2p:tx_pool_v2:nullifier_conflict_rule');
 
-  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess, _context?: PreAddContext): Promise<PreAddResult> {
+  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess, context?: PreAddContext): Promise<PreAddResult> {
     const result = checkNullifierConflict(
       incomingMeta,
       nullifier => poolAccess.getTxHashByNullifier(nullifier),
       txHash => poolAccess.getMetadata(txHash),
+      context?.priceBumpPercentage,
     );
 
     if (result.shouldIgnore) {

yarn-project/p2p/src/mem_pools/tx_pool_v2/interfaces.ts

@@ -46,6 +46,8 @@ export type TxPoolV2Config = {
   evictedTxCacheSize: number;
   /** The probability (0-1) that a transaction is discarded. 0 disables dropping. For testing purposes only. */
   dropTransactionsProbability: number;
+  /** Minimum percentage fee increase required to replace an existing tx via RPC (0 = no bump). */
+  priceBumpPercentage: number;
 };
 
 /**
@@ -57,6 +59,7 @@ export const DEFAULT_TX_POOL_V2_CONFIG: TxPoolV2Config = {
   minTxPoolAgeMs: 2_000,
   evictedTxCacheSize: 10_000,
   dropTransactionsProbability: 0,
+  priceBumpPercentage: 10,
 };
 
 /**