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

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

@@ -238,15 +238,20 @@ except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
 ## 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.
+importable from `ipor_fusion`; the builtin bases they had are kept. One rule holds
+across the whole SDK: a caller's mistake (a bad argument, or an operation the object
+was not built for) raises a plain `ValueError` (`TypeError` for an argument of the
+wrong type, `KeyError` for an unknown name in a mapping-style lookup such as
+`ipor_fusion.guide.guide_text`); a chain, provider or remote API answering something the
+SDK cannot use raises an `IporFusionError` subclass. Except for
+`CrosschainDiscoveryError` (discovery) and `SimulationError` (`quote_ccip_native_fee`),
+every subclass that replaces a `ValueError` raise also derives from `ValueError`, so
+`except ValueError` keeps catching it; catch the subclass to tell a chain fact from a
+bad argument. Receipts,
+logs and transports passed in that do not contain what the call needs (a clone
+receipt without its events, logs without the lane's `BalanceProposed`, a CCIP
+message to a chain the transport does not configure) stay `ValueError`: the input
+is the wrong one.
 
 - `MorphoApiError` (still a `RuntimeError`), `ExternalStateEventDecodeError` (still a
   `ValueError`) and `VerifierResultUnavailable` (still a `LookupError`) now derive
@@ -274,3 +279,40 @@ indexer answer, and `erc20_balance_slot` raises `ValueError` when no slot answer
 - 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).
+- The MCP `market_meta_morpho` tool lets `MorphoApiError` propagate instead of
+  re-raising it as `ValueError`. MCP clients see the same tool error message; only a
+  direct Python call of the tool function sees the new type.
+- `read_hypercore_nav` (and `read_hypercore_vault_state`, which calls it) raises the new
+  `HyperCoreValuationError` (still a `ValueError`) for a failed `spotBalance`,
+  `tokenInfo` or `accountMarginSummary` precompile read, a granted spot token the
+  oracle does not price, a price overflow and an unsupported HIP-3 dex bitmap;
+  `HyperCoreNav.balance_wad` raises it for a negative NAV.
+- `read_hypercore_transfer_snapshot` raises `UnsupportedChainError` (still a
+  `ValueError`) on a chain with no known `HyperCorePendingReader` when none is passed.
+- `fetch_verifier_result` no longer leaks `KeyError`, `TypeError` or `ValueError` from
+  an indexer answer it cannot read (not JSON, a missing or mistyped field, invalid hex
+  or address, an empty or non-array CCV list, or a result for a different message id,
+  both now checked): that
+  indexer is skipped like an unreachable one, and when none serves a readable result
+  it raises `VerifierResultUnavailable` naming each indexer's reason. A `message_id`
+  that is not 32 bytes is still a `ValueError`.
+- `erc20_balance_slot` raises the new `BalanceSlotNotFoundError` (still a
+  `ValueError`) when no slot up to `max_slot` answers as the balances mapping; a
+  negative `max_slot` is a `ValueError` with its own message.
+- The external-state market raises the new `ExternalStateError` (still a
+  `ValueError`): `read_external_state` for a storage word longer than 32 bytes, an
+  executor word with bits above the address or a pause word other than 0 or 1;
+  `ExternalStateExecutor.for_vault` when no executor is deployed and, instead of
+  eth_abi's `NonEmptyPaddingBytes`, for a slot that is not an address;
+  `parse_balance_proposed` / `find_balance_proposed` for one of the executor's own
+  `BalanceProposed` logs whose data is missing or malformed (including data that is
+  not hex at all, which raised `TypeError`) or whose hash is not the hash of its own
+  fields; and `mark_nav` when the propose receipt it fetched has no such log or
+  records another value or proposer. A log that is not the event or not from the
+  executor, and `find_balance_proposed` over logs that hold no match, are still
+  `ValueError`.
+- `ccip_token_lane` raises the new `UnsupportedContractVersionError` (still a
+  `ValueError`) for an OnRamp version whose layout is not verified.
+- `quote_ccip_native_fee` raises `SimulationError` (label `"quote"`, with
+  `revert_reason`) instead of `ValueError` when the call reverts before the CCIP fee
+  check. A call that succeeds without sending a message is still a `ValueError`.

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

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

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

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

@@ -173,9 +173,12 @@ from ipor_fusion.dependency_graph import (
 )
 from ipor_fusion.errors import (
     CUSTOM_ERRORS,
+    BalanceSlotNotFoundError,
     ContractNotFoundError,
     CrosschainDiscoveryError,
     EmptyCallResultError,
+    ExternalStateError,
+    HyperCoreValuationError,
     IporFusionError,
     LogScanError,
     LogSourceUnavailable,
@@ -185,6 +188,7 @@ from ipor_fusion.errors import (
     SimulationRunError,
     TransactionError,
     UnsupportedChainError,
+    UnsupportedContractVersionError,
     UnsupportedVaultVersionError,
     decode_custom_error,
     get_revert_reason,
@@ -717,9 +721,12 @@ __all__ = [
     "format_market_label",
     "market_name",
     "DOCS",
+    "BalanceSlotNotFoundError",
     "ContractNotFoundError",
     "CrosschainDiscoveryError",
     "EmptyCallResultError",
+    "ExternalStateError",
+    "HyperCoreValuationError",
     "IporFusionError",
     "LogScanError",
     "LogSourceUnavailable",
@@ -729,6 +736,7 @@ __all__ = [
     "SimulationError",
     "SimulationRunError",
     "UnsupportedChainError",
+    "UnsupportedContractVersionError",
     "UnsupportedVaultVersionError",
     "CUSTOM_ERRORS",
     "decode_custom_error",

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev86}/src/ipor_fusion/core/external_state_executor.py

@@ -31,6 +31,7 @@ from web3.types import BlockIdentifier, TxReceipt
 
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.contract import Call, ContractWrapper
+from ipor_fusion.errors import ExternalStateError
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.types import (
     ZERO_ADDRESS,
@@ -107,6 +108,17 @@ def _hash_of(
     )
 
 
+def _no_balance_proposed(
+    executor: ChecksumAddress, balance_account: ChecksumAddress | None
+) -> str:
+    for_account = (
+        f" for account {Web3.to_checksum_address(balance_account)}"
+        if balance_account is not None
+        else ""
+    )
+    return f"no BalanceProposed log from executor {executor}{for_account}"
+
+
 def _require_matching_hash(
     proposal: BalanceProposal, *, executor: ChecksumAddress, chain_id: ChainId
 ) -> None:
@@ -122,7 +134,7 @@ def _require_matching_hash(
     if proposal.proposal_hash != _hash_of(
         proposal, executor=executor, chain_id=chain_id
     ):
-        raise ValueError(
+        raise ExternalStateError(
             "proposal hash does not match its own fields: it pairs this value "
             "with another proposal's hash, or it was computed for a different "
             "executor or chain id"
@@ -191,7 +203,9 @@ def _storage_word(raw: bytes) -> int:
     never a value an EVM slot can hold."""
     data = bytes(raw)
     if len(data) > 32:
-        raise ValueError(f"storage word of {len(data)} bytes, more than a 32-byte slot")
+        raise ExternalStateError(
+            f"storage word of {len(data)} bytes, more than a 32-byte slot"
+        )
     return int.from_bytes(data.rjust(32, b"\x00"), "big")
 
 
@@ -230,9 +244,10 @@ def read_external_state(
     hash by identity; ``pending`` is rejected), so the four values never mix
     blocks; the block number is returned so executor reads can be pinned to
     it. Decoding is canonical: a word longer than 32 bytes, an executor word
-    with bits above the address, or a pause word other than 0 or 1, raises ``ValueError`` rather than passing as
-    a plausible value; a zero executor word is ``None`` (no executor deployed),
-    which is a state, while an RPC or decoding failure raises.
+    with bits above the address, or a pause word other than 0 or 1, raises
+    ``ExternalStateError`` rather than passing as a plausible value; a zero
+    executor word is ``None`` (no executor deployed), which is a state, while
+    an RPC or decoding failure raises.
     """
     vault = Web3.to_checksum_address(vault_address)
     read_at, block = _snapshot_block(ctx)
@@ -241,11 +256,11 @@ def read_external_state(
         _storage_word(ctx.get_storage_at(vault, base + i, read_at)) for i in range(4)
     ]
     if words[0] >> 160:
-        raise ValueError(
+        raise ExternalStateError(
             f"malformed executor word in the external-state storage of {vault}"
         )
     if words[3] not in (0, 1):
-        raise ValueError(
+        raise ExternalStateError(
             f"malformed pause flag in the external-state storage of {vault}"
         )
     return ExternalStateVaultState(
@@ -309,24 +324,26 @@ class ExternalStateExecutor(ContractWrapper):
     ) -> ExternalStateExecutor:
         """Resolve the per-vault executor from vault storage and wrap it.
 
-        Raises `ValueError` when no executor is deployed yet (the slot reads
-        zero) rather than returning a wrapper around the zero address, and lets
-        `decode` reject a slot whose high 12 bytes are non-zero (a wrong or
-        corrupt slot, not an address-in-slot).
+        Raises `ExternalStateError` when no executor is deployed yet (the slot
+        reads zero) rather than returning a wrapper around the zero address, and
+        when the slot is not an address (its high 12 bytes are non-zero: a wrong
+        or corrupt slot) or is longer than 32 bytes.
         """
-        # Left-pad so an RPC that strips leading zero bytes still decodes; the
-        # address is the slot's low 20 bytes, `decode` verifies the rest is zero.
-        raw = bytes(
+        word = _storage_word(
             ctx.get_storage_at(
                 Web3.to_checksum_address(vault_address), cls._EXECUTOR_STORAGE_SLOT
             )
-        ).rjust(32, b"\x00")
-        executor = Web3.to_checksum_address(decode(["address"], raw)[0])
-        if executor == ZERO_ADDRESS:
-            raise ValueError(
+        )
+        if word >> 160:
+            raise ExternalStateError(
+                f"malformed executor word in the external-state storage of "
+                f"{vault_address}"
+            )
+        if word == 0:
+            raise ExternalStateError(
                 f"no ExternalStateExecutor deployed for vault {vault_address}"
             )
-        return cls(ctx, executor)
+        return cls(ctx, Web3.to_checksum_address(f"0x{word:040x}"))
 
     def balances(self, balance_account: ChecksumAddress) -> Call[Amount]:
         """Underlying-unit balance the executor tracks for `balance_account`.
@@ -634,11 +651,10 @@ class ExternalStateExecutor(ContractWrapper):
         Accepts receipt-shaped logs (HexBytes) and JSON-RPC / `eth_simulateV1`
         -shaped logs (`0x`-hex strings) alike, so it also decodes rows from an
         event index. Needs no chain access. Raises `ValueError` for a log that
-        is not this event, was not emitted by this executor, carries a hash that
-        is not the hash of its own fields, or whose data is malformed -- and for
-        a call with no chain id available at all; `TypeError` for `data` that is
-        not hex at all, which is the one field whose shape it cannot rule out
-        first.
+        is not this event or was not emitted by this executor, and for a call
+        with no chain id available at all; `ExternalStateError` (also a
+        `ValueError`) for one of ours that carries a hash that is not the hash
+        of its own fields, or whose data is missing or malformed.
 
         Security: two checks, and both are needed. This executor must have
         emitted the log, and `proposal_hash` must be the hash of the log's own
@@ -682,7 +698,7 @@ class ExternalStateExecutor(ContractWrapper):
         """Decode a log whose topic0 is already known to be this event."""
         data = log.get("data")
         if data is None:
-            raise ValueError("BalanceProposed log carries no data")
+            raise ExternalStateError("BalanceProposed log carries no data")
         try:
             # Unpacked in the order `BalanceProposed` declares them; all six
             # are unindexed, so topics carries topic0 alone.
@@ -690,8 +706,8 @@ class ExternalStateExecutor(ContractWrapper):
                 cls._BALANCE_PROPOSED_TYPES,
                 HexBytes(data),
             )
-        except (DecodingError, ValueError) as exc:
-            raise ValueError(f"malformed BalanceProposed data: {exc}") from exc
+        except (DecodingError, ValueError, TypeError) as exc:
+            raise ExternalStateError(f"malformed BalanceProposed data: {exc}") from exc
         return BalanceProposal(
             balance_account=Web3.to_checksum_address(account),
             proposer=Web3.to_checksum_address(proposer),
@@ -750,7 +766,19 @@ class ExternalStateExecutor(ContractWrapper):
         silently skips, and over a range you filtered yourself a foreign log
         means the filter is wrong, not that the row is uninteresting.
         """
-        expected_emitter = self._require_address()
+        found = self._last_balance_proposed(logs, balance_account, chain_id)
+        if found is not None:
+            return found
+        raise ValueError(_no_balance_proposed(self._address, balance_account))
+
+    def _last_balance_proposed(
+        self,
+        logs: Iterable[RawLog],
+        balance_account: ChecksumAddress | None,
+        chain_id: ChainId | None,
+    ) -> BalanceProposal | None:
+        """`find_balance_proposed` without the raise when nothing matches."""
+        self._require_address()
         wanted = (
             Web3.to_checksum_address(balance_account)
             if balance_account is not None
@@ -773,11 +801,7 @@ class ExternalStateExecutor(ContractWrapper):
                 executor=self._address,
                 chain_id=self._require_chain_id(chain_id),
             )
-            return found
-        for_account = f" for account {wanted}" if wanted is not None else ""
-        raise ValueError(
-            f"no BalanceProposed log from executor {expected_emitter}{for_account}"
-        )
+        return found
 
     def mark_nav(
         self,
@@ -840,19 +864,24 @@ class ExternalStateExecutor(ContractWrapper):
         )
         # Verified against the CONFIRMER's chain, which is the one the confirm
         # will be checked on; the wrapper's own ctx may be a third context.
-        proposal = self.find_balance_proposed(
-            propose_receipt["logs"], balance_account, chain_id=confirmer_ctx.chain_id
+        proposal = self._last_balance_proposed(
+            propose_receipt["logs"], balance_account, confirmer_ctx.chain_id
         )
+        if proposal is None:
+            raise ExternalStateError(
+                "the propose receipt records "
+                + _no_balance_proposed(self._address, balance_account)
+            )
         # The receipt is data from the node, so confirm only what we asked for:
         # signing off on a proposal that differs from the one just sent would
         # attest a value this call never chose.
         if proposal.value != value:
-            raise ValueError(
+            raise ExternalStateError(
                 f"proposed {value} but the receipt records {proposal.value}; "
                 "refusing to confirm"
             )
         if proposal.proposer != proposer_address:
-            raise ValueError(
+            raise ExternalStateError(
                 f"proposal was made by {proposal.proposer}, not {proposer_address}; "
                 "refusing to confirm"
             )

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

@@ -16,6 +16,7 @@ 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 (
+    BalanceSlotNotFoundError,
     SimulationError,
     SimulationRunError,
     decode_custom_error,
@@ -751,13 +752,13 @@ def erc20_balance_slot(
     """Find the storage slot of ``token``'s ``balances`` mapping by overriding
     every candidate in one ``eth_simulateV1`` request, using a distinct holder
     per slot, until ``balanceOf`` reflects the override (slot 9 for Circle's
-    FiatToken, 0 for OpenZeppelin ERC20). Raises ``ValueError`` when no slot up
-    to ``max_slot`` answers, which is the case for tokens whose balances are not
-    a plain address-keyed mapping."""
+    FiatToken, 0 for OpenZeppelin ERC20). Raises ``BalanceSlotNotFoundError``
+    when no slot up to ``max_slot`` answers, which is the case for tokens whose
+    balances are not a plain address-keyed mapping, and ``ValueError`` for a
+    negative ``max_slot``."""
     probe = 0x1234_5678_9ABC
-    no_slot = f"no balances mapping slot found for {token} up to {max_slot}"
     if max_slot < 0:
-        raise ValueError(no_slot)
+        raise ValueError(f"max_slot must be non-negative, got {max_slot}")
 
     sim = VaultSimulator(web3, block=block)
     for slot in range(max_slot + 1):
@@ -778,7 +779,9 @@ def erc20_balance_slot(
     for slot in range(max_slot + 1):
         if result.get(f"balance_slot_{slot}") == probe:
             return slot
-    raise ValueError(no_slot)
+    raise BalanceSlotNotFoundError(
+        f"no balances mapping slot found for {token} up to {max_slot}"
+    )
 
 
 def _normalize_call_error(

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev86}/src/ipor_fusion/crosschain/ccip/chainlink.py

@@ -16,6 +16,7 @@ from eth_typing import ChecksumAddress
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.contract import Call, ContractWrapper
 from ipor_fusion.crosschain.contracts import _address
+from ipor_fusion.errors import UnsupportedContractVersionError
 from ipor_fusion.types import ZERO_ADDRESS, MessageId
 
 
@@ -118,9 +119,9 @@ def ccip_token_lane(
     chain_selector: int,
 ) -> CcipTokenLane:
     """Read, on ``router``'s chain, whether a message lane and a ``token`` lane
-    exist towards ``chain_selector``. Seven reads at most. Raises ``ValueError``
-    before reading static config when the OnRamp version has an unverified
-    layout."""
+    exist towards ``chain_selector``. Seven reads at most. Raises
+    ``UnsupportedContractVersionError`` before reading static config when the
+    OnRamp version has an unverified layout."""
     router_wrapper = CcipRouter(ctx, router)
     if not router_wrapper.is_chain_supported(chain_selector).call():
         return CcipTokenLane(chain_selector, message_lane=False)
@@ -128,7 +129,7 @@ def ccip_token_lane(
     on_ramp_wrapper = CcipOnRamp(ctx, on_ramp)
     on_ramp_version = on_ramp_wrapper.type_and_version().call()
     if on_ramp_version not in _SUPPORTED_ON_RAMP_VERSIONS:
-        raise ValueError(
+        raise UnsupportedContractVersionError(
             f"unsupported CCIP OnRamp version {on_ramp_version!r} at {on_ramp}; "
             "ccip_token_lane supports OnRamp 2.0.0"
         )

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

@@ -35,8 +35,9 @@ _HEADERS = {"Accept": "application/json", "User-Agent": "ipor-fusion-sdk"}
 
 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. Also a
-    LookupError: the result looked up is not there (yet)."""
+    yet, the indexers were unreachable, or they answered something unreadable);
+    the message says which, per indexer. Also a LookupError: the result looked
+    up is not there (yet)."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -63,7 +64,10 @@ def fetch_verifier_result(
     timeout: float = 15.0,
 ) -> VerifierResult:
     """``GET /v1/verifierresults/<messageId>`` from the first indexer that has
-    a result; raises :class:`VerifierResultUnavailable` otherwise."""
+    a readable result; raises :class:`VerifierResultUnavailable` otherwise. An
+    indexer whose answer cannot be read (not JSON, a missing or mistyped field,
+    invalid hex or address, a result for another message) is skipped like one
+    that is unreachable."""
     if len(message_id) != 32:
         raise ValueError("message_id must be 32 bytes")
     hex_id = "0x" + message_id.hex()
@@ -79,26 +83,57 @@ def fetch_verifier_result(
         if response.status_code != 200:
             reasons.append(f"{base}: HTTP {response.status_code}")
             continue
-        results = (response.json() or {}).get("results") or []
-        if not results:
+        try:
+            result = _parse_answer(response.json(), message_id, base)
+        except (KeyError, IndexError, TypeError, ValueError) as exc:
+            reasons.append(f"{base}: malformed answer ({type(exc).__name__}: {exc})")
+            continue
+        if result is None:
             reasons.append(f"{base}: no result yet")
             continue
-        result = results[0]["verifierResult"]
-        return VerifierResult(
-            message_id=MessageId(bytes.fromhex(result["message_id"][2:])),
-            ccv_addresses=tuple(
-                Web3.to_checksum_address(a) for a in result["message_ccv_addresses"]
-            ),
-            ccv_data=bytes.fromhex(result["ccv_data"][2:]),
-            executor=Web3.to_checksum_address(result["message_executor_address"]),
-            message=result["message"],
-            indexer=base,
-        )
+        return result
     raise VerifierResultUnavailable(
         f"no verifier result for {hex_id}: " + "; ".join(reasons)
     )
 
 
+def _hex_bytes(value: Any) -> bytes:
+    if not isinstance(value, str) or not value.startswith("0x"):
+        raise ValueError(f"not 0x-prefixed hex: {value!r}")
+    return bytes.fromhex(value[2:])
+
+
+def _parse_answer(
+    body: Any, message_id: MessageId, indexer: str
+) -> VerifierResult | None:
+    """The first result of an indexer's JSON answer; ``None`` when it has none.
+    Anything else it cannot read raises a builtin error, reported by the caller
+    as a malformed answer."""
+    if not isinstance(body, Mapping):
+        raise TypeError("answer is not a JSON object")
+    results = body.get("results")
+    if not results:
+        return None
+    result = results[0]["verifierResult"]
+    served_id = _hex_bytes(result["message_id"])
+    if served_id != message_id:
+        raise ValueError(f"result is for message 0x{served_id.hex()}")
+    message = result["message"]
+    if not isinstance(message, Mapping):
+        raise TypeError("message is not an object")
+    ccvs = result["message_ccv_addresses"]
+    if not isinstance(ccvs, list) or not ccvs:
+        raise ValueError("message_ccv_addresses is not a non-empty array")
+    return VerifierResult(
+        message_id=MessageId(served_id),
+        ccv_addresses=tuple(Web3.to_checksum_address(a) for a in ccvs),
+        ccv_data=_hex_bytes(result["ccv_data"]),
+        executor=Web3.to_checksum_address(result["message_executor_address"]),
+        message=message,
+        indexer=indexer,
+    )
+
+
 def manual_execution(
     off_ramp: CcipOffRamp,
     encoded_message: bytes,

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev86}/src/ipor_fusion/crosschain/ccip/quote.py

@@ -18,6 +18,7 @@ from web3.types import BlockIdentifier
 
 from ipor_fusion.core.contract import Call
 from ipor_fusion.core.simulation import VaultSimulator
+from ipor_fusion.errors import SimulationError
 
 #: Selector of ``CcipInsufficientNativeFeeBalance(uint256 balance, uint256 required)``.
 INSUFFICIENT_NATIVE_FEE_SELECTOR: bytes = keccak(
@@ -40,8 +41,8 @@ def quote_ccip_native_fee(
     ``payer`` is the contract that pays: the factory for ``requestDispatcher``,
     the executor for a supply or command (``from_`` is then the alpha sending
     the vault's ``execute``), the dispatcher for a return. The call must be
-    valid at ``block`` up to the fee check; a revert before it, or a call that
-    sends no message, raises ``ValueError``.
+    valid at ``block`` up to the fee check: a revert before it raises
+    ``SimulationError`` and a call that sends no message ``ValueError``.
     """
     simulator = VaultSimulator(web3, alpha=from_, block=block)
     simulator.with_state_override(payer, balance=hex(0))
@@ -55,6 +56,8 @@ def quote_ccip_native_fee(
         raise ValueError(
             "the call succeeded with the payer at zero balance: it sends no CCIP message"
         )
-    raise ValueError(
-        f"the call reverted before the CCIP fee check: {result.revert_reason}"
+    raise SimulationError(
+        f"the call reverted before the CCIP fee check: {result.revert_reason}",
+        label="quote",
+        revert_reason=result.revert_reason,
     )

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

@@ -148,16 +148,17 @@ def get_revert_reason(web3: Web3, tx_hash: TxHash, receipt: TxReceipt) -> str |
 class IporFusionError(Exception):
     """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.
+    The rule the SDK follows everywhere: 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;
+    an argument of the wrong type raises ``TypeError`` and an unknown name in a
+    mapping-style lookup ``KeyError``. 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``; others keep the builtin base
+    their raise sites had before 4.0 (``ValueError``, ``RuntimeError``,
+    ``LookupError``) so existing handlers still catch them.
     """
 
 
@@ -191,6 +192,44 @@ class UnsupportedVaultVersionError(IporFusionError, ValueError):
     """
 
 
+class UnsupportedContractVersionError(IporFusionError, ValueError):
+    """A contract reports a version whose layout the SDK has not verified, so
+    reading it further could misread its storage or return data.
+
+    Also a ValueError, the type these failures had before 4.0.
+    """
+
+
+class HyperCoreValuationError(IporFusionError, ValueError):
+    """The HyperCore NAV cannot be valued: a precompile read failed, the
+    oracle prices no granted spot token or its price overflows, the vault
+    grants a perp dex bitmap the valuation does not support, or the NAV is
+    negative (where the balance fuse reverts).
+
+    Also a ValueError, the type these failures had before 4.0.
+    """
+
+
+class ExternalStateError(IporFusionError, ValueError):
+    """The external-state market's on-chain data is not usable: the vault's
+    storage holds no executor or a malformed word, an executor's
+    ``BalanceProposed`` log is malformed or carries a hash that is not the hash
+    of its own fields, or a propose receipt does not record the proposal that
+    was sent.
+
+    Also a ValueError, the type these failures had before 4.0.
+    """
+
+
+class BalanceSlotNotFoundError(IporFusionError, ValueError):
+    """No candidate storage slot of a token answers as its ``balances``
+    mapping: its balances are not a plain address-keyed mapping, or the
+    mapping lies beyond the slots searched.
+
+    Also a ValueError, the type this failure had before 4.0.
+    """
+
+
 class LogScanError(IporFusionError):
     """An `eth_getLogs` scan could not cover its whole block range.
 
@@ -252,7 +291,8 @@ class SimulationRunError(IporFusionError, RuntimeError):
 
 
 class SimulationError(IporFusionError):
-    """A simulated call reverted; raised by ``SimulationResult.raise_for_failure``."""
+    """A simulated call reverted; raised by ``SimulationResult.raise_for_failure``
+    and by ``quote_ccip_native_fee`` for a revert before the CCIP fee check."""
 
     def __init__(
         self,

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev86}/src/ipor_fusion/mcp/server.py

@@ -633,10 +633,7 @@ def market_meta_morpho(
         vault_address: MetaMorpho V1 or Vault V2 address.
         chain_id: EVM chain ID.
     """
-    try:
-        info = fetch_vault(Web3.to_checksum_address(vault_address), chain_id)
-    except MorphoApiError as exc:
-        raise ValueError(str(exc)) from exc
+    info = fetch_vault(Web3.to_checksum_address(vault_address), chain_id)
     payload = build_meta_morpho_json(info, chain_id)
     return MetaMorphoVaultResponse.model_validate(payload)