Identity Management

Comprehensive guide to Aqua Protocol’s decentralized identity management system

Identity Management

Aqua Protocol provides a robust decentralized identity management system that enables secure, privacy-preserving identity verification and attestation without relying on centralized authorities.

Overview

Aqua Protocol’s identity management system allows users to:

• Create decentralized identities with cryptographic proof
• Manage credentials and attestations securely
• Control access to personal data and services
• Verify identities without revealing sensitive information
• Maintain privacy while ensuring authenticity

Core Concepts

Decentralized Identity

A decentralized identity in Aqua Protocol is a cryptographically secured digital identity that:

• Exists independently of any centralized authority
• Is controlled entirely by the identity owner
• Can be verified through cryptographic proofs
• Maintains privacy through selective disclosure
• Is portable across different applications and services

Identity Components

Identity Document

The core identity document contains:

{
  "identityHash": "0x1234567890abcdef...",
  "publicKey": "0x0380a77a1a6d59be5c10d7ee5e10def79283938bb8a60025d0fe5404e650e8ccc1",
  "walletAddress": "0x568a94a8f0f3dc0b245b853bef572075c1df5c50",
  "metadata": {
    "name": "John Doe",
    "email": "[e-mail]",
    "created": "2024-01-15T10:30:00Z"
  },
  "verificationHash": "0xabcdef1234567890..."
}

Attestations

Credentials and claims associated with the identity:

{
  "attestationHash": "0x9876543210fedcba...",
  "subject": "0x1234567890abcdef...",
  "issuer": "0xuniversity123...",
  "claim": {
    "type": "educational_credential",
    "value": "Bachelor of Computer Science",
    "institution": "University of Technology",
    "issued": "2020-06-15T00:00:00Z"
  },
  "signature": "0x799cd8177dc2c5dc34d389601175d550466a73509b71d533aaa3ff0ee958b3b3...",
  "verificationHash": "0xfedcba0987654321..."
}

Creating Identities

Basic Identity Creation

import { AquaClient } from '@aqua-protocol/sdk';

const client = new AquaClient({
  apiKey: process.env.AQUA_API_KEY,
  endpoint: 'https://api.aqua-protocol.org/v3'
});

// Create a new identity
const identity = await client.createIdentity({
  name: 'John Doe',
  email: '[e-mail]',
  walletAddress: '0x568a94a8f0f3dc0b245b853bef572075c1df5c50',
  publicKey: '0x0380a77a1a6d59be5c10d7ee5e10def79283938bb8a60025d0fe5404e650e8ccc1'
});

console.log('Identity created:', identity.verificationHash);

Advanced Identity Creation

// Create identity with custom metadata
const identity = await client.createIdentity({
  name: 'John Doe',
  email: '[e-mail]',
  walletAddress: '0x568a94a8f0f3dc0b245b853bef572075c1df5c50',
  publicKey: '0x0380a77a1a6d59be5c10d7ee5e10def79283938bb8a60025d0fe5404e650e8ccc1',
  metadata: {
    dateOfBirth: '1995-10-15',
    nationality: 'US',
    phone: '[phone]',
    address: {
      street: '123 Main St',
      city: 'New York',
      state: 'NY',
      zipCode: '10001',
      country: 'US'
    }
  },
  options: {
    hashingMethod: 'tree', // Enable selective disclosure
    addWitness: true,
    addSignature: true
  }
});

Managing Attestations

Creating Attestations

// Create an educational credential attestation
const attestation = await client.createAttestation({
  subject: identity.verificationHash,
  issuer: '0xuniversity123...',
  claim: {
    type: 'educational_credential',
    value: 'Bachelor of Computer Science',
    institution: 'University of Technology',
    field: 'Computer Science',
    level: 'bachelor',
    issued: '2020-06-15T00:00:00Z',
    expires: '2030-06-15T00:00:00Z'
  },
  attestationType: 'educational_credential',
  options: {
    addWitness: true,
    addSignature: true
  }
});

Professional Attestations

// Create a professional certification attestation
const certification = await client.createAttestation({
  subject: identity.verificationHash,
  issuer: '0xprofessional123...',
  claim: {
    type: 'professional_certification',
    value: 'Certified Software Engineer',
    organization: 'Software Engineering Institute',
    certificationId: 'CSE-2024-001',
    issued: '2024-01-15T00:00:00Z',
    expires: '2026-01-15T00:00:00Z'
  },
  attestationType: 'professional_certification'
});

Identity Verification Attestations

// Create an identity verification attestation
const verification = await client.createAttestation({
  subject: identity.verificationHash,
  issuer: '0xverification123...',
  claim: {
    type: 'identity_verification',
    method: 'government_id',
    level: 'high',
    verified: true,
    issued: '2024-01-15T00:00:00Z'
  },
  attestationType: 'identity_verification'
});

Identity Verification

Basic Verification

// Verify an identity
const verification = await client.verifyIdentity({
  identityHash: identity.verificationHash,
  publicKey: identity.publicKey
});

console.log('Identity verification:', verification.isValid);

Attestation Verification

// Verify an attestation
const attestationVerification = await client.verifyAttestation({
  attestationHash: attestation.verificationHash,
  subject: identity.verificationHash,
  issuer: '0xuniversity123...'
});

console.log('Attestation verification:', attestationVerification.isValid);

Complete Identity Verification

// Verify complete identity with all attestations
const completeVerification = await client.verifyCompleteIdentity({
  identityHash: identity.verificationHash,
  includeAttestations: true,
  includeRevocation: true,
  options: {
    verifySignatures: true,
    verifyWitness: true,
    verifyTimestamps: true
  }
});

console.log('Complete verification:', completeVerification);

Selective Disclosure

Tree-based Verification

Aqua Protocol supports selective disclosure through Merkle tree verification:

// Create identity with selective disclosure
const identity = await client.createIdentity({
  name: 'John Doe',
  email: '[e-mail]',
  walletAddress: '0x568a94a8f0f3dc0b245b853bef572075c1df5c50',
  metadata: {
    dateOfBirth: '1995-10-15',
    ssn: '123-45-6789',
    address: '123 Main St, New York, NY 10001'
  },
  options: {
    hashingMethod: 'tree' // Enable selective disclosure
  }
});

// Disclose only specific fields
const selectiveVerification = await client.verifySelective({
  identityHash: identity.verificationHash,
  disclosedFields: ['name', 'email'], // Only disclose name and email
  verifier: '0xverifier123...'
});

Privacy-Preserving Verification

// Verify age without revealing exact birth date
const ageVerification = await client.verifyAge({
  identityHash: identity.verificationHash,
  minimumAge: 18,
  maximumAge: 65
});

console.log('Age verification:', ageVerification.isValid);
console.log('Age range:', ageVerification.ageRange);

Access Control Integration

Identity-based Access Control

// Create access policy based on identity
const accessPolicy = await client.createAccessPolicy({
  resource: '0xresource123...',
  rules: [
    {
      subject: identity.verificationHash,
      permissions: ['read', 'write'],
      conditions: {
        requiredAttestations: ['educational_credential'],
        minimumLevel: 'bachelor',
        validUntil: '2025-12-31T23:59:59Z'
      }
    }
  ]
});

// Check access based on identity
const hasAccess = await client.checkIdentityAccess({
  subject: identity.verificationHash,
  resource: '0xresource123...',
  action: 'read'
});

Credential-based Access

// Check access based on specific credentials
const credentialAccess = await client.checkCredentialAccess({
  subject: identity.verificationHash,
  resource: '0xresource123...',
  action: 'write',
  requiredCredentials: [
    {
      type: 'professional_certification',
      organization: 'Software Engineering Institute',
      minimumLevel: 'senior'
    }
  ]
});

Identity Recovery

Backup and Recovery

// Create identity backup
const backup = await client.createIdentityBackup({
  identityHash: identity.verificationHash,
  encryptionKey: 'user-provided-key',
  options: {
    includeAttestations: true,
    includeMetadata: true
  }
});

// Restore identity from backup
const restoredIdentity = await client.restoreIdentity({
  backup: backup,
  decryptionKey: 'user-provided-key'
});

Key Recovery

// Set up key recovery
const recoverySetup = await client.setupKeyRecovery({
  identityHash: identity.verificationHash,
  recoveryMethod: 'social_recovery',
  guardians: [
    '0xguardian1...',
    '0xguardian2...',
    '0xguardian3...'
  ],
  threshold: 2 // Require 2 out of 3 guardians
});

// Recover identity using guardians
const recoveredIdentity = await client.recoverIdentity({
  identityHash: identity.verificationHash,
  guardianSignatures: [
    '0xsignature1...',
    '0xsignature2...'
  ]
});

Best Practices

Security

• Protect private keys used for identity signing
• Use hardware wallets for high-value identities
• Regularly rotate identity keys
• Monitor identity for unauthorized changes

Privacy

• Use selective disclosure for sensitive information
• Minimize data collection to only necessary fields
• Implement data retention policies
• Provide user control over data sharing

Usability

• Simplify identity creation process
• Provide clear verification status
• Enable easy backup and recovery
• Support multiple authentication methods

Use Cases

Digital Identity

• Government services and e-identity
• Healthcare patient records
• Financial services and KYC
• Education credentials and transcripts

Professional Identity

• Professional certifications and licenses
• Employment verification and references
• Skills assessment and portfolios
• Continuing education credits

Access Control

• Building access and security systems
• Digital services and subscriptions
• Content access and permissions
• API access and rate limiting