feat(invariants): dual-state migration helper + beacon-owner pin

src/lib/LibMigrationInvariant.sol

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: LicenseRef-DCL-1.0
+// SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
+pragma solidity ^0.8.25;
+
+/// @notice `actual` is neither the accepted pre-migration nor the accepted
+/// post-migration state, and the migration deadline has not yet passed. The
+/// live chain has drifted onto a value neither side of the migration expects.
+/// @param label Human-readable identifier for the invariant being asserted
+/// (e.g. `"STOX_RECEIPT_VAULT_BEACON_V1.owner()"`).
+/// @param expectedPre The accepted state before the migration runs.
+/// @param expectedPost The accepted state after the migration runs.
+/// @param actual The value read from the live chain.
+error MigrationStateDrift(string label, bytes32 expectedPre, bytes32 expectedPost, bytes32 actual);
+
+/// @notice The migration deadline has passed but `actual` is still not the
+/// post-migration value. Signals that either the script never ran on-chain
+/// before `deadline`, or the deadline was set too aggressively. The invariant
+/// deliberately red-lines cron CI in this state to force an explicit
+/// operator choice: run the migration, extend the deadline, or delete the
+/// invariant (accepting the pre-state as the new canonical).
+/// @param label Human-readable identifier for the invariant being asserted.
+/// @param expectedPost The accepted state after the migration runs.
+/// @param actual The value read from the live chain.
+/// @param deadline The unix timestamp past which only the post-state passes.
+error MigrationDeadlinePassed(string label, bytes32 expectedPost, bytes32 actual, uint256 deadline);
+
+/// @title LibMigrationInvariant
+/// @notice Reusable dual-state invariant helper with an operator SLA baked
+/// in. Encodes the pattern:
+///
+/// - The migration script mutates some on-chain value from `pre` to `post`.
+/// - A live-fork invariant test asserts, against the head of the target
+///   network, that the value is EITHER `pre` (script has not run yet) OR
+///   `post` (script has run) — while `block.timestamp < deadline`.
+/// - Once `block.timestamp >= deadline`, only `post` passes. If the script
+///   has not landed on-chain by then, cron CI red-lines and forces the
+///   operator to make an explicit choice — run the script, extend the
+///   deadline, or delete the invariant (accepting `pre` as the new
+///   canonical).
+///
+/// This lets the invariant test PR merge alongside the migration script
+/// (rather than waiting until the script has actually executed on-chain),
+/// giving the migration itself the same "cron would trip if we drifted"
+/// enforcement every other production invariant has — even while the
+/// migration is pending.
+///
+/// @dev `block.timestamp` is read once per call from the current chain. A
+/// live-fork test at chain head sees real time, so cron picks up the
+/// deadline transition automatically without any per-test warping.
+library LibMigrationInvariant {
+    /// @notice Assert `actual` matches the migration acceptance window for
+    /// the current time. Before `deadline`: `actual` must be `pre` OR `post`.
+    /// At or after `deadline`: `actual` must be `post`.
+    /// @param label Human-readable identifier for the invariant surfaced in
+    /// revert data — pick something that unambiguously names the on-chain
+    /// slot being asserted (e.g. `"STOX_RECEIPT_VAULT_BEACON_V1.owner()"`).
+    /// @param actual The value read from the live chain.
+    /// @param pre The accepted state before the migration runs.
+    /// @param post The accepted state after the migration runs.
+    /// @param deadline Unix timestamp past which only `post` is accepted.
+    function assertMigration(string memory label, bytes32 actual, bytes32 pre, bytes32 post, uint256 deadline)
+        internal
+        view
+    {
+        if (block.timestamp >= deadline) {
+            if (actual != post) {
+                revert MigrationDeadlinePassed(label, post, actual, deadline);
+            }
+        } else if (actual != pre && actual != post) {
+            revert MigrationStateDrift(label, pre, post, actual);
+        }
+    }
+
+    /// @notice `address` overload. Casts each address to `bytes32` under the
+    /// hood via `uint160`.
+    /// @param label Human-readable identifier for the invariant surfaced in
+    /// revert data.
+    /// @param actual The value read from the live chain.
+    /// @param pre The accepted state before the migration runs.
+    /// @param post The accepted state after the migration runs.
+    /// @param deadline Unix timestamp past which only `post` is accepted.
+    function assertMigration(string memory label, address actual, address pre, address post, uint256 deadline)
+        internal
+        view
+    {
+        assertMigration(
+            label,
+            bytes32(uint256(uint160(actual))),
+            bytes32(uint256(uint160(pre))),
+            bytes32(uint256(uint160(post))),
+            deadline
+        );
+    }
+
+    /// @notice `uint256` overload. Casts each value to `bytes32` under the
+    /// hood.
+    /// @param label Human-readable identifier for the invariant surfaced in
+    /// revert data.
+    /// @param actual The value read from the live chain.
+    /// @param pre The accepted state before the migration runs.
+    /// @param post The accepted state after the migration runs.
+    /// @param deadline Unix timestamp past which only `post` is accepted.
+    function assertMigration(string memory label, uint256 actual, uint256 pre, uint256 post, uint256 deadline)
+        internal
+        view
+    {
+        assertMigration(label, bytes32(actual), bytes32(pre), bytes32(post), deadline);
+    }
+}

test/src/concrete/deploy/BeaconOwnerMigrationPin.t.sol

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: LicenseRef-DCL-1.0
+// SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
+pragma solidity =0.8.25;
+
+import {Test} from "forge-std-1.16.1/src/Test.sol";
+import {Ownable} from "@openzeppelin-contracts-5.6.1/access/Ownable.sol";
+import {LibRainDeploy} from "rain-deploy-0.1.4/src/lib/LibRainDeploy.sol";
+import {LibMigrationInvariant} from "../../../../src/lib/LibMigrationInvariant.sol";
+import {LibProdDeployV1} from "../../../../src/lib/LibProdDeployV1.sol";
+import {LibSafeInvariants} from "../../../../src/lib/LibSafeInvariants.sol";
+
+/// @title BeaconOwnerMigrationPinTest
+/// @notice Live-fork pin of the beacon-ownership migration executed by
+/// `script/MigrateBeaconOwners.s.sol` (PR #196). Reads each of the three V1
+/// beacons' `owner()` from live Base head and asserts, via
+/// `LibMigrationInvariant`, that the value is either the pre-migration EOA
+/// (`LibProdDeployV1.BEACON_INITIAL_OWNER`) or the post-migration Safe
+/// (`LibSafeInvariants.STOX_TOKEN_OWNER_SAFE`) — up until
+/// `BEACON_OWNER_MIGRATION_DEADLINE`. From that timestamp on only the Safe is
+/// accepted; any beacon still EOA-owned at that point trips
+/// `MigrationDeadlinePassed` and red-lines the cron.
+///
+/// @dev Uses an unpinned Base head fork so `block.timestamp` is real. Pinning
+/// a block would freeze the deadline check to whichever timestamp the pinned
+/// block carried, which is exactly the wrong behaviour for a deadline-gated
+/// invariant.
+///
+/// When the migration lands on-chain the beacon owner reads flip from EOA
+/// to Safe and this test transitions from the "pre acceptable" branch to the
+/// "post required" branch without any code change. If the migration has not
+/// landed by the deadline this test red-lines and forces an operator choice:
+/// run the script, extend the deadline, or delete the invariant.
+contract BeaconOwnerMigrationPinTest is Test {
+    /// @notice Unix timestamp past which only the Safe-owned post-state is
+    /// accepted — the operator-SLA cut-off for the beacon-owner migration.
+    /// `2026-09-01T00:00:00Z`. Past this instant the invariant demands the
+    /// migration has landed on-chain; a later PR can move it earlier to
+    /// tighten the forcing function or later to loosen it if the SLA shifts.
+    uint256 internal constant BEACON_OWNER_MIGRATION_DEADLINE = 1_788_220_800;
+
+    /// @notice Assert the migration-window invariant on a single beacon.
+    function assertBeaconOwnerMigrationInvariant(address beacon, string memory label) internal view {
+        LibMigrationInvariant.assertMigration(
+            label,
+            Ownable(beacon).owner(),
+            LibProdDeployV1.BEACON_INITIAL_OWNER,
+            LibSafeInvariants.STOX_TOKEN_OWNER_SAFE,
+            BEACON_OWNER_MIGRATION_DEADLINE
+        );
+    }
+
+    /// @notice Each of the three V1 beacons `MigrateBeaconOwners` targets
+    /// is either still EOA-owned or already Safe-owned. Runs against Base
+    /// head so any drift into a third owner surfaces immediately, and the
+    /// deadline transition surfaces automatically on cron.
+    function testV1BeaconOwnersInMigrationWindow() external {
+        vm.createSelectFork(LibRainDeploy.BASE);
+        assertBeaconOwnerMigrationInvariant(LibProdDeployV1.STOX_RECEIPT_BEACON_V1, "STOX_RECEIPT_BEACON_V1.owner()");
+        assertBeaconOwnerMigrationInvariant(
+            LibProdDeployV1.STOX_RECEIPT_VAULT_BEACON_V1, "STOX_RECEIPT_VAULT_BEACON_V1.owner()"
+        );
+        assertBeaconOwnerMigrationInvariant(
+            LibProdDeployV1.STOX_WRAPPED_TOKEN_VAULT_BEACON_V1, "STOX_WRAPPED_TOKEN_VAULT_BEACON_V1.owner()"
+        );
+    }
+}

test/src/lib/LibMigrationInvariant.t.sol

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: LicenseRef-DCL-1.0
+// SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
+pragma solidity =0.8.25;
+
+import {Test} from "forge-std-1.16.1/src/Test.sol";
+import {
+    LibMigrationInvariant,
+    MigrationStateDrift,
+    MigrationDeadlinePassed
+} from "../../../src/lib/LibMigrationInvariant.sol";
+import {LibMigrationInvariantHarness} from "./LibMigrationInvariantHarness.sol";
+
+/// @title LibMigrationInvariantTest
+/// @notice Behavioural coverage of the migration invariant helper: both
+/// acceptance branches before the deadline, the exact-deadline boundary, the
+/// two enforcement branches after the deadline, and the two typed errors it
+/// surfaces. Each overload (`bytes32` / `address` / `uint256`) exercises the
+/// same underlying decision, so the address and uint256 overloads only need
+/// one round-trip test each to prove the cast — the exhaustive branch
+/// coverage lives on the `bytes32` overload.
+///
+/// @dev `block.timestamp` is warped explicitly per test rather than forking a
+/// live chain: the helper's decision surface is pure `block.timestamp`
+/// comparisons, so cheatcode warping is the tightest way to exercise every
+/// branch without pulling in fork state that is irrelevant to what is being
+/// tested.
+contract LibMigrationInvariantTest is Test {
+    LibMigrationInvariantHarness internal harness;
+
+    string internal constant LABEL = "test.invariant";
+    bytes32 internal constant PRE = bytes32(uint256(0xAAAA));
+    bytes32 internal constant POST = bytes32(uint256(0xBBBB));
+    bytes32 internal constant OTHER = bytes32(uint256(0xCCCC));
+    uint256 internal constant DEADLINE = 2_000_000_000;
+
+    function setUp() external {
+        harness = new LibMigrationInvariantHarness();
+    }
+
+    /// @notice Before the deadline, `actual == pre` is accepted: the script
+    /// has not yet run and the chain still reports the pre-migration value.
+    function testBeforeDeadlineAcceptsPre() external {
+        vm.warp(DEADLINE - 1);
+        harness.callAssertMigrationBytes32(LABEL, PRE, PRE, POST, DEADLINE);
+    }
+
+    /// @notice Before the deadline, `actual == post` is accepted: the script
+    /// has already run and the chain now reports the post-migration value.
+    function testBeforeDeadlineAcceptsPost() external {
+        vm.warp(DEADLINE - 1);
+        harness.callAssertMigrationBytes32(LABEL, POST, PRE, POST, DEADLINE);
+    }
+
+    /// @notice Before the deadline, `actual` matching neither `pre` nor
+    /// `post` trips `MigrationStateDrift` — the chain has landed on a value
+    /// the migration does not anticipate on either side of the transition.
+    function testBeforeDeadlineRejectsOtherWithDrift() external {
+        vm.warp(DEADLINE - 1);
+        vm.expectRevert(abi.encodeWithSelector(MigrationStateDrift.selector, LABEL, PRE, POST, OTHER));
+        harness.callAssertMigrationBytes32(LABEL, OTHER, PRE, POST, DEADLINE);
+    }
+
+    /// @notice At exactly the deadline the helper flips to strict
+    /// enforcement — `post` still passes.
+    function testAtDeadlineAcceptsPost() external {
+        vm.warp(DEADLINE);
+        harness.callAssertMigrationBytes32(LABEL, POST, PRE, POST, DEADLINE);
+    }
+
+    /// @notice At exactly the deadline the helper flips to strict
+    /// enforcement — `pre` no longer passes, trips
+    /// `MigrationDeadlinePassed`. This is the forcing-function on the
+    /// operator: run the migration or make an explicit choice.
+    function testAtDeadlineRejectsPreWithDeadlinePassed() external {
+        vm.warp(DEADLINE);
+        vm.expectRevert(abi.encodeWithSelector(MigrationDeadlinePassed.selector, LABEL, POST, PRE, DEADLINE));
+        harness.callAssertMigrationBytes32(LABEL, PRE, PRE, POST, DEADLINE);
+    }
+
+    /// @notice After the deadline, `actual == post` still passes.
+    function testAfterDeadlineAcceptsPost() external {
+        vm.warp(DEADLINE + 1);
+        harness.callAssertMigrationBytes32(LABEL, POST, PRE, POST, DEADLINE);
+    }
+
+    /// @notice After the deadline, `actual == pre` trips
+    /// `MigrationDeadlinePassed` — the pre-state grace window has closed.
+    function testAfterDeadlineRejectsPreWithDeadlinePassed() external {
+        vm.warp(DEADLINE + 1);
+        vm.expectRevert(abi.encodeWithSelector(MigrationDeadlinePassed.selector, LABEL, POST, PRE, DEADLINE));
+        harness.callAssertMigrationBytes32(LABEL, PRE, PRE, POST, DEADLINE);
+    }
+
+    /// @notice After the deadline, any drift trips
+    /// `MigrationDeadlinePassed` (not `MigrationStateDrift`) — the strict-
+    /// enforcement branch is unconditional.
+    function testAfterDeadlineRejectsOtherWithDeadlinePassed() external {
+        vm.warp(DEADLINE + 1);
+        vm.expectRevert(abi.encodeWithSelector(MigrationDeadlinePassed.selector, LABEL, POST, OTHER, DEADLINE));
+        harness.callAssertMigrationBytes32(LABEL, OTHER, PRE, POST, DEADLINE);
+    }
+
+    /// @notice An unset (`deadline == 0`) deadline resolves to the
+    /// restrictive outcome: it reads as already-passed, so only `post` is
+    /// accepted and `pre` trips `MigrationDeadlinePassed`. Pins the fail-safe
+    /// reading of an uninitialized SLA — guards against a future "0 means no
+    /// deadline / accept `pre` forever" misinterpretation, which would flip
+    /// the sentinel from fail-closed to fail-open.
+    function testZeroDeadlineIsStrict() external {
+        // A realistic non-zero chain time; the zero deadline must still
+        // enforce strictly rather than open an unbounded grace window.
+        vm.warp(DEADLINE);
+        harness.callAssertMigrationBytes32(LABEL, POST, PRE, POST, 0);
+        vm.expectRevert(abi.encodeWithSelector(MigrationDeadlinePassed.selector, LABEL, POST, PRE, 0));
+        harness.callAssertMigrationBytes32(LABEL, PRE, PRE, POST, 0);
+    }
+
+    /// @notice The `address` overload round-trips through the same
+    /// decision — one before-deadline pre acceptance is enough to prove the
+    /// `bytes32(uint256(uint160(...)))` cast lands where it should.
+    function testAddressOverloadRoundTripsPre() external {
+        vm.warp(DEADLINE - 1);
+        address pre = address(0x1111111111111111111111111111111111111111);
+        address post = address(0x2222222222222222222222222222222222222222);
+        harness.callAssertMigrationAddress(LABEL, pre, pre, post, DEADLINE);
+    }
+
+    /// @notice The `address` overload surfaces the same
+    /// `MigrationStateDrift` selector as the `bytes32` overload when the
+    /// value matches neither side — the byte layout of the emitted
+    /// revert data is unaffected by which overload was called.
+    function testAddressOverloadDriftSurfacesSelector() external {
+        vm.warp(DEADLINE - 1);
+        address pre = address(0x1111111111111111111111111111111111111111);
+        address post = address(0x2222222222222222222222222222222222222222);
+        address other = address(0x3333333333333333333333333333333333333333);
+        vm.expectRevert(
+            abi.encodeWithSelector(
+                MigrationStateDrift.selector,
+                LABEL,
+                bytes32(uint256(uint160(pre))),
+                bytes32(uint256(uint160(post))),
+                bytes32(uint256(uint160(other)))
+            )
+        );
+        harness.callAssertMigrationAddress(LABEL, other, pre, post, DEADLINE);
+    }
+
+    /// @notice The `uint256` overload round-trips through the same decision.
+    function testUint256OverloadRoundTripsPre() external {
+        vm.warp(DEADLINE - 1);
+        harness.callAssertMigrationUint256(LABEL, 1, 1, 3, DEADLINE);
+    }
+
+    /// @notice The `uint256` overload surfaces the same
+    /// `MigrationDeadlinePassed` selector as the `bytes32` overload after
+    /// the deadline has passed.
+    function testUint256OverloadDeadlinePassedSurfacesSelector() external {
+        vm.warp(DEADLINE + 1);
+        vm.expectRevert(
+            abi.encodeWithSelector(
+                MigrationDeadlinePassed.selector, LABEL, bytes32(uint256(3)), bytes32(uint256(1)), DEADLINE
+            )
+        );
+        harness.callAssertMigrationUint256(LABEL, 1, 1, 3, DEADLINE);
+    }
+}

test/src/lib/LibMigrationInvariantHarness.sol

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: LicenseRef-DCL-1.0
+// SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
+pragma solidity =0.8.25;
+
+import {LibMigrationInvariant} from "../../../src/lib/LibMigrationInvariant.sol";
+
+/// @title LibMigrationInvariantHarness
+/// @notice External-call shim around the internal library so `vm.expectRevert`
+/// can intercept the typed errors. `vm.expectRevert` only catches reverts from
+/// external calls; library `internal` functions inline and would fail the
+/// depth check otherwise. One `call*` per overload so each `bytes32` /
+/// `address` / `uint256` signature is exercised end-to-end.
+contract LibMigrationInvariantHarness {
+    function callAssertMigrationBytes32(
+        string memory label,
+        bytes32 actual,
+        bytes32 pre,
+        bytes32 post,
+        uint256 deadline
+    ) external view {
+        LibMigrationInvariant.assertMigration(label, actual, pre, post, deadline);
+    }
+
+    function callAssertMigrationAddress(
+        string memory label,
+        address actual,
+        address pre,
+        address post,
+        uint256 deadline
+    ) external view {
+        LibMigrationInvariant.assertMigration(label, actual, pre, post, deadline);
+    }
+
+    function callAssertMigrationUint256(
+        string memory label,
+        uint256 actual,
+        uint256 pre,
+        uint256 post,
+        uint256 deadline
+    ) external view {
+        LibMigrationInvariant.assertMigration(label, actual, pre, post, deadline);
+    }
+}