PAS contracts

.github/workflows/test.yml

@@ -1,38 +1,37 @@
-name: CI
+name: test
 
-permissions: {}
-
-on:
-  push:
-  pull_request:
-  workflow_dispatch:
+on: [push, pull_request]
 
 env:
   FOUNDRY_PROFILE: ci
 
 jobs:
   check:
+    strategy:
+      fail-fast: true
+
     name: Foundry project
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v3
         with:
-          persist-credentials: false
           submodules: recursive
 
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
-
-      - name: Show Forge version
-        run: forge --version
-
-      - name: Run Forge fmt
-        run: forge fmt --check
+        with:
+          version: stable
 
       - name: Run Forge build
-        run: forge build --sizes
+        run: |
+          forge --version
+          forge build --sizes
+        id: build
 
       - name: Run Forge tests
-        run: forge test -vvv
+        run: |
+          forge test -vvv
+        id: test
+        env:
+          ETH_RPC_URL : ${{ secrets.ETH_RPC_URL  }}
+          BASE_RPC_URL: ${{ secrets.BASE_RPC_URL }}

.gitmodules

@@ -1,3 +1,10 @@
 [submodule "lib/forge-std"]
 	path = lib/forge-std
 	url = https://github.com/foundry-rs/forge-std
+[submodule "lib/openzeppelin-contracts"]
+	path = lib/openzeppelin-contracts
+	url = https://github.com/OpenZeppelin/openzeppelin-contracts
+[submodule "lib/dss-test"]
+	path = lib/dss-test
+	url = https://github.com/sky-ecosystem/dss-test
+

README.md

@@ -0,0 +1,35 @@
+# PAS - Parallelized Allocation System
+
+PAS is a governance framework for managing rate-limited operations through authorized actors called cBeams. It provides timelocked proposal execution, configurable rate limits, and role-based access control for interacting with external controllers.
+
+## Contracts
+
+### BeamState
+
+Central registry that manages system configuration and access control. Stores which cBeams are authorized to operate on which rate limit contracts and controllers, defines default rate limits and allowed controller actions, and configures parameters like `hop` (minimum time between increases) and `maxChange` (maximum rate of change). Supports role-based permissions with actions split between timelocked and direct access.
+
+### Configurator
+
+The operational interface used by cBeams to modify rate limits and execute controller actions. Enforces that rate limit changes respect the configured ceilings and requires waiting for `hop` between increases. Also gates controller calls through pre-approved action hashes stored in BeamState.
+
+### Timelock
+
+Extended OpenZeppelin TimelockController with pausing support, permissionless execution, and operation tracking for keeper integration. Disables self-calls to prevent proposals from modifying admin settings.
+
+### PASMom
+
+Emergency governance contract that allows authorized parties to trigger circuit breakers. Can call `stop()` on BeamState to halt Configurator operations and `pause()` on Timelock to block scheduling and execution. Callable by the owner or via the Chief's hat through the authority.
+
+## Unlimited rate limits
+
+A rate limit key is treated as unlimited — the Configurator forces any cBeam call to keep it at `(max, 0)` and rejects any attempt to lower it — in either of these cases:
+
+- It is registered in BeamState as `(max, 0)` (via `addInitRateLimits`), or
+- It is currently `(max, 0)` in RateLimits and has no BeamState default for that key.
+
+The second case protects keys that are already unlimited (e.g. withdrawal keys kept unlimited for security) even when they were never registered: a cBeam cannot unilateraly reset such a key to `0`. This holds both when first enabling the Configurator on an already-active PAU and when later opting into a facet that adds such a key.
+
+To make an existing unlimited key adjustable by a cBeam (e.g. to bound it), a `roleAuth` caller must register a bounded default for it via `addInitRateLimits` (through a star spell or the Timelock, depending on how the action is routed); the key then follows the normal bounded-limit rules.
+Note that the bounded default must be nonzero in at least one field as (0, 0) is indistinguishable from an unregistered key.
+
+**Warning:** unlocking a protected unlimited key (by registering a bounded default) hands control of it to the cBeam — which can then set it to any value down to `0`, immediately. Treat it as a deliberate governance decision: use a **key-rateLimits** specific default (never the general `address(0)` slot, which applies to that key across all RateLimits contracts), and only for keys you intend to make cBeam-adjustable.

SECURITY.md

@@ -0,0 +1,22 @@
+# Notes and Trust Assumptions
+
+- The following entities are trusted:
+  - **Timelock**: Fully trusted.
+  - **Core Council through direct actions**: Very highly trusted.
+  - **cBEAMs**: Mostly trusted (a trusted team's multisig, malicious activity is assumed to be of very low likelihood).
+
+- It is assumed proposers or cancelers would not cancel proposals maliciously (including Core Council).
+- It is assumed that before adding calldata, rate limits, or whitelisting targets, security related scenarios are thoroughly considered.
+- As part of the above considerations, possible misalignment of cBEAMs is expected to be taken into consideration (although unlikely). For example:
+  1. Omission - not executing a call when expected
+  2. Double execution - executing the same call twice
+  3. Stale execution - executing an old call after a newer one superseded it
+  4. Reordering - executing calls in the wrong order
+- It is also expected to be considered whether cBEAMs can block withdrawals in case of emergencies (for example, when needed, infinity rate limit would be configured).
+- It is assumed the Core Council would not block withdrawals or emergency mechanisms on purpose.
+- It is expected to be considered whether a default rate limits / calldata can be applied simultaneously on many controllers, thus amplifying potential harm. For example, the damage of depositing into a new vault without applying slippage protection might be amplified if it can be done for all whitelisted controllers. In general it is assumed that as the system scales more protections are added for such scenarios.
+- It is assumed that cBEAMs and Core Council are synced in their operations, including timing their actions against Timelock executions.
+- It is assumed the cancelers and Core Council are available on short notice to remove proposals and configurations if needed. This includes removing old calldata/rate-limits in a timely manner.
+- It is assumed pausers would not temporarily DoS the timelock on purpose.
+- As with other Sky contracts, a mom mechanism is not expected to be deployed on remote chains. It is expected to be sufficiently replaced with highly secured and trusted multisigs.
+

deploy/L2PASSpell.sol

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: © 2026 Dai Foundation <www.daifoundation.org>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+pragma solidity ^0.8.24;
+
+import { PASInit } from "./PASInit.sol";
+import { PASInstance } from "./PASInstance.sol";
+
+// An L2 spell template for L2GovernanceRelay to initialize PAS contracts on a foreign chain.
+// This spell should be viewed as skeleton/sample and can be altered prior to being used
+// if further configurations are needed (for example adding more proposers).
+contract L2PASSpell {
+
+    address public immutable beamState;
+    address public immutable configurator;
+    address public immutable timelock;
+
+    constructor(address beamState_, address configurator_, address timelock_) {
+        beamState    = beamState_;
+        configurator = configurator_;
+        timelock     = timelock_;
+    }
+
+    function init(
+        uint256          minDelay,
+        address          coreCouncil,
+        address[] memory cancellers,
+        address[] memory pausers,
+        bool             startPaused
+    ) external {
+        PASInstance memory pas = PASInstance({
+            beamState:    beamState,
+            configurator: configurator,
+            timelock:     timelock
+        });
+
+        PASInit.init(pas, minDelay, coreCouncil, cancellers, pausers);
+        if (startPaused) PASInit.pauseTimelock(timelock, address(this));
+    }
+}

deploy/PASAuthorizeInPAU.sol

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: © 2026 Dai Foundation <www.daifoundation.org>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+pragma solidity >=0.8.0;
+
+interface AccessControlLike {
+    function grantRole(bytes32 role, address account) external;
+}
+
+// Authorizes the PAS Configurator within a Star's PAU access-control system.
+//
+// Counterpart to PASInit: whereas PASInit configures the PAS-owned contracts (BeamState,
+// Configurator, Timelock), this is run by a Star's governance (the current DEFAULT_ADMIN_ROLE
+// holder on its PAU controller stack) to grant the PAS Configurator the admin access it needs
+// on the Star's own contracts.
+//
+// The two grants cover everything the Configurator calls:
+//   - accessControls: gates every facet admin setter dispatched via `callControllerAction`
+//                     (the controller has no roles of its own; it delegates to AccessControls).
+//   - rateLimits:     gates `setRateLimit` (setRateLimitData / setUnlimitedRateLimitData).
+//
+// NOTE: DEFAULT_ADMIN_ROLE is the OZ role-admin, so each grant makes the Configurator a full
+// role-superadmin of that contract (it can grant/revoke any role, including allocators). This
+// is the intended trust model but has a wide blast radius; the security of these roles rests
+// entirely on the timelock/cBeam/BeamState gating in front of the Configurator.
+library PASAuthorizeInPAU {
+
+    bytes32 internal constant DEFAULT_ADMIN_ROLE = 0x00;
+
+    function authorize(
+        address configurator,
+        address accessControls,
+        address rateLimits
+    ) internal {
+        AccessControlLike(accessControls).grantRole(DEFAULT_ADMIN_ROLE, configurator);
+        AccessControlLike(rateLimits).grantRole(DEFAULT_ADMIN_ROLE, configurator);
+    }
+}

deploy/PASDeploy.sol

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: © 2026 Dai Foundation <www.daifoundation.org>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+pragma solidity ^0.8.24;
+
+import { ScriptTools } from "dss-test/ScriptTools.sol";
+import { PASInstance } from "./PASInstance.sol";
+import { BeamState } from "src/BeamState.sol";
+import { Configurator } from "src/Configurator.sol";
+import { Timelock } from "src/timelock/Timelock.sol";
+import { PASMom } from "src/PASMom.sol";
+
+library PASDeploy {
+
+    function deploy(
+        address deployer,
+        address owner,
+        uint256 minDelay
+    ) internal returns (PASInstance memory pasInstance) {
+        pasInstance.beamState = address(new BeamState());
+        pasInstance.configurator = address(new Configurator(pasInstance.beamState));
+        pasInstance.timelock = address(new Timelock(
+            minDelay,
+            owner
+        ));
+        ScriptTools.switchOwner(pasInstance.beamState, deployer, owner);
+    }
+
+    function deployMom(
+        address owner,
+        address beamState,
+        address timelock
+    ) internal returns (address mom) {
+        mom = address(new PASMom(
+            beamState,
+            timelock
+        ));
+        PASMom(mom).setOwner(owner);
+    }
+}