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

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

@@ -158,7 +158,7 @@ the lifecycle matrix follows that.
   subpackage (`core`, `config`, `fuses`, `readers`, `crosschain`,
   `crosschain.fuses`, `crosschain.ccip`, `crosschain.stargate`) also goes in that
   subpackage's `__all__`. `ipor_fusion.guide` keeps its own namespace. The
-  public modules (`about`, `chains`, `dependency_graph`, `errors`, `explorer`,
+  public modules (`about`, `cache`, `chains`, `dependency_graph`, `errors`, `explorer`,
   `field_docs`, `market_ids`, `market_info`, `morpho_api`, `substrates`, `types`,
   `validation`, `vault_data`, `vault_info`) stay importable for the names they
   define; `cli`, `mcp` and every other module are internal. Examples, the guide
@@ -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.dev110}/MIGRATION_4.md

@@ -334,6 +334,66 @@ 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. The CLI's text and JSON output name contracts through the
+  context's cache.
+- `build_vault_info_json(data)` without `resolve_name` names no contract (every
+  `contract` is `"?"`) instead of reading names from the on-disk cache; pass
+  `resolve_name=partial(get_contract_name, chain_id, api_key=..., cache=ctx.cache)`
+  for the CLI's document.
+- `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, and so is a stored number that does
+  not parse.
+- `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 +431,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.dev110}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev106"
+version = "4.0.0.dev110"
 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.dev110}/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.dev110/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.dev110}/src/ipor_fusion/cli/vault_info_view.py

@@ -85,10 +85,11 @@ def _print_vault_info(
         data.deployment_error,
     ) = fetch_deployment_info(ctx, data.vault, api_key=api_key)
 
+    resolve_name = partial(
+        get_contract_name, chain_id, api_key=api_key, cache=ctx.cache
+    )
     if json_output:
-        result = build_vault_info_json(
-            data, resolve_name=partial(get_contract_name, chain_id, api_key=api_key)
-        )
+        result = build_vault_info_json(data, resolve_name=resolve_name)
         click.echo(json.dumps(result, indent=2))
         return
 
@@ -102,7 +103,7 @@ def _print_vault_info(
 
     _print_role_accounts(_role_accounts_json(data))
 
-    _print_markets(data, api_key)
+    _print_markets(data, resolve_name)
 
     validation = validate_vault_state(data)
     click.echo("ERC20 Balances (vault holdings):")

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev110}/src/ipor_fusion/cli/vault_markets_view.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from concurrent.futures import Future, ThreadPoolExecutor
 from typing import Any
 
@@ -13,12 +13,11 @@ from ipor_fusion.cli.vault_rendering import (
     _print_table,
     _substrate_details,
 )
-from ipor_fusion.explorer import get_contract_name
 from ipor_fusion.substrates import (
     decode_substrate,
     format_market_label,
 )
-from ipor_fusion.types import ChainId, FuseAddress, MarketId, parse_hex_address
+from ipor_fusion.types import FuseAddress, MarketId, parse_hex_address
 from ipor_fusion.vault_data import (
     GET_MARKET_SUBSTRATES,
     VaultData,
@@ -27,6 +26,10 @@ from ipor_fusion.vault_info import (
     _CAPABILITY_BALANCE_FUSES,
 )
 
+# Address to contract name, "" when unknown (`get_contract_name` bound to the
+# chain, API key and the context's cache).
+NameResolver = Callable[[HexAddress], str]
+
 
 def _print_lending_health(data: VaultData) -> None:  # noqa: C901
     lh = data.lending_health
@@ -154,16 +157,14 @@ def _print_health_lines(market: Any, indent: str) -> None:
     click.secho(f"{indent}Status:        {status}", fg=color, bold=bold)
 
 
-def _print_markets(data: VaultData, api_key: str | None) -> None:
+def _print_markets(data: VaultData, resolve_name: NameResolver) -> None:
     """Fuses, balance fuses, dependency graph and substrates."""
-    chain_id = data.chain_id
     _print_fuse_section(
         "Fuses",
         data.fuses,
         data.fuse_markets,
         data.market_substrates,
-        chain_id,
-        api_key,
+        resolve_name,
     )
     click.echo()
 
@@ -172,18 +173,17 @@ def _print_markets(data: VaultData, api_key: str | None) -> None:
         data.instant_fuses,
         data.fuse_markets,
         data.market_substrates,
-        chain_id,
-        api_key,
+        resolve_name,
     )
     click.echo()
 
-    _print_balance_fuses_table(data, api_key)
+    _print_balance_fuses_table(data, resolve_name)
     click.echo()
 
     _print_dependency_graph(data)
 
     click.echo("Substrates per Market:")
-    _print_market_substrates(data, api_key)
+    _print_market_substrates(data, resolve_name)
     click.echo()
 
 
@@ -235,8 +235,7 @@ def _print_fuse_section(
     fuses: Sequence[FuseAddress],
     fuse_markets: dict[FuseAddress, MarketId] | None,
     market_substrates: dict[MarketId, list[bytes]] | None,
-    chain_id: ChainId,
-    api_key: str | None,
+    resolve_name: NameResolver,
 ) -> None:
     """Render a fuse section (regular or instant-withdrawal) with a unified
     layout.
@@ -262,10 +261,7 @@ def _print_fuse_section(
         return
 
     with ThreadPoolExecutor() as pool:
-        name_futs = {
-            addr: pool.submit(get_contract_name, chain_id, addr, api_key)
-            for addr in counts
-        }
+        name_futs = {addr: pool.submit(resolve_name, addr) for addr in counts}
         rows: list[tuple[str, ...]] = []
         for idx, addr in enumerate(counts, 1):
             market_label = "?"
@@ -285,7 +281,7 @@ def _print_fuse_section(
     _print_table(("#", "Address", "Contract", "Market", "Substrates"), rows)
 
 
-def _print_balance_fuses_table(data: VaultData, api_key: str | None) -> None:
+def _print_balance_fuses_table(data: VaultData, resolve_name: NameResolver) -> None:
     balance_fuses = data.balance_fuses
     decimals = data.asset_decimals
     asset_symbol = data.asset_symbol
@@ -294,9 +290,7 @@ def _print_balance_fuses_table(data: VaultData, api_key: str | None) -> None:
         futures: list[tuple[int, MarketId, str, Future]] = []
         for idx, balance_fuse in enumerate(balance_fuses, 1):
             market_id_str = format_market_label(balance_fuse.market_id)
-            f_contract = pool.submit(
-                get_contract_name, data.chain_id, balance_fuse.fuse, api_key
-            )
+            f_contract = pool.submit(resolve_name, balance_fuse.fuse)
             futures.append((idx, balance_fuse.market_id, market_id_str, f_contract))
 
         venue_rows: list[tuple[str, ...]] = []
@@ -328,18 +322,18 @@ def _print_balance_fuses_table(data: VaultData, api_key: str | None) -> None:
         _print_table(header, [(str(i), *row) for i, row in enumerate(zero_rows, 1)])
 
 
-def _print_market_substrates(data: VaultData, api_key: str | None) -> set[str]:
+def _print_market_substrates(data: VaultData, resolve_name: NameResolver) -> set[str]:
     if GET_MARKET_SUBSTRATES in data.unimplemented_getters:
         click.secho(
             f"  (unavailable: the vault predates {GET_MARKET_SUBSTRATES})",
             fg="yellow",
         )
         return set()
-    return _print_substrates(data, api_key)
+    return _print_substrates(data, resolve_name)
 
 
 def _print_substrates(  # noqa: C901
-    data: VaultData, api_key: str | None
+    data: VaultData, resolve_name: NameResolver
 ) -> set[str]:
     substrates_by_market = data.market_substrates or {}
     balance_fuses = data.balance_fuses
@@ -364,8 +358,7 @@ def _print_substrates(  # noqa: C901
     resolved_symbols = data.token_symbols
     with ThreadPoolExecutor() as pool:
         contract_futs = {
-            addr: pool.submit(get_contract_name, data.chain_id, addr, api_key)
-            for addr in all_addresses
+            addr: pool.submit(resolve_name, addr) for addr in all_addresses
         }
         resolved_contracts = {addr: fut.result() for addr, fut in contract_futs.items()}
 

{ipor_fusion-4.0.0.dev106 → ipor_fusion-4.0.0.dev110}/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(