Use TrustWeave Facade for Quick Setup

This guide shows you how to use TrustWeave’s simple facade API for rapid prototyping and production applications. The facade provides sensible defaults and reduces setup code by 95%.

Prerequisites

Before you begin, ensure you have:

  • ✅ TrustWeave dependencies added to your project
  • ✅ Basic understanding of DIDs and verifiable credentials
  • ✅ Kotlin coroutines knowledge

Expected Outcome

After completing this guide, you will have:

  • ✅ Created a TrustWeave instance with one line
  • ✅ Issued your first credential with minimal code
  • ✅ Understood when to use the facade vs. full configuration
  • ✅ Learned how to customize facade defaults

Quick Example

Here’s a complete example showing the simplicity of the facade API:

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
27
28
29
30

import org.trustweave.trust.dsl.trustWeave
import org.trustweave.trust.dsl.credential.*
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    trustWeave {
        keys { provider(IN_MEMORY); algorithm(ED25519) }
        did { method(KEY) { algorithm(ED25519) } }
    }.run {
        // Create DID (uses default method from config)
        val (issuerDid, issuerDoc) = createDid().getOrThrow()
        
        // Issue credential using DSL
        val credential = issue {
            credential {
                type("EmployeeCredential")
                issuer(issuerDid)
                subject {
                    id("did:key:holder")
                    "name" to "Alice"
                    "role" to "Engineer"
                }
            }
            signedBy(issuerDid, issuerDoc.verificationMethod.first().id.substringAfter("#"))
        }.getOrThrow()

        println("✅ Created DID: ${issuerDid.value}")
        println("✅ Issued credential: ${credential.id}")
    }
}

Expected Output:

1
2

✅ Created DID: did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
✅ Issued credential: urn:uuid:12345678-1234-1234-1234-123456789abc

Step-by-Step Guide

Step 1: Create TrustWeave Instance

Configure TrustWeave with minimal setup:

1
2
3
4
5
6
7

import org.trustweave.trust.dsl.trustWeave
import org.trustweave.trust.dsl.credential.*

val tw = trustWeave {
    keys { provider(IN_MEMORY); algorithm(ED25519) }
    did { method(KEY) { algorithm(ED25519) } }
}

What this does:

  • ✅ Configures in-memory key management (Ed25519)
  • ✅ Registers did:key method
  • ✅ Sets up default proof types
  • ✅ Initializes all required services

Expected Result: A fully functional TrustWeave instance ready to use.

Step 2: Create a DID

Create a DID with automatic defaults:

1

val (issuerDid, issuerDoc) = tw.createDid().getOrThrow()  // Uses default from config

What this does:

  • ✅ Uses did:key method
  • ✅ Generates Ed25519 key pair
  • ✅ Creates verification method
  • ✅ Returns Did + DidDocument (no separate resolution needed!)

Expected Result: A Did object with value like did:key:z6Mk... and its document.

Step 3: Issue a Credential

Issue a credential using the DSL:

1
2
3
4
5
6
7
8
9
10
11
12

val credential = tw.issue {
    credential {
        type("EmployeeCredential")
        issuer(issuerDid)
        subject {
            id("did:key:holder")
            "name" to "Alice"
            "role" to "Engineer"
        }
    }
    signedBy(issuerDid, issuerDoc.verificationMethod.first().id.substringAfter("#"))
}.getOrThrow()

What this does:

  • ✅ Creates credential structure via DSL
  • ✅ Generates proof automatically
  • ✅ Signs with issuer’s key
  • ✅ Returns signed credential

Expected Result: A verifiable credential with proof.

Step 4: Verify the Credential

Verify the credential you just issued:

1
2

tw.verify { credential(credential) }.getOrThrow()
println("✅ Credential is valid")

Expected Result: Verification passes or throws with error details.

Comparison: Minimal vs. Full Configuration

Minimal Setup 

1
2
3
4
5
6
7
8
9
10

trustWeave {
    keys { provider(IN_MEMORY); algorithm(ED25519) }
    did { method(KEY) { algorithm(ED25519) } }
}.run {
    val (did, doc) = createDid().getOrThrow()  // Uses default
    val cred = issue {
        credential { type("MyCredential"); issuer(did); subject { "claim" to "value" } }
        signedBy(did, doc.verificationMethod.first().id.substringAfter("#"))
    }.getOrThrow()
}

Best for: Prototyping, examples, learning, simple use cases.

Full Configuration 

1
2
3
4
5
6
7
8
9
10
11
12
13
14

trustWeave {
    keys { provider(IN_MEMORY); algorithm(ED25519) }
    did { method(KEY) { algorithm(ED25519) }; method(WEB) { domain("example.com") } }
    anchor { chain("algorand:testnet") { provider(ALGORAND) } }
}.run {
    val (did, doc) = createDid().getOrThrow()  // Uses default "key"
    val cred = issue {
        credential { type("MyCredential"); issuer(did); subject { "claim" to "value" } }
        signedBy(did, doc.verificationMethod.first().id.substringAfter("#"))
    }.getOrThrow()
    
    // Anchor to blockchain
    blockchains.anchor(cred, VerifiableCredential.serializer(), "algorand:testnet").getOrThrow()
}

Best for: Production, multiple DID methods, blockchain anchoring, advanced features.

Customizing Defaults

Adding DID Methods and Blockchain Anchoring 

1
2
3
4
5
6
7
8

trustWeave {
    keys { provider(IN_MEMORY); algorithm(ED25519) }
    did {
        method(KEY) { algorithm(ED25519) }
        method(WEB) { domain("example.com") }
    }
    anchor { chain("algorand:testnet") { provider(ALGORAND) } }
}

What this does:

  • ✅ Registers multiple DID methods (did:key, did:web)
  • ✅ Configures blockchain anchoring
  • ✅ All with minimal, readable DSL syntax

Common Patterns

Pattern 1: Quick Prototype

For rapid prototyping and testing:

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

fun main() = runBlocking {
    trustWeave {
        keys { provider(IN_MEMORY); algorithm(ED25519) }
        did { method(KEY) { algorithm(ED25519) } }  // First method becomes default
    }.run {
        val (issuerDid, issuerDoc) = createDid().getOrThrow()  // Uses default "key"
        val (holderDid, _) = createDid().getOrThrow()
        
        val credential = issue {
            credential {
                type("PersonCredential")
                issuer(issuerDid)
                subject { id(holderDid.value); "name" to "Alice" }
            }
            signedBy(issuerDid, issuerDoc.verificationMethod.first().id.substringAfter("#"))
        }.getOrThrow()

        verify { credential(credential) }.getOrThrow()
        println("✅ Valid credential issued and verified")
    }
}

Pattern 2: Production with Blockchain Anchoring 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

fun main() = runBlocking {
    trustWeave {
        keys { provider(AWS); algorithm(ED25519) }  // Production KMS
        did { method(KEY) { algorithm(ED25519) }; method(WEB) { domain("yourdomain.com") } }
        anchor { chain("algorand:mainnet") { provider(ALGORAND) } }
    }.run {
        val (issuerDid, issuerDoc) = createDid().getOrThrow()  // Uses default "key"
        
        val credential = issue {
            credential { type("EmployeeCredential"); issuer(issuerDid); subject { "name" to "Alice" } }
            signedBy(issuerDid, issuerDoc.verificationMethod.first().id.substringAfter("#"))
        }.getOrThrow()

        // Anchor to blockchain for tamper-evidence
        blockchains.anchor(credential, VerifiableCredential.serializer(), "algorand:mainnet").getOrThrow()
        println("✅ Credential issued and anchored")
    }
}

Pattern 3: Complete Workflow

End-to-end workflow with verification:

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
27
28

fun main() = runBlocking {
    trustWeave {
        keys { provider(IN_MEMORY); algorithm(ED25519) }
        did { method(KEY) { algorithm(ED25519) } }
    }.run {
        // Create issuer and holder (uses default "key" method)
        val (issuerDid, issuerDoc) = createDid().getOrThrow()
        val (holderDid, _) = createDid().getOrThrow()

        // Issue credential
        val credential = issue {
            credential {
                type("EducationCredential")
                issuer(issuerDid)
                subject {
                    id(holderDid.value)
                    "degree" to "Bachelor of Science"
                    "university" to "Example University"
                }
            }
            signedBy(issuerDid, issuerDoc.verificationMethod.first().id.substringAfter("#"))
        }.getOrThrow()

        // Verify
        verify { credential(credential) }.getOrThrow()
        println("✅ Credential verified successfully")
    }
}

Error Handling

Handle errors using Result pattern or try-catch:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// Option 1: Using getOrThrow() - throws on error
trustWeave { ... }.run {
    val (did, doc) = createDid().getOrThrow()  // Throws if fails
}

// Option 2: Using fold() - handle success and failure
trustWeave { ... }.run {
    createDid().fold(
        onSuccess = { (did, doc) -> println("Created: ${did.value}") },
        onFailure = { error -> println("Failed: ${error.message}") }
    )
}

// Option 3: Using getOrElse() - provide default
trustWeave { ... }.run {
    val result = createDid().getOrElse { 
        println("Error: ${it.message}")
        return@run
    }
}

When to Use What

Use Case Configuration
Prototypes, demos, learning Minimal: trustWeave { keys {...}; did {...} }
Production, blockchain, multi-DID Full: Add anchor {...}, custom KMS

Type-Safe Constants

Use these imports to avoid string typos:

1

import org.trustweave.trust.dsl.credential.*
Object Constants
DidMethods KEY, WEB, ION, ETHR
KeyAlgorithms ED25519, SECP256K1, RSA
KmsProviders IN_MEMORY, AWS, AZURE, GOOGLE, HASHICORP, FORTANIX, THALES
AnchorProviders IN_MEMORY, ALGORAND, ETHEREUM, POLYGON, BASE, ARBITRUM
ProofTypes ED25519, JWT, BBS_BLS

For third-party/custom providers, use strings directly: provider("myCustomKms")

Next Steps

Now that you’ve learned the facade API, you can:

  1. Configure TrustWeave - Learn full configuration options
  2. Issue Credentials - Deep dive into credential issuance
  3. Verify Credentials - Learn verification options
  4. Manage Wallets - Store and organize credentials
This site uses Just the Docs, a documentation theme for Jekyll.