nansen-cli 1.26.0 → 1.27.0

package/src/trading.js

@@ -13,12 +13,14 @@ 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 { validateQuoteInput, validateBalance, resolvePercentAmount } from './trade-validation.js';
+import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance } from './trade-validation.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
+import { packageVersion, CommandError } from './api.js';
 
 // ============= Constants =============
 
 const TRADING_API_URL = process.env.NANSEN_TRADING_API_URL || 'https://trading-api.nansen.ai';
+const CLIENT_USER_AGENT = `nansen-cli/${packageVersion}`;
 
 const CHAIN_MAP = {
   solana:   { index: '501', type: 'solana', chainId: 501,  name: 'Solana',   explorer: 'https://solscan.io/tx/', lifiChainId: '1151111081099710' },
@@ -115,7 +117,7 @@ export async function getQuote(params) {
     }
   }
 
-  const headers = { 'Accept': 'application/json' };
+  const headers = { 'Accept': 'application/json', 'User-Agent': CLIENT_USER_AGENT };
 
   const res = await fetch(url.toString(), { headers });
 
@@ -153,6 +155,7 @@ export async function executeTransaction(params, { retries = 2, retryDelayMs = 1
   const headers = {
     'Content-Type': 'application/json',
     'Accept': 'application/json',
+    'User-Agent': CLIENT_USER_AGENT,
   };
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
@@ -216,7 +219,7 @@ export async function getBridgeStatus(txHash, fromChain, toChain) {
   url.searchParams.set('fromChain', fromConfig.lifiChainId || fromConfig.index);
   url.searchParams.set('toChain', toConfig.lifiChainId || toConfig.index);
 
-  const res = await fetch(url.toString(), { headers: { 'Accept': 'application/json' } });
+  const res = await fetch(url.toString(), { headers: { 'Accept': 'application/json', 'User-Agent': CLIENT_USER_AGENT } });
   const text = await res.text();
   let body;
   try {
@@ -940,7 +943,7 @@ export function formatQuote(quote, index) {
  * Build trading command handlers for CLI integration.
  */
 export function buildTradingCommands(deps = {}) {
-  const { log = console.log, exit = process.exit } = deps;
+  const { log = console.log } = deps;
 
   return {
     'quote': async (args, apiInstance, flags, options) => {
@@ -961,7 +964,7 @@ export function buildTradingCommands(deps = {}) {
       const amountUnit = options['amount-unit'];
 
       if (!chain || !from || !to || !amount) {
-        log(`
+        throw new CommandError(`
 Usage: nansen trade quote --chain <chain> --from <token> --to <token> --amount <baseUnits>
 
 PREREQUISITE:
@@ -991,23 +994,17 @@ EXAMPLES:
   nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
   nansen trade quote --chain base --to-chain solana --from USDC --to USDC --amount 1000000
   nansen trade quote --chain solana --to-chain base --from SOL --to ETH --amount 1000000000
-`);
-        exit(1);
-        return;
+`, 'MISSING_ARGS');
       }
 
       // Validate --amount-unit if provided
       if (amountUnit && amountUnit !== 'token' && amountUnit !== 'base' && amountUnit !== 'usd' && amountUnit !== 'percent') {
-        log(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base, usd, percent`);
-        exit(1);
-        return;
+        throw new CommandError(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base, usd, percent`, 'INVALID_INPUT');
       }
 
       // --amount-unit percent is only valid for exactIn (sell-side)
       if (amountUnit === 'percent' && swapMode === 'exactOut') {
-        log('Error: --amount-unit percent is not supported with --swap-mode exactOut. Percentage is relative to your sell-token balance.');
-        exit(1);
-        return;
+        throw new CommandError('Error: --amount-unit percent is not supported with --swap-mode exactOut. Percentage is relative to your sell-token balance.', 'INVALID_INPUT');
       }
 
       // Static input validation — catches common agent errors (wrong addresses,
@@ -1015,9 +1012,7 @@ EXAMPLES:
       try {
         validateQuoteInput({ chain, toChain: toChainRaw || null, from, to, amount });
       } catch (validationErr) {
-        log(`Error: ${validationErr.message}`);
-        exit(1);
-        return;
+        throw new CommandError(`Error: ${validationErr.message}`, 'INVALID_INPUT');
       }
 
       // When --amount-unit token is used, resolve decimals and convert to base units.
@@ -1036,9 +1031,7 @@ EXAMPLES:
           usdTokenAmount = tokenAmount.toFixed(resolvedDecimals);
           resolvedAmount = convertToBaseUnits(usdTokenAmount, resolvedDecimals);
         } catch (err) {
-          log(`Error converting USD amount: ${err.message}`);
-          exit(1);
-          return;
+          throw new CommandError(`Error converting USD amount: ${err.message}`, 'INVALID_INPUT');
         }
       } else if (amountUnit === 'token') {
         try {
@@ -1046,18 +1039,14 @@ EXAMPLES:
           resolvedDecimals = await resolveTokenDecimals(tokenForDecimals, chain);
           resolvedAmount = convertToBaseUnits(amount, resolvedDecimals);
         } catch (err) {
-          log(`Error resolving token decimals: ${err.message}`);
-          exit(1);
-          return;
+          throw new CommandError(`Error resolving token decimals: ${err.message}`, 'INVALID_INPUT');
         }
       } else if (amountUnit === 'percent') {
         // Resolved after wallet address is available — see percent resolution block below.
       } else {
         const amountError = validateBaseUnitAmount(amount);
         if (amountError) {
-          log(`Error: ${amountError}`);
-          exit(1);
-          return;
+          throw new CommandError(`Error: ${amountError}`, 'INVALID_INPUT');
         }
       }
 
@@ -1073,9 +1062,7 @@ EXAMPLES:
         if (isWalletConnect) {
           walletAddress = await getWalletConnectAddress(chainType);
           if (!walletAddress) {
-            log('No WalletConnect session active. Run: walletconnect connect');
-            exit(1);
-            return;
+            throw new CommandError('No WalletConnect session active. Run: walletconnect connect', 'NO_WALLET');
           }
         } else if (walletName) {
           const wallet = showWallet(walletName);
@@ -1101,9 +1088,7 @@ EXAMPLES:
         }
 
         if (!walletAddress) {
-          log('No wallet found. A wallet address is required for quotes because the trading API builds a transaction specific to the sender.\nCreate one with: nansen wallet create');
-          exit(1);
-          return;
+          throw new CommandError('No wallet found. A wallet address is required for quotes because the trading API builds a transaction specific to the sender.\nCreate one with: nansen wallet create', 'NO_WALLET');
         }
 
         // --amount-unit percent: fetch balance, calculate percentage, convert to base units.
@@ -1120,9 +1105,7 @@ EXAMPLES:
             });
             resolvedAmount = convertToBaseUnits(tokenAmount, resolvedDecimals);
           } catch (err) {
-            log(`Error: ${err.message}`);
-            exit(1);
-            return;
+            throw new CommandError(`Error: ${err.message}`, 'INVALID_INPUT');
           }
         }
 
@@ -1148,9 +1131,7 @@ EXAMPLES:
               resolvedAmount = convertToBaseUnits(balanceAdjusted, resolvedDecimals);
             }
           } catch (balanceErr) {
-            log(`Error: ${balanceErr.message}`);
-            exit(1);
-            return;
+            throw new CommandError(`Error: ${balanceErr.message}`, 'INSUFFICIENT_BALANCE');
           }
         }
 
@@ -1197,17 +1178,23 @@ EXAMPLES:
         const response = await getQuote(params);
 
         if (!response.success || !response.quotes?.length) {
-          log('No quotes available');
+          let msg = 'No quotes available';
           if (response.warnings?.length) {
-            response.warnings.forEach(w => log(`  Warning: ${w}`));
+            msg += '\n' + response.warnings.map(w => `  Warning: ${w}`).join('\n');
           }
-          exit(1);
-          return;
+          throw new CommandError(msg, 'NO_QUOTES');
         }
 
         log('');
         response.quotes.forEach((q, i) => log(formatQuote(q, i)));
 
+        // Gas balance validation — check that the wallet has enough native token for gas.
+        try {
+          await validateGasBalance({ chain, walletAddress });
+        } catch (gasErr) {
+          throw new CommandError(`Error: ${gasErr.message}`, 'INSUFFICIENT_GAS');
+        }
+
         const signerType = isWalletConnect ? 'walletconnect' : walletProvider;
         const quoteId = saveQuote(response, chain, signerType, privyWalletIds, isCrossChain ? toChainRaw : null);
         log(`\n  Quote ID: ${quoteId}`);
@@ -1225,13 +1212,14 @@ EXAMPLES:
         return undefined; // Output already printed above
 
       } catch (err) {
+        if (err instanceof CommandError) throw err;
         let message = err.message;
         if (err.code === 'INVALID_AMOUNT' || /amount/i.test(err.message)) {
           message += '. Amounts must be in base units (e.g., 1000000000 lamports for 1 SOL, 1000000000000000000 wei for 1 ETH)';
         }
-        log(`Error: ${message}`);
-        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
-        exit(1);
+        let msg = `Error: ${message}`;
+        if (err.details) msg += `\n  Details: ${JSON.stringify(err.details)}`;
+        throw new CommandError(msg, err.code || 'QUOTE_ERROR');
       }
     },
 
@@ -1241,8 +1229,7 @@ EXAMPLES:
       const noSimulate = flags['no-simulate'];
 
       if (!quoteId) {
-        log(`
-Usage: nansen trade execute --quote <quoteId> [options]
+        throw new CommandError(`Usage: nansen trade execute --quote <quoteId> [options]
 
 OPTIONS:
   --quote <id>              Quote ID from 'nansen quote'
@@ -1250,10 +1237,7 @@ OPTIONS:
   --no-simulate             Skip pre-broadcast simulation
 
 EXAMPLES:
-  nansen trade execute --quote 1708900000000-abc123
-`);
-        exit(1);
-        return;
+  nansen trade execute --quote 1708900000000-abc123`, 'MISSING_ARGS');
       }
 
       try {
@@ -1264,9 +1248,7 @@ EXAMPLES:
 
         const allQuotes = quoteData.response.quotes || [];
         if (!allQuotes.length) {
-          log('❌ No quote data found');
-          exit(1);
-          return;
+          throw new CommandError('❌ No quote data found', 'NO_QUOTES');
         }
 
         // --quote-index pins a specific quote (no fallback)
@@ -1277,10 +1259,7 @@ EXAMPLES:
         // Check if any quote in range has transaction data before prompting for password
         const hasAnyTransaction = allQuotes.slice(startIndex, endIndex).some(q => q?.transaction);
         if (!hasAnyTransaction) {
-          log('❌ No quotes contain transaction data.');
-          log('  Ensure userWalletAddress was provided when fetching the quote.');
-          exit(1);
-          return;
+          throw new CommandError('❌ No quotes contain transaction data.\n  Ensure userWalletAddress was provided when fetching the quote.', 'NO_TRANSACTION');
         }
 
         // Determine if this is a WalletConnect or Privy-signed quote
@@ -1301,16 +1280,14 @@ EXAMPLES:
           if (walletConfig.passwordHash) {
             password = resolveTradePassword();
             if (!password) {
-              log(JSON.stringify({
+              throw new CommandError('Wallet is encrypted and no password was found.', 'PASSWORD_REQUIRED', {
                 error: 'PASSWORD_REQUIRED',
                 message: 'Wallet is encrypted and no password was found.',
                 resolution: [
                   'Set NANSEN_WALLET_PASSWORD environment variable',
                   'Or run: nansen wallet create (password is saved to OS keychain automatically)',
                 ],
-              }));
-              exit(1);
-              return;
+              });
             }
           }
 
@@ -1320,9 +1297,7 @@ EXAMPLES:
             effectiveWalletName = list.defaultWallet;
           }
           if (!effectiveWalletName) {
-            log('No wallet found. Create one with: nansen wallet create');
-            exit(1);
-            return;
+            throw new CommandError('No wallet found. Create one with: nansen wallet create', 'NO_WALLET');
           }
 
           exported = exportWallet(effectiveWalletName, password);
@@ -1330,9 +1305,7 @@ EXAMPLES:
           // Verify WalletConnect session is still active and address matches quote
           const wcAddress = await getWalletConnectAddress(chainType);
           if (!wcAddress) {
-            log('No WalletConnect session active. Run: walletconnect connect');
-            exit(1);
-            return;
+            throw new CommandError('No WalletConnect session active. Run: walletconnect connect', 'NO_WALLET');
           }
           // Check address matches the one used during quoting
           const quoteWallet = quoteData.response?.quotes?.[0]?.transaction?.from
@@ -1340,9 +1313,7 @@ EXAMPLES:
           if (quoteWallet && (chainType === 'solana'
             ? wcAddress.trim() !== quoteWallet.trim()
             : wcAddress.toLowerCase().trim() !== quoteWallet.toLowerCase().trim())) {
-            log(`Connected wallet (${wcAddress}) doesn't match quote. Get a new quote with --wallet walletconnect`);
-            exit(1);
-            return;
+            throw new CommandError(`Connected wallet (${wcAddress}) doesn't match quote. Get a new quote with --wallet walletconnect`, 'WALLET_MISMATCH');
           }
         }
 
@@ -1705,8 +1676,7 @@ EXAMPLES:
                     lastQuoteError = `${quoteName} reverted on-chain`;
                     continue;
                   }
-                  exit(1);
-                  return;
+                  throw new CommandError(`\n  ⚠ Transaction was broadcast but REVERTED on-chain!\n    Tx Hash:   ${wcResult.txHash}\n    Explorer:  ${chainConfig.explorer}${wcResult.txHash}\n    Error:     ${receiptErr.message}`, 'TX_REVERTED');
                 }
 
                 log(`\n  ✓ Transaction successful!`);
@@ -1896,10 +1866,7 @@ EXAMPLES:
                     lastQuoteError = `${quoteName} reverted on-chain`;
                     continue;
                   }
-                  log(`\n  The trading API reported success, but the contract execution failed.`);
-                  log(`  This can happen due to: stale quotes, insufficient gas, or liquidity changes.`);
-                  exit(1);
-                  return;
+                  throw new CommandError(`\n  ⚠ Transaction was broadcast but REVERTED on-chain!\n    Tx Hash:   ${result.txHash}\n    Explorer:  ${explorerUrl}\n    Error:     ${receiptErr.message}\n\n  The trading API reported success, but the contract execution failed.\n  This can happen due to: stale quotes, insufficient gas, or liquidity changes.`, 'TX_REVERTED');
                 }
               }
 
@@ -1954,15 +1921,13 @@ EXAMPLES:
         }
 
         // All quotes exhausted
-        log(`\n❌ All quotes failed. Last error: ${lastQuoteError || 'unknown'}`);
-        log('');
-        exit(1);
-        return undefined;
+        throw new CommandError(`\n❌ All quotes failed. Last error: ${lastQuoteError || 'unknown'}\n`, 'ALL_QUOTES_FAILED');
 
       } catch (err) {
-        log(`Error: ${err.message}`);
-        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
-        exit(1);
+        if (err instanceof CommandError) throw err;
+        let msg = `Error: ${err.message}`;
+        if (err.details) msg += `\n  Details: ${JSON.stringify(err.details)}`;
+        throw new CommandError(msg, err.code || 'EXECUTE_ERROR');
       }
     },
 
@@ -1972,8 +1937,7 @@ EXAMPLES:
       const toChain = options['to-chain'] || args[2];
 
       if (!txHash || !fromChain || !toChain) {
-        log(`
-Usage: nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
+        throw new CommandError(`Usage: nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
 
 Check the status of a cross-chain bridge transaction.
 
@@ -1983,10 +1947,7 @@ OPTIONS:
   --to-chain <chain>        Destination chain (solana or base)
 
 EXAMPLES:
-  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana
-`);
-        exit(1);
-        return;
+  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana`, 'MISSING_ARGS');
       }
 
       try {
@@ -2010,9 +1971,10 @@ EXAMPLES:
         if (status.lifiExplorerLink) log(`  Li.Fi:       ${status.lifiExplorerLink}`);
         log('');
       } catch (err) {
-        log(`Error: ${err.message}`);
-        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
-        exit(1);
+        if (err instanceof CommandError) throw err;
+        let msg = `Error: ${err.message}`;
+        if (err.details) msg += `\n  Details: ${JSON.stringify(err.details)}`;
+        throw new CommandError(msg, err.code || 'BRIDGE_STATUS_ERROR');
       }
     },
   };

package/src/transfer.js

@@ -21,6 +21,16 @@ const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
 // Alias: buildEvmTransaction uses 'evm' as a generic fallback
 const CHAIN_IDS = { ...EVM_CHAIN_IDS, evm: 1 };
 
+// ============= Address Derivation =============
+
+function deriveEvmAddress(privateKeyHex) {
+  const privBuf = Buffer.from(privateKeyHex, 'hex');
+  const ecdh = crypto.createECDH('secp256k1');
+  ecdh.setPrivateKey(privBuf);
+  const pubKey = ecdh.getPublicKey(null, 'uncompressed');
+  return '0x' + keccak256(pubKey.subarray(1)).subarray(12).toString('hex');
+}
+
 // ============= Address Validation =============
 
 function validateEvmAddress(address) {
@@ -106,12 +116,9 @@ async function buildEvmTransaction({ to, amount, token, privateKey, chain, max =
   const rpcUrl = CHAIN_RPCS[chain] || CHAIN_RPCS.evm;
   const chainId = CHAIN_IDS[chain] || 1;
 
-  // Derive address
+  // Derive address and buffer for signing
   const privBuf = Buffer.from(privateKey, 'hex');
-  const ecdh = crypto.createECDH('secp256k1');
-  ecdh.setPrivateKey(privBuf);
-  const pubKey = ecdh.getPublicKey(null, 'uncompressed');
-  const from = '0x' + keccak256(pubKey.subarray(1)).subarray(12).toString('hex');
+  const from = deriveEvmAddress(privateKey);
 
   // Nonce
   const nonceHex = await rpcCall(rpcUrl, 'eth_getTransactionCount', [from, 'latest']);
@@ -735,11 +742,7 @@ export async function sendTokens({ to, amount, chain, token = null, wallet = nul
 
     if (max && token) {
       // Max ERC-20: full token balance
-      const privBuf = Buffer.from(walletData.evm.privateKey, 'hex');
-      const ecdh = crypto.createECDH('secp256k1');
-      ecdh.setPrivateKey(privBuf);
-      const pubKey = ecdh.getPublicKey(null, 'uncompressed');
-      const from = '0x' + keccak256(pubKey.subarray(1)).subarray(12).toString('hex');
+      const from = deriveEvmAddress(walletData.evm.privateKey);
       const balResult = await rpcCall(rpcUrl, 'eth_call', [{
         to: token, data: '0x70a08231' + from.slice(2).padStart(64, '0'),
       }, 'latest']);