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

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

@@ -220,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
@@ -232,3 +234,85 @@ 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. 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
+  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).
+- 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.dev78 → ipor_fusion-4.0.0.dev86}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev78"
+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.dev78 → ipor_fusion-4.0.0.dev86}/src/ipor_fusion/__init__.py

@@ -173,16 +173,22 @@ from ipor_fusion.dependency_graph import (
 )
 from ipor_fusion.errors import (
     CUSTOM_ERRORS,
+    BalanceSlotNotFoundError,
     ContractNotFoundError,
+    CrosschainDiscoveryError,
     EmptyCallResultError,
+    ExternalStateError,
+    HyperCoreValuationError,
     IporFusionError,
     LogScanError,
     LogSourceUnavailable,
     MorphoMarketNotFoundError,
     NotPlasmaVaultError,
     SimulationError,
+    SimulationRunError,
     TransactionError,
     UnsupportedChainError,
+    UnsupportedContractVersionError,
     UnsupportedVaultVersionError,
     decode_custom_error,
     get_revert_reason,
@@ -715,8 +721,12 @@ __all__ = [
     "format_market_label",
     "market_name",
     "DOCS",
+    "BalanceSlotNotFoundError",
     "ContractNotFoundError",
+    "CrosschainDiscoveryError",
     "EmptyCallResultError",
+    "ExternalStateError",
+    "HyperCoreValuationError",
     "IporFusionError",
     "LogScanError",
     "LogSourceUnavailable",
@@ -724,7 +734,9 @@ __all__ = [
     "NotPlasmaVaultError",
     "TransactionError",
     "SimulationError",
+    "SimulationRunError",
     "UnsupportedChainError",
+    "UnsupportedContractVersionError",
     "UnsupportedVaultVersionError",
     "CUSTOM_ERRORS",
     "decode_custom_error",

{ipor_fusion-4.0.0.dev78 → ipor_fusion-4.0.0.dev86}/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.dev78 → ipor_fusion-4.0.0.dev86}/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.dev78 → 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.dev78 → ipor_fusion-4.0.0.dev86}/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.dev78 → ipor_fusion-4.0.0.dev86}/src/ipor_fusion/core/simulation.py

@@ -15,7 +15,12 @@ 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 (
+    BalanceSlotNotFoundError,
+    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 +575,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 +602,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"
             )
@@ -747,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):
@@ -774,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.dev78 → 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.dev78 → ipor_fusion-4.0.0.dev86}/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,11 @@ 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, 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)
@@ -61,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()
@@ -77,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,