ipor-fusion 4.0.0.dev106__tar.gz → 4.0.0.dev108__tar.gz

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/AGENTS.md

@@ -204,7 +204,13 @@ the lifecycle matrix follows that.
   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);
-  `cache.py` the on-disk contract and deployment caches (`~/.cache/ipor-fusion/`).
+  `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
+  through `cache_get`/`cache_put` (a failing cache is a miss, never an error) on
+  `ctx.cache` (`Web3Context(cache=...)`, default `default_contract_cache()` under
+  `$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.
@@ -388,8 +394,11 @@ byte, e.g. Ebisu ZAPPER/REGISTRY).
 role-accounts, oracle-mapping). `vault info` runs independent fetch pipelines
 (vault/asset, fees, WithdrawManager, markets, roles) concurrently on a
 `ThreadPoolExecutor`, each a short chain of `Multicall3` batches; keep new
-reads inside a batch rather than adding per-call round trips. Contract names
-and token symbols are cached in `~/.cache/ipor-fusion/contract_cache.json`.
+reads inside a batch rather than adding per-call round trips. Contract names,
+token symbols and decimals and deployment blocks are cached per chain in
+`$XDG_CACHE_HOME/ipor-fusion/contract_cache.json` (`<chain>:<address>:<field>`
+keys); tests redirect it with `monkeypatch.setenv("XDG_CACHE_HOME", ...)` or
+inject a cache.
 
 Every CLI command has an MCP tool (`fusion changelog` maps to `server_info`;
 the rest share names). Read-only: `vault_info`, `vault_validate`,

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/MIGRATION_4.md

@@ -334,6 +334,61 @@ argument (`chain_id=`) for another chain. An external signer still needs the rea
 target address (`call.to`) and builds the chain-qualified transaction itself, or
 gets it from `call.build_transaction(ctx)`.
 
+## Contract cache
+
+Contract names, token symbols and decimals and deployment blocks are cached in a
+`ContractCache`, injected instead of always written to `~/.cache`:
+
+- `Web3Context(..., cache=...)` and `Web3Context.from_url(..., cache=...)` take one
+  (keyword-only); `ctx.cache` returns it, and `ctx.at_block(...)` keeps it. The
+  default (`None`) is `default_contract_cache()`, a `FileContractCache` at
+  `$XDG_CACHE_HOME/ipor-fusion/contract_cache.json` (`~/.cache/...` when unset),
+  resolved when used rather than at import. `NullCache()` keeps nothing;
+  `FileContractCache(path)` moves the file; any object with `get(keys)` and
+  `put(entries)` over `CacheKey(chain_id, address, field)` → `str` fits the
+  protocol (for example a shared store in a service).
+- `resolve_token_symbol`, `resolve_token_decimals`, the snapshot's token metadata
+  (`fetch_vault_data(metadata=True)`) and `fetch_deployment_info` use `ctx.cache`.
+  `get_contract_name(chain_id, address, api_key=None, *, cache=None)` takes the cache
+  explicitly (default: the file cache); pass `cache=ctx.cache` to share the
+  context's policy. `build_vault_info_json` without `resolve_name` still names
+  contracts from the default file cache; pass `resolve_name` to avoid it.
+- `ipor_fusion.cache` is a public module now and exports `ContractCache`,
+  `FileContractCache`, `NullCache`, `CacheKey`, `CacheField`, `cache_key` and
+  `default_contract_cache` (also from `ipor_fusion`). Its 3.x functions and constants
+  are gone: `load_contract_cache`, `save_contract_cache`, `update_contract_cache`,
+  `load_deployment_cache`, `update_deployment_cache`, `CACHE_DIR`, `CACHE_FILE` and
+  `DEPLOYMENT_CACHE_FILE`. `cache_key(chain_id, address, field)` returns a `CacheKey`
+  and raises `ValueError` for an address that is not 20 bytes of hex, so
+  `get_contract_name` does too.
+
+**File format.** One file, keys `<chain_id>:<lowercase address>:<field>` (`name`,
+`symbol`, `decimals`, `deployment_block`, `deployment_timestamp`), string values. On
+load, a 3.x contract name (`<chain_id>:<address>`) is kept as that chain's `name`;
+3.x token entries (`symbol:<address>`, `decimals:<address>`) name no chain and are
+discarded, so symbols and decimals are read again once per chain. `deployment_cache.json`
+is no longer read: a vault's deployment block is resolved again (it needs an
+Etherscan key) and the old file can be deleted.
+
+**Behavior.**
+
+- The same address on two chains has two entries: a token's symbol or decimals read
+  on one chain is never served for another.
+- Absence is not cached: `resolve_token_symbol` still returns `"no contract"` for an
+  address without code, but no longer stores it, so a token deployed later (or seen at
+  a later block) resolves.
+- A write merges with the file as it is on disk and replaces it atomically (a
+  temporary file in the same directory, then `os.replace`), so a crash or two CLI/MCP
+  processes writing at once never leave a torn file; one of two concurrent writers may
+  lose its newest entry, which is read again later.
+- A cache never fails a read: a corrupt or unreadable file reads as empty (logged
+  warning from `ipor_fusion.cache`) and is rewritten by the next write; an unwritable
+  directory (read-only file system) keeps the entries in memory for the process; a
+  custom cache that raises is treated as a miss.
+- `fetch_deployment_info` returns `rpc-fetch-failed` only when the creation
+  transaction or its block cannot be read; a cache failure is no longer reported as
+  one (the deployment block is returned).
+
 ## Behavior changes
 
 - Two fuses are equal (and hash alike) only when they have the same class and the
@@ -371,9 +426,8 @@ gets it from `call.build_transaction(ctx)`.
 - `TransactionError.tx_hash` is `0x`-prefixed.
 - Saved config entries are checksummed when loaded; the MCP `vault_add` tool rejects
   a value that is not an address.
-- The on-disk caches (`~/.cache/ipor-fusion/`) key addresses lowercased; older entries
-  are rekeyed on load, so a contract name cached for one spelling now also resolves
-  for the other.
+- The contract cache keys every entry by chain and lowercase address and no longer
+  caches an absence (see [Contract cache](#contract-cache)).
 
 ## Errors
 

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev106
+Version: 4.0.0.dev108
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -381,11 +381,11 @@ release; adding one does not.
   `crosschain.fuses`, `crosschain.ccip` and `crosschain.stargate`. `ipor_fusion.guide`
   (the packaged docs) keeps its names in its own namespace.
 - **Public modules** stay importable for the top-level names they define:
-  `about`, `chains`, `dependency_graph`, `errors`, `explorer`, `field_docs`,
+  `about`, `cache`, `chains`, `dependency_graph`, `errors`, `explorer`, `field_docs`,
   `market_ids`, `market_info`, `morpho_api`, `substrates`, `types`, `validation`,
   `vault_data` and `vault_info` (all under `ipor_fusion.`).
 - **Internal:** `ipor_fusion.cli`, `ipor_fusion.mcp`, every other module (e.g.
-  `cache`, `vault_reads`, the submodules of the public subpackages), underscore
+  `vault_reads`, the submodules of the public subpackages), underscore
   names, and names in no `__all__`. They change without notice; the CLI and the
   MCP server are stable as commands and tools, not as Python modules.
 - **Preview features** (`PREVIEW_FEATURES` in `ipor_fusion.about`: crosschain,
@@ -495,6 +495,14 @@ fields as unavailable (`null`) rather than partial. A `LogSource` on the context
 a service that caches an explorer's log API, answers those scans instead
 (`Web3Context(log_source=…)`); when it raises `LogSourceUnavailable` the RPC scan runs.
 
+Immutable contract facts (token symbols and decimals, contract names, deployment blocks)
+are cached per chain and address in the context's `ContractCache`. The default,
+`FileContractCache`, is `$XDG_CACHE_HOME/ipor-fusion/contract_cache.json`
+(`~/.cache/...`), written atomically and ignored when corrupt or unwritable. A service
+passes `Web3Context(..., cache=NullCache())` to keep nothing, `FileContractCache(path)`
+to move it, or its own `get` / `put` implementation; `get_contract_name(..., cache=)`
+takes the same object.
+
 ## Development
 
 ```bash

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/README.md

@@ -333,11 +333,11 @@ release; adding one does not.
   `crosschain.fuses`, `crosschain.ccip` and `crosschain.stargate`. `ipor_fusion.guide`
   (the packaged docs) keeps its names in its own namespace.
 - **Public modules** stay importable for the top-level names they define:
-  `about`, `chains`, `dependency_graph`, `errors`, `explorer`, `field_docs`,
+  `about`, `cache`, `chains`, `dependency_graph`, `errors`, `explorer`, `field_docs`,
   `market_ids`, `market_info`, `morpho_api`, `substrates`, `types`, `validation`,
   `vault_data` and `vault_info` (all under `ipor_fusion.`).
 - **Internal:** `ipor_fusion.cli`, `ipor_fusion.mcp`, every other module (e.g.
-  `cache`, `vault_reads`, the submodules of the public subpackages), underscore
+  `vault_reads`, the submodules of the public subpackages), underscore
   names, and names in no `__all__`. They change without notice; the CLI and the
   MCP server are stable as commands and tools, not as Python modules.
 - **Preview features** (`PREVIEW_FEATURES` in `ipor_fusion.about`: crosschain,
@@ -447,6 +447,14 @@ fields as unavailable (`null`) rather than partial. A `LogSource` on the context
 a service that caches an explorer's log API, answers those scans instead
 (`Web3Context(log_source=…)`); when it raises `LogSourceUnavailable` the RPC scan runs.
 
+Immutable contract facts (token symbols and decimals, contract names, deployment blocks)
+are cached per chain and address in the context's `ContractCache`. The default,
+`FileContractCache`, is `$XDG_CACHE_HOME/ipor-fusion/contract_cache.json`
+(`~/.cache/...`), written atomically and ignored when corrupt or unwritable. A service
+passes `Web3Context(..., cache=NullCache())` to keep nothing, `FileContractCache(path)`
+to move it, or its own `get` / `put` implementation; `get_contract_name(..., cache=)`
+takes the same object.
+
 ## Development
 
 ```bash

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/pyproject.toml

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

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/src/ipor_fusion/__init__.py

@@ -7,6 +7,15 @@ from ipor_fusion.about import (
     read_changelog,
     repository_url,
 )
+from ipor_fusion.cache import (
+    CacheField,
+    CacheKey,
+    ContractCache,
+    FileContractCache,
+    NullCache,
+    cache_key,
+    default_contract_cache,
+)
 from ipor_fusion.chains import (
     CHAIN_NAME_TO_ID,
     CHAIN_NAMES,
@@ -741,6 +750,13 @@ __all__ = [
     "decode_custom_error",
     "get_revert_reason",
     "register_custom_errors",
+    "CacheField",
+    "CacheKey",
+    "ContractCache",
+    "FileContractCache",
+    "NullCache",
+    "cache_key",
+    "default_contract_cache",
     "get_contract_name",
     "get_deployment_tx",
     "CHAIN_NAMES",

ipor_fusion-4.0.0.dev108/src/ipor_fusion/cache.py

@@ -0,0 +1,204 @@
+"""Caches of immutable per-contract chain facts: contract names, token symbols
+and decimals, deployment blocks. A `ContractCache` is injected through
+`Web3Context(cache=...)` (and `get_contract_name(cache=...)`); the default is
+`FileContractCache` at ``$XDG_CACHE_HOME/ipor-fusion/contract_cache.json``,
+and `NullCache` disables caching.
+
+A cache is an optimization, never a source of failure: the SDK reads and
+writes it through `cache_get` / `cache_put`, which log and swallow any error a
+cache raises, and `FileContractCache` itself degrades to an in-memory map when
+its file is corrupt, unreadable or unwritable."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import threading
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Literal, NamedTuple, Protocol, cast, get_args
+
+from eth_typing import HexAddress
+
+from ipor_fusion.types import ChainId, parse_hex_address
+
+_logger = logging.getLogger(__name__)
+
+CacheField = Literal[
+    "name", "symbol", "decimals", "deployment_block", "deployment_timestamp"
+]
+_FIELDS: frozenset[str] = frozenset(get_args(CacheField))
+
+
+class CacheKey(NamedTuple):
+    """One fact about the contract at ``address`` on ``chain_id``. Build it
+    with `cache_key`, which normalizes the address to lowercase."""
+
+    chain_id: ChainId
+    address: HexAddress
+    field: CacheField
+
+
+def cache_key(chain_id: ChainId, address: HexAddress, field: CacheField) -> CacheKey:
+    return CacheKey(chain_id, parse_hex_address(address), field)
+
+
+class ContractCache(Protocol):
+    """Immutable facts keyed by chain, address and field, as strings. Store
+    only what cannot change for that key; absence (no code, no answer) is
+    never stored."""
+
+    def get(self, keys: Iterable[CacheKey]) -> dict[CacheKey, str]:
+        """The cached values of ``keys``; a miss is absent from the result."""
+        ...
+
+    def put(self, entries: Mapping[CacheKey, str]) -> None: ...
+
+
+class NullCache:
+    """A `ContractCache` that stores nothing: every read goes to the chain or
+    the explorer."""
+
+    def get(self, keys: Iterable[CacheKey]) -> dict[CacheKey, str]:
+        return {}
+
+    def put(self, entries: Mapping[CacheKey, str]) -> None:
+        return None
+
+
+def _encode(key: CacheKey) -> str:
+    return f"{key.chain_id}:{key.address}:{key.field}"
+
+
+def _decode(raw: str) -> CacheKey | None:
+    """The key of one stored entry, ``None`` for an entry that cannot be
+    attributed to a chain, an address and a field. A ``<chain>:<address>`` entry is a contract
+    name (the 3.x layout); 3.x token entries (``symbol:<address>``) carry no
+    chain and are dropped."""
+    parts = raw.split(":")
+    if len(parts) == 2:
+        parts.append("name")
+    if len(parts) != 3 or not parts[0].isdigit() or parts[2] not in _FIELDS:
+        return None
+    chain, address, field = parts
+    try:
+        return cache_key(
+            ChainId(int(chain)), parse_hex_address(address), cast(CacheField, field)
+        )
+    except ValueError:
+        return None
+
+
+class FileContractCache:
+    """A `ContractCache` in one JSON file, loaded once per instance.
+
+    A write merges into the file as it is on disk (another process may have
+    added entries) and replaces it atomically (a temporary file in the same
+    directory, then `os.replace`), so a crash or a concurrent writer never
+    leaves a torn file; concurrent writers may drop each other's latest entry,
+    which is refetched later. A corrupt or unreadable file reads as empty and
+    is rewritten by the next write; a failed write is logged and the entry
+    kept in memory only."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self._lock = threading.Lock()
+        self._entries: dict[CacheKey, str] | None = None
+
+    def get(self, keys: Iterable[CacheKey]) -> dict[CacheKey, str]:
+        with self._lock:
+            entries = self._loaded()
+            return {key: entries[key] for key in keys if key in entries}
+
+    def put(self, entries: Mapping[CacheKey, str]) -> None:
+        if not entries:
+            return
+        with self._lock:
+            merged = self._read() | (self._entries or {}) | dict(entries)
+            self._entries = merged
+            try:
+                self._write(merged)
+            except OSError as exc:
+                _logger.warning("contract cache %s not written: %s", self.path, exc)
+
+    def _loaded(self) -> dict[CacheKey, str]:
+        if self._entries is None:
+            self._entries = self._read()
+        return self._entries
+
+    def _read(self) -> dict[CacheKey, str]:
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return {}
+        except (OSError, ValueError) as exc:
+            _logger.warning("contract cache %s unreadable, ignored: %s", self.path, exc)
+            return {}
+        if not isinstance(raw, dict):
+            _logger.warning(
+                "contract cache %s is not a JSON object, ignored", self.path
+            )
+            return {}
+        entries: dict[CacheKey, str] = {}
+        for raw_key, value in raw.items():
+            key = _decode(raw_key)
+            if key is not None and isinstance(value, str):
+                # A canonical entry wins over a 3.x one spelled otherwise.
+                if key not in entries or _encode(key) == raw_key:
+                    entries[key] = value
+        return entries
+
+    def _write(self, entries: dict[CacheKey, str]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(
+            {_encode(key): entries[key] for key in sorted(entries)}, indent=2
+        )
+        fd, tmp = tempfile.mkstemp(
+            dir=self.path.parent, prefix=f".{self.path.name}.", suffix=".tmp"
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(payload)
+            os.replace(tmp, self.path)
+        except BaseException:
+            Path(tmp).unlink(missing_ok=True)
+            raise
+
+
+def default_cache_path() -> Path:
+    """``$XDG_CACHE_HOME/ipor-fusion/contract_cache.json``
+    (``~/.cache/...`` when unset), resolved at call time."""
+    home = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return home / "ipor-fusion" / "contract_cache.json"
+
+
+_defaults: dict[Path, FileContractCache] = {}
+_defaults_lock = threading.Lock()
+
+
+def default_contract_cache() -> FileContractCache:
+    """The process-wide `FileContractCache` at `default_cache_path`."""
+    path = default_cache_path()
+    with _defaults_lock:
+        if (cache := _defaults.get(path)) is None:
+            cache = _defaults[path] = FileContractCache(path)
+        return cache
+
+
+def cache_get(cache: ContractCache, keys: Iterable[CacheKey]) -> dict[CacheKey, str]:
+    """``cache.get(keys)``; a cache that raises reads as all misses."""
+    try:
+        return cache.get(keys)
+    except Exception as exc:
+        _logger.warning("contract cache read failed, ignored: %s", exc)
+        return {}
+
+
+def cache_put(cache: ContractCache, entries: Mapping[CacheKey, str]) -> None:
+    """``cache.put(entries)``; a cache that raises loses the entries."""
+    try:
+        cache.put(entries)
+    except Exception as exc:
+        _logger.warning("contract cache write failed, ignored: %s", exc)

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/src/ipor_fusion/cli/vault_info_view.py

@@ -87,7 +87,10 @@ def _print_vault_info(
 
     if json_output:
         result = build_vault_info_json(
-            data, resolve_name=partial(get_contract_name, chain_id, api_key=api_key)
+            data,
+            resolve_name=partial(
+                get_contract_name, chain_id, api_key=api_key, cache=ctx.cache
+            ),
         )
         click.echo(json.dumps(result, indent=2))
         return

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/src/ipor_fusion/core/context.py

@@ -18,6 +18,7 @@ from web3.providers.rpc.utils import (
 )
 from web3.types import BlockIdentifier, LogReceipt, TxParams, TxReceipt, Wei
 
+from ipor_fusion.cache import ContractCache, default_contract_cache
 from ipor_fusion.chains import GET_LOGS_RANGE_HINTS
 from ipor_fusion.core.logs import (
     DEFAULT_LOG_SCAN_MAX_REQUESTS,
@@ -81,6 +82,7 @@ class Web3Context:
         log_scan_timeout_s: float = DEFAULT_LOG_SCAN_TIMEOUT_S,
         log_scan_max_requests: int | None = DEFAULT_LOG_SCAN_MAX_REQUESTS,
         log_source: LogSource | None = None,
+        cache: ContractCache | None = None,
     ):
         self._web3 = web3
         self._chain_id = chain_id
@@ -90,6 +92,8 @@ class Web3Context:
         self.log_scan_max_requests = log_scan_max_requests
         # Asked first by `get_logs`; None scans the RPC only.
         self.log_source = log_source
+        # None: the process-wide file cache (`cache.default_contract_cache`).
+        self._cache = cache
         self._private_key = private_key
         self._gas_multiplier = gas_multiplier
         self._default_block: BlockIdentifier = "latest"
@@ -109,6 +113,14 @@ class Web3Context:
     def chain_id(self) -> ChainId:
         return self._chain_id
 
+    @property
+    def cache(self) -> ContractCache:
+        """Where the SDK keeps immutable contract facts read through this
+        context (token symbols and decimals, contract names, deployment
+        blocks): the ``cache=`` passed in, else the file cache under
+        ``$XDG_CACHE_HOME/ipor-fusion/``. Pass `NullCache()` to keep nothing."""
+        return self._cache if self._cache is not None else default_contract_cache()
+
     @property
     def default_block(self) -> BlockIdentifier:
         return self._default_block
@@ -119,7 +131,7 @@ class Web3Context:
 
     def at_block(self, block: BlockIdentifier) -> Web3Context:
         """A copy of this context whose reads default to ``block``: same
-        connection, signer, log source and scan bounds. Pinning a copy leaves
+        connection, signer, log source, cache and scan bounds. Pinning a copy leaves
         this context (and anything sharing it across threads) untouched."""
         pinned = copy.copy(self)
         pinned._default_block = block
@@ -140,6 +152,7 @@ class Web3Context:
         log_scan_timeout_s: float = DEFAULT_LOG_SCAN_TIMEOUT_S,
         log_scan_max_requests: int | None = DEFAULT_LOG_SCAN_MAX_REQUESTS,
         log_source: LogSource | None = None,
+        cache: ContractCache | None = None,
     ) -> Web3Context:
         web3 = Web3(
             Web3.HTTPProvider(
@@ -168,6 +181,7 @@ class Web3Context:
             log_scan_timeout_s=log_scan_timeout_s,
             log_scan_max_requests=log_scan_max_requests,
             log_source=log_source,
+            cache=cache,
         )
 
     def call(

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/src/ipor_fusion/explorer.py

@@ -1,6 +1,6 @@
-"""Etherscan V2 client: contract names (cached on disk) and contract creation
-transactions. Every lookup needs an API key; without one, names come from the
-cache only."""
+"""Etherscan V2 client: contract names (cached in a `ContractCache`) and
+contract creation transactions. Every lookup needs an API key; without one,
+names come from the cache only."""
 
 from __future__ import annotations
 
@@ -12,7 +12,13 @@ from urllib.request import urlopen
 
 from eth_typing import HexAddress
 
-from ipor_fusion.cache import cache_key, load_contract_cache, update_contract_cache
+from ipor_fusion.cache import (
+    ContractCache,
+    cache_get,
+    cache_key,
+    cache_put,
+    default_contract_cache,
+)
 from ipor_fusion.types import ChainId, TxHash, parse_tx_hash
 
 ETHERSCAN_V2_URL = "https://api.etherscan.io/v2/api"
@@ -43,16 +49,22 @@ _etherscan_limiter = _RateLimiter(2.5)
 
 
 def get_contract_name(
-    chain_id: ChainId, address: HexAddress, api_key: str | None = None
+    chain_id: ChainId,
+    address: HexAddress,
+    api_key: str | None = None,
+    *,
+    cache: ContractCache | None = None,
 ) -> str:
-    cache = load_contract_cache()
-    key = cache_key(chain_id, address)
-
-    if cached := cache.get(key):
+    """The verified contract name at ``address``, ``""`` when unknown. Read from
+    ``cache`` first (default: the file cache, `default_contract_cache`; pass a
+    context's ``ctx.cache`` to share its policy), else from Etherscan when
+    ``api_key`` is set; a name found there is cached, its absence is not."""
+    store = default_contract_cache() if cache is None else cache
+    key = cache_key(chain_id, address, "name")
+    if cached := cache_get(store, [key]).get(key):
         return cached
-
     if name := _fetch_contract_name(chain_id, address, api_key):
-        update_contract_cache(key, name)
+        cache_put(store, {key: name})
         return name
     return ""
 

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev108}/src/ipor_fusion/mcp/server.py

@@ -210,7 +210,10 @@ def vault_info(
     ) = fetch_deployment_info(ctx, checksum, api_key=api_key)
 
     result = build_vault_info_json(
-        data, resolve_name=partial(get_contract_name, chain_id, api_key=api_key)
+        data,
+        resolve_name=partial(
+            get_contract_name, chain_id, api_key=api_key, cache=ctx.cache
+        ),
     )
     return VaultInfoResponse.model_validate(result)