Configuration Reference

How to configure TrustWeave for development, tests, and production. For what you get out of the box, see Default configuration.

Configuration entry points

  1. TrustWeave.quickStart() (suspend) — In-memory KMS, did:key, test-friendly defaults. Same as TrustWeave.inMemory(); use whichever reads better.
  2. TrustWeave.build { } (suspend) — Primary way to set KMS, DID methods, anchors, factories, and credential defaults.
  3. TrustWeave.from(config) — Wrap an existing TrustWeaveConfig. The config type has an internal constructor; application code should obtain it only via TrustWeave.build (or test utilities), not by calling the constructor directly.

All build / quickStart examples assume a suspend context or runBlocking { ... }.

1
2
3
4
5
6
7
8

import org.trustweave.trust.quickStart
import kotlinx.coroutines.runBlocking
import org.trustweave.trust.TrustWeave

fun main() = runBlocking {
    val trustWeave = TrustWeave.quickStart()
    // or: val trustWeave = TrustWeave.build { /* ... */ }
}

Configuration components

Key management (KMS)

Purpose: Signing keys for DIDs and credentials.

Default: In-memory KMS (testing only).

Production: Prefer passing a configured KMS instance via customKms(kms), or declare a provider name with keys { provider("awsKms"); algorithm("Ed25519") }. Note that KeysBuilder.provider(name) takes no nested block — provider-specific options are supplied when you construct the KMS instance you pass to customKms(...) (e.g. via KeyManagementServices.create("aws", awsKmsOptions { region = "us-east-1" })).

1
2
3
4
5
6
7
8
9
10
11

import org.trustweave.kms.KeyManagementServices
import org.trustweave.awskms.awsKmsOptions

val awsKms = KeyManagementServices.create("aws", awsKmsOptions { region = "us-east-1" })

TrustWeave.build {
    customKms(awsKms)
    // Alternative (named registration only, no provider-options block):
    // keys { provider("awsKms"); algorithm("Ed25519") }
    did { method("key") { algorithm("Ed25519") } }
}

See also: KMS integrations, Key management.

DID methods

Purpose: Create and resolve DIDs.

Default: did:key when you do not declare other methods.

Configuration: Declare methods in the did { } block. Additional methods are also picked up from classpath SPI when registered by plugins.

1
2
3
4
5
6

TrustWeave.build {
    did {
        method("web") { domain("example.com") }
        method("key") { algorithm("Ed25519") }
    }
}

See also: DID integrations, DIDs, DID method plugins.

Blockchain anchoring

Purpose: Anchor payloads to chains (CAIP-2 chain IDs).

Default: No chains until you add them.

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

import org.trustweave.trust.dsl.credential.AnchorProviders

TrustWeave.build {
    anchor {
        chain("algorand:testnet") {
            provider(AnchorProviders.ALGORAND)
            options { /* e.g. "algodUrl" to "…", "privateKey" to "…" */ }
        }
        chain("ethereum:mainnet") {
            provider(AnchorProviders.ETHEREUM)
            options { /* RPC URL, credentials, etc. */ }
        }
    }
}

For local tests, inMemory() inside chain("…") { } is available (see Default configuration).

See also: Blockchain integrations, Blockchain anchoring, Blockchain plugins.

Wallet factory

Purpose: Create holder wallets.

Default: In-memory / testkit-oriented factory unless you override.

1
2
3
4

TrustWeave.build {
    factories(walletFactory = databaseWalletFactory)
    did { method("key") { algorithm("Ed25519") } }
}

See also: Wallet API, Wallets.

Credential service and proof defaults

Purpose: Issuance/verification pipeline and defaults (proof type, auto-anchor, default chain).

The builder wires a default credential service from KMS + DID resolution unless you set credentialService(...).

1
2
3
4
5
6
7
8
9

TrustWeave.build {
    credentialService(myCredentialService) // optional override
    credentials {
        defaultProofType("Ed25519Signature2020")
        autoAnchor(true)                     // anchors a digest of every issued credential
        defaultChain("algorand:testnet")     // required when autoAnchor is on
    }
    did { method("key") { algorithm("Ed25519") } }
}

What autoAnchor writes. A SHA-256 digest envelope ({alg, digest, mediaType}) of the canonicalized credential — never the credential itself. Anchoring proves a credential existed and has not been altered; publishing its credentialSubject would put the subject’s claims on a public ledger permanently, and the default payload mode for an anchor client is full-payload. A single configuration flag must not be able to do that. To verify later, canonicalize the credential, hash it, and compare against the anchored digest. If you genuinely want the whole document on-chain, call trustWeave.blockchains.anchor(credential, ...) explicitly instead.

autoAnchor fails closed, matching withRevocation(): if no defaultChain is set, no anchor layer is configured, or the anchor write fails, issuance returns a failure rather than handing back a credential the caller believes was anchored.

See also: Credential service API, Verifiable credentials.

Validation

Configuration is resolved when TrustWeave.build runs. Failures surface as IllegalStateException or other domain exceptions (e.g. unknown provider). Handle them at application startup:

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

import org.trustweave.trust.TrustWeave
import kotlinx.coroutines.runBlocking

val result = runCatching {
    runBlocking {
        TrustWeave.build {
            anchor {
                chain("unknown:chain") { provider("no-such-provider") }
            }
        }
    }
}

result.onFailure { error ->
    println("Configuration failed: ${error.message}")
}

For TrustWeaveException.ValidationFailed and other error types, see Error handling.

Environment-oriented examples

Development 

1

val trustWeave = TrustWeave.quickStart()

Integration tests (in-memory anchor chains) 

1
2
3
4
5
6
7

TrustWeave.build {
    anchor {
        chain("inmemory:test-a") { inMemory() }
        chain("inmemory:test-b") { inMemory() }
    }
    did { method("key") { algorithm("Ed25519") } }
}

Production-shaped sketch 

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

TrustWeave.build {
    customKms(awsKms)
    did {
        method("web") { domain("yourcompany.com") }
    }
    anchor {
        chain("algorand:mainnet") {
            provider("algorand")
            options {
                "algodUrl" to System.getenv("ALGOD_URL")
                "privateKey" to System.getenv("ALGORAND_PRIVATE_KEY")
            }
        }
    }
    factories(walletFactory = DatabaseWalletFactory(dataSource))
}

Best practices

  1. Secrets: Load URLs and keys from the environment or a secret manager, not source control.
  2. Fail fast: Build TrustWeave at startup so misconfiguration is obvious.
  3. Close resources: Call trustWeave.close() when shutting down (KMS and clients may hold connections). For plugin-specific lifecycle, see Plugin lifecycle.
This site uses Just the Docs, a documentation theme for Jekyll.