Identity & attestations.

Verify once, trusted everywhere. The identity layer anchors a user-owned DID on-chain, attaches typed attestations to it, and gates every read behind the user's explicit grant. Recovery, merge, and revocation are built so that no builder, and not the Foundation, can take the identity away. This is the architectural heart of the substrate; payments sit downstream of it.

The DID is the identity

IdentityRegistry anchors decentralized identifiers derived from a key plus salt. On-chain, a DID reveals exactly one thing: that its holder controls a private key. No name, no country, no balance, no transaction history is attached by the protocol. One controlling key can hold unbounded DIDs, and the key, not any account at any company, is the ground truth of ownership. The Foundation holds no role that can rotate it. Addresses for every contract on this page live in the contract registry.

Handles and the institutional tick

HandleRegistry maps human-readable names, @aminata@kofi.businessto DIDs. Registration is opt-in: it trades pseudonymity for discoverability, a tradeoff appropriate for businesses and institutions and one that wallets must make legible to individuals. Institutional handles are the top of the trust model: regulated institutions receive category-verified handles with a visual tick, issued by verifiers that the Foundation authorizes per institutional category through the multi-sig with a 14-day timelock, one of the few deliberately Foundation-gated surfaces (Charter §8.4.2).

The three-layer trust model

Three levels of assurance, distinct by design. A wallet, a lender, or an embassy decides how much identity it needs; the protocol never forces more.

Layer	What it proves	Anchored by
1 · DID	A key pair controls this identifier. Minimum viable identity.	IdentityRegistry
2 · Attestations	Typed, signed claims about the DID, phone verified, KYC tier, employment confirmed.	AttestationsRegistry · IdentityAttestations
3 · Institutional verification	A regulated institution is who its handle says it is. The visual tick.	HandleRegistry

Attestations, typed, consented, hash-only

An attestation is a typed, signed claim about a DID. AttestationsRegistry holds the schema registry and issuance policies; IdentityAttestations holds per-DID records with freshness and multi-attester support. Benign identity-scoped attestations require the subject's EIP-712 consent, a friend or an app cannot append a favourable-looking claim to your identity unsolicited. Regulatory and adverse records are the deliberate exception: authoritative negative records (defaults, dispute history) and the regulator-only adverse band (AML, sanctions, PEP flags) are issued under accredited-issuer authority without the subject's consent, by design, a subject cannot suppress a sanctions flag by withholding a signature. Only a 32-byte commitment (dataHash) touches the chain; the claim's content stays off-chain, delivered through channels the subject controls and checked against the commitment. No PII is stored on-chain, only commitments and attestation references.

Who may issue depends on the schema's policy: OPEN (any DID), ACCREDITED (issuers accredited per schema, authorized by the Foundation through the 14-day timelock, revocable), or RESTRICTED (a per-schema authorized-verifier set with bounded mandates). That is the precise sense in which issuance is permissionless: open schemas are; accredited ones are Foundation-gated by design.

Reads are consent-gated

SelectiveDisclosure enforces the rule that the grant is the gate, not the caller. Users sign EIP-712 grants scoped to specific readers and attestation scopes, with a full grant / revoke / expire lifecycle. It is the contract behind Sign in with Adunaiand behind ReputationExportthe read-only assembler that packages consented attestations into a portable reputation bundle a lender or landlord verifies item-by-item. Verify once with an accredited attester; prove it, on your terms, to any counterparty that asks. The SDK wraps both flows.

Recovery, three tiers, and the right to leave

Users choose a recovery posture at signup and can upgrade later.

Tier	Mechanism	Coordinated by
1 · Time-locked (default)	Phone/email proof opens a 60–90-day timelock the legitimate user can veto.	IdentityRegistry recovery config
2 · Social guardians (recommended)	2–7 guardian DIDs; a majority co-signs key rotation.	GuardianRegistry
3 · KYC re-verification (advanced)	Multiple accredited attesters co-sign recovery against re-verified KYC.	AttesterRegistry attesters
Reclaim	Escape a hostile or unavailable builder without its cooperation.	AbandonmentRegistry

The last row is the portability guarantee. If a builder custodied a user's key and turns hostile or disappears, AbandonmentRegistry lets the user claim the identity back: a 60–90-day timelocked claim, vetoable during the window by the current key or any registered guardian, writing a key override on expiry. GuardianRegistry and AbandonmentRegistry are non-upgradeable, non-pausable, and role-free, the Foundation cannot cancel an abandonment, rotate a user's key, or veto a recovery (Charter Article VIII). Every signature-gated identity surface resolves keys through the override-aware path, so a recovered user keeps their handles.

Linkage and merge

African users accumulate DIDs, multiple SIMs, shared devices, diaspora signups across apps. LinkedIdentitiesRegistry lets the same human merge up to five DIDs with mutual signatures, or with abandonment-claim proofs where one DID was hostile-recovered. Linked DIDs stay technically distinct on-chain, attestations remain scoped to the issuing DID, while clients and the SDK aggregate the graph into one identity with combined history. Linkages are stored as commitments, not plaintext pairs; reveals route through SelectiveDisclosure; unlinking carries a 30-day timelock. The full merge architecture is whitepaper §4.

Revocation, with a cooling-off

A user can revoke their own DID through RevocationRegistry. Where the DID carries real activity, self-revocation has a cooling-off period at least as long as the abandonment timelock, so a hostile key-holder cannot scorch an identity while a legitimate abandonment claim is running. Fresh, unused DIDs revoke instantly; cleanup stays cheap.

Where you meet this layer

The reference implementations are aIDthe open-source reference identity client, identity home, grant flow, attestation management, linked identities, guardians and reclaim; identity only, no commerce, and a reference wallet held open for Phase 1+, with a public design preview. aID is forkable; neither it nor any reference wallet is privileged at the protocol layer, and no commercial builder is.