Allow for extensible BitcoinNetwork (#57)

* allow for extensible `BitcoinNetwork`

---------

Signed-off-by: Níckolas Goline <nickolas.goline+github@gmail.com>

Author: nGoline

src/NLightning.Domain/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## v1.1.0
+
+This version introduces the ability to register and manage custom Bitcoin-like networks at runtime, enhancing the
+flexibility and extensibility of the `BitcoinNetwork` class. This allows developers to define and work with networks
+beyond the standard `mainnet`, `testnet`, and `regtest`, making the library more adaptable to various use cases and
+testing scenarios.
+
+### Added
+
+- **Extensible Custom Bitcoin Networks:**  
+  `BitcoinNetwork` now supports registration and management of custom network names and corresponding `ChainHash` values
+  at runtime.
+    - Implementers can register any custom Bitcoin-like network and have it fully supported throughout the domain layer.
+    - Provides methods to register and unregister custom networks and retrieve their `ChainHash` from name, with all
+      conversions and equality logic preserved.
+    - Built-in networks (`mainnet`, `testnet`, `regtest`) remain unchanged.
+
 ## v1.0.0
 
 This version's focus has been on enhancing Bitcoin integration, refining channel management, standardizing protocol

src/NLightning.Domain/NLightning.Domain.csproj

@@ -5,7 +5,7 @@
     <LangVersion>latest</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>1.0.0</Version>
+    <Version>1.1.0</Version>
     <Configurations>Debug;Release;Debug.Native;Debug.Wasm;Release.Native;Release.Wasm</Configurations>
     <Platforms>AnyCPU</Platforms>
   </PropertyGroup>
@@ -16,8 +16,8 @@
     <Copyright>Copyright © Níckolas Goline 2024-2025</Copyright>
     <RepositoryUrl>https://github.com/ipms-io/nlightning</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
-    <AssemblyVersion>1.0.0</AssemblyVersion>
-    <FileVersion>1.0.0</FileVersion>
+    <AssemblyVersion>1.1.0</AssemblyVersion>
+    <FileVersion>1.1.0</FileVersion>
     <NeutralLanguage>en</NeutralLanguage>
     <Icon>logo.png</Icon>
     <PackageTags>lightning-network,bitcoin,crypto,infrastructure,dotnet,cryptography,cross-platform,libsodium,blazor,webassembly,aot</PackageTags>
@@ -26,7 +26,7 @@
     <PackageLicenseFile>LICENSE</PackageLicenseFile>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageId>NLightning.Domain</PackageId>
-    <PackageReleaseNotes>This version's focus has been on enhancing Bitcoin integration, refining channel management, standardizing protocol message handling, and improving core domain primitives. These changes aim to solidify the domain logic and provide a richer, more robust foundation for building Lightning Network features.</PackageReleaseNotes>
+    <PackageReleaseNotes>This version introduces the ability to register and manage custom Bitcoin-like networks at runtime, enhancing the flexibility and extensibility of the `BitcoinNetwork` class. This allows developers to define and work with networks beyond the standard `mainnet`, `testnet`, and `regtest`, making the library more adaptable to various use cases and testing scenarios.</PackageReleaseNotes>
   </PropertyGroup>
 
   <PropertyGroup Condition="$(Configuration.Contains('Debug'))">

src/NLightning.Domain/Protocol/ValueObjects/BitcoinNetwork.cs

@@ -4,6 +4,8 @@ namespace NLightning.Domain.Protocol.ValueObjects;
 
 public readonly struct BitcoinNetwork : IEquatable<BitcoinNetwork>
 {
+    private static Dictionary<string, ChainHash> CustomChainHashes { get; } = new();
+
     public static readonly BitcoinNetwork Mainnet = new(NetworkConstants.Mainnet);
     public static readonly BitcoinNetwork Testnet = new(NetworkConstants.Testnet);
     public static readonly BitcoinNetwork Regtest = new(NetworkConstants.Regtest);
@@ -25,19 +27,49 @@ public ChainHash ChainHash
                 NetworkConstants.Mainnet => ChainConstants.Main,
                 NetworkConstants.Testnet => ChainConstants.Testnet,
                 NetworkConstants.Regtest => ChainConstants.Regtest,
-                _ => throw new Exception("Chain not supported.")
+                _ => CustomChainHashes.TryGetValue(Name.ToLowerInvariant(), out var hash)
+                         ? hash
+                         : throw new InvalidOperationException($"Chain not supported: {Name}")
             };
         }
     }
 
     public override string ToString() => Name;
 
+    /// <summary>
+    /// Register a custom network mapping
+    /// </summary>
+    public void Register(string name, ChainHash chainHash)
+    {
+        if (string.IsNullOrWhiteSpace(name)) throw new ArgumentNullException(nameof(name));
+
+        if (!CustomChainHashes.TryAdd(name.ToLowerInvariant(), chainHash))
+        {
+            if (CustomChainHashes.ContainsKey(name.ToLowerInvariant()))
+                throw new InvalidOperationException($"Chain hash already registered: {name}");
+
+            throw new InvalidOperationException($"Failed to register chain hash: {name}");
+        }
+    }
+
+    /// <summary>
+    /// Unregister a custom network mapping
+    /// </summary>
+    public static void Unregister(string name)
+    {
+        if (string.IsNullOrWhiteSpace(name)) throw new ArgumentNullException(nameof(name));
+        CustomChainHashes.Remove(name.ToLowerInvariant());
+    }
+
     #region Implicit Conversions
+
     public static implicit operator string(BitcoinNetwork bitcoinNetwork) => bitcoinNetwork.Name.ToLowerInvariant();
     public static implicit operator BitcoinNetwork(string value) => new(value.ToLowerInvariant());
+
     #endregion
 
     #region Equality
+
     public override bool Equals(object? obj)
     {
         return obj is BitcoinNetwork network && ChainHash.Equals(network.ChainHash);
@@ -62,5 +94,6 @@ public override int GetHashCode()
     {
         return !(left == right);
     }
+
     #endregion
 }

test/NLightning.Domain.Tests/ValueObjects/BitcoinNetworkTests.cs

@@ -1,8 +1,7 @@
-using NLightning.Domain.Protocol.ValueObjects;
-
 namespace NLightning.Domain.Tests.ValueObjects;
 
 using Domain.Protocol.Constants;
+using Domain.Protocol.ValueObjects;
 
 public class BitcoinNetworkTests
 {
@@ -60,7 +59,7 @@ public void Given_NetworkInstance_When_ChainHashAccessed_Then_ReturnsCorrectHash
             NetworkConstants.Mainnet => ChainConstants.Main,
             NetworkConstants.Testnet => ChainConstants.Testnet,
             NetworkConstants.Regtest => ChainConstants.Regtest,
-            _ => throw new Exception("Chain not supported.")
+            _ => throw new InvalidOperationException("Chain not supported.")
         };
 
         // When
@@ -77,7 +76,7 @@ public void Given_UnsupportedNetworkName_When_ChainHashAccessed_Then_ThrowsExcep
         var network = new BitcoinNetwork("unsupported");
 
         // When & Then
-        Assert.Throws<Exception>(() => network.ChainHash);
+        Assert.Throws<InvalidOperationException>(() => network.ChainHash);
     }
 
     [Fact]
@@ -120,4 +119,132 @@ public void Given_TwoDifferentNetworkInstances_When_Compared_Then_AreNotEqual()
         Assert.False(network1.Equals(network2));
         Assert.False(network2.Equals(network1));
     }
+
+    [Fact]
+    public void Builtin_Networks_ChainHash_Matches()
+    {
+        Assert.Equal(ChainConstants.Main, BitcoinNetwork.Mainnet.ChainHash);
+        Assert.Equal(ChainConstants.Testnet, BitcoinNetwork.Testnet.ChainHash);
+        Assert.Equal(ChainConstants.Regtest, BitcoinNetwork.Regtest.ChainHash);
+    }
+
+    [Fact]
+    public void Unregistered_CustomNetwork_Throws()
+    {
+        var net = new BitcoinNetwork("mycustomnet");
+        Assert.Throws<InvalidOperationException>(() =>
+        {
+            var _ = net.ChainHash;
+        });
+    }
+
+    [Fact]
+    public void RegisterCustomNetwork_ReturnsExpectedChainHash()
+    {
+        var customChainHash = DummyChainHash(0x42);
+        // Register
+        var tmpNet = new BitcoinNetwork("mycustomnet");
+        tmpNet.Register("mycustomnet", customChainHash);
+
+        var net = new BitcoinNetwork("mycustomnet");
+        Assert.Equal(customChainHash, net.ChainHash);
+    }
+
+    [Fact]
+    public void Register_IsCaseInsensitive()
+    {
+        var customChainHash = DummyChainHash(0xDD);
+        var lower = "lowercase";
+        var upper = "LOWERCASE";
+
+        var tmpNet = new BitcoinNetwork(lower);
+        tmpNet.Register(upper, customChainHash);
+
+        var net1 = new BitcoinNetwork(lower);
+        var net2 = new BitcoinNetwork(upper);
+        Assert.Equal(customChainHash, net1.ChainHash);
+        Assert.Equal(customChainHash, net2.ChainHash);
+    }
+
+    [Fact]
+    public void Unregister_RemovesChainHash()
+    {
+        var customChainHash = DummyChainHash(0xAB);
+        var name = "toRemove";
+        var net = new BitcoinNetwork(name);
+        net.Register(name, customChainHash);
+
+        var useNet = new BitcoinNetwork(name);
+        Assert.Equal(customChainHash, useNet.ChainHash);
+
+        BitcoinNetwork.Unregister(name);
+
+        var afterRemove = new BitcoinNetwork(name);
+        Assert.Throws<InvalidOperationException>(() =>
+        {
+            var _ = afterRemove.ChainHash;
+        });
+    }
+
+    [Fact]
+    public void ToString_And_Conversions_Work_For_Custom()
+    {
+        var customChainHash = DummyChainHash(0x5A);
+        var name = "foo_bar";
+        var bnet = new BitcoinNetwork(name);
+        bnet.Register(name, customChainHash);
+
+        Assert.Equal(name, bnet.ToString());
+
+        string str = bnet;
+        Assert.Equal(name.ToLowerInvariant(), str);
+
+        BitcoinNetwork net2 = name;
+        Assert.Equal(name, net2.Name);
+        Assert.Equal(customChainHash, net2.ChainHash);
+    }
+
+    [Fact]
+    public void Register_Throws_For_AlreadyExistingCustomNetwork()
+    {
+        var chainHash1 = DummyChainHash(0x13);
+        var chainHash2 = DummyChainHash(0x53);
+        var name = "networkdup";
+
+        // Ensure clean slate
+        BitcoinNetwork.Unregister(name);
+
+        var net = new BitcoinNetwork(name);
+        net.Register(name, chainHash1);
+
+        // Attempting to add again (any value) must throw
+        var ex = Assert.Throws<InvalidOperationException>(() => net.Register(name, chainHash2));
+        Assert.Contains("already registered", ex.Message, StringComparison.OrdinalIgnoreCase);
+
+        // Clean up for other tests
+        BitcoinNetwork.Unregister(name);
+    }
+
+    [Fact]
+    public void Register_Throws_For_Null_Or_Whitespace_Name()
+    {
+        var net = new BitcoinNetwork("foo");
+        var ch = DummyChainHash(0x77);
+
+        Assert.Throws<ArgumentNullException>(() => net.Register(null, ch));
+        Assert.Throws<ArgumentNullException>(() => net.Register("", ch));
+        Assert.Throws<ArgumentNullException>(() => net.Register("   ", ch));
+    }
+
+    private static ChainHash DummyChainHash(byte fill)
+    {
+        // Create a 32-byte chainhash with a pattern to differentiate
+        return new ChainHash(new[]
+        {
+            fill, fill, fill, fill, fill, fill, fill, fill, fill, fill, fill, fill, fill, fill,
+            fill, fill,
+            fill, fill, fill, fill, fill, fill, fill, fill, fill, fill, fill, fill, fill, fill,
+            fill, fill
+        });
+    }
 }