ckb-cycle-tools 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,652 +1,788 @@
1
- # ckb-cycle-tools
2
-
3
- Cycle measurement for CKB on-chain scripts.
4
-
5
- **Live demo:** [ckb-cycle-tools.vercel.app](https://ckb-cycle-tools.vercel.app/) — paste a testnet tx hash, see cycles and script groups (CKB testnet).
6
-
7
- **Status: v1.0.** Built in the open during my CKBuilder programme.
8
-
9
- | When | Milestone |
10
- |---|---|
11
- | w/c 5 Oct 2026 | ✅ Scaffold, CI, the Windows `ckb-debugger` shim fix |
12
- | w/c 12 Oct | ✅ CLI: per-script cycle table for a transaction |
13
- | w/c 19 Oct | ✅ Failure-path profiling; ✅ CI on Linux and Windows |
14
- | w/c 26 Oct | ✅ ckb-js-vm vs Rust comparison harness |
15
- | w/c 2 Nov | v1.0 on npm |
16
-
17
- ## The problem
18
-
19
- Every CKB script consumes cycles, and cycles are a hard limit rather than a
20
- suggestion. But finding out how many a script uses — and *which part* of it is
21
- expensive — currently means driving `ckb-debugger` by hand and reading raw output.
22
-
23
- There is no convenient way to answer the two questions people actually have:
24
-
25
- 1. How many cycles does this script use, on the transactions it will really see?
26
- 2. Which implementation is cheaper, and by how much?
27
-
28
- ## What this is meant to be
29
-
30
- - A **cycle profiler** that reports usage per script for a given transaction,
31
- including the failure paths rather than only the happy one.
32
- - A **comparison harness** that runs the *same* assertion set against two
33
- implementations — ckb-js-vm and native Rust — and reports both, so the comparison
34
- is like-for-like instead of anecdotal.
35
- - The **Windows toolchain fixes** from my Week 1 findings: `ckb-testtool` cannot find
36
- the `ckb-debugger` that offckb installs, because a `.cmd` shim is invisible to a
37
- bare-name `child_process` spawn. That blocks every contract test on Windows, and
38
- the workaround should not have to be rediscovered by everyone who hits it.
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
-
50
- ## Try it
51
-
52
- ```bash
53
- npm install
54
- npm test # unit tests, no network needed
55
- npm run demo # the Next.js web demo at http://localhost:3000
56
- npm run analyze:testnet -- <tx hash> [<tx hash> …]
57
- npm run cycles -- <tx hash> # per-group cycles via ckb-debugger
58
- ```
59
-
60
- The demo takes a CKB testnet transaction hash and shows the total cycles the node
61
- spent verifying it, and every **script group** that ran. CKB runs each script once
62
- per group: input locks grouped by lock script, type scripts grouped across inputs and
63
- outputs. Output locks never run. Links are shareable: `?tx=<hash>`.
64
-
65
- ### What it already shows
66
-
67
- Real testnet transactions from my CKBuilder work:
68
-
69
- | Transaction | Cycles | Script groups |
70
- |---|---|---|
71
- | [Plain CKB transfer](https://testnet.explorer.nervos.org/transaction/0x52a1b3ba45a28614c30ddc52f0795c164141abbebd1558e6c69fb0ac45fada50) | 1,657,727 | 1 lock |
72
- | [Counter Type Script update (ckb-js-vm)](https://testnet.explorer.nervos.org/transaction/0x64f695a23416d9a7b2d34bb7025140c90991b82e9f1dea98e103bc13a72b77ac) | 15,675,038 | 1 lock + 1 type |
73
- | [Script deployment with Type ID](https://testnet.explorer.nervos.org/transaction/0xa21da18ff3f142127cf63d6e705d64c14577fb99a9a0cbf74f47fb70b6ad66cf) | 2,607,561 | 1 lock + Type ID |
74
-
75
- The counter's type script, running on ckb-js-vm, costs roughly ten times a standard
76
- lock. Which part of that is the JavaScript VM and which is the script itself is what
77
- the per-group breakdown (the CLI, below) and the ckb-js-vm vs Rust harness are for.
78
-
79
- ## Per-script cycles: the `ckb-cycles` CLI
80
-
81
- The web demo shows the total the node reports. The CLI goes further: it rebuilds
82
- the transaction as a ckb-debugger mock transaction (every input cell, every cell
83
- dep, dep groups expanded), runs `ckb-debugger` once per script group, and checks
84
- that the groups add up to exactly what the node reported.
85
-
86
- ```
87
- $ npm run cycles -- 0x64f695a23416d9a7b2d34bb7025140c90991b82e9f1dea98e103bc13a72b77ac
88
-
89
- GROUP SCRIPT RUN AT RESULT CYCLES SHARE
90
- lock Secp256k1Blake160 input.0.lock ok 1,652,198 10.5%
91
- type 0x3e9b6b…18bed7 input.0.type ok 14,022,840 89.5%
92
-
93
- measured (sum of groups) 15,675,038
94
- reported by node 15,675,038 ✓ match
95
- ckb-debugger 1.1.1 · testnet · https://testnet.ckb.dev/
96
-
97
- input.0.type logged:
98
- [DEBUG] counter: 1 input(s) -> 1 output(s)
99
- [DEBUG] counter incremented 2 -> 3
100
- ```
101
-
102
- So in that transaction, **89.5% of the cost is the counter Type Script running on
103
- ckb-js-vm**. Type ID is verified natively by the node and cannot run in
104
- ckb-debugger; the CLI charges it the node's fixed `TYPE_ID_CYCLES` (1,000,000), and
105
- the totals still match exactly.
106
-
107
- **Header-reading scripts replay too.** Each input cell carries the block it was
108
- created in, so a script that reads its input's header (as a Nervos DAO withdrawal
109
- does) sees what it saw on the node, as long as the transaction lists that block in
110
- `header_deps`, which the node requires as well. Before this, a
111
- [DAO withdrawal](https://testnet.explorer.nervos.org/transaction/0xe8776bb8eb039365be9679cd61870cdc7ea3c24e4f2164fdd5d5f103bdfa2cc5)
112
- replayed with NervosDao exiting 2 (header missing) and a total 8,058 cycles short;
113
- it now matches the node's 1,776,369 exactly, and CI checks it.
114
-
115
- The replay is exact for what a script can observe through syscalls: cells, data,
116
- witnesses, headers. **Older transactions replay on the VM they ran on:** a
117
- `hash_type: "type"` script runs on the CKB-VM version of its block's epoch (v0
118
- before Mirana, v1 before Meepo, v2 since), so a 2023 testnet transaction matches
119
- the node only on v1, and the CLI picks it from the block. The hardfork epochs come
120
- from the node it asks (`get_consensus`), never from a flag: `--rpc` with a mainnet
121
- node gives mainnet's schedule with or without `--mainnet`, and `--mainnet` with a
122
- node that serves another chain stops with an error. The output ends with the
123
- ckb-debugger version, that VM version, the network and the node used, so a result
124
- can be reproduced.
125
-
126
- Some public nodes report `0x0` cycles for older blocks; the CLI then says the node
127
- did not record them instead of claiming a mismatch (`--rpc` another node to
128
- compare). A script that faults in the VM (invalid instruction, cycle limit) shows
129
- as a rejection with the VM's message, Type ID is checked as the node checks it,
130
- and a script's logs can neither fake its result nor send control characters to
131
- your terminal: only ckb-debugger's final lines are read, they must agree with its
132
- exit code, and a run that prints more than 64 MB is an error, never parsed.
133
-
134
- Exit codes: **0** every script accepts (and the sum matches the node's); **1** a
135
- script rejects, or the sum differs from the node's; **2** a usage or environment
136
- error: bad arguments, a node that cannot be reached or does not answer within
137
- `--timeout` (default 30 s), a transaction the node does not have (or rejected),
138
- ckb-debugger missing or printing something it cannot read. So `test $? = 1`
139
- asserts a rejection without passing when the node is down. CI runs the CLI against
140
- live testnet transactions on a clean machine. `--json` for machine output,
141
- `--mainnet` or `--rpc <url>` for another node (at most 16 requests in flight).
142
- Your own scripts show as a short code
143
- hash; name them with `--name <code-hash>=<label>` (repeatable, optionally
144
- `<code-hash>:<hash-type>=…`), or `profileTransaction(tx, { scriptNames })` from code.
145
- The web page does the same: click a script for its full code hash and a name box
146
- (saved in that browser), and it prints the CLI command for the per-group breakdown
147
- with those names filled in. ckb-debugger is found the same way
148
- as everywhere else in this repo (see the Windows fix above).
149
-
150
- ### In the browser: per-group cycles on the web page
151
-
152
- The page's **per-group cycles** button runs the same replay without installing
153
- anything: ckb-debugger's WebAssembly build (0.200.1, shipped in `ckb-testtool`)
154
- runs in a Web Worker through a WASI shim, with the mock transaction as an
155
- in-memory file. It downloads ~4 MB (about 1.1 MB compressed) only when pressed,
156
- then shows each group's result, cycles, share and logs, and whether the total
157
- matches the node. It gives the same numbers as the native ckb-debugger 1.1.1:
158
- 15,675,038 (counter), 2,607,561 (Type ID deploy) and 1,787,335 (a 2023, VM v1
159
- transaction), and `test/wasm.test.ts` checks that offline on recorded transactions.
160
- From code: `wasmRunner(module, tx)` from `ckb-cycle-tools/wasm` plugs into
161
- `replayGroups` from `ckb-cycle-tools/replay`, neither of which uses Node built-ins.
162
-
163
- ### Before you send: the failure path
164
-
165
- `--file` profiles a transaction that is not on chain — one you are about to send,
166
- or one the node rejected — and shows which script refuses it, with its exit code
167
- and what it cost to get there. It reads the node's RPC JSON, a `get_transaction`
168
- result, or a CCC transaction saved with `ccc.stringify(tx)`.
169
-
170
- Here a real [session-lock spend](https://testnet.explorer.nervos.org/transaction/0x48b3bde2a50bb8ba3aff0800e850b2aa521793b35628d165eab7f22f984be828)
171
- of exactly its 100 CKB limit, edited to pay one shannon more
172
- ([`test/fixtures/session-lock-overspend.json`](test/fixtures/session-lock-overspend.json)):
173
-
174
- ```
175
- $ npx -p ckb-cycle-tools ckb-cycles --file session-lock-overspend.json
176
- tx not on chain
177
-
178
- GROUP SCRIPT RUN AT RESULT CYCLES SHARE
179
- lock 0x1ae8b8…26bc20 input.0.lock exit 12 12,893 0.8%
180
- lock Secp256k1Blake160 input.1.lock exit -31 1,642,194 99.2%
181
- ```
182
-
183
- The session lock refuses with its code 12 (outflow over `max_per_tx`) after
184
- 12,893 cycles; the secp256k1 lock fails too, because the edit invalidated the
185
- signature. CI replays this file and requires exactly that refusal.
186
-
187
- In code: `profileTransaction(readTransactionJson(json))`, or pass an RPC-shaped
188
- transaction object directly.
189
-
190
- ### Inside a script: flamegraphs
191
-
192
- `ckb-cycles flame` shows where inside each script the cycles go. It runs every
193
- script group in ckb-debugger's flamegraph mode, merges the stacks, names the
194
- frames by function, prints the costliest ones and writes an SVG flamegraph and
195
- a folded-stack file per group (open the `.folded` in
196
- [speedscope](https://www.speedscope.app/) for an interactive view).
197
-
198
- Deployed scripts are stripped, so a profile of one is a single frame. Give an
199
- unstripped build of the same code with `--bin <code-hash>=<elf>`; the tool runs
200
- the group with both binaries and says whether the cycles agree, so you know the
201
- graph describes the deployed code. Here, a real
202
- [subscription charge](https://testnet.explorer.nervos.org/transaction/0x50ae6df49d411a5766da1c9717da9e6ff34670194b389779f717fcee71a03092)
203
- of the ckb-session-kit lock, with that lock built with symbols
204
- (`CARGO_PROFILE_RELEASE_STRIP=false cargo build --release`):
205
-
206
- ```
207
- $ npx -p ckb-cycle-tools ckb-cycles flame 0x50ae6df4…a03092 --script input.0.lock \
208
- --bin 0xab419466…4c08ce=target/riscv64imac-unknown-none-elf/release/session-lock
209
- input.0.lock 0xab4194…4c08ce ok 20,999 cycles
210
- --bin …/session-lock: same cycles as the deployed binary
211
- profiled 19,187 cycles (loading the binary is not profiled)
212
- SELF TOTAL FUNCTION
213
- 4,490 5,972 session_lock::lock_hash
214
- 3,145 3,145 compiler_builtins::mem::memcpy
215
- 2,545 18,678 __ckb_std_main
216
- 2,156 2,156 session_lock::has_type
217
- 2,076 2,076 memcmp
218
- → flame/input.0.lock.svg, flame/input.0.lock.folded
219
- ```
220
-
221
- Reading the lock hashes of the transaction's cells is the lock's largest cost.
222
- The profile covers the script's run; loading the binary into the VM (1,812
223
- cycles here) is counted by the node but not by the profiler.
224
-
225
- **In the browser:** drop the `.folded` file on the
226
- [web inspector](https://ckb-cycle-tools.vercel.app/) ("inside a script"), or open
227
- its example, and it draws the same flamegraph and table. Nothing is uploaded.
228
- (The page's WebAssembly ckb-debugger can profile but not name functions, so the
229
- profile itself comes from the CLI.)
230
-
231
- In code: `flameTransaction(target, { bins, readFile })`, then `functionCosts`,
232
- `flameTree` and `renderFlameSvg` from `ckb-cycle-tools/flame` (no Node
233
- built-ins, so the browser can draw the same graph).
234
-
235
- ## Cycle reports on pull requests
236
-
237
- A change to a script should say what it did to that script's cycles, and above
238
- all whether any accept turned into a reject. `ckb-cycles report` replays every
239
- scenario in a [`cycles.json`](cycles.json) and records each script group's result
240
- and cycles; `ckb-cycles diff` compares two such reports; the
241
- [GitHub Action](action/README.md) runs both on a PR (the PR's build against its
242
- base's) and keeps one comment up to date.
243
-
244
- Scenarios are best kept as ckb-debugger mock transactions, so CI needs no node:
245
- this repo's five are written by `benchmarks/session-lock/mocks.mjs`, and
246
- `ckb-cycles mock <tx-hash> -o file.json` saves any transaction that way.
247
- `binaries` swaps the deployed code for the one just built (the rules for
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.
269
-
270
- Here the ckb-js-vm session lock was changed to allow one shannon more than its
271
- limit and to do extra work per recipient check:
272
-
273
- ```
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
277
- 1 result change, 1 over the 1% threshold, 5 of 10 script groups changed
278
- ```
279
-
280
- | Scenario | Group | Script | Base | Head | Δ | Δ% | |
281
- |---|---|---|---:|---:|---:|---:|---|
282
- | one shannon over max\_per\_tx | `input.0.lock` | session-lock (ckb-js-vm) | 14,544,014 (exit 12) | 14,557,318 | +13,304 | +0.09% | **RESULT CHANGED: exit 12 → ok** |
283
- | pays the allowed recipient | `input.0.lock` | session-lock (ckb-js-vm) | 14,768,645 | 15,465,881 | +697,236 | +4.72% | **over 1%** |
284
- | spend exactly max\_per\_tx | `input.0.lock` | session-lock (ckb-js-vm) | 14,544,018 | 14,557,320 | +13,302 | +0.09% | |
285
-
286
- That table (with `--markdown`) is what the PR comment shows; unchanged groups
287
- fold away below it. This repo runs the Action on its own pull requests
288
- ([`.github/workflows/cycle-report.yml`](.github/workflows/cycle-report.yml)).
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
-
299
- ### Which functions changed
300
-
301
- A row says a group got 3% dearer; the flamegraph mode can say where. Give a
302
- binary an unstripped build of the same code as `symbols`, and ask for
303
- `functions`, for every scenario or per scenario:
304
-
305
- ```json
306
- {
307
- "functions": true,
308
- "binaries": {
309
- "my-lock": {
310
- "path": "build/release/my-lock",
311
- "symbols": "build/release/my-lock.debug",
312
- "codeHash": "0x…"
313
- }
314
- },
315
- "scenarios": [{ "name": "spend", "mock": "tests/mocks/spend.json" }]
316
- }
317
- ```
318
-
319
- For each group whose script is that binary, `report` runs the group again in
320
- ckb-debugger's flamegraph mode with `--bin <symbols>` and records the 15
321
- costliest functions (self and total cycles) in the report. It first checks that
322
- the symbols build costs exactly the cycles of the binary it stands for; if not,
323
- it is not the same code, and the group gets a warning instead of functions.
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
328
- group: the functions whose self cycles changed, base, head and Δ, the ten
329
- largest changes first. A report without functions (an older base, or a
330
- config without `symbols`) still diffs as before; a function shows `—` where
331
- its cycles are not known on that side.
332
-
333
- A Rust build keeps its symbols with `CARGO_PROFILE_RELEASE_STRIP=false`; build
334
- it next to the stripped one, from the same commit.
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
-
459
- ## ckb-js-vm vs Rust: one lock, two implementations
460
-
461
- `benchmarks/session-lock` holds a TypeScript port of the
462
- [ckb-session-kit](https://github.com/luongthanhtung03/ckb-session-kit) session lock
463
- for ckb-js-vm, plain CKB and token sessions (error codes 10-20). It runs the same
464
- 58 scenarios as the Rust original (ckb-session-kit 49227cd) in the real CKB-VM and
465
- fails unless both implementations make every accept/reject decision correctly.
466
-
467
- | | Rust | ckb-js-vm |
468
- |---|---:|---:|
469
- | Mean cycles, accepted plain CKB spends | 14,758 | 15,037,968 |
470
- | Mean cycles, accepted token spends | 20,348 | 15,518,698 |
471
- | Cheapest run (start-up cost) | 3,145 | 14,272,805 |
472
-
473
- About 95% of the ckb-js-vm cost is starting the VM; the lock's own logic runs at
474
- roughly 66× the Rust logic. Full table, and the 8 Oct numbers for comparison:
475
- [RESULTS.md](benchmarks/session-lock/RESULTS.md).
476
-
477
- ```bash
478
- npm run bench:session-lock # needs the Rust lock built in ../ckb-session-kit, or SESSION_LOCK_BIN
479
- ```
480
-
481
- CI rebuilds both implementations from source — the Rust lock from a pinned
482
- ckb-session-kit commit — reruns every scenario, and publishes the table in the
483
- job summary.
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
-
576
- ## Limits
577
-
578
- - **It needs a node, or a saved transaction.** Rebuilding a transaction means
579
- fetching every input cell and cell dep; without RPC access, use a mock file
580
- (`ckb-cycles mock` saves one) or `--file`.
581
- - **Type ID is charged, not run.** The node verifies Type ID natively; the tools
582
- charge its fixed 1,000,000 cycles and check its rules the way the node does.
583
- - **Two debugger builds.** The CLI uses the native ckb-debugger you install
584
- (1.1.1 here); the web page uses the WebAssembly build shipped in
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.
589
- - **Flamegraphs need symbols.** On-chain binaries are stripped; `flame` names
590
- functions only with an unstripped build passed by `--bin` (or `symbols` in a
591
- cycles.json). The CLI draws the graphs, the PR comment lists the changed
592
- functions, and the web page draws a `.folded` file the CLI made.
593
- - **Older blocks.** Some public nodes report `0x0` cycles for old blocks; the
594
- tools then say the total is unknown instead of claiming a match.
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.
599
-
600
- ## Why it is a separate repository
601
-
602
- It started as measurement scaffolding inside a learning exercise. That is a bad place
603
- for a tool to live if anyone else might want it.
604
-
605
- ## Related work
606
-
607
- Other CKB tools touch the same ground. This is what each one does, as far as its
608
- own documentation says, and where this repository sits next to it.
609
-
610
- - **[ckb-debugger](https://github.com/nervosnetwork/ckb-standalone-debugger)**
611
- (nervosnetwork) runs CKB scripts off chain from a mock transaction and reports
612
- their cycles, with a flamegraph mode. It is the engine everything here drives;
613
- nothing in this repository re-implements the VM. What is added on top: rebuilding
614
- a mock transaction from a tx hash or a saved transaction, one run per script
615
- group with totals checked against the node, picking the VM version from the
616
- block, Type ID charged as the node charges it, named flamegraphs checked against
617
- the deployed binary, report diffs, and the PR Action.
618
- - **[ckb-devnet-explorer](https://github.com/wildanrhmn/ckb-devnet-explorer)** is a
619
- lightweight explorer for OffCKB devnets that reads the node directly. It names
620
- genesis and project-deployed scripts (including JS contracts on ckb-js-vm),
621
- decodes cells such as DAO, xUDT, Spore and Type ID, and shows each transaction's
622
- fee, size and cycles. It answers "what is in this transaction"; cycle-tools
623
- answers "which script spent the cycles, and why", on testnet and mainnet as well.
624
- The two fit together: a devnet transaction can be saved with `ckb-cycles mock`
625
- and profiled here.
626
- - **[CKB Contract Flow](https://talk.nervos.org/t/ckb-contract-flow-visual-cell-transition-explainers-on-chain-tx-decoder-for-46-ckb-contracts/11014)**
627
- ([repo](https://github.com/gpBlockchain/ckb-contract-flow-html)) explains the
628
- cell transition rules of 46 contracts as visual pages, and its decoder splits a
629
- testnet or mainnet transaction into script groups and checks each contract's
630
- rules. It explains what a script requires; it does not run scripts or measure
631
- cycles. Cycle-tools runs them and measures, without explaining the rules.
632
- - **[CKBadger](https://talk.nervos.org/t/ckbadger-a-local-first-ckb-native-explorer-and-a-vibe-coding-experiment/10276)**
633
- ([repo](https://github.com/janx/ckbadger)) is a local-first explorer built around
634
- the cell model, syncing from a node and showing mainnet and testnet side by side.
635
- It is for browsing the chain; cycle-tools looks at one transaction at a time and
636
- only at its execution cost.
637
- - **[CellScript](https://github.com/CellScript-Labs/CellScript)**'s
638
- [cost report](https://talk.nervos.org/t/cellscript-0-30-abstractions-bytes-and-the-cost/10732)
639
- compares executable bytes and cycles of matched CellScript and hand-written Rust
640
- contracts, with acceptance and rejection cases on both sides. It is a language
641
- project measuring its own compiler output, and the method is close to this
642
- repository's ckb-js-vm vs Rust harness. The two are complementary: a
643
- `cycles.json` and the PR Action could track such pairs on every change, with
644
- per-function diffs, rather than only at release time.
645
-
646
- ## Licence
647
-
648
- MIT. See [LICENSE](LICENSE).
649
-
650
- ## Author
651
-
652
- Luong Thanh Tung — [@luongthanhtung03](https://github.com/luongthanhtung03)
1
+ # ckb-cycle-tools
2
+
3
+ Cycle measurement for CKB on-chain scripts.
4
+
5
+ **Live demo:** [ckb-cycle-tools.vercel.app](https://ckb-cycle-tools.vercel.app/) — paste a testnet tx hash, see cycles and script groups (CKB testnet).
6
+
7
+ **Status: v1.0.** Built in the open during my CKBuilder programme.
8
+
9
+ | When | Milestone |
10
+ |---|---|
11
+ | w/c 5 Oct 2026 | ✅ Scaffold, CI, the Windows `ckb-debugger` shim fix |
12
+ | w/c 12 Oct | ✅ CLI: per-script cycle table for a transaction |
13
+ | w/c 19 Oct | ✅ Failure-path profiling; ✅ CI on Linux and Windows |
14
+ | w/c 26 Oct | ✅ ckb-js-vm vs Rust comparison harness |
15
+ | w/c 2 Nov | v1.0 on npm |
16
+
17
+ ## The problem
18
+
19
+ Every CKB script consumes cycles, and cycles are a hard limit rather than a
20
+ suggestion. But finding out how many a script uses — and *which part* of it is
21
+ expensive — currently means driving `ckb-debugger` by hand and reading raw output.
22
+
23
+ There is no convenient way to answer the two questions people actually have:
24
+
25
+ 1. How many cycles does this script use, on the transactions it will really see?
26
+ 2. Which implementation is cheaper, and by how much?
27
+
28
+ ## What this is meant to be
29
+
30
+ - A **cycle profiler** that reports usage per script for a given transaction,
31
+ including the failure paths rather than only the happy one.
32
+ - A **comparison harness** that runs the *same* assertion set against two
33
+ implementations — ckb-js-vm and native Rust — and reports both, so the comparison
34
+ is like-for-like instead of anecdotal.
35
+ - The **Windows toolchain fixes** from my Week 1 findings: `ckb-testtool` cannot find
36
+ the `ckb-debugger` that offckb installs, because a `.cmd` shim is invisible to a
37
+ bare-name `child_process` spawn. That blocks every contract test on Windows, and
38
+ the workaround should not have to be rediscovered by everyone who hits it.
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.3.0, ESM, Node 20 or
48
+ later). It drives `ckb-debugger`, which must be on PATH or passed with `--debugger`.
49
+
50
+ ## Try it
51
+
52
+ ```bash
53
+ npm install
54
+ npm test # unit tests, no network needed
55
+ npm run demo # the Next.js web demo at http://localhost:3000
56
+ npm run analyze:testnet -- <tx hash> [<tx hash> …]
57
+ npm run cycles -- <tx hash> # per-group cycles via ckb-debugger
58
+ ```
59
+
60
+ The demo takes a CKB testnet transaction hash and shows the total cycles the node
61
+ spent verifying it, and every **script group** that ran. CKB runs each script once
62
+ per group: input locks grouped by lock script, type scripts grouped across inputs and
63
+ outputs. Output locks never run. Links are shareable: `?tx=<hash>`.
64
+
65
+ ### What it already shows
66
+
67
+ Real testnet transactions from my CKBuilder work:
68
+
69
+ | Transaction | Cycles | Script groups |
70
+ |---|---|---|
71
+ | [Plain CKB transfer](https://testnet.explorer.nervos.org/transaction/0x52a1b3ba45a28614c30ddc52f0795c164141abbebd1558e6c69fb0ac45fada50) | 1,657,727 | 1 lock |
72
+ | [Counter Type Script update (ckb-js-vm)](https://testnet.explorer.nervos.org/transaction/0x64f695a23416d9a7b2d34bb7025140c90991b82e9f1dea98e103bc13a72b77ac) | 15,675,038 | 1 lock + 1 type |
73
+ | [Script deployment with Type ID](https://testnet.explorer.nervos.org/transaction/0xa21da18ff3f142127cf63d6e705d64c14577fb99a9a0cbf74f47fb70b6ad66cf) | 2,607,561 | 1 lock + Type ID |
74
+
75
+ The counter's type script, running on ckb-js-vm, costs roughly ten times a standard
76
+ lock. Which part of that is the JavaScript VM and which is the script itself is what
77
+ the per-group breakdown (the CLI, below) and the ckb-js-vm vs Rust harness are for.
78
+
79
+ ## Per-script cycles: the `ckb-cycles` CLI
80
+
81
+ The web demo shows the total the node reports. The CLI goes further: it rebuilds
82
+ the transaction as a ckb-debugger mock transaction (every input cell, every cell
83
+ dep, dep groups expanded), runs `ckb-debugger` once per script group, and checks
84
+ that the groups add up to exactly what the node reported.
85
+
86
+ ```
87
+ $ npm run cycles -- 0x64f695a23416d9a7b2d34bb7025140c90991b82e9f1dea98e103bc13a72b77ac
88
+
89
+ GROUP SCRIPT RUN AT RESULT CYCLES SHARE
90
+ lock Secp256k1Blake160 input.0.lock ok 1,652,198 10.5%
91
+ type 0x3e9b6b…18bed7 input.0.type ok 14,022,840 89.5%
92
+
93
+ measured (sum of groups) 15,675,038
94
+ reported by node 15,675,038 ✓ match
95
+ ckb-debugger 1.1.1 · testnet · https://testnet.ckb.dev/
96
+
97
+ input.0.type logged:
98
+ [DEBUG] counter: 1 input(s) -> 1 output(s)
99
+ [DEBUG] counter incremented 2 -> 3
100
+ ```
101
+
102
+ So in that transaction, **89.5% of the cost is the counter Type Script running on
103
+ ckb-js-vm**. Type ID is verified natively by the node and cannot run in
104
+ ckb-debugger; the CLI charges it the node's fixed `TYPE_ID_CYCLES` (1,000,000), and
105
+ the totals still match exactly.
106
+
107
+ **Header-reading scripts replay too.** Each input cell carries the block it was
108
+ created in, so a script that reads its input's header (as a Nervos DAO withdrawal
109
+ does) sees what it saw on the node, as long as the transaction lists that block in
110
+ `header_deps`, which the node requires as well. Before this, a
111
+ [DAO withdrawal](https://testnet.explorer.nervos.org/transaction/0xe8776bb8eb039365be9679cd61870cdc7ea3c24e4f2164fdd5d5f103bdfa2cc5)
112
+ replayed with NervosDao exiting 2 (header missing) and a total 8,058 cycles short;
113
+ it now matches the node's 1,776,369 exactly, and CI checks it.
114
+
115
+ The replay is exact for what a script can observe through syscalls: cells, data,
116
+ witnesses, headers. **Older transactions replay on the VM they ran on:** a
117
+ `hash_type: "type"` script runs on the CKB-VM version of its block's epoch (v0
118
+ before Mirana, v1 before Meepo, v2 since), so a 2023 testnet transaction matches
119
+ the node only on v1, and the CLI picks it from the block. The hardfork epochs come
120
+ from the node it asks (`get_consensus`), never from a flag: `--rpc` with a mainnet
121
+ node gives mainnet's schedule with or without `--mainnet`, and `--mainnet` with a
122
+ node that serves another chain stops with an error. The output ends with the
123
+ ckb-debugger version, that VM version, the network and the node used, so a result
124
+ can be reproduced.
125
+
126
+ Some public nodes report `0x0` cycles for older blocks; the CLI then says the node
127
+ did not record them instead of claiming a mismatch (`--rpc` another node to
128
+ compare). A script that faults in the VM (invalid instruction, cycle limit) shows
129
+ as a rejection with the VM's message, Type ID is checked as the node checks it,
130
+ and a script's logs can neither fake its result nor send control characters to
131
+ your terminal: only ckb-debugger's final lines are read, they must agree with its
132
+ exit code, and a run that prints more than 64 MB is an error, never parsed.
133
+
134
+ Exit codes: **0** every script accepts (and the sum matches the node's); **1** a
135
+ script rejects, or the sum differs from the node's; **2** a usage or environment
136
+ error: bad arguments, a node that cannot be reached or does not answer within
137
+ `--timeout` (default 30 s), a transaction the node does not have (or rejected),
138
+ ckb-debugger missing or printing something it cannot read. So `test $? = 1`
139
+ asserts a rejection without passing when the node is down. CI runs the CLI against
140
+ live testnet transactions on a clean machine. `--json` for machine output,
141
+ `--mainnet` or `--rpc <url>` for another node (at most 16 requests in flight).
142
+ Your own scripts show as a short code
143
+ hash; name them with `--name <code-hash>=<label>` (repeatable, optionally
144
+ `<code-hash>:<hash-type>=…`), or `profileTransaction(tx, { scriptNames })` from code.
145
+ The web page does the same: click a script for its full code hash and a name box
146
+ (saved in that browser), and it prints the CLI command for the per-group breakdown
147
+ with those names filled in. ckb-debugger is found the same way
148
+ as everywhere else in this repo (see the Windows fix above).
149
+
150
+ ### In the browser: per-group cycles on the web page
151
+
152
+ The page's **per-group cycles** button runs the same replay without installing
153
+ anything: ckb-debugger's WebAssembly build (0.200.1, shipped in `ckb-testtool`)
154
+ runs in a Web Worker through a WASI shim, with the mock transaction as an
155
+ in-memory file. It downloads ~4 MB (about 1.1 MB compressed) only when pressed,
156
+ then shows each group's result, cycles, share and logs, and whether the total
157
+ matches the node. It gives the same numbers as the native ckb-debugger 1.1.1:
158
+ 15,675,038 (counter), 2,607,561 (Type ID deploy) and 1,787,335 (a 2023, VM v1
159
+ transaction), and `test/wasm.test.ts` checks that offline on recorded transactions.
160
+ From code: `wasmRunner(module, tx)` from `ckb-cycle-tools/wasm` plugs into
161
+ `replayGroups` from `ckb-cycle-tools/replay`, neither of which uses Node built-ins.
162
+
163
+ ### Before you send: the failure path
164
+
165
+ `--file` profiles a transaction that is not on chain — one you are about to send,
166
+ or one the node rejected — and shows which script refuses it, with its exit code
167
+ and what it cost to get there. It reads the node's RPC JSON, a `get_transaction`
168
+ result, or a CCC transaction saved with `ccc.stringify(tx)`.
169
+
170
+ Here a real [session-lock spend](https://testnet.explorer.nervos.org/transaction/0x48b3bde2a50bb8ba3aff0800e850b2aa521793b35628d165eab7f22f984be828)
171
+ of exactly its 100 CKB limit, edited to pay one shannon more
172
+ ([`test/fixtures/session-lock-overspend.json`](test/fixtures/session-lock-overspend.json)):
173
+
174
+ ```
175
+ $ npx -p ckb-cycle-tools ckb-cycles --file session-lock-overspend.json
176
+ tx not on chain
177
+
178
+ GROUP SCRIPT RUN AT RESULT CYCLES SHARE
179
+ lock 0x1ae8b8…26bc20 input.0.lock exit 12 12,893 0.8%
180
+ lock Secp256k1Blake160 input.1.lock exit -31 1,642,194 99.2%
181
+
182
+ sum of groups, each run on its own 1,655,087
183
+ not what the node spends: it stops at the first failing group, input.1.lock (Secp256k1Blake160),
184
+ and reports no cycles for a rejected tx (it runs lock groups, then type groups,
185
+ each in script-hash order)
186
+ the node never runs: input.0.lock
187
+ ```
188
+
189
+ The session lock refuses with its code 12 (outflow over `max_per_tx`) after
190
+ 12,893 cycles; the secp256k1 lock fails too, because the edit invalidated the
191
+ signature. CI replays this file and requires exactly that refusal.
192
+
193
+ **What a rejected transaction's numbers mean.** The CLI runs every group on its
194
+ own, so you see every script that refuses, not only the first. The node does not
195
+ work that way. ckb-script's `TransactionScriptsVerifier::verify` runs the groups
196
+ one after another and returns at the first error, with no cycle count; a
197
+ rejected transaction has no cycles on the node at all. Its order is every lock
198
+ group, then every type group, each sorted by script hash (two `BTreeMap`s keyed by
199
+ script hash, locks chained before types), which is not the order the CLI lists
200
+ them in (first appearance). So for a rejected transaction the sum is labelled as
201
+ what it is, and the CLI names the group the node would stop at and the groups it
202
+ would never run. Above, the secp256k1 lock's script hash sorts first, so the node
203
+ rejects on the signature and never runs the session lock. In `--json` and in a
204
+ report's JSON, the scenario or profile gets `nodeStopsAt` (that group's selector)
205
+ and every group gets `nodeReaches: true | false`; both are absent when every
206
+ group accepts, so reports of accepted transactions are unchanged. The same
207
+ applies to a transaction whose groups each accept but together pass the node's
208
+ per-transaction cycle limit (see Max cycles below): it gets `overTxLimit:
209
+ { limit, sum }` too, and `nodeStopsAt` names the group at which the running
210
+ sum, in the node's order, passes the limit. Sources, from
211
+ ckb `develop` at
212
+ [a4aa128](https://github.com/nervosnetwork/ckb/tree/a4aa1286a45bc1d42c30f6698dc51521c3749b40):
213
+ [`script/src/verify.rs`](https://github.com/nervosnetwork/ckb/blob/a4aa1286a45bc1d42c30f6698dc51521c3749b40/script/src/verify.rs#L180-L197)
214
+ (`verify`, stops at the first failing group) and
215
+ [`script/src/types.rs`](https://github.com/nervosnetwork/ckb/blob/a4aa1286a45bc1d42c30f6698dc51521c3749b40/script/src/types.rs#L642-L666)
216
+ with [L865-L868](https://github.com/nervosnetwork/ckb/blob/a4aa1286a45bc1d42c30f6698dc51521c3749b40/script/src/types.rs#L865-L868)
217
+ (group order). Which group fails first is computed, not observed: no node has
218
+ been asked to confirm it for a rejected transaction yet.
219
+
220
+ In code: `profileTransaction(readTransactionJson(json))`, or pass an RPC-shaped
221
+ transaction object directly; `nodeOrder(groups)` and `nodeStop(groups)` give the
222
+ node's order and where it stops.
223
+
224
+ ### What comes from where when replaying
225
+
226
+ A replay rebuilds everything a script can observe from the chain, and takes the
227
+ rest from the node it asks or from ckb-debugger's defaults:
228
+
229
+ | Input to the replay | Where it comes from |
230
+ |---|---|
231
+ | Input cells (output, data) | The original chain via RPC: `get_transaction` of the transaction that created each cell, so a spent cell replays as it was, not from the live cell set |
232
+ | Cell deps, dep groups | Same, from the creating transactions; a dep group's cell is read and every cell it lists added as a code dep |
233
+ | Input cell headers | The block that created each input cell (its `block_hash`), as on the node; a script sees it only if the transaction lists it in `header_deps`, as on the node |
234
+ | Header deps | `get_header` for each hash in the transaction's `header_deps` |
235
+ | Witnesses, outputs, outputs data | The transaction itself (from `get_transaction`, or the `--file` you pass) |
236
+ | Hardfork epochs (consensus) | The node's current `get_consensus` (RFC 0032 for CKB-VM v1, RFC 0049 for v2); a built-in table only when the public node of `--mainnet`/testnet cannot say |
237
+ | CKB-VM version | For `hash_type: "type"` scripts: the version at the epoch of the transaction's block, from `get_header`, on those consensus epochs. `data`, `data1`, `data2` name their own. A transaction not on chain (`--file`) gets v2, today's version, not one read from the node |
238
+ | Max cycles | ckb-debugger's default, 3,500,000,000 **per group** (each group is its own run). The node's limit is **per transaction**: in a block, each transaction is verified with the consensus `max_block_cycles` (3,500,000,000 on mainnet and testnet), the remaining budget shrinking group by group, and the block's sum must stay under it too. So a transaction whose groups each fit but together exceed the limit passes ckb-debugger and fails on the node; the CLI, `report` and `diff` flag it ("over the node's per-transaction limit ...: the node would reject this transaction (exceeded max cycles)", `overTxLimit` in the JSON, exit 1), with the node's `max_block_cycles` from `get_consensus` when the replay asked the node, else 3,500,000,000. A gated `diff` fails on a scenario newly over it |
239
+ | Group order | Here: first appearance, every group run, failures included. Node: lock groups then type groups, each by script hash, stopping at the first failure (see above) |
240
+ | Type ID | Not a binary: checked here as the node checks it, and charged the node's fixed `TYPE_ID_CYCLES` (1,000,000) |
241
+ | Since, capacity, maturity checks | Not replayed: the node checks them outside any script, so a script-level replay cannot see them |
242
+ | Script names | CCC's known-script table for the network, and your `--name`s; labels only |
243
+
244
+ The node's own verification lives in
245
+ [`verification/contextual/src/contextual_block_verifier.rs`](https://github.com/nervosnetwork/ckb/blob/a4aa1286a45bc1d42c30f6698dc51521c3749b40/verification/contextual/src/contextual_block_verifier.rs#L413-L466)
246
+ (per-transaction limit and block sum) and ckb-debugger's default in
247
+ [`ckb-debugger/src/main.rs`](https://github.com/nervosnetwork/ckb-standalone-debugger/blob/740d6de0c1d7c2394a492f9bfef57e77abb98dfd/ckb-debugger/src/main.rs#L44)
248
+ of v1.1.1. A node's transaction pool also has a `max_tx_verify_cycles` setting
249
+ in its `ckb.toml`: a local setting, not consensus.
250
+
251
+ ### Inside a script: flamegraphs
252
+
253
+ `ckb-cycles flame` shows where inside each script the cycles go. It runs every
254
+ script group in ckb-debugger's flamegraph mode, merges the stacks, names the
255
+ frames by function, prints the costliest ones and writes an SVG flamegraph and
256
+ a folded-stack file per group (open the `.folded` in
257
+ [speedscope](https://www.speedscope.app/) for an interactive view).
258
+
259
+ Deployed scripts are stripped, so a profile of one is a single frame. Give an
260
+ unstripped build of the same code with `--bin <code-hash>=<elf>`; the tool runs
261
+ the group with both binaries and says whether the cycles agree, so you know the
262
+ graph describes the deployed code. Here, a real
263
+ [subscription charge](https://testnet.explorer.nervos.org/transaction/0x50ae6df49d411a5766da1c9717da9e6ff34670194b389779f717fcee71a03092)
264
+ of the ckb-session-kit lock, with that lock built with symbols
265
+ (`CARGO_PROFILE_RELEASE_STRIP=false cargo build --release`):
266
+
267
+ ```
268
+ $ npx -p ckb-cycle-tools ckb-cycles flame 0x50ae6df4…a03092 --script input.0.lock \
269
+ --bin 0xab419466…4c08ce=target/riscv64imac-unknown-none-elf/release/session-lock
270
+ input.0.lock 0xab4194…4c08ce ok 20,999 cycles
271
+ --bin …/session-lock: same cycles as the deployed binary
272
+ profiled 19,187 cycles (loading the binary is not profiled)
273
+ SELF TOTAL FUNCTION
274
+ 4,490 5,972 session_lock::lock_hash
275
+ 3,145 3,145 compiler_builtins::mem::memcpy
276
+ 2,545 18,678 __ckb_std_main
277
+ 2,156 2,156 session_lock::has_type
278
+ 2,076 2,076 memcmp
279
+ → flame/input.0.lock.svg, flame/input.0.lock.folded
280
+ ```
281
+
282
+ Reading the lock hashes of the transaction's cells is the lock's largest cost.
283
+ The profile covers the instructions the script ran; the difference (1,812 cycles
284
+ here) is what the VM charges outside instructions, such as loading the binary and
285
+ the bytes each syscall copies, counted by the node but in no frame.
286
+
287
+ **A script that spawns another** (CKB2023 `spawn`): its group's cycles include
288
+ every script it spawned, as on the node, and the CLI and report say how many it
289
+ spawned. The functions are the spawning script's own: ckb-debugger profiles only
290
+ that one, and `--bin` replaces only its binary, so the spawned scripts' work is
291
+ in the total but in no frame. [`test/fixtures/spawn-project`](test/fixtures/spawn-project)
292
+ is such a pair.
293
+
294
+ **Flamegraph fidelity: what is exact and what is attributed.** The group's cycle
295
+ total is exact: it is ckb-debugger's run of the deployed binary, the same number
296
+ the node counts (and `--bin` checks that the symbols build costs the same). How
297
+ that total is split between functions is reconstructed. ckb-debugger's profiler
298
+ (`machine_analyzer.rs` in
299
+ [v1.1.1](https://github.com/nervosnetwork/ckb-standalone-debugger/blob/740d6de0c1d7c2394a492f9bfef57e77abb98dfd/ckb-debugger/src/machine_analyzer.rs))
300
+ charges each instruction's cost (ckb-vm's cost model) to the current frame, and
301
+ opens a frame only when a `jal`/`jalr` jumps to an address the ELF symbol table
302
+ lists as a function start. So:
303
+
304
+ - inlined code has no symbol of its own and is charged to the function it was
305
+ inlined into, so an optimised build shows fewer, heavier frames than the source
306
+ has functions, and moving code between inlined and not changes the split
307
+ without changing the total;
308
+ - frames are named with the binary's DWARF info where it has some, and otherwise
309
+ from the symbol table (this tool fills in the `func_0x…` frames the profiler
310
+ could not name);
311
+ - cycles the VM charges outside instructions (loading the binary, bytes copied by
312
+ syscalls) are in no frame, so the profile is a little under the group total and
313
+ the CLI prints both;
314
+ - spawned scripts are in the total but in no frame (above).
315
+
316
+ Per-function numbers are therefore exact sums of the instructions attributed to
317
+ each frame, but which frame gets them depends on the build's inlining and symbols.
318
+ Compare functions only between builds with the same profile.
319
+
320
+ **In the browser:** drop the `.folded` file on the
321
+ [web inspector](https://ckb-cycle-tools.vercel.app/) ("inside a script"), or open
322
+ its example, and it draws the same flamegraph and table. Nothing is uploaded.
323
+ (The page's WebAssembly ckb-debugger can profile but not name functions, so the
324
+ profile itself comes from the CLI.)
325
+
326
+ In code: `flameTransaction(target, { bins, readFile })`, then `functionCosts`,
327
+ `flameTree` and `renderFlameSvg` from `ckb-cycle-tools/flame` (no Node
328
+ built-ins, so the browser can draw the same graph).
329
+
330
+ ## Cycle reports on pull requests
331
+
332
+ A change to a script should say what it did to that script's cycles, and above
333
+ all whether any accept turned into a reject. `ckb-cycles report` replays every
334
+ scenario in a [`cycles.json`](cycles.json) and records each script group's result
335
+ and cycles; `ckb-cycles diff` compares two such reports; the
336
+ [GitHub Action](action/README.md) runs both on a PR (the PR's build against its
337
+ base's) and keeps one comment up to date.
338
+
339
+ Scenarios are best kept as ckb-debugger mock transactions, so CI needs no node:
340
+ this repo's five are written by `benchmarks/session-lock/mocks.mjs`, and
341
+ `ckb-cycles mock <tx-hash> -o file.json` saves any transaction that way.
342
+ `binaries` swaps the deployed code for the one just built (the rules for
343
+ `type` vs `data*` hash types are in the [Action's README](action/README.md#cyclesjson)).
344
+ For a cycles.json from a pull request, `--root <dir>` (repeatable) refuses any
345
+ file it names outside those directories, and ignores its `"rpc"` (with a
346
+ warning; `--rpc` still applies). Mocks with ckb-debugger template directives
347
+ (`{{ data <path> }}`, `{{ hash <path> }}`, …), or a field that should be hex and is not, are
348
+ refused, with or without `--root`.
349
+
350
+ With `--fail-above` or `--fail-on-result-change` set, `diff` fails on anything
351
+ it could not check, not only on what it measured: a scenario either side could
352
+ not run, an error in either report (a binary that matched no cell dep in any
353
+ scenario is in the report JSON's `"errors"`), and a base group with nothing in
354
+ the head to compare against (a scenario or group removed, renamed or moved, or
355
+ measured without its binary); `--allow-removed` accepts the last. A group the VM
356
+ stopped (past the cycle limit, a bad instruction) is a result change, and over
357
+ any `--fail-above` threshold, never a -100% saving; two different VM errors are
358
+ two different results. A group that accepted on the base and rejects on the
359
+ head (`ok` → `exit 5`, or a VM error) fails `--fail-above` too, whatever its
360
+ cycles: a cheaper rejection is not a saving. `--fail-on-result-change` is
361
+ broader: it also fails on a rejection that now accepts, one exit code turning
362
+ into another, and a new group that does not accept. With `--binaries-from`, a binary missing from that
363
+ checkout is left as the mock has it: only the groups whose code it is are not
364
+ compared, and every other binary is still swapped in. A binary offered to a
365
+ scenario that matches none of its cell deps is a warning on that scenario, in
366
+ the comment too. The summary says when the two reports come from different
367
+ ckb-debugger versions.
368
+
369
+ #### What a report was measured with: the manifest
370
+
371
+ Each report's JSON has a `manifest` (from 1.3.0 on): the ckb-cycle-tools version,
372
+ ckb-debugger's `--version` and the sha256 of the binary every scenario ran (or a
373
+ WebAssembly build's id, when a library caller runs one), the git commit of the
374
+ checkout the cycles.json is in (and of `--binaries-from`; none outside a git
375
+ checkout), an optional `--toolchain <text>` (say, `rustc -V` and the build
376
+ profile), and per scenario the CKB-VM version, an `inputs` sha256 and each
377
+ swapped-in binary's path, sha256 and size. `inputs` covers what decides what a
378
+ scenario runs: the bytes of its mock or transaction file as read, and its
379
+ cycles.json entry without its name or file path (its form, transaction hash,
380
+ `binaries` list, `scriptVersion`, and the network for a transaction fetched
381
+ from a node).
382
+
383
+ `diff` reads both manifests. A scenario whose `inputs` differ between base and
384
+ head did not measure the same transaction: its groups are **NOT COMPARED:
385
+ inputs changed**, and a gated diff (`--fail-above` or `--fail-on-result-change`)
386
+ fails on it unless `--allow-changed-inputs`. Another ckb-debugger (version,
387
+ binary, or native against WebAssembly) or another CKB-VM version for a scenario
388
+ fails a gated diff with the reason listed under the summary, and is a
389
+ prominent note otherwise. A different toolchain is a note. A report without a
390
+ manifest (written before 1.3.0) on one side is a note, never a failure; two
391
+ such reports diff as they always did. Every manifest string (a toolchain, a
392
+ path) is cleaned like any other report text before it reaches a terminal or a
393
+ comment.
394
+
395
+ Here the ckb-js-vm session lock was changed to allow one shannon more than its
396
+ limit and to do extra work per recipient check:
397
+
398
+ ```
399
+ $ npx -p ckb-cycle-tools ckb-cycles report cycles.json --json base.json
400
+ $ npx -p ckb-cycle-tools ckb-cycles report cycles.json --binaries-from ../pr --json head.json
401
+ $ npx -p ckb-cycle-tools ckb-cycles diff base.json head.json --fail-above 1
402
+ 1 result change, 1 over the 1% threshold, 5 of 10 script groups changed
403
+ ```
404
+
405
+ | Scenario | Group | Script | Base | Head | Δ | Δ% | |
406
+ |---|---|---|---:|---:|---:|---:|---|
407
+ | one shannon over max\_per\_tx | `input.0.lock` | session-lock (ckb-js-vm) | 14,544,014 (exit 12) | 14,557,318 | +13,304 | +0.09% | **RESULT CHANGED: exit 12 → ok** |
408
+ | pays the allowed recipient | `input.0.lock` | session-lock (ckb-js-vm) | 14,768,645 | 15,465,881 | +697,236 | +4.72% | **over 1%** |
409
+ | spend exactly max\_per\_tx | `input.0.lock` | session-lock (ckb-js-vm) | 14,544,018 | 14,557,320 | +13,302 | +0.09% | |
410
+
411
+ That table (with `--markdown`) is what the PR comment shows; unchanged groups
412
+ fold away below it. This repo runs the Action on its own pull requests
413
+ ([`.github/workflows/cycle-report.yml`](.github/workflows/cycle-report.yml)).
414
+
415
+ The PR's build is the PR's code. In the Action's one-job setup it runs in the
416
+ job that also holds the comment's token (`pull-requests: write`; read-only for
417
+ a PR from a fork): the Action keeps what the build writes to `$GITHUB_PATH` and
418
+ `$GITHUB_ENV` away from that token, but a build that leaves a process running
419
+ or replaces files on the runner can still take it. For pull requests you would
420
+ not trust with it, the [two-job setup](action/README.md#two-jobs-the-build-never-shares-a-runner-with-the-comment-token)
421
+ builds with a read-only token and posts from a second job that runs no PR code
422
+ (`action/comment`). Check out with `persist-credentials: false` either way.
423
+
424
+ ### Which functions changed
425
+
426
+ A row says a group got 3% dearer; the flamegraph mode can say where. Give a
427
+ binary an unstripped build of the same code as `symbols`, and ask for
428
+ `functions`, for every scenario or per scenario:
429
+
430
+ ```json
431
+ {
432
+ "functions": true,
433
+ "binaries": {
434
+ "my-lock": {
435
+ "path": "build/release/my-lock",
436
+ "symbols": "build/release/my-lock.debug",
437
+ "codeHash": "0x…"
438
+ }
439
+ },
440
+ "scenarios": [{ "name": "spend", "mock": "tests/mocks/spend.json" }]
441
+ }
442
+ ```
443
+
444
+ For each group whose script is that binary, `report` runs the group again in
445
+ ckb-debugger's flamegraph mode with `--bin <symbols>` and records the 15
446
+ costliest functions (self and total cycles) in the report. It first checks that
447
+ the symbols build costs exactly the cycles of the binary it stands for; if not,
448
+ it is not the same code, and the group gets a warning instead of functions.
449
+ Code the debugger has no line info for (ckb-std's `_start`, the allocator shims
450
+ rustc adds) it calls `func_0x<address>`; those frames take their name from the
451
+ build's ELF symbol table, so a function that moved between builds is not a
452
+ removal and an addition in a diff. `diff --markdown` then adds a folded block under the table for each changed
453
+ group: the functions whose self cycles changed, base, head and Δ, the ten
454
+ largest changes first. A report without functions (an older base, or a
455
+ config without `symbols`) still diffs as before; a function shows `—` where
456
+ its cycles are not known on that side.
457
+
458
+ A Rust build keeps its symbols with `CARGO_PROFILE_RELEASE_STRIP=false`; build
459
+ it next to the stripped one, from the same commit.
460
+
461
+ ### From ckb-testtool tests (ckb-script-templates projects)
462
+
463
+ A project made from
464
+ [ckb-script-templates](https://github.com/nervosnetwork/ckb-script-templates)
465
+ already has its scenarios: the Rust tests in `tests/`, on ckb-testtool. Each
466
+ test can leave its transaction behind as a mock, and `ckb-cycles scan` writes
467
+ the cycles.json from them, so nothing is written by hand.
468
+
469
+ 1. In the tests crate, add the helper in
470
+ [`integrations/ckb-testtool`](integrations/ckb-testtool/src/lib.rs) and call
471
+ it where a test calls `context.verify_tx`:
472
+
473
+ ```toml
474
+ # tests/Cargo.toml
475
+ [dependencies]
476
+ ckb-cycles-testtool = { git = "https://github.com/luongthanhtung03/ckb-cycle-tools" }
477
+ ```
478
+
479
+ ```rust
480
+ let cycles = ckb_cycles_testtool::verify_tx(&context, &tx, MAX_CYCLES).expect("pass verification");
481
+ ```
482
+
483
+ The tests `make generate` writes call `context.verify_tx(&tx, 10_000_000)`
484
+ over two lines; one substitution changes them all:
485
+
486
+ ```
487
+ perl -0pi -e 's/context\s*\.verify_tx\(&tx,/ckb_cycles_testtool::verify_tx(&context, &tx,/g' tests/src/tests.rs
488
+ ```
489
+
490
+ It returns what `context.verify_tx` returns. When `CKB_CYCLES_MOCKS` names a
491
+ directory, it also writes `context.dump_tx(&tx)` there, accepted or rejected,
492
+ named after the test: `tests::test_transfer` is `tests.test_transfer.json`, a
493
+ second transaction in the same test `tests.test_transfer-2.json`. Without the
494
+ variable it writes nothing. (It is about 40 lines; copying it into
495
+ `tests/src/lib.rs` works as well.)
496
+
497
+ 2. Add a target to the workspace Makefile:
498
+
499
+ ```make
500
+ CKB_CYCLES ?= npx -y -p ckb-cycle-tools ckb-cycles
501
+ CYCLES_MOCKS := target/ckb-cycles
502
+
503
+ cycles-config: build
504
+ rm -rf $(CYCLES_MOCKS)
505
+ CKB_CYCLES_MOCKS="$(abspath $(CYCLES_MOCKS))" cargo test -p tests
506
+ $(CKB_CYCLES) scan $(CYCLES_MOCKS) --binaries $(BUILD_DIR) --functions -o cycles.json
507
+
508
+ cycles: cycles-config
509
+ $(CKB_CYCLES) report cycles.json
510
+ ```
511
+
512
+ The npm package is `ckb-cycle-tools`; its command is `ckb-cycles`, so a
513
+ project with no package.json needs `npx -p ckb-cycle-tools` (a bare
514
+ `npx ckb-cycles` looks for a package of that name). `scan` needs 1.1.0 or
515
+ later; to run a checkout instead, point the variable at it,
516
+ `make cycles CKB_CYCLES="node ../ckb-cycle-tools/dist/cli.js"`.
517
+
518
+ `make cycles` then builds the contracts, runs the tests, and reports each
519
+ test's script groups, with the costliest functions of your own contracts. The
520
+ fixture project below, its two steps run by hand:
521
+
522
+ ```
523
+ $ npx -p ckb-cycle-tools ckb-cycles scan mocks --binaries build/release --functions -o cycles.json
524
+ cycles.json: 6 scenario(s), 1 binary (args-loop)
525
+ code cells that are none of the binaries: 0xe683b041…3660d7
526
+ $ npx -p ckb-cycle-tools ckb-cycles report cycles.json
527
+ SCENARIO GROUP SCRIPT RESULT CYCLES
528
+ tests.test_beside_always_success input.0.lock args-loop ok 95,392
529
+ tests.test_beside_always_success input.1.lock 0x91b570…218629 ok 2,107
530
+ tests.test_empty_args_rejected input.0.lock args-loop exit 5 2,186
531
+ tests.test_heavy_spend input.0.lock args-loop ok 468,128
532
+ tests.test_light_spend input.0.lock args-loop ok 25,504
533
+ …
534
+ tests.test_heavy_spend input.0.lock: costliest functions (self cycles): args_loop::work 440,320, _start 26,713, memset 230
535
+ ```
536
+
537
+ `scan` makes one `"mock"` scenario per file, and one binary per file in
538
+ `--binaries` (default `build/release`) that a test deployed, matched by its data
539
+ hash, with `<name>.debug` (the template's unstripped copy) as its `symbols`. It
540
+ says on stderr which files no test deployed and which code cells are none of
541
+ the binaries (ckb-testtool's always-success, above). The code hashes are those of
542
+ the build the tests ran against, so the cycles.json is regenerated after each
543
+ build, not committed.
544
+
545
+ ckb-testtool gives each deployed cell a Type ID type script and `build_script`
546
+ uses `hash_type: "type"`, so swapping in another build changes only the code.
547
+ On a pull request, make the head's mocks and cycles.json in a step before the
548
+ Action, and let the Action build both sides (the base's tests may not have the
549
+ helper yet):
550
+
551
+ ```yaml
552
+ - run: make cycles-config
553
+ - uses: luongthanhtung03/ckb-cycle-tools/action@<commit-sha>
554
+ with:
555
+ build: make build
556
+ ```
557
+
558
+ [`test/fixtures/testtool-project`](test/fixtures/testtool-project) is a small
559
+ project in the template's layout, with the output above; the design and its
560
+ open questions are in [docs/design/testtool-integration.md](docs/design/testtool-integration.md).
561
+
562
+ [`scripts/templates-e2e.sh`](scripts/templates-e2e.sh) does all of this on a
563
+ real project: it generates a workspace from ckb-script-templates (commit
564
+ `f90b1e2`), adds two contracts with `make generate` (`alpha` from `contract`,
565
+ `beta` from `contract-without-simulator`), applies the two steps above, runs
566
+ `make cycles-config`, then makes `alpha` run a 1,000-step loop and runs it again.
567
+ It fails unless each report agrees with the cycles ckb-testtool itself counted
568
+ and only `alpha` changed. Its run on Linux (rustc 1.99, clang 19, ckb-debugger
569
+ 1.1.1):
570
+
571
+ ```
572
+ SCENARIO GROUP SCRIPT BASE HEAD Δ Δ%
573
+ tests.test_alpha input.0.lock alpha 7,156 19,174 +12,018 +167.94%
574
+ tests.test_beta input.0.lock beta 7,156 7,156 0 0%
575
+
576
+ functions in tests.test_alpha input.0.lock: __ckb_std_main +12,008
577
+ ```
578
+
579
+ The base column is the base's binaries swapped into the head's mocks
580
+ (`report --binaries-from`); it gives the same 7,156 as the base's own tests.
581
+ (The Action measures the base with the base commit's own cycles.json and mocks,
582
+ so a scenario a pull request deletes still shows up, as removed.)
583
+
584
+ ## ckb-js-vm vs Rust: one lock, two implementations
585
+
586
+ `benchmarks/session-lock` holds a TypeScript port of the
587
+ [ckb-session-kit](https://github.com/luongthanhtung03/ckb-session-kit) session lock
588
+ for ckb-js-vm, plain CKB and token sessions (error codes 10-20). It runs the same
589
+ 58 scenarios as the Rust original (ckb-session-kit 49227cd) in the real CKB-VM and
590
+ fails unless both implementations make every accept/reject decision correctly.
591
+
592
+ | | Rust | ckb-js-vm |
593
+ |---|---:|---:|
594
+ | Mean cycles, accepted plain CKB spends | 14,758 | 15,037,968 |
595
+ | Mean cycles, accepted token spends | 20,348 | 15,518,698 |
596
+ | Cheapest run (start-up cost) | 3,145 | 14,272,805 |
597
+
598
+ About 95% of the ckb-js-vm cost is starting the VM; the lock's own logic runs at
599
+ roughly 66× the Rust logic. Full table, and the 8 Oct numbers for comparison:
600
+ [RESULTS.md](benchmarks/session-lock/RESULTS.md).
601
+
602
+ ```bash
603
+ npm run bench:session-lock # needs the Rust lock built in ../ckb-session-kit, or SESSION_LOCK_BIN
604
+ ```
605
+
606
+ CI rebuilds both implementations from source — the Rust lock from a pinned
607
+ ckb-session-kit commit — reruns every scenario, and publishes the table in the
608
+ job summary.
609
+
610
+ ## Mainnet cycle atlas
611
+
612
+ A one-off snapshot of what the scripts in recent mainnet transactions cost, measured
613
+ with the same replay as `ckb-cycles <tx-hash>`:
614
+ [atlas/2026-10-28/report.md](atlas/2026-10-28/report.md), raw results in
615
+ [data.json](atlas/2026-10-28/data.json).
616
+
617
+ 1,000 transactions from every 12th block between 20,835,876 and 20,851,152
618
+ (26 to 27 Oct 2026, about 39 hours), each replayed per script group in
619
+ ckb-debugger 1.1.1. All 1,000 matched the node's cycle totals exactly, so none was
620
+ excluded. secp256k1_blake160 accounts for 93.7% of the cycles, at a median of
621
+ 1,647,788 per group; it runs once per distinct owner, so the costliest transaction
622
+ in the sample (68 owners) cost 111,979,599 cycles. 694 of the 1,000 transactions
623
+ update d.id's on-chain time oracle (two type scripts at about 45k and 33k cycles),
624
+ and the next most expensive type script is the Bitcoin SPV client behind RGB++
625
+ (median 1,369,197). The report lists min, median, p90 and max per script, its
626
+ share, an example transaction, and the cell each script's code came from.
627
+
628
+ The random sample saw no xUDT, Omnilock, Spore or Type ID, so the report has a
629
+ second, separate section of targeted samples: for each of 22 scripts, up to 40 of
630
+ the most recent transactions in which it ran, found with the indexer RPC and
631
+ replayed the same way (653 replays; 601 matched the node, none mismatched, and
632
+ 52 older transactions, all at or before block 19,011,137, have no cycle total
633
+ on the public node and are listed as not recorded). Medians per group from that
634
+ section: xUDT 20,498, Spore 103,953, Cluster 98,683, Omnilock 1,458,708
635
+ (Ethereum displaying) and 1,458,571 (Bitcoin), JoyID 6,844,452, RGB++ lock
636
+ 1,418,522, COTA 1,134,820. These are costs per run, not shares of mainnet.
637
+
638
+ Only a transaction whose groups add up to the node's total is aggregated; any other
639
+ is listed in the report with its reason, never dropped. To reproduce the same window
640
+ (read-only JSON-RPC against a public node, paced and retried; about 25 minutes):
641
+
642
+ ```bash
643
+ npm ci
644
+ npm run atlas -- --rpc https://mainnet.ckb.dev/ --to 20851152 --blocks 15277 --stride 12 --max-txs 1000
645
+ ```
646
+
647
+ Without `--to` it samples back from the current tip; `--out <dir>` chooses where
648
+ `data.json` and `report.md` go, `--resume` continues an interrupted run, and
649
+ `--report-only <dir>` rebuilds the report from an existing `data.json` (and names
650
+ scripts identified since the run). The atlas and its script are part of the
651
+ repository only, not the npm package.
652
+
653
+ Targeted samples are added to an existing atlas folder. `--script` takes a name
654
+ (`xudt`, `omnilock`, `spore`, `cluster`, `type-id`, `joyid`, `rgbpp-lock`,
655
+ `ickb-logic`, `das-lock` and others; an unknown name lists them) or a code hash as
656
+ `<hash>[:<hash type>[:lock|type]]`, optionally narrowed to an args prefix with
657
+ `@<hex>`, e.g. `omnilock@0x04` for Omnilock's Bitcoin auth. The search looks back
658
+ from `--to`, widening five-fold from 20,000 blocks up to `--max-window`, and
659
+ replays the newest `--max-txs` (default 40). The command that made the report's
660
+ section is at the end of the report.
661
+
662
+ ## Across ckb-debugger versions
663
+
664
+ Do the numbers depend on which ckb-debugger you have? `npm run compat` replays the
665
+ same 35 frozen scenarios under every release in
666
+ [compat/debuggers.json](compat/debuggers.json) and compares each script group
667
+ with the reference, 1.1.1 (the release the CLI and CI pin):
668
+ [compat/RESULTS.md](compat/RESULTS.md), raw runs in
669
+ [results.json](compat/results.json).
670
+
671
+ The scenarios are the six ckb-testtool fixture mocks, the five session-lock
672
+ benchmark mocks (ckb-js-vm), the two recorded testnet transactions (one on VM 1),
673
+ and 22 mainnet transactions from the atlas, one per script it sampled (xUDT,
674
+ Omnilock, Spore, Type ID, JoyID, RGB++, iCKB, COTA, Nervos DAO and others). They
675
+ are stored with every cell in
676
+ [compat/scenarios.json.br](compat/scenarios.json.br), so every build reads the
677
+ same bytes and the run needs no network.
678
+
679
+ Measured on 28 Oct 2026 on Windows: native releases 0.121.0, 0.200.0, 0.200.1,
680
+ 0.200.2, 0.203.0, 1.0.0, 1.1.0 and 1.1.1, and the WebAssembly builds of 0.200.1
681
+ to 1.1.1 (the web page's build in ckb-testtool is byte for byte the 0.200.1 one).
682
+ All 455 scenario runs, 1,170 script groups, gave the reference's cycles and exit
683
+ code, and every mainnet and testnet total matched the node. The same
684
+ transactions on another CKB-VM version do cost differently (VM 2 is cheaper than
685
+ VM 1, and VM 0 cannot run most of today's binaries); the results explain each
686
+ case from the hardfork RFCs. That is why the replay takes the VM version from the
687
+ block's epoch, not from the debugger.
688
+
689
+ ```bash
690
+ npm ci
691
+ npm run compat -- fetch # downloads each release into .cache/, sha256 checked
692
+ npm run compat # runs everything (about 2.5 minutes), exits 1 on any mismatch
693
+ ```
694
+
695
+ `--only 1.0.0,1.1.0` limits the releases, `--no-wasm` skips the WebAssembly
696
+ builds, `--no-sweep` skips the VM 0/1/2 sweep, and `npm run compat -- record`
697
+ rebuilds the scenario file (read-only RPC; needs `npm run bench:build` first).
698
+ [.github/workflows/compat.yml](.github/workflows/compat.yml) runs the check with
699
+ the Linux builds weekly and on demand; its first run on GitHub (2 Nov 2026) passed.
700
+
701
+ ## Limits
702
+
703
+ - **It needs a node, or a saved transaction.** Rebuilding a transaction means
704
+ fetching every input cell and cell dep; without RPC access, use a mock file
705
+ (`ckb-cycles mock` saves one) or `--file`.
706
+ - **Type ID is charged, not run.** The node verifies Type ID natively; the tools
707
+ charge its fixed 1,000,000 cycles and check its rules the way the node does.
708
+ - **Two debugger builds.** The CLI uses the native ckb-debugger you install
709
+ (1.1.1 here); the web page uses the WebAssembly build shipped in
710
+ `ckb-testtool` (0.200.1). They agree on every transaction checked, and so do
711
+ the releases in between ([Across ckb-debugger versions](#across-ckb-debugger-versions)),
712
+ but a future CKB-VM change could reach one before the other; each result names
713
+ the version it used.
714
+ - **Flamegraphs need symbols.** On-chain binaries are stripped; `flame` names
715
+ functions only with an unstripped build passed by `--bin` (or `symbols` in a
716
+ cycles.json). The CLI draws the graphs, the PR comment lists the changed
717
+ functions, and the web page draws a `.folded` file the CLI made.
718
+ - **Groups run on their own.** Every group is a separate ckb-debugger run with
719
+ its own 3,500,000,000-cycle limit; the node runs them in its own order under
720
+ one per-transaction limit and stops at the first failure. A rejected
721
+ transaction's sum is labelled as such, and the group the node would stop at
722
+ is computed from ckb-script's order, not yet confirmed by a node. A sum over
723
+ the per-transaction limit is flagged as a rejection, from the summed group
724
+ cycles; no node has been asked to confirm one yet
725
+ ([What comes from where](#what-comes-from-where-when-replaying)).
726
+ - **Older blocks.** Some public nodes report `0x0` cycles for old blocks; the
727
+ tools then say the total is unknown instead of claiming a match. Replays on
728
+ both sides of each VM hardfork, checked against recorded totals where a node
729
+ has them, and why nothing could be checked against a node before Mirana:
730
+ [compat/HARDFORK.md](compat/HARDFORK.md).
731
+ - **The PR Action has run on one public pull request so far**, in this repository:
732
+ [#1](https://github.com/luongthanhtung03/ckb-cycle-tools/pull/1) slows one check of
733
+ the ckb-js-vm benchmark lock on purpose, and the comment reports it (+2.94% on that
734
+ scenario, results unchanged). It has not yet run in another project's repository.
735
+
736
+ ## Why it is a separate repository
737
+
738
+ It started as measurement scaffolding inside a learning exercise. That is a bad place
739
+ for a tool to live if anyone else might want it.
740
+
741
+ ## Related work
742
+
743
+ Other CKB tools touch the same ground. This is what each one does, as far as its
744
+ own documentation says, and where this repository sits next to it.
745
+
746
+ - **[ckb-debugger](https://github.com/nervosnetwork/ckb-standalone-debugger)**
747
+ (nervosnetwork) runs CKB scripts off chain from a mock transaction and reports
748
+ their cycles, with a flamegraph mode. It is the engine everything here drives;
749
+ nothing in this repository re-implements the VM. What is added on top: rebuilding
750
+ a mock transaction from a tx hash or a saved transaction, one run per script
751
+ group with totals checked against the node, picking the VM version from the
752
+ block, Type ID charged as the node charges it, named flamegraphs checked against
753
+ the deployed binary, report diffs, and the PR Action.
754
+ - **[ckb-devnet-explorer](https://github.com/wildanrhmn/ckb-devnet-explorer)** is a
755
+ lightweight explorer for OffCKB devnets that reads the node directly. It names
756
+ genesis and project-deployed scripts (including JS contracts on ckb-js-vm),
757
+ decodes cells such as DAO, xUDT, Spore and Type ID, and shows each transaction's
758
+ fee, size and cycles. It answers "what is in this transaction"; cycle-tools
759
+ answers "which script spent the cycles, and why", on testnet and mainnet as well.
760
+ The two fit together: a devnet transaction can be saved with `ckb-cycles mock`
761
+ and profiled here.
762
+ - **[CKB Contract Flow](https://talk.nervos.org/t/ckb-contract-flow-visual-cell-transition-explainers-on-chain-tx-decoder-for-46-ckb-contracts/11014)**
763
+ ([repo](https://github.com/gpBlockchain/ckb-contract-flow-html)) explains the
764
+ cell transition rules of 46 contracts as visual pages, and its decoder splits a
765
+ testnet or mainnet transaction into script groups and checks each contract's
766
+ rules. It explains what a script requires; it does not run scripts or measure
767
+ cycles. Cycle-tools runs them and measures, without explaining the rules.
768
+ - **[CKBadger](https://talk.nervos.org/t/ckbadger-a-local-first-ckb-native-explorer-and-a-vibe-coding-experiment/10276)**
769
+ ([repo](https://github.com/janx/ckbadger)) is a local-first explorer built around
770
+ the cell model, syncing from a node and showing mainnet and testnet side by side.
771
+ It is for browsing the chain; cycle-tools looks at one transaction at a time and
772
+ only at its execution cost.
773
+ - **[CellScript](https://github.com/CellScript-Labs/CellScript)**'s
774
+ [cost report](https://talk.nervos.org/t/cellscript-0-30-abstractions-bytes-and-the-cost/10732)
775
+ compares executable bytes and cycles of matched CellScript and hand-written Rust
776
+ contracts, with acceptance and rejection cases on both sides. It is a language
777
+ project measuring its own compiler output, and the method is close to this
778
+ repository's ckb-js-vm vs Rust harness. The two are complementary: a
779
+ `cycles.json` and the PR Action could track such pairs on every change, with
780
+ per-function diffs, rather than only at release time.
781
+
782
+ ## Licence
783
+
784
+ MIT. See [LICENSE](LICENSE).
785
+
786
+ ## Author
787
+
788
+ Luong Thanh Tung — [@luongthanhtung03](https://github.com/luongthanhtung03)