blue-js-sdk 2.4.0 → 2.7.0

package/chain/rpc.js

@@ -59,6 +59,57 @@ export async function createRpcQueryClientWithFallback() {
   throw new Error(`All RPC endpoints failed: ${errors.map(e => `${e.url}: ${e.error}`).join('; ')}`);
 }
 
+// ─── Failover with Per-Attempt Timeout ────────────────────────────────────
+
+/**
+ * Race a promise against a timeout. The timer is unref()'d so it won't pin
+ * the event loop if the connect succeeds first.
+ */
+function withTimeout(promise, ms, label) {
+  return Promise.race([
+    promise,
+    new Promise((_, rej) => {
+      const t = setTimeout(() => rej(new Error(`${label} timed out after ${ms}ms`)), ms);
+      if (typeof t?.unref === 'function') t.unref();
+    }),
+  ]);
+}
+
+/**
+ * Try RPC endpoints in order with a per-attempt timeout. Returns the first
+ * endpoint that connects AND passes a status health-check within the timeout.
+ *
+ * Fixes: Tendermint37Client.connect() never times out on a hung TCP handshake,
+ * leaving startup stalled for 30+ seconds against a Cloudflare-fronted RPC.
+ *
+ * @param {string[]} endpoints - RPC URLs to try in order
+ * @param {object} [opts]
+ * @param {number} [opts.perAttemptTimeoutMs=4000] - Timeout per endpoint (connect + status)
+ * @param {boolean} [opts.healthCheck=true] - If true, also races status() within timeout
+ * @returns {Promise<{ tmClient: Tendermint37Client, url: string }>}
+ */
+export async function connectFailoverWithTimeout(endpoints, { perAttemptTimeoutMs = 4000, healthCheck = true } = {}) {
+  const errors = [];
+  for (const url of endpoints) {
+    try {
+      const tmClient = await withTimeout(
+        Tendermint37Client.connect(url),
+        perAttemptTimeoutMs,
+        `${url} connect`,
+      );
+      if (healthCheck) {
+        await withTimeout(tmClient.status(), perAttemptTimeoutMs, `${url} status`);
+      }
+      return { tmClient, url };
+    } catch (err) {
+      errors.push({ url, msg: err.message });
+    }
+  }
+  const e = new Error(`All RPC endpoints failed (timeout: ${perAttemptTimeoutMs}ms)`);
+  e.attempts = errors;
+  throw e;
+}
+
 /**
  * Disconnect and clear cached RPC client.
  */
@@ -402,11 +453,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 +503,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
@@ -768,8 +831,14 @@ export async function rpcQueryFeeGrantsIssued(client, granter, { limit = 100 } =
     const fields = decodeProto(new Uint8Array(response));
     // Field 1 = repeated Grant
     return (fields[1] || []).map(entry => _decodeFeeGrant(entry.value, null, granter));
-  } catch {
-    return [];
+  } catch (err) {
+    // Classify: "not found"/404 → treat as empty (genuinely no grants). Any
+    // other error (network, decode, timeout) should surface so the caller can
+    // distinguish "granter has no grants" from "RPC is broken" and fall back
+    // to LCD instead of silently returning [].
+    const msg = (err?.message || '').toLowerCase();
+    if (msg.includes('not found') || msg.includes('404')) return [];
+    throw err;
   }
 }
 
@@ -891,6 +960,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/cli.js

@@ -116,7 +116,7 @@ Sentinel SDK CLI — command-line tools for Sentinel dVPN
 
 WALLET
   balance                          Show wallet balance
-  generate                         Generate new mnemonic + address
+  generate [--out <path>]          Generate new mnemonic + address (mnemonic to stderr or 0600 file)
   address                          Show wallet address + provider address
 
 NODES
@@ -177,7 +177,9 @@ Options:
   --dns <preset>    DNS preset: handshake (default), google, cloudflare, or custom IPs
 
 Environment:
-  MNEMONIC          BIP39 mnemonic phrase (in .env file)
+  MNEMONIC          BIP39 mnemonic phrase. Prefer a 0600 file or OS keychain
+                    over .env: .env files are world-readable to processes
+                    running as the same user and are easy to commit by accident.
 `);
   },
 
@@ -192,9 +194,28 @@ Environment:
 
   async generate() {
     const { mnemonic, account } = await generateWallet();
-    console.log(`Mnemonic: ${mnemonic}`);
-    console.log(`Address:  ${account.address}`);
-    console.log(`\nSave the mnemonic in your .env file as MNEMONIC="..."`);
+    const out = flag('out', null);
+
+    if (out) {
+      const fs = await import('node:fs');
+      const path = await import('node:path');
+      const target = path.resolve(out);
+      fs.writeFileSync(target, mnemonic + '\n', { mode: 0o600 });
+      try { fs.chmodSync(target, 0o600); } catch {}
+      process.stdout.write(`Address:  ${account.address}\n`);
+      process.stderr.write(`\nMnemonic written to ${target} (mode 0600).\n`);
+      process.stderr.write(`Store this file offline — anyone who reads it controls the wallet.\n`);
+      return;
+    }
+
+    // Interactive path: print to stderr (not stdout) so the phrase does not
+    // land in shell pipelines, redirected log files, or CI stdout capture.
+    // Address goes to stdout because callers pipe it into automation safely.
+    process.stdout.write(`Address:  ${account.address}\n`);
+    process.stderr.write(`\n*** RECOVERY PHRASE — DO NOT LOG, DO NOT COMMIT ***\n`);
+    process.stderr.write(`Mnemonic: ${mnemonic}\n`);
+    process.stderr.write(`\nStore the phrase offline (hardware wallet, paper, encrypted vault).\n`);
+    process.stderr.write(`Pass --out <path> next time to write a 0600 file instead of printing.\n`);
   },
 
   async address() {

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,
@@ -49,6 +50,10 @@ export class SentinelClient extends EventEmitter {
    * @param {string} opts.rpcUrl - Default RPC URL (overridable per-call)
    * @param {string} opts.lcdUrl - Default LCD URL (overridable per-call)
    * @param {string} opts.mnemonic - Default mnemonic (overridable per-call)
+   * @param {object} opts.signer - Pre-built cosmjs OfflineDirectSigner (e.g. from
+   *   PrivyCosmosSigner.fromRawSign). When provided, takes precedence over `mnemonic`
+   *   for queries and broadcasts. NOTE: VPN connect/disconnect (tunnel handshake)
+   *   currently still requires a mnemonic — see docs/PRIVY-INTEGRATION.md.
    * @param {string} opts.v2rayExePath - Default V2Ray binary path
    * @param {function} opts.logger - Logger function (default: console.log). Set to null to suppress.
    * @param {'tofu'|'none'} opts.tlsTrust - TLS trust mode (default: 'tofu')
@@ -88,6 +93,21 @@ export class SentinelClient extends EventEmitter {
     return merged;
   }
 
+  /**
+   * Throw a helpful error if a connect path is invoked without a mnemonic.
+   * The WireGuard/V2Ray handshake currently signs locally with the cosmos privkey,
+   * so a raw-sign-only signer (e.g. Privy custody) cannot complete the tunnel
+   * handshake. Queries and broadcasts work without a mnemonic.
+   */
+  _requireMnemonicForTunnel(merged) {
+    if (typeof merged.mnemonic === 'string' && merged.mnemonic.trim().length > 0) return;
+    throw new SentinelError(ErrorCodes.INVALID_MNEMONIC,
+      'VPN connect/disconnect requires a mnemonic. A signer-only client (e.g. ' +
+      'Privy raw-sign Mode B) can broadcast TXs and query chain state, but the ' +
+      'tunnel handshake signs with the raw secp256k1 privkey. Pass `mnemonic` to ' +
+      'the constructor or to this call. See docs/PRIVY-INTEGRATION.md.');
+  }
+
   // ─── Connection ──────────────────────────────────────────────────────────
 
   /**
@@ -97,6 +117,7 @@ export class SentinelClient extends EventEmitter {
    */
   async connect(opts = {}) {
     const merged = this._mergeOpts(opts);
+    this._requireMnemonicForTunnel(merged);
     this._connection = await connectDirect(merged);
     return this._connection;
   }
@@ -109,6 +130,7 @@ export class SentinelClient extends EventEmitter {
    */
   async autoConnect(opts = {}) {
     const merged = this._mergeOpts(opts);
+    this._requireMnemonicForTunnel(merged);
     this._connection = await connectAuto(merged);
     return this._connection;
   }
@@ -120,18 +142,34 @@ export class SentinelClient extends EventEmitter {
    */
   async connectPlan(opts = {}) {
     const merged = this._mergeOpts(opts);
+    this._requireMnemonicForTunnel(merged);
     this._connection = await connectViaPlan(merged);
     return this._connection;
   }
 
   /**
-   * 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.
    */
@@ -193,16 +231,50 @@ export class SentinelClient extends EventEmitter {
   // ─── Wallet & Chain ──────────────────────────────────────────────────────
 
   /**
-   * Create or return cached wallet from mnemonic.
-   * @param {string} mnemonic - Override mnemonic (or uses instance default)
+   * Create or return cached wallet/signer.
+   *
+   * Resolution order:
+   *   1. `mnemonic` arg (per-call override) → derive a DirectSecp256k1HdWallet
+   *   2. `this._defaults.signer` (constructor-supplied OfflineDirectSigner) → use as-is
+   *   3. `this._defaults.mnemonic` → derive once, cache by mnemonic SHA
+   *
+   * Returned shape: `{ wallet, account }` — `wallet` is a cosmjs OfflineDirectSigner
+   * (DirectSecp256k1HdWallet OR a PrivyRawSignDirectSigner OR any equivalent), and
+   * `account` is the first entry from `wallet.getAccounts()`.
+   *
+   * @param {string} [mnemonic] - Optional per-call mnemonic override
    */
   async getWallet(mnemonic) {
-    const m = mnemonic || this._defaults.mnemonic;
-    if (!m) throw new SentinelError(ErrorCodes.INVALID_MNEMONIC, 'No mnemonic provided');
-    // Invalidate cache if mnemonic changed
+    // Per-call mnemonic always wins (override path).
+    if (mnemonic) {
+      if (this._wallet && this._walletMnemonic !== mnemonic) {
+        this._wallet = null;
+        this._client = null;
+      }
+      if (this._wallet) return this._wallet;
+      this._wallet = await createWallet(mnemonic);
+      this._walletMnemonic = mnemonic;
+      return this._wallet;
+    }
+    // Constructor-supplied signer (Privy raw-sign, Keplr offline signer, etc.).
+    if (this._defaults.signer) {
+      if (this._wallet) return this._wallet;
+      const accounts = await this._defaults.signer.getAccounts();
+      if (!accounts || accounts.length === 0) {
+        throw new SentinelError(ErrorCodes.INVALID_OPTIONS,
+          'signer.getAccounts() returned no accounts');
+      }
+      this._wallet = { wallet: this._defaults.signer, account: accounts[0] };
+      this._walletMnemonic = null;
+      return this._wallet;
+    }
+    // Constructor-supplied mnemonic (the original path).
+    const m = this._defaults.mnemonic;
+    if (!m) throw new SentinelError(ErrorCodes.INVALID_MNEMONIC,
+      'No mnemonic or signer provided. Pass `mnemonic` or `signer` to the SentinelClient constructor.');
     if (this._wallet && this._walletMnemonic !== m) {
       this._wallet = null;
-      this._client = null; // client depends on wallet
+      this._client = null;
     }
     if (this._wallet) return this._wallet;
     this._wallet = await createWallet(m);

package/connection/connect.js

@@ -9,13 +9,13 @@ import {
   events, _defaultState, progress, checkAborted,
   warnIfNoCleanup, cachedCreateWallet, _recordMetric,
   broadcastWithInactiveRetry, getConnectLock, setConnectLock,
-  getAbortConnect, setAbortConnect,
+  getAbortConnect, setAbortConnect, _endSessionOnChain,
 } from './state.js';
 
 import {
   createClient, privKeyFromMnemonic, broadcastWithFeeGrant,
   extractId, findExistingSession, getBalance, MSG_TYPES, queryNode,
-  isMnemonicValid, filterNodes,
+  isMnemonicValid, filterNodes, checkFeeGrant,
 } from '../cosmjs-setup.js';
 import { nodeStatusV3, waitForPort } from '../v3protocol.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,
@@ -40,11 +40,51 @@ import {
 import { performHandshake, validateTunnelRequirements, killV2RayProc, verifyDependencies } from './tunnel.js';
 import { verifyConnection } from './state.js';
 import { registerCleanupHandlers } from './disconnect.js';
+import { withMnemonicRedaction } from './logger.js';
 
-let defaultLog = console.log;
+// Default logger wraps console.log with a mnemonic redactor. Anything that
+// resembles a 12–24 word BIP-39 phrase in a log argument is replaced with
+// `[REDACTED MNEMONIC]` before it reaches stdout. Defense-in-depth — the SDK
+// does not currently log the mnemonic, but a future template-string bug or
+// careless `JSON.stringify(opts)` won't leak it through the default logger.
+let defaultLog = withMnemonicRedaction(console.log);
 
 // ─── Shared Validation ───────────────────────────────────────────────────────
 
+/**
+ * Validate a chain endpoint URL. Enforces https:// to prevent attackers from
+ * coercing the SDK into broadcasting signed TXs over cleartext HTTP — a passive
+ * network observer on http://attacker.example/rpc would see the full TX body
+ * and could correlate it to the user's wallet address. Localhost is exempted
+ * for local-node development.
+ *
+ * @param {*} url - Value to validate (allowed: undefined/null, or string)
+ * @param {string} fieldName - 'rpcUrl' or 'lcdUrl', used in error messages
+ */
+function validateChainUrl(url, fieldName) {
+  if (url == null) return;
+  if (typeof url !== 'string') {
+    throw new ValidationError(ErrorCodes.INVALID_URL, `${fieldName} must be a string URL`, { value: url });
+  }
+  let parsed;
+  try { parsed = new URL(url); }
+  catch { throw new ValidationError(ErrorCodes.INVALID_URL, `${fieldName} is not a valid URL`, { value: url }); }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new ValidationError(ErrorCodes.INVALID_URL, `${fieldName} must use http:// or https:// (got ${parsed.protocol})`, { value: url });
+  }
+  const isLocalhost = parsed.hostname === 'localhost'
+    || parsed.hostname === '127.0.0.1'
+    || parsed.hostname === '::1'
+    || parsed.hostname === '[::1]';
+  if (parsed.protocol === 'http:' && !isLocalhost) {
+    throw new ValidationError(
+      ErrorCodes.INVALID_URL,
+      `${fieldName} must use https:// for non-localhost endpoints. Cleartext HTTP leaks signed TXs and queries to network observers (got ${url}).`,
+      { value: url },
+    );
+  }
+}
+
 function validateConnectOpts(opts, fnName) {
   if (!opts || typeof opts !== 'object') throw new ValidationError(ErrorCodes.INVALID_OPTIONS, `${fnName}() requires an options object`);
   if (typeof opts.mnemonic !== 'string') {
@@ -60,8 +100,8 @@ function validateConnectOpts(opts, fnName) {
   if (typeof opts.nodeAddress !== 'string' || !/^sentnode1[a-z0-9]{38}$/.test(opts.nodeAddress)) {
     throw new ValidationError(ErrorCodes.INVALID_NODE_ADDRESS, 'nodeAddress must be a valid sentnode1... bech32 address (47 characters)', { value: opts.nodeAddress });
   }
-  if (opts.rpcUrl != null && typeof opts.rpcUrl !== 'string') throw new ValidationError(ErrorCodes.INVALID_URL, 'rpcUrl must be a string URL', { value: opts.rpcUrl });
-  if (opts.lcdUrl != null && typeof opts.lcdUrl !== 'string') throw new ValidationError(ErrorCodes.INVALID_URL, 'lcdUrl must be a string URL', { value: opts.lcdUrl });
+  validateChainUrl(opts.rpcUrl, 'rpcUrl');
+  validateChainUrl(opts.lcdUrl, 'lcdUrl');
 }
 
 // ─── Shared Connect Flow (eliminates connectDirect/connectViaPlan duplication) ─
@@ -79,8 +119,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;
@@ -97,13 +139,17 @@ async function connectInternal(opts, paymentStrategy, retryStrategy, state = _de
   // v21: parallelized — saves ~300ms (was sequential)
   progress(onProgress, logFn, 'wallet', 'Setting up wallet...');
   checkAborted(signal);
-  const [{ wallet, account }, privKey] = await Promise.all([
+  const [walletResult, privKey] = await Promise.all([
     cachedCreateWallet(opts.mnemonic),
     privKeyFromMnemonic(opts.mnemonic),
   ]);
+  const { wallet, account } = walletResult;
 
-  // Store mnemonic on state for session-end TX on disconnect (fire-and-forget cleanup)
-  state._mnemonic = opts.mnemonic;
+  // v37 (security): store the derived OfflineSigner — NOT the BIP-39 mnemonic.
+  // _endSessionOnChain only needs to sign one TX on disconnect; it doesn't need
+  // the recovery phrase. Holding the mnemonic in heap for the full session
+  // expanded the heap-dump attack surface unnecessarily.
+  state._wallet = walletResult;
 
   // 2. RPC connect + LCD lookup in parallel (independent network calls)
   // v21: parallelized — saves 1-3s (was sequential)
@@ -379,9 +425,12 @@ export async function connectDirect(opts) {
 
   // ── Fast Reconnect: check for saved credentials ──
   if (!forceNewSession) {
-    // Set mnemonic on state BEFORE fast reconnect — needed for _endSessionOnChain() on disconnect
-    (opts._state || _defaultState)._mnemonic = opts.mnemonic;
-    const fast = await tryFastReconnect(opts, opts._state || _defaultState);
+    // v37: Derive wallet BEFORE fast reconnect and stash on state — _endSessionOnChain()
+    // needs the signer, not the mnemonic. Same wallet object is reused by connectInternal()
+    // below if fast reconnect misses (cachedCreateWallet keys on mnemonic SHA256).
+    const fastState = opts._state || _defaultState;
+    fastState._wallet = await cachedCreateWallet(opts.mnemonic);
+    const fast = await tryFastReconnect(opts, fastState);
     if (fast) {
       clearCircuitBreaker(opts.nodeAddress);
       return fast;
@@ -397,7 +446,20 @@ 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}...`);
+          // v37: pass the derived wallet (set on state above) instead of the mnemonic
+          const w = (opts._state || _defaultState)._wallet;
+          if (!w) { logFn?.(`[connect] No wallet on state — skipping stale session ${staleId} cleanup`); return; }
+          _endSessionOnChain(staleId, w).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;
@@ -536,7 +598,7 @@ export async function connectAuto(opts) {
   if (opts.circuitBreaker) configureCircuitBreaker(opts.circuitBreaker);
 
   const maxAttempts = opts.maxAttempts || 3;
-  const logFn = opts.log || console.log;
+  const logFn = opts.log || defaultLog;
   const errors = [];
 
   // If nodeAddress specified, try it first (skip circuit breaker check for explicit choice)
@@ -689,6 +751,22 @@ export async function connectViaPlan(opts) {
     // Fee grant: the app passes the plan owner's address as feeGranter.
     const feeGranter = opts.feeGranter || null;
 
+    // Opt-in precheck: verify the grant exists and is not expired before the TX.
+    // Builders who prefer fail-fast over silent user-pay fallback set requireFeeGrant.
+    if (feeGranter && opts.requireFeeGrant === true) {
+      const status = await checkFeeGrant(lcdUrl, feeGranter, account.address);
+      if (!status.exists) {
+        throw new ChainError(ErrorCodes.FEE_GRANT_MISSING_AT_START,
+          `Required fee grant missing from ${feeGranter} to ${account.address}`,
+          { granter: feeGranter, grantee: account.address });
+      }
+      if (status.expired) {
+        throw new ChainError(ErrorCodes.FEE_GRANT_EXPIRED,
+          `Required fee grant expired at ${status.expiresAt?.toISOString()}`,
+          { granter: feeGranter, grantee: account.address, expiresAt: status.expiresAt });
+      }
+    }
+
     progress(null, opts.log || defaultLog, 'session', `Subscribing to plan ${opts.planId} + starting session${feeGranter ? ' (fee granted)' : ''}...`);
 
     let result;
@@ -696,8 +774,10 @@ export async function connectViaPlan(opts) {
       try {
         result = await broadcastWithFeeGrant(client, account.address, [msg], feeGranter);
       } catch (feeErr) {
-        // Fee grant TX failed — fall back to user-paid
-        progress(null, opts.log || defaultLog, 'session', 'Fee grant failed, paying gas from wallet...');
+        if (opts.requireFeeGrant === true) throw feeErr;
+        // Fee grant TX failed — fall back to user-paid (default behavior)
+        const reason = feeErr?.message ? `: ${feeErr.message}` : '';
+        progress(null, opts.log || defaultLog, 'session', `Fee grant failed${reason}, paying gas from wallet...`);
         result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
       }
     } else {
@@ -758,7 +838,7 @@ export async function connectViaSubscription(opts) {
   try {
 
   async function subPayment(ctx) {
-    const { client, account, logFn, onProgress, signal } = ctx;
+    const { client, account, lcd: lcdUrl, logFn, onProgress, signal } = ctx;
     const msg = {
       typeUrl: MSG_TYPES.SUB_START_SESSION,
       value: {
@@ -772,6 +852,22 @@ export async function connectViaSubscription(opts) {
 
     // Fee grant: operator pays gas for the agent (e.g., x402 managed plan flow)
     const feeGranter = opts.feeGranter || null;
+
+    // Opt-in precheck: verify the grant exists and is not expired before the TX.
+    if (feeGranter && opts.requireFeeGrant === true) {
+      const status = await checkFeeGrant(lcdUrl, feeGranter, account.address);
+      if (!status.exists) {
+        throw new ChainError(ErrorCodes.FEE_GRANT_MISSING_AT_START,
+          `Required fee grant missing from ${feeGranter} to ${account.address}`,
+          { granter: feeGranter, grantee: account.address });
+      }
+      if (status.expired) {
+        throw new ChainError(ErrorCodes.FEE_GRANT_EXPIRED,
+          `Required fee grant expired at ${status.expiresAt?.toISOString()}`,
+          { granter: feeGranter, grantee: account.address, expiresAt: status.expiresAt });
+      }
+    }
+
     progress(null, opts.log || defaultLog, 'session', `Starting session via subscription ${opts.subscriptionId}${feeGranter ? ' (fee granted)' : ''}...`);
 
     let result;
@@ -779,8 +875,10 @@ export async function connectViaSubscription(opts) {
       try {
         result = await broadcastWithFeeGrant(client, account.address, [msg], feeGranter);
       } catch (feeErr) {
-        // Fee grant TX failed — fall back to user-paid
-        progress(null, opts.log || defaultLog, 'session', 'Fee grant failed, paying gas from wallet...');
+        if (opts.requireFeeGrant === true) throw feeErr;
+        // Fee grant TX failed — fall back to user-paid (default behavior)
+        const reason = feeErr?.message ? `: ${feeErr.message}` : '';
+        progress(null, opts.log || defaultLog, 'session', `Fee grant failed${reason}, paying gas from wallet...`);
         result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
       }
     } else {