ckb-cycle-tools 0.0.0-stage → 1.0.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 +44 -0
- package/LICENSE +21 -0
- package/README.md +394 -3
- package/dist/analyze.d.ts +50 -0
- package/dist/analyze.js +95 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +354 -0
- package/dist/debugger.d.ts +28 -0
- package/dist/debugger.js +56 -0
- package/dist/diff.d.ts +152 -0
- package/dist/diff.js +325 -0
- package/dist/flame.d.ts +59 -0
- package/dist/flame.js +179 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +10 -0
- package/dist/mock.d.ts +109 -0
- package/dist/mock.js +197 -0
- package/dist/profile.d.ts +68 -0
- package/dist/profile.js +130 -0
- package/dist/replay.d.ts +154 -0
- package/dist/replay.js +254 -0
- package/dist/report.d.ts +85 -0
- package/dist/report.js +396 -0
- package/dist/substitute.d.ts +41 -0
- package/dist/substitute.js +122 -0
- package/dist/wasm.d.ts +22 -0
- package/dist/wasm.js +51 -0
- package/package.json +68 -6
package/dist/report.js
ADDED
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `ckb-cycles report`: runs every scenario in a `cycles.json` and records the
|
|
3
|
+
* cycles and result of each script group, for `ckb-cycles diff` to compare.
|
|
4
|
+
*
|
|
5
|
+
* A scenario is a transaction in one of three forms:
|
|
6
|
+
* - `"mock"`: a ckb-debugger mock transaction (every cell it touches, inline).
|
|
7
|
+
* Needs no node at all, so it is what CI should use.
|
|
8
|
+
* - `"file"`: a transaction in the node's RPC shape (or CCC's), as `--file` reads
|
|
9
|
+
* it. The cells it spends and depends on are fetched from a node.
|
|
10
|
+
* - `"tx"`: a transaction hash, fetched from a node.
|
|
11
|
+
*
|
|
12
|
+
* `"binaries"` swaps a deployed script for the one built from the commit under
|
|
13
|
+
* test (see substitute.ts for the rules). A binary with `"symbols"` (an
|
|
14
|
+
* unstripped build of the same code) can also say which functions its cycles
|
|
15
|
+
* went to, in scenarios with `"functions": true`.
|
|
16
|
+
*/
|
|
17
|
+
import { readFile, realpath, stat } from "node:fs/promises";
|
|
18
|
+
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
19
|
+
import { FUNCTION_LIMIT, resultLabel } from "./diff.js";
|
|
20
|
+
import { functionCosts } from "./flame.js";
|
|
21
|
+
import { buildMockTransaction, httpRpc, mockFromTransaction, scriptVersionAt } from "./mock.js";
|
|
22
|
+
import { flameTransaction, parseNames, profileTransaction, readTransactionJson } from "./profile.js";
|
|
23
|
+
import { consensusOf, nodeVerdict, PUBLIC_RPC } from "./replay.js";
|
|
24
|
+
import { substituteBinaries } from "./substitute.js";
|
|
25
|
+
const HASH = /^0x[0-9a-fA-F]{64}$/;
|
|
26
|
+
/** Parses and checks a cycles.json, with a message that says what to fix. */
|
|
27
|
+
export function parseCyclesConfig(json) {
|
|
28
|
+
const fail = (msg) => {
|
|
29
|
+
throw new Error(`cycles.json: ${msg}`);
|
|
30
|
+
};
|
|
31
|
+
let c;
|
|
32
|
+
try {
|
|
33
|
+
c = JSON.parse(json);
|
|
34
|
+
}
|
|
35
|
+
catch (e) {
|
|
36
|
+
return fail(`not valid JSON (${e instanceof Error ? e.message : e})`);
|
|
37
|
+
}
|
|
38
|
+
if (!c || typeof c !== "object" || !Array.isArray(c.scenarios))
|
|
39
|
+
fail(`expected { "scenarios": [ ... ] }`);
|
|
40
|
+
if (c.network !== undefined && c.network !== "testnet" && c.network !== "mainnet") {
|
|
41
|
+
fail(`"network" must be "testnet" or "mainnet"`);
|
|
42
|
+
}
|
|
43
|
+
if (c.names !== undefined)
|
|
44
|
+
parseNames(Object.entries(c.names).map(([k, v]) => `${k}=${v}`));
|
|
45
|
+
for (const [name, b] of Object.entries(c.binaries ?? {})) {
|
|
46
|
+
if (!b || typeof b.path !== "string")
|
|
47
|
+
fail(`binary "${name}" needs a "path"`);
|
|
48
|
+
if (!b.outPoint === !b.codeHash)
|
|
49
|
+
fail(`binary "${name}" needs either "outPoint" or "codeHash"`);
|
|
50
|
+
if (b.codeHash !== undefined && !HASH.test(b.codeHash))
|
|
51
|
+
fail(`binary "${name}": "codeHash" must be 0x + 64 hex`);
|
|
52
|
+
if (b.outPoint && (!HASH.test(b.outPoint.tx_hash ?? "") || !/^0x[0-9a-fA-F]+$/.test(b.outPoint.index ?? ""))) {
|
|
53
|
+
fail(`binary "${name}": "outPoint" must be { "tx_hash": "0x…", "index": "0x0" }`);
|
|
54
|
+
}
|
|
55
|
+
if (b.symbols !== undefined && (typeof b.symbols !== "string" || !b.symbols))
|
|
56
|
+
fail(`binary "${name}": "symbols" must be a path`);
|
|
57
|
+
}
|
|
58
|
+
if (c.functions !== undefined && typeof c.functions !== "boolean")
|
|
59
|
+
fail(`"functions" must be true or false`);
|
|
60
|
+
const seen = new Set();
|
|
61
|
+
for (const s of c.scenarios) {
|
|
62
|
+
if (!s || typeof s.name !== "string" || !s.name)
|
|
63
|
+
fail(`every scenario needs a "name"`);
|
|
64
|
+
if (seen.has(s.name))
|
|
65
|
+
fail(`two scenarios are named "${s.name}"`);
|
|
66
|
+
seen.add(s.name);
|
|
67
|
+
const sources = [s.tx, s.file, s.mock].filter((v) => v !== undefined);
|
|
68
|
+
if (sources.length !== 1)
|
|
69
|
+
fail(`scenario "${s.name}" needs exactly one of "tx", "file", "mock"`);
|
|
70
|
+
for (const k of ["file", "mock"]) {
|
|
71
|
+
if (s[k] !== undefined && (typeof s[k] !== "string" || !s[k]))
|
|
72
|
+
fail(`scenario "${s.name}": "${k}" must be a path`);
|
|
73
|
+
}
|
|
74
|
+
if (s.tx !== undefined && !HASH.test(s.tx))
|
|
75
|
+
fail(`scenario "${s.name}": "tx" must be a transaction hash`);
|
|
76
|
+
for (const b of s.binaries ?? [])
|
|
77
|
+
if (!c.binaries?.[b])
|
|
78
|
+
fail(`scenario "${s.name}" uses unknown binary "${b}"`);
|
|
79
|
+
if (s.scriptVersion !== undefined && ![0, 1, 2].includes(s.scriptVersion)) {
|
|
80
|
+
fail(`scenario "${s.name}": "scriptVersion" must be 0, 1 or 2`);
|
|
81
|
+
}
|
|
82
|
+
if (s.functions !== undefined && typeof s.functions !== "boolean")
|
|
83
|
+
fail(`scenario "${s.name}": "functions" must be true or false`);
|
|
84
|
+
}
|
|
85
|
+
// Functions come only from a symbols build: asking without one would record nothing, silently.
|
|
86
|
+
if (c.scenarios.some((s) => s.functions ?? c.functions) && !Object.values(c.binaries ?? {}).some((b) => b.symbols)) {
|
|
87
|
+
fail(`"functions" needs a binary with "symbols" (an unstripped build of the same code)`);
|
|
88
|
+
}
|
|
89
|
+
return c;
|
|
90
|
+
}
|
|
91
|
+
const short = (h, n = 6) => (h.length > 2 * n + 2 ? `${h.slice(0, n + 2)}…${h.slice(-n)}` : h);
|
|
92
|
+
export function groupResults(p) {
|
|
93
|
+
return p.groups.map((g) => ({
|
|
94
|
+
selector: g.selector,
|
|
95
|
+
role: g.role,
|
|
96
|
+
script: g.name ?? short(g.codeHash),
|
|
97
|
+
codeHash: g.codeHash,
|
|
98
|
+
hashType: g.hashType,
|
|
99
|
+
result: g.result,
|
|
100
|
+
...(g.error && { error: g.error }),
|
|
101
|
+
cycles: Number(g.cycles),
|
|
102
|
+
}));
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Runs every scenario of a cycles.json. A scenario that cannot run is recorded
|
|
106
|
+
* with its error rather than ending the report, so one broken scenario does not
|
|
107
|
+
* hide the others' numbers.
|
|
108
|
+
*/
|
|
109
|
+
export async function runReport(configPath, options = {}) {
|
|
110
|
+
const config = parseCyclesConfig(await readFile(configPath, "utf8"));
|
|
111
|
+
const dir = dirname(resolve(configPath));
|
|
112
|
+
const binDir = options.binariesRoot ? resolve(options.binariesRoot) : dir;
|
|
113
|
+
// Only a network the config names is checked against the node; otherwise the
|
|
114
|
+
// node says which chain it serves, and its own hardfork epochs are used.
|
|
115
|
+
const network = config.network;
|
|
116
|
+
const rpcUrl = options.rpcUrl ?? config.rpc;
|
|
117
|
+
const baseNames = parseNames(Object.entries(config.names ?? {}).map(([k, v]) => `${k}=${v}`));
|
|
118
|
+
const roots = options.roots?.length ? await Promise.all(options.roots.map((r) => realpath(resolve(r)))) : undefined;
|
|
119
|
+
const inside = (file) => confine(file, roots);
|
|
120
|
+
const binaries = new Map();
|
|
121
|
+
const binary = (name) => {
|
|
122
|
+
let p = binaries.get(name);
|
|
123
|
+
if (!p) {
|
|
124
|
+
const b = config.binaries[name];
|
|
125
|
+
p = inside(resolve(binDir, b.path))
|
|
126
|
+
.then((file) => readFile(file))
|
|
127
|
+
.then((data) => ({
|
|
128
|
+
name,
|
|
129
|
+
data: new Uint8Array(data),
|
|
130
|
+
...(b.outPoint && { outPoint: b.outPoint }),
|
|
131
|
+
...(b.codeHash && { codeHash: b.codeHash }),
|
|
132
|
+
}), (e) => {
|
|
133
|
+
const err = new Error(`binary "${name}": cannot read ${b.path} (${e.message}); build it first`);
|
|
134
|
+
// Absent from another checkout (the base): the scenario's code is new there, not broken.
|
|
135
|
+
if (options.binariesRoot && e.code === "ENOENT")
|
|
136
|
+
missingBinary.add(err);
|
|
137
|
+
throw err;
|
|
138
|
+
});
|
|
139
|
+
binaries.set(name, p);
|
|
140
|
+
}
|
|
141
|
+
return p;
|
|
142
|
+
};
|
|
143
|
+
const used = new Set();
|
|
144
|
+
const missingBinary = new WeakSet();
|
|
145
|
+
let debuggerVersion;
|
|
146
|
+
const scenarios = [];
|
|
147
|
+
for (const s of config.scenarios) {
|
|
148
|
+
let result;
|
|
149
|
+
try {
|
|
150
|
+
const explicit = s.binaries !== undefined;
|
|
151
|
+
const names = explicit ? s.binaries : Object.keys(config.binaries ?? {});
|
|
152
|
+
const subs = await Promise.all(names.map(binary));
|
|
153
|
+
const profileOptions = {
|
|
154
|
+
...(network && { network }),
|
|
155
|
+
...(rpcUrl && { rpcUrl }),
|
|
156
|
+
...(options.timeoutMs !== undefined && { timeoutMs: options.timeoutMs }),
|
|
157
|
+
...(options.debuggerPath && { debuggerPath: options.debuggerPath }),
|
|
158
|
+
...(options.runDebugger && { runDebugger: options.runDebugger }),
|
|
159
|
+
...(s.scriptVersion !== undefined && { scriptVersion: s.scriptVersion }),
|
|
160
|
+
};
|
|
161
|
+
let profile;
|
|
162
|
+
let groups;
|
|
163
|
+
const warnings = [];
|
|
164
|
+
if (s.tx && !subs.length) {
|
|
165
|
+
// Nothing to swap: profile it as the CLI does, with the node's check.
|
|
166
|
+
profile = await profileTransaction(s.tx, { ...profileOptions, scriptNames: baseNames });
|
|
167
|
+
}
|
|
168
|
+
else {
|
|
169
|
+
const url = rpcUrl ?? PUBLIC_RPC[network ?? "testnet"];
|
|
170
|
+
const rpc = () => httpRpc(url, { ...(options.timeoutMs !== undefined && { timeoutMs: options.timeoutMs }) });
|
|
171
|
+
let mock;
|
|
172
|
+
let scriptVersion = s.scriptVersion;
|
|
173
|
+
if (s.mock) {
|
|
174
|
+
mock = JSON.parse(await readFile(await inside(resolve(dir, s.mock)), "utf8"));
|
|
175
|
+
if (!mock?.mock_info || !mock.tx)
|
|
176
|
+
throw new Error(`${s.mock} is not a ckb-debugger mock transaction`);
|
|
177
|
+
}
|
|
178
|
+
else if (s.file) {
|
|
179
|
+
mock = await mockFromTransaction(rpc(), readTransactionJson(await readFile(await inside(resolve(dir, s.file)), "utf8")));
|
|
180
|
+
}
|
|
181
|
+
else {
|
|
182
|
+
const node = rpc();
|
|
183
|
+
const [built, consensus] = await Promise.all([
|
|
184
|
+
buildMockTransaction(node, s.tx),
|
|
185
|
+
consensusOf(node, url, { ...(network && { network }), ...(rpcUrl && { rpcUrl }) }),
|
|
186
|
+
]);
|
|
187
|
+
mock = built.mock;
|
|
188
|
+
if (scriptVersion === undefined && built.epoch !== undefined) {
|
|
189
|
+
scriptVersion = scriptVersionAt(consensus?.vmEpochs ?? network ?? "testnet", built.epoch);
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
const { mock: swapped, applied } = substituteBinaries(mock, subs, { skipUnmatched: !explicit });
|
|
193
|
+
// A substituted binary is labelled by its name; "names" still wins.
|
|
194
|
+
const scriptNames = {};
|
|
195
|
+
for (const a of applied) {
|
|
196
|
+
used.add(a.name);
|
|
197
|
+
for (const k of a.scriptKeys)
|
|
198
|
+
scriptNames[k] = a.name;
|
|
199
|
+
warnings.push(...a.warnings.map((w) => `${a.name}: ${w}`));
|
|
200
|
+
}
|
|
201
|
+
Object.assign(scriptNames, baseNames);
|
|
202
|
+
profile = await profileTransaction(swapped, {
|
|
203
|
+
...profileOptions,
|
|
204
|
+
...(scriptVersion !== undefined && { scriptVersion }),
|
|
205
|
+
scriptNames,
|
|
206
|
+
});
|
|
207
|
+
// The scripts whose code is a binary with symbols, when the scenario asks for functions.
|
|
208
|
+
const symbols = new Map();
|
|
209
|
+
if (s.functions ?? config.functions) {
|
|
210
|
+
for (const a of applied) {
|
|
211
|
+
const sym = config.binaries[a.name].symbols;
|
|
212
|
+
if (sym)
|
|
213
|
+
for (const k of a.scriptKeys)
|
|
214
|
+
symbols.set(k.toLowerCase(), sym);
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
if (symbols.size) {
|
|
218
|
+
groups = groupResults(profile);
|
|
219
|
+
await recordFunctions(groups, swapped, symbols, binDir, inside, {
|
|
220
|
+
...profileOptions,
|
|
221
|
+
...(scriptVersion !== undefined && { scriptVersion }),
|
|
222
|
+
});
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
debuggerVersion ??= profile.env.debugger;
|
|
226
|
+
// Kept with the scenario: numbers that do not add up to the node's are not to be trusted.
|
|
227
|
+
if (nodeVerdict(profile) === "mismatch") {
|
|
228
|
+
warnings.push(`the groups add up to ${profile.measuredCycles} cycles, the node reported ${profile.nodeCycles}`);
|
|
229
|
+
}
|
|
230
|
+
result = { name: s.name, groups: groups ?? groupResults(profile), ...(warnings.length && { warnings }) };
|
|
231
|
+
}
|
|
232
|
+
catch (e) {
|
|
233
|
+
result = {
|
|
234
|
+
name: s.name,
|
|
235
|
+
error: e instanceof Error ? e.message : String(e),
|
|
236
|
+
groups: [],
|
|
237
|
+
...(e instanceof Error && missingBinary.has(e) && { binaryMissing: true }),
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
scenarios.push(result);
|
|
241
|
+
options.onScenario?.(result);
|
|
242
|
+
}
|
|
243
|
+
const errors = scenarios.filter((s) => s.error).map((s) => `scenario "${s.name}": ${s.error}`);
|
|
244
|
+
// A binary offered to every scenario that none of them uses is almost always
|
|
245
|
+
// a wrong out point or code hash: the report would measure the old code.
|
|
246
|
+
// Only said when every scenario ran: one that failed may be the one that uses it.
|
|
247
|
+
const offered = !errors.length && config.scenarios.some((s) => s.binaries === undefined) ? Object.keys(config.binaries ?? {}) : [];
|
|
248
|
+
for (const name of offered) {
|
|
249
|
+
if (!used.has(name) && !config.scenarios.some((s) => s.binaries?.includes(name))) {
|
|
250
|
+
errors.push(`binary "${name}" matched no cell dep in any scenario: check its outPoint / codeHash`);
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
return {
|
|
254
|
+
tool: "ckb-cycles",
|
|
255
|
+
version: 1,
|
|
256
|
+
...(debuggerVersion && { debugger: debuggerVersion }),
|
|
257
|
+
scenarios,
|
|
258
|
+
errors,
|
|
259
|
+
};
|
|
260
|
+
}
|
|
261
|
+
/**
|
|
262
|
+
* Adds `functions` to each group whose script (`codeHash:hashType`) is in
|
|
263
|
+
* `symbols` (to the symbols build's path in the config), from a flamegraph run
|
|
264
|
+
* of that group with that build. A build that does not cost the same cycles as
|
|
265
|
+
* the binary it stands for is not the same code: the group gets a warning instead.
|
|
266
|
+
*/
|
|
267
|
+
async function recordFunctions(groups, mock, symbols, binDir, inside, options) {
|
|
268
|
+
const fmt = (n) => n.toLocaleString("en-US");
|
|
269
|
+
const symbolsOf = (g) => symbols.get(`${g.codeHash}:${g.hashType}`.toLowerCase());
|
|
270
|
+
const wanted = groups.filter((g) => symbolsOf(g));
|
|
271
|
+
const bins = {};
|
|
272
|
+
for (const g of wanted) {
|
|
273
|
+
let file;
|
|
274
|
+
try {
|
|
275
|
+
file = await inside(resolve(binDir, symbolsOf(g)));
|
|
276
|
+
}
|
|
277
|
+
catch (e) {
|
|
278
|
+
g.functionsWarning = e instanceof Error ? e.message : String(e);
|
|
279
|
+
continue;
|
|
280
|
+
}
|
|
281
|
+
// A missing build is said on its group; the cycles are measured all the same.
|
|
282
|
+
const found = await stat(file).then((st) => st.isFile(), () => false);
|
|
283
|
+
if (found)
|
|
284
|
+
bins[g.codeHash] = file;
|
|
285
|
+
else
|
|
286
|
+
g.functionsWarning = `cannot read the symbols build ${symbolsOf(g)}: build it first`;
|
|
287
|
+
}
|
|
288
|
+
const run = wanted.filter((g) => bins[g.codeHash]);
|
|
289
|
+
if (!run.length)
|
|
290
|
+
return;
|
|
291
|
+
let flame;
|
|
292
|
+
try {
|
|
293
|
+
flame = await flameTransaction(mock, {
|
|
294
|
+
...options,
|
|
295
|
+
bins,
|
|
296
|
+
scripts: run.map((g) => g.selector),
|
|
297
|
+
readFile: (path) => readFile(path, "utf8"),
|
|
298
|
+
});
|
|
299
|
+
}
|
|
300
|
+
catch (e) {
|
|
301
|
+
for (const g of run)
|
|
302
|
+
g.functionsWarning = `the flamegraph run failed: ${e instanceof Error ? e.message : String(e)}`;
|
|
303
|
+
return;
|
|
304
|
+
}
|
|
305
|
+
for (const g of run) {
|
|
306
|
+
const f = flame.groups.find((f) => f.selector === g.selector);
|
|
307
|
+
if (!f)
|
|
308
|
+
g.functionsWarning = "the flamegraph run did not profile this group";
|
|
309
|
+
else if (f.cycles !== BigInt(g.cycles) || resultLabel(f) !== resultLabel(g)) {
|
|
310
|
+
g.functionsWarning =
|
|
311
|
+
`the symbols build ${symbolsOf(g)} runs ${fmt(f.cycles)} cycles (${resultLabel(f)}), the binary ${fmt(g.cycles)} (${resultLabel(g)}): ` +
|
|
312
|
+
"not the same code, so its functions would not describe this binary";
|
|
313
|
+
}
|
|
314
|
+
else if (!f.folded.size)
|
|
315
|
+
g.functionsWarning = "the profiler recorded no stacks";
|
|
316
|
+
else {
|
|
317
|
+
g.functions = functionCosts(f.folded)
|
|
318
|
+
.slice(0, FUNCTION_LIMIT)
|
|
319
|
+
.map((c) => ({ name: c.name, self: Number(c.self), total: Number(c.total) }));
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
/**
|
|
324
|
+
* `file` with its symlinks resolved, when it is inside one of `roots` (already
|
|
325
|
+
* resolved); an error otherwise. A file that does not exist is checked by its
|
|
326
|
+
* path and returned as given, so reading it fails with the usual ENOENT (a
|
|
327
|
+
* binary absent from the base is a new binary, not an error).
|
|
328
|
+
*/
|
|
329
|
+
export async function confine(file, roots) {
|
|
330
|
+
if (!roots)
|
|
331
|
+
return file;
|
|
332
|
+
const real = await realpath(file).catch((e) => {
|
|
333
|
+
if (e.code === "ENOENT")
|
|
334
|
+
return undefined;
|
|
335
|
+
throw e;
|
|
336
|
+
});
|
|
337
|
+
const within = (p) => roots.some((root) => {
|
|
338
|
+
const rel = relative(root, p);
|
|
339
|
+
return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
|
|
340
|
+
});
|
|
341
|
+
if (!within(real ?? (await realParent(resolve(file))))) {
|
|
342
|
+
throw new Error(`${file} is outside the checkout (${roots.join(", ")}): not read`);
|
|
343
|
+
}
|
|
344
|
+
return real ?? file;
|
|
345
|
+
}
|
|
346
|
+
/**
|
|
347
|
+
* A missing file's path with its nearest existing ancestor resolved, so it compares
|
|
348
|
+
* like the roots do (Windows runners' temp dir is an 8.3 short name, RUNNER~1).
|
|
349
|
+
*/
|
|
350
|
+
async function realParent(p) {
|
|
351
|
+
const parent = dirname(p);
|
|
352
|
+
if (parent === p)
|
|
353
|
+
return p;
|
|
354
|
+
try {
|
|
355
|
+
return join(await realpath(parent), basename(p));
|
|
356
|
+
}
|
|
357
|
+
catch (e) {
|
|
358
|
+
if (e.code !== "ENOENT")
|
|
359
|
+
throw e;
|
|
360
|
+
return join(await realParent(parent), basename(p));
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
/** The report for a terminal: one block per scenario. */
|
|
364
|
+
export function formatReport(report) {
|
|
365
|
+
const fmt = (n) => n.toLocaleString("en-US");
|
|
366
|
+
const rows = report.scenarios.flatMap((s) => s.error
|
|
367
|
+
? [[s.name, "", "", "error", ""]]
|
|
368
|
+
: s.groups.map((g) => [s.name, g.selector, g.script, resultLabel(g), fmt(g.cycles)]));
|
|
369
|
+
const head = ["SCENARIO", "GROUP", "SCRIPT", "RESULT", "CYCLES"];
|
|
370
|
+
const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
|
|
371
|
+
const line = (cells) => cells.map((c, i) => (i === 4 ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join(" ").trimEnd();
|
|
372
|
+
const out = [line(head), ...rows.map(line)];
|
|
373
|
+
for (const s of report.scenarios)
|
|
374
|
+
if (s.error)
|
|
375
|
+
out.push("", `${s.name}: ${s.error}`);
|
|
376
|
+
for (const s of report.scenarios)
|
|
377
|
+
for (const w of s.warnings ?? [])
|
|
378
|
+
out.push("", `${s.name}: warning: ${w}`);
|
|
379
|
+
for (const s of report.scenarios) {
|
|
380
|
+
for (const g of s.groups.filter((g) => g.error))
|
|
381
|
+
out.push("", `${s.name} ${g.selector} stopped: ${g.error}`);
|
|
382
|
+
}
|
|
383
|
+
for (const s of report.scenarios) {
|
|
384
|
+
for (const g of s.groups) {
|
|
385
|
+
if (g.functionsWarning)
|
|
386
|
+
out.push("", `${s.name} ${g.selector}: functions not recorded: ${g.functionsWarning}`);
|
|
387
|
+
else if (g.functions?.length) {
|
|
388
|
+
const top = g.functions.slice(0, 3).map((f) => `${f.name} ${fmt(f.self)}`);
|
|
389
|
+
out.push("", `${s.name} ${g.selector}: costliest functions (self cycles): ${top.join(", ")}`);
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
if (report.debugger)
|
|
394
|
+
out.push("", report.debugger);
|
|
395
|
+
return out.join("\n");
|
|
396
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { MockTransaction, RpcOutPoint } from "./mock.js";
|
|
2
|
+
type Hex = string;
|
|
3
|
+
export interface BinarySubstitution {
|
|
4
|
+
/** A label for messages, and for the script in reports. */
|
|
5
|
+
name?: string;
|
|
6
|
+
/** The new binary, as bytes or 0x-hex. */
|
|
7
|
+
data: Uint8Array | Hex;
|
|
8
|
+
/** The cell dep to replace. Give this or `codeHash`. */
|
|
9
|
+
outPoint?: RpcOutPoint;
|
|
10
|
+
/** Replace every code dep whose data hash or type script hash is this. */
|
|
11
|
+
codeHash?: Hex;
|
|
12
|
+
}
|
|
13
|
+
export interface AppliedSubstitution {
|
|
14
|
+
name?: string;
|
|
15
|
+
/** The cell deps that now hold the new binary. */
|
|
16
|
+
outPoints: RpcOutPoint[];
|
|
17
|
+
oldDataHash: Hex;
|
|
18
|
+
newDataHash: Hex;
|
|
19
|
+
/**
|
|
20
|
+
* The code hashes scripts can now reach the binary by, as `codeHash:hashType`
|
|
21
|
+
* keys (the form profileTransaction's `scriptNames` takes).
|
|
22
|
+
*/
|
|
23
|
+
scriptKeys: string[];
|
|
24
|
+
/** How many scripts had their code hash rewritten (data hash types only). */
|
|
25
|
+
rewritten: number;
|
|
26
|
+
warnings: string[];
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Applies the substitutions in order and returns a new mock; the input is not
|
|
30
|
+
* modified. Throws if a substitution matches no code dep, since silently
|
|
31
|
+
* measuring the old binary would be the worst possible result — unless
|
|
32
|
+
* `skipUnmatched`, for a binary offered to every scenario, which only some use;
|
|
33
|
+
* the ones that matched are in `applied`.
|
|
34
|
+
*/
|
|
35
|
+
export declare function substituteBinaries(mock: MockTransaction, substitutions: BinarySubstitution[], options?: {
|
|
36
|
+
skipUnmatched?: boolean;
|
|
37
|
+
}): {
|
|
38
|
+
mock: MockTransaction;
|
|
39
|
+
applied: AppliedSubstitution[];
|
|
40
|
+
};
|
|
41
|
+
export {};
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Swaps a script binary in a mock transaction for another one — typically the
|
|
3
|
+
* binary just built from the commit under test — so a replay measures that
|
|
4
|
+
* build instead of the one deployed on chain.
|
|
5
|
+
*
|
|
6
|
+
* Pure: no network, no file system. The caller reads the binary.
|
|
7
|
+
*
|
|
8
|
+
* A substitution targets `code` cell deps (including the cells a dep group
|
|
9
|
+
* expands to), by out point or by code hash:
|
|
10
|
+
* - by out point: that cell, whatever it holds;
|
|
11
|
+
* - by code hash: every cell whose data hash, or whose type script hash, equals it.
|
|
12
|
+
*
|
|
13
|
+
* Its data is replaced. What else has to change depends on how scripts point at
|
|
14
|
+
* the cell:
|
|
15
|
+
* - `hash_type: "type"`: by the cell's type script, which does not change. The
|
|
16
|
+
* scripts that run are byte-for-byte the same; only the code differs. This is
|
|
17
|
+
* the case that measures exactly "the same transaction, new binary".
|
|
18
|
+
* - `hash_type: "data" | "data1" | "data2"`: by the hash of the data, which the new
|
|
19
|
+
* binary changes. Every script whose code hash was the old data hash is
|
|
20
|
+
* rewritten to the new one — in input cells, cell deps and outputs — or it would
|
|
21
|
+
* not find its code at all. The transaction is then not the one you measured
|
|
22
|
+
* before: rewriting an output's script changes the transaction hash, so any
|
|
23
|
+
* signature over it (secp256k1 sighash-all, for one) stops verifying, and a
|
|
24
|
+
* script that carries the old hash in its args (a ckb-js-vm script naming its
|
|
25
|
+
* bytecode, a lock naming another lock's hash) is not rewritten. Both are
|
|
26
|
+
* reported as warnings, so a changed result can be traced to them.
|
|
27
|
+
*/
|
|
28
|
+
import { ccc } from "@ckb-ccc/core";
|
|
29
|
+
const DATA_HASH_TYPES = ["data", "data1", "data2"];
|
|
30
|
+
const sameOutPoint = (a, b) => a.tx_hash.toLowerCase() === b.tx_hash.toLowerCase() && Number(a.index) === Number(b.index);
|
|
31
|
+
const typeHash = (s) => ccc.Script.from({ codeHash: s.code_hash, hashType: s.hash_type, args: s.args }).hash();
|
|
32
|
+
/**
|
|
33
|
+
* Applies the substitutions in order and returns a new mock; the input is not
|
|
34
|
+
* modified. Throws if a substitution matches no code dep, since silently
|
|
35
|
+
* measuring the old binary would be the worst possible result — unless
|
|
36
|
+
* `skipUnmatched`, for a binary offered to every scenario, which only some use;
|
|
37
|
+
* the ones that matched are in `applied`.
|
|
38
|
+
*/
|
|
39
|
+
export function substituteBinaries(mock, substitutions, options = {}) {
|
|
40
|
+
const next = structuredClone(mock);
|
|
41
|
+
const applied = [];
|
|
42
|
+
for (const sub of substitutions) {
|
|
43
|
+
const result = substituteOne(next, sub, options.skipUnmatched ?? false);
|
|
44
|
+
if (result)
|
|
45
|
+
applied.push(result);
|
|
46
|
+
}
|
|
47
|
+
return { mock: next, applied };
|
|
48
|
+
}
|
|
49
|
+
function substituteOne(mock, sub, skipUnmatched) {
|
|
50
|
+
const label = sub.name ?? sub.codeHash ?? (sub.outPoint && `${sub.outPoint.tx_hash}:${Number(sub.outPoint.index)}`);
|
|
51
|
+
if (!sub.outPoint === !sub.codeHash)
|
|
52
|
+
throw new Error(`substitution ${label}: give an out point or a code hash, not both`);
|
|
53
|
+
const data = ccc.hexFrom(sub.data);
|
|
54
|
+
const newDataHash = ccc.hashCkb(data);
|
|
55
|
+
const want = sub.codeHash?.toLowerCase();
|
|
56
|
+
const targets = mock.mock_info.cell_deps.filter((d) => {
|
|
57
|
+
if (d.cell_dep.dep_type !== "code")
|
|
58
|
+
return false;
|
|
59
|
+
if (sub.outPoint)
|
|
60
|
+
return sameOutPoint(d.cell_dep.out_point, sub.outPoint);
|
|
61
|
+
return ccc.hashCkb(d.data) === want || (d.output.type != null && typeHash(d.output.type) === want);
|
|
62
|
+
});
|
|
63
|
+
if (!targets.length) {
|
|
64
|
+
if (skipUnmatched)
|
|
65
|
+
return undefined;
|
|
66
|
+
throw new Error(`substitution ${label}: no code cell dep in this transaction matches it`);
|
|
67
|
+
}
|
|
68
|
+
const oldHashes = new Set(targets.map((d) => ccc.hashCkb(d.data)));
|
|
69
|
+
if (oldHashes.size > 1)
|
|
70
|
+
throw new Error(`substitution ${label}: matches cells holding different binaries`);
|
|
71
|
+
const [oldDataHash] = oldHashes;
|
|
72
|
+
const scriptKeys = new Set();
|
|
73
|
+
for (const d of targets) {
|
|
74
|
+
d.data = data;
|
|
75
|
+
if (d.output.type)
|
|
76
|
+
scriptKeys.add(`${typeHash(d.output.type)}:type`);
|
|
77
|
+
}
|
|
78
|
+
const warnings = [];
|
|
79
|
+
let rewritten = 0;
|
|
80
|
+
if (oldDataHash !== newDataHash) {
|
|
81
|
+
for (const t of DATA_HASH_TYPES)
|
|
82
|
+
scriptKeys.add(`${newDataHash}:${t}`);
|
|
83
|
+
let outputsRewritten = 0;
|
|
84
|
+
let argsMentions = 0;
|
|
85
|
+
const rewrite = (s, where) => {
|
|
86
|
+
if (!s)
|
|
87
|
+
return;
|
|
88
|
+
if (s.code_hash.toLowerCase() === oldDataHash && DATA_HASH_TYPES.includes(s.hash_type)) {
|
|
89
|
+
s.code_hash = newDataHash;
|
|
90
|
+
rewritten++;
|
|
91
|
+
if (where === "output")
|
|
92
|
+
outputsRewritten++;
|
|
93
|
+
}
|
|
94
|
+
if (s.args.toLowerCase().includes(oldDataHash.slice(2)))
|
|
95
|
+
argsMentions++;
|
|
96
|
+
};
|
|
97
|
+
for (const c of [...mock.mock_info.inputs, ...mock.mock_info.cell_deps]) {
|
|
98
|
+
rewrite(c.output.lock, "cell");
|
|
99
|
+
rewrite(c.output.type, "cell");
|
|
100
|
+
}
|
|
101
|
+
for (const o of mock.tx.outputs) {
|
|
102
|
+
rewrite(o.lock, "output");
|
|
103
|
+
rewrite(o.type, "output");
|
|
104
|
+
}
|
|
105
|
+
if (outputsRewritten) {
|
|
106
|
+
warnings.push(`${outputsRewritten} output script(s) now name the new code hash, which changes the transaction hash: ` +
|
|
107
|
+
`signatures over it no longer verify`);
|
|
108
|
+
}
|
|
109
|
+
if (argsMentions) {
|
|
110
|
+
warnings.push(`the old code hash still appears in the args of ${argsMentions} script(s); args are not rewritten`);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
return {
|
|
114
|
+
...(sub.name && { name: sub.name }),
|
|
115
|
+
outPoints: targets.map((d) => d.cell_dep.out_point),
|
|
116
|
+
oldDataHash,
|
|
117
|
+
newDataHash,
|
|
118
|
+
scriptKeys: [...scriptKeys],
|
|
119
|
+
rewritten,
|
|
120
|
+
warnings,
|
|
121
|
+
};
|
|
122
|
+
}
|
package/dist/wasm.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { RunDebugger } from "./replay.js";
|
|
2
|
+
export interface WasmRun {
|
|
3
|
+
exitCode: number;
|
|
4
|
+
stdout: string;
|
|
5
|
+
stderr: string;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Runs the debugger once. `files` are placed in `/`, so `--tx-file /tx.json`
|
|
9
|
+
* reads `files["tx.json"]`. A fresh instance each time: no state leaks between runs.
|
|
10
|
+
*/
|
|
11
|
+
export declare function runWasmDebugger(module: WebAssembly.Module, args: string[], files?: Record<string, Uint8Array>): Promise<WasmRun>;
|
|
12
|
+
/** "ckb-debugger 0.200.1", as `--version` prints it. */
|
|
13
|
+
export declare function wasmDebuggerVersion(module: WebAssembly.Module): Promise<string>;
|
|
14
|
+
/** The text the debugger printed, stdout then stderr. */
|
|
15
|
+
export declare const wasmOutput: (r: WasmRun) => string;
|
|
16
|
+
/** Where wasmRunner puts the mock transaction. */
|
|
17
|
+
export declare const WASM_TX_FILE = "/tx.json";
|
|
18
|
+
/**
|
|
19
|
+
* A runner for replayGroups, with the mock transaction (its JSON, encoded) at
|
|
20
|
+
* WASM_TX_FILE: `replayGroups(plan, wasmRunner(module, tx), { txFile: WASM_TX_FILE, … })`.
|
|
21
|
+
*/
|
|
22
|
+
export declare function wasmRunner(module: WebAssembly.Module, tx: Uint8Array): RunDebugger;
|
package/dist/wasm.js
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ckb-debugger compiled to WebAssembly (WASI), run in memory: no Node
|
|
3
|
+
* built-ins, so the same code runs in a browser (or a Web Worker) and in Node.
|
|
4
|
+
*
|
|
5
|
+
* The WASI build ships in the `ckb-testtool` npm package
|
|
6
|
+
* (`src/wasm/ckb-debugger.wasm`); compile it once with `WebAssembly.compile`
|
|
7
|
+
* and pass the module in. Files the debugger reads live in an in-memory
|
|
8
|
+
* directory at `/`, and stdout/stderr are collected as text.
|
|
9
|
+
*/
|
|
10
|
+
import { ConsoleStdout, File, OpenFile, PreopenDirectory, WASI } from "@bjorn3/browser_wasi_shim";
|
|
11
|
+
/**
|
|
12
|
+
* Runs the debugger once. `files` are placed in `/`, so `--tx-file /tx.json`
|
|
13
|
+
* reads `files["tx.json"]`. A fresh instance each time: no state leaks between runs.
|
|
14
|
+
*/
|
|
15
|
+
export async function runWasmDebugger(module, args, files = {}) {
|
|
16
|
+
const decoders = [new TextDecoder(), new TextDecoder()];
|
|
17
|
+
const text = ["", ""];
|
|
18
|
+
const capture = (i) => new ConsoleStdout((bytes) => (text[i] += decoders[i].decode(bytes, { stream: true })));
|
|
19
|
+
const root = new Map(Object.entries(files).map(([name, data]) => [name, new File(data, { readonly: true })]));
|
|
20
|
+
const fds = [new OpenFile(new File([])), capture(0), capture(1), new PreopenDirectory("/", root)];
|
|
21
|
+
// `debug: false` explicitly: the shim logs every call when it is left undefined.
|
|
22
|
+
const wasi = new WASI(["ckb-debugger", ...args], [], fds, { debug: false });
|
|
23
|
+
const instance = (await WebAssembly.instantiate(module, { wasi_snapshot_preview1: wasi.wasiImport }));
|
|
24
|
+
let exitCode;
|
|
25
|
+
try {
|
|
26
|
+
exitCode = wasi.start(instance);
|
|
27
|
+
}
|
|
28
|
+
catch (e) {
|
|
29
|
+
// A trap inside the debugger (e.g. out of memory): report it like a crashed
|
|
30
|
+
// process. Exit code -1 tells parseDebuggerRun not to trust the stdout so far.
|
|
31
|
+
text[1] += `\n${e instanceof Error ? e.message : String(e)}`;
|
|
32
|
+
exitCode = -1;
|
|
33
|
+
}
|
|
34
|
+
return { exitCode, stdout: text[0] + decoders[0].decode(), stderr: text[1] + decoders[1].decode() };
|
|
35
|
+
}
|
|
36
|
+
/** "ckb-debugger 0.200.1", as `--version` prints it. */
|
|
37
|
+
export async function wasmDebuggerVersion(module) {
|
|
38
|
+
return (await runWasmDebugger(module, ["--version"])).stdout.trim() || "unknown";
|
|
39
|
+
}
|
|
40
|
+
/** The text the debugger printed, stdout then stderr. */
|
|
41
|
+
export const wasmOutput = (r) => r.stdout + r.stderr;
|
|
42
|
+
/** Where wasmRunner puts the mock transaction. */
|
|
43
|
+
export const WASM_TX_FILE = "/tx.json";
|
|
44
|
+
/**
|
|
45
|
+
* A runner for replayGroups, with the mock transaction (its JSON, encoded) at
|
|
46
|
+
* WASM_TX_FILE: `replayGroups(plan, wasmRunner(module, tx), { txFile: WASM_TX_FILE, … })`.
|
|
47
|
+
*/
|
|
48
|
+
export function wasmRunner(module, tx) {
|
|
49
|
+
// The whole run, exit code included: replayGroups checks the result lines against it.
|
|
50
|
+
return (args) => runWasmDebugger(module, args, { "tx.json": tx });
|
|
51
|
+
}
|