feat: add V4 fee adapter with policy-based waterfall and automated classification

[ccashwell]

Adds the V4 leg of the protocol-fee system: a long-lived V4FeeAdapter registered with v4-core's PoolManager as the protocolFeeController, and a replaceable V4FeePolicy that resolves fees via either a piecewise-linear bucket schedule (vanilla pools) or family-based classification (hook-using and dynamic-fee pools). Per-pair fees are stored in pairClassFees[pairHash][familyId] so aggregator rollout and native-math rollout do not share a single pair-level knob. Permissionless triggerFeeUpdate propagates resolved fees onto pools; permissionless collect routes accrued protocol fees to the immutable TOKEN_JAR.

Files

Path	Purpose
src/feeAdapters/V4FeeAdapter.sol	The PoolManager's registered protocolFeeController. Pool-level overrides, policy delegation, permissionless triggerFeeUpdate / batchTriggerFeeUpdate / collect.
src/feeAdapters/V4FeePolicy.sol	Pluggable fee-resolution policy. Bucket schedule (Path A) + family classification (Path B) with per-family pair class fees.
src/interfaces/IV4FeeAdapter.sol, IV4FeePolicy.sol	Interfaces, shared structs (FeeBucket, FlagRule).
src/interfaces/IFeeClassifiedHook.sol	Optional self-classification interface for hooks.
src/libraries/HookFeeFlags.sol	12-flag behavioral vocabulary across value-extraction / strategy / integration buckets.
test/V4FeeAdapter.t.sol	115 unit tests against MockV4PoolManager.
test/V4FeeAdapter.fork.t.sol	11 integration tests against a real v4 PoolManager via Deployers.
snapshots/V4FeeAdapter*.json	Gas snapshots, isolated mode (matches CI).
README.md	V4 architecture section + ASCII waterfall + role/cap summary.
audit/openzeppelin-4.pdf	OpenZeppelin audit report for the V4 fee adapter stack.

Net diff vs main: +3535 / −8.

Mental model

The adapter is a scheduler + collector, not on the swap path. It is never called during a swap.

swapper                                                LP
  │                                                    │
  └──► PoolManager.swap (only inside unlock())         │
         │                                             │
         ├──► takes lpFee from swap proceeds  ────────► (LP's portion)
         │
         └──► IF Slot0.protocolFee != 0:
                takes protocolFee from swap proceeds
                  │
                  └──► protocolFeesAccrued[currency] += amount

Slot0.protocolFee is only set because someone previously called adapter.triggerFeeUpdate(key), which called PoolManager.setProtocolFee(key, getFee(key)) with the value returned by the adapter+policy waterfall. v4-core never asks the controller for a fee — controllers only push. New pools start at protocol fee 0 and stay there until triggered.

   (anyone calls adapter.collect at any time)
                  │
                  ▼
            PoolManager.collectProtocolFees(TOKEN_JAR, currency, amount)
                  │
                  └──► tokens delivered to the immutable TokenJar

Both triggerFeeUpdate and collect are permissionless because their effects are bounded by adapter/policy state (governance-controlled) and the immutable TOKEN_JAR destination.

Fee resolution waterfall

adapter.poolOverrides[poolId]   ──►  return (sentinel-decoded)
        │
        └──►  policy.computeFee(key)
                │
                ├── Path A: StaticNativeMath ──►  pairClassFees[pair][NATIVE_MATH_FAMILY_ID]  OR
                │                                 walk feeBuckets backward, find largest
                │                                 lpFeeFloor <= key.fee (snap to bucket 0
                │                                 if key.fee < floor_0); return
                │                                 alpha + beta × (key.fee - floor) / 1_000_000
                │
                └── Path B: Classified ────────►  familyId from _resolveFamily(hook)
                                                  (hookFamilyId  OR  flag-rule match)
                                                  │
                                                  ├─ family == 0 ──►  defaultFee
                                                  │
                                                  └─ family > 0 ──►  pairClassFees[pair][family]  OR
                                                                     familyDefaults[family]  OR
                                                                     defaultFee

A pool takes Path A when the hook has no *_RETURNS_DELTA flags AND key.fee is static; Path B otherwise. key.fee is unreliable on Path B (dynamic fees can change every swap; custom-accounting hooks rewrite swap deltas), so the bucket schedule does not apply there.

NATIVE_MATH_FAMILY_ID (0) is a reserved slot in pairClassFees for StaticNativeMath pair overrides only. It is not the same as hookFamilyId == 0 on Path B, which means unclassified and falls through to defaultFee. Path B never reads pairClassFees[pair][0].

Both paths use MULTIPLIER_DENOMINATOR = 1_000_000 for bucket slope math and the per-direction MAX_PROTOCOL_FEE = 1000 clamp from v4-core's ProtocolFeeLibrary. v4-core re-validates the value pushed via setProtocolFee (defense in depth).

Path A — bucket schedule

Each FeeBucket is (uint24 lpFeeFloor, uint24 alphaPips, uint32 betaPips) packed into a single storage slot:

• alpha — flat per-direction base fee, capped at MAX_PROTOCOL_FEE (1000).
• beta — slope in pips of protocol fee per pip of (lpFee - floor), capped at 1_000_000_000.
• beta = 0 → step function. alpha = 0 → slope-only. Both nonzero → general piecewise-linear.
• Continuity at boundaries is governance's responsibility — not enforced by the contract.
• lpFee < floor_0 snaps to bucket 0 with delta = 0, so alpha_0 doubles as a minimum-fee floor for very-low-LP-fee pools (race-to-the-bottom defense without an explicit minFee field).
• Capped at 16 buckets (MAX_BUCKETS); set atomically via setFeeBuckets, cleared via clearFeeBuckets.

Optional Path A pair override: setPairClassFee(c0, c1, NATIVE_MATH_FAMILY_ID, fee) — same behavior as the old flat pairFees, but scoped to the native-math slot so classified families cannot inherit it.

Path B — family classification

_resolveFamily(hook):

1. Governance override — hookFamilyId[hook] wins if non-zero.
2. Self-report — if any flag rules are configured, gas-capped (30k) staticcall to hook.protocolFeeFlags(). Walk _flagRules in array order; first rule whose requiredFlags are all set in the hook's flags wins.
3. Otherwise — familyId = 0 → defaultFee only.

With family > 0, the policy returns pairClassFees[ph][family] if set (literal fee, no scaling), else familyDefaults[family], else defaultFee. This supports per-pair fees for one family (e.g. aggregator) without affecting other families or native-math pools on the same token pair.

Self-report is opt-in: hooks not implementing IFeeClassifiedHook.protocolFeeFlags() land at family = 0 unless pinned via setHookFamily. Failure modes (revert / OOG / bad return data / no code) all gracefully fall through.

Sentinel encoding

pairClassFees, familyDefaults, defaultFee, and poolOverrides use ZERO_FEE_SENTINEL = type(uint24).max to distinguish "explicit zero" (short-circuits the waterfall to 0) from "not set" (falls through to the next layer). The sentinel is provably never a valid protocol fee — both 12-bit components decode to 4095, and isValidProtocolFee requires each ≤ 1000 — so there is no collision risk.

Roles

• owner — Solmate Owned, single-step. Swaps the policy (adapter only) and rotates the fee-setter on each contract. Adapter and policy have independent owner slots, so rotation is two transactions.
• feeSetter — operational governance. On the adapter: pool overrides. On the policy: bucket schedule, pair class fees (setPairClassFee / clearPairClassFee), hook families, flag rules, family defaults, defaultFee.
• anyone — triggerFeeUpdate, batchTriggerFeeUpdate, collect, all view methods.

Push-only fee setting

v4-core's PoolManager.initialize does not call into the protocolFeeController (verified at lib/v4-core/src/libraries/Pool.sol:105 — "the initial protocolFee is 0 so doesn't need to be set"). Pools start at protocol fee 0 and stay there until someone explicitly pushes a value via triggerFeeUpdate. Implications:

• We will run a keeper that watches Initialize, PolicyUpdated, FeeBucketsUpdated, PairClassFeeUpdated, PoolOverrideUpdated, etc., and triggers affected pools. Anyone can do this — it's a pure liveness role.
• Discovery is off-chain. v4 doesn't enumerate PoolKeys on-chain; the keeper indexes PoolManager.Initialize events to learn them.
• After any governance config change, fees on the PoolManager are stale until the corresponding triggerFeeUpdate lands. Operational mitigation: bundle config + trigger in a single multicall.

Deliberate design choices

These are conscious tradeoffs, not oversights. Calling them out so reviewers don't suggest changing them:

1. Single-step Solmate Owned. Governance is trusted to handle ownership rotation correctly.
2. No pause(). Owner can effectively pause/disable fees via setPolicy(address(0)) + batchTriggerFeeUpdate(allPools).
3. Per-family pair fees instead of a global pairFees + multiplier. Avoids coupling aggregator per-pair tuning to native-math pools and other classified families. Fees are literal per (pair, family); no discount/premium multiplier layer.
4. NATIVE_MATH_FAMILY_ID reuses uint8 0 in a different namespace from hookFamilyId == 0. Documented on-chain constant; Path B never indexes the native slot.
5. TOKEN_JAR is immutable, not validated at construction. Deployment-time concern; deploy script handles the invariant.
6. batchTriggerFeeUpdate and collect are unbounded. Caller bears their own gas.
7. No on-chain enforcement that adapter.owner == policy.owner. Deploy script handles coordinated ownership transfer.
8. Hook self-report is opt-in and unauthenticated. Governance-configured flag rules MUST only point at families with fees ≥ the intended floor. High-stakes hooks are pinned via setHookFamily directly.
9. triggerFeeUpdate is permissionless even immediately after a config change. Bounded by MAX_PROTOCOL_FEE = 0.1%.

Notes

The branch evolved through several fee-resolution iterations (curve → single multiplier → piecewise-linear buckets → per-family pairClassFees) as governance refined rollout requirements (native curve vs aggregator per-pair vs classified families). The final shape lives in the current V4FeePolicy; squash-merging is fine since this lands as one PR.

[hensha256]

_encodeFee, _decodeFee and _validateFee are all defined in both contracts. Would be great to have a fee library instead that both contracts use fee.decode() fee.encode() fee.validate()

[hensha256]

in fact you could not bother with validate, and call the protocol fee library inline instead, that way the error emitted can have better parameters available in the higher level function call?

[hensha256]

oh both contracts also have a feeSetter, and onlyFeeSetter. Maybe more stuff too? Is it worth having a base contract with common stuff?

[hensha256]

feels kind of weird that the 2 contracts might have different fee setter addresses? or is that intentional?

[ccashwell]

this was intentional with the idea being that a future version of the v4 policy could be the sole entrypoint to fee configuration while deferring the complexity of a potentially multi-role design to a later date