blue-js-sdk 2.4.0 → 2.7.0

package/connection/disconnect.js

@@ -26,15 +26,42 @@ import { DEFAULT_LCD, DEFAULT_TIMEOUTS } from '../defaults.js';
 import { nodeStatusV3 } from '../v3protocol.js';
 import { queryNode, privKeyFromMnemonic } from '../cosmjs-setup.js';
 import { createNodeHttpsAgent } from '../tls-trust.js';
+import { withMnemonicRedaction } from './logger.js';
+
+// Default logger wraps console.log so any 12–24 word BIP-39 phrase that ends
+// up in a log argument is replaced before reaching stdout. See connection/logger.js.
+const defaultLog = withMnemonicRedaction(console.log);
 
 // ─── Disconnect ──────────────────────────────────────────────────────────────
+//
+// TWO DISCONNECT PATHS — CHOOSE INTENT EXPLICITLY.
+//
+// Soft: disconnect() / disconnectState(state)
+//   - Tears down the local tunnel (WireGuard/V2Ray) and cleans up system state.
+//   - Leaves the on-chain session in status=1 (active).
+//   - Next connectDirect() to the SAME node reuses the session via
+//     findExistingSession — no new MsgStartSession TX, no new payment, bandwidth preserved.
+//   - Use when: user is pausing, network changed, closing the app temporarily.
+//
+// Hard: disconnectAndEndSession() / disconnectStateAndEndSession(state)
+//   - Tears down the tunnel AND broadcasts MsgCancelSession on chain.
+//   - Session moves status=1 → settling → refund after ~2h settlement window.
+//   - Use when: user is done with this node, switching nodes permanently,
+//     or wants the bandwidth deposit back.
+//
+// Internal: _disconnectInternal(state, { endSession })
+//   - Caller MUST pass endSession explicitly as true or false.
+//   - No default — forces intentional choice at every callsite.
 
 /**
- * Clean up all active tunnels and system proxy.
- * ALWAYS call this on exit — a stale WireGuard tunnel will kill your internet.
+ * Internal disconnect implementation. Caller must explicitly pass endSession.
+ * @param {object} state - ConnectionState instance
+ * @param {{ endSession: boolean }} opts
+ *   endSession: true  → broadcast MsgCancelSession (hard disconnect)
+ *   endSession: false → preserve on-chain session for reuse (soft disconnect)
+ * @private
  */
-/** Disconnect a specific state instance (internal). */
-export async function disconnectState(state) {
+async function _disconnectInternal(state, { endSession }) {
   // v30: Signal any running connectAuto() retry loop to abort, and release the
   // connection lock so the user can reconnect after disconnect completes.
   setAbortConnect(true);
@@ -65,15 +92,22 @@ export async function disconnectState(state) {
       try { disableDnsLeakPrevention(); } catch (e) { console.warn('[sentinel-sdk] DNS restore warning:', e.message); }
     }
 
-    // End session on chain (best-effort, fire-and-forget — never blocks disconnect)
-    if (prev?.sessionId && state._mnemonic) {
-      _endSessionOnChain(prev.sessionId, state._mnemonic).catch(e => {
-        console.warn(`[sentinel-sdk] Failed to end session ${prev.sessionId} on chain: ${e.message}`);
-      });
+    if (endSession) {
+      // Hard disconnect: broadcast MsgCancelSession — session settles and refunds deposit.
+      if (prev?.sessionId && state._wallet) {
+        _endSessionOnChain(prev.sessionId, state._wallet).catch(e => {
+          console.warn(`[sentinel-sdk] Failed to end session ${prev.sessionId} on chain: ${e.message}`);
+        });
+      }
+    } else {
+      // Soft disconnect: leave session on chain in status=1 for reuse.
+      if (prev?.sessionId) {
+        console.log(`[sentinel-sdk] Session ${prev.sessionId} preserved on chain (status=1) for future reuse — no MsgCancelSession broadcast.`);
+      }
     }
   } finally {
     // ALWAYS clear connection state — even if teardown threw
-    state._mnemonic = null;
+    state._wallet = null;
     state.connection = null;
     clearState();
     clearWalletCache(); // v34: Clear cached wallet objects (private keys) from memory
@@ -82,8 +116,55 @@ export async function disconnectState(state) {
   }
 }
 
+/**
+ * Soft disconnect — tear down the local tunnel, leave the on-chain session active.
+ *
+ * A subsequent connectDirect() to the SAME node will reuse the session via
+ * findExistingSession — no new MsgStartSession TX, no new payment, remaining
+ * bandwidth is preserved.
+ *
+ * Use when: user is pausing, network changed, or closing the app temporarily.
+ * To settle the session on-chain and reclaim the unused deposit, use
+ * disconnectAndEndSession() instead.
+ *
+ * @param {object} [state] - ConnectionState instance (defaults to _defaultState)
+ */
+export async function disconnectState(state) {
+  return _disconnectInternal(state, { endSession: false });
+}
+
+/**
+ * Soft disconnect (default state) — tear down the tunnel, leave on-chain session active.
+ *
+ * @see disconnectState
+ */
 export async function disconnect() {
-  return disconnectState(_defaultState);
+  return _disconnectInternal(_defaultState, { endSession: false });
+}
+
+/**
+ * Hard disconnect — tear down the tunnel AND broadcast MsgCancelSession on chain.
+ *
+ * The session settles after the ~2h inactive_pending window. The node refunds
+ * the unused portion of the bandwidth deposit (for peer-to-peer sessions).
+ * For plan-based sessions, this stops metering against the plan allocation.
+ *
+ * Use when: user is done with this node (switching nodes permanently, ending
+ * their session, or wants the deposit back).
+ *
+ * @param {object} [state] - ConnectionState instance (defaults to _defaultState)
+ */
+export async function disconnectStateAndEndSession(state) {
+  return _disconnectInternal(state, { endSession: true });
+}
+
+/**
+ * Hard disconnect (default state) — tear down the tunnel AND broadcast MsgCancelSession.
+ *
+ * @see disconnectStateAndEndSession
+ */
+export async function disconnectAndEndSession() {
+  return _disconnectInternal(_defaultState, { endSession: true });
 }
 
 // ─── Cleanup Registration ───────────────────────────────────────────────────
@@ -128,7 +209,7 @@ export async function recoverSession(opts) {
   if (!opts?.nodeAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'recoverSession requires opts.nodeAddress');
   if (!opts?.mnemonic) throw new ValidationError(ErrorCodes.INVALID_MNEMONIC, 'recoverSession requires opts.mnemonic');
 
-  const logFn = opts.log || console.log;
+  const logFn = opts.log || defaultLog;
   const onProgress = opts.onProgress || null;
   const sessionId = BigInt(opts.sessionId);
   const timeouts = { ...DEFAULT_TIMEOUTS, ...opts.timeouts };

package/connection/index.js

@@ -32,6 +32,8 @@ export {
 export {
   disconnect,
   disconnectState,
+  disconnectAndEndSession,
+  disconnectStateAndEndSession,
   registerCleanupHandlers,
   recoverSession,
 } from './disconnect.js';

package/connection/logger.js

@@ -0,0 +1,66 @@
+/**
+ * Redacting logger wrapper — defense-in-depth against accidental mnemonic leaks
+ * in SDK log output.
+ *
+ * The SDK's default logger is `console.log`. Any future bug that interpolates
+ * a mnemonic into a log template string (e.g. `log(`opts: ${JSON.stringify(opts)}`)`)
+ * would leak the BIP-39 phrase to stdout/stderr — and from there to terminal
+ * scrollback, CI logs, log-aggregation tools (Datadog, Loki, Sentry breadcrumbs),
+ * and shell history.
+ *
+ * This module wraps any logger function with a regex-based redactor that matches
+ * BIP-39 word sequences and replaces them with `[REDACTED MNEMONIC]` before the
+ * underlying logger sees them. It is NOT a substitute for the rule "do not log
+ * the mnemonic" — it is a safety net so that violation does not produce a leak.
+ *
+ * Performance: the regex runs only on string arguments and short-circuits if the
+ * argument has fewer than ~60 characters (a 12-word mnemonic is ~80 characters).
+ * Negligible overhead on the SDK's hot path (a few connect-time progress logs).
+ */
+
+/**
+ * Match 12 / 15 / 18 / 21 / 24 lowercase BIP-39-shaped words separated by single
+ * spaces. We deliberately don't try to validate against the full 2048-word list
+ * here — the goal is to catch anything that *looks* like a mnemonic and redact
+ * it. False positives (e.g. a long lowercase sentence) are acceptable since the
+ * SDK's own log strings never contain 12+ consecutive lowercase-only ASCII words.
+ *
+ * BIP-39 words are 3–8 lowercase ASCII letters (a–z), no digits, no diacritics.
+ */
+const MNEMONIC_REGEX = /\b(?:[a-z]{3,8}\s+){11,23}[a-z]{3,8}\b/g;
+
+const REDACTED = '[REDACTED MNEMONIC]';
+
+/**
+ * Redact mnemonic-shaped substrings from a single value. Strings are scanned;
+ * everything else is returned unchanged. We do NOT recurse into objects — the
+ * SDK's loggers are called with scalar args, and walking arbitrary objects
+ * would risk triggering custom getters that have side effects.
+ *
+ * @param {*} value
+ * @returns {*}
+ */
+function redactValue(value) {
+  if (typeof value !== 'string') return value;
+  if (value.length < 60) return value; // shortest plausible 12-word phrase ~ 60 chars
+  return value.replace(MNEMONIC_REGEX, REDACTED);
+}
+
+/**
+ * Wrap a logger function so that mnemonic-shaped strings in its arguments are
+ * replaced with `[REDACTED MNEMONIC]` before they reach the wrapped logger.
+ * Pass-through for non-function input (returns it unchanged) so callers can
+ * disable logging by passing `null`.
+ *
+ * @param {Function|null|undefined} logFn - underlying logger (typically console.log)
+ * @returns {Function|null|undefined}
+ */
+export function withMnemonicRedaction(logFn) {
+  if (typeof logFn !== 'function') return logFn;
+  return function redactedLog(...args) {
+    return logFn(...args.map(redactValue));
+  };
+}
+
+// Exported for tests.
+export const _internal = { MNEMONIC_REGEX, redactValue };

package/connection/resilience.js

@@ -30,6 +30,11 @@ import { findV2RayExe } from './tunnel.js';
 import { enableKillSwitch, isKillSwitchEnabled as _isKillSwitchEnabled } from './security.js';
 import { setSystemProxy, clearSystemProxy, checkPortFree } from './proxy.js';
 import { connectAuto, connectViaSubscription, connectViaPlan } from './connect.js';
+import { withMnemonicRedaction } from './logger.js';
+
+// Default logger wraps console.log so any 12–24 word BIP-39 phrase that ends
+// up in a log argument is replaced before reaching stdout. See connection/logger.js.
+const defaultLog = withMnemonicRedaction(console.log);
 
 // ─── Circuit Breaker ─────────────────────────────────────────────────────────
 // v22: Skip nodes that repeatedly fail. Resets after TTL expires.
@@ -108,7 +113,7 @@ export async function tryFastReconnect(opts, state = _defaultState) {
   if (!saved) return null;
 
   const onProgress = opts.onProgress || null;
-  const logFn = opts.log || console.log;
+  const logFn = opts.log || defaultLog;
   const fullTunnel = opts.fullTunnel !== false;
   const killSwitch = opts.killSwitch === true;
   const systemProxy = opts.systemProxy === true;
@@ -210,12 +215,12 @@ export async function tryFastReconnect(opts, state = _defaultState) {
           }
           try { await disconnectWireGuard(); } catch {}
           // End session on chain (fire-and-forget)
-          if (saved.sessionId && state._mnemonic) {
-            _endSessionOnChain(saved.sessionId, state._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+          if (saved.sessionId && state._wallet) {
+            _endSessionOnChain(saved.sessionId, state._wallet).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
           }
           state.wgTunnel = null;
           state.connection = null;
-          state._mnemonic = null;
+          state._wallet = null;
           clearState();
         },
       };
@@ -335,11 +340,11 @@ export async function tryFastReconnect(opts, state = _defaultState) {
           if (state.v2rayProc) { state.v2rayProc.kill(); state.v2rayProc = null; await sleep(500); }
           if (state.systemProxy) clearSystemProxy(state);
           // End session on chain (fire-and-forget)
-          if (sessionIdStr && state._mnemonic) {
-            _endSessionOnChain(sessionIdStr, state._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+          if (sessionIdStr && state._wallet) {
+            _endSessionOnChain(sessionIdStr, state._wallet).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
           }
           state.connection = null;
-          state._mnemonic = null;
+          state._wallet = null;
           clearState();
         },
       };

package/connection/state.js

@@ -82,7 +82,13 @@ export class ConnectionState {
     this.systemProxy = false;
     this.connection = null;  // { nodeAddress, serviceType, sessionId, connectedAt, socksPort? }
     this.savedProxyState = null;
-    this._mnemonic = null;   // Stored for session-end TX on disconnect (zeroed after use)
+    // v37 (security): store the derived OfflineSigner wallet, NOT the raw BIP-39 mnemonic.
+    // Previously _mnemonic held the recovery phrase for the full session lifetime so
+    // that disconnect could sign MsgEndSession. The mnemonic is the highest-value
+    // secret in the SDK — keeping it on a long-lived object enlarged the heap-dump
+    // attack surface unnecessarily. The wallet object holds only the derived signing
+    // key, which is no more sensitive than the privKey buffer we were already keeping.
+    this._wallet = null;     // OfflineSigner — used by _endSessionOnChain on disconnect
     _activeStates.add(this);
   }
   get isConnected() { return !!(this.v2rayProc || this.wgTunnel); }
@@ -216,11 +222,14 @@ export function formatUptime(ms) {
  * End a session on-chain. Best-effort, fire-and-forget.
  * Prevents stale session accumulation on nodes.
  * @param {string|bigint} sessionId - Session ID to end
- * @param {string} mnemonic - BIP39 mnemonic for signing the TX
+ * @param {object} walletObj - { wallet, account } from cachedCreateWallet (NOT the mnemonic).
+ *   Accepting the derived signer instead of the raw phrase keeps the BIP-39 mnemonic
+ *   off the long-lived ConnectionState — see ConnectionState._wallet.
  * @private
  */
-export async function _endSessionOnChain(sessionId, mnemonic) {
-  const { wallet, account } = await cachedCreateWallet(mnemonic);
+export async function _endSessionOnChain(sessionId, walletObj) {
+  if (!walletObj) throw new SentinelError(ErrorCodes.INVALID_OPTIONS, '_endSessionOnChain requires a wallet object');
+  const { wallet, account } = walletObj;
   const client = await tryWithFallback(
     RPC_ENDPOINTS,
     async (url) => createClient(url, wallet),
@@ -261,8 +270,8 @@ export function getStatus() {
     const stale = _defaultState.connection;
     _defaultState.connection = null;
     // End session on chain (fire-and-forget) to prevent stale session leaks
-    if (stale?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(stale.sessionId, _defaultState._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    if (stale?.sessionId && _defaultState._wallet) {
+      _endSessionOnChain(stale.sessionId, _defaultState._wallet).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     clearState();
     events.emit('disconnected', { nodeAddress: stale.nodeAddress, serviceType: stale.serviceType, reason: 'phantom_state' });
@@ -308,8 +317,8 @@ export function getStatus() {
   // clean up stale state. Prevents ghost "connected" status after tunnel dies.
   if (!healthChecks.tunnelActive && !_defaultState.v2rayProc && !_defaultState.wgTunnel) {
     // Both tunnel handles are null — connection state is stale
-    if (conn?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    if (conn?.sessionId && _defaultState._wallet) {
+      _endSessionOnChain(conn.sessionId, _defaultState._wallet).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.connection = null;
     clearState();
@@ -317,8 +326,8 @@ export function getStatus() {
   }
   if (_defaultState.wgTunnel && !healthChecks.tunnelActive) {
     // WireGuard state says connected but tunnel is dead — auto-cleanup
-    if (conn?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    if (conn?.sessionId && _defaultState._wallet) {
+      _endSessionOnChain(conn.sessionId, _defaultState._wallet).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.wgTunnel = null;
     _defaultState.connection = null;
@@ -328,8 +337,8 @@ export function getStatus() {
   }
   if (_defaultState.v2rayProc && !healthChecks.tunnelActive) {
     // V2Ray process died — auto-cleanup
-    if (conn?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    if (conn?.sessionId && _defaultState._wallet) {
+      _endSessionOnChain(conn.sessionId, _defaultState._wallet).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.v2rayProc = null;
     _defaultState.connection = null;

package/connection/tunnel.js

@@ -389,12 +389,12 @@ async function setupWireGuard({ remoteUrl, sessionId, privKey, fullTunnel, split
       if (isKillSwitchEnabled()) disableKillSwitch();
       try { await disconnectWireGuard(); } catch {} // tunnel may already be down
       // End session on chain (fire-and-forget)
-      if (sessionIdStr && state._mnemonic) {
-        _endSessionOnChain(sessionIdStr, state._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+      if (sessionIdStr && state._wallet) {
+        _endSessionOnChain(sessionIdStr, state._wallet).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
       }
       state.wgTunnel = null;
       state.connection = null;
-      state._mnemonic = null;
+      state._wallet = null;
       clearState();
     },
   };
@@ -560,12 +560,28 @@ async function setupV2Ray({ remoteUrl, serverHost, sessionId, privKey, v2rayExeP
           }
         });
       }
-      // Delete config after V2Ray reads it (contains UUID credentials)
-      setTimeout(() => { try { unlinkSync(cfgPath); } catch {} }, 2000);
+      // Delete config after V2Ray reads it (contains UUID credentials).
+      // Race-safe approach: delete the moment we know V2Ray has loaded config
+      // (port is up OR process exited), and a deadline-bound unref'd safety net.
+      // The previous fixed 2s timer raced the loop iterating to the next outbound,
+      // which overwrites cfgPath — the stale timer would then delete the NEW config.
+      let cfgDeleted = false;
+      const deleteCfg = () => {
+        if (cfgDeleted) return;
+        cfgDeleted = true;
+        try { unlinkSync(cfgPath); } catch {} // best-effort: V2Ray may have file open on Windows
+      };
+      proc.once('exit', deleteCfg);
+      const cfgSafetyTimer = setTimeout(deleteCfg, 5000);
+      cfgSafetyTimer.unref();
 
       // Wait for SOCKS5 port to accept connections instead of fixed sleep.
       // V2Ray binding is async — fixed 6s sleep causes false failures on slow starts.
       const ready = await waitForPort(socksPort, timeouts.v2rayReady);
+      // Once the SOCKS port accepts connections, V2Ray has fully parsed the config —
+      // safe to delete (Windows: file is still open by V2Ray, unlink will return EBUSY,
+      // try/catch swallows; falls back to exit-handler or process orphan-cleanup).
+      if (ready) deleteCfg();
       if (!ready || proc.exitCode !== null) {
         progress(onProgress, logFn, 'tunnel', `  ${ob.tag}: v2ray ${proc.exitCode !== null ? `exited (code ${proc.exitCode})` : 'SOCKS5 port not ready'}, skipping`);
         proc.kill();
@@ -653,11 +669,11 @@ async function setupV2Ray({ remoteUrl, serverHost, sessionId, privKey, v2rayExeP
       if (state.v2rayProc) { state.v2rayProc.kill(); state.v2rayProc = null; await sleep(500); }
       if (state.systemProxy) clearSystemProxy();
       // End session on chain (fire-and-forget)
-      if (sessionIdStr && state._mnemonic) {
-        _endSessionOnChain(sessionIdStr, state._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+      if (sessionIdStr && state._wallet) {
+        _endSessionOnChain(sessionIdStr, state._wallet).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
       }
       state.connection = null;
-      state._mnemonic = null;
+      state._wallet = null;
       clearState();
     },
   };

package/cosmjs-setup.js

@@ -74,6 +74,8 @@ import {
   getProviderByAddress as _getProviderByAddress,
   queryPlanSubscribers as _queryPlanSubscribers,
   getPlanStats as _getPlanStats,
+  queryPlanDetails as _queryPlanDetails,
+  isActiveStatus as _isActiveStatus,
   querySubscriptionAllocations as _querySubscriptionAllocations,
   queryAuthzGrants as _queryAuthzGrants,
   loadVpnSettings as _loadVpnSettings,
@@ -83,10 +85,13 @@ import {
   queryFeeGrants as _queryFeeGrants,
   queryFeeGrantsIssued as _queryFeeGrantsIssued,
   queryFeeGrant as _queryFeeGrant,
+  checkFeeGrant as _checkFeeGrant,
   grantPlanSubscribers as _grantPlanSubscribers,
   getExpiringGrants as _getExpiringGrants,
   renewExpiringGrants as _renewExpiringGrants,
   monitorFeeGrants as _monitorFeeGrants,
+  streamGrantPlanSubscribers as _streamGrantPlanSubscribers,
+  computeFeeGrantGasCosts as _computeFeeGrantGasCosts,
 } from './chain/fee-grants.js';
 
 // ─── Input Validation Helpers ────────────────────────────────────────────────
@@ -485,9 +490,15 @@ export async function getBalance(client, address) {
  * Returns session ID (BigInt) or null. Use this to avoid double-paying.
  *
  * Note: Sessions have a nested base_session object containing the actual data.
+ *
+ * @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 _findExistingSession(lcdUrl, walletAddr, nodeAddr);
+export async function findExistingSession(lcdUrl, walletAddr, nodeAddr, opts) {
+  return _findExistingSession(lcdUrl, walletAddr, nodeAddr, opts);
 }
 
 /**
@@ -804,6 +815,20 @@ export async function queryFeeGrant(lcdUrl, granter, grantee) {
   return _queryFeeGrant(lcdUrl, granter, grantee);
 }
 
+/**
+ * Builder-friendly parsed fee-grant status — exists, expired, expiresAt,
+ * spendLimit, allowedMessages. RPC-first with LCD fallback. Use before
+ * broadcasting plan/subscription session TXs that rely on a fee granter.
+ *
+ * @param {string} lcdUrl
+ * @param {string} granter
+ * @param {string} grantee
+ * @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) {
+  return _checkFeeGrant(lcdUrl, granter, grantee);
+}
+
 /**
  * Broadcast a TX with fee paid by a granter (fee grant).
  * The grantee signs; the granter pays gas via their fee allowance.
@@ -945,6 +970,29 @@ export async function getPlanStats(planId, ownerAddress, opts = {}) {
   return _getPlanStats(planId, ownerAddress, opts);
 }
 
+/**
+ * Query a plan's on-chain metadata (provider, prices, duration, status).
+ * RPC-first with LCD fallback. Returns null if the plan does not exist.
+ *
+ * @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 = {}) {
+  return _queryPlanDetails(planId, opts);
+}
+
+/**
+ * Normalize chain status values. Returns true only for active status
+ * (never for transient INACTIVE_PENDING / status=3).
+ * @param {number|string|undefined} v
+ * @returns {boolean}
+ */
+export function isActiveStatus(v) {
+  return _isActiveStatus(v);
+}
+
 // ─── Fee Grant Workflow Helpers (v25b) ────────────────────────────────────────
 
 /**
@@ -1006,6 +1054,22 @@ export function monitorFeeGrants(opts = {}) {
   return _monitorFeeGrants(opts);
 }
 
+/**
+ * Stream progress as we grant fee allowances to all plan subscribers in batches.
+ * Async generator. See chain/fee-grants.js for event shapes.
+ */
+export function streamGrantPlanSubscribers(planId, opts = {}) {
+  return _streamGrantPlanSubscribers(planId, opts);
+}
+
+/**
+ * Sum udvpn fees the granter has paid on behalf of a plan's subscribers.
+ * Iterates subscribers, pulls TX history, filters on fee.granter.
+ */
+export async function computeFeeGrantGasCosts(planId, opts = {}) {
+  return _computeFeeGrantGasCosts(planId, opts);
+}
+
 // ─── Query Helpers (v25c) ────────────────────────────────────────────────────
 
 /**
@@ -1124,6 +1188,8 @@ export async function hasActiveSubscription(address, planId, lcdUrl) {
   return _hasActiveSubscription(address, planId, lcdUrl);
 }
 
+
+
 // ─── v26c: Display Helpers ───────────────────────────────────────────────────
 
 /**