Architecture Overview

TrustWeave follows a modular, pluggable architecture that enables flexibility and extensibility. This page ties the high-level mental model—DIDs, credentials, proofs, anchoring—into the modules you will touch as you build a trust layer.

TrustWeave Mental Model

TrustWeave operates on three abstraction layers that provide different levels of control and simplicity:

1. Facade Layer (`TrustWeave.create()`) - Simplest API

The facade provides a unified, high-level API with sensible defaults. Use this when you want the simplest integration:

val TrustWeave = TrustWeave.create()
val did = TrustWeave.createDid().getOrThrow()
val credential = TrustWeave.issueCredential(...).getOrThrow()

When to use:

Quick prototypes and demos
Simple applications with standard requirements
When you want TrustWeave to handle configuration automatically

2. Service Layer (Direct Interfaces) - Fine-Grained Control

Access individual services directly for maximum control:

val kms = InMemoryKeyManagementService()
val didMethod = DidKeyMockMethod(kms)
val didRegistry = DidMethodRegistry().apply { register(didMethod) }
val document = didMethod.createDid(options)

When to use:

Custom configurations
Advanced use cases
When you need to compose services manually

3. DSL Layer (`trustLayer { }`) - Declarative Configuration

Use the DSL for declarative, readable configuration:

val trustLayer = trustLayer {
    keys { provider("inMemory") }
    did { method("key") }
    blockchains {
        "algorand:testnet" to algorandClient
    }
}

When to use:

Complex trust layer configurations
When you prefer declarative style
Building reusable trust configurations

Component Interaction Flow

Understanding how components interact helps you debug and extend TrustWeave:

┌─────────────────────────────────────────────────────────────┐
│                    User Application Code                     │
└───────────────────────────┬─────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                    TrustWeave Facade                           │
│              (TrustWeave.create())                             │
└───────────────┬───────────────────────────────┬───────────────┘
                │                               │
                ▼                               ▼
┌───────────────────────────┐    ┌───────────────────────────┐
│   Service Interfaces      │    │   Service Registries      │
│  - DidMethod              │    │  - DidMethodRegistry      │
│  - KeyManagementService   │    │  - BlockchainAnchorRegistry│
│  - BlockchainAnchorClient │    │  - CredentialServiceRegistry│
└───────────────┬───────────┘    └───────────────┬───────────┘
                │                               │
                ▼                               ▼
┌─────────────────────────────────────────────────────────────┐
│              Plugin Implementations                          │
│  - DidKeyMethod, DidWebMethod, etc.                          │
│  - InMemoryKMS, AWSKMS, AzureKMS, etc.                      │
│  - AlgorandClient, PolygonClient, etc.                       │
└───────────────┬───────────────────────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────────────────┐
│              External Systems                                 │
│  - Blockchains (Algorand, Ethereum, Polygon, etc.)          │
│  - KMS Providers (AWS, Azure, Google Cloud, etc.)          │
│  - DID Resolvers (Universal Resolver, etc.)                 │
└─────────────────────────────────────────────────────────────┘

Plugin Architecture

TrustWeave uses the Service Provider Interface (SPI) pattern for automatic plugin discovery:

Plugin Registration: Plugins implement provider interfaces (e.g., DidMethodProvider)
Automatic Discovery: Java ServiceLoader discovers plugins on the classpath
Manual Registration: You can also register plugins manually via registries

// Automatic discovery (via SPI)
val result = WaltIdIntegration.discoverAndRegister(registry)

// Manual registration
val didRegistry = DidMethodRegistry().apply {
    register(DidKeyMethod(kms))
    register(DidWebMethod(kms))
}

Trust Layer Concept

The Trust Layer is TrustWeave’s configuration DSL that lets you declaratively configure all services:

val trustLayer = trustLayer {
    keys {
        provider("inMemory")  // KMS configuration
    }
    did {
        method("key")          // DID method configuration
    }
    blockchains {
        "algorand:testnet" to algorandClient  // Blockchain configuration
    }
    wallet {
        enableOrganization()
        enablePresentation()
    }
}

When to use the Trust Layer:

Complex multi-service configurations
Reusable trust configurations across applications
When you want a single source of truth for configuration

End-to-End Identity Flow

sequenceDiagram
    participant App as Application / SDK Client
    participant DID as DidMethodRegistry<br/>+ DidMethod
    participant KMS as KeyManagementService
    participant VC as CredentialServiceRegistry<br/>+ Issuer
    participant Anchor as BlockchainAnchorClient

    App->>DID: request method("key")
    DID->>KMS: generateKey(algorithm)
    KMS-->>DID: KeyHandle
    DID-->>App: DidDocument
    App->>VC: issueCredential(did, claims)
    VC->>KMS: sign(canonicalCredential)
    VC-->>App: VerifiableCredential (+ proof)
    App->>Anchor: writePayload(credentialDigest)
    Anchor-->>App: AnchorResult (AnchorRef)
    note over App,Anchor: Store DID, VC, AnchorRef<br/>Verify later via TrustWeave.verifyCredential()

Roles and relationships

DID creation: DidMethodRegistry resolves a method implementation, which collaborates with KeyManagementService to mint keys and returns a W3C-compliant DidDocument.
Credential issuance: The CredentialServiceRegistry hands off to an issuer that canonicalises the payload, signs it through the same KMS, and produces a VerifiableCredential with a proof.
Anchoring: The credential digest (or any payload) flows through BlockchainAnchorClient, yielding an AnchorRef teams can persist for tamper evidence.
Verification: When verifying, TrustWeave pulls the DID document, replays canonicalisation + signature validation, and optionally checks the anchor reference.

Use this flow as a mental checklist: if you know which step you are implementing, the linked module sections below show the relevant interfaces and extension points.

Module Structure

TrustWeave is organized into a domain-centric structure with core modules and plugin implementations:

TrustWeave/
├── common/                         # Common module
│   └── trustweave-common/             # Base types, exceptions, JSON utilities, plugin infrastructure (includes SPI interfaces)
├── trust/                          # Trust module
│   └── trustweave-trust/            # Trust registry and trust layer
├── testkit/                        # Test utilities
│   └── trustweave-testkit/          # Test utilities and mocks
│
├── did/                           # DID domain
│   ├── trustweave-did/              # Core DID abstraction
│   └── plugins/                   # DID method implementations
│       ├── key/                   # did:key implementation
│       ├── web/                   # did:web implementation
│       ├── ion/                   # did:ion implementation
│       └── ...                    # Other DID methods
│
├── kms/                           # KMS domain
│   ├── trustweave-kms/              # Core KMS abstraction
│   └── plugins/                   # KMS implementations
│       ├── aws/                   # AWS KMS
│       ├── azure/                 # Azure Key Vault
│       ├── google/                # Google Cloud KMS
│       └── ...                    # Other KMS providers
│
├── chains/                        # Blockchain/Chain domain
│   ├── trustweave-anchor/           # Core anchor abstraction
│   └── plugins/                   # Chain implementations
│       ├── algorand/              # Algorand adapter
│       ├── polygon/               # Polygon adapter
│       └── ...                    # Other blockchain adapters
│
└── distribution/                  # Distribution modules
    ├── trustweave-all/              # All-in-one module
    ├── trustweave-bom/              # Bill of Materials
    └── trustweave-examples/         # Example applications

Core Modules

trustweave-common

Base exception classes (com.trustweave.core.exception)
Common constants and utilities (com.trustweave.core.util)
Plugin infrastructure (com.trustweave.core.plugin)
JSON canonicalization and digest computation (com.trustweave.core.util.DigestUtils)
Input validation utilities (com.trustweave.core.util)
Result extensions and error handling (com.trustweave.core.util)

trustweave-kms

KeyManagementService interface
Key generation, signing, retrieval
Algorithm-agnostic design

trustweave-did

DidMethod interface
DID Document models (W3C compliant)
DidMethodRegistry for method registration (instance-scoped)

trustweave-anchor

BlockchainAnchorClient interface
AnchorRef for chain-agnostic references
BlockchainAnchorRegistry for client registration (instance-scoped)

trustweave-testkit

In-memory implementations
Test utilities
Mock implementations for testing

Integration Modules

KMS Plugins

Cloud KMS Providers

AWS KMS (com.trustweave.kms:aws) – AWS Key Management Service. See AWS KMS Integration Guide.
AWS CloudHSM (com.trustweave.kms:cloudhsm) – AWS CloudHSM for dedicated hardware security modules. Documentation coming soon.
Azure Key Vault (com.trustweave.kms:azure) – Azure Key Vault integration. See Azure KMS Integration Guide.
Google Cloud KMS (com.trustweave.kms:google) – Google Cloud KMS integration. See Google KMS Integration Guide.
IBM Key Protect (com.trustweave.kms:ibm) – IBM Cloud Key Protect integration. Documentation coming soon.

Self-Hosted KMS Providers

HashiCorp Vault (com.trustweave.kms:hashicorp) – HashiCorp Vault Transit engine. See HashiCorp Vault KMS Integration Guide.
Thales CipherTrust (com.trustweave.kms:thales) – Thales CipherTrust Manager integration. Documentation coming soon.
Thales Luna (com.trustweave.kms:thales-luna) – Thales Luna HSM integration. Documentation coming soon.
CyberArk Conjur (com.trustweave.kms:cyberark) – CyberArk Conjur secrets management integration. Documentation coming soon.
Fortanix DSM (com.trustweave.kms:fortanix) – Fortanix Data Security Manager multi-cloud key management. Documentation coming soon.
Entrust (com.trustweave.kms:entrust) – Entrust key management integration. Documentation coming soon.
Utimaco (com.trustweave.kms:utimaco) – Utimaco HSM integration. Documentation coming soon.

Other KMS Integrations

walt.id (com.trustweave.kms:waltid) – walt.id-based KMS and DID methods. See walt.id Integration Guide.

DID Method Plugins

GoDiddy (com.trustweave.did:godiddy) – HTTP integration with GoDiddy services. Universal Resolver, Registrar, Issuer, Verifier. Supports 20+ DID methods. See GoDiddy Integration Guide.
did:key (com.trustweave.did:key) – Native did:key implementation. See Key DID Integration Guide.
did:web (com.trustweave.did:web) – Web DID method. See Web DID Integration Guide.
did:ion (com.trustweave.did:ion) – Microsoft ION DID method. See ION DID Integration Guide.
See Integration Modules for all DID method implementations.

Blockchain Anchor Plugins

Algorand (com.trustweave.chains:algorand) – Algorand blockchain adapter. Mainnet and testnet support. See Algorand Integration Guide.
Polygon (com.trustweave.chains:polygon) – Polygon blockchain adapter. See Integration Modules.
Ethereum (com.trustweave.chains:ethereum) – Ethereum blockchain adapter. See Ethereum Anchor Integration Guide.
Base (com.trustweave.chains:base) – Base (Coinbase L2) adapter. See Base Anchor Integration Guide.
Arbitrum (com.trustweave.chains:arbitrum) – Arbitrum adapter. See Arbitrum Anchor Integration Guide.
See Integration Modules for all blockchain adapters.

Design Patterns

Scoped Registry Pattern

Registries are owned by the application context rather than global singletons:

val didRegistry = DidMethodRegistry().apply { register(didMethod) }
val blockchainRegistry = BlockchainAnchorRegistry().apply { register(chainId, client) }

val config = TrustWeaveConfig(
    kms = kms,
    walletFactory = walletFactory,
    didRegistry = didRegistry,
    blockchainRegistry = blockchainRegistry,
    credentialRegistry = CredentialServiceRegistry.create()
)
val TrustWeave = TrustWeave.create(config)

Service Provider Interface (SPI)

Adapters can be automatically discovered via Java ServiceLoader:

// Automatic discovery
val result = WaltIdIntegration.discoverAndRegister()

Interface-Based Design

All external dependencies are abstracted through interfaces:

KeyManagementService - Key operations
DidMethod - DID operations
BlockchainAnchorClient - Blockchain operations

Data Flow

DID Creation Flow

Application
    ↓
TrustWeaveContext.getDidMethod("key")
    ↓
DidMethod.createDid()
    ↓
KeyManagementService.generateKey()
    ↓
DidDocument (returned)

Blockchain Anchoring Flow

Application
    ↓
TrustWeaveContext.getBlockchainClient("algorand:mainnet")
    ↓
BlockchainAnchorClient.writePayload()
    ↓
AnchorResult (with AnchorRef)

Integrity Verification Flow

Blockchain Anchor
    ↓
Verifiable Credential (with digest)
    ↓
Linkset (with digest)
    ↓
Artifacts (with digests)
    ↓
Verification Result

Dependencies

Core Module Dependencies

trustweave-common
    (no dependencies - includes JSON utilities, plugin infrastructure, SPI interfaces)

trustweave-kms
    → trustweave-common

trustweave-did
    → trustweave-common
    → trustweave-kms

trustweave-anchor
    → trustweave-common

trustweave-testkit
    → trustweave-common
    → trustweave-kms
    → trustweave-did
    → trustweave-anchor

Integration Module Dependencies

KMS Plugins (com.trustweave.kms:*)
    → trustweave-common
    → trustweave-kms
    See: [KMS Integration Guides](/integrations/README/#other-did--kms-integrations)

DID Plugins (com.trustweave.did:*)
    → trustweave-common
    → trustweave-did
    → trustweave-kms
    See: [DID Integration Guides](/integrations/README/#did-method-integrations)

Chain Plugins (com.trustweave.chains:*)
    → trustweave-common
    → trustweave-anchor
    See: [Blockchain Integration Guides](/integrations/README/#blockchain-anchor-integrations)

Extensibility

Adding a New DID Method

Implement DidMethod interface
Optionally implement DidMethodProvider for SPI
Register via DidMethodRegistry.register()

Adding a New Blockchain Adapter

Implement BlockchainAnchorClient interface
Optionally implement BlockchainAnchorClientProvider for SPI
Register via BlockchainAnchorRegistry.register()

Adding a New KMS Backend

Implement KeyManagementService interface
Optionally implement KeyManagementServiceProvider for SPI
Use directly or register via SPI

Next Steps

Learn about Core Modules
Explore Integration Modules
Review the Trust Layer Setup Checklist before wiring issuance or verification flows

Architecture Overview

TrustWeave Mental Model

1. Facade Layer (TrustWeave.create()) - Simplest API

2. Service Layer (Direct Interfaces) - Fine-Grained Control

3. DSL Layer (trustLayer { }) - Declarative Configuration

Component Interaction Flow

Plugin Architecture

Trust Layer Concept

End-to-End Identity Flow

Module Structure

Core Modules

trustweave-common

trustweave-kms

trustweave-did

trustweave-anchor

trustweave-testkit

Integration Modules

KMS Plugins

Cloud KMS Providers

Self-Hosted KMS Providers

Other KMS Integrations

DID Method Plugins

Blockchain Anchor Plugins

Design Patterns

Scoped Registry Pattern

Service Provider Interface (SPI)

Interface-Based Design

Data Flow

DID Creation Flow

Blockchain Anchoring Flow

Integrity Verification Flow

Dependencies

Core Module Dependencies

Integration Module Dependencies

Extensibility

Adding a New DID Method

Adding a New Blockchain Adapter

Adding a New KMS Backend

Next Steps

1. Facade Layer (`TrustWeave.create()`) - Simplest API

3. DSL Layer (`trustLayer { }`) - Declarative Configuration