NSpark 0.1.0-alpha.7

NSpark

NSpark is a first-class .NET SDK for the Spark Lightning Network protocol. Send and receive Bitcoin over Lightning — BOLT11 invoices, FROST threshold signing, deposits, withdrawals, Spark-to-Spark transfers — from any modern .NET application with a clean, DI-friendly API.

dotnet add package NSpark

Why NSpark

• Real Lightning, not a wrapper. Talks directly to Spark Signing Operators over gRPC and to your SSP over GraphQL — no daemon to babysit, no node to operate.
• Modern .NET. net8.0/net9.0/net10.0, nullable reference types, async-first, IHttpClientFactory, IOptions<T>, ILogger<T>, OpenTelemetry. Plays nicely with ASP.NET Core, the generic host, and minimal APIs.
• Cryptographically sound. BIP-39/BIP-32 derivation via NBitcoin, FROST threshold signing via the audited spark_frost Rust library through UniFFI bindings, ECIES share encryption, tagged-hash domain separation, BOLT11 description-hash support for NIP-57 zaps.
• Observability by default. Structured logging with documented EventIds, an ActivitySource named "NSpark", and a Meter with counters/histograms — all of it inactive unless you subscribe.
• Resilient. Pluggable Polly v8 retry/backoff/breaker on transient gRPC failures, bounded auth token cache with TTL eviction.
• Open source. MIT-licensed, single-package distribution with reproducible builds and SBOM in every release.

Quickstart

using NSpark;

var options = Microsoft.Extensions.Options.Options.Create(new SparkOptions
{
    Network = SparkNetwork.Mainnet,
});

using var http = new HttpClient();
await using var spark = new SparkConnection(options, http);

// Use a real mnemonic in production — derive once and store securely.
const string mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
var wallet = spark.CreateWallet(mnemonic);

// Receive
var invoice = await wallet.CreateLightningInvoiceAsync(amountSats: 21_000, memo: "hello world");
Console.WriteLine(invoice.PaymentRequest);

// Send
await wallet.PayLightningInvoiceAsync("lnbc...");

// Balance
var balance = await wallet.GetBalanceAsync();
Console.WriteLine($"Available: {balance.SatsBalance.Available} sats");
Console.WriteLine($"Owned:     {balance.SatsBalance.Owned} sats  (incl. locked in-flight)");
Console.WriteLine($"Incoming:  {balance.SatsBalance.Incoming} sats (pending claim)");

ASP.NET Core / generic host

// Program.cs
builder.Services.AddSpark(options =>
{
    options.Network = SparkNetwork.Mainnet;
});

// Optional: background lifecycle service for token refresh hooks
builder.Services.AddHostedService<NSpark.Hosting.SparkHostedService>();

// In any controller / service
public class InvoicesController(SparkConnection spark) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Create(long sats, string memo, CancellationToken ct)
    {
        var wallet = spark.CreateWallet(Environment.GetEnvironmentVariable("WALLET_MNEMONIC")!);
        var invoice = await wallet.CreateLightningInvoiceAsync(sats, memo, ct: ct);
        return Ok(invoice);
    }
}

Supported platforms

NSpark ships a native FROST signing library (libspark_frost) for the following runtime identifiers:

SHA-256 hashes for every shipped binary are published in each GitHub release and packed at runtimes/SHA256SUMS.txt inside the NuGet.

Documentation

Working examples live under samples/:

• samples/QuickStart — console app: mnemonic → wallet → invoice → balance
• samples/AspNetCore — minimal-API receiver wired with OpenTelemetry (see roadmap)
• samples/CustomSigner — implementing ISparkSigner against an HSM (see roadmap)

Status & roadmap

NSpark targets a 1.0.0 release on NuGet. Until then, versions are published as pre-releases under the same package id. See CHANGELOG.md.

Security

This SDK handles Bitcoin keys. Read SECURITY.md before deploying in production, and review docs/trust-model.md for the threat model — including the default Signing Operators and SSP that NSpark trusts. To report a vulnerability privately, see the disclosure process in SECURITY.md.

Contributing

Issues, discussions, and pull requests are welcome. See CONTRIBUTING.md for build setup, coding conventions, and the PR checklist. Please read CODE_OF_CONDUCT.md before participating.

License

NSpark is licensed under the MIT License. Third-party dependencies and their licenses are enumerated in THIRD_PARTY_NOTICES.md. © OrkLabs S.A.S. and NSpark contributors.