ipor-fusion 4.0.0.dev244__tar.gz → 4.0.0.dev249__tar.gz

{ipor_fusion-4.0.0.dev244 → ipor_fusion-4.0.0.dev249}/MIGRATION_4.md

@@ -20,8 +20,9 @@ the details, and each change is described once, in its section.
 >   checker cannot see the calls made through them;
 > - run the reads against a provider, not only the test suite.
 
-Work through these in order; each is what breaks first at run time after the one
-before it is fixed.
+Work through these in order. Removed imports fail first, at import; the rest is
+the recommended order, roughly what fails next at run time (a positional option
+such as `Web3Context.from_url(url, key)` can fail before any wrapper is built).
 
 1. **Removed and renamed imports fail first, at import.** The preview features
    left the top level: crosschain names import from `ipor_fusion.crosschain`,
@@ -47,8 +48,9 @@ before it is fixed.
    raises `AttributeError`. See [Vault reads and validation](#vault-reads-and-validation).
 5. **The vault read is one snapshot.** `fetch_vault_data(ctx, vault, *, block=None,
    lending=True, metadata=True)` takes the vault address and the chain from `ctx`;
-   `validate_vault_state(state)` and `build_vault_info_json(data, *,
-   resolve_name=None)` are pure. See [Vault reads and validation](#vault-reads-and-validation).
+   `validate_vault_state(state)` reads nothing, and `build_vault_info_json(data, *,
+   resolve_name=None)` reads no vault state (contract names come from
+   `resolve_name`, the deployment age from the wall clock). See [Vault reads and validation](#vault-reads-and-validation).
 6. **Simulations return typed observations.** `sim.observe("label", call)` raises
    `TypeError`: `read = sim.observe(call, label="label")` returns a
    `SimulationObservation`, read as `read.value` after `run()`;
@@ -282,7 +284,8 @@ The vault read is one pinned snapshot, and the chain is always the context's:
   `VaultState` also provides `vault`, `chain_id`, `market_balances`, `erc20` and the
   queue's `shares_to_release_assets`.
 - `build_vault_info_json(data, *, resolve_name=None)` renders from the snapshot and
-  reads nothing; the chain and its label come from `data.chain_id`. Without
+  reads no vault state (`resolve_name`, which may look names up, and the deployment
+  age, computed from the wall clock, are its only other inputs); the chain and its label come from `data.chain_id`. Without
   `resolve_name` it names no contract (see
   [Contract cache and request limit](#contract-cache-and-request-limit)).
 - `fetch_deployment_info(ctx, vault, *, api_key=None)` and
@@ -301,14 +304,16 @@ The vault read is one pinned snapshot, and the chain is always the context's:
 
 **Public API.** 4.0 declares it: `ipor_fusion.__all__`, which now also exports the
 names earlier reachable only by module path (`FusionFactory`, `FusionInstance`,
-`fetch_market`, `resolve_token_symbol`, the crosschain codecs, ...). Import from
+`fetch_market`, `resolve_token_symbol`, ...); the preview features are exported only
+from their subpackages (see below). Import from
 `ipor_fusion`: a module path outside the README's list (*Public API and stability*)
 still works but is internal. Every project type a public signature or field uses is
 exported too, among them `AaveV3PositionBreakdown`, `AaveV3ReserveTokens`,
-`AccountRequest`, `StateOverrideProvider`, `TransferDirection` and the validation
+`AccountRequest`, `StateOverrideProvider` and the validation
 vocabulary `Severity`, `Verdict` and `Check`. Also new: `InFlightLimit` (see
-[Contract cache and request limit](#contract-cache-and-request-limit)) and
-`log_bytes`, the hex-or-bytes log field helper the crosschain decoders use.
+[Contract cache and request limit](#contract-cache-and-request-limit)), and in
+`ipor_fusion.crosschain` `log_bytes`, the hex-or-bytes log field helper the
+crosschain decoders use.
 
 **Crosschain fuse encoders moved.** The crosschain market encoders moved from
 `ipor_fusion.fuses.crosschain` into the crosschain package, and
@@ -391,9 +396,9 @@ the modules are internal.
 - `MORPHO_BLUE_ADDRESS`: use `morpho_blue_address(chain_id)`. `BLOCK_EXPLORER_URLS`,
   `MORPHO_BLUE_ADDRESSES`, `AAVE_V3_POOL` and `explorer.SUPPORTED_CHAINS` are
   internal. Import `CHAIN_NAMES`, `CHAIN_NAME_TO_ID`, `SUPPORTED_CHAIN_IDS`,
-  `GET_LOGS_RANGE_HINTS`, `PUBLIC_ALLOCATOR_ADDRESSES`, `HYPERCORE_PENDING_READERS`,
-  `HYPEREVM_CHAIN_ID` and `HYPERCORE_MARKET` from `ipor_fusion` (the HyperCore ones
-  also from `ipor_fusion.readers`).
+  `GET_LOGS_RANGE_HINTS`, `PUBLIC_ALLOCATOR_ADDRESSES` and `HYPEREVM_CHAIN_ID` from
+  `ipor_fusion` (`HYPEREVM_CHAIN_ID` also from `ipor_fusion.readers`), and
+  `HYPERCORE_PENDING_READERS` and `HYPERCORE_MARKET` from `ipor_fusion.hypercore`.
 - `read_erc20_holdings`: the holdings are `VaultData.erc20`.
 - `ExternalStateExecutor.mark_nav` and `NavMark`: send `propose_balance` and
   `confirm_balance` from separate custodians, then
@@ -626,7 +631,10 @@ typed client with pyright's `reportArgumentType`. Other fields keep their types
 the SDK returns already carry their type and go back in unwrapped.
 
 The SDK's own types are importable from `ipor_fusion` (and the public module
-`ipor_fusion.types`), as are `USDC_TOKEN_INDEX` and `hip3_action_asset`. Third-party
+`ipor_fusion.types`), except the preview features' ids, which come from their
+subpackages: the crosschain ids (`CommandId`, ...) from `ipor_fusion.crosschain`, the
+HyperCore ids (`HyperCoreAsset`, ...), `USDC_TOKEN_INDEX` and `hip3_action_asset`
+from `ipor_fusion.hypercore`. Third-party
 types are not re-exported: `ChecksumAddress` and `HexAddress` come from `eth_typing`,
 and `BlockIdentifier`, `Timestamp` and `TxParams` from `web3.types`. The wrappers
 label values; they do not validate byte widths or address spelling.
@@ -890,8 +898,10 @@ oracle node's `source_detail`, the Morpho `asset`, `adapters`, `caps`,
 ## Typed JSON documents
 
 The JSON document builders return `TypedDict`s instead of `dict[str, Any]`; the
-documents themselves (keys, values, order, the MCP schemas) are unchanged, so
-untyped code needs none of this section.
+typing itself changes no document (keys, values, order); the documents' own 4.0
+changes are listed under [Behavior changes](#behavior-changes) (the validation
+document, reconciliation and lending-health fields, MCP null keys, addresses,
+supply cap).
 
 | Builder | Returns |
 |---|---|
@@ -968,8 +978,9 @@ class. 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. Every name is importable from `ipor_fusion` and
-from `ipor_fusion.fuses`.
+`FuseAddress | None` on every event. The ExternalState names are importable from
+`ipor_fusion` and `ipor_fusion.fuses`; the HyperCore ones (preview) only from
+`ipor_fusion.hypercore`.
 
 The two families share one input contract. `decode_external_state_event(log)` and
 `decode_hypercore_event(log)` take a web3 receipt log or a raw JSON-RPC / indexer
@@ -991,15 +1002,20 @@ These apply to every caller, type-checked or not. Changes described in full abov
 are listed with a link.
 
 - **The CLI and the MCP tools take the same arguments.**
-  - **MCP inputs:** `chain_id` and `block_number` are optional and omitted means
-    auto-detected / latest. The `0` sentinel is gone, and `0` is now rejected with
-    an error naming the argument to omit (it is never read as chain or block 0);
-    a client that passed `0` must omit the argument instead. The CLI refuses
-    `--block-number 0` and `--chain-id 0` the same way. `server_info(changelog_since=)` is `server_info(since=)` as in
+  - **MCP inputs:** the vault tools' `chain_id` and every `block_number` are
+    optional and omitted means auto-detected / latest; `market_morpho_blue` and
+    `market_meta_morpho` still require a positive `chain_id`. The `0` sentinel is
+    gone: an optional `0` is rejected with an error naming the argument to omit (it
+    is never read as chain or block 0), so a client that passed `0` omits the
+    argument instead; the market tools' required `chain_id` rejects `0` too and
+    needs the real chain id. The CLI refuses `--block-number 0` and `--chain-id 0`
+    the same way. `server_info(changelog_since=)` is `server_info(since=)` as in
     `fusion changelog --since`, and `vault_oracle_mapping` takes `max_depth` like
     `--max-depth`.
-  - **Chain auto-detection:** both surfaces use the saved vault's chain, else the
-    chain of the only configured provider. The CLI used only the saved vault.
+  - **Chain auto-detection:** the vault commands and tools use the saved vault's
+    chain, else the chain of the only configured provider (the CLI used only the
+    saved vault); `vault_add` uses the only configured provider, and
+    `config_set_provider` asks the provider (`eth_chainId`).
   - **CLI options:** every `--block-number` rejects a negative block, and
     `fusion market morpho-blue --block` is `--block-number` (`--block` still
     works).
@@ -1104,8 +1120,8 @@ are listed with a link.
   and small or empty markets could be off by orders of magnitude: expect materially
   different numbers where they were wrong.
 
-- **MCP `outputSchema` describes every nested block.** The tool output is
-  byte-identical; the schemas of `vault_info`, `vault_oracle_mapping`,
+- **MCP `outputSchema` describes every nested block.** This change alone keeps the
+  tool output byte-identical (the other changes in this list still apply); 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`),
@@ -1192,4 +1208,6 @@ are listed with a link.
   Both stay unhashable (`__hash__` is `None`, as before). The freeze is shallow:
   the `logs` / `calls` lists themselves can still be mutated.
 - Saved config entries are checksummed when loaded; the MCP `vault_add` tool rejects
-  a value that is not an address.
+  a value that is not an address. The MCP vault tools accept a vault address as 3.x
+  did (any letter case, with or without `0x`, surrounding whitespace) and normalize
+  it before the strict SDK parser; only the SDK's `parse_*` functions are strict.

{ipor_fusion-4.0.0.dev244 → ipor_fusion-4.0.0.dev249}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev244
+Version: 4.0.0.dev249
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -412,7 +412,8 @@ release; adding one does not.
 - **Third-party types** are not re-exported: import `ChecksumAddress` and
   `HexAddress` from `eth_typing`, and `BlockIdentifier`, `Timestamp` and `TxParams`
   from `web3.types`. The SDK's own types (`ChainId`, `Amount`, `PlasmaVaultAddress`,
-  ...) come from `ipor_fusion` or `ipor_fusion.types`.
+  ...) come from `ipor_fusion` or `ipor_fusion.types`; a preview feature's ids
+  (`CommandId`, `HyperCoreAsset`, ...) come from its subpackage.
 
 `tests/test_public_api.py` snapshots every `__all__` and the names each public
 module keeps by path, so a change to the surface is a deliberate, reviewed edit.

{ipor_fusion-4.0.0.dev244 → ipor_fusion-4.0.0.dev249}/README.md

@@ -364,7 +364,8 @@ release; adding one does not.
 - **Third-party types** are not re-exported: import `ChecksumAddress` and
   `HexAddress` from `eth_typing`, and `BlockIdentifier`, `Timestamp` and `TxParams`
   from `web3.types`. The SDK's own types (`ChainId`, `Amount`, `PlasmaVaultAddress`,
-  ...) come from `ipor_fusion` or `ipor_fusion.types`.
+  ...) come from `ipor_fusion` or `ipor_fusion.types`; a preview feature's ids
+  (`CommandId`, `HyperCoreAsset`, ...) come from its subpackage.
 
 `tests/test_public_api.py` snapshots every `__all__` and the names each public
 module keeps by path, so a change to the surface is a deliberate, reviewed edit.

{ipor_fusion-4.0.0.dev244 → ipor_fusion-4.0.0.dev249}/pyproject.toml

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

{ipor_fusion-4.0.0.dev244 → ipor_fusion-4.0.0.dev249}/src/ipor_fusion/mcp/server.py

@@ -59,6 +59,7 @@ from ipor_fusion.readers.morpho import MorphoReader, morpho_blue_address
 from ipor_fusion.readers.oracle_mapping import build_oracle_mapping
 from ipor_fusion.types import (
     ChainId,
+    PlasmaVaultAddress,
     parse_morpho_market_id,
     parse_plasma_vault_address,
 )
@@ -100,6 +101,12 @@ def _resolve_provider(cfg: FusionConfig, chain_id: ChainId) -> str:
     )
 
 
+def _vault_arg(raw: str) -> PlasmaVaultAddress:
+    """A vault address as a tool caller sends it: surrounding whitespace, a
+    missing ``0x`` and any letter case are accepted, as in 3.x."""
+    return parse_plasma_vault_address(Web3.to_checksum_address(raw.strip()))
+
+
 def _resolve_chain_id(
     cfg: FusionConfig, vault_address: str, chain_id: ChainId | None
 ) -> ChainId:
@@ -210,12 +217,12 @@ def vault_info(
     etc.).
     """
     cfg = load_config()
-    chain_id = _resolve_chain_id(cfg, vault_address, chain_id)
+    checksum = _vault_arg(vault_address)
+    chain_id = _resolve_chain_id(cfg, checksum, chain_id)
     # Fail fast (before any RPC) on chains the vault tooling can't handle;
     # UnsupportedChainError doubles as ValueError so FastMCP surfaces it.
     ensure_supported_chain(chain_id)
     ctx, effective_block = _build_ctx(cfg, chain_id, block_number)
-    checksum = parse_plasma_vault_address(vault_address)
 
     # Cheap single-call probe: raises the typed ContractNotFoundError /
     # NotPlasmaVaultError ("not a vault" in both revert and empty-return
@@ -257,10 +264,10 @@ def vault_validate(
     consistent. It reads about as much as vault_info and takes about as long.
     """
     cfg = load_config()
-    chain_id = _resolve_chain_id(cfg, vault_address, chain_id)
+    checksum = _vault_arg(vault_address)
+    chain_id = _resolve_chain_id(cfg, checksum, chain_id)
     ensure_supported_chain(chain_id)
     ctx, effective_block = _build_ctx(cfg, chain_id, block_number)
-    checksum = parse_plasma_vault_address(vault_address)
 
     # Same cheap probe as vault_info: "not a vault" fails before the fetch.
     resolve_access_manager(ctx, checksum)
@@ -323,12 +330,12 @@ def vault_role_accounts(
     """
     cfg = load_config()
     role_id = None if role is None else Roles.resolve(role)
-    chain_id = _resolve_chain_id(cfg, vault_address, chain_id)
+    checksum = _vault_arg(vault_address)
+    chain_id = _resolve_chain_id(cfg, checksum, chain_id)
     # Fail fast (before any RPC) on chains the vault tooling is not
     # validated on.
     ensure_supported_chain(chain_id)
     ctx, _ = _build_ctx(cfg, chain_id, block_number)
-    checksum = parse_plasma_vault_address(vault_address)
 
     access_manager = resolve_access_manager(ctx, checksum)
     accounts = (
@@ -408,12 +415,12 @@ def vault_oracle_mapping(
     'events'). Historical blocks require an archive node.
     """
     cfg = load_config()
-    chain_id = _resolve_chain_id(cfg, vault_address, chain_id)
+    checksum = _vault_arg(vault_address)
+    chain_id = _resolve_chain_id(cfg, checksum, chain_id)
     # The asset-source event replay scans logs from block 0 — fail fast
     # (before any RPC) on chains the vault tooling is not validated on.
     ensure_supported_chain(chain_id)
     ctx, _ = _build_ctx(cfg, chain_id, block_number)
-    checksum = parse_plasma_vault_address(vault_address)
 
     # The event-replay fallback and the output both need a concrete block
     # number, so resolve "latest" up front and pin the context to it.
@@ -464,7 +471,7 @@ def vault_add(
         address: Vault address (required).
         label: Human-readable label (fetched from on-chain name() if empty).
     """
-    checksum = parse_plasma_vault_address(address)
+    checksum = _vault_arg(address)
     cfg = load_config()
 
     if chain_id is None:

{ipor_fusion-4.0.0.dev244 → ipor_fusion-4.0.0.dev249}/tests/test_mcp_server.py

@@ -26,6 +26,7 @@ from ipor_fusion.mcp.models import (
     WithdrawManagerDetails,
 )
 from ipor_fusion.mcp.server import (
+    _vault_arg,
     config_set_etherscan_key,
     config_set_provider,
     config_show,
@@ -39,6 +40,7 @@ from ipor_fusion.mcp.server import (
     vault_oracle_mapping,
     vault_remove,
     vault_role_accounts,
+    vault_validate,
 )
 from ipor_fusion.morpho_api import (
     MorphoApiError,
@@ -1082,3 +1084,77 @@ class TestMarketMetaMorpho:
     def test_unknown_vault_errors(self, _fetch):
         with pytest.raises(MorphoApiError, match="not found"):
             market_meta_morpho(vault_address=_VAULT, chain_id=1)
+
+
+class TestVaultAddressArgument:
+    """Tool callers send addresses as 3.x accepted them; the server normalizes
+    before the strict SDK parser."""
+
+    VAULT = "0x43ee0243ea8cf02f7087d8b16c8d2007cc9c7ca2"
+
+    @pytest.mark.parametrize(
+        "raw",
+        [
+            VAULT,
+            VAULT.upper().replace("0X", "0x"),
+            VAULT[2:],
+            f"  {VAULT}  ",
+            Web3.to_checksum_address(VAULT),
+        ],
+    )
+    def test_accepts_any_spelling(self, raw: str):
+        assert _vault_arg(raw) == Web3.to_checksum_address(self.VAULT)
+
+    @pytest.mark.parametrize("raw", ["", "0x1234", "not an address", "0x" + "g" * 40])
+    def test_rejects_non_addresses(self, raw: str):
+        with pytest.raises(ValueError):
+            _vault_arg(raw)
+
+
+class TestVaultAddressResolvesSavedChain:
+    """Every spelling the tools accept finds the saved vault's chain."""
+
+    @staticmethod
+    def _config(providers: list[int]):
+        from ipor_fusion.cli.config_store import FusionConfig, VaultEntry
+
+        return FusionConfig(
+            providers={str(c): "https://rpc.example.com" for c in providers},
+            vaults=[VaultEntry(address=_SAVED_VAULT, label="Test", chain_id=1)],
+        )
+
+    @pytest.mark.parametrize(
+        "spelling", [f"  {_SAVED_VAULT}  ", _SAVED_VAULT[2:], _SAVED_VAULT.upper()]
+    )
+    @pytest.mark.parametrize(
+        "tool", [vault_info, vault_validate, vault_role_accounts, vault_oracle_mapping]
+    )
+    def test_saved_chain_wins_over_other_providers(self, tool, spelling: str):
+        seen: list[int] = []
+
+        def stop(_cfg, chain_id, _block):
+            seen.append(chain_id)
+            raise RuntimeError("stop")
+
+        with (
+            patch(
+                "ipor_fusion.mcp.server.load_config",
+                autospec=True,
+                return_value=self._config([1, 8453]),
+            ),
+            patch("ipor_fusion.mcp.server._build_ctx", autospec=True, side_effect=stop),
+            pytest.raises(RuntimeError, match="stop"),
+        ):
+            tool(spelling)
+        assert seen == [1]
+
+    def test_missing_saved_chain_provider_is_reported_not_substituted(self):
+        with (
+            patch(
+                "ipor_fusion.mcp.server.load_config",
+                autospec=True,
+                return_value=self._config([8453]),
+            ),
+            pytest.raises(ValueError, match="No provider for chain 1"),
+        ):
+            vault_info(f"  {_SAVED_VAULT[2:]}  ")