Decentralized Identifiers
Self-sovereign, verifiable identities for Wallet accounts and smart contracts within the SafePulse ecosystem.
Overview
A Decentralized Identifier (DID) is a globally unique, persistent identifier that allows its controller to prove cryptographic ownership over it. Unlike traditional identifiers (email addresses, usernames, account numbers), DIDs are not issued or managed by any central authority. The entity that controls a DID is called the controller.
The DID Document
Every DID resolves to a DID Document—a structured JSON file that describes the subject and provides the technical information needed for cryptographic interactions. A DID Document typically contains:
| Component | Description |
|---|---|
| id | The DID itself. |
| controller | The DID of the entity that controls this DID (can be the same DID). |
| verificationMethod | Public keys and their metadata, used for verifying signatures. |
| authentication | Keys authorized to prove the DID controller's identity. |
| assertionMethod | Keys authorized to make verifiable claims or sign credentials. |
| service | Service endpoints for interacting with the DID subject (e.g., linked domains, messaging endpoints). |
DID Methods in SafePulse
A DID method defines the specific rules for how a DID is created, resolved, updated, and deactivated. SafePulse supports two primary DID methods, each suited for different use cases.
1. did:key — Off-Chain, Generative Identity
did:key is a purely off-chain, deterministic DID method. The identifier is generated directly from a public key, requiring no blockchain transaction, no registration, and no gas fees. The DID Document can always be re-derived from the public key alone.
Syntax:
did:key:<multibase-encoded-public-key>
Example:
did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
Key Characteristics:
- Cost: Free to create. No on-chain transaction is required.
- Key Rotation: Not supported. A new key means a new DID.
- Delegation: Not supported. The controller is implicitly the key holder.
- Use Case: Ideal for ephemeral interactions, quick prototyping, or scenarios where on-chain anchoring is unnecessary.
2. did:ethr — On-Chain, Ethereum-Anchored Identity (ERC-1056)
did:ethr is an Ethereum-based DID method built on the ERC-1056 Lightweight Identity standard. It uses an on-chain registry to manage DIDs, their keys, delegates, and service endpoints, providing a verifiable and auditable identity layer.
Syntax:
did:ethr:<chain-id>:<ethereum-address>
Example:
did:ethr:1:0xAbC123456789abcdef123456789abcdef1234567
Key Characteristics:
- Cost: Requires gas for updates (adding delegates, rotating keys, setting attributes).
- Key Rotation: Fully supported via delegate management and registry updates.
- Delegation: Supported. The controller can authorize multiple delegates to act on its behalf.
- Service Endpoints: Stored as on-chain attributes, enabling verifiable service discovery.
- Use Case: Ideal for persistent, enterprise-grade identities requiring auditability and advanced key management.
Comparison: did:key vs did:ethr
| Feature | did:key | did:ethr (ERC-1056) |
|---|---|---|
| Storage | Fully off-chain (derived from key) | On-chain registry (Ethereum) |
| Creation Cost | Free | Gas required for initial setup |
| Update Cost | N/A (new key = new DID) | Gas required for each update |
| Key Rotation | Not supported | Supported via delegates |
| Delegation | Not supported | Supported |
| Service Endpoints | Derived or embedded in DID | Stored as on-chain attributes |
| Auditability | None on-chain | Fully auditable via Ethereum history |
| Best For | Ephemeral, lightweight use cases | Persistent, high-trust, enterprise use cases |
Contract DID & Registry DID
Beyond user and organizational identities, SafePulse extends the DID standard to smart contracts and registries. These Contract DIDs serve as cryptographic handles for on-chain entities, enabling secure reference and interaction.
Contract DID Structure
A Contract DID identifies a specific deployed smart contract and can optionally include a cipher key for encrypting sensitive contract state.
Format:
did:ethr:<chain-id>:<contract-address-hex>[;key=<cipher-key-hex>]
Example:
did:ethr:1:0x4b3c7a9e5f2d3a6b8c9d0e1f2a3b4c5d6e7f8a9b;key=0a1b2c3d4e5f67890123456789abcdef
Components:
did:ethr: Ethereum-compatible DID method.<chain-id>: The EVM chain ID where the contract is deployed (e.g.,1for Ethereum mainnet).<contract-address-hex>: The contract's on-chain address in hexadecimal format.key=<cipher-key-hex>(Optional): A private cipher key for encrypting sensitive contract data. This key must never be shared with unauthorized parties, as it grants the ability to decrypt confidential contract information.
Registry DID Structure
Registries are on-chain data structures that map, verify, or index other contracts, users, or assets. A simpler DID format is used to reference them.
Format:
did:ethr:<chain-id>:<32byte-hash-hex>
Example:
did:ethr:5:0x9f8a7b6c5d4e3f2a1b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2
Registry DIDs enable tamper-proof lookups, automated verification, and secure referencing of on-chain data without relying on centralized indexers.
Security & Privacy Considerations
- Private Key Protection: Control over a DID is ultimately determined by control of its associated private keys. Safeguarding these keys is the user's sole responsibility.
- Cipher Key Confidentiality: For Contract DIDs that include a
key=parameter, the cipher key should be treated as a secret. Sharing it with unauthorized parties compromises any encrypted contract state. - On-Chain vs. Off-Chain:
did:keyoffers greater privacy (nothing is on-chain), whiledid:ethroffers greater auditability and management flexibility. Choose the method that aligns with your use case. - Key Rotation: For long-lived identities,
did:ethris recommended due to its support for key rotation, reducing the risk associated with key compromise.
Summary
Decentralized Identifiers are the identity backbone of the SafePulse ecosystem. They enable users, organizations, and smart contracts to interact with cryptographic certainty, without relying on centralized authorities. SafePulse supports two DID methods—did:key for lightweight, off-chain use and did:ethr for persistent, on-chain identity management—as well as Contract DIDs for secure, verifiable smart contract interaction.