blue-js-sdk 2.6.0 → 2.7.1

package/defaults.js

@@ -25,12 +25,14 @@ axios.defaults.adapter = 'http';
 // This is the npm/semver version for consumers. Internal development iterations
 // (v20, v21, v22, etc.) track feature milestones and are not exposed as exports.
 
-export const SDK_VERSION = '2.4.0';
+export const SDK_VERSION = '2.7.1';
 
 // ─── Timestamps ──────────────────────────────────────────────────────────────
 
-/** When these defaults were last verified against the live chain */
-export const LAST_VERIFIED = '2026-03-08T00:00:00Z';
+/** When these defaults were last verified against the live chain.
+ *  RPC + LCD endpoint lists refreshed 2026-05-02 (audit-rpc-endpoints.mjs).
+ *  Other defaults (gas, transport rates, etc.) still 2026-03-08. */
+export const LAST_VERIFIED = '2026-05-02T00:00:00Z';
 
 /** Human-readable note for builders */
 export const HARDCODED_NOTE = 'Static defaults — no RPC query server yet. Verify endpoints are live before production use. See README.md "Hardcoded Defaults" section.';
@@ -44,28 +46,48 @@ export const CHAIN_VERSION = 'v12.0.0';     // sentinelhub version
 export const COSMOS_SDK_VERSION = '0.47.17';
 
 // ─── RPC Endpoints (TX broadcast) ────────────────────────────────────────────
-// Ordered by reliability. Primary is tried first, fallbacks on failure.
-// Verified reachable 2026-03-08.
+// Latency-sorted list of endpoints that passed consensus health check on
+// 2026-05-02. "Healthy" means: connects, /status reports catching_up=false,
+// and the bank balance for a known address matches the modal answer across
+// all responding candidates within 50 blocks of tip. Run
+// `node tools/audit-rpc-endpoints.mjs` to refresh.
+//
+// rpc.sentinel.co / lcd.sentinel.co are intentionally excluded: on 2026-05-02
+// they were ~22k blocks behind tip and returning 0 for funded addresses while
+// reporting catching_up=false on /status. Consumers that need them can add
+// them at runtime via addRpcEndpoint() / addLcdEndpoint().
 
 export const RPC_ENDPOINTS = [
-  { url: 'https://rpc.sentinel.co:443',           name: 'Sentinel Official',  verified: '2026-03-08' },
-  { url: 'https://sentinel-rpc.polkachu.com',     name: 'Polkachu',           verified: '2026-03-08' },
-  { url: 'https://rpc.mathnodes.com',             name: 'MathNodes',          verified: '2026-03-08' },
-  { url: 'https://sentinel-rpc.publicnode.com',   name: 'PublicNode',         verified: '2026-03-08' },
-  { url: 'https://rpc.sentinel.quokkastake.io',   name: 'QuokkaStake',       verified: '2026-03-08' },
+  { url: 'https://rpc-sentinel.busurnode.com',      name: 'Busurnode',             verified: '2026-05-02' },
+  { url: 'https://rpc.trinitystake.io',             name: 'Trinity Stake',         verified: '2026-05-02' },
+  { url: 'https://sentinel-rpc.publicnode.com',     name: 'PublicNode (Allnodes)', verified: '2026-05-02' },
+  { url: 'https://sentinel-rpc.polkachu.com',       name: 'Polkachu',              verified: '2026-05-02' },
+  { url: 'https://rpc.mathnodes.com',               name: 'MathNodes',             verified: '2026-05-02' },
+  { url: 'https://rpc.dvpn.roomit.xyz',             name: 'Roomit',                verified: '2026-05-02' },
+  { url: 'https://rpc.sentinel.suchnode.net',       name: 'SuchNode',              verified: '2026-05-02' },
+  { url: 'https://rpc.sentinel.chaintools.tech',    name: 'ChainTools',            verified: '2026-05-02' },
+  { url: 'https://rpc.sentinel.validatus.com',      name: 'Validatus',             verified: '2026-05-02' },
+  { url: 'https://rpc.sentinel.quokkastake.io',     name: 'QuokkaStake',           verified: '2026-05-02' },
+  { url: 'https://rpc.sentineldao.com',             name: 'Sentinel Growth DAO',   verified: '2026-05-02' },
+  { url: 'https://rpc-sentinel.chainvibes.com',     name: 'ChainVibes',            verified: '2026-05-02' },
 ];
 
 export const DEFAULT_RPC = RPC_ENDPOINTS[0].url;
 
 // ─── LCD Endpoints (REST queries) ────────────────────────────────────────────
-// Ordered by reliability. All have same limitations (v3 providers = 501, plan details = 501).
-// Verified reachable 2026-03-08.
+// Same consensus methodology as RPC. lcd.sentinel.co excluded for the same
+// stale-state reason.
 
 export const LCD_ENDPOINTS = [
-  { url: 'https://lcd.sentinel.co',               name: 'Sentinel Official',  verified: '2026-03-08' },
-  { url: 'https://sentinel-api.polkachu.com',     name: 'Polkachu',           verified: '2026-03-08' },
-  { url: 'https://api.sentinel.quokkastake.io',   name: 'QuokkaStake',       verified: '2026-03-08' },
-  { url: 'https://sentinel-rest.publicnode.com',   name: 'PublicNode',         verified: '2026-03-08' },
+  { url: 'https://api-sentinel.busurnode.com',      name: 'Busurnode',             verified: '2026-05-02' },
+  { url: 'https://sentinel-rest.publicnode.com',    name: 'PublicNode (Allnodes)', verified: '2026-05-02' },
+  { url: 'https://api.sentinel.suchnode.net',       name: 'SuchNode',              verified: '2026-05-02' },
+  { url: 'https://sentinel-api.polkachu.com',       name: 'Polkachu',              verified: '2026-05-02' },
+  { url: 'https://api.dvpn.roomit.xyz',             name: 'Roomit',                verified: '2026-05-02' },
+  { url: 'https://api.sentinel.quokkastake.io',     name: 'QuokkaStake',           verified: '2026-05-02' },
+  { url: 'https://api.sentinel.chaintools.tech',    name: 'ChainTools',            verified: '2026-05-02' },
+  { url: 'https://api-sentinel.chainvibes.com',     name: 'ChainVibes',            verified: '2026-05-02' },
+  { url: 'https://api.sentinel.validatus.com',      name: 'Validatus',             verified: '2026-05-02' },
 ];
 
 export const DEFAULT_LCD = LCD_ENDPOINTS[0].url;

package/docs/PRIVY-INTEGRATION.md

@@ -0,0 +1,177 @@
+# Privy Integration
+
+Privy provides embedded EVM/Solana wallets but has no native Cosmos signer. This SDK ships an adapter that bridges a Privy-held key to a cosmjs-compatible Cosmos signer, so a consumer can use Privy for auth/onboarding while still using every Sentinel SDK helper that takes a `wallet`.
+
+The adapter lives in `auth/privy-cosmos-signer.js` and is re-exported from the SDK root.
+
+## Two strategies
+
+The adapter supports two paths, selected by the `mode` field on `createPrivyCosmosSigner`. Pick the one that matches your custody requirements.
+
+### Mode A — `mnemonic` (seed-import)
+
+The consumer triggers Privy's `exportWallet()`. The user reveals their seed once. The adapter re-derives a Cosmos secp256k1 key on the standard Cosmos HD path (`m/44'/118'/0'/0/0`) and wraps it in `DirectSecp256k1HdWallet`.
+
+```js
+import { PrivyCosmosSigner } from 'blue-js-sdk';
+
+const signer = await PrivyCosmosSigner.fromMnemonic({
+  mnemonic: privyExportedSeed,
+  prefix: 'sent',
+});
+
+const [account] = await signer.getAccounts();
+// account.address === 'sent1...'
+```
+
+Trust model: identical to a normal mnemonic wallet — the seed has left Privy's enclave. Use this when you need full broadcast capability and your UX can prompt the user to export once.
+
+### Mode B — `rawSign` (custody-preserving)
+
+The seed never leaves Privy. The consumer supplies:
+
+- `pubkey` — the compressed secp256k1 pubkey (33 bytes) Privy derived for this user on the Cosmos `m/44'/118'/0'/0/0` path.
+- `signRawSecp256k1(digest32)` — async function that asks Privy to produce a 64-byte (`r||s`) signature over the supplied 32-byte digest using the same key.
+
+The adapter computes the digest of the cosmjs `SignDoc` itself, so Privy only sees a hash.
+
+```js
+import { PrivyCosmosSigner } from 'blue-js-sdk';
+
+const signer = await PrivyCosmosSigner.fromRawSign({
+  pubkey: privyDerivedCompressedPubkey,
+  signRawSecp256k1: async (digest32) => {
+    const sig = await privy.signRawHash({ hash: digest32, curve: 'secp256k1' });
+    return sig; // Uint8Array(64), r||s
+  },
+  prefix: 'sent',
+});
+```
+
+Use this when you must keep custody inside Privy. Requirements on the callback:
+
+- Returns a 64-byte (`r||s`) `Uint8Array`. The adapter rejects any other shape.
+- The signature MUST be over the raw 32-byte digest the adapter passed in. Do not let Privy re-hash it (no `eth_sign`-style "Ethereum Signed Message" prefixing).
+- Low-S form is preferred but not required — the adapter normalizes high-S signatures to low-S before encoding the result, since cosmos-sdk validators reject high-S since v0.42.
+
+## Address parity
+
+Both modes derive the **same** `sent1...` address from the same seed. You can pre-compute the address in either direction with `deriveCosmosPubkeyFromMnemonic`:
+
+```js
+import { deriveCosmosPubkeyFromMnemonic } from 'blue-js-sdk';
+
+const { pubkey, address } = await deriveCosmosPubkeyFromMnemonic(mnemonic);
+```
+
+This is useful when the consumer wants to display the user's `sent1...` address in Privy onboarding before a Mode B signer is wired up.
+
+## What the adapter is
+
+The Mode A return value IS a `DirectSecp256k1HdWallet`. The Mode B return value is an `OfflineDirectSigner` — `getAccounts()` + `signDirect(signerAddress, signDoc)`. Either can be passed straight to `SigningStargateClient.connectWithSigner` and to every Sentinel SDK helper that accepts a `wallet`:
+
+- `broadcast()`, `broadcastWithFeeGrant()`, `createSafeBroadcaster()` — TX broadcast
+- Operator helpers: `autoLeaseNode()`, `batchLeaseNodes()`, `batchRevokeFeeGrants()`, etc.
+- `SentinelClient` query surface — `getBalance()`, `getClient()`, `listNodes()`, etc.
+
+### Tunnel connect/disconnect — Mode A only (today)
+
+VPN session start (`connect()`, `autoConnect()`, `connectPlan()`) and matching teardown perform a WireGuard/V2Ray handshake with the node. The handshake protocol requires the SDK to sign a small payload with the **raw** secp256k1 privkey **locally**, before any chain TX. That privkey is not available in Mode B — Privy's raw-sign endpoint signs digests but does not export the key.
+
+In short:
+
+| Operation | Mode A (mnemonic) | Mode B (rawSign) |
+|---|---|---|
+| `getBalance()`, `listNodes()`, queries | works | works |
+| `broadcast()`, `broadcastWithFeeGrant()` | works | works |
+| Operator helpers (`autoLeaseNode`, batch*) | works | works |
+| `connect()`, `autoConnect()`, `connectPlan()` | works | **throws** with "VPN connect/disconnect requires a mnemonic" |
+
+A signer-only `SentinelClient` will throw a helpful error from the connect methods rather than failing deep inside the handshake. Lifting this restriction requires either (a) refactoring the handshake to call out to `signRawSecp256k1`, or (b) Privy exposing a "raw secp256k1 sign" endpoint shaped like the cosmjs `Secp256k1.createSignature` signature already accepted in Mode B — both viable, neither in this PR.
+
+## Using `SentinelClient` with Privy
+
+```js
+import { SentinelClient, PrivyCosmosSigner } from 'blue-js-sdk';
+
+// Mode A — full feature set
+const signer = await PrivyCosmosSigner.fromMnemonic({ mnemonic: privyExportedSeed });
+const client = new SentinelClient({
+  signer,
+  rpcUrl: 'https://rpc.sentinel.co',
+  // mnemonic still required for VPN connect — see table above
+  mnemonic: privyExportedSeed,
+});
+const balance = await client.getBalance(); // works
+const conn = await client.autoConnect();   // works (uses mnemonic)
+
+// Mode B — custody-preserving (queries + broadcasts only)
+const custodySigner = await PrivyCosmosSigner.fromRawSign({
+  pubkey: privyDerivedCompressedPubkey,
+  signRawSecp256k1: async (digest32) => privy.signRawHash({ hash: digest32, curve: 'secp256k1' }),
+});
+const queryClient = new SentinelClient({ signer: custodySigner, rpcUrl: 'https://rpc.sentinel.co' });
+await queryClient.getBalance();          // works — queries Privy for the address
+// await queryClient.connect(...);       // throws: requires a mnemonic
+```
+
+## Unified factory
+
+```js
+import { createPrivyCosmosSigner } from 'blue-js-sdk';
+
+// Routes to fromMnemonic / fromRawSign by `mode`.
+const signer = await createPrivyCosmosSigner({ mode: 'mnemonic', mnemonic });
+// or
+const signer = await createPrivyCosmosSigner({
+  mode: 'rawSign', pubkey, signRawSecp256k1,
+});
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `signerAddress mismatch (got X, signer holds Y)` | Caller passed a different `signerAddress` to `signDirect` than the one the signer derived from the pubkey. | Use the address from `getAccounts()[0]`. |
+| `signRawSecp256k1 must return a 64-byte (r\|\|s) Uint8Array` | Privy callback returned DER, hex string, or included a recovery byte. | Strip to fixed 64-byte `r\|\|s` before returning. |
+| Chain rejects TX with `signature verification failed` | Privy hashed the input again before signing (e.g. `eth_sign` prefixing). | Use Privy's "raw hash" sign endpoint, not `signMessage`. |
+| Address differs between modes | Privy derived the pubkey on a non-Cosmos path. | Use Cosmos path `m/44'/118'/0'/0/0`; coinType MUST be 118. |
+
+## Tests
+
+`test/privy-cosmos-signer.test.mjs` — 20 assertions covering:
+
+- Mode A address parity with `createWallet()`
+- `deriveCosmosPubkeyFromMnemonic` matches Mode A
+- Mode B address parity with Mode A using the same seed
+- `signDirect` produces a signature that verifies against the pubkey on `sha256(makeSignBytes(signDoc))`
+- High-S signatures returned by the callback are normalized to low-S
+- `signerAddress` mismatch is rejected
+- Unified factory routes correctly and rejects unknown modes
+- Static facade delegates to the underlying functions
+
+### Run the offline suite (CI-safe)
+
+```sh
+npm run test:privy   # 32 assertions, no network
+```
+
+### Run the live suites (require credentials, NOT in CI)
+
+```sh
+# Mainnet broadcast — proves Sentinel chain accepts adapter signatures.
+# Sends a 1 udvpn self-MsgSend; needs ~20000 udvpn for fee.
+MNEMONIC="..." npm run test:privy:live
+
+# Real Privy API — creates a server-managed Cosmos wallet on Privy and proves
+# the bytes Privy's /raw_sign returns verify against the Privy-derived pubkey.
+PRIVY_APP_ID="..." PRIVY_APP_SECRET="..." npm run test:privy:server
+```
+
+`test/privy-client-integration.test.mjs` — 12 assertions covering:
+
+- `SentinelClient({ signer })` — `getWallet()` returns the supplied signer + first account, no mnemonic required
+- `SentinelClient({ mnemonic })` — backwards-compatible path still works
+- `SentinelClient({})` — `getWallet()` throws with a helpful "mnemonic or signer" message
+- `SentinelClient({ signer })` — `connect()`, `autoConnect()`, `connectPlan()` all reject with "requires a mnemonic" pointing to this doc
+- Address parity between `PrivyCosmosSigner(mnemonic)` and `SentinelClient(mnemonic)`

package/errors.js

@@ -71,6 +71,82 @@ export class SecurityError extends SentinelError {
   }
 }
 
+// ─── Audit Errors ────────────────────────────────────────────────────────────
+//
+// Errors raised by audit / network-test pipelines. They carry a `.diag`
+// blob — the structured snapshot of what was happening when the failure
+// fired (handshake transcript, timings, transport state, etc.). UI surfaces
+// render that into the per-row failure log so an operator can copy the
+// full context.
+//
+// Audit errors share a hardcoded code per subclass — the subclass IS the
+// taxonomy. Callers don't have to remember code strings; they catch by
+// type.
+
+/**
+ * Base class for audit / network-test failures.
+ * Adds a `.diag` field on top of SentinelError's `.details`.
+ *
+ * @param {string} message
+ * @param {string} code
+ * @param {object} [diag] - Diagnostic snapshot (handshake bytes, timings, etc.)
+ */
+export class AuditError extends SentinelError {
+  constructor(message, code, diag = {}) {
+    super(code, message, diag);
+    this.name = 'AuditError';
+    this.diag = diag;
+  }
+}
+
+/** V3 handshake to the node failed (bad transport, timeout, malformed reply). */
+export class HandshakeError extends AuditError {
+  constructor(message, diag = {}) {
+    super(message, 'HANDSHAKE_FAILED', diag);
+    this.name = 'HandshakeError';
+  }
+}
+
+/** Payment-side failure during audit (subscription sub-allocation, fee-grant, etc.). */
+export class PaymentError extends AuditError {
+  constructor(message, diag = {}) {
+    super(message, 'PAYMENT_FAILED', diag);
+    this.name = 'PaymentError';
+  }
+}
+
+/** A pre-existing VPN process / WireGuard interface is interfering with the test. */
+export class VpnInterferenceError extends AuditError {
+  constructor(message, diag = {}) {
+    super(message, 'VPN_INTERFERENCE', diag);
+    this.name = 'VpnInterferenceError';
+  }
+}
+
+/** Node failed to respond at all to status / status-update probe. */
+export class NodeUnreachableError extends AuditError {
+  constructor(message, diag = {}) {
+    super(message, 'NODE_UNREACHABLE', diag);
+    this.name = 'NodeUnreachableError';
+  }
+}
+
+/** Wallet doesn't have enough udvpn for the audit run (mid-pipeline detection). */
+export class InsufficientBalanceError extends AuditError {
+  constructor(message, diag = {}) {
+    super(message, 'INSUFFICIENT_BALANCE', diag);
+    this.name = 'InsufficientBalanceError';
+  }
+}
+
+/** Speed test phase failed (Cloudflare unreachable, all fallback hosts dead, etc.). */
+export class SpeedTestError extends AuditError {
+  constructor(message, diag = {}) {
+    super(message, 'SPEEDTEST_FAILED', diag);
+    this.name = 'SpeedTestError';
+  }
+}
+
 /** Error code constants — use these for switch/if checks instead of string parsing */
 export const ErrorCodes = {
   // Validation
@@ -120,9 +196,50 @@ export const ErrorCodes = {
   ALL_NODES_FAILED: 'ALL_NODES_FAILED',
   ALREADY_CONNECTED: 'ALREADY_CONNECTED',
   PARTIAL_CONNECTION_FAILED: 'PARTIAL_CONNECTION_FAILED',
+  NOT_CONNECTED: 'NOT_CONNECTED',
+  CONNECTION_IN_PROGRESS: 'CONNECTION_IN_PROGRESS',
+  HANDSHAKE_FAILED: 'HANDSHAKE_FAILED',
 
   // Chain timing
   CHAIN_LAG: 'CHAIN_LAG',
+  SEQUENCE_MISMATCH: 'SEQUENCE_MISMATCH',
+
+  // Subscription / Plan
+  SUBSCRIBE_FAILED: 'SUBSCRIBE_FAILED',
+  SUBSCRIPTION_NOT_FOUND: 'SUBSCRIPTION_NOT_FOUND',
+  SHARE_FAILED: 'SHARE_FAILED',
+
+  // Fee grants
+  FEE_GRANT_MISSING_AT_START: 'FEE_GRANT_MISSING_AT_START',
+  FEE_GRANT_EXPIRED: 'FEE_GRANT_EXPIRED',
+
+  // Node (additional states)
+  NODE_MISCONFIGURED: 'NODE_MISCONFIGURED',
+  NODE_DB_CORRUPT: 'NODE_DB_CORRUPT',
+  NODE_RPC_BROKEN: 'NODE_RPC_BROKEN',
+
+  // Fee grant
+  FEE_GRANT_MISSING_AT_START: 'FEE_GRANT_MISSING_AT_START',
+  FEE_GRANT_EXPIRED: 'FEE_GRANT_EXPIRED',
+
+  // Node extended
+  NODE_MISCONFIGURED: 'NODE_MISCONFIGURED',
+  NODE_DB_CORRUPT: 'NODE_DB_CORRUPT',
+  NODE_RPC_BROKEN: 'NODE_RPC_BROKEN',
+
+  // Chain extended
+  SEQUENCE_MISMATCH: 'SEQUENCE_MISMATCH',
+
+  // Connection lifecycle
+  NOT_CONNECTED: 'NOT_CONNECTED',
+  CONNECTION_IN_PROGRESS: 'CONNECTION_IN_PROGRESS',
+
+  // Audit / network-test pipeline (used by AuditError subclasses)
+  HANDSHAKE_FAILED: 'HANDSHAKE_FAILED',
+  PAYMENT_FAILED: 'PAYMENT_FAILED',
+  VPN_INTERFERENCE: 'VPN_INTERFERENCE',
+  NODE_UNREACHABLE: 'NODE_UNREACHABLE',
+  SPEEDTEST_FAILED: 'SPEEDTEST_FAILED',
 };
 
 // ─── Error Severity Classification ───────────────────────────────────────────
@@ -141,6 +258,12 @@ export const ERROR_SEVERITY = {
   [ErrorCodes.SESSION_POISONED]: 'fatal',
   [ErrorCodes.WG_NOT_AVAILABLE]: 'fatal',
   [ErrorCodes.NODE_DATABASE_CORRUPT]: 'retryable',
+  [ErrorCodes.ALREADY_CONNECTED]: 'fatal',
+  [ErrorCodes.NOT_CONNECTED]: 'fatal',
+  [ErrorCodes.CONNECTION_IN_PROGRESS]: 'fatal',
+  [ErrorCodes.ABORTED]: 'fatal',
+  [ErrorCodes.FEE_GRANT_MISSING_AT_START]: 'fatal',
+  [ErrorCodes.FEE_GRANT_EXPIRED]: 'fatal',
 
   // Retryable — node-level
   [ErrorCodes.NODE_NOT_FOUND]: 'retryable',
@@ -150,6 +273,9 @@ export const ERROR_SEVERITY = {
   [ErrorCodes.NODE_NO_UDVPN]: 'retryable',
   [ErrorCodes.NODE_CLOCK_DRIFT]: 'retryable',
   [ErrorCodes.NODE_INACTIVE]: 'retryable',
+  [ErrorCodes.NODE_MISCONFIGURED]: 'retryable',
+  [ErrorCodes.NODE_DB_CORRUPT]: 'retryable',
+  [ErrorCodes.NODE_RPC_BROKEN]: 'retryable',
   [ErrorCodes.V2RAY_ALL_FAILED]: 'retryable',
   [ErrorCodes.BROADCAST_FAILED]: 'retryable',
   [ErrorCodes.TX_FAILED]: 'retryable',
@@ -159,15 +285,44 @@ export const ERROR_SEVERITY = {
   [ErrorCodes.WG_NO_CONNECTIVITY]: 'retryable',
   [ErrorCodes.TUNNEL_SETUP_FAILED]: 'retryable',
   [ErrorCodes.CHAIN_LAG]: 'retryable',
+  [ErrorCodes.SEQUENCE_MISMATCH]: 'retryable',
+  [ErrorCodes.SUBSCRIBE_FAILED]: 'retryable',
+  [ErrorCodes.SUBSCRIPTION_NOT_FOUND]: 'retryable',
+  [ErrorCodes.SHARE_FAILED]: 'retryable',
+  [ErrorCodes.INVALID_ASSIGNED_IP]: 'retryable',
 
   // Recoverable — can resume with recoverSession()
   [ErrorCodes.SESSION_EXTRACT_FAILED]: 'recoverable',
   [ErrorCodes.PARTIAL_CONNECTION_FAILED]: 'recoverable',
   [ErrorCodes.SESSION_EXISTS]: 'recoverable',
+  [ErrorCodes.HANDSHAKE_FAILED]: 'recoverable',
 
   // Infrastructure — check system state
   [ErrorCodes.TLS_CERT_CHANGED]: 'infrastructure',
   [ErrorCodes.V2RAY_NOT_FOUND]: 'infrastructure',
+
+  // Fee grant
+  [ErrorCodes.FEE_GRANT_MISSING_AT_START]: 'fatal',
+  [ErrorCodes.FEE_GRANT_EXPIRED]: 'fatal',
+
+  // Node extended
+  [ErrorCodes.NODE_MISCONFIGURED]: 'retryable',
+  [ErrorCodes.NODE_DB_CORRUPT]: 'retryable',
+  [ErrorCodes.NODE_RPC_BROKEN]: 'retryable',
+
+  // Chain extended
+  [ErrorCodes.SEQUENCE_MISMATCH]: 'retryable',
+
+  // Connection lifecycle
+  [ErrorCodes.NOT_CONNECTED]: 'fatal',
+  [ErrorCodes.CONNECTION_IN_PROGRESS]: 'recoverable',
+
+  // Audit pipeline
+  [ErrorCodes.HANDSHAKE_FAILED]: 'retryable',
+  [ErrorCodes.PAYMENT_FAILED]: 'retryable',
+  [ErrorCodes.NODE_UNREACHABLE]: 'retryable',
+  [ErrorCodes.SPEEDTEST_FAILED]: 'retryable',
+  [ErrorCodes.VPN_INTERFERENCE]: 'infrastructure',
 };
 
 /** Check if an error should be retried. */
@@ -213,6 +368,18 @@ export function userMessage(error) {
     [ErrorCodes.CHAIN_LAG]: 'Session not yet confirmed on node. Wait a moment and try again.',
     [ErrorCodes.NODE_DATABASE_CORRUPT]: 'Node has a corrupted database. Try a different server.',
     [ErrorCodes.INVALID_ASSIGNED_IP]: 'Node returned an invalid IP address during handshake. Try a different server.',
+    [ErrorCodes.NODE_MISCONFIGURED]: 'Node is misconfigured. Try a different server.',
+    [ErrorCodes.NODE_DB_CORRUPT]: 'Node database is corrupt. Try a different server.',
+    [ErrorCodes.NODE_RPC_BROKEN]: 'Node backend is temporarily unavailable. Try again later.',
+    [ErrorCodes.NOT_CONNECTED]: 'Not connected to any node.',
+    [ErrorCodes.CONNECTION_IN_PROGRESS]: 'A connection attempt is already in progress.',
+    [ErrorCodes.HANDSHAKE_FAILED]: 'Connection handshake failed. Try again.',
+    [ErrorCodes.SEQUENCE_MISMATCH]: 'Transaction sequence error. Retry automatically.',
+    [ErrorCodes.SUBSCRIBE_FAILED]: 'Failed to subscribe to the plan. Check your balance and try again.',
+    [ErrorCodes.SUBSCRIPTION_NOT_FOUND]: 'Subscription not found after payment. Check chain state.',
+    [ErrorCodes.SHARE_FAILED]: 'Failed to share subscription bandwidth. Try again.',
+    [ErrorCodes.FEE_GRANT_MISSING_AT_START]: 'Plan owner has not issued a fee grant to this wallet. Contact the plan provider.',
+    [ErrorCodes.FEE_GRANT_EXPIRED]: 'The plan owner\'s fee grant has expired. Contact the plan provider to renew.',
   };
   return map[code] || error?.message || 'An unexpected error occurred.';
 }

package/index.js

@@ -95,6 +95,7 @@ export {
   buildRevokeFeeGrantMsg,
   queryFeeGrants,
   queryFeeGrant,
+  checkFeeGrant,
   // Authz
   buildAuthzGrantMsg,
   buildAuthzRevokeMsg,
@@ -107,6 +108,8 @@ export {
   // Plan Subscriber Helpers (v25b)
   queryPlanSubscribers,
   getPlanStats,
+  queryPlanDetails,
+  isActiveStatus,
   // Fee Grant Workflow (v25b)
   grantPlanSubscribers,
   queryFeeGrantsIssued,
@@ -187,6 +190,9 @@ export {
   flushSpeedTestDnsCache,
   compareSpeedTests,
   SPEEDTEST_DEFAULTS,
+  checkGoogleDirect,
+  checkGoogleViaSocks5,
+  resolveGoogleIp,
 } from './speedtest.js';
 
 // ─── Plan & Provider Management ─────────────────────────────────────────────
@@ -296,6 +302,7 @@ export {
 export {
   createRpcQueryClient,
   createRpcQueryClientWithFallback,
+  connectFailoverWithTimeout,
   disconnectRpc,
   rpcQueryNodes,
   rpcQueryNode,
@@ -322,6 +329,7 @@ export {
   shareSubscription,
   shareSubscriptionWithFeeGrant,
   onboardPlanUser,
+  withBroadcastQueue,
 } from './chain/broadcast.js';
 
 export {
@@ -412,6 +420,13 @@ export {
   ChainError,
   TunnelError,
   SecurityError,
+  AuditError,
+  HandshakeError,
+  PaymentError,
+  VpnInterferenceError,
+  NodeUnreachableError,
+  InsufficientBalanceError,
+  SpeedTestError,
   ErrorCodes,
   ERROR_SEVERITY,
   isRetryable,
@@ -430,7 +445,7 @@ export {
 
 // ─── Session Manager ─────────────────────────────────────────────────────────
 
-export { SessionManager } from './session-manager.js';
+export { SessionManager, extractSessionMap } from './session-manager.js';
 
 // ─── Batch Session Operations ────────────────────────────────────────────────
 
@@ -496,12 +511,22 @@ export {
   estimateSessionPrice,
   buildNodeDisplay,
   groupNodesByCountry,
+  CONTINENT_BY_CODE,
+  CONTINENT_NAMES,
+  countryToContinent,
   HOUR_OPTIONS,
   GB_OPTIONS,
   formatUptime,
   computeSessionAllocation,
 } from './app-helpers.js';
 
+// ─── Auth Utilities (ADR-36, Keplr) ─────────────────────────────────────────
+
+export {
+  sortedJsonStringify,
+  verifyAdr36Signature,
+} from './auth/adr36.js';
+
 // ─── Instantiable Client Class ───────────────────────────────────────────────
 
 export { SentinelClient } from './client.js';
@@ -518,3 +543,47 @@ export {
   reorderOutbounds,
   getCacheStats,
 } from './audit.js';
+
+// ─── Operator: Lease Batch Utilities ────────────────────────────────────────
+
+export {
+  autoLeaseNode,
+  batchLeaseNodes,
+} from './operator/auto-lease.js';
+// ─── Operator: Batch Fee Grant Revoke ───────────────────────────────────────
+
+export {
+  batchRevokeFeeGrants,
+} from './operator/batch-revoke.js';
+
+// ─── Operator: Fee Grant History ────────────────────────────────────────────
+
+export {
+  queryFeeGrantHistory,
+  decodeFeeGrantEvent,
+  attr,
+} from './operator/feegrant-history.js';
+// ─── Plan Ownership Pre-Flight ──────────────────────────────────────────────
+
+export {
+  assertPlanOwnership,
+  PlanOwnershipError,
+  walletToProviderAddr,
+} from './operator/plan-ownership.js';
+// ─── Auth Utilities (Keplr) ─────────────────────────────────────────
+
+export {
+  buildKeplrSignDoc,
+  broadcastSignedKeplrTx,
+} from './auth/keplr-signdoc.js';
+
+// --- Auth Utilities (Privy embedded wallets) ---
+
+export {
+  PrivyCosmosSigner,
+  PrivyRawSignDirectSigner,
+  privyCosmosSignerFromMnemonic,
+  privyCosmosSignerFromRawSign,
+  createPrivyCosmosSigner,
+  deriveCosmosPubkeyFromMnemonic,
+} from './auth/privy-cosmos-signer.js';