DID Management

Decentralized Identifiers (DIDs) are the foundation of self-sovereign identity in KryptoOS. This guide covers everything you need to know about managing DIDs.

What are DIDs?

A Decentralized Identifier (DID) is a globally unique identifier that enables verifiable, decentralized digital identity. DIDs are:

Self-sovereign: You own and control them completely
Persistent: Independent of any centralized authority
Resolvable: Can be looked up to retrieve associated information
Cryptographically verifiable: Secured by public-key cryptography
W3C compliant: Following the W3C DID Core 1.0 specification

DID Format

KryptoOS uses the did:emp method:

did:emp:1234abcd5678efgh9012ijkl
│   │   └─────────────┬─────────────┘
│   │                 │
│   │                 └─ Unique identifier
│   └─ Method (emp = Empoorio)
└─ DID scheme

Creating a DID

Basic DID Creation

import { SSIClient } from '@empoorio/ssi-sdk';

const client = new SSIClient({
  nodeUrl: 'wss://ws.empooriochain.org'
});

// Create a new DID
const did = await client.did.register({
  method: 'Ed25519VerificationKey2020',
  controller: walletAddress
});

console.log('DID created:', did.id);
console.log('DID Document:', did.document);

Advanced DID Creation with Services

You can add service endpoints to your DID for communication and discovery:

const did = await client.did.register({
  method: 'Ed25519VerificationKey2020',
  controller: walletAddress,
  services: [
    {
      id: '#didcomm-1',
      type: 'DIDCommMessaging',
      serviceEndpoint: 'https://messaging.example.com'
    },
    {
      id: '#profile-1',
      type: 'ProfileService',
      serviceEndpoint: 'https://profile.example.com/user/123'
    }
  ]
});

DID Documents

A DID Document contains the public keys, authentication methods, and service endpoints associated with a DID.

Structure

{
  "id": "did:emp:1234abcd",
  "controller": ["did:emp:1234abcd"],
  "verificationMethod": [
    {
      "id": "did:emp:1234abcd#keys-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:emp:1234abcd",
      "publicKeyMultibase": "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
    }
  ],
  "authentication": ["did:emp:1234abcd#keys-1"],
  "assertionMethod": ["did:emp:1234abcd#keys-1"],
  "keyAgreement": ["did:emp:1234abcd#keys-1"],
  "capabilityInvocation": ["did:emp:1234abcd#keys-1"],
  "service": [
    {
      "id": "#didcomm-1",
      "type": "DIDCommMessaging",
      "serviceEndpoint": "https://messaging.emp"
    }
  ]
}

Verification Relationships

authentication: Keys used to authenticate as the DID subject
assertionMethod: Keys used to issue verifiable credentials
keyAgreement: Keys used for encryption (e.g., DIDComm)
capabilityInvocation: Keys used to invoke capabilities
capabilityDelegation: Keys used to delegate capabilities

Resolving DIDs

Retrieve a DID Document from the blockchain:

const didDocument = await client.did.resolve('did:emp:1234abcd');

console.log('Controller:', didDocument.controller);
console.log('Verification Methods:', didDocument.verificationMethod);
console.log('Services:', didDocument.service);

Updating DID Documents

Adding Verification Methods

Add new cryptographic keys to your DID:

await client.did.addVerificationMethod({
  did: 'did:emp:1234abcd',
  verificationMethod: {
    id: 'did:emp:1234abcd#keys-2',
    type: 'EcdsaSecp256k1VerificationKey2019',
    controller: 'did:emp:1234abcd',
    publicKeyMultibase: 'zQ3s...'
  },
  purposes: ['authentication', 'assertionMethod']
});

Adding Services

Add service endpoints for communication:

await client.did.addService({
  did: 'did:emp:1234abcd',
  service: {
    id: '#api-1',
    type: 'APIService',
    serviceEndpoint: 'https://api.example.com/v1'
  }
});

Updating the Entire Document

const updatedDoc = await client.did.update({
  did: 'did:emp:1234abcd',
  document: {
    // Updated DID Document
    verificationMethod: [...],
    service: [...],
    // ... other fields
  }
});

Key Rotation

Rotating cryptographic keys is essential for security. KryptoOS supports seamless key rotation:

Step 1: Add New Key

// Add new verification method
await client.did.addVerificationMethod({
  did: 'did:emp:1234abcd',
  verificationMethod: newKey,
  purposes: ['authentication', 'assertionMethod']
});

Step 2: Update Applications

Update all applications and services to use the new key.

Step 3: Remove Old Key

// Remove old verification method after grace period
await client.did.removeVerificationMethod({
  did: 'did:emp:1234abcd',
  verificationMethodId: 'did:emp:1234abcd#keys-1'
});

Best Practices

Grace Period: Keep old keys active for 30-90 days
Notifications: Notify relying parties about key rotation
Backup: Securely backup new keys before removing old ones
Regular Rotation: Rotate keys annually or after suspected compromise

Deactivating DIDs

Permanently deactivate a DID when it's no longer needed:

await client.did.deactivate('did:emp:1234abcd');

Important

Deactivation is permanent and irreversible. The DID cannot be reactivated or reused.

When to Deactivate

Account closure
Security compromise (after creating a new DID)
Organizational restructuring
End of service

DID Controllers

DIDs can have multiple controllers for shared management:

const did = await client.did.register({
  method: 'Ed25519VerificationKey2020',
  controller: [
    'did:emp:user-123',      // Primary controller
    'did:emp:backup-456',    // Backup controller
    'did:emp:guardian-789'   // Guardian for recovery
  ]
});

Use Cases for Multiple Controllers

Corporate accounts: Multiple executives control company DID
Recovery: Trusted guardians can help recover access
Delegation: Temporary delegation to service providers
Multi-sig: Require multiple signatures for critical operations

Pairwise DIDs

Create unique DIDs for each relationship to enhance privacy:

// Create pairwise DID for relationship with specific verifier
const pairwiseDid = await client.did.createPairwise({
  peerDid: 'did:emp:verifier-456',
  purpose: 'employment-verification'
});

// This DID is only used with this specific verifier
console.log('Pairwise DID:', pairwiseDid.id);

Benefits

Privacy: Prevents correlation across different services
Selective disclosure: Different identities for different contexts
Revocation: Revoke relationship without affecting others

DID Registry (On-Chain)

KryptoOS stores DID anchors on the EmpoorioChain blockchain:

What's Stored On-Chain

DID identifier
Hash of DID Document
Controller addresses
Verification method references
Service endpoint hashes
Version number
Creation and update timestamps

What's NOT Stored On-Chain

Private keys (always kept off-chain)
Personal identifiable information (PII)
Full service endpoint URLs (only hashes)
Credential data

Transaction Fees

DID operations require Dracma (DMS) tokens for transaction fees:

Operation	Approximate Fee
Register DID	0.1 Dracma (DMS)
Update DID Document	0.05 Dracma (DMS)
Add Verification Method	0.03 Dracma (DMS)
Add Service	0.02 Dracma (DMS)
Deactivate DID	0.05 Dracma (DMS)