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

{ipor_fusion-4.0.0.dev293 → 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.dev293 → ipor_fusion-4.0.0.dev303}/MIGRATION_4.md

@@ -438,8 +438,12 @@ exist; the comparison is equality either way.
 - `ExternalStateVaultState.last_checked_custodian_timestamp` is
   `last_checked_custodian_marker` and `BalanceFuseSnapshot.last_custodian_update_timestamp`
   is `custodian_marker`, both a `CustodianMarker` (an opaque value the
-  contracts only compare for equality): a timestamp on an earlier executor, the
-  confirm count on a released one. `ExternalStateExecutor.confirm_count()`
+  contracts only compare for equality): a unix timestamp on an earlier
+  executor, a confirmation count on a released one.
+  `ExternalStateVaultState.custodian_marker_kind` (`CustodianMarkerKind`, read
+  from the executor at the snapshot block; `None` without an executor) and
+  `ExternalStateExecutor.read_custodian_marker_kind(ctx)` say which; never
+  compare a count with a clock. `ExternalStateExecutor.confirm_count()`
   exists only on the released executor (it reverts on an earlier one), and
   `last_custodian_update_timestamp()` reads the timestamp on both.
 - New on the released build: `ExternalStateExecutor.unforwarded_credit(asset)`,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev293
+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.dev293 → 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.dev293 → ipor_fusion-4.0.0.dev303}/pyproject.toml

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

@@ -42,6 +42,7 @@ from ipor_fusion.core.erc20 import ERC20
 from ipor_fusion.core.external_state_executor import (
     BalanceFuseSnapshot,
     BalanceProposal,
+    CustodianMarkerKind,
     ExternalStateExecutor,
     ExternalStateVaultState,
     read_external_state,
@@ -52,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,
@@ -113,6 +120,7 @@ from ipor_fusion.errors import (
     ContractNotFoundError,
     CrosschainDiscoveryError,
     EmptyCallResultError,
+    ExecutePreflightError,
     ExternalStateError,
     ExternalStateEventDecodeError,
     HyperCoreEventDecodeError,
@@ -255,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,
@@ -351,6 +373,7 @@ from ipor_fusion.types import (
     Price,
     ProposalHash,
     RoleId,
+    ScheduleId,
     Severity,
     Shares,
     Tick,
@@ -477,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",
@@ -545,6 +585,7 @@ __all__ = [
     "CloneArgs",
     "ExternalStateExecutor",
     "BalanceFuseSnapshot",
+    "CustodianMarkerKind",
     "ExternalStateVaultState",
     "read_external_state",
     "erc20_balance_slot",
@@ -655,6 +696,7 @@ __all__ = [
     "Liquidity",
     "RoleId",
     "ChainId",
+    "ScheduleId",
     "Wad",
     "MorphoBlueMarketId",
     "ProposalHash",

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

@@ -18,6 +18,7 @@ from ipor_fusion.core.erc20 import ERC20
 from ipor_fusion.core.external_state_executor import (
     BalanceFuseSnapshot,
     BalanceProposal,
+    CustodianMarkerKind,
     ExternalStateExecutor,
     ExternalStateVaultState,
     read_external_state,
@@ -35,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,
@@ -86,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",
@@ -122,6 +133,7 @@ __all__ = [
     "BalanceFuseSnapshot",
     "BalanceProposal",
     "ExternalStateExecutor",
+    "CustodianMarkerKind",
     "ExternalStateVaultState",
     "read_external_state",
     "Fuse",

{ipor_fusion-4.0.0.dev293 → 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.dev293 → ipor_fusion-4.0.0.dev303}/src/ipor_fusion/core/external_state_executor.py

@@ -18,13 +18,15 @@ from __future__ import annotations
 
 from collections.abc import Iterable
 from dataclasses import dataclass, replace
+from enum import Enum
 
 from eth_abi import decode, encode
 from eth_abi.exceptions import DecodingError
 from eth_typing import ChecksumAddress
-from eth_utils import keccak
+from eth_utils import function_signature_to_4byte_selector, keccak
 from hexbytes import HexBytes
 from web3 import Web3
+from web3.exceptions import ContractLogicError
 from web3.types import BlockIdentifier, Timestamp
 
 from ipor_fusion.core.context import Web3Context
@@ -118,6 +120,35 @@ def _require_matching_hash(
         )
 
 
+class CustodianMarkerKind(Enum):
+    """What an executor's custodian marker counts: the last confirmed update's
+    unix timestamp (executors before the 2026-10-21 contracts release) or the
+    number of confirmed updates (executors of that release)."""
+
+    TIMESTAMP = "timestamp"
+    CONFIRM_COUNT = "confirm_count"
+
+
+_CONFIRM_COUNT_SELECTOR = function_signature_to_4byte_selector("confirmCount()")
+
+
+def _read_marker_kind(
+    ctx: Web3Context, executor: ChecksumAddress, block: BlockIdentifier
+) -> CustodianMarkerKind:
+    """Decided from the executor, not guessed from a value: a released
+    executor answers ``confirmCount()``, an earlier one has no such function
+    and the call reverts. Any other failure raises."""
+    try:
+        raw = ctx.call(executor, _CONFIRM_COUNT_SELECTOR, block)
+    except ContractLogicError:
+        return CustodianMarkerKind.TIMESTAMP
+    if len(raw) != 32:
+        raise ExternalStateError(
+            f"confirmCount() of {executor} returned {len(raw)} bytes, not a uint256"
+        )
+    return CustodianMarkerKind.CONFIRM_COUNT
+
+
 @dataclass(frozen=True, slots=True)
 class ExternalStateVaultState:
     """The external-state market's vault-scoped state, read from the vault's
@@ -136,7 +167,9 @@ class ExternalStateVaultState:
     and not the pre-hook's staleness clock, which is
     `ExternalStateExecutor.get_oldest_update_timestamp`. The fuse and the
     pre-hook only compare it for equality with
-    `BalanceFuseSnapshot.custodian_marker`; `paused` is the flag
+    `BalanceFuseSnapshot.custodian_marker`. `custodian_marker_kind` says
+    which, read from the executor at the same block (``None`` without an
+    executor); `paused` is the flag
     the balance fuse sets on a big change and `ExternalStateUnpauseFuse` clears
     with an atomist signature. `ExternalStatePausePreHook` blocks the vault's
     gated user operations while the flag is set, and also, flag or not, while
@@ -148,6 +181,7 @@ class ExternalStateVaultState:
     executor: ChecksumAddress | None
     last_total_balance: Amount
     last_checked_custodian_marker: CustodianMarker
+    custodian_marker_kind: CustodianMarkerKind | None
     paused: bool
     block: int
 
@@ -232,10 +266,14 @@ def read_external_state(
         raise ExternalStateError(
             f"malformed pause flag in the external-state storage of {checksum}"
         )
+    executor = Web3.to_checksum_address(f"0x{words[0]:040x}") if words[0] else None
     return ExternalStateVaultState(
-        executor=Web3.to_checksum_address(f"0x{words[0]:040x}") if words[0] else None,
+        executor=executor,
         last_total_balance=Amount(words[1]),
         last_checked_custodian_marker=CustodianMarker(words[2]),
+        custodian_marker_kind=(
+            _read_marker_kind(ctx, executor, read_at) if executor else None
+        ),
         paused=words[3] == 1,
         block=block,
     )
@@ -365,6 +403,11 @@ class ExternalStateExecutor(ContractWrapper):
             )
         )
 
+    def read_custodian_marker_kind(self, ctx: Web3Context) -> CustodianMarkerKind:
+        """Whether this executor's custodian marker is a timestamp or a
+        confirm count, at ``ctx``'s default block (see `CustodianMarkerKind`)."""
+        return _read_marker_kind(ctx, self._require_address(), ctx.default_block)
+
     def confirm_count(self) -> Call[CustodianMarker]:
         """Executors of the 2026-10-21 contracts release only: the count of
         confirmed custodian updates across every balance account, the marker

{ipor_fusion-4.0.0.dev293 → 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