ipor-fusion 4.0.0.dev295__tar.gz → 4.0.0.dev303__tar.gz

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/AGENTS.md

@@ -207,7 +207,7 @@ the lifecycle matrix follows that.
   subpackages do not list them). Their exceptions stay in `errors` and the top
   level. `ipor_fusion.guide` keeps its own namespace. The
   public modules (`about`, `cache`, `chains`, `dependency_graph`, `errors`, `explorer`,
-  `field_docs`, `market_ids`, `market_info`, `morpho_api`, `registry`, `substrates`, `types`,
+  `field_docs`, `market_ids`, `market_info`, `morpho_api`, `preflight`, `registry`, `substrates`, `types`,
   `validation`, `vault_data`, `vault_info`) stay importable for the names they
   define and the moved names README lists; `cli`, `mcp`, every other module and
   every submodule of a public subpackage (`core.contract`, `fuses.base`, ...) are
@@ -268,6 +268,9 @@ the lifecycle matrix follows that.
   `ctx.cache` (`Web3Context(cache=...)`, default `default_contract_cache()` under
   `$XDG_CACHE_HOME/ipor-fusion/`) or `get_contract_name(cache=...)`. Never cache an
   absence (no code, no answer): it can change at a later block.
+  `preflight.py` — `preflight_execute`: an execute batch checked as its sender would
+  send it (canCall, registered fuses, MARKET_ID, balance fuses, one eth_simulateV1
+  run), `ExecutePreflight` and the `fusion vault preflight` document;
   `registry.py` the ipor-abi address registry (`fetch_address_registry` →
   `AddressRegistry`, one raw-GitHub file per chain in `REGISTRY_CHAIN_IDS`, cached ten
   minutes in the process, for good at a commit ref) and the `fusion address` documents;
@@ -295,7 +298,9 @@ the lifecycle matrix follows that.
   of the node's response), `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
+  substrate packers), `fuse_decoding` (`decode_execute_calldata`, `decode_fuse_action`,
+  `fuse_classes_for`: an action back to the function its class encoded, from each
+  class's `SIGNATURES`), `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,
   erc4626, euler_v2, external_state, fluid_instadapp, gearbox_v3, merkl, morpho, ramses_v2,
@@ -459,7 +464,10 @@ or examples.
   `ipor-abi` `addresses.json`; a fuse must be registered on the vault
   (`PlasmaVault.get_fuses()`) and its market granted substrates before an
   action can succeed.
-- Adding a protocol: new module in `fuses/`, re-export from `fuses/__init__.py`
+- Adding a protocol: new module in `fuses/` whose classes list every Solidity
+  function they encode in `SIGNATURES` (`tests/conftest.py` fails any call an
+  encoder builds under test that its class does not declare; it cannot catch an
+  extra or never-exercised entry), re-export from `fuses/__init__.py`
   and the top-level `__all__` (and both snapshots in `test_public_api.py`),
   encoding test in `test_fuse_encoding.py`, and a row in the README protocol
   table.
@@ -497,7 +505,7 @@ byte, e.g. Ebisu ZAPPER/REGISTRY).
 `fusion address` (lookup, names, list; the ipor-abi registry through `registry.py`),
 `fusion config` (set-provider, set-etherscan-key, show), `fusion market`
 (morpho-blue, meta-morpho), `fusion vault` (add, remove, list, info, validate,
-role-accounts, oracle-mapping). `vault info` runs independent fetch pipelines
+role-accounts, oracle-mapping, preflight). `vault info` runs independent fetch pipelines
 (vault/asset, fees, WithdrawManager, markets, roles) concurrently on a
 `ThreadPoolExecutor`, each a short chain of `Multicall3` batches; keep new
 reads inside a batch rather than adding per-call round trips. A `from_url` context
@@ -510,7 +518,7 @@ keys); tests redirect it with `monkeypatch.setenv("XDG_CACHE_HOME", ...)` or
 inject a cache.
 
 Every CLI command has an MCP tool (`fusion changelog` maps to `server_info`;
-the rest share names). Read-only: `vault_info`, `vault_validate`,
+the rest share names). Read-only: `vault_info`, `vault_validate`, `vault_preflight`,
 `vault_list`, `vault_role_accounts`, `vault_oracle_mapping`, `market_morpho_blue`,
 `market_meta_morpho`, `address_lookup`, `address_names`, `address_list`,
 `config_show`, `server_info`. Mutating: `vault_add`,

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev295
+Version: 4.0.0.dev303
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -201,6 +201,23 @@ if result.all_success:
     print(after.value - before.value)
 ```
 
+Read a batch back from calldata, e.g. to review a multisig transaction:
+
+```python
+from ipor_fusion import AaveV3SupplyFuse, decode_execute_calldata, decode_fuse_action, fuse_classes_for
+
+# The class behind each fuse address you know (from the registry or your config);
+# fuse_classes_for(action) lists the candidates when you do not.
+known = {fuse.address: AaveV3SupplyFuse}
+for action in decode_execute_calldata(payload):  # execute / claimRewards calldata
+    cls = known.get(action.fuse)
+    if cls is None:
+        print(action.fuse, "one of", [c.__name__ for c in fuse_classes_for(action)])
+        continue
+    decoded = decode_fuse_action(action, cls)
+    print(decoded.label, decoded.args)  # AaveV3SupplyFuse.enter ((asset, amount, e_mode),)
+```
+
 ## CLI Quickstart
 
 The SDK ships with a `fusion` CLI for inspecting and managing Plasma Vaults from the terminal.
@@ -223,6 +240,9 @@ fusion vault validate 0xB8a451107A9f87FDe481D4D686247D6e43Ed715e --chain-id ethe
 # List saved vaults
 fusion vault list
 
+# Check an execute batch before signing it (role, fuses, balance fuses, simulation)
+fusion vault preflight 0xVAULT_ADDRESS --calldata 0xEXECUTE_CALLDATA --sender 0xALPHA
+
 # Inspect a Morpho Blue market or MetaMorpho vault
 fusion market morpho-blue 0xMARKET_ID --chain ethereum
 fusion market meta-morpho 0xVAULT_ADDRESS --chain ethereum
@@ -289,6 +309,7 @@ Available tools:
 | `config_set_etherscan_key` | Set Etherscan API key (enables contract name resolution) |
 | `vault_info` | Full on-chain vault state — assets, fuses, balances, fees, lending health, reconciliation |
 | `vault_validate` | Health verdict (ok / warning / critical) with the reconciliation, lending-health and ERC20 numbers behind it |
+| `vault_preflight` | Check execute calldata as its sender would send it: permission, fuses, balance fuses, simulation |
 | `vault_role_accounts` | Accounts holding each AccessManager role on a vault |
 | `vault_oracle_mapping` | Price-oracle sources per asset for a vault |
 | `vault_list` | List all saved vaults |

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/README.md

@@ -152,6 +152,23 @@ if result.all_success:
     print(after.value - before.value)
 ```
 
+Read a batch back from calldata, e.g. to review a multisig transaction:
+
+```python
+from ipor_fusion import AaveV3SupplyFuse, decode_execute_calldata, decode_fuse_action, fuse_classes_for
+
+# The class behind each fuse address you know (from the registry or your config);
+# fuse_classes_for(action) lists the candidates when you do not.
+known = {fuse.address: AaveV3SupplyFuse}
+for action in decode_execute_calldata(payload):  # execute / claimRewards calldata
+    cls = known.get(action.fuse)
+    if cls is None:
+        print(action.fuse, "one of", [c.__name__ for c in fuse_classes_for(action)])
+        continue
+    decoded = decode_fuse_action(action, cls)
+    print(decoded.label, decoded.args)  # AaveV3SupplyFuse.enter ((asset, amount, e_mode),)
+```
+
 ## CLI Quickstart
 
 The SDK ships with a `fusion` CLI for inspecting and managing Plasma Vaults from the terminal.
@@ -174,6 +191,9 @@ fusion vault validate 0xB8a451107A9f87FDe481D4D686247D6e43Ed715e --chain-id ethe
 # List saved vaults
 fusion vault list
 
+# Check an execute batch before signing it (role, fuses, balance fuses, simulation)
+fusion vault preflight 0xVAULT_ADDRESS --calldata 0xEXECUTE_CALLDATA --sender 0xALPHA
+
 # Inspect a Morpho Blue market or MetaMorpho vault
 fusion market morpho-blue 0xMARKET_ID --chain ethereum
 fusion market meta-morpho 0xVAULT_ADDRESS --chain ethereum
@@ -240,6 +260,7 @@ Available tools:
 | `config_set_etherscan_key` | Set Etherscan API key (enables contract name resolution) |
 | `vault_info` | Full on-chain vault state — assets, fuses, balances, fees, lending health, reconciliation |
 | `vault_validate` | Health verdict (ok / warning / critical) with the reconciliation, lending-health and ERC20 numbers behind it |
+| `vault_preflight` | Check execute calldata as its sender would send it: permission, fuses, balance fuses, simulation |
 | `vault_role_accounts` | Accounts holding each AccessManager role on a vault |
 | `vault_oracle_mapping` | Price-oracle sources per asset for a vault |
 | `vault_list` | List all saved vaults |

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/pyproject.toml

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

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/__init__.py

@@ -53,6 +53,12 @@ from ipor_fusion.core.fee_manager import (
     HighWaterMarkPerformanceFee,
     RecipientFee,
 )
+from ipor_fusion.core.fuse_decoding import (
+    DecodedFuseAction,
+    decode_execute_calldata,
+    decode_fuse_action,
+    fuse_classes_for,
+)
 from ipor_fusion.core.fusion_factory import CloneArgs, FusionFactory, FusionInstance
 from ipor_fusion.core.logs import (
     LogSource,
@@ -114,6 +120,7 @@ from ipor_fusion.errors import (
     ContractNotFoundError,
     CrosschainDiscoveryError,
     EmptyCallResultError,
+    ExecutePreflightError,
     ExternalStateError,
     ExternalStateEventDecodeError,
     HyperCoreEventDecodeError,
@@ -256,6 +263,20 @@ from ipor_fusion.morpho_api import (
     fetch_market,
     fetch_vault,
 )
+from ipor_fusion.preflight import (
+    ExecutePreflight,
+    ExecutePreflightJson,
+    PreflightAction,
+    PreflightActionJson,
+    PreflightCheck,
+    PreflightFinding,
+    PreflightFindingJson,
+    PreflightSimulation,
+    PreflightSimulationJson,
+    build_execute_preflight_json,
+    parse_execute_actions,
+    preflight_execute,
+)
 from ipor_fusion.readers import (
     HYPEREVM_CHAIN_ID,
     AaveV3FuseReader,
@@ -352,6 +373,7 @@ from ipor_fusion.types import (
     Price,
     ProposalHash,
     RoleId,
+    ScheduleId,
     Severity,
     Shares,
     Tick,
@@ -478,6 +500,23 @@ __all__ = [
     "repository_url",
     "Web3Context",
     "InFlightLimit",
+    "ExecutePreflightError",
+    "ExecutePreflight",
+    "ExecutePreflightJson",
+    "PreflightAction",
+    "PreflightActionJson",
+    "PreflightCheck",
+    "PreflightFinding",
+    "PreflightFindingJson",
+    "PreflightSimulation",
+    "PreflightSimulationJson",
+    "build_execute_preflight_json",
+    "parse_execute_actions",
+    "preflight_execute",
+    "DecodedFuseAction",
+    "decode_execute_calldata",
+    "decode_fuse_action",
+    "fuse_classes_for",
     "AddressNotInRegistryError",
     "AddressRegistryError",
     "REGISTRY_CHAIN_IDS",
@@ -657,6 +696,7 @@ __all__ = [
     "Liquidity",
     "RoleId",
     "ChainId",
+    "ScheduleId",
     "Wad",
     "MorphoBlueMarketId",
     "ProposalHash",

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/cli/main.py

@@ -9,6 +9,7 @@ from ipor_fusion.cli.address_cmd import address
 from ipor_fusion.cli.changelog_cmd import changelog
 from ipor_fusion.cli.config_cmd import config
 from ipor_fusion.cli.market_cmd import market
+from ipor_fusion.cli.preflight_cmd import preflight
 from ipor_fusion.cli.vault_cmd import vault
 
 
@@ -35,6 +36,7 @@ cli.add_command(changelog)
 cli.add_command(config)
 cli.add_command(market)
 cli.add_command(vault)
+vault.add_command(preflight)
 
 
 def main() -> None:

ipor_fusion-4.0.0.dev303/src/ipor_fusion/cli/preflight_cmd.py

@@ -0,0 +1,128 @@
+"""`fusion vault preflight`: check an execute batch before sending it."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from eth_typing import ChecksumAddress
+
+from ipor_fusion.cli.config_store import load_config
+from ipor_fusion.cli.options import (
+    ADDRESS,
+    BLOCK_NUMBER,
+    CHAIN,
+    VAULT_ADDRESS,
+    _build_ctx,
+)
+from ipor_fusion.cli.vault_rendering import _print_table
+from ipor_fusion.preflight import (
+    ExecutePreflight,
+    build_execute_preflight_json,
+    parse_execute_actions,
+    preflight_execute,
+)
+from ipor_fusion.types import ChainId, PlasmaVaultAddress
+
+
+def _read_calldata(calldata: str) -> str:
+    if calldata.startswith("@"):
+        try:
+            return Path(calldata[1:]).read_text()
+        except OSError as exc:
+            raise click.BadParameter(str(exc), param_hint="--calldata") from exc
+    return calldata
+
+
+@click.command("preflight")
+@click.argument("vault_address", type=VAULT_ADDRESS)
+@click.option(
+    "--calldata",
+    required=True,
+    help="execute((address,bytes)[]) calldata as hex, or @file holding it.",
+)
+@click.option(
+    "--sender",
+    type=ADDRESS,
+    required=True,
+    help="The account that will send execute (an ALPHA).",
+)
+@click.option(
+    "--chain-id", type=CHAIN, default=None, help="Chain ID or name (e.g. 1, ethereum)."
+)
+@click.option(
+    "--block-number", type=BLOCK_NUMBER, default=None, help="Block (default: latest)."
+)
+@click.option(
+    "--simulate/--no-simulate",
+    default=True,
+    help="Run the batch through eth_simulateV1 (default) or only the static checks.",
+)
+@click.option(
+    "--json", "json_output", is_flag=True, default=False, help="Output as JSON."
+)
+def preflight(
+    vault_address: PlasmaVaultAddress,
+    calldata: str,
+    sender: ChecksumAddress,
+    chain_id: ChainId | None,
+    block_number: int | None,
+    simulate: bool,
+    json_output: bool,
+) -> None:
+    """Check an execute batch as SENDER would send it: role, fuse registration,
+    balance fuses, and a simulation of the exact calldata. Read-only. Exits with
+    status 1 when a check is critical."""
+    try:
+        actions = parse_execute_actions(_read_calldata(calldata))
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="--calldata") from exc
+    if not actions:
+        raise click.BadParameter("the batch has no actions", param_hint="--calldata")
+    _, ctx = _build_ctx(load_config(), vault_address, chain_id, block_number)
+    result = preflight_execute(
+        ctx, vault_address, actions, sender=sender, simulate=simulate
+    )
+    if json_output:
+        click.echo(json.dumps(build_execute_preflight_json(result), indent=2))
+    else:
+        _print_preflight(result)
+    if result.verdict == "critical":
+        sys.exit(1)
+
+
+def _print_preflight(result: ExecutePreflight) -> None:
+    click.echo(f"Vault:   {result.vault}")
+    click.echo(f"Block:   {result.block_number}")
+    click.echo(f"Sender:  {result.sender}")
+    click.echo(f"Verdict: {result.verdict}")
+    click.echo("\nActions")
+    _print_table(
+        ("#", "Fuse", "Registered", "Market", "Encoder"),
+        [
+            (
+                str(a.index),
+                a.fuse,
+                "yes" if a.registered else "NO",
+                "?" if a.market_id is None else str(a.market_id),
+                ", ".join(a.candidates) or "unknown",
+            )
+            for a in result.actions
+        ],
+    )
+    click.echo("\nFindings")
+    _print_table(
+        ("Severity", "Check", "Message"),
+        [(f.severity, f.check, f.message) for f in result.findings],
+    )
+    if result.simulation is not None:
+        sim = result.simulation
+        click.echo("\nSimulation")
+        click.echo(f"  success: {sim.success}  gas: {sim.gas_used}")
+        click.echo(
+            f"  totalAssets: {sim.total_assets_before} -> {sim.total_assets_after}"
+        )
+        if sim.revert_reason:
+            click.echo(f"  revert: {sim.revert_reason}")

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/core/__init__.py

@@ -36,6 +36,12 @@ from ipor_fusion.core.fuse import (
 from ipor_fusion.core.fuse_action import (
     FuseAction,
 )
+from ipor_fusion.core.fuse_decoding import (
+    DecodedFuseAction,
+    decode_execute_calldata,
+    decode_fuse_action,
+    fuse_classes_for,
+)
 from ipor_fusion.core.fusion_factory import CloneArgs, FusionFactory, FusionInstance
 from ipor_fusion.core.logs import (
     LogSource,
@@ -87,6 +93,10 @@ from ipor_fusion.core.withdraw_manager import (
 __all__ = [
     "Web3Context",
     "InFlightLimit",
+    "DecodedFuseAction",
+    "decode_execute_calldata",
+    "decode_fuse_action",
+    "fuse_classes_for",
     "ContextManager",
     "Multicall3",
     "Multicall3Batch",

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/core/access.py

@@ -2,7 +2,7 @@ from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from typing import TypedDict
 
-from eth_abi import decode
+from eth_abi import decode, encode
 from eth_abi.exceptions import InsufficientDataBytes
 from eth_typing import ChecksumAddress
 from hexbytes import HexBytes
@@ -27,6 +27,7 @@ from ipor_fusion.types import (
     Period,
     PlasmaVaultAddress,
     RoleId,
+    ScheduleId,
 )
 
 
@@ -183,6 +184,26 @@ class AccessManager(ContractWrapper):
             decoder=_role_status_decoder,
         )
 
+    def get_schedule(self, operation: ScheduleId) -> Call[Timestamp]:
+        """When the scheduled ``operation`` becomes executable; 0 when it is not
+        scheduled, was executed or cancelled, or expired (a week after that time)."""
+        return self._view(
+            "getSchedule(bytes32)",
+            operation,
+            output_types=["uint48"],
+            decoder=Timestamp,
+        )
+
+    @staticmethod
+    def hash_operation(
+        caller: ChecksumAddress, target: ChecksumAddress, data: bytes
+    ) -> ScheduleId:
+        """The id `schedule` and `get_schedule` use for ``caller`` calling
+        ``target`` with ``data``, computed offline as the manager does."""
+        return ScheduleId(
+            Web3.keccak(encode(["address", "address", "bytes"], [caller, target, data]))
+        )
+
     def can_call(
         self, caller: ChecksumAddress, target: ChecksumAddress, selector: bytes
     ) -> Call[CallPermission]:

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/core/fuse.py

@@ -9,6 +9,7 @@ without importing that package, whose ``__init__`` loads every encoder.
 from abc import ABC
 from collections.abc import Sequence
 from types import MemberDescriptorType
+from typing import ClassVar
 
 from eth_abi import encode
 from eth_typing import ChecksumAddress
@@ -27,8 +28,15 @@ class Fuse(ABC):  # noqa: B024  # ABC marks intent; no shared abstract method
     same class and carry the same constructor state (the fuse address, plus e.g.
     a `StakeFuse`'s staking contract), so a subclass that stores more state is
     compared on it without overriding anything. That state must be hashable.
+
+    ``SIGNATURES`` lists the Solidity functions a class's own methods encode;
+    `signatures` adds the inherited ones. The decoder reads them to recognize an
+    action; the test suite fails any call an encoder builds under test that its
+    class does not declare.
     """
 
+    SIGNATURES: ClassVar[tuple[str, ...]] = ()
+
     def __init__(self, address: FuseAddress):
         _validate_not_zero_address(address, "fuse address")
         self._address = address
@@ -37,6 +45,15 @@ class Fuse(ABC):  # noqa: B024  # ABC marks intent; no shared abstract method
     def address(self) -> FuseAddress:
         return self._address
 
+    @classmethod
+    def signatures(cls) -> tuple[str, ...]:
+        """Every Solidity function this class encodes, inherited ones included."""
+        seen: dict[str, None] = {}
+        for klass in reversed(cls.__mro__):
+            for signature in vars(klass).get("SIGNATURES", ()):
+                seen[signature] = None
+        return tuple(seen)
+
     @staticmethod
     def _validate_amount(value: Amount, name: str) -> None:
         if value <= 0:
@@ -94,6 +111,11 @@ class Fuse(ABC):  # noqa: B024  # ABC marks intent; no shared abstract method
 class StakeFuse(Fuse):
     """Base fuse for stake/unstake operations on a staking contract."""
 
+    SIGNATURES = (
+        "enter((uint256,address))",
+        "exit((uint256,address))",
+    )
+
     def __init__(self, fuse_address: FuseAddress, staking_address: ChecksumAddress):
         super().__init__(fuse_address)
         self._staking_address = staking_address

ipor_fusion-4.0.0.dev303/src/ipor_fusion/core/fuse_decoding.py

@@ -0,0 +1,109 @@
+"""Decode `execute` / `claimRewards` calldata into `FuseAction`s, and a
+`FuseAction` into the function and arguments its fuse class encoded."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from eth_abi import decode
+from eth_abi.exceptions import DecodingError
+from eth_utils import function_signature_to_4byte_selector
+from web3 import Web3
+
+from ipor_fusion.core.contract import _parse_param_types
+from ipor_fusion.core.fuse import Fuse
+from ipor_fusion.core.fuse_action import FuseAction
+from ipor_fusion.types import FuseAddress
+
+_BATCH_SIGNATURES = (
+    "execute((address,bytes)[])",
+    "claimRewards((address,bytes)[])",
+)
+_BATCH_SELECTORS = {
+    function_signature_to_4byte_selector(sig): sig for sig in _BATCH_SIGNATURES
+}
+
+
+@dataclass(frozen=True)
+class DecodedFuseAction:
+    """A `FuseAction` read as one call of ``fuse_class``: the Solidity
+    ``signature`` it encodes and the ``args`` as eth_abi decodes them (tuples for
+    structs and arrays, lowercase address strings, ``bytes`` for byte values).
+    The class is the caller's reading; nothing checks the deployed contract."""
+
+    fuse: FuseAddress
+    fuse_class: type[Fuse]
+    signature: str
+    args: tuple[object, ...]
+
+    @property
+    def function(self) -> str:
+        return self.signature[: self.signature.index("(")]
+
+    @property
+    def label(self) -> str:
+        """``AaveV3SupplyFuse.enter`` style: the class and the function."""
+        return f"{self.fuse_class.__name__}.{self.function}"
+
+
+def decode_execute_calldata(data: bytes) -> list[FuseAction]:
+    """The actions of a `PlasmaVault.execute` or `RewardsManager.claim_rewards`
+    call's calldata; raises ``ValueError`` for any other function or for data
+    that does not decode."""
+    signature = _BATCH_SELECTORS.get(bytes(data[:4]))
+    if signature is None:
+        raise ValueError(
+            f"not execute or claimRewards calldata (selector 0x{bytes(data[:4]).hex()})"
+        )
+    try:
+        (actions,) = decode(["(address,bytes)[]"], bytes(data[4:]))
+    except DecodingError as exc:
+        raise ValueError(f"{signature} calldata does not decode: {exc}") from exc
+    return [
+        FuseAction(fuse=FuseAddress(Web3.to_checksum_address(fuse)), data=bytes(call))
+        for fuse, call in actions
+    ]
+
+
+def _loaded_fuse_classes() -> list[type[Fuse]]:
+    found: dict[type[Fuse], None] = {}
+    pending = list(Fuse.__subclasses__())
+    while pending:
+        cls = pending.pop()
+        if cls not in found:
+            found[cls] = None
+            pending += cls.__subclasses__()
+    return sorted(found, key=lambda c: (c.__module__, c.__qualname__))
+
+
+def _signature_for(selector: bytes, fuse_class: type[Fuse]) -> str | None:
+    for signature in fuse_class.signatures():
+        if function_signature_to_4byte_selector(signature) == selector:
+            return signature
+    return None
+
+
+def fuse_classes_for(action: FuseAction) -> list[type[Fuse]]:
+    """Every loaded fuse class whose encoders produce ``action``'s selector.
+    Several fuses share a shape (``enter((address,uint256))``), so this narrows
+    the candidates; the vault's fuse list or the registry name settles them."""
+    selector = bytes(action.data[:4])
+    return [cls for cls in _loaded_fuse_classes() if _signature_for(selector, cls)]
+
+
+def decode_fuse_action(action: FuseAction, fuse_class: type[Fuse]) -> DecodedFuseAction:
+    """``action`` as a call of ``fuse_class``; raises ``ValueError`` when the
+    class encodes no function with its selector or the arguments do not decode."""
+    selector = bytes(action.data[:4])
+    signature = _signature_for(selector, fuse_class)
+    if signature is None:
+        raise ValueError(
+            f"{fuse_class.__name__} encodes no function with selector 0x{selector.hex()}"
+        )
+    try:
+        args = decode(_parse_param_types(signature), bytes(action.data[4:]))
+    except DecodingError as exc:
+        raise ValueError(f"{signature} arguments do not decode: {exc}") from exc
+    return DecodedFuseAction(
+        fuse=action.fuse, fuse_class=fuse_class, signature=signature, args=tuple(args)
+    )

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/crosschain/fuses/base.py

@@ -238,6 +238,8 @@ class CrosschainClaimFuse(Fuse):
     """``CrosschainClaimFuse``: pull settled idle executor assets back into the
     vault. Transport-agnostic."""
 
+    SIGNATURES = ("enter((address,uint256))",)
+
     def enter(self, *, executor: ChecksumAddress, amount: Amount) -> FuseAction:
         """Claim up to ``amount`` (capped at the executor's idle ledger) of the
         executor's asset. The measured receipt is what the balance fuse removes

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/crosschain/fuses/ccip.py

@@ -72,6 +72,7 @@ class CcipCrosschainSupplyFuse(CrosschainSupplyFuse):
 
     _ENTER = "enter((address,address,uint256,uint256,uint256,address,uint256))"
     _EXIT = "exit((address,uint256,uint256,uint256,uint256,address,uint256))"
+    SIGNATURES = (_ENTER, _EXIT)
 
     def enter(
         self,
@@ -169,6 +170,7 @@ class CcipCrosschainCommandFuse(CrosschainCommandFuse):
         "enter((uint8,address,uint256,(uint64,address,address,uint96,uint96,uint256,bool),"
         f"address[],bool,bool,{COMMAND_TUPLE_TYPE},uint256,address,uint256))"
     )
+    SIGNATURES = (_ENTER,)
     _WITH_COMMAND = frozenset(
         {
             CcipCommandType.SEND_COMMAND,

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/crosschain/fuses/stargate.py

@@ -80,6 +80,7 @@ class StargateCrosschainSupplyFuse(CrosschainSupplyFuse):
 
     _ENTER = "enter((address,address,uint256,uint256,uint256,bytes))"
     _EXIT = "exit((address,uint256,uint256,uint256,uint128,bytes))"
+    SIGNATURES = (_ENTER, _EXIT)
 
     def enter(
         self,
@@ -157,6 +158,7 @@ class StargateCrosschainCommandFuse(CrosschainCommandFuse):
         "enter((uint8,address,uint256,uint32,bytes,address[],uint256,"
         f"{COMMAND_TUPLE_TYPE}))"
     )
+    SIGNATURES = (_ENTER,)
     _CHAIN_SCOPED = frozenset(
         {
             StargateCrosschainCommandType.REGISTER_CHAIN,

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/errors.py

@@ -293,6 +293,11 @@ class MorphoApiError(IporFusionError, RuntimeError):
     addresses or market ids). Also a RuntimeError, its base before 4.0."""
 
 
+class ExecutePreflightError(IporFusionError, RuntimeError):
+    """A preflight of a `PlasmaVault.execute` batch found a critical problem:
+    `ExecutePreflight.raise_for_failure` lists them."""
+
+
 class AddressRegistryError(IporFusionError, RuntimeError):
     """The ipor-abi address registry is unreachable or its file does not parse
     as a ``{name: address}`` map."""