feat: add max-priority-fee-per-gas-cap (ceiling for the oracle tip)

[SahilVasava]

Problem

gasPriceManager has gas floors (floor-max-fee-per-gas, floor-max-priority-fee-per-gas) but no ceiling — it bids whatever eth_maxPriorityFeePerGas returns, verbatim.

On low-traffic chains where the bundler is the dominant tx sender, the priority-fee oracle feedback-loops on the bundler's own past tips and reports an absurd value. Observed on Arc mainnet:

• base fee sits at the 20 gwei protocol floor, blocks 0% full
• but eth_maxPriorityFeePerGas returns 500 gwei, and the executor bids it
• per Arc's docs, a 0 gwei tip is accepted (1 gwei suggested for congestion), target ~$0.01/tx
• result: each tx costs ~0.24–0.36 USDC instead of ~0.01 — a ~25× overpay that repeatedly drains the executor wallet

There's no config knob to cap this today (floors only raise; gas-price-bump < 100 scales a moving oracle and undershoots below base fee as the loop unwinds → stalls). So it needs a ceiling primitive.

Change

Add an optional max-priority-fee-per-gas-cap (gwei, parsed like the floors). When set:

• the priority fee is capped to it via minBigInt
• maxFeePerGas is reduced by the same delta, so the base-fee component is preserved (never pushes maxFee below the base fee) and we don't pay an inflated tip
• applied after the floors, so the cap wins if both are configured
• no behavior change when unset

bumpTheGasPrice is refactored to a single return so floors + cap compose cleanly.

It's also self-correcting: once the bundler bids capped tips, the oracle's percentile of recent tips drops within a few blocks and the loop unwinds.

Rollout

Set on the affected chain's config, e.g. Arc:

"max-priority-fee-per-gas-cap": "5"

(5 gwei = 5× Arc's suggested tip, ~100× below the looped 500; lands at ~$0.01/tx — Arc's target. Base fee is still paid in full and can rise legitimately under real congestion.) Other low-traffic chains where the bundler dominates can set it as needed; leaving it unset preserves current behavior.

[Copilot]

Pull request overview

Adds an optional configuration ceiling for maxPriorityFeePerGas so the bundler doesn’t blindly follow an inflated eth_maxPriorityFeePerGas value on low-traffic chains (where the oracle can feedback-loop on the bundler’s own prior tips), while keeping the base-fee component intact by reducing maxFeePerGas by the same delta.

Changes:

• Refactors bumpTheGasPrice to compute final floor-enforced fees via a single return.
• Introduces maxPriorityFeePerGasCap logic that caps priority fee and reduces maxFeePerGas by the same amount.
• Wires the new max-priority-fee-per-gas-cap option through CLI option definitions and Zod config schema parsing (gwei → wei via parseGwei).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
src/handlers/gasPriceManager.ts	Adds cap application for priority fee and refactors floor composition logic.
src/cli/config/options.ts	Exposes a new CLI/config option description for max-priority-fee-per-gas-cap.
src/cli/config/bundler.ts	Adds Zod schema parsing for max-priority-fee-per-gas-cap using parseGwei.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.