# Cross-Chain Identity Contracts
Source: https://docs.chain.link/ace/reference/cross-chain-identity-contracts
Last Updated: 2026-08-18

> For the complete documentation index, see [llms.txt](/llms.txt).

> **NOTE: On-chain contracts vs. ACE Platform**
>
> The contracts on this page are the **on-chain foundation** of ACE — smart contracts deployed on EVM chains that manage
> identities and credentials. The **ACE Platform** (Policy Manager, Identity Manager, Reporting Manager) is a separate
> set of off-chain services built on top of these contracts, providing a managed experience through the Platform UI and
> Coordinator API. You can use the platform to manage these contracts, or interact with them directly. See [Beta
> Scope](/ace/beta-scope) for current platform limitations.

The Cross-Chain Identity contracts manage identity registries and credential lifecycles for ACE. They depend on the [Policy Management contracts](/ace/reference/policy-management-contracts) — registries are owned and governed by a PolicyEngine. The source code and full documentation are available in the <a href="https://github.com/smartcontractkit/chainlink-ace/tree/main/packages/cross-chain-identity" target="_blank">cross-chain-identity package</a> of the <a href="https://github.com/smartcontractkit/chainlink-ace" target="_blank">chainlink-ace repository</a> (Business Source License 1.1).

## Core interfaces

| Interface                                                                                                                                                         | Description                                                                                                                                                                                                              |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [IIdentityRegistry](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/interfaces/IIdentityRegistry.sol)               | Maps wallet addresses to Cross-Chain Identifiers (CCIDs). Supports registering and removing address-to-CCID mappings, and looking up the CCID for a given address or all addresses for a given CCID.                     |
| [ICredentialRegistry](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/interfaces/ICredentialRegistry.sol)           | Manages the lifecycle of credentials linked to a CCID — registration, renewal, removal, and expiration checks. Each credential is identified by a `credentialTypeId` (a `keccak256` hash of the credential type string). |
| [ICredentialRequirements](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/interfaces/ICredentialRequirements.sol)   | Defines which credentials a policy requires, which registries to check, and how many validations must pass. Supports complex rules via credential sources, minimum validation thresholds, and inverted checks.           |
| [IIdentityValidator](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/interfaces/IIdentityValidator.sol)             | Validates whether an account meets all configured credential requirements. Used by the `CredentialRegistryIdentityValidatorPolicy` to check identities during policy evaluation.                                         |
| [ICredentialValidator](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/interfaces/ICredentialValidator.sol)         | Validates whether specific credentials exist and are valid for a given CCID. Provides both single-credential and batch validation functions.                                                                             |
| [ICredentialDataValidator](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/interfaces/ICredentialDataValidator.sol) | Optional interface for inspecting the contents of a credential's `credentialData` field. Enables granular, data-level checks beyond simple attestation (e.g., verifying a specific claim within the credential payload). |
| [ITrustedIssuerRegistry](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/interfaces/ITrustedIssuerRegistry.sol)     | Manages the list of trusted credential issuers — addresses authorized to register and manage credentials in a credential registry.                                                                                       |

## Data validators

Data validators inspect the contents of a credential's `credentialData` field, enabling checks beyond simple attestation (for example, a jurisdiction allow/deny list). They are attached to a [Credential Source](/ace/concepts/cross-chain-identity#credential-sources) and invoked by the identity validator policies after the credential's existence is confirmed. Data validators are a curated catalog maintained by Chainlink — see [Beta Scope](/ace/beta-scope#credential-data-validation-is-a-curated-catalog) for details.

| Contract                                                                                                                                                                   | Description                                                                                                                                                                                                                                                                                    |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AllowDenyListDataValidator](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/data-validators/AllowDenyListDataValidator.sol) | Pre-built `ICredentialDataValidator` that validates a `bytes32[]` credential payload against an allowlist and denylist, with optional restriction by credential type. Used for jurisdiction control (ISO 3166-1 alpha-2 country codes). Configuration is versioned for optimistic concurrency. |
| [DataValidatorFactory](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/data-validators/DataValidatorFactory.sol)             | Deploys deterministic data validator instances (minimal-proxy clones or ERC-1967 proxies) from an implementation, with `create` and idempotent `getOrCreate` variants. Verifies the implementation supports the required interfaces via ERC-165.                                               |
| [IInitializableDataValidator](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/src/interfaces/IInitializableDataValidator.sol)    | Minimal initializer surface (`initialize(initialOwner, configData)`) implemented by data validators so the factory can deploy and configure them in one step.                                                                                                                                  |

## Repository documentation

The [cross-chain-identity docs](https://github.com/smartcontractkit/chainlink-ace/tree/main/packages/cross-chain-identity/docs) folder contains detailed guides:

- [Concepts](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/docs/CONCEPTS.md)
  — CCID model, credential type IDs, privacy, and design rationale
- [API Guide](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/docs/API_GUIDE.md)
  — Deploy registries, configure validator policies, and authorize issuers
- [API Reference](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/docs/API_REFERENCE.md)
  — Complete interface specifications with function signatures, events, and errors
- [Credential Flow](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/docs/CREDENTIAL_FLOW.md)
  — End-to-end lifecycle from issuance to validation
- [Security Considerations](https://github.com/smartcontractkit/chainlink-ace/blob/main/packages/cross-chain-identity/docs/SECURITY.md)
  — Issuer trust, PII handling, CCID correlation, and non-reverting requirements

## Related pages

- [Cross-Chain Identity](/ace/concepts/cross-chain-identity) — Conceptual overview of CCIDs, registries, and credential sources
- [Credential Registry Identity Validator Policy](/ace/reference/policy-library/credential-registry-identity-validator-policy) — The policy that checks credentials at transaction time