blue-js-sdk 2.6.0 → 2.7.0

package/app-helpers.js

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

package/chain/broadcast.js

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

package/chain/fee-grants.js

@@ -185,6 +185,62 @@ export async function queryFeeGrant(lcdUrl, granter, grantee) {
   } catch { return null; } // 404 = no grant
 }
 
+/**
+ * Builder-friendly fee-grant check. Returns a parsed, normalized status so
+ * callers don't have to walk nested `AllowedMsgAllowance` → `BasicAllowance`
+ * shapes. Use this before broadcasting plan/subscription sessions that rely on
+ * a granter paying gas.
+ *
+ * RPC-first with LCD fallback. Either both granter+grantee, or pre-fetched
+ * allowance object can be passed.
+ *
+ * @param {string} lcdUrl - LCD endpoint (for fallback)
+ * @param {string} granter - sent1... granter address
+ * @param {string} grantee - sent1... grantee address
+ * @returns {Promise<{ exists: boolean, expired: boolean, expiresAt: Date|null, spendLimit: Array<{denom:string,amount:string}>, allowedMessages: string[]|null, typeUrl: string, raw: object|null }>}
+ */
+export async function checkFeeGrant(lcdUrl, granter, grantee) {
+  const allowance = await queryFeeGrant(lcdUrl, granter, grantee);
+  if (!allowance) {
+    return {
+      exists: false,
+      expired: false,
+      expiresAt: null,
+      spendLimit: [],
+      allowedMessages: null,
+      typeUrl: '',
+      raw: null,
+    };
+  }
+
+  // If shape is { granter, grantee, allowance: {...} } from rpcQueryFeeGrant
+  const inner = allowance.allowance || allowance;
+  const typeUrl = inner['@type'] || '';
+  let basic = inner;
+  let allowedMessages = null;
+  if (typeUrl.includes('AllowedMsgAllowance')) {
+    allowedMessages = inner.allowed_messages || [];
+    basic = inner.allowance || null;
+  }
+
+  const spendLimit = (basic?.spend_limit || []).map(c => ({
+    denom: c.denom,
+    amount: String(c.amount || '0'),
+  }));
+  const expiresAt = basic?.expiration ? new Date(basic.expiration) : null;
+  const expired = expiresAt ? expiresAt.getTime() <= Date.now() : false;
+
+  return {
+    exists: true,
+    expired,
+    expiresAt,
+    spendLimit,
+    allowedMessages,
+    typeUrl,
+    raw: allowance,
+  };
+}
+
 // ─── Fee Grant Workflow Helpers (v25b) ────────────────────────────────────────
 
 /**
@@ -194,19 +250,26 @@ export async function queryFeeGrant(lcdUrl, granter, grantee) {
  * @param {number|string} planId
  * @param {object} opts
  * @param {string} opts.granterAddress - Who pays fees (typically plan owner)
- * @param {string} opts.lcdUrl - LCD endpoint
+ * @param {string} [opts.lcdUrl] - LCD endpoint (used as fallback when RPC unavailable)
+ * @param {boolean} [opts.preferRpc=true] - Force RPC for all queries, skip LCD URL for grant lookup
+ * @param {object} [opts.rpcClient] - Pre-built RPC client to inject (skips internal createRpcQueryClientWithFallback)
  * @param {object} [opts.grantOpts] - Options for buildFeeGrantMsg (spendLimit, expiration, allowedMessages)
  * @returns {Promise<{ msgs: Array, skipped: string[], newGrants: string[] }>} Messages ready for broadcast
  */
 export async function grantPlanSubscribers(planId, opts = {}) {
-  const { granterAddress, lcdUrl, grantOpts = {} } = opts;
+  const { granterAddress, lcdUrl, preferRpc = true, rpcClient, grantOpts = {} } = opts;
   if (!granterAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'granterAddress is required');
 
-  // Get subscribers
+  // Get subscribers — already RPC-first internally
   const { subscribers } = await queryPlanSubscribers(planId, { lcdUrl });
 
-  // Get existing grants ISSUED BY granter (not grants received)
-  const existingGrants = await queryFeeGrantsIssued(lcdUrl || LCD_ENDPOINTS[0].url, granterAddress);
+  // Get existing grants ISSUED BY granter.
+  // preferRpc=true: pass null lcdUrl so internal getRpcClient() path is taken first.
+  // preferRpc=false: pass lcdUrl so LCD is used (useful when RPC is blocked).
+  const grantLcdUrl = preferRpc ? null : (lcdUrl || LCD_ENDPOINTS[0].url);
+  const existingGrants = rpcClient
+    ? await _rpcQueryFeeGrantsIssued(rpcClient, granterAddress).catch(() => queryFeeGrantsIssued(grantLcdUrl, granterAddress))
+    : await queryFeeGrantsIssued(grantLcdUrl, granterAddress);
   const alreadyGranted = new Set(existingGrants.map(g => g.grantee));
 
   const msgs = [];
@@ -375,7 +438,9 @@ export function monitorFeeGrants(opts = {}) {
  * @param {number|string} planId
  * @param {object} opts
  * @param {string} opts.granterAddress - Plan owner paying fees
- * @param {string} opts.lcdUrl - LCD endpoint
+ * @param {string} [opts.lcdUrl] - LCD endpoint (used as fallback when RPC unavailable)
+ * @param {boolean} [opts.preferRpc=true] - Force RPC for all queries, skip LCD URL for grant lookup
+ * @param {object} [opts.rpcClient] - Pre-built RPC client to inject (skips internal createRpcQueryClientWithFallback)
  * @param {(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
@@ -386,6 +451,8 @@ export async function* streamGrantPlanSubscribers(planId, opts = {}) {
   const {
     granterAddress,
     lcdUrl,
+    preferRpc = true,
+    rpcClient,
     broadcast,
     grantOpts = {},
     batchSize = 5,
@@ -416,7 +483,10 @@ export async function* streamGrantPlanSubscribers(planId, opts = {}) {
     }
 
     yield { type: 'status', msg: 'Checking existing grants...' };
-    const existing = await queryFeeGrantsIssued(lcdUrl || LCD_ENDPOINTS[0].url, granterAddress);
+    const streamLcdUrl = preferRpc ? null : (lcdUrl || LCD_ENDPOINTS[0].url);
+    const existing = rpcClient
+      ? await _rpcQueryFeeGrantsIssued(rpcClient, granterAddress).catch(() => queryFeeGrantsIssued(streamLcdUrl, granterAddress))
+      : await queryFeeGrantsIssued(streamLcdUrl, granterAddress);
     const existingGrantees = new Set(existing.map(g => g.grantee));
     const needGrant = uniqueAddrs.filter(a => !existingGrantees.has(a));
     const skipped = uniqueAddrs.length - needGrant.length;

package/chain/queries.js

@@ -618,8 +618,80 @@ export async function querySubscriptionAllocations(subscriptionId, lcdUrl) {
   } catch { return []; }
 }
 
+/**
+ * Normalize chain status values from RPC (numeric: 1=active, 2=inactive, 3=pending)
+ * and LCD (strings: "STATUS_ACTIVE", "STATUS_INACTIVE", "STATUS_INACTIVE_PENDING").
+ * Returns true only for the ACTIVE status, never for INACTIVE_PENDING (status=3),
+ * which is a transient terminal state and should never be treated as connectable.
+ *
+ * @param {number|string|undefined} v
+ * @returns {boolean}
+ */
+export function isActiveStatus(v) {
+  if (v === 1 || v === '1') return true;
+  if (typeof v === 'string') return v === 'STATUS_ACTIVE' || v === 'active';
+  return false;
+}
+
 // ─── Plan Subscriber Helpers (v25b) ──────────────────────────────────────────
 
+/**
+ * Query a single plan's metadata. RPC-first with LCD fallback.
+ *
+ * Returns the plan's provider (sentprov1...), price list, duration, bytes quota,
+ * and status. Builders use this before connecting through a plan subscription to
+ * resolve the plan owner (the address that typically acts as fee granter for
+ * MsgStartSubscriptionRequest + MsgPlanStartSession TXs).
+ *
+ * NOTE: `prov_address` is a sentprov1... provider address, which is usually
+ * derived from a sent1... account address. If you need the operator's sent1...
+ * account (the expected fee granter), either pass it in explicitly via app
+ * config or call `getProviderByAddress(prov_address)` and read `.address`.
+ *
+ * @param {number|string} planId
+ * @param {object} [opts]
+ * @param {string} [opts.lcdUrl]
+ * @returns {Promise<{ planId: string, provider: string, prices: Array, bytes: string, duration: string, status: number, statusAt: string|null, private: boolean } | null>}
+ */
+export async function queryPlanDetails(planId, opts = {}) {
+  // RPC-first
+  try {
+    const rpc = await getRpcClient();
+    if (rpc) {
+      const plan = await rpcQueryPlan(rpc, planId);
+      if (plan) {
+        return {
+          planId: String(plan.id),
+          provider: plan.prov_address,
+          prices: plan.prices || [],
+          bytes: plan.bytes || '0',
+          duration: plan.duration || '0s',
+          status: plan.status,
+          statusAt: plan.status_at,
+          private: plan.private === true,
+        };
+      }
+    }
+  } catch { /* fall through to LCD */ }
+
+  // LCD fallback: /sentinel/plan/v3/plans/{planId}
+  try {
+    const data = await lcdQuery(`/sentinel/plan/v3/plans/${planId}`, { lcdUrl: opts.lcdUrl });
+    const plan = data?.plan;
+    if (!plan) return null;
+    return {
+      planId: String(plan.id),
+      provider: plan.prov_address || plan.provider_address || '',
+      prices: plan.prices || [],
+      bytes: plan.bytes || '0',
+      duration: plan.duration || '0s',
+      status: typeof plan.status === 'number' ? plan.status : (plan.status === 'STATUS_ACTIVE' ? 1 : 2),
+      statusAt: plan.status_at || null,
+      private: plan.private === true,
+    };
+  } catch { return null; }
+}
+
 /**
  * Query all subscriptions for a plan. Supports owner filtering.
  * RPC-first with LCD fallback.

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.
  */
@@ -780,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;
   }
 }
 

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

@@ -50,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')
@@ -89,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 ──────────────────────────────────────────────────────────
 
   /**
@@ -98,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;
   }
@@ -110,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;
   }
@@ -121,6 +142,7 @@ export class SentinelClient extends EventEmitter {
    */
   async connectPlan(opts = {}) {
     const merged = this._mergeOpts(opts);
+    this._requireMnemonicForTunnel(merged);
     this._connection = await connectViaPlan(merged);
     return this._connection;
   }
@@ -209,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);