ipor-fusion 4.0.0.dev49__tar.gz → 4.0.0.dev52__tar.gz

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/MIGRATION_4.md

@@ -4,7 +4,7 @@
 vault/oracle/token addresses and transaction hashes a nominal type
 (`typing.NewType`) across the public API, and checks the SDK, the examples and a
 typed client with pyright's `reportArgumentType`. Other fields keep their types
-(e.g. `VaultData.access_manager` is still `str`).
+(e.g. symbols, names and URLs stay `str`).
 
 The wrappers do not change values: `ChainId(1)` is `1` at runtime. The
 [behavior changes](#behavior-changes) below, however, apply to **every** caller,
@@ -15,7 +15,7 @@ type-checked or not. In particular, `fetch_market` and
 returns already carry their type and go back in unwrapped.
 
 All types are importable from `ipor_fusion` (and `ipor_fusion.types`);
-`ChecksumAddress`, `HexAddress` and `HexStr` come from `eth_typing`,
+`ChecksumAddress` and `HexAddress` come from `eth_typing`,
 `BlockIdentifier` from `web3.types`, and `USDC_TOKEN_INDEX` / `hip3_action_asset` from
 `ipor_fusion.fuses.hypercore`. The wrappers label values; they do not validate byte
 widths or address spelling.
@@ -29,9 +29,9 @@ widths or address spelling.
 | `RoleId` | a `Roles` member (accepted as is), or `RoleId(n)`; `Roles.resolve(name)` returns one |
 | `Decimals`, `Period`, `Amount`, ... | `Decimals(8)`, `Period(0)`, `Amount(n)` (unchanged) |
 | `ChecksumAddress` | `Web3.to_checksum_address(value)` |
-| `HexAddress` | any `ChecksumAddress`, or `HexAddress(HexStr("0x..."))` for a lowercase address |
+| `HexAddress` | any `ChecksumAddress`, or `parse_hex_address(value)` (20 bytes or hex in any spelling → lowercase `0x` form) |
 | `MorphoBlueMarketId` | `parse_morpho_market_id(value)`: 32 bytes or hex in any spelling, always `0x` + 64 lowercase digits |
-| `TxHash` | `TxHash(HexStr("0x..."))` |
+| `TxHash` | `parse_tx_hash(value)` (32 bytes or hex in any spelling) |
 | crosschain ids | `CommandId(b)`, `MessageId(b)`, `AssetId(b)`, `OperationId(b)`, `TransferId(b)`, `ReturnRequestId(b)`, `PositionSetHash(b)` (bytes32); `ProposalId(n)`, `DeploymentRequestId(n)`, `StargateAssetId(n)` (int) |
 | HyperCore ids | `HyperCoreTokenIndex(n)` (or `USDC_TOKEN_INDEX`), `HyperCoreAsset(n)` (or `hip3_action_asset(dex, index)`), `HyperCoreOrderId(n)`, `HyperCoreClientOrderId(n)`, `MarginTableId(n)`, `HyperCoreActionId(n)`, `PayloadHash(b)` |
 | external state | `ProposalHash(b)` |
@@ -59,11 +59,18 @@ and the `dependency_graph` helpers (`compute_update_reach`, `compute_update_grou
 `find_orphan_fuse_markets`, `find_markets_missing_erc20_dependency`).
 A custom `VaultState` implementation also annotates `asset` as `ChecksumAddress` and
 its `unpriceable_priced_tokens` items' `market_id` as `MarketId`
-(`UnpriceableToken`). `VaultData.asset`, `VaultValidation.vault` / `asset` are
-`ChecksumAddress`,
+(`UnpriceableToken`), and `price_oracle_addr` / `fuse_markets` keys as
+`ChecksumAddress`. `VaultData.asset`, `access_manager`, `price_oracle_addr`,
+`rewards_manager`, `withdraw_manager`, `fuses` and `instant_fuses` (and the
+`fuse_markets` keys), `FeeData.fee_manager` / `ipor_dao_fee_recipient`, and
+`VaultValidation.vault` / `asset` are `ChecksumAddress`; `VaultData.balance_fuses`
+is `list[BalanceFuse]` and `token_prices_usd` is keyed by `HexAddress` (lowercase);
+the Uniswap V3 / Ramses V2 position events' `version`, `sender` and `recipient` are
+`ChecksumAddress`;
 `VaultValidation.chain_id` is `ChainId`; `LendingMarketHealth.market_id` and
-`MiddlewarePricedToken.market_id` are `MarketId`; `Erc20Holding.address` and
-`SubstrateInfo.address` are `HexAddress` (still `""` when a substrate has no address).
+`MiddlewarePricedToken.market_id` are `MarketId`; `Erc20Holding.address` is
+`HexAddress`, and `SubstrateInfo.address` is `HexAddress | None` (`None`, no longer
+`""`, when a substrate carries no address).
 `LegacyPriceOracleMiddleware` takes `base_currency_decimals: Decimals`.
 `get_logs_adaptive(chain_id=)` and `LogSource.get_logs` take `ChainId`;
 `quote_ccip_native_fee(block=)` and `OracleMappingReader.asset_source_events` take a
@@ -112,7 +119,8 @@ takes a `ProposalHash`; `BalanceProposal.proposal_hash` and `NavMark.proposal_ha
 are `ProposalHash`; `ExternalStateEvent.transaction_hash` is a `TxHash`.
 
 **Errors and explorer.** `TransactionError(tx_hash=)` takes a `TxHash`,
-`LogScanError(address=)` a `ChecksumAddress`; `get_deployment_tx` returns a `TxHash`.
+`LogScanError(address=)` a `ChecksumAddress`; `get_deployment_tx` returns a `TxHash`
+(a malformed hash from Etherscan is reported as the error `malformed-tx-hash`).
 
 **MCP response models** (Python constructors only; the JSON schemas are unchanged
 except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
@@ -128,6 +136,13 @@ except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
 
 - The MCP `vault_info` document reports the vault address checksummed (the CLI
   already did).
+- `SubstrateInfo.address` is `None` instead of `""` for a substrate without an
+  address. Truthiness checks are unaffected and the SDK's JSON documents already
+  omit it, but `dataclasses.asdict(info)` now gives `"address": None` and
+  `info.address == ""` is false.
+- The Uniswap V3 / Ramses V2 position events (`extract_new_position_events`,
+  `extract_close_position_events`) return their addresses checksummed (they were the
+  lowercase ABI-decoded strings).
 - `fusion market meta-morpho --json` and the MCP `market_meta_morpho` tool report
   `null` instead of `""` for an absent curator, guardian or fee recipient; the MCP
   schema's `curator` is nullable.

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev49
+Version: 4.0.0.dev52
 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.dev49 → ipor_fusion-4.0.0.dev52}/pyproject.toml

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

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/__init__.py

@@ -345,7 +345,9 @@ from ipor_fusion.types import (
     TokenId,
     TransferId,
     TxHash,
+    parse_hex_address,
     parse_morpho_market_id,
+    parse_tx_hash,
 )
 from ipor_fusion.validation import (
     Erc20Holding,
@@ -624,7 +626,9 @@ __all__ = [
     "PayloadHash",
     "ProposalHash",
     "TxHash",
+    "parse_hex_address",
     "parse_morpho_market_id",
+    "parse_tx_hash",
     "AssetId",
     "CommandId",
     "DeploymentRequestId",

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/cli/vault_markets_view.py

@@ -20,7 +20,7 @@ from ipor_fusion.substrates import (
     decode_substrate,
     format_market_label,
 )
-from ipor_fusion.types import ChainId, MarketId
+from ipor_fusion.types import ChainId, MarketId, parse_hex_address
 from ipor_fusion.vault_data import (
     GET_MARKET_SUBSTRATES,
     VaultData,
@@ -213,7 +213,7 @@ def _format_token_amount(
     ctx: Web3Context,
     raw: int,
     token_address: HexAddress,
-    prices_usd: dict[str, float] | None = None,
+    prices_usd: dict[HexAddress, float] | None = None,
 ) -> str:
     """Format a raw on-chain amount using cached ERC-20 symbol + decimals.
 
@@ -226,7 +226,9 @@ def _format_token_amount(
         return f"{raw} raw ({symbol})"
     base = f"{_format_amount(raw, decimals)} {symbol}"
     if prices_usd:
-        usd_suffix = _format_usd(raw, decimals, prices_usd.get(token_address.lower()))
+        usd_suffix = _format_usd(
+            raw, decimals, prices_usd.get(parse_hex_address(token_address))
+        )
         return f"{base}{usd_suffix}"
     return base
 
@@ -259,7 +261,7 @@ def _print_dependency_graph(data: VaultData) -> None:
 def _print_fuse_section(
     title: str,
     fuses: Sequence[ChecksumAddress],
-    fuse_markets: dict[str, MarketId] | None,
+    fuse_markets: dict[ChecksumAddress, MarketId] | None,
     market_substrates: dict[MarketId, list[bytes]] | None,
     chain_id: ChainId,
     api_key: str | None,

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/core/context.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 
 from eth_account import Account
-from eth_typing import ChecksumAddress, HexStr
+from eth_typing import ChecksumAddress
 from hexbytes import HexBytes
 from requests import ConnectionError as RequestsConnectionError
 from requests import HTTPError, Timeout
@@ -25,7 +25,7 @@ from ipor_fusion.core.logs import (
     get_logs_adaptive,
 )
 from ipor_fusion.errors import LogSourceUnavailable, TransactionError, get_revert_reason
-from ipor_fusion.types import ChainId, TxHash
+from ipor_fusion.types import ChainId, parse_tx_hash
 
 # web3 retries every allowlisted method on any HTTP error, a 400 included;
 # a too-wide eth_getLogs answered with HTTP 400/413 or a query timeout would be
@@ -229,7 +229,7 @@ class Web3Context:
             reason = get_revert_reason(self.web3, tx_hash, receipt)
             raise TransactionError(
                 "Transaction failed",
-                tx_hash=TxHash(HexStr(tx_hash.to_0x_hex())),
+                tx_hash=parse_tx_hash(bytes(tx_hash)),
                 revert_reason=reason,
             )
         return receipt

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/dependency_graph.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from collections.abc import Mapping, Sequence, Set
 
+from eth_typing import ChecksumAddress
+
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.types import MarketId
 
@@ -38,7 +40,7 @@ _ERC20_DEP_NOT_REQUIRED: frozenset[MarketId] = frozenset(
 
 
 def find_orphan_fuse_markets(
-    fuse_markets: Mapping[str, MarketId],
+    fuse_markets: Mapping[ChecksumAddress, MarketId],
     balance_fuse_market_ids: Set[MarketId],
 ) -> dict[MarketId, list[str]]:
     """Return markets claimed by action fuses but lacking a balance fuse.

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/explorer.py

@@ -10,10 +10,10 @@ import time
 from urllib.parse import urlencode
 from urllib.request import urlopen
 
-from eth_typing import HexAddress, HexStr
+from eth_typing import HexAddress
 
 from ipor_fusion.cache import cache_key, load_contract_cache, update_contract_cache
-from ipor_fusion.types import ChainId, TxHash
+from ipor_fusion.types import ChainId, TxHash, parse_tx_hash
 
 ETHERSCAN_V2_URL = "https://api.etherscan.io/v2/api"
 
@@ -67,6 +67,17 @@ def get_deployment_tx(
     return _fetch_contract_creation_tx(chain_id, address, api_key)
 
 
+def _creation_tx_hash(raw: object) -> tuple[TxHash | None, str | None]:
+    if not raw:
+        return None, None
+    if not isinstance(raw, str):
+        return None, "malformed-tx-hash"
+    try:
+        return parse_tx_hash(raw), None
+    except ValueError:
+        return None, "malformed-tx-hash"
+
+
 def _fetch_contract_creation_tx(
     chain_id: ChainId, address: HexAddress, api_key: str | None = None
 ) -> tuple[TxHash | None, str | None]:
@@ -91,8 +102,7 @@ def _fetch_contract_creation_tx(
             with urlopen(url, timeout=10) as resp:  # noqa: S310
                 data = json.loads(resp.read().decode())
             if data.get("status") == "1" and data.get("result"):
-                tx_hash = data["result"][0].get("txHash")
-                return (TxHash(HexStr(tx_hash)) if tx_hash else None), None
+                return _creation_tx_hash(data["result"][0].get("txHash"))
             result_text = str(data.get("result", "")).lower()
             if "free api access is not supported" in result_text:
                 return None, "etherscan-paid-tier-required"

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/fuses/events.py

@@ -14,5 +14,12 @@ def extract_events(
     for log in receipt["logs"]:
         if log["topics"][0] == sig_hash:
             decoded = decode(abi_types, log["data"])
-            events.append(dataclass_type(*decoded))
+            events.append(
+                dataclass_type(
+                    *(
+                        Web3.to_checksum_address(value) if abi == "address" else value
+                        for abi, value in zip(abi_types, decoded, strict=True)
+                    )
+                )
+            )
     return events

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/fuses/external_state_events.py

@@ -28,11 +28,11 @@ from typing import Any
 
 from eth_abi import decode
 from eth_abi.exceptions import DecodingError
-from eth_typing import ChecksumAddress, HexStr
+from eth_typing import ChecksumAddress
 from web3 import Web3
 from web3.types import TxReceipt
 
-from ipor_fusion.types import TxHash
+from ipor_fusion.types import TxHash, parse_tx_hash
 
 
 @dataclass(frozen=True, slots=True)
@@ -196,7 +196,7 @@ def external_state_event_name(topic: bytes | str) -> str | None:
 def _hex(value: Any) -> TxHash | None:
     if value is None:
         return None
-    return TxHash(HexStr("0x" + _as_bytes(value, "transactionHash").hex()))
+    return parse_tx_hash(_as_bytes(value, "transactionHash"))
 
 
 def decode_external_state_event(log: Mapping[str, Any]) -> ExternalStateEvent | None:

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/fuses/ramses_v2.py

@@ -136,13 +136,13 @@ class RamsesClaimFuse(Fuse):
 
 @dataclass(slots=True)
 class RamsesNewPositionEvent:
-    version: str
+    version: ChecksumAddress
     token_id: TokenId
     liquidity: Liquidity
     amount0: Amount
     amount1: Amount
-    sender: str
-    recipient: str
+    sender: ChecksumAddress
+    recipient: ChecksumAddress
     fee: Fee
     tick_lower: Tick
     tick_upper: Tick

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/fuses/uniswap_v3.py

@@ -140,13 +140,13 @@ class UniswapV3CollectFuse(Fuse):
 
 @dataclass(slots=True)
 class UniswapV3NewPositionEvent:
-    version: str
+    version: ChecksumAddress
     token_id: TokenId
     liquidity: Liquidity
     amount0: Amount
     amount1: Amount
-    sender: str
-    recipient: str
+    sender: ChecksumAddress
+    recipient: ChecksumAddress
     fee: Fee
     tick_lower: Tick
     tick_upper: Tick
@@ -154,7 +154,7 @@ class UniswapV3NewPositionEvent:
 
 @dataclass(slots=True)
 class UniswapV3ClosePositionEvent:
-    version: str
+    version: ChecksumAddress
     token_id: TokenId
 
 

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/readers/hypercore.py

@@ -499,7 +499,7 @@ def _market_layout(
     bitmap = 0
     for raw in substrates:
         info = decode_substrate(raw, HYPERCORE_MARKET)
-        if info.type_label == "SPOT_TOKEN" and not info.is_error:
+        if info.type_label == "SPOT_TOKEN" and not info.is_error and info.address:
             index = HyperCoreTokenIndex(int(info.extra["token_index"]))
             if index in seen:
                 continue

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/readers/lending_health.py

@@ -353,7 +353,7 @@ def _aave_v4_spokes(substrates: list[bytes]) -> list[ChecksumAddress]:
     spokes: dict[ChecksumAddress, None] = {}
     for sub in substrates:
         info = decode_substrate(sub, market_id=IporFusionMarkets.AAVE_V4)
-        if info.type_label == "AAVE_V4_RESERVE":
+        if info.type_label == "AAVE_V4_RESERVE" and info.address:
             spokes[Web3.to_checksum_address(info.address)] = None
     return list(spokes)
 

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/substrates.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 from collections.abc import Callable
 from dataclasses import dataclass, field
 
-from eth_typing import HexAddress, HexStr
+from eth_typing import HexAddress
 from eth_utils import keccak
 
 from ipor_fusion.fuses.hypercore import (
@@ -25,12 +25,12 @@ from ipor_fusion.fuses.hypercore import (
     read_index_of,
 )
 from ipor_fusion.market_ids import IporFusionMarkets
-from ipor_fusion.types import HyperCoreAsset, MarketId
+from ipor_fusion.types import HyperCoreAsset, MarketId, parse_hex_address
 
 
 @dataclass
 class SubstrateInfo:
-    address: HexAddress = HexAddress(HexStr(""))
+    address: HexAddress | None = None
     raw_hex: str = ""
     type_label: str = ""
     is_error: bool = False
@@ -47,14 +47,10 @@ class SubstrateInfo:
 #   Slippage variant: [2 type chars][62 value chars]
 
 
-def _hex_address(hex_digits: str) -> HexAddress:
-    return HexAddress(HexStr(f"0x{hex_digits}"))
-
-
 def _decode_type_lshift160(hex_str: str, types: dict[int, str]) -> SubstrateInfo:
     """Decode type<<160 | address (Ebisu, Midas, Balancer, Velodrome)."""
     type_byte = int(hex_str[22:24], 16)
-    addr = _hex_address(hex_str[24:])
+    addr = parse_hex_address(hex_str[24:])
     label = types.get(type_byte, f"type={type_byte}")
     return SubstrateInfo(address=addr, type_label=label)
 
@@ -67,13 +63,13 @@ def _decode_type_lshift248(hex_str: str, types: dict[int, str]) -> SubstrateInfo
         return SubstrateInfo(
             raw_hex=f"0x{hex_str}", type_label=label, extra={"slippage": str(value)}
         )
-    addr = _hex_address(hex_str[24:])
+    addr = parse_hex_address(hex_str[24:])
     return SubstrateInfo(address=addr, type_label=label)
 
 
 def _decode_plain_address(hex_str: str) -> SubstrateInfo:
     """Decode zero-padded address: 12 zero bytes + 20 address bytes."""
-    return SubstrateInfo(address=_hex_address(hex_str[24:]))
+    return SubstrateInfo(address=parse_hex_address(hex_str[24:]))
 
 
 def _decode_morpho(hex_str: str) -> SubstrateInfo:
@@ -88,14 +84,14 @@ def _decode_uniswap_v4(hex_str: str) -> SubstrateInfo:
     substrate-as-asset (12 zero bytes + address)."""
     if hex_str[:24] == "0" * 24:
         return SubstrateInfo(
-            address=_hex_address(hex_str[24:]), type_label="uniswap_v4_token"
+            address=parse_hex_address(hex_str[24:]), type_label="uniswap_v4_token"
         )
     return SubstrateInfo(raw_hex=f"0x{hex_str}", type_label="uniswap_v4_pool_id")
 
 
 def _decode_enso(hex_str: str) -> SubstrateInfo:
     """Decode address<<96 | selector<<64 (Enso)."""
-    addr = _hex_address(hex_str[0:40])
+    addr = parse_hex_address(hex_str[0:40])
     selector = f"0x{hex_str[40:48]}"
     return SubstrateInfo(
         address=addr, type_label="ENSO_TARGET", extra={"selector": selector}
@@ -104,7 +100,7 @@ def _decode_enso(hex_str: str) -> SubstrateInfo:
 
 def _decode_dolomite(hex_str: str) -> SubstrateInfo:
     """Decode asset<<96 | subAccountId<<88 | canBorrow<<80 (Dolomite)."""
-    addr = _hex_address(hex_str[0:40])
+    addr = parse_hex_address(hex_str[0:40])
     sub_account_id = int(hex_str[40:42], 16)
     can_borrow = (int(hex_str[42:44], 16) & 0x01) == 1
     return SubstrateInfo(
@@ -131,7 +127,7 @@ def _decode_aave_v4(hex_str: str) -> SubstrateInfo:
         return SubstrateInfo(raw_hex=f"0x{hex_str}", type_label=label)
     flags = int(hex_str[50:52], 16)
     return SubstrateInfo(
-        address=_hex_address(hex_str[2:42]),
+        address=parse_hex_address(hex_str[2:42]),
         type_label="AAVE_V4_RESERVE",
         extra={
             "reserve_id": str(int(hex_str[42:50], 16)),
@@ -149,7 +145,7 @@ def _decode_euler_v2(hex_str: str) -> SubstrateInfo:
     plain-address path silently produces a malformed address (last 20 bytes are
     flag bytes + zero padding).
     """
-    addr = _hex_address(hex_str[0:40])
+    addr = parse_hex_address(hex_str[0:40])
     is_collateral = (int(hex_str[40:42], 16) & 0x01) == 1
     can_borrow = (int(hex_str[42:44], 16) & 0x01) == 1
     sub_account = f"0x{hex_str[44:46]}"
@@ -178,13 +174,13 @@ def _decode_async_action(hex_str: str) -> SubstrateInfo:
     type_byte = int(hex_str[0:2], 16)
     if type_byte == 0:
         return SubstrateInfo(
-            address=_hex_address(hex_str[2:42]),
+            address=parse_hex_address(hex_str[2:42]),
             type_label="ALLOWED_AMOUNT_TO_OUTSIDE",
             extra={"amount": str(int(hex_str[42:64], 16))},
         )
     if type_byte == 1:
         return SubstrateInfo(
-            address=_hex_address(hex_str[16:56]),
+            address=parse_hex_address(hex_str[16:56]),
             type_label="ALLOWED_TARGETS",
             extra={"selector": f"0x{hex_str[56:64]}"},
         )
@@ -229,10 +225,10 @@ def _decode_external_state(hex_str: str) -> SubstrateInfo:
     if type_byte == 0:
         return SubstrateInfo(raw_hex=f"0x{hex_str}", type_label="UNDEFINED")
     if label := _EXTERNAL_STATE_ADDRESS_TYPES.get(type_byte):
-        return SubstrateInfo(address=_hex_address(hex_str[24:]), type_label=label)
+        return SubstrateInfo(address=parse_hex_address(hex_str[24:]), type_label=label)
     if type_byte == 2:
         return SubstrateInfo(
-            address=_hex_address(hex_str[24:]),
+            address=parse_hex_address(hex_str[24:]),
             type_label="TARGET",
             extra={"selector": f"0x{hex_str[16:24]}"},
         )
@@ -270,7 +266,7 @@ def _decode_crosschain(hex_str: str) -> SubstrateInfo:
             is_error=True,
             extra={"chain_id": str(chain_id)},
         )
-    info = SubstrateInfo(address=_hex_address(hex_str[24:]), type_label=label)
+    info = SubstrateInfo(address=parse_hex_address(hex_str[24:]), type_label=label)
     if type_byte == 2:
         info.extra = {"chain_id": str(chain_id)}
     return info
@@ -330,7 +326,7 @@ def _decode_hypercore(hex_str: str) -> SubstrateInfo:
         return _hypercore_invalid(hex_str, label)
     if type_byte == 1:
         return SubstrateInfo(
-            address=_hex_address(hex_str[24:]),
+            address=parse_hex_address(hex_str[24:]),
             type_label=label,
             extra={"token_index": str(int(hex_str[8:24], 16))},
         )
@@ -351,10 +347,10 @@ def _decode_hypercore(hex_str: str) -> SubstrateInfo:
             extra["read_index"] = str(read_index_of(asset))
         return SubstrateInfo(raw_hex=f"0x{hex_str}", type_label=label, extra=extra)
     if type_byte == 3:
-        return SubstrateInfo(address=_hex_address(hex_str[24:]), type_label=label)
+        return SubstrateInfo(address=parse_hex_address(hex_str[24:]), type_label=label)
     if type_byte == 4:
         return SubstrateInfo(
-            address=_hex_address(hex_str[24:]),
+            address=parse_hex_address(hex_str[24:]),
             type_label=label,
             extra={"max_fee_rate_decibps": str(int(hex_str[8:24], 16))},
         )

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/types.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 from typing import ClassVar, Literal, NewType, TypeAlias
 
-from eth_typing import ChecksumAddress, HexStr
+from eth_typing import ChecksumAddress, HexAddress, HexStr
 
 Amount = NewType("Amount", int)
 Shares = NewType("Shares", int)
@@ -131,3 +131,27 @@ def parse_morpho_market_id(value: str | bytes) -> MorphoBlueMarketId:
     if len(digits) != 64 or any(c not in "0123456789abcdef" for c in digits):
         raise ValueError(f"invalid Morpho market ID (expected 32-byte hex): {value}")
     return MorphoBlueMarketId("0x" + digits)
+
+
+def _hex_digits(value: str | bytes, size: int, what: str) -> str:
+    if isinstance(value, bytes):
+        if len(value) != size:
+            raise ValueError(f"invalid {what} (expected {size} bytes): {value!r}")
+        return value.hex()
+    digits = value.strip().removeprefix("0x").removeprefix("0X").lower()
+    if len(digits) != 2 * size or any(c not in "0123456789abcdef" for c in digits):
+        raise ValueError(f"invalid {what} (expected {size}-byte hex): {value}")
+    return digits
+
+
+def parse_hex_address(value: str | bytes) -> HexAddress:
+    """An address as ``0x`` and 40 lowercase hex digits, from 20 raw bytes or hex
+    in any spelling; raises ``ValueError`` on anything else. For a checksummed
+    address use ``Web3.to_checksum_address``."""
+    return HexAddress(HexStr("0x" + _hex_digits(value, 20, "address")))
+
+
+def parse_tx_hash(value: str | bytes) -> TxHash:
+    """A transaction hash as ``0x`` and 64 lowercase hex digits, from 32 raw bytes
+    or hex in any spelling; raises ``ValueError`` on anything else."""
+    return TxHash(HexStr("0x" + _hex_digits(value, 32, "transaction hash")))

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/validation.py

@@ -110,13 +110,13 @@ class VaultState(Protocol):
     @property
     def underlying_balance_on_vault(self) -> int: ...
     @property
-    def price_oracle_addr(self) -> str: ...
+    def price_oracle_addr(self) -> ChecksumAddress: ...
     @property
     def balance_fuses(self) -> Sequence[BalanceFuse]: ...
     @property
     def market_substrates(self) -> Mapping[MarketId, Sequence[bytes]] | None: ...
     @property
-    def fuse_markets(self) -> Mapping[str, MarketId] | None: ...
+    def fuse_markets(self) -> Mapping[ChecksumAddress, MarketId] | None: ...
     @property
     def dependency_graph(self) -> Mapping[MarketId, Sequence[MarketId]] | None: ...
     @property

{ipor_fusion-4.0.0.dev49 → ipor_fusion-4.0.0.dev52}/src/ipor_fusion/vault_data.py

@@ -22,7 +22,7 @@ from eth_typing import HexAddress
 from eth_utils import function_signature_to_4byte_selector
 from web3 import Web3
 from web3.exceptions import ContractLogicError, TimeExhausted, Web3RPCError
-from web3.types import ChecksumAddress, HexStr
+from web3.types import ChecksumAddress
 
 from ipor_fusion.cache import (
     cache_key,
@@ -83,6 +83,7 @@ from ipor_fusion.types import (
     ChainId,
     MarketId,
     MorphoBlueMarketId,
+    parse_hex_address,
     parse_morpho_market_id,
 )
 
@@ -124,8 +125,8 @@ class FeeData:
     management_fee_vault_bps: int | None = None
     management_fee_last_update: int | None = None
     unrealized_management_fee: int | None = None
-    fee_manager: str | None = None
-    ipor_dao_fee_recipient: str | None = None
+    fee_manager: ChecksumAddress | None = None
+    ipor_dao_fee_recipient: ChecksumAddress | None = None
     deposit_fee_wad: int | None = None
     performance_fee_manager_bps: int | None = None
     management_fee_manager_bps: int | None = None
@@ -167,14 +168,14 @@ class VaultData:
     supply_cap: int
     asset: ChecksumAddress
     asset_symbol: str
-    access_manager: str
-    price_oracle_addr: str
-    rewards_manager: str | None
-    withdraw_manager: str | None
+    access_manager: ChecksumAddress
+    price_oracle_addr: ChecksumAddress
+    rewards_manager: ChecksumAddress | None
+    withdraw_manager: ChecksumAddress | None
     asset_price_usd: float | None
-    fuses: list
-    balance_fuses: list
-    instant_fuses: list
+    fuses: list[ChecksumAddress]
+    balance_fuses: list[BalanceFuse]
+    instant_fuses: list[ChecksumAddress]
     # Underlying asset balance held directly on the vault (raw). Part of
     # totalAssets via ERC4626 base accounting; by design NOT tracked as an
     # ERC20_VAULT_BALANCE substrate, so it is read directly in
@@ -206,7 +207,7 @@ class VaultData:
     # breakdowns (Morpho loan/collateral, Aave reserve assets). Sourced from the
     # vault's PriceOracleMiddleware. Missing keys mean the oracle has no source
     # configured for that token.
-    token_prices_usd: dict[str, float] | None = None
+    token_prices_usd: dict[HexAddress, float] | None = None
     # Middleware-priced tokens of granted substrates the PriceOracleMiddleware
     # cannot price (see readers.unpriceable). None when the check did not run.
     unpriceable_priced_tokens: list[MiddlewarePricedToken] | None = None
@@ -215,7 +216,7 @@ class VaultData:
     # are absent from the dict — used to detect orphan markets (action fuses
     # with no matching balance fuse, which silently drop positions from
     # totalAssets).
-    fuse_markets: dict[str, MarketId] | None = None
+    fuse_markets: dict[ChecksumAddress, MarketId] | None = None
     # Substrates registered for each balance-fuse market. Allows the fuse
     # tables to report substrate counts per fuse without duplicating reads.
     market_substrates: dict[MarketId, list[bytes]] | None = None
@@ -665,7 +666,7 @@ def _fetch_breakdown_token_prices(
     ctx: Web3Context,
     oracle: PriceOracleMiddleware,
     addresses: set[ChecksumAddress],
-) -> dict[str, float] | None:
+) -> dict[HexAddress, float] | None:
     """Fetch USD prices for breakdown tokens in one batch via the vault's oracle.
 
     Returns a dict keyed by lowercase token address. Tokens with no oracle
@@ -678,7 +679,7 @@ def _fetch_breakdown_token_prices(
         [oracle.get_asset_price(addr) for addr in ordered]
     )
     result = {
-        addr.lower(): price.readable()
+        parse_hex_address(addr): price.readable()
         for addr, price in zip(ordered, prices, strict=True)
         if price is not None
     }
@@ -1064,7 +1065,7 @@ def fetch_deployment_info(
         return None, None, error
 
     try:
-        tx = ctx.web3.eth.get_transaction(HexStr(tx_hash))
+        tx = ctx.web3.eth.get_transaction(tx_hash)
         block_number: int = tx["blockNumber"]
         block_info = ctx.web3.eth.get_block(block_number)
         timestamp: int = block_info["timestamp"]