refactor(swaps): bind preimage scheme to (tag || descriptor || index)

Kukks · Kukks · commit d643a3b79de0 · 2026-05-30T18:41:25.000+02:00
Two small but meaningful changes to the v1 derivation message:

  - Descriptor folded into the signed message in addition to the tag.
    Domain separation now defends against accidental signature reuse
    even within this codebase (a future feature that signs a
    descriptor-derived hash for some unrelated proof can't repurpose
    the same signature). The descriptor is also what would scope the
    preimage if the tag ever got reused outside our control.

  - u32 little-endian index baked into the message (always 0 today).
    Forward-compatibility for multi-preimage-per-descriptor flows
    without a scheme bump: when a caller wants two preimages from one
    descriptor, they pass index=1 and recovery iterates 0..N.

So the v1 scheme is now:

  message  = SHA-256(  "NArk-Boltz-Preimage-v1"
                    || descriptor.ToString()
                    || u32_le(index) )
  sig      = BIP-340-Schnorr(descriptor_key, message, aux_rand=null)
  preimage = SHA-256(sig)

DerivePreimageAsync gains an explicit `uint index` parameter; all four
call sites (three Initiate*Swap + the RestoreSwaps recovery branch)
pass index=0. The restore path leaves a comment noting that a future
multi-preimage variant should iterate index=0..MAX here.

Also documents the determinism requirement on IRemoteSignerTransport.SignAsync:
implementations MUST sign with aux_rand=null for remote-signed wallets
to recover outstanding preimages from seed. The contract was implicit
before — implementations that randomise (hardware wallet side-channel
hardening) would silently break recovery; now it's explicit in XML doc.

docs/articles/swaps.md updated to describe the bundled message
construction and the remote-signer caveat.
diff --git a/NArk.Abstractions/Wallets/IRemoteSignerTransport.cs b/NArk.Abstractions/Wallets/IRemoteSignerTransport.cs
@@ -78,6 +78,16 @@ Task<MusigPartialSignature> SignMusigAsync(
     /// the descriptor's private key, returning the x-only pubkey alongside the
     /// signature.
     /// </summary>
+    /// <remarks>
+    /// Implementations <b>SHOULD</b> sign with <c>aux_rand</c> set to null (or all-zero) so the
+    /// signature is deterministic per <c>(key, hash)</c>. The SDK relies on this for the
+    /// swap-preimage recovery scheme in <c>SwapsManagementService.DerivePreimageAsync</c>:
+    /// same descriptor + same wallet must produce the same signature, otherwise a restored
+    /// wallet that rediscovers an outstanding swap will re-derive a different preimage and
+    /// fail to claim the VHTLC. Implementations that randomise <c>aux_rand</c> (e.g. for
+    /// side-channel resistance on a hardware signer) break that contract, and remote-signed
+    /// wallets on such transports will not recover outstanding swap preimages from seed.
+    /// </remarks>
     /// <param name="walletId">The wallet whose key signs.</param>
     /// <param name="descriptor">The descriptor identifying the signing key.</param>
     /// <param name="hash">The 32-byte hash to sign.</param>
diff --git a/NArk.Swaps/Services/SwapsManagementService.cs b/NArk.Swaps/Services/SwapsManagementService.cs
@@ -103,21 +103,42 @@ public ISwapProvider ResolveProvider(SwapRoute route, string? preferredProviderI
     public IReadOnlyList<ISwapProvider> Providers => _providers;
 
     // BIP-340 sign+hash gives us a deterministic preimage rooted in the wallet's secret
-    // material without leaking the key (signatures reveal nothing about the key). Same
-    // descriptor + same wallet → same signature → same preimage, so a restored wallet that
-    // rediscovers an outstanding swap via Boltz /v2/swap/restore can re-derive the preimage
-    // and claim the VHTLC. Watch-only and remote-signer-less wallets fall through to a
-    // random preimage (recovery gap, but the swap still works at create time).
-    private static readonly uint256 PreimageSignTagHash =
-        new uint256(SHA256.HashData(Encoding.UTF8.GetBytes("NArk-Boltz-Preimage-v1")));
+    // material without leaking the key (signatures reveal nothing about the key). The signed
+    // message bundles:
+    //   tag:        domain-separates this signature from any other use of the signing key
+    //               (versioned so a future scheme bump can coexist on recovery)
+    //   descriptor: scopes the preimage to the specific swap descriptor
+    //   index:      lets the caller derive multiple preimages from the same descriptor;
+    //               always 0 today, but baked into v1 so recovery iteration is forward-
+    //               compatible without a scheme bump
+    // Same (wallet, descriptor, index) → same signature → same preimage, so a restored
+    // wallet that rediscovers an outstanding swap via Boltz /v2/swap/restore can re-derive
+    // the preimage and claim the VHTLC. Watch-only and remote-signer-less wallets fall
+    // through to a random preimage.
+    //
+    // Local signing sources pass aux_rand=null to BIP-340, so signatures are deterministic.
+    // Remote-signer transports MUST honour the same convention or the preimage will rotate
+    // per call and recovery will silently fail — see IRemoteSignerTransport.SignAsync.
+    private const string PreimageTag = "NArk-Boltz-Preimage-v1";
+    private static readonly byte[] PreimageTagBytes = Encoding.UTF8.GetBytes(PreimageTag);
 
     private async Task<byte[]> DerivePreimageAsync(
-        string walletId, OutputDescriptor descriptor, CancellationToken cancellationToken)
+        string walletId, OutputDescriptor descriptor, uint index, CancellationToken cancellationToken)
     {
         var signer = await _walletProvider.GetSignerAsync(walletId, cancellationToken);
         if (signer is null)
             return RandomUtils.GetBytes(32); // watch-only — no entropy floor to draw from
-        var (_, sig) = await signer.Sign(descriptor, PreimageSignTagHash, cancellationToken);
+
+        var descriptorBytes = Encoding.UTF8.GetBytes(descriptor.ToString());
+        var indexBytes = BitConverter.GetBytes(index);
+        if (!BitConverter.IsLittleEndian) Array.Reverse(indexBytes); // canonical u32 LE
+        var message = new byte[PreimageTagBytes.Length + descriptorBytes.Length + indexBytes.Length];
+        Buffer.BlockCopy(PreimageTagBytes, 0, message, 0, PreimageTagBytes.Length);
+        Buffer.BlockCopy(descriptorBytes, 0, message, PreimageTagBytes.Length, descriptorBytes.Length);
+        Buffer.BlockCopy(indexBytes, 0, message, PreimageTagBytes.Length + descriptorBytes.Length, indexBytes.Length);
+        var messageHash = new uint256(SHA256.HashData(message));
+
+        var (_, sig) = await signer.Sign(descriptor, messageHash, cancellationToken);
         return SHA256.HashData(sig.ToBytes());
     }
 
@@ -294,7 +315,7 @@ public async Task<string> InitiateReverseSwap(string walletId, CreateInvoicePara
             walletId, invoiceParams.Amount);
         var addressProvider = await _walletProvider.GetAddressProviderAsync(walletId, cancellationToken);
         var destinationDescriptor = await addressProvider!.GetNextSigningDescriptor(cancellationToken);
-        var preimage = await DerivePreimageAsync(walletId, destinationDescriptor, cancellationToken);
+        var preimage = await DerivePreimageAsync(walletId, destinationDescriptor, index: 0, cancellationToken);
         var revSwap =
             await boltz.BoltzService.CreateReverseSwap(
                 invoiceParams,
@@ -349,7 +370,7 @@ await _swapsStorage.SaveSwap(
 
         var addressProvider = await _walletProvider.GetAddressProviderAsync(walletId, cancellationToken);
         var claimDescriptor = await addressProvider!.GetNextSigningDescriptor(cancellationToken);
-        var preimage = await DerivePreimageAsync(walletId, claimDescriptor, cancellationToken);
+        var preimage = await DerivePreimageAsync(walletId, claimDescriptor, index: 0, cancellationToken);
 
         var result = await boltz.BoltzService.CreateBtcToArkSwapAsync(
             amountSats, claimDescriptor, preimage, cancellationToken);
@@ -417,7 +438,7 @@ public async Task<string> InitiateArkToBtcChainSwap(
 
         var addressProvider = await _walletProvider.GetAddressProviderAsync(walletId, cancellationToken);
         var refundDescriptor = await addressProvider!.GetNextSigningDescriptor(cancellationToken);
-        var preimage = await DerivePreimageAsync(walletId, refundDescriptor, cancellationToken);
+        var preimage = await DerivePreimageAsync(walletId, refundDescriptor, index: 0, cancellationToken);
 
         // Extract pub key hex for Boltz API
         var extractedRefund = OutputDescriptorHelpers.Extract(refundDescriptor);
@@ -653,7 +674,10 @@ await _contractService.ImportContract(
                 // before it expires. Submarine swaps don't apply — Boltz controls that preimage.
                 if (restored.IsReverseSwap && !string.IsNullOrEmpty(restored.PreimageHash))
                 {
-                    var derived = await DerivePreimageAsync(walletId, contract.Receiver, cancellationToken);
+                    // index=0 is the only value used at create-time today. If a future scheme
+                    // bump ships multi-preimage-per-descriptor, recovery should iterate
+                    // 0..MAX_INDEX here looking for a hash match.
+                    var derived = await DerivePreimageAsync(walletId, contract.Receiver, index: 0, cancellationToken);
                     var derivedHashHex = Convert.ToHexString(Hashes.SHA256(derived)).ToLowerInvariant();
                     if (string.Equals(derivedHashHex, restored.PreimageHash, StringComparison.OrdinalIgnoreCase))
                     {
diff --git a/docs/articles/swaps.md b/docs/articles/swaps.md
@@ -107,16 +107,26 @@ Typical states recorded against each `ArkSwap`:
 
 ### Deterministic preimages (for recoverable claims)
 
-The preimages we generate for reverse and chain swaps are derived deterministically from the wallet's signing material so that a restored wallet can re-derive them and claim outstanding VHTLCs. The scheme is:
+The preimages we generate for reverse and chain swaps are derived deterministically from the wallet's signing material so that a restored wallet can re-derive them and claim outstanding VHTLCs. The scheme:
 
 ```
-preimage = SHA-256( BIP-340-Schnorr( descriptor_key, SHA-256("NArk-Boltz-Preimage-v1") ) )
+message  = SHA-256( "NArk-Boltz-Preimage-v1" || descriptor.ToString() || u32_le(index) )
+sig      = BIP-340-Schnorr( descriptor_key, message, aux_rand=null )
+preimage = SHA-256( sig )
 ```
 
-— signing the constant tag-hash with the receiver descriptor's key. BIP-340 with `aux_rand=null` is deterministic, so the same descriptor + same wallet always produces the same preimage. Recovery: when `RestoreSwaps` rediscovers a reverse swap, it re-derives the candidate preimage, verifies `SHA-256(candidate) == restored.PreimageHash`, and attaches it to the swap's metadata for the sweeper to claim. Hash mismatch (legacy random preimage, or wrong descriptor) leaves the preimage out; `EnrichReverseSwapPreimage` remains the manual fallback.
+The signed input bundles three things:
+
+- **Tag** — domain-separates this signature from any other use of the descriptor's key. Versioned (`-v1`) so a future scheme bump can ship as `-v2` while recovery still tries v1 for older swaps.
+- **Descriptor** — scopes the preimage to the specific swap descriptor.
+- **Index** — lets a caller derive multiple preimages from the same descriptor. Always `0` today; baked into v1 so recovery iteration is forward-compatible without a scheme bump.
+
+BIP-340 with `aux_rand=null` is deterministic per `(key, message)`, so same `(wallet, descriptor, index)` always yields the same preimage. Recovery: when `RestoreSwaps` rediscovers a reverse swap, it re-derives the candidate preimage with `index=0`, verifies `SHA-256(candidate) == restored.PreimageHash`, and attaches it to the swap's metadata for the sweeper to claim. Hash mismatch (legacy random preimage, or wrong descriptor) leaves the preimage out; `EnrichReverseSwapPreimage` remains the manual fallback.
 
 Watch-only wallets (no signer) fall back to a random preimage on create — they don't get the recovery story but they can still execute swaps until they pair a signer.
 
+> **Remote signers and determinism.** `IRemoteSignerTransport.SignAsync` MUST use `aux_rand=null` for the recovery scheme to work end-to-end on remote-signed wallets. Implementations that randomise `aux_rand` (e.g. hardware-wallet side-channel hardening) will produce a different signature each call → different preimage → recovery silently fails. See the XML doc on `SignAsync`. Local sources (`Bip39SigningSource`, `NsecSigningSource`) already satisfy this.
+
 ## Chain Swap Recovery (Renegotiation + Cooperative Refund)
 
 Chain swaps can fail to settle when the user funds the lockup with an amount that doesn't match Boltz's original quote, when an LN invoice times out, or when the swap window expires. The SDK handles these cases automatically inside the routine status-poll loop in `BoltzSwapProvider.PollSwapState`:
