> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.adid.dev/llms.txt. > For full documentation content, see https://docs.adid.dev/llms-full.txt. # did:adi Method Specification **Version:** 1.0 **Status:** Draft **Authors:** Infinia Team **Date:** 2026-03-28 This document specifies the `did:adi` DID method, conformant with the [W3C DID Core v1.0](https://www.w3.org/TR/did-core/) specification. The `did:adi` method uses the ADI blockchain as its Verifiable Data Registry. *** ## 1. DID Method Name The method name for this DID method is `adi`. A DID using this method MUST begin with the prefix `did:adi:`. The remainder of the DID is the method-specific identifier described below. ## 2. Method-Specific Identifier ### 2.1 ABNF Syntax ```abnf did-adi = "did:adi:" method-specific-id method-specific-id = entity-id / agent-id entity-id = 1*64HEXDIG agent-id = "agent:" 1*64HEXDIG HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" DIGIT = %x30-39 ; 0-9 ``` ### 2.2 Identifier Generation The method-specific identifier is derived from the initial public key: 1. Generate a cryptographic key pair (Ed25519, secp256k1, or P-256) 2. Compute `SHA-256(publicKey)` 3. Take the first 32 bytes (64 hex characters) as the identifier 4. For AI agents, prefix with `agent:` ### 2.3 Examples ``` did:adi:3f7a9b2e1c4d5f6a8b0c2d4e6f8a0b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f did:adi:agent:7f3a9b2e1c4d5f6a8b0c2d4e6f8a0b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f ``` ## 3. DID Document ### 3.1 Structure Every `did:adi` DID Document MUST conform to the W3C DID Core Data Model. The document is stored on the ADI blockchain via the DID Registry smart contract. ```json { "@context": [ "https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/ed25519-2020/v1", "https://w3id.org/security/suites/secp256k1-2019/v1", "https://ida.infinia.io/ns/did/v1" ], "id": "did:adi:3f7a9b2e1c4d5f6a8b0c2d4e6f8a0b2c...", "controller": "did:adi:3f7a9b2e1c4d5f6a8b0c2d4e6f8a0b2c...", "verificationMethod": [ { "id": "did:adi:3f7a...#key-1", "type": "Ed25519VerificationKey2020", "controller": "did:adi:3f7a...", "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP" } ], "authentication": ["did:adi:3f7a...#key-1"], "assertionMethod": ["did:adi:3f7a...#key-1"], "keyAgreement": [ { "id": "did:adi:3f7a...#key-agreement-1", "type": "X25519KeyAgreementKey2020", "controller": "did:adi:3f7a...", "publicKeyMultibase": "z6LShs9GGnqk85JBBenbnvGGnm1V8..." } ], "service": [ { "id": "did:adi:3f7a...#didcomm", "type": "DIDCommMessaging", "serviceEndpoint": "https://agent.example.com/didcomm" } ], "created": "2026-03-28T10:00:00Z", "updated": "2026-03-28T10:00:00Z", "versionId": 1, "deactivated": false } ``` ### 3.2 Verification Methods The `did:adi` method supports the following verification key types: | Type | Curve | Usage | | ----------------------------------- | --------- | ------------------------------------------------ | | `Ed25519VerificationKey2020` | Ed25519 | Authentication, assertion, capability invocation | | `EcdsaSecp256k1VerificationKey2019` | secp256k1 | Authentication, assertion (blockchain-native) | | `JsonWebKey2020` (P-256) | P-256 | Authentication (FIDO2/WebAuthn compatibility) | | `X25519KeyAgreementKey2020` | X25519 | Key agreement for encrypted communications | | `Bls12381G2Key2020` | BLS12-381 | BBS+ selective disclosure signatures | ### 3.3 Verification Relationships | Relationship | Purpose | | ---------------------- | --------------------------------------- | | `authentication` | Prove control of the DID (DID Auth) | | `assertionMethod` | Issue Verifiable Credentials | | `keyAgreement` | Establish encrypted channels (DIDComm) | | `capabilityInvocation` | Invoke capabilities (IBCT verification) | | `capabilityDelegation` | Delegate capabilities to other DIDs | ## 4. CRUD Operations ### 4.1 Create (Register) To create a new `did:adi`: 1. **Generate key pair**: Client generates one or more cryptographic key pairs 2. **Compute DID**: `did:adi:` + SHA-256(publicKey)\[0:32].hex() 3. **Construct DID Document**: Build conformant document with verification methods 4. **Submit transaction**: Call `DIDRegistry.registerDID(did, didDocumentHash, ipfsHash)` on ADI blockchain 5. **Store document**: Upload full DID Document to IPFS, store hash on-chain ```solidity // On-chain registration function registerDID( string calldata did, bytes32 didDocumentHash, string calldata storageUri ) external; ``` The transaction MUST be signed by the private key corresponding to the first authentication key in the DID Document. ### 4.2 Read (Resolve) DID resolution returns the DID Document and metadata: 1. **Query on-chain**: Call `DIDRegistry.resolveDID(did)` to get document hash and storage URI 2. **Fetch document**: Retrieve full DID Document from IPFS using the storage URI 3. **Verify integrity**: Confirm `SHA-256(document) == onChainHash` 4. **Return**: DID Document + resolution metadata ``` GET /api/v1/dids/did:adi:3f7a9b2e... ``` Resolution metadata: ```json { "didDocument": { ... }, "didDocumentMetadata": { "created": "2026-03-28T10:00:00Z", "updated": "2026-03-28T10:00:00Z", "versionId": 1, "deactivated": false, "nextUpdate": null, "equivalentId": null }, "didResolutionMetadata": { "contentType": "application/did+ld+json", "duration": 45, "cached": false } } ``` ### 4.3 Update To update a DID Document: 1. **Authenticate**: Sign the update with a key listed in the current `authentication` relationship 2. **Modify document**: Add/remove verification methods, update services, etc. 3. **Submit transaction**: Call `DIDRegistry.updateDID(did, newDocumentHash, newStorageUri, signature)` 4. **Increment version**: On-chain version counter increments automatically Allowed updates: | Operation | Requires | | -------------------------- | ---------------------------------------------------------- | | Add verification method | Authentication key signature | | Remove verification method | Authentication key signature (cannot remove last auth key) | | Add service endpoint | Authentication key signature | | Remove service endpoint | Authentication key signature | | Rotate keys | Old authentication key signature + new key material | | Change controller | Current controller's signature | ### 4.4 Deactivate Deactivation is permanent and irreversible: 1. **Authenticate**: Sign with authentication key 2. **Submit transaction**: Call `DIDRegistry.deactivateDID(did, signature)` 3. **On-chain state**: `deactivated` flag set to `true` 4. **Resolution**: Returns DID Document with `deactivated: true` After deactivation: * The DID can still be resolved (returns deactivated document) * No further updates are possible * All VCs issued by this DID should be treated as suspect * This satisfies GDPR right-to-erasure requirements ## 5. Security Considerations ### 5.1 Key Compromise If a private key is compromised: 1. Use a different authentication key (if multiple exist) to rotate the compromised key 2. If all authentication keys are compromised, use the recovery key (stored separately) 3. If no recovery is possible, the DID should be considered compromised ### 5.2 Recovery Mechanism The `did:adi` method supports social recovery: * A DID Document may include a `recovery` verification relationship * Recovery keys can be held by trusted parties (e.g., 3-of-5 multisig) * Recovery replaces all authentication keys and requires on-chain transaction ### 5.3 Replay Protection All on-chain transactions include: * **Nonce**: Monotonically increasing per DID * **Chain ID**: ADI chain identifier to prevent cross-chain replay * **Timestamp**: Transaction timestamp for temporal ordering ### 5.4 Man-in-the-Middle * DID resolution integrity is guaranteed by on-chain hash verification * IPFS content addressing provides content integrity * DIDComm messages are encrypted end-to-end with X25519 ### 5.5 Quantum Resistance The current key types (Ed25519, secp256k1) are not quantum-resistant. The specification anticipates future extension to post-quantum algorithms (e.g., CRYSTALS-Dilithium) as standards mature. ## 6. Privacy Considerations ### 6.1 Correlation * Each `did:adi` is globally unique and persistent, enabling correlation * For privacy-sensitive interactions, use pairwise DIDs (unique per relationship) * BBS+ credentials enable selective disclosure without revealing the full DID ### 6.2 On-Chain Data Only the following data is stored on-chain: * DID string * DID Document hash (SHA-256) * IPFS storage URI * Version counter * Deactivation flag * Timestamps No personally identifiable information (PII) is stored on-chain. ### 6.3 Herd Privacy DID resolution queries to ADI nodes may reveal which DIDs are being resolved. Mitigation: * Use a trusted resolver service * Batch resolution queries * Future: Private information retrieval (PIR) techniques ## 7. Conformance This DID method is designed to be conformant with: | Specification | Conformance Level | | ----------------------- | ---------------------------- | | W3C DID Core v1.0 | Full | | W3C DID Resolution v1.0 | Full | | DIF DIDComm v2 | Full | | Universal Resolver | Compatible | | GDPR | Compliant (via deactivation) | | eIDAS 2.0 | Aligned | ## 8. Reference Implementation The reference implementation is located at: * **DID Registry Smart Contract**: `packages/blockchain/contracts/DIDRegistry.sol` * **DID Service**: `packages/api/internal/did/` * **DID Resolver**: `packages/api/internal/resolver/`