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

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

@@ -237,6 +237,11 @@ the lifecycle matrix follows that.
 
 - `chains.py` chain registry; `market_ids.py` `IporFusionMarkets`; `types.py`; `errors.py`
   defines every SDK exception class (`tests/test_error_hierarchy.py` pins it)
+- `fusion_errors.py` — `FUSION_ERROR_SIGNATURES`, every custom error of the
+  ipor-fusion contracts and their imports, registered by `errors.py` so reverts
+  decode by name; generated, never edited by hand: `uv run python
+  scripts/fusion_error_signatures.py ../ipor-fusion --source <commit>` (needs the
+  checkout's `npm ci`)
 - `about.py` — package version, repository URL, CHANGELOG parsing (`fusion changelog`,
   `server_info`); `field_docs.py` — `DOCS`, the JSON field descriptions shared by CLI
   output and MCP models

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev303
+Version: 4.0.0.dev311
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -369,10 +369,12 @@ A flash-loan fuse also needs `update_callback_handler(handler, sender, selector)
 
 The full clone → configure → deposit → execute sequence is exercised in [`tests/test_simulate_vault_from_scratch_base.py`](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/tests/test_simulate_vault_from_scratch_base.py).
 
-Custom errors of the crosschain contracts decode by name: importing
-`ipor_fusion.crosschain` registers their signatures (`CROSSCHAIN_ERROR_SIGNATURES`),
-so a simulated or sent call that reverts reads `NavSettledStale(8453)` in
-`SimulationResult.revert_reason` and `TransactionError` instead of a bare selector.
+Custom errors of the IPOR Fusion contracts and the libraries they import
+(OpenZeppelin included) decode by name, so a simulated or sent call that reverts
+reads `AccessManagedUnauthorized(0x...)`, `UnsupportedFuse()` or
+`NavSettledStale(8453)` in `SimulationResult.revert_reason` and `TransactionError`
+instead of a bare selector. Importing `ipor_fusion.crosschain` also registers
+`CROSSCHAIN_ERROR_SIGNATURES`.
 `register_custom_errors([...])` adds your own, and `SimulationResult.raise_for_failure()`
 raises `SimulationError` naming the first failed call.
 
@@ -476,7 +478,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.dev303 → ipor_fusion-4.0.0.dev311}/README.md

@@ -320,10 +320,12 @@ A flash-loan fuse also needs `update_callback_handler(handler, sender, selector)
 
 The full clone → configure → deposit → execute sequence is exercised in [`tests/test_simulate_vault_from_scratch_base.py`](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/tests/test_simulate_vault_from_scratch_base.py).
 
-Custom errors of the crosschain contracts decode by name: importing
-`ipor_fusion.crosschain` registers their signatures (`CROSSCHAIN_ERROR_SIGNATURES`),
-so a simulated or sent call that reverts reads `NavSettledStale(8453)` in
-`SimulationResult.revert_reason` and `TransactionError` instead of a bare selector.
+Custom errors of the IPOR Fusion contracts and the libraries they import
+(OpenZeppelin included) decode by name, so a simulated or sent call that reverts
+reads `AccessManagedUnauthorized(0x...)`, `UnsupportedFuse()` or
+`NavSettledStale(8453)` in `SimulationResult.revert_reason` and `TransactionError`
+instead of a bare selector. Importing `ipor_fusion.crosschain` also registers
+`CROSSCHAIN_ERROR_SIGNATURES`.
 `register_custom_errors([...])` adds your own, and `SimulationResult.raise_for_failure()`
 raises `SimulationError` naming the first failed call.
 
@@ -427,7 +429,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.dev303 → ipor_fusion-4.0.0.dev311}/pyproject.toml

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

ipor_fusion-4.0.0.dev311/scripts/fusion_error_signatures.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Regenerate ``src/ipor_fusion/fusion_errors.py`` from an ipor-fusion checkout.
+
+Collects every ``error`` declaration of the Solidity files reachable by import
+from ``contracts/`` (the contracts and the libraries they import, OpenZeppelin
+included, resolved through the checkout's ``foundry.toml`` remappings) and
+writes them as
+canonical ``Name(type,...)`` signatures: enums become ``uint8``, contract,
+interface and library types ``address``, ``uint``/``int`` their 256-bit form.
+Any other parameter type (a struct, a user-defined value type) stops the run,
+because its canonical form needs the compiler.
+
+    uv run python scripts/fusion_error_signatures.py ../ipor-fusion --source <commit>
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+_OUTPUT = Path(__file__).resolve().parent.parent / "src/ipor_fusion/fusion_errors.py"
+_IMPORT = re.compile(r'^\s*import\s+(?:[^"\']*\s+from\s+)?["\']([^"\']+)["\']', re.M)
+_ERROR = re.compile(r"\berror\s+(\w+)\s*\(([^)]*)\)\s*;")
+_ENUM = re.compile(r"\benum\s+(\w+)")
+_CONTRACT = re.compile(r"\b(?:abstract\s+)?(?:contract|interface|library)\s+(\w+)")
+_ELEMENTARY = re.compile(
+    r"^(address|bool|string|bytes([1-9]|[12]\d|3[0-2])?|u?int(8|16|24|32|40|48|56|64"
+    r"|72|80|88|96|104|112|120|128|136|144|152|160|168|176|184|192|200|208|216|224"
+    r"|232|240|248|256)?)$"
+)
+_COMMENTS = re.compile(r"//[^\n]*|/\*.*?\*/", re.S)
+
+
+class _Resolver:
+    """Forge's import resolution: relative paths, then the longest matching
+    remapping, then the checkout root and each ``libs`` directory."""
+
+    def __init__(self, root: Path) -> None:
+        profile = tomllib.loads((root / "foundry.toml").read_text())["profile"]
+        default = profile["default"]
+        pairs = [entry.split("=", 1) for entry in default["remappings"]]
+        self._root = root
+        self._remappings = sorted(pairs, key=lambda pair: -len(pair[0]))
+        self._bases = [root, *(root / lib for lib in default["libs"])]
+
+    def __call__(self, spec: str, importer: Path) -> Path:
+        if spec.startswith("."):
+            return (importer.parent / spec).resolve()
+        for prefix, target in self._remappings:
+            if spec.startswith(prefix):
+                return (self._root / (target + spec.removeprefix(prefix))).resolve()
+        for base in self._bases:
+            if (base / spec).is_file():
+                return (base / spec).resolve()
+        return (self._root / spec).resolve()
+
+
+def _closure(root: Path) -> dict[Path, str]:
+    resolve = _Resolver(root)
+    pending = sorted((root / "contracts").rglob("*.sol"))
+    sources: dict[Path, str] = {}
+    while pending:
+        path = pending.pop()
+        if path in sources:
+            continue
+        if not path.is_file():
+            raise SystemExit(f"unresolved import: {path}")
+        text = _COMMENTS.sub("", path.read_text())
+        sources[path] = text
+        pending.extend(resolve(spec, path) for spec in _IMPORT.findall(text))
+    return sources
+
+
+def _canonical(param: str, enums: set[str], contracts: set[str], where: str) -> str:
+    kind = param.split()[0].split(".")[-1]
+    if kind in ("uint", "int"):
+        return f"{kind}256"
+    if _ELEMENTARY.fullmatch(kind):
+        return kind
+    if kind in enums:
+        return "uint8"
+    if kind in contracts:
+        return "address"
+    raise SystemExit(f"{where}: no canonical form for parameter type {kind!r}")
+
+
+def collect(root: Path) -> list[str]:
+    sources = _closure(root)
+    enums = {name for text in sources.values() for name in _ENUM.findall(text)}
+    contracts = {name for text in sources.values() for name in _CONTRACT.findall(text)}
+    signatures: set[str] = set()
+    for path, text in sources.items():
+        for name, params in _ERROR.findall(text):
+            types = [
+                _canonical(p.strip(), enums, contracts, f"{path}: {name}")
+                for p in params.split(",")
+                if p.strip()
+            ]
+            signatures.add(f"{name}({','.join(types)})")
+    return sorted(signatures)
+
+
+def render(signatures: list[str], source: str) -> str:
+    lines = "\n".join(f'    "{signature}",' for signature in signatures)
+    return f'''"""Custom errors of the IPOR Fusion contracts and the libraries they import
+(OpenZeppelin included), registered by :mod:`ipor_fusion.errors` so revert data
+decodes by name (``AccessManagedUnauthorized(0x...)``, ``UnsupportedFuse()``)
+instead of a bare selector.
+
+Generated by ``scripts/fusion_error_signatures.py`` from ipor-fusion {source};
+do not edit by hand.
+"""
+
+#: ``Name(type,...)`` signatures, sorted; the selector is the keccak of each.
+FUSION_ERROR_SIGNATURES: tuple[str, ...] = (
+{lines}
+)
+'''
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Regenerate fusion_errors.py.")
+    parser.add_argument("checkout", type=Path, help="ipor-fusion checkout")
+    parser.add_argument(
+        "--source", required=True, help="what the checkout is, e.g. a commit"
+    )
+    args = parser.parse_args()
+    signatures = collect(args.checkout.resolve())
+    _OUTPUT.write_text(render(signatures, args.source))
+    print(f"{len(signatures)} signatures -> {_OUTPUT}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

{ipor_fusion-4.0.0.dev303 → ipor_fusion-4.0.0.dev311}/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,
@@ -556,6 +558,8 @@ __all__ = [
     "RoleAccount",
     "RoleAccountJson",
     "CallPermission",
+    "CallPlan",
+    "CallPlanKind",
     "RoleStatus",
     "resolve_access_manager",
     "role_account_sort_key",

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

@@ -1,6 +1,8 @@
 from ipor_fusion.core.access import (
     AccessManager,
     CallPermission,
+    CallPlan,
+    CallPlanKind,
     RoleAccount,
     RoleAccountJson,
     RoleAccountsJson,
@@ -107,6 +109,8 @@ __all__ = [
     "RoleAccount",
     "RoleAccountJson",
     "CallPermission",
+    "CallPlan",
+    "CallPlanKind",
     "RoleStatus",
     "RewardsManager",
     "VestingData",

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

@@ -1,6 +1,6 @@
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
-from typing import TypedDict
+from typing import Literal, TypedDict
 
 from eth_abi import decode, encode
 from eth_abi.exceptions import InsufficientDataBytes
@@ -68,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))
@@ -204,6 +231,82 @@ class AccessManager(ContractWrapper):
             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.dev303 → ipor_fusion-4.0.0.dev311}/src/ipor_fusion/errors.py

@@ -10,6 +10,7 @@ from eth_utils import function_signature_to_4byte_selector
 from web3 import Web3
 from web3.types import TxParams, TxReceipt
 
+from ipor_fusion.fusion_errors import FUSION_ERROR_SIGNATURES
 from ipor_fusion.types import TxHash
 
 log = logging.getLogger(__name__)
@@ -50,6 +51,9 @@ def register_custom_errors(signatures: Iterable[str]) -> None:
         CUSTOM_ERRORS[function_signature_to_4byte_selector(canonical)] = (name, types)
 
 
+register_custom_errors(FUSION_ERROR_SIGNATURES)
+
+
 def decode_custom_error(selector: bytes, payload: bytes) -> str | None:
     """``Name(arg, arg)`` for a registered selector, ``None`` otherwise."""
     registered = CUSTOM_ERRORS.get(bytes(selector))