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

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

@@ -188,8 +188,9 @@ the lifecycle matrix follows that.
 - `substrates.py` — public per-market bytes32 substrate decoding (`decode_substrate`,
   `SubstrateInfo`, `format_market_label`, `market_name`; re-exported from `ipor_fusion`),
   used by the CLI, MCP and `readers/lending_health`
-- `validation.py` — public vault validation (`validate_vault`; `read_erc20_holdings` +
-  `validate_vault_state` for an already-fetched state typed by the `VaultState` protocol):
+- `validation.py` — public vault validation (`validate_vault` fetches and validates;
+  `validate_vault_state` is a pure function of a snapshot typed by the `VaultState`
+  protocol):
   `VaultValidation` with ordered `Finding`s, an ok/warning/critical verdict, the
   `Reconciliation`, `Erc20Holdings` and lending health; `dependency_graph.py` holds the
   balance-graph checks
@@ -197,9 +198,11 @@ the lifecycle matrix follows that.
   `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
-  snapshots) and `vault_positions.py` (Morpho/Aave position breakdowns and their token
-  prices); `vault_info.py` — `build_vault_info_json`, the
-  `fusion vault info --json` document (contract names via an injected `resolve_name`),
+  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);
   `cache.py` the on-disk contract and deployment caches (`~/.cache/ipor-fusion/`).
   `morpho_api.py` the Morpho public GraphQL API client (`fetch_market`, `fetch_vault`,
@@ -213,8 +216,8 @@ the lifecycle matrix follows that.
   time and request budget, and raises `LogScanError` rather than return partial logs;
   `LogSource`: an optional index `Web3Context.get_logs` asks first for a topic0-only
   filter, falling back to the scan on `LogSourceUnavailable`;
-  prefer a storage or view read over a scan, as `get_balance_fuses` and
-  `withdraw_manager_address` do), `plasma_vault`, `access`, `withdraw_manager`, `rewards_manager`, `fee_manager`,
+  prefer a storage or view read over a scan, as `read_balance_fuses` and
+  `read_withdraw_manager_address` do), `plasma_vault`, `access`, `withdraw_manager`, `rewards_manager`, `fee_manager`,
   `simulation` (`VaultSimulator`, eth_simulateV1, `erc20_balance_slot` and ERC-20 balance
   overrides), `oracle`, `fusion_factory`,
   `external_state_executor` (NAV marks for market 50), `erc20`, `fuse_action`
@@ -276,18 +279,36 @@ Two patterns explain most of the code; know both before writing SDK code
 or examples.
 
 - `Call[T]` (`core/contract.py`): every `ContractWrapper` method (one per
-  Solidity function) returns a `Call` instead of executing. `.call()` runs
-  `eth_call` and decodes to `T`; `.send()` signs and submits, returning a
-  `TxReceipt`; `.calldata` hands the bytes to an external signer (a wrapper
-  built with `ctx=None`, e.g. `PlasmaVault(None, address)`, builds calldata
-  offline; there is no separate encoder factory);
-  `.build_transaction()` / `Web3Context.estimate_gas` preview without signing.
-  A `Call` without `output_types` (a write) raises on `.call()`. The same
-  `Call` feeds `VaultSimulator.observe`, so reads, sends and simulations share
-  one definition.
+  Solidity function) returns a `Call` instead of executing. Construction and
+  Call building are offline: a wrapper is its address (plus genuine contract
+  parameters such as a legacy oracle's decimals) and holds no `Web3Context`;
+  a `Call` holds `to`, `data`, output types and decoder, never a context.
+  Execution takes the context as a required argument: `.call(ctx)` runs
+  `eth_call` (at the context's, possibly pinned, block; `block=` overrides)
+  and decodes to `T`; `.send(ctx)` signs and submits, returning a `TxReceipt`;
+  `.build_transaction(ctx)` / `.estimate_gas(ctx)` preview without signing
+  (default `"latest"`). `.calldata`, `.decode(raw)` and `.map(f)` stay
+  offline. A `Call` without `output_types` (a write) raises on `.call(ctx)`.
+  The same `Call` feeds `VaultSimulator.observe`, so reads, sends and
+  simulations share one definition.
+- A wrapper method that must execute to answer (storage, a log scan, a read
+  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
+  (`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).
+  A chain-dependent decode takes the chain explicitly
+  (`ExternalStateExecutor.pending_proposals(account, chain_id=)`); a decoder
+  never consults the executing context.
 - Batch independent reads: `Multicall3(ctx).aggregate(calls)` (raises as
-  `.call()` would) or `.try_aggregate(calls)` (``None`` per failed read) runs
-  many `Call`s in one `eth_call` at one block. A loop of `.call()`s, or a
+  `.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.
 - Fuses (`fuses/`) are stateless encoders: a method returns an immutable
@@ -295,6 +316,9 @@ or examples.
   via `self._action_raw(solidity_signature, values)`; the shared `_validate_*`
   helpers raise before encoding. `PlasmaVault.execute([actions])` runs the
   batch atomically.
+- Pin reads, never mutate a shared context: `ctx.at_block(n)` is a copy whose
+  reads (and `get_logs` upper bound) default to block ``n``; `Call.call(ctx, block=n)`
+  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
@@ -383,9 +407,14 @@ are not validated.
 
 ## Domain rules (verified against the contracts)
 
-- `fetch_vault_data(..., chain_id=0)` (the default) skips lending_health,
-  Morpho/Aave position breakdowns and token prices, all guarded by `if chain_id:`.
-  Pass a real chain_id or those come back null/empty, silently.
+- `fetch_vault_data(ctx, vault, *, block=, lending=, metadata=)` is the snapshot:
+  it resolves one block (``block``, else a numeric `ctx.default_block`, else latest),
+  runs every read on `ctx.at_block(block)` (log scans end there too) and returns
+  everything validation and the ``vault info`` document need, so neither reads the
+  chain. The chain is `ctx.chain_id`; ``lending=False`` skips lending health, the
+  position breakdowns, their prices and the unpriceable check; ``metadata=False``
+  skips token symbols/decimals. Add a new chain-state input to the snapshot, never a
+  read inside a renderer or validator.
 - PlasmaVault serves governance/view functions via `fallback()` delegatecall to
   PlasmaVaultBase, so Etherscan's ABI for the vault address omits callable
   view functions such as `getDependencyBalanceGraph`. An empty dependency graph

{ipor_fusion-4.0.0.dev88 → ipor_fusion-4.0.0.dev103}/MIGRATION_4.md

@@ -57,20 +57,40 @@ names earlier reachable only by module path (`FusionFactory`, `FusionInstance`,
 `ipor_fusion`: a module path outside the README's list (*Public API and stability*)
 still works but is internal.
 
-**Vault reads and validation.** `fetch_vault_data(chain_id=)`, `fetch_deployment_info`,
-`build_vault_info_json`, `ensure_supported_chain` and `fetch_vault_lending_health`
-take `ChainId`. The vault is a `PlasmaVaultAddress` (see *Address roles*) in
-`validate_vault` and `fetch_deployment_info`; `build_vault_info_json(ctx, plasma_vault,
-data, *, chain_id, chain_label)` takes no address, takes the chain by keyword, and
-labels the document with `plasma_vault.address` (a test that mocks `PlasmaVault`
-sets `.address`). `fetch_unpriceable_priced_tokens` takes the oracle and
+**Vault reads and validation.** The vault read is one pinned snapshot, and the
+chain is always the context's:
+
+- `fetch_vault_data(ctx, vault, *, block=None, lending=True, metadata=True)` takes
+  the vault address (not a `PlasmaVault`) and no `chain_id`. It resolves one block
+  (``block``, else a numeric `ctx.default_block`, else the latest) and runs every
+  read, log scans included, on `ctx.at_block(block)`; `ctx` is not modified. The old
+  ``chain_id=0`` switch is ``lending=False``; ``metadata=False`` skips token symbols
+  and decimals. `VaultData` gains `vault`, `chain_id`, `market_balances`, `erc20`,
+  `token_symbols` and `token_decimals`; `WithdrawManagerData` gains
+  `shares_to_release_assets` and `pending_request_assets`.
+- `validate_vault(ctx, vault, *, block=None)` fetches with ``metadata=False`` and
+  validates; it no longer takes ``resolve_symbol``. `validate_vault_state(state)` is
+  pure: a custom `VaultState` also provides `vault`, `chain_id`, `market_balances`,
+  `erc20` and the queue's `shares_to_release_assets`. `read_erc20_holdings` is gone:
+  the holdings are `VaultData.erc20`.
+- `build_vault_info_json(data, *, resolve_name=None)` renders from the snapshot and
+  reads nothing; the chain and its label come from `data.chain_id`.
+- `fetch_deployment_info(ctx, vault, *, api_key=None)` and
+  `fetch_vault_lending_health(ctx, vault, *, balance_fuse_market_ids,
+  market_substrates, aave_pools=None)` take the chain from `ctx`.
+- `Web3Context(web3, chain_id, *, ...)` and `Web3Context.from_url(url, *, ...)` take
+  their options by keyword. New: `Web3Context.at_block(block)` (a pinned copy) and
+  `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"``.
+
+`ensure_supported_chain` takes `ChainId`. `fetch_unpriceable_priced_tokens` takes 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
 typed for `str` still fits). Market-keyed data is keyed by `MarketId`:
 `VaultData.market_substrates`, `dependency_graph`, `morpho_positions`,
-`aave_positions`; the `VaultState` protocol, `validate_vault_state`
-(`market_balances`), `fetch_vault_lending_health`, `fetch_unpriceable_priced_tokens`
+`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`).
 
@@ -93,7 +113,7 @@ The Uniswap V3 / Ramses V2 position events' `version`, `sender` and `recipient`
 `quote_ccip_native_fee(block=)` and `OracleMappingReader.asset_source_events` take a
 `BlockIdentifier`.
 
-**Address roles.** `PlasmaVault(ctx, address)` (`ctx` may be `None`, see below),
+**Address roles.** `PlasmaVault(address)`,
 `validate_vault`, `fetch_deployment_info`, the HyperCore, lending-health and
 oracle-mapping readers, `read_external_state`, `VaultSimulator(vault=)`,
 `CrosschainSimulator`, crosschain discovery, the hub-manager inputs
@@ -110,7 +130,7 @@ Every fuse constructor, `FuseAction.fuse`, `BalanceFuse.fuse`,
 `LaneFuses` and the HyperCore balance-fuse argument take a `FuseAddress`, and
 `get_fuses()`, `get_instant_withdrawal_fuses()`, `get_rewards_fuses()` and
 `VaultData.fuses` / `instant_fuses` / `fuse_markets` keys return it.
-`AccessManager(ctx, address)` takes an `AccessManagerAddress`;
+`AccessManager(address)` takes an `AccessManagerAddress`;
 `get_access_manager_address()`, `VaultData.access_manager` and
 `FusionInstance.access_manager` return one. `resolve_access_manager` still takes any
 `ChecksumAddress`: it is what checks that the address is a vault.
@@ -147,7 +167,7 @@ gone: use `morpho_blue_address(chain_id)`.
 `decode_substrate`, `market_name`, `format_market_label` take `MarketId`.
 
 **Access.** `AccessManager.has_role`, `grant_role`, `revoke_role`,
-`get_accounts_with_role` take `RoleId | Roles`; `RoleAccount.role_id` is `RoleId`.
+`read_accounts_with_role` take `RoleId | Roles`; `RoleAccount.role_id` is `RoleId`.
 
 **Morpho.** `MorphoBlueMarketId` now always carries `0x`; build it with
 `parse_morpho_market_id` instead of `MorphoBlueMarketId("<64 hex>")`. `fetch_market`,
@@ -194,29 +214,6 @@ are `ProposalHash`; `ExternalStateEvent.transaction_hash` is a `TxHash`.
 except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
 `MarketId`. Calling an MCP tool function directly from Python takes `ChainId`.
 
-**Offline wrappers.** `ContractWrapper.encoder()` (and the `PlasmaVault` /
-`AccessManager` overrides) is gone. Every wrapper constructor takes
-`ctx: Web3Context | None`, so build an offline wrapper with the normal
-constructor and an address: `PlasmaVault(None, vault)`, `ERC20(None, token)`,
-`FusionFactory(None, factory)`, `LegacyPriceOracleMiddleware(None, oracle,
-Decimals(8))`. The address is required (there is no zero-address placeholder) and
-subclass parameters stay required, so the wrapper is fully initialized:
-`.encoder()` skipped the constructor, and a legacy oracle built that way failed to
-decode `get_asset_price`. `.calldata` still needs no context; `.call()`, `.send()`,
-`.build_transaction()` and `.estimate_gas()` raise `ValueError` until one is passed
-to them, and a method that reads the chain itself (log scans such as
-`get_balance_fuses` or `get_pending_requests`, `withdraw_manager_address`,
-`Multicall3.aggregate` / `try_aggregate`, the Aave V3 and Morpho position reads)
-raises `ValueError("Web3Context required: <wrapper> at <address> ...")` instead of
-an `AttributeError` on `None`. `ExternalStateExecutor` still refuses the zero
-address for its hash and event readers.
-
-| 3.x | 4.0 |
-|---|---|
-| `PlasmaVault.encoder(vault)` | `PlasmaVault(None, vault)` |
-| `ERC20.encoder()` (no address) | `ERC20(None, token)`: pass the real address |
-| `Cls.__new__(Cls)` + `_ctx` / `_address` | `Cls(None, address)` |
-
 **Fuse base.** `Fuse`, `StakeFuse` and the shared validators and substrate packers
 live in `ipor_fusion.core.fuse`; `ipor_fusion.fuses.base`, `ipor_fusion.fuses` and
 `ipor_fusion` re-export them, so existing imports keep working. Fuse equality and
@@ -229,6 +226,93 @@ hash now cover every attribute a fuse stores, not only its class and address (se
 `ipor_fusion.cli.vault_cmd` was split into `options`, `vault_info_view`,
 `vault_markets_view` and `oracle_mapping_view` (private names, not API).
 
+## Context-free wrappers
+
+A contract wrapper is its address (plus genuine contract parameters, such as a legacy
+oracle's decimals) and nothing chain-bound. Construction and `Call` building are
+offline; the `Web3Context` is a required argument where something executes. In 3.x
+the context was stored on the wrapper and copied into every `Call`; that is gone,
+together with `ContractWrapper.encoder()`, `Call.ctx` and the zero-address
+placeholder wrapper.
+
+- Build every wrapper from its address: `PlasmaVault(vault)`, `ERC20(token)`,
+  `FusionFactory(factory)`, `AccessManager(manager)`,
+  `LegacyPriceOracleMiddleware(oracle, Decimals(8))`, the crosschain executor,
+  dispatcher and factory wrappers, the Chainlink CCIP wrappers, the readers
+  (`MorphoReader(morpho)`, `AaveV3Reader(pool)`, ...). `HyperCoreReader()` takes no
+  argument. The nominal address types are unchanged.
+- Execute a `Call` on a context: `.call(ctx, *, block=None)` (reads default to the
+  context's, possibly pinned, block), `.send(ctx)`, `.build_transaction(ctx, *,
+  block="latest")`, `.estimate_gas(ctx, *, block="latest")`. `ctx` may be passed by
+  keyword. Without it Python raises `TypeError` (and pyright reports the call),
+  instead of the 3.x `ValueError("Web3Context required ...")`. `.calldata`,
+  `.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,
+  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`,
+  `CrosschainSimulator` and `OracleMappingReader(ctx, oracle)`.
+- Resolvers that probe the chain stay eager and return context-free wrappers:
+  `price_oracle_middleware(ctx, oracle)`, `resolve_access_manager(ctx, vault)`,
+  `ExternalStateExecutor.for_vault(ctx, vault)`. A resolved oracle carries the ABI
+  found on that chain and block; resolve again for another one.
+- Crosschain lanes own both contexts: `CcipLane` / `StargateLane` take `hub_ctx=` and
+  `spoke_ctx=` instead of `spoke_chain_id=` (it is `spoke_ctx.chain_id`), and expose
+  them as `lane.hub_ctx` / `lane.spoke_ctx`. `needs_attestation`,
+  `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)`
+  and `.dispatcher(address)` no longer take a context.
+- Chain-bound decoding takes the chain explicitly:
+  `ExternalStateExecutor.pending_proposals(account, *, chain_id)`,
+  `parse_balance_proposed(log, *, chain_id)` and
+  `find_balance_proposed(logs, account=None, *, chain_id)` require it (3.x fell back
+  to the wrapper's context). The decoder captures it, so `.call(ctx)`, `Multicall3`
+  and `VaultSimulator.observe` stamp the same hash for the same bytes, whatever
+  context executes them. Pass `ctx.chain_id` for the chain you read from.
+  `pending_proposals` now refuses an executor at the zero address when the Call is
+  built, not when it is decoded. `mark_nav` takes the chain from its contexts.
+
+| 3.x | 4.0 |
+|---|---|
+| `PlasmaVault(ctx, vault)`, `ERC20(ctx, token)`, any `Wrapper(ctx, address, ...)` | `PlasmaVault(vault)`, `ERC20(token)`, `Wrapper(address, ...)` |
+| `PlasmaVault.encoder(vault)`, `ERC20.encoder()` | `PlasmaVault(vault)`, `ERC20(token)` (the real address) |
+| `LegacyPriceOracleMiddleware(ctx, oracle, decimals)` | `LegacyPriceOracleMiddleware(oracle, decimals)` |
+| `HyperCoreReader(ctx)` | `HyperCoreReader()` |
+| `Call(to=, data=, ..., ctx=ctx)` | `Call(to=, data=, ...)` |
+| `call.call()` / `call.call(block=n)` | `call.call(ctx)` / `call.call(ctx, block=n)` |
+| `call.send()` | `call.send(ctx)` |
+| `call.build_transaction(block=b)`, `call.estimate_gas(block=b)` | `call.build_transaction(ctx, block=b)`, `call.estimate_gas(ctx, block=b)` |
+| `call.ctx` | gone: keep the context yourself |
+| `PlasmaVault.get_balance_fuses()` | `PlasmaVault.read_balance_fuses(ctx)` |
+| `PlasmaVault.withdraw_manager_address()` | `PlasmaVault.read_withdraw_manager_address(ctx)` |
+| `PlasmaVault.price_oracle_address()` | `PlasmaVault.read_price_oracle_address(ctx)` |
+| `AccessManager.owner()` / `owners()` / `atomists()` | `read_owner(ctx)` / `read_owners(ctx)` / `read_atomists(ctx)` |
+| `AccessManager.get_accounts_with_role(role)` | `AccessManager.read_accounts_with_role(ctx, role)` |
+| `AccessManager.get_all_role_accounts()` | `AccessManager.read_all_role_accounts(ctx)` |
+| `PriceOracleMiddleware.get_assets_price_sources()` | `PriceOracleMiddleware.read_assets_price_sources(ctx)` |
+| `WithdrawManager.get_pending_requests(from_block)` | `WithdrawManager.read_pending_requests(ctx, from_block)` |
+| `WithdrawManager.get_pending_requests_info(from_block)` | `WithdrawManager.read_pending_requests_info(ctx, from_block)` |
+| `MorphoReader.position_breakdown(id, user)` | `MorphoReader.read_position_breakdown(ctx, id, user)` |
+| `MorphoReader.require_market(id)` | `MorphoReader.read_existing_market(ctx, id)` |
+| `MorphoReader.rates(id)` | `MorphoReader.read_rates(ctx, id)` |
+| `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)` |
+| `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`) |
+| `transport.executor(ctx, address)` / `transport.dispatcher(ctx, address)` | `transport.executor(address)` / `transport.dispatcher(address)` |
+
+A service that caches wrappers per chain can now share one wrapper across chains and
+snapshots; what it must not share is a `Call` result decoded with a chain-bound
+argument (`chain_id=`) for another chain. An external signer still needs the real
+target address (`call.to`) and builds the chain-qualified transaction itself, or
+gets it from `call.build_transaction(ctx)`.
+
 ## Behavior changes
 
 - Two fuses are equal (and hash alike) only when they have the same class and the
@@ -305,7 +389,7 @@ is the wrong one.
   executor of a transport. An executor reporting `transportKind()` `UNDEFINED` is now
   rejected by `detect_transport` instead of being returned. A transport kind passed in
   that has no lane is still a `ValueError`.
-- `Call.call()` and `Call.decode()` on a write-only `Call` raise `ValueError`, not
+- `Call.call(ctx)` and `Call.decode()` on a write-only `Call` raise `ValueError`, not
   `RuntimeError`. `CrosschainSimulator.relay` raises `ValueError`, not
   `RuntimeError`, for a message to a chain that was not added.
 - `VaultSimulator.run` (provider error from `eth_simulateV1`, or a result count that

{ipor_fusion-4.0.0.dev88 → ipor_fusion-4.0.0.dev103}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev88
+Version: 4.0.0.dev103
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -141,8 +141,8 @@ ctx = Web3Context.from_url(
     private_key="0x...",
 )
 
-# 2. Wrap the PlasmaVault contract
-vault = PlasmaVault(ctx, Web3.to_checksum_address("0xVAULT_ADDRESS"))
+# 2. Wrap the PlasmaVault contract (an address only; contexts are passed at execution)
+vault = PlasmaVault(Web3.to_checksum_address("0xVAULT_ADDRESS"))
 
 # 3. Build a fuse action (e.g. supply USDC to Aave V3)
 fuse = AaveV3SupplyFuse(Web3.to_checksum_address("0xFUSE_ADDRESS"))
@@ -151,25 +151,28 @@ action = fuse.supply(
     amount=1_000_000,  # 1 USDC (6 decimals)
 )
 
-# 4. Execute on-chain (execute() returns a Call; .send() signs and submits it)
-receipt = vault.execute([action]).send()
+# 4. Execute on-chain (execute() returns a Call; .send(ctx) signs and submits it)
+receipt = vault.execute([action]).send(ctx)
 ```
 
 Fuse, factory and manager addresses per chain are published in
 [ipor-abi](https://github.com/IPOR-Labs/ipor-abi) (`mainnet/mainnet-<chain>-fusion/addresses.json`).
-A fuse must also be registered on the vault; `vault.get_fuses().call()` lists the registered ones.
+A fuse must also be registered on the vault; `vault.get_fuses().call(ctx)` lists the registered ones.
 
 Amounts are raw on-chain integers (`Amount`, `Shares` in `ipor_fusion.types`); the SDK never scales by decimals.
 
 ### Read, send, or simulate
 
-Every wrapper method returns a `Call` instead of executing. The same `Call` powers all three modes:
+Every wrapper method returns a `Call` instead of executing. Wrappers and `Call`s hold no
+`Web3Context`: the context is a required argument wherever something runs, and methods that
+must read the chain to answer are named `read_*` and take it first
+(`vault.read_balance_fuses(ctx)`). The same `Call` powers all three modes:
 
 ```python
 from ipor_fusion import VaultSimulator
 
-total = vault.total_assets().call()          # eth_call -> Amount
-receipt = vault.execute([action]).send()     # signed tx -> TxReceipt
+total = vault.total_assets().call(ctx)          # eth_call -> Amount
+receipt = vault.execute([action]).send(ctx)     # signed tx -> TxReceipt
 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()
@@ -312,7 +315,7 @@ Reverts on the deploy-and-configure path, keyed by selector so a failed transact
 | `0x9996b315` | `AddressEmptyCode(address)` | `execute()` touched a market with no balance fuse | `add_balance_fuse(market_id, balance_fuse)` before the first `execute` on that market |
 | `0x4bf4de4e` | `HandlerNotFound()` | A protocol called back into the vault during `execute()` (a flash loan) and no handler is registered for its address and selector | `update_callback_handler(handler, sender, selector)` before the first `execute` that triggers the callback |
 | `0x068ca9d8` | `AccessManagedUnauthorized(address)` | The caller lacks the role the function requires: `FUSE_MANAGER` for `add_fuses`, `grant_market_substrates`, `add_balance_fuse`, `update_callback_handler`; `ALPHA` for `execute`; `WHITELIST` for `deposit` and `mint` on a private vault | `AccessManager.grant_role(role, account, 0)` from the role's admin (`OWNER` grants `ATOMIST`, `ATOMIST` grants the rest); for a reverting `deposit`, whitelist the depositor or convert the vault to public |
-| `ValueError: Private key required for sending transactions` | SDK, before any transaction | `.send()` on a `Web3Context` without a key | `Web3Context(w3, chain_id, signer=..., private_key=...)` or `Web3Context.from_url(url, private_key=...)` |
+| `ValueError: Private key required for sending transactions` | SDK, before any transaction | `.send(ctx)` on a `Web3Context` without a key | `Web3Context(w3, chain_id, signer=..., private_key=...)` or `Web3Context.from_url(url, private_key=...)` |
 
 `clone()` grants the owner only `Roles.OWNER_ROLE` (1). OWNER grants `Roles.ATOMIST_ROLE` (100), which administers `Roles.FUSE_MANAGER_ROLE` (300, configuration), `Roles.ALPHA_ROLE` (200, `execute`) and `Roles.WHITELIST_ROLE` (800, `deposit` on a private vault).
 
@@ -398,10 +401,10 @@ The SDK uses a **fuse adapter pattern**:
 - **Fuses** encode protocol-specific calls into `FuseAction` objects (pure calldata, no state)
 - **PlasmaVault** batches and executes `FuseAction` sequences on-chain via `execute()`; a batch is atomic
 - **Web3Context** manages provider connections, signing, and transaction dispatch
-- **Call** is the lazy result of every wrapper method: `.call()`, `.send()`, `.calldata`, or feed it to `VaultSimulator`
+- **Call** is the lazy result of every wrapper method: `.call(ctx)`, `.send(ctx)`, `.calldata`, or feed it to `VaultSimulator`
 
 ```
-Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call  -->  .send() / simulate
+Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call  -->  .send(ctx) / simulate
 ```
 
 ### Core modules (`ipor_fusion.core`)
@@ -409,7 +412,7 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | Module | Purpose |
 |--------|---------|
 | `Web3Context` | Provider connection, signing, tx dispatch, gas estimation |
-| `Call` | Pre-encoded contract call; `.call()`, `.send()`, `.calldata`, `.build_transaction()` |
+| `Call` | Pre-encoded contract call; `.call(ctx)`, `.send(ctx)`, `.calldata`, `.build_transaction(ctx)` |
 | `PlasmaVault` | ERC-4626 vault — execute, deposit, withdraw, fuse and market configuration |
 | `VaultSimulator` | Batch `execute` + reads through `eth_simulateV1`, multi-block, no local node |
 | `FusionFactory` | Deploy a new vault (`clone`, `clone_supervised`) |

{ipor_fusion-4.0.0.dev88 → ipor_fusion-4.0.0.dev103}/README.md

@@ -93,8 +93,8 @@ ctx = Web3Context.from_url(
     private_key="0x...",
 )
 
-# 2. Wrap the PlasmaVault contract
-vault = PlasmaVault(ctx, Web3.to_checksum_address("0xVAULT_ADDRESS"))
+# 2. Wrap the PlasmaVault contract (an address only; contexts are passed at execution)
+vault = PlasmaVault(Web3.to_checksum_address("0xVAULT_ADDRESS"))
 
 # 3. Build a fuse action (e.g. supply USDC to Aave V3)
 fuse = AaveV3SupplyFuse(Web3.to_checksum_address("0xFUSE_ADDRESS"))
@@ -103,25 +103,28 @@ action = fuse.supply(
     amount=1_000_000,  # 1 USDC (6 decimals)
 )
 
-# 4. Execute on-chain (execute() returns a Call; .send() signs and submits it)
-receipt = vault.execute([action]).send()
+# 4. Execute on-chain (execute() returns a Call; .send(ctx) signs and submits it)
+receipt = vault.execute([action]).send(ctx)
 ```
 
 Fuse, factory and manager addresses per chain are published in
 [ipor-abi](https://github.com/IPOR-Labs/ipor-abi) (`mainnet/mainnet-<chain>-fusion/addresses.json`).
-A fuse must also be registered on the vault; `vault.get_fuses().call()` lists the registered ones.
+A fuse must also be registered on the vault; `vault.get_fuses().call(ctx)` lists the registered ones.
 
 Amounts are raw on-chain integers (`Amount`, `Shares` in `ipor_fusion.types`); the SDK never scales by decimals.
 
 ### Read, send, or simulate
 
-Every wrapper method returns a `Call` instead of executing. The same `Call` powers all three modes:
+Every wrapper method returns a `Call` instead of executing. Wrappers and `Call`s hold no
+`Web3Context`: the context is a required argument wherever something runs, and methods that
+must read the chain to answer are named `read_*` and take it first
+(`vault.read_balance_fuses(ctx)`). The same `Call` powers all three modes:
 
 ```python
 from ipor_fusion import VaultSimulator
 
-total = vault.total_assets().call()          # eth_call -> Amount
-receipt = vault.execute([action]).send()     # signed tx -> TxReceipt
+total = vault.total_assets().call(ctx)          # eth_call -> Amount
+receipt = vault.execute([action]).send(ctx)     # signed tx -> TxReceipt
 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()
@@ -264,7 +267,7 @@ Reverts on the deploy-and-configure path, keyed by selector so a failed transact
 | `0x9996b315` | `AddressEmptyCode(address)` | `execute()` touched a market with no balance fuse | `add_balance_fuse(market_id, balance_fuse)` before the first `execute` on that market |
 | `0x4bf4de4e` | `HandlerNotFound()` | A protocol called back into the vault during `execute()` (a flash loan) and no handler is registered for its address and selector | `update_callback_handler(handler, sender, selector)` before the first `execute` that triggers the callback |
 | `0x068ca9d8` | `AccessManagedUnauthorized(address)` | The caller lacks the role the function requires: `FUSE_MANAGER` for `add_fuses`, `grant_market_substrates`, `add_balance_fuse`, `update_callback_handler`; `ALPHA` for `execute`; `WHITELIST` for `deposit` and `mint` on a private vault | `AccessManager.grant_role(role, account, 0)` from the role's admin (`OWNER` grants `ATOMIST`, `ATOMIST` grants the rest); for a reverting `deposit`, whitelist the depositor or convert the vault to public |
-| `ValueError: Private key required for sending transactions` | SDK, before any transaction | `.send()` on a `Web3Context` without a key | `Web3Context(w3, chain_id, signer=..., private_key=...)` or `Web3Context.from_url(url, private_key=...)` |
+| `ValueError: Private key required for sending transactions` | SDK, before any transaction | `.send(ctx)` on a `Web3Context` without a key | `Web3Context(w3, chain_id, signer=..., private_key=...)` or `Web3Context.from_url(url, private_key=...)` |
 
 `clone()` grants the owner only `Roles.OWNER_ROLE` (1). OWNER grants `Roles.ATOMIST_ROLE` (100), which administers `Roles.FUSE_MANAGER_ROLE` (300, configuration), `Roles.ALPHA_ROLE` (200, `execute`) and `Roles.WHITELIST_ROLE` (800, `deposit` on a private vault).
 
@@ -350,10 +353,10 @@ The SDK uses a **fuse adapter pattern**:
 - **Fuses** encode protocol-specific calls into `FuseAction` objects (pure calldata, no state)
 - **PlasmaVault** batches and executes `FuseAction` sequences on-chain via `execute()`; a batch is atomic
 - **Web3Context** manages provider connections, signing, and transaction dispatch
-- **Call** is the lazy result of every wrapper method: `.call()`, `.send()`, `.calldata`, or feed it to `VaultSimulator`
+- **Call** is the lazy result of every wrapper method: `.call(ctx)`, `.send(ctx)`, `.calldata`, or feed it to `VaultSimulator`
 
 ```
-Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call  -->  .send() / simulate
+Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call  -->  .send(ctx) / simulate
 ```
 
 ### Core modules (`ipor_fusion.core`)
@@ -361,7 +364,7 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | Module | Purpose |
 |--------|---------|
 | `Web3Context` | Provider connection, signing, tx dispatch, gas estimation |
-| `Call` | Pre-encoded contract call; `.call()`, `.send()`, `.calldata`, `.build_transaction()` |
+| `Call` | Pre-encoded contract call; `.call(ctx)`, `.send(ctx)`, `.calldata`, `.build_transaction(ctx)` |
 | `PlasmaVault` | ERC-4626 vault — execute, deposit, withdraw, fuse and market configuration |
 | `VaultSimulator` | Batch `execute` + reads through `eth_simulateV1`, multi-block, no local node |
 | `FusionFactory` | Deploy a new vault (`clone`, `clone_supervised`) |

{ipor_fusion-4.0.0.dev88 → ipor_fusion-4.0.0.dev103}/examples/CONTRIBUTING.md

@@ -35,7 +35,7 @@ own examples.
 The default (and only) behavior is preview plus `eth_simulateV1` simulation. An example must not
 sign or broadcast a transaction, and must not require a private key to run.
 
-- Show the read-only path with `.call()`, the unsigned-payload path with `.calldata`, and simulate
+- Show the read-only path with `.call(ctx)`, the unsigned-payload path with `.calldata`, and simulate
   the whole flow with `VaultSimulator`.
 - For "how to actually submit this on-chain", point the reader at their signer via `.calldata`, and
   at the deployment/operation repos -- do not add a runnable broadcast path.

{ipor_fusion-4.0.0.dev88 → ipor_fusion-4.0.0.dev103}/examples/README.md

@@ -104,7 +104,7 @@ default run also logs the unsigned `clone(...)` creation calldata.
 
 These examples only simulate; they never broadcast. To submit a flow on-chain, take
 the `.calldata` each builder produces and sign it with your own signer -- a multisig,
-hardware wallet, or key-management service. (`Call.send()` performs a direct send from a
+hardware wallet, or key-management service. (`Call.send(ctx)` performs a direct send from a
 configured signer, but a production deployment should not sign with a hot key.) Always
 review production configuration independently before using it with real funds.
 

{ipor_fusion-4.0.0.dev88 → ipor_fusion-4.0.0.dev103}/examples/advanced_euler_v2_credit_market_base.py

@@ -6,7 +6,7 @@ collateralized borrow. It shows, end to end and without reading the test suite,
 how to:
 
   1. connect a ``Web3Context`` to Base;
-  2. preview a vault deployment with ``FusionFactory.clone(...).call()`` and read
+  2. preview a vault deployment with ``FusionFactory.clone(...).call(ctx)`` and read
      its state-dependent CREATE addresses for the atomic simulation, plus the
      unsigned creation ``.calldata``;
   3. bootstrap the vault's roles in the correct order;
@@ -222,7 +222,7 @@ def _euler_account(plasma_vault: ChecksumAddress) -> ChecksumAddress:
 
 
 def _evault_debt_of(
-    ctx: Web3Context, euler_vault: ChecksumAddress, account: ChecksumAddress
+    euler_vault: ChecksumAddress, account: ChecksumAddress
 ) -> Call[int]:
     """Read an Euler eVault's outstanding debt for an account (underlying units).
 
@@ -234,7 +234,7 @@ def _evault_debt_of(
     data = function_signature_to_4byte_selector("debtOf(address)") + encode(
         ["address"], [account]
     )
-    return Call(to=euler_vault, data=data, output_types=["uint256"], ctx=ctx)
+    return Call(to=euler_vault, data=data, output_types=["uint256"])
 
 
 # ── Pure builders (no chain access -- safe to import and unit-test offline) ───
@@ -261,12 +261,12 @@ def clone_args() -> dict:
 def unsigned_clone_calldata() -> bytes:
     """Unsigned creation calldata (selector + ABI-encoded args) for the deploy.
 
-    Built on a wrapper with ctx=None, so it needs no provider. Hand these bytes to
-    an external signer / multisig instead of calling ``.send()``. NOTE: the owner
+    Built from an address-only wrapper, so it needs no provider. Hand these bytes to
+    an external signer / multisig instead of calling ``.send(ctx)``. NOTE: the owner
     encoded here is the simulation ``OWNER`` (a throwaway EOA) -- set your real
     owner in ``clone_args()`` before deploying, or the vault is owned by it.
     """
-    return FusionFactory(None, BASE_FUSION_FACTORY).clone(**clone_args()).calldata
+    return FusionFactory(BASE_FUSION_FACTORY).clone(**clone_args()).calldata
 
 
 def market_substrates() -> list[bytes]:
@@ -369,10 +369,10 @@ 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
-    factory = FusionFactory(ctx, BASE_FUSION_FACTORY)
+    factory = FusionFactory(BASE_FUSION_FACTORY)
 
     # 1. Preview the deterministic addresses (eth_call, no gas, no state change).
-    preview = factory.clone(**clone_args()).call()
+    preview = factory.clone(**clone_args()).call(ctx)
     log.info(
         "predicted vault=%s access_manager=%s price_manager=%s (index=%d)",
         preview.plasma_vault,
@@ -383,19 +383,19 @@ def run_simulation(web3: Web3) -> SimulationResult:
     # 2. The unsigned creation calldata (external-signer path).
     log.info("unsigned clone calldata: 0x%s", unsigned_clone_calldata().hex())
 
-    plasma_vault = PlasmaVault(ctx, preview.plasma_vault)
-    access_manager = AccessManager(ctx, preview.access_manager)
-    price_manager = PriceOracleMiddlewareManager(ctx, preview.price_manager)
-    cbeth = ERC20(ctx, BASE_CBETH)
+    plasma_vault = PlasmaVault(preview.plasma_vault)
+    access_manager = AccessManager(preview.access_manager)
+    price_manager = PriceOracleMiddlewareManager(preview.price_manager)
+    cbeth = ERC20(BASE_CBETH)
     euler_account = _euler_account(preview.plasma_vault)
 
     # The whole flow runs as ONE eth_simulateV1 batch; nothing here is signed or
     # broadcast (see the module docstring). Each simulator primitive stands in for
     # a production action, read as "simulation -> production":
-    #   - sim.add_call(call=X, from_=OWNER) -> X.send() by the owner/atomist
+    #   - 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() by the alpha.
-    #   - sim.observe("key", X) -> X.call(), a plain read.
+    #   - sim.execute([action]) -> plasma_vault.execute([action]).send(ctx) by the alpha.
+    #   - sim.observe("key", X) -> X.call(ctx), a plain read.
     sim = VaultSimulator(
         web3=web3, vault=preview.plasma_vault, alpha=ALPHA, block=PINNED_BLOCK
     )
@@ -499,7 +499,7 @@ 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(ctx, EVAULT_WETH, euler_account))
+    sim.observe("debt_after_borrow", _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
@@ -512,7 +512,7 @@ def run_simulation(web3: Web3) -> SimulationResult:
     # 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(ctx, EVAULT_WETH, euler_account))
+    sim.observe("debt_after_repay", _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