nansen-cli 2.3.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/CHANGELOG.md +112 -0
  2. package/README.md +61 -38
  3. package/docs/auth.md +56 -0
  4. package/docs/browser-login.md +101 -7
  5. package/docs/error-codes.md +251 -0
  6. package/package.json +10 -4
  7. package/skills/nansen-agent-guide/SKILL.md +20 -4
  8. package/skills/nansen-alerts-webhook-listener/SKILL.md +17 -14
  9. package/skills/nansen-dca-tracker/SKILL.md +1 -1
  10. package/skills/nansen-defi-positions/SKILL.md +1 -1
  11. package/skills/nansen-exit-signals/SKILL.md +2 -2
  12. package/skills/nansen-fund-tracker/SKILL.md +1 -1
  13. package/skills/nansen-general-search/SKILL.md +1 -1
  14. package/skills/nansen-holder-analysis/SKILL.md +2 -2
  15. package/skills/nansen-limit-orders/SKILL.md +9 -1
  16. package/skills/nansen-mpp-payment/SKILL.md +2 -2
  17. package/skills/nansen-perp-screener/SKILL.md +1 -1
  18. package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
  19. package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
  20. package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
  21. package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
  22. package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
  23. package/skills/nansen-prediction-markets/SKILL.md +1 -1
  24. package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
  25. package/skills/nansen-smart-alerts/SKILL.md +5 -2
  26. package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
  27. package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
  28. package/skills/nansen-smart-money-trend/SKILL.md +1 -1
  29. package/skills/nansen-token-research/SKILL.md +1 -1
  30. package/skills/nansen-token-screener/SKILL.md +1 -1
  31. package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
  32. package/skills/nansen-trading/SKILL.md +23 -2
  33. package/skills/nansen-wallet-batch/SKILL.md +1 -1
  34. package/skills/nansen-wallet-clustering/SKILL.md +1 -1
  35. package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
  36. package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
  37. package/skills/nansen-wallet-manager/SKILL.md +11 -5
  38. package/skills/nansen-wallet-profiler/SKILL.md +1 -1
  39. package/skills/nansen-web-fetcher/SKILL.md +1 -1
  40. package/skills/nansen-web-searcher/SKILL.md +1 -1
  41. package/src/api-endpoints.json +1605 -0
  42. package/src/api.js +282 -124
  43. package/src/auth-credentials.js +1 -0
  44. package/src/auth-key-input.js +57 -9
  45. package/src/auth-state.js +2 -2
  46. package/src/auth-store-native.js +6 -1
  47. package/src/auth-store-worker.js +1 -1
  48. package/src/auth-store.js +9 -4
  49. package/src/auto-paginate.js +25 -7
  50. package/src/bridge.js +19 -10
  51. package/src/cache-inspect.js +16 -6
  52. package/src/cli.js +272 -114
  53. package/src/commands/agent.js +2 -3
  54. package/src/commands/alerts.js +365 -18
  55. package/src/commands/completion.js +4 -1
  56. package/src/commands/feedback.js +98 -37
  57. package/src/commands/mcp.js +1 -1
  58. package/src/commands/research.js +14 -37
  59. package/src/cost-cache.js +33 -7
  60. package/src/doctor.js +14 -5
  61. package/src/ens.js +14 -5
  62. package/src/error-codes.js +228 -0
  63. package/src/execute-guard.js +8 -3
  64. package/src/input-validation.js +555 -0
  65. package/src/limit-order.js +127 -54
  66. package/src/perp.js +358 -35
  67. package/src/privy.js +90 -15
  68. package/src/query-options.js +47 -8
  69. package/src/response-cache-files.js +65 -0
  70. package/src/response-meta.js +8 -2
  71. package/src/rpc-urls.js +3 -1
  72. package/src/schema.json +1254 -156
  73. package/src/solana-tx.js +4 -0
  74. package/src/telemetry-flags.js +75 -0
  75. package/src/trade-validation.js +167 -8
  76. package/src/trading.js +243 -20
  77. package/src/transfer.js +79 -12
  78. package/src/update-check.js +32 -5
  79. package/src/wallet.js +246 -69
  80. package/src/walletconnect-x402.js +27 -9
package/src/solana-tx.js CHANGED
@@ -28,6 +28,8 @@ export function readCompactU16(buf, offset) {
28
28
  * [compact-u16 sigCount][sigCount * 64-byte signatures][message]) into its
29
29
  * header, static account keys, instructions, and (v0 only) address-table
30
30
  * lookups. `data` on instructions is returned undecoded (raw Buffer).
31
+ * `messageBase64` is the serialized message (everything after the
32
+ * signatures), the form RPC getFeeForMessage takes.
31
33
  */
32
34
  export function parseTransactionMessage(base64) {
33
35
  const bytes = Buffer.from(base64, 'base64');
@@ -41,6 +43,7 @@ export function parseTransactionMessage(base64) {
41
43
  };
42
44
  const { value: numSignatures, size: sigCountSize } = readCompactU16(bytes, 0);
43
45
  let offset = sigCountSize + numSignatures * 64;
46
+ const messageStart = offset;
44
47
 
45
48
  requireBytes(offset, 1);
46
49
  const first = bytes[offset];
@@ -136,6 +139,7 @@ export function parseTransactionMessage(base64) {
136
139
  recentBlockhash,
137
140
  instructions,
138
141
  addressTableLookups,
142
+ messageBase64: bytes.subarray(messageStart).toString('base64'),
139
143
  };
140
144
  }
141
145
 
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Flag names for telemetry events.
3
+ *
4
+ * The argument parser turns a dash-leading value given as a separate argument
5
+ * (`--webhook-secret -abc123`) into a flag named after the value. Telemetry
6
+ * therefore sends only option names the CLI defines for the command being run
7
+ * and replaces every other name with a fixed placeholder, so no user-supplied
8
+ * text can reach analytics through the `flags` list.
9
+ */
10
+
11
+ import { resolveResearchCommand } from './input-validation.js';
12
+
13
+ export const UNKNOWN_FLAG = '--<unknown>';
14
+
15
+ // Single-letter switches the CLI reads directly (help, version, pretty, table,
16
+ // stream, yes). They are not listed as options in the schema.
17
+ const SHORT_SWITCHES = ['h', 'v', 'p', 't', 's', 'y'];
18
+
19
+ // Deprecated top-level commands that run a `trade` subcommand.
20
+ const TRADE_SHORTCUTS = new Set(['quote', 'execute', 'bridge-status']);
21
+
22
+ function addOptionNames(known, options) {
23
+ if (!options || typeof options !== 'object') return;
24
+ for (const [name, spec] of Object.entries(options)) {
25
+ known.add(name);
26
+ if (Array.isArray(spec?.aliases)) {
27
+ for (const alias of spec.aliases) known.add(alias);
28
+ }
29
+ }
30
+ }
31
+
32
+ /** Schema entry for the command line, or null when none matches. */
33
+ function schemaLeaf(schema, command, subArgs) {
34
+ try {
35
+ const research = resolveResearchCommand(schema, command, subArgs);
36
+ if (research) return research.leaf;
37
+ } catch {
38
+ // Unknown research category or subcommand: fall through to the plain walk.
39
+ }
40
+ let node = null;
41
+ let path = subArgs;
42
+ if (Object.hasOwn(schema.commands, command)) {
43
+ node = schema.commands[command];
44
+ } else if (TRADE_SHORTCUTS.has(command) && schema.commands.trade?.subcommands) {
45
+ node = schema.commands.trade;
46
+ path = [command, ...subArgs];
47
+ }
48
+ for (const arg of path) {
49
+ const subs = node?.subcommands;
50
+ if (!subs || typeof arg !== 'string' || !Object.hasOwn(subs, arg)) break;
51
+ node = subs[arg];
52
+ }
53
+ return node;
54
+ }
55
+
56
+ /**
57
+ * Option names (without dashes) that telemetry may report for this command:
58
+ * the matched schema entry's options, the global options and the CLI's own
59
+ * valueless switches.
60
+ */
61
+ export function knownTelemetryFlags(schema, command, subArgs = [], switches = []) {
62
+ const known = new Set([...switches, ...SHORT_SWITCHES]);
63
+ addOptionNames(known, schema.globalOptions);
64
+ addOptionNames(known, schemaLeaf(schema, command, subArgs)?.options);
65
+ return known;
66
+ }
67
+
68
+ /**
69
+ * Map `--name` entries to themselves when the CLI defines them for this
70
+ * command, and to UNKNOWN_FLAG otherwise.
71
+ */
72
+ export function telemetryFlagNames({ schema, command, subArgs = [], switches = [] }, names) {
73
+ const known = knownTelemetryFlags(schema, command, subArgs, switches);
74
+ return names.map(name => (known.has(String(name).replace(/^--/, '')) ? name : UNKNOWN_FLAG));
75
+ }
@@ -41,8 +41,27 @@ const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
41
41
  const COMPUTE_BUDGET_SET_UNIT_LIMIT = 2;
42
42
  const COMPUTE_BUDGET_SET_UNIT_PRICE = 3;
43
43
  const SOLANA_MAX_COMPUTE_UNITS = 1_400_000; // Solana's per-transaction compute-unit ceiling — the
44
- // worst-case bound used when a price is set with no
45
- // explicit limit instruction.
44
+ // worst-case bound the priority-fee cap assumes when a
45
+ // price is set with no explicit limit instruction. The
46
+ // runtime clamps any larger requested limit to it.
47
+ // The runtime's default limit when none is set: 200,000 CU per instruction,
48
+ // or 3,000 for a builtin program's instruction (Agave's builtin cost map).
49
+ // Vote is mid-migration to on-chain BPF; counting it as a builtin can only
50
+ // understate the fee, and an unpayable fee is dropped by the leader unsigned
51
+ // and uncharged, whereas overstating it falsely rejects the transaction.
52
+ const SOLANA_DEFAULT_INSTRUCTION_COMPUTE_UNITS = 200_000;
53
+ const SOLANA_DEFAULT_BUILTIN_COMPUTE_UNITS = 3_000;
54
+ const SOLANA_BUILTIN_PROGRAMS = new Set([
55
+ SYSTEM_PROGRAM,
56
+ COMPUTE_BUDGET_PROGRAM,
57
+ 'BPFLoader1111111111111111111111111111111111',
58
+ 'BPFLoader2111111111111111111111111111111111',
59
+ 'BPFLoaderUpgradeab1e11111111111111111111111',
60
+ 'LoaderV411111111111111111111111111111111111',
61
+ 'KeccakSecp256k11111111111111111111111111111',
62
+ 'Ed25519SigVerify111111111111111111111111111',
63
+ 'Vote111111111111111111111111111111111111111',
64
+ ]);
46
65
  const MAX_PRIORITY_FEE_LAMPORTS = 10_000_000n; // 0.01 SOL sanity ceiling on the priority fee a
47
66
  // single trade can be made to pay.
48
67
 
@@ -1800,7 +1819,11 @@ export function assertLimitOrderCancelOutcome(sim, { inputMint, amount } = {}) {
1800
1819
  * against SPL_TOKEN_PROGRAMS/COMPUTE_BUDGET_PROGRAM, so it's rejected outright
1801
1820
  * rather than silently skipped.
1802
1821
  *
1803
- * Throws on any of those patterns. Returns the parsed transaction otherwise.
1822
+ * Throws on any of those patterns. Otherwise returns the parsed transaction
1823
+ * plus `priorityFeeLamports` (0n when no compute-unit price is set), which
1824
+ * checkSolanaFeeBalance compares against the wallet's balance. With no limit
1825
+ * instruction it is priced at the runtime's default limit, not the 1.4M
1826
+ * ceiling the priority-fee cap assumes, so it is not a worst-case bound.
1804
1827
  */
1805
1828
  export function assertSolanaInstructionsSafe(txBase64, { walletAddress } = {}) {
1806
1829
  // Fail closed on a missing wallet address: every authority check below
@@ -1832,6 +1855,7 @@ export function assertSolanaInstructionsSafe(txBase64, { walletAddress } = {}) {
1832
1855
 
1833
1856
  let computeUnitLimit = null;
1834
1857
  let computeUnitPriceMicroLamports = null;
1858
+ let builtinInstructions = 0;
1835
1859
 
1836
1860
  for (const ix of parsed.instructions) {
1837
1861
  const programId = resolveStaticAccount(parsed, ix.programIdIndex);
@@ -1847,6 +1871,7 @@ export function assertSolanaInstructionsSafe(txBase64, { walletAddress } = {}) {
1847
1871
  'Solana transaction invokes a program only resolvable via an address-lookup-table entry, which cannot be safety-classified. Refusing to sign.',
1848
1872
  );
1849
1873
  }
1874
+ if (SOLANA_BUILTIN_PROGRAMS.has(programId)) builtinInstructions++;
1850
1875
 
1851
1876
  if (SPL_TOKEN_PROGRAMS.has(programId)) {
1852
1877
  // No discriminator byte — not a valid SPL Token instruction (the runtime
@@ -1893,17 +1918,151 @@ export function assertSolanaInstructionsSafe(txBase64, { walletAddress } = {}) {
1893
1918
  }
1894
1919
  }
1895
1920
 
1921
+ let priorityFeeLamports = 0n;
1896
1922
  if (computeUnitPriceMicroLamports != null) {
1897
- const units = BigInt(computeUnitLimit ?? SOLANA_MAX_COMPUTE_UNITS);
1898
- const feeLamports = (computeUnitPriceMicroLamports * units) / 1_000_000n;
1899
- if (feeLamports > MAX_PRIORITY_FEE_LAMPORTS) {
1923
+ // The runtime rounds the priority fee up to a whole lamport.
1924
+ const feeAt = (units) =>
1925
+ (computeUnitPriceMicroLamports * BigInt(Math.min(units, SOLANA_MAX_COMPUTE_UNITS)) + 999_999n) / 1_000_000n;
1926
+ // Returned for checkSolanaFeeBalance's fallback. With no limit instruction
1927
+ // it prices the runtime's default limit, so it doesn't reject a transaction
1928
+ // the wallet can afford.
1929
+ const defaultLimit =
1930
+ SOLANA_DEFAULT_INSTRUCTION_COMPUTE_UNITS * (parsed.instructions.length - builtinInstructions) +
1931
+ SOLANA_DEFAULT_BUILTIN_COMPUTE_UNITS * builtinInstructions;
1932
+ priorityFeeLamports = feeAt(computeUnitLimit ?? defaultLimit);
1933
+ // The cap guards against a hostile transaction, so with no limit
1934
+ // instruction it assumes the 1.4M ceiling instead.
1935
+ const worstCaseFeeLamports = computeUnitLimit != null ? priorityFeeLamports : feeAt(SOLANA_MAX_COMPUTE_UNITS);
1936
+ if (worstCaseFeeLamports > MAX_PRIORITY_FEE_LAMPORTS) {
1900
1937
  throw new Error(
1901
- `Solana transaction sets an excessive priority fee (~${feeLamports} lamports, cap ${MAX_PRIORITY_FEE_LAMPORTS}). Refusing to sign.`,
1938
+ `Solana transaction sets an excessive priority fee (~${worstCaseFeeLamports} lamports, cap ${MAX_PRIORITY_FEE_LAMPORTS}). Refusing to sign.`,
1902
1939
  );
1903
1940
  }
1904
1941
  }
1905
1942
 
1906
- return parsed;
1943
+ return { ...parsed, priorityFeeLamports };
1944
+ }
1945
+
1946
+ // Fallback only: the protocol's per-signature base fee, used when the cluster
1947
+ // can't price the message (getFeeForMessage failed or returned null because
1948
+ // the blockhash is unknown to that node). The live figure comes from the
1949
+ // cluster below.
1950
+ const SOLANA_LAMPORTS_PER_SIGNATURE = 5_000n;
1951
+ // Signature-verification precompiles. Each signature they verify is charged
1952
+ // like a transaction signature; the count is the instruction's first data byte.
1953
+ const SOLANA_SIGNATURE_PRECOMPILES = new Set([
1954
+ 'Ed25519SigVerify111111111111111111111111111',
1955
+ 'KeccakSecp256k11111111111111111111111111111',
1956
+ 'Secp256r1SigVerify1111111111111111111111111',
1957
+ ]);
1958
+ // A hung read must not hold the transaction until its blockhash expires.
1959
+ const SOLANA_FEE_CHECK_RPC_TIMEOUT_MS = 10_000;
1960
+ // Account state the check reads. Finalized state lags ~13s, so SOL spent in
1961
+ // that window would still show.
1962
+ const SOLANA_FEE_CHECK_COMMITMENT = 'confirmed';
1963
+
1964
+ function formatLamports(lamports) {
1965
+ const whole = lamports / 1_000_000_000n;
1966
+ const frac = (lamports % 1_000_000_000n).toString().padStart(9, '0').replace(/0+$/, '');
1967
+ return frac ? `${whole}.${frac}` : `${whole}`;
1968
+ }
1969
+
1970
+ async function solanaRpc(rpcUrl, method, params) {
1971
+ const res = await fetch(rpcUrl, {
1972
+ method: 'POST',
1973
+ headers: { 'Content-Type': 'application/json' },
1974
+ body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
1975
+ signal: AbortSignal.timeout(SOLANA_FEE_CHECK_RPC_TIMEOUT_MS),
1976
+ });
1977
+ if (!res.ok) throw new Error(`${method} failed: HTTP ${res.status}`);
1978
+ const body = await res.json();
1979
+ if (body.error || body.result === undefined) {
1980
+ throw new Error(`${method} failed: ${body.error?.message || 'no result'}`);
1981
+ }
1982
+ return body.result;
1983
+ }
1984
+
1985
+ /**
1986
+ * Check, before signing, that the wallet holds enough SOL to pay THIS
1987
+ * transaction's network fee, when the wallet is the fee payer.
1988
+ *
1989
+ * The fee comes from the cluster (getFeeForMessage), so it follows the current
1990
+ * fee schedule and includes the priority fee and precompile signatures. When
1991
+ * the cluster can't price the message, it falls back to the protocol base fee
1992
+ * (5,000 lamports per transaction and precompile signature) plus the priority
1993
+ * fee assertSolanaInstructionsSafe parsed, rounded up.
1994
+ *
1995
+ * Only a missing Solana RPC or a failed balance read skips the check (warns
1996
+ * and returns { proceed: true }).
1997
+ *
1998
+ * Limits, left to simulation (verifySolanaSwapOutcome): SOL the transaction
1999
+ * takes from the wallet beyond the fee (account rent, the swap's SOL input,
2000
+ * transfers) is not counted.
2001
+ *
2002
+ * The quote-time gate (validateGasBalance) can only apply a fixed floor because
2003
+ * the transaction does not exist yet, and validateBalance holds back a fee
2004
+ * buffer only when selling 95% or more of the SOL balance. Simulation also
2005
+ * catches an unpayable transaction, but it is skipped by --no-verify-outcome
2006
+ * and degrades when no simulation RPC is reachable. This check runs on every
2007
+ * path regardless of that flag.
2008
+ *
2009
+ * REQUIRES `parsed` to be the return value of assertSolanaInstructionsSafe.
2010
+ *
2011
+ * @param {object} opts
2012
+ * @param {object} opts.parsed
2013
+ * @param {string} opts.walletAddress
2014
+ * @returns {Promise<{ proceed: boolean, reason?: string }>}
2015
+ */
2016
+ export async function checkSolanaFeeBalance({ parsed, walletAddress, log = () => {} }) {
2017
+ // The fee payer is the first static account. When another account pays (a
2018
+ // sponsored transaction), the fee is not the wallet's to cover.
2019
+ if (parsed.staticAccountKeys[0] !== walletAddress) return { proceed: true };
2020
+
2021
+ const rpcUrl = CHAIN_RPCS.solana;
2022
+ if (!rpcUrl) {
2023
+ log(' ⚠ SOL fee balance check could not run (no Solana RPC endpoint); proceeding without it.');
2024
+ return { proceed: true };
2025
+ }
2026
+
2027
+ let balance;
2028
+ let feeResult;
2029
+ try {
2030
+ [balance, feeResult] = await Promise.all([
2031
+ solanaRpc(rpcUrl, 'getBalance', [walletAddress, { commitment: SOLANA_FEE_CHECK_COMMITMENT }])
2032
+ .then(r => BigInt(r.value)),
2033
+ // A failed fee lookup falls back to the static estimate.
2034
+ solanaRpc(rpcUrl, 'getFeeForMessage', [parsed.messageBase64, { commitment: 'processed' }]).catch(() => null),
2035
+ ]);
2036
+ } catch (e) {
2037
+ log(` ⚠ SOL fee balance check could not run (${e.message}); proceeding without it.`);
2038
+ return { proceed: true };
2039
+ }
2040
+
2041
+ const clusterFee = feeResult?.value;
2042
+ const clusterPriced = Number.isSafeInteger(clusterFee) && clusterFee >= 0;
2043
+ let feeLamports;
2044
+ if (clusterPriced) {
2045
+ feeLamports = BigInt(clusterFee);
2046
+ } else {
2047
+ let precompileSignatures = 0n;
2048
+ for (const ix of parsed.instructions) {
2049
+ if (SOLANA_SIGNATURE_PRECOMPILES.has(resolveStaticAccount(parsed, ix.programIdIndex)) && ix.data.length > 0) {
2050
+ precompileSignatures += BigInt(ix.data[0]);
2051
+ }
2052
+ }
2053
+ feeLamports = SOLANA_LAMPORTS_PER_SIGNATURE * (BigInt(parsed.header.numRequiredSignatures) + precompileSignatures) +
2054
+ parsed.priorityFeeLamports;
2055
+ }
2056
+
2057
+ if (balance < feeLamports) {
2058
+ return {
2059
+ proceed: false,
2060
+ reason: `wallet has ${formatLamports(balance)} SOL but this transaction needs at least ${formatLamports(feeLamports)} SOL ` +
2061
+ `for its ${clusterPriced ? '' : 'estimated '}network fee. Fund ${walletAddress} with SOL and retry.`,
2062
+ };
2063
+ }
2064
+
2065
+ return { proceed: true };
1907
2066
  }
1908
2067
 
1909
2068
  /**