Identity & Claims

The Identity component provides on-chain identity infrastructure based on the OnchainID standard, 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.

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.

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, such as KYC verification, AML screening, country of residence, or investor accreditation.

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
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.

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

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.

Claims

Selective Disclosure

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.