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

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev308}/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.dev308}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev295
+Version: 4.0.0.dev308
 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 |
@@ -455,7 +476,7 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | `PlasmaVault` | ERC-4626 vault — execute, deposit, withdraw, previews, fuse, market, fee and limit configuration |
 | `VaultSimulator` | Batch `execute` + reads through `eth_simulateV1`, multi-block, no local node |
 | `FusionFactory` | Deploy a new vault (`clone`, `clone_supervised`) |
-| `AccessManager` | Role-based access control |
+| `AccessManager` | Role-based access control; `read_call_plan(ctx, call, caller=)` says whether a restricted call goes now, must be scheduled (execution delay), waits, is ready or is forbidden, and gives the call to send now; `schedule`, `execute` and `cancel` build the timelock calls |
 | `RewardsManager` | Claim and vest rewards |
 | `WithdrawManager` | Time-windowed withdrawal requests |
 | `FeeManager` | Deposit, performance, and management fee configuration and harvesting |

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev308}/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 |
@@ -406,7 +427,7 @@ Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call
 | `PlasmaVault` | ERC-4626 vault — execute, deposit, withdraw, previews, fuse, market, fee and limit configuration |
 | `VaultSimulator` | Batch `execute` + reads through `eth_simulateV1`, multi-block, no local node |
 | `FusionFactory` | Deploy a new vault (`clone`, `clone_supervised`) |
-| `AccessManager` | Role-based access control |
+| `AccessManager` | Role-based access control; `read_call_plan(ctx, call, caller=)` says whether a restricted call goes now, must be scheduled (execution delay), waits, is ready or is forbidden, and gives the call to send now; `schedule`, `execute` and `cancel` build the timelock calls |
 | `RewardsManager` | Claim and vest rewards |
 | `WithdrawManager` | Time-windowed withdrawal requests |
 | `FeeManager` | Deposit, performance, and management fee configuration and harvesting |

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

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev295"
+version = "4.0.0.dev308"
 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.dev308}/src/ipor_fusion/__init__.py

@@ -27,6 +27,8 @@ from ipor_fusion.config.roles import Roles
 from ipor_fusion.core.access import (
     AccessManager,
     CallPermission,
+    CallPlan,
+    CallPlanKind,
     RoleAccount,
     RoleAccountJson,
     RoleAccountsJson,
@@ -53,6 +55,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 +122,7 @@ from ipor_fusion.errors import (
     ContractNotFoundError,
     CrosschainDiscoveryError,
     EmptyCallResultError,
+    ExecutePreflightError,
     ExternalStateError,
     ExternalStateEventDecodeError,
     HyperCoreEventDecodeError,
@@ -256,6 +265,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 +375,7 @@ from ipor_fusion.types import (
     Price,
     ProposalHash,
     RoleId,
+    ScheduleId,
     Severity,
     Shares,
     Tick,
@@ -478,6 +502,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",
@@ -517,6 +558,8 @@ __all__ = [
     "RoleAccount",
     "RoleAccountJson",
     "CallPermission",
+    "CallPlan",
+    "CallPlanKind",
     "RoleStatus",
     "resolve_access_manager",
     "role_account_sort_key",
@@ -657,6 +700,7 @@ __all__ = [
     "Liquidity",
     "RoleId",
     "ChainId",
+    "ScheduleId",
     "Wad",
     "MorphoBlueMarketId",
     "ProposalHash",

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev308}/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.dev308/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.dev308}/src/ipor_fusion/core/__init__.py

@@ -1,6 +1,8 @@
 from ipor_fusion.core.access import (
     AccessManager,
     CallPermission,
+    CallPlan,
+    CallPlanKind,
     RoleAccount,
     RoleAccountJson,
     RoleAccountsJson,
@@ -36,6 +38,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 +95,10 @@ from ipor_fusion.core.withdraw_manager import (
 __all__ = [
     "Web3Context",
     "InFlightLimit",
+    "DecodedFuseAction",
+    "decode_execute_calldata",
+    "decode_fuse_action",
+    "fuse_classes_for",
     "ContextManager",
     "Multicall3",
     "Multicall3Batch",
@@ -97,6 +109,8 @@ __all__ = [
     "RoleAccount",
     "RoleAccountJson",
     "CallPermission",
+    "CallPlan",
+    "CallPlanKind",
     "RoleStatus",
     "RewardsManager",
     "VestingData",

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

@@ -1,8 +1,8 @@
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
-from typing import TypedDict
+from typing import Literal, 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,
 )
 
 
@@ -67,6 +68,33 @@ class CallPermission:
         return self.immediate or self.delay > 0
 
 
+# schedule(when=0): as soon as the sender's execution delay allows.
+_ASAP = Timestamp(0)
+
+CallPlanKind = Literal["immediate", "schedule", "waiting", "ready", "forbidden"]
+
+
+@dataclass(frozen=True, slots=True)
+class CallPlan:
+    """How ``caller`` gets a restricted call through the access manager now.
+
+    - ``immediate``: send the call itself (``next_call``).
+    - ``schedule``: the caller has an execution delay and nothing is scheduled;
+      ``next_call`` schedules it, executable ``delay`` seconds after it lands.
+    - ``waiting``: scheduled, executable at ``scheduled_at``; nothing to send yet.
+    - ``ready``: scheduled and executable; ``next_call`` is the call itself (or
+      the manager's ``execute`` with ``via_manager``), valid until the schedule
+      expires a week after ``scheduled_at``; an expired one plans ``schedule``.
+    - ``forbidden``: the caller has no role for it, or the target is closed.
+    """
+
+    kind: CallPlanKind
+    permission: CallPermission
+    operation: ScheduleId
+    scheduled_at: Timestamp | None
+    next_call: Call[None] | None
+
+
 def _call_permission_decoder(values: tuple[bool, int]) -> CallPermission:
     immediate, delay = values
     return CallPermission(immediate=immediate, delay=Period(delay))
@@ -183,6 +211,102 @@ 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 schedule(
+        self, target: ChecksumAddress, data: bytes, when: Timestamp = _ASAP
+    ) -> Call[None]:
+        """Schedule ``data`` on ``target`` for the sender, executable at ``when``;
+        0 means as soon as the sender's execution delay allows, and a nonzero
+        time before that reverts."""
+        return self._write("schedule(address,bytes,uint48)", target, data, when)
+
+    def execute(self, target: ChecksumAddress, data: bytes) -> Call[None]:
+        """Run ``data`` on ``target`` through the manager: an immediate call, or
+        the sender's scheduled operation once it is executable (it is consumed)."""
+        return self._write("execute(address,bytes)", target, data)
+
+    def cancel(
+        self, caller: ChecksumAddress, target: ChecksumAddress, data: bytes
+    ) -> Call[None]:
+        """Cancel ``caller``'s scheduled ``data`` on ``target``: the caller itself,
+        an ADMIN_ROLE member, or the guardian of the role ``target`` maps the
+        function's selector to may."""
+        return self._write("cancel(address,address,bytes)", caller, target, data)
+
+    def read_call_plan(
+        self,
+        ctx: Web3Context,
+        call: Call[object],
+        *,
+        caller: ChecksumAddress,
+        via_manager: bool = False,
+    ) -> CallPlan:
+        """What ``caller`` sends now to get ``call`` executed: an access and
+        timelock plan from ``canCall`` and, for a delayed caller, the schedule of
+        exactly ``call``'s calldata, all read at the block ``ctx.default_block``
+        names (a number, hash or tag, resolved once). It does not run the target's own checks
+        (redemption lock, pre-hooks, balances): simulate the call for those.
+
+        A ready operation is sent as ``call`` itself, from ``caller``: the target
+        consumes the schedule and still sees ``caller`` as the sender, which
+        deposits, withdrawals and other sender-dependent calls need.
+        ``via_manager`` sends it through the manager's ``execute`` instead, for a
+        target that does not consume schedules; the manager is then the sender.
+
+        Raises ``ValueError`` for a call on the access manager itself: its
+        authorization is function-specific (role grants depend on the role's
+        admin, target configuration on the target's admin delay, and the IPOR
+        manager's own restricted functions on ``canCall``), which this plan does
+        not model.
+        """
+        if call.to == self.address:
+            raise ValueError(
+                "read_call_plan does not plan calls on the access manager itself:"
+                " their authorization is function-specific"
+            )
+        block = ctx.web3.eth.get_block(ctx.default_block)
+        ctx = ctx.at_block(block["number"])
+        selector = bytes(call.data[:4])
+        permission = self.can_call(caller, call.to, selector).call(ctx)
+        operation = self.hash_operation(caller, call.to, call.data)
+        direct = Call[None](to=call.to, data=call.data)
+        if permission.immediate:
+            return CallPlan("immediate", permission, operation, None, direct)
+        if permission.delay == 0:
+            return CallPlan("forbidden", permission, operation, None, None)
+        scheduled_at = self.get_schedule(operation).call(ctx)
+        if scheduled_at == 0:
+            return CallPlan(
+                "schedule",
+                permission,
+                operation,
+                None,
+                self.schedule(call.to, call.data),
+            )
+        if scheduled_at > block["timestamp"]:
+            return CallPlan("waiting", permission, operation, scheduled_at, None)
+        ready = self.execute(call.to, call.data) if via_manager else direct
+        return CallPlan("ready", permission, operation, scheduled_at, ready)
+
     def can_call(
         self, caller: ChecksumAddress, target: ChecksumAddress, selector: bytes
     ) -> Call[CallPermission]:

{ipor_fusion-4.0.0.dev295 → ipor_fusion-4.0.0.dev308}/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