@chainlink/ace 0.5.0

package/README.md

@@ -0,0 +1,218 @@
+<div align="center">
+  <img src="assets/chainlink-logo.svg" alt="Chainlink" width="300" height="130"/>
+</div>
+
+# Chainlink ACE Core Contracts
+
+**Build the next generation of financial applications with programmable, cross‑chain compliance—powered by the Chainlink Automated Compliance Engine (ACE).**
+
+## What Problems Does This Solve?
+
+Building compliant applications on the blockchain requires handling:
+
+- **Dynamic policy enforcement** that evolves with regulations—without redeploying your core application contracts
+- **Identity verification** across chains, without fragmented credentials
+- **Trusted external data** (KYC providers, sanctions lists, price feeds, Proof of Reserves, etc.) delivered onchain
+
+## Your Modular Toolkit
+
+| Component                | Description                                                                        | Dependencies               |
+| ------------------------ | ---------------------------------------------------------------------------------- | -------------------------- |
+| **Policy Management**    | Dynamic engine to create and enforce onchain rules.                                | Standalone                 |
+| **Cross-Chain Identity** | Portable identity system for EVM chains; attach credentials once, verify anywhere. | Requires Policy Management |
+
+## Key Features
+
+- **Modular & Composable**: Use one component or all three. They're designed to work together seamlessly.
+- **Future-Proof**: Adapt to new regulations by updating policies, not your core application logic.
+- **Cross-Chain Ready**: Manage identity and compliance consistently across multiple EVM networks.
+- **Privacy-Preserving by Design**: Keep sensitive user data offchain while verifying credentials onchain.
+- **Ready-to-Use Policies**: Plug-and-play modules for common compliance scenarios like volume limits and authorization.
+- **EVM Compatible**: Works with existing tooling and supports future innovations like ZK proofs.
+
+## How It Works: A Real-World Example
+
+Here's how these three components work together. Imagine **Emma** (an institutional investor) wants to buy **$50,000** of a **Tokenized Bond** on a DEX.
+
+```mermaid
+graph TB
+    subgraph "External World"
+        KYC["<b>KYC Provider</b><br/>✅ Emma: Verified"]
+        Oracle["<b>Bond Price Feed</b><br/>📊 Current: $1.02"]
+        AML["<b>AML Watchlist</b><br/>🔍 Emma: Clean"]
+    end
+
+    subgraph "Chainlink ACE Modular Toolkit"
+        subgraph "Cross-Chain Identity"
+            CCID["<b>Emma's Identity</b><br/>ID: 0x1a2b... (Portable)"]
+            CredReg["<b>Credentials</b><br/>✅ KYC ✅ Accredited"]
+        end
+
+        subgraph "Policy Management ⚙️"
+            PE["<b>Policy Engine</b><br/>🧠 Decision Maker"]
+            P1["<b>Access Policy</b><br/>❓ Verified & not sanctioned?"]
+            P2["<b>Volume Rate Policy</b><br/>❓ $50k within daily limit?"]
+        end
+
+    end
+
+    subgraph "Emma's Transaction"
+        Emma["<b>👩‍💼 Emma</b><br/>Wants: $50k bonds"]
+        BondDEX["<b>Bond DEX</b><br/>🏦 Tokenized Bonds"]
+        Result["<b>✅ Trade Approved</b>"]
+    end
+
+    %% Data flows
+    KYC -.->|"<b>Issues Credential</b>"| CredReg
+    Oracle -.->|"<b>Provides Data</b>"| Registry
+    AML -.->|"<b>Provides Data</b>"| Registry
+
+    %% Transaction flow
+    Emma -->|"<b>1. Buy Bonds</b>"| BondDEX
+    BondDEX -->|"<b>2. Validate Tx</b>"| PE
+
+    %% Policy Engine orchestration
+    PE --> P1
+    PE --> P2
+
+    %% Policy checks using other components
+    P1 -->|"Checks"| CredReg
+    P1 -->|"Uses"| Registry
+    P2 -->|"Uses"| Registry
+
+    %% Completion
+    PE -->|"<b>3. All checks pass</b>"| BondDEX
+    BondDEX -->|"<b>4. Execute Trade</b>"| Result
+
+    classDef default fill:#2b2f37,stroke:#c0c5ce,stroke-width:1px,color:#c0c5ce
+    classDef external fill:#4338ca,stroke:#a5b4fc,stroke-width:1px,color:#e0e7ff
+    classDef user fill:#166534,stroke:#4ade80,stroke-width:1px,color:#dcfce7
+    classDef result fill:#be123c,stroke:#fda4af,stroke-width:1px,color:#ffe4e6
+
+    class KYC,Oracle,AML external
+    class Emma,Result user
+```
+
+### The Compliance Journey: Step-by-Step
+
+1.  **Transaction Initiated**: Emma submits her buy order on the DEX. Before executing, the DEX's smart contract calls the **Policy Engine** to validate the transaction.
+2.  **Access Policy Executes**: The Policy Engine executes the `Access Policy`, which uses the **Cross-Chain Identity** component to verify Emma has the required credentials (`✅ KYC`, `✅ Accredited`).
+    _Crucially, this same identity and credential would be valid even if Emma were using a different wallet address on a different EVM chain._
+3.  **Volume Rate Policy Executes**: Next, the engine runs the `Volume Rate Policy`, which tracks Emma's trading volume over time and confirms the $50,000 trade is within her daily limit.
+4.  **Transaction Approved**: With all policies passing, the Policy Engine allows the transaction to proceed. The DEX executes the trade, and Emma receives her tokenized bonds.
+
+_The power of this model is that if regulations change tomorrow, the DEX's owners could add a new policy (e.g., a 'Time-of-Day Policy') without having to redeploy or alter the main DEX contract._
+
+If any policy check had failed, the **Policy Engine would have reverted the transaction directly**, preventing a non-compliant trade.
+
+## 🚀 Ready to Build?
+
+### New to ACE? Start here
+
+**Get hands-on immediately.** Our beginner-friendly Getting Started Guide walks you through the core pattern with a simple, working example.
+
+**→ [Start the Getting Started Guide](./getting_started/GETTING_STARTED.md)**
+
+---
+
+### Need identity & credential verification?
+
+**After completing the basic guide**, level up with our Advanced Getting Started Guide featuring KYC checks, sanctions screening, and identity management.
+
+**Best for:** Applications requiring user verification, accredited investor checks, or cross-chain identity.
+
+**→ [Advanced Getting Started Guide](./getting_started/advanced/GETTING_STARTED_ADVANCED.md)**
+
+---
+
+### Want to study production-ready examples?
+
+Build with confidence using our reference implementations as your foundation.
+
+**Best for:** Experienced developers who want to study audited code and adapt it to their needs.
+
+- **Study the reference implementation for each component:**
+  - [Policy Management](./packages/policy-management/src)
+  - [Cross-Chain Identity](./packages/cross-chain-identity/src)
+- **See full integrations in the [example tokens](./packages/tokens)**
+
+---
+
+### Want to understand the architecture first?
+
+Understand the design before diving into implementation.
+
+**→ Continue reading about the components below**
+
+## Explore the Components
+
+### 🛡️ [Policy Management](./packages/policy-management/)
+
+Use this component to enforce onchain rules that can be updated without redeploying your core contracts.
+
+- **Policy Engine**: Pluggable, composable policy enforcement.
+- **Zero Downtime Updates**: Add, remove, or modify rules dynamically.
+- **Ready-to-Use Policies**: AllowPolicy, VolumePolicy, OnlyOwnerPolicy, and more.
+
+**How it works as a standalone component:**
+
+```mermaid
+graph LR
+    App[Your Contract] -->|inherits| PP[PolicyProtected]
+    App -->|calls| PE[PolicyEngine]
+    PE -->|executes| P1[Policy 1]
+    PE -->|executes| P2[Policy 2]
+    PE -->|executes| P3[Policy N]
+```
+
+**Use cases:** Access control, volume limits, time restrictions, pauseable functions, role-based permissions.
+
+→ **[📋 Quick Guide](./packages/policy-management/README.md)** | **[🏗️ Reference Implementation](./packages/policy-management/src/)** | **[📚 Deep Dive Docs](./packages/policy-management/docs/)** | **[📋 Ready-to-Use Policies](./packages/policy-management/src/policies/README.md)**
+
+### 🔗 [Cross-Chain Identity](./packages/cross-chain-identity/)
+
+Use this component to link wallet addresses to a single identity and manage credentials like KYC/AML.
+
+- **Cross-Chain ID (CCID)**: Single identifier linking addresses across multiple chains.
+- **Credential Registry**: Manage credentials (e.g., KYC, AML) that are tied directly to a user's CCID.
+- **Privacy-First**: Store sensitive data offchain, only hashes onchain.
+
+> **Requires:** Policy Management component (listed above)
+
+**How it works integrated with Policy Management:**
+
+```mermaid
+graph TB
+    App[Your Contract] -->|inherits| PP[PolicyProtected]
+    App -->|calls| PE[PolicyEngine]
+    PE -->|executes| IVP[CredentialRegistryIdentityValidatorPolicy]
+    PE -->|executes| SP[SanctionsPolicy]
+    PE -->|executes| OP[Other Policies]
+
+    IVP -->|reads from| IR[IdentityRegistry]
+    IVP -->|reads from| CR[CredentialRegistry]
+    SP -->|reads from| SL[Sanctions List]
+```
+
+**Use cases:** KYC/AML verification, accredited investor checks, cross-chain credential verification, sanctions screening.
+
+→ **[📋 Quick Guide](./packages/cross-chain-identity/README.md)** | **[🏗️ Reference Implementation](./packages/cross-chain-identity/src/)** | **[📚 Deep Dive Docs](./packages/cross-chain-identity/docs/)**
+
+## [Example Tokens](./packages/tokens/)
+
+Explore our example token contracts to see how these components work together in a real application.
+
+- **[ERC-20 Compliance Token](./packages/tokens/erc-20)** - A policy-protected ERC-20 implementation with advanced frozen token handling
+- **[ERC-3643 Compliance Token](./packages/tokens/erc-3643)** - A compliant implementation of the ERC-3643 T-REX standard
+
+> **📝 Important Note on Frozen Token Behavior:**  
+> These two token implementations handle frozen tokens differently during burns and forced transfers:
+>
+> - **ERC-20**: Frozen tokens remain frozen during burns/force transfers. The `_checkFrozenBalance()` function ensures sufficient unfrozen tokens are available before operations proceed.
+> - **ERC-3643**: Automatically unfreezes tokens as needed during burns/force transfers to complete the operation.
+>
+> Both approaches are valid design choices depending on your compliance requirements. Choose the implementation that best fits your use case.
+
+## Contributing & Feedback
+
+We welcome community **feedback, audits, and contributions**. If you have additional compliance requirements or ideas for new features, please feel free to propose expansions or new modules.

package/assets/chainlink-logo.svg

@@ -0,0 +1,21 @@
+<svg width="385" height="317" viewBox="0 115 385 85" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_4140_519)">
+<path d="M96.1722 127L69 142.688V174.065L96.1722 189.753L123.344 174.065V142.688L96.1722 127ZM111.833 167.416L96.1772 176.455L80.5215 167.416V149.338L96.1772 140.299L111.833 149.338V167.416Z" fill="#0847F7"/>
+<path d="M153.157 174.098C150.458 174.098 148.041 173.48 145.912 172.238C143.781 170.998 142.099 169.208 140.867 166.863C139.635 164.519 139.02 161.698 139.02 158.397C139.02 155.096 139.642 152.229 140.88 149.877C142.12 147.528 143.806 145.736 145.945 144.503C148.081 143.271 150.486 142.656 153.159 142.656C154.896 142.656 156.518 142.904 158.009 143.396C159.502 143.888 160.83 144.604 161.995 145.542C163.159 146.481 164.106 147.628 164.841 148.984C165.574 150.339 166.049 151.881 166.27 153.61H160.208C160.07 152.734 159.803 151.951 159.407 151.255C159.008 150.565 158.506 149.975 157.898 149.488C157.288 149.001 156.595 148.632 155.825 148.379C155.049 148.125 154.206 148 153.287 148C151.671 148 150.247 148.404 149.012 149.212C147.78 150.02 146.816 151.198 146.126 152.747C145.433 154.293 145.087 156.18 145.087 158.397C145.087 160.613 145.435 162.539 146.133 164.08C146.834 165.621 147.792 166.783 149.02 167.571C150.247 168.36 151.663 168.754 153.262 168.754C154.153 168.754 154.981 168.633 155.747 168.392C156.513 168.154 157.203 167.802 157.813 167.343C158.42 166.886 158.932 166.324 159.344 165.659C159.756 164.993 160.044 164.23 160.208 163.369H166.27C166.091 164.805 165.665 166.171 164.987 167.458C164.309 168.744 163.405 169.886 162.273 170.877C161.144 171.871 159.813 172.652 158.287 173.232C156.759 173.807 155.049 174.095 153.162 174.095V174.103L153.157 174.098Z" fill="#0847F7"/>
+<path d="M175.392 160.317V173.674H169.516V143.055H175.229V154.704H175.517C176.05 153.377 176.888 152.327 178.025 151.559C179.16 150.794 180.608 150.407 182.36 150.407C183.949 150.407 185.342 150.748 186.529 151.434C187.722 152.119 188.648 153.106 189.303 154.393C189.961 155.678 190.287 157.237 190.287 159.06V173.669H184.388V160.046C184.388 158.565 184.012 157.413 183.259 156.582C182.506 155.754 181.441 155.34 180.073 155.34C179.155 155.34 178.346 155.538 177.648 155.937C176.948 156.336 176.398 156.901 175.994 157.631C175.59 158.367 175.389 159.255 175.389 160.315V160.32L175.392 160.317Z" fill="#0847F7"/>
+<path d="M200.734 174.128C199.268 174.128 197.958 173.867 196.8 173.347C195.643 172.825 194.732 172.054 194.067 171.035C193.402 170.016 193.07 168.751 193.07 167.245C193.07 165.96 193.306 164.888 193.781 164.037C194.255 163.186 194.898 162.501 195.713 161.974C196.529 161.447 197.45 161.047 198.487 160.781C199.521 160.515 200.608 160.327 201.743 160.217C203.086 160.079 204.168 159.953 204.991 159.838C205.814 159.722 206.412 159.536 206.788 159.283C207.165 159.029 207.353 158.655 207.353 158.163V158.06C207.353 157.031 207.037 156.233 206.409 155.666C205.779 155.098 204.88 154.812 203.716 154.812C202.483 154.812 201.504 155.081 200.776 155.626C200.051 156.165 199.567 156.82 199.318 157.586L193.851 156.989C194.192 155.593 194.815 154.403 195.711 153.424C196.607 152.445 197.734 151.697 199.09 151.183C200.445 150.668 201.986 150.41 203.713 150.41C204.906 150.41 206.068 150.55 207.197 150.831C208.327 151.11 209.346 151.557 210.26 152.169C211.168 152.779 211.899 153.585 212.436 154.584C212.976 155.585 213.249 156.803 213.249 158.244V173.673H207.622V170.488H207.458C207.099 171.171 206.625 171.791 206.02 172.341C205.418 172.89 204.677 173.322 203.801 173.646C202.925 173.97 201.903 174.13 200.739 174.13H200.731L200.734 174.128ZM202.333 169.936C203.347 169.936 204.23 169.735 204.983 169.331C205.736 168.927 206.326 168.387 206.751 167.709C207.175 167.032 207.388 166.281 207.388 165.46V162.89C207.197 163.028 206.914 163.151 206.547 163.261C206.176 163.372 205.759 163.472 205.292 163.56C204.828 163.648 204.366 163.726 203.914 163.796C203.462 163.864 203.058 163.919 202.702 163.959C201.921 164.07 201.233 164.248 200.636 164.491C200.038 164.74 199.569 165.074 199.228 165.498C198.886 165.922 198.713 166.457 198.713 167.102C198.713 168.033 199.052 168.739 199.73 169.22C200.407 169.7 201.273 169.938 202.328 169.938H202.33L202.333 169.936Z" fill="#0847F7"/>
+<path d="M217.109 173.676V150.703H222.986V173.676H217.109Z" fill="#0847F7"/>
+<path d="M232.728 160.317V173.674H226.852V150.698H232.625V154.705H232.873C233.393 153.389 234.219 152.345 235.348 151.569C236.478 150.794 237.899 150.41 239.613 150.41C241.202 150.41 242.59 150.751 243.772 151.436C244.957 152.119 245.876 153.111 246.529 154.403C247.179 155.699 247.505 157.25 247.505 159.057V173.666H241.629V160.044C241.629 158.578 241.25 157.425 240.489 156.592C239.731 155.759 238.684 155.337 237.354 155.337C236.45 155.337 235.65 155.535 234.959 155.934C234.267 156.334 233.724 156.898 233.325 157.629C232.926 158.364 232.73 159.253 232.73 160.312V160.317H232.728Z" fill="#0847F7"/>
+<path d="M257.239 141.549V173.676H251.363V141.549H257.239Z" fill="#0847F7"/>
+<path d="M261.102 173.676V150.703H266.978V173.676H261.102Z" fill="#0847F7"/>
+<path d="M276.716 160.317V173.673H270.84V150.698H276.613V154.704H276.862C277.381 153.389 278.207 152.345 279.337 151.569C280.466 150.794 281.887 150.41 283.601 150.41C285.19 150.41 286.578 150.751 287.763 151.436C288.948 152.119 289.867 153.11 290.517 154.403C291.167 155.698 291.493 157.25 291.493 159.057V173.666H285.617V160.043C285.617 158.578 285.238 157.425 284.477 156.592C283.719 155.759 282.673 155.337 281.342 155.337C280.439 155.337 279.638 155.535 278.948 155.934C278.255 156.333 277.713 156.898 277.313 157.629C276.914 158.364 276.716 159.253 276.716 160.312V160.317Z" fill="#0847F7"/>
+<path d="M309.722 173.676H316.69L307.516 160.651L316.216 150.701H309.396L301.605 159.682H301.238V143.055H295.359V173.676H301.238V166.176L303.081 164.133L309.722 173.674V173.676Z" fill="#0847F7"/>
+<path d="M223.032 141.549H217.156V147.425H223.032V141.549Z" fill="#0847F7"/>
+<path d="M267.029 141.549H261.152V147.425H267.029V141.549Z" fill="#0847F7"/>
+</g>
+<defs>
+<clipPath id="clip0_4140_519">
+<rect width="247.69" height="62.7534" fill="white" transform="translate(69 127)"/>
+</clipPath>
+</defs>
+</svg>

package/chainlink-ace-License-grants

@@ -0,0 +1,2 @@
+Additional Use Grant(s):
+1. You may make use of chainlink-ace, which is available subject to the license here (the “Licensed Work”), solely for purposes listed below:

package/foundry.toml

@@ -0,0 +1,33 @@
+[profile.default]
+src = "packages"
+out = "out"
+solc = "0.8.26"
+optimizer = true
+optimizer_runs = 8000
+via_ir = true
+evm_version = "paris"
+
+[fmt]
+bracket_spacing = false
+int_types = "long"
+line_length = 120
+multiline_func_header = "all"
+quote_style = "double"
+tab_width = 2
+wrap_comments = true
+
+[profile.compliance-token-erc20]
+src = 'packages/token/erc-20/src'
+test = 'packages/token/erc-20/test'
+
+[profile.compliance-token-erc3643]
+src = 'packages/token/erc-3643/src'
+test = 'packages/token/erc-3643/test'
+
+[profile.policy-management]
+src = 'packages/policy-management/src'
+test = 'packages/policy-management/test'
+
+[profile.cross-chain-identity]
+src = 'packages/cross-chain-identity/src'
+test = 'packages/cross-chain-identity/test'