ipor-fusion 4.0.0.dev116__tar.gz → 4.0.0.dev120__tar.gz

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/AGENTS.md

@@ -429,7 +429,9 @@ are not validated.
   everything validation and the ``vault info`` document need, so neither reads the
   chain. The chain is `ctx.chain_id`; ``lending=False`` skips lending health, the
   position breakdowns, their prices and the unpriceable check; ``metadata=False``
-  skips token symbols/decimals. Add a new chain-state input to the snapshot, never a
+  reads no token symbol or decimals at all (`validate_vault`'s default), and
+  ``metadata=True`` reads them in one cached Multicall3 batch that also names the
+  ERC20 holdings. Add a new chain-state input to the snapshot, never a
   read inside a renderer or validator.
 - PlasmaVault serves governance/view functions via `fallback()` delegatecall to
   PlasmaVaultBase, so Etherscan's ABI for the vault address omits callable

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/MIGRATION_4.md

@@ -14,10 +14,11 @@ type-checked or not. In particular, `fetch_market` and
 (pyright, mypy, Pylance) also wraps literals and raw values as below. Values the SDK
 returns already carry their type and go back in unwrapped.
 
-All types are importable from `ipor_fusion` (and `ipor_fusion.types`), as are
-`USDC_TOKEN_INDEX` and `hip3_action_asset`; `ChecksumAddress` and `HexAddress` come
-from `eth_typing` and `BlockIdentifier` from `web3.types`. The wrappers label values;
-they do not validate byte widths or address spelling.
+The SDK's own types are importable from `ipor_fusion` (and `ipor_fusion.types`),
+as are `USDC_TOKEN_INDEX` and `hip3_action_asset`. 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.
 
 ## Building the types
 
@@ -64,12 +65,15 @@ chain is always the context's:
   the vault address (not a `PlasmaVault`) and no `chain_id`. It resolves one block
   (``block``, else a numeric `ctx.default_block`, else the latest) and runs every
   read, log scans included, on `ctx.at_block(block)`; `ctx` is not modified. The old
-  ``chain_id=0`` switch is ``lending=False``; ``metadata=False`` skips token symbols
-  and decimals. `VaultData` gains `vault`, `chain_id`, `market_balances`, `erc20`,
+  ``chain_id=0`` switch is ``lending=False``; ``metadata=False`` reads no token
+  symbol or decimals (the ERC20 holdings' symbols are then `"?"`), and with
+  ``metadata=True`` the holdings are named by the same cached, batched read as
+  `token_symbols`. `VaultData` gains `vault`, `chain_id`, `market_balances`, `erc20`,
   `token_symbols` and `token_decimals`; `WithdrawManagerData` gains
   `shares_to_release_assets` and `pending_request_assets`.
-- `validate_vault(ctx, vault, *, block=None)` fetches with ``metadata=False`` and
-  validates; it no longer takes ``resolve_symbol``. `validate_vault_state(state)` is
+- `validate_vault(ctx, vault, *, block=None, metadata=False)` fetches (by default
+  without token metadata) and validates; it no longer takes ``resolve_symbol``.
+  ``metadata=True`` names the ERC20 holdings in the result and its findings. `validate_vault_state(state)` is
   pure: a custom `VaultState` also provides `vault`, `chain_id`, `market_balances`,
   `erc20` and the queue's `shares_to_release_assets`. `read_erc20_holdings` is gone:
   the holdings are `VaultData.erc20`.
@@ -92,6 +96,10 @@ are `Fee`, `management_fee_last_update` a `Timestamp`, `unrealized_management_fe
 `Amount`; `WithdrawManagerData.withdraw_window` is a `Period`, its fees `Fee`,
 `shares_to_release` `Shares`, `last_release_funds_timestamp` a `Timestamp` and the
 converted amounts `Amount`. A custom `VaultState` annotates the same.
+`VaultValidation.block_timestamp` is a `Timestamp` and `asset_decimals` `Decimals`;
+`Erc20Holding.decimals` / `balance` are `Decimals | None` / `Amount | None` and
+`Erc20Holdings.value_in_asset` / `market_cached_value` `Amount`;
+`VaultData.token_decimals` values and `resolve_token_decimals` are `Decimals | None`.
 `PlasmaVault.total_supply()`, `balance_of()` and `get_total_supply_cap()` return
 `Shares` (vault shares), and `transfer` / `approve` / `transfer_from` /
 `set_total_supply_cap` take `Shares`; `ERC20` keeps `Amount`. The supply cap is
@@ -114,13 +122,15 @@ typed for `str` still fits). Market-keyed data is keyed by `MarketId`:
 and the `dependency_graph` helpers (`compute_update_reach`, `compute_update_groups`,
 `find_orphan_fuse_markets`, `find_markets_missing_erc20_dependency`).
 
-`VaultData.asset`, `price_oracle_addr`, `rewards_manager`, `withdraw_manager`,
+`VaultData.price_oracle_addr` is renamed `price_oracle`, like its sibling
+address fields (a custom `VaultState` renames it too).
+`VaultData.asset`, `price_oracle`, `rewards_manager`, `withdraw_manager`,
 `FeeData.fee_manager` / `ipor_dao_fee_recipient` and `VaultValidation.vault` /
 `asset` are `ChecksumAddress` (`VaultValidation.vault` a `PlasmaVaultAddress`);
 `VaultData.access_manager` is an `AccessManagerAddress`, `fuses` / `instant_fuses`
 and the `fuse_markets` keys are `FuseAddress`, `balance_fuses` is
 `list[BalanceFuse]`, and `token_prices_usd` is keyed by lowercase `HexAddress`. A
-custom `VaultState` implementation annotates `asset` and `price_oracle_addr` as
+custom `VaultState` implementation annotates `asset` and `price_oracle` as
 `ChecksumAddress`, `fuse_markets` keys as `FuseAddress`, and its
 `unpriceable_priced_tokens` items' `market_id` as `MarketId` (`UnpriceableToken`).
 The Uniswap V3 / Ramses V2 position events' `version`, `sender` and `recipient` are
@@ -155,6 +165,13 @@ Every fuse constructor, `FuseAction.fuse`, `BalanceFuse.fuse`,
 `FusionInstance.access_manager` return one. `resolve_access_manager` still takes any
 `ChecksumAddress`: it is what checks that the address is a vault.
 
+The vault parameter is named `vault` throughout: `validate_vault`,
+`fetch_deployment_info`, `fetch_vault_lending_health`, `build_oracle_mapping`,
+`read_external_state`, `ExternalStateExecutor.for_vault`, `read_hypercore_nav`,
+`read_hypercore_vault_state`, `read_hypercore_transfer_snapshot`,
+`read_hypercore_evm_exit_ceiling` and `resolve_access_manager` renamed
+``vault_address`` to ``vault``; only a call that passes it by keyword changes.
+
 **Simulation and factory records.** `VaultSimulator(web3, *, vault=None, alpha=None,
 block=...)` takes every argument after `web3` by keyword, and `vault` and `alpha` are
 optional: a simulator that only observes, deploys or sends `execute_call(call,

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/PKG-INFO

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

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

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/cli/vault_cmd.py

@@ -257,7 +257,9 @@ def validate(
         raise click.UsageError(str(exc)) from exc
 
     try:
-        validation = validate_vault(ctx, vault_address, block=block_number)
+        validation = validate_vault(
+            ctx, vault_address, block=block_number, metadata=True
+        )
     except UnsupportedVaultVersionError as exc:
         raise click.ClickException(str(exc)) from exc
 

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/cli/vault_info_view.py

@@ -191,7 +191,7 @@ def _print_supply(data: VaultData) -> None:
 
 def _print_managers(data: VaultData) -> None:
     click.echo(f"Access Manager:   {data.access_manager}")
-    click.echo(f"Price Oracle:     {data.price_oracle_addr}")
+    click.echo(f"Price Oracle:     {data.price_oracle}")
     click.echo(f"Rewards Manager:  {data.rewards_manager or 'N/A'}")
     click.echo(f"Withdraw Manager: {data.withdraw_manager or 'N/A'}")
     if data.withdraw_manager_data:

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/core/access.py

@@ -182,9 +182,7 @@ class AccessManager(ContractWrapper):
         )
 
 
-def resolve_access_manager(
-    ctx: Web3Context, vault_address: ChecksumAddress
-) -> AccessManager:
+def resolve_access_manager(ctx: Web3Context, vault: ChecksumAddress) -> AccessManager:
     """Resolve a vault address to its AccessManager, with typed guards. An
     eager resolver: it reads on ``ctx`` and returns a context-free wrapper.
 
@@ -195,7 +193,7 @@ def resolve_access_manager(
     (InsufficientDataBytes) or a revert (ContractLogicError).
     Provider/transport errors propagate unchanged.
     """
-    checksum = Web3.to_checksum_address(vault_address)
+    checksum = Web3.to_checksum_address(vault)
     # Same block as the eth_call below, or a pre-deployment pin would pass
     # this guard and get misdiagnosed as "not a vault".
     code = ctx.web3.eth.get_code(checksum, block_identifier=ctx.default_block)

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/core/context.py

@@ -21,6 +21,7 @@ from web3.providers.rpc.utils import (
 from web3.types import (
     BlockIdentifier,
     LogReceipt,
+    MakeBatchRequestFn,
     MakeRequestFn,
     RPCEndpoint,
     RPCResponse,
@@ -192,7 +193,14 @@ class Web3Context:
         # and leaves every other block untouched.
         web3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)
         if max_concurrent_requests is not None:
-            web3.middleware_onion.add(_in_flight_limit(max_concurrent_requests))
+            # Innermost (layer 0, injected last): a slot covers only the provider
+            # call, so a middleware that issues its own request (the gas price
+            # strategy reads a block) never waits on the slot it already holds.
+            web3.middleware_onion.inject(
+                _in_flight_limit(max_concurrent_requests),
+                name="in_flight_limit",
+                layer=0,
+            )
         chain_id = ChainId(web3.eth.chain_id)
 
         return cls(
@@ -411,7 +419,8 @@ class Web3Context:
 
 def _in_flight_limit(limit: int) -> type[Web3Middleware]:
     """A middleware class (web3 instantiates it per Web3) holding a semaphore
-    slot for the duration of each provider request."""
+    slot for the duration of each provider call; a JSON-RPC batch is one HTTP
+    request, so it takes one slot whatever its item count."""
     if limit < 1:
         raise ValueError(f"max_concurrent_requests must be at least 1, got {limit}")
     slots = threading.BoundedSemaphore(limit)
@@ -424,4 +433,15 @@ def _in_flight_limit(limit: int) -> type[Web3Middleware]:
 
             return limited
 
+        def wrap_make_batch_request(
+            self, make_batch_request: MakeBatchRequestFn
+        ) -> MakeBatchRequestFn:
+            def limited(
+                requests_info: list[tuple[RPCEndpoint, Any]],
+            ) -> list[RPCResponse] | RPCResponse:
+                with slots:
+                    return make_batch_request(requests_info)
+
+            return limited
+
     return InFlightLimit

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/core/external_state_executor.py

@@ -234,7 +234,7 @@ def _snapshot_block(ctx: Web3Context) -> tuple[BlockIdentifier, int]:
 
 
 def read_external_state(
-    ctx: Web3Context, vault_address: PlasmaVaultAddress
+    ctx: Web3Context, vault: PlasmaVaultAddress
 ) -> ExternalStateVaultState:
     """Read the external-state market's vault state as one coherent snapshot.
 
@@ -249,19 +249,19 @@ def read_external_state(
     executor word is ``None`` (no executor deployed), which is a state, while
     an RPC or decoding failure raises.
     """
-    vault = Web3.to_checksum_address(vault_address)
+    checksum = Web3.to_checksum_address(vault)
     read_at, block = _snapshot_block(ctx)
     base = ExternalStateExecutor._EXECUTOR_STORAGE_SLOT
     words = [
-        _storage_word(ctx.get_storage_at(vault, base + i, read_at)) for i in range(4)
+        _storage_word(ctx.get_storage_at(checksum, base + i, read_at)) for i in range(4)
     ]
     if words[0] >> 160:
         raise ExternalStateError(
-            f"malformed executor word in the external-state storage of {vault}"
+            f"malformed executor word in the external-state storage of {checksum}"
         )
     if words[3] not in (0, 1):
         raise ExternalStateError(
-            f"malformed pause flag in the external-state storage of {vault}"
+            f"malformed pause flag in the external-state storage of {checksum}"
         )
     return ExternalStateVaultState(
         executor=Web3.to_checksum_address(f"0x{words[0]:040x}") if words[0] else None,
@@ -321,7 +321,7 @@ class ExternalStateExecutor(ContractWrapper):
 
     @classmethod
     def for_vault(
-        cls, ctx: Web3Context, vault_address: PlasmaVaultAddress
+        cls, ctx: Web3Context, vault: PlasmaVaultAddress
     ) -> ExternalStateExecutor:
         """Resolve the per-vault executor from vault storage (at
         ``ctx.default_block``) and wrap it. An eager resolver: the wrapper it
@@ -334,17 +334,16 @@ class ExternalStateExecutor(ContractWrapper):
         """
         word = _storage_word(
             ctx.get_storage_at(
-                Web3.to_checksum_address(vault_address), cls._EXECUTOR_STORAGE_SLOT
+                Web3.to_checksum_address(vault), cls._EXECUTOR_STORAGE_SLOT
             )
         )
         if word >> 160:
             raise ExternalStateError(
-                f"malformed executor word in the external-state storage of "
-                f"{vault_address}"
+                f"malformed executor word in the external-state storage of {vault}"
             )
         if word == 0:
             raise ExternalStateError(
-                f"no ExternalStateExecutor deployed for vault {vault_address}"
+                f"no ExternalStateExecutor deployed for vault {vault}"
             )
         return cls(Web3.to_checksum_address(f"0x{word:040x}"))
 

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/mcp/server.py

@@ -245,7 +245,7 @@ def vault_validate(
     # Same cheap probe as vault_info: "not a vault" fails before the fetch.
     resolve_access_manager(ctx, checksum)
 
-    validation = validate_vault(ctx, checksum, block=effective_block)
+    validation = validate_vault(ctx, checksum, block=effective_block, metadata=True)
     return VaultValidationResponse.from_validation(
         validation, CHAIN_NAMES.get(chain_id, str(chain_id))
     )

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/readers/hypercore.py

@@ -575,7 +575,7 @@ def _perp_leg(
 
 def read_hypercore_nav(
     ctx: Web3Context,
-    vault_address: PlasmaVaultAddress,
+    vault: PlasmaVaultAddress,
     market_id: MarketId = HYPERCORE_MARKET,
 ) -> HyperCoreNav:
     """Reproduce ``HyperCoreValuationLib.liveValueWad(market_id)`` for the
@@ -589,17 +589,17 @@ def read_hypercore_nav(
     library reverts on (no price, overflow, a failed precompile) raise
     :class:`~ipor_fusion.errors.HyperCoreValuationError`.
     """
-    vault = PlasmaVault(vault_address)
+    pv = PlasmaVault(vault)
     reader = HyperCoreReader()
     multicall = Multicall3(ctx)
     substrates, oracle_address, exists, native = multicall.aggregate(
         cast(
             list[Call[Any]],
             [
-                vault.get_market_substrates(market_id),
-                vault.get_price_oracle_middleware_address(),
-                reader.core_user_exists(vault_address),
-                reader.account_margin_summary(NATIVE_PERP_DEX, vault_address),
+                pv.get_market_substrates(market_id),
+                pv.get_price_oracle_middleware_address(),
+                reader.core_user_exists(vault),
+                reader.account_margin_summary(NATIVE_PERP_DEX, vault),
             ],
         )
     )
@@ -611,11 +611,11 @@ def read_hypercore_nav(
     calls: list[Call[Any]] = []
     for index, evm_asset in tokens:
         calls += [
-            reader.spot_balance(vault_address, index),
+            reader.spot_balance(vault, index),
             reader.token_info(index),
             oracle.get_asset_price(evm_asset),
         ]
-    calls += [reader.account_margin_summary(dex, vault_address) for dex in dexes]
+    calls += [reader.account_margin_summary(dex, vault) for dex in dexes]
     results = multicall.try_aggregate(calls)
     spot = tuple(
         _spot_leg(index, evm_asset, *results[3 * i : 3 * i + 3])
@@ -685,7 +685,7 @@ def _granted_perp_markets(
 
 def read_hypercore_vault_state(
     ctx: Web3Context,
-    vault_address: PlasmaVaultAddress,
+    vault: PlasmaVaultAddress,
     balance_fuse: FuseAddress,
     market_id: MarketId = HYPERCORE_MARKET,
     *,
@@ -695,14 +695,14 @@ def read_hypercore_vault_state(
     the vault's context, the pending state (when a reader is known for the
     chain or given) and the granted perp markets with their coin names, all
     at ``ctx.default_block``."""
-    nav = read_hypercore_nav(ctx, vault_address, market_id)
-    vault = PlasmaVault(vault_address)
+    nav = read_hypercore_nav(ctx, vault, market_id)
+    pv = PlasmaVault(vault)
     reader = HyperCoreReader()
     pending_reader = pending_reader or HYPERCORE_PENDING_READERS.get(ctx.chain_id)
-    granted = _granted_perp_markets(vault.get_market_substrates(market_id).call(ctx))
-    calls: list[Call[Any]] = [vault.balance_fuse_value(balance_fuse)]
+    granted = _granted_perp_markets(pv.get_market_substrates(market_id).call(ctx))
+    calls: list[Call[Any]] = [pv.balance_fuse_value(balance_fuse)]
     if pending_reader is not None:
-        calls.append(HyperCorePendingReader(vault, pending_reader).pending_state())
+        calls.append(HyperCorePendingReader(pv, pending_reader).pending_state())
     calls += [reader.perp_asset_info(read_index_of(asset)) for asset, _, _ in granted]
     results = Multicall3(ctx).try_aggregate(calls)
     fuse_value = results[0]

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/readers/hypercore_outcome.py

@@ -110,7 +110,7 @@ def _pinned_context(ctx: Web3Context) -> tuple[Web3Context, int]:
 
 def read_hypercore_transfer_snapshot(
     ctx: Web3Context,
-    vault_address: PlasmaVaultAddress,
+    vault: PlasmaVaultAddress,
     evm_token: ChecksumAddress,
     *,
     token_index: HyperCoreTokenIndex = USDC_TOKEN_INDEX,
@@ -128,21 +128,21 @@ def read_hypercore_transfer_snapshot(
         raise UnsupportedChainError(
             f"no HyperCorePendingReader known for chain {ctx.chain_id}"
         )
-    vault = PlasmaVault(vault_address)
+    pv = PlasmaVault(vault)
     reader = HyperCoreReader()
     calls = cast(
         list[Call[Any]],
         [
-            reader.core_user_exists(vault_address),
-            reader.spot_balance(vault_address, token_index),
-            ERC20(evm_token).balance_of(vault_address),
-            HyperCorePendingReader(vault, pending_reader).pending_state(),
+            reader.core_user_exists(vault),
+            reader.spot_balance(vault, token_index),
+            ERC20(evm_token).balance_of(vault),
+            HyperCorePendingReader(pv, pending_reader).pending_state(),
         ],
     )
     exists, spot, evm_balance, pending = Multicall3(pinned).aggregate(calls)
     return HyperCoreTransferSnapshot(
         block_number=block,
-        vault=vault_address,
+        vault=vault,
         token_index=token_index,
         evm_token=evm_token,
         action_nonce=pending.action_nonce,
@@ -258,26 +258,26 @@ def read_hypercore_transfer_outcome(
 
 
 def read_hypercore_evm_exit_ceiling(
-    ctx: Web3Context, vault_address: PlasmaVaultAddress, holder: ChecksumAddress
+    ctx: Web3Context, vault: PlasmaVaultAddress, holder: ChecksumAddress
 ) -> HyperCoreEvmExitCeiling:
     """Read the holder's upper bound for an immediate EVM underlying exit.
 
     This uses idle ERC-20 only and is a ceiling, not an executable quote.
     """
     pinned, _ = _pinned_context(ctx)
-    vault = PlasmaVault(vault_address)
+    pv = PlasmaVault(vault)
     shares, asset = Multicall3(pinned).aggregate(
         cast(
             list[Call[Any]],
-            [vault.balance_of(holder), vault.underlying_asset_address()],
+            [pv.balance_of(holder), pv.underlying_asset_address()],
         )
     )
     share_assets, idle = Multicall3(pinned).aggregate(
         cast(
             list[Call[Any]],
             [
-                vault.convert_to_assets(shares),
-                ERC20(asset).balance_of(vault_address),
+                pv.convert_to_assets(shares),
+                ERC20(asset).balance_of(vault),
             ],
         )
     )

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/readers/lending_health.py

@@ -392,7 +392,7 @@ def _collect_lending_markets(
 
 def fetch_vault_lending_health(
     ctx: Web3Context,
-    vault_address: PlasmaVaultAddress,
+    vault: PlasmaVaultAddress,
     *,
     balance_fuse_market_ids: list[MarketId],
     market_substrates: dict[MarketId, list[bytes]],
@@ -402,7 +402,7 @@ def fetch_vault_lending_health(
 
     Args:
         ctx: Web3 context for on-chain calls.
-        vault_address: The Plasma Vault address.
+        vault: The Plasma Vault address.
         balance_fuse_market_ids: List of market IDs from balance fuses.
         market_substrates: Map of market_id -> list of raw substrate bytes.
             Morpho market ids and Aave V4 Spokes are read from it.
@@ -434,7 +434,7 @@ def fetch_vault_lending_health(
                         ctx,
                         morpho_reader,
                         morpho_mid,
-                        vault_address,
+                        vault,
                         ipor_mid,
                         name,
                     )
@@ -447,7 +447,7 @@ def fetch_vault_lending_health(
                     _compute_aave_market_health,
                     ctx,
                     AaveV3Reader(aave_pool),
-                    vault_address,
+                    vault,
                     ipor_mid,
                     name,
                 )
@@ -459,7 +459,7 @@ def fetch_vault_lending_health(
                     _compute_aave_v4_market_health,
                     ctx,
                     spoke,
-                    vault_address,
+                    vault,
                     ipor_mid,
                     name,
                 )

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/readers/oracle_mapping.py

@@ -427,23 +427,23 @@ def _enumerate_assets(
 
 def build_oracle_mapping(
     ctx: Web3Context,
-    vault_address: PlasmaVaultAddress,
+    vault: PlasmaVaultAddress,
     effective_block: int,
     max_depth: int = 6,
 ) -> OracleMapping:
-    """Build the full oracle mapping for ``vault_address``.
+    """Build the full oracle mapping for ``vault``.
 
     ``ctx`` must already be pinned to ``effective_block`` (the caller sets
     ``ctx.default_block``); the block is echoed in the output. Raises
     `UnsupportedVaultVersionError` for a vault that exposes no price-oracle
     getter.
     """
-    vault = PlasmaVault(vault_address)
-    oracle_addr = vault.read_price_oracle_address(ctx)
-    asset_addr = vault.underlying_asset_address().call(ctx)
+    pv = PlasmaVault(vault)
+    oracle_addr = pv.read_price_oracle_address(ctx)
+    asset_addr = pv.underlying_asset_address().call(ctx)
 
     try:
-        vault_name = vault.name().call(ctx)
+        vault_name = pv.name().call(ctx)
     except Exception:
         vault_name = None
 
@@ -468,7 +468,7 @@ def build_oracle_mapping(
             )
 
     return OracleMapping(
-        vault=vault_address,
+        vault=vault,
         vault_name=vault_name,
         asset=OracleAsset(
             address=asset_addr,

{ipor_fusion-4.0.0.dev116 → ipor_fusion-4.0.0.dev120}/src/ipor_fusion/validation.py

@@ -120,7 +120,7 @@ class VaultState(Protocol):
     @property
     def underlying_balance_on_vault(self) -> Amount: ...
     @property
-    def price_oracle_addr(self) -> ChecksumAddress: ...
+    def price_oracle(self) -> ChecksumAddress: ...
     @property
     def balance_fuses(self) -> Sequence[BalanceFuse]: ...
     @property
@@ -202,10 +202,10 @@ class VaultValidation:
     vault: PlasmaVaultAddress
     chain_id: ChainId
     block_number: int
-    block_timestamp: int
+    block_timestamp: Timestamp
     asset: ChecksumAddress
     asset_symbol: str
-    asset_decimals: int
+    asset_decimals: Decimals
     asset_price_usd: float | None
     findings: tuple[Finding, ...]
     reconciliation: Reconciliation
@@ -236,15 +236,20 @@ class VaultValidation:
 
 def validate_vault(
     ctx: Web3Context,
-    vault_address: PlasmaVaultAddress,
+    vault: PlasmaVaultAddress,
     *,
     block: int | None = None,
+    metadata: bool = False,
 ) -> VaultValidation:
     """Fetch the vault's snapshot at one block (`fetch_vault_data`: ``block``,
     else the context's numeric default block, else the latest) and validate
-    it; ``ctx`` itself is not modified."""
+    it; ``ctx`` itself is not modified.
+
+    The checks need no token metadata, so none is read by default and the
+    ERC20 holdings are named ``"?"``; ``metadata=True`` adds one batched,
+    cached symbol read that names them in the holdings and findings."""
     return validate_vault_state(
-        fetch_vault_data(ctx, vault_address, block=block, metadata=False)
+        fetch_vault_data(ctx, vault, block=block, metadata=metadata)
     )