ckb-cycle-tools 1.0.0 → 1.1.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,44 +1,180 @@
1
- # Changelog
2
-
3
- This project follows [semantic versioning](https://semver.org/).
4
-
5
- ## 1.0.0 (2026-10-27)
6
-
7
- First stable release.
8
-
9
- ### CLI: `ckb-cycles`
10
- - Replays a transaction per script group in ckb-debugger; the sum matches the node's
11
- total. Resolves the real ckb-debugger past the Windows `.cmd` shim.
12
- - Failure-path profiling: `--file` profiles a transaction that is not on chain.
13
- - Right VM version per script, from the node's hardfork epochs; input headers are
14
- replayed, so header-reading scripts (Nervos DAO) match.
15
- - Only complete ckb-debugger result lines are trusted, cross-checked with its exit code.
16
- - `report`, `diff` and `mock` subcommands; swap a cell dep's binary for a fresh build
17
- before replaying; name your own scripts with `--name`.
18
- - `flame`: per-group flamegraphs from ckb-debugger's profiler (SVG + folded
19
- stacks, costliest functions printed); `--bin` swaps in an unstripped build and
20
- checks its cycles against the deployed binary's.
21
- - Exit codes: 0 every script accepts and the sum matches the node; 1 a script
22
- rejects or the sum differs; 2 a usage or environment error.
23
-
24
- ### Library
25
- - `.` (analysis), `./analyze`, `./replay` and `./flame` (pure, work in the browser), `./wasm`
26
- (ckb-debugger's WebAssembly build, in memory, same numbers as native).
27
-
28
- ### GitHub Action
29
- - `action/`: posts one sticky cycle report on a pull request, group by group against
30
- the base branch; checksums the ckb-debugger it installs; fails on a broken base.
31
- - Function-level costs in the report: a binary's `symbols` build and `"functions": true`
32
- in cycles.json record each group's costliest functions (checked against the binary's
33
- cycles), and the comment folds in which functions changed.
34
- - Hardened for untrusted pull requests: `report --root` keeps the files a PR's
35
- cycles.json names inside the checkout; names in the comment cannot mention,
36
- link or break the table; the comment always fits GitHub's size limit.
37
-
38
- ### Web inspector
39
- - ckb-cycle-tools.vercel.app: paste a transaction hash, see its scripts and the
40
- per-group cycles computed in the page.
41
-
42
- ### Benchmark
43
- - The session lock in Rust vs ckb-js-vm, rebuilt and rerun in CI: the current lock
44
- (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.1.0 (2026-10-30)
6
+
7
+ Cycle reports from ckb-testtool tests, and a check across ckb-debugger releases.
8
+
9
+ ### Security
10
+ - Every mock transaction is checked before it is written for ckb-debugger
11
+ (native and WebAssembly; plain replay, `--file`, `report`, `flame`, `scan`
12
+ scenarios, mocks built from a node): a string containing `{{` anywhere in it,
13
+ or a field that should be hex and is not, is refused with an error that names
14
+ the field. ckb-debugger expands `{{ data <path> }}`, `{{ hash <path> }}`,
15
+ `{{ def_type … }}` and `{{ ref_type … }}` in a tx file, so a pull request's
16
+ mock could embed any file on the runner, past `--root`.
17
+ `checkMockTransaction` is exported from `.` and `./replay`.
18
+ - `report --root` ignores the config's `"rpc"` and says so in a warning: a pull
19
+ request's cycles.json no longer chooses the host the runner sends requests to.
20
+ `--rpc` still applies; otherwise the public node is asked.
21
+ - Names from a cycles.json, a build or a node (scenario, script, binary and
22
+ function names, warnings) are printed to the terminal and the CI log on one
23
+ line, without control or bidi characters, and never with `::` at the start
24
+ of a line (errors keep their lines, each cleaned the same way), so a name
25
+ cannot forge a GitHub Actions workflow command or drive the terminal:
26
+ `report`, `diff`, `flame`, `scan` and plain replay.
27
+ - GitHub Action: the PR's `build` runs in the same job as the sticky-comment
28
+ step, which gets `github-token`, and could take that token by writing its own
29
+ `gh` to `$GITHUB_PATH`, or BASH_ENV, PATH and the like to `$GITHUB_ENV`. `gh`
30
+ is now located before the build runs; the comment step runs `/bin/bash -p`
31
+ (not the `bash` on PATH; no BASH_ENV, ENV or exported functions), sets PATH
32
+ itself, blanks LD_PRELOAD and the like, and runs `gh` with only the variables
33
+ it needs (the proxies and CA settings as they were before the build) and an
34
+ empty config directory. The comment file is read from the runner's temp
35
+ directory, never from a step output, and must be a regular file. This does
36
+ not stop a build that leaves a process running or replaces files on the
37
+ runner; the Action's README says so and shows a two-job setup for PRs you do
38
+ not trust with the token.
39
+ - GitHub Action: `action/comment`, the sticky-comment step on its own, for that
40
+ second job: it posts a markdown file downloaded from the first job, with a
41
+ token the PR's build never shares a runner with. The first job runs the
42
+ Action with `comment: false` and a read-only token.
43
+ - GitHub Action: the comment's markdown is written only when the diff ran, so a
44
+ second job never posts a failed diff's output; the base commit is fetched only
45
+ when the checkout does not have it (a private repository checked out with
46
+ `persist-credentials: false` and `fetch-depth: 0` then needs no credentials).
47
+ - The README examples and this repository's cycle-report workflow check out
48
+ with `persist-credentials: false`, so no token is left in `.git/config` for
49
+ the PR's build, and the Action's README no longer says the build cannot get a
50
+ write token. GitHub-owned actions in this repository's workflows and the
51
+ README examples are pinned to commit SHAs, with the release as a comment.
52
+ - Web inspector: every page is served with `Content-Security-Policy:
53
+ frame-ancestors 'none'`, `X-Frame-Options: DENY`, `X-Content-Type-Options:
54
+ nosniff` and `Referrer-Policy: strict-origin-when-cross-origin`, and without
55
+ `X-Powered-By`, so no other site can frame it.
56
+
57
+ ### Fixed (audit, 31 Oct)
58
+ Each of these could give a gated check the wrong verdict.
59
+ - A binary missing from `--binaries-from` (a contract the PR adds) made every
60
+ scenario offered it a base error with no groups, so nothing in those
61
+ scenarios was compared, the other binaries' groups included. The scenario now
62
+ runs with the binaries that exist, the missing one left as the mock has it;
63
+ only the groups whose code it is are not compared (`missingBinary` on the
64
+ group, `missingBinaries` on the scenario), and a gated diff fails on them
65
+ unless `--allow-removed`.
66
+ - A binary offered to a scenario that matches none of its cell deps (a mock
67
+ dumped from an older build) was measured as the mock's old code on both
68
+ sides and shown unchanged, with nothing said. It is now a warning on that
69
+ scenario, listed in the comment. A binary that matches no cell dep in any
70
+ scenario was a report error that only reached the log: `report` now writes
71
+ its errors into the JSON (`"errors"`), and a gated diff fails when either
72
+ report has any, so the Action's `|| true` no longer hides them.
73
+ - A group the VM stopped (past the cycle limit) was recorded with 0 cycles and
74
+ read as a -100% saving, passing `--fail-above`. The cycles of a stopped run
75
+ are never used now; with `--fail-above` such a group is over the threshold,
76
+ and a result change for `--fail-on-result-change`. A result names the VM
77
+ error's kind (`error: invalid instruction`, `error: cycles error: max cycles
78
+ exceeded`), so one VM error turning into another is a result change.
79
+ - GitHub Action: the base report ran the PR's cycles.json, so a scenario the PR
80
+ deleted was never measured or listed. The base is now measured with the base
81
+ commit's own cycles.json, mocks and binaries (an empty report when the base
82
+ has none); the head still runs the PR's.
83
+ - A base group with nothing in the head to compare against (a scenario or group
84
+ removed, renamed, or moved to another selector) passed both gates. A gated
85
+ diff now fails on it unless `--allow-removed` (Action input `allow-removed`,
86
+ default false). The summary counts such groups and new groups.
87
+ - Two reports from different ckb-debugger versions were compared without a
88
+ word: the summary now names both versions.
89
+
90
+ ### CLI: `ckb-cycles`
91
+ - `scan <mocks-dir>`: writes a cycles.json from the mock transactions a test
92
+ suite wrote, one scenario per file, with each freshly built binary in
93
+ `--binaries` (default `build/release`) mapped by its data hash and
94
+ `<name>.debug` as its symbols build; `--functions` records each group's
95
+ costliest functions.
96
+ - Functions the profiler could not name from line info (`func_0x<address>`:
97
+ ckb-std's `_start`, rustc's allocator shims) are named from the symbols
98
+ build's ELF symbol table, so they no longer show in a diff as one address
99
+ removed and another added when code moves.
100
+ - ELF names skip absolute symbols, labels outside executable sections and
101
+ linker section markers (`__text_start`, `_etext`), so a marker at `_start`'s
102
+ address no longer renames the root frame.
103
+ - Legacy Rust symbol names are demangled in full (`$RF$`, `$LP$`, `$u7b$` and
104
+ the other escapes), so they read as `rustc-demangle` prints them.
105
+
106
+ ### ckb-testtool integration
107
+ - `integrations/ckb-testtool`: a Rust crate whose `verify_tx` writes each
108
+ ckb-testtool transaction as a mock when `CKB_CYCLES_MOCKS` is set, for
109
+ ckb-script-templates projects; with `scan`, `make cycles` reports every
110
+ test's script groups. Checked in CI on a project generated from
111
+ ckb-script-templates, two contracts, a change, a diff.
112
+ - README: the Makefile target uses `npx -p ckb-cycle-tools ckb-cycles` (a bare
113
+ `npx ckb-cycles` names a package that does not exist) and `cargo test -p tests`.
114
+ Every other `npx` line in the READMEs and the demo page now names the package
115
+ the same way.
116
+
117
+ ### Library
118
+ - `scanTestMocks`, `configFromMocks` and `formatScan` (and their types) from `.`.
119
+ - `flameTransaction` reads and parses each symbols build once, not once per
120
+ script group that runs it.
121
+ - `flameTransaction` takes `readBinary` beside `readFile`, so a caller whose
122
+ debugger sees another file system gets frame names from the builds there
123
+ too; it defaults to node:fs, as before.
124
+
125
+ ### GitHub Action
126
+ - When the sticky comment exists but updating it fails, the step retries the
127
+ update (three tries) and then warns; it no longer posts a second report
128
+ comment beside the first.
129
+ - When the pull request's comments cannot be listed, the step warns and posts
130
+ nothing (the report is in the job summary), since it cannot tell whether its
131
+ comment already exists.
132
+
133
+ ### Compatibility across ckb-debugger releases
134
+ - `npm run compat` (repository only): replays 35 frozen scenarios under every
135
+ ckb-debugger release from 0.121.0 to 1.1.1, native and WebAssembly, compares
136
+ each script group with 1.1.1, and writes compat/RESULTS.md; a weekly Linux CI
137
+ job runs it. A scenario the reference debugger could not run counts as a
138
+ mismatch, and two scenario ids that slug alike no longer replay the same
139
+ transaction.
140
+
141
+ ## 1.0.0 (2026-10-27)
142
+
143
+ First stable release.
144
+
145
+ ### CLI: `ckb-cycles`
146
+ - Replays a transaction per script group in ckb-debugger; the sum matches the node's
147
+ total. Resolves the real ckb-debugger past the Windows `.cmd` shim.
148
+ - Failure-path profiling: `--file` profiles a transaction that is not on chain.
149
+ - Right VM version per script, from the node's hardfork epochs; input headers are
150
+ replayed, so header-reading scripts (Nervos DAO) match.
151
+ - Only complete ckb-debugger result lines are trusted, cross-checked with its exit code.
152
+ - `report`, `diff` and `mock` subcommands; swap a cell dep's binary for a fresh build
153
+ before replaying; name your own scripts with `--name`.
154
+ - `flame`: per-group flamegraphs from ckb-debugger's profiler (SVG + folded
155
+ stacks, costliest functions printed); `--bin` swaps in an unstripped build and
156
+ checks its cycles against the deployed binary's.
157
+ - Exit codes: 0 every script accepts and the sum matches the node; 1 a script
158
+ rejects or the sum differs; 2 a usage or environment error.
159
+
160
+ ### Library
161
+ - `.` (analysis), `./analyze`, `./replay` and `./flame` (pure, work in the browser), `./wasm`
162
+ (ckb-debugger's WebAssembly build, in memory, same numbers as native).
163
+
164
+ ### GitHub Action
165
+ - `action/`: posts one sticky cycle report on a pull request, group by group against
166
+ the base branch; checksums the ckb-debugger it installs; fails on a broken base.
167
+ - Function-level costs in the report: a binary's `symbols` build and `"functions": true`
168
+ in cycles.json record each group's costliest functions (checked against the binary's
169
+ cycles), and the comment folds in which functions changed.
170
+ - Hardened for untrusted pull requests: `report --root` keeps the files a PR's
171
+ cycles.json names inside the checkout; names in the comment cannot mention,
172
+ link or break the table; the comment always fits GitHub's size limit.
173
+
174
+ ### Web inspector
175
+ - ckb-cycle-tools.vercel.app: paste a transaction hash, see its scripts and the
176
+ per-group cycles computed in the page.
177
+
178
+ ### Benchmark
179
+ - The session lock in Rust vs ckb-js-vm, rebuilt and rerun in CI: the current lock
180
+ (ckb-session-kit 49227cd, plain CKB and token sessions, codes 10-20), 58 scenarios.
package/README.md CHANGED
@@ -37,6 +37,16 @@ There is no convenient way to answer the two questions people actually have:
37
37
  bare-name `child_process` spawn. That blocks every contract test on Windows, and
38
38
  the workaround should not have to be rediscovered by everyone who hits it.
39
39
 
40
+ ## Install
41
+
42
+ ```bash
43
+ npm install -g ckb-cycle-tools # the ckb-cycles command
44
+ ckb-cycles <tx hash> # or without installing: npx -p ckb-cycle-tools ckb-cycles <tx hash>
45
+ ```
46
+
47
+ [ckb-cycle-tools on npm](https://www.npmjs.com/package/ckb-cycle-tools) (v1.1.0, ESM, Node 20 or
48
+ later). It drives `ckb-debugger`, which must be on PATH or passed with `--debugger`.
49
+
40
50
  ## Try it
41
51
 
42
52
  ```bash
@@ -162,7 +172,7 @@ of exactly its 100 CKB limit, edited to pay one shannon more
162
172
  ([`test/fixtures/session-lock-overspend.json`](test/fixtures/session-lock-overspend.json)):
163
173
 
164
174
  ```
165
- $ npx ckb-cycles --file session-lock-overspend.json
175
+ $ npx -p ckb-cycle-tools ckb-cycles --file session-lock-overspend.json
166
176
  tx not on chain
167
177
 
168
178
  GROUP SCRIPT RUN AT RESULT CYCLES SHARE
@@ -194,7 +204,7 @@ of the ckb-session-kit lock, with that lock built with symbols
194
204
  (`CARGO_PROFILE_RELEASE_STRIP=false cargo build --release`):
195
205
 
196
206
  ```
197
- $ npx ckb-cycles flame 0x50ae6df4…a03092 --script input.0.lock \
207
+ $ npx -p ckb-cycle-tools ckb-cycles flame 0x50ae6df4…a03092 --script input.0.lock \
198
208
  --bin 0xab419466…4c08ce=target/riscv64imac-unknown-none-elf/release/session-lock
199
209
  input.0.lock 0xab4194…4c08ce ok 20,999 cycles
200
210
  --bin …/session-lock: same cycles as the deployed binary
@@ -236,14 +246,34 @@ this repo's five are written by `benchmarks/session-lock/mocks.mjs`, and
236
246
  `ckb-cycles mock <tx-hash> -o file.json` saves any transaction that way.
237
247
  `binaries` swaps the deployed code for the one just built (the rules for
238
248
  `type` vs `data*` hash types are in the [Action's README](action/README.md#cyclesjson)).
249
+ For a cycles.json from a pull request, `--root <dir>` (repeatable) refuses any
250
+ file it names outside those directories, and ignores its `"rpc"` (with a
251
+ warning; `--rpc` still applies). Mocks with ckb-debugger template directives
252
+ (`{{ data <path> }}`, `{{ hash <path> }}`, …), or a field that should be hex and is not, are
253
+ refused, with or without `--root`.
254
+
255
+ With `--fail-above` or `--fail-on-result-change` set, `diff` fails on anything
256
+ it could not check, not only on what it measured: a scenario either side could
257
+ not run, an error in either report (a binary that matched no cell dep in any
258
+ scenario is in the report JSON's `"errors"`), and a base group with nothing in
259
+ the head to compare against (a scenario or group removed, renamed or moved, or
260
+ measured without its binary); `--allow-removed` accepts the last. A group the VM
261
+ stopped (past the cycle limit, a bad instruction) is a result change, and over
262
+ any `--fail-above` threshold, never a -100% saving; two different VM errors are
263
+ two different results. With `--binaries-from`, a binary missing from that
264
+ checkout is left as the mock has it: only the groups whose code it is are not
265
+ compared, and every other binary is still swapped in. A binary offered to a
266
+ scenario that matches none of its cell deps is a warning on that scenario, in
267
+ the comment too. The summary says when the two reports come from different
268
+ ckb-debugger versions.
239
269
 
240
270
  Here the ckb-js-vm session lock was changed to allow one shannon more than its
241
271
  limit and to do extra work per recipient check:
242
272
 
243
273
  ```
244
- $ npx ckb-cycles report cycles.json --json base.json
245
- $ npx ckb-cycles report cycles.json --binaries-from ../pr --json head.json
246
- $ npx ckb-cycles diff base.json head.json --fail-above 1
274
+ $ npx -p ckb-cycle-tools ckb-cycles report cycles.json --json base.json
275
+ $ npx -p ckb-cycle-tools ckb-cycles report cycles.json --binaries-from ../pr --json head.json
276
+ $ npx -p ckb-cycle-tools ckb-cycles diff base.json head.json --fail-above 1
247
277
  1 result change, 1 over the 1% threshold, 5 of 10 script groups changed
248
278
  ```
249
279
 
@@ -257,6 +287,15 @@ That table (with `--markdown`) is what the PR comment shows; unchanged groups
257
287
  fold away below it. This repo runs the Action on its own pull requests
258
288
  ([`.github/workflows/cycle-report.yml`](.github/workflows/cycle-report.yml)).
259
289
 
290
+ The PR's build is the PR's code. In the Action's one-job setup it runs in the
291
+ job that also holds the comment's token (`pull-requests: write`; read-only for
292
+ a PR from a fork): the Action keeps what the build writes to `$GITHUB_PATH` and
293
+ `$GITHUB_ENV` away from that token, but a build that leaves a process running
294
+ or replaces files on the runner can still take it. For pull requests you would
295
+ not trust with it, the [two-job setup](action/README.md#two-jobs-the-build-never-shares-a-runner-with-the-comment-token)
296
+ builds with a read-only token and posts from a second job that runs no PR code
297
+ (`action/comment`). Check out with `persist-credentials: false` either way.
298
+
260
299
  ### Which functions changed
261
300
 
262
301
  A row says a group got 3% dearer; the flamegraph mode can say where. Give a
@@ -282,7 +321,10 @@ ckb-debugger's flamegraph mode with `--bin <symbols>` and records the 15
282
321
  costliest functions (self and total cycles) in the report. It first checks that
283
322
  the symbols build costs exactly the cycles of the binary it stands for; if not,
284
323
  it is not the same code, and the group gets a warning instead of functions.
285
- `diff --markdown` then adds a folded block under the table for each changed
324
+ Code the debugger has no line info for (ckb-std's `_start`, the allocator shims
325
+ rustc adds) it calls `func_0x<address>`; those frames take their name from the
326
+ build's ELF symbol table, so a function that moved between builds is not a
327
+ removal and an addition in a diff. `diff --markdown` then adds a folded block under the table for each changed
286
328
  group: the functions whose self cycles changed, base, head and Δ, the ten
287
329
  largest changes first. A report without functions (an older base, or a
288
330
  config without `symbols`) still diffs as before; a function shows `—` where
@@ -291,6 +333,129 @@ its cycles are not known on that side.
291
333
  A Rust build keeps its symbols with `CARGO_PROFILE_RELEASE_STRIP=false`; build
292
334
  it next to the stripped one, from the same commit.
293
335
 
336
+ ### From ckb-testtool tests (ckb-script-templates projects)
337
+
338
+ A project made from
339
+ [ckb-script-templates](https://github.com/nervosnetwork/ckb-script-templates)
340
+ already has its scenarios: the Rust tests in `tests/`, on ckb-testtool. Each
341
+ test can leave its transaction behind as a mock, and `ckb-cycles scan` writes
342
+ the cycles.json from them, so nothing is written by hand.
343
+
344
+ 1. In the tests crate, add the helper in
345
+ [`integrations/ckb-testtool`](integrations/ckb-testtool/src/lib.rs) and call
346
+ it where a test calls `context.verify_tx`:
347
+
348
+ ```toml
349
+ # tests/Cargo.toml
350
+ [dependencies]
351
+ ckb-cycles-testtool = { git = "https://github.com/luongthanhtung03/ckb-cycle-tools" }
352
+ ```
353
+
354
+ ```rust
355
+ let cycles = ckb_cycles_testtool::verify_tx(&context, &tx, MAX_CYCLES).expect("pass verification");
356
+ ```
357
+
358
+ The tests `make generate` writes call `context.verify_tx(&tx, 10_000_000)`
359
+ over two lines; one substitution changes them all:
360
+
361
+ ```
362
+ perl -0pi -e 's/context\s*\.verify_tx\(&tx,/ckb_cycles_testtool::verify_tx(&context, &tx,/g' tests/src/tests.rs
363
+ ```
364
+
365
+ It returns what `context.verify_tx` returns. When `CKB_CYCLES_MOCKS` names a
366
+ directory, it also writes `context.dump_tx(&tx)` there, accepted or rejected,
367
+ named after the test: `tests::test_transfer` is `tests.test_transfer.json`, a
368
+ second transaction in the same test `tests.test_transfer-2.json`. Without the
369
+ variable it writes nothing. (It is about 40 lines; copying it into
370
+ `tests/src/lib.rs` works as well.)
371
+
372
+ 2. Add a target to the workspace Makefile:
373
+
374
+ ```make
375
+ CKB_CYCLES ?= npx -y -p ckb-cycle-tools ckb-cycles
376
+ CYCLES_MOCKS := target/ckb-cycles
377
+
378
+ cycles-config: build
379
+ rm -rf $(CYCLES_MOCKS)
380
+ CKB_CYCLES_MOCKS="$(abspath $(CYCLES_MOCKS))" cargo test -p tests
381
+ $(CKB_CYCLES) scan $(CYCLES_MOCKS) --binaries $(BUILD_DIR) --functions -o cycles.json
382
+
383
+ cycles: cycles-config
384
+ $(CKB_CYCLES) report cycles.json
385
+ ```
386
+
387
+ The npm package is `ckb-cycle-tools`; its command is `ckb-cycles`, so a
388
+ project with no package.json needs `npx -p ckb-cycle-tools` (a bare
389
+ `npx ckb-cycles` looks for a package of that name). `scan` needs 1.1.0 or
390
+ later; to run a checkout instead, point the variable at it,
391
+ `make cycles CKB_CYCLES="node ../ckb-cycle-tools/dist/cli.js"`.
392
+
393
+ `make cycles` then builds the contracts, runs the tests, and reports each
394
+ test's script groups, with the costliest functions of your own contracts. The
395
+ fixture project below, its two steps run by hand:
396
+
397
+ ```
398
+ $ npx -p ckb-cycle-tools ckb-cycles scan mocks --binaries build/release --functions -o cycles.json
399
+ cycles.json: 6 scenario(s), 1 binary (args-loop)
400
+ code cells that are none of the binaries: 0xe683b041…3660d7
401
+ $ npx -p ckb-cycle-tools ckb-cycles report cycles.json
402
+ SCENARIO GROUP SCRIPT RESULT CYCLES
403
+ tests.test_beside_always_success input.0.lock args-loop ok 95,392
404
+ tests.test_beside_always_success input.1.lock 0x91b570…218629 ok 2,107
405
+ tests.test_empty_args_rejected input.0.lock args-loop exit 5 2,186
406
+ tests.test_heavy_spend input.0.lock args-loop ok 468,128
407
+ tests.test_light_spend input.0.lock args-loop ok 25,504
408
+ …
409
+ tests.test_heavy_spend input.0.lock: costliest functions (self cycles): args_loop::work 440,320, _start 26,713, memset 230
410
+ ```
411
+
412
+ `scan` makes one `"mock"` scenario per file, and one binary per file in
413
+ `--binaries` (default `build/release`) that a test deployed, matched by its data
414
+ hash, with `<name>.debug` (the template's unstripped copy) as its `symbols`. It
415
+ says on stderr which files no test deployed and which code cells are none of
416
+ the binaries (ckb-testtool's always-success, above). The code hashes are those of
417
+ the build the tests ran against, so the cycles.json is regenerated after each
418
+ build, not committed.
419
+
420
+ ckb-testtool gives each deployed cell a Type ID type script and `build_script`
421
+ uses `hash_type: "type"`, so swapping in another build changes only the code.
422
+ On a pull request, make the head's mocks and cycles.json in a step before the
423
+ Action, and let the Action build both sides (the base's tests may not have the
424
+ helper yet):
425
+
426
+ ```yaml
427
+ - run: make cycles-config
428
+ - uses: luongthanhtung03/ckb-cycle-tools/action@<commit-sha>
429
+ with:
430
+ build: make build
431
+ ```
432
+
433
+ [`test/fixtures/testtool-project`](test/fixtures/testtool-project) is a small
434
+ project in the template's layout, with the output above; the design and its
435
+ open questions are in [docs/design/testtool-integration.md](docs/design/testtool-integration.md).
436
+
437
+ [`scripts/templates-e2e.sh`](scripts/templates-e2e.sh) does all of this on a
438
+ real project: it generates a workspace from ckb-script-templates (commit
439
+ `f90b1e2`), adds two contracts with `make generate` (`alpha` from `contract`,
440
+ `beta` from `contract-without-simulator`), applies the two steps above, runs
441
+ `make cycles-config`, then makes `alpha` run a 1,000-step loop and runs it again.
442
+ It fails unless each report agrees with the cycles ckb-testtool itself counted
443
+ and only `alpha` changed. Its run on Linux (rustc 1.99, clang 19, ckb-debugger
444
+ 1.1.1):
445
+
446
+ ```
447
+ SCENARIO GROUP SCRIPT BASE HEAD Δ Δ%
448
+ tests.test_alpha input.0.lock alpha 7,156 19,174 +12,018 +167.94%
449
+ tests.test_beta input.0.lock beta 7,156 7,156 0 0%
450
+
451
+ functions in tests.test_alpha input.0.lock: __ckb_std_main +12,008
452
+ ```
453
+
454
+ The base column is the base's binaries swapped into the head's mocks
455
+ (`report --binaries-from`); it gives the same 7,156 as the base's own tests.
456
+ (The Action measures the base with the base commit's own cycles.json and mocks,
457
+ so a scenario a pull request deletes still shows up, as removed.)
458
+
294
459
  ## ckb-js-vm vs Rust: one lock, two implementations
295
460
 
296
461
  `benchmarks/session-lock` holds a TypeScript port of the
@@ -317,6 +482,97 @@ CI rebuilds both implementations from source — the Rust lock from a pinned
317
482
  ckb-session-kit commit — reruns every scenario, and publishes the table in the
318
483
  job summary.
319
484
 
485
+ ## Mainnet cycle atlas
486
+
487
+ A one-off snapshot of what the scripts in recent mainnet transactions cost, measured
488
+ with the same replay as `ckb-cycles <tx-hash>`:
489
+ [atlas/2026-10-28/report.md](atlas/2026-10-28/report.md), raw results in
490
+ [data.json](atlas/2026-10-28/data.json).
491
+
492
+ 1,000 transactions from every 12th block between 20,835,876 and 20,851,152
493
+ (26 to 27 Oct 2026, about 39 hours), each replayed per script group in
494
+ ckb-debugger 1.1.1. All 1,000 matched the node's cycle totals exactly, so none was
495
+ excluded. secp256k1_blake160 accounts for 93.7% of the cycles, at a median of
496
+ 1,647,788 per group; it runs once per distinct owner, so the costliest transaction
497
+ in the sample (68 owners) cost 111,979,599 cycles. 694 of the 1,000 transactions
498
+ update d.id's on-chain time oracle (two type scripts at about 45k and 33k cycles),
499
+ and the next most expensive type script is the Bitcoin SPV client behind RGB++
500
+ (median 1,369,197). The report lists min, median, p90 and max per script, its
501
+ share, an example transaction, and the cell each script's code came from.
502
+
503
+ The random sample saw no xUDT, Omnilock, Spore or Type ID, so the report has a
504
+ second, separate section of targeted samples: for each of 22 scripts, up to 40 of
505
+ the most recent transactions in which it ran, found with the indexer RPC and
506
+ replayed the same way (653 replays; 601 matched the node, none mismatched, and
507
+ 52 older transactions, all at or before block 19,011,137, have no cycle total
508
+ on the public node and are listed as not recorded). Medians per group from that
509
+ section: xUDT 20,498, Spore 103,953, Cluster 98,683, Omnilock 1,458,708
510
+ (Ethereum displaying) and 1,458,571 (Bitcoin), JoyID 6,844,452, RGB++ lock
511
+ 1,418,522, COTA 1,134,820. These are costs per run, not shares of mainnet.
512
+
513
+ Only a transaction whose groups add up to the node's total is aggregated; any other
514
+ is listed in the report with its reason, never dropped. To reproduce the same window
515
+ (read-only JSON-RPC against a public node, paced and retried; about 25 minutes):
516
+
517
+ ```bash
518
+ npm ci
519
+ npm run atlas -- --rpc https://mainnet.ckb.dev/ --to 20851152 --blocks 15277 --stride 12 --max-txs 1000
520
+ ```
521
+
522
+ Without `--to` it samples back from the current tip; `--out <dir>` chooses where
523
+ `data.json` and `report.md` go, `--resume` continues an interrupted run, and
524
+ `--report-only <dir>` rebuilds the report from an existing `data.json` (and names
525
+ scripts identified since the run). The atlas and its script are part of the
526
+ repository only, not the npm package.
527
+
528
+ Targeted samples are added to an existing atlas folder. `--script` takes a name
529
+ (`xudt`, `omnilock`, `spore`, `cluster`, `type-id`, `joyid`, `rgbpp-lock`,
530
+ `ickb-logic`, `das-lock` and others; an unknown name lists them) or a code hash as
531
+ `<hash>[:<hash type>[:lock|type]]`, optionally narrowed to an args prefix with
532
+ `@<hex>`, e.g. `omnilock@0x04` for Omnilock's Bitcoin auth. The search looks back
533
+ from `--to`, widening five-fold from 20,000 blocks up to `--max-window`, and
534
+ replays the newest `--max-txs` (default 40). The command that made the report's
535
+ section is at the end of the report.
536
+
537
+ ## Across ckb-debugger versions
538
+
539
+ Do the numbers depend on which ckb-debugger you have? `npm run compat` replays the
540
+ same 35 frozen scenarios under every release in
541
+ [compat/debuggers.json](compat/debuggers.json) and compares each script group
542
+ with the reference, 1.1.1 (the release the CLI and CI pin):
543
+ [compat/RESULTS.md](compat/RESULTS.md), raw runs in
544
+ [results.json](compat/results.json).
545
+
546
+ The scenarios are the six ckb-testtool fixture mocks, the five session-lock
547
+ benchmark mocks (ckb-js-vm), the two recorded testnet transactions (one on VM 1),
548
+ and 22 mainnet transactions from the atlas, one per script it sampled (xUDT,
549
+ Omnilock, Spore, Type ID, JoyID, RGB++, iCKB, COTA, Nervos DAO and others). They
550
+ are stored with every cell in
551
+ [compat/scenarios.json.br](compat/scenarios.json.br), so every build reads the
552
+ same bytes and the run needs no network.
553
+
554
+ Measured on 28 Oct 2026 on Windows: native releases 0.121.0, 0.200.0, 0.200.1,
555
+ 0.200.2, 0.203.0, 1.0.0, 1.1.0 and 1.1.1, and the WebAssembly builds of 0.200.1
556
+ to 1.1.1 (the web page's build in ckb-testtool is byte for byte the 0.200.1 one).
557
+ All 455 scenario runs, 1,170 script groups, gave the reference's cycles and exit
558
+ code, and every mainnet and testnet total matched the node. The same
559
+ transactions on another CKB-VM version do cost differently (VM 2 is cheaper than
560
+ VM 1, and VM 0 cannot run most of today's binaries); the results explain each
561
+ case from the hardfork RFCs. That is why the replay takes the VM version from the
562
+ block's epoch, not from the debugger.
563
+
564
+ ```bash
565
+ npm ci
566
+ npm run compat -- fetch # downloads each release into .cache/, sha256 checked
567
+ npm run compat # runs everything (about 2.5 minutes), exits 1 on any mismatch
568
+ ```
569
+
570
+ `--only 1.0.0,1.1.0` limits the releases, `--no-wasm` skips the WebAssembly
571
+ builds, `--no-sweep` skips the VM 0/1/2 sweep, and `npm run compat -- record`
572
+ rebuilds the scenario file (read-only RPC; needs `npm run bench:build` first).
573
+ [.github/workflows/compat.yml](.github/workflows/compat.yml) runs the check with
574
+ the Linux builds weekly and on demand; it has not run on GitHub yet.
575
+
320
576
  ## Limits
321
577
 
322
578
  - **It needs a node, or a saved transaction.** Rebuilding a transaction means
@@ -326,18 +582,20 @@ job summary.
326
582
  charge its fixed 1,000,000 cycles and check its rules the way the node does.
327
583
  - **Two debugger builds.** The CLI uses the native ckb-debugger you install
328
584
  (1.1.1 here); the web page uses the WebAssembly build shipped in
329
- `ckb-testtool` (0.200.1). They agree on every transaction checked, but a
330
- future CKB-VM change could reach one before the other; each result names the
331
- version it used.
585
+ `ckb-testtool` (0.200.1). They agree on every transaction checked, and so do
586
+ the releases in between ([Across ckb-debugger versions](#across-ckb-debugger-versions)),
587
+ but a future CKB-VM change could reach one before the other; each result names
588
+ the version it used.
332
589
  - **Flamegraphs need symbols.** On-chain binaries are stripped; `flame` names
333
590
  functions only with an unstripped build passed by `--bin` (or `symbols` in a
334
591
  cycles.json). The CLI draws the graphs, the PR comment lists the changed
335
592
  functions, and the web page draws a `.folded` file the CLI made.
336
593
  - **Older blocks.** Some public nodes report `0x0` cycles for old blocks; the
337
594
  tools then say the total is unknown instead of claiming a match.
338
- - **The PR Action has not yet commented on a real pull request.** Every step is
339
- covered by tests and was run locally end to end; the first public run will be
340
- linked here.
595
+ - **The PR Action has run on one public pull request so far**, in this repository:
596
+ [#1](https://github.com/luongthanhtung03/ckb-cycle-tools/pull/1) slows one check of
597
+ the ckb-js-vm benchmark lock on purpose, and the comment reports it (+2.94% on that
598
+ scenario, results unchanged). It has not yet run in another project's repository.
341
599
 
342
600
  ## Why it is a separate repository
343
601