trustweave-contract Module

Version: 1.0.0-SNAPSHOT Domain-agnostic Smart Contract abstraction with verifiable credentials and blockchain anchoring

Overview

The trustweave-contract module provides a generic Smart Contract abstraction for executable agreements between parties. It integrates with TrustWeave’s verifiable credentials and blockchain anchoring to provide trust, auditability, and automation.

Purpose

Smart Contracts in TrustWeave enable:

  • Executable Agreements: Contracts that can automatically execute based on conditions
  • Verifiable Terms: Contract terms wrapped in Verifiable Credentials
  • Immutable Audit Trails: Blockchain anchoring for tamper-proof records
  • Multi-Party Support: Parties identified by DIDs
  • Pluggable Execution: Parametric, conditional, scheduled, event-driven, or manual execution

When to Use

Add this module when you need:

  • Parametric insurance contracts
  • Service level agreements (SLAs)
  • Financial derivatives
  • Legal contracts with automated execution
  • Supply chain agreements
  • Any executable agreement requiring trust and auditability

Installation 

1
2
3

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

Note: This module is included in trustweave-all, so you may already have access if you’re using the all-in-one distribution.

Module Dependencies 

1
2
3
4

trustweave-contract
    → trustweave-common (includes SPI, JSON utilities)
    → trustweave-anchor
    → trustweave-did

Key Components

Models

  • SmartContract: Main contract data model
  • ContractStatus: Contract lifecycle status enum
  • ContractType: Contract type classification (Insurance, Legal, Financial, etc.)
  • ExecutionModel: Execution model (Parametric, Conditional, Scheduled, etc.)
  • ContractParties: Parties identified by DIDs
  • ContractTerms: Obligations, conditions, penalties, rewards
  • AnchorRefData: Serializable wrapper for blockchain anchor references

Services

  • SmartContractService: Interface for contract operations
  • DefaultSmartContractService: In-memory implementation
  • ContractValidator: Validation utilities

Integration

  • ContractService: Service wrapper exposed via trustWeave.contracts property

Usage Example 

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
31
32
33
34

import com.trustweave.trust.TrustWeave
import com.trustweave.contract.models.*

val trustweave = TrustWeave.build { ... }

// Create contract draft
val contract = trustweave.contracts.draft(
    request = ContractDraftRequest(
        contractType = ContractType.Insurance,
        executionModel = ExecutionModel.Parametric(...),
        parties = ContractParties(...),
        terms = ContractTerms(...),
        effectiveDate = Instant.now().toString(),
        contractData = buildJsonObject { ... }
    )
).getOrThrow()

// Bind contract (issue VC and anchor)
val bound = trustweave.contracts.bindContract(
    contractId = contract.id,
    issuerDid = insurerDid,
    issuerKeyId = insurerKeyId
).getOrThrow()

// Activate contract
val active = trustweave.contracts.activateContract(bound.contract.id).getOrThrow()

// Execute contract
val result = trustweave.contracts.executeContract(
    contract = active,
    executionContext = ExecutionContext(
        triggerData = buildJsonObject { ... }
    )
).getOrThrow()

Features

Contract Lifecycle

Manages complete contract lifecycle:

  • DRAFT → PENDING → ACTIVE → EXECUTED/EXPIRED/CANCELLED/TERMINATED

Execution Models

Supports multiple execution models:

  • Parametric: Triggers based on external data (EO, weather, market data)
  • Conditional: If/then logic with rule evaluation
  • Scheduled: Time-based actions
  • Event-Driven: Responds to external events
  • Manual: Requires human intervention

Validation

Automatic validation of:

  • DID formats for all parties
  • Date ranges (expiration after effective date)
  • State transitions
  • Terms (unique IDs, valid party DIDs)
  • Expiration checking

TrustWeave Integration

  • Verifiable Credentials: Contracts issued as VCs
  • Blockchain Anchoring: Contracts anchored for audit trails
  • DID-Based Parties: All parties identified by DIDs

Thread Safety

DefaultSmartContractService uses ConcurrentHashMap for thread-safe contract storage. All operations use Kotlin coroutines for non-blocking I/O.

Storage

The default implementation (DefaultSmartContractService) uses in-memory storage suitable for:

  • Testing and development
  • Prototyping
  • Short-lived contracts

For production use, implement SmartContractService with persistent storage (database, etc.).

See Also