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