Migrate proportional action arguments from bps to ppm by e1Ru1o · Pull Request #617 · 0xProject/0x-settler

e1Ru1o · 2026-07-30T17:26:51Z

Summary

Breaking change. Every action argument that expresses a proportion of Settler's token balance is re-denominated from basis points (BASIS = 10_000) to parts-per-million (BASIS = 1_000_000), and renamed bps → ppm (maxBps → maxPpm in POSITIVE_SLIPPAGE). This makes sub-bp proportions expressible (e.g. a 30 ppm fee) and stops small fee proportions from truncating to zero on large-notional trades.

Action selectors are unchanged (parameter names are not part of the selector), so the unit is a property of the Settler deployment: encoders must key bps vs ppm on the Settler address they target.

Details

BASIS becomes 1_000_000 in SettlerAbstract, Encoder, and Decoder (the constructor cross-check asserts are unchanged and still hold).
The packed proportion field widens from 2 bytes to 3 bytes in two places:
- the non-VIP flash-accounting header (Encoder.encode / Decoder.initialize in FlashAccountingCommon.sol); VIP headers carry no proportion and are untouched;
- the leading field of every fill in UNISWAPV4, BALANCERV3, PANCAKE_INFINITY, EKUBO, and EKUBOV3. _HOP_DATA_LENGTH grows by 1 per venue (52→53, 3→4, 82→83, 47→48, 47→48).
Flag bits that ride on the fill proportion move to the new MSBs: BalancerV3 wrap/unwrap bits 15/14 → 23/22 (masks 0xc00000/0x400000/0x3fffff), Ekubo forwarding-extension bit 15 → 23 (0x800000/0x7fffff).
The Permit2 balance-proportional sell amount sentinel (~amount < BASIS) and the RFQ maker-permit asserts widen automatically with the constant.
The [Unreleased] CHANGELOG entry documents the full encoding change for integrators; sh/initial_description_*.md are updated so future chain bring-ups register ppm wording (existing chains' feature descriptions are immutable one-shot IPFS metadata and are unaffected).

Deliberately unchanged

Pool fees carried in the upper 16 bits of swapInfo (UniswapV2, Velodrome, VelodromeAlt) stay denominated in bps against a hard-coded 10_000: they describe the external pool's own fee convention, and 1e6 does not fit in that 16-bit field. Likewise EulerSwap's 1e4 LTV scale and MakerPSM's GEM_basis.

Testing

Unit tests: 189/189 pass via the CI command, including the UniswapV4 suite exercising the 3-byte fill encoding (single/multihop/multiplex/diamond/VIP) against a real PoolManager.
All unit and integration tests migrated: proportional values ×100, fill encoders uint16/bytes2 → uint24/bytes3, flag constructions moved to bits 23/22.
FOUNDRY_PROFILE=integration compiles; fork tests + gas comparison to be confirmed by CI.
Per-chain forge build --sizes passes for every chain in chain_config.json.

Gas Optimization

No hot-path changes; the arithmetic is identical (* ppm / BASIS). Calldata grows 1 byte per fill plus 1 byte per flash-accounting action. Contract size deltas vs master (95184a2) on the tightest chain:

Contract	master	this PR	Δ	headroom
MainnetSettler	23,619	23,625	+6 B	951 B
MainnetSettlerIntent	22,487	22,491	+4 B	2,085 B
MainnetSettlerMetaTxn	21,661	21,660	−1 B	2,916 B
MainnetBridgeSettler	6,340	6,345	+5 B	18,231 B

The growth is the PUSH2→PUSH3 widening of the BASIS literal and flag masks.

🤖 Generated with Claude Code

BASIS changes from 10_000 to 1_000_000. Every action argument expressing a proportion of Settler's token balance is renamed bps->ppm (maxBps->maxPpm) and re-denominated in parts-per-million. Action selectors are unchanged. The packed proportion field widens from 2 to 3 bytes in the flash-accounting header and in each UNISWAPV4/BALANCERV3/PANCAKE_INFINITY/EKUBO/EKUBOV3 fill; per-venue _HOP_DATA_LENGTH grows by 1. The BalancerV3 wrap/unwrap flags move to bits 23/22 of the fill's proportion field and the Ekubo forwarding-extension flag to bit 23. The Permit2 balance-proportional sentinel band widens with BASIS. Pool fees carried in swapInfo (UniswapV2, Velodrome) remain denominated in bps against a hard-coded 10_000 per the pools' own convention, as does EulerSwap's 1e4 LTV scale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

jparklev

Nice one.

Should we mention in the README like, "the first ppm deployment on each chain is nonce N (per-chain table), earlier nonces are bps”? Not 100% whats best for integrators, but seems like a pretty large behavoiral change we wouldn't want anyone to opt into accidentally

jparklev · 2026-08-04T20:32:56Z

                (
                    address(fromToken()),
-                    10_000,
+                    1_000_000,


Should we add some sub-bp cases here to test? (eg the 30 ppm fee mentioned by Phil)

we might, but:

ideally I would keep the proportions of all tests to not break them.

I don't think it brings that much value as tests should already test different proportions

jparklev · 2026-08-04T20:37:47Z

    using NotesLib for NotesLib.Note[];

-    uint256 internal constant BASIS = 10_000;
+    uint256 internal constant BASIS = 1_000_000;


thoughts on one shared like PPM_DENOM constant we import? (should be runtime bytecode neutral)

(in theory we also then wouldn't have to do like assert(BASIS == Encoder.BASIS) in BalancerV3 and pancake constructors)

yeah, at some point we should get to have a Constants.sol for things like this and native for example

Seems reasonable to me. Maybe add it to a Constants.sol file where we also put the ERC7528 constant?

Lol. I am slow.

jparklev · 2026-08-04T20:40:53Z

+                // implicitly advance it by 20 bytes to decode `ppm` then advance by 23 bytes

-                bps := shr(0x50, calldataload(data.offset))
+                ppm := shr(0x48, calldataload(data.offset))


nit: consider uint256 ppm; + ppm := shr(0xe8, calldataload(add(0x14, data.offset))).

It’s a couple bytes smaller, and then we don't need the “implicitly advance by 20 bytes” comment

(similar in erc20 branch below. could punt to a future cleanup)

that is a good catch

I believe the original implementation that created a dirty bps was more gas/stack efficient because it avoided an extra calldataload. But this is relatively old code that was written for an older solc that might be dumber than the current one.

It's worth testing.

jparklev · 2026-08-04T20:58:12Z

 ### Breaking changes

+* All proportional-amount action arguments are now denominated in parts-per-million (`ppm`; denominator 1_000_000) instead of basis points (`bps`; denominator 10_000)
+  * Affects the third-ish argument of `UNISWAPV3`, `UNISWAPV2`, `BASIC`, `VELODROME`, `MAKERPSM`, `DODOV1`, `DODOV2`, `MAVERICKV2`, `EULERSWAP`, `HANJI`, `UNISWAPV4`, `BALANCERV3`, `PANCAKE_INFINITY`, `EKUBO`, and `EKUBOV3`; the `maxBps` (now `maxPpm`) argument of `POSITIVE_SLIPPAGE`; and BridgeSettler's `BASIC`


"third-ish" reads as kind of odd here to me. Maybe just named like "the proportion-of-balance argument"?

changed it to bps to be explicit about the argument affected instead of its position

immunefi-magnus · 2026-08-12T10:30:54Z

🛡️ Immunefi PR Reviews

We noticed that your project isn't set up for automatic code reviews. If you'd like this PR reviewed by the Immunefi team, you can request it manually using the link below:

🔗 Send this PR in for review

Once submitted, we'll take care of assigning a reviewer and follow up here.

duncancmt · 2026-08-12T16:31:55Z

    using NotesLib for NotesLib.Note[];

-    uint256 internal constant BASIS = 10_000;
+    uint256 internal constant BASIS = 1_000_000;


Seems reasonable to me. Maybe add it to a Constants.sol file where we also put the ERC7528 constant?

duncancmt · 2026-08-12T16:32:24Z

    using NotesLib for NotesLib.Note[];

-    uint256 internal constant BASIS = 10_000;
+    uint256 internal constant BASIS = 1_000_000;


Lol. I am slow.

duncancmt · 2026-08-12T16:44:43Z

+                // implicitly advance it by 20 bytes to decode `ppm` then advance by 23 bytes

-                bps := shr(0x50, calldataload(data.offset))
+                ppm := shr(0x48, calldataload(data.offset))


I believe the original implementation that created a dirty bps was more gas/stack efficient because it avoided an extra calldataload. But this is relatively old code that was written for an older solc that might be dumber than the current one.

It's worth testing.

e1Ru1o and others added 2 commits July 30, 2026 19:26

update snapshots

b4c8aa4

e1Ru1o requested a review from jparklev July 31, 2026 11:03

e1Ru1o self-assigned this Jul 31, 2026

jparklev reviewed Aug 4, 2026

View reviewed changes

review comments

8632854

e1Ru1o force-pushed the e1Ru1o/ppm branch from 9a57364 to 8632854 Compare August 12, 2026 10:24

e1Ru1o marked this pull request as ready for review August 12, 2026 10:30

e1Ru1o requested a review from duncancmt as a code owner August 12, 2026 10:30

duncancmt approved these changes Aug 12, 2026

View reviewed changes

Uh oh!

Conversation

e1Ru1o commented Jul 30, 2026

Summary

Details

Deliberately unchanged

Testing

Gas Optimization

Uh oh!

jparklev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

immunefi-magnus Bot commented Aug 12, 2026

🛡️ Immunefi PR Reviews

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants