feat: add unilateral exit support with virtual tx storage and watchtower

Implements the full unilateral exit pipeline for NNark:

Transport: Add GetVtxoChainAsync, GetVirtualTxsAsync, GetVtxoTreeAsync
  to IClientTransport with gRPC and REST implementations.

Storage: VirtualTx/VtxoBranch/ExitSession entities with EF Core storage.
  Per-tx model deduplicates shared tree nodes across sibling VTXOs.

Services:
- VirtualTxService: fetch/store/prune virtual tx branches (Lite/Full modes)
- UnilateralExitService: orchestrate exit state machine
  (Broadcasting → AwaitingCsvDelay → Claimable → Claiming → Completed)
- ExitWatchtowerService: detect partial tree broadcasts, auto-respond
- P2ACpfpBuilder: build v3 CPFP children for 1p1c package relay

Integration:
- IOnchainBroadcaster with NBXplorer and Esplora implementations
- PostBatchVirtualTxFetchHandler: auto-fetch exit data on VTXO receive
- PostSpendVirtualTxPruneHandler: auto-prune on VTXO spend
- AddUnilateralExit() DI extension method

Tests: 12 new unit tests for VirtualTxService and P2ACpfpBuilder.

Author: Kukks

NArk.Abstractions/Blockchain/IOnchainBroadcaster.cs

@@ -0,0 +1,34 @@
+using NBitcoin;
+
+namespace NArk.Abstractions.Blockchain;
+
+/// <summary>
+/// Broadcasts Bitcoin transactions, including v3 package relay.
+/// </summary>
+public interface IOnchainBroadcaster
+{
+    /// <summary>
+    /// Broadcast a single transaction.
+    /// </summary>
+    Task<bool> BroadcastAsync(Transaction tx, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Broadcast a 1p1c package (parent + CPFP child) via submitpackage.
+    /// </summary>
+    Task<bool> BroadcastPackageAsync(Transaction parent, Transaction child, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Get transaction status on-chain.
+    /// </summary>
+    Task<TxStatus> GetTxStatusAsync(uint256 txid, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Estimate fee rate for the given confirmation target.
+    /// </summary>
+    Task<FeeRate> EstimateFeeRateAsync(int confirmTarget = 6, CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// On-chain transaction status.
+/// </summary>
+public record TxStatus(bool Confirmed, uint? BlockHeight, bool InMempool);

NArk.Abstractions/Exit/ExitSession.cs

@@ -0,0 +1,17 @@
+namespace NArk.Abstractions.Exit;
+
+/// <summary>
+/// Tracks the state of a unilateral exit for a single VTXO.
+/// </summary>
+public record ExitSession(
+    string Id,
+    string VtxoTxid,
+    uint VtxoVout,
+    string WalletId,
+    string ClaimAddress,
+    ExitSessionState State,
+    int NextTxIndex,
+    string? ClaimTxid,
+    DateTimeOffset CreatedAt,
+    DateTimeOffset UpdatedAt,
+    string? FailReason);

NArk.Abstractions/Exit/ExitSessionState.cs

@@ -0,0 +1,25 @@
+namespace NArk.Abstractions.Exit;
+
+/// <summary>
+/// State machine for unilateral exit sessions.
+/// </summary>
+public enum ExitSessionState
+{
+    /// <summary>Broadcasting tree txs root-to-leaf.</summary>
+    Broadcasting = 0,
+
+    /// <summary>All tree txs confirmed, waiting for CSV timelock to expire.</summary>
+    AwaitingCsvDelay = 1,
+
+    /// <summary>CSV expired, ready to claim funds on-chain.</summary>
+    Claimable = 2,
+
+    /// <summary>Claim tx broadcast, awaiting confirmation.</summary>
+    Claiming = 3,
+
+    /// <summary>Claim tx confirmed. Exit complete.</summary>
+    Completed = 4,
+
+    /// <summary>Unrecoverable error.</summary>
+    Failed = 5
+}

NArk.Abstractions/Exit/IExitSessionStorage.cs

@@ -0,0 +1,15 @@
+using NBitcoin;
+
+namespace NArk.Abstractions.Exit;
+
+/// <summary>
+/// Storage for unilateral exit sessions.
+/// </summary>
+public interface IExitSessionStorage
+{
+    Task UpsertAsync(ExitSession session, CancellationToken cancellationToken = default);
+    Task<ExitSession?> GetByIdAsync(string id, CancellationToken cancellationToken = default);
+    Task<ExitSession?> GetByVtxoAsync(OutPoint vtxoOutpoint, CancellationToken cancellationToken = default);
+    Task<IReadOnlyList<ExitSession>> GetByStateAsync(ExitSessionState state, CancellationToken cancellationToken = default);
+    Task<IReadOnlyList<ExitSession>> GetActiveSessionsAsync(string? walletId = null, CancellationToken cancellationToken = default);
+}

NArk.Abstractions/VirtualTxs/IVirtualTxStorage.cs

@@ -0,0 +1,39 @@
+using NBitcoin;
+
+namespace NArk.Abstractions.VirtualTxs;
+
+/// <summary>
+/// Storage for virtual transactions and their association with VTXOs.
+/// </summary>
+public interface IVirtualTxStorage
+{
+    /// <summary>
+    /// Upsert virtual transaction records. If a tx already exists, updates non-null fields.
+    /// </summary>
+    Task UpsertVirtualTxsAsync(IReadOnlyList<VirtualTx> txs, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Set the branch (ordered list of virtual txids) for a VTXO. Replaces any existing branch.
+    /// </summary>
+    Task SetBranchAsync(OutPoint vtxoOutpoint, IReadOnlyList<VtxoBranch> branch, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Get the virtual txs in a VTXO's exit branch, ordered by position.
+    /// </summary>
+    Task<IReadOnlyList<VirtualTx>> GetBranchAsync(OutPoint vtxoOutpoint, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Get a single virtual tx by txid.
+    /// </summary>
+    Task<VirtualTx?> GetVirtualTxAsync(string txid, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Remove branch entries for a spent VTXO, then clean up orphaned VirtualTx rows.
+    /// </summary>
+    Task PruneForSpentVtxoAsync(OutPoint vtxoOutpoint, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Check whether a VTXO has a stored branch.
+    /// </summary>
+    Task<bool> HasBranchAsync(OutPoint vtxoOutpoint, CancellationToken cancellationToken = default);
+}

NArk.Abstractions/VirtualTxs/VirtualTx.cs

@@ -0,0 +1,6 @@
+namespace NArk.Abstractions.VirtualTxs;
+
+/// <summary>
+/// A single virtual transaction in the VTXO tree.
+/// </summary>
+public record VirtualTx(string Txid, string? Hex, DateTimeOffset? ExpiresAt);

NArk.Abstractions/VirtualTxs/VirtualTxMode.cs

@@ -0,0 +1,17 @@
+namespace NArk.Abstractions.VirtualTxs;
+
+/// <summary>
+/// Controls how much virtual tx data is stored.
+/// </summary>
+public enum VirtualTxMode
+{
+    /// <summary>
+    /// Store only txids and branch structure. Tx hex is fetched on demand when needed for exit.
+    /// </summary>
+    Lite = 0,
+
+    /// <summary>
+    /// Store txids AND raw tx hex immediately on VTXO receive. Ready for instant exit.
+    /// </summary>
+    Full = 1
+}

NArk.Abstractions/VirtualTxs/VtxoBranch.cs

@@ -0,0 +1,7 @@
+namespace NArk.Abstractions.VirtualTxs;
+
+/// <summary>
+/// Links a VTXO to one virtual tx in its exit branch, with position ordering.
+/// Position 0 = closest to commitment tx (tree root), higher = closer to leaf.
+/// </summary>
+public record VtxoBranch(string VtxoTxid, uint VtxoVout, string VirtualTxid, int Position);

NArk.Core/Blockchain/Esplora/EsploraOnchainBroadcaster.cs

@@ -0,0 +1,153 @@
+using System.Net.Http.Json;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Logging;
+using NArk.Abstractions.Blockchain;
+using NBitcoin;
+
+namespace NArk.Blockchain.Esplora;
+
+/// <summary>
+/// Broadcasts transactions via Esplora REST API.
+/// Supports single tx broadcast and package relay.
+/// </summary>
+public class EsploraOnchainBroadcaster : IOnchainBroadcaster
+{
+    private readonly HttpClient _httpClient;
+    private readonly ILogger? _logger;
+
+    public EsploraOnchainBroadcaster(Uri baseUri, ILogger<EsploraOnchainBroadcaster>? logger = null)
+    {
+        _httpClient = new HttpClient { BaseAddress = baseUri };
+        _logger = logger;
+    }
+
+    public EsploraOnchainBroadcaster(HttpClient httpClient, ILogger<EsploraOnchainBroadcaster>? logger = null)
+    {
+        _httpClient = httpClient;
+        _logger = logger;
+    }
+
+    public async Task<bool> BroadcastAsync(Transaction tx, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var content = new StringContent(tx.ToHex(), Encoding.UTF8, "text/plain");
+            var response = await _httpClient.PostAsync("tx", content, cancellationToken);
+
+            if (!response.IsSuccessStatusCode)
+            {
+                var error = await response.Content.ReadAsStringAsync(cancellationToken);
+                _logger?.LogWarning("Esplora broadcast failed for tx {Txid}: {Error}",
+                    tx.GetHash(), error);
+                return false;
+            }
+
+            return true;
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogWarning(0, ex, "Failed to broadcast tx {Txid} via Esplora", tx.GetHash());
+            return false;
+        }
+    }
+
+    public async Task<bool> BroadcastPackageAsync(
+        Transaction parent, Transaction child, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var package = new[] { parent.ToHex(), child.ToHex() };
+            var response = await _httpClient.PostAsJsonAsync("txs/package", package, cancellationToken);
+
+            if (!response.IsSuccessStatusCode)
+            {
+                var error = await response.Content.ReadAsStringAsync(cancellationToken);
+                _logger?.LogWarning("Esplora package broadcast failed: {Error}", error);
+                return false;
+            }
+
+            return true;
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogWarning(0, ex, "Failed to broadcast package via Esplora");
+            return false;
+        }
+    }
+
+    public async Task<TxStatus> GetTxStatusAsync(
+        uint256 txid, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var response = await _httpClient.GetAsync(
+                $"tx/{txid}/status", cancellationToken);
+
+            if (!response.IsSuccessStatusCode)
+                return new TxStatus(false, null, false);
+
+            var status = await response.Content.ReadFromJsonAsync<EsploraTxStatus>(
+                cancellationToken: cancellationToken);
+
+            if (status is null)
+                return new TxStatus(false, null, false);
+
+            return new TxStatus(
+                status.Confirmed,
+                status.Confirmed ? (uint?)status.BlockHeight : null,
+                !status.Confirmed);
+        }
+        catch
+        {
+            return new TxStatus(false, null, false);
+        }
+    }
+
+    public async Task<FeeRate> EstimateFeeRateAsync(
+        int confirmTarget = 6, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var response = await _httpClient.GetAsync("fee-estimates", cancellationToken);
+            response.EnsureSuccessStatusCode();
+
+            var estimates = await response.Content.ReadFromJsonAsync<Dictionary<string, double>>(
+                cancellationToken: cancellationToken);
+
+            if (estimates is null)
+                return new FeeRate(Money.Satoshis(2));
+
+            // Find the closest target
+            var targetStr = confirmTarget.ToString();
+            if (estimates.TryGetValue(targetStr, out var rate))
+                return new FeeRate(Money.Satoshis((long)Math.Ceiling(rate)));
+
+            // Fallback to nearest available target
+            var closest = estimates
+                .Select(kvp => (Target: int.TryParse(kvp.Key, out var t) ? t : int.MaxValue, Rate: kvp.Value))
+                .Where(x => x.Target != int.MaxValue)
+                .OrderBy(x => Math.Abs(x.Target - confirmTarget))
+                .FirstOrDefault();
+
+            return closest.Rate > 0
+                ? new FeeRate(Money.Satoshis((long)Math.Ceiling(closest.Rate)))
+                : new FeeRate(Money.Satoshis(2));
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogWarning(0, ex, "Failed to estimate fee rate via Esplora, using fallback");
+            return new FeeRate(Money.Satoshis(2));
+        }
+    }
+
+    private class EsploraTxStatus
+    {
+        [JsonPropertyName("confirmed")]
+        public bool Confirmed { get; set; }
+
+        [JsonPropertyName("block_height")]
+        public long BlockHeight { get; set; }
+    }
+}