NuvTools.Blockchain 10.1.1

NuvTools.Blockchain

A suite of .NET libraries for abstracting tamper-evident, append-only blockchain ledger operations, with comprehensive support for Microsoft Azure Confidential Ledger.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Usage Examples
• Configuration
• Target Frameworks
• Building from Source
• Documentation
• License

Overview

NuvTools.Blockchain provides a clean, intuitive abstraction layer for writing and reading typed records to a blockchain ledger. The library follows a provider pattern, allowing you to implement custom ledger backends while maintaining a consistent API.

Libraries

NuvTools.Blockchain (Core)

The core library defines the foundational abstractions:

• ILedgerService - Interface for writing entries to and reading entries from a ledger
• LedgerEntry<T> - Typed entry returned from the ledger, including TransactionId and optional CollectionId
• LedgerEntryBase<T> - Base wrapper carrying the original Content and CommitTimeUtc

NuvTools.Blockchain.Azure

Azure Confidential Ledger implementation:

• AzureConfidentialLedgerService - Full ILedgerService implementation backed by Azure.Security.ConfidentialLedger
• BlockchainSection - Strongly-typed configuration POCO bound to the NuvTools.Blockchain configuration section
• BlockchainExtensions.AddBlockchain() - Dependency injection registration extension
• Authentication via DefaultAzureCredential (managed identity, environment, Visual Studio, Azure CLI, etc.)
• Built-in retry with linear backoff while entries are in the Loading state (eventual consistency)
• Automatic JSON serialization of payloads
• Lazy client initialization

Features

✅ Provider Pattern - Easy to implement custom ledger backends ✅ Async/Await - Fully asynchronous API with CancellationToken support ✅ Generic Type Support - Write and read any serializable type ✅ Azure Integration - Production-ready Azure Confidential Ledger implementation ✅ Collection / Sub-Ledger Support - Organize entries by collectionId ✅ Eventual-Consistency Retry - Configurable retry while the ledger commits the entry ✅ Automatic Serialization - Records are serialized to JSON transparently ✅ Comprehensive Documentation - Full XML documentation for IntelliSense ✅ Multi-Targeting - Supports .NET 8, 9, and 10

Installation

Install via NuGet Package Manager:

# Core library
dotnet add package NuvTools.Blockchain

# Azure Confidential Ledger implementation
dotnet add package NuvTools.Blockchain.Azure

Or via Package Manager Console:

Install-Package NuvTools.Blockchain
Install-Package NuvTools.Blockchain.Azure

Quick Start

Azure Confidential Ledger Example

1. Configure appsettings.json:

{
  "NuvTools.Blockchain": {
    "LedgerEndpoint": "https://your-ledger-name.confidential-ledger.azure.com"
  }
}

2. Register services in Program.cs:

using NuvTools.Blockchain.Azure;

builder.Services.AddBlockchain(builder.Configuration);

3. Inject ILedgerService and use it:

using NuvTools.Blockchain;

public class AuditService(ILedgerService ledgerService)
{
    public async Task RecordAsync(AuditRecord record, CancellationToken ct)
    {
        var transactionId = await ledgerService.WriteAsync(record, cancellationToken: ct);

        var entry = await ledgerService.ReadAsync<AuditRecord>(transactionId, cancellationToken: ct);

        Console.WriteLine($"Committed at: {entry?.CommitTimeUtc}");
    }
}

Usage Examples

Writing an Entry

public record AuditRecord(string UserId, string Action, DateTime Timestamp);

var record = new AuditRecord("user-42", "DocumentSigned", DateTime.UtcNow);

// Write to the default ledger
var transactionId = await ledgerService.WriteAsync(record);

Reading an Entry

// Read with default retry settings (10 attempts, 500ms base delay)
var entry = await ledgerService.ReadAsync<AuditRecord>(transactionId);

if (entry is not null)
{
    Console.WriteLine($"Transaction:  {entry.TransactionId}");
    Console.WriteLine($"Committed at: {entry.CommitTimeUtc}");
    Console.WriteLine($"User:         {entry.Content.UserId}");
    Console.WriteLine($"Action:       {entry.Content.Action}");
}

Working with Collections (Sub-Ledgers)

const string CollectionId = "audit-2026";

// Write to a specific collection
var transactionId = await ledgerService.WriteAsync(record, CollectionId);

// Read from the same collection
var entry = await ledgerService.ReadAsync<AuditRecord>(
    transactionId,
    collectionId: CollectionId);

Tuning Retry Behavior

Entries can briefly be in a Loading state while the ledger commits and seals them. The reader retries with linear backoff (delayMilliseconds * attempt) until the entry is available or maxRetries is exceeded.

var entry = await ledgerService.ReadAsync<AuditRecord>(
    transactionId,
    collectionId: null,
    maxRetries: 20,
    delayMilliseconds: 250,
    cancellationToken: ct);

If the ledger does not finish loading within the retry budget, a TimeoutException is thrown.

Custom Configuration Section

// Bind to a non-default section name
builder.Services.AddBlockchain(builder.Configuration, "MyApp:Ledger");

{
  "MyApp": {
    "Ledger": {
      "LedgerEndpoint": "https://my-ledger.confidential-ledger.azure.com"
    }
  }
}

Configuration

Authentication

AzureConfidentialLedgerService uses DefaultAzureCredential, which transparently tries the following credential sources in order:

1. Environment variables
2. Workload identity (Kubernetes)
3. Managed identity
4. Visual Studio / Visual Studio Code
5. Azure CLI / Azure PowerShell / Azure Developer CLI
6. Interactive browser (where enabled)

Ensure the identity running the application has the appropriate role on the ledger resource (typically Confidential Ledger Contributor).

Target Frameworks

• .NET 8.0
• .NET 9.0
• .NET 10.0

All libraries enable nullable reference types and implicit usings.

Building from Source

This solution uses the modern .slnx (XML-based) solution format.

Prerequisites

• .NET 10 SDK or later
• Visual Studio 2022 17.0+ or Visual Studio Code with C# extension

Build Commands

# Clone the repository
git clone https://github.com/nuvtools/nuvtools-blockchain.git
cd nuvtools-blockchain

# Build the solution
dotnet build NuvTools.Blockchain.slnx

# Run tests
dotnet test NuvTools.Blockchain.slnx

# Create NuGet packages
dotnet pack NuvTools.Blockchain.slnx -c Release

The solution structure:

nuvtools-blockchain/
├── src/
│   ├── NuvTools.Blockchain/             # Core abstractions
│   └── NuvTools.Blockchain.Azure/       # Azure Confidential Ledger implementation
├── tests/
│   └── NuvTools.Blockchain.Azure.Test/  # NUnit tests
└── NuvTools.Blockchain.slnx             # Solution file

Documentation

All public APIs include comprehensive XML documentation comments. IntelliSense in Visual Studio, Visual Studio Code, and Rider will display:

• Detailed descriptions of all types, methods, and properties
• Parameter information with expected values
• Return value descriptions
• Exception documentation
• Usage examples and best practices

XML documentation files are included in the NuGet packages for seamless integration.

Releasing

Publishing to nuget.org is irreversible per version, so the workflow makes it the last and smallest step.

One workflow per library. Each package has its own, so a run and an approval each concern exactly one package. The steps themselves are shared, in the reusable package-publish.yml.

1. Set the package's <Version> in its .csproj and merge it. That is the version that gets published; the workflow reads it and never computes one.
2. Run the library's workflow by hand (Actions → Blockchain Publish → Run workflow) with push checked.
3. The workflow builds the solution with -warnaserror, runs the tests, takes that package only from the build output, verifies it carries its README, licence, icon, symbols and every target framework, and then waits for approval on the nuget GitHub Environment before pushing.
4. After the push succeeds, the workflow tags the commit with the tag in the table above. The tag is a record of what is on nuget.org, never what starts a release, so it cannot exist for a version that did not get there. A run whose tag already exists stops before building: the version has been released and <Version> needs a bump.

A referenced package goes first. A package that references another of this repository as a project depends on whatever <Version> that one has in the commit. The workflow checks that version is on nuget.org and refuses to push a package whose dependency is not there yet. So:

• u before a.
• v before N.

That check knows a version exists, not what is in it: when a referenced package changes its public API, bump and publish it first, then bump and publish the packages built on it.

Versions published by hand are refused. Releases made before these workflows exist on nuget.org with no tag. Pushing one again would skip the duplicate and then tag the current commit as a release it is not, so a version that is already on nuget.org stops the run. The exception is a re-run of the same run, which is how a push that succeeded and a tag that failed gets finished.

No API key is stored. The push uses nuget.org's trusted publishing: the job presents a GitHub OIDC token, nuget.org checks it against the policy registered for this repository and answers with a key that lives for one hour. The repository needs one secret, NUGET_USER — the nuget.org profile name the policy belongs to — and the policy itself, registered under Trusted Publishing on nuget.org with the owner nuvtools, the repository nuvtools-blockchain, the workflow file and the environment nuget.

Run a library's workflow by hand with push unchecked for a dry run that stops after the verification.

License

Licensed under the MIT License.

Copyright © 2026 Nuv Tools