fix: silent truncation in QueryNodesAsync and QueryNodesForPlanAsync

Sentinel v3 caps node queries at limit and never emits next_key,
causing standard pagination loops to terminate on the first call. Plan
36 has 803 active nodes but limit=500 returned exactly 500. Defaults
raised to 10000 with <remarks> explaining the chain behavior.

Additional work in this commit: BroadcastTxAsync via Tendermint RPC
with LCD fallback, SessionModeTracker for per-session payment-mode
persistence, DiskCache generic helper, AppTypeHelpers for white-label
vs direct app modes, Consumer/Operator entrypoints in SDK.Node, event
parser improvements, and expanded ExhaustiveChainTests coverage.

Author: Sentinel-Bluebuilder

src/Sentinel.SDK.Core/AppTypeHelpers.cs

@@ -0,0 +1,189 @@
+namespace Sentinel.SDK.Core;
+
+// ─── App Type Validation Result ───
+
+/// <summary>
+/// Result of validating an app configuration against its type requirements.
+/// Ported from js-sdk/app-types.js line 188-230.
+/// </summary>
+/// <param name="Valid">True when no errors were found.</param>
+/// <param name="Errors">Hard validation failures (missing required config, unknown type).</param>
+/// <param name="Warnings">Soft issues (misaligned options, missing optional feeGranter).</param>
+/// <param name="TypeDescription">The matched app type description, or null when unknown.</param>
+public record AppConfigValidation(
+    bool Valid,
+    IReadOnlyList<string> Errors,
+    IReadOnlyList<string> Warnings,
+    string? TypeDescription);
+
+// ─── App Configuration ───
+
+/// <summary>
+/// App-level configuration used by <see cref="AppTypeHelpers.ValidateAppConfig"/>
+/// and <see cref="AppTypeHelpers.GetConnectDefaults"/>. Mirrors the JS config object.
+/// </summary>
+public sealed class AppConfig
+{
+    /// <summary>Wallet mnemonic (required for all app types).</summary>
+    public string? Mnemonic { get; init; }
+
+    /// <summary>Plan ID (required for <see cref="Constants.AppTypes.WhiteLabel"/>).</summary>
+    public long? PlanId { get; init; }
+
+    /// <summary>Fee granter address (recommended for white-label so users don't pay gas).</summary>
+    public string? FeeGranter { get; init; }
+
+    /// <summary>DNS preset name or "handshake" (default).</summary>
+    public string? Dns { get; init; }
+
+    /// <summary>Default gigabytes for direct P2P sessions (default: 1).</summary>
+    public int? DefaultGigabytes { get; init; }
+
+    /// <summary>Prefer hourly pricing when both GB and hourly are available.</summary>
+    public bool PreferHourly { get; init; }
+
+    /// <summary>Route all traffic through VPN (default: true).</summary>
+    public bool? FullTunnel { get; init; }
+
+    /// <summary>Enable kill switch (default: false).</summary>
+    public bool KillSwitch { get; init; }
+
+    /// <summary>Optional country filter for auto-connect.</summary>
+    public string[]? Countries { get; init; }
+}
+
+// ─── Connect Defaults ───
+
+/// <summary>
+/// Recommended connect options for an app type. Spread into your connect call.
+/// Ported from js-sdk/app-types.js line 242-267.
+/// </summary>
+public sealed class ConnectDefaults
+{
+    /// <summary>DNS preset name.</summary>
+    public string Dns { get; init; } = "handshake";
+
+    /// <summary>Route all traffic through VPN.</summary>
+    public bool FullTunnel { get; init; } = true;
+
+    /// <summary>Kill switch enabled.</summary>
+    public bool KillSwitch { get; init; }
+
+    /// <summary>Plan ID (white-label only).</summary>
+    public long? PlanId { get; init; }
+
+    /// <summary>Fee granter address (white-label only).</summary>
+    public string? FeeGranter { get; init; }
+
+    /// <summary>Gigabytes to purchase (direct-p2p only).</summary>
+    public int? Gigabytes { get; init; }
+
+    /// <summary>Prefer hourly pricing (direct-p2p only).</summary>
+    public bool PreferHourly { get; init; }
+}
+
+// ─── App Type Helpers ───
+
+/// <summary>
+/// Validation and defaults helpers for the three Sentinel app types.
+/// Ported from js-sdk/app-types.js (validateAppConfig + getConnectDefaults, lines 181-267).
+/// </summary>
+public static class AppTypeHelpers
+{
+    /// <summary>
+    /// Validate an app's configuration against its type requirements.
+    /// Call at app startup to catch misconfigurations early.
+    /// Ported from js-sdk/app-types.js line 195-230.
+    /// </summary>
+    public static AppConfigValidation ValidateAppConfig(string appType, AppConfig? config = null)
+    {
+        if (!Constants.AppTypes.All.Contains(appType))
+        {
+            return new AppConfigValidation(
+                Valid: false,
+                Errors: new[] { $"Unknown app type: \"{appType}\". Use: {string.Join(", ", Constants.AppTypes.All)}" },
+                Warnings: Array.Empty<string>(),
+                TypeDescription: null);
+        }
+
+        config ??= new AppConfig();
+        var errors = new List<string>();
+        var warnings = new List<string>();
+
+        // All app types require a mnemonic.
+        if (string.IsNullOrEmpty(config.Mnemonic))
+            errors.Add($"Missing required config: \"mnemonic\" (required for {appType} apps)");
+
+        if (appType == Constants.AppTypes.WhiteLabel)
+        {
+            if (!config.PlanId.HasValue || config.PlanId.Value <= 0)
+                errors.Add("White-label apps MUST have a planId configured");
+            if (string.IsNullOrEmpty(config.FeeGranter))
+                warnings.Add("White-label apps should have a feeGranter so users don't pay gas. Without it, users need P2P tokens for gas fees.");
+        }
+
+        if (appType == Constants.AppTypes.DirectP2P && config.PlanId.HasValue && config.PlanId.Value > 0)
+        {
+            warnings.Add("planId is set but app type is direct_p2p — plan functions won't be used. Did you mean all_in_one?");
+        }
+
+        return new AppConfigValidation(
+            Valid: errors.Count == 0,
+            Errors: errors,
+            Warnings: warnings,
+            TypeDescription: DescribeType(appType));
+    }
+
+    /// <summary>
+    /// Get the recommended connect options for an app type.
+    /// Returns a base config that callers can customize per connection.
+    /// Ported from js-sdk/app-types.js line 242-267.
+    /// </summary>
+    public static ConnectDefaults GetConnectDefaults(string appType, AppConfig? appConfig = null)
+    {
+        appConfig ??= new AppConfig();
+
+        var dns = string.IsNullOrEmpty(appConfig.Dns) ? "handshake" : appConfig.Dns;
+        var fullTunnel = appConfig.FullTunnel ?? true;
+
+        if (appType == Constants.AppTypes.WhiteLabel)
+        {
+            return new ConnectDefaults
+            {
+                Dns = dns,
+                FullTunnel = fullTunnel,
+                KillSwitch = appConfig.KillSwitch,
+                PlanId = appConfig.PlanId,
+                FeeGranter = string.IsNullOrEmpty(appConfig.FeeGranter) ? null : appConfig.FeeGranter,
+            };
+        }
+
+        if (appType == Constants.AppTypes.DirectP2P)
+        {
+            return new ConnectDefaults
+            {
+                Dns = dns,
+                FullTunnel = fullTunnel,
+                KillSwitch = appConfig.KillSwitch,
+                Gigabytes = appConfig.DefaultGigabytes ?? 1,
+                PreferHourly = appConfig.PreferHourly,
+            };
+        }
+
+        // ALL_IN_ONE or unknown — caller decides per-connection.
+        return new ConnectDefaults
+        {
+            Dns = dns,
+            FullTunnel = fullTunnel,
+            KillSwitch = appConfig.KillSwitch,
+        };
+    }
+
+    private static string DescribeType(string appType) => appType switch
+    {
+        Constants.AppTypes.WhiteLabel => "White-label dVPN — branded app with pre-loaded plan + fee grant",
+        Constants.AppTypes.DirectP2P => "Direct P2P — users pay nodes directly per-GB or per-hour",
+        Constants.AppTypes.AllInOne => "All-in-one — plan subscriptions + direct P2P in one app",
+        _ => appType,
+    };
+}

src/Sentinel.SDK.Core/ChainClient.Queries.cs

@@ -309,12 +309,27 @@ public async Task<List<DiscoveredPlan>> DiscoverPlansAsync(int maxId = 100, Canc
     }
 
     /// <summary>
-    /// Broadcast a raw transaction to the chain via LCD.
+    /// Broadcast a raw transaction to the chain. Tries Tendermint RPC
+    /// <c>broadcast_tx_sync</c> first; falls back to LCD <c>/cosmos/tx/v1beta1/txs</c> on
+    /// failure or unrecognizable RPC response.
     /// </summary>
     /// <param name="txBytes">Serialized TxRaw bytes.</param>
+    /// <param name="ct">Cancellation token.</param>
     /// <returns>Transaction result.</returns>
     internal async Task<TxResult> BroadcastTxAsync(byte[] txBytes, CancellationToken ct = default)
     {
+        // RPC-first: broadcast_tx_sync is lower-latency than LCD and avoids REST overhead.
+        try
+        {
+            var rpcResult = await _rpcClient.BroadcastTxAsync(txBytes, ct);
+            if (rpcResult is not null) return rpcResult;
+        }
+        catch (Exception ex)
+        {
+            _logger?.Debug($"RPC broadcast failed, falling back to LCD: {ex.Message}");
+        }
+
+        // LCD fallback
         var base64Tx = Convert.ToBase64String(txBytes);
         var payload = new { tx_bytes = base64Tx, mode = "BROADCAST_MODE_SYNC" };
 
@@ -356,17 +371,30 @@ internal async Task<TxResult> BroadcastTxAsync(byte[] txBytes, CancellationToken
         }
 
         throw new SentinelException("CLIENT_BROADCAST_FAILED",
-            $"All LCD endpoints failed to broadcast: {lastException?.Message}", lastException!);
+            $"All RPC and LCD endpoints failed to broadcast: {lastException?.Message}", lastException!);
     }
 
     /// <summary>
-    /// Query a transaction by hash from the LCD.
+    /// Query a transaction by hash. Tries Tendermint RPC <c>tx</c> method first; falls back
+    /// to LCD <c>/cosmos/tx/v1beta1/txs/{hash}</c> if RPC returns nothing.
     /// </summary>
     /// <param name="txHash">Transaction hash (hex).</param>
     /// <param name="ct">Cancellation token.</param>
     /// <returns>Transaction result if found, or null if not found.</returns>
     internal async Task<TxResult?> QueryTxAsync(string txHash, CancellationToken ct = default)
     {
+        // RPC-first: avoids LCD propagation lag for double-spend guard checks.
+        try
+        {
+            var rpcResult = await _rpcClient.QueryTxAsync(txHash, ct);
+            if (rpcResult is not null) return rpcResult;
+        }
+        catch (Exception ex)
+        {
+            _logger?.Debug($"RPC QueryTx failed for {txHash}, falling back to LCD: {ex.Message}");
+        }
+
+        // LCD fallback
         try
         {
             var path = $"/cosmos/tx/v1beta1/txs/{txHash}";
@@ -391,6 +419,134 @@ internal async Task<TxResult> BroadcastTxAsync(byte[] txBytes, CancellationToken
         }
     }
 
+    /// <summary>
+    /// Query a TX by hash and return the top-level <c>events</c> array as JSON text.
+    /// Modern Cosmos SDK emits events directly on <c>tx_response.events</c>; raw_log can be
+    /// empty. This method returns whichever is populated, normalized to the array format
+    /// expected by <see cref="EventParser.FindEvent"/>.
+    /// </summary>
+    private async Task<string?> QueryTxEventsJsonAsync(string txHash, CancellationToken ct)
+    {
+        // RPC-first: Tendermint tx method returns events directly, no LCD propagation lag.
+        try
+        {
+            var rpcEvents = await _rpcClient.QueryTxEventsJsonAsync(txHash, ct);
+            if (!string.IsNullOrEmpty(rpcEvents)) return rpcEvents;
+        }
+        catch (Exception ex)
+        {
+            _logger?.Debug($"RPC tx events failed for {txHash}, falling back to LCD: {ex.Message}");
+        }
+
+        try
+        {
+            var path = $"/cosmos/tx/v1beta1/txs/{txHash}";
+            var json = await LcdGetAsync(path, ct);
+            if (!json.TryGetProperty("tx_response", out var txResponse)) return null;
+
+            // Prefer tx_response.events (top-level, modern)
+            if (txResponse.TryGetProperty("events", out var eventsTop) &&
+                eventsTop.ValueKind == JsonValueKind.Array &&
+                eventsTop.GetArrayLength() > 0)
+            {
+                return eventsTop.GetRawText();
+            }
+
+            // Fallback: raw_log is a JSON string containing log entries with events
+            if (txResponse.TryGetProperty("raw_log", out var rl))
+            {
+                var raw = rl.GetString();
+                if (string.IsNullOrEmpty(raw)) return null;
+                try
+                {
+                    using var logDoc = JsonDocument.Parse(raw);
+                    if (logDoc.RootElement.ValueKind == JsonValueKind.Array)
+                    {
+                        var combined = new List<JsonElement>();
+                        foreach (var entry in logDoc.RootElement.EnumerateArray())
+                        {
+                            if (entry.TryGetProperty("events", out var evs) &&
+                                evs.ValueKind == JsonValueKind.Array)
+                            {
+                                foreach (var ev in evs.EnumerateArray()) combined.Add(ev);
+                            }
+                        }
+                        if (combined.Count == 0) return null;
+                        using var ms = new System.IO.MemoryStream();
+                        using (var writer = new Utf8JsonWriter(ms))
+                        {
+                            writer.WriteStartArray();
+                            foreach (var ev in combined) ev.WriteTo(writer);
+                            writer.WriteEndArray();
+                        }
+                        return System.Text.Encoding.UTF8.GetString(ms.ToArray());
+                    }
+                }
+                catch { /* raw_log not JSON — return as-is for regex fallback */ }
+                return raw;
+            }
+            return null;
+        }
+        catch (SentinelException ex) when (ex.Code == "CLIENT_HTTP_404") { return null; }
+    }
+
+    /// <inheritdoc />
+    public async Task<long?> ExtractPlanIdFromTxAsync(string txHash, int timeoutMs = 20000, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(txHash);
+        var deadline = DateTime.UtcNow.AddMilliseconds(timeoutMs);
+        while (DateTime.UtcNow < deadline)
+        {
+            ct.ThrowIfCancellationRequested();
+            var eventsJson = await QueryTxEventsJsonAsync(txHash, ct);
+            if (!string.IsNullOrEmpty(eventsJson))
+            {
+                var id = EventParser.ExtractPlanIdFromEvents(eventsJson);
+                if (id is > 0) return id;
+            }
+            await Task.Delay(2000, ct);
+        }
+        return null;
+    }
+
+    /// <inheritdoc />
+    public async Task<long?> ExtractSubscriptionIdFromTxAsync(string txHash, int timeoutMs = 20000, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(txHash);
+        var deadline = DateTime.UtcNow.AddMilliseconds(timeoutMs);
+        while (DateTime.UtcNow < deadline)
+        {
+            ct.ThrowIfCancellationRequested();
+            var eventsJson = await QueryTxEventsJsonAsync(txHash, ct);
+            if (!string.IsNullOrEmpty(eventsJson))
+            {
+                var id = EventParser.ExtractSubscriptionIdFromEvents(eventsJson);
+                if (id is > 0) return id;
+            }
+            await Task.Delay(2000, ct);
+        }
+        return null;
+    }
+
+    /// <inheritdoc />
+    public async Task<long?> ExtractSessionIdFromTxAsync(string txHash, int timeoutMs = 20000, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(txHash);
+        var deadline = DateTime.UtcNow.AddMilliseconds(timeoutMs);
+        while (DateTime.UtcNow < deadline)
+        {
+            ct.ThrowIfCancellationRequested();
+            var eventsJson = await QueryTxEventsJsonAsync(txHash, ct);
+            if (!string.IsNullOrEmpty(eventsJson))
+            {
+                var id = EventParser.ExtractSessionId(eventsJson);
+                if (id is > 0) return id;
+            }
+            await Task.Delay(2000, ct);
+        }
+        return null;
+    }
+
     // ─── IChainClient: Session Queries ───
 
     /// <inheritdoc />