ckb-cycle-tools 1.2.0 → 1.4.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/dist/flame.d.ts CHANGED
@@ -11,9 +11,19 @@
11
11
  */
12
12
  /** Stack (frames joined by `;`, outermost first) → cycles. */
13
13
  export type Folded = Map<string, bigint>;
14
+ /**
15
+ * A frame name with each U+037E (GREEK QUESTION MARK, which looks like `;`)
16
+ * turned back into `;`. Newer ckb-debugger and ckb-vm-pprof write a `;` inside
17
+ * a name that way, so it cannot be read as a frame separator
18
+ * (nervosnetwork/ckb-standalone-debugger#211, #212); older ones write `;`.
19
+ * Reading both as `;` keeps a function's name, and so its costs and diffs, the
20
+ * same whichever debugger profiled it.
21
+ */
22
+ export declare const asciiFrame: (name: string) => string;
14
23
  /**
15
24
  * `E:\…\src\main.rs:session_lock::lock_hash` → `session_lock::lock_hash`. The
16
- * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its address.
25
+ * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its
26
+ * address. A U+037E in the name is read as `;` (asciiFrame).
17
27
  */
18
28
  export declare function frameName(frame: string): string;
19
29
  /**
@@ -62,10 +72,18 @@ export declare function renderFlameSvg(tree: FlameNode, opts?: {
62
72
  minWidth?: number;
63
73
  }): string;
64
74
  /**
65
- * The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the
66
- * profile covers. The last one: when the script spawns other scripts, the
75
+ * The `All cycles: N` line ckb-debugger prints in flamegraph mode for the
76
+ * profiled run. The last one: when the script spawns other scripts, the
67
77
  * debugger first runs the whole group (printing its full total) to record
68
78
  * the syscalls, then profiles the root script alone ("Actual run").
79
+ *
80
+ * Up to ckb-debugger 1.1.1 this equals what the profile's frames cover. From
81
+ * 1.1.2 (nervosnetwork/ckb-standalone-debugger#209) it also counts loading the
82
+ * program, which no frame holds: on the spawn fixture 18,801 against 14,974 in
83
+ * the frames. It is not the group's total in either release (no spawned
84
+ * scripts, and 1.1.2 is still 14 cycles under the plain run on the testtool
85
+ * fixture). For what the frames cover, sum the folded stacks
86
+ * (`foldedTotal`), as `flame` and `report` do; it is the same in both releases.
69
87
  */
70
88
  export declare function profiledCycles(output: string): bigint | undefined;
71
89
  /**
@@ -77,3 +95,43 @@ export declare function profiledCycles(output: string): bigint | undefined;
77
95
  * script could print such a line itself; this count only adds a note.)
78
96
  */
79
97
  export declare function spawnedScripts(output: string): number;
98
+ /** One VM of a `Spawn tree:` that ckb-debugger prints in full mode (see spawnTree). */
99
+ export interface SpawnedVm {
100
+ /** The VM id, as `--vm-id` takes it. 0 is the group's own script. */
101
+ vm: number;
102
+ /** 0 for the program the VM was spawned with; more after each `exec` (`1/1`). `--vm-id` replays only generation 0. */
103
+ generation: number;
104
+ /** The VM that spawned it (the root's own parent is itself, 0). */
105
+ parent: number;
106
+ /** Where its binary came from, as printed: `cell_dep[1][0..11552]`. */
107
+ locator: string;
108
+ /** The same, parsed: the source, its index, and the byte range of the binary in that cell's data. */
109
+ source?: "input" | "output" | "cell_dep" | "header_dep" | "group_input" | "group_output";
110
+ index?: number;
111
+ start?: number;
112
+ end?: number;
113
+ }
114
+ /**
115
+ * Every VM in the `Spawn tree:` lines ckb-debugger (full mode) prints for a
116
+ * group whose script spawns others, root first, each with its parent and the
117
+ * locator of the binary it ran:
118
+ *
119
+ * Spawn tree: 0 cell_dep[0][0..15992]
120
+ * Spawn tree: └── 1 cell_dep[1][0..11552]
121
+ * Spawn tree: └── 2 cell_dep[2][0..9000]
122
+ *
123
+ * Each level of the tree is four characters of prefix. Empty when the script
124
+ * spawned nothing (no tree is printed). A script could print such lines itself
125
+ * (as a `Script log:` line, which does not start with `Spawn tree:`); only the
126
+ * debugger's own lines are read.
127
+ */
128
+ export declare function spawnTree(output: string): SpawnedVm[];
129
+ /** The first ckb-debugger release whose `--vm-id` replay of a spawned script is faithful, with `--vm-symbols` (1.1.2). */
130
+ export declare const CHILD_PROFILE_DEBUGGER = "1.1.2";
131
+ /**
132
+ * Whether a ckb-debugger (its `--version` line) can profile a spawned script on
133
+ * its own: 1.1.2 or later. Before it, the replay of `inherited_fds` was wrong
134
+ * (the child of the spawn fixture exits 3) and full mode read only the root's
135
+ * symbols. An unknown version cannot.
136
+ */
137
+ export declare function profilesChildren(version: string): boolean;
package/dist/flame.js CHANGED
@@ -9,12 +9,22 @@
9
9
  * A deployed binary is usually stripped: its whole run is one frame. Pass an
10
10
  * unstripped build of the same code (`ckb-debugger --bin`) to see functions.
11
11
  */
12
+ /**
13
+ * A frame name with each U+037E (GREEK QUESTION MARK, which looks like `;`)
14
+ * turned back into `;`. Newer ckb-debugger and ckb-vm-pprof write a `;` inside
15
+ * a name that way, so it cannot be read as a frame separator
16
+ * (nervosnetwork/ckb-standalone-debugger#211, #212); older ones write `;`.
17
+ * Reading both as `;` keeps a function's name, and so its costs and diffs, the
18
+ * same whichever debugger profiled it.
19
+ */
20
+ export const asciiFrame = (name) => name.replace(/\u037e/g, ";");
12
21
  /**
13
22
  * `E:\…\src\main.rs:session_lock::lock_hash` → `session_lock::lock_hash`. The
14
- * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its address.
23
+ * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its
24
+ * address. A U+037E in the name is read as `;` (asciiFrame).
15
25
  */
16
26
  export function frameName(frame) {
17
- const f = frame.trim();
27
+ const f = asciiFrame(frame.trim());
18
28
  if (f.startsWith("??:"))
19
29
  return f.slice(3);
20
30
  const m = /^.*?\.[A-Za-z0-9]+:(.+)$/.exec(f);
@@ -193,10 +203,18 @@ function colour(name) {
193
203
  return `hsl(${hue} 75% ${light}%)`;
194
204
  }
195
205
  /**
196
- * The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the
197
- * profile covers. The last one: when the script spawns other scripts, the
206
+ * The `All cycles: N` line ckb-debugger prints in flamegraph mode for the
207
+ * profiled run. The last one: when the script spawns other scripts, the
198
208
  * debugger first runs the whole group (printing its full total) to record
199
209
  * the syscalls, then profiles the root script alone ("Actual run").
210
+ *
211
+ * Up to ckb-debugger 1.1.1 this equals what the profile's frames cover. From
212
+ * 1.1.2 (nervosnetwork/ckb-standalone-debugger#209) it also counts loading the
213
+ * program, which no frame holds: on the spawn fixture 18,801 against 14,974 in
214
+ * the frames. It is not the group's total in either release (no spawned
215
+ * scripts, and 1.1.2 is still 14 cycles under the plain run on the testtool
216
+ * fixture). For what the frames cover, sum the folded stacks
217
+ * (`foldedTotal`), as `flame` and `report` do; it is the same in both releases.
200
218
  */
201
219
  export function profiledCycles(output) {
202
220
  const all = [...output.matchAll(/^All cycles:\s*(\d+)/gm)];
@@ -217,3 +235,62 @@ export function spawnedScripts(output) {
217
235
  ids.delete("0");
218
236
  return ids.size;
219
237
  }
238
+ /**
239
+ * Every VM in the `Spawn tree:` lines ckb-debugger (full mode) prints for a
240
+ * group whose script spawns others, root first, each with its parent and the
241
+ * locator of the binary it ran:
242
+ *
243
+ * Spawn tree: 0 cell_dep[0][0..15992]
244
+ * Spawn tree: └── 1 cell_dep[1][0..11552]
245
+ * Spawn tree: └── 2 cell_dep[2][0..9000]
246
+ *
247
+ * Each level of the tree is four characters of prefix. Empty when the script
248
+ * spawned nothing (no tree is printed). A script could print such lines itself
249
+ * (as a `Script log:` line, which does not start with `Spawn tree:`); only the
250
+ * debugger's own lines are read.
251
+ */
252
+ export function spawnTree(output) {
253
+ const vms = [];
254
+ const seen = new Set();
255
+ /** The VM at each depth, as the tree is walked top to bottom. */
256
+ const path = [];
257
+ for (const m of output.matchAll(/^Spawn tree: ([ │├└─]*)(\d+)(?:\/(\d+))?[ \t]+(\S+)[ \t]*$/gmu)) {
258
+ const depth = [...m[1]].length / 4;
259
+ if (!Number.isInteger(depth) || depth > path.length)
260
+ continue;
261
+ const vm = Number(m[2]);
262
+ const generation = Number(m[3] ?? 0);
263
+ const key = `${vm}/${generation}`;
264
+ if (seen.has(key))
265
+ continue;
266
+ seen.add(key);
267
+ path.length = depth;
268
+ const parent = depth ? path[depth - 1] : vm;
269
+ path.push(vm);
270
+ const loc = /^(input|output|cell_dep|header_dep|group_input|group_output)\[(\d+)\]\[(\d+)\.\.(\d+)\]$/.exec(m[4]);
271
+ vms.push({
272
+ vm,
273
+ generation,
274
+ parent,
275
+ locator: m[4],
276
+ ...(loc && { source: loc[1], index: Number(loc[2]), start: Number(loc[3]), end: Number(loc[4]) }),
277
+ });
278
+ }
279
+ return vms;
280
+ }
281
+ /** The first ckb-debugger release whose `--vm-id` replay of a spawned script is faithful, with `--vm-symbols` (1.1.2). */
282
+ export const CHILD_PROFILE_DEBUGGER = "1.1.2";
283
+ /**
284
+ * Whether a ckb-debugger (its `--version` line) can profile a spawned script on
285
+ * its own: 1.1.2 or later. Before it, the replay of `inherited_fds` was wrong
286
+ * (the child of the spawn fixture exits 3) and full mode read only the root's
287
+ * symbols. An unknown version cannot.
288
+ */
289
+ export function profilesChildren(version) {
290
+ const m = /(\d+)\.(\d+)\.(\d+)/.exec(version);
291
+ if (!m)
292
+ return false;
293
+ const [a, b, c] = m.slice(1).map(Number);
294
+ const [x, y, z] = CHILD_PROFILE_DEBUGGER.split(".").map(Number);
295
+ return a !== x ? a > x : b !== y ? b > y : c >= z;
296
+ }
package/dist/index.d.ts CHANGED
@@ -4,19 +4,24 @@ export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFound
4
4
  export type { ScriptGroup, TxAnalysis } from "./analyze.js";
5
5
  export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
6
6
  export type { HttpRpcOptions, MockTransaction, NodeConsensus, Rpc, RpcOutPoint, RpcTransaction, VmEpochs } from "./mock.js";
7
- export { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
7
+ export { checkMockTransaction, checkTypeId, debuggerArgs, DEFAULT_TX_CYCLE_LIMIT, groupsOf, nodeOrder, nodeStop, nodeVerdict, overTxLimitLines, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, sumLines, } from "./replay.js";
8
8
  export type { DebuggerOutput, GroupRun, Profile, ProfiledGroup, ReplayOptions, ReplayPlan, RunDebugger } from "./replay.js";
9
9
  export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
10
10
  export type { FlameGroup, ProfileOptions } from "./profile.js";
11
- export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, spawnedScripts, renderFlameSvg, splitStack, } from "./flame.js";
12
- export type { FlameNode, Folded, FunctionCost } from "./flame.js";
13
- export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
11
+ export { MAX_CHILD_PROFILES, olderDebuggerNote, profileChildren, profileSpawns, SERVER_EXIT_NOTE, serverExit } from "./children.js";
12
+ export type { ChildContext, FlameChild, SpawnSplit } from "./children.js";
13
+ export { resolvedCellDeps, spawnedBinary } from "./spawn.js";
14
+ export type { SpawnedBinary } from "./spawn.js";
15
+ export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, profilesChildren, spawnedScripts, spawnTree, CHILD_PROFILE_DEBUGGER, renderFlameSvg, splitStack, } from "./flame.js";
16
+ export type { FlameNode, Folded, FunctionCost, SpawnedVm } from "./flame.js";
17
+ export { runWasmDebugger, wasmDebuggerVersion, wasmFiles, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
14
18
  export type { WasmRun } from "./wasm.js";
15
19
  export { substituteBinaries } from "./substitute.js";
16
20
  export type { AppliedSubstitution, BinarySubstitution } from "./substitute.js";
17
- export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, resultLabel, summarize, } from "./diff.js";
18
- export type { CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, MarkdownOptions, ScenarioResult } from "./diff.js";
19
- export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
21
+ export { childDeltas, CHILDREN_FOOTNOTE, COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
22
+ export type { ChildDelta, ChildResult, CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, ManifestSummary, MarkdownOptions, ReportManifest, ScenarioManifest, ScenarioResult, } from "./diff.js";
23
+ export { canonicalJson, fileDigest, gitCommit, inputsHash, scenarioInputs, toolchainOf } from "./manifest.js";
24
+ export { childResult, formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
20
25
  export type { BinaryConfig, CyclesConfig, ReportOptions, ScenarioConfig } from "./report.js";
21
26
  export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
22
27
  export type { ScanOptions, ScanResult, ScannedBinary, ScannedMock } from "./scan.js";
package/dist/index.js CHANGED
@@ -1,11 +1,14 @@
1
1
  export { checkDebuggerPath, DebuggerNotFoundError, resolveDebugger } from "./debugger.js";
2
2
  export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFoundError } from "./analyze.js";
3
3
  export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
4
- export { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
4
+ export { checkMockTransaction, checkTypeId, debuggerArgs, DEFAULT_TX_CYCLE_LIMIT, groupsOf, nodeOrder, nodeStop, nodeVerdict, overTxLimitLines, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, sumLines, } from "./replay.js";
5
5
  export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
6
- export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, spawnedScripts, renderFlameSvg, splitStack, } from "./flame.js";
7
- export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
6
+ export { MAX_CHILD_PROFILES, olderDebuggerNote, profileChildren, profileSpawns, SERVER_EXIT_NOTE, serverExit } from "./children.js";
7
+ export { resolvedCellDeps, spawnedBinary } from "./spawn.js";
8
+ export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, profilesChildren, spawnedScripts, spawnTree, CHILD_PROFILE_DEBUGGER, renderFlameSvg, splitStack, } from "./flame.js";
9
+ export { runWasmDebugger, wasmDebuggerVersion, wasmFiles, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
8
10
  export { substituteBinaries } from "./substitute.js";
9
- export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, resultLabel, summarize, } from "./diff.js";
10
- export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
11
+ export { childDeltas, CHILDREN_FOOTNOTE, COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
12
+ export { canonicalJson, fileDigest, gitCommit, inputsHash, scenarioInputs, toolchainOf } from "./manifest.js";
13
+ export { childResult, formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
11
14
  export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
@@ -0,0 +1,37 @@
1
+ import type { ScenarioConfig } from "./report.js";
2
+ export declare const sha256: (data: Uint8Array | string) => string;
3
+ /** The sha256 and size of a file, read as a stream (a debugger binary is tens of MB). */
4
+ export declare function fileDigest(path: string): Promise<{
5
+ sha256: string;
6
+ size: number;
7
+ }>;
8
+ /** This package's name and version, from its package.json ("unknown" if it cannot be read). */
9
+ export declare function toolIdentity(): Promise<{
10
+ name: string;
11
+ version: string;
12
+ }>;
13
+ /**
14
+ * The commit checked out at `dir`, or undefined: not a git checkout, no git, or
15
+ * anything else. Never fails the report. Only a commit id is kept, whatever git printed.
16
+ */
17
+ export declare function gitCommit(dir: string): Promise<string | undefined>;
18
+ /** JSON with object keys sorted at every level: the same value always gives the same text. */
19
+ export declare function canonicalJson(value: unknown): string;
20
+ /**
21
+ * The part of a scenario's cycles.json entry that decides what runs: its form
22
+ * (and transaction hash), the binaries it names, its CKB-VM version, and for a
23
+ * transaction fetched from a node, the network. Not its name (the key it is
24
+ * matched by), the path of its file (whose bytes are hashed instead: a moved
25
+ * file with the same bytes is the same input), nor `functions` (which records
26
+ * names, not cycles).
27
+ */
28
+ export declare function scenarioInputs(s: ScenarioConfig, network: string | undefined): Record<string, unknown>;
29
+ /**
30
+ * sha256 over a scenario's inputs: the canonical entry (scenarioInputs), then
31
+ * the bytes of its mock or transaction file exactly as read, if it has one.
32
+ */
33
+ export declare function inputsHash(entry: Record<string, unknown>, file?: Uint8Array): string;
34
+ /** The longest toolchain description a report keeps. */
35
+ export declare const TOOLCHAIN_MAX = 4096;
36
+ /** A toolchain description as a report keeps it: trimmed, clipped; undefined when empty. */
37
+ export declare function toolchainOf(s: string | undefined): string | undefined;
@@ -0,0 +1,107 @@
1
+ /**
2
+ * What a report's numbers were measured with, so two reports can be checked for
3
+ * comparability (review #46, point 4): the tool, the debugger binary, the
4
+ * commit, the toolchain, and per scenario the CKB-VM version, a hash of its
5
+ * inputs and the binaries swapped into it. Node only (hashes files, runs git);
6
+ * the shape is in diff.ts, which compares it.
7
+ */
8
+ import { execFile } from "node:child_process";
9
+ import { createHash } from "node:crypto";
10
+ import { createReadStream } from "node:fs";
11
+ import { readFile } from "node:fs/promises";
12
+ export const sha256 = (data) => createHash("sha256").update(data).digest("hex");
13
+ /** The sha256 and size of a file, read as a stream (a debugger binary is tens of MB). */
14
+ export function fileDigest(path) {
15
+ return new Promise((resolve, reject) => {
16
+ const hash = createHash("sha256");
17
+ let size = 0;
18
+ createReadStream(path)
19
+ .on("data", (chunk) => {
20
+ const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
21
+ size += bytes.length;
22
+ hash.update(bytes);
23
+ })
24
+ .on("error", reject)
25
+ .on("end", () => resolve({ sha256: hash.digest("hex"), size }));
26
+ });
27
+ }
28
+ /** This package's name and version, from its package.json ("unknown" if it cannot be read). */
29
+ export async function toolIdentity() {
30
+ try {
31
+ const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
32
+ return { name: String(pkg.name ?? "ckb-cycle-tools"), version: String(pkg.version ?? "unknown") };
33
+ }
34
+ catch {
35
+ return { name: "ckb-cycle-tools", version: "unknown" };
36
+ }
37
+ }
38
+ const COMMIT = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
39
+ /**
40
+ * The commit checked out at `dir`, or undefined: not a git checkout, no git, or
41
+ * anything else. Never fails the report. Only a commit id is kept, whatever git printed.
42
+ */
43
+ export function gitCommit(dir) {
44
+ return new Promise((resolve) => {
45
+ try {
46
+ execFile("git", ["rev-parse", "--verify", "--quiet", "HEAD"], { cwd: dir, timeout: 10_000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" } }, (err, stdout) => {
47
+ const out = String(stdout ?? "").trim().toLowerCase();
48
+ resolve(!err && COMMIT.test(out) ? out : undefined);
49
+ });
50
+ }
51
+ catch {
52
+ resolve(undefined);
53
+ }
54
+ });
55
+ }
56
+ /** JSON with object keys sorted at every level: the same value always gives the same text. */
57
+ export function canonicalJson(value) {
58
+ if (Array.isArray(value))
59
+ return `[${value.map(canonicalJson).join(",")}]`;
60
+ if (value && typeof value === "object") {
61
+ const o = value;
62
+ return `{${Object.keys(o)
63
+ .filter((k) => o[k] !== undefined)
64
+ .sort()
65
+ .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
66
+ .join(",")}}`;
67
+ }
68
+ return JSON.stringify(value) ?? "null";
69
+ }
70
+ /**
71
+ * The part of a scenario's cycles.json entry that decides what runs: its form
72
+ * (and transaction hash), the binaries it names, its CKB-VM version, and for a
73
+ * transaction fetched from a node, the network. Not its name (the key it is
74
+ * matched by), the path of its file (whose bytes are hashed instead: a moved
75
+ * file with the same bytes is the same input), nor `functions` (which records
76
+ * names, not cycles).
77
+ */
78
+ export function scenarioInputs(s, network) {
79
+ const kind = s.mock !== undefined ? "mock" : s.file !== undefined ? "file" : "tx";
80
+ return {
81
+ kind,
82
+ ...(s.tx !== undefined && { tx: s.tx.toLowerCase() }),
83
+ ...(s.binaries !== undefined && { binaries: [...s.binaries].sort() }),
84
+ ...(s.scriptVersion !== undefined && { scriptVersion: s.scriptVersion }),
85
+ ...(kind !== "mock" && { network: network ?? null }),
86
+ };
87
+ }
88
+ /**
89
+ * sha256 over a scenario's inputs: the canonical entry (scenarioInputs), then
90
+ * the bytes of its mock or transaction file exactly as read, if it has one.
91
+ */
92
+ export function inputsHash(entry, file) {
93
+ const h = createHash("sha256");
94
+ h.update("ckb-cycles inputs v1\n");
95
+ h.update(canonicalJson(entry));
96
+ h.update("\n");
97
+ if (file)
98
+ h.update(file);
99
+ return h.digest("hex");
100
+ }
101
+ /** The longest toolchain description a report keeps. */
102
+ export const TOOLCHAIN_MAX = 4096;
103
+ /** A toolchain description as a report keeps it: trimmed, clipped; undefined when empty. */
104
+ export function toolchainOf(s) {
105
+ const t = (s ?? "").trim();
106
+ return t ? (t.length > TOOLCHAIN_MAX ? `${t.slice(0, TOOLCHAIN_MAX - 1)}…` : t) : undefined;
107
+ }
package/dist/mock.d.ts CHANGED
@@ -82,6 +82,11 @@ export interface NodeConsensus {
82
82
  /** "mainnet", "testnet", or the chain id for any other chain. */
83
83
  network: string;
84
84
  vmEpochs: VmEpochs;
85
+ /**
86
+ * The consensus `max_block_cycles`, when the node gives it: the node verifies
87
+ * each transaction under this one limit (see DEFAULT_TX_CYCLE_LIMIT).
88
+ */
89
+ maxBlockCycles?: bigint;
85
90
  }
86
91
  /**
87
92
  * Asks the node which chain it serves and when its hardforks took effect, so a
package/dist/mock.js CHANGED
@@ -94,7 +94,8 @@ export async function nodeConsensus(rpc) {
94
94
  return f.epoch_number === null ? Infinity : Number(f.epoch_number);
95
95
  };
96
96
  const network = c.id === "ckb" ? "mainnet" : c.id === "ckb_testnet" ? "testnet" : c.id;
97
- return { chain: c.id, network, vmEpochs: [epochOf("0032"), epochOf("0049")] };
97
+ const max = typeof c.max_block_cycles === "string" && /^0x[0-9a-fA-F]+$/.test(c.max_block_cycles) ? BigInt(c.max_block_cycles) : undefined;
98
+ return { chain: c.id, network, vmEpochs: [epochOf("0032"), epochOf("0049")], ...(max !== undefined && max > 0n && { maxBlockCycles: max }) };
98
99
  }
99
100
  /** Parses a molecule OutPointVec: u32 LE count, then 36-byte out points. */
100
101
  export function parseOutPointVec(data) {
package/dist/profile.d.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  import type { MockTransaction, RpcTransaction } from "./mock.js";
2
+ import { type FlameChild } from "./children.js";
2
3
  import { type Folded } from "./flame.js";
3
4
  import { type DebuggerOutput, type Profile, type ReplayOptions, type ReplayPlan } from "./replay.js";
4
5
  export { checkTypeId, parseDebuggerOutput, parseDebuggerRun, parseNames, readTransactionJson, selectorFor, TYPE_ID_CODE_HASH, TYPE_ID_CYCLES, } from "./replay.js";
5
6
  export type { DebuggerOutput, GroupRun, Profile, ProfiledGroup } from "./replay.js";
7
+ export { MAX_CHILD_PROFILES } from "./children.js";
8
+ export type { FlameChild } from "./children.js";
6
9
  /** The most a run may print. More is a script flooding its logs: the run is an error, not a result. */
7
10
  export declare const MAX_DEBUGGER_OUTPUT: number;
8
11
  export interface ProfileOptions extends ReplayOptions {
@@ -55,6 +58,15 @@ export interface FlameGroup {
55
58
  * but in no frame of `folded`, and `--bin` replaces only the root's binary.
56
59
  */
57
60
  spawned?: number;
61
+ /**
62
+ * With `spawned`: each spawned script's own profile, from one `--vm-id`
63
+ * replay per spawned VM (ckb-debugger 1.1.2 and later). The group's
64
+ * `cycles` stay the source of truth; these are profiled frames, and they
65
+ * leave out what the spawn itself costs the parent.
66
+ */
67
+ children?: FlameChild[];
68
+ /** With `spawned`: why some or all spawned scripts have no profile of their own (an older debugger, an `exec`, too many). */
69
+ childrenNote?: string;
58
70
  }
59
71
  /**
60
72
  * Profiles each script group with ckb-debugger's flamegraph mode. `bins` maps a
@@ -71,6 +83,15 @@ export declare function flameTransaction(target: string | RpcTransaction | MockT
71
83
  scripts?: string[];
72
84
  readFile: (path: string) => Promise<string>;
73
85
  readBinary?: (path: string) => Promise<Uint8Array>;
86
+ /**
87
+ * Unstripped builds of spawned scripts, by data hash (or the type hash of
88
+ * the cell they are in), to name a child's frames (`--vm-symbols`). `bins`
89
+ * is looked up too. Each must have the same code as the binary the child
90
+ * ran (elf.ts `sameCode`), or it is not used.
91
+ */
92
+ vmSymbols?: Record<string, string>;
93
+ /** Profile each spawned script on its own (default true; needs ckb-debugger 1.1.2). */
94
+ children?: boolean;
74
95
  }): Promise<{
75
96
  plan: ReplayPlan;
76
97
  groups: FlameGroup[];
package/dist/profile.js CHANGED
@@ -4,11 +4,14 @@ import { tmpdir } from "node:os";
4
4
  import { join } from "node:path";
5
5
  import { promisify } from "node:util";
6
6
  import { checkDebuggerPath, resolveDebugger } from "./debugger.js";
7
+ import { profileChildren } from "./children.js";
7
8
  import { elfFunctionNames } from "./elf.js";
8
9
  import { nameAddresses, parseFolded, spawnedScripts } from "./flame.js";
9
10
  import { debuggerArgs, parseDebuggerRun, planReplay, replayGroups, selectorFor, TYPE_ID_CODE_HASH, } from "./replay.js";
10
11
  // The pure parts live in replay.ts, shared with the browser; existing imports keep working.
11
12
  export { checkTypeId, parseDebuggerOutput, parseDebuggerRun, parseNames, readTransactionJson, selectorFor, TYPE_ID_CODE_HASH, TYPE_ID_CYCLES, } from "./replay.js";
13
+ // Child profiles live in children.ts, shared with the browser.
14
+ export { MAX_CHILD_PROFILES } from "./children.js";
12
15
  const run = promisify(execFile);
13
16
  /** The most a run may print. More is a script flooding its logs: the run is an error, not a result. */
14
17
  export const MAX_DEBUGGER_OUTPUT = 64 << 20;
@@ -82,6 +85,8 @@ export async function flameTransaction(target, options) {
82
85
  const { exec, version: debuggerVersion } = await debuggerOf(options);
83
86
  const plan = await planReplay(target, options);
84
87
  const bins = Object.fromEntries(Object.entries(options.bins ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
88
+ const vmSymbols = Object.fromEntries(Object.entries(options.vmSymbols ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
89
+ const scriptNames = Object.fromEntries(Object.entries(options.scriptNames ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
85
90
  const dir = await mkdtemp(join(tmpdir(), "ckb-flame-"));
86
91
  try {
87
92
  const txFile = join(dir, "tx.json");
@@ -115,10 +120,30 @@ export async function flameTransaction(target, options) {
115
120
  const spawned = spawnedScripts(runOut.stdout);
116
121
  const names = bin ? await namesOf(bin) : new Map();
117
122
  const folded = nameAddresses(parseFolded(await options.readFile(out).catch(() => "")), names);
118
- // Flamegraph mode leaves out loading the binary, so result and cycles come
119
- // from plain runs: with the build, and with the deployed binary to compare.
123
+ // A flamegraph run's own total is not the group's: up to ckb-debugger 1.1.1 it
124
+ // leaves out loading the binary, 1.1.2 counts loading but is still a few
125
+ // cycles short (14 on the testtool fixture), and every release leaves out
126
+ // spawned scripts. So result and cycles come from plain runs: with the
127
+ // build, and with the deployed binary to compare.
120
128
  const parsed = runOut.exitCode === null ? parseDebuggerRun(runOut) : parseDebuggerRun(await exec([...base, ...(bin ? ["--bin", bin] : [])]));
121
129
  const deployed = bin ? parseDebuggerRun(await exec(base)) : undefined;
130
+ let children;
131
+ let childrenNote;
132
+ if (spawned && options.children !== false) {
133
+ ({ children, childrenNote } = await profileChildren(runOut.stdout, {
134
+ version: debuggerVersion,
135
+ base: [...base, ...(bin ? ["--bin", bin] : [])],
136
+ out: (vm) => join(dir, `${selector}.vm${vm}.folded`),
137
+ exec,
138
+ mock: plan.mock,
139
+ group: g,
140
+ symbolsOf: (hash) => vmSymbols[hash] ?? bins[hash],
141
+ names: scriptNames,
142
+ readFile: options.readFile,
143
+ readBinary,
144
+ namesOf,
145
+ }));
146
+ }
122
147
  groups.push({
123
148
  selector,
124
149
  ...(g.name && { name: g.name }),
@@ -129,6 +154,8 @@ export async function flameTransaction(target, options) {
129
154
  cycles: parsed.cycles,
130
155
  folded,
131
156
  ...(spawned && { spawned }),
157
+ ...(children?.length && { children }),
158
+ ...(childrenNote && { childrenNote }),
132
159
  ...(bin &&
133
160
  deployed && {
134
161
  bin,