trustweave-anchor

The trustweave-anchor module provides blockchain anchoring abstraction with chain-agnostic interfaces for notarizing data on various blockchains.

1
2
3
4
5

dependencies {
    implementation("com.trustweave:trustweave-anchor:1.0.0-SNAPSHOT")
    implementation("com.trustweave:trustweave-common:1.0.0-SNAPSHOT")
    implementation("com.trustweave:trustweave-json:1.0.0-SNAPSHOT")
}

Result: Gradle exposes the blockchain anchor client interfaces and utilities so you can anchor data to any supported blockchain.

Overview

The trustweave-anchor module provides:

  • BlockchainAnchorClient Interface – chain-agnostic interface for anchoring operations
  • AnchorRef – chain-agnostic reference structure (chain ID + transaction hash)
  • AnchorResult – result structure containing anchor references
  • BlockchainAnchorRegistry – instance-scoped registry for managing blockchain clients
  • Type-Safe Options – sealed class hierarchy for blockchain-specific configurations
  • Type-Safe Chain IDs – CAIP-2 compliant chain identifier types
  • SPI Support – service provider interface for auto-discovery of blockchain adapters

Key Components

BlockchainAnchorClient Interface 

1
2
3
4
5
6
7
8

import com.trustweave.anchor.*

interface BlockchainAnchorClient {
    val chainId: String  // CAIP-2 format: "eip155:1", "algorand:testnet", etc.

    suspend fun writePayload(payload: ByteArray): AnchorResult
    suspend fun readPayload(anchorRef: AnchorRef): ByteArray?
}

What this does: Defines the contract for anchoring operations that all blockchain adapters must fulfill.

Outcome: Enables TrustWeave to anchor data to multiple blockchains (Algorand, Polygon, Ethereum, etc.) through a unified interface.

Type-Safe Options

The module provides type-safe configuration options:

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

sealed class BlockchainAnchorClientOptions {
    data class AlgorandOptions(
        val algodUrl: String,
        val indexerUrl: String? = null,
        val privateKey: String
    ) : BlockchainAnchorClientOptions()

    data class PolygonOptions(
        val rpcUrl: String,
        val chainId: Long,
        val privateKey: String
    ) : BlockchainAnchorClientOptions(), Closeable

    // ... other options
}

What this does: Provides compile-time validation for blockchain-specific configurations.

Outcome: Prevents runtime configuration errors and enables better IDE support.

Type-Safe Chain IDs 

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

sealed class ChainId {
    sealed class Algorand : ChainId() {
        object Mainnet : Algorand()
        object Testnet : Algorand()
    }

    sealed class Polygon : ChainId() {
        data class Mainnet(val id: Long = 137) : Polygon()
        data class Mumbai(val id: Long = 80001) : Polygon()
    }

    // ... other chain IDs
}

What this does: Provides type-safe chain identifiers that comply with CAIP-2 specification.

Outcome: Ensures correct chain ID usage and prevents common errors.

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

import com.trustweave.anchor.*
import java.util.ServiceLoader

// Discover blockchain adapter via SPI
val providers = ServiceLoader.load(BlockchainAnchorClientProvider::class.java)
val algorandProvider = providers.find { it.supportsChain("algorand:testnet") }

// Create anchor client with type-safe options
val options = AlgorandOptions(
    algodUrl = "https://testnet-api.algonode.cloud",
    privateKey = "..."
)

val client = algorandProvider?.create("algorand:testnet", options)

// Anchor data
val payload = "Hello, TrustWeave!".toByteArray()
val result = client?.writePayload(payload)

println("Anchored to: ${result?.anchorRef?.chainId}")
println("Transaction hash: ${result?.anchorRef?.transactionHash}")

// Read anchored data
val readData = result?.anchorRef?.let { client.readPayload(it) }

What this does: Uses SPI to discover a blockchain adapter, anchors data to the Algorand testnet, and then reads it back.

Outcome: Enables seamless blockchain anchoring across different networks.

Supported Blockchains

TrustWeave provides adapters for:

See the Blockchain Anchor Integration Guides for detailed information about each adapter.

Exception Hierarchy

The module provides structured exception handling:

  • BlockchainException – base exception with chain ID and operation context
  • BlockchainTransactionException – transaction failures (includes txHash, payloadSize, gasUsed)
  • BlockchainConnectionException – connection failures (includes endpoint)
  • BlockchainConfigurationException – configuration errors (includes config key)
  • BlockchainUnsupportedOperationException – unsupported operations

What this does: Provides rich error context for debugging and error handling.

Outcome: Enables better error messages and easier troubleshooting.

Dependencies

  • Depends on trustweave-common for core types, exceptions, and SPI interfaces (JSON utilities are included in trustweave-common)

Next Steps