feat: RPC-first migration — 15 query methods with LCD fallback

RpcClient wired into ChainClient. Added typed query methods for
sessions, subscriptions, provider, fee grants, authz grants, and
allocations using ProtobufReader decoders. All ChainClient query
methods now try RPC first and fall back to LCD on failure.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Sentinel-Bluebuilder

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

@@ -19,6 +19,14 @@ public async Task<List<FeeGrant>> QueryFeeGrantsAsync(string grantee, Cancellati
     {
         ArgumentNullException.ThrowIfNull(grantee);
 
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QueryFeeGrantsAsync(grantee, ct: ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC QueryFeeGrants failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/cosmos/feegrant/v1beta1/allowances/{grantee}";
         var items = await LcdPaginatedAsync(path, "allowances", ct);
 
@@ -47,6 +55,14 @@ public async Task<IReadOnlyList<FeeGrant>> QueryFeeGrantsIssuedAsync(string gran
     {
         ArgumentNullException.ThrowIfNull(granter);
 
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QueryFeeGrantsIssuedAsync(granter, ct: ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC QueryFeeGrantsIssued failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/cosmos/feegrant/v1beta1/issued/{granter}";
         var items = await LcdPaginatedAsync(path, "allowances", ct);
 

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

@@ -20,6 +20,14 @@ public async Task<Balance> GetBalanceAsync(string address, CancellationToken ct
     {
         ArgumentNullException.ThrowIfNull(address);
 
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QueryBalanceAsync(address, Constants.Denom, ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC GetBalance failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/cosmos/bank/v1beta1/balances/{address}/by_denom?denom={Constants.Denom}";
         var json = await LcdGetAsync(path, ct);
 
@@ -43,6 +51,14 @@ public async Task<Balance> GetBalanceAsync(string address, CancellationToken ct
     /// <returns>List of active chain nodes.</returns>
     public async Task<List<ChainNode>> GetActiveNodesAsync(int limit = 500, CancellationToken ct = default)
     {
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QueryNodesAsync(1, limit, ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC GetActiveNodes failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/sentinel/node/v3/nodes?status=1&pagination.limit={limit}";
         var items = await LcdPaginatedAsync(path, "nodes", ct);
         return items.Select(ParseChainNode).ToList();
@@ -57,6 +73,14 @@ public async Task<List<ChainNode>> GetActiveNodesAsync(int limit = 500, Cancella
     {
         ArgumentNullException.ThrowIfNull(nodeAddress);
 
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QueryNodeAsync(nodeAddress, ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC GetNode failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         try
         {
             var path = $"/sentinel/node/v3/nodes/{nodeAddress}";
@@ -84,6 +108,14 @@ public async Task<List<Subscription>> GetSubscriptionsAsync(string address, Canc
     {
         ArgumentNullException.ThrowIfNull(address);
 
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QuerySubscriptionsForAccountAsync(address, ct: ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC GetSubscriptions failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/sentinel/subscription/v3/accounts/{address}/subscriptions";
         var items = await LcdPaginatedAsync(path, "subscriptions", ct);
         return items.Select(ParseSubscription).ToList();
@@ -99,7 +131,18 @@ public async Task<List<ChainSession>> GetSessionsAsync(string address, string st
     {
         ArgumentNullException.ThrowIfNull(address);
 
-        // MUST use /accounts/{addr}/sessions — query-param format returns ALL sessions unfiltered
+        // RPC-first
+        try
+        {
+            var sessions = await _rpcClient.QuerySessionsForAccountAsync(address, ct: ct);
+            // Filter by status if specified (RPC returns all statuses)
+            if (status == "1")
+                return sessions.Where(s => s.Status == "active" || s.Status == "1").ToList();
+            return sessions;
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC GetSessions failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback — MUST use /accounts/{addr}/sessions path
         var path = $"/sentinel/session/v3/accounts/{address}/sessions?status={status}";
         var items = await LcdPaginatedAsync(path, "sessions", ct);
         return items.Select(ParseChainSession).ToList();
@@ -113,6 +156,14 @@ public async Task<List<ChainSession>> GetSessionsAsync(string address, string st
     /// <returns>List of nodes in the plan.</returns>
     public async Task<List<ChainNode>> GetPlanNodesAsync(int planId, CancellationToken ct = default)
     {
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QueryNodesForPlanAsync((ulong)planId, 1, 5000, ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC GetPlanNodes failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/sentinel/node/v3/plans/{planId}/nodes?pagination.limit=5000";
         var items = await LcdPaginatedAsync(path, "nodes", ct);
         return items.Select(ParseChainNode).ToList();
@@ -347,14 +398,27 @@ public async Task<IReadOnlyList<ActiveSession>> QueryActiveSessionsForAddressAsy
     {
         ArgumentNullException.ThrowIfNull(walletAddress);
 
-        // MUST use /accounts/{addr}/sessions — the query-param format returns ALL sessions unfiltered
+        // RPC-first
+        try
+        {
+            var rpcSessions = await _rpcClient.QuerySessionsForAccountAsync(walletAddress, ct: ct);
+            return rpcSessions
+                .Where(s => s.Status == "active" || s.Status == "1")
+                .Select(s => new ActiveSession(
+                    ulong.TryParse(s.Id, out var sid) ? sid : 0,
+                    s.NodeAddress,
+                    SessionStatus.Active))
+                .ToList();
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC QueryActiveSessions failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/sentinel/session/v3/accounts/{walletAddress}/sessions?status=1";
         var items = await LcdPaginatedAsync(path, "sessions", ct);
         var sessions = new List<ActiveSession>();
 
         foreach (var s in items)
         {
-            // v3 sessions wrap fields in base_session
             var bs = s.TryGetProperty("base_session", out var baseEl) ? baseEl : s;
             var idStr = bs.TryGetProperty("id", out var idEl) ? idEl.GetString() ?? "0" : "0";
             var nodeAddr = bs.TryGetProperty("node_address", out var naEl) ? naEl.GetString() ?? "" : "";
@@ -375,6 +439,15 @@ public async Task<IReadOnlyList<ActiveSession>> QueryActiveSessionsForAddressAsy
     /// <inheritdoc />
     public async Task<RawSessionAllocation?> QuerySessionAllocationAsync(ulong sessionId, CancellationToken ct = default)
     {
+        // RPC-first
+        try
+        {
+            var result = await _rpcClient.QuerySessionAllocationAsync(sessionId, ct);
+            if (result is not null) return result;
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC QuerySessionAllocation failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/sentinel/session/v3/sessions/{sessionId}/allocations";
         var json = await LcdGetAsync(path, ct);
 
@@ -408,8 +481,14 @@ public async Task<IReadOnlyList<ActiveSession>> QueryActiveSessionsForAddressAsy
     public async Task<List<SubscriptionAllocation>> QuerySubscriptionAllocationsAsync(
         ulong subscriptionId, CancellationToken ct = default)
     {
-        // NOTE: v3 endpoint for this specific query hasn't been implemented yet (returns 501).
-        // The v2 path works and returns the same allocation data. Same situation as /plan/v3/plans/{id}.
+        // RPC-first (v2 — v3 returns 501)
+        try
+        {
+            return await _rpcClient.QuerySubscriptionAllocationsAsync(subscriptionId, ct: ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC QuerySubAllocations failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback (v2 path — v3 returns 501)
         var path = $"/sentinel/subscription/v2/subscriptions/{subscriptionId}/allocations";
         var allocations = new List<SubscriptionAllocation>();
 
@@ -453,6 +532,14 @@ public async Task<List<SubscriptionAllocation>> QuerySubscriptionAllocationsAsyn
     /// <returns>List of nodes in the plan.</returns>
     public async Task<List<ChainNode>> QueryPlanNodesAsync(int planId, CancellationToken ct = default)
     {
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QueryNodesForPlanAsync((ulong)planId, 1, 5000, ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC QueryPlanNodes failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/sentinel/node/v3/plans/{planId}/nodes?pagination.limit=5000";
         var items = await LcdPaginatedAsync(path, "nodes", ct);
         return items.Select(ParseChainNode).ToList();
@@ -546,6 +633,15 @@ public async Task<IReadOnlyList<ChainNode>> GetAvailableNodesAsync(string wallet
     {
         ArgumentNullException.ThrowIfNull(provAddress);
 
+        // RPC-first (v2 — provider not migrated to v3)
+        try
+        {
+            var result = await _rpcClient.QueryProviderAsync(provAddress, ct);
+            if (result is not null) return result;
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC GetProvider failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         try
         {
             var path = $"/sentinel/provider/v2/providers/{provAddress}";
@@ -584,6 +680,17 @@ public async Task<IReadOnlyList<ChainNode>> GetAvailableNodesAsync(string wallet
     {
         ArgumentNullException.ThrowIfNull(id);
 
+        // RPC-first
+        if (ulong.TryParse(id, out var subId))
+        {
+            try
+            {
+                return await _rpcClient.QuerySubscriptionAsync(subId, ct);
+            }
+            catch (Exception ex) { _logger?.Debug($"RPC GetSubscription failed, falling back to LCD: {ex.Message}"); }
+        }
+
+        // LCD fallback
         try
         {
             var path = $"/sentinel/subscription/v3/subscriptions/{id}";
@@ -813,6 +920,14 @@ public async Task<IReadOnlyList<AuthzGrant>> QueryAuthzGrantsAsync(
         ArgumentException.ThrowIfNullOrWhiteSpace(granter);
         ArgumentException.ThrowIfNullOrWhiteSpace(grantee);
 
+        // RPC-first
+        try
+        {
+            return await _rpcClient.QueryAuthzGrantsAsync(granter, grantee, ct: ct);
+        }
+        catch (Exception ex) { _logger?.Debug($"RPC QueryAuthzGrants failed, falling back to LCD: {ex.Message}"); }
+
+        // LCD fallback
         var path = $"/cosmos/authz/v1beta1/grants?granter={granter}&grantee={grantee}";
         var grants = new List<AuthzGrant>();
 
@@ -833,7 +948,6 @@ public async Task<IReadOnlyList<AuthzGrant>> QueryAuthzGrantsAsync(
                         if (auth.TryGetProperty("@type", out var typeProp))
                             msgTypeUrl = typeProp.GetString() ?? "";
 
-                        // GenericAuthorization has msg field
                         if (auth.TryGetProperty("msg", out var msgProp))
                             msgTypeUrl = msgProp.GetString() ?? msgTypeUrl;
                     }

src/Sentinel.SDK.Core/ChainClient.cs

@@ -15,6 +15,7 @@ public sealed partial class ChainClient : IChainClient, IDisposable
     private readonly HttpClient _publicHttpClient; // CA-validated for LCD/RPC
     private readonly ISdkLogger? _logger;
     private readonly TimeSpan _timeout = TimeSpan.FromSeconds(15);
+    private readonly RpcClient _rpcClient;
 
     private static readonly JsonSerializerOptions JsonOptions = new()
     {
@@ -64,6 +65,9 @@ public ChainClient(string[]? lcdUrls = null, string[]? rpcUrls = null, ISdkLogge
         {
             Timeout = _timeout,
         };
+
+        // RPC client for protobuf/ABCI queries (~10x faster than LCD)
+        _rpcClient = new RpcClient(_rpcUrls, _logger);
     }
 
     // ─── Initialization ───
@@ -90,5 +94,6 @@ public void Dispose()
     {
         _httpClient.Dispose();
         _publicHttpClient.Dispose();
+        _rpcClient.Dispose();
     }
 }

src/Sentinel.SDK.Core/ProtobufReader.cs

@@ -96,6 +96,77 @@ internal static PriceEntry DecodePrice(List<ProtoField> fields)
         return new PriceEntry(denom, baseVal, quoteVal);
     }
 
+    /// <summary>
+    /// Decode a ChainSession from protobuf fields.
+    /// Session v3 wraps in base_session (field 1). Base session proto:
+    /// id=1, acc_address=2, node_address=3, download_bytes=7(varint), upload_bytes=8(varint),
+    /// max_bytes=9(varint), duration=10(string), max_duration=11(string), status=14(varint),
+    /// inactive_at=15(embedded timestamp), start_at=16(embedded timestamp)
+    /// </summary>
+    internal static ChainSession DecodeSession(List<ProtoField> outerFields)
+    {
+        // Unwrap base_session (field 1) if present
+        var baseField = GetField(outerFields, 1);
+        var fields = baseField is not null ? DecodeEmbedded(baseField) : outerFields;
+
+        var id = GetField(fields, 1) is { } f1 ? f1.Varint.ToString() : "0";
+        var accAddr = GetField(fields, 2) is { } f2 ? DecodeString(f2) : "";
+        var nodeAddr = GetField(fields, 3) is { } f3 ? DecodeString(f3) : "";
+        var download = GetField(fields, 7) is { } f7 ? f7.Varint.ToString() : "0";
+        var upload = GetField(fields, 8) is { } f8 ? f8.Varint.ToString() : "0";
+        var maxBytes = GetField(fields, 9) is { } f9 ? f9.Varint.ToString() : "0";
+        var duration = GetField(fields, 10) is { } f10 ? DecodeString(f10) : null;
+        var maxDuration = GetField(fields, 11) is { } f11 ? DecodeString(f11) : null;
+        var status = GetField(fields, 14) is { } f14 ? (int)f14.Varint : 0;
+        // status: 1=active, 2=inactive_pending, 3=inactive
+        var statusStr = status switch { 1 => "active", 2 => "inactive_pending", 3 => "inactive", _ => status.ToString() };
+
+        return new ChainSession(id, accAddr, nodeAddr, download, upload, maxBytes, duration, maxDuration, statusStr, null, null);
+    }
+
+    /// <summary>
+    /// Decode a Subscription from protobuf fields.
+    /// Subscription v3 wraps in base_subscription (field 1). Base:
+    /// id=1(varint), acc_address=2(string), plan_id=4(varint), status=7(varint),
+    /// start_at=8(timestamp), inactive_at=9(timestamp)
+    /// Price is on outer field 2.
+    /// </summary>
+    internal static Subscription DecodeSubscription(List<ProtoField> outerFields)
+    {
+        var baseField = GetField(outerFields, 1);
+        var fields = baseField is not null ? DecodeEmbedded(baseField) : outerFields;
+
+        var id = GetField(fields, 1) is { } f1 ? f1.Varint.ToString() : "0";
+        var accAddr = GetField(fields, 2) is { } f2 ? DecodeString(f2) : "";
+        var planId = GetField(fields, 4) is { } f4 ? f4.Varint.ToString() : "0";
+        var status = GetField(fields, 7) is { } f7 ? (int)f7.Varint : 0;
+        var statusStr = status switch { 1 => "active", 2 => "inactive_pending", 3 => "inactive", _ => status.ToString() };
+
+        // Price is outer field 2 (on the subscription wrapper, not base)
+        PriceEntry? price = null;
+        if (GetField(outerFields, 2) is { } pf)
+        {
+            price = DecodePrice(DecodeEmbedded(pf));
+        }
+
+        return new Subscription(id, accAddr, planId, price, statusStr, "", "");
+    }
+
+    /// <summary>
+    /// Decode a Provider from protobuf fields.
+    /// Provider v2: address=1, name=2, identity=3, website=4, description=5, status=6(varint)
+    /// </summary>
+    internal static Provider DecodeProvider(List<ProtoField> fields)
+    {
+        var address = GetField(fields, 1) is { } f1 ? DecodeString(f1) : "";
+        var name = GetField(fields, 2) is { } f2 ? DecodeString(f2) : "";
+        var identity = GetField(fields, 3) is { } f3 ? DecodeString(f3) : "";
+        var website = GetField(fields, 4) is { } f4 ? DecodeString(f4) : "";
+        var description = GetField(fields, 5) is { } f5 ? DecodeString(f5) : "";
+        var status = GetField(fields, 6) is { } f6 ? (int)f6.Varint : 0;
+        return new Provider(address, name, identity, website, description, status);
+    }
+
     /// <summary>
     /// Decode a ChainNode from protobuf fields.
     /// Node proto: address=1, gigabyte_prices=2, hourly_prices=3, remote_addrs=4, status=6