ipor-fusion 4.0.0.dev215__tar.gz → 4.0.0.dev222__tar.gz

{ipor_fusion-4.0.0.dev215 → ipor_fusion-4.0.0.dev222}/AGENTS.md

@@ -447,8 +447,11 @@ decoder sets a `type_label` (enum name or a protocol tag like `EULER_VAULT`);
 a label-less decode renders as a generic placeholder in every consumer.
 Plain-address decoding only when the fuses check `isSubstrateAsAssetGranted`;
 typed layouts get their own decoder with the enum labels carried over. A
-market with no substrate semantics stays unregistered ON PURPOSE and renders
-as a loud `no_decoder(NAME)` (e.g. LITE_PSM=48). Never default to
+market with no substrate semantics, or whose layout cannot be verified, stays
+unregistered ON PURPOSE with its reason in `_UNREGISTERED_ON_PURPOSE` and
+renders as a loud `no_decoder(NAME)` (e.g. LITE_PSM=48);
+`test_every_market_has_a_decoder_or_a_reason` fails for a member that has
+neither. Never default to
 plain-address or guess a layout: a wrong decoder renders plausible-looking
 garbage addresses that consumers act on, so it is worse than none (Aave V4,
 id 49, is the documented case in `substrates.py`). `decode_substrate` handles

{ipor_fusion-4.0.0.dev215 → ipor_fusion-4.0.0.dev222}/MIGRATION_4.md

@@ -990,6 +990,13 @@ and `log_index` was passed through as given (a hex string from a raw log); the e
 These apply to every caller, type-checked or not. Changes described in full above
 are listed with a link.
 
+- **More markets decode their substrates.** VELODROME_SUPERCHAIN (31, Gauge /
+  Pool), AGUA_GLOBAL_CARRY (51, VAULT / ASSET), TERM_FINANCE (52, SERVICER address
+  or COLLATERAL_TOKEN pair key), META_MORPHO_0001, MERKL and
+  ASSETS_BALANCE_VALIDATION (plain addresses) were `no_decoder(NAME)` in 3.x and
+  now decode per their Solidity substrate libraries and grant checks. The markets
+  still without a decoder are listed with their reason.
+
 - **`CcipLane.open` refuses a spoke it cannot reach.** The executor's
   `ccipRoute(spoke)` must be registered and point at the dispatcher at the
   executor's own address; otherwise `open` (and `open_lane` / `open_lanes`)

{ipor_fusion-4.0.0.dev215 → ipor_fusion-4.0.0.dev222}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev215
+Version: 4.0.0.dev222
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py

{ipor_fusion-4.0.0.dev215 → ipor_fusion-4.0.0.dev222}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev215"
+version = "4.0.0.dev222"
 description = "The IPOR Fusion SDK for Python"
 authors = [
     { name = "Adam Mydlarz", email = "amydlarz@gmail.com" },

{ipor_fusion-4.0.0.dev215 → ipor_fusion-4.0.0.dev222}/src/ipor_fusion/substrates.py

@@ -77,6 +77,45 @@ def _decode_plain_address(hex_str: str) -> SubstrateInfo:
     return SubstrateInfo(address=_address(hex_str[24:]))
 
 
+def _noncanonical(hex_str: str) -> SubstrateInfo:
+    return SubstrateInfo(
+        raw_hex=f"0x{hex_str}", type_label="noncanonical", is_error=True
+    )
+
+
+def _decode_strict_plain_address(hex_str: str) -> SubstrateInfo:
+    """A substrate-as-asset address: ``isSubstrateAsAssetGranted`` grants only
+    the zero-padded word, so dirty upper bits are no grant of the low address."""
+    if hex_str[:24] != "0" * 24:
+        return _noncanonical(hex_str)
+    return _decode_plain_address(hex_str)
+
+
+def _decode_strict_type_lshift160(hex_str: str, types: dict[int, str]) -> SubstrateInfo:
+    """type<<160 | address where Solidity converts the whole ``word >> 160`` to
+    the enum: any other upper bits, or a value outside it, reverts there."""
+    if hex_str[:22] != "0" * 22 or int(hex_str[22:24], 16) not in types:
+        return _noncanonical(hex_str)
+    return _decode_type_lshift160(hex_str, types)
+
+
+def _decode_term_finance(hex_str: str) -> SubstrateInfo:
+    """TermFinanceSubstrateLib.sol: a SERVICER is the TermRepoServicer address
+    in the plain zero-padded form (the whole upper 96 bits zero, as the fuses'
+    strict ``isServicerSubstrate`` requires); a COLLATERAL_TOKEN is type byte
+    0x01 over ``keccak256(abi.encode(servicer, collateralToken))`` truncated to
+    248 bits, a pair key and not an address."""
+    if hex_str[:24] == "0" * 24:
+        return SubstrateInfo(address=_address(hex_str[24:]), type_label="SERVICER")
+    if hex_str[:2] == "01":
+        return SubstrateInfo(raw_hex=f"0x{hex_str}", type_label="COLLATERAL_TOKEN")
+    return SubstrateInfo(
+        raw_hex=f"0x{hex_str}",
+        type_label=f"type={int(hex_str[:2], 16)}",
+        is_error=True,
+    )
+
+
 def _decode_morpho(hex_str: str) -> SubstrateInfo:
     """Raw bytes32 Morpho market ID — no structure."""
     return SubstrateInfo(raw_hex=f"0x{hex_str}", type_label="morpho_market_id")
@@ -441,6 +480,19 @@ _register_markets(
     ],
     _decode_plain_address,
 )
+# Substrate-as-asset markets registered from their grant checks, decoded
+# strictly (a word with dirty upper bits grants nothing):
+# META_MORPHO_0001 is deployed as Erc4626SupplyFuse (the MetaMorpho vault),
+# MERKL as MerklClaimWrapperFuse (the reward tokens it forwards) and
+# ASSETS_BALANCE_VALIDATION as PlasmaVaultBalanceAssetsValidationFuse.
+_register_markets(
+    [
+        200_001,
+        IporFusionMarkets.MERKL,
+        IporFusionMarkets.ASSETS_BALANCE_VALIDATION,
+    ],
+    _decode_strict_plain_address,
+)
 # Morpho markets — raw bytes32 market ids. MORPHO_FLASH_LOAN (19) is NOT one:
 # MorphoFlashLoanFuse gates the loan token via isSubstrateAsAssetGranted, and
 # every live market-19 substrate is the zero-padded address form (registry
@@ -478,6 +530,21 @@ _register_markets(
     [32],
     lambda h: _decode_type_lshift160(h, {0: "UNDEFINED", 1: "Gauge", 2: "Pool"}),
 )
+# Velodrome Superchain (VelodromeSuperchainLib.sol): the same type<<160 Gauge /
+# Pool layout, decoded strictly
+_register_markets(
+    [31],
+    lambda h: _decode_strict_type_lshift160(h, {0: "UNDEFINED", 1: "Gauge", 2: "Pool"}),
+)
+# Agua Global Carry (AguaSubstrateLib.sol): type<<160 | address
+_register_markets(
+    [51],
+    lambda h: _decode_strict_type_lshift160(
+        h, {0: "UNDEFINED", 1: "VAULT", 2: "ASSET"}
+    ),
+)
+# Term Finance (TermFinanceSubstrateLib.sol): SERVICER / COLLATERAL_TOKEN
+_register_markets([52], _decode_term_finance)
 # Aave V4 (id 49 per IporFusionMarkets.sol) — typed Reserve substrates per
 # AaveV4SubstrateLib.sol; an earlier draft enum (Asset/Spoke, address in the
 # low bytes) shipped here and decoded live substrates to garbage addresses
@@ -514,11 +581,6 @@ _register_markets([40], _decode_async_action)
 # / four uint248 guards).
 _register_markets([50], _decode_external_state)
 # Uniswap V4 (id 53 per IporFusionMarkets.sol): PoolId or pool currency.
-# TERM_FINANCE (52) stays unregistered on purpose — its substrate library is
-# not mirrored here yet, and no_decoder(TERM_FINANCE) is the honest answer.
-# SPOL_UNSTAKE (424243) likewise: SPOLUnstakeFuse is not in the public
-# contracts repo, so its substrate grant check cannot be verified — the market
-# doc says the sPOLController address, but no_decoder until the fuse is mirrored
 _register_markets([53], _decode_uniswap_v4)
 # Crosschain (id 54 on the contracts' crosschain branch): EXECUTOR /
 # REMOTE_VAULT typed substrates per CrosschainSubstrateLib.sol. The mainnet
@@ -538,6 +600,26 @@ _register_markets(
 _register_markets([55], _decode_hypercore)
 
 
+# Markets left without a decoder on purpose, each with the reason; they decode
+# as no_decoder(NAME). tests/test_substrates.py holds every IporFusionMarkets
+# member to a decoder or an entry here, so a new market cannot go unnoticed.
+_UNREGISTERED_ON_PURPOSE: dict[MarketId, str] = {
+    IporFusionMarkets.LITE_PSM: "IporFusionMarkets.sol declares no substrates "
+    "(a ZeroBalanceFuse market)",
+    IporFusionMarkets.SPOL_UNSTAKE: "SPOLUnstakeFuse is not in the public contracts "
+    "repository, so its grant check cannot be verified",
+    **{
+        MarketId(mid): "no deployment or layout verified in the address registry; "
+        "META_MORPHO_0001 is an Erc4626SupplyFuse, but a later one is not assumed"
+        for mid in range(200_002, 200_011)
+    },
+    IporFusionMarkets.EXCHANGE_RATE_VALIDATOR: "packed hook and validator words "
+    "(ExchangeRateValidatorConfigLib), not addresses; not mirrored here yet",
+    IporFusionMarkets.ZERO_BALANCE_MARKET: "a capability market: no fuse defines a "
+    "substrate layout for it",
+}
+
+
 def _build_market_lookup() -> dict[int, str]:
     lookup: dict[int, str] = {}
     for name in dir(IporFusionMarkets):

{ipor_fusion-4.0.0.dev215 → ipor_fusion-4.0.0.dev222}/tests/test_substrates.py

@@ -8,7 +8,10 @@ mainnet by tx 0x9321732ec456e44a46d6f10ba9eee956333c13f5a45fec3bd242218ce8c3ce93
 from __future__ import annotations
 
 import pytest
+from eth_abi import encode
+from eth_utils import keccak
 
+from ipor_fusion import substrates
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.substrates import SubstrateInfo, decode_substrate, market_name
 
@@ -269,16 +272,115 @@ def test_market_ids_52_and_53_follow_ipor_fusion_markets_sol():
     assert IporFusionMarkets.UNISWAP_V4 == 53
     assert market_name(52) == "TERM_FINANCE"
     assert market_name(53) == "UNISWAP_V4"
-    # no substrate library mirrored for Term Finance yet: loud, never guessed
-    info = decode_substrate("0x" + "11" * 32, market_id=52)
+
+
+SERVICER = "0x" + "5e" * 20
+
+
+def test_term_finance_servicer_is_the_plain_address():
+    info = decode_substrate("0x" + "00" * 12 + SERVICER[2:], market_id=52)
+    assert info == SubstrateInfo(address=SERVICER, type_label="SERVICER")
+
+
+def test_term_finance_collateral_pair_key_is_not_an_address():
+    # TermFinanceSubstrateLib.collateralPairKey: 0x01 << 248 | keccak(...)[low 248]
+    key = keccak(encode(["address", "address"], [SERVICER, USDE]))
+    raw = "0x01" + key.hex()[2:]
+    info = decode_substrate(raw, market_id=52)
+    assert info == SubstrateInfo(raw_hex=raw, type_label="COLLATERAL_TOKEN")
+
+
+def test_term_finance_unknown_word_is_an_error():
+    info = decode_substrate("0x02" + "11" * 31, market_id=52)
+    assert info.is_error
+    assert info.address is None
+    assert info.type_label == "type=2"
+
+
+@pytest.mark.parametrize(("type_byte", "label"), [(1, "Gauge"), (2, "Pool")])
+def test_velodrome_superchain_shares_the_slipstream_layout(type_byte, label):
+    raw = "0x" + "00" * 11 + f"{type_byte:02x}" + BOLD[2:]
+    for market_id in (31, 32):
+        info = decode_substrate(raw, market_id=market_id)
+        assert info == SubstrateInfo(address=BOLD, type_label=label)
+
+
+@pytest.mark.parametrize(("type_byte", "label"), [(1, "VAULT"), (2, "ASSET")])
+def test_agua_typed_substrates(type_byte, label):
+    raw = "0x" + "00" * 11 + f"{type_byte:02x}" + USDE[2:]
+    info = decode_substrate(raw, market_id=51)
+    assert info == SubstrateInfo(address=USDE, type_label=label)
+
+
+@pytest.mark.parametrize(
+    "market_id",
+    [
+        IporFusionMarkets.MERKL,
+        IporFusionMarkets.ASSETS_BALANCE_VALIDATION,
+        IporFusionMarkets.META_MORPHO_0001,
+    ],
+)
+def test_substrate_as_asset_markets_decode_plain_addresses(market_id):
+    info = decode_substrate("0x" + "00" * 12 + USDE[2:], market_id=market_id)
+    assert info == SubstrateInfo(address=USDE)
+
+
+def test_term_finance_dirty_servicer_padding_is_an_error():
+    raw = "0x00" + "11" * 11 + SERVICER[2:]
+    info = decode_substrate(raw, market_id=52)
+    assert info.is_error
+    assert info.address is None
+
+
+@pytest.mark.parametrize("market_id", [31, 51])
+@pytest.mark.parametrize(
+    "raw",
+    [
+        # dirty bits above the type byte: Solidity converts the whole word >> 160
+        "0x01" + "00" * 10 + "01" + USDE[2:],
+        # out-of-range enum value: Solidity reverts on it
+        "0x" + "00" * 11 + "03" + USDE[2:],
+    ],
+)
+def test_strict_typed_markets_flag_noncanonical_words(market_id, raw):
+    info = decode_substrate(raw, market_id=market_id)
+    assert info == SubstrateInfo(raw_hex=raw, type_label="noncanonical", is_error=True)
+
+
+@pytest.mark.parametrize(
+    "market_id",
+    [
+        IporFusionMarkets.MERKL,
+        IporFusionMarkets.ASSETS_BALANCE_VALIDATION,
+        IporFusionMarkets.META_MORPHO_0001,
+    ],
+)
+def test_strict_plain_markets_flag_dirty_padding(market_id):
+    raw = "0x" + "00" * 11 + "01" + USDE[2:]
+    info = decode_substrate(raw, market_id=market_id)
+    assert info.is_error
     assert info.address is None
-    assert info.type_label == "no_decoder(TERM_FINANCE)"
 
 
-def test_market_without_decoder_is_labelled_not_guessed():
-    info = decode_substrate("0x" + "11" * 32, market_id=31)
+def test_every_market_has_a_decoder_or_a_reason():
+    members = {
+        getattr(IporFusionMarkets, name)
+        for name in dir(IporFusionMarkets)
+        if not name.startswith("_")
+        and isinstance(getattr(IporFusionMarkets, name), int)
+    }
+    registered = set(substrates._SUBSTRATE_DECODERS)
+    on_purpose = set(substrates._UNREGISTERED_ON_PURPOSE)
+    assert not registered & on_purpose
+    assert members - registered == on_purpose
+    assert all(reason for reason in substrates._UNREGISTERED_ON_PURPOSE.values())
+
+
+@pytest.mark.parametrize("market_id", sorted(substrates._UNREGISTERED_ON_PURPOSE))
+def test_a_market_without_a_decoder_is_labelled_not_guessed(market_id):
+    info = decode_substrate("0x" + "11" * 32, market_id=market_id)
     assert info.address is None
-    assert info.type_label == "no_decoder(VELODROME_SUPERCHAIN)"
+    assert info.type_label == f"no_decoder({market_name(market_id)})"
 
 
 def test_external_state_is_market_50():