DidDoc

Abstract

x/diddoc is a Cosmos SDK module that enables on-chain management of Decentralized Identifiers (DIDs) and their associated DID Documents, a critical piece of EMPE DID method. This module allows for creating, updating, and deactivating DID Documents anchored on the blockchain. It supports a hybrid model, where a DID can exist off-chain and be anchored on-chain at any time. Once anchored on-chain, the on-chain version takes precedence. The module ensures secure key management by requiring a mandatory backup key and provides a one-time irreversible deactivation function, ensuring ultimate control and security for DID owners.

Contents

• Concepts

  • DID Documents

  • On-chain and Off-chain DID Documents

  • Backup Key

  • Deactivation

  • Updates

• State

• Messages

  • MsgCreateDidDocument

    • Parameters

    • Usage & Example

  • MsgUpdateDidDocument

    • Parameters

    • Usage & Example

  • MsgDeactivateDidDocument

    • Parameters

    • Usage & Example

  • MsgUpdateParams

    • Parameters

    • Usage & Example

• Events

• Client

  • CLI

  • gRPC

Concepts

DID Documents

A DID Document provides information on:

• Verification Methods: Keys or other cryptographic materials to authenticate as the DID owner.

• Verification Relationships (e.g., authentication, assertionMethod, keyAgreement, capabilityInvocation, capabilityDelegation): Define which verification methods serve specific roles.

• Services: URLs or endpoints to communicate with entities controlling the DID.

A DID Document must have at least two keys on-chain:

1. A primary key method (under authentication) derived from the DID.

2. A backup key (under capabilityInvocation) that cannot be changed once set.

On-chain and Off-chain DID Documents

• Off-chain: The DID Document exists but is not anchored on-chain. It can still be referenced by the DID, but without the security guarantees of on-chain anchoring.

• On-chain: The DID Document is stored and versioned on the blockchain. This version takes precedence and requires valid signatures to update or deactivate.

Backup Key

The backup key is included in capabilityInvocation and cannot be rotated. It provides a fallback to ensure you can always update or deactivate the DID Document if the primary keys are compromised.

Deactivation

Deactivation is a final, irreversible operation that disables the DID entirely. This ensures that even if attackers gain control of keys, the legitimate owner can permanently deactivate the DID to prevent misuse.

Updates

Updates allow fine-grained modifications:

• Adding or removing verification methods.

• Adjusting relationships (e.g., adding a new authentication method).

• Adding or removing services.

• Must increment the document's version number.

• Cannot change the backup key.

State

The state includes:

• Stored DID Documents split into sections (basic fields, verification methods, relationships, services).

• DID status (active or deactivated).

• Version number for replay protection and ensuring linear history.

Messages

MsgCreateDidDocument

Description: Anchors a new DID Document on-chain. Requires two signatures:

• Signature from the primary authentication method.

• Signature from the backup method.

Key Checks:

• Ensure both primary and backup keys are valid.

• DID is derived from the primary authentication method's public key.

Parameters

Name	Type	Description
Sender	string	The account executing the message (transaction signer).
DidDocument	DidDocument	The DID Document to anchor on-chain.
Signatures	[]Signature	Exactly 2 signatures: primary and backup key signatures.

Each Signature includes:

• MethodId: DID method ID referencing the verification method in the DID Document.

• SigBytes: Base64-encoded signature of the DID Document.

Usage & Example

$ emped tx diddoc create-did-document <document.json> --from

Example JSON Input (document.json):

{
  "id": "did:empe:abcd1234...",
"context": ["https://www.w3.org/ns/did/v1"],
"controller": ["did:empe:abcd1234..."],
"verificationMethod": [
{
"id": "did:empe:abcd1234...#0",
"type": "JsonWebKey",
"controller": "did:empe:abcd1234...",
"publicKeyJwk": {
"kty": "EC",
"crv": "secp256k1",
"x": "Base64UrlEncodedKeyX"
}
},
{
"id": "did:empe:abcd1234...#backup",
"type": "JsonWebKey",
"controller": "did:empe:abcd1234...",
"publicKeyJwk": {
"kty": "EC",
"crv": "secp256k1",
"x": "BackupKeyX"
}
}
],
"authentication": [
{"referenceId": "did:empe:abcd1234...#0" }
],
"capabilityInvocation": [
{
"referenceId": "did:empe:abcd1234...#backup" }
],
"service": [
{
"id": "did:empe:abcd1234...#service-1",
"type": "DIDCommMessaging",
"serviceEndpoint": ["https://example.com/endpoint1"]
}
]
}

Run the command: $ emped tx diddoc create-did-document empe1xyz... document.json --from empe1xyz...

If successful, the DID Document is anchored on-chain with version 1.

MsgUpdateDidDocument

Description: Updates an existing on-chain DID Document. Must be signed by a method in capabilityInvocation (e.g., the backup key). Updates can add or remove verification methods, services, and so forth, as specified in an UpdateDidDocumentRequest.

Key Checks:

• Incremented version number matches current_version + 1.

• Changes are valid (no backup key modification).

• Proper signature verification with a capabilityInvocation method.

Parameters

Name	Type	Description
Sender	string	The account executing the message.
DidDocumentUpdates	UpdateDidDocumentRequest	The partial update instructions.
Signature	Signature	Signature from an allowed capabilityInvocation method.

UpdateDidDocumentRequest includes fields like:

• Id: Target DID

• NewVersion: The intended new version number.

• VerificationMethodUpdates: Add or remove VM operations.

• ServiceUpdates: Add or remove service operations.

• ContextUpdates, ControllerUpdates, AlsoKnownAsUpdates: Field-level updates.

Usage & Example

$ emped tx diddoc update-did-document <updates.json> --from

Example updates (updates.json):

{
  "id": "did:empe:abcd1234...",
"newVersion": 2,
"verificationMethodUpdates": [
{
"operation": "ADD",
"method": {
"id": "did:empe:abcd1234...#newKey",
"type": "JsonWebKey",
"controller": "did:empe:abcd1234...",
"publicKeyBase58": "Base58EncodedKey"
}
}
],
"serviceUpdates": [
{
"operation": "REMOVE",
"serviceId": "did:empe:abcd1234...#service-1"
}
]
}

Run the command: $ emped tx diddoc update-did-document empe1xyz... updates.json "did:empe:abcd1234...#backup" --from empe1xyz...

If successful, the DID Document is updated to version 2.

MsgDeactivateDidDocument

Description: Deactivates a DID Document. Irreversible. If the DID is on-chain, must be signed by the backup key. If off-chain, requires an Ethereum-compatible signature derived from the DID's public key.

Key Checks:

• Correct version number increment.

• Correct signature method for on-chain DIDs (backup key) or correct eth-style signature if off-chain.

Parameters

Name	Type	Description
Sender	string	The account executing the message.
Did	string	The DID to deactivate.
Version	uint32	Should be current_version + 1.
Signature	string	Base64 signature (using backup key if on-chain).

Usage & Example

$ emped tx diddoc deactivate-did-document --from

Example: $ emped tx diddoc deactivate-did-document empe1xyz... "did:empe:abcd1234..." 3 --from empe1xyz...

If successful, the DID is permanently deactivated.

MsgUpdateParams

Description: Allows governance to update module parameters, such as DID prefix patterns.

Key Checks:

• Must be signed by the governance authority.

• Parameter values must pass validation rules.

Parameters

Name	Type	Description
Authority	string	Address of the governance authority.
Params	Params	New parameters to set.

Usage & Example

$ emped tx diddoc update-params <params.json> --from

Example params.json:

{
  "didPrefix": "did:empe:testnet:"
}

Run the command: $ emped tx diddoc update-params empe1gov... params.json --from empe1gov...

If successful, new params are applied.

Events

The module emits events on creation, update, and deactivation:

• did_document_created: Emitted when a DID Document is first anchored.

• did_document_updated: Emitted after a successful update.

• did_document_deactivated: Emitted when DID is deactivated.

• params_updated: Emitted when module parameters are changed.

These can be monitored by external indexing services or dApps.

Client

CLI

Querying: $ emped query diddoc did-document $ emped query diddoc did-status

Tx: $ emped tx diddoc create-did-document ... $ emped tx diddoc update-did-document ... $ emped tx diddoc deactivate-did-document ... $ emped tx diddoc update-params ...

gRPC

The module provides gRPC query endpoints:

• Query/DidDocument: Fetch a DID Document by DID.

• Query/DidStatus: Fetch DID status.

• Query/DidDocumentVersion: Get the version of a DID Document.

• Query/DidDocumentAll: Paginate through all DID Documents.

• Query/Params: View current module parameters.

These endpoints allow integration into wallets, dashboards, and third-party applications managing DIDs.