feat(wallets): compose signers from IPrivateKeyProviders

Closes #112.

Pushes signer composition down one layer: an IArkadeWalletSigner is now
always a CompositeArkadeWalletSigner built from one or more
IPrivateKeyProviders. Each provider answers CanProvideAsync(descriptor) and
exposes the signing operations rooted in the key it owns; the composite
dispatches each call to the first provider that claims the descriptor.

The three previous concrete signers collapse into providers behind the same
composite:

  - Bip39KeyProvider          (was HierarchicalDeterministicWalletSigner)
    claim by master fingerprint match on the descriptor's origin.

  - NsecKeyProvider           (was NSecWalletSigner)
    claim by x-only pubkey match on tr() descriptors.

  - RemoteTransportKeyProvider (was RemoteArkadeWalletSigner)
    claim by IRemoteSignerTransport.KnowsWalletAsync; passthrough proxy.

DefaultWalletProvider builds the composition automatically — adds the
matching local provider if Wallet.Secret is set, then a remote provider if
an IRemoteSignerTransport claims the wallet. Order is significant: local
providers get first refusal, remote is fallback. This is what makes hybrid
setups (e.g. local view-key paths + HWI spend path) expressible at all —
the previous binary local/remote split foreclosed them.

The interface keeps IArkadeWalletSigner unchanged for SDK consumers (the
TreeSignerSession path is unaffected); the new abstraction is added one
layer below. The three old concrete signer classes are deleted since
they're equivalent to constructing a CompositeArkadeWalletSigner with the
matching single provider — NsecKeyProvider.FromNsec is the new entry
point that mirrors the old NSecWalletSigner.FromNsec static.

The IPrivateKeyProvider shape is operation-level (Sign/SignMusig/
GenerateNonces) rather than returning a raw ECPrivKey, so a remote
provider can implement it honestly without round-tripping secret material
over the wire — the original sketch in #112 had IPrivateKeyProvider return
ECPrivKey, which would have defeated the point of remote signing.

Each local provider keeps its own per-session ConcurrentDictionary
nonce store with the same sessionId-keyed semantics established in #111.

Author: Kukks

NArk.Abstractions/Wallets/IPrivateKeyProvider.cs

@@ -0,0 +1,69 @@
+using NBitcoin;
+using NBitcoin.Scripting;
+using NBitcoin.Secp256k1;
+using NBitcoin.Secp256k1.Musig;
+
+namespace NArk.Abstractions.Wallets;
+
+/// <summary>
+/// A descriptor-scoped source of signing operations. The provider owns the private key (locally
+/// or by reference) and exposes the signer operations rooted in it — it never returns the raw
+/// key, which is what lets a remote-signing implementation honour the same contract.
+/// <para>
+/// A wallet's signer is a composition of one or more providers (see
+/// <see cref="IArkadeWalletSigner"/> implementations that compose providers). Each provider
+/// answers <see cref="CanProvideAsync"/> for the descriptors it owns; the composing signer
+/// dispatches each call to the first provider that claims the descriptor.
+/// </para>
+/// <para>
+/// The MuSig2 nonce lifecycle from <see cref="IArkadeWalletSigner"/> applies per-provider:
+/// <see cref="GenerateNoncesAsync"/> retains the secret half indexed by <c>sessionId</c>, and
+/// <see cref="SignMusigAsync"/> consumes it on use. Different providers maintain independent
+/// nonce stores — there is no cross-provider sharing.
+/// </para>
+/// </summary>
+public interface IPrivateKeyProvider
+{
+    /// <summary>
+    /// Returns <c>true</c> iff this provider owns signing material for <paramref name="descriptor"/>.
+    /// Implementations should make this cheap (fingerprint / x-only match) — it is called on
+    /// every dispatch and may run against the BIP-32 / BIP-39 derivation path of long descriptors.
+    /// </summary>
+    Task<bool> CanProvideAsync(OutputDescriptor descriptor, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets the compressed public key for <paramref name="descriptor"/>, preserving parity.
+    /// </summary>
+    Task<ECPubKey> GetPubKeyAsync(OutputDescriptor descriptor, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Produces a BIP-340 Schnorr signature over <paramref name="hash"/> using the descriptor's
+    /// private key, returning the x-only pubkey alongside the signature.
+    /// </summary>
+    Task<(ECXOnlyPubKey, SecpSchnorrSignature)> SignAsync(
+        OutputDescriptor descriptor,
+        uint256 hash,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Generates a fresh MuSig2 nonce pair for <paramref name="context"/>, retains the secret
+    /// half indexed by <paramref name="sessionId"/>, and returns the public half. See
+    /// <see cref="IArkadeWalletSigner.GenerateNonces"/> for the lifecycle contract.
+    /// </summary>
+    Task<MusigPubNonce> GenerateNoncesAsync(
+        OutputDescriptor descriptor,
+        MusigContext context,
+        string sessionId,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Produces a MuSig2 partial signature using the secret nonce generated for the same
+    /// <paramref name="sessionId"/>. The secret nonce is consumed on this call. See
+    /// <see cref="IArkadeWalletSigner.SignMusig"/> for the lifecycle contract.
+    /// </summary>
+    Task<MusigPartialSignature> SignMusigAsync(
+        OutputDescriptor descriptor,
+        MusigContext context,
+        string sessionId,
+        CancellationToken cancellationToken = default);
+}

NArk.Core/Wallet/CompositeArkadeWalletSigner.cs

@@ -0,0 +1,57 @@
+using NArk.Abstractions.Wallets;
+using NBitcoin;
+using NBitcoin.Scripting;
+using NBitcoin.Secp256k1;
+using NBitcoin.Secp256k1.Musig;
+
+namespace NArk.Core.Wallet;
+
+/// <summary>
+/// An <see cref="IArkadeWalletSigner"/> composed of one or more <see cref="IPrivateKeyProvider"/>s.
+/// For every signing call the composite resolves the first provider whose
+/// <see cref="IPrivateKeyProvider.CanProvideAsync"/> returns <c>true</c> and dispatches the
+/// operation to it. Provider order is significant — earlier providers take precedence — so
+/// callers should register the cheapest / most-local provider first and any fallbacks
+/// (e.g. remote-signer transports) last.
+/// </summary>
+public class CompositeArkadeWalletSigner : IArkadeWalletSigner
+{
+    private readonly IReadOnlyList<IPrivateKeyProvider> _providers;
+
+    public CompositeArkadeWalletSigner(IEnumerable<IPrivateKeyProvider> providers)
+    {
+        _providers = (providers ?? throw new ArgumentNullException(nameof(providers))).ToArray();
+        if (_providers.Count == 0)
+            throw new ArgumentException("At least one provider is required.", nameof(providers));
+    }
+
+    public CompositeArkadeWalletSigner(params IPrivateKeyProvider[] providers)
+        : this((IEnumerable<IPrivateKeyProvider>)providers)
+    {
+    }
+
+    public async Task<ECPubKey> GetPubKey(OutputDescriptor descriptor, CancellationToken cancellationToken = default)
+        => await (await ResolveAsync(descriptor, cancellationToken)).GetPubKeyAsync(descriptor, cancellationToken);
+
+    public async Task<(ECXOnlyPubKey, SecpSchnorrSignature)> Sign(OutputDescriptor descriptor, uint256 hash, CancellationToken cancellationToken = default)
+        => await (await ResolveAsync(descriptor, cancellationToken)).SignAsync(descriptor, hash, cancellationToken);
+
+    public async Task<MusigPubNonce> GenerateNonces(OutputDescriptor descriptor, MusigContext context, string sessionId, CancellationToken cancellationToken = default)
+        => await (await ResolveAsync(descriptor, cancellationToken)).GenerateNoncesAsync(descriptor, context, sessionId, cancellationToken);
+
+    public async Task<MusigPartialSignature> SignMusig(OutputDescriptor descriptor, MusigContext context, string sessionId, CancellationToken cancellationToken = default)
+        => await (await ResolveAsync(descriptor, cancellationToken)).SignMusigAsync(descriptor, context, sessionId, cancellationToken);
+
+    private async Task<IPrivateKeyProvider> ResolveAsync(OutputDescriptor descriptor, CancellationToken cancellationToken)
+    {
+        foreach (var provider in _providers)
+        {
+            if (await provider.CanProvideAsync(descriptor, cancellationToken).ConfigureAwait(false))
+                return provider;
+        }
+
+        throw new InvalidOperationException(
+            $"No registered IPrivateKeyProvider claims descriptor '{descriptor}'. " +
+            "Either the wallet is watch-only for this path, or a provider is missing from the composition.");
+    }
+}

NArk.Core/Wallet/DefaultWalletProvider.cs

@@ -5,6 +5,7 @@
 using NArk.Abstractions.Safety;
 using NArk.Abstractions.Wallets;
 using NArk.Core.Transport;
+using NArk.Core.Wallet.PrivateKeyProviders;
 using NBitcoin;
 
 namespace NArk.Core.Wallet;
@@ -30,9 +31,9 @@ public class DefaultWalletProvider(
     : IWalletProvider
 {
     // Signer instances must be reused across calls so the MuSig2 secret-nonce store on each
-    // signer (populated by GenerateNonces, consumed by SignMusig — see IArkadeWalletSigner)
-    // survives between the two calls. The cache key includes the wallet's secret so a wallet
-    // re-imported with a different mnemonic gets a fresh signer.
+    // provider (populated by GenerateNonces, consumed by SignMusig — see IArkadeWalletSigner)
+    // survives between the two calls. The cache key includes a hash of the wallet's secret so
+    // a wallet re-imported with different signing material gets a fresh signer.
     private readonly ConcurrentDictionary<string, IArkadeWalletSigner> _signerCache = new();
 
     public async Task<IArkadeWalletSigner?> GetSignerAsync(string identifier, CancellationToken cancellationToken = default)
@@ -46,30 +47,34 @@ public class DefaultWalletProvider(
             logger?.LogDebug("GetSignerAsync: identifier={Identifier}, walletId={WalletId}, walletType={WalletType}, hasSecret={HasSecret}",
                 identifier, wallet.Id, wallet.WalletType, !string.IsNullOrEmpty(wallet.Secret));
 
-            // Local signing material present → produce a local signer of the right shape.
+            var providers = new List<IPrivateKeyProvider>();
+
+            // Local signing material present → add the matching local provider.
             if (!string.IsNullOrEmpty(wallet.Secret))
             {
-                var cacheKey = $"local:{wallet.Id}:{wallet.Secret.GetHashCode():x}";
-                return _signerCache.GetOrAdd(cacheKey, _ => wallet.WalletType switch
+                providers.Add(wallet.WalletType switch
                 {
-                    WalletType.HD => new HierarchicalDeterministicWalletSigner(wallet),
-                    WalletType.SingleKey => NSecWalletSigner.FromNsec(wallet.Secret, logger),
+                    WalletType.HD => new Bip39KeyProvider(wallet.Secret),
+                    WalletType.SingleKey => NsecKeyProvider.FromNsec(wallet.Secret, logger),
                     _ => throw new ArgumentOutOfRangeException(nameof(wallet.WalletType))
                 });
             }
 
-            // No local secret → ask the remote-signer transport (if any) whether it can sign for
-            // this wallet. The transport is the source of truth for "remote vs watch-only" —
-            // no flag on ArkWalletInfo encodes it.
+            // Remote-signer transport claims this wallet → add a remote provider as a fallback
+            // for descriptors no local provider covers. Order is significant: local providers
+            // get first refusal.
             if (remoteSignerTransport is not null
                 && await remoteSignerTransport.KnowsWalletAsync(wallet.Id, cancellationToken).ConfigureAwait(false))
             {
-                return _signerCache.GetOrAdd($"remote:{wallet.Id}",
-                    _ => new RemoteArkadeWalletSigner(wallet.Id, remoteSignerTransport));
+                providers.Add(new RemoteTransportKeyProvider(remoteSignerTransport, wallet.Id));
             }
 
-            // No local key, no remote signer claims it → watch-only.
-            return null;
+            // No provider can sign for this wallet → watch-only.
+            if (providers.Count == 0)
+                return null;
+
+            var cacheKey = $"{wallet.Id}:{wallet.Secret?.GetHashCode():x}:{remoteSignerTransport?.GetHashCode():x}";
+            return _signerCache.GetOrAdd(cacheKey, _ => new CompositeArkadeWalletSigner(providers));
         }
         catch (KeyNotFoundException)
         {