ipor-fusion 4.0.0.dev129__tar.gz → 4.0.0.dev137__tar.gz

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/AGENTS.md

@@ -186,7 +186,8 @@ the lifecycle matrix follows that.
 
 ## Layout (`src/ipor_fusion/`)
 
-- `chains.py` chain registry; `market_ids.py` `IporFusionMarkets`; `types.py`, `errors.py`
+- `chains.py` chain registry; `market_ids.py` `IporFusionMarkets`; `types.py`; `errors.py`
+  defines every SDK exception class (`tests/test_error_hierarchy.py` pins it)
 - `about.py` — package version, repository URL, CHANGELOG parsing (`fusion changelog`,
   `server_info`); `field_docs.py` — `DOCS`, the JSON field descriptions shared by CLI
   output and MCP models
@@ -311,13 +312,18 @@ or examples.
   that depends on another read) is named `read_*` and takes `ctx` first:
   `PlasmaVault.read_balance_fuses(ctx)`, `AccessManager.read_all_role_accounts(ctx)`,
   `MorphoReader.read_rates(ctx, id)`. Decide by the I/O a method performs, not
-  by the class name. Resolvers that probe the chain to pick a wrapper
+  by the class name; the prefix is reserved for that, so a method that builds
+  a `Call` offline (`PlasmaVault.universal_read`) or a pure helper
+  (`precompile_index_of`) never takes it. Resolvers that probe the chain to pick a wrapper
   (`price_oracle_middleware(ctx, a)`, `resolve_access_manager`,
   `ExternalStateExecutor.for_vault`) return context-free wrappers. Executors
   and orchestrators own their contexts: `Multicall3(ctx)`, `VaultSimulator`,
   `CrosschainSimulator`, `OracleMappingReader(ctx, oracle)` and
   `CrosschainLane` (`hub_ctx` for the executor, `spoke_ctx` for the
-  dispatcher at the same address: run a lane's Calls on the matching one).
+  dispatcher at the same address; its eager `read_hub_state()` and
+  `read_observation()` run on the right one, and its Calls on whichever the
+  caller picks). A context is pinned by copy, `ctx.at_block(n)`;
+  `default_block` is read-only.
   A chain-dependent decode takes the chain explicitly
   (`ExternalStateExecutor.pending_proposals(account, chain_id=)`); a decoder
   never consults the executing context.

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/MIGRATION_4.md

@@ -33,7 +33,7 @@ values; they do not validate byte widths or address spelling.
 | `MorphoBlueMarketId` | `parse_morpho_market_id(value)`: 32 bytes or hex in any spelling, always `0x` + 64 lowercase digits |
 | `TxHash` | `parse_tx_hash(value)` (32 bytes or `0x`/`0X`-prefixed hex in any case) |
 | `PlasmaVaultAddress`, `FuseAddress`, `AccessManagerAddress` | from the SDK (`PlasmaVault.address`, `get_fuses()`, `get_access_manager_address()`, `FusionInstance`, discovery), or `parse_plasma_vault_address` / `parse_fuse_address` / `parse_access_manager_address(value)` for a raw address; they label the role and check nothing on chain |
-| crosschain ids | `CommandId(b)`, `MessageId(b)`, `AssetId(b)`, `OperationId(b)`, `TransferId(b)`, `ReturnRequestId(b)`, `PositionSetHash(b)` (bytes32); `ProposalId(n)`, `DeploymentRequestId(n)`, `StargateAssetId(n)` (int) |
+| crosschain ids | `CommandId(b)`, `MessageId(b)`, `AssetId(b)`, `OperationId(b)`, `TransferId(b)`, `ReturnRequestId(b)`, `PositionSetHash(b)` (bytes32); `ProposalId(n)`, `DeploymentRequestId(n)`, `StargateAssetId(n)`, `LayerZeroEid(n)`, `CcipChainSelector(n)` (int) |
 | HyperCore ids | `HyperCoreTokenIndex(n)` (or `USDC_TOKEN_INDEX`), `HyperCoreAsset(n)` (or `hip3_action_asset(dex, index)`), `HyperCoreOrderId(n)`, `HyperCoreClientOrderId(n)`, `MarginTableId(n)`, `HyperCoreActionId(n)`, `PayloadHash(b)` |
 | external state | `ProposalHash(b)` |
 | `BlockIdentifier` | a block number, `"latest"` / `"pending"` / ..., or a block hash |
@@ -92,6 +92,9 @@ chain is always the context's:
   `Call.call(ctx, *, block=None)` (see [Context-free wrappers](#context-free-wrappers)). `Web3Context.get_logs(to_block=None)` ends at
   the context's default block and `Web3Context.get_block(block=None)` returns it,
   both instead of ``"latest"``.
+- `Web3Context.default_block` is read-only: `ctx.default_block = n` raises
+  `AttributeError`. Pin a copy instead, `ctx = ctx.at_block(n)`; the old setter
+  changed the block under every thread sharing the context.
 
 Snapshot fields carry their units: `VaultData.total_assets`,
 `underlying_balance_on_vault` and `market_balances` values are `Amount`;
@@ -122,15 +125,21 @@ context built with it shares the same `n` slots. A context built from your own
 `limit.install(web3)` (innermost, as `from_url` does) or
 `web3.middleware_onion.inject(limit.middleware, layer=0)`.
 
-`ensure_supported_chain` takes `ChainId`. `fetch_unpriceable_priced_tokens` takes the oracle and
-underlying as `ChecksumAddress`. `resolve_token_symbol`, `resolve_token_decimals`,
+`ensure_supported_chain` takes `ChainId`. `fetch_unpriceable_priced_tokens(ctx, *,
+price_oracle, underlying, balance_fuses, market_substrates, morpho_positions)` takes
+everything after `ctx` by keyword, the oracle and underlying as `ChecksumAddress`.
+`resolve_token_symbol`, `resolve_token_decimals`,
 `get_contract_name` and `get_deployment_tx` take `HexAddress` (a checksum address
-fits), and the `resolve_name` / `resolve_symbol` callbacks receive one (a callback
+fits) and `api_key` by keyword only (`get_contract_name(chain_id, address, *,
+api_key=None, cache=None)`, `get_deployment_tx(chain_id, address, *, api_key=None)`),
+and the `resolve_name` / `resolve_symbol` callbacks receive one (a callback
 typed for `str` still fits). Market-keyed data is keyed by `MarketId`:
 `VaultData.market_substrates`, `dependency_graph`, `morpho_positions`,
 `aave_positions`, `market_balances`; the `VaultState` protocol, `fetch_vault_lending_health`, `fetch_unpriceable_priced_tokens`
 and the `dependency_graph` helpers (`compute_update_reach`, `compute_update_groups`,
 `find_orphan_fuse_markets`, `find_markets_missing_erc20_dependency`).
+`find_orphan_fuse_markets` returns `dict[MarketId, list[FuseAddress]]`, so its
+fuses go into `PlasmaVault.remove_fuses` as they are.
 
 `VaultData.price_oracle_addr` is renamed `price_oracle`, like its sibling
 address fields (a custom `VaultState` renames it too).
@@ -148,7 +157,8 @@ The Uniswap V3 / Ramses V2 position events' `version`, `sender` and `recipient`
 `LendingMarketHealth.market_id` and `MiddlewarePricedToken.market_id` are
 `MarketId`; `Erc20Holding.address` is `HexAddress`, and `SubstrateInfo.address` is
 `HexAddress | None` (`None`, no longer `""`, when a substrate carries no address).
-`LegacyPriceOracleMiddleware` takes `base_currency_decimals: Decimals`.
+`LegacyPriceOracleMiddleware` takes `base_currency_decimals: Decimals`, and
+`PriceOracleMiddleware.base_currency_decimals()` returns `Call[Decimals]`.
 `get_logs_adaptive(chain_id=)` and `LogSource.get_logs` take `ChainId`;
 `quote_ccip_native_fee(block=)` and `OracleMappingReader.asset_source_events` take a
 `BlockIdentifier`.
@@ -167,7 +177,9 @@ the async command helpers `Command.request_shares` / `redeem_from_request`,
 Every fuse constructor, `FuseAction.fuse`, `BalanceFuse.fuse`,
 `PlasmaVault.add_fuses` / `remove_fuses` / `add_balance_fuse` / `remove_balance_fuse`
 / `balance_fuse_value`, `RewardsManager.add_reward_fuses` / `is_reward_fuse_supported`,
-`LaneFuses` and the HyperCore balance-fuse argument take a `FuseAddress`, and
+`LaneFuses`, the HyperCore balance-fuse argument and the
+`PlasmaVault.configure_instant_withdrawal_fuses` configs
+(`Sequence[tuple[FuseAddress, Sequence[bytes]]]`) take a `FuseAddress`, and
 `get_fuses()`, `get_instant_withdrawal_fuses()`, `get_rewards_fuses()` and
 `VaultData.fuses` / `instant_fuses` / `fuse_markets` keys return it.
 `AccessManager(address)` takes an `AccessManagerAddress`;
@@ -196,7 +208,13 @@ from_=...)` needs neither, so drop a zero-address placeholder. `execute()` witho
 the fee fields are `Wei`). LayerZero endpoint ids are `LayerZeroEid`:
 `StargateChain.eid`, `Packet.src_eid` / `dst_eid`, `EnforcedOptionParam.eid`,
 `executor_eid()` and `eid_of()` return it and `chain_id_of`, `peers`, `lz_receive_calldata(src_eid=)`
-and the Stargate fuse's `eid=` take it (`LayerZeroEid(30101)`).
+and the Stargate fuse's `eid=` take it (`LayerZeroEid(30101)`). CCIP chain
+selectors are `CcipChainSelector`: `CcipChain.chain_selector`,
+`CcipRouteConfig.chain_selector`, `CcipTokenLane.chain_selector`, the `MessageV1`,
+`CcipMessageSent` and `Any2EVMMessage` selectors and `CcipRouter.get_off_ramps()`
+carry it, and `chain_id_of_selector`, `CcipRouter.is_chain_supported` /
+`get_on_ramp`, `CcipTokenPool.is_supported_chain` and `ccip_token_lane` take it
+(`CcipChainSelector(4949039107694359620)`).
 `encode_oft_compose_msg(*, nonce=, src_eid=, amount_ld=, compose_msg=)` takes
 keyword arguments only. `ZERO_ADDRESS` is a `ChecksumAddress` (same value).
 
@@ -229,7 +247,10 @@ gone: use `morpho_blue_address(chain_id)`.
 `MorphoPositionBreakdown.market_id` (as read from substrates) and the keys of
 `VaultV1Info.public_allocator_flow_caps` are canonical. `fetch_market`, `fetch_vault`,
 `morpho_blue_address`, `build_*_json` take `ChainId`; `fetch_vault` takes a
-`ChecksumAddress`. Every address on the `morpho_api` records is `ChecksumAddress`;
+`ChecksumAddress`. `build_morpho_blue_market_json(*, market_id, chain_id, params,
+state, rates, api_market=None, api_error=None, public_allocator=None)` takes every
+argument by keyword, `public_allocator` as `ChecksumAddress | None`.
+Every address on the `morpho_api` records is `ChecksumAddress`;
 optional ones (`curator`, `guardian`, `fee_recipient`, `performance_fee_recipient`,
 `management_fee_recipient`, `inner_vault`, `VaultFlowCap.admin`, the `VaultV2Cap`
 market params) are `ChecksumAddress | None`.
@@ -249,14 +270,21 @@ on CCIP, `active_return` → `OperationId`, `asset_id`, `tracked_position_set_ha
 before passing it on.
 
 **HyperCore (preview).** The fuses, `HyperCoreSubstrates`, `HyperCoreReader`,
-`read_hypercore_transfer_snapshot` and the helpers `system_address`, `read_index_of`,
+`read_hypercore_transfer_snapshot` and the helpers `system_address`, `precompile_index_of`
+(3.x `read_index_of`, renamed: it reads nothing),
 `perp_dex_of`, `is_native_perp_asset`, `is_hip3_asset` take the HyperCore ids;
 `HyperCorePerpAssetInfo`, `HyperCorePerpMarket`, `HyperCoreSpotLeg`,
 `HyperCorePendingState` and `HyperCoreTransferSnapshot` carry them.
+`HyperCorePendingReader(vault, reader)` takes the vault's `PlasmaVaultAddress`, not a
+`PlasmaVault` wrapper.
 
 **External state.** `ExternalStateExecutor.proposal_hash` returns and `confirm_balance`
 takes a `ProposalHash`; `BalanceProposal.proposal_hash` is a `ProposalHash`;
 `ExternalStateEvent.transaction_hash` is a `TxHash`.
+`ExternalStateVaultState.last_checked_custodian_timestamp`,
+`BalanceFuseSnapshot.last_custodian_update_timestamp`, `BalanceProposal.proposed_at`,
+`last_updated()` and `get_oldest_update_timestamp()` are web3's `Timestamp`, and
+`ExternalStateExecutor.proposal_hash(proposed_at=)` takes one.
 `ExternalStateExecutor.mark_nav` and `NavMark` are gone: send `propose_balance` and
 `confirm_balance` from separate custodians, then
 `PlasmaVault.update_markets_balances([IporFusionMarkets.EXTERNAL_STATE])`.
@@ -327,7 +355,8 @@ placeholder wrapper.
   `.decode(raw)` and `.map(f)` need no context. `Call(...)` no longer takes `ctx=`.
 - A wrapper method that executes to answer (storage, log scans, dependent reads) is
   named `read_*` and takes the context first (table below).
-- Executors and orchestrators keep their contexts: `Multicall3(ctx)` (every batch,
+- Executors and orchestrators keep their contexts: `Multicall3(ctx, *, address=,
+  batch_size=)` (options by keyword; every batch,
   every re-run of a failed sub-call and the per-call fallback run on its `ctx`, so a
   pinned context keeps them all at its block; it is no longer a `ContractWrapper`,
   `aggregate3(calls)` still returns the raw `Call`), `VaultSimulator`,
@@ -342,7 +371,14 @@ placeholder wrapper.
   `command_in_flight` and `transfer_in_flight` read on `hub_ctx`. The Calls a lane
   returns are unexecuted, and the executor and dispatcher share one address, so pick
   the context yourself: `lane.get_balance().call(lane.hub_ctx)`,
-  `lane.observation().call(lane.spoke_ctx)`. `CrosschainTransport.executor(address)`
+  `lane.observation().call(lane.spoke_ctx)`, or let the lane pick:
+  `lane.read_hub_state()` reads every executor bucket and counter
+  (`LaneHubState`) on `hub_ctx` through `Multicall3`, at one block (a `latest`, `safe` or
+  `finalized` default block resolved to its number once, so a per-call fallback
+  stays on it; a number or hash as is);
+  `lane.read_observation()` runs the observation on `spoke_ctx`. Keep
+  `transfer_in_flight()` / `command_in_flight()` for those decisions: the counters
+  do not see a CCIP recall or tell a parked command from a pending one. `CrosschainTransport.executor(address)`
   and `.dispatcher(address)` no longer take a context.
 - Chain-bound decoding takes the chain explicitly:
   `ExternalStateExecutor.pending_proposals(account, *, chain_id)`,
@@ -380,6 +416,10 @@ placeholder wrapper.
 | `MorphoReader.rates_from(market, params)` | `MorphoReader.read_rates_from(ctx, market, params)` (it reads the IRM) |
 | `AaveV3Reader.position_breakdown(asset, user)` | `AaveV3Reader.read_position_breakdown(ctx, asset, user)` |
 | `AaveV3FuseReader.pool()` | `AaveV3FuseReader.read_pool(ctx)` |
+| `PlasmaVault.read(target, data)` / `read_as(target, data, ...)` | `PlasmaVault.universal_read(target, data)` / `universal_read_decoded(target, data, ...)` (they build a Call; `read_*` names only methods that execute) |
+| `read_index_of(asset)` | `precompile_index_of(asset)` |
+| `ctx.default_block = n` | `ctx = ctx.at_block(n)` |
+| `Multicall3(ctx, address)` | `Multicall3(ctx, address=address)` |
 | `executor.pending_proposals(account)` | `executor.pending_proposals(account, chain_id=ctx.chain_id)` |
 | `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`) |
@@ -512,8 +552,12 @@ is the wrong one.
 - `MorphoApiError` (still a `RuntimeError`), `ExternalStateEventDecodeError` (still a
   `ValueError`) and `VerifierResultUnavailable` (still a `LookupError`) now derive
   from `IporFusionError`, so an `except IporFusionError` placed before their own
-  handlers catches them first. `MorphoApiError` lives in `ipor_fusion.errors` and is
-  exported from `ipor_fusion`; `ipor_fusion.morpho_api.MorphoApiError` still works.
+  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`,
+  `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`.
 - `EmptyCallResultError` is no longer an eth_abi `InsufficientDataBytes` (nor a
   `DecodingError`). Code that caught either around `.call()` to tolerate a missing
   contract or getter must catch `EmptyCallResultError`; return data that is present

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/PKG-INFO

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

@@ -367,8 +367,9 @@ def withdraw_collateral_action(max_amount: Amount) -> FuseAction:
 
 def run_simulation(web3: Web3) -> SimulationResult:
     """Build, fund and run the full Euler V2 credit lifecycle in one batch."""
-    ctx = Web3Context(web3=web3, chain_id=BASE_CHAIN_ID, signer=OWNER)
-    ctx.default_block = PINNED_BLOCK
+    ctx = Web3Context(web3=web3, chain_id=BASE_CHAIN_ID, signer=OWNER).at_block(
+        PINNED_BLOCK
+    )
     factory = FusionFactory(BASE_FUSION_FACTORY)
 
     # 1. Preview the deterministic addresses (eth_call, no gas, no state change).

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/examples/advanced_euler_v2_looping_arbitrum.py

@@ -315,8 +315,9 @@ def build_loop_action() -> FuseAction:
 
 def run_simulation(web3: Web3) -> SimulationResult:
     """Build, configure and run the WBTC/USDC leveraged loop without broadcasting."""
-    ctx = Web3Context(web3=web3, chain_id=ARBITRUM_CHAIN_ID, signer=OWNER)
-    ctx.default_block = PINNED_BLOCK
+    ctx = Web3Context(web3=web3, chain_id=ARBITRUM_CHAIN_ID, signer=OWNER).at_block(
+        PINNED_BLOCK
+    )
     factory = FusionFactory(ARBITRUM_FUSION_FACTORY)
     preview = factory.clone(**clone_args()).call(ctx)
 

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/examples/composed_hypercore_flow_arbitrum_hyperevm.py

@@ -76,6 +76,7 @@ from ipor_fusion import (
     USDC_SYSTEM_ADDRESS,
     USDC_TOKEN_INDEX,
     CcipChain,
+    CcipChainSelector,
     CcipCrosschainExecutor,
     CcipTransport,
     Command,
@@ -94,10 +95,10 @@ from ipor_fusion import (
     open_lane,
     parse_fuse_address,
     parse_plasma_vault_address,
+    precompile_index_of,
     quote_ccip_native_fee,
     read_hypercore_evm_exit_ceiling,
     read_hypercore_vault_state,
-    read_index_of,
     register_custom_errors,
 )
 from ipor_fusion.fuses import (
@@ -133,8 +134,8 @@ register_custom_errors(HYPERCORE_SEND_FUSE_ERRORS)
 ARBITRUM_CHAIN_ID = ChainId(42161)
 HYPEREVM_CHAIN_ID = ChainId(999)
 # Chainlink CCIP routers and chain selectors (docs.chain.link -> CCIP -> Directory).
-ARBITRUM_CCIP_SELECTOR = 4949039107694359620
-HYPEREVM_CCIP_SELECTOR = 2442541497099098535
+ARBITRUM_CCIP_SELECTOR = CcipChainSelector(4949039107694359620)
+HYPEREVM_CCIP_SELECTOR = CcipChainSelector(2442541497099098535)
 ARBITRUM_CCIP_ROUTER = Web3.to_checksum_address(
     "0x141fa059441E0ca23ce184B6A78bafD2A517DdE8"
 )
@@ -428,7 +429,7 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
     xyz_equity_usd6 = int(
         reader.account_margin_summary(XYZ_DEX, HYPERCORE_VAULT).call(ctx).account_value
     )
-    read_index = read_index_of(XYZ_NVDA_ASSET)
+    read_index = precompile_index_of(XYZ_NVDA_ASSET)
     # The precompile quotes a perp price with ``6 - szDecimals`` decimals; the
     # order fuse takes 8 implied decimals. Read szDecimals, then rescale.
     sz_decimals = int(reader.perp_asset_info(read_index).call(ctx).sz_decimals)
@@ -662,9 +663,7 @@ def _transport() -> CcipTransport:
 
 
 def _pinned(web3: Web3, chain_id: ChainId, block: int) -> Web3Context:
-    ctx = Web3Context(web3, chain_id=chain_id)
-    ctx.default_block = block
-    return ctx
+    return Web3Context(web3, chain_id=chain_id).at_block(block)
 
 
 class _Tail(NamedTuple):
@@ -889,8 +888,8 @@ def recall_attest_claim(web3_arb: Web3, web3_hype: Web3) -> dict[str, int]:
 
     # Where the live cycle stood: the settled bucket carries attestation 8, the
     # dispatcher holds the redeemed idle and the residual shares.
-    settled_before = int(lane.settled_remote_balance().call(hub_ctx))
-    observation_before = lane.observation().call(spoke_ctx)
+    settled_before = int(lane.read_hub_state().settled_remote_balance)
+    observation_before = lane.read_observation()
     remote_idle = Amount(int(observation_before.tracked_idle))
     residual_shares = int(
         PlasmaVault(HYPERCORE_VAULT).balance_of(EXECUTOR).call(spoke_ctx)

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/examples/crosschain_ccip_usdc_arbitrum_hyperevm.py

@@ -70,6 +70,7 @@ from web3 import Web3
 from ipor_fusion import (
     ERC20,
     CcipChain,
+    CcipChainSelector,
     CcipTransport,
     Command,
     CrosschainLane,
@@ -93,8 +94,8 @@ log = logging.getLogger("crosschain_ccip_usdc_arbitrum_hyperevm")
 # (docs.chain.link -> CCIP -> Directory -> Arbitrum One / Hyperliquid).
 ARBITRUM_CHAIN_ID = ChainId(42161)
 HYPEREVM_CHAIN_ID = ChainId(999)
-ARBITRUM_CCIP_SELECTOR = 4949039107694359620
-HYPEREVM_CCIP_SELECTOR = 2442541497099098535
+ARBITRUM_CCIP_SELECTOR = CcipChainSelector(4949039107694359620)
+HYPEREVM_CCIP_SELECTOR = CcipChainSelector(2442541497099098535)
 ARBITRUM_CCIP_ROUTER = Web3.to_checksum_address(
     "0x141fa059441E0ca23ce184B6A78bafD2A517DdE8"
 )
@@ -205,9 +206,7 @@ def _connected_web3(env_var: str, chain_id: ChainId) -> Web3:
 
 
 def _pinned_context(web3: Web3, chain_id: ChainId, block: int) -> Web3Context:
-    ctx = Web3Context(web3, chain_id=chain_id)
-    ctx.default_block = block
-    return ctx
+    return Web3Context(web3, chain_id=chain_id).at_block(block)
 
 
 # ── Pure builders (no chain access, unit-testable offline) ───────────────────

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/examples/external_state_margin_leg_base.py

@@ -807,8 +807,9 @@ def run_simulation(web3: Web3) -> SimulationResult:
     function does (exactly one failure, with the expected revert selector), not
     with ``result.all_success``.
     """
-    ctx = Web3Context(web3=web3, chain_id=BASE_CHAIN_ID, signer=OWNER)
-    ctx.default_block = PINNED_BLOCK
+    ctx = Web3Context(web3=web3, chain_id=BASE_CHAIN_ID, signer=OWNER).at_block(
+        PINNED_BLOCK
+    )
 
     factory = FusionFactory(BASE_FUSION_FACTORY)
 
@@ -931,7 +932,7 @@ def run_simulation(web3: Web3) -> SimulationResult:
     # to one custodian by either route, however separate the two keys are -- and
     # that is why a production deployment cannot drive both halves from one
     # process, whatever this example does under simulation.
-    proposed_at = baseline_timestamp + PROPOSE_OFFSET
+    proposed_at = Timestamp(baseline_timestamp + PROPOSE_OFFSET)
     proposal_hash = ExternalStateExecutor.proposal_hash(
         executor=executor_address,
         chain_id=BASE_CHAIN_ID,

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/examples/simple_aave_v3_supply_base.py

@@ -225,8 +225,9 @@ def build_supply_action(amount: Amount) -> FuseAction:
 
 def run_simulation(web3: Web3) -> SimulationResult:
     """Build, fund, deposit and supply -- all in one eth_simulateV1 batch."""
-    ctx = Web3Context(web3=web3, chain_id=BASE_CHAIN_ID, signer=OWNER)
-    ctx.default_block = PINNED_BLOCK
+    ctx = Web3Context(web3=web3, chain_id=BASE_CHAIN_ID, signer=OWNER).at_block(
+        PINNED_BLOCK
+    )
     factory = FusionFactory(BASE_FUSION_FACTORY)
 
     # 1. Preview the deterministic addresses (eth_call, no gas, no state change).

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/pyproject.toml

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

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/scripts/crosschain_readiness.py

@@ -43,7 +43,7 @@ from web3.types import RPCEndpoint
 
 from ipor_fusion import ERC20, Call, Web3Context, ccip_token_lane
 from ipor_fusion.crosschain import CcipCrosschainFactory, CcipOffRamp, CcipRouter
-from ipor_fusion.types import ChainId
+from ipor_fusion.types import CcipChainSelector, ChainId
 
 SCHEMA = "ipor-fusion.crosschain-readiness/4"
 EXIT_OK = 0
@@ -126,7 +126,7 @@ class ChainSpec:
 
     name: str
     chain_id: ChainId
-    chain_selector: int
+    chain_selector: CcipChainSelector
     env_var: str
     router: ChecksumAddress
     usdc: ChecksumAddress
@@ -137,7 +137,7 @@ class ChainSpec:
 ARBITRUM = ChainSpec(
     name="arbitrum",
     chain_id=ChainId(42161),
-    chain_selector=4949039107694359620,
+    chain_selector=CcipChainSelector(4949039107694359620),
     env_var="ARBITRUM_PROVIDER_URL",
     router=Web3.to_checksum_address("0x141fa059441E0ca23ce184B6A78bafD2A517DdE8"),
     usdc=Web3.to_checksum_address("0xaf88d065e77c8cC2239327C5EDb3A432268e5831"),
@@ -150,7 +150,7 @@ ARBITRUM = ChainSpec(
 HYPEREVM = ChainSpec(
     name="hyperevm",
     chain_id=ChainId(999),
-    chain_selector=2442541497099098535,
+    chain_selector=CcipChainSelector(2442541497099098535),
     env_var="HYPEREVM_PROVIDER_URL",
     router=Web3.to_checksum_address("0x13b3332b66389B1467CA6eBd6fa79775CCeF65ec"),
     usdc=Web3.to_checksum_address("0xb88339CB7199b77E23DB6E890353E22632Ba630f"),
@@ -756,9 +756,7 @@ def connect(spec: ChainSpec) -> Web3Context:
         raise ReadinessConfigError(
             f"{spec.env_var}: chain id {chain_id}, expected {spec.chain_id}"
         )
-    ctx = Web3Context(web3=web3, chain_id=spec.chain_id)
-    ctx.default_block = head
-    return ctx
+    return Web3Context(web3=web3, chain_id=spec.chain_id).at_block(head)
 
 
 def config_error_report(message: str) -> dict[str, Any]:

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/src/ipor_fusion/__init__.py

@@ -144,6 +144,7 @@ from ipor_fusion.crosschain import (
     EVMTokenAmount,
     ExecutorInitParams,
     LaneFuses,
+    LaneHubState,
     LaneObservation,
     MessageExecutionState,
     MessageV1,
@@ -168,7 +169,6 @@ from ipor_fusion.crosschain import (
     TaxiMessage,
     TokenTransferV1,
     VerifierResult,
-    VerifierResultUnavailable,
     ccip_events,
     ccip_receive_calldata,
     ccip_token_lane,
@@ -205,18 +205,21 @@ from ipor_fusion.errors import (
     CrosschainDiscoveryError,
     EmptyCallResultError,
     ExternalStateError,
+    ExternalStateEventDecodeError,
     HyperCoreValuationError,
     IporFusionError,
     LogScanError,
     LogSourceUnavailable,
     MorphoMarketNotFoundError,
     NotPlasmaVaultError,
+    OwnerNotFoundError,
     SimulationError,
     SimulationRunError,
     TransactionError,
     UnsupportedChainError,
     UnsupportedContractVersionError,
     UnsupportedVaultVersionError,
+    VerifierResultUnavailable,
     decode_custom_error,
     get_revert_reason,
     register_custom_errors,
@@ -300,7 +303,7 @@ from ipor_fusion.fuses import (
     is_hip3_asset,
     is_native_perp_asset,
     perp_dex_of,
-    read_index_of,
+    precompile_index_of,
     system_address,
 )
 from ipor_fusion.fuses.external_state_events import (
@@ -308,7 +311,6 @@ from ipor_fusion.fuses.external_state_events import (
     EXTERNAL_STATE_EVENTS,
     EXTERNAL_STATE_TOPICS,
     ExternalStateEvent,
-    ExternalStateEventDecodeError,
     ExternalStateEventSpec,
     decode_external_state_event,
     external_state_event_name,
@@ -411,6 +413,7 @@ from ipor_fusion.types import (
     Amount,
     AssetId,
     AssetSource,
+    CcipChainSelector,
     ChainId,
     Check,
     CommandId,
@@ -580,6 +583,7 @@ __all__ = [
     "StargateLane",
     "CcipLane",
     "LaneFuses",
+    "LaneHubState",
     "LaneObservation",
     "open_lane",
     "open_lanes",
@@ -717,7 +721,7 @@ __all__ = [
     "is_hip3_asset",
     "is_native_perp_asset",
     "perp_dex_of",
-    "read_index_of",
+    "precompile_index_of",
     "UniversalTokenSwapperAbi",
     "UniversalTokenSwapperFuse",
     "UniversalTokenSwapperSubstrates",
@@ -754,6 +758,7 @@ __all__ = [
     "LogSourceUnavailable",
     "MorphoMarketNotFoundError",
     "NotPlasmaVaultError",
+    "OwnerNotFoundError",
     "TransactionError",
     "SimulationError",
     "SimulationRunError",
@@ -817,6 +822,7 @@ __all__ = [
     "ReturnRequestId",
     "StargateAssetId",
     "LayerZeroEid",
+    "CcipChainSelector",
     "TransferId",
     "Price",
     "Period",

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/src/ipor_fusion/cli/market_cmd.py

@@ -123,7 +123,7 @@ def morpho_blue(
     provider_url = _resolve_provider(cfg, chain_id)
     ctx = Web3Context.from_url(provider_url)
     if block is not None:
-        ctx.default_block = block
+        ctx = ctx.at_block(block)
     reader = MorphoReader(morpho_blue_address(chain_id))
     mid = market_id
     params, state = reader.read_existing_market(ctx, mid)
@@ -143,14 +143,14 @@ def morpho_blue(
         click.echo(
             json_lib.dumps(
                 build_morpho_blue_market_json(
-                    market_id,
-                    chain_id,
-                    params,
-                    state,
-                    rates,
-                    api_market,
-                    api_error,
-                    public_allocator,
+                    market_id=market_id,
+                    chain_id=chain_id,
+                    params=params,
+                    state=state,
+                    rates=rates,
+                    api_market=api_market,
+                    api_error=api_error,
+                    public_allocator=public_allocator,
                 ),
                 indent=2,
             )

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/src/ipor_fusion/cli/options.py

@@ -123,7 +123,7 @@ def _build_ctx(
     provider_url = _resolve_provider(cfg, chain_id)
     ctx = Web3Context.from_url(provider_url)
     if block_number is not None:
-        ctx.default_block = block_number
+        ctx = ctx.at_block(block_number)
     return chain_id, ctx
 
 

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/src/ipor_fusion/cli/vault_cmd.py

@@ -441,7 +441,7 @@ def oracle_mapping(
     effective_block = (
         block_number if block_number is not None else ctx.web3.eth.block_number
     )
-    ctx.default_block = effective_block
+    ctx = ctx.at_block(effective_block)
 
     try:
         resolve_access_manager(ctx, vault_address)

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/src/ipor_fusion/core/access.py

@@ -18,6 +18,7 @@ from ipor_fusion.errors import (
     ContractNotFoundError,
     EmptyCallResultError,
     NotPlasmaVaultError,
+    OwnerNotFoundError,
 )
 from ipor_fusion.types import AccessManagerAddress, Period, PlasmaVaultAddress, RoleId
 
@@ -112,7 +113,14 @@ class AccessManager(ContractWrapper):
     # ── Composite reads on ``ctx``: event replay + batched hasRole reads ───
 
     def read_owner(self, ctx: Web3Context) -> ChecksumAddress:
-        return self.read_owners(ctx)[0]
+        """The first of :meth:`read_owners`; raises `OwnerNotFoundError` when no
+        account holds ``OWNER_ROLE``."""
+        owners = self.read_owners(ctx)
+        if not owners:
+            raise OwnerNotFoundError(
+                f"access manager {self._address} has no account with OWNER_ROLE"
+            )
+        return owners[0]
 
     def read_owners(self, ctx: Web3Context) -> list[ChecksumAddress]:
         return [

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/src/ipor_fusion/core/context.py

@@ -140,12 +140,10 @@ class Web3Context:
 
     @property
     def default_block(self) -> BlockIdentifier:
+        """The block reads default to: ``"latest"`` unless this context came
+        from `at_block`. Read-only; pin a copy with `at_block` instead."""
         return self._default_block
 
-    @default_block.setter
-    def default_block(self, value: BlockIdentifier) -> None:
-        self._default_block = value
-
     def at_block(self, block: BlockIdentifier) -> Web3Context:
         """A copy of this context whose reads default to ``block``: same
         connection, signer, log source, cache and scan bounds. Pinning a copy leaves

{ipor_fusion-4.0.0.dev129 → ipor_fusion-4.0.0.dev137}/src/ipor_fusion/core/contract.py

@@ -134,7 +134,7 @@ class ContractWrapper:
 
     A method that must execute to answer (a storage read, a log scan, a read
     that depends on another read) is named ``read_*`` and takes the context as
-    its first argument.
+    its first argument; no other method carries the prefix.
     """
 
     def __init__(self, address: ChecksumAddress):