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:

dependencies {
    implementation("org.trustweave:did-did-core:0.6.0")
    implementation("org.trustweave:common:0.6.0")
}

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

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

import org.trustweave.trust.TrustWeave
import org.trustweave.trust.types.getOrThrowDid
import org.trustweave.testkit.services.*
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val trustWeave = TrustWeave.build {
        keys { provider(IN_MEMORY); algorithm(ED25519) }
        did {
            method(KEY) {
                algorithm(ED25519)
            }
        }
    }

    val issuerDid = trustWeave.createDid {
        method(KEY)
        algorithm(ED25519)
    }.getOrThrowDid()

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

Outcome: Registers DID methods during TrustWeave creation, creates a new DID using typed options, and returns the DID 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 – createDid / resolveDid return sealed results; updateDid / rotateKey return documents or throw domain exceptions. 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.rotateKey { }.

Standards: DID Core 1.1

W3C Decentralized Identifiers v1.1 layers on Controlled Identifiers and moves much of resolution into a separate spec. TrustWeave today targets DID Core 1.0 semantics in docs and defaults; for a comparison of the specs and documented implementation gaps (embedded verification methods in relationship arrays, alsoKnownAs URLs, DID Resolution v0.3, test suite, etc.), see DID Core 1.0 vs 1.1 and TrustWeave gaps.

Create and Manage DIDs - Step-by-step guide for creating, resolving, updating, and deactivating DIDs

Next Steps

Ready to use DIDs?

Create and Manage DIDs](../how-to/create-dids.md) - Step-by-step guide
Quick Start – Step 3](../getting-started/quick-start.md#step-3-create-a-did-with-typed-options) - Create your first DID
DID Operations Tutorial](../tutorials/did-operations-tutorial.md) - Hands-on DID examples
Wallet API Reference – DidManagement](../api-reference/wallet-api.md#didmanagement) - DID management in wallets

Want to learn more?

Verifiable Credentials](verifiable-credentials.md) - Use DIDs to issue credentials
Key Management](key-management.md) - Understand key management for DIDs
DID Integration Guides](../integrations/README.md#did-method-integrations) - Implementation guides for all DID methods

Explore related concepts:

Architecture Overview](../introduction/architecture-overview.md) - Understand TrustWeave architecture
Mental Model](../introduction/mental-model.md) - Core concepts and how they fit together