W3C-compliant Decentralized Identity module for managing DIDs, verifiable credentials, and WebAuthn authentication on Sonr blockchain

DID Module (x/did)

Scope

This document covers the DID module's implementation of W3C DID Core specification, including DID documents, verification methods, verifiable credentials, and WebAuthn integration. It details data structures, messages, queries, and security considerations. This document does not cover deployment procedures or client SDK usage—see the SDK documentation for integration details.

Audience

Blockchain developers implementing identity features. System integrators connecting applications to Sonr's identity layer. Security engineers evaluating DID implementations. Prerequisites: Understanding of W3C DID specification, blockchain state machines, and Protocol Buffers.

Summary

The DID module implements W3C Decentralized Identifiers on the Sonr blockchain. It manages DID documents with verification methods (including WebAuthn), service endpoints, and verifiable credentials. The module provides on-chain resolution, cryptographic proof requirements, and standard-compliant identity operations. All state transitions require authorization from DID controllers.

Module Features

The DID module provides:

W3C DID Documents: Full implementation of DID Core specification
Verifiable Credentials: Issue and manage W3C-compliant credentials
Verification Methods: Support for JSON Web Keys and WebAuthn
Service Endpoints: Associate services with DIDs
On-chain Resolution: Decentralized DID resolution

Core Concepts

Decentralized Identifiers (DIDs)

DIDs are globally unique identifiers controlled by their owners. Sonr DIDs follow the format:

did:sonr:<unique-identifier>

Example: did:sonr:alice123

DID Documents

DID Documents contain:

Verification methods (public keys, WebAuthn credentials)
Service endpoints (URLs for services)
Controller relationships (who can update the DID)

Verifiable Credentials

Digital credentials containing:

Claims about subjects
Cryptographic proofs
Issuer signatures
Revocation status

WebAuthn Integration

WebAuthn enables:

Biometric authentication (Face ID, fingerprints)
Hardware security keys
Passwordless login
Multiple credentials per DID

Data Structures

DID Document

The primary state object storing DID information:

message W3CDIDDocument {
  string id = 1;                                      // DID identifier
  string context = 2;                                 // JSON-LD context
  repeated string controller = 3;                     // Controller DIDs
  repeated W3CVerificationMethod verification_method = 4;
  repeated string authentication = 5;                // Auth method references
  repeated string assertion_method = 6;              // Assertion method refs
  repeated string key_agreement = 7;                 // Key agreement refs
  repeated string capability_invocation = 8;         // Capability invocation
  repeated string capability_delegation = 9;         // Capability delegation
  repeated W3CService service = 10;                  // Service endpoints
}

Verification Method

Defines how to verify control of a DID:

message W3CVerificationMethod {
  string id = 1;                                      // Method identifier
  string verification_method_kind = 2;                // Method type
  string controller = 3;                              // Controller DID
  oneof verification_material {
    W3CJSONWebKey json_web_key = 4;                 // JWK format
    string public_key_multibase = 5;                 // Multibase key
    W3CWebAuthnCredential webauthn_credential = 6;  // WebAuthn cred
  }
}

Verifiable Credential

Stores credential data:

message W3CVerifiableCredential {
  string id = 1;                                      // Credential ID
  repeated string type = 2;                           // Credential types
  string issuer = 3;                                  // Issuer DID
  google.protobuf.Timestamp issuance_date = 4;       // Issue date
  google.protobuf.Timestamp expiration_date = 5;     // Expiry date
  google.protobuf.Any credential_subject = 6;         // Claims
  google.protobuf.Any proof = 7;                     // Signature
  CredentialStatus credential_status = 8;             // Status
}

State Transitions

All state transitions require cryptographic proof from authorized controllers.

DID Operations

Message	Description	Authorization
`MsgCreateDID`	Creates new DID document	Creator signature
`MsgUpdateDID`	Updates existing DID	Controller signature
`MsgDeactivateDID`	Deactivates DID	Controller signature

Verification Method Operations

Message	Description	Authorization
`MsgAddVerificationMethod`	Adds verification method	Controller signature
`MsgRemoveVerificationMethod`	Removes verification method	Controller signature

Service Operations

Message	Description	Authorization
`MsgAddService`	Adds service endpoint	Controller signature
`MsgRemoveService`	Removes service endpoint	Controller signature

Credential Operations

Message	Description	Authorization
`MsgIssueVerifiableCredential`	Issues credential	Issuer signature
`MsgRevokeVerifiableCredential`	Revokes credential	Issuer signature

Query Interface

DID Queries

# Resolve DID to document
snrd query did resolve did:sonr:alice123

# List all DID documents
snrd query did list-documents

# Get DIDs by controller
snrd query did documents-by-controller did:sonr:controller

Verification Method Queries

# Get specific verification method
snrd query did verification-method did:sonr:alice123#key-1

# Get service endpoint
snrd query did service did:sonr:alice123#vault

Credential Queries

# Get specific credential
snrd query did credential cred-123

# List credentials by holder
snrd query did credentials-by-holder did:sonr:alice123

# List credentials by issuer
snrd query did credentials-by-issuer did:sonr:issuer

WebAuthn Integration

Credential Structure

message W3CWebAuthnCredential {
  bytes credential_id = 1;      // Unique identifier
  bytes public_key = 2;         // Public key
  int32 algorithm = 3;          // Algorithm (-7 for ES256)
  string attestation_type = 4;  // Attestation format
  string origin = 5;            // Creation origin
  int64 created_at = 6;         // Timestamp
}

Authentication Flow

Create credential: User generates WebAuthn credential on device
Store on-chain: Add credential as verification method
Authenticate: User approves with biometrics
Verify: Module validates WebAuthn assertion

Supported Features

Passkeys: Platform authenticators with cloud sync
Security keys: Hardware FIDO2 devices
Multiple credentials: Many devices per DID
Origin validation: Phishing protection
Challenge verification: Replay attack prevention

Security Model

Authorization Requirements

Proof validation: All operations require valid cryptographic signatures
Controller authority: Only controllers can update DID documents
Issuer authority: Only issuers can revoke credentials
WebAuthn security: Origin and challenge validation enforced

Best Practices

Rotate keys regularly: Update verification methods periodically
Multiple controllers: Add backup controllers for recovery
Limit service endpoints: Only expose necessary services
Monitor credentials: Track issued and held credentials

Standards Compliance

The module implements:

Standard	Version	Features
W3C DID Core	1.0	Full specification
W3C Verifiable Credentials	1.1	Data model and proofs
WebAuthn	Level 2	Passkeys and FIDO2
JSON-LD	1.1	Context and framing
JWK/JWS	RFC 7517/7515	Key representation

Implementation Examples

Create DID with WebAuthn

// Create DID document
doc := &W3CDIDDocument{
    Id:         "did:sonr:alice123",
    Context:    "https://www.w3.org/ns/did/v1",
    Controller: []string{"did:sonr:alice123"},
}

// Add WebAuthn verification method
method := &W3CVerificationMethod{
    Id:                     "did:sonr:alice123#webauthn-1",
    VerificationMethodKind: "WebAuthnAuthentication2023",
    Controller:             "did:sonr:alice123",
    VerificationMaterial: &W3CVerificationMethod_WebauthnCredential{
        WebauthnCredential: credential,
    },
}

Issue Verifiable Credential

// Create credential
cred := &W3CVerifiableCredential{
    Id:           "urn:uuid:credential-123",
    Type:         []string{"VerifiableCredential", "DriverLicense"},
    Issuer:       "did:sonr:dmv",
    IssuanceDate: timestamppb.Now(),
    CredentialSubject: &anypb.Any{
        // Claims about subject
    },
}

Next Steps

Ready to Implement?

Developers: Review the Identity Guide for implementation patterns.

Integrators: Explore the SDK Documentation for client libraries.

Validators: Understand DID Verification requirements.

DID Module

DID Module (x/did)

Summary

Module Features

Core Concepts

Decentralized Identifiers (DIDs)

DID Documents

Verifiable Credentials

WebAuthn Integration

Data Structures

DID Document

Verification Method

Verifiable Credential

State Transitions

DID Operations

Verification Method Operations

Service Operations

Credential Operations

Query Interface

DID Queries

Verification Method Queries

Credential Queries

WebAuthn Integration

Credential Structure

Authentication Flow

Supported Features

Security Model

Authorization Requirements

Best Practices

Standards Compliance

Implementation Examples

Create DID with WebAuthn

Issue Verifiable Credential

Next Steps

DWN Module

UCAN Module

Service Module

On this page