blue-js-sdk 2.4.0 → 2.6.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/chain/fee-grants.js

@@ -354,3 +354,199 @@ 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
+ * @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,
+    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 existing = await queryFeeGrantsIssued(lcdUrl || LCD_ENDPOINTS[0].url, 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));
   }
-  return null;
+
+  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 matching[0];
 }
 
 /**
@@ -841,3 +871,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; }
+}

package/chain/rpc.js

@@ -402,11 +402,17 @@ function decodeAllocation(fields) {
 /**
  * Query active nodes via RPC.
  *
+ * NOTE ON PAGINATION: Sentinel v3's `QueryNodes` truncates at the requested
+ * `limit` and does NOT emit `pagination.next_key`. A standard Cosmos
+ * "loop while next_key is non-empty" pattern terminates on the first call
+ * and silently loses data. Request above the chain's current hard ceiling
+ * (~1048 active nodes as of 2026-04). Default raised to 10000.
+ *
  * @param {{ queryClient: QueryClient }} client - From createRpcQueryClient()
  * @param {{ status?: number, limit?: number }} [opts]
  * @returns {Promise<Array<{ address: string, gigabyte_prices: Array, hourly_prices: Array, remote_addrs: string[], status: number }>>}
  */
-export async function rpcQueryNodes(client, { status = 1, limit = 500 } = {}) {
+export async function rpcQueryNodes(client, { status = 1, limit = 10000 } = {}) {
   const path = '/sentinel.node.v3.QueryService/QueryNodes';
   const request = concat([
     encodeEnum(1, status),                                        // status field
@@ -446,12 +452,18 @@ export async function rpcQueryNode(client, address) {
 /**
  * Query nodes linked to a plan via RPC.
  *
+ * NOTE ON PAGINATION: `QueryNodesForPlan` silently truncates at the requested
+ * `limit` with no `next_key`. Observed 2026-04: plan 36 has 803 active nodes
+ * but `limit=500` returns exactly 500 with no indication more exist. Default
+ * raised to 10000. If a plan grows beyond that, raise further — the chain's
+ * own ceiling is the effective limit.
+ *
  * @param {{ queryClient: QueryClient }} client
  * @param {number|bigint} planId
  * @param {{ status?: number, limit?: number }} [opts]
  * @returns {Promise<Array>}
  */
-export async function rpcQueryNodesForPlan(client, planId, { status = 1, limit = 500 } = {}) {
+export async function rpcQueryNodesForPlan(client, planId, { status = 1, limit = 10000 } = {}) {
   const path = '/sentinel.node.v3.QueryService/QueryNodesForPlan';
   const request = concat([
     encodeUint64(1, planId),                                     // id
@@ -891,6 +903,50 @@ export async function rpcQueryProvider(client, provAddress) {
   }
 }
 
+// ─── TX Hash Lookup ─────────────────────────────────────────────────────────
+
+/**
+ * Fetch a transaction by hash via Tendermint RPC.
+ * Accepts bare hex (64 chars) or 0x-prefixed hex. Returns a normalized shape
+ * matching the LCD cosmos/tx/v1beta1/txs/{hash} response so callers don't
+ * need to handle both formats.
+ *
+ * @param {import('@cosmjs/tendermint-rpc').Tendermint37Client} tmClient - From createRpcQueryClient().tmClient
+ * @param {string} txHash - TX hash as hex string (bare or 0x-prefixed)
+ * @returns {Promise<{ hash: string, height: number, code: number, rawLog: string, events: Array<{ type: string, attributes: Array<{ key: string, value: string }> }>, gasUsed: string, gasWanted: string }>}
+ * @throws {Error} If the transaction is not found or RPC call fails
+ */
+export async function rpcGetTxByHash(tmClient, txHash) {
+  // Strip optional 0x prefix and normalise to upper-case for consistency
+  const hex = txHash.replace(/^0x/i, '').toUpperCase();
+  // Decode hex string → Uint8Array
+  const hashBytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    hashBytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+
+  const response = await tmClient.tx({ hash: hashBytes });
+
+  // Normalise events: TxData.events is already decoded by CosmJS
+  const events = (response.result.events || []).map(ev => ({
+    type: ev.type,
+    attributes: (ev.attributes || []).map(attr => ({
+      key: attr.key,
+      value: attr.value,
+    })),
+  }));
+
+  return {
+    hash: hex,
+    height: response.height,
+    code: response.result.code,
+    rawLog: response.result.log || '',
+    events,
+    gasUsed: String(response.result.gasUsed),
+    gasWanted: String(response.result.gasWanted),
+  };
+}
+
 export async function rpcQueryBalance(client, address, denom = 'udvpn') {
   const path = '/cosmos.bank.v1beta1.Query/Balance';
   const request = concat([

package/client.js

@@ -28,6 +28,7 @@ import { EventEmitter } from 'events';
 import {
   connectDirect, connectViaPlan, connectAuto, queryOnlineNodes,
   disconnect as sdkDisconnect, disconnectState,
+  disconnectAndEndSession as sdkDisconnectAndEndSession, disconnectStateAndEndSession,
   isConnected as sdkIsConnected, getStatus as sdkGetStatus,
   registerCleanupHandlers, setSystemProxy, clearSystemProxy,
   events as sdkEvents, ConnectionState,
@@ -125,13 +126,28 @@ export class SentinelClient extends EventEmitter {
   }
 
   /**
-   * Disconnect current VPN tunnel.
+   * Soft disconnect — tear down the tunnel, leave the on-chain session active.
+   *
+   * A subsequent connect() to the SAME node reuses the session (no new payment).
+   * Use for pause / temporary disconnect / network-change recovery.
+   * To settle the session and reclaim the deposit, use disconnectAndEndSession().
    */
   async disconnect() {
     await disconnectState(this._state);
     this._connection = null;
   }
 
+  /**
+   * Hard disconnect — tear down the tunnel AND broadcast MsgCancelSession on chain.
+   *
+   * Settles the session after the ~2h window and refunds the unused deposit.
+   * Use when the user is done with this node (switching permanently or wants refund).
+   */
+  async disconnectAndEndSession() {
+    await disconnectStateAndEndSession(this._state);
+    this._connection = null;
+  }
+
   /**
    * Check if a VPN tunnel is currently active.
    */

package/connection/connect.js

@@ -9,7 +9,7 @@ import {
   events, _defaultState, progress, checkAborted,
   warnIfNoCleanup, cachedCreateWallet, _recordMetric,
   broadcastWithInactiveRetry, getConnectLock, setConnectLock,
-  getAbortConnect, setAbortConnect,
+  getAbortConnect, setAbortConnect, _endSessionOnChain,
 } from './state.js';
 
 import {
@@ -31,7 +31,7 @@ import {
 import { createNodeHttpsAgent } from '../tls-trust.js';
 import { disconnectWireGuard } from '../wireguard.js';
 
-import { disconnectState } from './disconnect.js';
+import { disconnectState, disconnectStateAndEndSession } from './disconnect.js';
 import { queryOnlineNodes } from './discovery.js';
 import {
   recordNodeFailure, isCircuitOpen, configureCircuitBreaker,
@@ -79,8 +79,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;
@@ -397,7 +399,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).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;