feat: add morph tx pool

[panos-xyz]

Summary by CodeRabbit

• New Features

  • Introduced a Morph L2 transaction pool with ERC20-based fee support for 0x7F transactions, including validation, maintenance, and pool types.
  • Prague hardfork activation can now be enabled via the Emerald timestamp.

• Improvements

  • Enhanced validation and maintenance: L1 data fee handling, token price/balance checks, clearer failure classifications, and L1 block info caching.
  • Updated docs/terminology to MPTFork.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new Morph L2 transaction pool crate with ERC20-fee validation, validator and maintenance tasks; updates chainspec hardfork plumbing (Prague activation); adds MorphTx envelope accessors; and introduces error, transaction wrapper, and validation modules for pool integration.

Changes

Cohort / File(s)	Summary
Workspace / Manifest Cargo.toml, crates/txpool/Cargo.toml	Adds crates/txpool to workspace and introduces the morph-txpool crate manifest and workspace-scoped dependencies.
Chainspec crates/chainspec/src/hardfork.rs, crates/chainspec/src/spec.rs	Adds #[auto_impl::auto_impl(&, Arc)] to MorphHardforks and activates EthereumHardfork::Prague at the Emerald timestamp when configured; includes tests.
Primitives / Engine API crates/primitives/src/transaction/envelope.rs, crates/engine-api/src/lib.rs, crates/engine-api/src/validator.rs	Adds MorphTxEnvelope accessors is_morph_tx, fee_token_id, fee_limit; updates engine-api docs/terminology.
Txpool: Public API & Wiring crates/txpool/src/lib.rs	Exposes txpool types, validation APIs, maintenance entry point, and defines MorphTransactionPool type alias.
Txpool: Error Handling crates/txpool/src/error.rs	New MorphTxError enum with Display/Error impls, PoolTransactionError integration, and conversion to pool invalid transaction error.
Txpool: Transaction Wrapper crates/txpool/src/transaction.rs	Adds MorphPooledTransaction with lazy 2718 encoding and implements PoolTransaction / Typed2718 / alloy_consensus::Transaction / EthPoolTransaction traits (blob ops unsupported).
Txpool: Validation Logic crates/txpool/src/morph_tx_validation.rs	Centralizes MorphTx validation (input/result structs, validate_morph_tx, extract_morph_tx_fields) with token lookups, fee computations, and detailed error mapping.
Txpool: Validator & L1 Info crates/txpool/src/validator.rs	Adds MorphTransactionValidator and MorphL1BlockInfo, integrates L1 block info caching, rejects unsupported blob/L1-message txs, and performs ERC20-fee balance validation.
Txpool: Maintenance Task crates/txpool/src/maintain.rs	New maintain_morph_pool async task that subscribes to canonical heads, revalidates MorphTx entries, and prunes invalid transactions; logs and continues on recoverable failures.

Sequence Diagram(s)

sequenceDiagram
    participant PoolMaint as Pool<br/>Maintenance
    participant Canon as Canonical<br/>State
    participant ChainSpec as ChainSpec<br/>Provider
    participant StateDB as StateDB /<br/>State Provider
    participant Validator as MorphTx<br/>Validator
    participant Pool as Transaction<br/>Pool

    PoolMaint->>Canon: Subscribe to head changes
    Canon-->>PoolMaint: New block event
    PoolMaint->>ChainSpec: Get hardfork at block
    ChainSpec-->>PoolMaint: Hardfork ID
    PoolMaint->>Pool: Collect MorphTx from pending/queued
    Pool-->>PoolMaint: MorphTx list
    PoolMaint->>StateDB: Get state provider for tip
    StateDB-->>PoolMaint: State snapshot
    PoolMaint->>StateDB: Fetch L1 block info
    StateDB-->>PoolMaint: L1BlockInfo
    loop per MorphTx
        PoolMaint->>StateDB: Get sender ETH balance
        StateDB-->>PoolMaint: ETH balance
        PoolMaint->>Validator: validate_morph_tx(tx, balance, l1_fee, hardfork)
        Validator-->>PoolMaint: Valid / Invalid (MorphTxError)
        alt Invalid
            PoolMaint->>Pool: Remove transaction
        end
    end

Loading

sequenceDiagram
    participant Origin as Transaction<br/>Origin
    participant Validator as MorphTx<br/>Validator
    participant Envelope as MorphTxEnvelope
    participant TokenDB as StateDB /<br/>Token Lookup
    participant Result as Validation<br/>Result

    Origin->>Validator: validate_one(tx)
    Validator->>Envelope: extract fee_token_id, fee_limit
    Envelope-->>Validator: (token_id, fee_limit) or None
    Validator->>Validator: Check ETH balance >= tx.value
    alt ETH insufficient
        Validator-->>Result: InsufficientEthForValue
    else
        Validator->>TokenDB: TokenFeeInfo::try_fetch(token_id)
        alt Token not found / fetch failed
            TokenDB-->>Result: TokenNotFound / TokenInfoFetchFailed
        else
            TokenDB-->>Validator: TokenFeeInfo
            Validator->>Validator: Validate token active & price_ratio
            Validator->>Validator: Compute gas + L1 data -> total_eth_fee
            Validator->>Validator: Convert eth fee -> required_token_amount
            alt fee_limit < required_token_amount
                Validator-->>Result: FeeLimitTooLow
            else
                Validator->>TokenDB: Get token balance(sender)
                alt insufficient token balance
                    TokenDB-->>Result: InsufficientTokenBalance
                else
                    Validator-->>Result: Valid (MorphTxValidationResult)
                end
            end
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Refactor: Tx process and Validation #8 — overlaps additions of fee_token_id and fee_limit accessors used by txpool.
• feat: set precompiles for each spec #11 — changes to TokenFeeInfo::try_fetch signature may conflict with txpool calls that fetch token info.
• refactor: Rename AltFee to MorphTransaction #16 — modifies transaction envelope API/naming that relates to txpool's MorphTx handling.

Suggested reviewers

• anylots
• chengwenxi

"🐰
I hopped in code, with paws that tap,
A pool that counts each token's map,
Prague lit the chain, fees checked just right,
Morphs validate and queue by night,
Hooray—transactions take flight!"

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add morph tx pool' accurately and concisely summarizes the primary change—introducing a new Morph transaction pool implementation with validation, error handling, and maintenance tasks across multiple new modules.
Docstring Coverage	✅ Passed	Docstring coverage is 94.38% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

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 and usage tips.}

[panos-xyz]

@panos-xyz test