blue-js-sdk 2.4.0 → 2.6.0

package/connection/disconnect.js

@@ -28,13 +28,35 @@ import { queryNode, privKeyFromMnemonic } from '../cosmjs-setup.js';
 import { createNodeHttpsAgent } from '../tls-trust.js';
 
 // ─── 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,11 +87,18 @@ 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._mnemonic) {
+        _endSessionOnChain(prev.sessionId, state._mnemonic).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
@@ -82,8 +111,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 ───────────────────────────────────────────────────

package/connection/index.js

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

package/cosmjs-setup.js

@@ -87,6 +87,8 @@ import {
   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 +487,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);
 }
 
 /**
@@ -1006,6 +1014,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) ────────────────────────────────────────────────────
 
 /**

package/index.js

@@ -27,6 +27,9 @@ export {
   enrichNodes,
   buildNodeIndex,
   disconnect,
+  disconnectAndEndSession,
+  disconnectState,
+  disconnectStateAndEndSession,
   isConnected,
   getStatus,
   registerCleanupHandlers,
@@ -52,7 +55,6 @@ export {
   disableDnsLeakPrevention,
   events,
   ConnectionState,
-  disconnectState,
   tryFastReconnect,
 } from './node-connect.js';
 
@@ -311,6 +313,7 @@ export {
   rpcQueryFeeGrantsIssued,
   rpcQueryAuthzGrants,
   rpcQueryProvider,
+  rpcGetTxByHash,
 } from './chain/rpc.js';
 
 // ─── Subscription Sharing (plan operator → user onboarding) ────────────────
@@ -323,6 +326,7 @@ export {
 
 export {
   querySubscriptionAllocations,
+  getTxByHash,
 } from './chain/queries.js';
 
 // ─── TypeScript Client (extends CosmJS SigningStargateClient) ───────────────

package/node-connect.js

@@ -1011,7 +1011,17 @@ export async function connectDirect(opts) {
     if (!forceNewSession) {
       progress(onProgress, logFn, 'session', 'Checking for existing session...');
       checkAborted(signal);
-      sessionId = await findExistingSession(lcd, account.address, opts.nodeAddress);
+      sessionId = await findExistingSession(lcd, account.address, opts.nodeAddress, {
+        // Dedup: if multiple active sessions exist for this node (stale duplicates from
+        // crashes or multi-client wallets), keep the highest-ID one. Silently cancel stale
+        // lower-ID sessions before MsgStartSession — mirrors C# SessionManager dedup pattern.
+        onStaleDuplicate: (staleId) => {
+          logFn?.(`[connect] Cancelling stale duplicate session ${staleId} on ${opts.nodeAddress}...`);
+          _endSessionOnChain(staleId, opts.mnemonic, opts.feeGranter || null).catch(e => {
+            logFn?.(`[connect] Failed to cancel stale session ${staleId}: ${e.message}`);
+          });
+        },
+      });
       if (sessionId && isSessionPoisoned(String(sessionId))) {
         progress(onProgress, logFn, 'session', `Session ${sessionId} previously failed — skipping`);
         sessionId = null;
@@ -1460,8 +1470,10 @@ async function connectInternal(opts, paymentStrategy, retryStrategy, state = _de
         { nodeAddress: state.connection?.nodeAddress });
     }
     const prev = state.connection;
-    await disconnectState(state);
-    if (opts.log || defaultLog) (opts.log || defaultLog)(`[connect] Disconnected from ${prev?.nodeAddress || 'previous node'}`);
+    // Hard disconnect: user is actively connecting to a different node,
+    // so the old session should be settled and the deposit refunded.
+    await disconnectStateAndEndSession(state);
+    if (opts.log || defaultLog) (opts.log || defaultLog)(`[connect] Ended session on ${prev?.nodeAddress || 'previous node'} — connecting to new node`);
   }
 
   const onProgress = opts.onProgress || null;
@@ -2267,13 +2279,35 @@ function formatUptime(ms) {
 }
 
 // ─── 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.
   _abortConnect = true;
@@ -2299,11 +2333,18 @@ export async function disconnectState(state) {
       state.wgTunnel = null;
     }
 
-    // End session on chain (best-effort, fire-and-forget — never blocks disconnect)
-    if (prev?.sessionId && state._mnemonic) {
-      _endSessionOnChain(prev.sessionId, state._mnemonic, state._feeGranter).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._mnemonic) {
+        _endSessionOnChain(prev.sessionId, state._mnemonic, state._feeGranter).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
@@ -2317,8 +2358,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
+ */
+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
+ */
+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 });
 }
 
 // ─── Session End (on-chain cleanup) ──────────────────────────────────────────

package/operator.js

@@ -77,6 +77,8 @@ export {
   grantPlanSubscribers,
   renewExpiringGrants,
   monitorFeeGrants,
+  streamGrantPlanSubscribers,
+  computeFeeGrantGasCosts,
 } from './cosmjs-setup.js';
 
 // ─── Authz ──────────────────────────────────────────────────────────────────

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "blue-js-sdk",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Decentralized VPN SDK for the Sentinel P2P bandwidth network. WireGuard + V2Ray tunnels, Cosmos blockchain, 900+ nodes. Tested on Windows. macOS/Linux support included but untested.",
   "type": "module",
   "main": "index.js",
   "types": "types/index.d.ts",
   "bin": {
-    "sentinel": "./cli/index.js",
-    "sentinel-ai": "./ai-path/cli.js"
+    "sentinel": "./cli/index.js"
   },
   "exports": {
     ".": {
@@ -16,7 +15,6 @@
     },
     "./consumer": "./consumer.js",
     "./operator": "./operator.js",
-    "./ai-path": "./ai-path/index.js",
     "./blue": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
@@ -49,7 +47,6 @@
     "errors/",
     "examples/",
     "docs/",
-    "ai-path/",
     "bin/setup.js",
     "dist/",
     "src/",

package/types/index.d.ts

@@ -469,8 +469,8 @@ export function isMnemonicValid(mnemonic: string): boolean;
 /** Get current P2P price in USD */
 export function getDvpnPrice(): Promise<number>;
 
-/** Find existing active session for wallet+node pair */
-export function findExistingSession(lcdUrl: string, walletAddr: string, nodeAddr: string): Promise<bigint | null>;
+/** Find existing active session for wallet+node pair. Deduplicates stale sessions via onStaleDuplicate callback. */
+export function findExistingSession(lcdUrl: string, walletAddr: string, nodeAddr: string, opts?: { onStaleDuplicate?: (sessionId: bigint) => void }): Promise<bigint | null>;
 
 /** Fetch active nodes from LCD with pagination */
 export function fetchActiveNodes(lcdUrl: string, limit?: number, maxPages?: number): Promise<unknown[]>;

package/ai-path/ADMIN-ELEVATION.md

@@ -1,116 +0,0 @@
-# Admin Elevation Guide — Sentinel AI Path
-
-## Why Admin is Required
-
-WireGuard tunnel operations require system-level access:
-- **Windows:** Installing/removing WireGuard tunnel services (wireguard.exe /installtunnelservice)
-- **macOS:** Creating utun interfaces (wg-quick up)
-- **Linux:** Creating WireGuard interfaces (ip link add wg0)
-
-Without admin, you can only use V2Ray nodes (~70% of the network). With admin, you access 100% of nodes including the faster, more reliable WireGuard nodes.
-
-**The SDK checks admin BEFORE payment.** If you're not admin and select a WireGuard node, the SDK rejects the connection before any P2P tokens are spent. No money is wasted.
-
-## Windows — Using run-admin.vbs
-
-The `run-admin.vbs` script triggers a single UAC prompt, then runs your Node.js script with full Administrator privileges. One prompt per session.
-
-```bash
-# Setup (downloads V2Ray + installs WireGuard silently)
-cscript run-admin.vbs setup.js
-
-# Connect via CLI
-cscript run-admin.vbs cli.js connect
-
-# Run any custom script
-cscript run-admin.vbs my-agent.mjs
-
-# Test WireGuard specifically
-cscript run-admin.vbs test-wireguard.mjs
-```
-
-### How run-admin.vbs works
-1. Calls `Shell.Application.ShellExecute` with verb `"runas"` → triggers UAC
-2. Opens an elevated cmd.exe window
-3. cd's to the script directory
-4. Runs `node <your-script>`
-5. Keeps the window open (so you can see output)
-
-### For AI agents running unattended
-If the AI agent runs as a Windows Service or scheduled task, configure it to run as a user with admin rights (e.g., SYSTEM or a dedicated admin account). No UAC prompt needed for services.
-
-## macOS — Using sudo
-
-```bash
-sudo node setup.js              # Install WireGuard via brew
-sudo node cli.js connect        # Connect with WireGuard access
-sudo node my-agent.mjs          # Run agent elevated
-```
-
-For unattended agents, add to sudoers:
-```
-agent-user ALL=(ALL) NOPASSWD: /usr/local/bin/node
-```
-
-## Linux — Using sudo
-
-```bash
-sudo node setup.js              # Install wireguard-tools via apt/dnf
-sudo node cli.js connect        # Connect with WireGuard access
-sudo node my-agent.mjs          # Run agent elevated
-```
-
-For unattended agents in systemd:
-```ini
-[Service]
-User=root
-ExecStart=/usr/local/bin/node /path/to/my-agent.mjs
-```
-
-Or use capabilities instead of full root:
-```bash
-sudo setcap cap_net_admin+ep $(which node)
-```
-
-## V2Ray-Only Mode (No Admin Needed)
-
-If admin is not available, the SDK automatically falls back to V2Ray nodes:
-
-```js
-const vpn = await connect({
-  mnemonic: process.env.MNEMONIC,
-  protocol: 'v2ray',  // Explicitly request V2Ray only
-});
-```
-
-V2Ray runs as a userspace SOCKS5 proxy — no system-level access needed. It connects to ~630 nodes (70% of the network). This is the recommended mode for:
-- CI/CD pipelines
-- Docker containers without --privileged
-- Cloud VMs where root is restricted
-- Development/testing
-
-## Detection in Code
-
-The SDK exports `IS_ADMIN` for checking:
-
-```js
-import { IS_ADMIN, WG_AVAILABLE } from 'sentinel-dvpn-sdk';
-
-if (WG_AVAILABLE && IS_ADMIN) {
-  console.log('Full network access (WireGuard + V2Ray)');
-} else if (WG_AVAILABLE && !IS_ADMIN) {
-  console.log('WireGuard installed but not admin — V2Ray only');
-  console.log('Run: cscript run-admin.vbs your-script.mjs');
-} else {
-  console.log('V2Ray only (WireGuard not installed)');
-}
-```
-
-The `getEnvironment()` function reports this:
-```js
-import { getEnvironment } from 'sentinel-ai-connect';
-const env = getEnvironment();
-// env.admin: true/false
-// env.capabilities: ['v2ray', 'wireguard'] or ['v2ray', 'wireguard-needs-admin'] or ['v2ray']
-// env.recommended: ['run as admin to use WireGuard nodes (faster, more reliable)']
-```