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

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev88}/AGENTS.md

@@ -218,12 +218,14 @@ the lifecycle matrix follows that.
   `simulation` (`VaultSimulator`, eth_simulateV1, `erc20_balance_slot` and ERC-20 balance
   overrides), `oracle`, `fusion_factory`,
   `external_state_executor` (NAV marks for market 50), `erc20`, `fuse_action`
-  (`FuseAction`), `address` (`_validate_not_zero_address`). `core` imports neither
+  (`FuseAction`), `fuse` (the `Fuse` base, `StakeFuse`, the shared validators and
+  substrate packers), `address` (`_validate_not_zero_address`). `core` imports neither
   `fuses` nor `crosschain` (`tests/test_sdk_layering.py`)
 - `fuses/` — per-protocol fuse encoders (aave_v3, async_action, compound_v3, crosschain/,
   erc4626, euler_v2, external_state, fluid_instadapp, gearbox_v3, merkl, morpho, ramses_v2,
-  uniswap_v3, universal, `events.py`); `base.py` holds `Fuse` and the
-  shared validators and re-exports `FuseAction` and `ZERO_ADDRESS` (from `types`)
+  uniswap_v3, universal, `events.py`); `base.py` re-exports the `core/fuse.py` base and validators,
+  `FuseAction` and `ZERO_ADDRESS` (from `types`). A fuse is a value: equality and
+  hash cover its class and every attribute it stores
 - `crosschain/` — crosschain Plasma Vaults (executor on the hub chain, dispatcher at
   the same address on each spoke chain), split like the contracts: shared `messages`
   (`Command`, `MsgType`, envelopes), `contracts` (wrapper bases), `transport`
@@ -276,7 +278,9 @@ or examples.
 - `Call[T]` (`core/contract.py`): every `ContractWrapper` method (one per
   Solidity function) returns a `Call` instead of executing. `.call()` runs
   `eth_call` and decodes to `T`; `.send()` signs and submits, returning a
-  `TxReceipt`; `.calldata` hands the bytes to an external signer;
+  `TxReceipt`; `.calldata` hands the bytes to an external signer (a wrapper
+  built with `ctx=None`, e.g. `PlasmaVault(None, address)`, builds calldata
+  offline; there is no separate encoder factory);
   `.build_transaction()` / `Web3Context.estimate_gas` preview without signing.
   A `Call` without `output_types` (a write) raises on `.call()`. The same
   `Call` feeds `VaultSimulator.observe`, so reads, sends and simulations share

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

@@ -93,7 +93,7 @@ The Uniswap V3 / Ramses V2 position events' `version`, `sender` and `recipient`
 `quote_ccip_native_fee(block=)` and `OracleMappingReader.asset_source_events` take a
 `BlockIdentifier`.
 
-**Address roles.** `PlasmaVault(ctx, address)`, `PlasmaVault.encoder(address)`,
+**Address roles.** `PlasmaVault(ctx, address)` (`ctx` may be `None`, see below),
 `validate_vault`, `fetch_deployment_info`, the HyperCore, lending-health and
 oracle-mapping readers, `read_external_state`, `VaultSimulator(vault=)`,
 `CrosschainSimulator`, crosschain discovery, the hub-manager inputs
@@ -194,6 +194,35 @@ are `ProposalHash`; `ExternalStateEvent.transaction_hash` is a `TxHash`.
 except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
 `MarketId`. Calling an MCP tool function directly from Python takes `ChainId`.
 
+**Offline wrappers.** `ContractWrapper.encoder()` (and the `PlasmaVault` /
+`AccessManager` overrides) is gone. Every wrapper constructor takes
+`ctx: Web3Context | None`, so build an offline wrapper with the normal
+constructor and an address: `PlasmaVault(None, vault)`, `ERC20(None, token)`,
+`FusionFactory(None, factory)`, `LegacyPriceOracleMiddleware(None, oracle,
+Decimals(8))`. The address is required (there is no zero-address placeholder) and
+subclass parameters stay required, so the wrapper is fully initialized:
+`.encoder()` skipped the constructor, and a legacy oracle built that way failed to
+decode `get_asset_price`. `.calldata` still needs no context; `.call()`, `.send()`,
+`.build_transaction()` and `.estimate_gas()` raise `ValueError` until one is passed
+to them, and a method that reads the chain itself (log scans such as
+`get_balance_fuses` or `get_pending_requests`, `withdraw_manager_address`,
+`Multicall3.aggregate` / `try_aggregate`, the Aave V3 and Morpho position reads)
+raises `ValueError("Web3Context required: <wrapper> at <address> ...")` instead of
+an `AttributeError` on `None`. `ExternalStateExecutor` still refuses the zero
+address for its hash and event readers.
+
+| 3.x | 4.0 |
+|---|---|
+| `PlasmaVault.encoder(vault)` | `PlasmaVault(None, vault)` |
+| `ERC20.encoder()` (no address) | `ERC20(None, token)`: pass the real address |
+| `Cls.__new__(Cls)` + `_ctx` / `_address` | `Cls(None, address)` |
+
+**Fuse base.** `Fuse`, `StakeFuse` and the shared validators and substrate packers
+live in `ipor_fusion.core.fuse`; `ipor_fusion.fuses.base`, `ipor_fusion.fuses` and
+`ipor_fusion` re-export them, so existing imports keep working. Fuse equality and
+hash now cover every attribute a fuse stores, not only its class and address (see
+[Behavior changes](#behavior-changes)).
+
 **Moved, still importable.** `FuseAction` lives in `ipor_fusion.core.fuse_action` and
 `ZERO_ADDRESS` in `ipor_fusion.types`; both are re-exported from
 `ipor_fusion.fuses.base` and `FuseAction` from `ipor_fusion`. The CLI's internal
@@ -202,6 +231,12 @@ except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
 
 ## Behavior changes
 
+- Two fuses are equal (and hash alike) only when they have the same class and the
+  same stored state. `StakeFuse` subclasses (`GearboxStakeFuse`,
+  `FluidInstadappStakingFuse`) with the same fuse address but different
+  `staking_address` were equal and collapsed in a set or dict key; they are now
+  distinct. A custom `Fuse` subclass is compared on its instance attributes, which
+  must be hashable; drop an `__eq__` / `__hash__` override that only added them.
 - The MCP `vault_info` document reports the vault address checksummed (the CLI
   already did).
 - `SubstrateInfo.address` is `None` instead of `""` for a substrate without an
@@ -238,15 +273,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 +314,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.dev88}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev83
+Version: 4.0.0.dev88
 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.dev88}/examples/advanced_euler_v2_credit_market_base.py

@@ -261,12 +261,12 @@ def clone_args() -> dict:
 def unsigned_clone_calldata() -> bytes:
     """Unsigned creation calldata (selector + ABI-encoded args) for the deploy.
 
-    Built with a ctx-less encoder, so it needs no provider. Hand these bytes to
+    Built on a wrapper with ctx=None, so it needs no provider. Hand these bytes to
     an external signer / multisig instead of calling ``.send()``. NOTE: the owner
     encoded here is the simulation ``OWNER`` (a throwaway EOA) -- set your real
     owner in ``clone_args()`` before deploying, or the vault is owned by it.
     """
-    return FusionFactory.encoder(BASE_FUSION_FACTORY).clone(**clone_args()).calldata
+    return FusionFactory(None, BASE_FUSION_FACTORY).clone(**clone_args()).calldata
 
 
 def market_substrates() -> list[bytes]:

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev88}/examples/advanced_euler_v2_looping_arbitrum.py

@@ -208,7 +208,7 @@ def clone_args() -> dict:
 
 
 def unsigned_clone_calldata() -> bytes:
-    return FusionFactory.encoder(ARBITRUM_FUSION_FACTORY).clone(**clone_args()).calldata
+    return FusionFactory(None, ARBITRUM_FUSION_FACTORY).clone(**clone_args()).calldata
 
 
 def euler_market_substrates() -> list[bytes]:
@@ -260,7 +260,7 @@ def enable_euler_actions() -> list[FuseAction]:
 def build_swap_action() -> FuseAction:
     """Swap the borrowed USDC through Uniswap V3 and require flash repayment."""
     transfer_data = (
-        ERC20.encoder(ARBITRUM_USDC)
+        ERC20(None, ARBITRUM_USDC)
         .transfer(UNISWAP_UNIVERSAL_ROUTER, BORROW_USDC)
         .calldata
     )

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev88}/examples/external_state_margin_leg_base.py

@@ -438,12 +438,12 @@ def clone_args() -> dict:
 def unsigned_clone_calldata() -> bytes:
     """Unsigned creation calldata (selector + ABI-encoded args) for the deploy.
 
-    Built with a ctx-less encoder, so it needs no provider. Hand these bytes to
+    Built on a wrapper with ctx=None, so it needs no provider. Hand these bytes to
     an external signer / multisig instead of calling ``.send()``. NOTE: the owner
     encoded here is the simulation ``OWNER`` (a throwaway EOA) -- set your real
     owner in ``clone_args()`` before deploying, or the vault is owned by it.
     """
-    return FusionFactory.encoder(BASE_FUSION_FACTORY).clone(**clone_args()).calldata
+    return FusionFactory(None, BASE_FUSION_FACTORY).clone(**clone_args()).calldata
 
 
 def market_substrates() -> list[bytes]:
@@ -534,9 +534,9 @@ def market_substrates() -> list[bytes]:
 def venue_transfer_calldata(amount: Amount) -> bytes:
     """``USDC.transfer(VENUE_DEPOSIT_ADDRESS, amount)`` calldata, run from the executor.
 
-    Encoded with a ctx-less ERC20 wrapper -- pure bytes, no chain access.
+    Encoded with an ERC20 wrapper built with ctx=None -- pure bytes, no chain access.
     """
-    return ERC20.encoder(BASE_USDC).transfer(VENUE_DEPOSIT_ADDRESS, amount).calldata
+    return ERC20(None, BASE_USDC).transfer(VENUE_DEPOSIT_ADDRESS, amount).calldata
 
 
 def build_enter_action(amount: Amount) -> FuseAction:

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev88}/examples/simple_aave_v3_supply_base.py

@@ -201,12 +201,12 @@ def clone_args() -> dict:
 def unsigned_clone_calldata() -> bytes:
     """Unsigned creation calldata (selector + ABI-encoded args) for the deploy.
 
-    Built with a ctx-less encoder, so it needs no provider. Hand these bytes to
+    Built on a wrapper with ctx=None, so it needs no provider. Hand these bytes to
     an external signer / multisig instead of calling ``.send()``. NOTE: the owner
     encoded here is the simulation ``OWNER`` (a throwaway EOA) -- set your real
     owner in ``clone_args()`` before deploying, or the vault is owned by it.
     """
-    return FusionFactory.encoder(BASE_FUSION_FACTORY).clone(**clone_args()).calldata
+    return FusionFactory(None, BASE_FUSION_FACTORY).clone(**clone_args()).calldata
 
 
 def build_supply_action(amount: Amount) -> FuseAction:

{ipor_fusion-4.0.0.dev83 → ipor_fusion-4.0.0.dev88}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev83"
+version = "4.0.0.dev88"
 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.dev88}/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.dev88}/src/ipor_fusion/core/access.py

@@ -1,6 +1,5 @@
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Self
 
 from eth_abi import decode
 from eth_abi.exceptions import InsufficientDataBytes
@@ -68,17 +67,13 @@ def _role_status_decoder(values: tuple) -> RoleStatus:
 class AccessManager(ContractWrapper):
     """Manages role-based access control for PlasmaVault operations."""
 
-    def __init__(self, ctx: Web3Context, address: AccessManagerAddress):
+    def __init__(self, ctx: Web3Context | None, address: AccessManagerAddress):
         super().__init__(ctx, address)
 
     @property
     def address(self) -> AccessManagerAddress:
         return AccessManagerAddress(self._address)
 
-    @classmethod
-    def encoder(cls, address: AccessManagerAddress | None = None) -> Self:  # type: ignore[override]
-        return super().encoder(address)
-
     def grant_role(
         self, role_id: RoleId | Roles, account: ChecksumAddress, execution_delay: Period
     ) -> Call[None]:
@@ -161,7 +156,7 @@ class AccessManager(ContractWrapper):
             if predicate(role_id, account):
                 candidates[(role_id, account)] = None
 
-        statuses = Multicall3(self._ctx).aggregate(
+        statuses = Multicall3(self._require_ctx()).aggregate(
             [self.has_role(role_id, account) for role_id, account in candidates]
         )
         return [
@@ -180,7 +175,7 @@ class AccessManager(ContractWrapper):
             Web3.keccak(text="RoleGranted(uint64,address,uint32,uint48,bool)")
         ).to_0x_hex()
         return list(
-            self._ctx.get_logs(
+            self._require_ctx().get_logs(
                 contract_address=self._address, topics=[event_signature_hash]
             )
         )

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

@@ -129,18 +129,19 @@ class Call(Generic[T]):
         return actual
 
 
-_ENCODER_PLACEHOLDER_ADDRESS: ChecksumAddress = cast(
-    ChecksumAddress, "0x0000000000000000000000000000000000000000"
-)
-
-
 class ContractWrapper:
     """Base wrapper. Subclasses expose one method per Solidity function that
     returns a `Call[T]` — never executing eagerly. Callers chain `.call()` for
     reads, `.send()` for writes, or hand the `Call` to `VaultSimulator`.
+
+    `ctx` may be ``None`` for offline use, e.g. external-signer flows (HTTP
+    signing service, multisig) that only need `Call.calldata`: every builder
+    works, and `.call()` / `.send()` on its Calls raise until a context is
+    passed to them. Methods that read the chain themselves (log scans, storage
+    reads, batched reads) raise `ValueError` on such a wrapper.
     """
 
-    def __init__(self, ctx: Web3Context, address: ChecksumAddress):
+    def __init__(self, ctx: Web3Context | None, address: ChecksumAddress):
         self._ctx = ctx
         self._address = Web3.to_checksum_address(address)
 
@@ -148,30 +149,13 @@ class ContractWrapper:
     def address(self) -> ChecksumAddress:
         return self._address
 
-    @classmethod
-    def encoder(cls, address: ChecksumAddress | None = None):
-        """Build a ctx-less wrapper: every builder method, no Web3Context.
-
-        Named for its first use, external-signer flows (HTTP signing service,
-        multisig), which only need `Call.calldata` — the actual `to` and `ctx`
-        are filled in by the signer. It serves any builder that needs no chain
-        access, decoders included. Calling `.call()` or `.send()` on a Call
-        produced this way raises (no ctx).
-
-        Pass `address` unless `.calldata` really is the only consumer. The
-        encoding ignores it, but a builder that reads `self._address`
-        semantically — matching it against a log's emitter, say, or folding it
-        into a hash — runs against the placeholder zero address without one,
-        and so rejects input that is genuinely the caller's.
-        """
-        instance = cls.__new__(cls)
-        instance._ctx = None
-        instance._address = (
-            Web3.to_checksum_address(address)
-            if address is not None
-            else _ENCODER_PLACEHOLDER_ADDRESS
-        )
-        return instance
+    def _require_ctx(self) -> Web3Context:
+        if self._ctx is None:
+            raise ValueError(
+                f"Web3Context required: {type(self).__name__} at {self._address} "
+                "was built without one (ctx=None), which only builds calldata."
+            )
+        return self._ctx
 
     def _view(
         self,