# Identity & Claims The Identity component provides on-chain identity infrastructure based on the [OnchainID standard](https://onchainid.com/), which combines ERC-734 (key management) and ERC-735 (claims). It is the substrate on which all compliance checks in the Permissioned Tokens component rest: before an investor can hold or transfer a regulated token, they must have an on-chain identity with valid claims issued by a trusted authority. Beyond token compliance, Identity can be used standalone for any use case that requires verifiable on-chain credentials: accreditation checks, professional licensing, regulatory reporting, or cross-border access control. {% hint style="info" %} Personal identifiable information (PII) is never stored on-chain. All claim documents are stored encrypted via the Data Storage component and referenced on-chain only by content hash. Unauthorized access is blocked at three independent layers before any document can be read. {% endhint %} ## What OnchainID Is An OnchainID identity is a smart contract deployed for each subject (typically a wallet address representing a person or legal entity). The contract stores: * **Keys** (ERC-734): cryptographic public keys associated with the identity, with purpose labels (signing, encryption, claim issuance, management). * **Claims** (ERC-735): attestations made by external issuers about the subject, referenced by a hash that binds the claim to an encrypted document held in off-chain storage. The claim model separates the fact that a claim exists (visible on-chain) from the content of the claim (encrypted, off-chain, access-controlled). Regulators and counterparties can verify that a valid KYC claim exists without seeing the underlying documents unless they have been explicitly granted access. ## Claim Model A claim is a structured attestation from an issuer (e.g. a regulated KYC provider) about a subject (the identity contract holder). Claims are categorized by topic — a numeric identifier that corresponds to a specific compliance requirement. The platform defines eight registered topics: | Topic | Name | Purpose | Typical Expiry | | ----- | ------------------- | -------------------------------------------------- | ------------------------------- | | `1` | KYC | Identity verification (passport, proof of address) | 12 months | | `2` | AML | Anti-money-laundering screening | 30 days (rolling, auto-renewed) | | `3` | Accreditation | Accredited or qualified investor status | 12 months | | `4` | Sanctions Clear | Continuous sanctions list screening | 30 days (rolling, auto-renewed) | | `5` | Tax Residency | CRS / FATCA tax residency declaration | 12 months | | `6` | UBO | Ultimate Beneficial Owner declaration | 12 months | | `7` | PEP Status | Politically Exposed Person check | 30 days (rolling, auto-renewed) | | `8` | Travel Rule Profile | Originator information for payment disclosures | 6 months | ```mermaid flowchart TD Issuer["Claim Issuer\n(e.g. KYC provider)"] Subject["Subject Identity Contract\n(investor wallet)"] Storage["Encrypted Document\n(stored via Data Storage)"] Registry["IIdentityRegistry\n(on-chain)"] Verifier["Verifier\n(e.g. token compliance check)"] Issuer -- "1. Encrypt + store\nclaim document" --> Storage Issuer -- "2. Issue claim\n(topic + signature + doc hash)" --> Subject Subject -- "3. Register identity" --> Registry Verifier -- "4. Check: is subject registered\nwith valid claim for topic?" --> Registry Verifier -- "5. (optional) Request document\naccess for detailed review" --> Subject Subject -- "6. Grant per-verifier\ndecryption access" --> Verifier Verifier -- "7. Fetch + decrypt\nclaim document" --> Storage ``` Steps 1–4 are the standard compliance flow used by every token transfer check. Steps 5–7 are the selective disclosure flow, used when a verifier needs to inspect the underlying document (for example, a regulator conducting a detailed AML review). ### Claim Lifecycle | State | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------- | | **Pending** | A KYC application has been submitted to the issuer but has not yet been reviewed. No on-chain claim exists yet. | | **Issued** | Issuer has signed and published the claim to the subject's identity contract. | | **Valid** | Claim is issued, not expired, and the issuer is still in the token's ITrustedIssuersRegistry for the relevant claim topic. | | **Expired** | Claim passed its validity period. The subject must obtain a renewed claim from the issuer. | | **Revoked** | Issuer has explicitly revoked the claim. Revocation is immediate and on-chain. | ### Claim Renewal Claims with a finite validity period expire and must be renewed before they lapse to avoid disrupting investor access. When a claim approaches expiry, either the investor or an automated monitoring service calls `id_renewClaim`. The issuer re-runs the relevant verification checks (identity re-verification, updated screening, refreshed documentation), and if the result is satisfactory, issues a new claim with an extended expiry period. The new claim replaces the old one on the identity contract; the old claim is revoked atomically in the same transaction. Renewal does not require the investor to re-submit documents unless the issuer requests updated materials. For short-rolling-window claims managed by an automated AML screening service, renewal is fully automated with no investor action required. ### Continuous Screening AML (topic 2), Sanctions Clear (topic 4), and PEP Status (topic 7) are managed by an automated AML Screening Service rather than a human issuer. The screening service: * Runs continuous monitoring against updated sanctions lists, PEP registries, and adverse-media databases. * Automatically renews passing claims on their 30-day rolling window without any investor action. * Immediately revokes a claim if a hit is detected, triggering a compliance alert and freezing the investor's ability to transfer regulated tokens. This model means that a sanctions or PEP designation that occurs after initial onboarding is reflected on-chain within 24 hours, with no manual intervention required. Fund administrators receive a notification on claim revocation so they can follow up with the investor through the appropriate compliance workflow. ## Document Storage Claim documents — the actual KYC reports, AML screening results, accreditation certificates — are stored using the following scheme: 1. The issuer encrypts the document using a symmetric key. 2. The symmetric key is wrapped using the subject's ML-KEM-768 public key (so only the subject can initially decrypt it). 3. The encrypted document is published to the Data Storage component (torrent-ccip), which returns a content-addressed hash (IPFS CID or torrent infohash). 4. The on-chain claim record stores the content hash. Any tampering with the stored document would change the hash and break the binding. This scheme gives three guarantees: * **Confidentiality**: only parties with a delegated decryption key can read the document. * **Integrity**: the on-chain hash detects any tampering with the off-chain document. * **Availability**: the document is stored in a distributed content-addressed network, not on a central server that can be taken down. ## Selective Disclosure A subject (or their authorized agent) can grant a specific verifier access to a specific claim document without re-issuing the claim. The access grant is a delegated decryption envelope: 1. The subject re-wraps the symmetric key for the verifier's ML-KEM-768 public key. 2. The wrapped key is published on-chain as an access grant tied to the verifier's DID and the specific claim. 3. The verifier can now fetch the encrypted document and unwrap the key using their own private key. Access can be granted and revoked independently per verifier. Revoking access does not affect the claim itself or any other verifier's access. The access grant is scoped: a verifier with access to a KYC claim cannot use that grant to access an AML claim unless separately authorized. ## Access Control: Three Layers Unauthorized access to claim documents is prevented at three independent layers: | Layer | Mechanism | Where enforced | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | **UCAN Middleware** | RPC calls to read or grant claim access require a UCAN capability token scoped to the correct identity and claim topic. | Node RPC layer, before any contract call. | | **On-Chain Access Check** | The identity contract's `canAccess(verifier, claimTopic)` function is called before returning a document reference. | Smart contract, on every read. | | **Envelope Delegation** | Even with a valid access grant, the document is useless without the wrapped decryption key, which is only available to the designated verifier. | Cryptographic, in the client. | A successful attack would need to bypass all three layers simultaneously. ## DID Bridging OnchainID identities are bridged to the W3C DID standard for interoperability with external identity systems: * **did:pkh** — Each Ethereum wallet address is represented as a `did:pkh:eip155:...` DID. This allows the identity to be referenced in standard verifiable credential flows outside the Cocoon chain. * **did:key** — Each ML-KEM-768 encryption key pair used for claim document wrapping is expressed as a `did:key` DID, making key discovery machine-readable and standards-compliant. DID documents are resolved on-demand from the chain state; there is no separate DID registry contract. ## Integration with Permissioned Tokens Identity is the compliance backbone of Permissioned Tokens. The integration points are: * **Investor onboarding**: `token_onboardInvestor` deploys an identity contract, issues required claims, and registers the identity in the token's IIdentityRegistry in a single atomic call. * **Transfer validation**: every transfer check calls `IIdentityRegistry.isVerified(wallet)` for both sender and receiver. This query checks that the wallet has a registered identity with valid claims for all topics required by the token's `IClaimTopicsRegistry`. * **Compliance modules**: the Country Allow List module reads the country claim from the identity to determine whether the wallet is in a permitted jurisdiction. * **Regulatory access**: fund administrators can grant regulators selective disclosure access to investor claim documents for audit and reporting purposes without exposing documents to other parties. ## Key RPC Methods {% tabs %} {% tab title="Identity Management" %} | Method | Description | | ------------------- | --------------------------------------------------------------- | | `id_createIdentity` | Deploy a new OnchainID contract for a wallet address. | | `id_getIdentity` | Return the identity contract address and key list for a wallet. | | `id_addKey` | Add a key to an identity contract (e.g. add a new signing key). | | `id_removeKey` | Remove a key from an identity contract. | | {% endtab %} | | {% tab title="Claims" %} | Method | Description | | ---------------- | ---------------------------------------------------------------------------------------------------- | | `id_issueClaim` | Issue a claim to a subject identity, encrypting and storing the backing document. | | `id_getClaim` | Return claim metadata (topic, issuer, validity, doc hash) for a given identity and topic. | | `id_revokeClaim` | Revoke a previously issued claim. Takes effect immediately on-chain. | | `id_verifyClaim` | Check whether a claim is currently valid for a given identity and topic. | | `id_renewClaim` | Renew an expiring claim; issuer re-runs verification and replaces the claim with an extended expiry. | | {% endtab %} | | {% tab title="KYC Applications" %} | Method | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `id_submitKycApplication` | Submit a KYC application for a given identity and claim topic, attaching supporting documents for issuer review. Returns an `applicationId`. | | `id_getKycApplication` | Return the current status (`pending`, `approved`, `rejected`) and metadata of a KYC application. | | `id_reviewKycApplication` | Approve or reject a pending KYC application. Approving automatically issues the claim on-chain. Caller must be the trusted issuer for the topic. | | {% endtab %} | | {% tab title="Selective Disclosure" %} | Method | Description | | ---------------------- | -------------------------------------------------------------------------------------------- | | `id_grantClaimAccess` | Grant a specific verifier DID access to a specific claim document. | | `id_revokeClaimAccess` | Revoke a verifier's access to a claim document. | | `id_getClaimDocument` | Fetch and decrypt a claim document (requires a valid access grant or subject authorization). | | `id_listAccessGrants` | List all active access grants for a given identity and claim topic. | | {% endtab %} | | | {% endtabs %} | | ## Security Notes * **PII isolation**: The system is designed so that PII can never appear on-chain even in an error condition. Claim content is encrypted client-side before any network call is made. * **Tamper detection**: The on-chain claim record binds to the document's content hash. If the stored document is modified, `id_getClaimDocument` will return an integrity error rather than the tampered content. * **Key rotation**: ERC-734 key management allows the subject to rotate their encryption key pair. When a key is rotated, existing claim documents can be re-encrypted under the new key; access grants issued to verifiers under the old key remain valid until explicitly revoked. * **Issuer revocation**: If a claim issuer is removed from the `ITrustedIssuersRegistry`, all claims they issued for that claim topic immediately become invalid for compliance purposes, without any change to the claims themselves. This allows rapid response to a compromised or de-licensed issuer. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cocoon.erigon.tech/components/identity.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.