nansen-cli 1.45.0 → 2.0.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.
- package/CHANGELOG.md +172 -0
- package/README.md +158 -18
- package/docs/browser-login.md +117 -0
- package/package.json +11 -2
- package/scripts/postinstall.js +35 -30
- package/skills/nansen-agent-guide/SKILL.md +13 -2
- package/skills/nansen-alerts-webhook-listener/SKILL.md +5 -2
- package/skills/nansen-dca-tracker/SKILL.md +10 -2
- package/skills/nansen-defi-positions/SKILL.md +5 -2
- package/skills/nansen-exit-signals/SKILL.md +10 -2
- package/skills/nansen-fund-tracker/SKILL.md +10 -2
- package/skills/nansen-general-search/SKILL.md +10 -2
- package/skills/nansen-holder-analysis/SKILL.md +10 -2
- package/skills/nansen-limit-orders/SKILL.md +6 -3
- package/skills/nansen-perp-screener/SKILL.md +10 -2
- package/skills/nansen-perp-trader-profile/SKILL.md +10 -2
- package/skills/nansen-polymarket-deep-dive/SKILL.md +10 -2
- package/skills/nansen-polymarket-insider-scan/SKILL.md +10 -2
- package/skills/nansen-polymarket-trader-profile/SKILL.md +10 -2
- package/skills/nansen-portfolio-tracker/SKILL.md +10 -2
- package/skills/nansen-prediction-markets/SKILL.md +10 -2
- package/skills/nansen-sm-cross-chain-flows/SKILL.md +10 -2
- package/skills/nansen-smart-alerts/SKILL.md +9 -4
- package/skills/nansen-smart-money-alpha/SKILL.md +10 -2
- package/skills/nansen-smart-money-tracker/SKILL.md +10 -2
- package/skills/nansen-smart-money-trend/SKILL.md +10 -2
- package/skills/nansen-token-research/SKILL.md +10 -2
- package/skills/nansen-token-screener/SKILL.md +14 -4
- package/skills/nansen-token-transfer-analysis/SKILL.md +10 -2
- package/skills/nansen-trading/SKILL.md +27 -2
- package/skills/nansen-wallet-batch/SKILL.md +10 -2
- package/skills/nansen-wallet-clustering/SKILL.md +10 -2
- package/skills/nansen-wallet-deep-dive/SKILL.md +10 -2
- package/skills/nansen-wallet-keychain-migration/SKILL.md +23 -15
- package/skills/nansen-wallet-manager/SKILL.md +26 -10
- package/skills/nansen-wallet-profiler/SKILL.md +10 -2
- package/skills/nansen-web-fetcher/SKILL.md +5 -2
- package/skills/nansen-web-searcher/SKILL.md +5 -2
- package/src/api.js +319 -129
- package/src/auth-browser.js +16 -0
- package/src/auth-credentials.js +73 -0
- package/src/auth-device.js +242 -0
- package/src/auth-key-input.js +46 -0
- package/src/auth-login.js +90 -0
- package/src/auth-state.js +487 -0
- package/src/auth-store-native.js +20 -0
- package/src/auth-store-worker.js +64 -0
- package/src/auth-store.js +140 -0
- package/src/auto-paginate.js +272 -0
- package/src/bridge.js +309 -85
- package/src/cache-inspect.js +345 -0
- package/src/chain-ids.js +1 -2
- package/src/cli.js +779 -286
- package/src/commands/agent.js +20 -9
- package/src/commands/alerts.js +1 -1
- package/src/commands/completion.js +2 -15
- package/src/commands/mcp.js +22 -20
- package/src/commands/research.js +4 -2
- package/src/cost-cache.js +16 -2
- package/src/debug.js +348 -0
- package/src/doctor.js +22 -45
- package/src/ens.js +3 -1
- package/src/execute-guard.js +116 -0
- package/src/hl-action.js +41 -13
- package/src/limit-order.js +9 -1
- package/src/mcp-client-config.js +169 -0
- package/src/mcp-client-config.json +17 -0
- package/src/mcp-verify.js +6 -5
- package/src/perp.js +61 -9
- package/src/privy.js +12 -12
- package/src/query-options.js +38 -6
- package/src/response-meta.js +57 -2
- package/src/rpc-urls.js +9 -11
- package/src/schema.json +309 -30
- package/src/semver.js +23 -4
- package/src/swap-simulation.js +35 -30
- package/src/telemetry.js +20 -0
- package/src/trading.js +806 -40
- package/src/transfer.js +75 -9
- package/src/update-check.js +9 -1
- package/src/wallet.js +240 -20
- package/src/walletconnect-trading.js +29 -8
- package/src/walletconnect-x402.js +9 -5
- package/src/x402-svm.js +123 -64
- package/src/x402.js +46 -14
package/src/commands/agent.js
CHANGED
|
@@ -4,20 +4,20 @@
|
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
import crypto from 'crypto';
|
|
7
|
-
import { NansenError, ErrorCode, statusToErrorCode, telemetryHeaders, packageVersion } from '../api.js';
|
|
7
|
+
import { NansenError, ErrorCode, statusToErrorCode, browserSessionError, browserSessionResponseMeta, telemetryHeaders, packageVersion } from '../api.js';
|
|
8
8
|
import { getCostForEndpoint } from '../cost-cache.js';
|
|
9
9
|
import { readResponseMeta } from '../response-meta.js';
|
|
10
10
|
|
|
11
11
|
/**
|
|
12
12
|
* Build standard request headers, matching apiInstance.request() conventions.
|
|
13
13
|
*/
|
|
14
|
-
function buildHeaders(apiInstance) {
|
|
14
|
+
async function buildHeaders(apiInstance) {
|
|
15
15
|
return {
|
|
16
16
|
'Content-Type': 'application/json',
|
|
17
17
|
'X-Client-Type': 'nansen-cli',
|
|
18
18
|
'X-Client-Version': packageVersion,
|
|
19
19
|
...telemetryHeaders(),
|
|
20
|
-
...
|
|
20
|
+
...await apiInstance.requestCredentials(),
|
|
21
21
|
...(apiInstance.defaultHeaders || {}),
|
|
22
22
|
};
|
|
23
23
|
}
|
|
@@ -74,8 +74,11 @@ export async function consumeSSEStream(response, callbacks = {}) {
|
|
|
74
74
|
|
|
75
75
|
const processFrame = (frame) => {
|
|
76
76
|
for (const line of frame.split('\n')) {
|
|
77
|
-
if (!line.startsWith('data:
|
|
78
|
-
|
|
77
|
+
if (!line.startsWith('data:')) continue;
|
|
78
|
+
// SSE permits `data:value` and `data: value`; discard at most the one
|
|
79
|
+
// optional space after the colon before parsing the field value.
|
|
80
|
+
const fieldValue = line.slice(5);
|
|
81
|
+
const payload = fieldValue.startsWith(' ') ? fieldValue.slice(1) : fieldValue;
|
|
79
82
|
if (payload === '[DONE]') { done = true; return; }
|
|
80
83
|
|
|
81
84
|
let event;
|
|
@@ -239,7 +242,7 @@ EXAMPLES:
|
|
|
239
242
|
}
|
|
240
243
|
|
|
241
244
|
// ── Auth guard ──
|
|
242
|
-
if (
|
|
245
|
+
if (apiInstance.selection?.kind === 'anonymous') {
|
|
243
246
|
throw new NansenError(
|
|
244
247
|
'Not logged in. Run: nansen login',
|
|
245
248
|
ErrorCode.UNAUTHORIZED,
|
|
@@ -249,12 +252,15 @@ EXAMPLES:
|
|
|
249
252
|
}
|
|
250
253
|
|
|
251
254
|
// ── Request (no retry — SSE streams are not idempotent) ──
|
|
255
|
+
const sessionAuth = apiInstance.selection?.kind === 'session';
|
|
252
256
|
const url = `${apiInstance.baseUrl}${endpoint}`;
|
|
253
257
|
const body = {
|
|
254
258
|
text: question,
|
|
255
259
|
conversation_id: conversationId,
|
|
256
260
|
};
|
|
257
261
|
|
|
262
|
+
const requestHeaders = await buildHeaders(apiInstance);
|
|
263
|
+
|
|
258
264
|
// ── Timeout ──
|
|
259
265
|
const timeoutMs = expert ? 300_000 : 120_000; // 5min expert, 2min fast
|
|
260
266
|
const controller = new AbortController();
|
|
@@ -268,7 +274,7 @@ EXAMPLES:
|
|
|
268
274
|
// forwards custom credential headers (apikey) across a cross-origin
|
|
269
275
|
// redirect, handing the key to whatever host the response points at.
|
|
270
276
|
redirect: 'error',
|
|
271
|
-
headers:
|
|
277
|
+
headers: requestHeaders,
|
|
272
278
|
body: JSON.stringify(body),
|
|
273
279
|
signal: controller.signal,
|
|
274
280
|
});
|
|
@@ -283,10 +289,10 @@ EXAMPLES:
|
|
|
283
289
|
);
|
|
284
290
|
}
|
|
285
291
|
throw new NansenError(
|
|
286
|
-
`Network error: ${err.message}`,
|
|
292
|
+
sessionAuth ? 'Agent network request failed. Retry after checking connectivity.' : `Network error: ${err.message}`,
|
|
287
293
|
ErrorCode.NETWORK_ERROR,
|
|
288
294
|
null,
|
|
289
|
-
{ originalError: err.message },
|
|
295
|
+
sessionAuth ? {} : { originalError: err.message },
|
|
290
296
|
);
|
|
291
297
|
}
|
|
292
298
|
|
|
@@ -300,6 +306,10 @@ EXAMPLES:
|
|
|
300
306
|
serverDetail = errData.detail || errData.message;
|
|
301
307
|
} catch { /* ignore parse failure */ }
|
|
302
308
|
}
|
|
309
|
+
if (sessionAuth) {
|
|
310
|
+
const safe = browserSessionError(response.status, errData);
|
|
311
|
+
throw new NansenError(safe.message, safe.code, response.status, browserSessionResponseMeta(response));
|
|
312
|
+
}
|
|
303
313
|
const meta = readResponseMeta(response);
|
|
304
314
|
throwApiError(
|
|
305
315
|
serverDetail || `Agent returned ${response.status}`,
|
|
@@ -321,6 +331,7 @@ EXAMPLES:
|
|
|
321
331
|
{ detail: `${modeName} mode timeout (${timeoutMs / 1000}s)` },
|
|
322
332
|
);
|
|
323
333
|
}
|
|
334
|
+
if (sessionAuth) throw new NansenError('Agent stream failed. The selected browser session was not replaced.', err.code || ErrorCode.NETWORK_ERROR, err.status || null);
|
|
324
335
|
throw err;
|
|
325
336
|
};
|
|
326
337
|
|
package/src/commands/alerts.js
CHANGED
|
@@ -132,7 +132,7 @@ function parseFiniteNumber(raw, name) {
|
|
|
132
132
|
/**
|
|
133
133
|
* Validate a single-value string filter option (e.g. --chain, --token-address).
|
|
134
134
|
* Empty string/undefined mean "not provided"; any other non-string value
|
|
135
|
-
* (e.g. `--chain
|
|
135
|
+
* (e.g. `--chain '{}'`, from parseArgs' JSON.parse of option values) is
|
|
136
136
|
* rejected instead of crashing on .toLowerCase() or being silently dropped
|
|
137
137
|
* by a falsy check.
|
|
138
138
|
*/
|
|
@@ -19,28 +19,15 @@ const { version: VERSION } = require('../../package.json');
|
|
|
19
19
|
export const COMPLETION_SHELLS = ['bash', 'zsh', 'fish'];
|
|
20
20
|
|
|
21
21
|
/**
|
|
22
|
-
* Commands the CLI dispatches that schema.json does not describe.
|
|
23
|
-
*
|
|
24
|
-
* path runs before the hand-written text), so they are declared here.
|
|
22
|
+
* Commands the CLI dispatches that schema.json does not describe. They retain
|
|
23
|
+
* their hand-written help; the schema help path otherwise takes precedence.
|
|
25
24
|
* completion.test.js fails if a new top-level command appears in neither place.
|
|
26
25
|
*/
|
|
27
26
|
export const UNSCHEMA_COMMANDS = {
|
|
28
|
-
login: {
|
|
29
|
-
description: 'Save your Nansen API key',
|
|
30
|
-
options: {
|
|
31
|
-
'api-key': { type: 'string', description: 'API key (recorded in shell history — prefer --human)' },
|
|
32
|
-
human: { type: 'boolean', description: 'Prompt for the key interactively' },
|
|
33
|
-
},
|
|
34
|
-
},
|
|
35
|
-
logout: { description: 'Remove the saved API key' },
|
|
36
27
|
schema: {
|
|
37
28
|
description: 'Print the JSON schema for every command',
|
|
38
29
|
options: { full: { type: 'boolean', description: 'Verbose schema instead of the compact listing' } },
|
|
39
30
|
},
|
|
40
|
-
cache: {
|
|
41
|
-
description: 'API response cache maintenance',
|
|
42
|
-
subcommands: { clear: { description: 'Clear all cached responses' } },
|
|
43
|
-
},
|
|
44
31
|
changelog: {
|
|
45
32
|
description: 'Show release history',
|
|
46
33
|
options: { since: { type: 'string', description: 'Only show versions at or above this one' } },
|
package/src/commands/mcp.js
CHANGED
|
@@ -8,22 +8,27 @@
|
|
|
8
8
|
|
|
9
9
|
import { CommandError } from '../api.js';
|
|
10
10
|
import { DEFAULT_MCP_URL, formatMcpVerifyReport, runMcpVerifyChecks } from '../mcp-verify.js';
|
|
11
|
+
import { MCP_CLIENT_CONFIG, buildHttpEntry, buildStdioEntry, mcpRemoteSpec } from '../mcp-client-config.js';
|
|
11
12
|
import fs from 'fs';
|
|
12
13
|
import os from 'os';
|
|
13
14
|
import path from 'path';
|
|
14
15
|
|
|
16
|
+
// All values below come from src/mcp-client-config.json (API-322), the one
|
|
17
|
+
// maintained source that the README, the GitBook page and the .dxt manifest
|
|
18
|
+
// are generated from. Edit that file, not these constants.
|
|
19
|
+
|
|
15
20
|
// Hosted Nansen MCP server (streamable HTTP, auth via NANSEN-API-KEY header).
|
|
16
|
-
// Deliberately
|
|
17
|
-
// API key into a config that sends it to an arbitrary host.
|
|
18
|
-
// (REST dev override) intentionally does not affect this.
|
|
19
|
-
export const NANSEN_MCP_URL =
|
|
21
|
+
// Deliberately not user-configurable: a user-supplied URL would let `install`
|
|
22
|
+
// write the API key into a config that sends it to an arbitrary host.
|
|
23
|
+
// NANSEN_BASE_URL (REST dev override) intentionally does not affect this.
|
|
24
|
+
export const NANSEN_MCP_URL = MCP_CLIENT_CONFIG.endpoint;
|
|
20
25
|
|
|
21
26
|
// Claude Desktop's config only supports stdio servers, so it bridges through
|
|
22
27
|
// mcp-remote. Pinned exact so `npx -y` never auto-pulls a compromised future
|
|
23
|
-
// release; bump deliberately.
|
|
24
|
-
export const MCP_REMOTE_PIN =
|
|
28
|
+
// release; bump deliberately (see AGENTS.md > MCP client config).
|
|
29
|
+
export const MCP_REMOTE_PIN = mcpRemoteSpec();
|
|
25
30
|
|
|
26
|
-
const SERVER_KEY =
|
|
31
|
+
const SERVER_KEY = MCP_CLIENT_CONFIG.serverKey;
|
|
27
32
|
|
|
28
33
|
// House idiom (see src/api.js CONFIG_DIR): env first so tests can point HOME
|
|
29
34
|
// at a temp dir; os.homedir() as last resort.
|
|
@@ -49,8 +54,8 @@ OPTIONS:
|
|
|
49
54
|
--send-api-key Authorize sending your saved API key to a custom --url
|
|
50
55
|
(an https:// or loopback host). Not needed for --api-key.
|
|
51
56
|
|
|
52
|
-
The API key is taken from \`nansen login\` / NANSEN_API_KEY. Re-run install after
|
|
53
|
-
rotating your key to update the entry. Other clients:
|
|
57
|
+
The API key is taken from \`nansen login --human\` / NANSEN_API_KEY. Re-run install after
|
|
58
|
+
rotating your key to update the entry. Other clients: ${MCP_CLIENT_CONFIG.docsUrl}`;
|
|
54
59
|
|
|
55
60
|
/**
|
|
56
61
|
* Resolve the client's config file path for this platform.
|
|
@@ -83,16 +88,17 @@ export function buildServerEntry(client, apiKey) {
|
|
|
83
88
|
switch (client) {
|
|
84
89
|
case 'claude-code':
|
|
85
90
|
// "type" is required — a url without type is treated as broken stdio and skipped
|
|
86
|
-
return
|
|
91
|
+
return buildHttpEntry(apiKey, { withType: true });
|
|
87
92
|
case 'cursor':
|
|
88
|
-
return
|
|
93
|
+
return buildHttpEntry(apiKey);
|
|
89
94
|
case 'claude-desktop':
|
|
90
95
|
// Header name and value must be one arg. mcp-remote parses with
|
|
91
96
|
// /^([A-Za-z0-9_-]+):\s*(.*)$/, so whitespace after the colon is trimmed;
|
|
92
97
|
// what breaks it is an empty value.
|
|
93
98
|
// The ${NANSEN_API_KEY} placeholder is NOT shell syntax: mcp-remote itself
|
|
94
99
|
// substitutes ${VAR} in header values from its process env — see
|
|
95
|
-
// mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576
|
|
100
|
+
// mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576 (re-check this
|
|
101
|
+
// behavior before a pin bump; see AGENTS.md > MCP client config)
|
|
96
102
|
// (`value.replace(/\$\{([^}]+)}/g, ...)`, logging "Replacing ${...} with
|
|
97
103
|
// environment value in header"). Claude Desktop injects the `env` block
|
|
98
104
|
// into the spawned npx process, mcp-remote expands the reference, and the
|
|
@@ -100,11 +106,7 @@ export function buildServerEntry(client, apiKey) {
|
|
|
100
106
|
// the exact written config connects to prod with the substitution logged.
|
|
101
107
|
// Do NOT "fix" this by inlining the key into args.
|
|
102
108
|
// No --allow-http: the URL is HTTPS.
|
|
103
|
-
return
|
|
104
|
-
command: 'npx',
|
|
105
|
-
args: ['-y', MCP_REMOTE_PIN, NANSEN_MCP_URL, '--header', 'NANSEN-API-KEY:${NANSEN_API_KEY}'],
|
|
106
|
-
env: { NANSEN_API_KEY: apiKey },
|
|
107
|
-
};
|
|
109
|
+
return buildStdioEntry(apiKey);
|
|
108
110
|
default:
|
|
109
111
|
throw new CommandError(`Unknown client: ${client}. Supported: ${SUPPORTED_CLIENTS.join(', ')}`, 'INVALID_PARAMS');
|
|
110
112
|
}
|
|
@@ -233,8 +235,8 @@ export function buildMcpCommands(deps = {}) {
|
|
|
233
235
|
if (flags['api-key']) {
|
|
234
236
|
throw new CommandError('--api-key requires a value. Usage: nansen mcp verify --api-key <key>', 'MISSING_PARAM');
|
|
235
237
|
}
|
|
236
|
-
// parseArgs
|
|
237
|
-
//
|
|
238
|
+
// parseArgs turns a repeated flag into an array and a JSON object/array
|
|
239
|
+
// value into an object - both must fail, not fall back.
|
|
238
240
|
if ('api-key' in options && typeof options['api-key'] !== 'string') {
|
|
239
241
|
throw new CommandError('--api-key must be a single key string. Usage: nansen mcp verify --api-key <key>', 'INVALID_PARAMS');
|
|
240
242
|
}
|
|
@@ -356,7 +358,7 @@ export function buildMcpCommands(deps = {}) {
|
|
|
356
358
|
// install
|
|
357
359
|
const apiKey = apiInstance?.apiKey;
|
|
358
360
|
if (!apiKey) {
|
|
359
|
-
throw new CommandError('
|
|
361
|
+
throw new CommandError('MCP installation requires an API key. Set NANSEN_API_KEY or run nansen login --human. Browser sessions are not exported to MCP clients.', 'API_KEY_REQUIRED');
|
|
360
362
|
}
|
|
361
363
|
|
|
362
364
|
// Deliberate asymmetry with uninstall --dry-run (which previews even an
|
package/src/commands/research.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
7
|
import { NansenError, ErrorCode } from '../api.js';
|
|
8
|
-
import { parseSort, rejectBlankOption } from '../query-options.js';
|
|
8
|
+
import { parseSort, rejectBlankOption, parseObjectOption } from '../query-options.js';
|
|
9
9
|
|
|
10
10
|
// Research subcommands validate --page strictly. The shared helper in
|
|
11
11
|
// src/query-options.js clamps an invalid page to 1 for the category commands,
|
|
@@ -79,6 +79,8 @@ function parseTimeframeDays(value) {
|
|
|
79
79
|
function parseBooleanOption(options, flags, key) {
|
|
80
80
|
const value = options[key] ?? flags[key];
|
|
81
81
|
if (value === undefined) return undefined;
|
|
82
|
+
// Bare flags arrive through `flags` as true; explicit values arrive through
|
|
83
|
+
// `options` as strings (for example, `--apply-blacklist-filter false`).
|
|
82
84
|
if (typeof value === 'boolean') return value;
|
|
83
85
|
if (value === 'true' || value === '1') return true;
|
|
84
86
|
if (value === 'false' || value === '0') return false;
|
|
@@ -254,7 +256,7 @@ export function buildResearchCommands(deps = {}) {
|
|
|
254
256
|
|
|
255
257
|
const orderBy = parseSort(options.sort, options['order-by']);
|
|
256
258
|
const pagination = buildPagination(options);
|
|
257
|
-
const filters = options.filters
|
|
259
|
+
const filters = parseObjectOption(options.filters, 'filters');
|
|
258
260
|
const { fromDate, toDate } = resolveDateRange(options);
|
|
259
261
|
const asOfDate = options['as-of-date'];
|
|
260
262
|
|
package/src/cost-cache.js
CHANGED
|
@@ -14,6 +14,14 @@ const CACHE_FILE = path.join(CONFIG_DIR, 'cost-map.json');
|
|
|
14
14
|
const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
|
|
15
15
|
const OPENAPI_URL = 'https://api.nansen.ai/openapi.json';
|
|
16
16
|
|
|
17
|
+
/** How long a fetched cost map stays fresh. */
|
|
18
|
+
export const COST_MAP_TTL_MS = STALE_MS;
|
|
19
|
+
|
|
20
|
+
/** Absolute path of the cost map cache file, for `nansen cache stats` and `clear`. */
|
|
21
|
+
export function getCostMapFile() {
|
|
22
|
+
return CACHE_FILE;
|
|
23
|
+
}
|
|
24
|
+
|
|
17
25
|
/**
|
|
18
26
|
* Write `data` to `file` atomically: write to a unique temp file in the same
|
|
19
27
|
* directory, then rename over the target. rename(2) is atomic on POSIX, so a
|
|
@@ -55,7 +63,13 @@ export function getCostForEndpoint(endpoint) {
|
|
|
55
63
|
export function creditsCharged(meta, endpoint) {
|
|
56
64
|
const charged = meta?.credits?.cost;
|
|
57
65
|
if (charged != null) return { cost: charged, source: 'header' };
|
|
58
|
-
|
|
66
|
+
let estimate = endpoint ? getCostForEndpoint(endpoint) : null;
|
|
67
|
+
const livePages = meta?.pagination?.livePages;
|
|
68
|
+
if (estimate != null && Number.isSafeInteger(livePages) && livePages > 1) {
|
|
69
|
+
estimate = Object.fromEntries(
|
|
70
|
+
Object.entries(estimate).map(([plan, cost]) => [plan, typeof cost === 'number' ? cost * livePages : cost])
|
|
71
|
+
);
|
|
72
|
+
}
|
|
59
73
|
if (estimate != null) return { estimate, source: 'estimate' };
|
|
60
74
|
return null;
|
|
61
75
|
}
|
|
@@ -69,7 +83,7 @@ export async function refreshCostMapIfStale() {
|
|
|
69
83
|
try {
|
|
70
84
|
if (fs.existsSync(CACHE_FILE)) {
|
|
71
85
|
const { fetchedAt } = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
|
|
72
|
-
if (fetchedAt && Date.now() - fetchedAt < STALE_MS) return;
|
|
86
|
+
if (Number.isFinite(fetchedAt) && fetchedAt !== 0 && Date.now() - fetchedAt < STALE_MS) return;
|
|
73
87
|
}
|
|
74
88
|
|
|
75
89
|
const controller = new AbortController();
|
package/src/debug.js
ADDED
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Opt-in HTTP request tracing for the CLI.
|
|
3
|
+
*
|
|
4
|
+
* Turned on by the global `--debug` flag (which calls setDebugEnabled) or by
|
|
5
|
+
* `NANSEN_DEBUG=1` in the environment. The generic `DEBUG` variable is not
|
|
6
|
+
* consulted: other packages commonly use it, and enabling HTTP tracing must
|
|
7
|
+
* always be an explicit Nansen choice.
|
|
8
|
+
*
|
|
9
|
+
* Everything is written to **stderr**, never stdout. stdout carries the JSON
|
|
10
|
+
* or CSV that callers pipe into other programs, and a trace line in that
|
|
11
|
+
* stream would corrupt it.
|
|
12
|
+
*
|
|
13
|
+
* Nothing here ever prints a credential. Request and response bodies are never
|
|
14
|
+
* traced at all, header values are never traced, URLs go through redactUrl(),
|
|
15
|
+
* and every value handed to trace() goes through redact() first. Redaction is
|
|
16
|
+
* deliberately over-eager: an over-redacted value costs one support round
|
|
17
|
+
* trip, a leaked one costs a key rotation.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/** Placeholder written in place of anything that might be a credential. */
|
|
21
|
+
export const REDACTED = '[redacted]';
|
|
22
|
+
|
|
23
|
+
/** Longest traced value; anything longer is cut and marked. */
|
|
24
|
+
export const MAX_VALUE_LENGTH = 200;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Field/parameter/header names whose value is never safe to print.
|
|
28
|
+
* Matches substrings, so `apikey`, `X-Api-Key`, `authorization`,
|
|
29
|
+
* `payment-signature` and `token_address` are all covered — the last one is
|
|
30
|
+
* not a secret, but fail-closed is the right side to err on here.
|
|
31
|
+
*/
|
|
32
|
+
const SECRET_NAME = /key|token|secret|signature|password|passphrase|mnemonic|seed|auth|credential|cookie|private/i;
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* A credential carried inline in a header-ish string, e.g. `Bearer eyJ...`.
|
|
36
|
+
* Two copies on purpose: a /g regex carries lastIndex between .test() calls,
|
|
37
|
+
* so the matcher and the replacer must not be the same object.
|
|
38
|
+
*/
|
|
39
|
+
// Only `Bearer`/`Basic` introduce an inline credential in text we trace. `Payment`
|
|
40
|
+
// and `Signature` are ordinary English words here, and header-name matching plus the
|
|
41
|
+
// value-shape rules below already cover a real payment signature — keeping them in
|
|
42
|
+
// this pattern only garbled prose like "payment was transmitted".
|
|
43
|
+
// The value must look like a credential (8+ chars) so "Bearer token" stays readable.
|
|
44
|
+
// Keep this matcher stateless (no /g): looksLikeSecretValue calls .test() on
|
|
45
|
+
// it, while INLINE_SCHEME_ALL below is the separate global replacement copy.
|
|
46
|
+
const INLINE_SCHEME = /\b(Bearer|Basic)\s+[\w.~+/=-]{8,}/i;
|
|
47
|
+
const INLINE_SCHEME_ALL = new RegExp(INLINE_SCHEME.source, 'gi');
|
|
48
|
+
|
|
49
|
+
/** Request ids and other UUIDs are identifiers, not secrets — keep them readable. */
|
|
50
|
+
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
51
|
+
|
|
52
|
+
/** Private-key shaped: 32 bytes of hex, with or without the 0x prefix. */
|
|
53
|
+
const HEX_32_BYTES = /^(0x)?[0-9a-fA-F]{64}$/;
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* BIP-39 shaped: 12–24 lowercase words. Intentionally covers non-standard
|
|
57
|
+
* counts between the valid BIP-39 sizes too; over-redacting prose is safer
|
|
58
|
+
* than letting a malformed or partially copied recovery phrase through.
|
|
59
|
+
*/
|
|
60
|
+
const MNEMONIC = /^([a-z]{3,10} ){11,23}[a-z]{3,10}$/;
|
|
61
|
+
|
|
62
|
+
/** JWT shaped: three dot-separated base64url segments starting with a JSON header. */
|
|
63
|
+
const JWT = /^ey[\w-]{8,}\.[\w-]{4,}\.[\w-]+$/;
|
|
64
|
+
|
|
65
|
+
/** Base58 secret-key shaped (Solana keypairs are ~88 chars; addresses are ≤44). */
|
|
66
|
+
const LONG_BASE58 = /^[1-9A-HJ-NP-Za-km-z]{80,}$/;
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Long opaque blob — an encoded payment payload, an API key, a session token.
|
|
70
|
+
* The 64-character floor keeps public identifiers readable: EVM addresses are
|
|
71
|
+
* 42 characters and base58 mint addresses at most 44.
|
|
72
|
+
*/
|
|
73
|
+
const LONG_OPAQUE = /^[A-Za-z0-9_\-+/=.]{64,}$/;
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Credential-shaped substrings inside otherwise useful diagnostic prose.
|
|
77
|
+
*
|
|
78
|
+
* IMPORTANT: every module-level /g regex in this block, plus
|
|
79
|
+
* INLINE_SCHEME_ALL above, is replacement-only. Use these only with
|
|
80
|
+
* String.prototype.replace — never RegExp.test() or RegExp.exec(), whose
|
|
81
|
+
* stateful lastIndex would make results depend on earlier trace calls. Add a
|
|
82
|
+
* separate non-/g matcher (as INLINE_SCHEME does) if matching is ever needed.
|
|
83
|
+
*/
|
|
84
|
+
const EMBEDDED_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi;
|
|
85
|
+
const EMBEDDED_NAMED_SECRET = /\b([\w-]*(?:key|token|secret|signature|password|passphrase|mnemonic|seed|auth|credential|cookie|private)[\w-]*)\s*([=:])\s*([^\s,;]+)/gi;
|
|
86
|
+
const EMBEDDED_HEX_32_BYTES = /(?<![0-9a-fA-F])(?:0x)?[0-9a-fA-F]{64}(?![0-9a-fA-F])/g;
|
|
87
|
+
const EMBEDDED_JWT = /\bey[\w-]{8,}\.[\w-]{4,}\.[\w-]+\b/g;
|
|
88
|
+
// NOTE: This intentionally also hides public long identifiers in error prose
|
|
89
|
+
// (for example Solana transaction signatures and block hashes). See README
|
|
90
|
+
// "Debugging"; do not loosen the threshold without auditing credential leaks.
|
|
91
|
+
const EMBEDDED_LONG_OPAQUE = /(?<![A-Za-z0-9_\-+/=.])[A-Za-z0-9_\-+/=.]{64,}(?![A-Za-z0-9_\-+/=.])/g;
|
|
92
|
+
|
|
93
|
+
let forcedEnabled = null;
|
|
94
|
+
let writer = null;
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Force tracing on or off for the process, overriding the environment.
|
|
98
|
+
* Pass undefined to hand control back to NANSEN_DEBUG.
|
|
99
|
+
*/
|
|
100
|
+
export function setDebugEnabled(enabled) {
|
|
101
|
+
forcedEnabled = enabled === undefined ? null : Boolean(enabled);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Replace the stderr sink. Pass undefined to restore it. Tests only. */
|
|
105
|
+
export function setDebugWriter(fn) {
|
|
106
|
+
writer = typeof fn === 'function' ? fn : null;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function envEnabled(value) {
|
|
110
|
+
if (value === undefined || value === null) return false;
|
|
111
|
+
const normalized = String(value).trim().toLowerCase();
|
|
112
|
+
if (normalized === '') return false;
|
|
113
|
+
return !['0', 'false', 'no', 'off'].includes(normalized);
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
export function isDebugEnabled() {
|
|
117
|
+
if (forcedEnabled !== null) return forcedEnabled;
|
|
118
|
+
return envEnabled(process.env.NANSEN_DEBUG);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Cut a value to MAX_VALUE_LENGTH, marking that it was cut. */
|
|
122
|
+
export function truncate(value, max = MAX_VALUE_LENGTH) {
|
|
123
|
+
const text = String(value);
|
|
124
|
+
if (text.length <= max) return text;
|
|
125
|
+
return `${text.slice(0, max)}…(+${text.length - max} more)`;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** Whether a field, query parameter, or header name names a credential. */
|
|
129
|
+
export function isSecretName(name) {
|
|
130
|
+
return SECRET_NAME.test(String(name ?? ''));
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Whether a value looks like a credential regardless of what it is called —
|
|
135
|
+
* a private key, a mnemonic, a JWT, an encoded payment payload.
|
|
136
|
+
*/
|
|
137
|
+
export function looksLikeSecretValue(value) {
|
|
138
|
+
if (typeof value !== 'string') return false;
|
|
139
|
+
const text = value.trim();
|
|
140
|
+
if (text === '' || UUID.test(text)) return false;
|
|
141
|
+
return (
|
|
142
|
+
HEX_32_BYTES.test(text) ||
|
|
143
|
+
MNEMONIC.test(text) ||
|
|
144
|
+
JWT.test(text) ||
|
|
145
|
+
LONG_BASE58.test(text) ||
|
|
146
|
+
LONG_OPAQUE.test(text) ||
|
|
147
|
+
INLINE_SCHEME.test(text)
|
|
148
|
+
);
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function redactString(value) {
|
|
152
|
+
// Delegate only when the whole value is a URL. URL-prefixed diagnostic
|
|
153
|
+
// prose must still pass through the embedded Bearer/JWT/secret scrubbers.
|
|
154
|
+
if (/^[a-z][a-z0-9+.-]*:\/\/\S+$/i.test(value)) return redactUrl(value);
|
|
155
|
+
// Drop inline credentials first, keeping the scheme label ("Bearer …") so
|
|
156
|
+
// the trace still says what kind of credential was in play. Doing this
|
|
157
|
+
// before the shape checks keeps the surrounding prose readable.
|
|
158
|
+
const neutralized = value
|
|
159
|
+
.replace(EMBEDDED_URL, match => redactUrl(match))
|
|
160
|
+
.replace(INLINE_SCHEME_ALL, (_match, kind) => `${kind} ${REDACTED}`)
|
|
161
|
+
.replace(EMBEDDED_NAMED_SECRET, (_match, name, separator) => `${name}${separator}${REDACTED}`)
|
|
162
|
+
.replace(EMBEDDED_HEX_32_BYTES, REDACTED)
|
|
163
|
+
.replace(EMBEDDED_JWT, REDACTED)
|
|
164
|
+
.replace(EMBEDDED_LONG_OPAQUE, REDACTED);
|
|
165
|
+
if (neutralized !== value) return truncate(neutralized);
|
|
166
|
+
return looksLikeSecretValue(neutralized) ? REDACTED : truncate(neutralized);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Redact a string, array, or (possibly nested) object for tracing.
|
|
171
|
+
* Values under a secret-looking key are replaced wholesale; every other value
|
|
172
|
+
* is still checked for credential-shaped content and truncated.
|
|
173
|
+
*/
|
|
174
|
+
export function redact(value, seen = new WeakSet()) {
|
|
175
|
+
if (value === null || value === undefined) return value;
|
|
176
|
+
if (typeof value === 'string') return redactString(value);
|
|
177
|
+
if (typeof value === 'number' || typeof value === 'boolean') return value;
|
|
178
|
+
if (typeof value === 'bigint') return `${value}`;
|
|
179
|
+
if (ArrayBuffer.isView(value)) {
|
|
180
|
+
return `[${value.constructor?.name || 'TypedArray'} ${value.byteLength} bytes]`;
|
|
181
|
+
}
|
|
182
|
+
if (value instanceof ArrayBuffer) return `[ArrayBuffer ${value.byteLength} bytes]`;
|
|
183
|
+
if (Array.isArray(value)) return value.map((item) => redact(item, seen));
|
|
184
|
+
if (typeof value === 'object') {
|
|
185
|
+
if (seen.has(value)) return '[circular]';
|
|
186
|
+
seen.add(value);
|
|
187
|
+
const out = {};
|
|
188
|
+
for (const [key, item] of Object.entries(value)) {
|
|
189
|
+
out[key] = isSecretName(key) ? REDACTED : redact(item, seen);
|
|
190
|
+
}
|
|
191
|
+
return out;
|
|
192
|
+
}
|
|
193
|
+
return truncate(String(value));
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Redact a URL: drop any userinfo and fragment, sanitize path segments, blank out query values
|
|
198
|
+
* whose parameter is credential-named, and blank out any remaining value that
|
|
199
|
+
* looks like a credential. Path segments that look credential-related are
|
|
200
|
+
* withheld because reset/session/payment credentials are often put there.
|
|
201
|
+
*/
|
|
202
|
+
export function redactUrl(raw) {
|
|
203
|
+
const text = String(raw ?? '');
|
|
204
|
+
let url;
|
|
205
|
+
try {
|
|
206
|
+
url = new URL(text);
|
|
207
|
+
} catch {
|
|
208
|
+
// Not parseable (a relative path, or a malformed URL). Fall back to a
|
|
209
|
+
// textual pass over the query string so nothing leaks from the odd case.
|
|
210
|
+
const queryIndex = text.indexOf('?');
|
|
211
|
+
if (queryIndex === -1) return truncate(text);
|
|
212
|
+
const base = text.slice(0, queryIndex);
|
|
213
|
+
const query = text.slice(queryIndex + 1);
|
|
214
|
+
return truncate(`${base}?${redactQueryText(query)}`);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
const parts = [];
|
|
218
|
+
for (const [key, value] of url.searchParams.entries()) {
|
|
219
|
+
const safe = isSecretName(key) || looksLikeSecretValue(value);
|
|
220
|
+
parts.push(`${encodeURIComponent(key)}=${safe ? REDACTED : encodeURIComponent(value)}`);
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
const credentials = url.username || url.password ? `${REDACTED}@` : '';
|
|
224
|
+
const query = parts.length ? `?${parts.join('&')}` : '';
|
|
225
|
+
const path = url.pathname.split('/').map((segment) => {
|
|
226
|
+
let decoded = segment;
|
|
227
|
+
try { decoded = decodeURIComponent(segment); } catch { /* keep raw text */ }
|
|
228
|
+
// Short path names describe API resources (`token-screener`, `auth`)
|
|
229
|
+
// rather than naming a value, so SECRET_NAME alone would hide the endpoint
|
|
230
|
+
// users need to diagnose. Long secret-named or credential-shaped dynamic
|
|
231
|
+
// segments still fail closed.
|
|
232
|
+
return looksLikeSecretValue(decoded) || (decoded.length >= 32 && isSecretName(decoded))
|
|
233
|
+
? REDACTED
|
|
234
|
+
: segment;
|
|
235
|
+
}).join('/');
|
|
236
|
+
return truncate(`${url.protocol}//${credentials}${url.host}${path}${query}`);
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
function redactQueryText(query) {
|
|
240
|
+
return query
|
|
241
|
+
.split('&')
|
|
242
|
+
.map((pair) => {
|
|
243
|
+
const index = pair.indexOf('=');
|
|
244
|
+
if (index === -1) return pair;
|
|
245
|
+
const key = pair.slice(0, index);
|
|
246
|
+
const value = pair.slice(index + 1);
|
|
247
|
+
let decoded = value;
|
|
248
|
+
try { decoded = decodeURIComponent(value); } catch { /* keep malformed encoding readable */ }
|
|
249
|
+
if (isSecretName(key)) return `${key}=${REDACTED}`;
|
|
250
|
+
const safe = redactString(decoded);
|
|
251
|
+
return `${key}=${safe === decoded ? value : safe}`;
|
|
252
|
+
})
|
|
253
|
+
.join('&');
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* Redact a header bag (plain object, Map, or fetch Headers) down to names
|
|
258
|
+
* only. Header values are never traced: even the innocuous ones carry nothing
|
|
259
|
+
* worth the risk of a rule that misses one. Production traces currently omit
|
|
260
|
+
* headers entirely; this is exported as the mandatory boundary if a future
|
|
261
|
+
* trace event ever includes header names.
|
|
262
|
+
*/
|
|
263
|
+
export function redactHeaders(headers) {
|
|
264
|
+
const entries = typeof headers?.entries === 'function' ? [...headers.entries()] : Object.entries(headers ?? {});
|
|
265
|
+
const out = {};
|
|
266
|
+
for (const [name] of entries) out[name] = REDACTED;
|
|
267
|
+
return out;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
function formatValue(key, value) {
|
|
271
|
+
const safe = key === 'url' ? redactUrl(value) : redact(value);
|
|
272
|
+
const text = typeof safe === 'object' ? JSON.stringify(safe) : String(safe);
|
|
273
|
+
const bounded = truncate(text);
|
|
274
|
+
return /[\s"]/.test(bounded) ? JSON.stringify(bounded) : bounded;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
function write(line) {
|
|
278
|
+
if (writer) writer(line);
|
|
279
|
+
else process.stderr.write(line);
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* Emit one trace line. No-op unless tracing is enabled.
|
|
284
|
+
* Fields are rendered as `key=value`, in the order given, with null and
|
|
285
|
+
* undefined fields dropped.
|
|
286
|
+
*/
|
|
287
|
+
export function trace(event, fields = {}) {
|
|
288
|
+
if (!isDebugEnabled()) return;
|
|
289
|
+
const parts = [`[nansen:debug] ${event}`];
|
|
290
|
+
for (const [key, value] of Object.entries(fields)) {
|
|
291
|
+
if (value === undefined || value === null) continue;
|
|
292
|
+
parts.push(`${key}=${formatValue(key, value)}`);
|
|
293
|
+
}
|
|
294
|
+
write(`${parts.join(' ')}\n`);
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/** An HTTP request is about to go out. */
|
|
298
|
+
export function traceRequest({ method, url, attempt, maxAttempts, payment }) {
|
|
299
|
+
trace('http.request', {
|
|
300
|
+
method,
|
|
301
|
+
url,
|
|
302
|
+
attempt: maxAttempts ? `${attempt}/${maxAttempts}` : attempt,
|
|
303
|
+
payment,
|
|
304
|
+
});
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Response headers arrived. `duration_ms` is time from attempt start until
|
|
309
|
+
* fetch resolves with headers (time to first byte / TTFB); it deliberately
|
|
310
|
+
* excludes downloading and parsing the response body.
|
|
311
|
+
*/
|
|
312
|
+
export function traceResponse({ method, url, status, durationMs, requestId, attempt, payment }) {
|
|
313
|
+
trace('http.response', {
|
|
314
|
+
method,
|
|
315
|
+
url,
|
|
316
|
+
status,
|
|
317
|
+
duration_ms: durationMs,
|
|
318
|
+
request_id: requestId,
|
|
319
|
+
attempt,
|
|
320
|
+
payment,
|
|
321
|
+
});
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* The request never produced response headers. `duration_ms` is elapsed time
|
|
326
|
+
* from attempt start until the transport failure.
|
|
327
|
+
*/
|
|
328
|
+
export function traceError({ method, url, durationMs, attempt, error }) {
|
|
329
|
+
trace('http.error', { method, url, duration_ms: durationMs, attempt, error });
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/** A retry was decided on: which attempt failed, why, and how long we wait. */
|
|
333
|
+
export function traceRetry({ method, url, status, attempt, reason, delayMs, retryAfterMs }) {
|
|
334
|
+
trace('http.retry', {
|
|
335
|
+
method,
|
|
336
|
+
url,
|
|
337
|
+
status,
|
|
338
|
+
attempt,
|
|
339
|
+
reason,
|
|
340
|
+
delay_ms: delayMs === undefined || delayMs === null ? null : Math.round(delayMs),
|
|
341
|
+
retry_after_ms: retryAfterMs,
|
|
342
|
+
});
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
/** The response came from the local cache, so no request was made at all. */
|
|
346
|
+
export function traceCacheHit({ method, url }) {
|
|
347
|
+
trace('http.cache_hit', { method, url });
|
|
348
|
+
}
|