nansen-cli 1.43.0 → 1.44.0

package/src/semver.js

@@ -0,0 +1,26 @@
+/**
+ * Compare two semver strings. Returns 1 if a > b, -1 if a < b, 0 if equal.
+ *
+ * A missing trailing component is treated as 0 ("1.43" reads as "1.43.0"),
+ * not as `undefined` — `undefined` would make every `>` comparison against it
+ * false in both directions, so a version that matches on major.minor always
+ * came out "less than" a value that only specified major.minor (e.g.
+ * `compareSemver('1.43.1', '1.43')` fell through to comparing `1 > undefined`,
+ * which is false, so it returned -1 instead of 1).
+ *
+ * Shared by `nansen changelog --since` (src/cli.js) and the update-notifier's
+ * version check (src/update-check.js) so both compare versions the same,
+ * correct way instead of each hand-rolling its own parser.
+ */
+export function compareSemver(a, b) {
+  const parse = v => {
+    const parts = String(v).replace(/^v/, '').split('.').map(Number);
+    return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+  };
+  const [aM, am, ap] = parse(a);
+  const [bM, bm, bp] = parse(b);
+  if (aM !== bM) return aM > bM ? 1 : -1;
+  if (am !== bm) return am > bm ? 1 : -1;
+  if (ap !== bp) return ap > bp ? 1 : -1;
+  return 0;
+}

package/src/telemetry.js

@@ -5,10 +5,13 @@
  * how long they take, and where errors occur.  Events are fire-and-forget —
  * failures are silently ignored and never block the CLI.
  *
- * Perp `order`/`close` additionally emit a `perp_order_completed` event that
- * carries only the trade side and the Hyperliquid order id, tied to the same
- * random anonymous_id. All telemetry is opt-out via DO_NOT_TRACK=1 or
- * NANSEN_NO_TELEMETRY=1.
+ * Perp `order`/`close` additionally emit one canonical `trade_perps_*` outcome
+ * event per Hyperliquid response leg. Each event carries the leg's side,
+ * outcome and order id plus a shared submission id and SHA-256 wallet
+ * identifier. Raw wallet addresses, prices, sizes and exchange error text are
+ * never sent. The standard anonymous_id lets BI resolve a Nansen user when
+ * one is available.
+ * All telemetry is opt-out via DO_NOT_TRACK=1 or NANSEN_NO_TELEMETRY=1.
  */
 
 import fs from 'fs';
@@ -167,6 +170,54 @@ function buildContext() {
   };
 }
 
+function hashWalletAddress(walletAddress) {
+  if (!walletAddress) return undefined;
+  return crypto
+    .createHash('sha256')
+    .update(String(walletAddress).toLowerCase())
+    .digest('base64');
+}
+
+function contentDerivedUuid(value) {
+  const bytes = crypto.createHash('sha256').update(value).digest().subarray(0, 16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x50;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function perpLegAttemptId({ wallet_address, submission_id, leg_index }) {
+  if (
+    wallet_address === undefined
+    || wallet_address === null
+    || submission_id === undefined
+    || submission_id === null
+    || leg_index === undefined
+    || leg_index === null
+  ) {
+    return crypto.randomUUID();
+  }
+  return contentDerivedUuid(`${String(wallet_address).toLowerCase()}:${submission_id}:${leg_index}`);
+}
+
+function perpOutcomeEventId({ wallet_address, submission_id, leg_index, outcome }) {
+  if (
+    wallet_address === undefined
+    || wallet_address === null
+    || submission_id === undefined
+    || submission_id === null
+    || leg_index === undefined
+    || leg_index === null
+    || outcome === undefined
+    || outcome === null
+  ) {
+    return crypto.randomUUID();
+  }
+  return contentDerivedUuid(
+    `${String(wallet_address).toLowerCase()}:${submission_id}:${leg_index}:${outcome}`,
+  );
+}
+
 // ─── public API ────────────────────────────────────────────
 
 /**
@@ -258,7 +309,7 @@ export function trackCommandFailed({
 }
 
 /**
- * Track a completed Hyperliquid perp order (`nansen perp order` / `perp close`).
+ * Track one Hyperliquid perp response leg (`nansen perp order` / `perp close`).
  *
  * Fired from `buildScreenSignSubmit` in perp.js AFTER the HL /exchange response
  * is parsed (`summarizeOrderResult`). This is the only event that sees the order
@@ -268,25 +319,61 @@ export function trackCommandFailed({
  * Hyperliquid — Decision D4), so the backend never sees the response either;
  * this client-side event is the only way order outcomes reach BI.
  *
- * Fires on success only: a HL rejection throws in `submitExchange` and is
- * captured by `cli_command_failed`, so no failed event is emitted here.
+ * Reuse the canonical trade_perps order/close succeeded/failed event names so
+ * CLI, web, mobile, and backend share one BI vocabulary. Exchange rejections
+ * with a parsed response emit the matching `*_failed` event before
+ * the original command error is rethrown. Network and indeterminate timeout
+ * failures remain covered only by `cli_command_failed` because no authoritative
+ * exchange response exists.
  *
- * Deliberately minimal: only the trade side and the Hyperliquid order id — no
- * asset, price, size, or fill detail. A trade (fill) id is not carried by the
- * order-placement response (it exists only once the order fills, via the fills
- * feed), so it is not available here. `oid` is omitted when it exceeded JS
- * safe-integer precision at parse time (see summarizeOrderResult).
+ * One event is emitted for each response leg. This preserves bracket and batch
+ * order identity without putting a nested array contract into the BI pipeline.
+ * A trade/fill id is not carried by the placement response; BI joins each safe
+ * `oid` to Hyperliquid fills to obtain it. The wallet is SHA-256 hashed using
+ * the same lower-case convention as BI's `hash_address` macro.
  *
  * @param {object} opts
  * @param {'order'|'close'} opts.command  - Which perp command placed the order (routes `path`)
- * @param {'buy'|'sell'} opts.side        - Normalized trade side
- * @param {number} [opts.oid]             - Parent leg's Hyperliquid order id (omitted if imprecise)
+ * @param {'buy'|'sell'} opts.side        - This leg's normalized trade side
+ * @param {'long'|'short'} [opts.position_side] - Position side after accounting for reduce-only
+ * @param {'filled'|'resting'|'rejected'} opts.outcome - Exchange outcome
+ * @param {string} opts.submission_id     - Shared id for all legs in one action
+ * @param {number} opts.leg_index         - Zero-based response-leg index
+ * @param {string} opts.leg               - parent/take-profit/stop-loss/leg N
+ * @param {string} opts.wallet_address    - Raw signer address; hashed before send
+ * @param {number} [opts.oid]             - Hyperliquid order id (omitted if imprecise/unavailable)
+ * @param {string} [opts.error_code]      - Stable local code; never raw exchange text
  */
-export function trackPerpOrderCompleted({ command, side, oid }) {
+export function trackPerpOrderCompleted({
+  command,
+  side,
+  position_side,
+  outcome,
+  submission_id,
+  leg_index,
+  leg,
+  wallet_address,
+  oid,
+  error_code,
+}) {
+  const walletAddressHash = hashWalletAddress(wallet_address);
+  const attemptId = perpLegAttemptId({ wallet_address, submission_id, leg_index });
+  const eventId = perpOutcomeEventId({ wallet_address, submission_id, leg_index, outcome });
+  const event = `trade_perps_${command === 'close' ? 'close' : 'order'}_${outcome === 'rejected' ? 'failed' : 'succeeded'}`;
+  // position_side is supplied per leg by summarizeOrderResult (reduceOnly-aware,
+  // undefined when the leg's own side is unknown). Only derive a fallback when a
+  // real leg side is present; never fabricate a position_side from the
+  // command-level side when the leg's side is unknown — that would corrupt the
+  // wallet-scoped joins in the companion dbt change.
+  const positionSide = position_side ?? (side === undefined
+    ? undefined
+    : command === 'close'
+      ? (side === 'buy' ? 'short' : 'long')
+      : (side === 'buy' ? 'long' : 'short'));
   return sendEvent({
-    event: 'perp_order_completed',
+    event,
     event_source: getEventSource(),
-    event_id: crypto.randomUUID(),
+    event_id: eventId,
     user_id: null,
     anonymous_id: getAnonymousId(),
     session_id: getSessionId(),
@@ -295,9 +382,21 @@ export function trackPerpOrderCompleted({ command, side, oid }) {
     // "/perp/close"), so BI can line the two events up per command.
     path: commandToPath(`perp ${command}`),
     properties: {
-      source: `nansen-cli/${cliVersion}`,
-      side,
+      // Canonical trade events use a stable product source. The CLI release is
+      // already preserved in context.client_version by buildContext().
+      source: 'cli',
+      chain: 'hyperliquid',
+      attempt_id: attemptId,
+      action: command === 'close' ? 'close' : 'open',
+      position_side: positionSide,
+      order_side: side,
+      execution_status: outcome,
+      ...(submission_id !== undefined && { submission_id: String(submission_id) }),
+      leg_index,
+      leg,
+      ...(walletAddressHash && { wallet_address_hash: walletAddressHash }),
       ...(oid !== undefined && { oid }),
+      ...(error_code && { error_code }),
     },
     context: buildContext(),
   });

package/src/trading.js

@@ -87,22 +87,41 @@ export function resolveTokenAddress(symbolOrAddress, chainName) {
  * @returns {Promise<*>} Parsed result value
  * @throws {Error} If chain has no configured RPC or the RPC returns an error
  */
+// Error codes let a broadcasting caller (bridge.js) tell a DEFINITIVE rejection
+// (the node refused the tx — nothing is in flight, safe to retry) apart from an
+// AMBIGUOUS failure (a gateway/transport error that may have dropped the ack
+// AFTER the node accepted the tx), so it can fail closed only on the latter:
+//   - RPC_UNCONFIGURED — no URL; thrown before any request leaves the process
+//   - RPC_NETWORK_ERROR — request left but no response (reset/timeout): ambiguous
+//   - RPC_HTTP_ERROR    — non-JSON HTTP response (e.g. a 502 gateway page): ambiguous
+//   - RPC_JSON_ERROR    — a JSON-RPC { error }: the node definitively rejected it
 export async function evmRpcCall(chain, method, params = []) {
   const rpcUrl = CHAIN_RPCS[chain];
-  if (!rpcUrl) throw new Error(`No RPC URL configured for chain: ${chain}`);
-  const res = await fetch(rpcUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
-  });
+  if (!rpcUrl) throw Object.assign(new Error(`No RPC URL configured for chain: ${chain}`), { code: 'RPC_UNCONFIGURED' });
+  let res;
+  try {
+    res = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+    });
+  } catch (netErr) {
+    // The request left this process but no response came back. A reset or
+    // timeout can strike AFTER the node accepted the payload, so a caller that
+    // just broadcast a tx cannot assume it was never sent.
+    throw Object.assign(new Error(`RPC request to ${chain} failed for ${method}: ${netErr.message}`), { code: 'RPC_NETWORK_ERROR' });
+  }
   const text = await res.text();
   let body;
   try {
     body = JSON.parse(text);
   } catch {
-    throw new Error(`RPC endpoint returned non-JSON response (HTTP ${res.status}) for ${method}: ${text.slice(0, 100)}`);
+    throw Object.assign(
+      new Error(`RPC endpoint returned non-JSON response (HTTP ${res.status}) for ${method}: ${text.slice(0, 100)}`),
+      { code: 'RPC_HTTP_ERROR', status: res.status },
+    );
   }
-  if (body.error) throw new Error(`RPC error (${method}): ${body.error.message}`);
+  if (body.error) throw Object.assign(new Error(`RPC error (${method}): ${body.error.message}`), { code: 'RPC_JSON_ERROR' });
   return body.result;
 }
 
@@ -186,19 +205,72 @@ export async function executeTransaction(params, { retries = 2, retryDelayMs = 1
       await new Promise(r => setTimeout(r, retryDelayMs));
     }
 
-    const res = await fetch(`${TRADING_API_URL}/execute`, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(params),
-    });
+    let res;
+    try {
+      res = await fetch(`${TRADING_API_URL}/execute`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(params),
+      });
+    } catch (netErr) {
+      // The POST left this process but no response came back (a reset/timeout).
+      // That may have struck AFTER the backend received the signed tx and
+      // broadcast it — indistinguishable from "never sent" — so treat it as
+      // BROADCAST_FAILED, the same fail-closed class as a 502. Retrying re-sends
+      // the SAME signed bytes (a byte-identical replay a node dedupes), so a
+      // retry here can't itself double-broadcast; only exhausting them fails
+      // closed at the caller (isFatalBroadcastError → mark the quote spent).
+      lastError = Object.assign(
+        new Error(`Execute POST to /execute failed: ${netErr.message}`),
+        { code: 'BROADCAST_FAILED' }
+      );
+      if (attempt < retries) continue;
+      throw lastError;
+    }
 
-    const text = await res.text();
+    let text;
+    try {
+      text = await res.text();
+    } catch (bodyErr) {
+      // Headers arrived but the body read failed (a truncated/reset response).
+      // Like the network case above, the backend may already have broadcast, so
+      // fail closed as BROADCAST_FAILED rather than surface a codeless error the
+      // candidate loop would treat as nonfatal. A retry re-sends byte-identical
+      // bytes a node dedupes.
+      lastError = Object.assign(
+        new Error(`Execute response body read failed (status ${res.status}): ${bodyErr.message}`),
+        { code: 'BROADCAST_FAILED', status: res.status }
+      );
+      if (res.status >= 500 && attempt < retries) continue;
+      throw lastError;
+    }
+
+    // Parse up front so a JSON body can be preserved as structured details — but
+    // the classification below never lets a parseable body downgrade an
+    // ambiguous status to its own (nonfatal) code.
     let body;
+    let parsed = true;
     try {
       body = JSON.parse(text);
     } catch {
+      parsed = false;
+    }
+
+    // ANY 5xx is ambiguous no matter the body SHAPE: the gateway may have
+    // forwarded the signed tx upstream before failing (a JSON 502/504 like
+    // { code: "UPSTREAM_TIMEOUT" } is exactly that case, and a 500/504 carries
+    // the same "forwarded then lost the ack" risk as a 502/503). Classify EVERY
+    // 5xx as BROADCAST_FAILED and keep the body only as details — never fall
+    // through to the !res.ok branch below, which would surface a nonfatal
+    // upstream code and let the candidate loop broadcast the next quote on top
+    // of a live tx.
+    if (res.status >= 500) {
+      // Only append the simulation fee hint for a NON-JSON body. A structured
+      // JSON error (e.g. { code: "UPSTREAM_TIMEOUT" }) already explains itself
+      // via `details`; tacking "you may be out of SOL" onto a gateway timeout
+      // would misdirect the user.
       const chainType = params.chain && CHAIN_MAP[params.chain]?.type;
-      const feeHint = res.status === 502
+      const feeHint = !parsed
         ? chainType === 'solana'
           ? ' This often means the transaction failed simulation — check that you have enough SOL for fees (~0.005 SOL minimum).'
           : chainType === 'evm'
@@ -206,11 +278,21 @@ export async function executeTransaction(params, { retries = 2, retryDelayMs = 1
             : ''
         : '';
       lastError = Object.assign(
-        new Error(`Execute API returned non-JSON response (status ${res.status}).${feeHint || ' This may be a Cloudflare challenge or server error.'}`),
+        new Error(`Execute API returned ${res.status} — treating as an ambiguous broadcast failure; the transaction may already be live.${feeHint}`),
+        { code: 'BROADCAST_FAILED', status: res.status, details: parsed ? body : text.slice(0, 200) }
+      );
+      // Retry (re-POSTs byte-identical bytes) then fail closed at the caller.
+      if (attempt < retries) continue;
+      throw lastError;
+    }
+
+    if (!parsed) {
+      // Non-JSON on a sub-500 status (a Cloudflare challenge or HTML error
+      // page). Still uninterpretable after the POST went out, so fail closed.
+      lastError = Object.assign(
+        new Error(`Execute API returned non-JSON response (status ${res.status}). This may be a Cloudflare challenge or server error.`),
         { code: 'BROADCAST_FAILED', status: res.status, details: text.slice(0, 200) }
       );
-      // Retry on 502/503 (likely transient Cloudflare issues)
-      if ((res.status === 502 || res.status === 503) && attempt < retries) continue;
       throw lastError;
     }
 
@@ -434,9 +516,43 @@ export function loadQuote(quoteId) {
   if (data.type && data.type !== 'swap') {
     throw new Error(`Quote "${quoteId}" is a ${data.type} quote. Use the matching command (e.g. "nansen bridge execute" for a bridge quote).`);
   }
+  if (data.executedAt) {
+    // Quotes are single-use: re-signing and re-broadcasting would submit a
+    // second, independently valid swap — a fresh EVM nonce or Solana blockhash,
+    // not a byte-identical replay a node would reject. Refuse a quote that has
+    // already been broadcast, the way loadBridgeQuote does.
+    const when = new Date(data.executedAt).toISOString();
+    const hashes = (data.broadcasts || []).map(b => b.txHash).filter(Boolean);
+    const detail = hashes.length ? ` (${hashes.join(', ')})` : '';
+    throw new Error(
+      `Quote "${quoteId}" was already executed at ${when}${detail}. The transaction may still be pending — check the explorer before retrying. Request a new quote with "nansen trade quote" to trade again.`,
+    );
+  }
   return data;
 }
 
+// Records that a broadcast has happened. `executedAt` is set on the first call
+// and never moved, so the quote is consumed the instant the swap goes out — a
+// later receipt-wait timeout or a REVERTED/failed outcome must not leave the
+// quote reusable, since retrying would sign and broadcast a second,
+// independently valid swap. Mirrors markBridgeQuoteExecuted (bridge.js).
+export function markQuoteExecuted(quoteId, progress = {}) {
+  const filePath = safeQuotesPath(`${quoteId}.json`);
+  if (!filePath || !fs.existsSync(filePath)) return;
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    data.executedAt = data.executedAt || Date.now();
+    if (progress.broadcast) {
+      data.broadcasts = [...(data.broadcasts || []), { ...progress.broadcast, at: Date.now() }];
+    }
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+  } catch {
+    // Best-effort: if the marker can't be written, the next execute attempt
+    // will still proceed, but that's preferable to crashing after a successful
+    // broadcast.
+  }
+}
+
 /**
  * Remove stale files from the quotes dir. Quote files use a 1-hour TTL because
  * the price is stale; tx records use a 30-day TTL because a finalized tx hash
@@ -811,6 +927,12 @@ export async function waitForReceipt(chain, txHash, timeoutMs = 180000, pollMs =
  *   - RECEIPT_TIMEOUT  — receipt never landed; the tx may still be pending, so
  *                        retrying would race a second tx against the same nonce
  *                        (a confirmed on-chain revert is NOT this — it may retry)
+ *   - BROADCAST_FAILED — /execute returned an uninterpretable response (non-JSON,
+ *                        typically a 502/503 after all retries) AFTER we POSTed
+ *                        the signed tx. A dropped ack is indistinguishable from
+ *                        "never sent", so the backend may already have broadcast
+ *                        it; failing closed here trades a needless re-quote for
+ *                        never trying the next candidate on top of a live tx.
  *
  * @param {Error} err
  * @returns {boolean}
@@ -818,7 +940,8 @@ export async function waitForReceipt(chain, txHash, timeoutMs = 180000, pollMs =
 function isFatalBroadcastError(err) {
   return err?.code === 'TXHASH_MISMATCH'
     || err?.code === 'INVALID_SIGNED_TX'
-    || err?.code === 'RECEIPT_TIMEOUT';
+    || err?.code === 'RECEIPT_TIMEOUT'
+    || err?.code === 'BROADCAST_FAILED';
 }
 
 /**
@@ -3172,6 +3295,12 @@ EXAMPLES:
               }
 
               if (wcResult.txHash) {
+                // The wallet already broadcast — the quote is spent right here,
+                // before the receipt wait below can throw RECEIPT_TIMEOUT and
+                // abort this function without ever reaching the shared
+                // executeTransaction() marker further down.
+                markQuoteExecuted(quoteId, { broadcast: { txHash: wcResult.txHash } });
+
                 // Wallet broadcast — verify on-chain
                 log('  Verifying on-chain status...');
                 try {
@@ -3521,12 +3650,36 @@ EXAMPLES:
               execParams.requestId = requestId; // Solana Jupiter Ultra
             }
 
-            const result = await executeTransaction(execParams);
+            // A retry re-POSTs the signed payload. For a normal swap that's a
+            // byte-identical replay the node dedupes, so retrying an ambiguous
+            // 5xx/network failure can't itself double-broadcast. But a --gasless
+            // Relay swap sends a signed AUTHORIZATION, and Relay's solver
+            // broadcasts its OWN wrapping tx from it (the returned txHash is not
+            // our bytes) — so a re-POST after the solver already picked it up
+            // can't be deduped at the node level and risks a second solve. For
+            // gasless we therefore don't retry: a single POST either succeeds or
+            // fails closed (BROADCAST_FAILED marks the quote spent and aborts).
+            const result = await executeTransaction(execParams, { retries: gasless ? 0 : undefined });
 
             if (result.status === 'Success') {
               let txId = result.signature || result.txHash;
               let explorerUrl = chainConfig.explorer + txId;
 
+              // The transaction is on-chain (or in flight) the instant the
+              // Trading API accepts it — the quote is spent here, before the
+              // on-chain verification below can throw RECEIPT_TIMEOUT (or
+              // anything else) and abort this function. Covers local EVM,
+              // Privy EVM, Privy Solana, local/WalletConnect Solana, the
+              // WalletConnect sign-only fallback, and --gasless Relay — every
+              // path that reaches this shared broadcast call.
+              //
+              // Deliberate: a broadcast that later reverts on-chain (the
+              // "Trying next quote" path below) still consumes the quote —
+              // the revert still burned the nonce, so re-signing this same
+              // quote for a retry would race the reverted tx's nonce. This is
+              // intentional, not an oversight.
+              markQuoteExecuted(quoteId, { broadcast: { txHash: txId } });
+
               // For EVM: verify the tx actually succeeded on-chain
               if (chainType === 'evm') {
                 log('  Verifying on-chain status...');
@@ -3629,15 +3782,36 @@ EXAMPLES:
             } else {
               log(`\n  ✗ Quote ${quoteName} failed: ${result.status}`);
               if (result.error) log(`    Error:  ${result.error}`);
+              // A non-Success result can still carry a hash — the same
+              // /execute response shape (status: 'Failed' + txHash) is
+              // observed for approval broadcasts in trading.test.js, so a
+              // "Failed" swap isn't provably unbroadcast either. We can't
+              // tell from here whether the hash means the tx actually went
+              // out, but the asymmetry favors marking: a needless re-quote
+              // is cheaper than a silent double broadcast.
+              const failedTxId = result.signature || result.txHash;
+              if (failedTxId) markQuoteExecuted(quoteId, { broadcast: { txHash: failedTxId } });
               lastQuoteError = `${quoteName}: ${result.error || result.status}`;
               if (qi + 1 < endIndex) log(`  Trying next quote...`);
             }
 
           } catch (quoteErr) {
+            // A BROADCAST_FAILED throws out of executeTransaction — BEFORE the
+            // normal markQuoteExecuted runs — so nothing has recorded this quote
+            // as spent. The signed tx may already be live on the backend (a 502
+            // on the ack, not on the send), so fail closed: mark it here so a
+            // later "trade execute --quote <id>" (or an agent auto-retry) is
+            // refused before it re-signs under a fresh nonce. No broadcast hash
+            // is recorded — we don't have one — which yields loadQuote's generic
+            // "may still be pending, check the explorer" message.
+            if (quoteErr?.code === 'BROADCAST_FAILED') {
+              markQuoteExecuted(quoteId);
+            }
             // Post-broadcast failures abort the whole execute — never retry the
             // next quote once a transaction is already out and its outcome is
-            // unknown (mismatch, underivable local hash, or an unconfirmed
-            // receipt timeout). See isFatalBroadcastError.
+            // unknown (mismatch, underivable local hash, an unconfirmed receipt
+            // timeout, or an ambiguous broadcast failure). See
+            // isFatalBroadcastError.
             if (isFatalBroadcastError(quoteErr)) throw quoteErr;
             const msg = quoteErr.message || '';
             log(`  ❌ Quote ${quoteName} failed: ${msg}`);

package/src/transfer.js

@@ -49,7 +49,10 @@ function validateSolanaAddress(address) {
 // ============= Amount Parsing =============
 
 function parseAmount(amountStr, decimals) {
-  const parts = amountStr.split('.');
+  const str = String(amountStr).trim();
+  if (str.startsWith('-')) throw new Error('Amount must be positive');
+  if (!/^\d+(\.\d+)?$/.test(str)) throw new Error('Amount must be a valid number');
+  const parts = str.split('.');
   const whole = parts[0] || '0';
   let frac = (parts[1] || '').padEnd(decimals, '0').slice(0, decimals);
   return BigInt(whole) * (10n ** BigInt(decimals)) + BigInt(frac);

package/src/update-check.js

@@ -9,6 +9,7 @@ import fs from 'fs';
 import path from 'path';
 import childProcess from 'child_process';
 import { fileURLToPath } from 'url';
+import { compareSemver } from './semver.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '', '.nansen');
@@ -19,14 +20,20 @@ const PACKAGE_NAME = 'nansen-cli';
 /**
  * Compare two semver strings. Returns true if latest > current.
  * Exported so `nansen doctor` reports upgrade state with identical semantics.
+ *
+ * Delegates to the shared compareSemver (src/semver.js, also used by `nansen
+ * changelog --since`) instead of hand-rolling its own parser. The previous
+ * inline parser here had the same bug compareSemver used to have: a version
+ * string with fewer than 3 components (e.g. a hand-edited or truncated cache
+ * file) parsed its missing component as `undefined`, and `>` is always
+ * `false` against `undefined` in both directions — so a partial version
+ * always read as "not newer", never "newer". In practice both `latest` (from
+ * the npm registry) and `current` (from this package's own version) are
+ * always full x.y.z today, so this couldn't misfire yet — but it's the same
+ * defect class, so it's fixed the same way rather than left as a landmine.
  */
 export function isNewer(latest, current) {
-  const parse = v => v.replace(/^v/, '').split('.').map(Number);
-  const [lM, lm, lp] = parse(latest);
-  const [cM, cm, cp] = parse(current);
-  if (lM !== cM) return lM > cM;
-  if (lm !== cm) return lm > cm;
-  return lp > cp;
+  return compareSemver(latest, current) > 0;
 }
 
 const LAST_VERSION_FILE = path.join(CONFIG_DIR, 'last-version.json');

package/src/wallet.js

@@ -801,13 +801,15 @@ export function buildWalletCommands(deps = {}) {
             throw new CommandError('Usage: nansen wallet delete <name>', 'MISSING_ARGS');
           }
 
-          // Check if this is a Privy wallet (no password needed)
+          // Check if this is a Privy wallet (no password needed).
+          // getWalletFile() runs validateWalletName(), which rejects any name
+          // outside [a-zA-Z0-9_-]{1,64} — so the path is confined to the wallets
+          // dir and cannot traverse. deleteWallet() re-validates below.
           let isPrivy = false;
           try {
-            const walletFile = path.join(getWalletsDir(), `${name}.json`);
-            const data = JSON.parse(fs.readFileSync(walletFile, 'utf8'));
+            const data = JSON.parse(fs.readFileSync(getWalletFile(name), 'utf8'));
             if (data.provider === 'privy') isPrivy = true;
-          } catch { /* file might not exist, deleteWallet will throw */ }
+          } catch { /* invalid/missing name; deleteWallet will validate and throw */ }
 
           let password = null;
           if (!isPrivy) {
@@ -862,8 +864,10 @@ export function buildWalletCommands(deps = {}) {
             try {
               const walletName = options.wallet || getWalletConfig().defaultWallet;
               if (walletName) {
-                const walletFile = path.join(getWalletsDir(), `${walletName}.json`);
-                const data = JSON.parse(fs.readFileSync(walletFile, 'utf8'));
+                // getWalletFile() runs validateWalletName(), confining the path to
+                // the wallets dir; an invalid name throws and is ignored here, and
+                // the real wallet load downstream validates again.
+                const data = JSON.parse(fs.readFileSync(getWalletFile(walletName), 'utf8'));
                 if (data.provider === 'privy') isPrivyWallet = true;
               }
             } catch { /* ignore */ }

package/src/x402.js

@@ -285,7 +285,14 @@ export async function checkX402Balance(network, asset = null) {
         }),
       });
       const data = await resp.json();
-      return { balance: parseInt(data.result, 16) / 10 ** decimals, symbol };
+      // Use BigInt to avoid precision loss on 18-decimal tokens (BSC stablecoins).
+      if (!data.result || data.result === "0x") return { balance: 0, symbol };
+      const raw = BigInt(data.result);
+      const divisor = 10n ** BigInt(decimals);
+      // Fractional part is display-only (.toFixed(2)); sub-cent precision not guaranteed.
+      const whole = Number(raw / divisor);
+      const frac = Number((raw % divisor) * 10000n / divisor) / 10000;
+      return { balance: whole + frac, symbol };
     }
 
     return null;