ipor-fusion 4.0.0.dev151__tar.gz → 4.0.0.dev156__tar.gz

{ipor_fusion-4.0.0.dev151 → ipor_fusion-4.0.0.dev156}/AGENTS.md

@@ -186,7 +186,7 @@ the lifecycle matrix follows that.
 | Python 3.12 runtime, 3.11 floor | `.python-version` + CI `python-version` default; `requires-python`, ruff `target-version`, pyright `pythonVersion` |
 | `IporFusionMarkets`, `Roles` | `market_ids.py`, `config/roles.py` mirror `IporFusionMarkets.sol`, `Roles.sol` in `ipor-fusion/contracts/libraries/`; drift-gated by `tests/test_solidity_mirrors.py` — bump its pinned ref in the same change that syncs the mirrors An id sourced from a contracts feature branch ahead of the pinned ref goes in the test's `_AHEAD_OF_UPSTREAM` allowlist and is removed when the ref catches up |
 | substrate decoders | `substrates.py` registry mirrors each market's `contracts/fuses/<protocol>/*SubstrateLib.sol` or `*FuseLib.sol` |
-| `vault_info` JSON shape | `build_vault_info_json` in `vault_info.py`, models in `mcp/models.py` (`extra="forbid"`), `_full_vault_info_dict` fixture in `test_mcp_models.py` |
+| `vault_info` / `fusion market` JSON shapes | the builders and their TypedDicts (`VaultInfoJson`, `MorphoBlueMarketJson`, `MetaMorphoV1Json` / `MetaMorphoV2Json`) in `vault_info.py` / `market_info.py`, models in `mcp/models.py` (`extra="forbid"`, the published schema), the `VaultInfoJson`-typed `_full_vault_info_dict` fixture in `test_mcp_models.py` |
 | CLI command set | every CLI command has a matching tool in `mcp/server.py` (`changelog` maps to `server_info`) |
 
 ## Layout (`src/ipor_fusion/`)
@@ -207,14 +207,14 @@ the lifecycle matrix follows that.
   balance-graph checks
 - `vault_data.py` — public vault read: `fetch_vault_data` → `VaultData` (with `FeeData`,
   `WithdrawManagerData`), `fetch_deployment_info`, cached `resolve_token_symbol` /
-  `resolve_token_decimals`; it composes `vault_reads.py` (the shared Multicall3 batch
-  and degrade-to-``None`` helpers), `vault_managers.py` (fee and WithdrawManager
+  `resolve_token_decimals`; it composes `vault_reads.py` (the degrade-to-``None``
+  helpers), `vault_managers.py` (fee and WithdrawManager
   snapshots), `vault_positions.py` (Morpho/Aave position breakdowns and their token
   prices) and `vault_erc20.py` (the ERC20_VAULT_BALANCE holdings);
   `vault_info.py` — `build_vault_info_json(data)`, the `fusion vault info --json`
   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);
+  `resolve_name`) and typed block by block (`VaultInfoJson` and its nested
+  TypedDicts), and `health_check_lists`; `explorer.py` Etherscan V2 (single endpoint, needs API key);
   `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
@@ -223,8 +223,14 @@ the lifecycle matrix follows that.
   `$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.
+  `PUBLIC_ALLOCATOR_ADDRESSES`; it narrows the GraphQL body from `object`);
+  `market_info.py` — `build_morpho_blue_market_json`, `build_meta_morpho_json`, the
+  `fusion market` JSON documents (`MorphoBlueMarketJson`, `MetaMorphoV1Json` /
+  `MetaMorphoV2Json`). A JSON document is a TypedDict (`NotRequired` for a key only
+  some entries carry), never `dict[str, Any]`; JSON parsed from the network or a
+  caller enters as `object` / `Mapping[str, object]` and is narrowed with
+  `isinstance`. These two modules skip `from __future__ import annotations`, so a
+  TypedDict's `__optional_keys__` is right at run time.
   None of them imports `cli/` (`tests/test_sdk_layering.py`)
 - `config/roles.py` — `Roles` IntEnum
 - `core/` — `context` (`Web3Context`), `contract` (`Call`, `ContractWrapper`),
@@ -334,10 +340,14 @@ or examples.
   never consults the executing context.
 - Batch independent reads: `Multicall3(ctx).aggregate(calls)` (raises as
   `.call(ctx)` would) or `.try_aggregate(calls)` (``None`` per failed read) runs
-  many `Call`s in one `eth_call` at one block; every batch, re-run and
-  no-Multicall fallback runs on its `ctx`. A loop of `.call(ctx)`s, or a
-  thread pool of them, costs one round trip each; RPC latency, not decoding,
-  is what makes the vault tooling slow.
+  many `Call`s of one type in one `eth_call` at one block. Reads of different
+  types go through `batch = Multicall3(ctx).batch()`: `batch.add(call)` returns a
+  `BatchValue[T]` (raises from `batch.run()` as `.call(ctx)` would),
+  `batch.try_add(call)` a `BatchValue[T | None]`, and after one `batch.run()`
+  each `.value` keeps its type; never collect mixed reads in a `list[Call[Any]]`
+  or unpack an `aggregate` of them. Every batch, re-run and no-Multicall fallback
+  runs on its `ctx`. A loop of `.call(ctx)`s, or a thread pool of them, costs one
+  round trip each; RPC latency, not decoding, is what makes the vault tooling slow.
 - Fuses (`fuses/`) are stateless encoders: a method returns an immutable
   `FuseAction(fuse_address, calldata)` and touches no chain. `Fuse` builds it
   via `self._action_raw(solidity_signature, values)`; the shared `_validate_*`
@@ -348,8 +358,11 @@ or examples.
   pins one read.
 - Simulate before sending: `VaultSimulator(web3, vault=, alpha=)` batches
   `execute` and `observe` calls into one `eth_simulateV1` round trip, across
-  blocks via `next_block`. Integration tests and examples use it instead of a
-  local node.
+  blocks via `next_block`. `observe(call, label=)` returns a
+  `SimulationObservation[T]`; after `run()` its `.value` is the typed read (it
+  raises when the read reverted), from the latest run, so a crosschain relay
+  round re-resolves it. Labels only name calls in `result.calls` and failures.
+  Integration tests and examples use it instead of a local node.
 - Amounts are raw on-chain integers; `types.py` `NewType`s (`Amount`, `Shares`,
   `MarketId`, ...) name the unit, and nothing scales by decimals.
 - Three address roles are nominal: `PlasmaVaultAddress`, `FuseAddress` and
@@ -431,12 +444,16 @@ value sets are `Literal` enums. The docstring keeps only what has no
 structured home: a one-line summary, behavioral notes, cost warnings. Do not
 repeat schema content as prose; it drifts.
 
-`mcp/models.py` forbids extra keys. Adding a top-level field to
-`build_vault_info_json` requires adding it to the matching model (with a default
-for back-compat) and to the `_full_vault_info_dict` fixture; `test_mcp_models.py`
-enforces the mirror. Conditionally shaped blocks (`withdraw_manager_details`,
-`substrates`, `dependency_graph`) are `dict[str, Any]`, so their inner keys
-are not validated.
+`mcp/models.py` forbids extra keys and stays the source of the published JSON
+schema. Adding a field to `build_vault_info_json` (or a `fusion market` document)
+means adding it to its TypedDict, to the matching model (with a default for
+back-compat) and to the `_full_vault_info_dict` fixture;
+`TestTypedDocumentsMirrorModels` in `test_mcp_models.py` holds every TypedDict to
+its model block by block. The model keeps `dict[str, Any]` where the schema is
+deliberately loose (`substrates`, `deployment`, `share_price`, `dependency_graph`,
+`position_breakdown`): the SDK types those blocks, the schema does not validate
+their inner keys. The substrate entries stay open-ended on both sides
+(`SubstrateEntryJson`, `dict[str, str | bool]`): each decoder adds its own fields.
 
 ## Domain rules (verified against the contracts)
 

{ipor_fusion-4.0.0.dev151 → ipor_fusion-4.0.0.dev156}/MIGRATION_4.md

@@ -54,6 +54,10 @@ before it is fixed.
    nominal types. Wrap literals and raw values, `ChainId(8453)`, `Period(0)`,
    `Amount(n)`, `parse_fuse_address(...)`; values the SDK returns already carry
    their type. See [Nominal types](#nominal-types).
+9. **Typed JSON documents.** `build_vault_info_json` and the `fusion market`
+   builders return TypedDicts (`VaultInfoJson`, ...); code annotating them
+   `dict[str, Any]` switches to the TypedDict or `Mapping[str, object]`. See
+   [Typed JSON documents](#typed-json-documents).
 
 Then read [Behavior changes](#behavior-changes): they apply to every caller,
 type-checked or not.
@@ -138,6 +142,56 @@ placeholder wrapper.
 | `executor.parse_balance_proposed(log)` / `find_balance_proposed(logs)` | `...(log, chain_id=...)` / `...(logs, chain_id=...)` |
 | `CcipLane(executor=, dispatcher=, spoke_chain_id=, ...)` | `CcipLane(hub_ctx=, spoke_ctx=, executor=, dispatcher=, ...)` (same for `StargateLane`) |
 | `transport.executor(ctx, address)` / `transport.dispatcher(ctx, address)` | `transport.executor(address)` / `transport.dispatcher(address)` |
+| `sim.observe("label", call)` ... `result.get("label")` | `read = sim.observe(call)` ... `read.value` |
+| `csim.observe(chain_id, "label", call)` ... `results[chain_id].get("label")` | `read = csim.observe(chain_id, call)` ... `read.value` |
+| `result.observations`, `SimulatedCallResult.decoded` | gone: keep the observation, or `call.decode(bytes(r.return_data))` |
+| `a, b = Multicall3(ctx).aggregate(cast(list[Call[Any]], [x, y]))` | `batch = Multicall3(ctx).batch()`; `a = batch.add(x)`; `b = batch.add(y)`; `batch.run()`; `a.value`, `b.value` |
+
+### Typed batches and simulation observations
+
+Reads of different types keep their types. `Multicall3(ctx).batch()` returns a
+`Multicall3Batch`: `batch.add(call)` queues a `Call[T]` and returns a
+`BatchValue[T]`; `batch.try_add(call)` returns a `BatchValue[T | None]`. One
+`batch.run()` executes every queued read in one `eth_call` per `batch_size` reads
+(one per read where Multicall3 is not deployed), exactly as `aggregate` does for the
+same calls. A failing `add` read raises from `run()` what `Call.call(ctx)` would; a
+failing `try_add` read is `None`, as in `try_aggregate`. Each read chooses its own
+failure handling, so a mixed batch of required and optional reads is one round trip
+and every `value` says in its type whether it can be `None`. Reading `value` before
+`run()` raises `RuntimeError`, and a batch runs once. `aggregate` / `try_aggregate`
+stay for lists of one type.
+
+```python
+batch = Multicall3(ctx).batch()
+assets = batch.add(vault.total_assets())    # BatchValue[Amount]
+fuses = batch.add(vault.get_fuses())        # BatchValue[list[FuseAddress]]
+name = batch.try_add(vault.name())          # BatchValue[str | None]
+batch.run()
+assets.value, fuses.value, name.value
+```
+
+`VaultSimulator.observe(call, *, label=None)` returns a `SimulationObservation[T]`
+instead of the simulator, so it no longer chains, and its label is optional (it
+names the read in `result.calls` and in failures). After `run()`,
+`observation.value` is the read decoded as its `Call` decodes it, from the latest
+run; `observation.result` is its `SimulatedCallResult`.
+`CrosschainSimulator.observe(chain_id, call, *, label=None)` returns the same,
+resolved by every relay round. `SimulationResult.get`, `SimulationResult.observations`
+and `SimulatedCallResult.decoded` are removed: a list of results of many types has no
+honest element type, so the typed value lives on the observation. A write queued with
+`add_call` is no longer decoded; decode its return data with the `Call` you queued.
+
+```python
+before = sim.observe(vault.total_assets())   # SimulationObservation[Amount]
+sim.execute([action])
+after = sim.observe(vault.total_assets())
+sim.run()
+after.value - before.value
+```
+
+`Call` is a frozen dataclass and covariant in its result type: assigning to a
+field raises, and a `Call[Amount]` is a `Call[int]` and a `Call[object]`, so a
+`Sequence[Call[object]]` takes any calls without a cast.
 
 ### Renamed methods
 
@@ -721,6 +775,45 @@ string). Calling an MCP tool function
 directly from Python takes `ChainId`. Their amount, decimals and time fields stay
 `int`: they are JSON output models, and the SDK values above fit them unchanged.
 
+## Typed JSON documents
+
+The JSON document builders return `TypedDict`s instead of `dict[str, Any]`; the
+documents themselves (keys, values, order, the MCP schemas) are unchanged, so
+untyped code needs none of this section.
+
+| Builder | Returns |
+|---|---|
+| `build_vault_info_json` | `VaultInfoJson` |
+| `build_morpho_blue_market_json` | `MorphoBlueMarketJson` |
+| `build_meta_morpho_json` | `MetaMorphoV1Json \| MetaMorphoV2Json`, told apart by `doc["version"]` |
+| `RoleAccount.to_dict` | `RoleAccountJson` |
+
+Every nested block has its own TypedDict (`FeesJson`, `WithdrawManagerJson`,
+`BalanceFuseJson`, `ReconciliationJson`, `HyperCoreJson`, `MorphoSupplyingVaultJson`,
+...), all importable from `ipor_fusion` and from `ipor_fusion.vault_info` /
+`ipor_fusion.market_info` (`RoleAccountJson` from `ipor_fusion.core`). Values carry the
+SDK's nominal types (`doc["vault"]` is a `PlasmaVaultAddress`, `doc["chain_id"]` a
+`ChainId`). A block that can be `null` is `X | None`: check it before indexing
+(`fees = doc["fees"]; if fees is not None: fees["management_fee_percent"]`). A key
+that only some entries carry is `NotRequired` (a balance fuse's `pct_of_total` and
+`position_breakdown`, the Morpho API keys of the market document): read it with
+`.get`. A decoded substrate entry stays open-ended, `SubstrateEntryJson`
+(`dict[str, str | bool]`), since each decoder adds its own fields.
+
+- A variable or parameter annotated `dict[str, Any]` no longer accepts these
+  documents (a `TypedDict` is not a `dict[str, Any]`): annotate it with the TypedDict,
+  or `Mapping[str, object]` for code that only passes the document on (`json.dumps`
+  accepts either).
+- Parsing entry points take `Mapping[str, object]` instead of `Mapping[str, Any]`:
+  `decode_external_state_event(log)` and `FusionInstance.from_dict(data)`.
+  `VerifierResult.message` is a `Mapping[str, object]`, and `OutboundMessage.raw` is
+  `object`: narrow it before use (`isinstance(message.raw, MessageV1)` for CCIP; a
+  Stargate `Packet`, or a `(Packet, TaxiMessage)` pair for a token transfer).
+- The `vault info` document's `deployment` is `DeploymentJson` (block, timestamp,
+  age) or `DeploymentErrorJson` (`{"error": ...}`) or `None`; `share_price` is
+  `SharePriceJson` (`asset`, and `usd` when the asset is priced); `dependency_graph`
+  is `DependencyGraphJson` (`edges`, `update_reach`, `update_groups`).
+
 ## Behavior changes
 
 These apply to every caller, type-checked or not. Changes described in full above
@@ -775,5 +868,10 @@ are listed with a link.
 - `LendingMarketHealth.substrate_id` for a Morpho market is `0x`-prefixed (the JSON
   documents already were).
 - `TransactionError.tx_hash` is `0x`-prefixed.
+- An observed simulation read that reverted raises `SimulationError` from its
+  `value`, one that returned no data raises `EmptyCallResultError`, and one its
+  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`.
 - 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.dev151 → ipor_fusion-4.0.0.dev156}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev151
+Version: 4.0.0.dev156
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -188,12 +188,12 @@ payload = vault.execute([action]).calldata   # raw bytes for an external signer
 
 # Simulate first via eth_simulateV1 (no local node); alpha is the account allowed to call execute()
 sim = VaultSimulator(ctx.web3, vault=vault.address, alpha=Web3.to_checksum_address("0xALPHA"))
-sim.observe("before", vault.total_assets())
+before = sim.observe(vault.total_assets())      # SimulationObservation[Amount]
 sim.execute([action])
-sim.observe("after", vault.total_assets())
+after = sim.observe(vault.total_assets())
 result = sim.run()
 if result.all_success:
-    print(result.get("after") - result.get("before"))
+    print(after.value - before.value)
 ```
 
 ## CLI Quickstart

{ipor_fusion-4.0.0.dev151 → ipor_fusion-4.0.0.dev156}/README.md

@@ -140,12 +140,12 @@ payload = vault.execute([action]).calldata   # raw bytes for an external signer
 
 # Simulate first via eth_simulateV1 (no local node); alpha is the account allowed to call execute()
 sim = VaultSimulator(ctx.web3, vault=vault.address, alpha=Web3.to_checksum_address("0xALPHA"))
-sim.observe("before", vault.total_assets())
+before = sim.observe(vault.total_assets())      # SimulationObservation[Amount]
 sim.execute([action])
-sim.observe("after", vault.total_assets())
+after = sim.observe(vault.total_assets())
 result = sim.run()
 if result.all_success:
-    print(result.get("after") - result.get("before"))
+    print(after.value - before.value)
 ```
 
 ## CLI Quickstart

{ipor_fusion-4.0.0.dev151 → ipor_fusion-4.0.0.dev156}/examples/advanced_euler_v2_credit_market_base.py

@@ -396,7 +396,7 @@ def run_simulation(web3: Web3) -> SimulationResult:
     #   - sim.add_call(call=X, from_=OWNER) -> X.send(ctx) by the owner/atomist
     #     (or X.calldata to a multisig / timelock).
     #   - sim.execute([action]) -> plasma_vault.execute([action]).send(ctx) by the alpha.
-    #   - sim.observe("key", X) -> X.call(ctx), a plain read.
+    #   - read = sim.observe(X), then read.value -> X.call(ctx), a plain read.
     sim = VaultSimulator(
         web3=web3, vault=preview.plasma_vault, alpha=ALPHA, block=PINNED_BLOCK
     )
@@ -467,14 +467,14 @@ def run_simulation(web3: Web3) -> SimulationResult:
     )
 
     # Read the granted substrate set back so we can assert it is EXACTLY our two.
-    sim.observe("granted_substrates", plasma_vault.get_market_substrates(EULER_MARKET))
+    granted_substrates = sim.observe(plasma_vault.get_market_substrates(EULER_MARKET))
     plan.append("read the granted substrate set back")
 
     # Oracle coverage: the vault must be able to price every tracked asset. A fresh
     # vault's price manager delegates to the global middleware for assets without
     # an override, so these read the effective prices.
-    sim.observe("cbeth_price", price_manager.get_asset_price(BASE_CBETH))
-    sim.observe("weth_price", price_manager.get_asset_price(BASE_WETH))
+    cbeth_price_obs = sim.observe(price_manager.get_asset_price(BASE_CBETH))
+    weth_price_obs = sim.observe(price_manager.get_asset_price(BASE_WETH))
     plan.append("verify oracle coverage for cbETH and WETH")
 
     # Fund the vault with cbETH collateral. SIMULATION ONLY: an impersonated
@@ -485,7 +485,7 @@ def run_simulation(web3: Web3) -> SimulationResult:
         call=cbeth.transfer(preview.plasma_vault, COLLATERAL_FUND_AMOUNT),
         from_=BASE_CBETH_WHALE,
     )
-    sim.observe("vault_cbeth_funded", cbeth.balance_of(preview.plasma_vault))
+    vault_cbeth_funded = sim.observe(cbeth.balance_of(preview.plasma_vault))
     plan.append("fund the vault with cbETH collateral")
 
     # ── Credit lifecycle, driven by the alpha via PlasmaVault.execute(...). ──
@@ -500,20 +500,22 @@ def run_simulation(web3: Web3) -> SimulationResult:
 
     # Borrow WETH against the cbETH collateral; debt is now open.
     sim.execute([borrow_action(BORROW_AMOUNT)])
-    sim.observe("debt_after_borrow", _evault_debt_of(EVAULT_WETH, euler_account))
+    debt_after_borrow = sim.observe(_evault_debt_of(EVAULT_WETH, euler_account))
     plan.append("borrow 1 WETH against the cbETH collateral")
 
     # Re-value the market while the position is open so the balance fuse's
     # collateral-minus-debt valuation surfaces into the vault's stored NAV.
     sim.add_call(call=plasma_vault.update_markets_balances([EULER_MARKET]), from_=ALPHA)
-    sim.observe("euler_value_open", plasma_vault.total_assets_in_market(EULER_MARKET))
+    euler_value_open_obs = sim.observe(
+        plasma_vault.total_assets_in_market(EULER_MARKET)
+    )
     plan.append("re-value the open Euler position")
 
     # Repay the full debt. MAX_UINT256 caps at the outstanding amount; with no time
     # advance in this run, interest is negligible and the borrowed WETH covers it.
     # (Advancing time would accrue interest, requiring a small extra WETH buffer.)
     sim.execute([repay_action(Amount(MAX_UINT256))])
-    sim.observe("debt_after_repay", _evault_debt_of(EVAULT_WETH, euler_account))
+    debt_after_repay = sim.observe(_evault_debt_of(EVAULT_WETH, euler_account))
     plan.append("repay the full WETH debt")
 
     # Unwind in reverse of setup: disable the WETH controller, then the cbETH
@@ -529,8 +531,10 @@ def run_simulation(web3: Web3) -> SimulationResult:
     # to fully exit the position, then re-value the market so the exit surfaces.
     sim.execute([withdraw_collateral_action(Amount(MAX_UINT256))])
     sim.add_call(call=plasma_vault.update_markets_balances([EULER_MARKET]), from_=ALPHA)
-    sim.observe("euler_value_closed", plasma_vault.total_assets_in_market(EULER_MARKET))
-    sim.observe("vault_cbeth_closed", cbeth.balance_of(preview.plasma_vault))
+    euler_value_closed_obs = sim.observe(
+        plasma_vault.total_assets_in_market(EULER_MARKET)
+    )
+    vault_cbeth_closed = sim.observe(cbeth.balance_of(preview.plasma_vault))
     plan.append("withdraw cbETH; the Euler position is fully exited")
 
     log.info("transaction plan:")
@@ -544,29 +548,29 @@ def run_simulation(web3: Web3) -> SimulationResult:
     # is the single eth_simulateV1 call that executed it. From here we read the
     # recorded observations back and verify the outcome, failing loud on any
     # mismatch. ─────────────────────────────────────────────────────────────
-    cbeth_price = result.get("cbeth_price")
-    weth_price = result.get("weth_price")
+    cbeth_price = cbeth_price_obs.value
+    weth_price = weth_price_obs.value
     _check(cbeth_price.amount > 0, "cbETH has no oracle price -- vault cannot value it")
     _check(weth_price.amount > 0, "WETH has no oracle price -- vault cannot value it")
 
     # No unrelated permissions: the granted set is EXACTLY the two substrates we
     # built, and nothing else. Compare as sets (grant order is not guaranteed).
-    granted = {bytes(s) for s in result.get("granted_substrates")}
+    granted = {bytes(s) for s in granted_substrates.value}
     _check(
         granted == {bytes(s) for s in market_substrates()},
         f"unexpected market substrates granted: {sorted(s.hex() for s in granted)}",
     )
 
     _check(
-        result.get("vault_cbeth_funded") >= COLLATERAL_FUND_AMOUNT,
+        vault_cbeth_funded.value >= COLLATERAL_FUND_AMOUNT,
         "vault did not receive the cbETH collateral",
     )
     # borrow opened debt; repay cleared it -- read straight from the eWETH eVault.
-    debt_open = result.get("debt_after_borrow")
+    debt_open = debt_after_borrow.value
     _check(debt_open >= BORROW_AMOUNT, f"borrow did not open debt: {debt_open}")
     _check(
-        result.get("debt_after_repay") == 0,
-        f"repay did not clear debt: {result.get('debt_after_repay')}",
+        debt_after_repay.value == 0,
+        f"repay did not clear debt: {debt_after_repay.value}",
     )
     # The balance fuse nets the debt against the collateral. The open position is
     # worth the supplied cbETH MINUS the WETH debt, in the vault's WETH terms. To
@@ -575,7 +579,7 @@ def run_simulation(web3: Web3) -> SimulationResult:
     # debt: too narrow a gap means the debt was ignored (a bare "> 0" or "< value"
     # would miss it, since the collateral valuation rounds down), too wide means it
     # was double-counted. The band is +/-50% of one debt to absorb rounding.
-    euler_value_open = result.get("euler_value_open")
+    euler_value_open = euler_value_open_obs.value
     collateral_value = (
         COLLATERAL_SUPPLY_AMOUNT * cbeth_price.amount // weth_price.amount
     )
@@ -589,14 +593,14 @@ def run_simulation(web3: Web3) -> SimulationResult:
     # Fully exited after the withdraw: the Euler market values to dust, and the
     # supplied cbETH is back on the vault (the ~2 cbETH idle buffer plus the ~10
     # withdrawn -> roughly the funded amount, minus ERC4626 round-down dust).
-    euler_value_closed = result.get("euler_value_closed")
+    euler_value_closed = euler_value_closed_obs.value
     _check(
         euler_value_closed <= EULER_EXIT_DUST,
         f"Euler position not fully exited: market value {euler_value_closed}",
     )
     _check(
-        result.get("vault_cbeth_closed") >= COLLATERAL_FUND_AMOUNT - EULER_EXIT_DUST,
-        f"withdrawn cbETH not returned to the vault: {result.get('vault_cbeth_closed')}",
+        vault_cbeth_closed.value >= COLLATERAL_FUND_AMOUNT - EULER_EXIT_DUST,
+        f"withdrawn cbETH not returned to the vault: {vault_cbeth_closed.value}",
     )
 
     log.info(
@@ -605,7 +609,7 @@ def run_simulation(web3: Web3) -> SimulationResult:
         cbeth_price.amount,
         weth_price.amount,
         debt_open,
-        result.get("debt_after_repay"),
+        debt_after_repay.value,
         euler_value_open,
         euler_value_closed,
         result.gas_used,

{ipor_fusion-4.0.0.dev151 → ipor_fusion-4.0.0.dev156}/examples/advanced_euler_v2_looping_arbitrum.py

@@ -409,10 +409,10 @@ def run_simulation(web3: Web3) -> SimulationResult:
     )
     # update_callback_handler exercises FUSE_MANAGER_ROLE, held by OWNER above.
 
-    sim.observe("wbtc_price", price_manager.get_asset_price(ARBITRUM_WBTC))
-    sim.observe("usdc_price", price_manager.get_asset_price(ARBITRUM_USDC))
-    sim.observe("euler_substrates", vault.get_market_substrates(EULER_MARKET))
-    sim.observe("swapper_substrates", vault.get_market_substrates(SWAPPER_MARKET))
+    wbtc_price = sim.observe(price_manager.get_asset_price(ARBITRUM_WBTC))
+    usdc_price = sim.observe(price_manager.get_asset_price(ARBITRUM_USDC))
+    euler_substrates = sim.observe(vault.get_market_substrates(EULER_MARKET))
+    swapper_substrates = sim.observe(vault.get_market_substrates(SWAPPER_MARKET))
 
     # Simulation-only seed. In production WBTC arrives through normal deposits.
     sim.add_call(
@@ -423,56 +423,54 @@ def run_simulation(web3: Web3) -> SimulationResult:
     sim.execute([build_loop_action()])
 
     sim.add_call(call=vault.update_markets_balances([EULER_MARKET]), from_=ALPHA)
-    sim.observe(
-        "collateral_shares",
+    collateral_shares = sim.observe(
         ERC20(EVAULT_WBTC).balance_of(euler_account),
     )
-    sim.observe(
-        "usdc_debt",
+    usdc_debt = sim.observe(
         _debt_of(EVAULT_USDC, euler_account),
     )
-    sim.observe("vault_wbtc", wbtc.balance_of(preview.plasma_vault))
-    sim.observe("vault_usdc", usdc.balance_of(preview.plasma_vault))
-    sim.observe("euler_value", vault.total_assets_in_market(EULER_MARKET))
-    sim.observe("total_assets", vault.total_assets())
+    vault_wbtc = sim.observe(wbtc.balance_of(preview.plasma_vault))
+    vault_usdc = sim.observe(usdc.balance_of(preview.plasma_vault))
+    euler_value = sim.observe(vault.total_assets_in_market(EULER_MARKET))
+    total_assets = sim.observe(vault.total_assets())
 
     result = sim.run()
     _assert_all_success(result)
 
-    _check(result.get("wbtc_price").amount > 0, "WBTC has no oracle price")
-    _check(result.get("usdc_price").amount > 0, "USDC has no oracle price")
+    _check(wbtc_price.value.amount > 0, "WBTC has no oracle price")
+    _check(usdc_price.value.amount > 0, "USDC has no oracle price")
     _check(
-        {bytes(value) for value in result.get("euler_substrates")}
+        {bytes(value) for value in euler_substrates.value}
         == {bytes(value) for value in euler_market_substrates()},
         "Euler substrates differ from the narrow WBTC/USDC grant",
     )
     _check(
-        {bytes(value) for value in result.get("swapper_substrates")}
+        {bytes(value) for value in swapper_substrates.value}
         == {bytes(value) for value in swapper_market_substrates()},
         "swapper substrates differ from the narrow pair/target grant",
     )
-    _check(result.get("collateral_shares") > 0, "Euler collateral was not supplied")
+    _check(collateral_shares.value > 0, "Euler collateral was not supplied")
     _check(
-        result.get("usdc_debt") >= BORROW_USDC,
-        f"Euler USDC debt was not opened: {result.get('usdc_debt')}",
+        usdc_debt.value >= BORROW_USDC,
+        f"Euler USDC debt was not opened: {usdc_debt.value}",
     )
-    _check(result.get("vault_usdc") == 0, "borrowed USDC was not fully swapped")
+    _check(vault_usdc.value == 0, "borrowed USDC was not fully swapped")
     _check(
-        result.get("vault_wbtc") < Amount(1_000_000),
-        f"unexpected WBTC residue after flash repayment: {result.get('vault_wbtc')}",
+        vault_wbtc.value < Amount(1_000_000),
+        f"unexpected WBTC residue after flash repayment: {vault_wbtc.value}",
     )
-    _check(result.get("euler_value") > 0, "Euler net position has no value")
+    _check(euler_value.value > 0, "Euler net position has no value")
     _check(
-        INITIAL_WBTC * 98 // 100 <= result.get("total_assets") <= INITIAL_WBTC,
-        f"loop NAV moved outside the 2% safety band: {result.get('total_assets')}",
+        INITIAL_WBTC * 98 // 100 <= total_assets.value <= INITIAL_WBTC,
+        f"loop NAV moved outside the 2% safety band: {total_assets.value}",
     )
 
     log.info(
         "OK -- collateral shares=%s, USDC debt=%s, idle WBTC=%s, NAV=%s, gas=%s",
-        result.get("collateral_shares"),
-        result.get("usdc_debt"),
-        result.get("vault_wbtc"),
-        result.get("total_assets"),
+        collateral_shares.value,
+        usdc_debt.value,
+        vault_wbtc.value,
+        total_assets.value,
         result.gas_used,
     )
     return result

{ipor_fusion-4.0.0.dev151 → ipor_fusion-4.0.0.dev156}/examples/composed_hypercore_flow_arbitrum_hyperevm.py

@@ -83,6 +83,7 @@ from ipor_fusion import (
     CrosschainLane,
     CrosschainSimulator,
     HyperCoreReader,
+    LaneObservation,
     PlasmaVault,
     SimulationResult,
     TimeInForce,
@@ -784,9 +785,14 @@ def redeem_command_preview(web3_arb: Web3, web3_hype: Web3) -> dict[str, int]:
     }
 
 
-def _attest(flow: _Tail, tag: str, observation_label: str, *, hub_idle: int = 0) -> int:
+def _attest(
+    flow: _Tail,
+    tag: str,
+    observation: LaneObservation,
+    *,
+    hub_idle: int = 0,
+) -> int:
     lane, hub = flow.lane, flow.hub
-    observation = flow.simulator.results[HYPEREVM_CHAIN_ID].get(observation_label)
     proposal = lane.attestation(
         observation,
         remote_block=flow.spoke.current_block_number,
@@ -816,18 +822,14 @@ def _attest(flow: _Tail, tag: str, observation_label: str, *, hub_idle: int = 0)
         from_=ALPHA,
         label=f"refresh_54_{tag}",
     )
-    flow.simulator.observe(
-        ARBITRUM_CHAIN_ID, f"executor_balance_{tag}", lane.get_balance()
-    )
-    flow.simulator.observe(
-        ARBITRUM_CHAIN_ID,
-        f"market_total_{tag}",
-        flow.hub_vault.total_assets_in_market(CROSSCHAIN_MARKET),
+    executor_nav = flow.simulator.observe(ARBITRUM_CHAIN_ID, lane.get_balance())
+    market_nav = flow.simulator.observe(
+        ARBITRUM_CHAIN_ID, flow.hub_vault.total_assets_in_market(CROSSCHAIN_MARKET)
     )
-    results = flow.relay()
+    flow.relay()
     attested = int(observation.accounted_balance)
-    executor_balance = int(results[ARBITRUM_CHAIN_ID].get(f"executor_balance_{tag}"))
-    market_total = int(results[ARBITRUM_CHAIN_ID].get(f"market_total_{tag}"))
+    executor_balance = executor_nav.value
+    market_total = market_nav.value
     _check(
         executor_balance == attested + hub_idle,
         f"{tag}: executor NAV {executor_balance} != attested {attested} + idle {hub_idle}",
@@ -908,23 +910,23 @@ def recall_attest_claim(web3_arb: Web3, web3_hype: Web3) -> dict[str, int]:
     hub.execute([lane.recall(amount=remote_idle, min_return=remote_idle)])
     flow.advance(BRIDGE_LATENCY)
     flow.relay()
-    simulator.observe(ARBITRUM_CHAIN_ID, "idle_after_return", lane.idle_ledger())
-    simulator.observe(
-        ARBITRUM_CHAIN_ID, "settled_after_return", lane.settled_remote_balance()
+    idle_after_return = simulator.observe(ARBITRUM_CHAIN_ID, lane.idle_ledger())
+    settled_after_return = simulator.observe(
+        ARBITRUM_CHAIN_ID, lane.settled_remote_balance()
     )
-    simulator.observe(
-        ARBITRUM_CHAIN_ID, "pending_after_return", lane.pending_transfer_count()
+    pending_after_return = simulator.observe(
+        ARBITRUM_CHAIN_ID, lane.pending_transfer_count()
     )
-    simulator.observe(HYPEREVM_CHAIN_ID, "observation_after_return", lane.observation())
-    results = flow.relay()
-    idle = int(results[ARBITRUM_CHAIN_ID].get("idle_after_return"))
-    settled = int(results[ARBITRUM_CHAIN_ID].get("settled_after_return"))
+    observation_after_return = simulator.observe(HYPEREVM_CHAIN_ID, lane.observation())
+    flow.relay()
+    idle = idle_after_return.value
+    settled = settled_after_return.value
     _check(
         idle == int(remote_idle),
         f"the hub credited {idle}, the spoke sent {remote_idle} (no token fee on this lane)",
     )
     _check(
-        results[ARBITRUM_CHAIN_ID].get("pending_after_return") == 0,
+        pending_after_return.value == 0,
         "a transfer is still pending",
     )
     # The settled bucket keeps exactly the value of the residual shares; the
@@ -937,7 +939,7 @@ def recall_attest_claim(web3_arb: Web3, web3_hype: Web3) -> dict[str, int]:
     flow.numbers.update({"recalled": idle, "settled_after_return": settled})
 
     flow.advance(int(lane.executor.min_update_interval().call(hub_ctx)))
-    residual = _attest(flow, "residual", "observation_after_return", hub_idle=idle)
+    residual = _attest(flow, "residual", observation_after_return.value, hub_idle=idle)
     _check(
         residual == settled, f"the residual attestation {residual} != settled {settled}"
     )
@@ -948,32 +950,31 @@ def recall_attest_claim(web3_arb: Web3, web3_hype: Web3) -> dict[str, int]:
         from_=ALPHA,
         label="refresh_54_final",
     )
-    simulator.observe(
-        ARBITRUM_CHAIN_ID, "vault_usdc_after", flow.hub_usdc.balance_of(HUB_VAULT)
+    vault_usdc_after = simulator.observe(
+        ARBITRUM_CHAIN_ID, flow.hub_usdc.balance_of(HUB_VAULT)
     )
-    simulator.observe(ARBITRUM_CHAIN_ID, "idle_after_claim", lane.idle_ledger())
-    simulator.observe(ARBITRUM_CHAIN_ID, "nav_final", lane.get_balance())
-    simulator.observe(
+    idle_after_claim = simulator.observe(ARBITRUM_CHAIN_ID, lane.idle_ledger())
+    nav_final = simulator.observe(ARBITRUM_CHAIN_ID, lane.get_balance())
+    market_final = simulator.observe(
         ARBITRUM_CHAIN_ID,
-        "market_final",
         flow.hub_vault.total_assets_in_market(CROSSCHAIN_MARKET),
     )
-    results = flow.relay()
-    vault_after = int(results[ARBITRUM_CHAIN_ID].get("vault_usdc_after"))
+    flow.relay()
+    vault_after = vault_usdc_after.value
     _check(
         vault_after == vault_usdc_before + idle,
         f"hub vault USDC {vault_after} != {vault_usdc_before} + {idle}",
     )
     _check(
-        results[ARBITRUM_CHAIN_ID].get("idle_after_claim") == 0,
+        idle_after_claim.value == 0,
         "the idle ledger is not empty after the claim",
     )
     _check(
-        int(results[ARBITRUM_CHAIN_ID].get("nav_final")) == residual,
+        nav_final.value == residual,
         "executor NAV != the residual",
     )
     _check(
-        int(results[ARBITRUM_CHAIN_ID].get("market_final")) == residual,
+        market_final.value == residual,
         "market 54 total != the residual",
     )
     log.info(