nansen-cli 1.7.0 → 1.9.0

package/src/transfer.js

@@ -7,6 +7,8 @@
 import crypto from 'crypto';
 import { base58Encode, exportWallet, getWalletConfig, verifyPassword } from './wallet.js';
 import { keccak256, signSecp256k1, rlpEncode, bigIntToMinBuf } from './crypto.js';
+import { getWalletConnectAddress, sendTransactionViaWalletConnect } from './walletconnect-trading.js';
+import { EVM_CHAIN_IDS } from './chain-ids.js';
 
 // ============= Constants =============
 
@@ -27,7 +29,8 @@ const CHAIN_RPCS = {
   'solana': process.env.NANSEN_SOLANA_RPC || DEFAULT_SOLANA_RPC,
 };
 
-const CHAIN_IDS = { 'ethereum': 1, 'evm': 1, 'base': 8453 };
+// Alias: buildEvmTransaction uses 'evm' as a generic fallback
+const CHAIN_IDS = { ...EVM_CHAIN_IDS, evm: 1 };
 
 // ============= Base58 =============
 
@@ -587,12 +590,19 @@ async function broadcastTransaction(signedTx, chain) {
 // Exported for testing
 export { parseAmount, formatAmount, signEd25519, encodeCompactU16, base58Decode, base58DecodePubkey, deriveATA, validateEvmAddress, validateSolanaAddress, bigIntToHex };
 
-export async function sendTokens({ to, amount, chain, token = null, wallet = null, password, max = false, dryRun = false }) {
+export async function sendTokens({ to, amount, chain, token = null, wallet = null, password, max = false, dryRun = false, walletconnect = false }) {
   // Validate address
   const validate = chain === 'solana' ? validateSolanaAddress : validateEvmAddress;
   const v = validate(to);
   if (!v.valid) throw new Error(`Invalid recipient: ${v.error}`);
 
+  if (walletconnect) {
+    if (chain === 'solana') {
+      throw new Error('WalletConnect is only supported for EVM chains');
+    }
+    return sendTokensViaWalletConnect({ to, amount, chain, token, max, dryRun });
+  }
+
   const config = getWalletConfig();
   if (!verifyPassword(password, config)) throw new Error('Incorrect password');
 
@@ -701,6 +711,127 @@ export async function sendTokens({ to, amount, chain, token = null, wallet = nul
   };
 }
 
+/**
+ * Send tokens via WalletConnect (EVM only).
+ */
+async function sendTokensViaWalletConnect({ to, amount, chain, token, max, dryRun }) {
+  const rpcUrl = CHAIN_RPCS[chain] || CHAIN_RPCS.evm;
+  const chainId = CHAIN_IDS[chain] || 1;
+
+  const wcAddress = await getWalletConnectAddress();
+  if (!wcAddress) throw new Error('No WalletConnect session active. Run: walletconnect connect');
+
+  let txTo, txValue, txData, decimals = 18;
+
+  if (token) {
+    // Validate ERC-20 contract
+    const code = await rpcCall(rpcUrl, 'eth_getCode', [token, 'latest']);
+    if (!code || code === '0x' || code === '0x0') {
+      throw new Error(`Address ${token} is not a contract — not a valid ERC-20 token`);
+    }
+    const decResult = await rpcCall(rpcUrl, 'eth_call', [{ to: token, data: '0x313ce567' }, 'latest']);
+    decimals = parseInt(decResult, 16);
+
+    if (max) {
+      // Max ERC-20: full token balance
+      const balResult = await rpcCall(rpcUrl, 'eth_call', [{
+        to: token, data: '0x70a08231' + wcAddress.slice(2).toLowerCase().padStart(64, '0'),
+      }, 'latest']);
+      const tokenBalance = BigInt(balResult || '0x0');
+      if (tokenBalance === 0n) throw new Error('Token balance is zero');
+      amount = formatAmount(tokenBalance, decimals);
+      stderr(`  Max send: ${amount} (ERC-20)`);
+    }
+
+    const amountRaw = parseAmount(amount, decimals);
+    const toStripped = to.replace(/^0x/, '').padStart(64, '0');
+    const amtHex = amountRaw.toString(16).padStart(64, '0');
+
+    txTo = token;
+    txValue = '0';
+    txData = '0x' + ERC20_TRANSFER_SELECTOR + toStripped + amtHex;
+  } else {
+    // Native ETH
+    if (max) {
+      const balHex = await rpcCall(rpcUrl, 'eth_getBalance', [wcAddress, 'latest']);
+      const ethBalance = BigInt(balHex);
+      // Reserve gas estimate (3x gasLimit * baseFee estimate)
+      let estGasLimit;
+      try {
+        const dummyEstimate = await rpcCall(rpcUrl, 'eth_estimateGas', [
+          { from: wcAddress, to, value: '0x1' },
+        ]);
+        estGasLimit = BigInt(dummyEstimate) * 120n / 100n;
+      } catch {
+        estGasLimit = 21000n;
+      }
+      const feeHistory = await rpcCall(rpcUrl, 'eth_feeHistory', [4, 'latest', [50]]);
+      const baseFee = BigInt(feeHistory.baseFeePerGas[feeHistory.baseFeePerGas.length - 1]);
+      const safeReserve = baseFee * 2n * estGasLimit * 3n;
+      if (ethBalance <= safeReserve) throw new Error(`Insufficient balance: ${ethBalance} wei (need > ${safeReserve} for gas)`);
+      const maxAmount = ethBalance - safeReserve;
+      amount = formatAmount(maxAmount, 18);
+      stderr(`  Max send: ${amount} ETH (reserved ${formatAmount(safeReserve, 18)} for gas)`);
+    }
+
+    const amountRaw = parseAmount(amount, 18);
+    txTo = to;
+    txValue = amountRaw.toString();
+    txData = '0x';
+  }
+
+  if (dryRun) {
+    return {
+      dryRun: true,
+      from: wcAddress,
+      to, amount, token, chain,
+    };
+  }
+
+  // Estimate gas instead of hardcoding — ERC-20 transfers with hooks may need more than 100k
+  let gasLimit;
+  try {
+    const estimateParams = { from: wcAddress, to: txTo };
+    if (txData && txData !== '0x') estimateParams.data = txData;
+    if (txValue && txValue !== '0') estimateParams.value = '0x' + BigInt(txValue).toString(16);
+    const gasEstimate = await rpcCall(rpcUrl, 'eth_estimateGas', [estimateParams]);
+    gasLimit = (BigInt(gasEstimate) * 120n / 100n).toString(); // 20% buffer
+  } catch {
+    gasLimit = token ? '100000' : '21000'; // fallback
+  }
+
+  stderr('  Sending transaction via WalletConnect...');
+  const wcResult = await sendTransactionViaWalletConnect({
+    to: txTo,
+    data: txData,
+    value: txValue,
+    gas: gasLimit,
+    chainId,
+  });
+
+  let txHash;
+  if (wcResult.txHash) {
+    txHash = wcResult.txHash;
+  } else if (wcResult.signedTransaction) {
+    txHash = await broadcastTransaction(wcResult.signedTransaction, chain);
+  } else {
+    throw new Error('No transaction hash or signed transaction returned from WalletConnect');
+  }
+
+  // Wait for confirmation
+  const confirmation = await waitForEvmConfirmation(rpcUrl, txHash);
+
+  return {
+    success: true,
+    transactionHash: txHash,
+    confirmed: confirmation.confirmed,
+    ...(confirmation.blockNumber ? { blockNumber: confirmation.blockNumber } : {}),
+    from: wcAddress,
+    to, amount, token, chain,
+    explorer: getExplorerUrl(chain, txHash),
+  };
+}
+
 /**
  * Get block explorer URL for a transaction.
  */

package/src/update-check.js

@@ -28,6 +28,41 @@ function isNewer(latest, current) {
   return lp > cp;
 }
 
+const LAST_VERSION_FILE = path.join(CONFIG_DIR, 'last-version.json');
+
+/**
+ * After an update, show a one-time "what's new" notice on the first run.
+ * Compares current version against the stored last-seen version.
+ * Returns a notice string or null. Writes current version to disk.
+ */
+export function getUpgradeNotice(currentVersion) {
+  try {
+    if (process.env.NO_UPDATE_NOTIFIER || process.env.CI) return null;
+
+    let previousVersion = null;
+    if (fs.existsSync(LAST_VERSION_FILE)) {
+      const raw = fs.readFileSync(LAST_VERSION_FILE, 'utf8');
+      const data = JSON.parse(raw);
+      previousVersion = data.version;
+    }
+
+    // Always update the stored version
+    if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { mode: 0o700, recursive: true });
+    fs.writeFileSync(LAST_VERSION_FILE, JSON.stringify({ version: currentVersion }));
+
+    // If no previous version stored, this is a fresh install — no notice
+    if (!previousVersion) return null;
+
+    // If versions match, no update happened
+    if (previousVersion === currentVersion) return null;
+
+    // Version changed — show notice
+    return `\n  ✨ Updated to ${currentVersion} (was ${previousVersion}). Run \`nansen changelog --since ${previousVersion}\` for details.\n`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Read the cached check result and return a notification string (or null).
  */

package/src/wallet.js

@@ -629,45 +629,47 @@ export function buildWalletCommands(deps = {}) {
 
         'send': async () => {
           const { sendTokens } = await import('./transfer.js');
-          
+
           if (!options.to) {
             log('❌ --to <address> is required');
             exit(1);
             return;
           }
-          
+
           const isMax = flags.max || options.amount === 'max';
           if (!options.amount && !isMax) {
             log('❌ --amount <number> or --max is required');
             exit(1);
             return;
           }
-          
+
           if (!options.chain) {
             log('❌ --chain <evm|solana> is required');
             exit(1);
             return;
           }
-          
+
           if (!['evm', 'solana', 'ethereum', 'base'].includes(options.chain)) {
             log('❌ --chain must be one of: evm, solana, ethereum, base');
             exit(1);
             return;
           }
-          
-          const password = process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps);
+
+          const isWalletConnect = options.wallet === 'walletconnect' || options.wallet === 'wc';
+          const password = isWalletConnect ? null : (process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps));
           const dryRun = flags['dry-run'] || flags.dryRun;
-          
+
           try {
             const sendOpts = {
               to: options.to,
               amount: isMax ? '0' : String(options.amount),
               chain: options.chain,
               token: options.token || null,
-              wallet: options.wallet || null,
+              wallet: isWalletConnect ? null : (options.wallet || null),
               max: isMax,
               password,
               dryRun,
+              walletconnect: isWalletConnect,
             };
 
             if (dryRun) {
@@ -731,7 +733,7 @@ OPTIONS:
   --amount <number>          Amount to send in human-readable format (required unless --max)
   --chain <evm|solana>       Blockchain to use (required for send)
   --token <address>          Token contract/mint address (optional, sends native if omitted)
-  --wallet <name>            Wallet to use (optional, uses default if omitted)
+  --wallet <name>            Wallet to use (optional, uses default if omitted; use "walletconnect" or "wc" for WalletConnect, EVM only)
   --max                      Send entire balance (deducts gas for native transfers)
 
 ENVIRONMENT:

package/src/walletconnect-exec.js

@@ -0,0 +1,22 @@
+/**
+ * Shared subprocess helper for WalletConnect CLI calls.
+ *
+ * Used by walletconnect-x402.js and walletconnect-trading.js.
+ */
+
+import { execFile } from 'child_process';
+
+/**
+ * Execute a walletconnect CLI command and return stdout.
+ */
+export function wcExec(cmd, args, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: timeoutMs }, (err, stdout, stderr) => {
+      if (err) {
+        reject(new Error(err.message));
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}

package/src/walletconnect-trading.js

@@ -0,0 +1,91 @@
+/**
+ * WalletConnect Trading & Transfer Support
+ *
+ * Allows signing and broadcasting transactions via a WalletConnect-connected wallet
+ * (hardware wallets, mobile wallets) instead of local key storage.
+ * Uses the walletconnect CLI binary (subprocess-based, same as x402).
+ *
+ * EVM only — Solana via WalletConnect is not supported.
+ */
+
+import { wcExec } from './walletconnect-exec.js';
+
+/**
+ * Get the address of the connected WalletConnect wallet.
+ * Returns the first account address, or null if not connected / binary missing.
+ */
+export async function getWalletConnectAddress() {
+  try {
+    const output = await wcExec('walletconnect', ['whoami', '--json'], 3000);
+    const data = JSON.parse(output);
+    if (data.connected === false) return null;
+    return data.accounts?.[0]?.address || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Send a transaction via WalletConnect.
+ *
+ * The connected wallet signs and may broadcast the transaction.
+ * Returns either { txHash } (wallet broadcast) or { signedTransaction } (we broadcast).
+ *
+ * @param {object} txData - Transaction data: { to, data, value, gas, chainId }
+ * @param {number} [timeoutMs=120000] - Timeout for user approval
+ * @returns {{ txHash?: string, signedTransaction?: string }}
+ */
+export async function sendTransactionViaWalletConnect(txData, timeoutMs = 120000) {
+  // The walletconnect CLI expects chainId as "eip155:<id>" string format
+  const chainId = txData.chainId
+    ? (String(txData.chainId).startsWith('eip155:') ? txData.chainId : `eip155:${txData.chainId}`)
+    : undefined;
+
+  const payload = {
+    to: txData.to,
+    data: txData.data || '0x',
+    value: txData.value ? '0x' + BigInt(txData.value).toString(16) : '0x0',
+    gas: txData.gas ? '0x' + BigInt(txData.gas).toString(16) : undefined,
+    chainId,
+  };
+
+  const output = await wcExec('walletconnect', ['send-transaction', JSON.stringify(payload)], timeoutMs);
+
+  // walletconnect may print status messages before the JSON line — extract JSON only
+  const jsonLine = output.split('\n').find(line => line.startsWith('{'));
+  if (!jsonLine) throw new Error('No JSON output from walletconnect send-transaction');
+  const result = JSON.parse(jsonLine);
+
+  // The CLI returns { transactionHash: "0x..." }
+  if (result.transactionHash) return { txHash: result.transactionHash };
+  if (result.txHash) return { txHash: result.txHash };
+  if (result.signedTransaction) return { signedTransaction: result.signedTransaction };
+
+  throw new Error('Unexpected response from walletconnect send-transaction');
+}
+
+/**
+ * Send an ERC-20 approval via WalletConnect.
+ *
+ * Builds approve(spender, MAX_UINT256) calldata and delegates to sendTransactionViaWalletConnect.
+ *
+ * @param {string} tokenAddress - ERC-20 token contract
+ * @param {string} spenderAddress - Approval target (e.g. DEX router)
+ * @param {number} chainId - EIP-155 chain ID
+ * @returns {{ txHash?: string, signedTransaction?: string }}
+ */
+export async function sendApprovalViaWalletConnect(tokenAddress, spenderAddress, chainId) {
+  // ERC-20 approve(address spender, uint256 amount) selector = 0x095ea7b3
+  const MAX_UINT256_HEX = 'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';
+  const data = '0x095ea7b3'
+    + spenderAddress.slice(2).toLowerCase().padStart(64, '0')
+    + MAX_UINT256_HEX;
+
+  return sendTransactionViaWalletConnect({
+    to: tokenAddress,
+    data,
+    value: '0',
+    gas: '100000',
+    chainId,
+  });
+}

package/src/walletconnect-x402.js

@@ -0,0 +1,215 @@
+/**
+ * x402 Auto-Payment via WalletConnect
+ *
+ * Handles automatic payment signing when the API returns HTTP 402.
+ * Uses the walletconnect CLI to check wallet connection and sign EIP-712 typed data.
+ */
+
+import crypto from 'crypto';
+import { NansenError, ErrorCode } from './api.js';
+import { wcExec } from './walletconnect-exec.js';
+import { EVM_CHAIN_IDS } from './chain-ids.js';
+
+/**
+ * Check if a WalletConnect wallet session is active.
+ * Returns { wallet, accounts, expires } or null.
+ */
+export async function checkWalletConnection() {
+  try {
+    const output = await wcExec('walletconnect', ['whoami', '--json'], 3000);
+    const data = JSON.parse(output);
+    if (data.connected === false) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Select a compatible payment requirement from the accepts array.
+ * Requires scheme=exact and EIP-3009 TransferWithAuthorization support (extra.name + extra.version).
+ */
+export function selectPaymentRequirement(accepts) {
+  if (!Array.isArray(accepts) || accepts.length === 0) return null;
+
+  return accepts.find(req =>
+    req.scheme === 'exact' &&
+    req.extra?.name &&
+    req.extra?.version
+  ) || null;
+}
+
+/**
+ * Parse chain ID from network string (e.g., "eip155:8453" → 8453)
+ */
+function parseChainId(network) {
+  if (!network) return null;
+  const match = network.match(/^eip155:(\d+)$/);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Build EIP-712 typed data for TransferWithAuthorization (EIP-3009).
+ */
+export function buildEIP712TypedData({ fromAddress, requirement }) {
+  const { asset, payTo, extra, maxTimeoutSeconds } = requirement;
+  // x402 uses "amount", fall back to "maxAmountRequired" for compatibility
+  const amount = requirement.amount || requirement.maxAmountRequired;
+
+  // Determine chain ID: extra.chainId > parsed from network > fallback map > base
+  const chainId = extra.chainId || parseChainId(requirement.network) || EVM_CHAIN_IDS[requirement.chain] || EVM_CHAIN_IDS.base;
+
+  const now = Math.floor(Date.now() / 1000);
+  const nonce = '0x' + crypto.randomBytes(32).toString('hex');
+
+  const typedData = {
+    types: {
+      EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+        { name: 'chainId', type: 'uint256' },
+        { name: 'verifyingContract', type: 'address' },
+      ],
+      TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+      ],
+    },
+    primaryType: 'TransferWithAuthorization',
+    domain: {
+      name: extra.name,
+      version: extra.version,
+      chainId,
+      verifyingContract: asset,
+    },
+    message: {
+      from: fromAddress,
+      to: payTo,
+      value: amount,
+      validAfter: now - 600, // 10 min in the past to tolerate clock skew between client and verifier
+      validBefore: now + (maxTimeoutSeconds || 120),
+      nonce,
+    },
+  };
+
+  return typedData;
+}
+
+/**
+ * Build the base64-encoded Payment-Signature header value.
+ * Follows x402 v2 spec: { x402Version, resource, accepted, payload }
+ */
+export function buildPaymentSignatureHeader({ signature, authorization, resource, accepted }) {
+  const paymentPayload = {
+    x402Version: 2,
+    resource: resource || { url: '', description: '', mimeType: '' },
+    accepted: accepted || {},
+    payload: {
+      signature,
+      authorization,
+    },
+  };
+  return btoa(JSON.stringify(paymentPayload));
+}
+
+/**
+ * Format amount for human-readable display (e.g., "0.01 USDC")
+ */
+function formatPaymentAmount(requirement) {
+  const { extra } = requirement;
+  const rawAmount = requirement.amount || requirement.maxAmountRequired;
+  const symbol = extra.symbol || extra.name || 'tokens';
+  const decimals = extra.decimals || 6;
+  const amount = Number(rawAmount) / Math.pow(10, decimals);
+  const chain = requirement.network || requirement.chain || 'unknown';
+  return `${amount} ${symbol} on ${chain}`;
+}
+
+/**
+ * Handle x402 payment: check wallet, sign, return Payment-Signature header.
+ *
+ * @param {Object} paymentRequirements - Decoded payment requirements from 402 response
+ * @param {string} requestUrl - The original request URL (for context in errors)
+ * @returns {string} Base64-encoded Payment-Signature header value
+ * @throws {NansenError} On failure
+ */
+export async function handleX402Payment(paymentRequirements) {
+  // 1. Check wallet connection
+  const wallet = await checkWalletConnection();
+  if (!wallet) {
+    throw new NansenError(
+      'x402 payment required but no wallet connected. Run `walletconnect connect` first.',
+      ErrorCode.PAYMENT_REQUIRED,
+      402
+    );
+  }
+
+  const fromAddress = wallet.accounts[0]?.address;
+  if (!fromAddress) {
+    throw new NansenError(
+      'x402 payment required but wallet has no accounts.',
+      ErrorCode.PAYMENT_REQUIRED,
+      402
+    );
+  }
+
+  // 2. Select compatible payment requirement
+  const accepts = paymentRequirements.accepts || paymentRequirements;
+  const requirement = selectPaymentRequirement(Array.isArray(accepts) ? accepts : [accepts]);
+  if (!requirement) {
+    const available = (Array.isArray(accepts) ? accepts : []).map(r => r.scheme).join(', ');
+    throw new NansenError(
+      `x402 payment required but no compatible payment method found. Available: ${available || 'none'}. Need scheme=exact with EIP-3009 support.`,
+      ErrorCode.PAYMENT_REQUIRED,
+      402
+    );
+  }
+
+  // 3. Build EIP-712 typed data
+  const typedData = buildEIP712TypedData({ fromAddress, requirement });
+  const typedDataJson = JSON.stringify(typedData);
+
+  // 4. Log payment info to stderr (stdout is for JSON output)
+  const amountStr = formatPaymentAmount(requirement);
+  process.stderr.write(`x402: Requesting payment approval (${amountStr})...\n`);
+
+  // 5. Sign via walletconnect CLI (120s timeout for user approval)
+  let signResult;
+  try {
+    const output = await wcExec('walletconnect', ['sign-typed-data', typedDataJson], 120000);
+    // walletconnect may print status messages before the JSON line — extract JSON only
+    const jsonLine = output.split('\n').find(line => line.startsWith('{'));
+    if (!jsonLine) throw new Error('No JSON output from walletconnect sign-typed-data');
+    signResult = JSON.parse(jsonLine);
+  } catch (err) {
+    throw new NansenError(
+      `x402 payment signing failed: ${err.message}`,
+      ErrorCode.PAYMENT_REQUIRED,
+      402
+    );
+  }
+
+  // 6. Build Payment-Signature header (authorization values must be strings per x402 spec)
+  const authorization = {
+    from: fromAddress,
+    to: requirement.payTo,
+    value: (requirement.amount || requirement.maxAmountRequired).toString(),
+    validAfter: typedData.message.validAfter.toString(),
+    validBefore: typedData.message.validBefore.toString(),
+    nonce: typedData.message.nonce,
+  };
+
+  const headerValue = buildPaymentSignatureHeader({
+    signature: signResult.signature,
+    authorization,
+    resource: paymentRequirements.resource || { url: '', description: '', mimeType: '' },
+    accepted: requirement,
+  });
+
+  process.stderr.write(`x402: Payment signed successfully.\n`);
+  return headerValue;
+}

package/vitest.e2e.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.e2e.test.js'],
+    testTimeout: 120000,
+  },
+});