blue-js-sdk 2.4.0 → 2.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 JavaScript/TypeScript SDK for the [Sentinel](https://sentinel.co) decentralized VPN network. WireGuard + V2Ray tunnels, Cosmos blockchain, 900+ nodes. RPC queries, typed events, CosmJS compatible.
 
-**Also available:** [Blue C# SDK](https://github.com/Sentinel-Autonomybuilder/blue-csharp-sdk) | [Blue AI Connect](https://github.com/Sentinel-Autonomybuilder/blue-ai-connect) (zero-config wrapper for AI agents)
+**Also available:** [Blue C# SDK](https://github.com/Sentinel-Autonomybuilder/blue-csharp-sdk) | [Blue Agent Connect](https://github.com/Sentinel-Autonomybuilder/blue-agent-connect) (zero-config wrapper for AI agents)
 
 ## Platform Support
 
@@ -18,7 +18,7 @@ JavaScript/TypeScript SDK for the [Sentinel](https://sentinel.co) decentralized
 
 ---
 
-> **For AI agents:** If you just want `connect()` with one function call, use [`blue-ai-connect`](https://www.npmjs.com/package/blue-ai-connect) instead.
+> **For AI agents:** If you just want `connect()` with one function call, use [`blue-agent-connect`](https://www.npmjs.com/package/blue-agent-connect) instead.
 
 ## Install
 
@@ -46,7 +46,7 @@ await disconnect();
 
 ## For AI Agents
 
-Use [sentinel-ai-connect](https://www.npmjs.com/package/sentinel-ai-connect) — a zero-config wrapper with one function call from zero to encrypted tunnel.
+Use [blue-agent-connect](https://www.npmjs.com/package/blue-agent-connect) — a zero-config wrapper with one function call from zero to encrypted tunnel.
 
 ## Features
 

package/app-helpers.js

@@ -72,6 +72,15 @@ export const COUNTRY_MAP = Object.freeze({
   'pr': 'PR', 'cn': 'CN', 'sa': 'SA', 'kz': 'KZ', 'mn': 'MN', 'sk': 'SK',
   'al': 'AL', 'md': 'MD', 'jm': 'JM', 'bo': 'BO', 'ec': 'EC', 'uy': 'UY',
   'bh': 'BH', 'cd': 'CD',
+
+  // Central Asia
+  'kyrgyzstan': 'KG', 'uzbekistan': 'UZ', 'tajikistan': 'TJ',
+  'kg': 'KG', 'uz': 'UZ', 'tj': 'TJ',
+
+  // Balkans
+  'bosnia and herzegovina': 'BA', 'north macedonia': 'MK', 'montenegro': 'ME',
+  'kosovo': 'XK', 'slovenia': 'SI',
+  'ba': 'BA', 'mk': 'MK', 'me': 'ME', 'xk': 'XK', 'si': 'SI',
 });
 
 /**
@@ -286,6 +295,52 @@ export function groupNodesByCountry(nodes) {
   });
 }
 
+// ─── Country → Continent Map ────────────────────────────────────────────────
+// Continent classification for every ISO code present in COUNTRY_MAP.
+// Codes follow ISO 3166-1 alpha-2 regions: EU/AS/NA/SA/AF/OC (+ AN, ZZ).
+
+export const CONTINENT_BY_CODE = Object.freeze({
+  // Europe
+  DE: 'EU', FR: 'EU', GB: 'EU', NL: 'EU', ES: 'EU', IT: 'EU', SE: 'EU', NO: 'EU',
+  FI: 'EU', CH: 'EU', AT: 'EU', IE: 'EU', PT: 'EU', CZ: 'EU', HU: 'EU', BG: 'EU',
+  GR: 'EU', UA: 'EU', RU: 'EU', RO: 'EU', PL: 'EU', TR: 'EU', LV: 'EU', LT: 'EU',
+  EE: 'EU', HR: 'EU', RS: 'EU', DK: 'EU', BE: 'EU', LU: 'EU', MT: 'EU', CY: 'EU',
+  IS: 'EU', SK: 'EU', AL: 'EU', MD: 'EU', BA: 'EU', MK: 'EU', ME: 'EU', XK: 'EU',
+  SI: 'EU', GE: 'EU',
+  // Asia
+  JP: 'AS', SG: 'AS', IN: 'AS', KR: 'AS', HK: 'AS', TW: 'AS', TH: 'AS', VN: 'AS',
+  ID: 'AS', PH: 'AS', MY: 'AS', BD: 'AS', PK: 'AS', CN: 'AS', SA: 'AS', KZ: 'AS',
+  MN: 'AS', IL: 'AS', AE: 'AS', KG: 'AS', UZ: 'AS', TJ: 'AS', BH: 'AS',
+  // North America
+  US: 'NA', CA: 'NA', MX: 'NA', GT: 'NA', PR: 'NA', JM: 'NA', CR: 'NA', PA: 'NA',
+  DO: 'NA', SV: 'NA', HN: 'NA', NI: 'NA', CU: 'NA', HT: 'NA', TT: 'NA',
+  // South America
+  BR: 'SA', AR: 'SA', CL: 'SA', CO: 'SA', PE: 'SA', VE: 'SA', BO: 'SA', EC: 'SA',
+  UY: 'SA', PY: 'SA',
+  // Africa
+  ZA: 'AF', NG: 'AF', EG: 'AF', KE: 'AF', MA: 'AF', CD: 'AF',
+  // Oceania
+  AU: 'OC', NZ: 'OC',
+});
+
+export const CONTINENT_NAMES = Object.freeze({
+  EU: 'Europe', AS: 'Asia', NA: 'North America', SA: 'South America',
+  AF: 'Africa', OC: 'Oceania', AN: 'Antarctica', ZZ: 'Unknown',
+});
+
+/**
+ * Map a country (name or ISO code) to a continent code.
+ *
+ * @param {string} country - Country name (any variant in COUNTRY_MAP) or 2-letter ISO code
+ * @returns {string|null} 'EU' | 'AS' | 'NA' | 'SA' | 'AF' | 'OC' | null
+ */
+export function countryToContinent(country) {
+  if (!country) return null;
+  const code = country.length === 2 ? country.toUpperCase() : countryNameToCode(country);
+  if (!code) return null;
+  return CONTINENT_BY_CODE[code] || null;
+}
+
 // ─── Session Duration Helpers ───────────────────────────────────────────────
 
 /** Common hour options for hourly session selection UI. */

package/chain/broadcast.js

@@ -142,6 +142,33 @@ export function createSafeBroadcaster(rpcUrl, wallet, signerAddress) {
   return { safeBroadcast, getClient, resetClient };
 }
 
+// ─── Shared Broadcast Pool (per-key serialization) ──────────────────────────
+// For servers handling multiple concurrent wallets. Each wallet address gets
+// its own queue so wallet A's TX never blocks wallet B. Single-wallet
+// consumers (CLI tools) can pass any string as key — behavior is identical
+// to a single-instance createSafeBroadcaster.
+
+const _globalQueues = new Map();
+
+/**
+ * Serialize a broadcast behind a per-key queue without creating a full
+ * createSafeBroadcaster instance. Useful when the caller already has a
+ * signing client and only needs sequence-safe serialization per wallet.
+ *
+ * @param {string} key - Wallet address (or any unique string per logical sender)
+ * @param {() => Promise<any>} fn - Async function to serialize
+ * @returns {Promise<any>}
+ */
+export function withBroadcastQueue(key, fn) {
+  const prev = _globalQueues.get(key) ?? Promise.resolve();
+  const p = prev.then(fn);
+  _globalQueues.set(key, p.catch(() => {}));
+  p.finally(() => {
+    if (_globalQueues.get(key) === p) _globalQueues.delete(key);
+  });
+  return p;
+}
+
 /**
  * Broadcast a TX with fee paid by a granter (fee grant).
  * The grantee signs; the granter pays gas via their fee allowance.

package/chain/fee-grants.js

@@ -185,6 +185,62 @@ export async function queryFeeGrant(lcdUrl, granter, grantee) {
   } catch { return null; } // 404 = no grant
 }
 
+/**
+ * Builder-friendly fee-grant check. Returns a parsed, normalized status so
+ * callers don't have to walk nested `AllowedMsgAllowance` → `BasicAllowance`
+ * shapes. Use this before broadcasting plan/subscription sessions that rely on
+ * a granter paying gas.
+ *
+ * RPC-first with LCD fallback. Either both granter+grantee, or pre-fetched
+ * allowance object can be passed.
+ *
+ * @param {string} lcdUrl - LCD endpoint (for fallback)
+ * @param {string} granter - sent1... granter address
+ * @param {string} grantee - sent1... grantee address
+ * @returns {Promise<{ exists: boolean, expired: boolean, expiresAt: Date|null, spendLimit: Array<{denom:string,amount:string}>, allowedMessages: string[]|null, typeUrl: string, raw: object|null }>}
+ */
+export async function checkFeeGrant(lcdUrl, granter, grantee) {
+  const allowance = await queryFeeGrant(lcdUrl, granter, grantee);
+  if (!allowance) {
+    return {
+      exists: false,
+      expired: false,
+      expiresAt: null,
+      spendLimit: [],
+      allowedMessages: null,
+      typeUrl: '',
+      raw: null,
+    };
+  }
+
+  // If shape is { granter, grantee, allowance: {...} } from rpcQueryFeeGrant
+  const inner = allowance.allowance || allowance;
+  const typeUrl = inner['@type'] || '';
+  let basic = inner;
+  let allowedMessages = null;
+  if (typeUrl.includes('AllowedMsgAllowance')) {
+    allowedMessages = inner.allowed_messages || [];
+    basic = inner.allowance || null;
+  }
+
+  const spendLimit = (basic?.spend_limit || []).map(c => ({
+    denom: c.denom,
+    amount: String(c.amount || '0'),
+  }));
+  const expiresAt = basic?.expiration ? new Date(basic.expiration) : null;
+  const expired = expiresAt ? expiresAt.getTime() <= Date.now() : false;
+
+  return {
+    exists: true,
+    expired,
+    expiresAt,
+    spendLimit,
+    allowedMessages,
+    typeUrl,
+    raw: allowance,
+  };
+}
+
 // ─── Fee Grant Workflow Helpers (v25b) ────────────────────────────────────────
 
 /**
@@ -194,19 +250,26 @@ export async function queryFeeGrant(lcdUrl, granter, grantee) {
  * @param {number|string} planId
  * @param {object} opts
  * @param {string} opts.granterAddress - Who pays fees (typically plan owner)
- * @param {string} opts.lcdUrl - LCD endpoint
+ * @param {string} [opts.lcdUrl] - LCD endpoint (used as fallback when RPC unavailable)
+ * @param {boolean} [opts.preferRpc=true] - Force RPC for all queries, skip LCD URL for grant lookup
+ * @param {object} [opts.rpcClient] - Pre-built RPC client to inject (skips internal createRpcQueryClientWithFallback)
  * @param {object} [opts.grantOpts] - Options for buildFeeGrantMsg (spendLimit, expiration, allowedMessages)
  * @returns {Promise<{ msgs: Array, skipped: string[], newGrants: string[] }>} Messages ready for broadcast
  */
 export async function grantPlanSubscribers(planId, opts = {}) {
-  const { granterAddress, lcdUrl, grantOpts = {} } = opts;
+  const { granterAddress, lcdUrl, preferRpc = true, rpcClient, grantOpts = {} } = opts;
   if (!granterAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'granterAddress is required');
 
-  // Get subscribers
+  // Get subscribers — already RPC-first internally
   const { subscribers } = await queryPlanSubscribers(planId, { lcdUrl });
 
-  // Get existing grants ISSUED BY granter (not grants received)
-  const existingGrants = await queryFeeGrantsIssued(lcdUrl || LCD_ENDPOINTS[0].url, granterAddress);
+  // Get existing grants ISSUED BY granter.
+  // preferRpc=true: pass null lcdUrl so internal getRpcClient() path is taken first.
+  // preferRpc=false: pass lcdUrl so LCD is used (useful when RPC is blocked).
+  const grantLcdUrl = preferRpc ? null : (lcdUrl || LCD_ENDPOINTS[0].url);
+  const existingGrants = rpcClient
+    ? await _rpcQueryFeeGrantsIssued(rpcClient, granterAddress).catch(() => queryFeeGrantsIssued(grantLcdUrl, granterAddress))
+    : await queryFeeGrantsIssued(grantLcdUrl, granterAddress);
   const alreadyGranted = new Set(existingGrants.map(g => g.grantee));
 
   const msgs = [];
@@ -354,3 +417,206 @@ export function monitorFeeGrants(opts = {}) {
 
   return emitter;
 }
+
+// ─── Streaming Batch Grant (for SSE / progress UIs) ──────────────────────────
+
+/**
+ * Stream progress as we grant fee allowances to all plan subscribers in batches.
+ *
+ * Async generator. Yields events with `{ type, ...payload }`:
+ *   - status      { msg }                                  — human-readable status line
+ *   - batch_start { batch, total, count, addresses }       — about to broadcast a batch
+ *   - batch_ok    { batch, total, granted, totalGranted, txHash, elapsed }
+ *   - batch_error { batch, total, error, elapsed }
+ *   - done        { granted, skipped, total, errors? }
+ *   - error       { msg }
+ *
+ * The caller passes a `broadcast(msgs, memo)` function — any safe-broadcaster
+ * with the Plan Manager's mutex + sequence-retry semantics works. Consumer
+ * routes layer SSE (`res.write('data: ...\n\n')`) on top of these events.
+ *
+ * @param {number|string} planId
+ * @param {object} opts
+ * @param {string} opts.granterAddress - Plan owner paying fees
+ * @param {string} [opts.lcdUrl] - LCD endpoint (used as fallback when RPC unavailable)
+ * @param {boolean} [opts.preferRpc=true] - Force RPC for all queries, skip LCD URL for grant lookup
+ * @param {object} [opts.rpcClient] - Pre-built RPC client to inject (skips internal createRpcQueryClientWithFallback)
+ * @param {(msgs: Array, memo: string) => Promise<{code:number, rawLog?:string, transactionHash?:string}>} opts.broadcast
+ * @param {object} [opts.grantOpts] - { spendLimit, expiration } for BasicAllowance
+ * @param {number} [opts.batchSize=5] - Msgs per TX
+ * @param {() => boolean} [opts.isCancelled] - Return true to abort between batches
+ * @yields {{type: string, [key: string]: any}}
+ */
+export async function* streamGrantPlanSubscribers(planId, opts = {}) {
+  const {
+    granterAddress,
+    lcdUrl,
+    preferRpc = true,
+    rpcClient,
+    broadcast,
+    grantOpts = {},
+    batchSize = 5,
+    isCancelled = () => false,
+  } = opts;
+
+  if (!granterAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'granterAddress is required');
+  if (typeof broadcast !== 'function') throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'broadcast function is required');
+
+  try {
+    yield { type: 'status', msg: 'Fetching plan subscribers...' };
+    const { subscribers } = await queryPlanSubscribers(planId, { lcdUrl });
+
+    const now = new Date();
+    const activeSubs = subscribers.filter(s => {
+      if (s.status && s.status !== 'active') return false;
+      if (s.inactive_at && new Date(s.inactive_at) <= now) return false;
+      return true;
+    });
+    const uniqueAddrs = [...new Set(activeSubs.map(s => s.acc_address || s.address))]
+      .filter(a => a && a !== granterAddress && !isSameKey(a, granterAddress));
+
+    yield { type: 'status', msg: `Found ${activeSubs.length} active subscribers (${uniqueAddrs.length} unique, excl. self)` };
+
+    if (uniqueAddrs.length === 0) {
+      yield { type: 'done', granted: 0, skipped: 0, total: 0, msg: 'No active subscribers (excluding self)' };
+      return;
+    }
+
+    yield { type: 'status', msg: 'Checking existing grants...' };
+    const streamLcdUrl = preferRpc ? null : (lcdUrl || LCD_ENDPOINTS[0].url);
+    const existing = rpcClient
+      ? await _rpcQueryFeeGrantsIssued(rpcClient, granterAddress).catch(() => queryFeeGrantsIssued(streamLcdUrl, granterAddress))
+      : await queryFeeGrantsIssued(streamLcdUrl, granterAddress);
+    const existingGrantees = new Set(existing.map(g => g.grantee));
+    const needGrant = uniqueAddrs.filter(a => !existingGrantees.has(a));
+    const skipped = uniqueAddrs.length - needGrant.length;
+
+    yield { type: 'status', msg: `${existingGrantees.size} existing grants found. ${needGrant.length} need granting, ${skipped} already covered.` };
+
+    if (needGrant.length === 0) {
+      yield { type: 'done', granted: 0, skipped, total: 0, msg: 'All subscribers already have grants' };
+      return;
+    }
+
+    const totalBatches = Math.ceil(needGrant.length / batchSize);
+    let granted = 0;
+    const errors = [];
+
+    for (let i = 0; i < needGrant.length; i += batchSize) {
+      if (isCancelled()) break;
+
+      const batchNum = Math.floor(i / batchSize) + 1;
+      const batch = needGrant.slice(i, i + batchSize);
+      const shortAddrs = batch.map(a => a.slice(0, 12) + '...' + a.slice(-6)).join(', ');
+
+      yield { type: 'batch_start', batch: batchNum, total: totalBatches, count: batch.length, addresses: shortAddrs };
+
+      const msgs = batch.map(grantee => buildFeeGrantMsg(granterAddress, grantee, grantOpts));
+
+      const t0 = Date.now();
+      try {
+        const result = await broadcast(msgs, `Fee grant batch ${batchNum}/${totalBatches}`);
+        const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+
+        if (result.code !== 0) {
+          const errMsg = result.rawLog || `TX failed code=${result.code}`;
+          yield { type: 'batch_error', batch: batchNum, total: totalBatches, error: errMsg, elapsed };
+          errors.push(`Batch ${batchNum}: ${errMsg}`);
+        } else {
+          granted += batch.length;
+          yield {
+            type: 'batch_ok',
+            batch: batchNum,
+            total: totalBatches,
+            granted: batch.length,
+            totalGranted: granted,
+            txHash: result.transactionHash,
+            elapsed,
+          };
+        }
+      } catch (e) {
+        const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+        yield { type: 'batch_error', batch: batchNum, total: totalBatches, error: e.message, elapsed };
+        errors.push(`Batch ${batchNum}: ${e.message}`);
+      }
+    }
+
+    yield {
+      type: 'done',
+      granted,
+      skipped,
+      total: needGrant.length,
+      errors: errors.length ? errors : undefined,
+    };
+  } catch (e) {
+    yield { type: 'error', msg: e.message };
+  }
+}
+
+// ─── Gas Cost Analytics ──────────────────────────────────────────────────────
+
+/**
+ * Compute how many udvpn the granter has spent on fee-granted transactions
+ * for a plan's subscribers. Iterates each subscriber, pulls their outgoing
+ * TXs via LCD, and sums fees where `fee.granter === granterAddress`.
+ *
+ * @param {number|string} planId
+ * @param {object} opts
+ * @param {string} opts.granterAddress - Address that paid the fees (plan owner)
+ * @param {string} opts.lcdUrl - LCD endpoint
+ * @param {number} [opts.txLimit=100] - Max TXs to inspect per subscriber
+ * @param {(info: {processed:number, total:number, address:string}) => void} [opts.onProgress]
+ * @returns {Promise<{ totalUdvpn: number, txCount: number, byAddress: Record<string, {udvpn:number, txCount:number}>, subscriberCount: number }>}
+ */
+export async function computeFeeGrantGasCosts(planId, opts = {}) {
+  const { granterAddress, lcdUrl, txLimit = 100, onProgress } = opts;
+  if (!granterAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'granterAddress is required');
+
+  const { subscribers } = await queryPlanSubscribers(planId, { lcdUrl });
+  const subscriberAddrs = [...new Set(subscribers.map(s => s.acc_address || s.address))]
+    .filter(a => a && a !== granterAddress);
+
+  if (subscriberAddrs.length === 0) {
+    return { totalUdvpn: 0, txCount: 0, byAddress: {}, subscriberCount: 0 };
+  }
+
+  let totalUdvpn = 0;
+  let txCount = 0;
+  const byAddress = {};
+
+  const base = lcdUrl || LCD_ENDPOINTS[0].url;
+  for (let idx = 0; idx < subscriberAddrs.length; idx++) {
+    const addr = subscriberAddrs[idx];
+    try {
+      const path =
+        `/cosmos/tx/v1beta1/txs?events=${encodeURIComponent("message.sender='" + addr + "'")}` +
+        `&pagination.limit=${txLimit}&order_by=2`;
+      const txData = await lcdQuery(path, { lcdUrl: base });
+      const rawTxs = txData.txs || [];
+
+      let addrGas = 0;
+      let addrTxCount = 0;
+
+      for (const tx of rawTxs) {
+        const fee = tx?.auth_info?.fee;
+        if (fee?.granter === granterAddress) {
+          const udvpnFee = (fee.amount || []).find(f => f.denom === 'udvpn');
+          if (udvpnFee) {
+            addrGas += parseInt(udvpnFee.amount, 10);
+            addrTxCount++;
+          }
+        }
+      }
+
+      if (addrTxCount > 0) {
+        byAddress[addr] = { udvpn: addrGas, txCount: addrTxCount };
+        totalUdvpn += addrGas;
+        txCount += addrTxCount;
+      }
+    } catch { /* skip this subscriber on LCD failure */ }
+
+    if (onProgress) onProgress({ processed: idx + 1, total: subscriberAddrs.length, address: addr });
+  }
+
+  return { totalUdvpn, txCount, byAddress, subscriberCount: subscriberAddrs.length };
+}

package/chain/index.js

@@ -359,9 +359,15 @@ 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.
  * Delegates to chain/queries.js RPC-first implementation.
+ *
+ * @param {string} lcdUrl - LCD endpoint URL
+ * @param {string} walletAddr - sent1... wallet address
+ * @param {string} nodeAddr - sentnode1... node address
+ * @param {object} [opts] - Optional. Pass `{ onStaleDuplicate: (BigInt) => void }` to
+ *   receive fire-and-forget cancellation callbacks for stale duplicate sessions.
  */
-export async function findExistingSession(lcdUrl, walletAddr, nodeAddr) {
-  return _rpcFindExistingSession(lcdUrl, walletAddr, nodeAddr);
+export async function findExistingSession(lcdUrl, walletAddr, nodeAddr, opts) {
+  return _rpcFindExistingSession(lcdUrl, walletAddr, nodeAddr, opts);
 }
 
 /**

package/chain/queries.js

@@ -32,6 +32,7 @@ import {
   rpcQueryBalance,
   rpcQueryProvider as _rpcQueryProvider,
   rpcQueryAuthzGrants as _rpcQueryAuthzGrants,
+  rpcGetTxByHash,
 } from './rpc.js';
 
 // Re-export for convenience
@@ -81,8 +82,22 @@ export async function getBalance(client, address) {
  * Find an existing active session for a wallet+node pair.
  * Returns session ID (BigInt) or null. Use this to avoid double-paying.
  * RPC-first with LCD fallback.
+ *
+ * Dedup: if multiple active sessions exist for the same node_address (stale
+ * duplicates from crashes or multi-client wallets), the one with the HIGHEST
+ * session ID is returned. All lower-ID duplicates are passed to `onStaleDuplicate`
+ * (if provided) for fire-and-forget cancellation.
+ *
+ * @param {string} lcdUrl - LCD endpoint URL
+ * @param {string} walletAddr - sent1... wallet address
+ * @param {string} nodeAddr - sentnode1... node address
+ * @param {object} [opts]
+ * @param {function} [opts.onStaleDuplicate] - Called with (BigInt sessionId) for each
+ *   stale lower-ID duplicate session. Caller is responsible for fire-and-forget
+ *   MsgCancelSession. Keeps chain/queries.js dependency-free of signing/broadcast logic.
+ * @returns {Promise<BigInt|null>}
  */
-export async function findExistingSession(lcdUrl, walletAddr, nodeAddr) {
+export async function findExistingSession(lcdUrl, walletAddr, nodeAddr, opts = {}) {
   let sessions;
 
   // RPC-first: returns decoded, flat session objects
@@ -102,6 +117,8 @@ export async function findExistingSession(lcdUrl, walletAddr, nodeAddr) {
     });
   }
 
+  // Collect all non-exhausted active sessions for this node
+  const matching = [];
   for (const s of sessions) {
     if ((s.node_address || s.node) !== nodeAddr) continue;
     // RPC returns status as number (1=active), LCD as string
@@ -111,9 +128,22 @@ export async function findExistingSession(lcdUrl, walletAddr, nodeAddr) {
     if (acct && acct !== walletAddr) continue;
     const maxBytes = parseInt(s.max_bytes || '0');
     const used = parseInt(s.download_bytes || '0') + parseInt(s.upload_bytes || '0');
-    if (maxBytes === 0 || used < maxBytes) return BigInt(s.id);
+    if (maxBytes === 0 || used < maxBytes) matching.push(BigInt(s.id));
+  }
+
+  if (matching.length === 0) return null;
+
+  // Sort descending — highest session ID is the freshest (most recent MsgStartSession)
+  matching.sort((a, b) => (a > b ? -1 : a < b ? 1 : 0));
+
+  // Dedup: cancel stale lower-ID duplicates (fire-and-forget via caller callback)
+  if (matching.length > 1 && typeof opts.onStaleDuplicate === 'function') {
+    for (let i = 1; i < matching.length; i++) {
+      opts.onStaleDuplicate(matching[i]);
+    }
   }
-  return null;
+
+  return matching[0];
 }
 
 /**
@@ -588,8 +618,80 @@ export async function querySubscriptionAllocations(subscriptionId, lcdUrl) {
   } catch { return []; }
 }
 
+/**
+ * Normalize chain status values from RPC (numeric: 1=active, 2=inactive, 3=pending)
+ * and LCD (strings: "STATUS_ACTIVE", "STATUS_INACTIVE", "STATUS_INACTIVE_PENDING").
+ * Returns true only for the ACTIVE status, never for INACTIVE_PENDING (status=3),
+ * which is a transient terminal state and should never be treated as connectable.
+ *
+ * @param {number|string|undefined} v
+ * @returns {boolean}
+ */
+export function isActiveStatus(v) {
+  if (v === 1 || v === '1') return true;
+  if (typeof v === 'string') return v === 'STATUS_ACTIVE' || v === 'active';
+  return false;
+}
+
 // ─── Plan Subscriber Helpers (v25b) ──────────────────────────────────────────
 
+/**
+ * Query a single plan's metadata. RPC-first with LCD fallback.
+ *
+ * Returns the plan's provider (sentprov1...), price list, duration, bytes quota,
+ * and status. Builders use this before connecting through a plan subscription to
+ * resolve the plan owner (the address that typically acts as fee granter for
+ * MsgStartSubscriptionRequest + MsgPlanStartSession TXs).
+ *
+ * NOTE: `prov_address` is a sentprov1... provider address, which is usually
+ * derived from a sent1... account address. If you need the operator's sent1...
+ * account (the expected fee granter), either pass it in explicitly via app
+ * config or call `getProviderByAddress(prov_address)` and read `.address`.
+ *
+ * @param {number|string} planId
+ * @param {object} [opts]
+ * @param {string} [opts.lcdUrl]
+ * @returns {Promise<{ planId: string, provider: string, prices: Array, bytes: string, duration: string, status: number, statusAt: string|null, private: boolean } | null>}
+ */
+export async function queryPlanDetails(planId, opts = {}) {
+  // RPC-first
+  try {
+    const rpc = await getRpcClient();
+    if (rpc) {
+      const plan = await rpcQueryPlan(rpc, planId);
+      if (plan) {
+        return {
+          planId: String(plan.id),
+          provider: plan.prov_address,
+          prices: plan.prices || [],
+          bytes: plan.bytes || '0',
+          duration: plan.duration || '0s',
+          status: plan.status,
+          statusAt: plan.status_at,
+          private: plan.private === true,
+        };
+      }
+    }
+  } catch { /* fall through to LCD */ }
+
+  // LCD fallback: /sentinel/plan/v3/plans/{planId}
+  try {
+    const data = await lcdQuery(`/sentinel/plan/v3/plans/${planId}`, { lcdUrl: opts.lcdUrl });
+    const plan = data?.plan;
+    if (!plan) return null;
+    return {
+      planId: String(plan.id),
+      provider: plan.prov_address || plan.provider_address || '',
+      prices: plan.prices || [],
+      bytes: plan.bytes || '0',
+      duration: plan.duration || '0s',
+      status: typeof plan.status === 'number' ? plan.status : (plan.status === 'STATUS_ACTIVE' ? 1 : 2),
+      statusAt: plan.status_at || null,
+      private: plan.private === true,
+    };
+  } catch { return null; }
+}
+
 /**
  * Query all subscriptions for a plan. Supports owner filtering.
  * RPC-first with LCD fallback.
@@ -841,3 +943,75 @@ export function saveVpnSettings(settings) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
   writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2), { mode: 0o600 });
 }
+
+// ─── TX Hash Lookup (RPC-first, LCD fallback) ───────────────────────────────
+
+/**
+ * Fetch a transaction by hash. RPC is tried first; if it fails or the TX is
+ * not found, falls back to the LCD REST endpoint.
+ *
+ * Accepts bare hex or 0x-prefixed hex for the hash.
+ * Returns the same normalised shape regardless of source:
+ *   { hash, height, code, rawLog, events, gasUsed, gasWanted }
+ *
+ * Use this to re-fetch TX events after a crash/restart or from a different
+ * process (CosmJS only returns DeliverTxResponse inline from signAndBroadcast).
+ *
+ * @param {string} txHash - Transaction hash (bare hex or 0x-prefixed)
+ * @param {object} [opts]
+ * @param {string} [opts.rpcUrl] - RPC endpoint (uses cached client if omitted)
+ * @param {string} [opts.lcdUrl] - LCD endpoint for fallback
+ * @returns {Promise<{ hash: string, height: number, code: number, rawLog: string, events: Array<{ type: string, attributes: Array<{ key: string, value: string }> }>, gasUsed: string, gasWanted: string } | null>}
+ */
+export async function getTxByHash(txHash, opts = {}) {
+  const hex = txHash.replace(/^0x/i, '').toUpperCase();
+
+  // ── RPC-first ──────────────────────────────────────────────────────────────
+  try {
+    let rpc;
+    if (opts.rpcUrl) {
+      const { createRpcQueryClient } = await import('./rpc.js');
+      rpc = await createRpcQueryClient(opts.rpcUrl);
+    } else {
+      rpc = await getRpcClient();
+    }
+    if (rpc?.tmClient) {
+      const result = await rpcGetTxByHash(rpc.tmClient, hex);
+      return result;
+    }
+  } catch (rpcErr) {
+    // "tx not found" from RPC → fall through to LCD
+    const msg = rpcErr?.message || '';
+    if (!msg.toLowerCase().includes('not found') && !msg.toLowerCase().includes('404')) {
+      // Real connectivity error — still fall through, LCD may succeed
+    }
+  }
+
+  // ── LCD fallback ───────────────────────────────────────────────────────────
+  try {
+    const doLcd = async (baseUrl) => {
+      const data = await lcdQuery(`/cosmos/tx/v1beta1/txs/${hex}`, { lcdUrl: baseUrl });
+      const txResp = data?.tx_response;
+      if (!txResp) return null;
+      const events = (txResp.events || []).map(ev => ({
+        type: ev.type,
+        attributes: (ev.attributes || []).map(attr => ({
+          key: attr.key,
+          value: attr.value,
+        })),
+      }));
+      return {
+        hash: (txResp.txhash || hex).toUpperCase(),
+        height: parseInt(txResp.height || '0', 10),
+        code: txResp.code || 0,
+        rawLog: txResp.raw_log || '',
+        events,
+        gasUsed: String(txResp.gas_used || '0'),
+        gasWanted: String(txResp.gas_wanted || '0'),
+      };
+    };
+    if (opts.lcdUrl) return await doLcd(opts.lcdUrl);
+    const { result } = await tryWithFallback(LCD_ENDPOINTS, doLcd, `getTxByHash ${hex}`);
+    return result;
+  } catch { return null; }
+}