feat(contracts): draft minimal proxy pattern with immutable args implementation

Author: 0xjei

packages/contracts/contracts/src/core/checker/AdvancedChecker.sol

@@ -7,9 +7,7 @@ import {Checker} from "./Checker.sol";
 /// @title AdvancedChecker.
 /// @notice Multi-phase validation checker with pre, main, and post checks.
 /// @dev Base contract for implementing complex validation logic with configurable check phases.
-abstract contract AdvancedChecker is IAdvancedChecker, Checker {
-    constructor(address[] memory _verifiers) Checker(_verifiers) {}
-
+abstract contract AdvancedChecker is Checker, IAdvancedChecker {
     /// @notice Entry point for validation checks.
     /// @param subject Address to validate.
     /// @param evidence Validation data.

packages/contracts/contracts/src/core/checker/BaseChecker.sol

@@ -9,8 +9,6 @@ import {Checker} from "./Checker.sol";
 /// @dev Provides a standardized interface for implementing custom validation logic
 /// through the internal _check method.
 abstract contract BaseChecker is Checker, IBaseChecker {
-    constructor(address[] memory _verifiers) Checker(_verifiers) {}
-
     /// @notice Validates evidence for a given subject address.
     /// @dev External view function that delegates to internal _check implementation.
     /// @param subject Address to validate.

packages/contracts/contracts/src/core/checker/Checker.sol

@@ -2,39 +2,20 @@
 pragma solidity ^0.8.20;
 
 import {IChecker} from "../interfaces/IChecker.sol";
+import {LibClone} from "solady/src/utils/LibClone.sol";
 
-/// @title Checker
-/// @notice Abstract base contract for implementing attribute verification logic.
-/// @dev Provides infrastructure to orchestrate third-party verifiers for single checks.
+// @todo refactoring & comments
 abstract contract Checker is IChecker {
-    /// @notice Array of third-party contract addresses used for verification.
-    /// @dev Can include existing and already deployed Checkers, NFTs, MACI polls, and/or any other contract
-    /// that provides evidence verification. These contracts should already be deployed and operational.
-    address[] internal verifiers;
+    bool private _initialized;
 
-    /// @notice Initializes the Checker with an optional list of third-party verification contracts.
-    /// @param _verifiers Array of addresses for existing verification contracts.
-    /// @dev Each address should point to a deployed contract that will be consulted during verification.
-    /// This array can remain empty if there's no reliance on external verifiers.
-    constructor(address[] memory _verifiers) {
-        verifiers = _verifiers;
-    }
+    error AlreadyInitialized();
 
-    /// @notice Retrieves the verifier address at a specific index.
-    /// @param index The index of the verifier in the array.
-    /// @return The address of the verifier at the specified index.
-    /// @custom:throws VerifierNotFound if no address have been specified at given index.
-    function getVerifierAtIndex(uint256 index) external view returns (address) {
-        return _getVerifierAtIndex(index);
+    function initialize() public virtual {
+        if (_initialized) revert AlreadyInitialized();
+        _initialized = true;
     }
 
-    /// @notice Internal implementation of verifier address retrieval at a specific index.
-    /// @param index The index of the verifier in the array.
-    /// @return The address of the verifier at the specified index.
-    /// @custom:throws VerifierNotFound if no address have been specified at given index.
-    function _getVerifierAtIndex(uint256 index) internal view returns (address) {
-        if (index >= verifiers.length) revert VerifierNotFound();
-
-        return verifiers[index];
+    function _getAppendedBytes() internal view returns (bytes memory) {
+        return LibClone.argsOnClone(address(this));
     }
 }

packages/contracts/contracts/src/core/interfaces/IAdvancedChecker.sol

@@ -1,8 +1,6 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.20;
 
-import {IChecker} from "./IChecker.sol";
-
 /// @title Check.
 /// @notice Defines validation phases in the AdvancedChecker system.
 /// @custom:values PRE - Pre-condition validation.
@@ -28,7 +26,7 @@ struct CheckStatus {
 /// @title IAdvancedChecker.
 /// @notice Defines multi-phase validation system interface.
 /// @dev Implement this for custom validation logic with pre/main/post checks.
-interface IAdvancedChecker is IChecker {
+interface IAdvancedChecker {
     /// @notice Validates subject against specified check type.
     /// @param subject Address to validate.
     /// @param evidence Validation data.

packages/contracts/contracts/src/core/interfaces/IChecker.sol

@@ -6,10 +6,4 @@ pragma solidity ^0.8.20;
 interface IChecker {
     /// @notice Core error conditions.
     error VerifierNotFound();
-
-    /// @notice Retrieves the verifier address at a specific index.
-    /// @param index The index of the verifier in the array.
-    /// @return The address of the verifier at the specified index.
-    /// @custom:throws VerifierNotFound if no address have been specified at given index.
-    function getVerifierAtIndex(uint256 index) external view returns (address);
 }

packages/contracts/contracts/src/core/interfaces/IPolicy.sol

@@ -14,6 +14,7 @@ interface IPolicy {
     error TargetOnly();
     error TargetAlreadySet();
     error AlreadyEnforced();
+    error AlreadyInitialized();
 
     /// @notice Returns policy trait identifier.
     /// @return Policy trait string (e.g., "Semaphore").

packages/contracts/contracts/src/core/policy/AdvancedPolicy.sol

@@ -1,97 +1,80 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.20;
 
-import {Policy} from "./Policy.sol";
 import {IAdvancedPolicy, Check} from "../interfaces/IAdvancedPolicy.sol";
 import {AdvancedChecker, CheckStatus} from "../checker/AdvancedChecker.sol";
+import {Policy} from "./Policy.sol";
+import {LibClone} from "solady/src/utils/LibClone.sol";
 
-/// @title AdvancedPolicy.
+/// @title AdvancedPolicy
 /// @notice Implements advanced policy checks with pre, main, and post validation stages.
-/// @dev Extends Policy contract with multi-stage validation capabilities.
+/// @dev Extends Policy with multi-stage validation. Now clone-friendly with `initialize()`.
 abstract contract AdvancedPolicy is IAdvancedPolicy, Policy {
-    /// @notice Reference to the validation checker contract.
-    /// @dev Immutable to ensure checker cannot be changed after deployment.
-    AdvancedChecker public immutable ADVANCED_CHECKER;
+    /// @notice Reference to the validation checker contract. Stored, not immutable.
+    AdvancedChecker public ADVANCED_CHECKER;
 
     /// @notice Controls whether pre-condition checks are required.
-    bool public immutable SKIP_PRE;
+    bool public SKIP_PRE;
 
     /// @notice Controls whether post-condition checks are required.
-    bool public immutable SKIP_POST;
+    bool public SKIP_POST;
 
     /// @notice Controls whether main check can be executed multiple times.
-    bool public immutable ALLOW_MULTIPLE_MAIN;
+    bool public ALLOW_MULTIPLE_MAIN;
 
     /// @notice Tracks validation status for each subject per target.
-    /// @dev Maps subject => CheckStatus.
     mapping(address => CheckStatus) public enforced;
 
-    /// @notice Initializes contract with an AdvancedChecker instance and checks configs.
-    /// @param _advancedChecker Address of the AdvancedChecker contract.
-    /// @param _skipPre Skip pre-condition validation.
-    /// @param _skipPost Skip post-condition validation.
-    /// @param _allowMultipleMain Allow multiple main validations.
-    constructor(AdvancedChecker _advancedChecker, bool _skipPre, bool _skipPost, bool _allowMultipleMain) {
-        ADVANCED_CHECKER = _advancedChecker;
-        SKIP_PRE = _skipPre;
-        SKIP_POST = _skipPost;
-        ALLOW_MULTIPLE_MAIN = _allowMultipleMain;
+    /**
+     * @notice Initialize function for minimal proxy clones.
+     *         Decodes appended bytes for (AdvancedChecker, skipPre, skipPost, allowMultipleMain).
+     */
+    function initialize() public virtual override {
+        // 1. Call Policy’s initialize to set ownership and `_initialized`.
+        super.initialize();
+
+        // 2. Decode the appended bytes for the advanced config.
+        bytes memory data = _getAppendedBytes();
+        (address sender, address advCheckerAddr, bool skipPre, bool skipPost, bool allowMultipleMain) = abi.decode(
+            data,
+            (address, address, bool, bool, bool)
+        );
+
+        _transferOwnership(sender);
+
+        ADVANCED_CHECKER = AdvancedChecker(advCheckerAddr);
+        SKIP_PRE = skipPre;
+        SKIP_POST = skipPost;
+        ALLOW_MULTIPLE_MAIN = allowMultipleMain;
     }
 
-    /// @notice Enforces policy check for a subject.
-    /// @dev Only callable by target contract.
-    /// @param subject Address to validate.
-    /// @param evidence Validation data.
-    /// @param checkType Type of check (PRE, MAIN, POST).
+    /// @notice Enforces a policy check for a subject, handling multi-stage logic.
+    /// @dev Only callable by the target contract.
     function enforce(address subject, bytes[] calldata evidence, Check checkType) external override onlyTarget {
         _enforce(subject, evidence, checkType);
     }
 
-    /// @notice Internal check enforcement logic.
-    /// @dev Handles different check types and their dependencies.
-    /// @param subject Address to validate.
-    /// @param evidence Validation data.
-    /// @param checkType Type of check to perform.
-    /// @custom:throws CannotPreCheckWhenSkipped If PRE check attempted when skipped.
-    /// @custom:throws CannotPostCheckWhenSkipped If POST check attempted when skipped.
-    /// @custom:throws UnsuccessfulCheck If validation fails.
-    /// @custom:throws AlreadyEnforced If check was already completed.
-    /// @custom:throws PreCheckNotEnforced If PRE check is required but not done.
-    /// @custom:throws MainCheckNotEnforced If MAIN check is required but not done.
-    /// @custom:throws MainCheckAlreadyEnforced If multiple MAIN checks not allowed.
+    /// @notice Internal check enforcement logic for advanced multi-stage checks.
     function _enforce(address subject, bytes[] calldata evidence, Check checkType) internal {
         if (!ADVANCED_CHECKER.check(subject, evidence, checkType)) {
             revert UnsuccessfulCheck();
         }
 
         CheckStatus storage status = enforced[subject];
 
-        // Handle PRE check.
         if (checkType == Check.PRE) {
             if (SKIP_PRE) revert CannotPreCheckWhenSkipped();
-            if (status.pre) {
-                revert AlreadyEnforced();
-            }
-
+            if (status.pre) revert AlreadyEnforced();
             status.pre = true;
         } else if (checkType == Check.POST) {
-            // Handle POST check.
             if (SKIP_POST) revert CannotPostCheckWhenSkipped();
-            if (status.main == 0) {
-                revert MainCheckNotEnforced();
-            }
-            if (status.post) {
-                revert AlreadyEnforced();
-            }
+            if (status.main == 0) revert MainCheckNotEnforced();
+            if (status.post) revert AlreadyEnforced();
             status.post = true;
         } else {
-            // Handle MAIN check.
-            if (!SKIP_PRE && !status.pre) {
-                revert PreCheckNotEnforced();
-            }
-            if (!ALLOW_MULTIPLE_MAIN && status.main > 0) {
-                revert MainCheckAlreadyEnforced();
-            }
+            // MAIN check
+            if (!SKIP_PRE && !status.pre) revert PreCheckNotEnforced();
+            if (!ALLOW_MULTIPLE_MAIN && status.main > 0) revert MainCheckAlreadyEnforced();
             status.main += 1;
         }
 

packages/contracts/contracts/src/core/policy/BasePolicy.sol

@@ -4,54 +4,54 @@ pragma solidity ^0.8.20;
 import {IBasePolicy} from "../interfaces/IBasePolicy.sol";
 import {Policy} from "./Policy.sol";
 import {BaseChecker} from "../checker/BaseChecker.sol";
+import {LibClone} from "solady/src/utils/LibClone.sol";
 
 /// @title BasePolicy
 /// @notice Abstract base contract for implementing specific policy checks.
 /// @dev Inherits from Policy and implements IBasePolicy interface.
-///
-/// Provides core functionality for enforcing policy checks through a BaseChecker
-/// contract. Each specific policy implementation should extend this contract
-/// and implement its custom checking logic.
+///      Now uses an `initialize()` function for minimal proxy clones.
 abstract contract BasePolicy is Policy, IBasePolicy {
     /// @notice Reference to the BaseChecker contract used for validation.
-    /// @dev Immutable to ensure checker cannot be changed after deployment.
-    BaseChecker public immutable BASE_CHECKER;
+    /// @dev Stored in normal storage (not immutable) so it can be set in `initialize()`.
+    BaseChecker public BASE_CHECKER;
 
     /// @notice Tracks enforcement status for each subject per target.
-    /// @dev Maps subject => enforcement status.
     mapping(address => bool) public enforced;
 
-    /// @notice Initializes the contract with a BaseChecker instance.
-    /// @param _baseChecker Address of the BaseChecker contract.
-    /// @dev The BaseChecker address cannot be changed after deployment.
-    constructor(BaseChecker _baseChecker) {
-        BASE_CHECKER = _baseChecker;
+    /**
+     * @notice Initializes the contract with a BaseChecker instance, reading from appended bytes.
+     *         Replaces the old constructor-based approach.
+     */
+    function initialize() public virtual override {
+        // 1. Call the base `Policy.initialize()` to set ownership / handle `_initialized`.
+        super.initialize();
+
+        // 2. Decode the appended bytes to get the BaseChecker address (and anything else you might need).
+        bytes memory data = _getAppendedBytes();
+        (address sender, address baseCheckerAddr) = abi.decode(data, (address, address));
+
+        _transferOwnership(sender);
+
+        // 3. Store in the contract’s storage (previously `immutable`).
+        BASE_CHECKER = BaseChecker(baseCheckerAddr);
     }
 
     /// @notice External function to enforce policy checks.
     /// @dev Only callable by the target contract.
     /// @param subject Address to enforce the check on.
     /// @param evidence Additional data required for verification.
-    /// @custom:throws AlreadyEnforced if check was previously enforced.
-    /// @custom:throws UnsuccessfulCheck if the check fails.
-    /// @custom:emits Enforced when check succeeds.
     function enforce(address subject, bytes[] calldata evidence) external override onlyTarget {
         _enforce(subject, evidence);
     }
 
     /// @notice Internal implementation of enforcement logic.
-    /// @dev Performs the actual check using BASE_CHECKER.
-    /// @param subject Address to enforce the check on.
-    /// @param evidence Additional data required for verification.
-    /// @custom:throws AlreadyEnforced if already enforced for this subject.
-    /// @custom:throws UnsuccessfulCheck if BASE_CHECKER.check returns false.
     function _enforce(address subject, bytes[] memory evidence) internal {
         bool checked = BASE_CHECKER.check(subject, evidence);
 
         if (enforced[subject]) revert AlreadyEnforced();
         if (!checked) revert UnsuccessfulCheck();
 
-        enforced[subject] = checked;
+        enforced[subject] = true;
 
         emit Enforced(subject, target, evidence);
     }