ipor-fusion 4.0.0.dev74__tar.gz → 4.0.0.dev83__tar.gz

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/MIGRATION_4.md

@@ -133,6 +133,16 @@ and the Stargate fuse's `eid=` take it (`LayerZeroEid(30101)`).
 `encode_oft_compose_msg(*, nonce=, src_eid=, amount_ld=, compose_msg=)` takes
 keyword arguments only. `ZERO_ADDRESS` is a `ChecksumAddress` (same value).
 
+**Chain registry and removed aliases.** `CHAIN_NAMES`, `CHAIN_NAME_TO_ID`,
+`SUPPORTED_CHAIN_IDS`, `GET_LOGS_RANGE_HINTS`, `BLOCK_EXPLORER_URLS`,
+`MORPHO_BLUE_ADDRESSES`, `AAVE_V3_POOL`, `PUBLIC_ALLOCATOR_ADDRESSES` and
+`HYPERCORE_PENDING_READERS` are keyed by `ChainId` (`HYPEREVM_CHAIN_ID` is one) and
+`explorer.SUPPORTED_CHAINS` is a `frozenset[ChainId]`, so
+`ensure_supported_chain(CHAIN_NAME_TO_ID["ethereum"])` type-checks;
+`PUBLIC_ALLOCATOR_ADDRESSES` values are `ChecksumAddress`. `IporFusionMarkets.RWA`
+is gone: market 50 is `IporFusionMarkets.EXTERNAL_STATE`. `MORPHO_BLUE_ADDRESS` is
+gone: use `morpho_blue_address(chain_id)`.
+
 **Markets and substrates.** Every `IporFusionMarkets` member is a `MarketId`.
 `decode_substrate`, `market_name`, `format_market_label` take `MarketId`.
 
@@ -210,8 +220,10 @@ except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
 - 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
+  answer. Any other answer it cannot read (a missing key such as a `loanAsset`
+  without `address`, a value of the wrong type, a body that is not a JSON object) and
+  any transport failure also raise `MorphoApiError`, never `KeyError`, `TypeError` or
+  `ValueError` (see [Errors](#errors)). 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
@@ -222,3 +234,43 @@ except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
 - 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.
+
+## Errors
+
+Every exception class the SDK defines now derives from `IporFusionError` and is
+importable from `ipor_fusion`; the builtin bases they had are kept. The rule the
+changes below apply is: a caller's mistake (a bad argument, or an operation the
+object was not built for) raises a plain `ValueError`; a chain, provider or remote
+API answering something the SDK cannot use raises an `IporFusionError` subclass.
+4.0 applies it to the paths listed here, not yet everywhere: the HyperCore NAV
+reader (`read_hypercore_nav`) still raises `ValueError` for a failed precompile read,
+a missing oracle price or an unsupported dex configuration,
+`fetch_verifier_result` can still raise `KeyError` or `ValueError` on a malformed
+indexer answer, and `erc20_balance_slot` raises `ValueError` when no slot answers.
+
+- `MorphoApiError` (still a `RuntimeError`), `ExternalStateEventDecodeError` (still a
+  `ValueError`) and `VerifierResultUnavailable` (still a `LookupError`) now derive
+  from `IporFusionError`, so an `except IporFusionError` placed before their own
+  handlers catches them first. `MorphoApiError` lives in `ipor_fusion.errors` and is
+  exported from `ipor_fusion`; `ipor_fusion.morpho_api.MorphoApiError` still works.
+- `EmptyCallResultError` is no longer an eth_abi `InsufficientDataBytes` (nor a
+  `DecodingError`). Code that caught either around `.call()` to tolerate a missing
+  contract or getter must catch `EmptyCallResultError`; return data that is present
+  but too short still raises eth_abi's error.
+- Crosschain discovery (`discover_deployment`, `discover_lane_fuses`,
+  `detect_transport`, `open_lane`, `CrosschainDeployment.executor`) raises the new
+  `CrosschainDiscoveryError` instead of `ValueError` for on-chain configuration it
+  cannot use: a malformed or unknown market substrate, an executor managed by another
+  vault or of no known transport, a missing or duplicate lane fuse, or not exactly one
+  executor of a transport. An executor reporting `transportKind()` `UNDEFINED` is now
+  rejected by `detect_transport` instead of being returned. A transport kind passed in
+  that has no lane is still a `ValueError`.
+- `Call.call()` and `Call.decode()` on a write-only `Call` raise `ValueError`, not
+  `RuntimeError`. `CrosschainSimulator.relay` raises `ValueError`, not
+  `RuntimeError`, for a message to a chain that was not added.
+- `VaultSimulator.run` (provider error from `eth_simulateV1`, or a result count that
+  does not match the queued calls) and `CrosschainSimulator.relay` (not settled within
+  `max_rounds`) raise the new `SimulationRunError`, still a `RuntimeError`.
+- The Morpho API client raises `MorphoApiError` for every response it cannot read and
+  for any `OSError` or `http.client.HTTPException` while fetching (it caught only
+  `URLError` and `TimeoutError` before).

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/PKG-INFO

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

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

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/__init__.py

@@ -174,6 +174,7 @@ from ipor_fusion.dependency_graph import (
 from ipor_fusion.errors import (
     CUSTOM_ERRORS,
     ContractNotFoundError,
+    CrosschainDiscoveryError,
     EmptyCallResultError,
     IporFusionError,
     LogScanError,
@@ -181,6 +182,7 @@ from ipor_fusion.errors import (
     MorphoMarketNotFoundError,
     NotPlasmaVaultError,
     SimulationError,
+    SimulationRunError,
     TransactionError,
     UnsupportedChainError,
     UnsupportedVaultVersionError,
@@ -716,6 +718,7 @@ __all__ = [
     "market_name",
     "DOCS",
     "ContractNotFoundError",
+    "CrosschainDiscoveryError",
     "EmptyCallResultError",
     "IporFusionError",
     "LogScanError",
@@ -724,6 +727,7 @@ __all__ = [
     "NotPlasmaVaultError",
     "TransactionError",
     "SimulationError",
+    "SimulationRunError",
     "UnsupportedChainError",
     "UnsupportedVaultVersionError",
     "CUSTOM_ERRORS",

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/chains.py

@@ -5,48 +5,48 @@ from __future__ import annotations
 from ipor_fusion.errors import UnsupportedChainError
 from ipor_fusion.types import ChainId
 
-CHAIN_NAMES: dict[int, str] = {
-    1: "ethereum",
-    42161: "arbitrum",
-    8453: "base",
-    10: "optimism",
-    130: "unichain",
-    137: "polygon",
-    56: "bsc",
-    239: "tac",
-    9745: "plasma",
-    43114: "avalanche",
-    250: "fantom",
-    143: "monad",
-    999: "hyperevm",
-    4663: "robinhood",
-    747474: "katana",
-    3637: "botanix",
-    57073: "ink",
-    14: "flare",
+CHAIN_NAMES: dict[ChainId, str] = {
+    ChainId(1): "ethereum",
+    ChainId(42161): "arbitrum",
+    ChainId(8453): "base",
+    ChainId(10): "optimism",
+    ChainId(130): "unichain",
+    ChainId(137): "polygon",
+    ChainId(56): "bsc",
+    ChainId(239): "tac",
+    ChainId(9745): "plasma",
+    ChainId(43114): "avalanche",
+    ChainId(250): "fantom",
+    ChainId(143): "monad",
+    ChainId(999): "hyperevm",
+    ChainId(4663): "robinhood",
+    ChainId(747474): "katana",
+    ChainId(3637): "botanix",
+    ChainId(57073): "ink",
+    ChainId(14): "flare",
 }
 
-CHAIN_NAME_TO_ID: dict[str, int] = {name: cid for cid, name in CHAIN_NAMES.items()}
+CHAIN_NAME_TO_ID: dict[str, ChainId] = {name: cid for cid, name in CHAIN_NAMES.items()}
 
 # Chains the on-chain vault tooling (vault info/health/substrate fetch) is
 # validated on. A provider for another chain may connect fine and still fail
 # deeper in the stack (a missing Multicall3, an oracle quirk, an eth_getLogs
 # cap the adaptive scan cannot page through). Extend only after the full
 # vault_info path passes on every live vault of that chain.
-SUPPORTED_CHAIN_IDS: frozenset[int] = frozenset(
-    {1, 130, 143, 999, 8453, 9745, 42161, 43114, 747474}
+SUPPORTED_CHAIN_IDS: frozenset[ChainId] = frozenset(
+    ChainId(cid) for cid in (1, 130, 143, 999, 8453, 9745, 42161, 43114, 747474)
 )
 
 # First eth_getLogs page size, in blocks, on chains whose providers cap the
 # range (10,000 blocks) or time out on wide queries. The scan still shrinks a
 # page the provider rejects; a hint only skips the whole-range attempt and the
 # probing round trips.
-GET_LOGS_RANGE_HINTS: dict[int, int] = {
-    130: 10_000,
-    9745: 10_000,
-    57073: 10_000,
-    43114: 1_000_000,
-    747474: 1_000_000,
+GET_LOGS_RANGE_HINTS: dict[ChainId, int] = {
+    ChainId(130): 10_000,
+    ChainId(9745): 10_000,
+    ChainId(57073): 10_000,
+    ChainId(43114): 1_000_000,
+    ChainId(747474): 1_000_000,
 }
 
 

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/core/access.py

@@ -15,7 +15,11 @@ from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.contract import Call, ContractWrapper
 from ipor_fusion.core.multicall import Multicall3
 from ipor_fusion.core.plasma_vault import PlasmaVault
-from ipor_fusion.errors import ContractNotFoundError, NotPlasmaVaultError
+from ipor_fusion.errors import (
+    ContractNotFoundError,
+    EmptyCallResultError,
+    NotPlasmaVaultError,
+)
 from ipor_fusion.types import AccessManagerAddress, Period, PlasmaVaultAddress, RoleId
 
 
@@ -189,8 +193,9 @@ def resolve_access_manager(
 
     Raises ContractNotFoundError when no code is deployed at the address (as
     of ctx.default_block), and NotPlasmaVaultError when the contract does not
-    expose getAccessManagerAddress() — either an empty eth_call return
-    (InsufficientDataBytes on decode) or a revert (ContractLogicError).
+    expose getAccessManagerAddress(): an empty eth_call return
+    (EmptyCallResultError), return data too short to decode
+    (InsufficientDataBytes) or a revert (ContractLogicError).
     Provider/transport errors propagate unchanged.
     """
     checksum = Web3.to_checksum_address(vault_address)
@@ -210,7 +215,7 @@ def resolve_access_manager(
             .get_access_manager_address()
             .call()
         )
-    except (InsufficientDataBytes, ContractLogicError) as exc:
+    except (EmptyCallResultError, InsufficientDataBytes, ContractLogicError) as exc:
         raise NotPlasmaVaultError(
             f"Address {checksum} on chain {ctx.chain_id} does not appear "
             f"to be a Plasma Vault."

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/core/contract.py

@@ -73,7 +73,7 @@ class Call(Generic[T]):
         """Execute as `eth_call`; decode and convert per `output_types`/`decoder`."""
         actual = self._resolve_ctx(ctx)
         if not self.output_types:
-            raise RuntimeError(
+            raise ValueError(
                 "Call.call() on a write-only Call — use .send() instead "
                 "(no output_types declared)."
             )
@@ -91,7 +91,7 @@ class Call(Generic[T]):
         """Decode raw return data per `output_types`/`decoder` — the second half
         of `.call()`, for return data fetched elsewhere (e.g. `Multicall3`)."""
         if not self.output_types:
-            raise RuntimeError("Call.decode() on a write-only Call.")
+            raise ValueError("Call.decode() on a write-only Call.")
         values = tuple(decode(self.output_types, bytes(raw)))
         single: Any = values[0] if len(values) == 1 else values
         if self.decoder is not None:

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/core/multicall.py

@@ -23,7 +23,7 @@ MULTICALL3_ADDRESS: ChecksumAddress = Web3.to_checksum_address(
 DEFAULT_BATCH_SIZE = 100
 
 # A sub-call that reverts, returns nothing or returns undecodable data.
-_CALL_FAILURES = (ContractLogicError, DecodingError)
+_CALL_FAILURES = (ContractLogicError, EmptyCallResultError, DecodingError)
 
 
 class Multicall3(ContractWrapper):

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/core/simulation.py

@@ -15,7 +15,11 @@ from web3.utils.address import get_create_address
 
 from ipor_fusion.core.contract import Call, _encode_calldata
 from ipor_fusion.core.fuse_action import FuseAction
-from ipor_fusion.errors import SimulationError, decode_custom_error
+from ipor_fusion.errors import (
+    SimulationError,
+    SimulationRunError,
+    decode_custom_error,
+)
 from ipor_fusion.types import PlasmaVaultAddress
 
 #: ``n`` (the sent block's index in the run) -> account overrides for it.
@@ -570,7 +574,7 @@ class VaultSimulator:
         )
         if "error" in response:
             err = response["error"]
-            raise RuntimeError(f"eth_simulateV1 failed: {err}")
+            raise SimulationRunError(f"eth_simulateV1 failed: {err}")
 
         return self._parse_response(response["result"])
 
@@ -597,7 +601,7 @@ class VaultSimulator:
         for block_result in result:
             raw_calls.extend(block_result.get("calls", []))
         if len(raw_calls) != len(sources):
-            raise RuntimeError(
+            raise SimulationRunError(
                 "eth_simulateV1 returned "
                 f"{len(raw_calls)} call results for {len(sources)} queued calls"
             )

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/crosschain/ccip/indexer.py

@@ -21,6 +21,7 @@ from web3 import Web3
 
 from ipor_fusion.core.contract import Call
 from ipor_fusion.crosschain.ccip.chainlink import CcipOffRamp
+from ipor_fusion.errors import IporFusionError
 from ipor_fusion.types import MessageId
 
 #: Chainlink Labs' public mainnet indexers, tried in order.
@@ -32,9 +33,10 @@ INDEXER_URLS: tuple[str, ...] = (
 _HEADERS = {"Accept": "application/json", "User-Agent": "ipor-fusion-sdk"}
 
 
-class VerifierResultUnavailable(LookupError):
+class VerifierResultUnavailable(IporFusionError, LookupError):
     """No indexer could serve a verifier result for the message (not verified
-    yet, or the indexers were unreachable); the message says which."""
+    yet, or the indexers were unreachable); the message says which. Also a
+    LookupError: the result looked up is not there (yet)."""
 
 
 @dataclass(frozen=True, slots=True)

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/crosschain/discovery.py

@@ -9,6 +9,9 @@ whose ``hasDispatcher`` is true), every
 turns that into one ``CrosschainLane`` per executor and spoke; ``open_lane``
 does it for one executor address. ``LANES`` is the only place that knows the
 concrete lane classes: a new transport is a new subpackage plus one entry.
+
+On-chain configuration that discovery cannot use raises ``CrosschainDiscoveryError``;
+``ValueError`` is kept for a bad argument (a transport kind with no lane).
 """
 
 from __future__ import annotations
@@ -31,7 +34,7 @@ from ipor_fusion.crosschain.lane import CrosschainLane, LaneFuses
 from ipor_fusion.crosschain.messages import CrosschainTransportKind
 from ipor_fusion.crosschain.stargate.contracts import StargateCrosschainExecutor
 from ipor_fusion.crosschain.stargate.lane import StargateLane
-from ipor_fusion.errors import EmptyCallResultError
+from ipor_fusion.errors import CrosschainDiscoveryError, EmptyCallResultError
 from ipor_fusion.fuses.crosschain.base import (
     CrosschainSubstrateLib,
     CrosschainSubstrateType,
@@ -75,11 +78,18 @@ def detect_transport(
     non-zero ``STARGATE_POOL()`` and no ``transportKind()``."""
     transport_kind = _probe(CcipCrosschainExecutor(ctx, executor).transport_kind())
     if transport_kind is not None:
-        return CrosschainTransportKind(transport_kind)
+        if transport_kind not in LANES:
+            raise CrosschainDiscoveryError(
+                f"{executor} reports transportKind {transport_kind.name}, "
+                "which has no lane"
+            )
+        return transport_kind
     pool = _probe(StargateCrosschainExecutor(ctx, executor).stargate_pool())
     if pool is not None and pool != ZERO_ADDRESS:
         return CrosschainTransportKind.STARGATE_LAYERZERO
-    raise ValueError(f"{executor} is not a crosschain executor of a known transport")
+    raise CrosschainDiscoveryError(
+        f"{executor} is not a crosschain executor of a known transport"
+    )
 
 
 def discover_lane_fuses(
@@ -108,14 +118,16 @@ def discover_lane_fuses(
         for role, selector in selectors.items():
             if selector in code:
                 if role in found:
-                    raise ValueError(
+                    raise CrosschainDiscoveryError(
                         f"two {role} fuses on market {market_id}: "
                         f"{found[role]} and {fuse}"
                     )
                 found[role] = fuse
     missing = [role for role in selectors if role not in found]
     if missing:
-        raise ValueError(f"no {', '.join(missing)} fuse on market {market_id}")
+        raise CrosschainDiscoveryError(
+            f"no {', '.join(missing)} fuse on market {market_id}"
+        )
     return LaneFuses(found["supply"], found["command"], found["claim"])
 
 
@@ -163,7 +175,7 @@ class CrosschainDeployment:
         or more than one."""
         found = [e for e in self.executors if e.transport_kind == transport_kind]
         if len(found) != 1:
-            raise ValueError(
+            raise CrosschainDiscoveryError(
                 f"{len(found)} {transport_kind.name} executors on market "
                 f"{self.market_id} of {self.vault}"
             )
@@ -180,17 +192,23 @@ def discover_deployment(
     remote_vaults: dict[ChainId, list[ChecksumAddress]] = {}
     for raw in plasma_vault.get_market_substrates(market_id).call():
         raw_bytes = bytes(raw)
-        substrate = CrosschainSubstrateLib.bytes32_to_substrate(raw_bytes)
+        try:
+            substrate = CrosschainSubstrateLib.bytes32_to_substrate(raw_bytes)
+        except ValueError as exc:
+            raise CrosschainDiscoveryError(
+                f"substrate {raw_bytes.hex()} on market {market_id} does not "
+                f"decode: {exc}"
+            ) from exc
         if substrate.substrate_type == CrosschainSubstrateType.EXECUTOR:
             if substrate.chain_id != 0:
-                raise ValueError(
+                raise CrosschainDiscoveryError(
                     f"executor substrate {raw_bytes.hex()} on market {market_id} "
                     f"has nonzero chain id {substrate.chain_id}"
                 )
             executors.append(substrate.substrate_address)
         elif substrate.substrate_type == CrosschainSubstrateType.REMOTE_VAULT:
             if substrate.chain_id == 0:
-                raise ValueError(
+                raise CrosschainDiscoveryError(
                     f"remote vault substrate {raw_bytes.hex()} on market "
                     f"{market_id} has zero chain id"
                 )
@@ -198,7 +216,7 @@ def discover_deployment(
                 substrate.substrate_address
             )
         else:
-            raise ValueError(
+            raise CrosschainDiscoveryError(
                 f"substrate {raw_bytes.hex()} on market {market_id} has type "
                 f"{substrate.substrate_type.name}"
             )
@@ -208,7 +226,9 @@ def discover_deployment(
         wrapper = CrosschainExecutor(hub_ctx, address)
         manager = wrapper.manager().call()
         if manager != vault:
-            raise ValueError(f"executor {address} is managed by {manager}, not {vault}")
+            raise CrosschainDiscoveryError(
+                f"executor {address} is managed by {manager}, not {vault}"
+            )
         transport_kind = detect_transport(hub_ctx, address)
         infos.append(
             CrosschainExecutorInfo(

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/crosschain/simulation.py

@@ -40,6 +40,7 @@ from ipor_fusion.crosschain.transport import (
     CrosschainTransport,
     OutboundMessage,
 )
+from ipor_fusion.errors import SimulationRunError
 from ipor_fusion.types import ChainId, PlasmaVaultAddress
 
 #: What the synthetic token source holds: enough for any test amount.
@@ -117,8 +118,9 @@ class CrosschainSimulator:
     def relay(self, max_rounds: int = 8) -> dict[ChainId, SimulationResult]:
         """Run every chain and deliver messages until nothing is in flight.
 
-        Runs at most ``max_rounds`` rounds and raises ``RuntimeError`` if
-        messages are still being produced afterward. A delivery that reverts
+        Runs at most ``max_rounds`` rounds and raises ``SimulationRunError`` if
+        messages are still being produced afterward, and ``ValueError`` if a
+        message targets a chain that was not added. A delivery that reverts
         stays in the destination call list and surfaces through that chain's
         ``SimulationResult``.
         """
@@ -128,7 +130,7 @@ class CrosschainSimulator:
                 break
             pending = self._run_round(pending)
         if pending:
-            raise RuntimeError(f"relay did not settle within {max_rounds} rounds")
+            raise SimulationRunError(f"relay did not settle within {max_rounds} rounds")
         return dict(self._results)
 
     def _run_round(self, chain_ids: set[ChainId]) -> set[ChainId]:
@@ -147,7 +149,7 @@ class CrosschainSimulator:
     def _deliver(self, message: OutboundMessage) -> None:
         destination = self._chains.get(message.dst_chain_id)
         if destination is None:
-            raise RuntimeError(
+            raise ValueError(
                 f"message {message.message_id.hex()} targets chain "
                 f"{message.dst_chain_id}, which was not added to the simulator"
             )

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/errors.py

@@ -5,7 +5,6 @@ import re
 from collections.abc import Iterable
 
 from eth_abi import decode as abi_decode
-from eth_abi.exceptions import InsufficientDataBytes
 from eth_typing import ChecksumAddress
 from eth_utils import function_signature_to_4byte_selector
 from web3 import Web3
@@ -147,35 +146,48 @@ def get_revert_reason(web3: Web3, tx_hash: TxHash, receipt: TxReceipt) -> str |
 
 
 class IporFusionError(Exception):
-    """Base exception for all IPOR Fusion SDK errors."""
+    """Base of every exception the SDK defines.
+
+    The rule the SDK follows (a few older readers do not yet; see
+    MIGRATION_4.md): a subclass when the chain, a provider or a remote API
+    answers something it cannot use. A caller's mistake (a bad argument, or an
+    operation the object was not built for, such as ``.call()`` on a write-only
+    ``Call``) raises a builtin ``ValueError`` instead, as the standard library
+    does for an operation on a closed file. A subclass that also describes bad
+    input (an address that is not a vault, a chain the tooling does not cover)
+    additionally derives from ``ValueError``; a few keep the builtin base they
+    had before 4.0 (``RuntimeError``, ``LookupError``) so existing handlers
+    still catch them.
+    """
 
 
 class ContractNotFoundError(IporFusionError, ValueError):
     """No contract deployed at the given address.
 
-    Also a ValueError so MCP adapters can let it propagate unmapped.
+    Also a ValueError: the address the caller passed holds nothing to read.
     """
 
 
 class NotPlasmaVaultError(IporFusionError, ValueError):
     """Contract exists but does not implement the Plasma Vault interface.
 
-    Also a ValueError so MCP adapters can let it propagate unmapped.
+    Also a ValueError: the address the caller passed is not a vault.
     """
 
 
 class UnsupportedChainError(IporFusionError, ValueError):
     """Chain is not (yet) supported by the on-chain vault tooling.
 
-    Also a ValueError so MCP adapters can let it propagate unmapped.
+    Also a ValueError: the chain the caller passed is outside what the tooling
+    covers.
     """
 
 
 class UnsupportedVaultVersionError(IporFusionError, ValueError):
     """A Plasma Vault predates a getter the on-chain vault tooling requires.
 
-    Also a ValueError, so callers that report ValueError as a user error
-    surface it as one.
+    Also a ValueError: the vault the caller passed cannot be read by this
+    tooling.
     """
 
 
@@ -202,21 +214,40 @@ class LogSourceUnavailable(IporFusionError):
     falls back to its own `eth_getLogs` scan."""
 
 
-class EmptyCallResultError(IporFusionError, InsufficientDataBytes):
+class EmptyCallResultError(IporFusionError):
     """`eth_call` returned no data for a call that declares return values.
 
     Almost always there is no contract at the target address on the connected
     chain (or at the requested block); a contract whose catch-all fallback
-    returns nothing looks the same. Subclasses eth_abi's InsufficientDataBytes
-    — the error the ABI decoder used to raise — so existing handlers still
-    catch it.
+    returns nothing looks the same. Return data that is present but too short
+    still raises eth_abi's own decoding error.
     """
 
 
 class MorphoMarketNotFoundError(IporFusionError, ValueError):
     """Morpho Blue market ID was never created on the connected chain.
 
-    Also a ValueError so MCP adapters can let it propagate unmapped.
+    Also a ValueError: the market id the caller passed names no market.
+    """
+
+
+class MorphoApiError(IporFusionError, RuntimeError):
+    """The Morpho API is unreachable, returned an error, or answered with a
+    response the client cannot parse (missing keys, wrong types, invalid
+    addresses or market ids). Also a RuntimeError, its base before 4.0."""
+
+
+class CrosschainDiscoveryError(IporFusionError):
+    """A crosschain vault's on-chain configuration is not one discovery can
+    use: a malformed or unexpected market grant, an executor managed by another
+    vault or of no known transport, or a missing or duplicate lane fuse."""
+
+
+class SimulationRunError(IporFusionError, RuntimeError):
+    """A simulation could not run to completion: the provider rejected
+    ``eth_simulateV1`` or answered with a different number of call results than
+    were queued, or a crosschain relay was still producing messages after its
+    last round. Distinct from a simulated call that reverts (``SimulationError``).
     """
 
 

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/explorer.py

@@ -17,7 +17,9 @@ from ipor_fusion.types import ChainId, TxHash, parse_tx_hash
 
 ETHERSCAN_V2_URL = "https://api.etherscan.io/v2/api"
 
-SUPPORTED_CHAINS = {1, 42161, 8453, 10, 137, 56, 43114, 250}
+SUPPORTED_CHAINS: frozenset[ChainId] = frozenset(
+    ChainId(cid) for cid in (1, 42161, 8453, 10, 137, 56, 43114, 250)
+)
 
 _MAX_RETRIES = 3
 _RETRY_DELAY = 1.0

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/fuses/external_state_events.py

@@ -32,6 +32,7 @@ from eth_typing import ChecksumAddress
 from web3 import Web3
 from web3.types import TxReceipt
 
+from ipor_fusion.errors import IporFusionError
 from ipor_fusion.types import TxHash, parse_tx_hash
 
 
@@ -123,9 +124,10 @@ EXTERNAL_STATE_TOPICS: tuple[str, ...] = tuple(
 )
 
 
-class ExternalStateEventDecodeError(ValueError):
+class ExternalStateEventDecodeError(IporFusionError, ValueError):
     """A log carries a listed ExternalState topic but its data does not decode
-    to the declared parameters: malformed, never a plausible event."""
+    to the declared parameters: malformed, never a plausible event. Also a
+    ValueError: the log the caller passed is not a decodable event."""
 
 
 @dataclass(frozen=True, slots=True)

{ipor_fusion-4.0.0.dev74 → ipor_fusion-4.0.0.dev83}/src/ipor_fusion/market_ids.py

@@ -87,13 +87,6 @@ class IporFusionMarkets:
     # 4 BALANCE_ACCOUNT, 5 STALENESS_MAX, 6 BIG_CHANGE_BPS, 7 DUST_THRESHOLD,
     # 8 MIN_UPDATE_INTERVAL).
     EXTERNAL_STATE = MarketId(50)
-    # Deprecated alias of EXTERNAL_STATE, kept for backward compatibility.
-    # Reverse id->name lookups skip aliases (see _DEPRECATED_ALIASES) so the
-    # canonical name is the one displayed.
-    RWA = MarketId(50)
-    # Deprecated member names that alias a canonical member of the same value;
-    # reverse id->name lookups skip these so the canonical name wins.
-    _DEPRECATED_ALIASES = frozenset({"RWA"})
     # substrate type: AguaSubstrateLib (VAULT or ASSET)
     AGUA_GLOBAL_CARRY = MarketId(51)
     # dependence graph: balance of ERC20_VAULT_BALANCE (purchase tokens return