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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev303
+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
@@ -476,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.dev303 → ipor_fusion-4.0.0.dev308}/README.md

@@ -427,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.dev303 → ipor_fusion-4.0.0.dev308}/pyproject.toml

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

@@ -15,8 +15,11 @@ from ipor_fusion import (
     ContractNotFoundError,
     NotPlasmaVaultError,
     OwnerNotFoundError,
+    PlasmaVault,
     RoleAccount,
+    Roles,
     parse_access_manager_address,
+    parse_plasma_vault_address,
     resolve_access_manager,
     role_account_sort_key,
 )
@@ -317,3 +320,98 @@ def test_hash_operation_matches_the_deployed_manager():
     assert AccessManager.hash_operation(caller, vault, data).hex() == (
         "449c1b0678d9666078c86be94b86c7f4bfe8fe012bdacb56246db911e78b7ebb"
     )
+
+
+class TestCallPlan:
+    manager = AccessManager(parse_access_manager_address(MANAGER_ADDR))
+    target_call = PlasmaVault(parse_plasma_vault_address(VAULT_ADDR)).execute([])
+    NOW = 10_000
+
+    def _ctx(self, *, immediate: bool, delay: int, scheduled: int = 0):
+        def handler(_to: str, data: bytes) -> bytes:
+            selector = bytes(data[:4])
+            if selector == Web3.keccak(text="canCall(address,address,bytes4)")[:4]:
+                return encode(["bool", "uint32"], [immediate, delay])
+            assert selector == Web3.keccak(text="getSchedule(bytes32)")[:4]
+            return encode(["uint48"], [scheduled])
+
+        ctx = MagicMock()
+        ctx.default_block = "finalized"
+        ctx.at_block.return_value = ctx
+        ctx.call.side_effect = multicall_aware(handler)
+        ctx.web3.eth.get_block.return_value = {"number": 777, "timestamp": self.NOW}
+        return ctx
+
+    def _plan(self, *, via_manager: bool = False, **kwargs):
+        return self.manager.read_call_plan(
+            self._ctx(**kwargs), self.target_call, caller=ALICE, via_manager=via_manager
+        )
+
+    def test_immediate_sends_the_call_itself(self):
+        plan = self._plan(immediate=True, delay=0)
+        assert plan.kind == "immediate"
+        assert plan.next_call is not None
+        assert (plan.next_call.to, plan.next_call.data) == (
+            self.target_call.to,
+            self.target_call.data,
+        )
+
+    def test_the_block_the_context_names_is_resolved_once_and_pinned(self):
+        ctx = self._ctx(immediate=False, delay=3600, scheduled=self.NOW)
+        self.manager.read_call_plan(ctx, self.target_call, caller=ALICE)
+        ctx.web3.eth.get_block.assert_called_once_with("finalized")
+        ctx.at_block.assert_called_once_with(777)
+
+    def test_forbidden_sends_nothing(self):
+        plan = self._plan(immediate=False, delay=0)
+        assert (plan.kind, plan.next_call) == ("forbidden", None)
+
+    def test_a_delayed_caller_schedules_first(self):
+        plan = self._plan(immediate=False, delay=3600)
+        assert plan.kind == "schedule"
+        assert plan.next_call is not None
+        assert plan.next_call.data == Web3.keccak(
+            text="schedule(address,bytes,uint48)"
+        )[:4] + encode(
+            ["address", "bytes", "uint48"],
+            [self.target_call.to, self.target_call.data, 0],
+        )
+        assert plan.operation == AccessManager.hash_operation(
+            ALICE, self.target_call.to, self.target_call.data
+        )
+
+    def test_waiting_then_ready_through_the_manager(self):
+        waiting = self._plan(immediate=False, delay=3600, scheduled=self.NOW + 1)
+        assert (waiting.kind, waiting.scheduled_at, waiting.next_call) == (
+            "waiting",
+            self.NOW + 1,
+            None,
+        )
+        ready = self._plan(immediate=False, delay=3600, scheduled=self.NOW)
+        assert ready.kind == "ready"
+        assert ready.next_call is not None
+        # Sent as the call itself, so the target consumes the schedule and still
+        # sees the caller as the sender.
+        assert (ready.next_call.to, ready.next_call.data) == (
+            self.target_call.to,
+            self.target_call.data,
+        )
+        relayed = self._plan(
+            immediate=False, delay=3600, scheduled=self.NOW, via_manager=True
+        )
+        assert relayed.next_call is not None
+        assert relayed.next_call.to == MANAGER_ADDR
+        assert relayed.next_call.data == Web3.keccak(text="execute(address,bytes)")[
+            :4
+        ] + encode(["address", "bytes"], [self.target_call.to, self.target_call.data])
+
+    def test_calls_on_the_manager_itself_are_not_planned(self):
+        grant = self.manager.grant_role(Roles.ALPHA_ROLE, ALICE, Period(0))
+        with pytest.raises(ValueError, match="access manager itself"):
+            self.manager.read_call_plan(MagicMock(), grant, caller=ALICE)
+
+    def test_cancel_encodes_caller_target_and_data(self):
+        call = self.manager.cancel(ALICE, VAULT_ADDR, b"\x01")
+        assert call.data == Web3.keccak(text="cancel(address,address,bytes)")[
+            :4
+        ] + encode(["address", "address", "bytes"], [ALICE, VAULT_ADDR, b"\x01"])

{ipor_fusion-4.0.0.dev303 → ipor_fusion-4.0.0.dev308}/tests/test_public_api.py

@@ -82,6 +82,8 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "CacheKey",
             "Call",
             "CallPermission",
+            "CallPlan",
+            "CallPlanKind",
             "ChainId",
             "ChainlinkDetailJson",
             "ChangelogEntry",
@@ -548,6 +550,8 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "BlockOverrides",
             "Call",
             "CallPermission",
+            "CallPlan",
+            "CallPlanKind",
             "CloneArgs",
             "ContextManager",
             "DecodedFuseAction",

ipor_fusion-4.0.0.dev308/tests/test_simulate_timelock_base.py

@@ -0,0 +1,51 @@
+"""A timelocked governance call on a live Base vault, end to end in one
+eth_simulateV1 run: the plan says schedule, the scheduled call is not executable
+before the delay, and runs through the manager after it. Skipped without an
+archive ``BASE_PROVIDER_URL`` that serves ``eth_simulateV1``."""
+
+from _live import archive_context
+from web3 import Web3
+
+from ipor_fusion import AccessManager, PlasmaVault, Shares, VaultSimulator
+from ipor_fusion.types import parse_plasma_vault_address
+
+VAULT = parse_plasma_vault_address("0xc4c00d8b323f37527eeda27c87412378be9f68ec")
+# Holds the vault's ATOMIST role with a three-day execution delay.
+ATOMIST = Web3.to_checksum_address("0xF6a9bd8F6DC537675D499Ac1CA14f2c55d8b5569")
+BLOCK = 52973779
+NEW_CAP = Shares(10**30)
+
+
+def test_schedule_wait_and_execute_a_delayed_call(web3_base):
+    ctx = archive_context("BASE_PROVIDER_URL", BLOCK, VAULT)
+    vault = PlasmaVault(VAULT)
+    manager = AccessManager(vault.get_access_manager_address().call(ctx))
+    cap = vault.set_total_supply_cap(NEW_CAP)
+
+    plan = manager.read_call_plan(ctx, cap, caller=ATOMIST)
+    assert plan.kind == "schedule"
+    assert plan.permission.delay == 3 * 24 * 3600
+    assert plan.next_call is not None
+
+    early = VaultSimulator(web3_base, block=BLOCK)
+    early.add_call(plan.next_call, from_=ATOMIST, label="schedule")
+    early.next_block(3600)
+    early.add_call(cap, from_=ATOMIST, label="early")
+    scheduled, too_early = early.run().calls
+    assert scheduled.success
+    assert not too_early.success
+    assert too_early.error is not None
+    assert "0x18cb6b7a" in too_early.error  # AccessManagerNotReady(bytes32)
+
+    # Once ready, the vault consumes the schedule on a direct call from the
+    # atomist, or the manager relays it.
+    for ready in (cap, manager.execute(cap.to, cap.data)):
+        sim = VaultSimulator(web3_base, block=BLOCK)
+        sim.add_call(plan.next_call, from_=ATOMIST)
+        when = sim.observe(manager.get_schedule(plan.operation))
+        sim.next_block(int(plan.permission.delay) + 1)
+        sim.add_call(ready, from_=ATOMIST)
+        after = sim.observe(vault.get_total_supply_cap())
+        assert sim.run().all_success
+        assert when.value > 0
+        assert after.value == NEW_CAP