Decentralized Identifiers (DIDs)

TrustWeave is created and supported by Geoknoesis LLC. The project reflects Geoknoesis’ reference architecture for decentralized trust.

What is a DID?

A Decentralized Identifier (DID) is a self-sovereign identifier controlled by its subject. It follows the did:method:identifier pattern—for example:

1
2
3
4

dependencies {
    implementation("com.trustweave:trustweave-did:1.0.0-SNAPSHOT")
    implementation("com.trustweave:trustweave-common:1.0.0-SNAPSHOT")
}

Result: Pulls the DID registry, builders, and data models into your project so the examples below compile.

1
2
3

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
did:web:example.com:user:alice
did:ion:EiClkZMDnmYGhX8tR8i3z2b5M5fN5hJ5vK5xL5yM5zN5oP5q

Resolving a DID yields a DID Document, a JSON-LD structure listing public keys, services, and capabilities that prove control of the identifier. TrustWeave serialises these documents using Kotlinx Serialization so they remain strongly typed.

Why DIDs matter in TrustWeave

  • Identity anchor – issuers, holders, verifiers, and services use DIDs as their canonical identifier during credential issuance and verification.
  • Portability – you can switch DID methods (key, web, Ion, etc.) without rewriting business logic; only the registry wiring changes.
  • Foundation for proofs – verifier flows fetch DID documents to validate signatures created during issuance (see the Architecture Overview).

How TrustWeave models DIDs

Component Purpose
DidMethod Contracts createDid, resolveDid, updateDid, deactivateDid for a particular DID method implementation.
DidMethodRegistry Context-scoped registry that decides which methods are available to the current TrustWeaveConfig.
DidCreationOptions Typed builder for method-specific parameters (algorithm, domain, custom properties).

Wallets expose DID helpers through the DidManagement capability (see the Wallet API Reference).

Example: Registering and using DID methods 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

import com.trustweave.TrustWeave
import com.trustweave.did.*
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    // Create TrustWeave instance with DID methods registered
    val trustWeave = TrustWeave.build {
        factories(didMethodFactory = TestkitDidMethodFactory())
        keys { provider("inMemory"); algorithm("Ed25519") }
        did {
            method("key") {
                algorithm("Ed25519")
            }
        }
    }

    // Create a DID using DSL
    val issuerDid = trustWeave.createDid {
        method("key")
        algorithm("Ed25519")
    }

    println("Issuer DID: ${issuerDid.value}")
}

**Outcome:** Registers DID methods during TrustWeave creation, creates a new DID using typed options, and returns the DID document for use in issuance flows.

DID documents at a glance

A DID document generated by TrustWeave includes:

  • verificationMethod entries referencing public keys (JWK or multibase).
  • Usage relationships (authentication, assertionMethod, keyAgreement).
  • Optional service endpoints and metadata fields (created, updated, versionId) for provenance tracking.

Practical usage tips

  • Context-local registries – create registries inside your TrustWeaveConfig to avoid global state and to simplify tests.
  • SPI discovery – ship new methods by implementing DidMethodProvider; TrustWeave will auto-register them when the module is on the classpath.
  • Wallet DSL – expose DID creation to end-users through wallet { did { ... } } (powered by DidManagement). See Wallets.
  • Verification – ensure hosted DID documents or Universal Resolver endpoints are reachable from verifier environments to guarantee proof validation succeeds.
  • Error handling – DID operations throw TrustWeaveError exceptions on failure. See Error Handling.
  • Input validation – TrustWeave automatically validates DID format and method registration before operations.
  • DSL-based API – Access DID operations through trustWeave.createDid { }, trustWeave.resolveDid(), trustWeave.updateDid { }, and trustWeave.updateDid { deactivated(true) }.

Next Steps

Ready to use DIDs?

Want to learn more?

Explore related concepts: