ipor-fusion 4.0.0.dev159__tar.gz → 4.0.0.dev164__tar.gz

{ipor_fusion-4.0.0.dev159 → ipor_fusion-4.0.0.dev164}/AGENTS.md

@@ -449,11 +449,13 @@ schema. Adding a field to `build_vault_info_json` (or a `fusion market` document
 means adding it to its TypedDict, to the matching model (with a default for
 back-compat) and to the `_full_vault_info_dict` fixture;
 `TestTypedDocumentsMirrorModels` in `test_mcp_models.py` holds every TypedDict to
-its model block by block. The model keeps `dict[str, Any]` where the schema is
-deliberately loose (`substrates`, `deployment`, `share_price`, `dependency_graph`,
-`position_breakdown`): the SDK types those blocks, the schema does not validate
-their inner keys. The substrate entries stay open-ended on both sides
-(`SubstrateEntryJson`, `dict[str, str | bool]`): each decoder adds its own fields.
+its model block by block, a union block (`deployment`, `position_breakdown`,
+`source_detail`) shape by shape. Every block is a model; a block whose optional keys
+the producer omits is a `_Sparse` model, which dumps only the fields it was given,
+so the key stays absent rather than null. `TestNestedBlocksDumpVerbatim` pins that
+the typed blocks dump exactly what the producer wrote. The substrate entries stay
+open-ended on both sides (`SubstrateEntryJson`, `dict[str, str | bool]`): each
+decoder adds its own fields.
 
 ## Domain rules (verified against the contracts)
 

{ipor_fusion-4.0.0.dev159 → ipor_fusion-4.0.0.dev164}/MIGRATION_4.md

@@ -741,6 +741,28 @@ fuse's `eid=` take it (`LayerZeroEid(30101)`). CCIP chain selectors are
 (`CcipChainSelector(4949039107694359620)`). `ZERO_ADDRESS` is a `ChecksumAddress`
 (same value).
 
+**Simulation.** The `VaultSimulator` override methods name the keys `eth_simulateV1`
+accepts instead of taking `**Any`; the keys and the request they produce are
+unchanged. `with_state_override(address, **overrides)` takes `AccountOverride` keys
+(`balance`, `nonce`, `code`, `movePrecompileToAddress`: `0x` hex strings; `state`,
+`stateDiff`: `0x` slot to `0x` word), and a `StateOverrideProvider` returns
+`Mapping[str, AccountOverride]`. `with_block_override(**fields)` takes
+`BlockOverrides` keys (`number`, `time`, `gasLimit`, `baseFeePerGas`, `blobBaseFee`:
+an `int`, sent as hex, or a hex string; `feeRecipient`, `prevRandao`: strings) and
+raises `TypeError` for any other value type (`withdrawals` is not supported).
+Both TypedDicts are exported from `ipor_fusion`. A misspelled key or an `int` balance
+now fails type checking instead of reaching the node:
+
+```python
+sim.with_state_override(holder, balance=hex(10**18), nonce=hex(0))
+sim.with_block_override(gasLimit=30_000_000)
+sim.with_state_override_provider(lambda n: {oracle: {"code": code_hex}})
+```
+
+`add_transaction(transaction)` takes web3's `TxParams`, the shape
+`Call.build_transaction` returns; a node-shaped dict carrying `input` instead of `data`
+is still accepted at run time.
+
 **HyperCore (preview).** The fuses, `HyperCoreSubstrates`, `HyperCoreReader`,
 `read_hypercore_transfer_snapshot` and the helpers `system_address`,
 `precompile_index_of`, `perp_dex_of`, `is_native_perp_asset`, `is_hip3_asset` take the
@@ -774,6 +796,11 @@ except as listed under [Behavior changes](#behavior-changes)): `chain_id` fields
 string). Calling an MCP tool function
 directly from Python takes `ChainId`. Their amount, decimals and time fields stay
 `int`: they are JSON output models, and the SDK values above fit them unchanged.
+The nested blocks that were `dict[str, Any]` are models now (`deployment`,
+`share_price`, `links`, `dependency_graph`, a balance fuse's `position_breakdown`, an
+oracle node's `source_detail`, the Morpho `asset`, `adapters`, `caps`,
+`liquidity_adapter`, `public_allocator` and `allocations`): read them by attribute
+(`result.caps[0].loan_token`, not `["loan_token"]`).
 
 ## Typed JSON documents
 
@@ -820,15 +847,31 @@ that only some entries carry is `NotRequired` (a balance fuse's `pct_of_total` a
   `ipor_fusion` and `ipor_fusion.readers`). Narrow by a key before reading a
   kind-specific one: `if detail is not None and "aggregator" in detail:
   detail["description"]`.
-- Event `args` are typed per event kind: `ExternalStateEvent.args` is
-  `ExternalStateEventArgs` and `HyperCoreEvent.args` is `HyperCoreEventArgs`, a union
-  of one TypedDict per event (`ExternalStateUnpausedArgs`,
-  `HyperCoreDepositFuseEnterArgs`, ...; `EXTERNAL_STATE_EVENT_ARGS` /
-  `HYPERCORE_EVENT_ARGS` map an event name to its shape). Values carry nominal types
-  (`Amount`, `MarketId`, `FuseAddress`, `HyperCoreTokenIndex`, `PayloadHash`, web3's
-  `Timestamp`, ...). `event.args["signer"]` no longer type-checks on its own: narrow
-  with a key test (`if "signer" in event.args:`). `HyperCoreEvent.fuse` is a
-  `FuseAddress | None`.
+- Decoded events are discriminated unions. `ExternalStateEvent` and `HyperCoreEvent`
+  are type aliases over one frozen dataclass per event (`ExternalStateUnpausedEvent`,
+  `HyperCoreDepositFuseEnterEvent`, ...), each with `name: Literal["<event>"]` and
+  `args` typed as that event's TypedDict (`ExternalStateUnpausedArgs`, ...). Comparing
+  `name` narrows the event and its `args`, with no key test:
+
+  ```python
+  for event in external_state_events(receipt):
+      if event.name == "ExternalStateUnpaused":
+          event.args["signer"]  # ChecksumAddress
+  match hc_event:
+      case HyperCoreDepositFuseEnterEvent(args=args):
+          args["evmAsset"]
+  ```
+
+  Without that comparison `event.args["signer"]` does not type-check.
+  `isinstance(x, ExternalStateEvent)` still works (the alias is a union); the events
+  are no longer built positionally (`ExternalStateEvent(...)` is not a class: build
+  the event's own class with keywords, its `name` is preset).
+  `EXTERNAL_STATE_EVENT_CLASSES` / `HYPERCORE_EVENT_CLASSES` map an event name to its
+  class; they replace `EXTERNAL_STATE_EVENT_ARGS` / `HYPERCORE_EVENT_ARGS`, which are
+  removed. An event's args TypedDict is its class's `args` annotation:
+  `typing.get_type_hints(EXTERNAL_STATE_EVENT_CLASSES[name])["args"]`. Values carry nominal types (`Amount`, `MarketId`, `FuseAddress`,
+  `HyperCoreTokenIndex`, `PayloadHash`, web3's `Timestamp`, ...), and
+  `HyperCoreEvent.fuse` is a `FuseAddress | None` on every event.
 - `RawLog` (the log shape `ExternalStateExecutor.parse_balance_proposed` /
   `find_balance_proposed` accept) is `Mapping[str, object]`, not `Mapping[str, Any]`;
   a web3 `LogReceipt` still fits it.
@@ -838,6 +881,22 @@ that only some entries carry is `NotRequired` (a balance fuse's `pct_of_total` a
 These apply to every caller, type-checked or not. Changes described in full above
 are listed with a link.
 
+- **MCP `outputSchema` describes every nested block.** The tool output is
+  byte-identical; the schemas of `vault_info`, `vault_oracle_mapping`,
+  `market_morpho_blue` and `market_meta_morpho` replace each free-form object with
+  the block's own definition: `links` (`VaultLinks`), `deployment`
+  (`DeploymentModel` or `DeploymentErrorModel`), `share_price` (`SharePriceModel`),
+  `dependency_graph` (`DependencyGraphModel`), `position_breakdown` (a list of
+  `MorphoBreakdownEntry` or of `AaveBreakdownEntry`, amounts `BreakdownAmount`),
+  substrate entries (string or boolean values), `source_detail` (`ChainlinkDetail`,
+  `DualXrefDetail`, `Erc4626Detail`, `MorphoFeedDetail` or
+  `MiddlewareFallbackDetail`), a supplying vault's `asset` (`MorphoVaultAssetModel`)
+  and the MetaMorpho `asset`, `liquidity_adapter` / `adapters`, `caps`,
+  `public_allocator` (with `flow_caps`) and `allocations`. Fixed-shape blocks now declare their
+  required and optional fields and reject unknown keys (`additionalProperties:
+  false`), as the documents always wrote them; substrate entries and keyed maps
+  (`flow_caps`, `edges`, `update_reach`) stay open with typed values.
+
 - **Vault reads are pinned to one block**: every read of `fetch_vault_data`, log
   scans included, runs at the resolved block; see
   [Vault reads and validation](#vault-reads-and-validation).

{ipor_fusion-4.0.0.dev159 → ipor_fusion-4.0.0.dev164}/PKG-INFO

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

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

{ipor_fusion-4.0.0.dev159 → ipor_fusion-4.0.0.dev164}/src/ipor_fusion/__init__.py

@@ -72,6 +72,8 @@ from ipor_fusion.core.plasma_vault import (
 )
 from ipor_fusion.core.rewards_manager import RewardsManager, VestingData
 from ipor_fusion.core.simulation import (
+    AccountOverride,
+    BlockOverrides,
     SimulatedCallResult,
     SimulationObservation,
     SimulationResult,
@@ -314,43 +316,68 @@ from ipor_fusion.fuses import (
     system_address,
 )
 from ipor_fusion.fuses.external_state_events import (
-    EXTERNAL_STATE_EVENT_ARGS,
+    EXTERNAL_STATE_EVENT_CLASSES,
     EXTERNAL_STATE_EVENT_SPECS,
     EXTERNAL_STATE_EVENTS,
     EXTERNAL_STATE_TOPICS,
     ExternalStateAssetRescuedArgs,
+    ExternalStateAssetRescuedEvent,
+    ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent,
+    ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent,
     ExternalStateBigChangeDetectedArgs,
+    ExternalStateBigChangeDetectedEvent,
     ExternalStateCustodianTimestampUpdatedArgs,
     ExternalStateEvent,
     ExternalStateEventArgs,
     ExternalStateEventSpec,
     ExternalStateExecutorArgs,
+    ExternalStateExecutorCreatedEvent,
+    ExternalStateExecutorDeployedEvent,
     ExternalStateOperationArgs,
+    ExternalStateOperationFuseEnterEvent,
+    ExternalStateOperationFuseExitEvent,
     ExternalStateTotalBalanceUpdatedArgs,
     ExternalStateUnpausedArgs,
+    ExternalStateUnpausedEvent,
     decode_external_state_event,
     external_state_event_name,
     external_state_events,
 )
 from ipor_fusion.fuses.hypercore_events import (
-    HYPERCORE_EVENT_ARGS,
+    HYPERCORE_EVENT_CLASSES,
     HyperCoreActionEnqueuedArgs,
+    HyperCoreActionEnqueuedEvent,
     HyperCoreActionSettledArgs,
+    HyperCoreActionSettledEvent,
     HyperCoreBuilderFeeFuseEnterArgs,
+    HyperCoreBuilderFeeFuseEnterEvent,
     HyperCoreCancelByCloidArgs,
     HyperCoreCancelByOidArgs,
+    HyperCoreCancelFuseCancelByCloidEvent,
+    HyperCoreCancelFuseCancelByOidEvent,
     HyperCoreDepositFuseEnterArgs,
+    HyperCoreDepositFuseEnterEvent,
     HyperCoreEventArgs,
     HyperCoreMarginFuseEnterArgs,
+    HyperCoreMarginFuseEnterEvent,
     HyperCoreObserverSetChangedArgs,
+    HyperCoreObserverSetChangedEvent,
     HyperCoreObserverSetProposedArgs,
+    HyperCoreObserverSetProposedEvent,
     HyperCoreOrderFuseEnterArgs,
+    HyperCoreOrderFuseEnterEvent,
     HyperCoreRecoveryExecutedArgs,
+    HyperCoreRecoveryExecutedEvent,
     HyperCoreRecoveryProposedArgs,
+    HyperCoreRecoveryProposedEvent,
     HyperCoreReportedActionSettledArgs,
+    HyperCoreReportedActionSettledEvent,
     HyperCoreReportSubmittedArgs,
+    HyperCoreReportSubmittedEvent,
     HyperCoreSendFuseSendAssetArgs,
+    HyperCoreSendFuseSendAssetEvent,
     HyperCoreSendFuseSpotSendArgs,
+    HyperCoreSendFuseSpotSendEvent,
 )
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.market_info import (
@@ -589,7 +616,16 @@ __all__ = [
     "EXTERNAL_STATE_EVENTS",
     "EXTERNAL_STATE_TOPICS",
     "ExternalStateEvent",
-    "EXTERNAL_STATE_EVENT_ARGS",
+    "EXTERNAL_STATE_EVENT_CLASSES",
+    "ExternalStateBigChangeDetectedEvent",
+    "ExternalStateBalanceFuseLastCustodianTimestampUpdatedEvent",
+    "ExternalStateBalanceFuseLastTotalBalanceUpdatedEvent",
+    "ExternalStateUnpausedEvent",
+    "ExternalStateAssetRescuedEvent",
+    "ExternalStateExecutorCreatedEvent",
+    "ExternalStateOperationFuseEnterEvent",
+    "ExternalStateOperationFuseExitEvent",
+    "ExternalStateExecutorDeployedEvent",
     "ExternalStateAssetRescuedArgs",
     "ExternalStateBigChangeDetectedArgs",
     "ExternalStateCustodianTimestampUpdatedArgs",
@@ -606,7 +642,23 @@ __all__ = [
     "HYPERCORE_EVENTS",
     "HYPERCORE_EVENT_SPECS",
     "HyperCoreEvent",
-    "HYPERCORE_EVENT_ARGS",
+    "HYPERCORE_EVENT_CLASSES",
+    "HyperCoreDepositFuseEnterEvent",
+    "HyperCoreMarginFuseEnterEvent",
+    "HyperCoreSendFuseSpotSendEvent",
+    "HyperCoreSendFuseSendAssetEvent",
+    "HyperCoreOrderFuseEnterEvent",
+    "HyperCoreCancelFuseCancelByOidEvent",
+    "HyperCoreCancelFuseCancelByCloidEvent",
+    "HyperCoreBuilderFeeFuseEnterEvent",
+    "HyperCoreActionEnqueuedEvent",
+    "HyperCoreActionSettledEvent",
+    "HyperCoreReportedActionSettledEvent",
+    "HyperCoreReportSubmittedEvent",
+    "HyperCoreObserverSetProposedEvent",
+    "HyperCoreObserverSetChangedEvent",
+    "HyperCoreRecoveryProposedEvent",
+    "HyperCoreRecoveryExecutedEvent",
     "HyperCoreActionEnqueuedArgs",
     "HyperCoreActionSettledArgs",
     "HyperCoreBuilderFeeFuseEnterArgs",
@@ -649,6 +701,8 @@ __all__ = [
     "MULTICALL3_ADDRESS",
     "VaultSimulator",
     "StateOverrideProvider",
+    "AccountOverride",
+    "BlockOverrides",
     "SimulationObservation",
     "SimulationResult",
     "SimulatedCallResult",

{ipor_fusion-4.0.0.dev159 → ipor_fusion-4.0.0.dev164}/src/ipor_fusion/core/context.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import copy
 import logging
 import threading
-from typing import Any
 
 from eth_account import Account
 from eth_typing import ChecksumAddress, HexStr
@@ -453,7 +452,7 @@ class InFlightLimit:
 def _slot_middleware(slots: threading.BoundedSemaphore) -> type[Web3Middleware]:
     class InFlightLimitMiddleware(Web3Middleware):
         def wrap_make_request(self, make_request: MakeRequestFn) -> MakeRequestFn:
-            def limited(method: RPCEndpoint, params: Any) -> RPCResponse:
+            def limited(method: RPCEndpoint, params: object) -> RPCResponse:
                 with slots:
                     return make_request(method, params)
 
@@ -463,7 +462,7 @@ def _slot_middleware(slots: threading.BoundedSemaphore) -> type[Web3Middleware]:
             self, make_batch_request: MakeBatchRequestFn
         ) -> MakeBatchRequestFn:
             def limited(
-                requests_info: list[tuple[RPCEndpoint, Any]],
+                requests_info: list[tuple[RPCEndpoint, object]],
             ) -> list[RPCResponse] | RPCResponse:
                 with slots:
                     return make_batch_request(requests_info)

{ipor_fusion-4.0.0.dev159 → ipor_fusion-4.0.0.dev164}/src/ipor_fusion/core/contract.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, Generic, TypeVar, cast
+from typing import Generic, TypeVar, cast
 
 from eth_abi import decode, encode
 from eth_typing import ChecksumAddress
@@ -60,7 +60,7 @@ class Call(Generic[T_co]):
             raise ValueError("cannot map a write-only Call without output types")
         decoder = self.decoder
 
-        def mapped(value: Any) -> U:
+        def mapped(value: object) -> U:
             decoded = decoder(value) if decoder is not None else cast(T_co, value)
             return transform(decoded)
 
@@ -101,7 +101,7 @@ class Call(Generic[T_co]):
         if not self.output_types:
             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
+        single: object = values[0] if len(values) == 1 else values
         if self.decoder is not None:
             return self.decoder(single)
         return cast(T_co, single)
@@ -148,7 +148,7 @@ class ContractWrapper:
     def _view(
         self,
         signature: str,
-        *args: Any,
+        *args: object,
         output_types: list[str],
         decoder: Callable[..., T] | None = None,
     ) -> Call[T]:
@@ -159,11 +159,11 @@ class ContractWrapper:
             decoder=decoder,
         )
 
-    def _write(self, signature: str, *args: Any) -> Call[None]:
+    def _write(self, signature: str, *args: object) -> Call[None]:
         return Call(to=self._address, data=_encode_calldata(signature, *args))
 
 
-def _encode_calldata(signature: str, *args: Any) -> bytes:
+def _encode_calldata(signature: str, *args: object) -> bytes:
     selector = function_signature_to_4byte_selector(signature)
     types = _parse_param_types(signature)
     return selector + encode(types, list(args)) if types else selector

{ipor_fusion-4.0.0.dev159 → ipor_fusion-4.0.0.dev164}/src/ipor_fusion/core/plasma_vault.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections.abc import Callable, Sequence
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
-from typing import Any, TypeVar
+from typing import TypeVar, cast
 
 from eth_abi import decode, encode
 from eth_typing import ChecksumAddress
@@ -91,19 +91,21 @@ def _market_id_list_decoder(value: list) -> list[MarketId]:
 _BALANCE_OF_SELECTOR = function_signature_to_4byte_selector("balanceOf()")
 
 
+def _read_result_data(result: tuple[bytes]) -> bytes:
+    """``ReadResult.data``, undecoded."""
+    return bytes(result[0])
+
+
 def _universal_read_decoder(
-    output_types: list[str] | None, decoder: Callable[..., Any] | None
-) -> Callable[[tuple], Any]:
-    """Unwrap ``ReadResult.data`` and, given ``output_types``, decode it the way
-    `Call.decode` decodes a view's return data."""
-
-    def _decode(result: tuple) -> Any:
-        payload = bytes(result[0])
-        if output_types is None:
-            return payload
-        values = tuple(decode(output_types, payload))
-        single: Any = values[0] if len(values) == 1 else values
-        return decoder(single) if decoder is not None else single
+    output_types: list[str], decoder: Callable[..., T] | None
+) -> Callable[[tuple[bytes]], T]:
+    """Unwrap ``ReadResult.data`` and decode it the way `Call.decode` decodes a
+    view's return data."""
+
+    def _decode(result: tuple[bytes]) -> T:
+        values = tuple(decode(output_types, _read_result_data(result)))
+        single: object = values[0] if len(values) == 1 else values
+        return decoder(single) if decoder is not None else cast(T, single)
 
     return _decode
 
@@ -265,7 +267,7 @@ class PlasmaVault(ContractWrapper):
             target,
             data,
             output_types=["(bytes)"],
-            decoder=_universal_read_decoder(None, None),
+            decoder=_read_result_data,
         )
 
     def universal_read_decoded(