Revise linea-sequencer TxGasLimit Plugin for EIP-7825 Osaka Fork Compliance

[kyzooghost]

Description

EIP-7825 (part of the Osaka/Fusaka upgrade scheduled for December 3, 2025) introduces a per-transaction gas limit of 16,777,216 gas units (2²⁴).

The TxGasLimit plugin (GasLimitValidator) in the linea-sequencer currently defaults to 30,000,000 gas units, which exceeds the new protocol limit. EIP-7825 takes priority over this.

We need to:

1. Update the default maximum transaction gas limit to comply with EIP-7825 (16,777,216)
2. Ensure the validator properly enforces this limit for transactions submitted via API and P2P
3. Update gas estimation logic to respect the new limit
4. Revise tests and documentation to reflect the new constraint

Considered drawbacks:

• Transactions that previously worked with gas limits between 16,777,216 and 30,000,000 will be rejected
• May require coordination with users/clients who rely on higher gas limits
• Need to ensure backward compatibility considerations for pre-Osaka blocks

Motivation

Compliance: Linea must comply with Ethereum protocol changes to maintain compatibility and ensure transactions are valid on the network.

Network Stability: Enforcing the EIP-7825 limit prevents single transactions from consuming excessive gas, reducing DoS risk and enabling future parallel execution optimizations.

User Experience: Updating the plugin proactively ensures users receive clear error messages when transactions exceed the limit, rather than having them fail at the network level.

Consistency: Aligning our sequencer's gas limit validation with Ethereum's protocol ensures predictable behavior across the ecosystem.

Tasks

• Update DEFAULT_MAX_TRANSACTION_GAS_LIMIT constant in LineaTransactionPoolValidatorCliOptions.java from 30_000_000 to 16_777_216
• Review and update GasLimitValidator to ensure it properly handles the new limit (currently uses > comparison - verify this is correct)
• Update LineaEstimateGas.java to ensure gas estimation respects the EIP-7825 limit and provides appropriate error messages
• Update all test files that reference MAX_TX_GAS_LIMIT or use DefaultGasProvider.GAS_LIMIT to use the new limit:
  • TransactionGasLimitTest.java
  • EstimateGasTest.java (already partially updated)
  • SetExtraDataTest.java
  • TransactionCallDataSizeLimitTest.java
  • ProfitableTransactionTest.java
  • EthSendRawTransactionSimulationCheckTest.java
  • EthSendRawTransactionSimulationCheckLimitlessTest.java
  • TransactionTraceLimitTest.java
• Add fork-aware logic to enforce EIP-7825 limit only for blocks at or after Osaka fork activation
• Update error messages to reference EIP-7825 when appropriate
• Verify that GasLimitValidator correctly rejects transactions exceeding 16,777,216 gas
• Ensure linea_estimateGas endpoint properly validates against the new limit
• Review and update any documentation referencing the transaction gas limit

Acceptance criteria

• Default maxTxGasLimit is set to 16_777_216 (EIP-7825 limit)
• GasLimitValidator correctly rejects transactions with gas limit > 16,777,216
• GasLimitValidator accepts transactions with gas limit ≤ 16,777,216
• linea_estimateGas endpoint returns appropriate error when estimated gas exceeds EIP-7825 limit
• All existing tests pass with the new gas limit
• New test cases verify EIP-7825 compliance:
  • Test transaction with gas limit exactly at 16,777,216 is accepted
  • Test transaction with gas limit 16,777,217 is rejected
  • Test that gas estimation respects the limit
• Fork-aware validation: limit is enforced only for Osaka+ blocks (or always if we're post-Osaka)
• Documentation updated to reflect the new limit and reference EIP-7825
• Error messages clearly indicate when transactions exceed the EIP-7825 limit
• No regression in transaction pool validation performance

Risks

• Breaking Change: Transactions that previously worked may be rejected. Need to ensure clear communication and migration path.
• Fork Activation Timing: Must ensure the limit is enforced at the correct block/time for Osaka fork activation
• Gas Estimation Accuracy: Changes to gas limit may affect gas estimation accuracy for complex transactions
• Test Coverage: Existing tests may need significant updates, risk of missing edge cases
• Backward Compatibility: Need to handle pre-Osaka blocks correctly if the sequencer processes historical blocks
• Integration Points: Other systems (monitoring, tooling) may reference the old limit and need updates
• Performance Impact: Validation logic changes should not introduce performance regressions
• User Confusion: Users may not understand why previously valid transactions are now rejected

Remember to

• Add the documentation label - Documentation needs to be updated to reflect EIP-7825 compliance
• Add priority label - High (Protocol compliance requirement)
• Add team label - Sequencer team
• Add Task for updating the Runbook with:
  • New default gas limit value
  • EIP-7825 reference and compliance information
  • Troubleshooting guide for transactions rejected due to gas limit
• Add Task for metrics and alerts:
  • Track number of transactions rejected due to EIP-7825 gas limit
  • Alert if rejection rate spikes after Osaka fork activation
  • Monitor gas limit distribution to understand impact

Additional Notes

• EIP-7825 Reference: https://eips.ethereum.org/EIPS/eip-7825
• Current default: 30_000_000 (line 35 in LineaTransactionPoolValidatorCliOptions.java)
• New limit: 16_777_216 (2²⁴)
• Fork activation: Osaka fork (scheduled December 3, 2025)
• Related files:
  • besu-plugins/linea-sequencer/sequencer/src/main/java/net/consensys/linea/config/LineaTransactionPoolValidatorCliOptions.java
  • besu-plugins/linea-sequencer/sequencer/src/main/java/net/consensys/linea/sequencer/txpoolvalidation/validators/GasLimitValidator.java
  • besu-plugins/linea-sequencer/sequencer/src/main/java/net/consensys/linea/rpc/methods/LineaEstimateGas.java
  • Multiple test files in besu-plugins/linea-sequencer/acceptance-tests/