@chainlink/ace 0.5.0

package/packages/policy-management/docs/CUSTOM_POLICIES_TUTORIAL.md

@@ -0,0 +1,195 @@
+# Tutorial: Creating a Custom Policy
+
+This tutorial will guide you through the process of creating your own custom policy from scratch. We will build a simple `LockoutPolicy` that blocks transactions from an address for a specified period of time.
+
+This will teach you the core principles of policy development and provide a template for your own, more complex policies.
+
+> **Note:** A clean, copy-pasteable boilerplate template is available at the end of this tutorial for you to use as a starting point.
+
+## Step 1: The Policy Contract Boilerplate
+
+Every policy must inherit from the base `Policy` contract and implement the `run` function. Let's create our file `LockoutPolicy.sol` with the basic structure.
+
+**`LockoutPolicy.sol`**
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import { Policy } from "@chainlink/policy-management/core/Policy.sol";
+import { IPolicyEngine } from "@chainlink/policy-management/interfaces/IPolicyEngine.sol";
+
+contract LockoutPolicy is Policy {
+    // Our policy's logic will go here.
+
+    function run(
+        address caller,
+        address subject,
+        bytes4 selector,
+        bytes[] calldata parameters,
+        bytes calldata context
+    ) public view virtual override returns (IPolicyEngine.PolicyResult) {
+        // Our enforcement logic will go here.
+        return IPolicyEngine.PolicyResult.Continue; // Default to Continue
+    }
+}
+```
+
+This is the simplest possible policy. It doesn't do anything yet, but it's a valid, compilable policy contract.
+
+## Step 2: Adding State and Logic
+
+Our `LockoutPolicy` needs to store two pieces of information for each locked-out address: the address itself, and the Unix timestamp when their lockout period expires. We'll use a `mapping` for this.
+
+We also need a public function that the policy owner can call to add or update a lockout.
+
+```solidity
+// ... imports ...
+
+contract LockoutPolicy is Policy {
+    mapping(address => uint256) public lockoutExpiresAt;
+
+    /// @notice The policy owner can call this to lock an address.
+    /// @param account The address to lock out.
+    /// @param duration The duration of the lockout, in seconds.
+    function setLockout(address account, uint256 duration) public onlyOwner {
+        lockoutExpiresAt[account] = block.timestamp + duration;
+    }
+
+    function run(
+        address caller,
+        address, // subject
+        bytes4, // selector
+        bytes[] calldata, // parameters
+        bytes calldata // context
+    ) public view virtual override returns (IPolicyEngine.PolicyResult) {
+        // We only care about the original sender of the transaction.
+        if (lockoutExpiresAt[caller] > block.timestamp) {
+            // If the sender's lockout period is still active, reject.
+             revert IPolicyEngine.PolicyRejected("LockoutPolicy: Address is locked out");
+        }
+
+        // Otherwise, continue to the next policy.
+        return IPolicyEngine.PolicyResult.Continue;
+    }
+}
+```
+
+Our policy now has logic! It checks if the `sender` of the transaction is trying to transact before their `lockoutExpiresAt` timestamp has been reached. If they are, it rejects the transaction. Otherwise, it takes no action and lets the `PolicyEngine` continue to the next policy.
+
+## Step 3: Input Validation (A Critical Best Practice)
+
+What if our policy needed to check a parameter from the transaction data? For example, what if we wanted to lock out the `recipient` of a transfer instead of the `sender`?
+
+The policy would receive the recipient's address in the `parameters` array. It is a **critical best practice to always validate the inputs** your policy receives.
+
+Let's modify our `run` function to expect the `recipient` as a parameter and add the necessary `require` check.
+
+```solidity
+// ...
+    function run(
+        address, // caller
+        address, // subject
+        bytes4, // selector
+        bytes[] calldata parameters,
+        bytes calldata // context
+    ) public view virtual override returns (IPolicyEngine.PolicyResult) {
+        // BEST PRACTICE: Always validate your expected inputs.
+        // This prevents reverts and ensures your policy is used correctly.
+        require(parameters.length == 1, "LockoutPolicy: Expected 1 parameter");
+
+        // Decode the address from the parameters array.
+        address recipient = abi.decode(parameters[0], (address));
+
+        if (lockoutExpiresAt[recipient] > block.timestamp) {
+            revert IPolicyEngine.PolicyRejected("LockoutPolicy: Address is locked out");
+        }
+
+        return IPolicyEngine.PolicyResult.Continue;
+    }
+// ...
+```
+
+This `require` statement makes our policy more robust. It provides a clear error message if the policy is ever misconfigured in the `PolicyEngine` without the required parameter, which makes debugging much easier.
+
+## Step 4: Using Your Custom Policy
+
+Now your `LockoutPolicy` is complete. Using it follows the same pattern as any pre-built policy.
+
+In your deployment script:
+
+1.  **Deploy it**: `LockoutPolicy lockoutPolicy = new LockoutPolicy();`
+2.  **Initialize it**: `lockoutPolicy.initialize(address(policyEngine), OWNER_ADDRESS, new bytes(0));`
+    > **What is the `new bytes(0)` parameter?**
+    >
+    > The third argument of the `initialize` function is a `bytes` array called `configParams`. It's a the feature for passing initial setup data to more complex policies (e.g., setting a volume limit for a [`VolumePolicy`](../src/policies/VolumePolicy.sol)). Since our `LockoutPolicy` doesn't need any initial configuration, we pass an empty byte array to explicitly provide no parameters. The `initialize` function passes these bytes to an internal `configure` function, which you can override to handle this data in your own policies.
+3.  **Add it to the engine**: To use the version of our policy that checks the `recipient`, you must specify the parameter name. Assume we have an [`ERC20TransferExtractor`](../src/extractors/ERC20TransferExtractor.sol) registered for our target function.
+
+    ```solidity
+    // Define the parameter name your policy needs
+    bytes32[] memory policyParams = new bytes32[](1);
+    policyParams[0] = keccak256("to"); // This must match the name from the Extractor
+
+    // Add the policy to the engine and specify its required parameter
+    policyEngine.addPolicy(
+        address(myContract),
+        myContract.transfer.selector,
+        address(lockoutPolicy),
+        policyParams
+    );
+    ```
+
+You can then call `lockoutPolicy.setLockout(LOCKED_ADDRESS, 3600)` to block a recipient for one hour. Any transfer to that address will be rejected.
+
+You now have a complete, secure, and reusable custom policy and the knowledge needed to create many more!
+
+## Boilerplate Template for Custom Policies
+
+Here is a clean, commented template that you can use as a starting point for your own custom policies.
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import { Policy } from "@chainlink/policy-management/core/Policy.sol";
+import { IPolicyEngine } from "@chainlink/policy-management/interfaces/IPolicyEngine.sol";
+
+contract MyCustomPolicy is Policy {
+    /**
+     * @notice Use the `configure` function to decode and store any initial
+     * setup data passed into the `configParams` of the `initialize` function.
+     */
+    // function configure(bytes calldata parameters) internal override onlyInitializing {
+    //     // Your custom initialization logic here...
+    // }
+
+    function run(
+        address caller,
+        address subject,
+        bytes4 selector,
+        bytes[] calldata parameters,
+        bytes calldata context
+    ) public view virtual override returns (IPolicyEngine.PolicyResult) {
+        // Your custom validation logic here...
+        //
+        // Based on your logic, return one of the two possible results or revert.
+
+        // Revert with PolicyRejected to definitively block the transaction.
+        // This HALTS execution and bypasses all subsequent policies.
+        // if (condition_for_rejection) {
+        //     revert IPolicyEngine.PolicyRejected("reason for rejection");
+        // }
+
+        // Return ALLOWED to definitively approve the transaction.
+        // This ALSO HALTS execution and bypasses all subsequent policies.
+        // This is powerful and should be used with care (e.g., for an admin bypass).
+        // if (condition_for_allowance) {
+        //     return IPolicyEngine.PolicyResult.Allowed;
+        // }
+
+        // Return CONTINUE if your check passes but other policies in the chain should still be executed.
+        // This is the most common return value for a passing check.
+        return IPolicyEngine.PolicyResult.Continue;
+    }
+}
+```

package/packages/policy-management/docs/POLICY_ORDERING_GUIDE.md

@@ -0,0 +1,91 @@
+# Policy Ordering Guide
+
+## Why Order Matters
+
+Policies execute sequentially in the exact order they were added to the `PolicyEngine`. The execution order is critical because:
+
+- **reverts `PolicyRejected`** - Immediately stops execution and reverts the transaction
+- **`Allowed`** - Immediately stops execution and allows the transaction (skips all remaining policies)
+- **`Continue`** - Proceeds to the next policy in the chain, or applies the default engine behavior if no more policies remain
+
+This means the position of each policy in the chain directly affects which policies get executed.
+
+## Adding Policies
+
+### `addPolicy()` - Append to End
+
+Adds a policy to the end of the existing policy chain.
+
+```solidity
+// Current chain: []
+policyEngine.addPolicy(target, selector, address(policyA), params);
+// Result: [PolicyA]
+
+policyEngine.addPolicy(target, selector, address(policyB), params);
+// Result: [PolicyA, PolicyB]
+
+policyEngine.addPolicy(target, selector, address(policyC), params);
+// Result: [PolicyA, PolicyB, PolicyC]
+```
+
+### `addPolicyAt()` - Insert at Specific Position
+
+Inserts a policy at a specific position, shifting existing policies to the right.
+
+```solidity
+// Current chain: [PolicyA, PolicyB, PolicyC]
+
+// Insert PolicyD at position 1
+policyEngine.addPolicyAt(target, selector, address(policyD), params, 1);
+// Result: [PolicyA, PolicyD, PolicyB, PolicyC]
+
+// Insert PolicyE at position 0 (first position)
+policyEngine.addPolicyAt(target, selector, address(policyE), params, 0);
+// Result: [PolicyE, PolicyA, PolicyD, PolicyB, PolicyC]
+```
+
+## Removing Policies
+
+### `removePolicy()` - Remove by Address
+
+Removes a specific policy from the chain, shifting remaining policies to maintain order.
+
+```solidity
+// Current chain: [PolicyA, PolicyB, PolicyC, PolicyD]
+
+policyEngine.removePolicy(target, selector, address(policyB));
+// Result: [PolicyA, PolicyC, PolicyD]
+
+policyEngine.removePolicy(target, selector, address(policyA));
+// Result: [PolicyC, PolicyD]
+```
+
+## Checking Current Order
+
+Use `getPolicies()` to view the current policy chain in execution order:
+
+```solidity
+address[] memory policies = policyEngine.getPolicies(target, selector);
+// Returns: [policy1Address, policy2Address, policy3Address, ...]
+// Array index 0 executes first, then index 1, then index 2, etc.
+```
+
+## Reordering Existing Policies
+
+To change the position of an existing policy:
+
+1. Remove the policy from its current position
+2. Add it back at the desired position
+
+```solidity
+// Current: [PolicyA, PolicyB, PolicyC]
+// Goal: Move PolicyC to first position
+
+// Step 1: Remove PolicyC
+policyEngine.removePolicy(target, selector, address(policyC));
+// Result: [PolicyA, PolicyB]
+
+// Step 2: Add PolicyC at position 0
+policyEngine.addPolicyAt(target, selector, address(policyC), params, 0);
+// Result: [PolicyC, PolicyA, PolicyB]
+```

package/packages/policy-management/docs/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Considerations: Policy Management
+
+The Policy Management component provides a powerful and flexible way to enforce on-chain rules, but this flexibility requires careful attention to security during implementation and administration.
+
+## 1. Policy Administration is a Critical Control
+
+The ability to add, remove, or reorder policies in the `PolicyEngine` is the most sensitive administrative power in the system. An attacker who gains control over these functions can effectively disable or bypass all compliance rules.
+
+- **Access Control:** Only highly trusted roles, such as a DAO, a multi-sig wallet, or a designated `owner`, MUST be able to call `addPolicy`, `removePolicy`, `setExtractor`, `setPolicyMapper`, and `setDefaultAllow`.
+- **Timelocks:** It is RECOMMENDED that all administrative changes to the `PolicyEngine` are passed through a timelock contract. This creates a delay between the proposal of a change and its execution, giving users time to review the change and exit the system if they do not agree with it.
+
+## 2. Policy Order Matters
+
+The `PolicyEngine` executes policies for a given function in a specific, ordered sequence. The outcome of the entire chain can change dramatically based on this order.
+
+- **`Allowed` as a Bypass:** A policy that returns `Allowed` will immediately halt execution and bypass all subsequent policies in the chain. For this reason, permissive policies (like a `BypassPolicy` for admins) should be placed with extreme care, typically at the beginning of the policy chain.
+- **Ordering for Restriction:** Restrictive policies should generally be placed before more lenient ones. For example, a `RejectPolicy` for a hard-coded denylist should come before a `VolumePolicy` to ensure the denied user cannot transact at all.
+
+## 3. Trust in Policy, Extractor, and Mapper Contracts
+
+The `PolicyEngine` delegates trust to the individual `Policy`, `Extractor`, and `Mapper` contracts it is configured to use. A vulnerability in any one of these components can compromise the entire system.
+
+- **Policy Trust:** Malicious or poorly written policies can introduce vulnerabilities. Only install trusted, audited policies.
+- **`postRun` State Changes:** The `postRun` function on a policy can modify state. This is a powerful feature that could be used for malicious purposes if the policy is not trustworthy (e.g., draining funds, changing ownership).
+- **Extractor/Mapper Trust:** The `PolicyEngine` relies on `Extractors` to correctly and honestly parse transaction data. If an extractor is compromised or misrepresents data, policies may make decisions based on false information, potentially leading to a bypass. For example, an extractor could lie about the `value` of a transfer to circumvent a `VolumePolicy`.
+
+## 4. External Call Risks in Policy Logic
+
+Policies that make external calls during execution can introduce certain risks, though the specific risks depend on whether the policy functions are `view` or state-changing.
+
+- **External Calls in Policies:** Many policies make external calls during their `run()` function execution. Examples include:
+  - Data source queries (e.g., `SanctionsPolicy` calling `dataRegistry.getDataSource()` and `sanctionsList.isSanctioned()`)
+  - Identity verification (e.g., `CredentialRegistryIdentityValidatorPolicy` calling multiple registry contracts)
+  - Price feeds, oracles, or other external data sources
+- **Risks for `view` Policy Functions:** Since most policy `run()` functions are `view` (read-only), traditional reentrancy attacks are **not possible** because no state can be modified. However, other risks exist:
+  - **Denial of Service** - malicious external contracts could revert or consume excessive gas
+  - **Inconsistent reads** - external contract state could change between multiple calls within the same policy
+  - **Gas exhaustion** - deep call chains could cause transaction failures
+- **Risks for State-Changing Policy Functions:** Policies with non-view functions (like `postRun()`) could be vulnerable to traditional reentrancy if they make external calls and modify state
+- **Architectural Considerations:** Since protected contracts are **decoupled** from policy logic and policies can be changed dynamically:
+  - **Protected contract developers** cannot predict which policies will be applied to their functions
+  - **Policy administrators** bear the responsibility for ensuring safe policy combinations
+  - **External call risks** should be considered at the policy composition level, not forced onto every protected function
+- **Mitigation Strategies:**
+  - **Use trusted external contracts** - only interact with well-established, audited external contracts in policy logic to minimize DoS and manipulation risks
+  - **Implement proper error handling** - ensure policies gracefully handle external contract failures rather than causing transaction reverts
+  - **Consider gas limits** - external calls in policies consume gas and could cause transaction failures if gas limits are exceeded
+  - **For non-view policies** - if a policy's `postRun()` or other functions modify state and make external calls, consider reentrancy protection
+  - **Policy administrators should assess risk** - when adding policies with external calls, evaluate the trustworthiness of the external contracts being called
+
+## 5. `context` Handling and Race Conditions
+
+The `context` field in the `PolicyEngine.Payload` is a powerful feature for passing arbitrary data, but it must be managed carefully to avoid race conditions and incorrect usage.
+
+- **Context is Per-Sender, Not Per-Transaction:** The standard implementation of `PolicyProtected` stores context in a mapping (`sender` => `context`). It is **not** automatically cleared after every transaction. If context is set but not consumed in the same transaction by a protected method, the stale context may be incorrectly reused by a subsequent call from the same sender.
+- **Atomic Operations Recommended:** To mitigate this, it is **strongly recommended** to set and consume `context` within the same atomic transaction. The caller should first call `setContext(bytes)` and then immediately call the protected function. The `runPolicy` modifier will then consume the context and clear it.
+- **Re-entrancy & Multi-User Scenarios:** In contracts that can be used by multiple users (like relayers or governance contracts), context from one user could potentially be overwritten by another before it is consumed. Implementations must ensure that context cannot be mismatched, especially in scenarios involving re-entrancy.

package/packages/policy-management/src/core/Policy.sol

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.26;
+
+import {IPolicy} from "../interfaces/IPolicy.sol";
+import {IPolicyEngine} from "../interfaces/IPolicyEngine.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+import {ERC165Upgradeable} from "@openzeppelin/contracts-upgradeable/utils/introspection/ERC165Upgradeable.sol";
+
+abstract contract Policy is Initializable, OwnableUpgradeable, ERC165Upgradeable, IPolicy {
+  error Unauthorized();
+
+  /// @custom:storage-location erc7201:policy-management.Policy
+  struct PolicyStorage {
+    address policyEngine;
+  }
+
+  // keccak256(abi.encode(uint256(keccak256("policy-management.Policy")) - 1)) &
+  // ~bytes32(uint256(0xff))
+  // solhint-disable-next-line const-name-snakecase
+  bytes32 private constant PolicyStorageLocation = 0xe4b9805cdebef99d9d38a3fed61079cbd4f3c0d610c4396bdc28a2ed8ad07100;
+
+  function _getPolicyStorage() private pure returns (PolicyStorage storage $) {
+    // solhint-disable-next-line no-inline-assembly
+    assembly {
+      $.slot := PolicyStorageLocation
+    }
+  }
+
+  constructor() {
+    _disableInitializers();
+  }
+
+  modifier onlyPolicyEngine() {
+    if (msg.sender != _getPolicyStorage().policyEngine) {
+      revert Unauthorized();
+    }
+    _;
+  }
+
+  /**
+   * @notice Initializes the policy contract.
+   * @dev This function MUST be called immediately after deployment (or via proxy initializer),
+   * setting up the policy with the address of the policy engine, initial ownership, and
+   * any configuration parameters required by the policy.
+   * @param policyEngine The address of the policy engine that will invoke this policy.
+   * @param initialOwner The address that will be assigned as the initial owner of the policy contract.
+   * @param configParams Arbitrary encoded configuration parameters to initialize the policy logic.
+   */
+  function initialize(
+    address policyEngine,
+    address initialOwner,
+    bytes calldata configParams
+  )
+    public
+    virtual
+    initializer
+  {
+    __Policy_init(policyEngine, initialOwner);
+    configure(configParams);
+  }
+
+  // solhint-disable-next-line no-empty-blocks
+  function configure(bytes calldata parameters) internal virtual onlyInitializing {}
+
+  function __Policy_init(address policyEngine, address initialOwner) internal onlyInitializing {
+    __Policy_init_unchained(policyEngine);
+    __Ownable_init(initialOwner);
+    __ERC165_init();
+  }
+
+  function __Policy_init_unchained(address policyEngine) internal onlyInitializing {
+    _getPolicyStorage().policyEngine = policyEngine;
+  }
+
+  /// @inheritdoc IPolicy
+  // solhint-disable-next-line no-empty-blocks
+  function onInstall(bytes4 /*selector*/ ) public virtual override onlyPolicyEngine {}
+
+  /// @inheritdoc IPolicy
+  // solhint-disable-next-line no-empty-blocks
+  function onUninstall(bytes4 /*selector*/ ) public virtual override onlyPolicyEngine {}
+
+  function run(
+    address caller,
+    address subject,
+    bytes4 selector,
+    bytes[] calldata parameters,
+    bytes calldata context
+  )
+    public
+    view
+    virtual
+    override
+    returns (IPolicyEngine.PolicyResult);
+
+  function postRun(
+    address, /*caller*/
+    address, /*subject*/
+    bytes4, /*selector*/
+    bytes[] calldata, /*parameters*/
+    bytes calldata /*context*/
+  )
+    public
+    virtual
+    override
+    onlyPolicyEngine
+  // solhint-disable-next-line no-empty-blocks
+  {}
+
+  /**
+   * @dev See {ERC165-supportsInterface}.
+   */
+  function supportsInterface(bytes4 interfaceId)
+    public
+    view
+    virtual
+    override(ERC165Upgradeable, IERC165)
+    returns (bool)
+  {
+    return interfaceId == type(IPolicy).interfaceId || super.supportsInterface(interfaceId);
+  }
+}