Smart Contract API Reference

Complete API reference for TrustWeave Smart Contract operations

Overview

The Smart Contract API provides methods for creating, binding, executing, and managing executable contracts with verifiable credentials and blockchain anchoring.

Service Access 

1
2
3
4

import org.trustweave.trust.TrustWeave

val trustWeave = TrustWeave.build { ... }
val contracts = trustWeave.contracts

API Methods

draft (or createDraft)

Creates a new contract draft.

Signature:

1
2
3
4
5
6
7
8

suspend fun draft(
    request: ContractDraftRequest
): Result<SmartContract>

// Also available as:
suspend fun createDraft(
    request: ContractDraftRequest
): Result<SmartContract>

Parameters:

  • request (ContractDraftRequest, required): Contract draft request containing:
    • contractType: Type of contract (Insurance, Legal, Financial, etc.)
    • executionModel: How the contract executes (Parametric, Conditional, Scheduled, etc.)
    • parties: Contract parties identified by DIDs
    • terms: Contract terms (obligations, conditions, penalties, rewards)
    • effectiveDate: ISO 8601 timestamp when contract becomes effective
    • expirationDate: Optional ISO 8601 timestamp when contract expires
    • contractData: Domain-specific contract data as JSON

Returns: Result<SmartContract> with contract in DRAFT status

Example (DSL form, recommended):

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

import org.trustweave.trust.TrustWeave

val trustWeave = TrustWeave.build { ... }

val contract = trustWeave.contracts.draft {
    contractType = ContractType.Insurance
    executionModel = ExecutionModel.Parametric(...)
    parties = ContractParties(insurerDid, insuredDid)
    terms = contractTerms
    effectiveDate = Instant.now().toString()
    contractData {
        "domain" to "flood"
        "thresholds" {
            "floodDepthCm" to 50.0
        }
    }
}.getOrThrow()

If you already have a ContractDraftRequest in hand (e.g. coming over the wire), createDraft(request) and draft(request) accept it directly.

Validation:

  • Validates DID formats for all parties
  • Ensures expiration date is after effective date
  • Validates terms (unique IDs, valid party DIDs)
  • Validation failures surface as a Result.failure wrapping TrustWeaveException.InvalidOperation (or ValidationFailed); there is no separate InvalidOperationException type.

bindContract

Binds a contract by issuing a verifiable credential and anchoring to blockchain.

Signature:

1
2
3
4
5
6

suspend fun bindContract(
    contractId: String,
    issuerDid: String,
    issuerKeyId: String,
    chainId: String = "algorand:mainnet"
): Result<BoundContract>

Parameters:

  • contractId (String, required): ID of the contract to bind
  • issuerDid (String, required): DID of the credential issuer
  • issuerKeyId (String, required): Key ID from issuer’s DID document
  • chainId (String, optional): Blockchain chain ID (default: “algorand:mainnet”)

Returns: Result<BoundContract> containing:

  • contract: Updated contract with credential ID and anchor reference
  • credentialId: ID of the issued verifiable credential
  • anchorRef: Blockchain anchor reference

Example:

1
2
3
4
5
6

val bound = trustWeave.contracts.bindContract(
    contractId = contract.id,
    issuerDid = insurerDid,
    issuerKeyId = insurerKeyId,
    chainId = "algorand:mainnet"
).getOrThrow()

Status Transition: DRAFT → PENDING

activateContract

Activates a contract (moves from PENDING to ACTIVE).

Signature:

1
2
3

suspend fun activateContract(
    contractId: String
): Result<SmartContract>

Parameters:

  • contractId (String, required): ID of the contract to activate

Returns: Result<SmartContract> with contract in ACTIVE status

Example:

1

val active = trustWeave.contracts.activateContract(contractId).getOrThrow()

Validation:

  • Contract must be in PENDING status
  • Contract must not be expired
  • Failures surface as Result.failure(TrustWeaveException.InvalidOperation(...)).

Status Transition: PENDING → ACTIVE

executeContract

Executes a contract based on its execution model.

Signature:

1
2
3
4

suspend fun executeContract(
    contract: SmartContract,
    executionContext: ExecutionContext
): Result<ExecutionResult>

Parameters:

  • contract (SmartContract, required): The contract to execute
  • executionContext (ExecutionContext, required): Execution context containing:
    • triggerData: JSON data for parametric execution
    • eventData: JSON data for event-driven execution
    • timeContext: ISO 8601 timestamp for time-based execution
    • additionalContext: Additional context as JSON

Returns: Result<ExecutionResult> containing:

  • executed: Whether contract was executed
  • executionType: Type of execution (PARAMETRIC_TRIGGER, etc.)
  • outcomes: List of contract outcomes
  • evidence: List of verifiable credential IDs used as evidence
  • timestamp: Execution timestamp

Example (DSL form, recommended):

1
2
3
4
5
6

val result = trustWeave.contracts.executeContract(activeContract) {
    trigger {
        "floodDepthCm" to 75.0
        "credentialId" to floodCredential.id
    }
}.getOrThrow()

event { } is the event-driven counterpart; timeContext and additionalContext { } are also available inside the block. For one-liner parametric calls there is also executeParametric(contract, vararg pairs):

1

trustWeave.contracts.executeParametric(activeContract, "floodDepthCm" to 75.0)

Validation:

  • Contract must be in ACTIVE status
  • Contract must not be expired
  • Automatically expires contract if expired

Status Transition: ACTIVE → EXECUTED (if conditions met)

evaluateConditions

Evaluates contract conditions without executing.

Signature:

1
2
3
4

suspend fun evaluateConditions(
    contract: SmartContract,
    inputData: JsonElement
): Result<ConditionEvaluation>

Parameters:

  • contract (SmartContract, required): The contract to evaluate
  • inputData (JsonElement, required): Input data for condition evaluation

Returns: Result<ConditionEvaluation> containing:

  • conditions: List of condition results
  • overallResult: Whether all conditions are satisfied
  • timestamp: Evaluation timestamp

Example (DSL form, recommended):

1
2
3
4
5
6
7

val evaluation = trustWeave.contracts.evaluateConditions(contract) {
    "floodDepthCm" to 75.0
}.getOrThrow()

evaluation.conditions.forEach { condition ->
    println("${condition.conditionId}: ${if (condition.satisfied) "✓" else "✗"}")
}

updateStatus

Updates contract status with validation.

Signature:

1
2
3
4
5
6

suspend fun updateStatus(
    contractId: String,
    newStatus: ContractStatus,
    reason: String? = null,
    metadata: JsonElement? = null
): Result<SmartContract>

Parameters:

  • contractId (String, required): ID of the contract
  • newStatus (ContractStatus, required): New status
  • reason (String, optional): Reason for status change
  • metadata (JsonElement, optional): Additional metadata

Returns: Result<SmartContract> with updated status

Example:

1
2
3
4
5

val updated = trustWeave.contracts.updateStatus(
    contractId = contract.id,
    newStatus = ContractStatus.SUSPENDED,
    reason = "Under review"
).getOrThrow()

Validation:

  • Validates state transition is allowed
  • Invalid transitions surface as Result.failure(TrustWeaveException.InvalidOperation(...)).

getContract

Retrieves a contract by ID.

Signature:

1

suspend fun getContract(contractId: String): Result<SmartContract>

Parameters:

  • contractId (String, required): ID of the contract

Returns: Result<SmartContract>

Example:

1

val contract = trustWeave.contracts.getContract(contractId).getOrThrow()

Errors:

  • Result.failure(TrustWeaveException.NotFound(...)) if no contract with that id exists.

verifyContract

Verifies a contract’s verifiable credential.

Signature:

1
2
3

suspend fun verifyContract(
    credentialId: String
): Result<Boolean>

Parameters:

  • credentialId (String, required): ID of the contract credential

Returns: Result<Boolean> indicating verification result

Example:

1

val isValid = trustWeave.contracts.verifyContract(credentialId).getOrThrow()

Data Models

SmartContract

Main contract model:

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

data class SmartContract(
    val id: String,
    val contractNumber: String,
    val status: ContractStatus,
    val contractType: ContractType,
    val executionModel: ExecutionModel,
    val parties: ContractParties,
    val terms: ContractTerms,
    val effectiveDate: String,
    val expirationDate: String?,
    val createdAt: String,
    val updatedAt: String,
    val credentialId: String?,
    val anchorRef: AnchorRefData?,
    val contractData: JsonElement
)

ContractStatus

Contract lifecycle status:

1
2
3
4

enum class ContractStatus {
    DRAFT, PENDING, ACTIVE, SUSPENDED,
    EXECUTED, EXPIRED, CANCELLED, TERMINATED
}

ExecutionModel

Contract execution models:

1
2
3
4
5
6
7

sealed class ExecutionModel {
    data class Parametric(...) : ExecutionModel()
    data class Conditional(...) : ExecutionModel()
    data class Scheduled(...) : ExecutionModel()
    data class EventDriven(...) : ExecutionModel()
    object Manual : ExecutionModel()
}

ContractParties

Contract parties:

1
2
3
4
5

data class ContractParties(
    val primaryPartyDid: String,
    val counterpartyDid: String,
    val additionalParties: Map<String, String> = emptyMap()
)

ContractTerms

Contract terms:

1
2
3
4
5
6
7
8
9

data class ContractTerms(
    val obligations: List<Obligation>,
    val conditions: List<ContractCondition>,
    val penalties: List<Penalty>? = null,
    val rewards: List<Reward>? = null,
    val jurisdiction: String? = null,
    val governingLaw: String? = null,
    val disputeResolution: DisputeResolution? = null
)

Error Handling

All methods return kotlin.Result<T>. Failures wrap TrustWeaveException subtypes — there are no NotFoundException / InvalidOperationException types in TrustWeave.

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

import org.trustweave.core.exception.TrustWeaveException

result.fold(
    onSuccess = { contract -> /* handle success */ },
    onFailure = { error ->
        when (error) {
            is TrustWeaveException.NotFound -> { /* contract not found */ }
            is TrustWeaveException.InvalidOperation -> { /* invalid state transition / action */ }
            is TrustWeaveException.ValidationFailed -> { /* bad input */ }
            else -> { /* other error */ }
        }
    }
)

See Also

This site uses Just the Docs, a documentation theme for Jekyll.