nansen-cli 1.16.1 → 1.18.0

package/src/telemetry.js

@@ -0,0 +1,237 @@
+/**
+ * Lightweight CLI telemetry.
+ *
+ * Sends anonymous usage events so we can understand which commands are used,
+ * how long they take, and where errors occur.  Events are fire-and-forget —
+ * failures are silently ignored and never block the CLI.
+ *
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const { version: cliVersion } = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+);
+
+const TELEMETRY_URL =
+  'https://bi-data-sources.nansen.ai/events-service-68ifmnpsx2uq7cgab8dw/v2/event';
+
+const TIMEOUT_MS = 2000;
+
+// ─── opt-out ──────────────────────────────────────────────
+
+export const TELEMETRY_DISABLED =
+  process.env.DO_NOT_TRACK === '1' || process.env.NANSEN_NO_TELEMETRY === '1';
+
+// ─── environment ──────────────────────────────────────────
+
+/**
+ * Infer prod vs dev from NANSEN_BASE_URL env var.
+ * Only engineers pointing at a local/staging API will have this set.
+ */
+function getEventSource() {
+  const baseUrl = process.env.NANSEN_BASE_URL || '';
+  return baseUrl && !baseUrl.includes('api.nansen.ai') ? 'cli_dev' : 'cli_prod';
+}
+
+// ─── system info ──────────────────────────────────────────
+
+const SYSTEM_NAMES = { Darwin: 'macos', Linux: 'linux', Windows_NT: 'windows' };
+
+function getSystemName() {
+  return SYSTEM_NAMES[os.type()] || os.type().toLowerCase();
+}
+
+// ─── identity ──────────────────────────────────────────────
+
+const TELEMETRY_ID_FILE = path.join(
+  process.env.HOME || process.env.USERPROFILE || '',
+  '.nansen',
+  'telemetry-id'
+);
+
+/**
+ * Get or create a persistent random anonymous_id stored in ~/.nansen/telemetry-id.
+ */
+let _anonymousId;
+export function getAnonymousId() {
+  if (_anonymousId === undefined) {
+    try {
+      _anonymousId = fs.readFileSync(TELEMETRY_ID_FILE, 'utf8').trim();
+    } catch {
+      _anonymousId = crypto.randomUUID();
+      try {
+        fs.mkdirSync(path.dirname(TELEMETRY_ID_FILE), { recursive: true });
+        fs.writeFileSync(TELEMETRY_ID_FILE, _anonymousId, 'utf8');
+      } catch { /* best-effort persist */ }
+    }
+  }
+  return _anonymousId;
+}
+
+// ─── session ───────────────────────────────────────────────
+
+const SESSION_FILE = path.join(
+  process.env.HOME || process.env.USERPROFILE || '',
+  '.nansen',
+  'session'
+);
+
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+
+/**
+ * Get or create a session ID. The session rotates after 30 min of inactivity.
+ * Callers can override via NANSEN_SESSION_ID env var.
+ */
+let _sessionId;
+export function getSessionId() {
+  if (_sessionId !== undefined) return _sessionId;
+
+  if (process.env.NANSEN_SESSION_ID) {
+    _sessionId = process.env.NANSEN_SESSION_ID;
+    return _sessionId;
+  }
+
+  const now = Date.now();
+  try {
+    const raw = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8'));
+    if (raw.id && raw.ts && now - raw.ts < SESSION_TIMEOUT_MS) {
+      _sessionId = raw.id;
+      // touch timestamp, but only if >1 min elapsed to reduce writes
+      if (now - raw.ts > 60_000) {
+        try { fs.writeFileSync(SESSION_FILE, JSON.stringify({ id: _sessionId, ts: now }), 'utf8'); } catch { /* best-effort touch */ }
+      }
+      return _sessionId;
+    }
+  } catch { /* missing or corrupt → new session */ }
+
+  _sessionId = crypto.randomUUID();
+  try {
+    fs.mkdirSync(path.dirname(SESSION_FILE), { recursive: true });
+    fs.writeFileSync(SESSION_FILE, JSON.stringify({ id: _sessionId, ts: now }), 'utf8');
+  } catch { /* best-effort */ }
+  return _sessionId;
+}
+
+// ─── send ──────────────────────────────────────────────────
+
+/**
+ * Send a telemetry event. Fire-and-forget — never throws.
+ */
+function sendEvent(event) {
+  if (TELEMETRY_DISABLED) return;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  timer.unref();
+
+  fetch(TELEMETRY_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(event),
+    signal: controller.signal,
+  })
+    .catch(() => {}) // swallow errors
+    .finally(() => clearTimeout(timer));
+}
+
+// ─── context ───────────────────────────────────────────────
+
+function buildContext() {
+  return {
+    client_type: 'nansen-cli',
+    client_version: cliVersion,
+    system_name: getSystemName(),
+    system_version: os.release(),
+    node_version: process.version,
+  };
+}
+
+// ─── public API ────────────────────────────────────────────
+
+/**
+ * Convert a command string like "smart-money netflow" to a path like "/smart-money/netflow".
+ */
+function commandToPath(command) {
+  return '/' + command.replace(/\s+/g, '/');
+}
+
+/**
+ * Track a CLI command that completed successfully.
+ *
+ * @param {object} opts
+ * @param {string} opts.command  - Full command string, e.g. "smart-money netflow"
+ * @param {number} opts.duration_ms - Wall-clock execution time
+ * @param {boolean} [opts.from_cache] - Whether result was served from cache
+ * @param {string[]} [opts.flags] - Flag names used (no values), e.g. ["--chain", "--pretty"]
+ * @param {string|null} [opts.chain] - Chain name if specified, e.g. "ethereum", "solana"
+ */
+export function trackCommandSucceeded({
+  command,
+  duration_ms,
+  from_cache = false,
+  flags = [],
+  chain = null,
+}) {
+  sendEvent({
+    event: 'cli_command_succeeded',
+    event_source: getEventSource(),
+    event_id: crypto.randomUUID(),
+    user_id: null,
+    anonymous_id: getAnonymousId(),
+    session_id: getSessionId(),
+    timestamp: new Date().toISOString(),
+    path: commandToPath(command),
+    properties: {
+      latency: duration_ms / 1000,
+      from_cache,
+      flags,
+      ...(chain ? { chain } : {}),
+    },
+    context: buildContext(),
+  });
+}
+
+/**
+ * Track a CLI command that failed.
+ *
+ * @param {object} opts
+ * @param {string} opts.command - Full command string
+ * @param {number} opts.duration_ms - Wall-clock execution time
+ * @param {string} opts.error_code - Structured error code (from ErrorCode or custom)
+ * @param {number|null} [opts.status] - HTTP status if the error came from the API
+ * @param {string[]} [opts.flags] - Flag names used
+ * @param {string|null} [opts.chain] - Chain name if specified
+ */
+export function trackCommandFailed({
+  command,
+  duration_ms,
+  error_code,
+  status = null,
+  flags = [],
+  chain = null,
+}) {
+  sendEvent({
+    event: 'cli_command_failed',
+    event_source: getEventSource(),
+    event_id: crypto.randomUUID(),
+    user_id: null,
+    anonymous_id: getAnonymousId(),
+    session_id: getSessionId(),
+    timestamp: new Date().toISOString(),
+    path: commandToPath(command),
+    properties: {
+      latency: duration_ms / 1000,
+      error_code,
+      status,
+      flags,
+      ...(chain ? { chain } : {}),
+    },
+    context: buildContext(),
+  });
+}

package/src/trading.js

@@ -13,6 +13,7 @@ import { base58Decode } from './transfer.js';
 import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect, sendSolanaTransactionViaWalletConnect, sendApprovalViaWalletConnect } from './walletconnect-trading.js';
 import { retrievePassword } from './keychain.js';
+import { CHAIN_RPCS } from './rpc-urls.js';
 
 // ============= Constants =============
 
@@ -63,21 +64,17 @@ export function resolveTokenAddress(symbolOrAddress, chainName) {
   return resolved || symbolOrAddress;
 }
 
-// Default public RPC endpoints (used for nonce fetching)
-const EVM_RPC_URLS = {
-  base:     process.env.NANSEN_RPC_BASE     || 'https://mainnet.base.org',
-};
-
 /**
  * Make a JSON-RPC call to an EVM RPC endpoint.
- * @param {string} chain - Chain name (key into EVM_RPC_URLS)
+ * RPC URLs come from the shared CHAIN_RPCS registry in rpc-urls.js.
+ * @param {string} chain - Chain name (key into CHAIN_RPCS)
  * @param {string} method - JSON-RPC method name
  * @param {Array} params - Method parameters
  * @returns {Promise<*>} Parsed result value
  * @throws {Error} If chain has no configured RPC or the RPC returns an error
  */
 async function evmRpcCall(chain, method, params = []) {
-  const rpcUrl = EVM_RPC_URLS[chain];
+  const rpcUrl = CHAIN_RPCS[chain];
   if (!rpcUrl) throw new Error(`No RPC URL configured for chain: ${chain}`);
   const res = await fetch(rpcUrl, {
     method: 'POST',
@@ -406,7 +403,7 @@ export async function waitForReceipt(chain, txHash, timeoutMs = 30000, pollMs =
  * Returns { success: true } or { success: false, reason: string }.
  */
 export async function simulateEvmCall(chain, { from, to, data, value, gas }) {
-  if (!EVM_RPC_URLS[chain]) return { success: true }; // Can't simulate, skip
+  if (!CHAIN_RPCS[chain]) return { success: true }; // Can't simulate, skip
 
   try {
     const callObj = { from, to, data, value: value || '0x0' };
@@ -417,7 +414,24 @@ export async function simulateEvmCall(chain, { from, to, data, value, gas }) {
     const msg = e.message || 'unknown';
     // Only block on actual contract-level revert errors from the RPC
     if (msg.startsWith('RPC error (eth_call):')) {
-      return { success: false, reason: msg.replace(/^RPC error \(eth_call\): /, '') };
+      const rawReason = msg.replace(/^RPC error \(eth_call\): /, '');
+      // Convert raw "insufficient funds" RPC errors (amounts in wei) into a human-readable message.
+      // EVM nodes emit: "insufficient funds for gas * price + value: address 0x... have X want Y (supplied gas Z)"
+      // TODO: full fix would be a pre-flight eth_getBalance check at quote-fetch time so the error
+      //       surfaces before simulation with an estimated ETH requirement — see PR for this fix.
+      const m = rawReason.match(/insufficient funds[\s\S]*?\bhave (\d+)\s+want (\d+)/i);
+      if (m) {
+        const haveWei = BigInt(m[1]);
+        const wantWei = BigInt(m[2]);
+        const haveEth = (Number(haveWei) / 1e18).toFixed(6);
+        const wantEth = (Number(wantWei) / 1e18).toFixed(6);
+        const fundHint = from ? ` Send ETH to ${from} before trading.` : '';
+        return {
+          success: false,
+          reason: `Insufficient ETH: wallet has ${haveEth} ETH but this trade needs ~${wantEth} ETH (amount + gas).${fundHint}`,
+        };
+      }
+      return { success: false, reason: rawReason };
     }
     // Network/infrastructure errors (fetch failure, rate limit, non-JSON response) → non-blocking
     return { success: true };
@@ -429,7 +443,7 @@ export async function simulateEvmCall(chain, { from, to, data, value, gas }) {
  * Used to fix under-gassed quotes from aggregators.
  */
 export async function estimateEvmGas(chain, { from, to, data, value }) {
-  if (!EVM_RPC_URLS[chain]) return null;
+  if (!CHAIN_RPCS[chain]) return null;
 
   try {
     const result = await evmRpcCall(chain, 'eth_estimateGas', [{ from, to, data, value: value || '0x0' }]);
@@ -444,7 +458,7 @@ export async function estimateEvmGas(chain, { from, to, data, value }) {
  * Returns the allowance as a BigInt, or 0n on failure.
  */
 export async function checkErc20Allowance(chain, tokenAddress, ownerAddress, spenderAddress) {
-  if (!EVM_RPC_URLS[chain]) return 0n;
+  if (!CHAIN_RPCS[chain]) return 0n;
 
   try {
     // allowance(address,address) selector = 0xdd62ed3e
@@ -1123,7 +1137,7 @@ EXAMPLES:
               let finalGas = apiGas > 0 ? apiGas : txGas;
               if (finalGas === 0) {
                 try {
-                  const rpcUrl = EVM_RPC_URLS[chain];
+                  const rpcUrl = CHAIN_RPCS[chain];
                   const estRes = await fetch(rpcUrl, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },

package/src/transfer.js

@@ -9,26 +9,16 @@ import { base58Encode, exportWallet, getWalletConfig, verifyPassword, showWallet
 import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect } from './walletconnect-trading.js';
 import { EVM_CHAIN_IDS } from './chain-ids.js';
+import { CHAIN_RPCS } from './rpc-urls.js';
 
 // ============= Constants =============
 
-const DEFAULT_EVM_RPC = 'https://eth.public-rpc.com';
-const DEFAULT_SOLANA_RPC = 'https://api.mainnet-beta.solana.com';
-
 const PRIORITY_FEE_DEFAULTS = { base: 100000000n, ethereum: 1500000000n, evm: 1500000000n };
 
 const ERC20_TRANSFER_SELECTOR = 'a9059cbb'; // transfer(address,uint256)
 const SYSTEM_PROGRAM = '11111111111111111111111111111111'; // 32 zero bytes in base58
 const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
 
-// Chain-specific RPC endpoints
-const CHAIN_RPCS = {
-  'ethereum': process.env.NANSEN_EVM_RPC || DEFAULT_EVM_RPC,
-  'evm': process.env.NANSEN_EVM_RPC || DEFAULT_EVM_RPC,
-  'base': process.env.NANSEN_BASE_RPC || 'https://mainnet.base.org',
-  'solana': process.env.NANSEN_SOLANA_RPC || DEFAULT_SOLANA_RPC,
-};
-
 // Alias: buildEvmTransaction uses 'evm' as a generic fallback
 const CHAIN_IDS = { ...EVM_CHAIN_IDS, evm: 1 };
 

package/src/update-check.js

@@ -7,7 +7,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { spawn } from 'child_process';
+import childProcess from 'child_process';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -119,7 +119,7 @@ export function scheduleUpdateCheck() {
       req.setTimeout(5000, () => req.destroy());
     `;
 
-    const child = spawn(process.execPath, ['-e', script], {
+    const child = childProcess.spawn(process.execPath, ['-e', script], {
       detached: true,
       stdio: 'ignore'
     });

package/src/wallet.js

@@ -1067,7 +1067,8 @@ ENVIRONMENT:
   PRIVY_APP_ID               Privy application ID (required for --provider privy)
   PRIVY_APP_SECRET           Privy application secret (required for --provider privy)
   NANSEN_WALLET_PROVIDER     Default provider for wallet create ("local" or "privy")
-  NANSEN_EVM_RPC            Custom EVM RPC endpoint
+  NANSEN_EVM_RPC            Custom Ethereum RPC endpoint (also generic EVM fallback)
+  NANSEN_BASE_RPC           Custom Base RPC endpoint
   NANSEN_SOLANA_RPC         Custom Solana RPC endpoint
 
 EXAMPLES:

package/src/x402.js

@@ -12,6 +12,7 @@ import {
   getSolanaRpcUrl,
 } from './x402-svm.js';
 import { resolvePassword } from './keychain.js';
+import { CHAIN_RPCS } from './rpc-urls.js';
 
 /**
  * Parse PaymentRequirements from a 402 response.
@@ -187,10 +188,10 @@ export async function checkX402Balance(network) {
     }
 
     if (network.startsWith('eip155:')) {
-      // Base USDC balance check
+      // Base USDC balance check — RPC URL from shared registry so NANSEN_BASE_RPC override applies
       const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
       const addr = walletInfo.evm.replace('0x', '').toLowerCase().padStart(64, '0');
-      const resp = await fetch('https://mainnet.base.org', {
+      const resp = await fetch(CHAIN_RPCS.base, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({