CryptoLib.Net 1.0.0

CryptoLib

Self-contained .NET 10 Bitcoin & Altcoins RPC library.

CryptoLib is a modernized port of BitcoinLib (© George Kimionis) to .NET 10 / C#. It is a strongly-typed JSON-RPC wrapper for Bitcoin Core and its clones, rebuilt to be fully self-contained, defensive, and async-first.

The NuGet package id is CryptoLib.Net (the id CryptoLib was already taken). The assembly and root namespace remain CryptoLib.

Install

dotnet add package CryptoLib.Net

<PackageReference Include="CryptoLib.Net" Version="1.0.0" />

Requires the .NET 10 runtime/SDK.

Highlights

• Targets net10.0. Builds clean with zero warnings under <Nullable>enable</Nullable>.
• Zero external dependencies. No NuGet packages. JSON is handled by the in-box System.Text.Json; transport by HttpClient.
• Synchronous and asynchronous APIs. Every RPC method Foo(...) has an async twin FooAsync(..., CancellationToken cancellationToken = default) that shares the same request/response pipeline.
• Custom exception hierarchy. All operational errors derive from CryptoLibException — see Exception model.
• Defensive throughout. Every public entry point validates its arguments via a central Guard helper and fails fast with precise parameter names. Required identifiers (addresses, txids, hex) are rejected when null/blank; semantically optional values (the default account "", empty comments) are accepted.
• Hardened build. Compiles with TreatWarningsAsErrors, .NET analyzers at the recommended level, and code-style enforcement — zero warnings. Library awaits use ConfigureAwait(false) to avoid sync-over-async deadlocks.
• Explicit configuration. CryptoLib is a library; it never reads ambient config files. The consuming application passes the daemon URL and RPC credentials in.
• Multi-coin. Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Dash, SmartCash, Colx, Dallar, Mogwaicoin, Sarcoin, plus the generic CryptocoinService for any other clone.
• Tested. A 102-test xUnit suite covering serialization, configuration, the exception model, defensive guards, and the transport (no live daemon required).

What changed from BitcoinLib

This is a ground-up modernization, not a recompile:

A latent serialization bug was also fixed along the way: several response DTOs exposed public fields, which System.Text.Json ignores by default — they are now properties.

Quick start

using CryptoLib.Services.Coins.Bitcoin;

// Pass connection details explicitly — no config file required.
IBitcoinService bitcoin = new BitcoinService(
    daemonUrl: "http://127.0.0.1:8332",
    rpcUsername: "MyRpcUsername",
    rpcPassword: "MyRpcPassword",
    walletPassword: "MyWalletPassword");

// Synchronous
uint height = bitcoin.GetBlockCount();
string address = bitcoin.GetNewAddress();

// Asynchronous (with cancellation)
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
decimal balance = await bitcoin.GetBalanceAsync(cancellationToken: cts.Token);
string txId = await bitcoin.SendToAddressAsync(address, 0.01m, cancellationToken: cts.Token);

Any clone can be driven through the generic service without a dedicated class:

using CryptoLib.Services.Coins.Cryptocoin;

ICryptocoinService coin = new CryptocoinService(
    "http://127.0.0.1:9999", "user", "pass", "walletpass");

coin.Parameters.CoinShortName = "FOO";      // configure at run-time

Configuration

There is no .config parsing. Supply everything through the constructor, or set it on service.Parameters after construction:

ICryptocoinService coin = new CryptocoinService();   // unconfigured
coin.Parameters.DaemonUrl   = "http://127.0.0.1:9999";
coin.Parameters.RpcUsername = "user";
coin.Parameters.RpcPassword = "pass";
coin.Parameters.RpcRequestTimeoutInSeconds = 30;

When connection details are passed to a constructor they are validated eagerly and a CoinParametersException is thrown if any required value is missing. When left for the application to fill in, the connector validates them at request time.

Exception model

All errors raised by the library derive from CryptoLib.ExceptionHandling.CryptoLibException:

CryptoLibException
├── RpcException                            (CryptoLib.ExceptionHandling.Rpc)
│   ├── RpcConnectionException              — request could not be sent / no response
│   ├── RpcRequestTimeoutException          — per-request timeout elapsed
│   ├── RpcResponseDeserializationException — response could not be parsed
│   └── RpcInternalServerErrorException     — daemon returned an error (carries RpcErrorCode)
├── RawTransactionException                 (CryptoLib.ExceptionHandling.RawTransactions)
│   ├── RawTransactionExcessiveFeeException
│   └── RawTransactionInvalidAmountException
├── CoinParametersException                 — missing/invalid connection parameters
└── GetAddressBalanceException              (CryptoLib.ExceptionHandling.RpcExtenderService)

Argument validation throws the BCL argument-exception family (ArgumentNullException, ArgumentException, ArgumentOutOfRangeException) — the convention .NET callers expect — while operational failures use the hierarchy above.

Building

dotnet build

The library itself restores no third-party packages.

Tests

CryptoLib ships with an xUnit test suite under tests/CryptoLib.Tests (102 tests):

dotnet test

Coverage includes:

• The custom exception hierarchy and RpcErrorCode propagation.
• The defensive Guard helper and the per-method argument guards (rejecting null/blank identifiers while still accepting the default account "" and empty comments).
• JSON-RPC request serialization (property order, positional params) and response/error deserialization (RpcJson options: case-insensitivity, number-from-string).
• CoinParameters — per-coin constants, explicit-config validation, default timeout, testnet URL selection.
• Request models (CreateRawTransactionRequest, SignRawTransaction*Request).
• The RpcConnector transport, exercised end-to-end without a live daemon via a fake HttpMessageHandler: success, basic-auth header, request body shape, HTTP 500 and 200-with-error → RpcInternalServerErrorException (+ code), malformed/empty JSON → RpcResponseDeserializationException, transport failure → RpcConnectionException, per-request timeout → RpcRequestTimeoutException, and caller cancellation.
• Service-level logic (GetRawMemPool verbose/non-verbose parsing, conditional parameter handling) via a fake IRpcConnector.

The library exposes two narrow internal test seams (an HttpMessageHandler-injecting connector constructor and CoinService.UseConnector) shared only with the test project through InternalsVisibleTo; the public API is unchanged.

License

MIT. This is a derivative work of BitcoinLib (© 2018 Cryptean / George Kimionis).