ckb-cycle-tools 1.3.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/CHANGELOG.md CHANGED
@@ -1,331 +1,416 @@
1
- # Changelog
2
-
3
- This project follows [semantic versioning](https://semver.org/).
4
-
5
- ## 1.3.0 (2026-11-07)
6
-
7
- From the review on #46 (5 Nov): failed gates on a script that starts rejecting,
8
- a reproducibility manifest, and what a rejected transaction's numbers mean.
9
-
10
- ### Changed
11
- - `diff --fail-above` (and the Action's `fail-above`) now also fails when a
12
- group that accepted on the base rejects on the head (`ok` → `exit N` or a VM
13
- error), whatever its cycles: a script that starts rejecting what it accepted
14
- could pass before, by getting cheaper. This affects workflows that set only
15
- `fail-above`: a pull request that turns an accepting scenario into a
16
- rejection now fails the check (a warning with `informational: true`).
17
- `--fail-on-result-change` is unchanged and still broader (reject → accept,
18
- one exit code to another, a new group that does not accept); a diff with
19
- neither set stays informational. The comment marks such a row "accepted on
20
- the base, rejects now".
21
- - A gated diff (`--fail-above` or `--fail-on-result-change`) now also fails
22
- when a scenario's inputs changed between base and head (unless
23
- `--allow-changed-inputs`), or when the two sides ran another ckb-debugger or
24
- CKB-VM version. Before, an edited mock under the same scenario name was
25
- compared silently. Ungated diffs only gain notes. See Added.
26
- - A gated diff also fails when a head scenario's groups add up to more than
27
- the node's per-transaction cycle limit and the base's did not: the node would
28
- reject it, as if a group started rejecting (see Added). A new scenario over
29
- the limit fails `--fail-on-result-change` only. The CLI exits 1 for such a
30
- transaction.
31
-
32
- ### Added
33
- - `report` writes a `manifest` into its JSON: the ckb-cycle-tools version,
34
- ckb-debugger's `--version` and the sha256 (and path) of the binary every
35
- scenario ran (resolved once), or a WebAssembly build's id for a library
36
- caller that runs one (`debuggerBuild`), the git commit of the config's
37
- checkout and of `--binaries-from` (none, and no failure, outside git), an
38
- optional `--toolchain <text>`, and per scenario the CKB-VM version, an
39
- `inputs` sha256 (the mock or transaction file's bytes as read, and the
40
- cycles.json entry canonicalised without its name, file path or `functions`)
41
- and each swapped-in binary's path, sha256 and size. The terminal report
42
- ends with a manifest line.
43
- - `diff` reads both manifests. A scenario whose `inputs` differ is NOT
44
- COMPARED (its groups count as neither new nor removed); a gated diff fails
45
- on it unless `--allow-changed-inputs`. Another ckb-debugger (version, binary,
46
- native against WebAssembly) or another CKB-VM version for a scenario fails a
47
- gated diff, listed under the summary; ungated it is a bold note. Another
48
- toolchain is a note. A report without a manifest on one side is a note,
49
- never a failure; two such reports diff as before. The comment and the
50
- terminal output show each side's manifest in one line. Manifest strings go
51
- through the same cleaning as other report text.
52
- - Action inputs `toolchain` (a command run after the build in each checkout;
53
- its output goes to `--toolchain`) and `allow-changed-inputs`.
54
- - A rejected transaction (some group exits non-zero, the VM stops it, or Type
55
- ID refuses it) no longer shows "measured (sum of groups)". The CLI prints
56
- "sum of groups, each run on its own", names the group the node would stop
57
- at, says the node reports no cycles for a rejected transaction, and lists the
58
- groups the node would never run. The order is ckb-script's, read from its
59
- source (`TransactionScriptsVerifier::verify` and `TxData`/`TxInfo::groups`
60
- at ckb a4aa128): lock groups, then type groups, each by script hash,
61
- stopping at the first failure.
62
- - JSON, added fields only: a profile (`--json`, `profileTransaction`) and a
63
- report scenario get `nodeStopsAt` (that group's selector), and each group
64
- `nodeReaches: true | false`. Both are only set when some group rejects, so
65
- reports of accepted transactions are byte-for-byte as before. `report`'s text
66
- output says the same under a rejected scenario. `diff` and its gates are
67
- unchanged.
68
- - The node's cycle limit is per transaction (`max_block_cycles`, 3,500,000,000
69
- on mainnet and testnet: each group gets what the ones before it left), while
70
- ckb-debugger gives each group 3,500,000,000 on its own. A transaction whose
71
- groups each fit but together pass the limit was shown as accepted; it is now
72
- flagged: "over the node's per-transaction limit of 3,500,000,000 cycles: the
73
- node would reject this transaction (exceeded max cycles)", in the CLI table,
74
- the `report` text and the `diff` summary and comment. The limit is the
75
- node's `get_consensus` `max_block_cycles` when the replay asked the node,
76
- else 3,500,000,000 (`txCycleLimit` in the options to override;
77
- `DEFAULT_TX_CYCLE_LIMIT` exported). `nodeStopsAt` and `nodeReaches` then mark
78
- the group at which the running sum, in the node's order, passes the limit,
79
- unless a failing group comes first. JSON, added fields only, and only in
80
- that case: `overTxLimit: { limit, sum }` on a profile (bigints as strings,
81
- as `measuredCycles`) and on a report scenario (numbers), and in a diff, the
82
- head scenarios newly over it. Transactions under the limit are unchanged.
83
- - `nodeOrder`, `nodeStop` and `sumLines` exported from the package and from
84
- `ckb-cycle-tools/replay` (no Node built-ins).
85
-
86
- ### Docs
87
- - compat/HARDFORK.md, from the review on #46 (point 1): 24 real mainnet and
88
- testnet transactions next to Mirana (VM v1) and Meepo (VM v2), the nearest
89
- of each kind (secp only; another `type` script; a data/data1/data2 script)
90
- on each side of each fork, replayed as `ckb-cycles <hash>` replays them and
91
- again with `--script-version` forced to the two other values. The 18 after
92
- Mirana match the cycles a node recorded for their block exactly, at the
93
- chosen version only, and data/data1/data2 groups keep their own version.
94
- Before Mirana no public node has cycles (mainnet.ckb.dev reports `0x0`
95
- everywhere here; mainnet/testnet.ckbapp.dev record from the Mirana block on),
96
- and the explorer's number for those 6 equals the v1 sum, not the v0 sum the
97
- consensus rules give: reported as unverified, with how to settle it. Also why
98
- `estimate_cycles` is no oracle for a historical transaction (spent inputs do
99
- not resolve; it would run today's VM).
100
- - `npm run hardfork` (scripts/hardfork-check.ts, `--discover` to pick the
101
- transactions again) writes compat/hardfork.json, the table and
102
- test/fixtures/hardfork-mocks.json.br. test/hardfork.test.ts replays the
103
- recorded mocks offline with the WebAssembly debugger at every version, and
104
- with `CKB_HARDFORK_NETWORK=1` plans them again through the public nodes.
105
- No change to the replay itself.
106
- - README: "What a rejected transaction's numbers mean", and "What comes from
107
- where when replaying": a table of every input to a replay (cells, cell deps
108
- and dep groups, input headers, header deps, consensus epochs, CKB-VM version,
109
- max cycles, group order, Type ID, since/capacity checks) and whether it comes
110
- from the chain via RPC, the node's current state or ckb-debugger's defaults;
111
- ckb-debugger's limit is per group, the node's per transaction.
112
- - README: "Flamegraph fidelity": totals are exact, the split between functions
113
- is attributed (frames open only at symbol-table function starts, so inlined
114
- code is charged to its caller; cycles charged outside instructions are in no
115
- frame). The flame example now says the 1,812-cycle gap is everything charged
116
- outside instructions, not only loading the binary.
117
- - benchmarks/session-lock/RESULTS.md (and compare.mjs, which writes it): the
118
- comparison is of these two implementations only, and the Rust lock's build
119
- profile at 49227cd (`opt-level = "s"`, LTO, one codegen unit, `panic = "abort"`,
120
- overflow checks, stripped; `+zba,+zbb,+zbc,+zbs,-a`; ckb-std 1.1.0; no pinned
121
- toolchain).
122
-
123
- ## 1.2.0 (2026-11-05)
124
-
125
- Scripts that spawn other scripts (CKB2023 `spawn`).
126
-
127
- ### Added
128
- - `flame`, and `report` with `functions`, say when a script spawned others:
129
- ckb-debugger profiles only the spawning script, so the spawned scripts'
130
- cycles are in the group's total but in none of its functions. The report
131
- records `spawned` and `profiled` per group; `diff` notes it under the
132
- group, and for a group whose cycles changed while none of its own
133
- functions did, says that the change is in what it spawned.
134
- - A warning when a swapped-in binary's old code hash is still in a cell's
135
- data (a match cell naming the game it spawns by data hash): data is not
136
- rewritten, so that script would not find the new build.
137
- - `test/fixtures/spawn-project`: a parent lock that spawns a child found by
138
- data2 hash, with mocks, and tests against ckb-debugger 1.1.1.
139
- - Action: pull requests from forks, whose token cannot comment. `action/comment`
140
- runs in a `workflow_run` workflow: it finds the pull request from the run's
141
- head commit through the API (never from the artifact), posts only while the
142
- PR is still at that commit, and checks the downloaded report first (at most
143
- `max-bytes` (256 KiB), the marker on its first line, no NUL bytes; @mentions and #refs
144
- broken). The two workflows are in `action/README.md`.
145
- - Action input `informational`: a crossed threshold or a scenario that could
146
- not run is a warning, not a failed job.
147
- - Action input `base-config: head`: the base is measured with the PR's
148
- cycles.json and the base checkout's binaries (`--binaries-from`), for a
149
- cycles.json generated before the Action (`ckb-cycles scan`). With the
150
- default, the base checkout has no such file and every group was new.
151
-
152
- ### Fixed
153
- - `profiledCycles` reads the last `All cycles:` line: for a spawning script,
154
- flamegraph mode prints the whole group's total first.
155
-
156
- ## 1.1.0 (2026-10-30)
157
-
158
- Cycle reports from ckb-testtool tests, and a check across ckb-debugger releases.
159
-
160
- ### Security
161
- - Every mock transaction is checked before it is written for ckb-debugger
162
- (native and WebAssembly; plain replay, `--file`, `report`, `flame`, `scan`
163
- scenarios, mocks built from a node): a string containing `{{` anywhere in it,
164
- or a field that should be hex and is not, is refused with an error that names
165
- the field. ckb-debugger expands `{{ data <path> }}`, `{{ hash <path> }}`,
166
- `{{ def_type … }}` and `{{ ref_type … }}` in a tx file, so a pull request's
167
- mock could embed any file on the runner, past `--root`.
168
- `checkMockTransaction` is exported from `.` and `./replay`.
169
- - `report --root` ignores the config's `"rpc"` and says so in a warning: a pull
170
- request's cycles.json no longer chooses the host the runner sends requests to.
171
- `--rpc` still applies; otherwise the public node is asked.
172
- - Names from a cycles.json, a build or a node (scenario, script, binary and
173
- function names, warnings) are printed to the terminal and the CI log on one
174
- line, without control or bidi characters, and never with `::` at the start
175
- of a line (errors keep their lines, each cleaned the same way), so a name
176
- cannot forge a GitHub Actions workflow command or drive the terminal:
177
- `report`, `diff`, `flame`, `scan` and plain replay.
178
- - GitHub Action: the PR's `build` runs in the same job as the sticky-comment
179
- step, which gets `github-token`, and could take that token by writing its own
180
- `gh` to `$GITHUB_PATH`, or BASH_ENV, PATH and the like to `$GITHUB_ENV`. `gh`
181
- is now located before the build runs; the comment step runs `/bin/bash -p`
182
- (not the `bash` on PATH; no BASH_ENV, ENV or exported functions), sets PATH
183
- itself, blanks LD_PRELOAD and the like, and runs `gh` with only the variables
184
- it needs (the proxies and CA settings as they were before the build) and an
185
- empty config directory. The comment file is read from the runner's temp
186
- directory, never from a step output, and must be a regular file. This does
187
- not stop a build that leaves a process running or replaces files on the
188
- runner; the Action's README says so and shows a two-job setup for PRs you do
189
- not trust with the token.
190
- - GitHub Action: `action/comment`, the sticky-comment step on its own, for that
191
- second job: it posts a markdown file downloaded from the first job, with a
192
- token the PR's build never shares a runner with. The first job runs the
193
- Action with `comment: false` and a read-only token.
194
- - GitHub Action: the comment's markdown is written only when the diff ran, so a
195
- second job never posts a failed diff's output; the base commit is fetched only
196
- when the checkout does not have it (a private repository checked out with
197
- `persist-credentials: false` and `fetch-depth: 0` then needs no credentials).
198
- - The README examples and this repository's cycle-report workflow check out
199
- with `persist-credentials: false`, so no token is left in `.git/config` for
200
- the PR's build, and the Action's README no longer says the build cannot get a
201
- write token. GitHub-owned actions in this repository's workflows and the
202
- README examples are pinned to commit SHAs, with the release as a comment.
203
- - Web inspector: every page is served with `Content-Security-Policy:
204
- frame-ancestors 'none'`, `X-Frame-Options: DENY`, `X-Content-Type-Options:
205
- nosniff` and `Referrer-Policy: strict-origin-when-cross-origin`, and without
206
- `X-Powered-By`, so no other site can frame it.
207
-
208
- ### Fixed (audit, 31 Oct)
209
- Each of these could give a gated check the wrong verdict.
210
- - A binary missing from `--binaries-from` (a contract the PR adds) made every
211
- scenario offered it a base error with no groups, so nothing in those
212
- scenarios was compared, the other binaries' groups included. The scenario now
213
- runs with the binaries that exist, the missing one left as the mock has it;
214
- only the groups whose code it is are not compared (`missingBinary` on the
215
- group, `missingBinaries` on the scenario), and a gated diff fails on them
216
- unless `--allow-removed`.
217
- - A binary offered to a scenario that matches none of its cell deps (a mock
218
- dumped from an older build) was measured as the mock's old code on both
219
- sides and shown unchanged, with nothing said. It is now a warning on that
220
- scenario, listed in the comment. A binary that matches no cell dep in any
221
- scenario was a report error that only reached the log: `report` now writes
222
- its errors into the JSON (`"errors"`), and a gated diff fails when either
223
- report has any, so the Action's `|| true` no longer hides them.
224
- - A group the VM stopped (past the cycle limit) was recorded with 0 cycles and
225
- read as a -100% saving, passing `--fail-above`. The cycles of a stopped run
226
- are never used now; with `--fail-above` such a group is over the threshold,
227
- and a result change for `--fail-on-result-change`. A result names the VM
228
- error's kind (`error: invalid instruction`, `error: cycles error: max cycles
229
- exceeded`), so one VM error turning into another is a result change.
230
- - GitHub Action: the base report ran the PR's cycles.json, so a scenario the PR
231
- deleted was never measured or listed. The base is now measured with the base
232
- commit's own cycles.json, mocks and binaries (an empty report when the base
233
- has none); the head still runs the PR's.
234
- - A base group with nothing in the head to compare against (a scenario or group
235
- removed, renamed, or moved to another selector) passed both gates. A gated
236
- diff now fails on it unless `--allow-removed` (Action input `allow-removed`,
237
- default false). The summary counts such groups and new groups.
238
- - Two reports from different ckb-debugger versions were compared without a
239
- word: the summary now names both versions.
240
-
241
- ### CLI: `ckb-cycles`
242
- - `scan <mocks-dir>`: writes a cycles.json from the mock transactions a test
243
- suite wrote, one scenario per file, with each freshly built binary in
244
- `--binaries` (default `build/release`) mapped by its data hash and
245
- `<name>.debug` as its symbols build; `--functions` records each group's
246
- costliest functions.
247
- - Functions the profiler could not name from line info (`func_0x<address>`:
248
- ckb-std's `_start`, rustc's allocator shims) are named from the symbols
249
- build's ELF symbol table, so they no longer show in a diff as one address
250
- removed and another added when code moves.
251
- - ELF names skip absolute symbols, labels outside executable sections and
252
- linker section markers (`__text_start`, `_etext`), so a marker at `_start`'s
253
- address no longer renames the root frame.
254
- - Legacy Rust symbol names are demangled in full (`$RF$`, `$LP$`, `$u7b$` and
255
- the other escapes), so they read as `rustc-demangle` prints them.
256
-
257
- ### ckb-testtool integration
258
- - `integrations/ckb-testtool`: a Rust crate whose `verify_tx` writes each
259
- ckb-testtool transaction as a mock when `CKB_CYCLES_MOCKS` is set, for
260
- ckb-script-templates projects; with `scan`, `make cycles` reports every
261
- test's script groups. Checked in CI on a project generated from
262
- ckb-script-templates, two contracts, a change, a diff.
263
- - README: the Makefile target uses `npx -p ckb-cycle-tools ckb-cycles` (a bare
264
- `npx ckb-cycles` names a package that does not exist) and `cargo test -p tests`.
265
- Every other `npx` line in the READMEs and the demo page now names the package
266
- the same way.
267
-
268
- ### Library
269
- - `scanTestMocks`, `configFromMocks` and `formatScan` (and their types) from `.`.
270
- - `flameTransaction` reads and parses each symbols build once, not once per
271
- script group that runs it.
272
- - `flameTransaction` takes `readBinary` beside `readFile`, so a caller whose
273
- debugger sees another file system gets frame names from the builds there
274
- too; it defaults to node:fs, as before.
275
-
276
- ### GitHub Action
277
- - When the sticky comment exists but updating it fails, the step retries the
278
- update (three tries) and then warns; it no longer posts a second report
279
- comment beside the first.
280
- - When the pull request's comments cannot be listed, the step warns and posts
281
- nothing (the report is in the job summary), since it cannot tell whether its
282
- comment already exists.
283
-
284
- ### Compatibility across ckb-debugger releases
285
- - `npm run compat` (repository only): replays 35 frozen scenarios under every
286
- ckb-debugger release from 0.121.0 to 1.1.1, native and WebAssembly, compares
287
- each script group with 1.1.1, and writes compat/RESULTS.md; a weekly Linux CI
288
- job runs it. A scenario the reference debugger could not run counts as a
289
- mismatch, and two scenario ids that slug alike no longer replay the same
290
- transaction.
291
-
292
- ## 1.0.0 (2026-10-27)
293
-
294
- First stable release.
295
-
296
- ### CLI: `ckb-cycles`
297
- - Replays a transaction per script group in ckb-debugger; the sum matches the node's
298
- total. Resolves the real ckb-debugger past the Windows `.cmd` shim.
299
- - Failure-path profiling: `--file` profiles a transaction that is not on chain.
300
- - Right VM version per script, from the node's hardfork epochs; input headers are
301
- replayed, so header-reading scripts (Nervos DAO) match.
302
- - Only complete ckb-debugger result lines are trusted, cross-checked with its exit code.
303
- - `report`, `diff` and `mock` subcommands; swap a cell dep's binary for a fresh build
304
- before replaying; name your own scripts with `--name`.
305
- - `flame`: per-group flamegraphs from ckb-debugger's profiler (SVG + folded
306
- stacks, costliest functions printed); `--bin` swaps in an unstripped build and
307
- checks its cycles against the deployed binary's.
308
- - Exit codes: 0 every script accepts and the sum matches the node; 1 a script
309
- rejects or the sum differs; 2 a usage or environment error.
310
-
311
- ### Library
312
- - `.` (analysis), `./analyze`, `./replay` and `./flame` (pure, work in the browser), `./wasm`
313
- (ckb-debugger's WebAssembly build, in memory, same numbers as native).
314
-
315
- ### GitHub Action
316
- - `action/`: posts one sticky cycle report on a pull request, group by group against
317
- the base branch; checksums the ckb-debugger it installs; fails on a broken base.
318
- - Function-level costs in the report: a binary's `symbols` build and `"functions": true`
319
- in cycles.json record each group's costliest functions (checked against the binary's
320
- cycles), and the comment folds in which functions changed.
321
- - Hardened for untrusted pull requests: `report --root` keeps the files a PR's
322
- cycles.json names inside the checkout; names in the comment cannot mention,
323
- link or break the table; the comment always fits GitHub's size limit.
324
-
325
- ### Web inspector
326
- - ckb-cycle-tools.vercel.app: paste a transaction hash, see its scripts and the
327
- per-group cycles computed in the page.
328
-
329
- ### Benchmark
330
- - The session lock in Rust vs ckb-js-vm, rebuilt and rerun in CI: the current lock
331
- (ckb-session-kit 49227cd, plain CKB and token sessions, codes 10-20), 58 scenarios.
1
+ # Changelog
2
+
3
+ This project follows [semantic versioning](https://semver.org/).
4
+
5
+ ## 1.4.0 (2026-11-18)
6
+
7
+ ### Added
8
+ - Per-child profiles of a script that spawns others (ckb-debugger 1.1.2 or
9
+ later). For a group whose script spawned, `flame` and `report` (with
10
+ `functions`) read the spawn tree from the flamegraph run, find each spawned
11
+ VM's binary in the transaction by its data hash, and replay that VM alone
12
+ (`--vm-id N`, `--vm-symbols` with the matching unstripped build, used only
13
+ when its code is the code the VM ran). `flame` prints each spawned script's
14
+ profiled cycles and costliest functions under its group and writes
15
+ `<selector>.vm<N>.svg` and `.folded`. The group total from the plain run
16
+ stays the source of truth; a child's numbers are its profiled frames (on the
17
+ spawn fixture, heavy: group 761,957, parent frames 14,974, child frames
18
+ 635,605, `spawn_child::child_work` 606,720 self). With an older debugger, or
19
+ a replay that fails, the output is as before plus a note. At most 16 spawned
20
+ VMs per group; a VM that runs `exec` is replayed with its first program.
21
+ - Report JSON: a spawning group may carry `children` (per spawned VM: `vm`,
22
+ `parent`, `script`, `codeHash`, `result`, `error`, `profiled`, `functions`,
23
+ `functionsWarning`, `failed`) and `childrenNote`. Additive: the report stays
24
+ `version: 1`, and older readers ignore the fields. `diff` matches children by
25
+ VM id and says which spawned script changed, in the terminal and in a
26
+ "Spawned scripts" block of the PR comment (dropped with the function blocks
27
+ when the comment would be too long). A base report without children shows
28
+ the head's children without a change.
29
+ - Library: `FlameChild`, `MAX_CHILD_PROFILES`, `flameTransaction`'s
30
+ `vmSymbols` and `children` options; `spawnTree`, `profilesChildren`,
31
+ `CHILD_PROFILE_DEBUGGER` (also in `ckb-cycle-tools/flame`); `spawnedBinary`,
32
+ `resolvedCellDeps`; `childDeltas`, `childResult`, `CHILDREN_FOOTNOTE`;
33
+ types `ChildResult`, `ChildDelta`, `SpawnedVm`, `SpawnedBinary`.
34
+ - Web page: a group whose script spawns others is split by script, as `flame`
35
+ does. After the per-group replay, each group gets one profiled run; under a
36
+ spawning group's row the page lists the spawning script's own frames (vm 0)
37
+ and each spawned VM (its locator and code hash, exit code, and its own
38
+ frames from a `--vm-id` replay), says these sit inside the group's total
39
+ (loading and the spawn are in no frame), and gives the CLI's note on a
40
+ spawned server that ends non-zero after its group verified. At most 16
41
+ spawned VMs per group; a failed replay leaves the group row as it is. On the
42
+ Crowns race `0x2502c0b4…`: group 123,718,667, vm 0 7,993,759, vm 1
43
+ 115,556,444 (exit -1), the same as the CLI.
44
+ - Library: `ckb-cycle-tools/children` (no Node built-ins): `profileSpawns`,
45
+ `profileChildren`, `serverExit`, `olderDebuggerNote`, and `SERVER_EXIT_NOTE`
46
+ and `MAX_CHILD_PROFILES` (both still exported where they were); `wasmFiles`
47
+ in `ckb-cycle-tools/wasm`. `runWasmDebugger` now returns the files a run
48
+ wrote (`files`).
49
+ - ckb-debugger 1.1.2 (released 16 Nov 2026) in the check across releases
50
+ (`compat/debuggers.json`, native and WebAssembly, sha256 as the release
51
+ publishes it). Every script group gives 1.1.1's cycles and exit code, and the
52
+ node's total where it has one: 525 scenario runs, 1,350 groups, no mismatch.
53
+
54
+ ### Changed
55
+ - The web page runs ckb-debugger 1.1.2's WebAssembly build (was 0.200.1, from
56
+ `ckb-testtool`): `demo/scripts/copy-wasm.mjs` downloads the release asset
57
+ `ckb-debugger_v1.1.2_wasm32-wasip1.tar.gz`, checks it against the sha256 in
58
+ `compat/debuggers.json` and the wasm in it against a pinned sha256, and
59
+ stops the build on any mismatch. Per-group cycles are unchanged: the page's
60
+ three examples, a 2023 VM v1 transaction and the Crowns race give the same
61
+ cycles per group, and the node's total, on both builds.
62
+ - The Action installs ckb-debugger v1.1.2 by default (was v1.1.1), and CI and
63
+ the cross-version check's reference use 1.1.2. Group cycles are the same as
64
+ with 1.1.1 (see Added), but a report's manifest names the new version, so a
65
+ gated `diff` against a report saved with 1.1.1 fails as run under another
66
+ debugger (since 1.3.0); within one Action run both sides use the same. The
67
+ Action still knows v1.1.1's checksum, so `ckb-debugger-version: v1.1.1` works
68
+ without `ckb-debugger-sha256`.
69
+
70
+ ### Fixed
71
+ - A function keeps its name whichever ckb-debugger profiled it. Newer
72
+ ckb-debugger and ckb-vm-pprof write a `;` inside a frame name (`[u8; 32]`) as
73
+ U+037E, which looks the same (ckb-standalone-debugger#211, #212); frames,
74
+ function costs, report JSON and SVGs now read it back as `;`, and `diff`
75
+ does the same for function names in a saved report, so a base and a head
76
+ profiled with different debuggers show a change, not a rename.
77
+
78
+ ### Documentation
79
+ - `compat/notes.md`: what 1.1.2 changes in `--mode full`. Its `All cycles` line
80
+ now counts loading the program (ckb-standalone-debugger#209), which no frame
81
+ holds; the folded stacks are byte for byte the same as 1.1.1's, so `flame`
82
+ and `report`'s `profiled` do not change. The exported `profiledCycles()`
83
+ reads that line, so it returns more with 1.1.2 (18,801 against 14,974 on the
84
+ spawn fixture); its doc comment says so. Also: full mode now analyses the
85
+ `--vm-id` VM's own ELF (#210), and the `--vm-id` replay of a spawned script
86
+ that calls `inherited_fds` now runs (it exited 3 with 1.1.1).
87
+ - README: the milestone table ends at 1.3.0 with dates, and the cross-version
88
+ section gives the 17 Nov run.
89
+
90
+ ## 1.3.0 (2026-11-07)
91
+
92
+ From the review on #46 (5 Nov): failed gates on a script that starts rejecting,
93
+ a reproducibility manifest, and what a rejected transaction's numbers mean.
94
+
95
+ ### Changed
96
+ - `diff --fail-above` (and the Action's `fail-above`) now also fails when a
97
+ group that accepted on the base rejects on the head (`ok` → `exit N` or a VM
98
+ error), whatever its cycles: a script that starts rejecting what it accepted
99
+ could pass before, by getting cheaper. This affects workflows that set only
100
+ `fail-above`: a pull request that turns an accepting scenario into a
101
+ rejection now fails the check (a warning with `informational: true`).
102
+ `--fail-on-result-change` is unchanged and still broader (reject → accept,
103
+ one exit code to another, a new group that does not accept); a diff with
104
+ neither set stays informational. The comment marks such a row "accepted on
105
+ the base, rejects now".
106
+ - A gated diff (`--fail-above` or `--fail-on-result-change`) now also fails
107
+ when a scenario's inputs changed between base and head (unless
108
+ `--allow-changed-inputs`), or when the two sides ran another ckb-debugger or
109
+ CKB-VM version. Before, an edited mock under the same scenario name was
110
+ compared silently. Ungated diffs only gain notes. See Added.
111
+ - A gated diff also fails when a head scenario's groups add up to more than
112
+ the node's per-transaction cycle limit and the base's did not: the node would
113
+ reject it, as if a group started rejecting (see Added). A new scenario over
114
+ the limit fails `--fail-on-result-change` only. The CLI exits 1 for such a
115
+ transaction.
116
+
117
+ ### Added
118
+ - `report` writes a `manifest` into its JSON: the ckb-cycle-tools version,
119
+ ckb-debugger's `--version` and the sha256 (and path) of the binary every
120
+ scenario ran (resolved once), or a WebAssembly build's id for a library
121
+ caller that runs one (`debuggerBuild`), the git commit of the config's
122
+ checkout and of `--binaries-from` (none, and no failure, outside git), an
123
+ optional `--toolchain <text>`, and per scenario the CKB-VM version, an
124
+ `inputs` sha256 (the mock or transaction file's bytes as read, and the
125
+ cycles.json entry canonicalised without its name, file path or `functions`)
126
+ and each swapped-in binary's path, sha256 and size. The terminal report
127
+ ends with a manifest line.
128
+ - `diff` reads both manifests. A scenario whose `inputs` differ is NOT
129
+ COMPARED (its groups count as neither new nor removed); a gated diff fails
130
+ on it unless `--allow-changed-inputs`. Another ckb-debugger (version, binary,
131
+ native against WebAssembly) or another CKB-VM version for a scenario fails a
132
+ gated diff, listed under the summary; ungated it is a bold note. Another
133
+ toolchain is a note. A report without a manifest on one side is a note,
134
+ never a failure; two such reports diff as before. The comment and the
135
+ terminal output show each side's manifest in one line. Manifest strings go
136
+ through the same cleaning as other report text.
137
+ - Action inputs `toolchain` (a command run after the build in each checkout;
138
+ its output goes to `--toolchain`) and `allow-changed-inputs`.
139
+ - A rejected transaction (some group exits non-zero, the VM stops it, or Type
140
+ ID refuses it) no longer shows "measured (sum of groups)". The CLI prints
141
+ "sum of groups, each run on its own", names the group the node would stop
142
+ at, says the node reports no cycles for a rejected transaction, and lists the
143
+ groups the node would never run. The order is ckb-script's, read from its
144
+ source (`TransactionScriptsVerifier::verify` and `TxData`/`TxInfo::groups`
145
+ at ckb a4aa128): lock groups, then type groups, each by script hash,
146
+ stopping at the first failure.
147
+ - JSON, added fields only: a profile (`--json`, `profileTransaction`) and a
148
+ report scenario get `nodeStopsAt` (that group's selector), and each group
149
+ `nodeReaches: true | false`. Both are only set when some group rejects, so
150
+ reports of accepted transactions are byte-for-byte as before. `report`'s text
151
+ output says the same under a rejected scenario. `diff` and its gates are
152
+ unchanged.
153
+ - The node's cycle limit is per transaction (`max_block_cycles`, 3,500,000,000
154
+ on mainnet and testnet: each group gets what the ones before it left), while
155
+ ckb-debugger gives each group 3,500,000,000 on its own. A transaction whose
156
+ groups each fit but together pass the limit was shown as accepted; it is now
157
+ flagged: "over the node's per-transaction limit of 3,500,000,000 cycles: the
158
+ node would reject this transaction (exceeded max cycles)", in the CLI table,
159
+ the `report` text and the `diff` summary and comment. The limit is the
160
+ node's `get_consensus` `max_block_cycles` when the replay asked the node,
161
+ else 3,500,000,000 (`txCycleLimit` in the options to override;
162
+ `DEFAULT_TX_CYCLE_LIMIT` exported). `nodeStopsAt` and `nodeReaches` then mark
163
+ the group at which the running sum, in the node's order, passes the limit,
164
+ unless a failing group comes first. JSON, added fields only, and only in
165
+ that case: `overTxLimit: { limit, sum }` on a profile (bigints as strings,
166
+ as `measuredCycles`) and on a report scenario (numbers), and in a diff, the
167
+ head scenarios newly over it. Transactions under the limit are unchanged.
168
+ - `nodeOrder`, `nodeStop` and `sumLines` exported from the package and from
169
+ `ckb-cycle-tools/replay` (no Node built-ins).
170
+
171
+ ### Docs
172
+ - compat/HARDFORK.md, from the review on #46 (point 1): 24 real mainnet and
173
+ testnet transactions next to Mirana (VM v1) and Meepo (VM v2), the nearest
174
+ of each kind (secp only; another `type` script; a data/data1/data2 script)
175
+ on each side of each fork, replayed as `ckb-cycles <hash>` replays them and
176
+ again with `--script-version` forced to the two other values. The 18 after
177
+ Mirana match the cycles a node recorded for their block exactly, at the
178
+ chosen version only, and data/data1/data2 groups keep their own version.
179
+ Before Mirana no public node has cycles (mainnet.ckb.dev reports `0x0`
180
+ everywhere here; mainnet/testnet.ckbapp.dev record from the Mirana block on),
181
+ and the explorer's number for those 6 equals the v1 sum, not the v0 sum the
182
+ consensus rules give: reported as unverified, with how to settle it. Also why
183
+ `estimate_cycles` is no oracle for a historical transaction (spent inputs do
184
+ not resolve; it would run today's VM).
185
+ - `npm run hardfork` (scripts/hardfork-check.ts, `--discover` to pick the
186
+ transactions again) writes compat/hardfork.json, the table and
187
+ test/fixtures/hardfork-mocks.json.br. test/hardfork.test.ts replays the
188
+ recorded mocks offline with the WebAssembly debugger at every version, and
189
+ with `CKB_HARDFORK_NETWORK=1` plans them again through the public nodes.
190
+ No change to the replay itself.
191
+ - README: "What a rejected transaction's numbers mean", and "What comes from
192
+ where when replaying": a table of every input to a replay (cells, cell deps
193
+ and dep groups, input headers, header deps, consensus epochs, CKB-VM version,
194
+ max cycles, group order, Type ID, since/capacity checks) and whether it comes
195
+ from the chain via RPC, the node's current state or ckb-debugger's defaults;
196
+ ckb-debugger's limit is per group, the node's per transaction.
197
+ - README: "Flamegraph fidelity": totals are exact, the split between functions
198
+ is attributed (frames open only at symbol-table function starts, so inlined
199
+ code is charged to its caller; cycles charged outside instructions are in no
200
+ frame). The flame example now says the 1,812-cycle gap is everything charged
201
+ outside instructions, not only loading the binary.
202
+ - benchmarks/session-lock/RESULTS.md (and compare.mjs, which writes it): the
203
+ comparison is of these two implementations only, and the Rust lock's build
204
+ profile at 49227cd (`opt-level = "s"`, LTO, one codegen unit, `panic = "abort"`,
205
+ overflow checks, stripped; `+zba,+zbb,+zbc,+zbs,-a`; ckb-std 1.1.0; no pinned
206
+ toolchain).
207
+
208
+ ## 1.2.0 (2026-11-05)
209
+
210
+ Scripts that spawn other scripts (CKB2023 `spawn`).
211
+
212
+ ### Added
213
+ - `flame`, and `report` with `functions`, say when a script spawned others:
214
+ ckb-debugger profiles only the spawning script, so the spawned scripts'
215
+ cycles are in the group's total but in none of its functions. The report
216
+ records `spawned` and `profiled` per group; `diff` notes it under the
217
+ group, and for a group whose cycles changed while none of its own
218
+ functions did, says that the change is in what it spawned.
219
+ - A warning when a swapped-in binary's old code hash is still in a cell's
220
+ data (a match cell naming the game it spawns by data hash): data is not
221
+ rewritten, so that script would not find the new build.
222
+ - `test/fixtures/spawn-project`: a parent lock that spawns a child found by
223
+ data2 hash, with mocks, and tests against ckb-debugger 1.1.1.
224
+ - Action: pull requests from forks, whose token cannot comment. `action/comment`
225
+ runs in a `workflow_run` workflow: it finds the pull request from the run's
226
+ head commit through the API (never from the artifact), posts only while the
227
+ PR is still at that commit, and checks the downloaded report first (at most
228
+ `max-bytes` (256 KiB), the marker on its first line, no NUL bytes; @mentions and #refs
229
+ broken). The two workflows are in `action/README.md`.
230
+ - Action input `informational`: a crossed threshold or a scenario that could
231
+ not run is a warning, not a failed job.
232
+ - Action input `base-config: head`: the base is measured with the PR's
233
+ cycles.json and the base checkout's binaries (`--binaries-from`), for a
234
+ cycles.json generated before the Action (`ckb-cycles scan`). With the
235
+ default, the base checkout has no such file and every group was new.
236
+
237
+ ### Fixed
238
+ - `profiledCycles` reads the last `All cycles:` line: for a spawning script,
239
+ flamegraph mode prints the whole group's total first.
240
+
241
+ ## 1.1.0 (2026-10-30)
242
+
243
+ Cycle reports from ckb-testtool tests, and a check across ckb-debugger releases.
244
+
245
+ ### Security
246
+ - Every mock transaction is checked before it is written for ckb-debugger
247
+ (native and WebAssembly; plain replay, `--file`, `report`, `flame`, `scan`
248
+ scenarios, mocks built from a node): a string containing `{{` anywhere in it,
249
+ or a field that should be hex and is not, is refused with an error that names
250
+ the field. ckb-debugger expands `{{ data <path> }}`, `{{ hash <path> }}`,
251
+ `{{ def_type … }}` and `{{ ref_type … }}` in a tx file, so a pull request's
252
+ mock could embed any file on the runner, past `--root`.
253
+ `checkMockTransaction` is exported from `.` and `./replay`.
254
+ - `report --root` ignores the config's `"rpc"` and says so in a warning: a pull
255
+ request's cycles.json no longer chooses the host the runner sends requests to.
256
+ `--rpc` still applies; otherwise the public node is asked.
257
+ - Names from a cycles.json, a build or a node (scenario, script, binary and
258
+ function names, warnings) are printed to the terminal and the CI log on one
259
+ line, without control or bidi characters, and never with `::` at the start
260
+ of a line (errors keep their lines, each cleaned the same way), so a name
261
+ cannot forge a GitHub Actions workflow command or drive the terminal:
262
+ `report`, `diff`, `flame`, `scan` and plain replay.
263
+ - GitHub Action: the PR's `build` runs in the same job as the sticky-comment
264
+ step, which gets `github-token`, and could take that token by writing its own
265
+ `gh` to `$GITHUB_PATH`, or BASH_ENV, PATH and the like to `$GITHUB_ENV`. `gh`
266
+ is now located before the build runs; the comment step runs `/bin/bash -p`
267
+ (not the `bash` on PATH; no BASH_ENV, ENV or exported functions), sets PATH
268
+ itself, blanks LD_PRELOAD and the like, and runs `gh` with only the variables
269
+ it needs (the proxies and CA settings as they were before the build) and an
270
+ empty config directory. The comment file is read from the runner's temp
271
+ directory, never from a step output, and must be a regular file. This does
272
+ not stop a build that leaves a process running or replaces files on the
273
+ runner; the Action's README says so and shows a two-job setup for PRs you do
274
+ not trust with the token.
275
+ - GitHub Action: `action/comment`, the sticky-comment step on its own, for that
276
+ second job: it posts a markdown file downloaded from the first job, with a
277
+ token the PR's build never shares a runner with. The first job runs the
278
+ Action with `comment: false` and a read-only token.
279
+ - GitHub Action: the comment's markdown is written only when the diff ran, so a
280
+ second job never posts a failed diff's output; the base commit is fetched only
281
+ when the checkout does not have it (a private repository checked out with
282
+ `persist-credentials: false` and `fetch-depth: 0` then needs no credentials).
283
+ - The README examples and this repository's cycle-report workflow check out
284
+ with `persist-credentials: false`, so no token is left in `.git/config` for
285
+ the PR's build, and the Action's README no longer says the build cannot get a
286
+ write token. GitHub-owned actions in this repository's workflows and the
287
+ README examples are pinned to commit SHAs, with the release as a comment.
288
+ - Web inspector: every page is served with `Content-Security-Policy:
289
+ frame-ancestors 'none'`, `X-Frame-Options: DENY`, `X-Content-Type-Options:
290
+ nosniff` and `Referrer-Policy: strict-origin-when-cross-origin`, and without
291
+ `X-Powered-By`, so no other site can frame it.
292
+
293
+ ### Fixed (audit, 31 Oct)
294
+ Each of these could give a gated check the wrong verdict.
295
+ - A binary missing from `--binaries-from` (a contract the PR adds) made every
296
+ scenario offered it a base error with no groups, so nothing in those
297
+ scenarios was compared, the other binaries' groups included. The scenario now
298
+ runs with the binaries that exist, the missing one left as the mock has it;
299
+ only the groups whose code it is are not compared (`missingBinary` on the
300
+ group, `missingBinaries` on the scenario), and a gated diff fails on them
301
+ unless `--allow-removed`.
302
+ - A binary offered to a scenario that matches none of its cell deps (a mock
303
+ dumped from an older build) was measured as the mock's old code on both
304
+ sides and shown unchanged, with nothing said. It is now a warning on that
305
+ scenario, listed in the comment. A binary that matches no cell dep in any
306
+ scenario was a report error that only reached the log: `report` now writes
307
+ its errors into the JSON (`"errors"`), and a gated diff fails when either
308
+ report has any, so the Action's `|| true` no longer hides them.
309
+ - A group the VM stopped (past the cycle limit) was recorded with 0 cycles and
310
+ read as a -100% saving, passing `--fail-above`. The cycles of a stopped run
311
+ are never used now; with `--fail-above` such a group is over the threshold,
312
+ and a result change for `--fail-on-result-change`. A result names the VM
313
+ error's kind (`error: invalid instruction`, `error: cycles error: max cycles
314
+ exceeded`), so one VM error turning into another is a result change.
315
+ - GitHub Action: the base report ran the PR's cycles.json, so a scenario the PR
316
+ deleted was never measured or listed. The base is now measured with the base
317
+ commit's own cycles.json, mocks and binaries (an empty report when the base
318
+ has none); the head still runs the PR's.
319
+ - A base group with nothing in the head to compare against (a scenario or group
320
+ removed, renamed, or moved to another selector) passed both gates. A gated
321
+ diff now fails on it unless `--allow-removed` (Action input `allow-removed`,
322
+ default false). The summary counts such groups and new groups.
323
+ - Two reports from different ckb-debugger versions were compared without a
324
+ word: the summary now names both versions.
325
+
326
+ ### CLI: `ckb-cycles`
327
+ - `scan <mocks-dir>`: writes a cycles.json from the mock transactions a test
328
+ suite wrote, one scenario per file, with each freshly built binary in
329
+ `--binaries` (default `build/release`) mapped by its data hash and
330
+ `<name>.debug` as its symbols build; `--functions` records each group's
331
+ costliest functions.
332
+ - Functions the profiler could not name from line info (`func_0x<address>`:
333
+ ckb-std's `_start`, rustc's allocator shims) are named from the symbols
334
+ build's ELF symbol table, so they no longer show in a diff as one address
335
+ removed and another added when code moves.
336
+ - ELF names skip absolute symbols, labels outside executable sections and
337
+ linker section markers (`__text_start`, `_etext`), so a marker at `_start`'s
338
+ address no longer renames the root frame.
339
+ - Legacy Rust symbol names are demangled in full (`$RF$`, `$LP$`, `$u7b$` and
340
+ the other escapes), so they read as `rustc-demangle` prints them.
341
+
342
+ ### ckb-testtool integration
343
+ - `integrations/ckb-testtool`: a Rust crate whose `verify_tx` writes each
344
+ ckb-testtool transaction as a mock when `CKB_CYCLES_MOCKS` is set, for
345
+ ckb-script-templates projects; with `scan`, `make cycles` reports every
346
+ test's script groups. Checked in CI on a project generated from
347
+ ckb-script-templates, two contracts, a change, a diff.
348
+ - README: the Makefile target uses `npx -p ckb-cycle-tools ckb-cycles` (a bare
349
+ `npx ckb-cycles` names a package that does not exist) and `cargo test -p tests`.
350
+ Every other `npx` line in the READMEs and the demo page now names the package
351
+ the same way.
352
+
353
+ ### Library
354
+ - `scanTestMocks`, `configFromMocks` and `formatScan` (and their types) from `.`.
355
+ - `flameTransaction` reads and parses each symbols build once, not once per
356
+ script group that runs it.
357
+ - `flameTransaction` takes `readBinary` beside `readFile`, so a caller whose
358
+ debugger sees another file system gets frame names from the builds there
359
+ too; it defaults to node:fs, as before.
360
+
361
+ ### GitHub Action
362
+ - When the sticky comment exists but updating it fails, the step retries the
363
+ update (three tries) and then warns; it no longer posts a second report
364
+ comment beside the first.
365
+ - When the pull request's comments cannot be listed, the step warns and posts
366
+ nothing (the report is in the job summary), since it cannot tell whether its
367
+ comment already exists.
368
+
369
+ ### Compatibility across ckb-debugger releases
370
+ - `npm run compat` (repository only): replays 35 frozen scenarios under every
371
+ ckb-debugger release from 0.121.0 to 1.1.1, native and WebAssembly, compares
372
+ each script group with 1.1.1, and writes compat/RESULTS.md; a weekly Linux CI
373
+ job runs it. A scenario the reference debugger could not run counts as a
374
+ mismatch, and two scenario ids that slug alike no longer replay the same
375
+ transaction.
376
+
377
+ ## 1.0.0 (2026-10-27)
378
+
379
+ First stable release.
380
+
381
+ ### CLI: `ckb-cycles`
382
+ - Replays a transaction per script group in ckb-debugger; the sum matches the node's
383
+ total. Resolves the real ckb-debugger past the Windows `.cmd` shim.
384
+ - Failure-path profiling: `--file` profiles a transaction that is not on chain.
385
+ - Right VM version per script, from the node's hardfork epochs; input headers are
386
+ replayed, so header-reading scripts (Nervos DAO) match.
387
+ - Only complete ckb-debugger result lines are trusted, cross-checked with its exit code.
388
+ - `report`, `diff` and `mock` subcommands; swap a cell dep's binary for a fresh build
389
+ before replaying; name your own scripts with `--name`.
390
+ - `flame`: per-group flamegraphs from ckb-debugger's profiler (SVG + folded
391
+ stacks, costliest functions printed); `--bin` swaps in an unstripped build and
392
+ checks its cycles against the deployed binary's.
393
+ - Exit codes: 0 every script accepts and the sum matches the node; 1 a script
394
+ rejects or the sum differs; 2 a usage or environment error.
395
+
396
+ ### Library
397
+ - `.` (analysis), `./analyze`, `./replay` and `./flame` (pure, work in the browser), `./wasm`
398
+ (ckb-debugger's WebAssembly build, in memory, same numbers as native).
399
+
400
+ ### GitHub Action
401
+ - `action/`: posts one sticky cycle report on a pull request, group by group against
402
+ the base branch; checksums the ckb-debugger it installs; fails on a broken base.
403
+ - Function-level costs in the report: a binary's `symbols` build and `"functions": true`
404
+ in cycles.json record each group's costliest functions (checked against the binary's
405
+ cycles), and the comment folds in which functions changed.
406
+ - Hardened for untrusted pull requests: `report --root` keeps the files a PR's
407
+ cycles.json names inside the checkout; names in the comment cannot mention,
408
+ link or break the table; the comment always fits GitHub's size limit.
409
+
410
+ ### Web inspector
411
+ - ckb-cycle-tools.vercel.app: paste a transaction hash, see its scripts and the
412
+ per-group cycles computed in the page.
413
+
414
+ ### Benchmark
415
+ - The session lock in Rust vs ckb-js-vm, rebuilt and rerun in CI: the current lock
416
+ (ckb-session-kit 49227cd, plain CKB and token sessions, codes 10-20), 58 scenarios.