blue-js-sdk 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 Every fix made during SDK creation, why it matters, and what happens if you use upstream Sentinel code directly without these fixes.
 
+## v2.3.0 — RPC-First Migration (2026-04-14)
+
+**100% of chain queries now use RPC-first with LCD fallback.** Protobuf/ABCI queries via Tendermint37Client are ~912x faster than LCD REST. If RPC fails, every query automatically falls back to LCD.
+
+### JS SDK Changes
+- **chain/rpc.js**: Added 4 new RPC functions — `rpcQueryFeeGrants`, `rpcQueryFeeGrantsIssued`, `rpcQueryAuthzGrants`, `rpcQueryProvider`
+- **chain/queries.js**: All 22 query functions are RPC-first with LCD fallback
+- **chain/fee-grants.js**: All 7 functions are RPC-first with LCD fallback
+- **cosmjs-setup.js**: All 28 query bodies replaced with thin wrappers delegating to RPC-first modules
+- **session-manager.js**: `buildSessionMap()` now uses RPC-first `querySessions()`
+- **batch.js**: `waitForBatchSessions()` now uses RPC-first `querySessions()`
+- **defaults.js**: Added runtime endpoint management — `addRpcEndpoint`, `removeRpcEndpoint`, `setEndpoints`, `getEndpoints`, `checkRpcEndpointHealth`, `optimizeEndpoints`
+- **index.js**: 16 RPC query exports + 8 endpoint management exports
+- **SDK_VERSION**: Bumped to 2.3.0
+
+### C# SDK Changes
+- **RpcClient.cs**: Wired into ChainClient. 17 typed query methods (sessions, subscriptions, nodes, balance, provider, fee grants, authz, allocations)
+- **ProtobufReader.cs**: Added `DecodeSession`, `DecodeSubscription`, `DecodeProvider` decoders
+- **ChainClient.Queries.cs**: 13 methods upgraded to RPC-first with LCD fallback
+- **ChainClient.FeeGrants.cs**: 2 methods upgraded to RPC-first with LCD fallback
+- **Total**: 15 direct + 9 transitive = 24 query methods are RPC-first
+
+### Coverage
+| Module | RPC-First | Total |
+|--------|-----------|-------|
+| JS chain/queries.js | 22/22 | 100% |
+| JS chain/fee-grants.js | 7/7 | 100% |
+| JS session-manager.js | 1/1 | 100% |
+| JS batch.js | 1/1 | 100% |
+| C# ChainClient.Queries | 13/13 | 100% |
+| C# ChainClient.FeeGrants | 2/2 | 100% |
+
+---
+
 ## Documentation Versions
 
 | Version | Date | Changes |

package/batch.js

@@ -25,14 +25,13 @@
  */
 
 import { ChainError, ErrorCodes } from './errors.js';
-import { sleep } from './defaults.js';
+import { sleep, DEFAULT_LCD } from './defaults.js';
 import {
   broadcast,
   extractAllSessionIds,
-  findExistingSession,
-  lcdPaginatedSafe,
   MSG_TYPES,
 } from './cosmjs-setup.js';
+import { findExistingSession, querySessions } from './chain/queries.js';
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
@@ -247,7 +246,7 @@ async function _processBatch(client, account, batch, gigabytes, denom, ctx) {
 export async function waitForBatchSessions(nodeAddrs, walletAddr, lcdUrl, options = {}) {
   const maxWaitMs = options.maxWaitMs ?? DEFAULT_POLL_TIMEOUT;
   const pollIntervalMs = options.pollIntervalMs ?? 2000;
-  const baseLcd = lcdUrl || 'https://lcd.sentinel.co';
+  const baseLcd = lcdUrl || DEFAULT_LCD;
 
   if (nodeAddrs.length === 0) return { confirmed: [], pending: [] };
 
@@ -257,18 +256,15 @@ export async function waitForBatchSessions(nodeAddrs, walletAddr, lcdUrl, option
   while (pending.size > 0 && Date.now() < deadline) {
     await sleep(pollIntervalMs);
     try {
-      const result = await lcdPaginatedSafe(
-        baseLcd,
-        `/sentinel/session/v3/sessions?address=${walletAddr}&status=1`,
-        'sessions',
-      );
+      // RPC-first via chain/queries.js — returns flattened sessions
+      const result = await querySessions(walletAddr, baseLcd, { status: '1' });
       for (const s of (result.items || [])) {
         const bs = s.base_session || s;
         const n = bs.node_address || bs.node;
         if (pending.has(n)) pending.delete(n);
       }
     } catch {
-      // Transient LCD error — will retry on next poll
+      // Transient RPC/LCD error — will retry on next poll
     }
   }
 

package/chain/authz.js

@@ -11,7 +11,6 @@
 
 import { protoString, protoEmbedded, protoInt64 } from '../v3protocol.js';
 import { ChainError, ErrorCodes } from '../errors.js';
-import { lcd, lcdPaginatedSafe } from './lcd.js';
 import { buildRegistry } from './client.js';
 
 // ─── Protobuf Helpers ───────────────────────────────────────────────────────
@@ -99,11 +98,4 @@ export function encodeForExec(msgs) {
   });
 }
 
-/**
- * Query authz grants between granter and grantee.
- * @returns {Promise<Array>} Array of grant objects
- */
-export async function queryAuthzGrants(lcdUrl, granter, grantee) {
-  const { items } = await lcdPaginatedSafe(lcdUrl, `/cosmos/authz/v1beta1/grants?granter=${granter}&grantee=${grantee}`, 'grants');
-  return items;
-}
+// queryAuthzGrants removed — use RPC-first version from chain/queries.js

package/chain/fee-grants.js

@@ -13,9 +13,15 @@ import { EventEmitter } from 'events';
 import { protoString, protoInt64, protoEmbedded } from '../v3protocol.js';
 import { LCD_ENDPOINTS } from '../defaults.js';
 import { ValidationError, ErrorCodes } from '../errors.js';
-import { lcd, lcdPaginatedSafe, lcdQueryAll } from './lcd.js';
+import { lcdQuery, lcdPaginatedSafe } from './lcd.js';
 import { isSameKey } from './wallet.js';
 import { queryPlanSubscribers } from './queries.js';
+import {
+  createRpcQueryClientWithFallback,
+  rpcQueryFeeGrant as _rpcQueryFeeGrant,
+  rpcQueryFeeGrants as _rpcQueryFeeGrants,
+  rpcQueryFeeGrantsIssued as _rpcQueryFeeGrantsIssued,
+} from './rpc.js';
 
 // ─── Protobuf Helpers for FeeGrant ──────────────────────────────────────────
 // Uses the same manual protobuf encoding as Sentinel types — no codegen needed.
@@ -60,6 +66,21 @@ function encodeAny(typeUrl, valueBytes) {
   ]);
 }
 
+// ─── RPC Client Helper ─────────────────────────────────────────────────────
+
+let _rpcClient = null;
+let _rpcClientPromise = null;
+
+async function getRpcClient() {
+  if (_rpcClient) return _rpcClient;
+  if (_rpcClientPromise) return _rpcClientPromise;
+  _rpcClientPromise = createRpcQueryClientWithFallback()
+    .then(client => { _rpcClient = client; return client; })
+    .catch(() => { _rpcClient = null; return null; })
+    .finally(() => { _rpcClientPromise = null; });
+  return _rpcClientPromise;
+}
+
 // ─── FeeGrant (cosmos.feegrant.v1beta1) ─────────────────────────────────────
 
 /**
@@ -105,31 +126,61 @@ export function buildRevokeFeeGrantMsg(granter, grantee) {
 
 /**
  * Query fee grants given to a grantee.
+ * RPC-first with LCD fallback.
  * @returns {Promise<Array>} Array of allowance objects
  */
 export async function queryFeeGrants(lcdUrl, grantee) {
+  // RPC-first
+  try {
+    const rpc = await getRpcClient();
+    if (rpc) {
+      return await _rpcQueryFeeGrants(rpc, grantee);
+    }
+  } catch { /* fall through to LCD */ }
+
+  // LCD fallback
   const { items } = await lcdPaginatedSafe(lcdUrl, `/cosmos/feegrant/v1beta1/allowances/${grantee}`, 'allowances');
   return items;
 }
 
 /**
  * Query fee grants issued BY an address (where addr is the granter).
+ * RPC-first with LCD fallback.
  * @param {string} lcdUrl
  * @param {string} granter - Address that issued the grants
  * @returns {Promise<Array>}
  */
 export async function queryFeeGrantsIssued(lcdUrl, granter) {
+  // RPC-first
+  try {
+    const rpc = await getRpcClient();
+    if (rpc) {
+      return await _rpcQueryFeeGrantsIssued(rpc, granter);
+    }
+  } catch { /* fall through to LCD */ }
+
+  // LCD fallback
   const { items } = await lcdPaginatedSafe(lcdUrl, `/cosmos/feegrant/v1beta1/issued/${granter}`, 'allowances');
   return items;
 }
 
 /**
  * Query a specific fee grant between granter and grantee.
+ * RPC-first with LCD fallback.
  * @returns {Promise<object|null>} Allowance object or null
  */
 export async function queryFeeGrant(lcdUrl, granter, grantee) {
+  // RPC-first
+  try {
+    const rpc = await getRpcClient();
+    if (rpc) {
+      return await _rpcQueryFeeGrant(rpc, granter, grantee);
+    }
+  } catch { /* fall through to LCD */ }
+
+  // LCD fallback (with endpoint failover via lcdQuery)
   try {
-    const data = await lcd(lcdUrl, `/cosmos/feegrant/v1beta1/allowance/${granter}/${grantee}`);
+    const data = await lcdQuery(`/cosmos/feegrant/v1beta1/allowance/${granter}/${grantee}`, { lcdUrl });
     return data.allowance || null;
   } catch { return null; } // 404 = no grant
 }

package/chain/index.js

@@ -50,6 +50,19 @@ import { publicEndpointAgent } from '../security/index.js';
 // Wallet — validation helpers (used by chain functions that validate addresses)
 import { validateMnemonic, validateAddress } from '../wallet/index.js';
 
+// RPC-first query modules — delegates LCD-only functions to these
+import {
+  findExistingSession as _rpcFindExistingSession,
+  fetchActiveNodes as _rpcFetchActiveNodes,
+  getNetworkOverview as _rpcGetNetworkOverview,
+  getNodePrices as _rpcGetNodePrices,
+  discoverPlanIds as _rpcDiscoverPlanIds,
+} from './queries.js';
+import {
+  queryFeeGrants as _rpcQueryFeeGrants,
+  queryFeeGrant as _rpcQueryFeeGrant,
+} from './fee-grants.js';
+
 // ─── All Type URL Constants ──────────────────────────────────────────────────
 
 export const MSG_TYPES = {
@@ -345,19 +358,10 @@ export function txResponse(result) {
 /**
  * Find an existing active session for a wallet+node pair.
  * Returns session ID (BigInt) or null. Use this to avoid double-paying.
- *
- * Note: Sessions have a nested base_session object containing the actual data.
+ * Delegates to chain/queries.js RPC-first implementation.
  */
 export async function findExistingSession(lcdUrl, walletAddr, nodeAddr) {
-  const data = await lcd(lcdUrl, `/sentinel/session/v3/sessions?address=${walletAddr}&status=1&pagination.limit=100`);
-  for (const s of (data.sessions || [])) {
-    const bs = s.base_session || s; // session data is nested in base_session
-    if (bs.node_address !== nodeAddr) continue;
-    const maxBytes = parseInt(bs.max_bytes || '0');
-    const used = parseInt(bs.download_bytes || '0') + parseInt(bs.upload_bytes || '0');
-    if (maxBytes === 0 || used < maxBytes) return BigInt(bs.id);
-  }
-  return null;
+  return _rpcFindExistingSession(lcdUrl, walletAddr, nodeAddr);
 }
 
 /**
@@ -377,176 +381,44 @@ export function resolveNodeUrl(node) {
 }
 
 /**
- * Fetch all active nodes from LCD with pagination.
+ * Fetch all active nodes with RPC-first + LCD fallback.
  * Returns array of node objects. Each node has `remote_url` resolved from `remote_addrs`.
+ * Delegates to chain/queries.js RPC-first implementation.
  */
 export async function fetchActiveNodes(lcdUrl, limit = 500, maxPages = 20) {
-  const nodes = [];
-  let nextKey = null;
-  let page = 0;
-  do {
-    const keyParam = nextKey ? `&pagination.key=${encodeURIComponent(nextKey)}` : '';
-    const data = await lcd(lcdUrl, `/sentinel/node/v3/nodes?status=1&pagination.limit=${limit}${keyParam}`);
-    nodes.push(...(data.nodes || []));
-    nextKey = data.pagination?.next_key || null;
-    page++;
-  } while (nextKey && page < maxPages);
-  // Add computed remote_url for backward compatibility
-  for (const n of nodes) {
-    try { n.remote_url = resolveNodeUrl(n); } catch { /* skip nodes with no address */ }
-  }
-  return nodes;
+  return _rpcFetchActiveNodes(lcdUrl, limit, maxPages);
 }
 
 /**
  * Get a quick network overview — total nodes, counts by country and service type, average prices.
- * Perfect for dashboard UIs, onboarding screens, and network health displays.
+ * Delegates to chain/queries.js RPC-first implementation.
  *
  * @param {string} [lcdUrl] - LCD endpoint (default: cascading fallback)
  * @returns {Promise<{ totalNodes: number, byCountry: Array<{country: string, count: number}>, byType: {wireguard: number, v2ray: number, unknown: number}, averagePrice: {gigabyteDvpn: number, hourlyDvpn: number}, nodes: Array }>}
- *
- * @example
- *   const overview = await getNetworkOverview();
- *   console.log(`${overview.totalNodes} nodes across ${overview.byCountry.length} countries`);
- *   console.log(`Average: ${overview.averagePrice.gigabyteDvpn.toFixed(3)} P2P/GB`);
  */
 export async function getNetworkOverview(lcdUrl) {
-  const fetchFn = async (url) => fetchActiveNodes(url);
-  let nodes;
-  if (lcdUrl) {
-    nodes = await fetchFn(lcdUrl);
-  } else {
-    const result = await tryWithFallback(LCD_ENDPOINTS, fetchFn, 'getNetworkOverview');
-    nodes = result.result;
-  }
-
-  // Filter to nodes that accept udvpn
-  const active = nodes.filter(n => n.remote_url && (n.gigabyte_prices || []).some(p => p.denom === 'udvpn'));
-
-  // Count by country (from LCD metadata, limited — enrichNodes gives better data)
-  const countryMap = {};
-  for (const n of active) {
-    const c = n.location?.country || n.country || 'Unknown';
-    countryMap[c] = (countryMap[c] || 0) + 1;
-  }
-  const byCountry = Object.entries(countryMap)
-    .map(([country, count]) => ({ country, count }))
-    .sort((a, b) => b.count - a.count);
-
-  // Count by type (type not in LCD — estimate from service_type field if present)
-  const byType = { wireguard: 0, v2ray: 0, unknown: 0 };
-  for (const n of active) {
-    const t = n.service_type || n.type;
-    if (t === 'wireguard' || t === 1) byType.wireguard++;
-    else if (t === 'v2ray' || t === 2) byType.v2ray++;
-    else byType.unknown++;
-  }
-
-  // Average prices
-  let gbTotal = 0, gbCount = 0, hrTotal = 0, hrCount = 0;
-  for (const n of active) {
-    const gb = (n.gigabyte_prices || []).find(p => p.denom === 'udvpn');
-    if (gb?.quote_value) { gbTotal += parseInt(gb.quote_value, 10); gbCount++; }
-    const hr = (n.hourly_prices || []).find(p => p.denom === 'udvpn');
-    if (hr?.quote_value) { hrTotal += parseInt(hr.quote_value, 10); hrCount++; }
-  }
-
-  return {
-    totalNodes: active.length,
-    byCountry,
-    byType,
-    averagePrice: {
-      gigabyteDvpn: gbCount > 0 ? (gbTotal / gbCount) / 1_000_000 : 0,
-      hourlyDvpn: hrCount > 0 ? (hrTotal / hrCount) / 1_000_000 : 0,
-    },
-    nodes: active,
-  };
+  return _rpcGetNetworkOverview(lcdUrl);
 }
 
 /**
  * Discover plan IDs by probing subscription endpoints.
- * Workaround for /sentinel/plan/v3/plans returning 501 Not Implemented.
+ * Delegates to chain/queries.js RPC-first implementation.
  * Returns sorted array of plan IDs that have at least 1 subscription.
  */
 export async function discoverPlanIds(lcdUrl, maxId = 100) {
-  const ids = [];
-  const batchSize = 10;
-  for (let batch = 0; batch < maxId / batchSize; batch++) {
-    const checks = [];
-    for (let i = batch * batchSize + 1; i <= (batch + 1) * batchSize; i++) {
-      checks.push(
-        lcd(lcdUrl, `/sentinel/subscription/v3/plans/${i}/subscriptions?pagination.limit=1&pagination.count_total=true`)
-          .then(d => { if (parseInt(d.pagination?.total || '0') > 0) ids.push(i); })
-          .catch(() => {})
-      );
-    }
-    await Promise.all(checks);
-  }
-  return ids.sort((a, b) => a - b);
+  return _rpcDiscoverPlanIds(lcdUrl, maxId);
 }
 
 /**
- * Get standardized prices for a node — abstracts V3 LCD price parsing entirely.
- *
- * Solves the common "NaN / GB" problem by defensively extracting quote_value,
- * base_value, or amount from the nested LCD response structure.
+ * Get standardized prices for a node — abstracts V3 price parsing entirely.
+ * Delegates to chain/queries.js RPC-first implementation (direct node lookup, not full-list scan).
  *
  * @param {string} nodeAddress - sentnode1... address
  * @param {string} [lcdUrl] - LCD endpoint URL (default: cascading fallback across all endpoints)
  * @returns {Promise<{ gigabyte: { dvpn: number, udvpn: number, raw: object|null }, hourly: { dvpn: number, udvpn: number, raw: object|null }, denom: string, nodeAddress: string }>}
- *
- * @example
- *   const prices = await getNodePrices('sentnode1abc...');
- *   console.log(`${prices.gigabyte.dvpn} P2P/GB, ${prices.hourly.dvpn} P2P/hr`);
- *   // Use prices.gigabyte.raw for the full { denom, base_value, quote_value } object
- *   // needed by encodeMsgStartSession's max_price field.
  */
 export async function getNodePrices(nodeAddress, lcdUrl) {
-  if (typeof nodeAddress !== 'string' || !/^sentnode1[a-z0-9]{38}$/.test(nodeAddress)) {
-    throw new ValidationError(ErrorCodes.INVALID_NODE_ADDRESS, 'nodeAddress must be a valid sentnode1... bech32 address (46 characters)', { value: nodeAddress });
-  }
-
-  const fetchNode = async (baseUrl) => {
-    let nextKey = null;
-    let pages = 0;
-    do {
-      const keyParam = nextKey ? `&pagination.key=${encodeURIComponent(nextKey)}` : '';
-      const data = await lcd(baseUrl, `/sentinel/node/v3/nodes?status=1&pagination.limit=500${keyParam}`);
-      const nodes = data.nodes || [];
-      const found = nodes.find(n => n.address === nodeAddress);
-      if (found) return found;
-      nextKey = data.pagination?.next_key || null;
-      pages++;
-    } while (nextKey && pages < 20);
-    return null;
-  };
-
-  let node;
-  if (lcdUrl) {
-    node = await fetchNode(lcdUrl);
-  } else {
-    const result = await tryWithFallback(LCD_ENDPOINTS, fetchNode, 'getNodePrices');
-    node = result.result;
-  }
-
-  if (!node) throw new NodeError(ErrorCodes.NODE_NOT_FOUND, `Node ${nodeAddress} not found on LCD (may be inactive or deregistered)`, { nodeAddress });
-
-  function extractPrice(priceArray) {
-    if (!Array.isArray(priceArray)) return { dvpn: 0, udvpn: 0, raw: null };
-    const entry = priceArray.find(p => p.denom === 'udvpn');
-    if (!entry) return { dvpn: 0, udvpn: 0, raw: null };
-    // Defensive fallback chain: quote_value (V3 current) -> base_value -> amount (legacy)
-    const rawVal = entry.quote_value || entry.base_value || entry.amount || '0';
-    const udvpn = parseInt(rawVal, 10) || 0;
-    return { dvpn: parseFloat((udvpn / 1_000_000).toFixed(6)), udvpn, raw: entry };
-  }
-
-  return {
-    gigabyte: extractPrice(node.gigabyte_prices),
-    hourly: extractPrice(node.hourly_prices),
-    denom: 'P2P',
-    nodeAddress,
-  };
+  return _rpcGetNodePrices(nodeAddress, lcdUrl);
 }
 
 // ─── Display & Serialization Helpers ────────────────────────────────────────
@@ -761,22 +633,20 @@ export function buildRevokeFeeGrantMsg(granter, grantee) {
 
 /**
  * Query fee grants given to a grantee.
+ * Delegates to chain/fee-grants.js RPC-first implementation.
  * @returns {Promise<Array>} Array of allowance objects
  */
 export async function queryFeeGrants(lcdUrl, grantee) {
-  const data = await lcd(lcdUrl, `/cosmos/feegrant/v1beta1/allowances/${grantee}`);
-  return data.allowances || [];
+  return _rpcQueryFeeGrants(lcdUrl, grantee);
 }
 
 /**
  * Query a specific fee grant between granter and grantee.
+ * Delegates to chain/fee-grants.js RPC-first implementation.
  * @returns {Promise<object|null>} Allowance object or null
  */
 export async function queryFeeGrant(lcdUrl, granter, grantee) {
-  try {
-    const data = await lcd(lcdUrl, `/cosmos/feegrant/v1beta1/allowance/${granter}/${grantee}`);
-    return data.allowance || null;
-  } catch { return null; } // 404 = no grant
+  return _rpcQueryFeeGrant(lcdUrl, granter, grantee);
 }
 
 /**
@@ -878,14 +748,7 @@ export function encodeForExec(msgs) {
   });
 }
 
-/**
- * Query authz grants between granter and grantee.
- * @returns {Promise<Array>} Array of grant objects
- */
-export async function queryAuthzGrants(lcdUrl, granter, grantee) {
-  const data = await lcd(lcdUrl, `/cosmos/authz/v1beta1/grants?granter=${granter}&grantee=${grantee}`);
-  return data.grants || [];
-}
+// queryAuthzGrants removed — use RPC-first version from chain/queries.js
 
 // Re-export extractSessionId for convenience (from protocol module)
 export { extractSessionId };

package/chain/queries.js

@@ -30,6 +30,8 @@ import {
   rpcQuerySubscriptionAllocations as rpcQuerySubAllocations,
   rpcQueryPlan,
   rpcQueryBalance,
+  rpcQueryProvider as _rpcQueryProvider,
+  rpcQueryAuthzGrants as _rpcQueryAuthzGrants,
 } from './rpc.js';
 
 // Re-export for convenience
@@ -54,6 +56,15 @@ async function getRpcClient() {
   return _rpcClientPromise;
 }
 
+/**
+ * Clear the cached RPC query client. Called during process cleanup
+ * to ensure WebSocket connections are properly closed.
+ */
+export function resetQueryRpcCache() {
+  _rpcClient = null;
+  _rpcClientPromise = null;
+}
+
 // ─── Query Helpers ───────────────────────────────────────────────────────────
 
 /**
@@ -342,9 +353,9 @@ export async function querySessionById(lcdUrl, sessionId) {
     }
   } catch { /* fall through to LCD */ }
 
-  // LCD fallback
+  // LCD fallback (with endpoint failover via lcdQuery)
   try {
-    const data = await lcd(lcdUrl, `/sentinel/session/v3/sessions/${sessionId}`);
+    const data = await lcdQuery(`/sentinel/session/v3/sessions/${sessionId}`, { lcdUrl });
     const raw = data?.session;
     if (!raw) return null;
     return flattenSession(raw);
@@ -370,9 +381,9 @@ export async function querySessionAllocation(lcdUrl, sessionId) {
   } catch { /* fall through */ }
 
   if (!s) {
-    // LCD fallback
+    // LCD fallback (with endpoint failover via lcdQuery)
     try {
-      const data = await lcd(lcdUrl, `/sentinel/session/v3/sessions/${sessionId}`);
+      const data = await lcdQuery(`/sentinel/session/v3/sessions/${sessionId}`, { lcdUrl });
       s = data.session?.base_session || data.session || null;
     } catch { return null; }
   }
@@ -674,7 +685,7 @@ export async function queryPlanNodes(planId, lcdUrl) {
 
 /**
  * Discover all available plans with metadata (subscriber count, node count, price).
- * Probes plan IDs 1-maxId, returns plans with >=1 subscriber.
+ * RPC-first: probes plan IDs via rpcQueryPlan, falls back to LCD.
  *
  * @param {string} [lcdUrl]
  * @param {object} [opts]
@@ -690,19 +701,61 @@ export async function discoverPlans(lcdUrl, opts = {}) {
   const baseLcd = lcdUrl || LCD_ENDPOINTS[0].url;
   const plans = [];
 
+  // Try to get RPC client for plan queries
+  let rpc = null;
+  try { rpc = await getRpcClient(); } catch { /* LCD only */ }
+
   for (let batch = 0; batch < Math.ceil(maxId / batchSize); batch++) {
     const probes = [];
     for (let i = batch * batchSize + 1; i <= Math.min((batch + 1) * batchSize, maxId); i++) {
       probes.push((async (id) => {
         try {
-          const subData = await lcd(baseLcd, `/sentinel/subscription/v3/plans/${id}/subscriptions?pagination.limit=1&pagination.count_total=true`);
-          const subCount = parseInt(subData.pagination?.total || '0', 10);
+          // RPC-first: query plan existence via RPC
+          let plan = null;
+          if (rpc) {
+            try { plan = await rpcQueryPlan(rpc, id); } catch { /* fall through */ }
+          }
+
+          // Get subscriber count — RPC for plan subs, LCD as fallback
+          let subCount = 0;
+          let price = null;
+          if (rpc) {
+            try {
+              const subs = await rpcQuerySubscriptionsForPlan(rpc, id, { limit: 1 });
+              subCount = subs.length; // Quick check — at least 1
+              price = subs[0]?.price || null;
+              // If RPC returned subs, plan exists even if rpcQueryPlan returned null
+              if (subCount > 0 && !plan) plan = { id };
+            } catch { /* fall through */ }
+          }
+          if (!plan && subCount === 0) {
+            // LCD fallback for subscriber count
+            try {
+              const subData = await lcd(baseLcd, `/sentinel/subscription/v3/plans/${id}/subscriptions?pagination.limit=1&pagination.count_total=true`);
+              subCount = parseInt(subData.pagination?.total || '0', 10);
+              price = subData.subscriptions?.[0]?.price || null;
+              if (subCount > 0) plan = { id };
+            } catch { /* plan doesn't exist */ }
+          }
+
+          if (!plan && !includeEmpty) return null;
           if (subCount === 0 && !includeEmpty) return null;
-          // Plan nodes endpoint has broken pagination (count_total wrong, next_key null).
-          // Use limit=5000 single request and count the actual array.
-          const nodeData = await lcd(baseLcd, `/sentinel/node/v3/plans/${id}/nodes?pagination.limit=5000`);
-          const nodeCount = (nodeData.nodes || []).length;
-          const price = subData.subscriptions?.[0]?.price || null;
+
+          // Get node count — RPC-first
+          let nodeCount = 0;
+          if (rpc) {
+            try {
+              const nodes = await rpcQueryNodesForPlan(rpc, id, { status: 1, limit: 5000 });
+              nodeCount = nodes.length;
+            } catch { /* fall through to LCD */ }
+          }
+          if (nodeCount === 0) {
+            try {
+              const nodeData = await lcd(baseLcd, `/sentinel/node/v3/plans/${id}/nodes?pagination.limit=5000`);
+              nodeCount = (nodeData.nodes || []).length;
+            } catch { /* no nodes */ }
+          }
+
           return { id, subscribers: subCount, nodeCount, price, hasNodes: nodeCount > 0 };
         } catch { return null; }
       })(i));
@@ -716,18 +769,51 @@ export async function discoverPlans(lcdUrl, opts = {}) {
 
 /**
  * Get provider details by address.
+ * RPC-first with LCD fallback. Provider is still v2 on chain.
  * @param {string} provAddress - sentprov1... address
  * @param {object} [opts]
  * @param {string} [opts.lcdUrl]
  * @returns {Promise<object|null>}
  */
 export async function getProviderByAddress(provAddress, opts = {}) {
+  // RPC-first
+  try {
+    const rpc = await getRpcClient();
+    if (rpc) {
+      const provider = await _rpcQueryProvider(rpc, provAddress);
+      if (provider) return provider;
+    }
+  } catch { /* fall through to LCD */ }
+
+  // LCD fallback
   try {
     const data = await lcdQuery(`/sentinel/provider/v2/providers/${provAddress}`, opts);
     return data.provider || null;
   } catch { return null; }
 }
 
+/**
+ * Query authz grants between granter and grantee.
+ * RPC-first with LCD fallback.
+ * @param {string} lcdUrl - LCD endpoint
+ * @param {string} granter - Granter address (sent1...)
+ * @param {string} grantee - Grantee address (sent1...)
+ * @returns {Promise<Array>}
+ */
+export async function queryAuthzGrants(lcdUrl, granter, grantee) {
+  // RPC-first
+  try {
+    const rpc = await getRpcClient();
+    if (rpc) {
+      return await _rpcQueryAuthzGrants(rpc, granter, grantee);
+    }
+  } catch { /* fall through to LCD */ }
+
+  // LCD fallback
+  const { items } = await lcdPaginatedSafe(lcdUrl, `/cosmos/authz/v1beta1/grants?granter=${granter}&grantee=${grantee}`, 'grants');
+  return items;
+}
+
 // ─── VPN Settings Persistence ────────────────────────────────────────────────
 // v27: Persistent user settings (backported from C# VpnSettings.cs).
 // Stores preferences in ~/.sentinel-sdk/settings.json with restrictive permissions.