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

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

@@ -155,8 +155,8 @@ the lifecycle matrix follows that.
   cases and non-obvious logic.
 - The public API is `ipor_fusion.__all__` (README, "Public API and stability").
   Every public symbol is imported and listed there; a symbol of a public
-  subpackage (`core`, `config`, `fuses`, `fuses.crosschain`, `readers`,
-  `crosschain`, `crosschain.ccip`, `crosschain.stargate`) also goes in 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`,
   `field_docs`, `market_ids`, `market_info`, `morpho_api`, `substrates`, `types`,
@@ -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.
@@ -224,7 +230,7 @@ the lifecycle matrix follows that.
   (`FuseAction`), `fuse` (the `Fuse` base, `StakeFuse`, the shared validators and
   substrate packers), `address` (`_validate_not_zero_address`). `core` imports neither
   `fuses` nor `crosschain` (`tests/test_sdk_layering.py`)
-- `fuses/` — per-protocol fuse encoders (aave_v3, async_action, compound_v3, crosschain/,
+- `fuses/` — per-protocol fuse encoders (aave_v3, async_action, compound_v3,
   erc4626, euler_v2, external_state, fluid_instadapp, gearbox_v3, merkl, morpho, ramses_v2,
   uniswap_v3, universal, `events.py`); `base.py` re-exports the `core/fuse.py` base and validators,
   `FuseAction` and `ZERO_ADDRESS` (from `types`). A fuse is a value: equality and
@@ -251,15 +257,20 @@ the lifecycle matrix follows that.
   (`CcipOffRamp.execute` is the permissionless delivery) and `ccip/indexer` fetches a
   message's verifier result from Chainlink's public indexers and builds that
   `manual_execution` call.
-  `fuses/crosschain/` mirrors it (`base`, `stargate`, `ccip`). Names mirror
-  the Solidity contracts and libraries. Adding a transport: a new subpackage plus one
-  `LANES` entry. Layering: the fuse encoders import the wire codecs and wrappers; lanes,
-  discovery, transports and the simulator import the encoders. A package `__init__`
-  runs before its modules, so `ipor_fusion.crosschain`, `.stargate` and `.ccip`
-  export only the fuse-free half; the rest is exported from `ipor_fusion` and
-  imported by module path. `tests/test_crosschain_layering.py` pins this (no
-  function-level or `TYPE_CHECKING` imports in either package); never work around
-  a cycle with a lazy import, move the module instead.
+  The market fuse encoders live in `crosschain/fuses/` (`base`, `stargate`, `ccip`),
+  mirroring `contracts/fuses/crosschain/`; they build on `core/fuse.py`, so the
+  dependency direction is `core` <- `crosschain` and `fuses/` holds no crosschain code
+  (neither package imports the other). Names mirror the Solidity contracts and
+  libraries. Adding a transport: a new subpackage, its encoders in `crosschain/fuses/`
+  and one `LANES` entry. Layering: the encoders import the wire codecs and wrappers;
+  lanes, discovery, transports and the simulator import the encoders.
+  `ipor_fusion.crosschain` exports the whole surface (encoders, lanes, discovery,
+  transports, simulator). A package `__init__` runs before its modules and the
+  encoders import `ccip.contracts` / `stargate.layerzero`, so `.ccip` and `.stargate`
+  export only their codecs and wrappers. `tests/test_crosschain_layering.py` pins this:
+  the SDK's module-level import graph, with the implicit package-`__init__` edges, is
+  acyclic, and the crosschain package has no function-level or `TYPE_CHECKING`
+  imports; never work around a cycle with a lazy import, move the module instead.
 - `readers/` — read side: lending_health, oracle_mapping, position_manager, aave_v3,
   compound_v3, morpho, ramses_v2, uniswap_v3, unpriceable (middleware-priced tokens of
   granted substrates the oracle cannot price)
@@ -383,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.dev103 → ipor_fusion-4.0.0.dev108}/MIGRATION_4.md

@@ -220,6 +220,27 @@ live in `ipor_fusion.core.fuse`; `ipor_fusion.fuses.base`, `ipor_fusion.fuses` a
 hash now cover every attribute a fuse stores, not only its class and address (see
 [Behavior changes](#behavior-changes)).
 
+**Crosschain fuse encoders moved.** The crosschain market encoders moved from
+`ipor_fusion.fuses.crosschain` into the crosschain package, and
+`ipor_fusion.fuses` no longer re-exports them. There is no shim: the old paths
+raise `ImportError`. The top-level names (`from ipor_fusion import ...`) are
+unchanged.
+
+| 3.x import | 4.0 import |
+|---|---|
+| `ipor_fusion.fuses.crosschain` | `ipor_fusion.crosschain.fuses` (or `ipor_fusion.crosschain`) |
+| `ipor_fusion.fuses.crosschain.base` | `ipor_fusion.crosschain.fuses.base` |
+| `ipor_fusion.fuses.crosschain.ccip` | `ipor_fusion.crosschain.fuses.ccip` |
+| `ipor_fusion.fuses.crosschain.stargate` | `ipor_fusion.crosschain.fuses.stargate` |
+| `from ipor_fusion.fuses import CcipCrosschainSupplyFuse` (and the other crosschain encoders, `SendParams`, `CrosschainSubstrate*`, `crosschain_market_id`) | `from ipor_fusion.crosschain import ...` or `from ipor_fusion import ...` |
+
+`ipor_fusion.crosschain` now exports the whole crosschain surface: besides the
+codecs and wrappers, the encoders, `CrosschainLane`, `CcipLane`, `StargateLane`,
+the transports and chains, `discover_deployment`, `open_lane(s)`, `LANES` and
+`CrosschainSimulator`, which 3.x exported only from `ipor_fusion`.
+`ipor_fusion.crosschain.ccip` and `.stargate` keep exporting only their codecs
+and wrappers.
+
 **Moved, still importable.** `FuseAction` lives in `ipor_fusion.core.fuse_action` and
 `ZERO_ADDRESS` in `ipor_fusion.types`; both are re-exported from
 `ipor_fusion.fuses.base` and `FuseAction` from `ipor_fusion`. The CLI's internal
@@ -313,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
@@ -350,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.dev103 → ipor_fusion-4.0.0.dev108}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev103
+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
@@ -377,15 +377,15 @@ renaming a name in it, or changing a signature incompatibly, waits for a major
 release; adding one does not.
 
 - **Public subpackages** declare their own `__all__`, each a subset of the top
-  level: `ipor_fusion.core`, `config`, `fuses`, `fuses.crosschain`, `readers`,
-  `crosschain`, `crosschain.ccip` and `crosschain.stargate`. `ipor_fusion.guide`
+  level: `ipor_fusion.core`, `config`, `fuses`, `readers`, `crosschain`,
+  `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.dev103 → ipor_fusion-4.0.0.dev108}/README.md

@@ -329,15 +329,15 @@ renaming a name in it, or changing a signature incompatibly, waits for a major
 release; adding one does not.
 
 - **Public subpackages** declare their own `__all__`, each a subset of the top
-  level: `ipor_fusion.core`, `config`, `fuses`, `fuses.crosschain`, `readers`,
-  `crosschain`, `crosschain.ccip` and `crosschain.stargate`. `ipor_fusion.guide`
+  level: `ipor_fusion.core`, `config`, `fuses`, `readers`, `crosschain`,
+  `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.dev103 → ipor_fusion-4.0.0.dev108}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev103"
+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.dev103 → 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,
@@ -79,17 +88,24 @@ from ipor_fusion.crosschain import (
     EMPTY_COMMAND,
     INDEXER_URLS,
     INSUFFICIENT_NATIVE_FEE_SELECTOR,
+    LANES,
     PACKET_SENT_TOPIC,
+    SYNTHETIC_TOKEN_SOURCE,
     ActiveCommand,
     Any2EVMMessage,
     BalanceObservation,
     BusinessAction,
+    CcipChain,
+    CcipCommandType,
     CcipCommitteeVerifier,
+    CcipCrosschainCommandFuse,
     CcipCrosschainDispatcher,
     CcipCrosschainExecutor,
     CcipCrosschainFactory,
+    CcipCrosschainSupplyFuse,
     CcipEvent,
     CcipEventSpec,
+    CcipLane,
     CcipMessageSent,
     CcipMsgType,
     CcipObservation,
@@ -97,32 +113,57 @@ from ipor_fusion.crosschain import (
     CcipOnRamp,
     CcipRouteConfig,
     CcipRouter,
+    CcipSendParams,
     CcipTokenAdminRegistry,
     CcipTokenLane,
     CcipTokenPool,
+    CcipTransport,
     CcipVerifierResolver,
     CcvRequirements,
     Command,
     CommandStatus,
+    CrosschainClaimFuse,
+    CrosschainCommandFuse,
+    CrosschainDeployment,
     CrosschainDispatcher,
     CrosschainExecutor,
+    CrosschainExecutorInfo,
     CrosschainFactory,
+    CrosschainLane,
+    CrosschainSimulator,
+    CrosschainSubstrate,
+    CrosschainSubstrateLib,
+    CrosschainSubstrateType,
+    CrosschainSupplyFuse,
+    CrosschainTransport,
     CrosschainTransportKind,
+    DeliveryCall,
     DeploymentStatus,
     EnforcedOptionParam,
     EVMTokenAmount,
     ExecutorInitParams,
+    LaneFuses,
+    LaneObservation,
     MessageExecutionState,
     MessageV1,
     MsgType,
     Observation,
     OptionsBuilder,
+    OutboundMessage,
     Packet,
     SafetyConfig,
+    SendParams,
+    StargateChain,
+    StargateCrosschainCommandFuse,
+    StargateCrosschainCommandType,
     StargateCrosschainDispatcher,
     StargateCrosschainExecutor,
     StargateCrosschainFactory,
+    StargateCrosschainSupplyFuse,
+    StargateLane,
+    StargateSendParams,
     StargateTokenMessaging,
+    StargateTransport,
     TaxiMessage,
     TokenTransferV1,
     VerifierResult,
@@ -130,10 +171,14 @@ from ipor_fusion.crosschain import (
     ccip_events,
     ccip_receive_calldata,
     ccip_token_lane,
+    crosschain_market_id,
     decode_ccip_envelope,
     decode_ccip_event,
     decode_command,
     decode_envelope,
+    detect_transport,
+    discover_deployment,
+    discover_lane_fuses,
     encode_enforced_options,
     encode_oft_compose_msg,
     fetch_verifier_result,
@@ -141,29 +186,9 @@ from ipor_fusion.crosschain import (
     lz_compose_calldata,
     lz_receive_calldata,
     manual_execution,
-    quote_ccip_native_fee,
-)
-from ipor_fusion.crosschain.ccip.lane import CcipLane
-from ipor_fusion.crosschain.ccip.transport import CcipChain, CcipTransport
-from ipor_fusion.crosschain.discovery import (
-    LANES,
-    CrosschainDeployment,
-    CrosschainExecutorInfo,
-    detect_transport,
-    discover_deployment,
-    discover_lane_fuses,
     open_lane,
     open_lanes,
-)
-from ipor_fusion.crosschain.lane import CrosschainLane, LaneFuses, LaneObservation
-from ipor_fusion.crosschain.simulation import CrosschainSimulator
-from ipor_fusion.crosschain.stargate.lane import StargateLane
-from ipor_fusion.crosschain.stargate.transport import StargateChain, StargateTransport
-from ipor_fusion.crosschain.transport import (
-    SYNTHETIC_TOKEN_SOURCE,
-    CrosschainTransport,
-    DeliveryCall,
-    OutboundMessage,
+    quote_ccip_native_fee,
 )
 from ipor_fusion.dependency_graph import (
     compute_update_groups,
@@ -206,17 +231,7 @@ from ipor_fusion.fuses import (
     AaveV3SupplyFuse,
     AsyncActionFuse,
     AsyncActionSubstrates,
-    CcipCommandType,
-    CcipCrosschainCommandFuse,
-    CcipCrosschainSupplyFuse,
-    CcipSendParams,
     CompoundV3SupplyFuse,
-    CrosschainClaimFuse,
-    CrosschainCommandFuse,
-    CrosschainSubstrate,
-    CrosschainSubstrateLib,
-    CrosschainSubstrateType,
-    CrosschainSupplyFuse,
     ERC4626SupplyFuse,
     EulerSwapDynamicParams,
     EulerSwapInitialState,
@@ -261,13 +276,8 @@ from ipor_fusion.fuses import (
     RamsesV2CollectFuse,
     RamsesV2ModifyPositionFuse,
     RamsesV2NewPositionFuse,
-    SendParams,
     SettlementMode,
     StakeFuse,
-    StargateCrosschainCommandFuse,
-    StargateCrosschainCommandType,
-    StargateCrosschainSupplyFuse,
-    StargateSendParams,
     TimeInForce,
     UniswapV3ClosePositionEvent,
     UniswapV3CollectFuse,
@@ -279,7 +289,6 @@ from ipor_fusion.fuses import (
     UniversalTokenSwapperAbi,
     UniversalTokenSwapperFuse,
     UniversalTokenSwapperSubstrates,
-    crosschain_market_id,
     decode_hypercore_event,
     euler_substrate,
     find_hypercore_events,
@@ -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)