bug(anvil): improve UX on Anvil's side and user's side when a transaction is dropped from the mempool

[zerosnacks]

Component

Anvil

Describe the feature you would like

We currently get stuck into a transactionReceipt fetching loop on the user side and the user has no feedback that their transaction has been dropped.

Additional context

No response

[gakonst]

Draft PR Proposal: Improve UX for Dropped Transactions

Summary

This PR addresses the issue where users get stuck in a eth_getTransactionReceipt polling loop with no feedback when their transaction is dropped from the mempool.

Proposed Changes

1. New Subscription: droppedTransactions (Anvil Extension)

Add a new WebSocket subscription mirroring newPendingTransactions:

// Hash-only (default)
await provider.send("eth_subscribe", ["droppedTransactions"])

// Full details
await provider.send("eth_subscribe", ["droppedTransactions", true])

Wire format (full mode):

{
  "method": "eth_subscription",
  "params": {
    "subscription": "0x...",
    "result": {
      "hash": "0x...",
      "reason": "replaced|invalid|evicted|dropped|discarded",
      "replaced_by": "0x...",  // optional
      "removed_at": 1707223456
    }
  }
}

2. Bounded Dropped Transaction Index

Track recently dropped transactions in a memory-bounded structure:

pub struct DroppedTxRecord {
    pub hash: TxHash,
    pub reason: DroppedReason,
    pub removed_at: u64,
    pub replaced_by: Option<TxHash>,
}

pub enum DroppedReason {
    Replaced,    // tx replaced by higher gas price tx
    Invalid,     // tx became invalid (nonce gap, etc.)
    Evicted,     // pool capacity limit
    Dropped,     // manual anvil_dropTransaction
    Discarded,   // promotion failure
}

• Cap at ~10,000 entries with FIFO eviction
• Low memory overhead (~500KB)

3. Informative eth_getTransactionReceipt Error

Change behavior when a tx hash is known to be dropped:

Scenario	Current Behavior	New Behavior
Tx mined	Returns receipt	Returns receipt
Tx pending	Returns null	Returns null
Tx dropped	Returns null forever	Returns JSON-RPC error

Error format:

{
  "code": -32000,
  "message": "transaction dropped from mempool",
  "data": {
    "hash": "0x...",
    "reason": "replaced",
    "replaced_by": "0x...",
    "removed_at": 1707223456
  }
}

This immediately breaks the polling loop and surfaces actionable information.

Files to Modify

File	Changes
crates/anvil/src/eth/pool/mod.rs	Add dropped_listener, DroppedIndex, emit drop events
crates/anvil/src/pubsub.rs	Add DroppedTransactions subscription variant
crates/anvil/src/server/rpc_handlers.rs	Handle droppedTransactions subscription
crates/anvil/src/eth/api.rs	Modify transaction_receipt() to check dropped index
crates/anvil/core/src/eth/mod.rs	Add DroppedTransactions to subscription kinds

Emission Points

All paths where txs leave the pool without being mined:

1. Pool::drop_transaction() → DroppedReason::Dropped
2. Pool::remove_invalid() → DroppedReason::Invalid
3. Pool::add_transaction() replacements → DroppedReason::Replaced (with replaced_by)
4. PoolInner::prune_markers() failures → DroppedReason::Discarded

Testing Plan

• Unit tests for DroppedIndex (insert, lookup, FIFO eviction)
• Integration test: subscribe to droppedTransactions, drop a tx, verify event
• Integration test: drop tx via anvil_dropTransaction, verify receipt error
• Integration test: replace tx with higher gas, verify original reported as replaced
• E2E test with cast/script to verify polling stops on dropped tx

Risks & Mitigations

Risk	Mitigation
Receipt error breaks strict geth compatibility	Anvil is dev-focused; optionally gate behind flag
Memory growth	Bounded FIFO index with configurable cap
Deadlock from nested locks	Drop pool lock before notifying listeners

Effort Estimate

~1-2 days for core implementation + tests

---

cc @zerosnacks

[gakonst]

Downstream Tooling Changes Required

Since droppedTransactions is a non-standard subscription, this needs support across several layers:

1. alloy-rs/alloy — alloy-rpc-types-eth

SubscriptionKind is currently a closed enum with only 4 variants (NewHeads, Logs, NewPendingTransactions, Syncing). No Other(String) escape hatch exists.

Options:

• (a) Add Other(String) variant to SubscriptionKind in alloy (upstream PR)
• (b) Bypass SubscriptionKind in Anvil's request parsing — deserialize the raw subscription name string in anvil_core before it hits alloy's enum, and match "droppedTransactions" at the Anvil level

Option (b) is faster and avoids an upstream dependency, but (a) is cleaner long-term and benefits other custom node implementations.

2. alloy-rs/alloy — alloy-provider / PendingTransactionBuilder

PendingTransactionBuilder::get_receipt() polls eth_getTransactionReceipt in a loop. Needs to handle the new -32000 error as a terminal "dropped" signal instead of retrying.

3. Foundry — crates/script/src/receipts.rs

check_tx_status() already has a TxStatus::Dropped variant and falls back to get_transaction_by_hash to detect drops. With the new receipt error, it should also match on the -32000 error code directly — giving faster, more reliable drop detection.

4. Foundry — crates/cast/src/tx.rs

Cast::receipt() uses PendingTransactionBuilder and will spin forever if a tx is dropped. Needs to catch the new error and surface it to the user.

5. Foundry — crates/forge/src/cmd/create.rs

Contract deployment receipt polling via PendingTransactionError — should map the new error to ContractDeploymentError with a clear message.

Summary

Repo	Crate/File	Change
alloy-rs/alloy	alloy-rpc-types-eth	Add Other(String) to SubscriptionKind, or skip
alloy-rs/alloy	alloy-provider	PendingTransactionBuilder handles -32000 dropped error
foundry-rs/foundry	anvil/core	Parse "droppedTransactions" subscription
foundry-rs/foundry	anvil/src/eth/pool	Emit drop events, maintain dropped index
foundry-rs/foundry	anvil/src/pubsub.rs	DroppedTransactions subscription variant
foundry-rs/foundry	anvil/src/eth/api.rs	Receipt endpoint checks dropped index
foundry-rs/foundry	script/src/receipts.rs	Handle -32000 error as terminal drop
foundry-rs/foundry	cast/src/tx.rs	Surface dropped error to user
foundry-rs/foundry	forge/src/cmd/create.rs	Map dropped error to deployment error

The Anvil-side changes (pool, pubsub, api) can land first with option (b) for subscription parsing. The alloy upstream PR and foundry consumer-side fixes can follow.