@chainlink/ace 0.5.0

package/packages/policy-management/src/interfaces/IPolicyEngine.sol

@@ -0,0 +1,264 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity ^0.8.20;
+
+/**
+ * @title IPolicyEngine
+ * @dev Interface for the policy engine.
+ */
+interface IPolicyEngine {
+  /// @notice Error emitted when the target is not attached to the policy engine.
+  error TargetNotAttached(address target);
+  /// @notice Error emitted when the target is already attached to the policy engine.
+  error TargetAlreadyAttached(address target);
+  /// @notice Error emitted when the policy engine is missing or not present.
+  error PolicyEngineUndefined();
+  /// @notice Error emitted when the PolicyEngine run has been rejected by one of the polices.
+  error PolicyRunRejected(bytes4 selector, address policy, string rejectReason);
+  /// @notice Error emitted when a policy mapper results in an error.
+  error PolicyMapperError(address policy, bytes errorReason);
+  /// @notice Error emitted when an individual policy is rejecting a transaction.
+  error PolicyRejected(string rejectReason);
+  /// @notice Error emitted when the PolicyEngine run encounters an error while executing one of the policies.
+  error PolicyRunError(bytes4 selector, address policy, bytes errorReason);
+  /// @notice Error emitted when a policy run is unauthorized.
+  error PolicyRunUnauthorizedError(address account);
+  /// @notice Error emitted when a policy postRun results in an error.
+  error PolicyPostRunError(bytes4 selector, address policy, bytes errorReason);
+  /// @notice Error emitted when a policy extractor is run with an unsupported selector.
+  error UnsupportedSelector(bytes4 selector);
+  /// @notice Error emitted when a configuration is invalid.
+  error InvalidConfiguration(string errorReason);
+  /// @notice Error emitted when an extraction of parameters results in an error.
+  error ExtractorError(bytes4 selector, address extractor, bytes errorReason);
+
+  /**
+   * @notice Emitted when a target contract has attached to the policy engine.
+   * @param target The target contract.
+   */
+  event TargetAttached(address indexed target);
+
+  /**
+   * @notice Emitted when a target contract has detached from the policy engine.
+   * @param target The target contract.
+   */
+  event TargetDetached(address indexed target);
+
+  /**
+   * @notice Emitted when a policy engine run has completed successfully.
+   * @param sender The sender of the transaction.
+   * @param target The target contract that invoked the method.
+   * @param selector The selector of the method invoked on the target.
+   */
+  event PolicyRunComplete(address indexed sender, address indexed target, bytes4 indexed selector);
+
+  /**
+   * @notice Emitted when a policy is added to the policy engine.
+   * @param target The address of the target contract for which the policy was configured.
+   * @param selector The selector of the policy.
+   * @param policy The policy address.
+   */
+  event PolicyAdded(address indexed target, bytes4 indexed selector, address policy);
+
+  /**
+   * @notice Emitted when a policy is removed from the policy engine.
+   * param target The address of the target contract for which the policy was configured.
+   * @param selector The selector of the policy.
+   * @param policy The policy address.
+   */
+  event PolicyRemoved(address indexed target, bytes4 indexed selector, address policy);
+
+  /**
+   * @notice Emitted when an extractor is set for a selector.
+   * @param selector The selector.
+   * @param extractor The extractor address.
+   */
+  event ExtractorSet(bytes4 indexed selector, address indexed extractor);
+
+  /**
+   * @notice Emitted when policy parameters are set for a policy.
+   * @param policy The policy address.
+   * @param parameters The parameters for the policy.
+   */
+  event PolicyParametersSet(address indexed policy, bytes[] parameters);
+
+  /**
+   * @notice Emitted when the default policy action rule is set for the policy engine.
+   * @param defaultAllow Indicates whether to allow or reject a transaction if no policy explicitly returns an Allow
+   * or a Reject. True to allow, false to reject.
+   */
+  event DefaultPolicyAllowSet(bool defaultAllow);
+
+  /**
+   * @notice Emitted when the default policy allow rule for a target is set.
+   * @param target The target contract.
+   * @param defaultAllow Indicates whether to allow or reject a transaction if no policy explicitly returns an Allow
+   * or a Reject. True to allow, false to reject.
+   */
+  event TargetDefaultPolicyAllowSet(address indexed target, bool defaultAllow);
+
+  /**
+   * @notice The PolicyResult enum represents the possible types of success results of a policy run. When a policy
+   * should reject a transaction, it MUST revert using the `PolicyReject` error with a descriptive reject message.
+   * @param None No specific policy result, typically used as a default or uninitialized state.
+   * @param Allowed The policy allowed the run.
+   * @param Continue The policy did not reject the run and processing should continue to the next policy.
+   */
+  enum PolicyResult {
+    None,
+    Allowed,
+    Continue
+  }
+
+  /**
+   * @notice The Payload struct combines the components on which policies operate.
+   * @param selector The selector of the method being invoked on the target.
+   * @param sender The sender of the transaction.
+   * @param data The original calldata of the invoked transaction.
+   * @param context Additional information or authorization to perform the operation.
+   */
+  struct Payload {
+    bytes4 selector;
+    address sender;
+    bytes data;
+    bytes context;
+  }
+
+  /**
+   * @notice The Parameter struct contains the data of the parameters sent to policies.
+   * @param name The name of the parameter.
+   * @param value The value of the parameter.
+   */
+  struct Parameter {
+    bytes32 name;
+    bytes value;
+  }
+
+  /**
+   * @notice Attaches the calling contract to the policy engine.
+   */
+  function attach() external;
+
+  /**
+   * @notice Detaches the calling contract from the policy engine.
+   */
+  function detach() external;
+
+  /**
+   * @notice Assigns an extractor to the specified selector, enabling policies to utilize it for parameter extraction.
+   * @param selector The selector of the policy.
+   * @param extractor The extractor address.
+   */
+  function setExtractor(bytes4 selector, address extractor) external;
+
+  /**
+   * @notice Assigns an extractor to the specified selectors, enabling policies to utilize it for parameter extraction.
+   * @param selectors The selectors of the policies.
+   * @param extractor The extractor address.
+   */
+  function setExtractors(bytes4[] calldata selectors, address extractor) external;
+
+  /**
+   * @notice Gets the extractor for a given selector.
+   * @param selector The selector.
+   * @return The extractor for the selector.
+   */
+  function getExtractor(bytes4 selector) external view returns (address);
+
+  /**
+   * @notice Sets the custom policy parameter mapper for a policy.
+   * @param policy The policy address.
+   * @param mapper The mapper address, address(0) to use the default mapper.
+   */
+  function setPolicyMapper(address policy, address mapper) external;
+
+  /**
+   * @notice Gets the policy parameter mapper for a given policy.
+   * @param policy The policy address.
+   * @return The custom policy parameter mapper for the policy, address(0) if the policy uses the default mapper.
+   */
+  function getPolicyMapper(address policy) external view returns (address);
+
+  /**
+   * @notice Adds a policy to the policy engine.
+   *
+   * - Policy MUST be added to the end of the current policy list.
+   *
+   * @param target The address of the target contract for which the policy apply.
+   * @param selector The selector of the policy.
+   * @param policy The policy address.
+   * @param policyParameterNames The parameter names for the policy.
+   */
+  function addPolicy(address target, bytes4 selector, address policy, bytes32[] calldata policyParameterNames) external;
+
+  /**
+   * @notice Adds a policy to the policy engine at a specific position.
+   *
+   * @param target The address of the target contract for which the policy apply.
+   * @param selector The selector of the policy.
+   * @param policy The policy address.
+   * @param policyParameterNames The parameter names for the policy.
+   * @param position The position to add the policy at.
+   */
+  function addPolicyAt(
+    address target,
+    bytes4 selector,
+    address policy,
+    bytes32[] calldata policyParameterNames,
+    uint256 position
+  )
+    external;
+
+  /**
+   * @notice Removes a policy from the policy engine.
+   * @param target The address of the target contract for which the policy was configured.
+   * @param selector The selector of the policy.
+   * @param policy The policy address.
+   */
+  function removePolicy(address target, bytes4 selector, address policy) external;
+
+  /**
+   * @notice Gets the policies for a given selector and target.
+   *
+   * - MUST return the policies in the order they will execute.
+   * - MUST return an empty array if no policies are found.
+   *
+   * @param selector The selector of the policy.
+   * @param target The address of the target contract for which the policies are configured.
+   * @return The policies for the selector and target.
+   */
+  function getPolicies(address target, bytes4 selector) external view returns (address[] memory);
+
+  /**
+   * @notice Sets whether to allow or reject the transaction if no policy explicitly returns an Allow or a Reject.
+   * @param defaultAllow Indicates whether to allow or reject a transaction if no policy explicitly returns an Allow
+   * or a Reject. True to allow, false to reject.
+   */
+  function setDefaultPolicyAllow(bool defaultAllow) external;
+
+  /**
+   * @notice Sets whether to allow or reject the transaction if no policy explicitly returns an Allow or a Reject
+   * for a specific target.
+   * @param target The address of the target contract.
+   * @param defaultAllow Indicates whether to allow or reject a transaction if no policy explicitly returns an Allow
+   * or a Reject. True to allow, false to reject.
+   */
+  function setTargetDefaultPolicyAllow(address target, bool defaultAllow) external;
+
+  /**
+   * @notice Runs the policies for a given payload for offchain pre-validation. MUST revert on policy rejection/failure.
+   * @param payload The payload to run the policies on.
+   */
+  function check(Payload calldata payload) external view;
+
+  /**
+   * @notice Runs the policies for a given operation payload.
+   *
+   * - MUST revert on policy rejection/failure.
+   * - MUST revert if the target contract that invoked the method is not allowed. Target contract address is
+   *   obtained from the msg.sender global variable.
+   * - MUST execute policies in the order they were added or that were specified using `addPolicyAt`.
+   *
+   * @param payload The payload to run the policies on.
+   */
+  function run(Payload calldata payload) external;
+}

package/packages/policy-management/src/interfaces/IPolicyProtected.sol

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity ^0.8.20;
+
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+/**
+ * @title IPolicyProtected
+ * @dev Interface for attaching a policy engine to a smart contract.
+ */
+interface IPolicyProtected is IERC165 {
+  /**
+   * @notice Emitted when a policy engine is attached to the contract.
+   * @param policyEngine The policy engine attached.
+   */
+  event PolicyEngineAttached(address indexed policyEngine);
+
+  /**
+   * @notice Attaches a policy engine to the current contract.
+   * @param policyEngine The policy engine to attach.
+   */
+  function attachPolicyEngine(address policyEngine) external;
+
+  /**
+   * @notice Gets the policy engine attached to the current contract.
+   * @return The policy engine attached to the contract.
+   */
+  function getPolicyEngine() external view returns (address);
+
+  /**
+   * @notice Sets the context for the current transaction.
+   * @dev WARNING: The context is stored per sender and is not automatically linked to a specific transaction or
+   * function call. Ensure that context is set and consumed atomically and that race conditions or reentrancy do not
+   * result in stale or mismatched context usage.
+   * @param context The context to set.
+   */
+  function setContext(bytes calldata context) external;
+
+  /**
+   * @notice Gets the context for the current transaction.
+   * @return The context for the transaction.
+   */
+  function getContext() external view returns (bytes memory);
+
+  /**
+   * @notice Clears the context for the current transaction.
+   */
+  function clearContext() external;
+}

package/packages/policy-management/src/policies/AllowPolicy.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.26;
+
+import {IPolicyEngine} from "@chainlink/policy-management/interfaces/IPolicyEngine.sol";
+import {Policy} from "@chainlink/policy-management/core/Policy.sol";
+
+/**
+ * @title AllowPolicy
+ * @notice A policy that permits method calls if all of the addresses are on an allowlist.
+ */
+contract AllowPolicy is Policy {
+  /**
+   * @notice Emitted when an address is added to the allow list.
+   * @param account The address that was added to the allow list.
+   */
+  event AddressAllowed(address indexed account);
+
+  /**
+   * @notice Emitted when an address is removed from the allow list.
+   * @param account The address that was removed from the allow list.
+   */
+  event AddressDisallowed(address indexed account);
+
+  /// @custom:storage-location erc7201:policy-management.AllowPolicy
+  struct AllowPolicyStorage {
+    /// @notice If the address is not on this list, method calls will always be rejected.
+    mapping(address account => bool isAllowed) allowList;
+  }
+
+  // keccak256(abi.encode(uint256(keccak256("policy-management.AllowPolicy")) - 1)) & ~bytes32(uint256(0xff))
+  bytes32 private constant AllowPolicyStorageLocation =
+    0x765cab6c47f7237f7aa9342433ee5465ec3e83a263328a78226aaa7d8727a800;
+
+  function _getAllowPolicyStorage() private pure returns (AllowPolicyStorage storage $) {
+    assembly {
+      $.slot := AllowPolicyStorageLocation
+    }
+  }
+
+  /**
+   * @notice Adds the account to the allow list.
+   * @dev Throws if the account is already in the allow list.
+   * @param account The address to add to the allow list.
+   */
+  function allowAddress(address account) public onlyOwner {
+    AllowPolicyStorage storage $ = _getAllowPolicyStorage();
+    require(!$.allowList[account], "Account already in allow list");
+    $.allowList[account] = true;
+    emit AddressAllowed(account);
+  }
+
+  /**
+   * @notice Removes the account from the allow list.
+   * @dev Throws if the account is not in the allow list.
+   * @param account The address to remove from the allow list.
+   */
+  function disallowAddress(address account) public onlyOwner {
+    AllowPolicyStorage storage $ = _getAllowPolicyStorage();
+    require($.allowList[account], "Account not in allow list");
+    $.allowList[account] = false;
+    emit AddressDisallowed(account);
+  }
+
+  /**
+   * @notice Checks if the account is on the allow list.
+   * @param account The address to check.
+   * @return addressAllowed if the account is on the allow list, false otherwise.
+   */
+  function addressAllowed(address account) public view returns (bool) {
+    return _getAllowPolicyStorage().allowList[account];
+  }
+
+  /**
+   * @notice Function to be called by the policy engine to check if execution is allowed.
+   * @param parameters encoded policy parameters.
+   *        [account(address),...] List of addresses to check for present on the allow list.
+   * @return result The result of the policy check.
+   */
+  function run(
+    address, /*caller*/
+    address, /*subject*/
+    bytes4, /*selector*/
+    bytes[] calldata parameters, /*parameters*/
+    bytes calldata /*context*/
+  )
+    public
+    view
+    override
+    returns (IPolicyEngine.PolicyResult)
+  {
+    require(parameters.length >= 1, "expected at least 1 parameter");
+
+    // Gas optimization: Load storage reference once instead of calling _getAllowPolicyStorage() in each iteration
+    AllowPolicyStorage storage $ = _getAllowPolicyStorage();
+
+    for (uint256 i = 0; i < parameters.length; i++) {
+      address account = abi.decode(parameters[i], (address));
+      if (!$.allowList[account]) {
+        revert IPolicyEngine.PolicyRejected("address is not on allow list");
+      }
+    }
+    return IPolicyEngine.PolicyResult.Continue;
+  }
+}

package/packages/policy-management/src/policies/BypassPolicy.sol

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.26;
+
+import {IPolicyEngine} from "@chainlink/policy-management/interfaces/IPolicyEngine.sol";
+import {Policy} from "@chainlink/policy-management/core/Policy.sol";
+
+/**
+ * @title BypassPolicy
+ * @notice A policy that permits method calls if all of the addresses are on an allowlist, overriding and bypassing any
+ * subsequent policies in the chain.
+ */
+contract BypassPolicy is Policy {
+  /// @custom:storage-location erc7201:policy-management.BypassPolicy
+  struct BypassPolicyStorage {
+    /// @notice If the address is on this list, method calls will always be allowed.
+    mapping(address account => bool isAllowed) allowList;
+  }
+
+  // keccak256(abi.encode(uint256(keccak256("policy-management.BypassPolicy")) - 1)) & ~bytes32(uint256(0xff))
+  bytes32 private constant BypassPolicyStorageLocation =
+    0x58a84146d7d8a792905a46c0c78d69c71c1cf7909b1068f119d17e740a8cb600;
+
+  function _getBypassPolicyStorage() private pure returns (BypassPolicyStorage storage $) {
+    assembly {
+      $.slot := BypassPolicyStorageLocation
+    }
+  }
+
+  /**
+   * @notice Adds the account to the bypass list.
+   * @dev Throws if the account is already in the bypass list.
+   * @param account The address to add to the bypass list.
+   */
+  function allowAddress(address account) public onlyOwner {
+    BypassPolicyStorage storage $ = _getBypassPolicyStorage();
+    require(!$.allowList[account], "Account already in bypass list");
+    $.allowList[account] = true;
+  }
+
+  /**
+   * @notice Removes the account from the bypass list.
+   * @dev Throws if the account is not in the bypass list.
+   * @param account The address to remove from the bypass list.
+   */
+  function disallowAddress(address account) public onlyOwner {
+    BypassPolicyStorage storage $ = _getBypassPolicyStorage();
+    require($.allowList[account], "Account not in bypass list");
+    $.allowList[account] = false;
+  }
+
+  /**
+   * @notice Checks if the account is on the bypass list.
+   * @param account The address to check.
+   * @return addressAllowed if the account is on the bypass list, false otherwise.
+   */
+  function addressAllowed(address account) public view returns (bool) {
+    BypassPolicyStorage storage $ = _getBypassPolicyStorage();
+    return $.allowList[account];
+  }
+
+  /**
+   * @notice Function to be called by the policy engine to check if execution is allowed.
+   * @param parameters encoded policy parameters.
+   *        [account(address),...] List of addresses to check for present on the bypass list.
+   * @return result The result of the policy check.
+   */
+  function run(
+    address, /*caller*/
+    address, /*subject*/
+    bytes4, /*selector*/
+    bytes[] calldata parameters, /*parameters*/
+    bytes calldata /*context*/
+  )
+    public
+    view
+    override
+    returns (IPolicyEngine.PolicyResult)
+  {
+    require(parameters.length >= 1, "expected at least 1 parameter");
+    // Gas optimization: load storage reference once
+    BypassPolicyStorage storage $ = _getBypassPolicyStorage();
+    for (uint256 i = 0; i < parameters.length; i++) {
+      address account = abi.decode(parameters[i], (address));
+      if (!$.allowList[account]) {
+        return IPolicyEngine.PolicyResult.Continue;
+      }
+    }
+    return IPolicyEngine.PolicyResult.Allowed;
+  }
+}