blue-js-sdk 2.0.0

package/chain/rpc.js

@@ -0,0 +1,408 @@
+/**
+ * Sentinel SDK — Chain / RPC Query Module
+ *
+ * RPC-based chain queries via CosmJS QueryClient + ABCI.
+ * ~912x faster than LCD for bulk queries. Uses protobuf transport.
+ *
+ * Falls back to LCD if RPC connection fails.
+ *
+ * Usage:
+ *   import { createRpcQueryClient, rpcQueryNodes, rpcQueryNode } from './chain/rpc.js';
+ *   const rpcClient = await createRpcQueryClient('https://rpc.sentinel.co:443');
+ *   const nodes = await rpcQueryNodes(rpcClient, { status: 1, limit: 100 });
+ */
+
+import { Tendermint37Client } from '@cosmjs/tendermint-rpc';
+import { QueryClient, createProtobufRpcClient } from '@cosmjs/stargate';
+import { RPC_ENDPOINTS } from '../defaults.js';
+
+// ─── RPC Client Creation ────────────────────────────────────────────────────
+
+let _cachedRpcClient = null;
+let _cachedRpcUrl = null;
+
+/**
+ * Create or return cached RPC query client with ABCI protobuf support.
+ * Tries RPC endpoints in order until one connects.
+ *
+ * @param {string} [rpcUrl] - RPC endpoint URL (defaults to first in RPC_ENDPOINTS)
+ * @returns {Promise<{ queryClient: QueryClient, rpc: ReturnType<typeof createProtobufRpcClient>, tmClient: Tendermint37Client }>}
+ */
+export async function createRpcQueryClient(rpcUrl) {
+  const url = rpcUrl || RPC_ENDPOINTS[0]?.url || 'https://rpc.sentinel.co:443';
+
+  if (_cachedRpcClient && _cachedRpcUrl === url) return _cachedRpcClient;
+
+  const tmClient = await Tendermint37Client.connect(url);
+  const queryClient = QueryClient.withExtensions(tmClient);
+  const rpc = createProtobufRpcClient(queryClient);
+
+  _cachedRpcClient = { queryClient, rpc, tmClient };
+  _cachedRpcUrl = url;
+  return _cachedRpcClient;
+}
+
+/**
+ * Try connecting to RPC endpoints in order, return first success.
+ * @returns {Promise<{ queryClient: QueryClient, rpc: ReturnType<typeof createProtobufRpcClient>, tmClient: Tendermint37Client, url: string }>}
+ */
+export async function createRpcQueryClientWithFallback() {
+  const errors = [];
+  for (const ep of RPC_ENDPOINTS) {
+    try {
+      const client = await createRpcQueryClient(ep.url);
+      return { ...client, url: ep.url };
+    } catch (err) {
+      errors.push({ url: ep.url, error: err.message });
+    }
+  }
+  throw new Error(`All RPC endpoints failed: ${errors.map(e => `${e.url}: ${e.error}`).join('; ')}`);
+}
+
+/**
+ * Disconnect and clear cached RPC client.
+ */
+export function disconnectRpc() {
+  if (_cachedRpcClient?.tmClient) {
+    _cachedRpcClient.tmClient.disconnect();
+  }
+  _cachedRpcClient = null;
+  _cachedRpcUrl = null;
+}
+
+// ─── ABCI Query Helper ─────────────────────────────────────────────────────
+
+/**
+ * Raw ABCI query — sends protobuf-encoded request to a gRPC service path.
+ * This is the low-level primitive used by all typed query functions below.
+ *
+ * @param {QueryClient} queryClient - CosmJS QueryClient
+ * @param {string} path - gRPC method path (e.g., '/sentinel.node.v3.QueryService/QueryNodes')
+ * @param {Uint8Array} requestBytes - Protobuf-encoded request
+ * @returns {Promise<Uint8Array>} Protobuf-encoded response
+ */
+async function abciQuery(queryClient, path, requestBytes) {
+  const result = await queryClient.queryAbci(path, requestBytes);
+  return result.value;
+}
+
+// ─── Protobuf Encoding Helpers (minimal, for query requests) ────────────────
+
+function encodeVarint(value) {
+  let n = BigInt(value);
+  const bytes = [];
+  do {
+    let b = Number(n & 0x7fn);
+    n >>= 7n;
+    if (n > 0n) b |= 0x80;
+    bytes.push(b);
+  } while (n > 0n);
+  return new Uint8Array(bytes);
+}
+
+function encodeString(fieldNum, str) {
+  if (!str) return new Uint8Array(0);
+  const encoder = new TextEncoder();
+  const b = encoder.encode(str);
+  const tag = encodeVarint((BigInt(fieldNum) << 3n) | 2n);
+  const len = encodeVarint(b.length);
+  const result = new Uint8Array(tag.length + len.length + b.length);
+  result.set(tag, 0);
+  result.set(len, tag.length);
+  result.set(b, tag.length + len.length);
+  return result;
+}
+
+function encodeUint64(fieldNum, value) {
+  if (!value) return new Uint8Array(0);
+  const tag = encodeVarint((BigInt(fieldNum) << 3n) | 0n);
+  const val = encodeVarint(value);
+  const result = new Uint8Array(tag.length + val.length);
+  result.set(tag, 0);
+  result.set(val, tag.length);
+  return result;
+}
+
+function encodeEnum(fieldNum, value) {
+  return encodeUint64(fieldNum, value);
+}
+
+function encodeEmbedded(fieldNum, bytes) {
+  if (!bytes || bytes.length === 0) return new Uint8Array(0);
+  const tag = encodeVarint((BigInt(fieldNum) << 3n) | 2n);
+  const len = encodeVarint(bytes.length);
+  const result = new Uint8Array(tag.length + len.length + bytes.length);
+  result.set(tag, 0);
+  result.set(len, tag.length);
+  result.set(bytes, tag.length + len.length);
+  return result;
+}
+
+function encodePagination({ limit = 100, key, countTotal = false, reverse = false } = {}) {
+  const parts = [];
+  if (key) parts.push(encodeString(1, key));  // key
+  parts.push(encodeUint64(2, limit));          // limit
+  if (countTotal) parts.push(encodeEnum(4, 1)); // count_total
+  if (reverse) parts.push(encodeEnum(5, 1));    // reverse
+  return concat(parts);
+}
+
+function concat(arrays) {
+  const totalLen = arrays.reduce((sum, a) => sum + a.length, 0);
+  const result = new Uint8Array(totalLen);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+
+// ─── Protobuf Decoding Helpers (minimal, for query responses) ───────────────
+
+/**
+ * Decode a protobuf message into a field map.
+ * Returns { fieldNumber: { wireType, value } } for each field.
+ * Wire types: 0=varint, 2=length-delimited
+ */
+function decodeProto(buf) {
+  const fields = {};
+  let i = 0;
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+
+  while (i < buf.length) {
+    // Read tag
+    let tag = 0n;
+    let shift = 0n;
+    while (i < buf.length) {
+      const b = buf[i++];
+      tag |= BigInt(b & 0x7f) << shift;
+      shift += 7n;
+      if (!(b & 0x80)) break;
+    }
+
+    const fieldNum = Number(tag >> 3n);
+    const wireType = Number(tag & 0x7n);
+
+    if (wireType === 0) {
+      // Varint
+      let val = 0n;
+      let s = 0n;
+      while (i < buf.length) {
+        const b = buf[i++];
+        val |= BigInt(b & 0x7f) << s;
+        s += 7n;
+        if (!(b & 0x80)) break;
+      }
+      if (!fields[fieldNum]) fields[fieldNum] = [];
+      fields[fieldNum].push({ wireType, value: val });
+    } else if (wireType === 2) {
+      // Length-delimited
+      let len = 0n;
+      let s = 0n;
+      while (i < buf.length) {
+        const b = buf[i++];
+        len |= BigInt(b & 0x7f) << s;
+        s += 7n;
+        if (!(b & 0x80)) break;
+      }
+      const numLen = Number(len);
+      const data = buf.slice(i, i + numLen);
+      i += numLen;
+      if (!fields[fieldNum]) fields[fieldNum] = [];
+      fields[fieldNum].push({ wireType, value: data });
+    } else if (wireType === 5) {
+      // 32-bit fixed
+      i += 4;
+    } else if (wireType === 1) {
+      // 64-bit fixed
+      i += 8;
+    }
+  }
+
+  return fields;
+}
+
+function decodeString(data) {
+  return new TextDecoder().decode(data);
+}
+
+function decodeRepeatedMessages(fieldEntries) {
+  if (!fieldEntries) return [];
+  return fieldEntries.map(entry => decodeProto(entry.value));
+}
+
+// ─── Node Decoder ───────────────────────────────────────────────────────────
+
+function decodePrice(fields) {
+  return {
+    denom: fields[1]?.[0] ? decodeString(fields[1][0].value) : '',
+    base_value: fields[2]?.[0] ? decodeString(fields[2][0].value) : '0',
+    quote_value: fields[3]?.[0] ? decodeString(fields[3][0].value) : '0',
+  };
+}
+
+function decodeNode(fields) {
+  return {
+    address: fields[1]?.[0] ? decodeString(fields[1][0].value) : '',
+    gigabyte_prices: (fields[2] || []).map(f => decodePrice(decodeProto(f.value))),
+    hourly_prices: (fields[3] || []).map(f => decodePrice(decodeProto(f.value))),
+    remote_addrs: (fields[4] || []).map(f => decodeString(f.value)),
+    status: fields[6]?.[0] ? Number(fields[6][0].value) : 0,
+  };
+}
+
+// ─── Typed Query Functions ──────────────────────────────────────────────────
+
+/**
+ * Query active nodes via RPC.
+ *
+ * @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 } = {}) {
+  const path = '/sentinel.node.v3.QueryService/QueryNodes';
+  const request = concat([
+    encodeEnum(1, status),                                        // status field
+    encodeEmbedded(2, encodePagination({ limit })),               // pagination field
+  ]);
+
+  const response = await abciQuery(client.queryClient, path, request);
+  const fields = decodeProto(new Uint8Array(response));
+
+  // Field 1 = repeated Node
+  const nodes = (fields[1] || []).map(entry => decodeNode(decodeProto(entry.value)));
+  return nodes;
+}
+
+/**
+ * Query a single node by address via RPC.
+ *
+ * @param {{ queryClient: QueryClient }} client
+ * @param {string} address - sentnode1... address
+ * @returns {Promise<object|null>}
+ */
+export async function rpcQueryNode(client, address) {
+  const path = '/sentinel.node.v3.QueryService/QueryNode';
+  const request = encodeString(1, address);
+
+  try {
+    const response = await abciQuery(client.queryClient, path, request);
+    const fields = decodeProto(new Uint8Array(response));
+    // Field 1 = Node
+    if (!fields[1]?.[0]) return null;
+    return decodeNode(decodeProto(fields[1][0].value));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query nodes linked to a plan via RPC.
+ *
+ * @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 } = {}) {
+  const path = '/sentinel.node.v3.QueryService/QueryNodesForPlan';
+  const request = concat([
+    encodeUint64(1, planId),                                     // id
+    encodeEnum(2, status),                                        // status
+    encodeEmbedded(3, encodePagination({ limit })),               // pagination
+  ]);
+
+  const response = await abciQuery(client.queryClient, path, request);
+  const fields = decodeProto(new Uint8Array(response));
+  return (fields[1] || []).map(entry => decodeNode(decodeProto(entry.value)));
+}
+
+/**
+ * Query sessions for an account via RPC.
+ *
+ * @param {{ queryClient: QueryClient }} client
+ * @param {string} address - sent1... address
+ * @param {{ limit?: number }} [opts]
+ * @returns {Promise<Array<Uint8Array>>} Raw session Any-encoded bytes (need type-specific decoding)
+ */
+export async function rpcQuerySessionsForAccount(client, address, { limit = 100 } = {}) {
+  const path = '/sentinel.session.v3.QueryService/QuerySessionsForAccount';
+  const request = concat([
+    encodeString(1, address),
+    encodeEmbedded(2, encodePagination({ limit })),
+  ]);
+
+  const response = await abciQuery(client.queryClient, path, request);
+  const fields = decodeProto(new Uint8Array(response));
+  // Field 1 = repeated google.protobuf.Any (sessions)
+  return (fields[1] || []).map(entry => entry.value);
+}
+
+/**
+ * Query subscriptions for an account via RPC.
+ *
+ * @param {{ queryClient: QueryClient }} client
+ * @param {string} address - sent1... address
+ * @param {{ limit?: number }} [opts]
+ * @returns {Promise<Array<Uint8Array>>} Raw subscription bytes
+ */
+export async function rpcQuerySubscriptionsForAccount(client, address, { limit = 100 } = {}) {
+  const path = '/sentinel.subscription.v3.QueryService/QuerySubscriptionsForAccount';
+  const request = concat([
+    encodeString(1, address),
+    encodeEmbedded(2, encodePagination({ limit })),
+  ]);
+
+  const response = await abciQuery(client.queryClient, path, request);
+  const fields = decodeProto(new Uint8Array(response));
+  return (fields[1] || []).map(entry => entry.value);
+}
+
+/**
+ * Query a single plan by ID via RPC.
+ *
+ * @param {{ queryClient: QueryClient }} client
+ * @param {number|bigint} planId
+ * @returns {Promise<Uint8Array|null>} Raw plan bytes
+ */
+export async function rpcQueryPlan(client, planId) {
+  const path = '/sentinel.plan.v3.QueryService/QueryPlan';
+  const request = encodeUint64(1, planId);
+
+  try {
+    const response = await abciQuery(client.queryClient, path, request);
+    const fields = decodeProto(new Uint8Array(response));
+    return fields[1]?.[0]?.value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query wallet balance via RPC (uses cosmos bank module).
+ *
+ * @param {{ queryClient: QueryClient }} client
+ * @param {string} address - sent1... address
+ * @param {string} [denom='udvpn']
+ * @returns {Promise<{ denom: string, amount: string }>}
+ */
+export async function rpcQueryBalance(client, address, denom = 'udvpn') {
+  const path = '/cosmos.bank.v1beta1.Query/Balance';
+  const request = concat([
+    encodeString(1, address),
+    encodeString(2, denom),
+  ]);
+
+  const response = await abciQuery(client.queryClient, path, request);
+  const fields = decodeProto(new Uint8Array(response));
+
+  // Field 1 = Coin (embedded)
+  if (!fields[1]?.[0]) return { denom, amount: '0' };
+  const coinFields = decodeProto(fields[1][0].value);
+  return {
+    denom: coinFields[1]?.[0] ? decodeString(coinFields[1][0].value) : denom,
+    amount: coinFields[2]?.[0] ? decodeString(coinFields[2][0].value) : '0',
+  };
+}

package/chain/wallet.js

@@ -0,0 +1,141 @@
+/**
+ * Sentinel SDK — Chain / Wallet Module
+ *
+ * Wallet creation, mnemonic validation, private key derivation,
+ * and bech32 address prefix conversion.
+ *
+ * Usage:
+ *   import { createWallet, generateWallet, privKeyFromMnemonic } from './chain/wallet.js';
+ *   const { wallet, account } = await createWallet(mnemonic);
+ */
+
+import { Bip39, EnglishMnemonic, Slip10, Slip10Curve, Random } from '@cosmjs/crypto';
+import { makeCosmoshubPath } from '@cosmjs/amino';
+import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';
+import { fromBech32, toBech32 } from '@cosmjs/encoding';
+import { ValidationError, ErrorCodes } from '../errors.js';
+
+// ─── Input Validation Helpers ────────────────────────────────────────────────
+
+/**
+ * Validate a BIP39 mnemonic string against the English wordlist.
+ * Returns true if valid (12/15/18/21/24 words, all in BIP39 list, valid checksum).
+ * Use this to enable/disable a "Connect" button in your UI.
+ *
+ * @param {string} mnemonic - The mnemonic to validate
+ * @returns {boolean} True if the mnemonic is a valid BIP39 English mnemonic
+ *
+ * @example
+ *   if (isMnemonicValid(userInput)) showConnectButton();
+ */
+export function isMnemonicValid(mnemonic) {
+  if (typeof mnemonic !== 'string') return false;
+  const trimmed = mnemonic.trim();
+  if (trimmed.split(/\s+/).length < 12) return false;
+  try {
+    // EnglishMnemonic constructor validates word count, wordlist membership, and checksum
+    new EnglishMnemonic(trimmed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function validateMnemonic(mnemonic, fnName) {
+  if (typeof mnemonic !== 'string') {
+    throw new ValidationError(ErrorCodes.INVALID_MNEMONIC,
+      `${fnName}(): mnemonic must be a string`, { wordCount: 0 });
+  }
+  const words = mnemonic.trim().split(/\s+/);
+  if (words.length < 12) {
+    throw new ValidationError(ErrorCodes.INVALID_MNEMONIC,
+      `${fnName}(): mnemonic must have at least 12 words`,
+      { wordCount: words.length });
+  }
+  if (!isMnemonicValid(mnemonic)) {
+    throw new ValidationError(ErrorCodes.INVALID_MNEMONIC,
+      `${fnName}(): mnemonic contains invalid BIP39 words or failed checksum`,
+      { wordCount: words.length });
+  }
+}
+
+export function validateAddress(addr, prefix, fnName) {
+  if (typeof addr !== 'string' || !addr.startsWith(prefix)) {
+    throw new ValidationError(ErrorCodes.INVALID_NODE_ADDRESS,
+      `${fnName}(): address must be a valid ${prefix}... bech32 string`,
+      { value: addr });
+  }
+}
+
+// ─── Wallet ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a Sentinel wallet from a BIP39 mnemonic.
+ * Returns { wallet, account } where account.address is the sent1... address.
+ */
+export async function createWallet(mnemonic) {
+  validateMnemonic(mnemonic, 'createWallet');
+  const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, { prefix: 'sent' });
+  const [account] = await wallet.getAccounts();
+  return { wallet, account };
+}
+
+/**
+ * Generate a new wallet with a fresh random BIP39 mnemonic.
+ * @param {number} strength - 128 for 12 words, 256 for 24 words (default: 128)
+ * @returns {{ mnemonic: string, wallet: DirectSecp256k1HdWallet, account: { address: string } }}
+ */
+export async function generateWallet(strength = 128) {
+  const entropy = Random.getBytes(strength / 8);
+  const mnemonic = Bip39.encode(entropy).toString();
+  const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, { prefix: 'sent' });
+  const [account] = await wallet.getAccounts();
+  return { mnemonic, wallet, account };
+}
+
+/**
+ * Derive the raw secp256k1 private key from a mnemonic.
+ * Needed for handshake signatures (node-handshake protocol).
+ */
+export async function privKeyFromMnemonic(mnemonic) {
+  validateMnemonic(mnemonic, 'privKeyFromMnemonic');
+  const seed = await Bip39.mnemonicToSeed(new EnglishMnemonic(mnemonic));
+  const { privkey } = Slip10.derivePath(Slip10Curve.Secp256k1, seed, makeCosmoshubPath(0));
+  return Buffer.from(privkey);
+}
+
+// ─── Address Prefix Conversion ───────────────────────────────────────────────
+// Same key, different bech32 prefix. See address-prefixes.md.
+
+export function sentToSentprov(sentAddr) {
+  validateAddress(sentAddr, 'sent', 'sentToSentprov');
+  const { data } = fromBech32(sentAddr);
+  return toBech32('sentprov', data);
+}
+
+export function sentToSentnode(sentAddr) {
+  validateAddress(sentAddr, 'sent', 'sentToSentnode');
+  const { data } = fromBech32(sentAddr);
+  return toBech32('sentnode', data);
+}
+
+export function sentprovToSent(provAddr) {
+  validateAddress(provAddr, 'sentprov', 'sentprovToSent');
+  const { data } = fromBech32(provAddr);
+  return toBech32('sent', data);
+}
+
+/**
+ * Compare two addresses across different bech32 prefixes (sent1, sentprov1, sentnode1).
+ * Returns true if they derive from the same public key.
+ * @param {string} addr1
+ * @param {string} addr2
+ * @returns {boolean}
+ */
+export function isSameKey(addr1, addr2) {
+  try {
+    const { data: d1 } = fromBech32(addr1);
+    const { data: d2 } = fromBech32(addr2);
+    return Buffer.from(d1).equals(Buffer.from(d2));
+  } catch { return false; }
+}

package/cli/config.js

@@ -0,0 +1,143 @@
+/**
+ * Sentinel CLI — Configuration Management
+ *
+ * Reads/writes ~/.sentinel/config.json for persistent CLI settings.
+ * Prompts for mnemonic on first run if not configured.
+ *
+ * No external dependencies — uses Node.js built-ins only.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { createInterface } from 'readline';
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+const CONFIG_DIR = join(homedir(), '.sentinel');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG = {
+  mnemonic: '',
+  rpc: 'https://rpc.sentinel.co:443',
+  lcd: 'https://lcd.sentinel.co',
+  gigabytes: 1,
+  denom: 'udvpn',
+};
+
+// ─── Read/Write ──────────────────────────────────────────────────────────────
+
+/**
+ * Load config from ~/.sentinel/config.json.
+ * Returns defaults merged with any saved values.
+ * @returns {object}
+ */
+export function loadConfig() {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      const raw = readFileSync(CONFIG_FILE, 'utf8');
+      const saved = JSON.parse(raw);
+      return { ...DEFAULT_CONFIG, ...saved };
+    }
+  } catch {
+    // Corrupted config — fall back to defaults
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+/**
+ * Save config to ~/.sentinel/config.json.
+ * Creates ~/.sentinel/ directory if it does not exist.
+ * @param {object} config
+ */
+export function saveConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+}
+
+/**
+ * Get a single config value, with CLI flag override.
+ * Priority: flag > config file > default.
+ * @param {string} key
+ * @param {*} flagValue - Value from CLI flag (undefined if not set)
+ * @returns {*}
+ */
+export function getConfigValue(key, flagValue) {
+  if (flagValue !== undefined && flagValue !== null) return flagValue;
+  const config = loadConfig();
+  return config[key] ?? DEFAULT_CONFIG[key];
+}
+
+// ─── Interactive Prompt ──────────────────────────────────────────────────────
+
+/**
+ * Prompt user for input on stdin. Used for first-run mnemonic setup.
+ * @param {string} question
+ * @param {boolean} [hidden=false] - If true, input is not echoed (for secrets)
+ * @returns {Promise<string>}
+ */
+export function prompt(question, hidden = false) {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stderr,
+    });
+
+    if (hidden) {
+      process.stderr.write(question);
+      const onData = (char) => {
+        const c = char.toString();
+        if (c === '\n' || c === '\r') {
+          process.stdin.removeListener('data', onData);
+          process.stderr.write('\n');
+          rl.close();
+          resolve(rl.line || '');
+          return;
+        }
+        // Suppress echo by not writing back
+      };
+      process.stdin.setRawMode?.(true);
+      process.stdin.resume();
+      process.stdin.on('data', onData);
+    } else {
+      rl.question(question, (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      });
+    }
+  });
+}
+
+/**
+ * Ensure mnemonic is available. Checks config, then prompts user.
+ * Saves to config on first entry so subsequent runs skip the prompt.
+ * @returns {Promise<string>}
+ */
+export async function ensureMnemonic() {
+  const config = loadConfig();
+  if (config.mnemonic) return config.mnemonic;
+
+  // Check environment variable as fallback
+  if (process.env.MNEMONIC) return process.env.MNEMONIC;
+
+  process.stderr.write('\n  No mnemonic configured.\n');
+  process.stderr.write('  Enter your BIP39 mnemonic to get started.\n');
+  process.stderr.write('  It will be saved to ~/.sentinel/config.json\n\n');
+
+  const mnemonic = await prompt('  Mnemonic: ', true); // hidden=true: suppress echo
+  if (!mnemonic) {
+    process.stderr.write('  No mnemonic provided. Exiting.\n');
+    process.exit(1);
+  }
+
+  config.mnemonic = mnemonic;
+  saveConfig(config);
+  process.stderr.write('  Saved.\n\n');
+  return mnemonic;
+}
+
+// ─── Config Path Export ──────────────────────────────────────────────────────
+
+export { CONFIG_DIR, CONFIG_FILE, DEFAULT_CONFIG };