ckb-cycle-tools 1.1.0 → 1.2.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 +213 -180
- package/README.md +659 -652
- package/dist/cli.js +6 -1
- package/dist/diff.d.ts +20 -0
- package/dist/diff.js +24 -2
- package/dist/flame.d.ts +15 -1
- package/dist/flame.js +23 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/profile.d.ts +6 -0
- package/dist/profile.js +3 -1
- package/dist/report.js +8 -2
- package/dist/substitute.js +11 -0
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,180 +1,213 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
This project follows [semantic versioning](https://semver.org/).
|
|
4
|
-
|
|
5
|
-
## 1.
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
###
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
###
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
the
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
the
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
-
|
|
152
|
-
- `
|
|
153
|
-
|
|
154
|
-
- `
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
###
|
|
179
|
-
-
|
|
180
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
This project follows [semantic versioning](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
## 1.2.0 (2026-11-05)
|
|
6
|
+
|
|
7
|
+
Scripts that spawn other scripts (CKB2023 `spawn`).
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
- `flame`, and `report` with `functions`, say when a script spawned others:
|
|
11
|
+
ckb-debugger profiles only the spawning script, so the spawned scripts'
|
|
12
|
+
cycles are in the group's total but in none of its functions. The report
|
|
13
|
+
records `spawned` and `profiled` per group; `diff` notes it under the
|
|
14
|
+
group, and for a group whose cycles changed while none of its own
|
|
15
|
+
functions did, says that the change is in what it spawned.
|
|
16
|
+
- A warning when a swapped-in binary's old code hash is still in a cell's
|
|
17
|
+
data (a match cell naming the game it spawns by data hash): data is not
|
|
18
|
+
rewritten, so that script would not find the new build.
|
|
19
|
+
- `test/fixtures/spawn-project`: a parent lock that spawns a child found by
|
|
20
|
+
data2 hash, with mocks, and tests against ckb-debugger 1.1.1.
|
|
21
|
+
- Action: pull requests from forks, whose token cannot comment. `action/comment`
|
|
22
|
+
runs in a `workflow_run` workflow: it finds the pull request from the run's
|
|
23
|
+
head commit through the API (never from the artifact), posts only while the
|
|
24
|
+
PR is still at that commit, and checks the downloaded report first (at most
|
|
25
|
+
`max-bytes` (256 KiB), the marker on its first line, no NUL bytes; @mentions and #refs
|
|
26
|
+
broken). The two workflows are in `action/README.md`.
|
|
27
|
+
- Action input `informational`: a crossed threshold or a scenario that could
|
|
28
|
+
not run is a warning, not a failed job.
|
|
29
|
+
- Action input `base-config: head`: the base is measured with the PR's
|
|
30
|
+
cycles.json and the base checkout's binaries (`--binaries-from`), for a
|
|
31
|
+
cycles.json generated before the Action (`ckb-cycles scan`). With the
|
|
32
|
+
default, the base checkout has no such file and every group was new.
|
|
33
|
+
|
|
34
|
+
### Fixed
|
|
35
|
+
- `profiledCycles` reads the last `All cycles:` line: for a spawning script,
|
|
36
|
+
flamegraph mode prints the whole group's total first.
|
|
37
|
+
|
|
38
|
+
## 1.1.0 (2026-10-30)
|
|
39
|
+
|
|
40
|
+
Cycle reports from ckb-testtool tests, and a check across ckb-debugger releases.
|
|
41
|
+
|
|
42
|
+
### Security
|
|
43
|
+
- Every mock transaction is checked before it is written for ckb-debugger
|
|
44
|
+
(native and WebAssembly; plain replay, `--file`, `report`, `flame`, `scan`
|
|
45
|
+
scenarios, mocks built from a node): a string containing `{{` anywhere in it,
|
|
46
|
+
or a field that should be hex and is not, is refused with an error that names
|
|
47
|
+
the field. ckb-debugger expands `{{ data <path> }}`, `{{ hash <path> }}`,
|
|
48
|
+
`{{ def_type … }}` and `{{ ref_type … }}` in a tx file, so a pull request's
|
|
49
|
+
mock could embed any file on the runner, past `--root`.
|
|
50
|
+
`checkMockTransaction` is exported from `.` and `./replay`.
|
|
51
|
+
- `report --root` ignores the config's `"rpc"` and says so in a warning: a pull
|
|
52
|
+
request's cycles.json no longer chooses the host the runner sends requests to.
|
|
53
|
+
`--rpc` still applies; otherwise the public node is asked.
|
|
54
|
+
- Names from a cycles.json, a build or a node (scenario, script, binary and
|
|
55
|
+
function names, warnings) are printed to the terminal and the CI log on one
|
|
56
|
+
line, without control or bidi characters, and never with `::` at the start
|
|
57
|
+
of a line (errors keep their lines, each cleaned the same way), so a name
|
|
58
|
+
cannot forge a GitHub Actions workflow command or drive the terminal:
|
|
59
|
+
`report`, `diff`, `flame`, `scan` and plain replay.
|
|
60
|
+
- GitHub Action: the PR's `build` runs in the same job as the sticky-comment
|
|
61
|
+
step, which gets `github-token`, and could take that token by writing its own
|
|
62
|
+
`gh` to `$GITHUB_PATH`, or BASH_ENV, PATH and the like to `$GITHUB_ENV`. `gh`
|
|
63
|
+
is now located before the build runs; the comment step runs `/bin/bash -p`
|
|
64
|
+
(not the `bash` on PATH; no BASH_ENV, ENV or exported functions), sets PATH
|
|
65
|
+
itself, blanks LD_PRELOAD and the like, and runs `gh` with only the variables
|
|
66
|
+
it needs (the proxies and CA settings as they were before the build) and an
|
|
67
|
+
empty config directory. The comment file is read from the runner's temp
|
|
68
|
+
directory, never from a step output, and must be a regular file. This does
|
|
69
|
+
not stop a build that leaves a process running or replaces files on the
|
|
70
|
+
runner; the Action's README says so and shows a two-job setup for PRs you do
|
|
71
|
+
not trust with the token.
|
|
72
|
+
- GitHub Action: `action/comment`, the sticky-comment step on its own, for that
|
|
73
|
+
second job: it posts a markdown file downloaded from the first job, with a
|
|
74
|
+
token the PR's build never shares a runner with. The first job runs the
|
|
75
|
+
Action with `comment: false` and a read-only token.
|
|
76
|
+
- GitHub Action: the comment's markdown is written only when the diff ran, so a
|
|
77
|
+
second job never posts a failed diff's output; the base commit is fetched only
|
|
78
|
+
when the checkout does not have it (a private repository checked out with
|
|
79
|
+
`persist-credentials: false` and `fetch-depth: 0` then needs no credentials).
|
|
80
|
+
- The README examples and this repository's cycle-report workflow check out
|
|
81
|
+
with `persist-credentials: false`, so no token is left in `.git/config` for
|
|
82
|
+
the PR's build, and the Action's README no longer says the build cannot get a
|
|
83
|
+
write token. GitHub-owned actions in this repository's workflows and the
|
|
84
|
+
README examples are pinned to commit SHAs, with the release as a comment.
|
|
85
|
+
- Web inspector: every page is served with `Content-Security-Policy:
|
|
86
|
+
frame-ancestors 'none'`, `X-Frame-Options: DENY`, `X-Content-Type-Options:
|
|
87
|
+
nosniff` and `Referrer-Policy: strict-origin-when-cross-origin`, and without
|
|
88
|
+
`X-Powered-By`, so no other site can frame it.
|
|
89
|
+
|
|
90
|
+
### Fixed (audit, 31 Oct)
|
|
91
|
+
Each of these could give a gated check the wrong verdict.
|
|
92
|
+
- A binary missing from `--binaries-from` (a contract the PR adds) made every
|
|
93
|
+
scenario offered it a base error with no groups, so nothing in those
|
|
94
|
+
scenarios was compared, the other binaries' groups included. The scenario now
|
|
95
|
+
runs with the binaries that exist, the missing one left as the mock has it;
|
|
96
|
+
only the groups whose code it is are not compared (`missingBinary` on the
|
|
97
|
+
group, `missingBinaries` on the scenario), and a gated diff fails on them
|
|
98
|
+
unless `--allow-removed`.
|
|
99
|
+
- A binary offered to a scenario that matches none of its cell deps (a mock
|
|
100
|
+
dumped from an older build) was measured as the mock's old code on both
|
|
101
|
+
sides and shown unchanged, with nothing said. It is now a warning on that
|
|
102
|
+
scenario, listed in the comment. A binary that matches no cell dep in any
|
|
103
|
+
scenario was a report error that only reached the log: `report` now writes
|
|
104
|
+
its errors into the JSON (`"errors"`), and a gated diff fails when either
|
|
105
|
+
report has any, so the Action's `|| true` no longer hides them.
|
|
106
|
+
- A group the VM stopped (past the cycle limit) was recorded with 0 cycles and
|
|
107
|
+
read as a -100% saving, passing `--fail-above`. The cycles of a stopped run
|
|
108
|
+
are never used now; with `--fail-above` such a group is over the threshold,
|
|
109
|
+
and a result change for `--fail-on-result-change`. A result names the VM
|
|
110
|
+
error's kind (`error: invalid instruction`, `error: cycles error: max cycles
|
|
111
|
+
exceeded`), so one VM error turning into another is a result change.
|
|
112
|
+
- GitHub Action: the base report ran the PR's cycles.json, so a scenario the PR
|
|
113
|
+
deleted was never measured or listed. The base is now measured with the base
|
|
114
|
+
commit's own cycles.json, mocks and binaries (an empty report when the base
|
|
115
|
+
has none); the head still runs the PR's.
|
|
116
|
+
- A base group with nothing in the head to compare against (a scenario or group
|
|
117
|
+
removed, renamed, or moved to another selector) passed both gates. A gated
|
|
118
|
+
diff now fails on it unless `--allow-removed` (Action input `allow-removed`,
|
|
119
|
+
default false). The summary counts such groups and new groups.
|
|
120
|
+
- Two reports from different ckb-debugger versions were compared without a
|
|
121
|
+
word: the summary now names both versions.
|
|
122
|
+
|
|
123
|
+
### CLI: `ckb-cycles`
|
|
124
|
+
- `scan <mocks-dir>`: writes a cycles.json from the mock transactions a test
|
|
125
|
+
suite wrote, one scenario per file, with each freshly built binary in
|
|
126
|
+
`--binaries` (default `build/release`) mapped by its data hash and
|
|
127
|
+
`<name>.debug` as its symbols build; `--functions` records each group's
|
|
128
|
+
costliest functions.
|
|
129
|
+
- Functions the profiler could not name from line info (`func_0x<address>`:
|
|
130
|
+
ckb-std's `_start`, rustc's allocator shims) are named from the symbols
|
|
131
|
+
build's ELF symbol table, so they no longer show in a diff as one address
|
|
132
|
+
removed and another added when code moves.
|
|
133
|
+
- ELF names skip absolute symbols, labels outside executable sections and
|
|
134
|
+
linker section markers (`__text_start`, `_etext`), so a marker at `_start`'s
|
|
135
|
+
address no longer renames the root frame.
|
|
136
|
+
- Legacy Rust symbol names are demangled in full (`$RF$`, `$LP$`, `$u7b$` and
|
|
137
|
+
the other escapes), so they read as `rustc-demangle` prints them.
|
|
138
|
+
|
|
139
|
+
### ckb-testtool integration
|
|
140
|
+
- `integrations/ckb-testtool`: a Rust crate whose `verify_tx` writes each
|
|
141
|
+
ckb-testtool transaction as a mock when `CKB_CYCLES_MOCKS` is set, for
|
|
142
|
+
ckb-script-templates projects; with `scan`, `make cycles` reports every
|
|
143
|
+
test's script groups. Checked in CI on a project generated from
|
|
144
|
+
ckb-script-templates, two contracts, a change, a diff.
|
|
145
|
+
- README: the Makefile target uses `npx -p ckb-cycle-tools ckb-cycles` (a bare
|
|
146
|
+
`npx ckb-cycles` names a package that does not exist) and `cargo test -p tests`.
|
|
147
|
+
Every other `npx` line in the READMEs and the demo page now names the package
|
|
148
|
+
the same way.
|
|
149
|
+
|
|
150
|
+
### Library
|
|
151
|
+
- `scanTestMocks`, `configFromMocks` and `formatScan` (and their types) from `.`.
|
|
152
|
+
- `flameTransaction` reads and parses each symbols build once, not once per
|
|
153
|
+
script group that runs it.
|
|
154
|
+
- `flameTransaction` takes `readBinary` beside `readFile`, so a caller whose
|
|
155
|
+
debugger sees another file system gets frame names from the builds there
|
|
156
|
+
too; it defaults to node:fs, as before.
|
|
157
|
+
|
|
158
|
+
### GitHub Action
|
|
159
|
+
- When the sticky comment exists but updating it fails, the step retries the
|
|
160
|
+
update (three tries) and then warns; it no longer posts a second report
|
|
161
|
+
comment beside the first.
|
|
162
|
+
- When the pull request's comments cannot be listed, the step warns and posts
|
|
163
|
+
nothing (the report is in the job summary), since it cannot tell whether its
|
|
164
|
+
comment already exists.
|
|
165
|
+
|
|
166
|
+
### Compatibility across ckb-debugger releases
|
|
167
|
+
- `npm run compat` (repository only): replays 35 frozen scenarios under every
|
|
168
|
+
ckb-debugger release from 0.121.0 to 1.1.1, native and WebAssembly, compares
|
|
169
|
+
each script group with 1.1.1, and writes compat/RESULTS.md; a weekly Linux CI
|
|
170
|
+
job runs it. A scenario the reference debugger could not run counts as a
|
|
171
|
+
mismatch, and two scenario ids that slug alike no longer replay the same
|
|
172
|
+
transaction.
|
|
173
|
+
|
|
174
|
+
## 1.0.0 (2026-10-27)
|
|
175
|
+
|
|
176
|
+
First stable release.
|
|
177
|
+
|
|
178
|
+
### CLI: `ckb-cycles`
|
|
179
|
+
- Replays a transaction per script group in ckb-debugger; the sum matches the node's
|
|
180
|
+
total. Resolves the real ckb-debugger past the Windows `.cmd` shim.
|
|
181
|
+
- Failure-path profiling: `--file` profiles a transaction that is not on chain.
|
|
182
|
+
- Right VM version per script, from the node's hardfork epochs; input headers are
|
|
183
|
+
replayed, so header-reading scripts (Nervos DAO) match.
|
|
184
|
+
- Only complete ckb-debugger result lines are trusted, cross-checked with its exit code.
|
|
185
|
+
- `report`, `diff` and `mock` subcommands; swap a cell dep's binary for a fresh build
|
|
186
|
+
before replaying; name your own scripts with `--name`.
|
|
187
|
+
- `flame`: per-group flamegraphs from ckb-debugger's profiler (SVG + folded
|
|
188
|
+
stacks, costliest functions printed); `--bin` swaps in an unstripped build and
|
|
189
|
+
checks its cycles against the deployed binary's.
|
|
190
|
+
- Exit codes: 0 every script accepts and the sum matches the node; 1 a script
|
|
191
|
+
rejects or the sum differs; 2 a usage or environment error.
|
|
192
|
+
|
|
193
|
+
### Library
|
|
194
|
+
- `.` (analysis), `./analyze`, `./replay` and `./flame` (pure, work in the browser), `./wasm`
|
|
195
|
+
(ckb-debugger's WebAssembly build, in memory, same numbers as native).
|
|
196
|
+
|
|
197
|
+
### GitHub Action
|
|
198
|
+
- `action/`: posts one sticky cycle report on a pull request, group by group against
|
|
199
|
+
the base branch; checksums the ckb-debugger it installs; fails on a broken base.
|
|
200
|
+
- Function-level costs in the report: a binary's `symbols` build and `"functions": true`
|
|
201
|
+
in cycles.json record each group's costliest functions (checked against the binary's
|
|
202
|
+
cycles), and the comment folds in which functions changed.
|
|
203
|
+
- Hardened for untrusted pull requests: `report --root` keeps the files a PR's
|
|
204
|
+
cycles.json names inside the checkout; names in the comment cannot mention,
|
|
205
|
+
link or break the table; the comment always fits GitHub's size limit.
|
|
206
|
+
|
|
207
|
+
### Web inspector
|
|
208
|
+
- ckb-cycle-tools.vercel.app: paste a transaction hash, see its scripts and the
|
|
209
|
+
per-group cycles computed in the page.
|
|
210
|
+
|
|
211
|
+
### Benchmark
|
|
212
|
+
- The session lock in Rust vs ckb-js-vm, rebuilt and rerun in CI: the current lock
|
|
213
|
+
(ckb-session-kit 49227cd, plain CKB and token sessions, codes 10-20), 58 scenarios.
|