ipor-fusion 4.0.0.dev149__tar.gz → 4.0.0.dev153__tar.gz

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/AGENTS.md

@@ -186,7 +186,7 @@ the lifecycle matrix follows that.
 | Python 3.12 runtime, 3.11 floor | `.python-version` + CI `python-version` default; `requires-python`, ruff `target-version`, pyright `pythonVersion` |
 | `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` JSON shape | `build_vault_info_json` in `vault_info.py`, models in `mcp/models.py` (`extra="forbid"`), `_full_vault_info_dict` fixture in `test_mcp_models.py` |
+| `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`) |
 
 ## Layout (`src/ipor_fusion/`)
@@ -213,8 +213,8 @@ the lifecycle matrix follows that.
   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 `health_check_lists`; `explorer.py` Etherscan V2 (single endpoint, needs API key);
+  `resolve_name`) and 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
   replace, corrupt/unwritable degrades to memory) and `NullCache`; every SDK use goes
@@ -223,8 +223,14 @@ the lifecycle matrix follows that.
   `$XDG_CACHE_HOME/ipor-fusion/`) or `get_contract_name(cache=...)`. Never cache an
   absence (no code, no answer): it can change at a later block.
   `morpho_api.py` the Morpho public GraphQL API client (`fetch_market`, `fetch_vault`,
-  `PUBLIC_ALLOCATOR_ADDRESSES`); `market_info.py` — `build_morpho_blue_market_json`,
-  `build_meta_morpho_json`, the `fusion market` JSON documents.
+  `PUBLIC_ALLOCATOR_ADDRESSES`; it narrows the GraphQL body from `object`);
+  `market_info.py` — `build_morpho_blue_market_json`, `build_meta_morpho_json`, the
+  `fusion market` JSON documents (`MorphoBlueMarketJson`, `MetaMorphoV1Json` /
+  `MetaMorphoV2Json`). A JSON document is a TypedDict (`NotRequired` for a key only
+  some entries carry), never `dict[str, Any]`; JSON parsed from the network or a
+  caller enters as `object` / `Mapping[str, object]` and is narrowed with
+  `isinstance`. These two modules skip `from __future__ import annotations`, so a
+  TypedDict's `__optional_keys__` is right at run time.
   None of them imports `cli/` (`tests/test_sdk_layering.py`)
 - `config/roles.py` — `Roles` IntEnum
 - `core/` — `context` (`Web3Context`), `contract` (`Call`, `ContractWrapper`),
@@ -431,12 +437,16 @@ value sets are `Literal` enums. The docstring keeps only what has no
 structured home: a one-line summary, behavioral notes, cost warnings. Do not
 repeat schema content as prose; it drifts.
 
-`mcp/models.py` forbids extra keys. Adding a top-level field to
-`build_vault_info_json` requires adding it to the matching model (with a default
-for back-compat) and to the `_full_vault_info_dict` fixture; `test_mcp_models.py`
-enforces the mirror. Conditionally shaped blocks (`withdraw_manager_details`,
-`substrates`, `dependency_graph`) are `dict[str, Any]`, so their inner keys
-are not validated.
+`mcp/models.py` forbids extra keys and stays the source of the published JSON
+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.
 
 ## Domain rules (verified against the contracts)
 

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/MIGRATION_4.md

@@ -54,6 +54,10 @@ before it is fixed.
    nominal types. Wrap literals and raw values, `ChainId(8453)`, `Period(0)`,
    `Amount(n)`, `parse_fuse_address(...)`; values the SDK returns already carry
    their type. See [Nominal types](#nominal-types).
+9. **Typed JSON documents.** `build_vault_info_json` and the `fusion market`
+   builders return TypedDicts (`VaultInfoJson`, ...); code annotating them
+   `dict[str, Any]` switches to the TypedDict or `Mapping[str, object]`. See
+   [Typed JSON documents](#typed-json-documents).
 
 Then read [Behavior changes](#behavior-changes): they apply to every caller,
 type-checked or not.
@@ -721,6 +725,45 @@ 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.
 
+## 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.
+
+| Builder | Returns |
+|---|---|
+| `build_vault_info_json` | `VaultInfoJson` |
+| `build_morpho_blue_market_json` | `MorphoBlueMarketJson` |
+| `build_meta_morpho_json` | `MetaMorphoV1Json \| MetaMorphoV2Json`, told apart by `doc["version"]` |
+| `RoleAccount.to_dict` | `RoleAccountJson` |
+
+Every nested block has its own TypedDict (`FeesJson`, `WithdrawManagerJson`,
+`BalanceFuseJson`, `ReconciliationJson`, `HyperCoreJson`, `MorphoSupplyingVaultJson`,
+...), all importable from `ipor_fusion` and from `ipor_fusion.vault_info` /
+`ipor_fusion.market_info` (`RoleAccountJson` from `ipor_fusion.core`). Values carry the
+SDK's nominal types (`doc["vault"]` is a `PlasmaVaultAddress`, `doc["chain_id"]` a
+`ChainId`). A block that can be `null` is `X | None`: check it before indexing
+(`fees = doc["fees"]; if fees is not None: fees["management_fee_percent"]`). A key
+that only some entries carry is `NotRequired` (a balance fuse's `pct_of_total` and
+`position_breakdown`, the Morpho API keys of the market document): read it with
+`.get`. A decoded substrate entry stays open-ended, `SubstrateEntryJson`
+(`dict[str, str | bool]`), since each decoder adds its own fields.
+
+- A variable or parameter annotated `dict[str, Any]` no longer accepts these
+  documents (a `TypedDict` is not a `dict[str, Any]`): annotate it with the TypedDict,
+  or `Mapping[str, object]` for code that only passes the document on (`json.dumps`
+  accepts either).
+- Parsing entry points take `Mapping[str, object]` instead of `Mapping[str, Any]`:
+  `decode_external_state_event(log)` and `FusionInstance.from_dict(data)`.
+  `VerifierResult.message` is a `Mapping[str, object]`, and `OutboundMessage.raw` is
+  `object`: narrow it before use (`isinstance(message.raw, MessageV1)` for CCIP; a
+  Stargate `Packet`, or a `(Packet, TaxiMessage)` pair for a token transfer).
+- The `vault info` document's `deployment` is `DeploymentJson` (block, timestamp,
+  age) or `DeploymentErrorJson` (`{"error": ...}`) or `None`; `share_price` is
+  `SharePriceJson` (`asset`, and `usd` when the asset is priced); `dependency_graph`
+  is `DependencyGraphJson` (`edges`, `update_reach`, `update_groups`).
+
 ## Behavior changes
 
 These apply to every caller, type-checked or not. Changes described in full above

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/PKG-INFO

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

@@ -72,7 +72,7 @@ from ipor_fusion.fuses import (
     euler_substrate,
 )
 from ipor_fusion.market_ids import IporFusionMarkets
-from ipor_fusion.types import MAX_UINT256, Amount, ChainId, MarketId, Period
+from ipor_fusion.types import MAX_UINT256, Amount, ChainId, Period
 
 log = logging.getLogger("advanced_euler_v2_credit_market_base")
 
@@ -83,7 +83,7 @@ log = logging.getLogger("advanced_euler_v2_credit_market_base")
 # deployments -- see their note below.
 
 BASE_CHAIN_ID = ChainId(8453)
-EULER_MARKET = MarketId(IporFusionMarkets.EULER_V2)
+EULER_MARKET = IporFusionMarkets.EULER_V2
 
 # IporFusionFactoryProxy on Base. Its clone(...) takes the six args in clone_args().
 BASE_FUSION_FACTORY = Web3.to_checksum_address(

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/examples/advanced_euler_v2_looping_arbitrum.py

@@ -61,7 +61,7 @@ from ipor_fusion.fuses import (
     euler_substrate,
 )
 from ipor_fusion.market_ids import IporFusionMarkets
-from ipor_fusion.types import Amount, ChainId, MarketId, Period
+from ipor_fusion.types import Amount, ChainId, Period
 
 log = logging.getLogger("advanced_euler_v2_looping_arbitrum")
 
@@ -71,9 +71,9 @@ log = logging.getLogger("advanced_euler_v2_looping_arbitrum")
 # mainnet-arbitrum-fusion/addresses.json
 
 ARBITRUM_CHAIN_ID = ChainId(42161)
-EULER_MARKET = MarketId(IporFusionMarkets.EULER_V2)
-SWAPPER_MARKET = MarketId(IporFusionMarkets.UNIVERSAL_TOKEN_SWAPPER_V2)
-MORPHO_FLASH_MARKET = MarketId(IporFusionMarkets.MORPHO_FLASH_LOAN)
+EULER_MARKET = IporFusionMarkets.EULER_V2
+SWAPPER_MARKET = IporFusionMarkets.UNIVERSAL_TOKEN_SWAPPER_V2
+MORPHO_FLASH_MARKET = IporFusionMarkets.MORPHO_FLASH_LOAN
 
 ARBITRUM_FUSION_FACTORY = Web3.to_checksum_address(
     "0x134fCAce7a2C7Ef3dF2479B62f03ddabAEa922d5"

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/examples/composed_hypercore_flow_arbitrum_hyperevm.py

@@ -113,7 +113,6 @@ from ipor_fusion.types import (
     Decimals,
     HyperCoreAsset,
     HyperCoreClientOrderId,
-    MarketId,
     Period,
     Shares,
 )
@@ -162,7 +161,7 @@ HYPERCORE_BALANCE_FUSE = parse_fuse_address(
     "0xaC7404Ec2Bc3F2d3c0853633e0c3edfA25DC50F9"
 )
 HYPERCORE_MARKET = IporFusionMarkets.HYPERCORE
-CROSSCHAIN_MARKET = MarketId(int(IporFusionMarkets.CROSSCHAIN))
+CROSSCHAIN_MARKET = IporFusionMarkets.CROSSCHAIN
 
 # ── Actors ───────────────────────────────────────────────────────────────────
 # One EOA holds the alpha role on both vaults in this test deployment; the two

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/examples/crosschain_ccip_usdc_arbitrum_hyperevm.py

@@ -86,7 +86,7 @@ from ipor_fusion import (
     parse_plasma_vault_address,
 )
 from ipor_fusion.market_ids import IporFusionMarkets
-from ipor_fusion.types import Amount, ChainId, Decimals, MarketId, Period, Shares
+from ipor_fusion.types import Amount, ChainId, Decimals, Period, Shares
 
 log = logging.getLogger("crosschain_ccip_usdc_arbitrum_hyperevm")
 
@@ -123,7 +123,7 @@ EXECUTOR = Web3.to_checksum_address("0xcb83A78BD8e8c284d5704B62945EF2C454266dB0"
 SPOKE_VAULT = parse_plasma_vault_address("0xA342eBA00bD725799828A34EA55D25a55958f643")
 # ``IporFusionMarkets.CROSSCHAIN``: the market the four crosschain fuses are
 # registered under on the hub vault.
-CROSSCHAIN_MARKET = MarketId(int(IporFusionMarkets.CROSSCHAIN))
+CROSSCHAIN_MARKET = IporFusionMarkets.CROSSCHAIN
 
 # ── Actors ───────────────────────────────────────────────────────────────────
 # Role separation: the alpha is an online, least-privilege key that can only

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/examples/external_state_margin_leg_base.py

@@ -96,7 +96,7 @@ from ipor_fusion import (
 )
 from ipor_fusion.fuses import ExternalStateOperationFuse
 from ipor_fusion.market_ids import IporFusionMarkets
-from ipor_fusion.types import Amount, ChainId, MarketId, Period, ProposalHash, Shares
+from ipor_fusion.types import Amount, ChainId, Period, ProposalHash, Shares
 
 log = logging.getLogger("external_state_margin_leg_base")
 
@@ -121,7 +121,7 @@ BASE_FUSION_FACTORY = Web3.to_checksum_address(
 BASE_USDC = Web3.to_checksum_address("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
 
 # External-state market (IporFusionMarkets.EXTERNAL_STATE).
-EXTERNAL_STATE_MARKET = MarketId(IporFusionMarkets.EXTERNAL_STATE)
+EXTERNAL_STATE_MARKET = IporFusionMarkets.EXTERNAL_STATE
 
 # External-state *operation* fuse (enter/exit) -- the functional fuse. It also
 # lazily deploys the per-vault ExternalStateExecutor on the first enter.

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/examples/simple_aave_v3_supply_base.py

@@ -53,7 +53,7 @@ from ipor_fusion import (
 )
 from ipor_fusion.fuses import AaveV3SupplyFuse
 from ipor_fusion.market_ids import IporFusionMarkets
-from ipor_fusion.types import Amount, ChainId, MarketId, Period
+from ipor_fusion.types import Amount, ChainId, Period
 
 log = logging.getLogger("simple_aave_v3_supply_base")
 
@@ -75,7 +75,7 @@ BASE_FUSION_FACTORY = Web3.to_checksum_address(
 BASE_USDC = Web3.to_checksum_address("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
 
 # Aave V3 market (IporFusionMarkets.AAVE_V3).
-AAVE_MARKET = MarketId(IporFusionMarkets.AAVE_V3)
+AAVE_MARKET = IporFusionMarkets.AAVE_V3
 
 # Aave V3 *supply* fuse (registry name SupplyFuseAaveV3) -- the functional fuse
 # that encodes supply/withdraw.

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev149"
+version = "4.0.0.dev153"
 description = "The IPOR Fusion SDK for Python"
 authors = [
     { name = "Adam Mydlarz", email = "amydlarz@gmail.com" },
@@ -111,7 +111,8 @@ executionEnvironments = [
   { root = "examples", reportArgumentType = "error" },
   # A negative case is a line that must fail to type-check, marked with
   # `# pyright: ignore[rule]`; an ignore that suppresses nothing is an error.
-  { root = "tests/typed_client", reportArgumentType = "error", reportUnnecessaryTypeIgnoreComment = "error" },
+  # A client reads the SDK's NotRequired document keys with .get().
+  { root = "tests/typed_client", reportArgumentType = "error", reportUnnecessaryTypeIgnoreComment = "error", reportTypedDictNotRequiredAccess = "error" },
 ]
 
 [tool.coverage.run]

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/src/ipor_fusion/__init__.py

@@ -27,6 +27,7 @@ from ipor_fusion.config.roles import Roles
 from ipor_fusion.core.access import (
     AccessManager,
     RoleAccount,
+    RoleAccountJson,
     RoleStatus,
     resolve_access_manager,
     role_account_sort_key,
@@ -318,6 +319,21 @@ from ipor_fusion.fuses.external_state_events import (
 )
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.market_info import (
+    MetaMorphoAdapterJson,
+    MetaMorphoAllocationJson,
+    MetaMorphoCapJson,
+    MetaMorphoFlowCapJson,
+    MetaMorphoPublicAllocatorJson,
+    MetaMorphoV1Json,
+    MetaMorphoV2Json,
+    MorphoAssetJson,
+    MorphoBlueMarketJson,
+    MorphoFlowCapConfigJson,
+    MorphoMarketParamsJson,
+    MorphoMarketRatesJson,
+    MorphoMarketStateJson,
+    MorphoSupplyingVaultJson,
+    MorphoVaultAssetJson,
     build_meta_morpho_json,
     build_morpho_blue_market_json,
 )
@@ -480,7 +496,42 @@ from ipor_fusion.vault_data import (
     resolve_token_decimals,
     resolve_token_symbol,
 )
-from ipor_fusion.vault_info import build_vault_info_json
+from ipor_fusion.vault_info import (
+    AaveBreakdownJson,
+    AmountJson,
+    BalanceFuseJson,
+    BreakdownAmountJson,
+    DeltaJson,
+    DependencyGraphJson,
+    DeploymentErrorJson,
+    DeploymentJson,
+    Erc20BalanceJson,
+    FeesJson,
+    FuseJson,
+    HealthCheckJson,
+    HighWaterMarkJson,
+    HyperCoreJson,
+    HyperCorePendingJson,
+    HyperCorePerpLegJson,
+    HyperCorePerpMarketJson,
+    HyperCoreSpotLegJson,
+    LendingHealthJson,
+    LendingMarketJson,
+    ManagersJson,
+    MorphoBreakdownJson,
+    PendingRequestJson,
+    PricedAmountJson,
+    RecipientFeeJson,
+    ReconciliationJson,
+    SharePriceJson,
+    SubstrateEntryJson,
+    UsdAmountJson,
+    VaultAssetJson,
+    VaultInfoJson,
+    VaultLinksJson,
+    WithdrawManagerJson,
+    build_vault_info_json,
+)
 
 __version__ = package_version()
 
@@ -526,6 +577,7 @@ __all__ = [
     "PlasmaVault",
     "AccessManager",
     "RoleAccount",
+    "RoleAccountJson",
     "RoleStatus",
     "resolve_access_manager",
     "role_account_sort_key",
@@ -919,6 +971,39 @@ __all__ = [
     "resolve_token_decimals",
     "resolve_token_symbol",
     "build_vault_info_json",
+    "AaveBreakdownJson",
+    "AmountJson",
+    "BalanceFuseJson",
+    "BreakdownAmountJson",
+    "DeltaJson",
+    "DependencyGraphJson",
+    "DeploymentErrorJson",
+    "DeploymentJson",
+    "Erc20BalanceJson",
+    "FeesJson",
+    "FuseJson",
+    "HealthCheckJson",
+    "HighWaterMarkJson",
+    "HyperCoreJson",
+    "HyperCorePendingJson",
+    "HyperCorePerpLegJson",
+    "HyperCorePerpMarketJson",
+    "HyperCoreSpotLegJson",
+    "LendingHealthJson",
+    "LendingMarketJson",
+    "ManagersJson",
+    "MorphoBreakdownJson",
+    "PendingRequestJson",
+    "PricedAmountJson",
+    "RecipientFeeJson",
+    "ReconciliationJson",
+    "SharePriceJson",
+    "SubstrateEntryJson",
+    "UsdAmountJson",
+    "VaultAssetJson",
+    "VaultInfoJson",
+    "VaultLinksJson",
+    "WithdrawManagerJson",
     "MorphoApiError",
     "MorphoApiMarket",
     "PUBLIC_ALLOCATOR_ADDRESSES",
@@ -933,4 +1018,19 @@ __all__ = [
     "fetch_vault",
     "build_meta_morpho_json",
     "build_morpho_blue_market_json",
+    "MetaMorphoAdapterJson",
+    "MetaMorphoAllocationJson",
+    "MetaMorphoCapJson",
+    "MetaMorphoFlowCapJson",
+    "MetaMorphoPublicAllocatorJson",
+    "MetaMorphoV1Json",
+    "MetaMorphoV2Json",
+    "MorphoAssetJson",
+    "MorphoBlueMarketJson",
+    "MorphoFlowCapConfigJson",
+    "MorphoMarketParamsJson",
+    "MorphoMarketRatesJson",
+    "MorphoMarketStateJson",
+    "MorphoSupplyingVaultJson",
+    "MorphoVaultAssetJson",
 ]

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/src/ipor_fusion/cli/vault_cmd.py

@@ -2,10 +2,11 @@ from __future__ import annotations
 
 import json
 import sys
-from typing import Any
+from typing import TypedDict
 
 import click
 from web3 import Web3
+from web3.types import Timestamp
 
 from ipor_fusion.chains import CHAIN_NAMES
 from ipor_fusion.cli.config_store import (
@@ -41,7 +42,7 @@ from ipor_fusion.errors import (
 from ipor_fusion.readers.oracle_mapping import (
     build_oracle_mapping,
 )
-from ipor_fusion.types import ChainId, PlasmaVaultAddress
+from ipor_fusion.types import ChainId, Check, PlasmaVaultAddress, Severity, Verdict
 from ipor_fusion.validation import (
     VaultValidation,
     validate_vault,
@@ -51,6 +52,10 @@ from ipor_fusion.vault_data import (
     fetch_vault_data,
 )
 from ipor_fusion.vault_info import (
+    Erc20BalanceJson,
+    LendingHealthJson,
+    ReconciliationJson,
+    VaultAssetJson,
     _erc20_balances_json,
     _lending_health_json,
     _reconciliation_json,
@@ -58,6 +63,32 @@ from ipor_fusion.vault_info import (
 )
 
 
+class _FindingJson(TypedDict):
+    check: Check
+    severity: Severity
+    message: str
+
+
+class _ValidationJson(TypedDict):
+    """The ``fusion vault validate --json`` document."""
+
+    vault: PlasmaVaultAddress
+    chain: str
+    chain_id: ChainId
+    block: int
+    block_timestamp: Timestamp
+    block_timestamp_utc: str
+    asset: VaultAssetJson
+    verdict: Verdict
+    criticals: list[str]
+    warnings: list[str]
+    ok: list[str]
+    findings: list[_FindingJson]
+    reconciliation: ReconciliationJson
+    erc20_balances: list[Erc20BalanceJson]
+    lending_health: LendingHealthJson | None
+
+
 def _auto_save_vault(
     cfg: FusionConfig,
     vault_address: PlasmaVaultAddress,
@@ -276,7 +307,7 @@ def validate(
         sys.exit(1)
 
 
-def _validation_json(validation: VaultValidation, chain_label: str) -> dict[str, Any]:
+def _validation_json(validation: VaultValidation, chain_label: str) -> _ValidationJson:
     return {
         "vault": validation.vault,
         "chain": chain_label,

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/src/ipor_fusion/cli/vault_info_view.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import json
+from collections.abc import Sequence
 from functools import partial
-from typing import Any
 
 import click
 
@@ -23,6 +23,7 @@ from ipor_fusion.cli.vault_rendering import (
     _format_usd,
     _print_table,
 )
+from ipor_fusion.core.access import RoleAccountJson
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.fee_manager import RecipientFee
 from ipor_fusion.explorer import get_contract_name
@@ -48,7 +49,7 @@ from ipor_fusion.vault_info import (
 )
 
 
-def _print_role_accounts_table(role_accounts: list[dict[str, Any]]) -> None:
+def _print_role_accounts_table(role_accounts: Sequence[RoleAccountJson]) -> None:
     _print_table(
         ("Account", "Role", "Role ID", "Delay (s)"),
         [
@@ -63,7 +64,7 @@ def _print_role_accounts_table(role_accounts: list[dict[str, Any]]) -> None:
     )
 
 
-def _print_role_accounts(role_accounts: list[dict[str, Any]] | None) -> None:
+def _print_role_accounts(role_accounts: Sequence[RoleAccountJson] | None) -> None:
     click.echo("Role Accounts:")
     if role_accounts is None:
         click.echo("  (unavailable — the RoleGranted log scan did not complete)")

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/src/ipor_fusion/cli/vault_markets_view.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from collections.abc import Callable, Sequence
 from concurrent.futures import Future, ThreadPoolExecutor
-from typing import Any
 
 import click
 from eth_typing import HexAddress
@@ -13,6 +12,7 @@ from ipor_fusion.cli.vault_rendering import (
     _print_table,
     _substrate_details,
 )
+from ipor_fusion.readers.lending_health import LendingMarketHealth, VaultLendingHealth
 from ipor_fusion.substrates import (
     decode_substrate,
     format_market_label,
@@ -42,7 +42,7 @@ def _print_lending_health(data: VaultData) -> None:  # noqa: C901
     click.echo("Position Breakdown:")
     morpho_health, aave_health = _index_lending_health(lh)
     consumed_morpho_subs: set[str] = set()
-    consumed_aave_mids: set[int | str] = set()
+    consumed_aave_mids: set[MarketId | str] = set()
 
     for ipor_mid, positions in (data.morpho_positions or {}).items():
         click.echo(f"  {format_market_label(ipor_mid)}:")
@@ -98,16 +98,16 @@ def _print_lending_health(data: VaultData) -> None:  # noqa: C901
 
 
 def _index_lending_health(
-    lh: Any,
-) -> tuple[dict[str, Any], dict[int | str, Any]]:
+    lh: VaultLendingHealth | None,
+) -> tuple[dict[str, LendingMarketHealth], dict[MarketId | str, LendingMarketHealth]]:
     """Split lending health rows by protocol for fast lookup during rendering.
 
     Morpho rows are keyed by morpho substrate id (one row per substrate).
     Aave V3 rows are keyed by IPOR market id (account-aggregated, one row per
     market); Aave V4 rows by Spoke address (account-aggregated per Spoke).
     """
-    morpho: dict[str, Any] = {}
-    aave: dict[int | str, Any] = {}
+    morpho: dict[str, LendingMarketHealth] = {}
+    aave: dict[MarketId | str, LendingMarketHealth] = {}
     if lh is None:
         return morpho, aave
     for m in lh.markets:
@@ -120,7 +120,7 @@ def _index_lending_health(
     return morpho, aave
 
 
-def _print_health_lines(market: Any, indent: str) -> None:
+def _print_health_lines(market: LendingMarketHealth, indent: str) -> None:
     """Render LTV / Health Factor / Status lines for a lending market.
 
     Status colors: green when safe, yellow at warning (HF < 1.10), red+bold

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/src/ipor_fusion/core/__init__.py

@@ -1,4 +1,9 @@
-from ipor_fusion.core.access import AccessManager, RoleAccount, RoleStatus
+from ipor_fusion.core.access import (
+    AccessManager,
+    RoleAccount,
+    RoleAccountJson,
+    RoleStatus,
+)
 from ipor_fusion.core.context import InFlightLimit, Web3Context
 from ipor_fusion.core.erc20 import ERC20
 from ipor_fusion.core.fee_manager import (
@@ -37,6 +42,7 @@ __all__ = [
     "PlasmaVault",
     "AccessManager",
     "RoleAccount",
+    "RoleAccountJson",
     "RoleStatus",
     "RewardsManager",
     "VestingData",

{ipor_fusion-4.0.0.dev149 → ipor_fusion-4.0.0.dev153}/src/ipor_fusion/core/access.py

@@ -1,5 +1,6 @@
 from collections.abc import Callable
 from dataclasses import dataclass
+from typing import TypedDict
 
 from eth_abi import decode
 from eth_abi.exceptions import InsufficientDataBytes
@@ -23,6 +24,16 @@ from ipor_fusion.errors import (
 from ipor_fusion.types import AccessManagerAddress, Period, PlasmaVaultAddress, RoleId
 
 
+class RoleAccountJson(TypedDict):
+    """`RoleAccount.to_dict`: one role membership as JSON."""
+
+    account: ChecksumAddress
+    role_id: RoleId
+    role_name: str
+    is_member: bool
+    execution_delay: Period
+
+
 @dataclass(slots=True)
 class RoleStatus:
     """Result of a role membership check for an account."""
@@ -44,7 +55,7 @@ class RoleAccount:
     def role_name(self) -> str:
         return Roles.get_name(self.role_id)
 
-    def to_dict(self) -> dict[str, str | int | bool]:
+    def to_dict(self) -> RoleAccountJson:
         """Canonical JSON-ready row shape, shared by the CLI surfaces."""
         return {
             "account": self.account,