[PT1-696, PT1-704] Refactor balance scale adjusters

[SteMak]

Change Summary

New opcode: FulfillBonus - last fill has a rate discount, incentivize order to be filled fully over partial fills
Refactored: BaseFeeAdjuster - apply adjustments to balances, not the post-swap amounts; required by partial fill implemented in swap opcodes
New opcode: BalanceScaleCut - guard to prevent multiple balance adjusters for taker side exceed specified maker min rate

Testing & Verification

How was this tested?

• Unit tests
• Integration tests
• Manual testing (describe steps)
• Verified on staging

Risk Assessment

Risk Level:

• Low - Minor changes, no operational impact
• Medium - Moderate changes, limited impact, standard rollback available
• High - Significant changes, potential operational impact, complex rollback

---

Note

Medium Risk
Changes core swap VM pricing for limit orders and replaces the BaseFeeAdjuster API/encoding; behavior shifts for partial fills and stacked adjusters, though covered by new unit tests.

Overview
Refactors limit-order pricing on balances instead of post-swap amounts so gas discounts, auctions, and partial fills compose correctly.

BaseFeeAdjuster is split into BaseFeeAdjusterBalanceIn / BaseFeeAdjusterBalanceOut: high basefee now reduces balanceIn or increases balanceOut (capped in bps of balance), replacing the old single opcode that tweaked amountIn/amountOut with a maxDecay on the trade size.

FulfillBonusBalanceIn / FulfillBonusBalanceOut add taker incentives when a fill consumes the remaining order (exact-in/out thresholds vs adjusted balances).

BalanceScaleCutIn / BalanceScaleCutOut clamp adjusted balances so stacked PLS, base-fee, and fulfill-bonus steps cannot offer a rate worse than a configured maker minimum (token-sorted rates, maker-favoring ceil/floor).

New opcodes are registered in OpcodeList and dispatched from Opcodes / LimitOpcodes; AdjustMinRate now rejects zero rates. Gas scripts and snapshots reflect the new encodings and slightly higher swap costs.

^{Reviewed by Cursor Bugbot for commit fca77f9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fca77f9. Configure here.}

[cursor]

FulfillBonus fees distort threshold

Medium Severity

FulfillBonusBalanceIn and FulfillBonusBalanceOut decide the all-or-nothing incentive using amountIn / amountOut, but fee opcodes such as FeeFlatOut and FeeProtocol (token-out) inflate or shrink those amounts before runLoop runs the bonus. Under the usual fee-before-adjuster layout used elsewhere (e.g. BaseFeeAdjuster fee invariants), an exact-out ask can cross the fulfillment threshold only because of the fee gross-up, so the bonus applies when the taker was not actually fulfilling on the balance curve. That grants an unintended maker-funded discount. The opposite fee-in path can also block a genuine fulfillment ask by reducing amountIn below the threshold.

 

^{Reviewed by Cursor Bugbot for commit fca77f9. Configure here.}

[SteMak]

Fulfill bonus under discussion
Adding a new register instead of BalanceScaleCut tracking the bonus feels more efficient