ipor-fusion 4.0.0.dev93__tar.gz → 4.0.0.dev106__tar.gz

{ipor_fusion-4.0.0.dev93 → ipor_fusion-4.0.0.dev106}/AGENTS.md

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

{ipor_fusion-4.0.0.dev93 → ipor_fusion-4.0.0.dev106}/MIGRATION_4.md

@@ -80,7 +80,7 @@ chain is always the context's:
   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=None, *, block=None)`. `Web3Context.get_logs(to_block=None)` ends at
+  `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"``.
 
@@ -113,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
@@ -130,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.
@@ -167,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`,
@@ -214,41 +214,126 @@ 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
 hash now cover every attribute a fuse stores, not only its class and address (see
 [Behavior changes](#behavior-changes)).
 
+**Crosschain fuse encoders moved.** The crosschain market encoders moved from
+`ipor_fusion.fuses.crosschain` into the crosschain package, and
+`ipor_fusion.fuses` no longer re-exports them. There is no shim: the old paths
+raise `ImportError`. The top-level names (`from ipor_fusion import ...`) are
+unchanged.
+
+| 3.x import | 4.0 import |
+|---|---|
+| `ipor_fusion.fuses.crosschain` | `ipor_fusion.crosschain.fuses` (or `ipor_fusion.crosschain`) |
+| `ipor_fusion.fuses.crosschain.base` | `ipor_fusion.crosschain.fuses.base` |
+| `ipor_fusion.fuses.crosschain.ccip` | `ipor_fusion.crosschain.fuses.ccip` |
+| `ipor_fusion.fuses.crosschain.stargate` | `ipor_fusion.crosschain.fuses.stargate` |
+| `from ipor_fusion.fuses import CcipCrosschainSupplyFuse` (and the other crosschain encoders, `SendParams`, `CrosschainSubstrate*`, `crosschain_market_id`) | `from ipor_fusion.crosschain import ...` or `from ipor_fusion import ...` |
+
+`ipor_fusion.crosschain` now exports the whole crosschain surface: besides the
+codecs and wrappers, the encoders, `CrosschainLane`, `CcipLane`, `StargateLane`,
+the transports and chains, `discover_deployment`, `open_lane(s)`, `LANES` and
+`CrosschainSimulator`, which 3.x exported only from `ipor_fusion`.
+`ipor_fusion.crosschain.ccip` and `.stargate` keep exporting only their codecs
+and wrappers.
+
 **Moved, still importable.** `FuseAction` lives in `ipor_fusion.core.fuse_action` and
 `ZERO_ADDRESS` in `ipor_fusion.types`; both are re-exported from
 `ipor_fusion.fuses.base` and `FuseAction` from `ipor_fusion`. The CLI's internal
 `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
@@ -325,7 +410,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.dev93 → ipor_fusion-4.0.0.dev106}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev93
+Version: 4.0.0.dev106
 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).
 
@@ -374,8 +377,8 @@ renaming a name in it, or changing a signature incompatibly, waits for a major
 release; adding one does not.
 
 - **Public subpackages** declare their own `__all__`, each a subset of the top
-  level: `ipor_fusion.core`, `config`, `fuses`, `fuses.crosschain`, `readers`,
-  `crosschain`, `crosschain.ccip` and `crosschain.stargate`. `ipor_fusion.guide`
+  level: `ipor_fusion.core`, `config`, `fuses`, `readers`, `crosschain`,
+  `crosschain.fuses`, `crosschain.ccip` and `crosschain.stargate`. `ipor_fusion.guide`
   (the packaged docs) keeps its names in its own namespace.
 - **Public modules** stay importable for the top-level names they define:
   `about`, `chains`, `dependency_graph`, `errors`, `explorer`, `field_docs`,
@@ -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.dev93 → ipor_fusion-4.0.0.dev106}/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).
 
@@ -326,8 +329,8 @@ renaming a name in it, or changing a signature incompatibly, waits for a major
 release; adding one does not.
 
 - **Public subpackages** declare their own `__all__`, each a subset of the top
-  level: `ipor_fusion.core`, `config`, `fuses`, `fuses.crosschain`, `readers`,
-  `crosschain`, `crosschain.ccip` and `crosschain.stargate`. `ipor_fusion.guide`
+  level: `ipor_fusion.core`, `config`, `fuses`, `readers`, `crosschain`,
+  `crosschain.fuses`, `crosschain.ccip` and `crosschain.stargate`. `ipor_fusion.guide`
   (the packaged docs) keeps its names in its own namespace.
 - **Public modules** stay importable for the top-level names they define:
   `about`, `chains`, `dependency_graph`, `errors`, `explorer`, `field_docs`,
@@ -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.dev93 → ipor_fusion-4.0.0.dev106}/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.dev93 → ipor_fusion-4.0.0.dev106}/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.dev93 → ipor_fusion-4.0.0.dev106}/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