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

ipor_fusion-4.0.0.dev52/MIGRATION_4.md

@@ -0,0 +1,166 @@
+# Migrating to ipor-fusion 4.0
+
+4.0 gives chain, market and role ids, the crosschain, HyperCore and Morpho ids,
+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. 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,
+type-checked or not. In particular, `fetch_market` and
+`build_morpho_blue_market_json` no longer add a `0x` prefix themselves: pass
+`parse_morpho_market_id(raw_id)`, never a bare 64-hex string. Type-checked code
+(pyright, mypy, Pylance) also wraps literals and raw values as below. Values the SDK
+returns already carry their type and go back in unwrapped.
+
+All types are importable from `ipor_fusion` (and `ipor_fusion.types`);
+`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.
+
+## Building the types
+
+| Type | From a literal or raw value |
+|---|---|
+| `ChainId` | `ChainId(1)` |
+| `MarketId` | an `IporFusionMarkets` member, or `MarketId(n)` |
+| `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 `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` | `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)` |
+| `BlockIdentifier` | a block number, `"latest"` / `"pending"` / ..., or a block hash |
+
+`MessageId` covers both a CCIP `messageId` and a LayerZero `guid`. `AssetId` is the
+crosschain executor's `bytes32` asset id; a Stargate pool's `uint16` asset id is
+`StargateAssetId`. `DeploymentRequestId` is a factory's `uint256` dispatcher request;
+a `bytes32` return (recall) request is `ReturnRequestId`.
+
+## What changed, by area
+
+**Vault reads and validation.** `fetch_vault_data(chain_id=)`, `fetch_deployment_info`,
+`build_vault_info_json`, `ensure_supported_chain`, `fetch_vault_lending_health` take
+`ChainId`; vault and oracle addresses
+(`validate_vault`, `fetch_deployment_info`, `build_vault_info_json`,
+`fetch_unpriceable_priced_tokens`) take `ChecksumAddress`; `resolve_token_symbol`,
+`resolve_token_decimals`, `get_contract_name`, `get_deployment_tx` take `HexAddress`
+(a checksum address fits). The `resolve_name` / `resolve_symbol` callbacks receive a
+`HexAddress` (a callback typed for `str` still fits). Market-keyed data is keyed by
+`MarketId`: `VaultData.market_substrates`, `dependency_graph`, `fuse_markets`,
+`morpho_positions`, `aave_positions`; the `VaultState` protocol, `validate_vault_state`
+(`market_balances`), `fetch_vault_lending_health`, `fetch_unpriceable_priced_tokens`
+and the `dependency_graph` helpers (`compute_update_reach`, `compute_update_groups`,
+`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`), 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` 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
+`BlockIdentifier`.
+
+**Markets and substrates.** Every `IporFusionMarkets` member is a `MarketId`.
+`decode_substrate`, `market_name`, `format_market_label` take `MarketId`.
+
+**Access.** `AccessManager.has_role`, `grant_role`, `revoke_role`,
+`get_accounts_with_role` take `RoleId | Roles`; `RoleAccount.role_id` is `RoleId`.
+
+**Morpho.** `MorphoBlueMarketId` now always carries `0x`; build it with
+`parse_morpho_market_id` instead of `MorphoBlueMarketId("<64 hex>")`. `fetch_market`,
+`build_morpho_blue_market_json` take it; `MorphoApiMarket.market_id`,
+`VaultV1MarketAllocation.market_id`, `VaultV2Cap.market_id`,
+`MorphoPositionBreakdown.market_id` (as read from substrates) and the keys of
+`VaultV1Info.public_allocator_flow_caps` are canonical. `fetch_market`, `fetch_vault`,
+`morpho_blue_address`, `build_*_json` take `ChainId`; `fetch_vault` takes a
+`ChecksumAddress`. Every address on the `morpho_api` records is `ChecksumAddress`;
+optional ones (`curator`, `guardian`, `fee_recipient`, `performance_fee_recipient`,
+`management_fee_recipient`, `inner_vault`, `VaultFlowCap.admin`, the `VaultV2Cap`
+market params) are `ChecksumAddress | None`.
+
+**Crosschain.** The executor, dispatcher and factory wrappers, the lanes and
+`StargateCrosschainCommandFuse.enter(request_id=)` take the crosschain ids above, and
+their getters return them (`active_command`, `active_proposal_id`, `propose_balance`
+on CCIP, `active_return` → `OperationId`, `asset_id`, `tracked_position_set_hash`,
+`pending_request_by_chain`, `CrosschainLane.proposal_id_from_logs` /
+`proposal_id_from_receipt`). Records carry them too: `Command`, `ActiveCommand`,
+`ExecutorInitParams`, `BalanceObservation`, `LaneObservation`, `Observation`,
+`CcipObservation`, `OutboundMessage`, `CcipMessageSent`, `Any2EVMMessage`,
+`VerifierResult`, `Packet.guid`, `TaxiMessage`, `StargateChain`; and the helpers
+`fetch_verifier_result(message_id=)`, `lz_receive_calldata(guid=)` and
+`lz_compose_calldata(guid=)` take a `MessageId`. Decoded event values
+(`ccip_events` → `CcipEvent.values`) stay a generic mapping: convert a value
+before passing it on.
+
+**HyperCore (preview).** The fuses, `HyperCoreSubstrates`, `HyperCoreReader`,
+`read_hypercore_transfer_snapshot` and the helpers `system_address`, `read_index_of`,
+`perp_dex_of`, `is_native_perp_asset`, `is_hip3_asset` take the HyperCore ids;
+`HyperCorePerpAssetInfo`, `HyperCorePerpMarket`, `HyperCoreSpotLeg`,
+`HyperCorePendingState` and `HyperCoreTransferSnapshot` carry them.
+
+**External state.** `ExternalStateExecutor.proposal_hash` returns and `confirm_balance`
+takes a `ProposalHash`; `BalanceProposal.proposal_hash` and `NavMark.proposal_hash`
+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`
+(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`
+`MarketId`. Calling an MCP tool function directly from Python takes `ChainId`.
+
+**Moved, still importable.** `FuseAction` lives in `ipor_fusion.core.fuse_action` and
+`ZERO_ADDRESS` in `ipor_fusion.types`; both are re-exported from
+`ipor_fusion.fuses.base` and `FuseAction` from `ipor_fusion`. The CLI's internal
+`ipor_fusion.cli.vault_cmd` was split into `options`, `vault_info_view`,
+`vault_markets_view` and `oracle_mapping_view` (private names, not API).
+
+## Behavior changes
+
+- 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.
+- The Morpho API client checksums every address it returns (market, vault,
+  allocation, adapter and cap records, and the `fusion market` / MCP market documents
+  built from them), so string comparisons against the API's own spelling change.
+- It raises `MorphoApiError` for a market id or address it parses (market and V1
+  allocation ids, V1 flow-cap ids, vault/asset/owner/token/oracle/IRM/allocator
+  addresses) when the value is invalid, or absent where the field is optional in the
+  answer. A key the parser requires can instead raise `KeyError`, e.g. a `loanAsset`
+  without `address`. When matching a market's own allocation and flow cap, an id that
+  does not parse matches nothing, and a V1 flow cap without an id is skipped, as
+  before. `--market` rejects a malformed id.
+- `LendingMarketHealth.substrate_id` for a Morpho market is `0x`-prefixed (the JSON
+  documents already were).
+- `TransactionError.tx_hash` is `0x`-prefixed.
+- Saved config entries are checksummed when loaded; the MCP `vault_add` tool rejects
+  a value that is not an address.
+- The on-disk caches (`~/.cache/ipor-fusion/`) key addresses lowercased; older entries
+  are rekeyed on load, so a contract name cached for one spelling now also resolves
+  for the other.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev45
+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
@@ -115,6 +115,10 @@ alt="Release">
   </tr>
 </table>
 
+> **Upgrading from 3.x?** 4.0 types the public API's ids and addresses and changes
+> a few behaviors (Morpho market ids, nullable optional addresses); see
+> [MIGRATION_4.md](MIGRATION_4.md).
+
 ## Quickstart
 
 ### Install

{ipor_fusion-4.0.0.dev45 → ipor_fusion-4.0.0.dev52}/README.md

@@ -69,6 +69,10 @@ alt="Release">
   </tr>
 </table>
 
+> **Upgrading from 3.x?** 4.0 types the public API's ids and addresses and changes
+> a few behaviors (Morpho market ids, nullable optional addresses); see
+> [MIGRATION_4.md](MIGRATION_4.md).
+
 ## Quickstart
 
 ### Install

{ipor_fusion-4.0.0.dev45 → ipor_fusion-4.0.0.dev52}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev45"
+version = "4.0.0.dev52"
 description = "The IPOR Fusion SDK for Python"
 authors = [
     { name = "Adam Mydlarz", email = "amydlarz@gmail.com" },
@@ -165,3 +165,4 @@ packages = ["src/ipor_fusion"]
 # semantic-release before `build_command`, so each wheel carries its own entry.
 [tool.hatch.build.targets.wheel.force-include]
 "CHANGELOG.md" = "ipor_fusion/CHANGELOG.md"
+"MIGRATION_4.md" = "ipor_fusion/MIGRATION_4.md"

{ipor_fusion-4.0.0.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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")))