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 +180 -44
- package/README.md +270 -12
- package/dist/cli.js +73 -22
- package/dist/diff.d.ts +74 -8
- package/dist/diff.js +143 -27
- package/dist/elf.d.ts +18 -0
- package/dist/elf.js +209 -0
- package/dist/flame.d.ts +6 -0
- package/dist/flame.js +20 -0
- package/dist/index.d.ts +3 -1
- package/dist/index.js +2 -1
- package/dist/profile.d.ts +5 -1
- package/dist/profile.js +18 -4
- package/dist/replay.d.ts +14 -1
- package/dist/replay.js +44 -2
- package/dist/report.d.ts +6 -1
- package/dist/report.js +79 -30
- package/dist/scan.d.ts +46 -0
- package/dist/scan.js +122 -0
- package/dist/substitute.d.ts +7 -0
- package/dist/substitute.js +28 -7
- package/dist/wasm.d.ts +1 -1
- package/dist/wasm.js +7 -0
- package/package.json +11 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,44 +1,180 @@
|
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
330
|
-
|
|
331
|
-
|
|
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
|
|
339
|
-
|
|
340
|
-
|
|
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
|
|