ResQ .NET SDK

A collection of .NET 9 client libraries for interacting with the ResQ autonomous disaster-response platform.

Overview

The ResQ .NET SDK provides typed client libraries, domain models, and protocol bindings for the ResQ platform. It targets .NET 9 and facilitates high-performance communication with autonomous drone fleets, blockchain-based telemetry anchoring, and disaster simulation environments.

Features

• Neo N3 Blockchain Support: Integrated auditing and data anchoring for mission-critical telemetry.
• SITL Simulation Harness: Native tools to run Software-in-the-Loop simulations with virtual drone fleets.
• Protobuf-Native: High-performance binary serialization using standardized .proto definitions.
• Typed Service Clients: Robust wrappers for the ResQ Infrastructure and Coordination (HCE) APIs.
• Cross-Platform: Built for .NET 9 with Nix-based development environment consistency.

Architecture

The SDK is organized into modular libraries. The ResQ.Clients and ResQ.Blockchain layers consume ResQ.Core models, while ResQ.Protocols provides the shared gRPC contract definitions.

C4Context
title ResQ Platform Ecosystem & SDK Dependencies
Person(operator, "Operator")
System_Boundary(resq_sdk, "ResQ .NET SDK") {
Component(clients, "ResQ.Clients", "HTTP/REST", "Service communication")
Component(blockchain, "ResQ.Blockchain", "Neo N3", "Audit trail anchoring")
Component(storage, "ResQ.Storage", "IPFS/Pinata", "Evidence persistence")
}
System_Boundary(platform, "ResQ Infrastructure") {
System(neo, "Neo N3 Ledger", "Immutable records")
System(api, "Infrastructure API", "Backend services")
}
Rel(operator, clients, "Uses")
Rel(clients, api, "REST/JSON")
Rel(blockchain, neo, "Transaction submission")
Rel(storage, api, "Pinning")

Loading

flowchart TD
App[Consumer Application] --> Clients[ResQ.Clients]
App --> Storage[ResQ.Storage]
App --> Sim[ResQ.Simulation]
Clients --> Core[ResQ.Core]
Clients --> Protocols[ResQ.Protocols]
Protocols --> Protos[Protobuf Definitions]
subgraph CoreLayer
Core
Protocols
end

Loading

Installation

Add the necessary packages to your .NET 9 project via CLI:

# Core domain models and interfaces
dotnet add package ResQ.Core
# Typed HTTP clients
dotnet add package ResQ.Clients
# Blockchain integration
dotnet add package ResQ.Blockchain

Quick Start

Initialize a client and fetch fleet telemetry:

usingResQ.Clients;// Initialize the API clientvarclient=newInfrastructureApiClient("https://api.resq.software");// Perform a requestvartelemetry=awaitclient.GetTelemetryAsync("drone-01");Console.WriteLine($"Current Battery: {telemetry.BatteryLevel}%");

Usage

Blockchain Anchoring

Secure mission data on the Neo N3 ledger:

usingResQ.Blockchain;varneo=newNeoClient(newNeoClientOptions{RpcUrl="http://localhost:10332"});vartx=awaitneo.AnchorMissionAsync(missionId:"mission-99",dataHash:"ipfs://...");

Simulation Testing

Use the SITL harness to validate flight paths without physical hardware:

usingResQ.Simulation;vardrone=newVirtualDrone("drone-id");awaitdrone.ConnectAsync();awaitdrone.ExecuteFlightPathAsync(waypoints);

Configuration

Environment Variable	Description	Default
RESQ_API_URL	Base endpoint for ResQ services	https://api.resq.software
NEO_RPC_URL	Neo N3 RPC endpoint	http://localhost:10332
NEO_MOCK_MODE	Toggle mock blockchain for local dev	false

The SDK supports configuration via environment variables and standard .NET configuration providers (e.g., appsettings.json). For libraries, settings should be injected via IOptions<T> pattern.

For example, to configure the InfrastructureApiClient via appsettings.json:

{
"ResQ": {
"InfrastructureApiUrl": "https://your-api.example.com",
"Resilience": {
"MaxRetries": 5,
"RequestTimeoutSec": 15
}
}
}

Then, in your application's Startup.cs or equivalent:

services.Configure<PinataOptions>(Configuration.GetSection("PinataOptions"));// Example for Pinata// For InfrastructureApiClient, you would typically configure the HttpClient registrationservices.AddHttpClient<InfrastructureApiClient>(c =>{// Configure base address, headers, etc. from configurationc.BaseAddress=newUri(Configuration["ResQ:InfrastructureApiUrl"]??"https://api.resq.software");// Resilience settings could be applied here using Polly if not handled internally}).ConfigurePrimaryHttpMessageHandler(()=>newHttpClientHandler())// Optional: customize handler.AddPolicyHandler(PollyPolicies.GetCircuitBreakerPolicy());// Example of adding Polly policies

API Reference

• ResQ.Core: Contains shared domain entities (Location, Telemetry, IncidentType) and service interfaces.
• ResQ.Protocols: Houses auto-generated gRPC contracts and protocol-specific extension methods.
• ResQ.Clients: Provides high-level abstractions for infrastructure APIs, including built-in Polly-based retry/circuit-breaker logic.
• ResQ.Storage: Implements IPFS storage adapters using Pinata.
• Error Handling & Retries: Clients utilize Polly.ResiliencePipeline to handle 429 (Rate Limit), 408 (Timeout), and 5xx (Server) errors with exponential backoff and circuit-breaking strategies.

Testing

The SDK includes comprehensive unit and integration tests for its various components. You can run these tests using the dotnet test command.

dotnet test -c Release

The ResQ.Clients.Tests project uses MockHttpMessageHandler to simulate HTTP responses, allowing for thorough testing of resilience policies like retries and circuit breakers without actual network calls.

The ResQ.Blockchain project provides MockNeoClient for testing blockchain interactions in memory.

To facilitate testing of your own code that uses the ResQ SDK, you can leverage these mock implementations:

1. Dependency Injection: Register mock implementations in your test setup.

   // In your test setupservices.AddSingleton<INeoClient,MockNeoClient>();services.AddSingleton<IStorageClient,MockPinataClient>();// Assuming a mock for storageservices.AddSingleton<CoordinationHceClient>();// Use DI for clients too

2. Mocking HTTP Handlers: For clients like InfrastructureApiClient and CoordinationHceClient, inject a MockHttpMessageHandler to control HTTP responses.

   varmockHandler=newMockHttpMessageHandler();mockHandler.QueueJsonResponse(System.Net.HttpStatusCode.OK,"{\"Token\": \"fake-jwt-token\"}");varclient=newCoordinationHceClient("http://localhost",mockHandler);

This allows you to isolate your code's logic from external dependencies and verify its behavior under various conditions, including error scenarios.

Shared Protobuf Source

The checked-in protos/ directory is a synced local cache of the canonical schemas published from buf.build/resq-software/resq-proto.

When updating shared contracts:

bash scripts/sync-protos.sh && dotnet build ResQ.Protocols/ResQ.Protocols.csproj

Development

Prerequisites

• .NET 9.0 SDK
• Docker (for packaging and integration tests)
• Nix (optional, for development environment parity)

Setup

git clone https://github.com/resq-software/dotnet-sdk.git
./scripts/setup.sh
dotnet build

Versioning and Compatibility Policy

The ResQ SDK follows Semantic Versioning (SemVer).

• Major: Breaking API changes.
• Minor: New features, non-breaking.
• Patch: Bug fixes and security patches.

Contributing

We strictly follow the Conventional Commits specification.

1. Fork the repository.
2. Branch your changes: feat/my-feature or fix/my-bug.
3. Commit using clear, imperative messages.
4. Push and open a Pull Request.

All changes must pass existing CI workflows and include tests for new functionality.

License

Copyright 2026 ResQ. Licensed under the Apache License, Version 2.0.