DIDRegistry

Overview

The DIDRegistry contract implements a decentralized identity (DID) registry following the W3C DID specification. It enables users to register, update, and manage DID Documents on-chain with support for verification methods, services, and delegated control.

Contract Details

Property	Value
Solidity Version	^0.8.28
License	MIT
Inheritance	Context, EIP712 (OpenZeppelin)
DID Method	did:pkh (Public Key Hash)

---

Purpose

The DIDRegistry contract provides a complete on-chain DID management system:

• Self-Sovereign Identity: Users control their own DID documents

• Delegated Control: Authorized controllers can manage DIDs on behalf of subjects

• Verification Methods: Support for multiple cryptographic keys with relationship types

• Services: Link external services to DID documents

• Meta-Transactions: EIP-712 signatures enable gasless updates

---

Data Structures

VerificationMethod

Represents a cryptographic key or verification method.

struct VerificationMethod {
    string id;              // Unique identifier (e.g., "did:pkh:0x...#key-1")
    string methodType;      // Type (e.g., "EcdsaSecp256k1VerificationKey2019")
    string metadata;        // JSON string with additional properties
    address controller;     // Address that controls this method
    uint8 relationships;    // Packed bitflags for relationship types
}

Field	Type	Description
id	string	Full DID URL identifier for the method
methodType	string	Cryptographic suite type
metadata	string	JSON-encoded additional properties
controller	address	Ethereum address of the controller
relationships	uint8	Bitflags indicating verification relationships

Service

Represents an external service endpoint.

struct Service {
    string id;              // Service identifier
    string serviceType;     // Type of service (e.g., "LinkedDomains")
    string serviceEndpoint; // URL or endpoint reference
}

Field	Type	Description
id	string	Unique service identifier
serviceType	string	Type classification
serviceEndpoint	string	URL, URI, or JSON endpoint data

DIDDocument

The complete DID Document structure.

struct DIDDocument {
    string[] context;                       // JSON-LD @context values
    address[] controllers;                  // Addresses authorized to update
    string[] alsoKnownAs;                   // Alternative identifiers
    VerificationMethod[] verificationMethods; // Cryptographic methods
    Service[] services;                     // Service endpoints
    uint256 nonce;                          // Replay protection counter
}

Field	Type	Description
context	string[]	JSON-LD context URIs
controllers	address[]	Delegated controller addresses
alsoKnownAs	string[]	Alias identifiers
verificationMethods	VerificationMethod[]	Array of verification methods
services	Service[]	Array of service endpoints
nonce	uint256	Auto-incrementing counter for updates

---

Verification Relationships

Verification relationships are stored as packed bitflags in a uint8:

Constant	Value	Hex	Description
AUTHENTICATION	1	0x01	Key can authenticate as the DID subject
ASSERTION	2	0x02	Key can make assertions/claims
KEY_AGREEMENT	4	0x04	Key can be used for key agreement (encryption)
CAPABILITY_INVOCATION	8	0x08	Key can invoke capabilities
CAPABILITY_DELEGATION	16	0x10	Key can delegate capabilities

Examples

Relationships	Value	Binary
Authentication only	1	00001
Authentication + Assertion	3	00011
Key Agreement only	4	00100
All relationships	31	11111

---

State Variables

Variable	Type	Visibility	Description
DID_TYPE	string	public constant	DID method type ("did:pkh")
AUTHENTICATION	uint8	public constant	Authentication bitflag (1)
ASSERTION	uint8	public constant	Assertion bitflag (2)
KEY_AGREEMENT	uint8	public constant	Key Agreement bitflag (4)
CAPABILITY_INVOCATION	uint8	public constant	Capability Invocation bitflag (8)
CAPABILITY_DELEGATION	uint8	public constant	Capability Delegation bitflag (16)
didDocuments	mapping(address => DIDDocument)	internal	DID document storage

---

Functions

Constructor

constructor(string memory name, string memory version)

Initializes the contract with EIP-712 domain parameters.

Parameters:

Name	Type	Description
name	string	Domain name (e.g., "DIDRegistry")
version	string	Domain version (e.g., "1")

---

Registration Functions

registerDID

function registerDID(DIDDocument calldata _didDocument) external

Registers a new DID document for msg.sender.

Parameters:

Name	Type	Description
_didDocument	DIDDocument	The DID document to register

Requirements:

• Subject must not already have a registered DID (nonce == 0)

• Context array must not be empty

Emits: DIDRegistered

---

registerDIDOf

function registerDIDOf(
    DIDDocument calldata _didDocument,
    address _didSubject,
    bytes calldata _subjectSignature
) external

Registers a DID on behalf of another address using their signature.

Parameters:

Name	Type	Description
_didDocument	DIDDocument	The DID document to register
_didSubject	address	The address to register the DID for
_subjectSignature	bytes	EIP-712 signature from the subject

Requirements:

• Signature must be from the _didSubject

• Subject must not already have a registered DID

Emits: DIDRegistered

---

Update Functions

updateDID

function updateDID(
    DIDDocument calldata _didDocument,
    address _didSubject
) external

Updates an existing DID document.

Parameters:

Name	Type	Description
_didDocument	DIDDocument	The updated DID document
_didSubject	address	The address whose DID to update

Requirements:

• Caller must be the subject OR a listed controller

• Provided nonce must match current stored nonce

• Context array must not be empty

Emits: DIDUpdated

---

updateDIDOf

function updateDIDOf(
    DIDDocument calldata _didDocument,
    address _didSubject,
    bytes calldata _signature
) external

Updates a DID document using a signature from an authorized party.

Parameters:

Name	Type	Description
_didDocument	DIDDocument	The updated DID document
_didSubject	address	The address whose DID to update
_signature	bytes	EIP-712 signature from subject or controller

Requirements:

• Signer must be the subject OR a listed controller

• Provided nonce must match current stored nonce

Emits: DIDUpdated

---

Query Functions

getDIDDocument

function getDIDDocument(address subject) public view returns (DIDDocument memory)

Retrieves the DID document for a given address.

Parameters:

Name	Type	Description
subject	address	The DID subject address

Returns: DIDDocument struct (empty if not registered)

---

isController

function isController(address subject, address account) public view returns (bool)

Checks if an address is a controller for a DID.

Parameters:

Name	Type	Description
subject	address	The DID subject address
account	address	The address to check

Returns: true if account is listed as a controller

---

Relationship Helper Functions

hasRelationship

function hasRelationship(uint8 relationships, uint8 flag) public pure returns (bool)

Checks if a relationship flag is set.

Parameters:

Name	Type	Description
relationships	uint8	The packed relationship bitflags
flag	uint8	The flag to check (e.g., AUTHENTICATION)

Returns: true if the flag is set

Example:

// Check if key has authentication relationship
bool canAuth = registry.hasRelationship(vm.relationships, registry.AUTHENTICATION());

---

addRelationship

function addRelationship(uint8 relationships, uint8 flag) public pure returns (uint8)

Adds a relationship flag.

Parameters:

Name	Type	Description
relationships	uint8	Current relationship bitflags
flag	uint8	The flag to add

Returns: Updated relationship bitflags

---

removeRelationship

function removeRelationship(uint8 relationships, uint8 flag) public pure returns (uint8)

Removes a relationship flag.

Parameters:

Name	Type	Description
relationships	uint8	Current relationship bitflags
flag	uint8	The flag to remove

Returns: Updated relationship bitflags

---

Hashing Functions

hashDIDDocument

function hashDIDDocument(DIDDocument calldata doc) public pure returns (bytes32)

Computes the EIP-712 struct hash for a DID document.

getTypedDataHash

function getTypedDataHash(DIDDocument calldata doc) public view returns (bytes32)

Returns the complete EIP-712 typed data hash for signing.

---

Events

DIDRegistered

event DIDRegistered(address indexed subject);

Emitted when a new DID document is registered.

DIDUpdated

event DIDUpdated(
    address indexed subject,
    address indexed updatedBy,
    uint256 nonce
);

Emitted when a DID document is updated.

Parameter	Description
subject	The DID subject address
updatedBy	The address that performed the update
nonce	The new nonce value after update

---

Errors

Error	Description
InvalidContext()	Context array is empty
InvalidControllers()	Controllers array validation failed
InvalidSignature()	Signature verification failed
InvalidNonce()	Provided nonce doesn't match stored nonce
Unauthorized()	Caller is not authorized to update
AlreadyRegistered()	DID already registered for this address

---

EIP-712 Type Definitions

VerificationMethod

const VerificationMethod = [
  { name: "id", type: "string" },
  { name: "methodType", type: "string" },
  { name: "controller", type: "address" },
  { name: "metadata", type: "string" },
  { name: "relationships", type: "uint8" },
];

Service

const Service = [
  { name: "id", type: "string" },
  { name: "serviceType", type: "string" },
  { name: "serviceEndpoint", type: "string" },
];

DIDDocument

const DIDDocument = [
  { name: "context", type: "string[]" },
  { name: "controllers", type: "address[]" },
  { name: "alsoKnownAs", type: "string[]" },
  { name: "verificationMethods", type: "VerificationMethod[]" },
  { name: "services", type: "Service[]" },
  { name: "nonce", type: "uint256" },
];

---

Usage Examples

Registering a DID Document (TypeScript/Viem)

// Helper function to calculate relationships
function calculateRelationships(flags: {
  authentication?: boolean;
  assertion?: boolean;
  keyAgreement?: boolean;
  capabilityInvocation?: boolean;
  capabilityDelegation?: boolean;
}): number {
  let relationships = 0;
  if (flags.authentication) relationships |= 1;
  if (flags.assertion) relationships |= 2;
  if (flags.keyAgreement) relationships |= 4;
  if (flags.capabilityInvocation) relationships |= 8;
  if (flags.capabilityDelegation) relationships |= 16;
  return relationships;
}

// Prepare DID document
const userAddress = userWallet.account.address;
const did = `did:pkh:${userAddress}`;

const didDocument = {
  context: ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/secp256k1-2019/v1"],
  controllers: [], // No delegated controllers
  alsoKnownAs: [],
  verificationMethods: [
    {
      id: `${did}#key-1`,
      methodType: "EcdsaSecp256k1VerificationKey2019",
      controller: userAddress,
      metadata: JSON.stringify({ blockchainAccountId: `eip155:1:${userAddress}` }),
      relationships: calculateRelationships({
        authentication: true,
        assertion: true,
      }),
    },
  ],
  services: [
    {
      id: `${did}#profile`,
      serviceType: "LinkedDomains",
      serviceEndpoint: "https://example.com",
    },
  ],
  nonce: 0n,
};

// Register DID
await registry.write.registerDID([didDocument], { account: userWallet.account });

Registering on Behalf of Another User

const typedData = {
  domain: {
    name: "DIDRegistry",
    version: "1",
    chainId: 1n,
    verifyingContract: registryAddress,
  },
  types: {
    VerificationMethod: [
      { name: "id", type: "string" },
      { name: "methodType", type: "string" },
      { name: "controller", type: "address" },
      { name: "metadata", type: "string" },
      { name: "relationships", type: "uint8" },
    ],
    Service: [
      { name: "id", type: "string" },
      { name: "serviceType", type: "string" },
      { name: "serviceEndpoint", type: "string" },
    ],
    DIDDocument: [
      { name: "context", type: "string[]" },
      { name: "controllers", type: "address[]" },
      { name: "alsoKnownAs", type: "string[]" },
      { name: "verificationMethods", type: "VerificationMethod[]" },
      { name: "services", type: "Service[]" },
      { name: "nonce", type: "uint256" },
    ],
  },
  primaryType: "DIDDocument",
  message: didDocument,
};

// Subject signs the document
const signature = await subjectWallet.signTypedData(typedData);

// Relayer submits the transaction
await registry.write.registerDIDOf([didDocument, subjectAddress, signature], {
  account: relayerWallet.account,
});

Updating with Delegated Controller

// Original registration includes controller
const docWithController = {
  ...didDocument,
  controllers: [controllerAddress],
};
await registry.write.registerDID([docWithController], { account: userWallet.account });

// Controller can now update (nonce is 1 after registration)
const updatedDoc = {
  ...didDocument,
  context: ["https://www.w3.org/ns/did/v1", "https://example.com/custom-context"],
  controllers: [controllerAddress],
  nonce: 1n, // Must match current nonce
};

await registry.write.updateDID([updatedDoc, userAddress], {
  account: controllerWallet.account,
});

Reading and Decoding a DID Document

const storedDoc = await registry.read.getDIDDocument([userAddress]);

// Check if registered
const isRegistered = storedDoc.nonce > 0n;

// Parse verification method metadata
const vm = storedDoc.verificationMethods[0];
const metadata = JSON.parse(vm.metadata);

// Check relationships
const AUTHENTICATION = 1;
const ASSERTION = 2;
const hasAuth = (vm.relationships & AUTHENTICATION) !== 0;
const hasAssertion = (vm.relationships & ASSERTION) !== 0;

---

W3C DID Document Mapping

The contract's structures map to W3C DID Document format:

W3C Property	Contract Field	Notes
@context	context	Array of context URIs
id	N/A (mapping key)	Derived from did:pkh:{address}
controller	controllers	Array of controller addresses
alsoKnownAs	alsoKnownAs	Alternative identifiers
verificationMethod	verificationMethods	Array of methods
authentication	relationships bitflag	Derived from bitflag
assertionMethod	relationships bitflag	Derived from bitflag
keyAgreement	relationships bitflag	Derived from bitflag
capabilityInvocation	relationships bitflag	Derived from bitflag
capabilityDelegation	relationships bitflag	Derived from bitflag
service	services	Array of services

Example: JSON-LD to Solidity Encoding

W3C JSON-LD Format:

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:pkh:0x1234...",
  "verificationMethod": [
    {
      "id": "did:pkh:0x1234...#key-1",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "controller": "did:pkh:0x1234...",
      "blockchainAccountId": "eip155:1:0x1234..."
    }
  ],
  "authentication": ["did:pkh:0x1234...#key-1"],
  "assertionMethod": ["did:pkh:0x1234...#key-1"]
}

Solidity Struct Encoding:

{
  context: ["https://www.w3.org/ns/did/v1"],
  controllers: [],
  alsoKnownAs: [],
  verificationMethods: [{
    id: "did:pkh:0x1234...#key-1",
    methodType: "EcdsaSecp256k1VerificationKey2019",
    controller: "0x1234...",
    metadata: '{"blockchainAccountId":"eip155:1:0x1234..."}',
    relationships: 3  // AUTHENTICATION (1) | ASSERTION (2)
  }],
  services: [],
  nonce: 0n
}

---

Security Considerations

1. Nonce Protection: Each update increments the nonce, preventing replay attacks

2. Controller Authorization: Only subject or listed controllers can update

3. Signature Verification: Meta-transactions verified via EIP-712 ECDSA recovery

4. Context Validation: Empty context arrays are rejected

5. Immutable Registration: DID cannot be re-registered once created

---

Related Contracts

• Agreement: Uses DIDs for party identification

• Consent: Links consent records to DID-identified suppliers

---

Deployment

The contract is deployed using Hardhat Ignition:

// ignition/modules/DIDRegistry.ts
import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";

const DOMAIN_NAME = "DIDRegistry";
const DOMAIN_VERSION = "1";

export default buildModule("DIDRegistryModule", (m) => {
  const didRegistry = m.contract("DIDRegistry", [DOMAIN_NAME, DOMAIN_VERSION]);

  return { didRegistry };
});