@chainlink/ace 0.5.0

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

@@ -0,0 +1,290 @@
+# API Guide: Policy Management
+
+This guide provides practical, task-oriented examples for the most common operations you'll perform with the Policy Management component.
+
+## 1. Protecting a Contract Function
+
+To protect a smart contract function with the policy system, you must perform two steps:
+
+1.  In your contract's code, add the `runPolicy` modifier to the function.
+2.  Connect your contract instance to a `PolicyEngine` instance.
+
+### Step 1.1: Applying the `runPolicy` Modifier
+
+In your contract, import `PolicyProtected`, inherit from it, and add `runPolicy` to any function you want to secure.
+
+```solidity
+import { PolicyProtected } from "@chainlink/policy-management/core/PolicyProtected.sol";
+
+contract MyGuardedContract is PolicyProtected {
+    event ActionCompleted(address indexed caller);
+
+    // This function is now protected by the Policy Engine.
+    function protectedAction() public runPolicy {
+        emit ActionCompleted(msg.sender);
+    }
+
+    function unprotectedAction() public {
+        // This function is not protected and can be called freely.
+    }
+}
+```
+
+### Step 1.2: Connecting the Policy Engine
+
+After deploying your contract, you must attach it to a `PolicyEngine`. This is typically done in the contract's `initialize` function.
+
+Here is how you would write the deployment script code:
+
+```solidity
+// --- In your deployment script ---
+PolicyEngine policyEngine = new PolicyEngine();
+bool defaultAllow = true;
+policyEngine.initialize(defaultAllow, address(this)); // Recommended default
+
+MyGuardedContract myContract = new MyGuardedContract();
+
+// The initialize function calls __PolicyProtected_init to set the engine
+myContract.initialize(OWNER_ADDRESS, address(policyEngine));
+```
+
+## 2. Configuring Policies for a Function
+
+Once the engine is attached, you can add one or more policies to any protected function. A policy can either be self-contained or it can be designed to receive parameters extracted from the function call.
+
+### Step 2.1: Adding a Policy Without Parameters
+
+**The Goal:** You want to add a policy that does not require any data from the function it is protecting (e.g., checking the `msg.sender` against an internal access list).
+
+**The Action:** In your deployment script, deploy the policy and use `policyEngine.addPolicy()`. The final argument, `policyParameterNames`, will be an empty array.
+
+```solidity
+// --- In your deployment script ---
+
+// Deploy a policy that doesn't need parameters, like OnlyOwnerPolicy
+OnlyOwnerPolicy onlyOwnerPolicy = new OnlyOwnerPolicy();
+onlyOwnerPolicy.initialize(address(policyEngine), OWNER_ADDRESS, "");
+
+// Get the function selector
+bytes4 selector = myContract.protectedAction.selector;
+
+// Add the policy to the engine's registry for that function
+policyEngine.addPolicy(
+    address(myContract),      // The target contract
+    selector,                 // The function selector
+    address(onlyOwnerPolicy), // The policy contract address
+    new bytes32[](0)          // An empty array for parameter names
+);
+```
+
+### Step 2.2: Adding a Policy That Requires Parameters
+
+**The Goal:** You want to add a policy that makes a decision based on the arguments of the function call (e.g., checking the `value` of an ERC20 `transfer`).
+
+**The Actions:** This is a two-step process in your deployment script.
+
+1.  First, you must register an `Extractor` contract that knows how to parse the parameters for that function's signature.
+2.  Second, when you call `addPolicy`, you must specify which of the extracted parameters your policy needs.
+
+Here is how you would write the deployment script code:
+
+```solidity
+// --- In your deployment script ---
+
+// Action 1: Set the Extractor for the transfer function
+ERC20TransferExtractor transferExtractor = new ERC20TransferExtractor();
+bytes4 transferSelector = myToken.transfer.selector;
+policyEngine.setExtractor(transferSelector, address(transferExtractor));
+
+// Action 2: Add a policy that uses an extracted parameter
+VolumePolicy volumePolicy = new VolumePolicy();
+// ... initialize volumePolicy with a volume limit ...
+
+// Create a list of the parameter names this policy needs.
+// These names MUST match the names defined in the ERC20TransferExtractor.
+bytes32[] memory policyParams = new bytes32[](1);
+policyParams[0] = transferExtractor.PARAM_VALUE(); // e.g., keccak256("value")
+
+// Add the policy and specify the parameters it requires
+policyEngine.addPolicy(
+    address(myToken),
+    transferSelector,
+    address(volumePolicy),
+    policyParams
+);
+```
+
+The `PolicyEngine` will now automatically call the `ERC20TransferExtractor`, find the `value` parameter, and pass it to the `VolumePolicy` for every `transfer` call.
+
+### Step 2.3: Reusing a Policy on a Different Function
+
+A powerful feature of the system is policy reuse. You can apply the same policy contract to multiple different functions, even if those functions have different parameters.
+
+**The Goal:** Imagine you have a [`SanctionsPolicy`](../../../getting_started/advanced/SanctionsPolicy.sol) already checking the `to` address on `transfer` calls. Now, you also want to block minting directly to a sanctioned address.
+
+**The Action:** You will call `addPolicy` again, this time targeting the `mint` selector. You will provide the name of the parameter from the `mint` function's extractor that corresponds to the address you want to check.
+
+```solidity
+// --- In your deployment script ---
+
+// Assume `sanctionsPolicy` and `mintBurnExtractor` are already deployed.
+
+// 1. Define WHICH parameter the SanctionsPolicy needs for THIS attachment.
+//    The mint function's extractor calls the recipient parameter "account".
+bytes32[] memory mintSanctionsParams = new bytes32[](1);
+mintSanctionsParams[0] = mintBurnExtractor.PARAM_ACCOUNT(); // This is keccak256("account")
+
+// 2. Add the SAME sanctionsPolicy to the MINT selector.
+policyEngine.addPolicy(
+    address(myToken),
+    myToken.mint.selector,     // Applying to the MINT function
+    address(sanctionsPolicy),  // Re-using the same deployed policy instance
+    mintSanctionsParams        // Specifying the "account" parameter is needed here
+);
+```
+
+The same `sanctionsPolicy` instance now protects both the `transfer` and `mint` functions, receiving the correct address to check from two different extractors, all configured through the `PolicyEngine`.
+
+## 3. Setting a Default Result
+
+**The Goal:** You want to define the engine's behavior for the case where a transaction passes through all of a function's policies without any of them returning a definitive `Allowed` or reverting `PolicyRejected`.
+
+**The Recommendation:** For most development and production scenarios, it is **recommended to set the default to `Allowed`**.
+
+**The Action:** In your deployment script, call `policyEngine.setDefaultPolicyAllow()`.
+
+```solidity
+// --- In your deployment script ---
+
+// Set the default result for the entire engine.
+policyEngine.setDefaultPolicyAllow(true);
+```
+
+### Rationale and Alternative Approaches
+
+There are two primary philosophies for the default behavior of a policy system.
+
+1.  **Default `Allowed` is `true` (Recommended):**
+
+    - **Pros:** This approach maintains the regular, expected behavior of your contract's functions until you decide which specific protections are required. It allows you to start with a working system and progressively layer on restrictions (reject policies that revert) as needed.
+    - **Cons:** You must be diligent in protecting all new, sensitive functions. If you add a protected function but forget to add a policy, it will be open by default.
+
+2.  **Default `Allowed` is `false` (Alternative "Fail-Safe" Approach):**
+    - **Pros:** This is a more aggressive security posture. It ensures that no transaction can pass unless a policy explicitly permits it, which prevents new or misconfigured functions from being accidentally exposed.
+    - **Cons:** This model forces you to have at least one policy in every chain that returns `Allowed`, which can add complexity.
+
+## 4. Using the `context` Parameter
+
+**The Goal:** You need to pass arbitrary, transaction-specific data (like an offchain signature or Merkle proof) to a policy for validation.
+
+**The Actions:** There are two methods to achieve this, depending on your use case. The recommended method is to pass the `context` directly as a function argument.
+
+### Step 4.1: The Custom Policy (Common to Both Methods)
+
+First, write a policy that is designed to receive and decode data from the `context` argument of its `run()` function. This `SignaturePolicy` is a common example.
+
+```solidity
+// Assumes usage of OpenZeppelin's ECDSA library
+import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+import {IPolicyEngine} from "@chainlink/policy-management/interfaces/IPolicyEngine.sol";
+
+contract SignaturePolicy is Policy {
+    address public requiredSigner;
+
+    // ... constructor to set the requiredSigner ...
+
+    function run(
+        address caller,
+        address, // subject
+        bytes4, // selector
+        bytes[] calldata, // parameters
+        bytes calldata context
+    ) public view virtual override returns (IPolicyEngine.PolicyResult) {
+        require(context.length > 0, "SignaturePolicy: context cannot be empty");
+
+        // Create the same message hash that was signed offchain
+        bytes32 messageHash = keccak256(abi.encodePacked("I approve this transaction for:", caller));
+        bytes32 signedHash = ECDSA.toEthSignedMessageHash(messageHash);
+
+        address recoveredSigner = ECDSA.recover(signedHash, context);
+
+        if (recoveredSigner != requiredSigner) {
+            revert IPolicyEngine.PolicyRejected("SignaturePolicy: invalid signature");
+        }
+
+        return IPolicyEngine.PolicyResult.Continue;
+    }
+}
+```
+
+### Step 4.2: Passing Context Directly (Recommended Pattern)
+
+For your own custom functions, the cleanest and safest pattern is to pass the `context` directly as a function argument using the `runPolicyWithContext` modifier.
+
+**The Action:** Create a custom function that accepts `context` as its final argument and protect it with the `runPolicyWithContext` modifier.
+
+```solidity
+// In your custom contract...
+contract MyCustomContract is PolicyProtected {
+    // ...
+    function doSomethingSpecialWithApproval(
+        uint256 arg1,
+        bytes calldata context // The extra data is a direct argument
+    )
+        public
+        runPolicyWithContext(context) // The modifier receives the context directly
+    {
+        // Your core logic here...
+    }
+}
+
+// In your calling transaction (e.g., a script or front-end):
+// The context (e.g., a signature) is prepared offchain
+bytes memory signature = getSignatureFromOffChainService(sender);
+
+// Make a single call to the protected function
+myCustomContract.doSomethingSpecialWithApproval(123, signature);
+```
+
+This approach is recommended for new, custom functions as it is more explicit and gas-efficient.
+
+### Step 4.3: Passing Context via `setContext` (For Standard Interfaces)
+
+If you need to protect a function with a standard, unchangeable signature (like ERC20 `transfer`), you **must** use the two-step `setContext` method.
+
+**The Action:** The offchain client or calling contract must set the context for the `msg.sender` and then call the protected function within the same transaction.
+
+```solidity
+// In a test or script, using a multicall pattern:
+
+// 1. Offchain: A trusted party signs a message approving the transaction for the sender.
+//    (This signature is the `context` bytes)
+bytes memory signature = getSignatureFromOffChainService(sender);
+
+// 2. Onchain: In a single atomic transaction:
+//    a. Set the context for the sender
+myContract.setContext(signature);
+//    b. Call the protected function
+myContract.protectedAction();
+```
+
+The `PolicyProtected` contract provides the `setContext` and `clearContext` functions. After a transaction that uses `setContext`, it is the responsibility of the caller or a subsequent process to clear the context to prevent it from being reused.
+
+> **Security Note:** This method stores the context on a per-sender basis. It is **strongly recommended** to set and consume the context in the same atomic transaction to avoid potential race conditions or stale context being reused. **[Learn more about the security implications.](./SECURITY.md#4-context-handling-and-race-conditions)**
+
+## Common Design Patterns
+
+The Policy Management component enables several powerful, high-level design patterns for building robust and flexible systems.
+
+### Pattern: Securing Core Infrastructure with Policies
+
+The `PolicyEngine` is not just for protecting your main application contract (e.g., your token). You can and should use it to govern the administrative functions of the other components in your system, such as the `IdentityRegistry` and `CredentialRegistry` (learn more about the [Cross-Chain Identity](../../cross-chain-identity/README.md) component).
+
+This creates a unified, consistent security model for your entire dApp ecosystem.
+
+- **The Goal:** Ensure that only authorized addresses can add or remove credentials in the `CredentialRegistry`.
+- **The Implementation:**
+  1.  When you deploy the `CredentialRegistry`, you set its owner to be the `PolicyEngine` contract. This means all administrative actions must now pass through the engine.
+  2.  You deploy a policy, such as `OnlyAuthorizedSenderPolicy`, which maintains a list of trusted addresses (e.g., your KYC provider).
+  3.  In the `PolicyEngine`, you use `addPolicy` to apply this `OnlyAuthorizedSenderPolicy` to the administrative functions of the `CredentialRegistry` (e.g., `registerCredential`, `removeCredential`).
+  4.  **The Result:** The `CredentialRegistry` is now fully protected. No one, not even the original deployer, can manage credentials unless they are explicitly added to the authorized senders list in the policy, creating a robust and auditable separation of roles.

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

@@ -0,0 +1,173 @@
+> **Note for Developers:** This file provides a complete, auto-generated list of all functions and interfaces. For a more practical, task-oriented guide with code examples, please see the **[API Guide](API_GUIDE.md)** first.
+
+# API Reference: Policy Management
+
+This document provides the complete, formal interface specifications for the Policy Management component.
+
+## Core Interfaces
+
+### IPolicyEngine
+
+**File:** [`src/interfaces/IPolicyEngine.sol`](../src/interfaces/IPolicyEngine.sol)
+
+The `IPolicyEngine` interface defines the core functions for the central orchestrator that manages and executes policies.
+
+#### Enums and Structs
+
+```solidity
+enum PolicyResult {
+    None,
+    Allowed,
+    Continue
+}
+
+struct Parameter {
+    bytes32 name;
+    bytes value;
+}
+
+struct Payload {
+    bytes4 selector;
+    address sender;
+    bytes data;
+    bytes context;
+}
+```
+
+#### Key Functions
+
+```solidity
+interface IPolicyEngine is IERC165 {
+    function attach() external;
+    function detach() external;
+
+    function setExtractor(bytes4 selector, address extractor) external;
+    function setExtractors(bytes4[] calldata selectors, address extractor) external;
+    function getExtractor(bytes4 selector) external view returns (address);
+
+    function setPolicyMapper(address policy, address mapper) external;
+    function getPolicyMapper(address policy) external view returns (address);
+
+    function addPolicy(address target, bytes4 selector, address policy, bytes32[] calldata policyParameterNames) external;
+    function addPolicyAt(address target, bytes4 selector, address policy, bytes32[] calldata policyParameterNames, uint256 position) external;
+    function removePolicy(address target, bytes4 selector, address policy) external;
+    function getPolicies(address target, bytes4 selector) external view returns (address[] memory);
+
+    function setDefaultPolicyAllow(bool defaultAllow) external;
+    function setTargetDefaultPolicyAllow(address target, bool defaultAllow) external;
+
+    function check(Payload calldata payload) external view;
+    function run(Payload calldata payload) external;
+}
+```
+
+### IPolicy
+
+**File:** [`src/interfaces/IPolicy.sol`](../src/interfaces/IPolicy.sol)
+
+The `IPolicy` interface is the standard for all policy contracts. Each policy must implement this interface to be compatible with the `PolicyEngine`.
+
+#### Key Functions
+
+```solidity
+interface IPolicy is IERC165 {
+  function run(
+    address caller,
+    address subject,
+    bytes4 selector,
+    bytes[] calldata parameters,
+    bytes calldata context
+  ) external view returns (IPolicyEngine.PolicyResult);
+
+  function postRun(
+    address caller,
+    address subject,
+    bytes4 selector,
+    bytes[] calldata parameters,
+    bytes calldata context
+  ) external;
+
+  function onInstall(bytes4 selector) external;
+  function onUninstall(bytes4 selector) external;
+}
+```
+
+### IPolicyProtected
+
+**File:** [`src/interfaces/IPolicyProtected.sol`](../src/interfaces/IPolicyProtected.sol)
+
+The `IPolicyProtected` interface must be implemented by any contract that wishes to be protected by a `PolicyEngine`.
+
+#### Key Functions
+
+```solidity
+interface IPolicyProtected is IERC165 {
+  function attachPolicyEngine(address policyEngine) external;
+  function getPolicyEngine() external view returns (address);
+  function setContext(bytes calldata context) external;
+  function getContext() external view returns (bytes memory);
+  function clearContext() external;
+}
+```
+
+## Helper Interfaces
+
+### IExtractor
+
+**File:** [`src/interfaces/IExtractor.sol`](../src/interfaces/IExtractor.sol)
+
+The `IExtractor` interface is the standard for contracts that parse transaction calldata into named parameters for the `PolicyEngine`.
+
+#### Key Functions
+
+```solidity
+interface IExtractor is IERC165 {
+  function extract(IPolicyEngine.Payload calldata payload) external view returns (IPolicyEngine.Parameter[] memory);
+}
+```
+
+### IMapper
+
+**File:** [`src/interfaces/IMapper.sol`](../src/interfaces/IMapper.sol)
+
+The `IMapper` interface is the standard for custom mapper contracts. A custom mapper is only needed for advanced scenarios where parameter data needs to be transformed before being passed to a policy.
+
+#### Key Functions
+
+```solidity
+interface IMapper is IERC165 {
+  function map(
+    IPolicyEngine.Parameter[] calldata extractedParameters
+  ) external view returns (bytes[] memory mappedParameters);
+}
+```
+
+## Events
+
+```solidity
+event TargetAttached(address indexed target);
+event TargetDetached(address indexed target);
+event PolicyAdded(address indexed target, bytes4 indexed selector, address policy);
+event PolicyRemoved(address indexed target, bytes4 indexed selector, address policy);
+event ExtractorSet(bytes4 indexed selector, address indexed extractor);
+event PolicyParametersSet(address indexed policy, bytes[] parameters);
+event DefaultPolicyAllowSet(bool defaultAllow);
+event TargetDefaultPolicyAllowSet(address indexed target, bool defaultAllow);
+```
+
+## Errors
+
+```solidity
+error TargetNotAttached(address target);
+error TargetAlreadyAttached(address target);
+error PolicyEngineUndefined();
+error PolicyRunRejected(bytes4 selector, address policy, string rejectReason);
+error PolicyRejected(string rejectReason);
+error PolicyMapperError(address policy, bytes errorReason);
+error PolicyRunError(bytes4 selector, address policy, bytes errorReason);
+error PolicyRunUnauthorizedError(address account);
+error PolicyPostRunError(bytes4 selector, address policy, bytes errorReason);
+error UnsupportedSelector(bytes4 selector);
+error InvalidConfiguration(string errorReason);
+error ExtractorError(bytes4 selector, address extractor, bytes errorReason);
+```

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

@@ -0,0 +1,156 @@
+# Core Concepts: Policy Management
+
+## Abstract
+
+The Policy Management component provides a modular framework for defining, executing, and managing dynamic onchain rules. By separating policy logic from core contract logic, this component allows developers to add, remove, and compose compliance and operational rules without redeploying or modifying an application's primary business logic. It provides a robust, extensible, and secure foundation for building adaptable financial applications.
+
+## Glossary of Key Terms
+
+| Term                  | Role                                                                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`PolicyProtected`** | An abstract contract that your application inherits from. It provides the `runPolicy` modifier which acts as the hook into the policy system. |
+| **`PolicyEngine`**    | The central onchain orchestrator. It holds the registry of all policies, executes them in order, and manages the default outcome.             |
+| **`Policy`**          | A self-contained, modular contract that holds a single, specific rule (e.g., checking a user's role or limiting transaction volume).          |
+| **`Extractor`**       | A helper contract that parses raw transaction `calldata` for a specific function signature and decodes it into a list of named parameters.    |
+| **`Mapper`**          | An advanced, optional helper contract used to transform or combine parameters from an `Extractor` before they are passed to a `Policy`.       |
+
+## Core Architecture
+
+The Policy Management architecture is designed to be as flexible and decoupled as possible. It is built on a few key components that work in concert to validate transactions.
+
+- **`PolicyProtected`**: The bridge between your application and the compliance engine. By inheriting from this contract and using its `runPolicy` modifier on a function, you designate that function as being subject to the rules managed by the `PolicyEngine`.
+
+- **`PolicyEngine`**: The brain of the system. For any protected function, the engine is responsible for:
+
+  1.  Calling the correct `Extractor` to parse the transaction data.
+  2.  Mapping the extracted parameters for each policy (either internally by default, or by delegating to a custom **[`Mapper`](#the-advanced-flow-custom-mappers)**).
+  3.  Executing a chain of `Policy` contracts in a defined order.
+  4.  Processing the `Allowed`, `Continue` result or `PolicyRejected` revert from each policy.
+  5.  Applying a final, default result if no policy returns a definitive `Allowed` or revert.
+
+- **`Policy`**: A modular rule. Each policy is a small, focused contract with a `run()` function that receives parameters and returns a verdict. This is where your specific business or compliance logic lives. The `Policy` can also have an optional `postRun()` function for state changes.
+
+### The Policy Flow: A Step-by-Step Breakdown
+
+The heart of the Policy Management component is the "chain of responsibility" pattern, where a transaction is passed through a series of checks before it is allowed to execute.
+
+#### Policy Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant YourContract
+    participant PolicyEngine
+    participant Extractor
+    participant Policy1
+    participant Policy2
+
+    YourContract->>PolicyEngine: 1. run(payload)
+    Note right of YourContract: payload contains<br/>{selector, sender, data, context}
+
+    PolicyEngine->>Extractor: 2. extract(payload)
+    Extractor-->>PolicyEngine: 3. Returns named parameters (Parameter[])
+
+    Note over PolicyEngine: 4. Internally maps parameters for Policy 1
+    PolicyEngine->>Policy1: 5. run(caller, subject, selector, mapped_params, context)
+
+    alt Policy 1 Returns Continue
+        Policy1-->>PolicyEngine: 6a. Returns `Continue`
+        PolicyEngine->>Policy1: 7a. postRun(...) (optional)
+
+        Note over PolicyEngine: 8a. Proceeds to next policy.<br/>Internally maps parameters for Policy 2.
+        PolicyEngine->>Policy2: 9a. run(caller, subject, selector, mapped_params, context)
+
+        alt Final Decision
+            Policy2-->>PolicyEngine: 10a. Returns `Allowed` or reverts `PolicyRejected`
+            PolicyEngine->>Policy2: 11a. postRun(...) (if not reverted)
+            PolicyEngine-->>YourContract: 12a. Allows or Reverts Transaction
+        else No More Policies
+             Policy2-->>PolicyEngine: 10b. Returns `Continue`
+             PolicyEngine->>Policy2: 11b. postRun(...)
+             Note over PolicyEngine: 12b. No policies left, applying default result.
+             PolicyEngine-->>YourContract: 13b. Allows or Reverts based on default
+        end
+
+    else Policy 1 Makes Final Decision
+        Policy1-->>PolicyEngine: 6b. Returns `Allowed` or reverts `PolicyRejected`
+        PolicyEngine->>Policy1: 7b. postRun(...) (if not reverted)
+        Note over PolicyEngine: Skips all subsequent policies
+        PolicyEngine-->>YourContract: 8b. Allows or Reverts Transaction
+    end
+```
+
+1.  **Diagram Step 1-3 — Invocation and Extraction**  
+    The protected contract invokes `PolicyEngine.run(payload)`. The engine calls the designated **Extractor** for the function selector, which decodes the calldata into a full list of named parameters.
+
+2.  **Diagram Step 4-5 — First Policy Execution**  
+    The engine's internal mapper prepares the specific parameters required by **`Policy1`**. The engine then calls `Policy1.run(...)`.
+
+3.  **Diagram Step 6-7 — Processing the Result**  
+    The diagram now shows two main paths:
+
+    - **Policy 1 makes a final decision (Path 6b):** If `Policy1` returns `Allowed` the engine calls its optional `postRun(...)` function (if not reverted) and the process stops, skipping `Policy2` entirely.
+    - **Policy 1 defers (Path 6a):** If `Policy1` returns `Continue`, the engine calls its optional `postRun(...)` function and prepares to execute the next policy in the chain.
+
+4.  **Diagram Step 8-13 — Second Policy Execution**  
+    Following Path 6a, the engine now prepares the parameters required by **`Policy2`** and calls its `run` function. The outcome of this second call (or any subsequent policy) will determine the final result, or the engine will use its default if `Policy2` also returns `Continue`.
+
+5.  **Branching Decisions & `postRun`**
+    - **reverts `PolicyRejected`**: The policy has found a definitive reason to block the transaction. The `PolicyEngine` immediately reverts the entire transaction. No `postRun` is called.
+    - **`Allowed`**: The engine then calls the policy's optional `postRun(...)` function (if implemented), which can be used to perform state changes. The engine then **skips** any remaining policies and allows the transaction.
+    - **`Continue`**: The engine calls the policy's optional `postRun(...)` function (if implemented), then moves to the next policy in the chain. If no policies remain, it applies the engine's default outcome.
+
+### The Extractor and Mapper Pattern
+
+A key design principle of the Policy Management component is the separation of concerns between **parsing data** and **enforcing rules**. This is achieved through Extractors and Mappers.
+
+#### The Default Flow (95% of Use Cases)
+
+For most scenarios, the process is simple and powerful:
+
+1.  You write an **Extractor** for a specific function signature (e.g., `ERC20TransferExtractor` for `transfer(address,uint256)`). This extractor is responsible for parsing _all_ the parameters you might need from that function's calldata (e.g., `to` and `value`). You register this one extractor for that function selector using `setExtractor`.
+
+2.  You then attach multiple **Policies** to that same function selector using `addPolicy`. The `PolicyEngine` has a built-in default mapper that works by **name matching**. When you call `addPolicy`, you provide a list of the parameter names that specific policy needs (e.g., `["to"]` for a sanctions policy, `["value"]` for a volume policy).
+
+The engine handles the rest: it calls the single extractor, gets all the parameters, and then for each policy, it provides only the subset of parameters that policy requested by name.
+
+This provides the best of both worlds: efficient data parsing (one extraction per transaction) and clean, decoupled policies.
+
+#### The Advanced Flow (Custom Mappers)
+
+A custom **Mapper** contract (`IMapper`) is only needed for rare, advanced scenarios where simple name-based mapping is not enough. This is for when you need to **transform or combine** extracted data before passing it to a policy.
+
+For example, imagine a policy that needs a `usdValue`, but the extractor only provides `tokenAmount` and `tokenPrice`. You could write a custom mapper that:
+
+1.  Takes `tokenAmount` and `tokenPrice` as input.
+2.  Multiplies them to calculate `usdValue`.
+3.  Returns the `usdValue` in the `bytes[]` array for the policy.
+
+You would then associate this custom mapper with that specific policy using `setPolicyMapper`, overriding the engine's default behavior for that policy only.
+
+### The `context` Parameter: A Flexible Data Channel
+
+Throughout the Policy Management interfaces, you will see a `bytes calldata context` parameter in functions like `run` and `postRun`. This parameter serves as a powerful, flexible data channel for passing arbitrary, transaction-specific information to your policies.
+
+It is designed for situations where the data needed for a compliance check is **not** part of the protected function's arguments and is provided by the entity that initiates the transaction.
+
+#### Common Use Cases for `context`
+
+- **Offchain Signatures:** A user signs a message offchain (e.g., approving a high-value transaction), and the front-end passes this signature into the `context`. A policy can then decode the signature and use `ecrecover` to validate it.
+- **Merkle Proofs:** To verify that an address is part of a large, dynamic allowlist stored offchain, the caller can provide a Merkle proof in the `context`. The policy would then validate this proof against a stored Merkle root.
+- **Dynamic Risk Parameters:** An integrator could pass in dynamic, offchain risk scores or session data via the `context`, allowing policies to make more nuanced decisions.
+
+#### How it Works: Two Methods for Passing Context
+
+The `PolicyProtected` contract offers two ways to pass `context` data. The recommended approach is to pass it directly as a function argument, but a two-step method is also available for compatibility with standard interfaces.
+
+1.  **The `...WithContext` Method (Recommended for Custom Functions):**
+    For your own custom functions, the cleanest, safest, and most gas-efficient pattern is to pass the context directly as an argument. The `PolicyProtected` contract provides a `runPolicyWithContext(bytes)` modifier for this purpose.
+
+    - **Pros:** Cleaner code, safer (eliminates risk of stale context), more gas-efficient (one transaction).
+    - **Cons:** Only works for custom functions where you can define the signature.
+    - **Implementation:** The function signature would look like `myFunction(arg1, arg2, bytes calldata context)`, and the modifier would be `runPolicyWithContext(context)`.
+
+2.  **The `setContext` Method (For Standard Interfaces):**
+    This method should be used when you need to protect a function with a standard, unchangeable signature (like an ERC20 `transfer`). An external caller first calls `setContext(bytes)` and then immediately calls the protected function in the same transaction. The `runPolicy` modifier automatically retrieves this `context`, includes it in the `Payload`, and clears it after the transaction.
+
+    > **Security Note:** This method stores the context on a per-sender basis. It is **strongly recommended** to set and consume the context in the same atomic transaction to avoid potential race conditions or stale context being reused. **[Learn more about the security implications.](./SECURITY.md#4-context-handling-and-race-conditions)**