ckb-cycle-tools 1.1.0 → 1.3.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/cli.js CHANGED
@@ -6,7 +6,7 @@ import { diffFailed, diffReports, formatMarkdown, formatText, termLine, termLine
6
6
  import { buildMockTransaction, httpRpc, mockFromTransaction } from "./mock.js";
7
7
  import { flameTree, foldedTotal, formatFolded, functionCosts, renderFlameSvg } from "./flame.js";
8
8
  import { flameTransaction, parseNames, profileTransaction, readTransactionJson } from "./profile.js";
9
- import { PUBLIC_RPC } from "./replay.js";
9
+ import { PUBLIC_RPC, sumLines } from "./replay.js";
10
10
  import { formatReport, runReport } from "./report.js";
11
11
  import { formatScan, scanTestMocks } from "./scan.js";
12
12
  const USAGE = `usage: ckb-cycles <tx-hash> [--mainnet] [--rpc <url>] [--timeout <s>] [--debugger <path>]
@@ -14,8 +14,9 @@ const USAGE = `usage: ckb-cycles <tx-hash> [--mainnet] [--rpc <url>] [--timeout
14
14
  ckb-cycles --file <tx.json> [same options]
15
15
  ckb-cycles report <cycles.json> [--json <out.json>] [--binaries-from <dir>]
16
16
  [--root <dir> ...] [--rpc <url>] [--timeout <s>] [--debugger <path>]
17
+ [--toolchain <text>]
17
18
  ckb-cycles diff <base.json> <head.json> [--markdown] [--fail-above <percent>]
18
- [--fail-on-result-change] [--allow-removed] [--title <s>]
19
+ [--fail-on-result-change] [--allow-removed] [--allow-changed-inputs] [--title <s>]
19
20
  [--base-label <s>] [--head-label <s>]
20
21
  ckb-cycles mock <tx-hash> | --file <tx.json> [-o <mock.json>] [--mainnet] [--rpc <url>]
21
22
  [--timeout <s>]
@@ -38,7 +39,8 @@ the cycles each group cost.
38
39
  repeat for several. Without :<hash-type> it applies to all of them
39
40
 
40
41
  Exit codes: 0 every script accepts (and the sum matches the node's)
41
- 1 a script rejects, or the sum differs from the node's
42
+ 1 a script rejects, the sum differs from the node's, or the sum is
43
+ over the node's per-transaction limit (max_block_cycles)
42
44
  2 usage or environment error: bad arguments, node unreachable,
43
45
  transaction not found, ckb-debugger missing or unreadable output
44
46
 
@@ -55,11 +57,18 @@ Exit codes: 0 every script accepts (and the sum matches the node's)
55
57
  cell dep in any scenario (both also in the JSON's "errors"):
56
58
  a rejection is a result, not an error. A binary missing from
57
59
  --binaries-from is left as the mock has it: only the groups
58
- whose code it is are marked, and not compared
60
+ whose code it is are marked, and not compared.
61
+ The JSON's "manifest" records what the numbers were measured
62
+ with: tool version, ckb-debugger version and the sha256 of its
63
+ binary, the git commit, per scenario the CKB-VM version, a hash
64
+ of its inputs and the swapped-in binaries' hashes. --toolchain
65
+ adds free text to it (e.g. the output of rustc -V)
59
66
  diff compares two reports group by group: Δ cycles, Δ%, and any group
60
67
  whose result changed (ok → exit 12, or back). --fail-above exits 1
61
68
  when a group grows by more than that percentage (a new group
62
69
  has no base, so no percentage: it is never over the threshold),
70
+ or a group that accepted on the base rejects on the head
71
+ (whatever its cycles; also with --fail-on-result-change),
63
72
  --fail-on-result-change when a result changed, including a new
64
73
  group that does not accept, or a group the VM stopped (also
65
74
  over any --fail-above). A scenario the head could not run
@@ -67,7 +76,12 @@ Exit codes: 0 every script accepts (and the sum matches the node's)
67
76
  unchecked: a scenario the base could not run, an error in
68
77
  either report, a base group with nothing in the head to
69
78
  compare with (removed, renamed, moved, or its binary not built
70
- on the base); --allow-removed accepts the last
79
+ on the base); --allow-removed accepts the last. With both
80
+ reports' manifests: a scenario whose inputs (mock, transaction
81
+ file, cycles.json entry) changed is NOT COMPARED, and fails a
82
+ gated diff unless --allow-changed-inputs; another ckb-debugger
83
+ (version or binary) or CKB-VM version fails a gated diff, and
84
+ is a note otherwise. A report without a manifest is a note
71
85
  mock saves a transaction as a ckb-debugger mock transaction, every cell
72
86
  it touches included, so a scenario can replay it with no node
73
87
  scan writes a cycles.json from the mock transactions a test suite wrote
@@ -101,7 +115,7 @@ function table(p) {
101
115
  const line = (cells) => cells.map((c, i) => (i >= 4 ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join(" ");
102
116
  const title = p.nodeCycles === undefined && p.status === "not on chain" ? "tx not on chain" : `tx ${p.hash} (${p.status})`;
103
117
  const out = [title, "", line(head), ...rows.map(line), ""];
104
- out.push(`measured (sum of groups) ${fmt(p.measuredCycles)}`);
118
+ out.push(...sumLines(p, termLine));
105
119
  if (p.nodeCycles !== undefined) {
106
120
  const match = p.nodeCycles === p.measuredCycles;
107
121
  out.push(`reported by node ${fmt(p.nodeCycles)} ${match ? "✓ match" : "✗ MISMATCH"}`);
@@ -138,6 +152,7 @@ async function reportCommand(args) {
138
152
  debugger: { type: "string" },
139
153
  "binaries-from": { type: "string" },
140
154
  root: { type: "string", multiple: true },
155
+ toolchain: { type: "string" },
141
156
  },
142
157
  });
143
158
  if (positionals.length !== 1) {
@@ -150,6 +165,7 @@ async function reportCommand(args) {
150
165
  ...(values.debugger && { debuggerPath: values.debugger }),
151
166
  ...(values["binaries-from"] && { binariesRoot: values["binaries-from"] }),
152
167
  ...(values.root && { roots: values.root }),
168
+ ...(values.toolchain && { toolchain: values.toolchain }),
153
169
  onScenario: (s) => console.error(`${s.error ? "✗" : "·"} ${termLine(s.name)}`),
154
170
  });
155
171
  const { errors, notices, ...data } = report;
@@ -179,6 +195,7 @@ async function diffCommand(args) {
179
195
  "fail-above": { type: "string" },
180
196
  "fail-on-result-change": { type: "boolean" },
181
197
  "allow-removed": { type: "boolean" },
198
+ "allow-changed-inputs": { type: "boolean" },
182
199
  "base-label": { type: "string" },
183
200
  "head-label": { type: "string" },
184
201
  title: { type: "string" },
@@ -197,6 +214,7 @@ async function diffCommand(args) {
197
214
  ...(failAbove !== undefined && { failAbove }),
198
215
  failOnResultChange: values["fail-on-result-change"],
199
216
  allowRemoved: values["allow-removed"],
217
+ allowChangedInputs: values["allow-changed-inputs"],
200
218
  };
201
219
  const diff = diffReports(await readReport(positionals[0]), await readReport(positionals[1]), options);
202
220
  console.log(values.markdown
@@ -331,7 +349,12 @@ async function flameCommand(args) {
331
349
  const costs = functionCosts(g.folded);
332
350
  if (costs.length === 1)
333
351
  out.push(" one frame: the binary has no symbols. Pass an unstripped build with --bin <code-hash>=<elf>");
334
- out.push(` profiled ${fmt(profiled)} cycles (loading the binary is not profiled)`, " SELF TOTAL FUNCTION");
352
+ out.push(` profiled ${fmt(profiled)} cycles (loading the binary is not profiled)`);
353
+ if (g.spawned) {
354
+ const n = g.spawned;
355
+ out.push(` spawned ${n} other script${n === 1 ? "" : "s"}: ${n === 1 ? "its" : "their"} cycles are in the ${fmt(g.cycles)}, not in this profile`, " (ckb-debugger profiles only the spawning script; --bin replaces only its binary)");
356
+ }
357
+ out.push(" SELF TOTAL FUNCTION");
335
358
  for (const c of costs.slice(0, top))
336
359
  out.push(` ${fmt(c.self).padStart(10)} ${fmt(c.total).padStart(10)} ${termLine(c.name)}`);
337
360
  const base = join(dir, g.selector);
@@ -394,7 +417,8 @@ async function main() {
394
417
  console.log(table(p));
395
418
  }
396
419
  const mismatch = p.nodeCycles !== undefined && p.nodeCycles !== p.measuredCycles;
397
- return mismatch || p.groups.some((g) => g.result !== 0) ? 1 : 0;
420
+ // Over the node's per-transaction limit: the node would reject it, so a verdict too.
421
+ return mismatch || p.groups.some((g) => g.result !== 0) || p.overTxLimit !== undefined ? 1 : 0;
398
422
  }
399
423
  // 1 is a verdict (a script rejects, a sum differs, a diff over its thresholds);
400
424
  // anything thrown is the tool not getting that far: 2, so a CI job asserting a
package/dist/diff.d.ts CHANGED
@@ -17,6 +17,61 @@ export interface CycleReport {
17
17
  * fails on these, from either side.
18
18
  */
19
19
  errors?: string[];
20
+ /**
21
+ * What the numbers were measured with (1.3.0 and later). A diff checks the two
22
+ * sides' manifests: changed scenario inputs, another debugger, another CKB-VM.
23
+ */
24
+ manifest?: ReportManifest;
25
+ }
26
+ /**
27
+ * A reproducibility manifest. Every string in it can come from a pull request
28
+ * (a path in its cycles.json, the toolchain its build printed): whatever shows
29
+ * it cleans it as any other report text.
30
+ */
31
+ export interface ReportManifest {
32
+ /** This object's layout. */
33
+ schema: 1;
34
+ /** The package that wrote the report, e.g. `{ name: "ckb-cycle-tools", version: "1.3.0" }`. */
35
+ tool: {
36
+ name: string;
37
+ version: string;
38
+ };
39
+ debugger: {
40
+ /** `--version`, as the report's `debugger`. */
41
+ version: string;
42
+ /** The native binary every scenario ran, and its sha256. */
43
+ path?: string;
44
+ sha256?: string;
45
+ /** For a WebAssembly build: its id (the sha256 of the .wasm). */
46
+ wasm?: string;
47
+ };
48
+ /** The commit checked out where the cycles.json is, and where the binaries came from with --binaries-from. */
49
+ git?: {
50
+ commit?: string;
51
+ binaries?: string;
52
+ };
53
+ /** Free text the caller gave (`--toolchain`): the compiler and build profile, e.g. `rustc -V`. */
54
+ toolchain?: string;
55
+ scenarios: ScenarioManifest[];
56
+ }
57
+ export interface ScenarioManifest {
58
+ name: string;
59
+ /** The CKB-VM version the scenario's `hash_type: "type"` scripts ran on. */
60
+ scriptVersion?: number;
61
+ /**
62
+ * sha256 over what decides what the scenario runs: its cycles.json entry
63
+ * (canonical, without its name or file path) and its mock or transaction file
64
+ * as read. Two reports with the same scenario name and a different hash did
65
+ * not measure the same thing.
66
+ */
67
+ inputs?: string;
68
+ /** The binaries swapped in, as read: the path the config gives, sha256, size in bytes. */
69
+ binaries?: {
70
+ name: string;
71
+ path: string;
72
+ sha256: string;
73
+ size: number;
74
+ }[];
20
75
  }
21
76
  export interface ScenarioResult {
22
77
  name: string;
@@ -38,7 +93,35 @@ export interface ScenarioResult {
38
93
  */
39
94
  binaryMissing?: boolean;
40
95
  missingBinaries?: string[];
96
+ /**
97
+ * Set when some group rejects (added after 1.2.0): the selector of the group the
98
+ * node would stop at, the first failing one in its order (lock groups, then
99
+ * type groups, each by script hash). The node reports no cycles for a
100
+ * rejected transaction, so the groups' cycles, each run on its own, do not
101
+ * add up to anything the node spends.
102
+ */
103
+ nodeStopsAt?: string;
104
+ /**
105
+ * Set only when the groups' cycles add up to more than the node's limit for
106
+ * one transaction (added after 1.3.0): `limit` is the consensus
107
+ * `max_block_cycles` (3,500,000,000 on mainnet and testnet), `sum` the groups'
108
+ * cycles. ckb-debugger gives each group that limit on its own; the node gives
109
+ * it to the whole transaction, so it would reject this one (exceeded max
110
+ * cycles). `nodeStopsAt` names the group where the running sum passes it.
111
+ */
112
+ overTxLimit?: {
113
+ limit: number;
114
+ sum: number;
115
+ };
41
116
  }
117
+ /**
118
+ * A scenario's `overTxLimit`, read defensively (a report file is the PR's):
119
+ * undefined unless both numbers are there and the sum is over the limit.
120
+ */
121
+ export declare function overTxLimitOf(s: ScenarioResult): {
122
+ limit: number;
123
+ sum: number;
124
+ } | undefined;
42
125
  export interface GroupResult {
43
126
  /** ckb-debugger's selector, e.g. `input.0.lock`: the key a group is matched by across reports. */
44
127
  selector: string;
@@ -52,6 +135,14 @@ export interface GroupResult {
52
135
  error?: string;
53
136
  /** Cycles; 0 when the VM stopped the script (`error`), whose count is not a cost. */
54
137
  cycles: number;
138
+ /**
139
+ * Set on every group of a scenario where some group rejects (added after 1.2.0):
140
+ * whether the node would run this group at all. It stops at the first failing
141
+ * group in its order (the scenario's `nodeStopsAt`); every group is still run
142
+ * on its own here, so the ones after it have a result and cycles the node
143
+ * would never produce. Absent when every group accepts: the node runs them all.
144
+ */
145
+ nodeReaches?: boolean;
55
146
  /**
56
147
  * The binary this group's code stands for was not in the checkout (the base):
57
148
  * its numbers are the mock's code, not that build's, so it is not compared.
@@ -64,6 +155,14 @@ export interface GroupResult {
64
155
  functions?: FunctionResult[];
65
156
  /** Why `functions` were not recorded although asked for (the symbols build costs other cycles…). */
66
157
  functionsWarning?: string;
158
+ /**
159
+ * How many scripts this one spawned (CKB2023 `spawn`), seen by the run that
160
+ * recorded `functions`. Their cycles are in `cycles`, but `functions` cover
161
+ * only this script: ckb-debugger profiles the root VM alone.
162
+ */
163
+ spawned?: number;
164
+ /** With `spawned`: the cycles the function profile covers (the root script's own run). */
165
+ profiled?: number;
67
166
  }
68
167
  export interface FunctionResult {
69
168
  name: string;
@@ -113,8 +212,24 @@ export interface DiffRow {
113
212
  functions?: FunctionDelta[];
114
213
  /** The head's reason for not recording functions. */
115
214
  functionsWarning?: string;
116
- /** Why the base side of this group was not compared (its binary was not in the base checkout). */
215
+ /** The head's script spawned this many others, whose cycles no function accounts for. */
216
+ spawned?: number;
217
+ /** With `spawned`: the cycles the head's function profile covers. */
218
+ profiled?: number;
219
+ /** Why the base side of this group was not compared (its binary was not in the base checkout, its inputs changed). */
117
220
  notCompared?: string;
221
+ /** Not compared because the scenario's inputs differ between the two reports' manifests. */
222
+ inputsChanged?: boolean;
223
+ }
224
+ /** One side's manifest, as a comment shows it. */
225
+ export interface ManifestSummary {
226
+ tool?: string;
227
+ debugger?: string;
228
+ debuggerSha256?: string;
229
+ wasm?: string;
230
+ commit?: string;
231
+ binariesCommit?: string;
232
+ toolchain?: string;
118
233
  }
119
234
  export interface CycleDiff {
120
235
  rows: DiffRow[];
@@ -149,6 +264,40 @@ export interface CycleDiff {
149
264
  head: string;
150
265
  };
151
266
  threshold?: number;
267
+ /**
268
+ * Groups not compared because their scenario's inputs (mock, transaction
269
+ * file, cycles.json entry) differ between the manifests. A gated diff fails
270
+ * on them unless `allowChangedInputs`.
271
+ */
272
+ inputsChanged?: number;
273
+ /** The scenarios whose inputs changed. */
274
+ changedScenarios?: string[];
275
+ /**
276
+ * Why the two reports did not run in the same environment, from their
277
+ * manifests: another ckb-debugger (version or binary), another CKB-VM version
278
+ * for a scenario. A gated diff fails on any.
279
+ */
280
+ environment?: string[];
281
+ /** What could not be checked, or differs without failing: a report without a manifest, another toolchain. */
282
+ notes?: string[];
283
+ /** Each side's manifest, short, for the comment. */
284
+ manifests?: {
285
+ base?: ManifestSummary;
286
+ head?: ManifestSummary;
287
+ };
288
+ /**
289
+ * Head scenarios whose groups add up to more than the node's per-transaction
290
+ * limit while the base's did not (`newScenario`: no base scenario ran to
291
+ * compare with). The node would reject them (exceeded max cycles) though every
292
+ * group may accept: a gated diff fails on one the base ran under the limit, as
293
+ * on a group that starts rejecting; `failOnResultChange` on any.
294
+ */
295
+ overTxLimit?: {
296
+ scenario: string;
297
+ limit: number;
298
+ sum: number;
299
+ newScenario?: boolean;
300
+ }[];
152
301
  }
153
302
  export interface DiffOptions {
154
303
  /** Percent. An increase above it is flagged, and makes `failed` true. */
@@ -157,7 +306,11 @@ export interface DiffOptions {
157
306
  failOnResultChange?: boolean;
158
307
  /** Removed, renamed or uncompared base groups do not fail a gated diff. */
159
308
  allowRemoved?: boolean;
309
+ /** Scenarios whose inputs changed (manifest hashes differ) do not fail a gated diff; still not compared. */
310
+ allowChangedInputs?: boolean;
160
311
  }
312
+ /** The note on a group whose scenario's inputs differ between base and head. */
313
+ export declare const INPUTS_CHANGED = "inputs changed: the scenario's mock, transaction file or cycles.json entry differs from the base's";
161
314
  /** The message for a binary no scenario's cell deps match, in a report's `errors` and the diff. */
162
315
  export declare const unmatchedError: (name: string) => string;
163
316
  /**
@@ -180,7 +333,16 @@ export declare function functionDeltas(base: FunctionResult[] | undefined, head:
180
333
  * run, an error in either report, and a base group with nothing to compare
181
334
  * against (removed, renamed, moved, or measured without its binary) unless
182
335
  * `allowRemoved`. A head group the VM stopped is a result change, and over any
183
- * `failAbove` threshold.
336
+ * `failAbove` threshold. With a gate set, a group that accepted on the base and
337
+ * rejects on the head (`ok` → `exit N` or a VM error) always fails, whatever its
338
+ * cycles: a cheaper rejection is not a saving. `failOnResultChange` fails on any
339
+ * result change besides (reject → accept, one exit code or VM error to another,
340
+ * a new group that does not accept). A new group has no base that accepted, so
341
+ * this rule leaves it alone: with `failAbove` alone it fails only as before (a
342
+ * new group the VM stopped is over the threshold). A scenario whose groups add
343
+ * up to more than the node's per-transaction limit on the head, and not on the
344
+ * base, counts as a group that starts rejecting (the node would reject it); a
345
+ * new scenario over the limit, as a new group that does not accept.
184
346
  */
185
347
  export declare function diffFailed(diff: CycleDiff, options?: DiffOptions): boolean;
186
348
  /**
@@ -200,6 +362,14 @@ export declare const termLine: (s: string) => string;
200
362
  export declare const termLines: (s: string) => string;
201
363
  /** How many changed functions a comment lists per group. */
202
364
  export declare const FUNCTIONS_SHOWN = 10;
365
+ /** What a function list leaves out when the script spawned others: their cycles. */
366
+ export declare function spawnNote(r: {
367
+ spawned?: number;
368
+ profiled?: number;
369
+ head?: {
370
+ cycles?: number;
371
+ };
372
+ }): string;
203
373
  /** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */
204
374
  export declare const COMMENT_MARKER = "<!-- ckb-cycles-report -->";
205
375
  export interface MarkdownOptions {
@@ -214,5 +384,10 @@ export interface MarkdownOptions {
214
384
  * reverse) matters more than any cycle count.
215
385
  */
216
386
  export declare function formatMarkdown(diff: CycleDiff, options?: MarkdownOptions): string;
387
+ /**
388
+ * One line per side that has a manifest: tool, debugger (and its binary's
389
+ * hash), commit, toolchain. Plain text: the caller cleans it (md or termLine).
390
+ */
391
+ export declare function manifestLines(diff: CycleDiff): string[];
217
392
  /** The same table for a terminal. */
218
393
  export declare function formatText(diff: CycleDiff): string;