ipor-fusion 4.0.0.dev164__tar.gz → 4.0.0.dev171__tar.gz

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/AGENTS.md

@@ -32,9 +32,19 @@ uv run pytest -m "cli or mcp" --no-cov                        # fast offline sub
 uv run pytest --run-readiness -m readiness --no-cov -rA       # opt-in live Ethereum-hub POC checks
 uv run python scripts/crosschain_readiness.py --output /tmp/crosschain-readiness.json # live Arbitrum/HyperEVM report
 uv run pytest tests/test_fuse_encoding.py -k aave --no-cov    # single file / test
+UPDATE_GOLDEN=1 uv run pytest -k golden --no-cov              # rewrite pinned CLI/MCP output (tests/fixtures/*_golden/)
 uv lock --check                                               # uv.lock in sync with pyproject.toml
 ```
 
+**Golden output.** The exact text of `fusion vault info` (text and `--json`),
+`fusion market morpho-blue|meta-morpho --json`, `fusion vault oracle-mapping
+--json` and the matching MCP tools (`vault_info`, `market_morpho_blue`,
+`market_meta_morpho`, `vault_oracle_mapping`, called through the server) is pinned
+in `tests/fixtures/*_golden/` (`tests/_golden.py`, the `*_golden.py` tests), from
+recorded inputs and no network. A change to any of them fails those tests;
+regenerate with `UPDATE_GOLDEN=1` only when the change is intended and review the
+fixture diff. Without it the tests only compare.
+
 Run format, check, pyright and pytest after every code change; that is exactly
 the sequence in `.github/workflows/python-build.yml`. When ruff `C901` trips,
 extract helpers, never suppress.

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/MIGRATION_4.md

@@ -306,6 +306,14 @@ The internal `ipor_fusion.fuses.base` still re-exports them. The CLI's internal
 `ipor_fusion.cli.vault_cmd` was split into `options`, `vault_info_view`,
 `vault_markets_view` and `oracle_mapping_view` (private names, not API).
 
+**Event decoder modules renamed.** `ipor_fusion.fuses.external_state_events` and
+`ipor_fusion.fuses.hypercore_events` are now `external_state_event_decoding` and
+`hypercore_event_decoding`. The receipt decoder `hypercore_events`, re-exported
+from `ipor_fusion.fuses`, hid its submodule of the same name (`import
+ipor_fusion.fuses.hypercore_events as m` bound the function); the external-state
+module was renamed to match. Import the decoders with `from ipor_fusion import
+external_state_events, hypercore_events`; the modules are internal.
+
 **Removed.**
 
 - `IporFusionMarkets.RWA`: market 50 is `IporFusionMarkets.EXTERNAL_STATE`.
@@ -379,7 +387,7 @@ is the wrong one.
   from `IporFusionError`, so an `except IporFusionError` placed before their own
   handlers catches them first. All three live in `ipor_fusion.errors`, like every
   other SDK exception, and are exported from `ipor_fusion`; the modules that raise
-  them (`ipor_fusion.morpho_api`, `ipor_fusion.fuses.external_state_events`,
+  them (`ipor_fusion.morpho_api`, `ipor_fusion.fuses.external_state_event_decoding`,
   `ipor_fusion.crosschain.ccip.indexer`) still import the same classes.
 - `AccessManager.read_owner(ctx)` raises the new `OwnerNotFoundError` (a
   `LookupError`) when no account holds `OWNER_ROLE`, instead of an `IndexError`.
@@ -951,5 +959,22 @@ are listed with a link.
   decoder cannot read raises the decoder's error. 3.x left it out of
   `result.observations` (so `result.get(label)` raised `KeyError`) or reported an
   undecodable read as `None`, indistinguishable from a read that returns `None`.
+- **Check `success`; `error` is always set on failure.** A failed
+  `SimulatedCallResult` always carries a non-empty `error`: the node's message joined
+  with the decoded revert (`"execution reverted: NotAllowed"`), the decoded revert
+  alone when the node sent no message, else `"reverted without a reason"` (with the
+  return data's hex when it is too short to decode). 3.x could report `success=False`
+  with `error=None`, and `error` was the node's message only. A successful call's
+  `error` is `None`, and constructing one with an `error` raises `ValueError`.
+  `revert_reason` is `None` exactly when the call succeeded. The messages of
+  `SimulationResult.raise_for_failure` and `SimulationObservation.value`'s
+  `SimulationError` are `failed: {error}`; drop any `call.error or "reverted"`
+  fallback and match on `revert_reason`, not on the text of `error`.
+- **`SimulatedCallResult` and `SimulationResult` are frozen**, so the rule above
+  holds after construction too: assigning a field raises
+  `dataclasses.FrozenInstanceError`. Build a changed copy with
+  `dataclasses.replace(result, ...)` (a failed call's `error` is completed again).
+  Both stay unhashable (`__hash__` is `None`, as before). The freeze is shallow:
+  the `logs` / `calls` lists themselves can still be mutated.
 - Saved config entries are checksummed when loaded; the MCP `vault_add` tool rejects
   a value that is not an address.

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev164
+Version: 4.0.0.dev171
 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.dev164 → ipor_fusion-4.0.0.dev171}/examples/advanced_euler_v2_credit_market_base.py

@@ -191,9 +191,7 @@ def _assert_all_success(result: SimulationResult) -> None:
     if result.all_success:
         return
     failed = [(c.label, c.error) for c in result.failed_calls]
-    raise AssertionError(
-        f"simulation calls failed: {failed} (reason={result.revert_reason})"
-    )
+    raise AssertionError(f"simulation calls failed: {failed}")
 
 
 def _connected_web3() -> Web3:

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/examples/advanced_euler_v2_looping_arbitrum.py

@@ -153,9 +153,7 @@ def _assert_all_success(result: SimulationResult) -> None:
     if result.all_success:
         return
     failed = [(call.label, call.error) for call in result.failed_calls]
-    raise AssertionError(
-        f"simulation calls failed: {failed} (reason={result.revert_reason})"
-    )
+    raise AssertionError(f"simulation calls failed: {failed}")
 
 
 def _connected_web3() -> Web3:

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/examples/composed_hypercore_flow_arbitrum_hyperevm.py

@@ -634,7 +634,7 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
 # ── Part B: the hub legs, simulated at pinned blocks ─────────────────────────
 def _assert_relay_success(results: dict[ChainId, SimulationResult]) -> None:
     failed = [
-        f"{chain}:{call.label}:{call.revert_reason}"
+        f"{chain}:{call.label}:{call.error}"
         for chain, result in results.items()
         for call in result.calls
         if not call.success

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/examples/crosschain_ccip_usdc_arbitrum_hyperevm.py

@@ -179,7 +179,7 @@ def _assert_relay_success(results: dict[ChainId, SimulationResult]) -> None:
     """Raise with a readable summary if any simulated call on either chain
     reverted; each entry names the call and decodes its own revert."""
     failed = [
-        (int(chain_id), call.label, call.revert_reason or call.error)
+        (int(chain_id), call.label, call.error)
         for chain_id, result in results.items()
         for call in result.calls
         if not call.success

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/examples/external_state_margin_leg_base.py

@@ -332,9 +332,7 @@ def _assert_all_success(result: SimulationResult) -> None:
     if result.all_success:
         return
     failed = [(c.label, c.error) for c in result.failed_calls]
-    raise AssertionError(
-        f"simulation calls failed: {failed} (reason={result.revert_reason})"
-    )
+    raise AssertionError(f"simulation calls failed: {failed}")
 
 
 def _assert_only_expected_failure(result: SimulationResult, label: str) -> bytes:

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/examples/simple_aave_v3_supply_base.py

@@ -159,9 +159,7 @@ def _assert_all_success(result: SimulationResult) -> None:
     if result.all_success:
         return
     failed = [(c.label, c.error) for c in result.failed_calls]
-    raise AssertionError(
-        f"simulation calls failed: {failed} (reason={result.revert_reason})"
-    )
+    raise AssertionError(f"simulation calls failed: {failed}")
 
 
 def _connected_web3() -> Web3:

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/pyproject.toml

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

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/src/ipor_fusion/__init__.py

@@ -315,7 +315,7 @@ from ipor_fusion.fuses import (
     precompile_index_of,
     system_address,
 )
-from ipor_fusion.fuses.external_state_events import (
+from ipor_fusion.fuses.external_state_event_decoding import (
     EXTERNAL_STATE_EVENT_CLASSES,
     EXTERNAL_STATE_EVENT_SPECS,
     EXTERNAL_STATE_EVENTS,
@@ -343,7 +343,7 @@ from ipor_fusion.fuses.external_state_events import (
     external_state_event_name,
     external_state_events,
 )
-from ipor_fusion.fuses.hypercore_events import (
+from ipor_fusion.fuses.hypercore_event_decoding import (
     HYPERCORE_EVENT_CLASSES,
     HyperCoreActionEnqueuedArgs,
     HyperCoreActionEnqueuedEvent,

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/src/ipor_fusion/core/simulation.py

@@ -142,8 +142,17 @@ class _Block:
     override_provider: StateOverrideProvider | None = None
 
 
-@dataclass(slots=True)
+@dataclass(frozen=True, slots=True)
 class SimulatedCallResult:
+    """One simulated call. ``error`` is set exactly when ``success`` is False:
+    check ``success``, then read ``error`` for a non-empty, human-readable
+    failure (the node's message with the decoded revert reason, or
+    ``"reverted without a reason"`` plus any undecodable return data).
+    Construction enforces it: a failed call's ``error`` is completed from its
+    return data, and a successful call given an ``error`` raises
+    ``ValueError``. The record is frozen, so the invariant holds afterwards;
+    build a changed copy with `dataclasses.replace`."""
+
     label: str | None
     success: bool
     return_data: HexBytes
@@ -151,19 +160,33 @@ class SimulatedCallResult:
     error: str | None
     logs: list[dict]
     predicted_address: ChecksumAddress | None = None
+    # Frozen would add a __hash__ that fails on the logs list; stay unhashable.
+    __hash__ = None  # type: ignore[assignment]
+
+    def __post_init__(self) -> None:
+        if self.success:
+            if self.error is not None:
+                raise ValueError(
+                    f"successful simulated call {self.label!r} carries an error"
+                )
+        else:
+            # The record is frozen; completing the error is part of building it.
+            object.__setattr__(
+                self, "error", _failure_message(self.error, self.return_data)
+            )
 
     @property
     def revert_reason(self) -> str | None:
         """This call's decoded revert (a registered custom error by name, an
-        ``Error(string)`` text or ``Panic``), ``None`` when it succeeded or
-        reverted without data. ``SimulationResult.revert_reason`` is the
+        ``Error(string)`` text or ``Panic``), else its ``error``; ``None``
+        exactly when it succeeded. ``SimulationResult.revert_reason`` is the
         chain's first failed call, which may be a different one."""
         if self.success:
             return None
         return _decode_revert(self.return_data, self.error)
 
 
-@dataclass(slots=True)
+@dataclass(frozen=True, slots=True)
 class SimulationResult:
     success: bool
     all_success: bool
@@ -172,6 +195,7 @@ class SimulationResult:
     execute_logs: list[dict]
     calls: list[SimulatedCallResult] = field(default_factory=list)
     failed_calls: list[SimulatedCallResult] = field(default_factory=list)
+    __hash__ = None  # type: ignore[assignment]
 
     def raise_for_failure(self) -> None:
         """Raise :class:`SimulationError` naming the first failed call (label,
@@ -179,15 +203,11 @@ class SimulationResult:
         if not self.failed_calls:
             return
         first = self.failed_calls[0]
-        reason = _decode_revert(first.return_data, first.error)
         label = first.label or "<unlabelled>"
-        detail = first.error or "reverted"
-        if reason and reason != first.error:
-            detail = f"{detail}: {reason}"
         raise SimulationError(
-            f"simulated call {label!r} failed: {detail}",
+            f"simulated call {label!r} failed: {first.error}",
             label=first.label,
-            revert_reason=reason,
+            revert_reason=first.revert_reason,
         )
 
 
@@ -223,12 +243,10 @@ class SimulationObservation(Generic[T_co]):
         result = self.result
         name = self._label or "<unlabelled>"
         if not result.success:
-            reason = result.revert_reason
             raise SimulationError(
-                f"observation {name!r} failed: {result.error or 'reverted'}"
-                + (f": {reason}" if reason and reason != result.error else ""),
+                f"observation {name!r} failed: {result.error}",
                 label=self._label,
-                revert_reason=reason,
+                revert_reason=result.revert_reason,
             )
         if not result.return_data:
             raise EmptyCallResultError(
@@ -732,7 +750,7 @@ class VaultSimulator:
             status = int(raw.get("status", "0x1"), 16)
             success = status == 1
             gas_used = int(raw.get("gasUsed", "0x0"), 16)
-            error, return_data = _normalize_call_error(raw.get("error"), return_data)
+            message, return_data = _normalize_call_error(raw.get("error"), return_data)
             logs = raw.get("logs", []) or []
 
             call_result = SimulatedCallResult(
@@ -740,7 +758,7 @@ class VaultSimulator:
                 success=success,
                 return_data=return_data,
                 gas_used=gas_used,
-                error=error,
+                error=None if success else message,
                 logs=logs,
                 predicted_address=(source.predicted_address if success else None),
             )
@@ -753,14 +771,13 @@ class VaultSimulator:
                 execute_gas += gas_used
                 execute_logs.extend(logs)
                 if not success and revert_reason is None:
-                    revert_reason = _decode_revert(return_data, error)
+                    revert_reason = call_result.revert_reason
 
         failed_calls = [c for c in parsed if not c.success]
         all_success = not failed_calls
         if revert_reason is None and failed_calls:
             # No execute call reverted but a setup/observation did — surface it.
-            first_failed = failed_calls[0]
-            revert_reason = _decode_revert(first_failed.return_data, first_failed.error)
+            revert_reason = failed_calls[0].revert_reason
 
         return SimulationResult(
             success=execute_success,
@@ -910,6 +927,22 @@ def _normalize_call_error(
     return (error_raw if isinstance(error_raw, str) else None), return_data
 
 
+def _failure_message(message: str | None, return_data: HexBytes) -> str:
+    """A failed call's ``error``: the node's message joined with the decoded
+    revert unless the message already carries it, else whichever exists, else
+    ``"reverted without a reason"`` with any return data too short to decode."""
+    reason = _decode_revert(return_data, None)
+    if message and reason:
+        return message if reason in message else f"{message}: {reason}"
+    if message:
+        return message
+    if reason:
+        return reason
+    if return_data:
+        return f"reverted without a reason (return data 0x{bytes(return_data).hex()})"
+    return "reverted without a reason"
+
+
 def _decode_revert(return_data: HexBytes, error: str | None) -> str | None:
     if return_data and len(return_data) >= 4:
         selector = bytes(return_data[:4])

{ipor_fusion-4.0.0.dev164 → ipor_fusion-4.0.0.dev171}/src/ipor_fusion/fuses/__init__.py

@@ -49,7 +49,7 @@ from ipor_fusion.fuses.hypercore import (
     precompile_index_of,
     system_address,
 )
-from ipor_fusion.fuses.hypercore_events import (
+from ipor_fusion.fuses.hypercore_event_decoding import (
     HYPERCORE_EVENT_CLASSES,
     HYPERCORE_EVENT_SPECS,
     HYPERCORE_EVENTS,

ipor_fusion-4.0.0.dev171/tests/_golden.py

@@ -0,0 +1,69 @@
+"""Golden outputs: the exact text a CLI command or an MCP tool emits, pinned in
+``tests/fixtures/*_golden/``.
+
+Regenerate them only when an output change is intended, then review the diff:
+
+    UPDATE_GOLDEN=1 uv run pytest -k golden --no-cov
+
+Without ``UPDATE_GOLDEN`` (the default) a golden is only compared, never written.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from datetime import UTC, datetime, tzinfo
+from pathlib import Path
+
+from mcp.types import TextContent
+from pydantic import BaseModel
+
+from ipor_fusion.mcp.server import mcp
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+# The instant the goldens are rendered at: ages ("N days ago", `age_days`)
+# are relative to it.
+FROZEN_NOW = datetime(2026, 10, 1, tzinfo=UTC)
+
+
+class FrozenDatetime(datetime):
+    """`datetime` whose `now()` is `FROZEN_NOW`; patched over a module's
+    `datetime` import so its rendering does not depend on the wall clock."""
+
+    @classmethod
+    def now(cls, tz: tzinfo | None = None) -> FrozenDatetime:
+        return cls.fromtimestamp(FROZEN_NOW.timestamp(), tz)
+
+
+def assert_golden(path: Path, text: str) -> None:
+    """Compare ``text`` with the golden at ``path`` byte for byte; write it
+    instead when ``UPDATE_GOLDEN`` is set."""
+    if os.environ.get("UPDATE_GOLDEN"):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+    assert path.exists(), f"missing golden {path}; generate it with UPDATE_GOLDEN=1"
+    assert text == path.read_text(encoding="utf-8"), (
+        f"output differs from {path}; if the change is intended, regenerate "
+        "with UPDATE_GOLDEN=1 and review the diff"
+    )
+
+
+def mcp_tool_text(
+    tool: str, arguments: dict[str, object], model: type[BaseModel]
+) -> str:
+    """Call ``tool`` through the MCP server, as a client does, and return the
+    text it emits. Checks that the text is ``model_dump_json(indent=2)`` of the
+    tool's response model and carries the same document as its structured
+    content."""
+    result = asyncio.run(mcp.call_tool(tool, arguments))
+    # A tool with a typed return answers (content blocks, structured content).
+    assert isinstance(result, tuple) and len(result) == 2
+    content, structured = result
+    assert isinstance(content, list) and len(content) == 1
+    block = content[0]
+    assert isinstance(block, TextContent)
+    assert json.loads(block.text) == structured
+    assert block.text == model.model_validate(structured).model_dump_json(indent=2)
+    return block.text

ipor_fusion-4.0.0.dev171/tests/_oracle_mapping_fake.py

@@ -0,0 +1,200 @@
+"""In-memory stand-ins for the oracle mapping's chain reads: `FakeReader`
+answers what `OracleMappingReader` would, `FakeVault` the three reads
+`build_oracle_mapping` makes of the vault. No network, no RPC."""
+
+from __future__ import annotations
+
+from typing import Generic, TypedDict, TypeVar
+
+from web3 import Web3
+
+from ipor_fusion.types import Price
+
+T = TypeVar("T")
+
+
+def addr(n: int) -> str:
+    return Web3.to_checksum_address(f"0x{n:040x}")
+
+
+class Feed(TypedDict, total=False):
+    """What a price feed answers; an absent key is a getter that reverts."""
+
+    morpho_oracle: str
+    collateral: str
+    loan: str
+    vault: str
+    round: tuple[int, int, int, int, int]
+    feed_decimals: int
+    description: str | None
+    version: int
+    aggregator: str
+    phase_id: int
+    asset_x: str
+    xy_feed: str
+    y_usd_feed: str
+
+
+class Erc4626(TypedDict, total=False):
+    asset: str
+    decimals: int
+    rate: int
+
+
+class FakeReader:
+    """In-memory stand-in for :class:`oracle_mapping.OracleMappingReader`."""
+
+    def __init__(self) -> None:
+        self.symbols: dict[str, str] = {}
+        self.decimals: dict[str, int] = {}
+        self.prices: dict[str, Price] = {}
+        self.sources: dict[str, str] = {}
+        self.feeds: dict[str, Feed] = {}
+        self.vaults: dict[str, Erc4626] = {}
+        self.morpho_prices: dict[str, int] = {}
+        # oracle variant (middleware-fallback resolution); "_mw" because the
+        # exact method name would be shadowed by the attribute
+        self.underlying_mw: str | None = None
+        self.registry: str | None = None
+        self.delegated: FakeReader | None = None
+        # enumeration (configured_assets / asset_source_events)
+        self.configured: list[str] | None = None
+        self.events: list[tuple[int, str, str]] = []
+        self.events_to_block: int | None = None
+
+    # token metadata
+    def symbol(self, a: str) -> str | None:
+        return self.symbols.get(a)
+
+    def token_decimals(self, a: str) -> int | None:
+        return self.decimals.get(a)
+
+    # oracle
+    def asset_price(self, a: str) -> Price | None:
+        return self.prices.get(a)
+
+    def source_of(self, a: str) -> str | None:
+        return self.sources.get(a)
+
+    # oracle variant probes
+    def underlying_middleware(self) -> str | None:
+        return self.underlying_mw
+
+    def chainlink_feed_registry(self) -> str | None:
+        return self.registry
+
+    def delegate(self, oracle: str) -> FakeReader:
+        assert oracle == self.underlying_mw  # must delegate to the probed middleware
+        assert self.delegated is not None  # fail fast on a misconfigured test
+        return self.delegated
+
+    # feed probes
+    def _f(self, s: str) -> Feed:
+        return self.feeds.get(s, {})
+
+    def feed_morpho_oracle(self, s: str) -> str | None:
+        return self._f(s).get("morpho_oracle")
+
+    def feed_collateral_token(self, s: str) -> str | None:
+        return self._f(s).get("collateral")
+
+    def feed_loan_token(self, s: str) -> str | None:
+        return self._f(s).get("loan")
+
+    def feed_vault(self, s: str) -> str | None:
+        return self._f(s).get("vault")
+
+    def feed_latest_round_data(self, s: str) -> tuple[int, int, int, int, int] | None:
+        return self._f(s).get("round")
+
+    def feed_decimals(self, s: str) -> int | None:
+        return self._f(s).get("feed_decimals")
+
+    def feed_description(self, s: str) -> str | None:
+        return self._f(s).get("description")
+
+    def feed_version(self, s: str) -> int | None:
+        return self._f(s).get("version")
+
+    def feed_aggregator(self, s: str) -> str | None:
+        return self._f(s).get("aggregator")
+
+    def feed_phase_id(self, s: str) -> int | None:
+        return self._f(s).get("phase_id")
+
+    def morpho_oracle_price(self, o: str) -> int | None:
+        return self.morpho_prices.get(o)
+
+    def feed_asset_x(self, s: str) -> str | None:
+        return self._f(s).get("asset_x")
+
+    def feed_asset_x_asset_y_feed(self, s: str) -> str | None:
+        return self._f(s).get("xy_feed")
+
+    def feed_asset_y_usd_feed(self, s: str) -> str | None:
+        return self._f(s).get("y_usd_feed")
+
+    # erc4626 vault
+    def vault_asset(self, v: str) -> str | None:
+        return self.vaults.get(v, {}).get("asset")
+
+    def vault_decimals(self, v: str) -> int | None:
+        return self.vaults.get(v, {}).get("decimals")
+
+    def vault_convert_to_assets(self, v: str, shares: int) -> int | None:
+        return self.vaults.get(v, {}).get("rate")
+
+    # enumeration
+    def configured_assets(self) -> list[str] | None:
+        return self.configured
+
+    def asset_source_events(self, to_block: int) -> list[tuple[int, str, str]]:
+        self.events_to_block = to_block
+        return self.events
+
+
+def chainlink_asset(r: FakeReader, asset: str, source: str, *, symbol: str) -> None:
+    r.symbols[asset] = symbol
+    r.decimals[asset] = 6
+    r.sources[asset] = source
+    r.prices[asset] = Price(asset=asset, amount=99_980_000, decimals=8)
+    # full confirmed-tier evidence: description + version on top of the round
+    r.feeds[source] = {
+        "round": (1, 99_980_000, 0, 1_700_000_000, 1),
+        "feed_decimals": 8,
+        "description": f"{symbol} / USD",
+        "version": 4,
+    }
+
+
+class Returns(Generic[T]):
+    """Wraps a value as a Call-like object exposing .call(ctx)."""
+
+    def __init__(self, value: T):
+        self._value = value
+
+    def call(self, ctx: object) -> T:
+        return self._value
+
+
+class FakeVault:
+    """Stand-in for PlasmaVault — only the three reads build_oracle_mapping makes."""
+
+    def __init__(
+        self, oracle: str, asset: str, name: str, *, name_raises: bool = False
+    ):
+        self._oracle = oracle
+        self._asset = asset
+        self._name = name
+        self._name_raises = name_raises
+
+    def read_price_oracle_address(self, ctx: object) -> str:
+        return self._oracle
+
+    def underlying_asset_address(self) -> Returns[str]:
+        return Returns(self._asset)
+
+    def name(self) -> Returns[str]:
+        if self._name_raises:
+            raise RuntimeError("name() reverted")
+        return Returns(self._name)