ipor-fusion 4.0.0.dev54__tar.gz → 4.0.0.dev60__tar.gz

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/AGENTS.md

@@ -184,7 +184,10 @@ the lifecycle matrix follows that.
   balance-graph checks
 - `vault_data.py` — public vault read: `fetch_vault_data` → `VaultData` (with `FeeData`,
   `WithdrawManagerData`), `fetch_deployment_info`, cached `resolve_token_symbol` /
-  `resolve_token_decimals`; `vault_info.py` — `build_vault_info_json`, the
+  `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`),
   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/`).
@@ -283,6 +286,14 @@ or examples.
   local node.
 - Amounts are raw on-chain integers; `types.py` `NewType`s (`Amount`, `Shares`,
   `MarketId`, ...) name the unit, and nothing scales by decimals.
+- Three address roles are nominal: `PlasmaVaultAddress`, `FuseAddress` and
+  `AccessManagerAddress` (NewTypes of `ChecksumAddress`). Their wrappers, getters and
+  records return them, so a vault, a fuse and an access manager cannot be passed for
+  each other; `parse_*_address` brands raw input. Generic plumbing (`ContractWrapper`,
+  `Call`, `Multicall3`, logs, storage, simulation overrides, ERC20 and account
+  inputs, event emitters) and recognition boundaries (`resolve_access_manager`'s
+  input) stay `ChecksumAddress`; external vaults (ERC4626, Euler, MetaMorpho) are not
+  `PlasmaVaultAddress`.
 - Ids and addresses are nominal in every signature: `ChainId`, `MarketId` (each
   `IporFusionMarkets` member is one), `RoleId | Roles`, `ChecksumAddress`;
   `HexAddress` only for the lowercase addresses decoded from substrates;

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/MIGRATION_4.md

@@ -32,6 +32,7 @@ widths or address spelling.
 | `HexAddress` | any `ChecksumAddress`, or `parse_hex_address(value)` (20 bytes or hex in any spelling → lowercase `0x` form) |
 | `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 hex in any spelling) |
+| `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) |
 | 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)` |
@@ -45,37 +46,62 @@ a `bytes32` return (recall) request is `ReturnRequestId`.
 ## What changed, by area
 
 **Vault reads and validation.** `fetch_vault_data(chain_id=)`, `fetch_deployment_info`,
-`build_vault_info_json`, `ensure_supported_chain`, `fetch_vault_lending_health` take
-`ChainId`; vault and oracle addresses
-(`validate_vault`, `fetch_deployment_info`, `build_vault_info_json`,
-`fetch_unpriceable_priced_tokens`) take `ChecksumAddress`; `resolve_token_symbol`,
-`resolve_token_decimals`, `get_contract_name`, `get_deployment_tx` take `HexAddress`
-(a checksum address fits). The `resolve_name` / `resolve_symbol` callbacks receive a
-`HexAddress` (a callback typed for `str` still fits). Market-keyed data is keyed by
-`MarketId`: `VaultData.market_substrates`, `dependency_graph`, `fuse_markets`,
-`morpho_positions`, `aave_positions`; the `VaultState` protocol, `validate_vault_state`
+`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 and labels the document with
+`plasma_vault.address`. `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`
 and the `dependency_graph` helpers (`compute_update_reach`, `compute_update_groups`,
 `find_orphan_fuse_markets`, `find_markets_missing_erc20_dependency`).
-A custom `VaultState` implementation also annotates `asset` as `ChecksumAddress` and
-its `unpriceable_priced_tokens` items' `market_id` as `MarketId`
-(`UnpriceableToken`), and `price_oracle_addr` / `fuse_markets` keys as
-`ChecksumAddress`. `VaultData.asset`, `access_manager`, `price_oracle_addr`,
-`rewards_manager`, `withdraw_manager`, `fuses` and `instant_fuses` (and the
-`fuse_markets` keys), `FeeData.fee_manager` / `ipor_dao_fee_recipient`, and
-`VaultValidation.vault` / `asset` are `ChecksumAddress`; `VaultData.balance_fuses`
-is `list[BalanceFuse]` and `token_prices_usd` is keyed by `HexAddress` (lowercase);
-the Uniswap V3 / Ramses V2 position events' `version`, `sender` and `recipient` are
-`ChecksumAddress`;
-`VaultValidation.chain_id` is `ChainId`; `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).
+
+`VaultData.asset`, `price_oracle_addr`, `rewards_manager`, `withdraw_manager`,
+`FeeData.fee_manager` / `ipor_dao_fee_recipient` and `VaultValidation.vault` /
+`asset` are `ChecksumAddress` (`VaultValidation.vault` a `PlasmaVaultAddress`);
+`VaultData.access_manager` is an `AccessManagerAddress`, `fuses` / `instant_fuses`
+and the `fuse_markets` keys are `FuseAddress`, `balance_fuses` is
+`list[BalanceFuse]`, and `token_prices_usd` is keyed by lowercase `HexAddress`. A
+custom `VaultState` implementation annotates `asset` and `price_oracle_addr` as
+`ChecksumAddress`, `fuse_markets` keys as `FuseAddress`, and its
+`unpriceable_priced_tokens` items' `market_id` as `MarketId` (`UnpriceableToken`).
+The Uniswap V3 / Ramses V2 position events' `version`, `sender` and `recipient` are
+`ChecksumAddress`. `VaultValidation.chain_id` is `ChainId`;
+`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`.
 `get_logs_adaptive(chain_id=)` and `LogSource.get_logs` take `ChainId`;
 `quote_ccip_native_fee(block=)` and `OracleMappingReader.asset_source_events` take a
 `BlockIdentifier`.
 
+**Address roles.** `PlasmaVault(ctx, address)`, `PlasmaVault.encoder(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
+(`ExecutorInitParams.manager`, `create_executor(manager=)`, `executors_of(manager=)`),
+the async command helpers `Command.request_shares` / `redeem_from_request`,
+`pending_request_shares` and `WithdrawManager.update_plasma_vault_address` take a
+`PlasmaVaultAddress`; `.address`, `FusionInstance.plasma_vault` and the executor's
+`manager()` return one. Crosschain deposit and redeem destinations stay
+`ChecksumAddress`: `Command.deposit` / `redeem`, `is_allowed_vault`,
+`is_tracked_vault` and the remote-vault substrate accept any allowlisted ERC4626.
+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
+`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`;
+`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.
+
 **Markets and substrates.** Every `IporFusionMarkets` member is a `MarketId`.
 `decode_substrate`, `market_name`, `format_market_label` take `MarketId`.
 

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/PKG-INFO

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

@@ -59,6 +59,7 @@ from ipor_fusion import (
     VaultSimulator,
     Web3Context,
     is_simulate_v1_supported,
+    parse_fuse_address,
 )
 from ipor_fusion.core import FusionFactory
 from ipor_fusion.core.contract import Call
@@ -92,24 +93,22 @@ BASE_FUSION_FACTORY = Web3.to_checksum_address(
 # The four Euler V2 *functional* fuses (registry names quoted). Each is a
 # stateless encoder for one EVC operation; the balance fuse below is what values
 # the resulting position for NAV.
-EULER_SUPPLY_FUSE = Web3.to_checksum_address(  # "SupplyFuseEulerV2"
+EULER_SUPPLY_FUSE = parse_fuse_address(  # "SupplyFuseEulerV2"
     "0x598326fcEDE2C1B8E9023a20C18FFf6Dea5306A4"
 )
-EULER_COLLATERAL_FUSE = Web3.to_checksum_address(  # "CollateralFuseEulerV2"
+EULER_COLLATERAL_FUSE = parse_fuse_address(  # "CollateralFuseEulerV2"
     "0x12c479f8aB53D4884fc76F803dD24eb8B6D17a94"
 )
-EULER_CONTROLLER_FUSE = Web3.to_checksum_address(  # "ControllerFuseEulerV2"
+EULER_CONTROLLER_FUSE = parse_fuse_address(  # "ControllerFuseEulerV2"
     "0x108c8cFB9e00681FfA1fa3b654937E8b3BCd2E64"
 )
-EULER_BORROW_FUSE = Web3.to_checksum_address(  # "BorrowFuseEulerV2"
+EULER_BORROW_FUSE = parse_fuse_address(  # "BorrowFuseEulerV2"
     "0x906496F0D4C733275F892b1a6fC92eD56639B379"
 )
 # The Euler V2 *balance* fuse (registry name "BalanceFuseEulerV2") -- distinct
 # from the functional fuses; this is what lets total_assets_in_market(EULER_MARKET)
 # value the collateral net of debt.
-EULER_BALANCE_FUSE = Web3.to_checksum_address(
-    "0xF8A6AA09bB55f2319113b0DA88883F392e66A5fa"
-)
+EULER_BALANCE_FUSE = parse_fuse_address("0xF8A6AA09bB55f2319113b0DA88883F392e66A5fa")
 
 # Euler V2 eVaults on Base: the collateral eVault (cbETH) and the debt eVault
 # (WETH). These are Euler protocol (EVK) deployments, NOT IPOR Fusion addresses,

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/examples/advanced_euler_v2_looping_arbitrum.py

@@ -44,6 +44,7 @@ from ipor_fusion import (
     VaultSimulator,
     Web3Context,
     is_simulate_v1_supported,
+    parse_fuse_address,
 )
 from ipor_fusion.core import FusionFactory
 from ipor_fusion.core.contract import Call
@@ -77,31 +78,21 @@ MORPHO_FLASH_MARKET = MarketId(IporFusionMarkets.MORPHO_FLASH_LOAN)
 ARBITRUM_FUSION_FACTORY = Web3.to_checksum_address(
     "0x134fCAce7a2C7Ef3dF2479B62f03ddabAEa922d5"
 )
-EULER_SUPPLY_FUSE = Web3.to_checksum_address(
-    "0x920f6c81666877490A8D6dcFEFd85d151Ef04B7d"
-)
-EULER_COLLATERAL_FUSE = Web3.to_checksum_address(
-    "0x6D35934cB431B36338fF88641BEBF540e826bd7D"
-)
-EULER_CONTROLLER_FUSE = Web3.to_checksum_address(
-    "0x2A02Ae392816441E804aa9eCcf5c0333911Dc989"
-)
-EULER_BORROW_FUSE = Web3.to_checksum_address(
-    "0x10eb9B247e7Ce00F3290F66d8B5E83BfD311375F"
-)
-EULER_BALANCE_FUSE = Web3.to_checksum_address(
-    "0xF7dF7b8eB5B0c6d02b1b8FEC769dFE65D9a27E3b"
-)
-MORPHO_FLASH_LOAN_FUSE = Web3.to_checksum_address(
+EULER_SUPPLY_FUSE = parse_fuse_address("0x920f6c81666877490A8D6dcFEFd85d151Ef04B7d")
+EULER_COLLATERAL_FUSE = parse_fuse_address("0x6D35934cB431B36338fF88641BEBF540e826bd7D")
+EULER_CONTROLLER_FUSE = parse_fuse_address("0x2A02Ae392816441E804aa9eCcf5c0333911Dc989")
+EULER_BORROW_FUSE = parse_fuse_address("0x10eb9B247e7Ce00F3290F66d8B5E83BfD311375F")
+EULER_BALANCE_FUSE = parse_fuse_address("0xF7dF7b8eB5B0c6d02b1b8FEC769dFE65D9a27E3b")
+MORPHO_FLASH_LOAN_FUSE = parse_fuse_address(
     "0xeA36D6478CAAE9a5CDbEA0814bDe98533320d742"
 )
-MORPHO_FLASH_BALANCE_FUSE = Web3.to_checksum_address(
+MORPHO_FLASH_BALANCE_FUSE = parse_fuse_address(
     "0xAD5EdaEc3cd9a25C8Cc42284dDeF57dCFF40341d"
 )
-UNIVERSAL_SWAPPER_FUSE_V2 = Web3.to_checksum_address(
+UNIVERSAL_SWAPPER_FUSE_V2 = parse_fuse_address(
     "0x799b979A2377268ac2D5E43247cbd6F797229Ef3"
 )
-UNIVERSAL_SWAPPER_BALANCE_FUSE_V2 = Web3.to_checksum_address(
+UNIVERSAL_SWAPPER_BALANCE_FUSE_V2 = parse_fuse_address(
     "0x69199E8360b3Baa536Cda2bd71dFFb30F79fBeF7"
 )
 MORPHO_CALLBACK_HANDLER = Web3.to_checksum_address(

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/examples/composed_hypercore_flow_arbitrum_hyperevm.py

@@ -87,6 +87,8 @@ from ipor_fusion import (
     decode_substrate,
     erc20_balance_slot,
     open_lane,
+    parse_fuse_address,
+    parse_plasma_vault_address,
     quote_ccip_native_fee,
     read_hypercore_evm_exit_ceiling,
     read_hypercore_vault_state,
@@ -148,13 +150,15 @@ HYPEREVM_USDC = Web3.to_checksum_address("0xb88339CB7199b77E23DB6E890353E22632Ba
 # The composed test deployment the live cycles drove (created by the IPOR SDK
 # team against the v3 CCIP crosschain factory pair). Not in the ipor-abi
 # registry; verify with ``discover_deployment`` on the hub vault.
-HUB_VAULT = Web3.to_checksum_address("0x8BeED16DB1f354B0BFa31eF7e747102e26eb8FbF")
+HUB_VAULT = parse_plasma_vault_address("0x8BeED16DB1f354B0BFa31eF7e747102e26eb8FbF")
 # The executor on Arbitrum and the dispatcher on HyperEVM: one CREATE3 address.
 EXECUTOR = Web3.to_checksum_address("0xcb83A78BD8e8c284d5704B62945EF2C454266dB0")
 # The remote vault: a HyperCore vault (market 55) on HyperEVM, and the Core
 # account the trade runs in.
-HYPERCORE_VAULT = Web3.to_checksum_address("0xB8De01Ca5ca57A14671E1c696337134a02B4A478")
-HYPERCORE_BALANCE_FUSE = Web3.to_checksum_address(
+HYPERCORE_VAULT = parse_plasma_vault_address(
+    "0xB8De01Ca5ca57A14671E1c696337134a02B4A478"
+)
+HYPERCORE_BALANCE_FUSE = parse_fuse_address(
     "0xaC7404Ec2Bc3F2d3c0853633e0c3edfA25DC50F9"
 )
 HYPERCORE_MARKET = IporFusionMarkets.HYPERCORE
@@ -398,13 +402,13 @@ def core_leg_previews(web3_hype: Web3) -> list[Preview]:
     # 2. The fuses the vault registered for market 55, read from the vault.
     fuses = {Web3.to_checksum_address(f) for f in vault.get_fuses().call()}
     deposit_fuse = HyperCoreDepositFuse(
-        Web3.to_checksum_address("0xDbE31Da504ac89B618664bB02e1521c335a41E73")
+        parse_fuse_address("0xDbE31Da504ac89B618664bB02e1521c335a41E73")
     )
     send_fuse = HyperCoreSendFuse(
-        Web3.to_checksum_address("0x984D84183008C52d9A645C3ba4863F0A29b4785A")
+        parse_fuse_address("0x984D84183008C52d9A645C3ba4863F0A29b4785A")
     )
     order_fuse = HyperCoreOrderFuse(
-        Web3.to_checksum_address("0x8Dc849FC55D9195cc987CA4ddFF5eA022651c173")
+        parse_fuse_address("0x8Dc849FC55D9195cc987CA4ddFF5eA022651c173")
     )
     for fuse in (deposit_fuse, send_fuse, order_fuse):
         _check(

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/examples/crosschain_ccip_usdc_arbitrum_hyperevm.py

@@ -81,6 +81,7 @@ from ipor_fusion import (
     erc20_balance_slot,
     is_simulate_v1_supported,
     open_lane,
+    parse_plasma_vault_address,
 )
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.types import Amount, ChainId, MarketId, Period, Shares
@@ -114,10 +115,10 @@ HYPEREVM_USDC = Web3.to_checksum_address("0xb88339CB7199b77E23DB6E890353E22632Ba
 # live as a regression fixture (the SDK's own tests pin the same addresses). Verify
 # them yourself with ``discover_deployment(hub_ctx, HUB_VAULT, CROSSCHAIN_MARKET)``,
 # which reads the executor, its fuses and its spoke from the vault's grants.
-HUB_VAULT = Web3.to_checksum_address("0x8BeED16DB1f354B0BFa31eF7e747102e26eb8FbF")
+HUB_VAULT = parse_plasma_vault_address("0x8BeED16DB1f354B0BFa31eF7e747102e26eb8FbF")
 # The executor on Arbitrum and the dispatcher on HyperEVM: one CREATE3 address.
 EXECUTOR = Web3.to_checksum_address("0xcb83A78BD8e8c284d5704B62945EF2C454266dB0")
-SPOKE_VAULT = Web3.to_checksum_address("0xA342eBA00bD725799828A34EA55D25a55958f643")
+SPOKE_VAULT = parse_plasma_vault_address("0xA342eBA00bD725799828A34EA55D25a55958f643")
 # ``IporFusionMarkets.CROSSCHAIN``: the market the four crosschain fuses are
 # registered under on the hub vault.
 CROSSCHAIN_MARKET = MarketId(int(IporFusionMarkets.CROSSCHAIN))

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/examples/external_state_margin_leg_base.py

@@ -90,6 +90,7 @@ from ipor_fusion import (
     Web3Context,
     WithdrawManager,
     is_simulate_v1_supported,
+    parse_fuse_address,
 )
 from ipor_fusion.core import FusionFactory
 from ipor_fusion.core.fusion_factory import FusionInstance
@@ -124,12 +125,12 @@ EXTERNAL_STATE_MARKET = MarketId(IporFusionMarkets.EXTERNAL_STATE)
 
 # External-state *operation* fuse (enter/exit) -- the functional fuse. It also
 # lazily deploys the per-vault ExternalStateExecutor on the first enter.
-BASE_EXTERNAL_STATE_OPERATION_FUSE = Web3.to_checksum_address(
+BASE_EXTERNAL_STATE_OPERATION_FUSE = parse_fuse_address(
     "0x01f05736B79C7abcFbeeCe76B1C27e54f7A07D03"
 )
 # External-state *balance* fuse -- distinct from the operation fuse; this is what
 # lets total_assets_in_market(EXTERNAL_STATE_MARKET) value the attested figure.
-BASE_EXTERNAL_STATE_BALANCE_FUSE = Web3.to_checksum_address(
+BASE_EXTERNAL_STATE_BALANCE_FUSE = parse_fuse_address(
     "0xCDEb32ACF766587b5Eac9dbfB875145ec05E3517"
 )
 

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/examples/simple_aave_v3_supply_base.py

@@ -48,6 +48,7 @@ from ipor_fusion import (
     VaultSimulator,
     Web3Context,
     is_simulate_v1_supported,
+    parse_fuse_address,
 )
 from ipor_fusion.core import FusionFactory
 from ipor_fusion.fuses import AaveV3SupplyFuse
@@ -78,13 +79,13 @@ AAVE_MARKET = MarketId(IporFusionMarkets.AAVE_V3)
 
 # Aave V3 *supply* fuse (registry name SupplyFuseAaveV3) -- the functional fuse
 # that encodes supply/withdraw.
-BASE_AAVE_V3_SUPPLY_FUSE = Web3.to_checksum_address(
+BASE_AAVE_V3_SUPPLY_FUSE = parse_fuse_address(
     "0x26fD6EF391E98C78CfCA27e00c3d15be4D941625"
 )
 # Aave V3 *balance* fuse (registry name AaveV3WithPriceOracleMiddlewareBalanceFuse)
 # -- distinct from the supply fuse; this is what lets
 # total_assets_in_market(AAVE_MARKET) value the position.
-BASE_AAVE_V3_BALANCE_FUSE = Web3.to_checksum_address(
+BASE_AAVE_V3_BALANCE_FUSE = parse_fuse_address(
     "0x952573Ec1B6895a88a95CA523097083d4da4D8e5"
 )
 

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/pyproject.toml

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

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/src/ipor_fusion/__init__.py

@@ -310,6 +310,7 @@ from ipor_fusion.substrates import (
 )
 from ipor_fusion.types import (
     MAX_UINT256,
+    AccessManagerAddress,
     Amount,
     AssetId,
     AssetSource,
@@ -318,6 +319,7 @@ from ipor_fusion.types import (
     Decimals,
     DeploymentRequestId,
     Fee,
+    FuseAddress,
     HyperCoreActionId,
     HyperCoreAsset,
     HyperCoreClientOrderId,
@@ -333,6 +335,7 @@ from ipor_fusion.types import (
     OperationId,
     PayloadHash,
     Period,
+    PlasmaVaultAddress,
     PositionSetHash,
     Price,
     ProposalHash,
@@ -345,8 +348,11 @@ from ipor_fusion.types import (
     TokenId,
     TransferId,
     TxHash,
+    parse_access_manager_address,
+    parse_fuse_address,
     parse_hex_address,
     parse_morpho_market_id,
+    parse_plasma_vault_address,
     parse_tx_hash,
 )
 from ipor_fusion.validation import (
@@ -626,7 +632,13 @@ __all__ = [
     "PayloadHash",
     "ProposalHash",
     "TxHash",
+    "PlasmaVaultAddress",
+    "FuseAddress",
+    "AccessManagerAddress",
+    "parse_access_manager_address",
+    "parse_fuse_address",
     "parse_hex_address",
+    "parse_plasma_vault_address",
     "parse_morpho_market_id",
     "parse_tx_hash",
     "AssetId",

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/src/ipor_fusion/cli/options.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import click
-from eth_typing import ChecksumAddress
 from web3 import Web3
 
 from ipor_fusion.chains import CHAIN_NAME_TO_ID, ensure_supported_chain
@@ -12,7 +11,7 @@ from ipor_fusion.core.context import Web3Context
 from ipor_fusion.errors import (
     UnsupportedChainError,
 )
-from ipor_fusion.types import ChainId
+from ipor_fusion.types import ChainId, PlasmaVaultAddress
 
 
 class AddressType(click.ParamType):
@@ -48,6 +47,17 @@ class AddressType(click.ParamType):
 ADDRESS = AddressType()
 
 
+class VaultAddressType(AddressType):
+    """An address the command treats as a Plasma Vault; the command's probe
+    (`resolve_access_manager`) is what checks it on chain."""
+
+    def convert(self, value, param, ctx) -> PlasmaVaultAddress:  # type: ignore[override]
+        return PlasmaVaultAddress(super().convert(value, param, ctx))
+
+
+VAULT_ADDRESS = VaultAddressType()
+
+
 class ChainType(click.ParamType):
     """Accepts chain ID as int or chain name (ethereum, base, arbitrum, ...)."""
 
@@ -75,7 +85,7 @@ CHAIN = ChainType()
 
 
 def _resolve_chain_id(
-    cfg: FusionConfig, vault_address: ChecksumAddress, chain_id: ChainId | None
+    cfg: FusionConfig, vault_address: PlasmaVaultAddress, chain_id: ChainId | None
 ) -> ChainId:
     if chain_id is not None:
         return chain_id
@@ -100,7 +110,7 @@ def _resolve_provider(cfg: FusionConfig, chain_id: ChainId) -> str:
 
 def _build_ctx(
     cfg: FusionConfig,
-    vault_address: ChecksumAddress,
+    vault_address: PlasmaVaultAddress,
     chain_id: ChainId | None,
     block_number: int | None,
 ) -> tuple[ChainId, Web3Context]:

{ipor_fusion-4.0.0.dev54 → ipor_fusion-4.0.0.dev60}/src/ipor_fusion/cli/vault_cmd.py

@@ -6,7 +6,6 @@ from functools import partial
 from typing import Any
 
 import click
-from eth_typing import ChecksumAddress
 from web3 import Web3
 
 from ipor_fusion.chains import CHAIN_NAMES
@@ -16,7 +15,7 @@ from ipor_fusion.cli.config_store import (
     load_config,
     save_config,
 )
-from ipor_fusion.cli.options import ADDRESS, CHAIN, _build_ctx, _resolve_provider
+from ipor_fusion.cli.options import CHAIN, VAULT_ADDRESS, _build_ctx, _resolve_provider
 from ipor_fusion.cli.oracle_mapping_view import _print_oracle_mapping
 from ipor_fusion.cli.vault_health import (
     _print_validation,
@@ -43,7 +42,7 @@ from ipor_fusion.errors import (
 from ipor_fusion.readers.oracle_mapping import (
     build_oracle_mapping,
 )
-from ipor_fusion.types import ChainId
+from ipor_fusion.types import ChainId, PlasmaVaultAddress
 from ipor_fusion.validation import (
     VaultValidation,
     validate_vault,
@@ -63,7 +62,7 @@ from ipor_fusion.vault_info import (
 
 def _auto_save_vault(
     cfg: FusionConfig,
-    vault_address: ChecksumAddress,
+    vault_address: PlasmaVaultAddress,
     chain_id: ChainId,
     plasma_vault: PlasmaVault,
 ) -> None:
@@ -85,7 +84,7 @@ def vault() -> None:
 
 
 @vault.command("add")
-@click.argument("address", type=ADDRESS)
+@click.argument("address", type=VAULT_ADDRESS)
 @click.option(
     "--label", default=None, help="Label (default: fetched from on-chain name())."
 )
@@ -95,7 +94,9 @@ def vault() -> None:
     default=None,
     help="Chain ID or name (auto-detected when only one provider is configured).",
 )
-def add(address: ChecksumAddress, label: str | None, chain_id: ChainId | None) -> None:
+def add(
+    address: PlasmaVaultAddress, label: str | None, chain_id: ChainId | None
+) -> None:
     """Save a vault to the config."""
     cfg = load_config()
 
@@ -111,7 +112,7 @@ def add(address: ChecksumAddress, label: str | None, chain_id: ChainId | None) -
     if label is None:
         provider_url = _resolve_provider(cfg, chain_id)
         ctx = Web3Context.from_url(provider_url)
-        checksum = Web3.to_checksum_address(address)
+        checksum = address
         try:
             label = PlasmaVault(ctx, checksum).name().call()
         except Exception:
@@ -130,8 +131,8 @@ def add(address: ChecksumAddress, label: str | None, chain_id: ChainId | None) -
 
 
 @vault.command("remove")
-@click.argument("address", type=ADDRESS)
-def remove(address: ChecksumAddress) -> None:
+@click.argument("address", type=VAULT_ADDRESS)
+def remove(address: PlasmaVaultAddress) -> None:
     """Remove a saved vault."""
     cfg = load_config()
     before = len(cfg.vaults)
@@ -180,7 +181,7 @@ vault.add_command(list_vaults, "ls")
 
 
 @vault.command("info")
-@click.argument("vault_address", type=ADDRESS)
+@click.argument("vault_address", type=VAULT_ADDRESS)
 @click.option(
     "--chain-id", type=CHAIN, default=None, help="Chain ID or name (e.g. 1, ethereum)."
 )
@@ -194,7 +195,7 @@ vault.add_command(list_vaults, "ls")
     "--json", "json_output", is_flag=True, default=False, help="Output as JSON."
 )
 def info(
-    vault_address: ChecksumAddress,
+    vault_address: PlasmaVaultAddress,
     chain_id: ChainId | None,
     block_number: int | None,
     json_output: bool,
@@ -206,7 +207,7 @@ def info(
     """
     cfg = load_config()
     chain_id, ctx = _build_ctx(cfg, vault_address, chain_id, block_number)
-    checksum_address = Web3.to_checksum_address(vault_address)
+    checksum_address = vault_address
 
     # Cheap single-call probe: friendly errors for "nothing deployed here" and
     # "not a Plasma Vault" (revert and empty-return flavors alike) before the
@@ -230,7 +231,7 @@ def info(
 
 
 @vault.command("validate")
-@click.argument("vault_address", type=ADDRESS)
+@click.argument("vault_address", type=VAULT_ADDRESS)
 @click.option(
     "--chain-id", type=CHAIN, default=None, help="Chain ID or name (e.g. 1, ethereum)."
 )
@@ -244,7 +245,7 @@ def info(
     "--json", "json_output", is_flag=True, default=False, help="Output as JSON."
 )
 def validate(
-    vault_address: ChecksumAddress,
+    vault_address: PlasmaVaultAddress,
     chain_id: ChainId | None,
     block_number: int | None,
     json_output: bool,
@@ -316,7 +317,7 @@ def _validation_json(validation: VaultValidation, chain_label: str) -> dict[str,
 
 
 @vault.command("role-accounts")
-@click.argument("vault_address", type=ADDRESS)
+@click.argument("vault_address", type=VAULT_ADDRESS)
 @click.option(
     "--role",
     default="",
@@ -336,7 +337,7 @@ def _validation_json(validation: VaultValidation, chain_label: str) -> dict[str,
     "--json", "json_output", is_flag=True, default=False, help="Output as JSON."
 )
 def role_accounts(
-    vault_address: ChecksumAddress,
+    vault_address: PlasmaVaultAddress,
     role: str,
     chain_id: ChainId | None,
     block_number: int | None,
@@ -385,7 +386,7 @@ def role_accounts(
 
 
 @vault.command("oracle-mapping")
-@click.argument("vault_address", type=ADDRESS)
+@click.argument("vault_address", type=VAULT_ADDRESS)
 @click.option(
     "--chain-id", type=CHAIN, default=None, help="Chain ID or name (e.g. 1, ethereum)."
 )
@@ -406,7 +407,7 @@ def role_accounts(
     "--json", "json_output", is_flag=True, default=False, help="Output as JSON."
 )
 def oracle_mapping(
-    vault_address: ChecksumAddress,
+    vault_address: PlasmaVaultAddress,
     chain_id: ChainId | None,
     block_number: int | None,
     max_depth: int,
@@ -458,9 +459,7 @@ def oracle_mapping(
         raise click.UsageError(str(exc)) from exc
 
     try:
-        mapping = build_oracle_mapping(
-            ctx, Web3.to_checksum_address(vault_address), effective_block, max_depth
-        )
+        mapping = build_oracle_mapping(ctx, vault_address, effective_block, max_depth)
     except UnsupportedVaultVersionError as exc:
         raise click.ClickException(str(exc)) from exc