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

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev234}/AGENTS.md

@@ -487,9 +487,13 @@ 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 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;
+schema. A command whose CLI `--json` and MCP tool return the same data publish one
+document: an SDK builder returns its TypedDict (`build_vault_info_json`,
+`build_vault_validation_json`, the `fusion market` builders) and the tool
+validates it into the mirroring model, never a second hand-built shape. Adding a
+field to a 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 for vault
+info;
 `TestTypedDocumentsMirrorModels` in `test_mcp_models.py` holds every TypedDict to
 its model block by block, a union block (`deployment`, `position_breakdown`,
 `source_detail`) shape by shape. Every block is a model; a block whose optional keys

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

@@ -990,6 +990,29 @@ 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.
 
+- **`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,
+  chain)` (exported from `ipor_fusion` and `ipor_fusion.vault_info`):
+  - `findings` lists every check in order with its `check`, `severity` and
+    `message`. It replaces the CLI's `criticals` / `warnings` / `ok` string lists
+    and the MCP tool's `criticals` / `warnings` / `passed` lists; filter by
+    `severity`.
+  - `erc20` (`tokens`, `value_in_asset`, `market_cached_value`, `unpriced_tokens`)
+    replaces the CLI's `erc20_balances`; `erc20.tokens` has the same entries.
+  - `reconciliation`, `lending_health` and `asset` share their shapes with the
+    `vault info` document. For the MCP tool this means `delta.percent` instead of
+    `delta_percent`, amounts formatted with thousands separators and at most six
+    decimals (`"14,912.465797"`; `raw` keeps the exact value) and the delta's
+    `formatted` as its absolute value, as in `vault info`.
+  - The MCP tool's output gains `block_timestamp`.
+  - An ERC20 entry whose balance read failed keeps its `decimals` when they were
+    read (in `vault info` too).
+  - The MCP output is the builder's document key for key: an amount without a
+    USD value and an ERC20 entry without a balance no longer gain `null` keys
+    (`usd`, `price_usd`, ...) in either tool, `vault_info` included, and a zero
+    USD delta without a price is `0.0`, not `0`.
+
 - **A failed lending read is a warning, never a silent `ok`.** 3.x caught every
   exception in the lending-health readers and dropped the position, so a provider
   outage could leave no lending finding and an `ok` verdict. Now:

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

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

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

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

@@ -368,7 +368,9 @@ from ipor_fusion.vault_info import (
     DeploymentErrorJson,
     DeploymentJson,
     Erc20BalanceJson,
+    Erc20HoldingsJson,
     FeesJson,
+    FindingJson,
     FuseJson,
     HealthCheckJson,
     HighWaterMarkJson,
@@ -392,8 +394,10 @@ from ipor_fusion.vault_info import (
     VaultAssetJson,
     VaultInfoJson,
     VaultLinksJson,
+    VaultValidationJson,
     WithdrawManagerJson,
     build_vault_info_json,
+    build_vault_validation_json,
 )
 
 __version__ = package_version()
@@ -719,6 +723,10 @@ __all__ = [
     "UsdAmountJson",
     "VaultAssetJson",
     "VaultInfoJson",
+    "VaultValidationJson",
+    "FindingJson",
+    "Erc20HoldingsJson",
+    "build_vault_validation_json",
     "VaultLinksJson",
     "WithdrawManagerJson",
     "MorphoApiError",

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

@@ -2,11 +2,9 @@ from __future__ import annotations
 
 import json
 import sys
-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 (
@@ -42,9 +40,8 @@ from ipor_fusion.errors import (
 from ipor_fusion.readers.oracle_mapping import (
     build_oracle_mapping,
 )
-from ipor_fusion.types import ChainId, Check, PlasmaVaultAddress, Severity, Verdict
+from ipor_fusion.types import ChainId, PlasmaVaultAddress
 from ipor_fusion.validation import (
-    VaultValidation,
     validate_vault,
 )
 from ipor_fusion.vault_data import (
@@ -52,43 +49,11 @@ 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,
     _unix_to_iso,
+    build_vault_validation_json,
 )
 
 
-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,
@@ -296,7 +261,9 @@ def validate(
 
     chain_label = CHAIN_NAMES.get(chain_id, str(chain_id))
     if json_output:
-        click.echo(json.dumps(_validation_json(validation, chain_label), indent=2))
+        click.echo(
+            json.dumps(build_vault_validation_json(validation, chain_label), indent=2)
+        )
     else:
         click.echo(f"Vault:   {validation.vault}")
         click.echo(f"Chain:   {chain_label} (chain-id={chain_id})")
@@ -307,36 +274,6 @@ def validate(
         sys.exit(1)
 
 
-def _validation_json(validation: VaultValidation, chain_label: str) -> _ValidationJson:
-    return {
-        "vault": validation.vault,
-        "chain": chain_label,
-        "chain_id": validation.chain_id,
-        "block": validation.block_number,
-        "block_timestamp": validation.block_timestamp,
-        "block_timestamp_utc": _unix_to_iso(validation.block_timestamp),
-        "asset": {
-            "address": validation.asset,
-            "symbol": validation.asset_symbol,
-            "decimals": validation.asset_decimals,
-            "price_usd": validation.asset_price_usd,
-        },
-        "verdict": validation.verdict,
-        "criticals": list(validation.criticals),
-        "warnings": list(validation.warnings),
-        "ok": list(validation.ok),
-        "findings": [
-            {"check": f.check, "severity": f.severity, "message": f.message}
-            for f in validation.findings
-        ],
-        "reconciliation": _reconciliation_json(
-            validation.reconciliation, validation.asset_decimals
-        ),
-        "erc20_balances": _erc20_balances_json(validation),
-        "lending_health": _lending_health_json(validation.lending_health),
-    }
-
-
 @vault.command("role-accounts")
 @click.argument("vault_address", type=VAULT_ADDRESS)
 @click.option(

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev234}/src/ipor_fusion/mcp/models.py

@@ -33,8 +33,6 @@ Design notes:
 
 from __future__ import annotations
 
-from datetime import UTC, datetime
-from decimal import Decimal
 from typing import TYPE_CHECKING, Literal
 
 from pydantic import (
@@ -62,19 +60,7 @@ from ipor_fusion.types import (
 if TYPE_CHECKING:
     from ipor_fusion.about import ChangelogEntry
     from ipor_fusion.core.access import RoleAccount
-    from ipor_fusion.readers.lending_health import (
-        LendingMarketHealth as ReaderLendingMarketHealth,
-    )
-    from ipor_fusion.readers.lending_health import VaultLendingHealth
     from ipor_fusion.readers.oracle_mapping import OracleMapping, OracleNode
-    from ipor_fusion.validation import (
-        Erc20Holding,
-        Erc20Holdings,
-        VaultValidation,
-    )
-    from ipor_fusion.validation import (
-        Reconciliation as ValidationReconciliation,
-    )
 
 
 class _Base(BaseModel):
@@ -98,7 +84,7 @@ class _Sparse(_Base):
 # ---------------------------------------------------------------------------
 
 
-class Amount(_Base):
+class Amount(_Sparse):
     """Token amount with both raw and formatted representations."""
 
     raw: int | str = Field(description="Raw on-chain integer (or 'unlimited').")
@@ -382,7 +368,7 @@ class BalanceFuseEntry(_Base):
     )
 
 
-class ERC20Entry(_Base):
+class ERC20Entry(_Sparse):
     """ERC-20 balance entry; field set varies by data availability."""
 
     address: str
@@ -770,255 +756,51 @@ class OracleMappingResponse(_Base):
 # ---------------------------------------------------------------------------
 
 
-def _formatted(raw: int, decimals: int) -> str:
-    return format(Decimal(raw).scaleb(-decimals).normalize(), "f") if raw else "0"
-
-
-def _amount(raw: int, decimals: int, usd: float | None = None) -> Amount:
-    """An Amount in vault_info's convention, the sign kept in `formatted`."""
-    return Amount(raw=raw, formatted=_formatted(raw, decimals), usd=usd)
-
-
 class FindingModel(_Base):
     check: Check
     severity: Severity
     message: str
 
 
-class ReconciliationModel(_Base):
-    """totalAssets against balance fuses, idle underlying and the rewards
-    claim manager's balance."""
-
-    balance_fuses_total: Amount
-    underlying_on_vault: Amount
-    rewards_manager_balance: Amount = Field(
-        description="RewardsClaimManager.balanceOf(), which totalAssets includes; "
-        "0 without a manager or when it could not be read."
-    )
-    management_fee_netted: Amount = Field(
-        description="Unrealized management fee subtracted from sum: totalAssets "
-        "nets it on vaults built before ipor-fusion #475; 0 otherwise."
-    )
-    erc20_direct_total: Amount = Field(
-        description="Informational: already valued by the ERC20_VAULT_BALANCE "
-        "balance fuse, never added to sum."
-    )
-    sum: Amount
-    on_chain_total_assets: Amount
-    delta: Amount
-    delta_percent: float
-    pending_withdrawals: Amount
-    implied_market_total: Amount
-    market_storage_divergence: int = Field(
-        description="balance_fuses_total minus implied_market_total, raw: "
-        "per-market caches drifting from the stored global total."
-    )
-
-    @classmethod
-    def from_reconciliation(
-        cls, rec: ValidationReconciliation, decimals: int
-    ) -> ReconciliationModel:
-        def amount(raw: int, usd: float | None = None) -> Amount:
-            return _amount(raw, decimals, usd)
-
-        return cls(
-            balance_fuses_total=amount(
-                rec.balance_fuses_total, rec.balance_fuses_total_usd
-            ),
-            underlying_on_vault=amount(
-                rec.underlying_on_vault, rec.underlying_on_vault_usd
-            ),
-            rewards_manager_balance=amount(
-                rec.rewards_manager_balance, rec.rewards_manager_balance_usd
-            ),
-            management_fee_netted=amount(
-                rec.management_fee_netted, rec.management_fee_netted_usd
-            ),
-            erc20_direct_total=amount(
-                rec.erc20_direct_total, rec.erc20_direct_total_usd
-            ),
-            sum=amount(rec.sum, rec.sum_usd),
-            on_chain_total_assets=amount(
-                rec.on_chain_total_assets, rec.on_chain_total_assets_usd
-            ),
-            delta=amount(rec.delta, rec.delta_usd),
-            delta_percent=rec.delta_percent,
-            pending_withdrawals=amount(
-                rec.pending_withdrawals, rec.pending_withdrawals_usd
-            ),
-            implied_market_total=amount(rec.implied_market_total),
-            market_storage_divergence=rec.market_storage_divergence,
-        )
-
-
-class LendingMarketModel(_Base):
-    protocol: str
-    market_id: MarketId
-    market_name: str
-    substrate_id: str | None = Field(
-        description="0x-prefixed Morpho market id or Aave V4 Spoke; null for "
-        "Aave V3, whose health is account-level."
-    )
-    current_ltv: float | None
-    max_ltv: float
-    health_factor: float | None
-    total_collateral_usd: float | None
-    total_debt_usd: float | None
-    ltv_usage_percent: float | None
-
-    @classmethod
-    def from_market(cls, m: ReaderLendingMarketHealth) -> LendingMarketModel:
-        substrate_id = m.substrate_id
-        if substrate_id is not None and not substrate_id.startswith("0x"):
-            substrate_id = f"0x{substrate_id}"
-        return cls(
-            protocol=m.protocol,
-            market_id=m.market_id,
-            market_name=m.market_name,
-            substrate_id=substrate_id,
-            current_ltv=m.current_ltv,
-            max_ltv=m.max_ltv,
-            health_factor=m.health_factor,
-            total_collateral_usd=m.total_collateral_usd,
-            total_debt_usd=m.total_debt_usd,
-            ltv_usage_percent=m.ltv_usage_percent,
-        )
-
-
-class LendingHealthModel(_Base):
-    markets: list[LendingMarketModel]
-    unreadable: list[UnreadableLendingMarket] = Field(
-        description="Positions whose health could not be read: unknown, not healthy."
-    )
-    worst_ltv_usage_percent: float | None
-
-    @classmethod
-    def from_health(cls, health: VaultLendingHealth) -> LendingHealthModel:
-        return cls(
-            markets=[LendingMarketModel.from_market(m) for m in health.markets],
-            unreadable=[
-                UnreadableLendingMarket(
-                    protocol=u.protocol,
-                    market_id=u.market_id,
-                    market_name=u.market_name,
-                    substrate_id=u.substrate_id,
-                    reason=u.reason,
-                )
-                for u in health.unreadable
-            ],
-            worst_ltv_usage_percent=health.worst_ltv_usage,
-        )
-
-
-class Erc20HoldingModel(_Base):
-    address: str
-    symbol: str
-    decimals: int | None
-    balance: Amount | None
-    price_usd: float | None
-    usd_value: float | None
-    note: str
-
-    @classmethod
-    def from_holding(cls, token: Erc20Holding) -> Erc20HoldingModel:
-        balance = (
-            _amount(token.balance, token.decimals)
-            if token.balance is not None and token.decimals is not None
-            else None
-        )
-        return cls(
-            address=token.address,
-            symbol=token.symbol,
-            decimals=token.decimals,
-            balance=balance,
-            price_usd=token.price_usd,
-            usd_value=token.usd_value,
-            note=token.note,
-        )
-
-
 class Erc20HoldingsModel(_Base):
-    tokens: list[Erc20HoldingModel]
+    """The ERC20_VAULT_BALANCE tokens read directly."""
+
+    tokens: list[ERC20Entry]
     value_in_asset: Amount
     market_cached_value: Amount = Field(
         description="What the ERC20_VAULT_BALANCE market last stored for "
         "these tokens, in the asset."
     )
-    unpriced_tokens: list[str]
-
-    @classmethod
-    def from_holdings(cls, erc20: Erc20Holdings, decimals: int) -> Erc20HoldingsModel:
-        return cls(
-            tokens=[Erc20HoldingModel.from_holding(t) for t in erc20.tokens],
-            value_in_asset=_amount(erc20.value_in_asset, decimals, erc20.value_usd),
-            market_cached_value=_amount(erc20.market_cached_value, decimals),
-            unpriced_tokens=list(erc20.unpriced_tokens),
-        )
+    unpriced_tokens: list[str] = Field(
+        description="Held tokens that could not be valued, as 'address (symbol)'."
+    )
 
 
 class VaultValidationResponse(_Base):
-    """Health verdict of one Plasma Vault at one block."""
+    """Health verdict of one Plasma Vault at one block; the same document as
+    ``fusion vault validate --json``."""
 
     vault: str
     chain: str
     chain_id: ChainId
     block: int
+    block_timestamp: int
     block_timestamp_utc: str
     asset: AssetInfo
     verdict: Verdict = Field(
         description="Worst severity found: critical if any critical finding, "
         "else warning if any warning, else ok."
     )
-    criticals: list[FindingModel]
-    warnings: list[FindingModel]
-    passed: list[FindingModel] = Field(
-        description="Checks that ran and found nothing wrong."
+    findings: list[FindingModel] = Field(
+        description="Every check in the order it ran, ok ones included."
     )
-    reconciliation: ReconciliationModel
-    lending_health: LendingHealthModel | None = Field(
+    reconciliation: Reconciliation
+    erc20: Erc20HoldingsModel
+    lending_health: LendingHealth | None = Field(
         description="LTV and health factor per lending market (Morpho, Aave "
-        "V3/V4); null when the vault has no lending position."
+        "V3/V4) and the positions that could not be read; null when the vault "
+        "has no lending position."
     )
-    erc20: Erc20HoldingsModel
-
-    @classmethod
-    def from_validation(cls, v: VaultValidation, chain: str) -> VaultValidationResponse:
-        def by(severity: Severity) -> list[FindingModel]:
-            return [
-                FindingModel(check=f.check, severity=f.severity, message=f.message)
-                for f in v.findings
-                if f.severity == severity
-            ]
-
-        health = v.lending_health
-        return cls(
-            vault=v.vault,
-            chain=chain,
-            chain_id=v.chain_id,
-            block=v.block_number,
-            block_timestamp_utc=datetime.fromtimestamp(
-                v.block_timestamp, tz=UTC
-            ).strftime("%Y-%m-%dT%H:%M:%SZ"),
-            asset=AssetInfo(
-                address=v.asset,
-                symbol=v.asset_symbol,
-                decimals=v.asset_decimals,
-                price_usd=v.asset_price_usd,
-            ),
-            verdict=v.verdict,
-            criticals=by("critical"),
-            warnings=by("warning"),
-            passed=by("ok"),
-            reconciliation=ReconciliationModel.from_reconciliation(
-                v.reconciliation, v.asset_decimals
-            ),
-            lending_health=(
-                LendingHealthModel.from_health(health)
-                if health is not None and health.has_lending_positions
-                else None
-            ),
-            erc20=Erc20HoldingsModel.from_holdings(v.erc20, v.asset_decimals),
-        )
 
 
 # ---------------------------------------------------------------------------

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev234}/src/ipor_fusion/mcp/server.py

@@ -65,7 +65,7 @@ from ipor_fusion.vault_data import (
     fetch_deployment_info,
     fetch_vault_data,
 )
-from ipor_fusion.vault_info import build_vault_info_json
+from ipor_fusion.vault_info import build_vault_info_json, build_vault_validation_json
 
 # chain_id default: detect the chain from the saved vault or the single provider.
 _AUTO_CHAIN = ChainId(0)
@@ -246,8 +246,10 @@ def vault_validate(
     resolve_access_manager(ctx, checksum)
 
     validation = validate_vault(ctx, checksum, block=effective_block, metadata=True)
-    return VaultValidationResponse.from_validation(
-        validation, CHAIN_NAMES.get(chain_id, str(chain_id))
+    return VaultValidationResponse.model_validate(
+        build_vault_validation_json(
+            validation, CHAIN_NAMES.get(chain_id, str(chain_id))
+        )
     )
 
 

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev234}/src/ipor_fusion/validation.py

@@ -345,7 +345,7 @@ def _reconcile(state: VaultState) -> Reconciliation:
     total = Amount(gross - fee)
     total_usd = balance_fuses_usd + underlying_usd + rewards_usd - fee_usd
     delta = Amount(total - on_chain)
-    delta_usd = abs(total_usd - (on_chain / 10**decimals * price)) if price else 0
+    delta_usd = abs(total_usd - (on_chain / 10**decimals * price)) if price else 0.0
     delta_percent = abs(delta / on_chain * 100) if on_chain else 0.0
 
     # totalAssets reads the global market total while balance fuses report