v4quote 0.1.0__py3-none-any.whl

v4quote/__init__.py

@@ -0,0 +1 @@
+

v4quote/amm/__init__.py

@@ -0,0 +1 @@
+"""Exact-integer AMM swap math. Pure functions over explicit pool state."""

v4quote/amm/algebra_integral.py

@@ -0,0 +1,91 @@
+"""Algebra Integral (v1.x) concentrated-liquidity pools: the Uniswap v3 swap math with Algebra's tick walk.
+
+What is the same as Uniswap v3 (so ``v4quote.amm.v3.pool`` quotes these pools; no second copy of the math):
+* the swap step (``PriceMovementMath.movePriceTowardsTarget`` = ``SwapMath.computeSwapStep``: fee taken from the
+  input as ``mulDiv(amount, 1e6 - fee, 1e6)``, the same rounding of the price and the token deltas), TickMath,
+  the crossing (``liquidity += liquidityDelta`` upwards, ``-=`` downwards; tick = nextTick - 1 after crossing down);
+* the swap ABI ``swap(recipient, zeroToOne, amountRequired, limitSqrtPrice, data)`` (selector 0x128acb08) and the
+  callback semantics (``algebraSwapCallback(int256, int256, bytes)``);
+* the events ``Swap`` / ``Mint`` / ``Burn`` (same topics as Uniswap v3: post price, liquidity, tick).
+
+What differs (and is modelled here):
+* the tick walk: Algebra jumps from one initialised tick to the next (a linked list, ``prevTickGlobal`` /
+  ``nextTickGlobal`` / ``ticks(t).nextTick``), it never stops at a 256-tick bitmap word boundary like v3. Every
+  step rounds on its own, so the number of steps matters at the wei level: ``AlgebraTickSnapshot`` answers
+  ``next_initialized_tick_within_one_word`` with the next initialised tick itself (across words);
+* the bitmap ``tickTable(int16)`` holds UNcompressed ticks (word = tick >> 8, bit = tick & 0xFF, whatever the
+  tickSpacing): the snapshot always has ``tick_spacing = 1`` (also the state's ``tick_spacing``, the real spacing
+  only matters for minting); ``ticks(int24)`` returns (liquidityTotal uint256, liquidityDelta int128, prevTick,
+  nextTick, outerFeeGrowth0, outerFeeGrowth1);
+* the fee: ``globalState().lastFee`` is NOT necessarily the fee of the next swap. With the plugin's DYNAMIC_FEE
+  flag (pluginConfig bit 7) the plugin's ``beforeSwap`` returns an override fee (adaptive fee from the volatility
+  oracle) and ``fee()`` of the pool returns ``plugin.getCurrentFee()``; the applied fee is logged per swap by
+  ``SwapFee(address indexed sender, uint24 overrideFee, uint24 pluginFee)`` right BEFORE the ``Swap`` of the same
+  call (Integral v1.2). The state's ``fee`` is the fee the next swap pays: ``fee()`` at load, then the logged
+  ``overrideFee`` (``swap_fee_from_log``) and ``fee()`` re-reads.
+
+Checked on Robinhood Chain (block 100117724): pool 0x49ffa9b5 WETH/USDG of factory 0xf03875b5, plugin
+AlgebraUpgradeablePlugin (Sourcify), adaptive fee alphas 0 -> fee = baseFee 100; exact-input round trips simulated on
+chain (``eth_simulateV1``) equal ``v3.pool.quote_exact_input`` on a state of ``load_algebra_integral_pool`` to the wei
+(fixture ``tests/fixtures/algebra_integral_robinhood.json``).
+
+Not covered: a plugin fee > 0 (``swap_fee_from_log`` returns None: its effect on the step is not verified on chain,
+every logged swap of the pool had pluginFee 0; the book's model check then quarantines the pool), an override fee
+of 0 (the pool then charges ``lastFee``), ``swapWithPaymentInAdvance``, a plugin that changes amounts.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from v4quote.amm.v3.tick_bitmap import TickBitmapSnapshot, position
+from v4quote.amm.v3.tick_math import MAX_TICK, MIN_TICK
+from v4quote.math.bit_math import least_significant_bit, most_significant_bit
+from v4quote.math.uint import MAX_UINT256
+
+MAX_FEE = 1_000_000  # pips; Algebra rejects an override fee >= 1e6
+DYNAMIC_FEE_FLAG = 128  # Plugins.DYNAMIC_FEE (globalState().pluginConfig)
+_MIN_WORD, _MAX_WORD = MIN_TICK >> 8, MAX_TICK >> 8
+
+
+@dataclass(frozen=True)
+class AlgebraTickSnapshot(TickBitmapSnapshot):
+    """Initialised ticks of an Algebra Integral pool (``tick_spacing`` must be 1: uncompressed ticks).
+
+    ``next_initialized_tick_within_one_word`` returns the next initialised tick in any word (Algebra's linked-list
+    walk); beyond the last one MIN_TICK / MAX_TICK (not initialised, as v3's loop clamps). A word outside
+    ``word_range`` on the way raises ``InsufficientState`` (never a guess). A subclass: the native v3 kernel (word
+    steps) never gets a handle for it (``v4quote.amm.native`` checks the exact type), the Python loop serves it.
+    """
+
+    def __post_init__(self) -> None:
+        if self.tick_spacing != 1:
+            raise ValueError("AlgebraTickSnapshot holds uncompressed ticks: tick_spacing must be 1")
+
+    def next_initialized_tick_within_one_word(self, tick: int, lte: bool) -> tuple[int, bool]:
+        if lte:
+            wp, bp = position(tick)
+            masked = self.word(wp) & ((1 << (bp + 1)) - 1)
+            while not masked:
+                wp -= 1
+                if wp < _MIN_WORD:
+                    return MIN_TICK, False
+                masked = self.word(wp)
+            return (wp << 8) + most_significant_bit(masked), True
+        t = tick + 1
+        wp, bp = position(t)
+        masked = self.word(wp) & (~((1 << bp) - 1) & MAX_UINT256)
+        while not masked:
+            wp += 1
+            if wp > _MAX_WORD:
+                return MAX_TICK, False
+            masked = self.word(wp)
+        return (wp << 8) + least_significant_bit(masked), True
+
+
+def swap_fee_from_log(override_fee: int, plugin_fee: int) -> int | None:
+    """Fee (pips) the swap step charged, from ``SwapFee(sender, overrideFee, pluginFee)``; None when core cannot
+    apply it: overrideFee 0 (the pool fell back to ``lastFee``, not in this log), >= 1e6 (no fee), pluginFee != 0
+    (not modelled)."""
+    if plugin_fee != 0 or not 0 < override_fee < MAX_FEE:
+        return None
+    return override_fee

v4quote/amm/erc4626.py

@@ -0,0 +1,173 @@
+"""ERC-4626 tokenized vault as a two-token "pool" (asset <-> shares), exact integer math of OpenZeppelin v5 ``ERC4626``.
+
+Model (OpenZeppelin Contracts v5.0, ``token/ERC20/extensions/ERC4626.sol``), with ``A = totalAssets()``,
+``S = totalSupply()`` and ``o = _decimalsOffset()``::
+
+    previewDeposit(a) = convertToShares(a, Floor) = mulDiv(a, S + 10**o, A + 1, Floor)
+    previewRedeem(s)  = convertToAssets(s, Floor) = mulDiv(s, A + 1, S + 10**o, Floor)
+    previewMint(s)    = mulDiv(s, A + 1, S + 10**o, Ceil)
+    previewWithdraw(a)= mulDiv(a, S + 10**o, A + 1, Ceil)
+
+``deposit(a)`` pulls ``a`` of the asset and mints ``previewDeposit(a)`` shares; ``redeem(s)`` burns ``s`` shares and pays
+``previewRedeem(s)`` of the asset. No fee. A vault that overrides the conversion (fees, other rounding, a non-default
+``totalAssets`` that is not the asset balance) is NOT this model: ``v4quote.chain.loaders.load_erc4626`` checks
+``previewDeposit`` / ``previewRedeem`` on chain against these formulas at load time and refuses a vault that differs.
+
+Gnosis sDAI (``SavingsXDai`` 0xaf20...3701): OZ v5 ERC4626 over WXDAI,
+``totalAssets = WXDAI.balanceOf(vault)``, ``o = 0``, not a proxy; the formulas matched ``previewDeposit`` /
+``previewRedeem`` 125/125 times on 25 historical blocks. The price moves only through direct asset transfers into the
+vault (``BridgeInterestReceiver.claim()``, every block since 2026-09-28).
+
+Pool view for ``v4quote.routing``: tokens ``(asset, vault)`` (the vault address IS the share token);
+coin index 0 -> 1 = ``deposit`` (asset in, shares out), 1 -> 0 = ``redeem`` (shares in, asset out).
+
+Reverts (``MathRevert``): a result above 2**256 - 1 (OZ v5.0 ``Math.mulDiv``: ``MathOverflowedMulDiv``), a mint that
+would overflow ``totalSupply`` or an asset balance overflow (checked arithmetic), a redeem of more shares than exist
+(``ERC4626ExceededMaxRedeem``: ``maxRedeem(owner) = balanceOf(owner) <= totalSupply``). ``maxDeposit`` is OZ's default
+(``type(uint256).max``); a vault with another ``maxDeposit`` is outside the model (the loader checks it).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+from v4quote.errors import MathRevert
+from v4quote.math.uint import MAX_UINT256
+
+MAX_DECIMALS_OFFSET = 18  # OZ allows uint8, 10**o overflows uint256 for o >= 78; real vaults use 0 .. a few
+ERR_MULDIV = "MathOverflowedMulDiv"
+ERR_MAX_REDEEM = "ERC4626ExceededMaxRedeem"
+ERR_SUPPLY_OVERFLOW = "panic: arithmetic overflow (totalSupply)"
+ERR_ASSETS_OVERFLOW = "panic: arithmetic overflow (asset balance)"
+
+
+@dataclass(frozen=True)
+class ERC4626VaultState:
+    """Snapshot of an OZ v5 ERC-4626 vault: ``address`` is the vault (= share token), ``asset`` the underlying.
+
+    Not ``slots``: the native backend caches its handle by a weak reference to the (frozen) state object."""
+
+    address: str
+    asset: str
+    total_assets: int
+    total_supply: int
+    decimals_offset: int = 0
+    block_number: int | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("total_assets", "total_supply"):
+            v = getattr(self, name)
+            if type(v) is not int or not 0 <= v <= MAX_UINT256:
+                raise ValueError(f"{name} must be an int in [0, 2**256)")
+        if type(self.decimals_offset) is not int or not 0 <= self.decimals_offset <= MAX_DECIMALS_OFFSET:
+            raise ValueError(f"decimals_offset must be an int in 0..{MAX_DECIMALS_OFFSET}")
+        if self.address.lower() == self.asset.lower():
+            raise ValueError("vault and asset must differ")
+
+    @property
+    def coins(self) -> tuple[str, str]:
+        """``(asset, vault)``: index 0 -> 1 is deposit, 1 -> 0 is redeem."""
+        return (self.asset, self.address)
+
+    @property
+    def virtual_shares(self) -> int:
+        return 10 ** self.decimals_offset
+
+
+def _mul_div(x: int, y: int, d: int, ceil: bool) -> int:
+    q, r = divmod(x * y, d)
+    if ceil and r:
+        q += 1
+    if q > MAX_UINT256:
+        raise MathRevert(ERR_MULDIV)
+    return q
+
+
+def convert_to_shares(st: ERC4626VaultState, assets: int, *, ceil: bool = False) -> int:
+    return _mul_div(assets, st.total_supply + st.virtual_shares, st.total_assets + 1, ceil)
+
+
+def convert_to_assets(st: ERC4626VaultState, shares: int, *, ceil: bool = False) -> int:
+    return _mul_div(shares, st.total_assets + 1, st.total_supply + st.virtual_shares, ceil)
+
+
+def preview_deposit(st: ERC4626VaultState, assets: int) -> int:
+    """Shares minted by ``deposit(assets)`` (floor)."""
+    _check_amount(assets)
+    return convert_to_shares(st, assets)
+
+
+def preview_redeem(st: ERC4626VaultState, shares: int) -> int:
+    """Assets paid by ``redeem(shares)`` (floor)."""
+    _check_amount(shares)
+    return convert_to_assets(st, shares)
+
+
+def preview_mint(st: ERC4626VaultState, shares: int) -> int:
+    """Assets pulled by ``mint(shares)`` (ceil)."""
+    _check_amount(shares)
+    return convert_to_assets(st, shares, ceil=True)
+
+
+def preview_withdraw(st: ERC4626VaultState, assets: int) -> int:
+    """Shares burnt by ``withdraw(assets)`` (ceil)."""
+    _check_amount(assets)
+    return convert_to_shares(st, assets, ceil=True)
+
+
+def _check_amount(x: int) -> None:
+    if type(x) is not int or not 0 <= x <= MAX_UINT256:
+        raise ValueError("amount must be an int in [0, 2**256)")
+
+
+def deposit_out(st: ERC4626VaultState, assets: int) -> int:
+    """``deposit(assets)`` as executed: the shares minted, with the reverts of the transfer-in and the mint."""
+    shares = preview_deposit(st, assets)
+    if st.total_assets + assets > MAX_UINT256:
+        raise MathRevert(ERR_ASSETS_OVERFLOW)
+    if st.total_supply + shares > MAX_UINT256:
+        raise MathRevert(ERR_SUPPLY_OVERFLOW)
+    return shares
+
+
+def redeem_out(st: ERC4626VaultState, shares: int) -> int:
+    """``redeem(shares)`` as executed by an owner holding ``shares``: the assets paid (``shares <= totalSupply``)."""
+    _check_amount(shares)
+    if shares > st.total_supply:
+        raise MathRevert(ERR_MAX_REDEEM)
+    return convert_to_assets(st, shares)  # <= A whenever shares <= S (floor of s (A+1) / (S + 10**o))
+
+
+def deposit(st: ERC4626VaultState, assets: int) -> tuple[int, ERC4626VaultState]:
+    """Shares and the post-state (A + assets, S + shares)."""
+    shares = deposit_out(st, assets)
+    return shares, replace(st, total_assets=st.total_assets + assets, total_supply=st.total_supply + shares)
+
+
+def redeem(st: ERC4626VaultState, shares: int) -> tuple[int, ERC4626VaultState]:
+    """Assets and the post-state (A - assets, S - shares)."""
+    assets = redeem_out(st, shares)
+    return assets, replace(st, total_assets=st.total_assets - assets, total_supply=st.total_supply - shares)
+
+
+def quote(st: ERC4626VaultState, i: int, j: int, amount: int) -> int:
+    """Exact-input quote in pool-coin terms: ``(0, 1)`` = deposit, ``(1, 0)`` = redeem."""
+    if (i, j) == (0, 1):
+        return deposit_out(st, amount)
+    if (i, j) == (1, 0):
+        return redeem_out(st, amount)
+    raise ValueError(f"bad coin indices ({i}, {j}) for an ERC-4626 vault (0 = asset, 1 = shares)")
+
+
+def apply_flows(st: ERC4626VaultState, d_assets: int, d_supply: int, block_number: int | None = None) -> ERC4626VaultState:
+    """The state after net asset-balance / supply changes (e.g. summed from simulated ``Transfer`` logs: asset
+    transfers to / from the vault, share mints / burns). Raises ValueError when a result leaves [0, 2**256)."""
+    return replace(st, total_assets=st.total_assets + d_assets, total_supply=st.total_supply + d_supply,
+                   block_number=st.block_number if block_number is None else block_number)
+
+
+__all__ = [
+    "ERC4626VaultState", "ERR_ASSETS_OVERFLOW", "ERR_MAX_REDEEM", "ERR_MULDIV", "ERR_SUPPLY_OVERFLOW",
+    "MAX_DECIMALS_OFFSET", "apply_flows", "convert_to_assets", "convert_to_shares", "deposit", "deposit_out",
+    "preview_deposit", "preview_mint", "preview_redeem", "preview_withdraw", "quote", "redeem", "redeem_out",
+]

v4quote/amm/liquidity_book/__init__.py

@@ -0,0 +1,40 @@
+"""LFJ Liquidity Book v2.1 / v2.2 (and exact forks such as Pharaoh DLMM)."""
+
+from v4quote.amm.liquidity_book.math import FeeParameters, get_price_from_id
+from v4quote.amm.liquidity_book.hooks_allowlist import (
+    DEFAULT_HOOKS_ALLOWLIST,
+    HookApproval,
+    HooksAllowlist,
+    REPLAY_PENDING,
+    validate_allowlist,
+)
+from v4quote.amm.liquidity_book.pair import (
+    ALLOWED_HOOK_FLAGS,
+    BinSwap,
+    LBPairState,
+    execution_permitted,
+    LBSwapResult,
+    get_amounts,
+    get_swap_in,
+    get_swap_out,
+    swap,
+)
+
+__all__ = [
+    "ALLOWED_HOOK_FLAGS",
+    "DEFAULT_HOOKS_ALLOWLIST",
+    "BinSwap",
+    "HookApproval",
+    "HooksAllowlist",
+    "REPLAY_PENDING",
+    "execution_permitted",
+    "validate_allowlist",
+    "FeeParameters",
+    "LBPairState",
+    "LBSwapResult",
+    "get_amounts",
+    "get_price_from_id",
+    "get_swap_in",
+    "get_swap_out",
+    "swap",
+]

v4quote/amm/liquidity_book/hooks_allowlist.py

@@ -0,0 +1,237 @@
+"""Allowlist of LB v2.2 hooks contracts whose pools v4quote may simulate.
+
+An entry pins the hook by (chain, address), binds it to the one pair it was
+verified with (``pair``), and pins the on-chain codehash and, for proxies, the
+implementation address and implementation codehash. Any change on chain (upgrade,
+beacon switch, redeploy, the hook reused by another pair) makes the pool
+``UnsupportedPool`` again. For LFJ rewarder clones the pool is also rejected while an
+extra rewarder is set or the hook is unlinked (``pair.LBPairState.unsupported_reasons``).
+
+``execution_allowed`` is a policy flag for callers that send transactions: simulating a pool is
+permitted by being in the list, sending transactions through it is not, unless this flag is True. All entries
+are False.
+
+Evidence: a replay of historical ``swap()`` calls of each pair (hooks executed) against the model,
+``tests/onchain/test_lb_swap_replay.py``, plus the codehash / pair links re-checked by
+``tests/onchain/test_address_links.py``. Entries whose on-chain swap replay is still pending are listed in
+``REPLAY_PENDING``: their pools are simulated, but results through them should be treated as unverified.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal, Mapping, Optional
+
+Verification = Literal["source-verified", "empirical"]
+ProxyKind = Literal["lfj-immutable-clone", "eip1967-beacon", "eip1967"]
+
+_HASH_RE = re.compile(r"^0x[0-9a-fA-F]{64}$")
+_ADDR_RE = re.compile(r"^0x[0-9a-fA-F]{40}$")
+_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+KNOWN_CHAINS = ("monad", "avalanche")
+EVIDENCE = "tests/onchain/test_lb_swap_replay.py"  # where the entries are verified against the chain
+
+
+@dataclass(frozen=True)
+class HookApproval:
+    """Allowlist entry for one hooks contract (hex strings compared case-insensitively).
+
+    Validation (raises ValueError): ``pair`` is a mandatory address (the LBPair whose
+    ``getLBHooksParameters()`` points at this hook); codehashes are
+    32-byte hex; ``verification`` is "source-verified" or "empirical"; for a proxy
+    (``proxy_kind`` set) both ``implementation`` and ``implementation_codehash`` are
+    mandatory, for a non-proxy both must be absent.
+    """
+
+    codehash: str
+    implementation: Optional[str] = None
+    implementation_codehash: Optional[str] = None
+    proxy_kind: Optional[ProxyKind] = None
+    verification: Verification = "empirical"
+    execution_allowed: bool = False
+    pinned_block: Optional[int] = None
+    added_date: Optional[str] = None
+    evidence: Optional[str] = None
+    pair: Optional[str] = None  # mandatory (validated below); last only because the fields above are positional
+
+    def __post_init__(self) -> None:
+        if not (isinstance(self.pair, str) and _ADDR_RE.match(self.pair)):
+            raise ValueError(f"allowlist entry requires the pair address, got {self.pair!r}")
+        if not _HASH_RE.match(self.codehash or ""):
+            raise ValueError(f"invalid codehash {self.codehash!r}")
+        if self.verification not in ("source-verified", "empirical"):
+            raise ValueError(f"invalid verification {self.verification!r}")
+        if not isinstance(self.execution_allowed, bool):
+            raise ValueError("execution_allowed must be bool")
+        if self.proxy_kind is not None:
+            if self.proxy_kind not in ("lfj-immutable-clone", "eip1967-beacon", "eip1967"):
+                raise ValueError(f"invalid proxy_kind {self.proxy_kind!r}")
+            if not (self.implementation and _ADDR_RE.match(self.implementation)):
+                raise ValueError("proxy entry requires a valid implementation address")
+            if not (self.implementation_codehash and _HASH_RE.match(self.implementation_codehash)):
+                raise ValueError("proxy entry requires implementation_codehash")
+        elif self.implementation is not None or self.implementation_codehash is not None:
+            raise ValueError("implementation fields set but proxy_kind is None")
+        if self.added_date is not None and not _DATE_RE.match(self.added_date):
+            raise ValueError(f"invalid added_date {self.added_date!r}")
+
+
+HooksAllowlist = Mapping[tuple[str, str], HookApproval]  # key: (chain, hook address)
+
+
+def validate_allowlist(allowlist: HooksAllowlist) -> None:
+    pairs: set[tuple[str, str]] = set()
+    for (chain, hook), approval in allowlist.items():
+        if chain not in KNOWN_CHAINS:
+            raise ValueError(f"unknown chain {chain!r}")
+        if not _ADDR_RE.match(hook):
+            raise ValueError(f"invalid hook address {hook!r}")
+        if not isinstance(approval, HookApproval):
+            raise ValueError("allowlist values must be HookApproval")
+        key = (chain, str(approval.pair).lower())
+        if key in pairs:
+            raise ValueError(f"pair {approval.pair} on {chain} has more than one allowlisted hook")
+        pairs.add(key)
+
+
+# Codehashes re-read on-chain when the entries were added (2026-09-21):
+# Avalanche block 95854756/95854758, Monad blocks 106830370/106830372.
+# AUSD pair hooks added 2026-09-23 at Avalanche block 95951189.
+# USDt/USDC and sAVAX/WAVAX pair hooks added 2026-09-29 at Avalanche block 96389826.
+# ``pair``: the pair each hook was verified and replayed with (tests/fixtures/pools.yaml / route_pools.yaml);
+# re-checked on chain by tests/onchain/test_address_links.py::test_default_hooks_allowlist_matches_chain
+# (pair.getLBHooksParameters() points at the hook).
+_LFJ_HOOK_IMPL = "0x2235CDFe1172aA5eD7cEC6E1713f93eeaBFbc295"
+
+DEFAULT_HOOKS_ALLOWLIST: HooksAllowlist = {
+    # LFJ WAVAX/USDC bs10 (0x864d4e5e...16ea). Implementation LBHooksSimpleRewarder verified on routescan.
+    ("avalanche", "0xBA83987a28b1C7514576e15D58c134b8F0E00Fa9"): HookApproval(
+        pair="0x864d4e5Ee7318e97483DB7EB0912E09F161516EA",
+        codehash="0x419f4e8dcd4dd32a0220cb95d64b152d3331fc5a8fa7b3d30ac6d7ac256a17b7",
+        implementation=_LFJ_HOOK_IMPL,
+        implementation_codehash="0x0e088a5b6645a261bcdcb2efad8789e25f5b423a129dbd4188869a8361e73ba1",
+        proxy_kind="lfj-immutable-clone",
+        verification="source-verified",
+        execution_allowed=False,
+        pinned_block=95854756,
+        added_date="2026-09-21",
+        evidence=EVIDENCE,
+    ),
+    # LFJ WMON/USDC bs10 (0x5e60bc3f...fe22). Monad implementation bytecode differs from the verified
+    # Avalanche one -> empirical (swap replay) only.
+    ("monad", "0xd0B3Ff65058609743877637e689B30abdb97364a"): HookApproval(
+        pair="0x5E60BC3F7a7303BC4dfE4dc2220bdC90bc04fE22",
+        codehash="0x908dd8930d84a8f5bae05ee104f1dbae9c34d3f08640c27b2cb1cc279b875769",
+        implementation=_LFJ_HOOK_IMPL,
+        implementation_codehash="0xef6f52a0e9e2cf26dd81f5456c6071f58dafbb06017c411f9f02b7a93a452ea1",
+        proxy_kind="lfj-immutable-clone",
+        verification="empirical",
+        execution_allowed=False,
+        pinned_block=106830370,
+        added_date="2026-09-21",
+        evidence=EVIDENCE,
+    ),
+    # LFJ WMON/USDC bs5 (0x5AFD3EC8...7620).
+    ("monad", "0x8b0D325fEa6F13BB6D62F825137ABd4cF6457367"): HookApproval(
+        pair="0x5AFD3EC861f6104af26e8755aBcc1f876de77620",
+        codehash="0xcd9425f235e9de88175cbd19c472d9a3c5ff6d73ed0c4db2169fa77adda3a180",
+        implementation=_LFJ_HOOK_IMPL,
+        implementation_codehash="0xef6f52a0e9e2cf26dd81f5456c6071f58dafbb06017c411f9f02b7a93a452ea1",
+        proxy_kind="lfj-immutable-clone",
+        verification="empirical",
+        execution_allowed=False,
+        pinned_block=106830372,
+        added_date="2026-09-21",
+        evidence=EVIDENCE,
+    ),
+    # Pharaoh DLMM WAVAX/USDC bs5 (0x8aC5707f...3379). BeaconProxy; beacon 0xd28467eD...548C.
+    ("avalanche", "0x138ce0008F7feBdcFfdf27C0aD156584eCa7D5B6"): HookApproval(
+        pair="0x8aC5707f8D4BDe1d771d34c7AfD81c3922b73379",
+        codehash="0xa57cb656b9262cee1544dfe70bbd760543cd40bff89a2a1c06f29f888d1ed741",
+        implementation="0xC997575204290FF7106aB8b2BCFa7e7dEA43D783",
+        implementation_codehash="0x67524de60f5a73e3f9ec5d78fea749d2133b323ef1fa340bf151866b0258fb51",
+        proxy_kind="eip1967-beacon",
+        verification="empirical",
+        execution_allowed=False,
+        pinned_block=95854758,
+        added_date="2026-09-21",
+        evidence=EVIDENCE,
+    ),
+    # LFJ AUSD/USDC bs1 (0x8573f981...9cee). Same implementation codehash as the WAVAX/USDC hook above;
+    # clone bytecode identical to it except the embedded pair address. Allowlisted for simulation 2026-09-27.
+    ("avalanche", "0xE104964852BE626EE27762712E4DE521066859C9"): HookApproval(
+        pair="0x8573F98175D816d520248B5fACF40D309B1c9ceE",
+        codehash="0xdaf577bdcbb29359151d7d9f5d0f0e3bf7bf2aa7cc5a7ff09aea9efe49c29dbf",
+        implementation=_LFJ_HOOK_IMPL,
+        implementation_codehash="0x0e088a5b6645a261bcdcb2efad8789e25f5b423a129dbd4188869a8361e73ba1",
+        proxy_kind="lfj-immutable-clone",
+        verification="source-verified",
+        execution_allowed=False,
+        pinned_block=95951189,
+        added_date="2026-09-23",
+        evidence=EVIDENCE,
+    ),
+    # LFJ AUSD/USDt bs1 (0xcec37728...631a). Same as above. Allowlisted for simulation 2026-09-27.
+    ("avalanche", "0x72ed0b6AcB5c585873b3F644F99FC167c7601256"): HookApproval(
+        pair="0xcEC377285AbF370FDf872625D2742252656d631a",
+        codehash="0x1131a0dabd90112bc1cbbd9cdc68110d54374178e8572eaa2dde5fdd27f79006",
+        implementation=_LFJ_HOOK_IMPL,
+        implementation_codehash="0x0e088a5b6645a261bcdcb2efad8789e25f5b423a129dbd4188869a8361e73ba1",
+        proxy_kind="lfj-immutable-clone",
+        verification="source-verified",
+        execution_allowed=False,
+        pinned_block=95951189,
+        added_date="2026-09-23",
+        evidence=EVIDENCE,
+    ),
+    # LFJ USDt/USDC bs1 (0x2823299a...ef5d). Clone of the same verified LBHooksSimpleRewarder as 0xBA83...0Fa9;
+    # clone bytecode identical except the embedded pair address. Approved for simulation 2026-09-29.
+    ("avalanche", "0x90014c5E78Bd8a3E2bbBaA8e5a0Aee2C1D2131CD"): HookApproval(
+        pair="0x2823299af89285fF1a1abF58DB37cE57006FEf5D",
+        codehash="0x5fd2e48584442dd82aaa6ef7be5ab8a9fa699c9c456a560545800042892b483a",
+        implementation=_LFJ_HOOK_IMPL,
+        implementation_codehash="0x0e088a5b6645a261bcdcb2efad8789e25f5b423a129dbd4188869a8361e73ba1",
+        proxy_kind="lfj-immutable-clone",
+        verification="source-verified",
+        execution_allowed=False,
+        pinned_block=96389826,
+        added_date="2026-09-29",
+        evidence=EVIDENCE,
+    ),
+    # LFJ sAVAX/WAVAX bs5 (0x883ea72c...c5c0). Same as above. Approved for simulation 2026-09-29.
+    ("avalanche", "0xdAe382F3542dd8a6b42F0F1F71B3f7227a4a3622"): HookApproval(
+        pair="0x883eA72c2A46F7AcB3820855344C43666c6cc5c0",
+        codehash="0x68d59a1ef8d61856d4a2c036b4603529a848af31cc7efabdae1d2c7fba8dd928",
+        implementation=_LFJ_HOOK_IMPL,
+        implementation_codehash="0x0e088a5b6645a261bcdcb2efad8789e25f5b423a129dbd4188869a8361e73ba1",
+        proxy_kind="lfj-immutable-clone",
+        verification="source-verified",
+        execution_allowed=False,
+        pinned_block=96389826,
+        added_date="2026-09-29",
+        evidence=EVIDENCE,
+    ),
+    # Pharaoh DLMM USDt/USDC bs1 (0x16888ee5...255c). BeaconProxy of the same beacon 0xd28467eD...548C and the same
+    # DLMMRewarder implementation as 0x138c...D5B6 (identical proxy codehash); pair = same unverified implementation
+    # 0xF41253C1...d710 as 0x8aC5...3379. Rewards were active when added (2026-09-29).
+    ("avalanche", "0x32E68C4b8Edc6d1F16E99EbA826B292FDC18daDC"): HookApproval(
+        pair="0x16888EE58E706C253b821EAA637ae9b2cFeA255C",
+        codehash="0xa57cb656b9262cee1544dfe70bbd760543cd40bff89a2a1c06f29f888d1ed741",
+        implementation="0xC997575204290FF7106aB8b2BCFa7e7dEA43D783",
+        implementation_codehash="0x67524de60f5a73e3f9ec5d78fea749d2133b323ef1fa340bf151866b0258fb51",
+        proxy_kind="eip1967-beacon",
+        verification="empirical",
+        execution_allowed=False,
+        pinned_block=96389826,
+        added_date="2026-09-29",
+        evidence=EVIDENCE,
+    ),
+}
+validate_allowlist(DEFAULT_HOOKS_ALLOWLIST)
+
+# Pairs (chain, pair address lower case) whose hooks were allowlisted WITHOUT an on-chain swap replay of their own
+# (criterion: >= 24 replayed swaps per pair, 0 wei mismatches). Consumers should treat results through them as
+# unverified. Remove a pair here once its replay passed.
+# 2026-09-29: the replay of all three 2026-09-29 pairs passed (24 of 24 swaps each, 0 mismatches).
+REPLAY_PENDING: frozenset[tuple[str, str]] = frozenset()