Port nonce-aware tx mempool (#971) to the soft-finality branch

[vishalchangrani]

Summary

This is a port of #971 (the nonce-aware transaction mempool) onto the soft-finality branch mpeter/poc-index-finalized-block-results. The team maintains two parallel lines — main (no soft-finality) and mpeter/poc-index-finalized-block-results (with soft-finality); #971 landed on the main line and now needs to exist here too.

Only the mempool feature was ported. vishal/nonce-aware-mini-pool had merged recent main (including the Glamsterdam EVM upgrade); none of that main/Glamsterdam churn is included here — this is a feature-diff port, not a whole-branch merge.

What was ported

• services/requester/tx_mempool.go (new) — TxMemPool with fast-path submission of expected-nonce txs, out-of-order nonce-gap holding, TTL, per-EOA submission spacing, and batch-size caps.
• services/requester/nonce_provider.go — upgraded the branch's existing (earlier-iteration) provider to the final Add nonce-aware transaction pool #971 API: split NonceView out of NonceProvider, renamed GetNonce → GetNextNonce, cached the built block view by indexed height, and added cache hit/miss metrics. NewLocalNonceProvider now takes a metrics.Collector.
• bootstrap/bootstrap.go — wired TxMemPool behind the new --tx-mempool-mode flag.
• config/config.go + cmd/run/cmd.go — Tx* mempool config fields, flags, and validation.
• metrics/collector.go + metrics/nop.go — txpool_* and nonce-view-cache metrics.
• models/errors/errors.go — ErrInFlightNonce, ErrNonceTooLow, ErrNonceTooHigh.
• services/requester/tx_mempool_test.go + tests/tx_mempool_test.go (new) — unit and e2e tests.

Notable conflict resolutions / adaptations

• nonce_provider.go already existed on the soft-finality branch as an earlier iteration of this same feature. Took the final Add nonce-aware transaction pool #971 version. Verified its dependencies (NewOverridableBlocksProvider 3-arg signature, blockGasLimit) match the soft-finality branch's APIs. The existing BatchTxPool caller uses GetBlockView().GetNonce(addr), which remains compatible with the new NonceView interface — only its NewLocalNonceProvider call needed the added collector arg.
• cmd/run/cmd.go — both the soft-finality flags/validation and the mempool flags/validation add code at the same anchor points; combined both (kept soft-finality's experimental-* flags and its [DEPRECATED] eoa-activity-cache-ttl help text).
• e2e tests — the soft-finality branch had folded an older iteration of the mempool e2e tests into tests/tx_batching_test.go (with a duplicate fundEOA). Removed those older duplicates and the imports they alone used, and added the canonical Add nonce-aware transaction pool #971 suite (tests/tx_mempool_test.go), which adds TTL-expiry and in-flight-nonce-rejection cases and uses its own setupTxMemPoolGatewayNode helper.

Validation

• go build ./... — pass
• go vet ./services/requester/ ./metrics/ ./bootstrap/ ./cmd/... — pass
• go test ./services/requester/ ./metrics/ -count=1 — pass
• go vet ./... / go build ./... in the tests/ module — pass
• gofmt -l on every touched file — clean

e2e tests were not run in this port (generous gas limits are harmless on either fork per the porting brief).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8566c45f-6df7-4289-90ad-d8e5ed3f0e85

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch vishal/port-971-nonce-mempool-soft-finality

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[vishalchangrani]

Testnet validation ✅

The soft-finality build was deployed to Flow testnet and validated end-to-end against a live gateway, mirroring the testing done for the base PR (#971).

Build under test (confirmed via web3_clientVersion): flow-evm-gateway@v1.5.1-eoa-nonce-cache-2-with-sf

Results:

• Fast path (single expected-nonce tx): 1/1 mined, status 1.
• In-order burst (50 txs submitted concurrently): sent in ~235ms with 0 send errors → 50/50 mined, status1=50, status0=0, not-mined=0 (~19s). No silent drops.

Both scenarios were verified via on-chain receipts against evm-001.devnet0. Since the mempool code here is an identical port of #971 (whose fuller scenario suite — gap/hold, TTL, duplicate, sustained 200-tx, multi-EOA — already passed on the main-line build), this confirms the soft-finality build submits, batches, and mines correctly.

🤖 Generated with Claude Code

[m-Peter]

LGTM!

[vishalchangrani]

Deployed these changes to the foundation run mainnet EVM GW one hour back and so far its looking good. DFNS traffic is being served OK - no dropped transactions and the EOA nonce cache is working as expected.

Tag: https://github.com/onflow/flow-evm-gateway/releases/tag/v1.5.1-eoa-nonce-cache-3-with-sf