@chainlink/ace 0.5.0

package/packages/cross-chain-identity/README.md

@@ -0,0 +1,148 @@
+> **Prerequisite: Understanding Policy Management**
+>
+> This component is designed to be securely governed by the **[Policy Management](../policy-management/README.md)** component. The following examples and guides assume you have a basic understanding of how the `PolicyEngine` and policies work. We recommend reviewing the Policy Management documentation first.
+
+# Cross-Chain Identity
+
+**A unified identity and credential management system for all EVM-compatible blockchains, secured by the Policy Management component.**
+
+Cross-Chain Identity provides a **single identity system** that works across all EVM chains. Using Cross-Chain Identifiers (**CCID**s) as unique identity anchors, you can **attach credentials** like
+KYC, AML, or custom verifications **to each CCID** once and verify them everywhere—no more maintaining separate identity systems on each chain.
+
+## Why This Matters
+
+Managing user identity and compliance credentials (like KYC/AML) across multiple blockchains is a major challenge. Without a unified system, a user's identity is tied to a single address, forcing them to re-verify for every new address and on every new chain. This is expensive, inefficient, and a terrible user experience.
+
+```solidity
+// ❌ Before: A fragmented, per-address system. A user's KYC is tied
+// to one address and doesn't apply to their other addresses.
+contract FragmentedDApp {
+    mapping(address => bool) public isKycVerified;
+
+    function sensitiveAction() public {
+        // This fails if the user calls from a different, un-verified address,
+        // even if they are the same person who completed KYC.
+        require(isKycVerified[msg.sender], "User not verified");
+        // ...
+    }
+}
+
+// ✅ After: A unified, identity-centric system. A user's credential is
+// attached to their universal identity (CCID), not just one address. Any of
+// their linked addresses can be used to pass a compliance check.
+import { PolicyProtected } from "@chainlink/policy-management/core/PolicyProtected.sol";
+
+contract UnifiedDApp is PolicyProtected {
+    function sensitiveAction() public runPolicy {
+        // The attached CredentialRegistryIdentityValidatorPolicy checks the credential
+        // associated with the msg.sender's underlying CCID.
+        // ...
+    }
+}
+```
+
+The Cross-Chain Identity component solves this with a universal **Cross-Chain Identifier (CCID)**. By attaching a credential to a user's single, persistent identity instead of a single address, that credential becomes portable and reusable across all their addresses and all EVM chains. A user verifies once and is recognized everywhere.
+
+When this system is governed by the Policy Management component, it becomes not just portable, but also dynamically upgradeable, allowing you to change your credential requirements on the fly.
+
+## How It Works: An Overview
+
+Cross-Chain Identity is built on two core pillars:
+
+1.  **[Cross-Chain Identifier (CCID)](docs/CONCEPTS.md#1-cross-chain-identifier-ccid)**: A unique `bytes32` identifier that links a user's various blockchain addresses (EVM) into a single, universal identity.
+2.  **[Credential Management](docs/CONCEPTS.md#2-credential-management)**: A standardized framework to issue, manage, and verify credentials (like KYC/AML) associated with a CCID. By attaching credentials to a CCID instead of a wallet address, they become portable across all chains.
+
+These concepts are implemented through a few key onchain contracts and offchain actors.
+
+### Core Identity Components
+
+- **`IdentityRegistry` & `CredentialRegistry`**: These two contracts are the heart of the system. The first maps user addresses to their universal CCID, and the second stores the credentials (like KYC status) associated with that CCID.
+- **Credential Issuer (Offchain Actor)**: This is a trusted entity (e.g., your KYC provider) that performs real-world verification. It has the onchain permission to create new identities in the `IdentityRegistry` and/or issue credentials to them in the `CredentialRegistry`.
+- **`CredentialRegistryIdentityValidatorPolicy`**: This is a specialized, pre-built policy that contains all the logic for checking credentials. You attach this to your application's functions to enforce your compliance rules.
+
+### The Governance Layer (Policy Management)
+
+The entire identity system is designed to be securely governed by the [Policy Management component](../policy-management/README.md).
+
+- **Protecting the Registries**: The administrative functions on the `IdentityRegistry` and `CredentialRegistry` are protected by a `PolicyEngine`. This ensures that no unauthorized changes can be made.
+- **Authorizing Issuers**: Instead of hardcoding who can manage the registries, you use a policy (like `OnlyAuthorizedSenderPolicy`) to grant a specific `Credential Issuer` the permission to call administrative functions on the `IdentityRegistry` and/or the `CredentialRegistry`.
+
+This two-layered approach provides a powerful separation of concerns: the identity components manage the data, and the policy components manage the permissions.
+
+This diagram illustrates how the components work together in the recommended, integrated pattern.
+
+```mermaid
+graph TD
+    subgraph "Offchain"
+        Issuer["Credential Issuer"]
+    end
+
+    subgraph "Onchain Application"
+        YourApp["Your dApp<br/>(PolicyProtected)"]
+    end
+
+    subgraph "Policy Management"
+        PE["PolicyEngine"]
+        IVP["CredentialRegistryIdentityValidatorPolicy"]
+        IssuancePolicy["Issuance Policy<br/>(e.g., OnlyAuthorizedSender)"]
+    end
+
+    subgraph "Cross-Chain Identity"
+        IR["IdentityRegistry"]
+        CR["CredentialRegistry"]
+    end
+
+    Issuer -- "1- Issues Credential" --> CR
+    Issuer -- "1- Creates Identity" --> IR
+    CR -- "is protected by" --> PE
+    IR -- "is protected by" --> PE
+    PE -- "uses" --> IssuancePolicy
+
+    YourApp -- "2- User calls protected function" --> PE
+    PE -- "3- Validates user via" --> IVP
+    IVP -- "4- Reads from" --> IR
+    IVP -- "4- Reads from" --> CR
+```
+
+**Key Benefits**:
+
+- **Cross-Chain Consistency**: Verify credentials issued on any EVM chain.
+- **Secure by Design**: All administrative actions on the identity registries are governed by onchain policies.
+- **Role Separation**: Clearly separates the role of the credential issuer from the application owner.
+- **Dynamic & Upgradeable**: Update your verification requirements (e.g., require a new credential) or change your list of trusted issuers simply by updating a policy in the engine, with no changes to your core application.
+- **Privacy Preserving**: Private information stays offchain, only verification results are onchain.
+
+## How to Use
+
+Using the Cross-Chain Identity component in a secure, integrated way involves three main steps, which are typically performed in a deployment script:
+
+1.  **Deploy and Secure Infrastructure**: Deploy the `IdentityRegistry` and `CredentialRegistry`, making sure to set their owner to your `PolicyEngine` instance.
+2.  **Configure Validation**: Deploy and configure the `CredentialRegistryIdentityValidatorPolicy` with your desired credential requirements (e.g., must have KYC). Then, use the `PolicyEngine` to attach this policy to the application functions you want to protect.
+3.  **Authorize Issuers**: Deploy an access control policy (like `OnlyAuthorizedSenderPolicy`) to grant a trusted off-chain entity the permission to issue new credentials.
+
+This setup creates a robust system where credential issuance and validation are both governed by flexible, onchain policies.
+
+→ **For a complete, step-by-step code walkthrough, see the [API Guide](./docs/API_GUIDE.md).**
+
+## Critical Requirements
+
+### Non-Reverting View Functions
+
+**All view functions in Cross-Chain Identity interfaces MUST NOT revert under any circumstances.** This is a critical requirement for reliable system operation.
+
+Specifically, the following functions must be implemented with defensive programming patterns:
+
+- `IIdentityValidator.validate()`
+- `ICredentialDataValidator.validateCredentialData()`
+- `ICredentialRegistryValidator.validate()` and `validateAll()`
+
+Implementations should use try-catch blocks around external calls and return appropriate boolean results rather than allowing reverts to propagate. This ensures that credential validation failures in one source don't block the entire validation process.
+
+## Next Steps
+
+- **[Core Concepts](./docs/CONCEPTS.md)**: A deep dive into the architecture and design rationale.
+- **[Credential Flow](./docs/CREDENTIAL_FLOW.md)**: A detailed sequence diagram of the entire verification process.
+- **[API Guide](./docs/API_GUIDE.md)**: A developer-focused guide for common tasks.
+- **[API Reference](./docs/API_REFERENCE.md)**: Complete interface specifications.
+- **[Security Considerations](./docs/SECURITY.md)**: A checklist of key principles for a secure implementation.
+- **[Implementation](./src/) & [Tests](./test/)**: Examine the reference implementation in `/src` and see it in action in the `/test` folder.

package/packages/cross-chain-identity/docs/API_GUIDE.md

@@ -0,0 +1,120 @@
+# API Guide: Cross-Chain Identity
+
+This guide provides practical, task-oriented examples for using the Cross-Chain Identity component as part of the integrated Chainlink ACE, secured by the Policy Management component.
+
+## 1. Setting Up the Identity Infrastructure
+
+The first step is to deploy the core contracts. The recommended pattern is to create a secure system where the `IdentityRegistry` and `CredentialRegistry` are governed by a `PolicyEngine`.
+
+Here is how you would write the deployment script code:
+
+```solidity
+// --- In your deployment script ---
+import { PolicyEngine } from "@chainlink/policy-management/core/PolicyEngine.sol";
+import { IdentityRegistry } from "@chainlink/cross-chain-identity/src/IdentityRegistry.sol";
+import { CredentialRegistry } from "@chainlink/cross-chain-identity/src/CredentialRegistry.sol";
+
+// 1. Deploy the engine that will act as the guardian
+PolicyEngine policyEngine = new PolicyEngine();
+bool defaultAllow = true;
+policyEngine.initialize(defaultAllow, address(this)); // Recommended default
+
+// 2. Deploy the registries and transfer their ownership to the engine
+IdentityRegistry identityRegistry = new IdentityRegistry();
+identityRegistry.initialize(address(policyEngine));
+
+CredentialRegistry credentialRegistry = new CredentialRegistry();
+credentialRegistry.initialize(address(policyEngine));
+```
+
+With this setup, all administrative actions on the registries (like issuing credentials) are now under the control of the `PolicyEngine`.
+
+## Task 2: Performing Validation with `CredentialRegistryIdentityValidatorPolicy`
+
+The primary way to check for credentials in an integrated system is with the `CredentialRegistryIdentityValidatorPolicy`. This is a specialized policy that contains all the logic needed to query the registries.
+
+### Step 2.1: Deploy and Configure the Policy
+
+First, deploy an instance of `CredentialRegistryIdentityValidatorPolicy`. Its `initialize` function takes the credential sources and requirements as ABI-encoded arguments.
+
+```solidity
+// --- In your deployment script ---
+import { CredentialRegistryIdentityValidatorPolicy } from "@chainlink/cross-chain-identity/src/CredentialRegistryIdentityValidatorPolicy.sol";
+import { ICredentialRequirements } from "@chainlink/cross-chain-identity/src/interfaces/ICredentialRequirements.sol";
+
+// e.g.: Define the KYC credential type we will be checking for
+bytes32 kycCredential = keccak256("common.kyc");
+
+// 1. Define the Credential Source
+// This tells the policy which registries to use for the "common.kyc" type.
+ICredentialRequirements.CredentialSourceInput[] memory sources = new ICredentialRequirements.CredentialSourceInput[](1);
+sources[0] = ICredentialRequirements.CredentialSourceInput(kycCredential, address(identityRegistry), address(credentialRegistry), address(0));
+
+// 2. Define the Credential Requirement
+// This specifies that an identity must have at least one "common.kyc" credential.
+bytes32[] memory requiredCredentials = new bytes32[](1);
+requiredCredentials[0] = kycCredential;
+ICredentialRequirements.CredentialRequirementInput[] memory requirements = new ICredentialRequirements.CredentialRequirementInput[](1);
+requirements[0] = ICredentialRequirements.CredentialRequirementInput(keccak256("requirement.KYC"), requiredCredentials, 1, false);
+
+// 3. Deploy and initialize the policy
+CredentialRegistryIdentityValidatorPolicy kycCheckPolicy = new CredentialRegistryIdentityValidatorPolicy();
+kycCheckPolicy.initialize(address(policyEngine), address(this), abi.encode(sources, requirements));
+```
+
+### Step 2.2: Attach the Policy to Your Application
+
+Next, use the `PolicyEngine` to apply your `kycCheckPolicy` to a protected function, such as an ERC20 token's `transfer` method.
+
+```solidity
+// --- In your deployment script ---
+import { ERC20TransferExtractor } from "@chainlink/policy-management/extractors/ERC20TransferExtractor.sol";
+
+// 1. Register an extractor to parse the 'to' address from the transfer function
+ERC20TransferExtractor transferExtractor = new ERC20TransferExtractor();
+policyEngine.setExtractor(myToken.transfer.selector, address(transferExtractor));
+
+// 2. Specify that our policy needs the 'to' parameter from the extractor
+bytes32[] memory transferParams = new bytes32[](1);
+transferParams[0] = transferExtractor.PARAM_TO();
+
+// 3. Add the policy to the engine for the token's transfer function
+policyEngine.addPolicy(
+    address(myToken),
+    myToken.transfer.selector,
+    address(kycCheckPolicy),
+    transferParams
+);
+```
+
+Your token is now protected. All calls to `transfer()` will be automatically checked to ensure the recipient has a valid KYC credential.
+
+## Task 3: Authorizing a Credential Issuer
+
+The final step is to grant a trusted offchain entity (the **Credential Issuer**) permission to write to the `CredentialRegistry`.
+
+**The Goal:** You want to allow a specific address (`verificationIssuer`) to call `registerCredential` on the `CredentialRegistry`, but no one else.
+
+**The Action:** You deploy a simple access control policy (like `OnlyAuthorizedSenderPolicy`) and apply it to the `registerCredential` function on the registry contract itself.
+
+```solidity
+// --- In your deployment script ---
+import { OnlyAuthorizedSenderPolicy } from "@chainlink/policy-management/policies/OnlyAuthorizedSenderPolicy.sol";
+
+address verificationIssuer = 0x...; // The address of your trusted KYC provider
+
+// 1. Deploy a policy that manages a list of authorized senders
+OnlyAuthorizedSenderPolicy issuerPolicy = new OnlyAuthorizedSenderPolicy();
+issuerPolicy.initialize(address(policyEngine), address(this), new bytes(0));
+issuerPolicy.authorizeSender(verificationIssuer);
+
+// 2. Apply this policy to the CredentialRegistry's `registerCredential` function
+policyEngine.addPolicy(
+    address(credentialRegistry),
+    credentialRegistry.registerCredential.selector,
+    address(issuerPolicy),
+    new bytes32[](0) // No parameters needed for this policy
+);
+```
+
+Your system is now fully configured. The `verificationIssuer` is the only entity that can issue KYC credentials, and your `myToken` contract will automatically enforce that all recipients of a transfer possess one.

package/packages/cross-chain-identity/docs/API_REFERENCE.md

@@ -0,0 +1,271 @@
+> **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: Cross-Chain Identity
+
+This document provides the complete, formal interface specifications for the Cross-Chain Identity component.
+
+## Core Interfaces
+
+### IIdentityRegistry
+
+**File:** [`src/interfaces/IIdentityRegistry.sol`](../src/interfaces/IIdentityRegistry.sol)
+
+The `IIdentityRegistry` manages how each local blockchain address maps to a Cross-Chain Identifier (CCID). By interacting with this registry, applications can link multiple addresses to a single identity.
+
+#### Key Functions
+
+```solidity
+interface IIdentityRegistry {
+    function registerIdentity(bytes32 ccid, address account, bytes calldata context) external;
+    function registerIdentities(bytes32[] calldata ccids, address[] calldata accounts, bytes calldata context) external;
+    function removeIdentity(bytes32 ccid, address account, bytes calldata context) external;
+    function getIdentity(address account) external view returns (bytes32);
+    function getAccounts(bytes32 ccid) external view returns (address[] memory);
+}
+```
+
+#### Events
+
+```solidity
+event IdentityRegistered(bytes32 indexed ccid, address indexed account);
+event IdentityRemoved(bytes32 indexed ccid, address indexed account);
+```
+
+#### Errors
+
+```solidity
+error IdentityAlreadyRegistered(bytes32 ccid, address account);
+error IdentityNotFound(bytes32 ccid, address account);
+error InvalidConfiguration(bytes errorReason);
+```
+
+### ICredentialRegistry
+
+**File:** [`src/interfaces/ICredentialRegistry.sol`](../src/interfaces/ICredentialRegistry.sol)
+
+The `ICredentialRegistry` manages the lifecycle of credentials linked to a CCID, including registration, removal, and renewal processes.
+
+#### Credential Struct
+
+```solidity
+struct Credential {
+    uint40 expiresAt;
+    bytes credentialData;
+}
+```
+
+#### Key Functions
+
+```solidity
+interface ICredentialRegistry {
+    function registerCredential(
+        bytes32 ccid,
+        bytes32 credentialTypeId,
+        uint40 expiresAt,
+        bytes calldata credentialData,
+        bytes calldata context
+    ) external;
+
+    function registerCredentials(
+        bytes32 ccid,
+        bytes32[] calldata credentialTypeIds,
+        uint40 expiresAt,
+        bytes[] calldata credentialDatas,
+        bytes calldata context
+    ) external;
+
+    function removeCredential(bytes32 ccid, bytes32 credentialTypeId, bytes calldata context) external;
+
+    function renewCredential(bytes32 ccid, bytes32 credentialTypeId, uint40 expiresAt, bytes calldata context) external;
+
+    function isCredentialExpired(bytes32 ccid, bytes32 credentialTypeId) external view returns (bool);
+
+    function getCredentialTypes(bytes32 ccid) external view returns (bytes32[] memory);
+
+    function getCredential(bytes32 ccid, bytes32 credentialTypeId) external view returns (Credential memory);
+
+    function getCredentials(
+        bytes32 ccid,
+        bytes32[] calldata credentialTypeIds
+    ) external view returns (Credential[] memory);
+}
+```
+
+#### Events
+
+```solidity
+event CredentialRegistered(
+    bytes32 indexed ccid, bytes32 indexed credentialTypeId, uint40 expiresAt, bytes credentialData
+);
+event CredentialRemoved(bytes32 indexed ccid, bytes32 indexed credentialTypeId);
+event CredentialRenewed(
+    bytes32 indexed ccid,
+    bytes32 indexed credentialTypeId,
+    uint40 previousExpiresAt,
+    uint40 expiresAt
+);
+```
+
+#### Errors
+
+```solidity
+error CredentialAlreadyRegistered(bytes32 ccid, bytes32 credentialTypeId);
+error CredentialNotFound(bytes32 ccid, bytes32 credentialTypeId);
+error InvalidConfiguration(string errorReason);
+```
+
+### ICredentialRegistryValidator
+
+**File:** [`src/interfaces/ICredentialRegistryValidator.sol`](../src/interfaces/ICredentialRegistryValidator.sol)
+
+The `ICredentialRegistryValidator` provides validation functionality to check whether credentials exist and are valid for a given CCID.
+
+#### Key Functions
+
+```solidity
+interface ICredentialRegistryValidator {
+    function validate(bytes32 ccid, bytes32 credentialTypeId, bytes calldata context) external view returns (bool);
+
+    function validateAll(
+        bytes32 ccid,
+        bytes32[] calldata credentialTypeIds,
+        bytes calldata context
+    ) external view returns (bool);
+}
+```
+
+#### Critical Requirements
+
+**Non-Reverting Guarantee:** The `validate` and `validateAll` functions, along with all other view functions in `ICredentialRegistryValidator` implementations **MUST NOT revert under any circumstances**. This requirement is critical to ensure reliable interactions with credential registry validator contracts.
+
+## Application Integration Interfaces
+
+### ICredentialRequirements
+
+**File:** [`src/interfaces/ICredentialRequirements.sol`](../src/interfaces/ICredentialRequirements.sol)
+
+The `ICredentialRequirements` interface allows applications to define complex credential requirements using multiple sources and validation rules.
+
+#### Key Structs
+
+```solidity
+struct CredentialRequirement {
+    bytes32[] credentialTypeIds;
+    uint256 minValidations;
+    bool invert;
+}
+
+struct CredentialSource {
+    address identityRegistry;
+    address credentialRegistry;
+    address dataValidator;
+}
+
+struct CredentialRequirementInput {
+    bytes32 requirementId;
+    bytes32[] credentialTypeIds;
+    uint256 minValidations;
+    bool invert;
+}
+
+struct CredentialSourceInput {
+    bytes32 credentialTypeId;
+    address identityRegistry;
+    address credentialRegistry;
+    address dataValidator;
+}
+```
+
+#### Key Functions
+
+```solidity
+interface ICredentialRequirements {
+    function addCredentialRequirement(CredentialRequirementInput memory input) external;
+    function removeCredentialRequirement(bytes32 requirementId) external;
+    function getCredentialRequirement(bytes32 requirementId) external view returns (CredentialRequirement memory);
+    function getCredentialRequirementIds() external view returns (bytes32[] memory);
+
+    function addCredentialSource(CredentialSourceInput memory input) external;
+    function removeCredentialSource(
+        bytes32 credentialTypeId,
+        address identityRegistry,
+        address credentialRegistry
+    ) external;
+    function getCredentialSources(bytes32 credentialTypeId) external view returns (CredentialSource[] memory);
+}
+```
+
+#### Events
+
+```solidity
+event CredentialRequirementAdded(bytes32 indexed requirementId, bytes32[] credentialTypeIds, uint256 minValidations, bool invert);
+event CredentialRequirementRemoved(bytes32 indexed requirementId, bytes32[] credentialTypeIds, uint256 minValidations, bool invert);
+event CredentialSourceAdded(
+    bytes32 indexed credentialTypeId,
+    address indexed identityRegistry,
+    address indexed credentialRegistry,
+    address dataValidator
+);
+event CredentialSourceRemoved(
+    bytes32 indexed credentialTypeId,
+    address indexed identityRegistry,
+    address indexed credentialRegistry,
+    address dataValidator
+);
+```
+
+#### Errors
+
+```solidity
+error RequirementExists(bytes32 requirementId);
+error RequirementNotFound(bytes32 requirementId);
+error SourceExists(bytes32 credentialTypeId, address identityRegistry, address credentialRegistry);
+error SourceNotFound(bytes32 credentialTypeId, address identityRegistry, address credentialRegistry);
+error InvalidConfiguration(string errorReason);
+```
+
+### IIdentityValidator
+
+**File:** [`src/interfaces/IIdentityValidator.sol`](../src/interfaces/IIdentityValidator.sol)
+
+The `IIdentityValidator` provides a unified interface for applications to validate user accounts against defined credential requirements.
+
+#### Key Functions
+
+```solidity
+interface IIdentityValidator {
+    function validate(address account, bytes calldata context) external view returns (bool);
+}
+```
+
+#### Critical Requirements
+
+**Non-Reverting Guarantee:** The `validate` function and all other view functions in `IIdentityValidator` implementations **MUST NOT revert under any circumstances**. This requirement is critical to ensure reliable interactions with IdentityValidator contracts.
+
+Implementations must use defensive programming patterns such as try-catch blocks around external calls to gracefully handle failures and return appropriate boolean results rather than allowing reverts to propagate.
+
+## Data Validation Interface
+
+### ICredentialDataValidator
+
+**File:** [`src/interfaces/ICredentialDataValidator.sol`](../src/interfaces/ICredentialDataValidator.sol)
+
+The `ICredentialDataValidator` is an optional interface for implementing custom validation rules on the data attached to a credential.
+
+#### Key Functions
+
+```solidity
+interface ICredentialDataValidator {
+    function validateCredentialData(
+        bytes32 ccid,
+        address account,
+        bytes32 credentialTypeId,
+        bytes calldata credentialData,
+        bytes calldata context
+    ) external view returns (bool);
+}
+```
+
+#### Critical Requirements
+
+**Non-Reverting Guarantee:** The `validateCredentialData` function and all other view functions in `ICredentialDataValidator` implementations **MUST NOT revert under any circumstances**. This requirement is critical to ensure reliable interactions with data validator contracts.