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

{ipor_fusion-4.0.0.dev240 → ipor_fusion-4.0.0.dev249}/AGENTS.md

@@ -28,7 +28,7 @@ uv run ruff format ./                                         # format (CI runs
 uv run ruff check ./                                          # lint: bandit S, C901 max-complexity 10, PLR limits
 uv run pyright                                                # types, basic mode, src + tests + examples + scripts
 uv run pytest                                                 # all tests + coverage gate (fail_under = 98, mcp/ included)
-uv run pytest -m "cli or mcp" --no-cov                        # fast offline subset
+uv run pytest -m "cli or mcp" --no-cov                        # CLI/MCP subset (the full suite is mostly offline too)
 uv run pytest --run-readiness -m readiness --no-cov -rA       # opt-in live Ethereum-hub POC checks
 uv run python scripts/crosschain_readiness.py --output /tmp/crosschain-readiness.json # live Arbitrum/HyperEVM report
 uv run pytest tests/test_fuse_encoding.py -k aave --no-cov    # single file / test
@@ -59,9 +59,9 @@ everything else is `sdk`). Most `sdk` tests are offline too: the suite with no
 provider set still clears the coverage gate.
 Integration tests (`test_simulate_*`, `test_vault_info_onchain_*`) run against
 live RPCs via `eth_simulateV1`, no Docker or Anvil (`ANVIL_WALLET` is just a
-named address constant). They auto-skip unless `ETHEREUM_PROVIDER_URL`,
-`BASE_PROVIDER_URL` and `ARBITRUM_PROVIDER_URL` are set (`.env` is loaded via
-python-dotenv) and the provider supports `eth_simulateV1`. Every such gate goes
+named address constant). Each skips unless the provider it needs
+(`ETHEREUM_PROVIDER_URL`, `BASE_PROVIDER_URL` or `ARBITRUM_PROVIDER_URL`; `.env` is
+loaded via python-dotenv) is set and supports `eth_simulateV1`. Every such gate goes
 through `tests/_live.py` (`provider_url`, `archive_context`, `unavailable`): it
 skips locally and fails when the source is named in `IPOR_FUSION_REQUIRE_LIVE`
 (comma-separated env var names, `GITHUB` for the Solidity mirrors). CI
@@ -84,9 +84,11 @@ executors from the creation code they store; `source` builds a factory pair from
 that revision (the fuses are compiled from it); a checkout without `node_modules` also
 needs `IPOR_FUSION_FOUNDRY_REMAPPINGS` for OpenZeppelin. `test_crosschain_ccip_events.py`
 mirrors the CCIP event registry from a checkout at its own `CONTRACTS_REVISION`.
-`test_solidity_compiler.py` uses `IPOR_FUSION_CONTRACTS_DIR` for a local contracts
-checkout and optional `IPOR_FUSION_FOUNDRY_REMAPPINGS`. These tests skip when their
-external prerequisites are unavailable.
+`test_solidity_compiler.py` unit-tests that compiler helper (`tests/_foundry.py`)
+offline, with `forge` and `git` mocked. The checkout-based tests above skip when their
+external prerequisites are unavailable. `test_hypercore_live.py`,
+`test_hypercore_deployment.py` and `test_hypercore_simulation.py` need
+`HYPEREVM_PROVIDER_URL` as well.
 `test_simulate_crosschain_lifecycle.py` drives the mainnet POC deployment from
 Ethereum to every spoke on every transport through `CrosschainLane` and
 `CrosschainSimulator`; the fixtures (`Chain`, `Deployment`, `Spoke`, pinned
@@ -110,8 +112,9 @@ the deployed runtimes, and `tests/_hypercore_model.py` answers those addresses t
 tests prove EVM validation under supplied Core state. `test_hypercore_simulation.py`
 runs one vault cycle; `test_simulate_crosschain_hypercore.py` runs the composed flow
 (v3 canary hub → CCIP → the market-55 vault → a trade → recall → claim) and holds every
-CCIP delivery to its route gas limit. Both skip without the source directory and both
-RPCs.
+CCIP delivery to its route gas limit. Both skip without the source directory;
+`test_hypercore_simulation.py` also needs `HYPEREVM_PROVIDER_URL`, the composed flow
+`ARBITRUM_PROVIDER_URL` as well.
 `test_crosschain_readiness.py` checks the Ethereum-hub POC's live bridge and IPOR
 preconditions. Its `readiness` marker requires `--run-readiness`: ordinary runs
 exclude it even with `-m sdk`. Known HyperEVM gaps are non-strict xfails restricted
@@ -243,8 +246,10 @@ the lifecycle matrix follows that.
   snapshots), `vault_positions.py` (Morpho/Aave position breakdowns and their token
   prices) and `vault_erc20.py` (the ERC20_VAULT_BALANCE holdings);
   `vault_info.py` — `build_vault_info_json(data)`, the `fusion vault info --json`
-  document rendered from the snapshot alone (contract names via an injected
-  `resolve_name`) and typed block by block (`VaultInfoJson` and its nested
+  document rendered from the snapshot, plus three inputs that are not chain state at
+  its block: contract names through the injected `resolve_name` (Etherscan I/O on a
+  pool), the deployment fields the caller writes into the snapshot from
+  `fetch_deployment_info`, and `age_days` from the wall clock; typed block by block (`VaultInfoJson` and its nested
   TypedDicts), and `health_check_lists`; `explorer.py` Etherscan V2 (single endpoint, needs API key);
   `cache.py` the `ContractCache` protocol (`get`/`put` of immutable facts keyed
   `CacheKey(chain_id, address, field)`), `FileContractCache` (one JSON file, atomic
@@ -284,13 +289,16 @@ the lifecycle matrix follows that.
   uniswap_v3, universal); `events.py` (`extract_events`, `abi_value` and the raw-log
   event decoder both event families share), `external_state_event_decoding.py` and
   `hypercore_event_decoding.py` (the ExternalState and HyperCore event specs, classes
-  and decoders; internal modules, the names are exported from `ipor_fusion.fuses`);
+  and decoders; internal modules, the ExternalState names are exported from
+  `ipor_fusion.fuses`, the HyperCore ones from `ipor_fusion.hypercore`), `hypercore.py`
+  (the HyperCore fuses, market 55);
   `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`
+  (`Command`, `MsgType`, envelopes), `logs` (`log_bytes` and the raw-log field
+  helpers the decoders share), `contracts` (wrapper bases), `transport`
   (`CrosschainTransport` seam), `lane` (`CrosschainLane`: one executor/dispatcher pair
   driven without knowing its transport; it carries its transport's fuse classes and
   the keeper's attestation helpers), `discovery` (`discover_deployment` reads the
@@ -304,6 +312,8 @@ the lifecycle matrix follows that.
   `ccip/`, each with its wire codecs, executor/dispatcher/factory wrappers, transport
   and lane; `ccip/chainlink` reads Chainlink's Router, OnRamp, TokenAdminRegistry and
   token pool (`ccip_token_lane`: is there a lane, does the token travel on it);
+  `ccip/quote` (`quote_ccip_native_fee`: the exact native fee of a send, from a
+  simulation with the payer's balance at zero);
   `ccip/events` decodes the executor/dispatcher/factory events by topic (one
   registry, mirrored from the v3 source; the v2 pair emits a subset of it);
   `ccip/chainlink` also wraps the 2.0 OffRamp, verifier resolver and committee verifier
@@ -314,19 +324,27 @@ the lifecycle matrix follows that.
   mirroring `contracts/fuses/crosschain/`; they build on `core/fuse.py`, so the
   dependency direction is `core` <- `crosschain` and `fuses/` holds no crosschain code
   (neither package imports the other). Names mirror the Solidity contracts and
-  libraries. Adding a transport: a new subpackage, its encoders in `crosschain/fuses/`
-  and one `LANES` entry. Layering: the encoders import the wire codecs and wrappers;
+  libraries. Adding a transport: a new subpackage, its encoders in `crosschain/fuses/`,
+  one `LANES` entry and its probe in `discovery.detect_transport` (CCIP answers
+  `transportKind()`, Stargate a non-zero `STARGATE_POOL()`). Layering: the encoders import the wire codecs and wrappers;
   lanes, discovery, transports and the simulator import the encoders.
   `ipor_fusion.crosschain` exports the whole surface (encoders, lanes, discovery,
   transports, simulator). A package `__init__` runs before its modules and the
   encoders import `ccip.contracts` / `stargate.layerzero`, so `.ccip` and `.stargate`
-  export only their codecs and wrappers. `tests/test_crosschain_layering.py` pins this:
+  export only what sits below the encoders: their codecs and wrappers, and for
+  `.ccip` also the Chainlink readers (`ccip_token_lane`), the fee quote
+  (`quote_ccip_native_fee`) and the indexer client (`fetch_verifier_result`,
+  `manual_execution`). `tests/test_crosschain_layering.py` pins this:
   the SDK's module-level import graph, with the implicit package-`__init__` edges, is
   acyclic, and the crosschain package has no function-level or `TYPE_CHECKING`
   imports; never work around a cycle with a lazy import, move the module instead.
-- `readers/` — read side: lending_health, oracle_mapping, position_manager, aave_v3,
-  compound_v3, morpho, ramses_v2, uniswap_v3, unpriceable (middleware-priced tokens of
-  granted substrates the oracle cannot price)
+- `readers/` — read side: lending_health, oracle_mapping (with oracle_mapping_nodes
+  and oracle_mapping_reader), position_manager, aave_v3, aave_v4, compound_v3, morpho,
+  ramses_v2, uniswap_v3, unpriceable (middleware-priced tokens of granted substrates
+  the oracle cannot price), hypercore and hypercore_outcome (HyperCore reads and
+  transfer outcomes)
+- `hypercore/` — the preview HyperCore names re-exported from `fuses/hypercore*.py`
+  and `readers/hypercore*.py`; no code of its own
 - `cli/` — `main.py` root group; `changelog_cmd.py`, `config_cmd.py`, `market_cmd.py`,
   `vault_cmd.py` command orchestration over `vault_data` / `vault_info`; `options.py`
   the shared `--chain-id` / address param types and chain/provider resolution;
@@ -387,7 +405,8 @@ or examples.
 - Fuses (`fuses/`) are stateless encoders: a method returns an immutable
   `FuseAction(fuse_address, calldata)` and touches no chain. `Fuse` builds it
   via `self._action_raw(solidity_signature, values)`; the shared `_validate_*`
-  helpers raise before encoding. `PlasmaVault.execute([actions])` runs the
+  helpers raise before encoding (the HyperCore encoders add their own integer-width
+  checks, `_validate_uint` / `_validate_positive_uint` in `fuses/hypercore.py`). `PlasmaVault.execute([actions])` runs the
   batch atomically.
 - Pin reads, never mutate a shared context: `ctx.at_block(n)` is a copy whose
   reads (and `get_logs` upper bound) default to block ``n``; `Call.call(ctx, block=n)`

{ipor_fusion-4.0.0.dev240 → 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.dev240 → ipor_fusion-4.0.0.dev249}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev240
+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.
@@ -489,9 +490,12 @@ import these from their subpackage, and expect changes in a minor release.
 | Crosschain fuses (market 54): `StargateCrosschainSupplyFuse`, `StargateCrosschainCommandFuse`, `CcipCrosschainSupplyFuse`, `CcipCrosschainCommandFuse`, `CrosschainClaimFuse`; transport-agnostic bases `CrosschainSupplyFuse` / `CrosschainCommandFuse` with `StargateSendParams` / `CcipSendParams`, plus `Command`, `CrosschainSubstrateLib`, `OptionsBuilder` | `ipor_fusion.crosschain` |
 | HyperCore fuses (market 55): `HyperCoreDepositFuse`, `HyperCoreMarginFuse`, `HyperCoreSendFuse`, `HyperCoreOrderFuse`, `HyperCoreCancelFuse`, `HyperCoreBuilderFeeFuse`, `HyperCoreSubstrates` | `ipor_fusion.hypercore`, with `HyperCoreReader`, `read_hypercore_vault_state` and the event decoders |
 
-The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Use
-`crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1")` for that deployment;
-`open_lane` discovers the vault's actual market grants rather than assuming 54.
+The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Pass
+`market_id=crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1")` to `open_lane`
+/ `discover_deployment` for that deployment. Both require it explicitly:
+`discover_deployment` reads the market's executor grants; `open_lane` takes an executor
+address and uses the market ID to find the vault's matching fuses unless they are
+passed.
 
 ### Readers (`ipor_fusion.readers`)
 
@@ -542,15 +546,18 @@ takes the same object.
 ## Development
 
 ```bash
-uv sync --all-extras                                       # Install dependencies
+uv sync --all-extras --locked                              # Install dependencies (as CI)
 uv run pytest tests/test_fuse_encoding.py -n auto -v       # Unit tests (fast, offline)
-uv run pytest -v -s                                        # All tests (needs `.*_PROVIDER_URL` variables in `.env`)
+uv run pytest -v -s                                        # All tests; live ones skip without their provider
 uv run ruff format ./                                      # Format
 uv run ruff check ./                                       # Lint
 uv run pyright                                             # Type check
 ```
 
-Integration tests need provider URLs in `.env` (eth_simulateV1 at a pinned fork block — no local node):
+Each integration test runs when its provider URL is in `.env` (eth_simulateV1 at a
+pinned fork block, no local node) and skips otherwise; HyperEVM tests also need
+`HYPEREVM_PROVIDER_URL`, and the source-backed rehearsals a contracts checkout (see
+AGENTS.md):
 
 ```bash
 cp .env.example .env

{ipor_fusion-4.0.0.dev240 → 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.
@@ -441,9 +442,12 @@ import these from their subpackage, and expect changes in a minor release.
 | Crosschain fuses (market 54): `StargateCrosschainSupplyFuse`, `StargateCrosschainCommandFuse`, `CcipCrosschainSupplyFuse`, `CcipCrosschainCommandFuse`, `CrosschainClaimFuse`; transport-agnostic bases `CrosschainSupplyFuse` / `CrosschainCommandFuse` with `StargateSendParams` / `CcipSendParams`, plus `Command`, `CrosschainSubstrateLib`, `OptionsBuilder` | `ipor_fusion.crosschain` |
 | HyperCore fuses (market 55): `HyperCoreDepositFuse`, `HyperCoreMarginFuse`, `HyperCoreSendFuse`, `HyperCoreOrderFuse`, `HyperCoreCancelFuse`, `HyperCoreBuilderFeeFuse`, `HyperCoreSubstrates` | `ipor_fusion.hypercore`, with `HyperCoreReader`, `read_hypercore_vault_state` and the event decoders |
 
-The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Use
-`crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1")` for that deployment;
-`open_lane` discovers the vault's actual market grants rather than assuming 54.
+The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Pass
+`market_id=crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1")` to `open_lane`
+/ `discover_deployment` for that deployment. Both require it explicitly:
+`discover_deployment` reads the market's executor grants; `open_lane` takes an executor
+address and uses the market ID to find the vault's matching fuses unless they are
+passed.
 
 ### Readers (`ipor_fusion.readers`)
 
@@ -494,15 +498,18 @@ takes the same object.
 ## Development
 
 ```bash
-uv sync --all-extras                                       # Install dependencies
+uv sync --all-extras --locked                              # Install dependencies (as CI)
 uv run pytest tests/test_fuse_encoding.py -n auto -v       # Unit tests (fast, offline)
-uv run pytest -v -s                                        # All tests (needs `.*_PROVIDER_URL` variables in `.env`)
+uv run pytest -v -s                                        # All tests; live ones skip without their provider
 uv run ruff format ./                                      # Format
 uv run ruff check ./                                       # Lint
 uv run pyright                                             # Type check
 ```
 
-Integration tests need provider URLs in `.env` (eth_simulateV1 at a pinned fork block — no local node):
+Each integration test runs when its provider URL is in `.env` (eth_simulateV1 at a
+pinned fork block, no local node) and skips otherwise; HyperEVM tests also need
+`HYPEREVM_PROVIDER_URL`, and the source-backed rehearsals a contracts checkout (see
+AGENTS.md):
 
 ```bash
 cp .env.example .env

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

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

@@ -1,10 +1,11 @@
 """`fusion market` command group — protocol-level market inspection.
 
-Currently exposes `morpho-blue <marketId>`: fetches a Morpho Blue market's
-parameters and state (loan/collateral/oracle/IRM/LLTV, totals, liquidity, APYs)
-plus the MetaMorpho vaults supplying it (current allocation, supply caps, and
-PublicAllocator flow caps + fees). Combines on-chain reads via `MorphoReader`
-with the Morpho public GraphQL API for vault discovery.
+`morpho-blue <marketId>` fetches a Morpho Blue market's parameters and state
+(loan/collateral/oracle/IRM/LLTV, totals, liquidity, APYs) plus the MetaMorpho
+vaults supplying it (current allocation, supply caps, and PublicAllocator flow
+caps + fees), combining on-chain reads via `MorphoReader` with the Morpho public
+GraphQL API. `meta-morpho <vault>` inspects a MetaMorpho V1 or Vault V2 from the
+API: roles, fees, adapters or allocations and caps.
 """
 
 from __future__ import annotations

{ipor_fusion-4.0.0.dev240 → 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.dev240 → 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:]}  ")