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

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/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
@@ -218,7 +221,7 @@ the lifecycle matrix follows that.
 | `IporFusionMarkets`, `Roles` | `market_ids.py`, `config/roles.py` mirror `IporFusionMarkets.sol`, `Roles.sol` in `ipor-fusion/contracts/libraries/`; drift-gated by `tests/test_solidity_mirrors.py` — bump its pinned ref in the same change that syncs the mirrors An id sourced from a contracts feature branch ahead of the pinned ref goes in the test's `_AHEAD_OF_UPSTREAM` allowlist and is removed when the ref catches up |
 | substrate decoders | `substrates.py` registry mirrors each market's `contracts/fuses/<protocol>/*SubstrateLib.sol` or `*FuseLib.sol` |
 | `vault_info` / `fusion market` JSON shapes | the builders and their TypedDicts (`VaultInfoJson`, `MorphoBlueMarketJson`, `MetaMorphoV1Json` / `MetaMorphoV2Json`) in `vault_info.py` / `market_info.py`, models in `mcp/models.py` (`extra="forbid"`, the published schema), the `VaultInfoJson`-typed `_full_vault_info_dict` fixture in `test_mcp_models.py` |
-| CLI command set | every CLI command has a matching tool in `mcp/server.py` (`changelog` maps to `server_info`) |
+| CLI command set | every CLI command has a matching tool in `mcp/server.py` with the same arguments (`changelog` maps to `server_info`; `--json` and display filters are CLI-only); `tests/test_cli_mcp_parity.py` enforces it, and both resolve chain and provider through `cli/config_store.resolve_chain_id` |
 
 ## Layout (`src/ipor_fusion/`)
 
@@ -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)`
@@ -479,7 +498,9 @@ the rest share names). Read-only: `vault_info`, `vault_validate`,
 `vault_list`, `vault_role_accounts`, `vault_oracle_mapping`, `market_morpho_blue`,
 `market_meta_morpho`, `config_show`, `server_info`. Mutating: `vault_add`,
 `vault_remove`, `config_set_provider`, `config_set_etherscan_key`. Every new
-CLI command gets a matching MCP tool. Put every fact in its structured home:
+CLI command gets a matching MCP tool with the same argument names; an optional
+chain or block is `None` when omitted (`ChainArg`, `BlockArg`), never a `0`
+sentinel. Put every fact in its structured home:
 the return shape is the Pydantic return type (it becomes `outputSchema`),
 per-argument semantics go in `Annotated[..., Field(description=...)]`, closed
 value sets are `Literal` enums. The docstring keeps only what has no

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

@@ -990,6 +990,25 @@ and `log_index` was passed through as given (a hex string from a raw log); the e
 These apply to every caller, type-checked or not. Changes described in full above
 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
+    `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.
+  - **CLI options:** every `--block-number` rejects a negative block, and
+    `fusion market morpho-blue --block` is `--block-number` (`--block` still
+    works).
+  - **One role-accounts document:** `fusion vault role-accounts --json` and
+    `vault_role_accounts` publish `RoleAccountsJson`, built by
+    `build_role_accounts_json` (exported).
+  - **Parity test:** `tests/test_cli_mcp_parity.py` holds every command to a
+    tool with the same arguments.
+
 - **`vault validate` publishes one document.** In 3.x the CLI's `--json` output
   and the MCP `vault_validate` tool returned two different shapes; both now
   return `VaultValidationJson`, built by `build_vault_validation_json(validation,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev234
+Version: 4.0.0.dev244
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -489,9 +489,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 +545,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.dev234 → ipor_fusion-4.0.0.dev244}/README.md

@@ -441,9 +441,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 +497,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.dev234 → ipor_fusion-4.0.0.dev244}/pyproject.toml

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

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/src/ipor_fusion/__init__.py

@@ -28,7 +28,9 @@ from ipor_fusion.core.access import (
     AccessManager,
     RoleAccount,
     RoleAccountJson,
+    RoleAccountsJson,
     RoleStatus,
+    build_role_accounts_json,
     resolve_access_manager,
     role_account_sort_key,
 )
@@ -465,6 +467,8 @@ __all__ = [
     "RoleStatus",
     "resolve_access_manager",
     "role_account_sort_key",
+    "RoleAccountsJson",
+    "build_role_accounts_json",
     "RewardsManager",
     "VestingData",
     "ERC20",

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/src/ipor_fusion/cli/config_cmd.py

@@ -20,7 +20,7 @@ def config() -> None:
 @click.argument("url")
 @click.option(
     "--chain-id",
-    type=int,
+    type=click.IntRange(min=1),
     default=None,
     help="Chain ID (auto-detected from URL if omitted).",
 )

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/src/ipor_fusion/cli/config_store.py

@@ -88,3 +88,21 @@ def load_config() -> FusionConfig:
 def save_config(config: FusionConfig) -> None:
     CONFIG_DIR.mkdir(parents=True, exist_ok=True)
     CONFIG_FILE.write_text(config.model_dump_json(indent=2), encoding="utf-8")
+
+
+def resolve_chain_id(
+    cfg: FusionConfig, vault_address: str, chain_id: ChainId | None
+) -> ChainId | None:
+    """The chain a command or tool runs on: the one given, else the saved
+    vault's, else the chain of the only configured provider; None when none
+    applies. The CLI and the MCP server share it so both resolve alike."""
+    if chain_id is not None:
+        return chain_id
+    if entry := next(
+        (v for v in cfg.vaults if v.address.lower() == vault_address.lower()),
+        None,
+    ):
+        return entry.chain_id
+    if len(cfg.providers) == 1:
+        return ChainId(int(next(iter(cfg.providers))))
+    return None

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/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
@@ -16,7 +17,7 @@ from eth_typing import ChecksumAddress
 
 from ipor_fusion.chains import CHAIN_NAMES
 from ipor_fusion.cli.config_store import load_config
-from ipor_fusion.cli.options import ADDRESS, CHAIN, _resolve_provider
+from ipor_fusion.cli.options import ADDRESS, BLOCK_NUMBER, CHAIN, _resolve_provider
 from ipor_fusion.cli.vault_rendering import _format_amount, _print_table
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.market_info import (
@@ -81,8 +82,10 @@ def market() -> None:
     help="Chain ID or name (ethereum, base, arbitrum, ...).",
 )
 @click.option(
+    "--block-number",
     "--block",
-    type=int,
+    "block_number",
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number for on-chain reads (default: latest).",
 )
@@ -109,7 +112,7 @@ def market() -> None:
 def morpho_blue(
     market_id: MorphoBlueMarketId,
     chain_id: ChainId,
-    block: int | None,
+    block_number: int | None,
     no_api: bool,
     vault_filter: str | None,
     json_output: bool,
@@ -125,8 +128,8 @@ def morpho_blue(
     cfg = load_config()
     provider_url = _resolve_provider(cfg, chain_id)
     ctx = Web3Context.from_url(provider_url)
-    if block is not None:
-        ctx = ctx.at_block(block)
+    if block_number is not None:
+        ctx = ctx.at_block(block_number)
     reader = MorphoReader(morpho_blue_address(chain_id))
     mid = market_id
     params, state = reader.read_existing_market(ctx, mid)

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/src/ipor_fusion/cli/options.py

@@ -7,6 +7,7 @@ from web3 import Web3
 from ipor_fusion.chains import CHAIN_NAME_TO_ID, ensure_supported_chain
 from ipor_fusion.cli.config_store import (
     FusionConfig,
+    resolve_chain_id,
 )
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.errors import (
@@ -74,11 +75,11 @@ class ChainType(click.ParamType):  # pyright: ignore[reportMissingTypeArgument]
         self, value: object, param: click.Parameter | None, ctx: click.Context | None
     ) -> ChainId:
         if isinstance(value, int):
-            return ChainId(value)
+            return self._positive(value, param, ctx)
         if not isinstance(value, str):
             self.fail(f"expected string, got {type(value).__name__}", param, ctx)
         try:
-            return ChainId(int(value))
+            return self._positive(int(value), param, ctx)
         except ValueError:
             pass
         lower = value.lower().strip()
@@ -91,22 +92,54 @@ class ChainType(click.ParamType):  # pyright: ignore[reportMissingTypeArgument]
             ctx,
         )
 
+    def _positive(
+        self, value: int, param: click.Parameter | None, ctx: click.Context | None
+    ) -> ChainId:
+        if value <= 0:
+            self.fail(
+                f"chain ID must be positive, got {value}; omit --chain-id to "
+                "auto-detect it",
+                param,
+                ctx,
+            )
+        return ChainId(value)
+
 
 CHAIN = ChainType()
 
 
+class BlockNumberType(click.IntRange):
+    """A positive block number. 0 is refused rather than read as block 0:
+    some callers still pass it meaning "latest"."""
+
+    name = "block"
+
+    def __init__(self) -> None:
+        super().__init__(min=1)
+
+    def convert(
+        self, value: object, param: click.Parameter | None, ctx: click.Context | None
+    ) -> int:
+        if value in (0, "0"):
+            self.fail(
+                "0 is not a block selector: omit --block-number for the latest block",
+                param,
+                ctx,
+            )
+        return super().convert(value, param, ctx)
+
+
+BLOCK_NUMBER = BlockNumberType()
+
+
 def _resolve_chain_id(
     cfg: FusionConfig, vault_address: PlasmaVaultAddress, chain_id: ChainId | None
 ) -> ChainId:
-    if chain_id is not None:
-        return chain_id
-    if entry := next(
-        (v for v in cfg.vaults if v.address.lower() == vault_address.lower()),
-        None,
-    ):
-        return entry.chain_id
+    if (resolved := resolve_chain_id(cfg, vault_address, chain_id)) is not None:
+        return resolved
     raise click.UsageError(
-        "Unknown vault — use --chain-id (e.g. --chain-id ethereum, --chain-id 8453)"
+        "Cannot tell the chain: the vault is not saved and there is not exactly one "
+        "configured provider — use --chain-id (e.g. --chain-id ethereum, --chain-id 8453)"
     )
 
 

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/src/ipor_fusion/cli/vault_cmd.py

@@ -4,7 +4,6 @@ import json
 import sys
 
 import click
-from web3 import Web3
 
 from ipor_fusion.chains import CHAIN_NAMES
 from ipor_fusion.cli.config_store import (
@@ -13,7 +12,13 @@ from ipor_fusion.cli.config_store import (
     load_config,
     save_config,
 )
-from ipor_fusion.cli.options import CHAIN, VAULT_ADDRESS, _build_ctx, _resolve_provider
+from ipor_fusion.cli.options import (
+    BLOCK_NUMBER,
+    CHAIN,
+    VAULT_ADDRESS,
+    _build_ctx,
+    _resolve_provider,
+)
 from ipor_fusion.cli.oracle_mapping_view import _print_oracle_mapping
 from ipor_fusion.cli.vault_health import (
     _print_validation,
@@ -27,8 +32,8 @@ from ipor_fusion.cli.vault_rendering import (
 )
 from ipor_fusion.config.roles import Roles
 from ipor_fusion.core.access import (
+    build_role_accounts_json,
     resolve_access_manager,
-    role_account_sort_key,
 )
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.plasma_vault import PlasmaVault
@@ -181,7 +186,7 @@ vault.add_command(list_vaults, "ls")
 )
 @click.option(
     "--block-number",
-    type=int,
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number (default: latest).",
 )
@@ -226,7 +231,7 @@ def info(
 )
 @click.option(
     "--block-number",
-    type=int,
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number (default: latest).",
 )
@@ -287,7 +292,7 @@ def validate(
 )
 @click.option(
     "--block-number",
-    type=int,
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number (default: latest).",
 )
@@ -326,21 +331,19 @@ def role_accounts(
         raise click.ClickException(
             f"RoleGranted log scan failed ({type(exc).__name__}: {exc})."
         ) from exc
-    rows = [ra.to_dict() for ra in sorted(accounts, key=role_account_sort_key)]
-
+    document = build_role_accounts_json(
+        accounts,
+        vault=vault_address,
+        access_manager=manager.address,
+        chain_id=chain_id,
+        role=role_id,
+    )
     if json_output:
-        payload = {
-            "vault": Web3.to_checksum_address(vault_address),
-            "access_manager": manager.address,
-            "chain_id": chain_id,
-            "role_filter": Roles.get_name(role_id) if role_id is not None else None,
-            "accounts": rows,
-        }
-        click.echo(json.dumps(payload, indent=2))
+        click.echo(json.dumps(document, indent=2))
         return
 
     click.echo(f"Access Manager: {manager.address}")
-    _print_role_accounts_table(rows)
+    _print_role_accounts_table(document["accounts"])
 
 
 @vault.command("oracle-mapping")
@@ -350,7 +353,7 @@ def role_accounts(
 )
 @click.option(
     "--block-number",
-    type=click.IntRange(min=0),
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number (default: latest).",
 )

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/src/ipor_fusion/core/__init__.py

@@ -2,7 +2,9 @@ from ipor_fusion.core.access import (
     AccessManager,
     RoleAccount,
     RoleAccountJson,
+    RoleAccountsJson,
     RoleStatus,
+    build_role_accounts_json,
     resolve_access_manager,
     role_account_sort_key,
 )
@@ -138,4 +140,6 @@ __all__ = [
     "price_oracle_middleware",
     "resolve_access_manager",
     "role_account_sort_key",
+    "RoleAccountsJson",
+    "build_role_accounts_json",
 ]

{ipor_fusion-4.0.0.dev234 → ipor_fusion-4.0.0.dev244}/src/ipor_fusion/core/access.py

@@ -1,4 +1,4 @@
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from typing import TypedDict
 
@@ -21,7 +21,13 @@ from ipor_fusion.errors import (
     NotPlasmaVaultError,
     OwnerNotFoundError,
 )
-from ipor_fusion.types import AccessManagerAddress, Period, PlasmaVaultAddress, RoleId
+from ipor_fusion.types import (
+    AccessManagerAddress,
+    ChainId,
+    Period,
+    PlasmaVaultAddress,
+    RoleId,
+)
 
 
 class RoleAccountJson(TypedDict):
@@ -71,6 +77,38 @@ def role_account_sort_key(role_account: RoleAccount) -> tuple[str, int]:
     return (role_account.account.lower(), role_account.role_id)
 
 
+class RoleAccountsJson(TypedDict):
+    """The ``fusion vault role-accounts --json`` document and the
+    ``vault_role_accounts`` MCP tool output (`build_role_accounts_json`)."""
+
+    vault: PlasmaVaultAddress
+    access_manager: AccessManagerAddress
+    chain_id: ChainId
+    role_filter: str | None
+    accounts: list[RoleAccountJson]
+
+
+def build_role_accounts_json(
+    accounts: Sequence[RoleAccount],
+    *,
+    vault: PlasmaVaultAddress,
+    access_manager: AccessManagerAddress,
+    chain_id: ChainId,
+    role: RoleId | Roles | None = None,
+) -> RoleAccountsJson:
+    """Role holders as the one document both tools publish, in
+    `role_account_sort_key` order; ``role`` is the filter applied, if any."""
+    return {
+        "vault": vault,
+        "access_manager": access_manager,
+        "chain_id": chain_id,
+        "role_filter": Roles.get_name(role) if role is not None else None,
+        "accounts": [
+            ra.to_dict() for ra in sorted(accounts, key=role_account_sort_key)
+        ],
+    }
+
+
 def _role_status_decoder(values: tuple[bool, int]) -> RoleStatus:
     is_member, execution_delay = values
     return RoleStatus(is_member=is_member, execution_delay=Period(execution_delay))