ckb-cycle-tools 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/replay.js ADDED
@@ -0,0 +1,296 @@
1
+ /**
2
+ * Replaying a transaction group by group, with any ckb-debugger: the native
3
+ * binary (profile.ts, for the CLI) or its WebAssembly build (wasm.ts, for the
4
+ * browser). Everything here is plain TypeScript with no Node built-ins, so
5
+ * both get the same planning, the same Type ID check and the same parsing,
6
+ * and therefore the same numbers.
7
+ */
8
+ import { ccc } from "@ckb-ccc/core";
9
+ import { cccA } from "@ckb-ccc/core/advanced";
10
+ import { groupScripts, knownScriptNames } from "./analyze.js";
11
+ import { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, scriptVersionAt, } from "./mock.js";
12
+ /**
13
+ * Type ID is verified natively by the node rather than by a script binary, so
14
+ * ckb-debugger cannot run it. The node charges it a fixed cost (TYPE_ID_CYCLES
15
+ * in ckb-script).
16
+ */
17
+ export const TYPE_ID_CODE_HASH = "0x00000000000000000000000000000000000000000000000000545950455f4944";
18
+ export const TYPE_ID_CYCLES = 1000000n;
19
+ export const PUBLIC_RPC = { testnet: "https://testnet.ckb.dev/", mainnet: "https://mainnet.ckb.dev/" };
20
+ const toScript = (s) => ({ codeHash: s.code_hash, hashType: s.hash_type, args: s.args });
21
+ /** The first cell in a group is enough: ckb-debugger runs the whole group from it. */
22
+ export function selectorFor(g) {
23
+ if (g.inputs.length)
24
+ return `input.${g.inputs[0]}.${g.role}`;
25
+ return `output.${g.outputs[0]}.${g.role}`;
26
+ }
27
+ /** The ckb-debugger arguments for one group, the same for the native and the WebAssembly build. */
28
+ export function debuggerArgs(txFile, selector, scriptVersion) {
29
+ return ["--tx-file", txFile, "--script", selector, "--script-version", String(scriptVersion)];
30
+ }
31
+ /** Control characters a script could print to move the cursor or recolour the terminal. */
32
+ const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
33
+ /** The tail of some output, cleaned for a terminal: enough to see what went wrong, never megabytes. */
34
+ export function outputTail(out, max = 2048) {
35
+ const tail = out.length > max ? `…${out.slice(-max)}` : out;
36
+ return tail.trim().replace(CONTROL, "�");
37
+ }
38
+ /**
39
+ * ckb-debugger's own result lines are the last lines it prints: `Run result:`
40
+ * then `All cycles:` (or `Run result:` alone when the VM stopped the script).
41
+ * A script's logs come before them. Only those final lines are read, so a
42
+ * script that logs "Run result: 0" (even after a newline of its own) cannot
43
+ * fake its result, as long as the output is complete: a run whose output was
44
+ * cut off must never get here (see parseDebuggerRun).
45
+ */
46
+ export function parseDebuggerOutput(out) {
47
+ const lines = out.trimEnd().split(/\r?\n/);
48
+ const cyclesLine = /^All cycles: (\d+)/.exec(lines.at(-1) ?? "");
49
+ const resultLine = /^Run result: (.*?)\s*$/.exec(lines.at(cyclesLine ? -2 : -1) ?? "");
50
+ if (!resultLine)
51
+ throw new Error(`unexpected ckb-debugger output:\n${outputTail(out)}`);
52
+ const result = resultLine[1];
53
+ const cycles = cyclesLine?.[1];
54
+ const logs = [...out.matchAll(/^Script log: (.*)$/gm)].map((m) => m[1].trim().replace(CONTROL, "�"));
55
+ if (/^-?\d+$/.test(result) && cycles !== undefined)
56
+ return { result: Number(result), cycles: BigInt(cycles), logs };
57
+ // The VM stopped the script (invalid instruction, cycle limit, bad ELF…): a rejection, not a crash.
58
+ // Never its cycles: a stopped run's count is not what the script costs (0, or wherever the VM gave up).
59
+ return { result: -1, error: result.replace(CONTROL, "�"), cycles: 0n, logs };
60
+ }
61
+ /**
62
+ * Reads one run: its final result lines (parseDebuggerOutput), checked against
63
+ * its exit code. ckb-debugger exits 0 only when the script returned 0, so lines
64
+ * that say 0 with a non-zero exit code (or the reverse) were faked or cut
65
+ * short, and make an error rather than a result. Output that was cut off is
66
+ * never parsed at all.
67
+ */
68
+ export function parseDebuggerRun(run) {
69
+ const stopped = (error) => ({ result: -1, error, cycles: 0n, logs: [] });
70
+ if (run.failure)
71
+ return stopped(run.failure);
72
+ if (run.exitCode === null)
73
+ return stopped("ckb-debugger was killed before it finished");
74
+ // The WebAssembly build trapped (e.g. out of memory): whatever stdout it left is incomplete.
75
+ if (run.exitCode === -1)
76
+ return stopped(`ckb-debugger crashed: ${outputTail(run.stderr, 500) || "no message"}`);
77
+ let parsed;
78
+ try {
79
+ parsed = parseDebuggerOutput(run.stdout);
80
+ }
81
+ catch {
82
+ // Nothing usable on stdout: what it said on stderr is the reason.
83
+ throw new Error(`unexpected ckb-debugger output (exit ${run.exitCode}):\n${outputTail(run.stdout + run.stderr)}`);
84
+ }
85
+ if ((parsed.result === 0 && !parsed.error) !== (run.exitCode === 0)) {
86
+ const said = parsed.error ? "an error" : `result ${parsed.result}`;
87
+ return { ...parsed, result: -1, error: `ckb-debugger printed ${said} but exited with ${run.exitCode}: output not trusted` };
88
+ }
89
+ return parsed;
90
+ }
91
+ /**
92
+ * Type ID, checked as the node does (ckb-script's type_id): at most one cell on
93
+ * each side, 32-byte args, and a new Type ID's args are the hash of the first
94
+ * input and the new cell's output index.
95
+ */
96
+ export function checkTypeId(g, tx) {
97
+ if (g.inputs.length > 1 || g.outputs.length > 1)
98
+ return "type id: more than one cell in the group";
99
+ if (g.args.length !== 2 + 64)
100
+ return "type id: args must be 32 bytes";
101
+ if (g.inputs.length)
102
+ return undefined;
103
+ const first = tx.inputs[0];
104
+ if (!first)
105
+ return "type id: no input to derive it from";
106
+ // CellInput (since u64 LE ‖ tx hash ‖ index u32 LE), then the output index as u64 LE.
107
+ const expected = ccc.hashCkb(ccc.bytesConcat(ccc.numLeToBytes(BigInt(first.since), 8), ccc.bytesFrom(first.previous_output.tx_hash), ccc.numLeToBytes(Number(first.previous_output.index), 4), ccc.numLeToBytes(g.outputs[0], 8)));
108
+ return expected === g.args.toLowerCase() ? undefined : "type id: args do not match the first input";
109
+ }
110
+ /** The string fields of a mock transaction that are names, not hex. */
111
+ const NAME_FIELDS = { hash_type: /^(type|data[0-9]*)$/, dep_type: /^(code|dep_group)$/ };
112
+ /**
113
+ * Refuses a mock transaction that ckb-debugger would read as more than data.
114
+ * The debugger expands `{{ data <path> }}`, `{{ hash <path> }}`, `{{ def_type … }}`
115
+ * and `{{ ref_type … }}` in a tx file before parsing it (mock_tx_embed.rs), so
116
+ * such a string embeds any file on the machine that runs it, past `--root`.
117
+ * Every string must be hex (`0x…`), except `hash_type` and `dep_type`, which
118
+ * must be one of their names. Called on every mock before it is written for a
119
+ * debugger (groupsOf, so planReplay, profile, flame and report; wasmRunner).
120
+ */
121
+ export function checkMockTransaction(mock) {
122
+ const refuse = (path, why) => {
123
+ throw new Error(`mock transaction refused: ${path} ${why}`);
124
+ };
125
+ const walk = (v, path, key) => {
126
+ if (typeof v === "string") {
127
+ if (v.includes("{{")) {
128
+ refuse(path, `contains "{{", a ckb-debugger template directive that reads files from the machine running it`);
129
+ }
130
+ const name = NAME_FIELDS[key];
131
+ if (name ? !name.test(v) : !/^0x[0-9a-fA-F]*$/.test(v))
132
+ refuse(path, name ? `is not a ${key}` : "is not 0x-prefixed hex");
133
+ }
134
+ else if (Array.isArray(v)) {
135
+ v.forEach((x, i) => walk(x, `${path}[${i}]`, key));
136
+ }
137
+ else if (v && typeof v === "object") {
138
+ for (const [k, x] of Object.entries(v)) {
139
+ if (k.includes("{{"))
140
+ refuse(path, `has a key containing "{{", a ckb-debugger template directive`);
141
+ walk(x, /^[A-Za-z_]\w*$/.test(k) ? `${path}.${k}` : `${path}[${JSON.stringify(k)}]`, k);
142
+ }
143
+ }
144
+ };
145
+ walk(mock, "mock", "");
146
+ }
147
+ /**
148
+ * The script groups that run for a mock transaction, in first-appearance order.
149
+ * A cellbase runs none. A mock checkMockTransaction refuses is an error.
150
+ */
151
+ export function groupsOf(mock) {
152
+ checkMockTransaction(mock);
153
+ if (isCellbase(mock.tx))
154
+ return [];
155
+ return groupScripts(mock.mock_info.inputs.map((c) => ({ lock: toScript(c.output.lock), type: c.output.type && toScript(c.output.type) })), mock.tx.outputs.map((o) => ({ lock: toScript(o.lock), type: o.type && toScript(o.type) })));
156
+ }
157
+ /**
158
+ * Fetches what a replay needs: a committed transaction by hash (with the node's
159
+ * total), or any transaction in RPC shape, e.g. one about to be sent.
160
+ */
161
+ export async function planReplay(target, options = {}) {
162
+ const rpcUrl = options.rpcUrl ?? PUBLIC_RPC[options.network ?? "testnet"];
163
+ const rpc = httpRpc(rpcUrl, { ...(options.timeoutMs !== undefined && { timeoutMs: options.timeoutMs }) });
164
+ const isMock = typeof target === "object" && "mock_info" in target;
165
+ // The node's chain and hardfork epochs are asked alongside the transaction:
166
+ // a flag can name the wrong network, the node cannot.
167
+ const [fetched, consensus] = await Promise.all([
168
+ typeof target === "string"
169
+ ? buildMockTransaction(rpc, target).catch((e) => {
170
+ throw new Error(/^transaction not found/.test(e.message) ? `${e.message} on ${rpcUrl}` : e.message);
171
+ })
172
+ : "mock_info" in target
173
+ ? { mock: target, cycles: undefined, status: "not on chain", epoch: undefined }
174
+ : mockFromTransaction(rpc, target).then((mock) => ({ mock, cycles: undefined, status: "not on chain", epoch: undefined })),
175
+ // A ready mock transaction needs no node, and is not sent to one.
176
+ isMock ? undefined : consensusOf(rpc, rpcUrl, options),
177
+ ]);
178
+ const { mock, cycles, status, epoch } = fetched;
179
+ const network = consensus?.network ?? options.network ?? "testnet";
180
+ const groups = groupsOf(mock);
181
+ // Known-script names are CCC's table for the network, through the same node;
182
+ // a network CCC does not know (a devnet) names its scripts with `scriptNames`.
183
+ const client = network === "mainnet" ? new ccc.ClientPublicMainnet({ url: rpcUrl }) : new ccc.ClientPublicTestnet({ url: rpcUrl });
184
+ const names = await knownScriptNames(client);
185
+ for (const [k, name] of Object.entries(options.scriptNames ?? {}))
186
+ names.set(k.toLowerCase(), name);
187
+ for (const g of groups) {
188
+ const name = names.get(`${g.codeHash}:${g.hashType}`);
189
+ if (name)
190
+ g.name = name;
191
+ }
192
+ return {
193
+ hash: typeof target === "string" ? target : "(not on chain)",
194
+ status,
195
+ ...(cycles !== undefined && { nodeCycles: cycles }),
196
+ mock,
197
+ groups,
198
+ // `hash_type: "type"` scripts run on the VM of their block's epoch, on the
199
+ // node's own hardfork schedule; a transaction not yet in a block would run
200
+ // on the current one.
201
+ scriptVersion: options.scriptVersion ??
202
+ (epoch === undefined ? 2 : scriptVersionAt(consensus?.vmEpochs ?? (network === "mainnet" ? "mainnet" : "testnet"), epoch)),
203
+ network,
204
+ rpcUrl,
205
+ };
206
+ }
207
+ /**
208
+ * The node's chain and CKB-VM epochs, from `get_consensus`. Stops when the node
209
+ * serves another chain than `options.network` names. If the node cannot say,
210
+ * the built-in table stands in only for the public node of `network`; for a
211
+ * node given by URL the chain is unknown, so the replay stops.
212
+ */
213
+ export async function consensusOf(rpc, rpcUrl, options = {}) {
214
+ let consensus;
215
+ try {
216
+ consensus = await nodeConsensus(rpc);
217
+ }
218
+ catch (e) {
219
+ if (options.rpcUrl === undefined)
220
+ return undefined;
221
+ const why = e instanceof Error ? e.message : String(e);
222
+ throw new Error(`cannot read the hardfork epochs from ${rpcUrl}, so the CKB-VM version is unknown: ${why}`);
223
+ }
224
+ if (options.network !== undefined && consensus.network !== options.network) {
225
+ throw new Error(`${rpcUrl} serves ${consensus.network} (chain id "${consensus.chain}"), not ${options.network}`);
226
+ }
227
+ return consensus;
228
+ }
229
+ /**
230
+ * Replays every group of a plan, one after another, through `run`. The mock
231
+ * transaction must already be readable by that debugger at `txFile`.
232
+ * `onGroup` hears about each group before it runs, for progress.
233
+ */
234
+ export async function replayGroups(plan, run, options) {
235
+ const profiled = [];
236
+ // Sequential on purpose: output stays readable and the machine stays usable.
237
+ for (const [i, g] of plan.groups.entries()) {
238
+ const selector = selectorFor(g);
239
+ options.onGroup?.(i, selector);
240
+ if (g.role === "type" && g.codeHash === TYPE_ID_CODE_HASH && g.hashType === "type") {
241
+ const error = checkTypeId(g, plan.mock.tx);
242
+ const verdict = error ? { result: -1, error } : { result: 0 };
243
+ profiled.push({ ...g, name: "TypeId (built in)", selector, ...verdict, cycles: TYPE_ID_CYCLES, logs: [] });
244
+ continue;
245
+ }
246
+ const out = await run(debuggerArgs(options.txFile, selector, plan.scriptVersion));
247
+ profiled.push({ ...g, selector, ...(typeof out === "string" ? parseDebuggerOutput(out) : parseDebuggerRun(out)) });
248
+ }
249
+ return {
250
+ hash: plan.hash,
251
+ status: plan.status,
252
+ ...(plan.nodeCycles !== undefined && { nodeCycles: plan.nodeCycles }),
253
+ measuredCycles: profiled.reduce((sum, g) => sum + g.cycles, 0n),
254
+ groups: profiled,
255
+ env: { debugger: options.debugger, network: plan.network, rpcUrl: plan.rpcUrl, scriptVersion: plan.scriptVersion },
256
+ };
257
+ }
258
+ /** How a profile's total compares with the node's: what the CLI and the web page both print. */
259
+ export function nodeVerdict(p) {
260
+ if (p.nodeCycles !== undefined)
261
+ return p.nodeCycles === p.measuredCycles ? "match" : "mismatch";
262
+ return p.status === "committed" ? "not recorded" : undefined;
263
+ }
264
+ /**
265
+ * Reads a transaction from JSON in any of the shapes people have at hand: the
266
+ * node's RPC shape, a `get_transaction` result (`{ transaction }`), or a CCC
267
+ * transaction saved with `ccc.stringify`.
268
+ */
269
+ export function readTransactionJson(json) {
270
+ let value = JSON.parse(json);
271
+ if (value && typeof value === "object" && "transaction" in value)
272
+ value = value.transaction;
273
+ if (value && typeof value === "object" && "cellDeps" in value) {
274
+ const tx = cccA.JsonRpcTransformers.transactionFrom(ccc.Transaction.from(value));
275
+ // CCC leaves out an absent type; the node writes it as null.
276
+ return { ...tx, outputs: tx.outputs.map((o) => ({ ...o, type: o.type ?? null })) };
277
+ }
278
+ if (!value || typeof value !== "object" || !Array.isArray(value.cell_deps) || !Array.isArray(value.inputs)) {
279
+ throw new Error("not a CKB transaction: expected RPC fields (cell_deps, inputs, …) or a CCC transaction");
280
+ }
281
+ return value;
282
+ }
283
+ const HASH_TYPES = ["type", "data", "data1", "data2"];
284
+ /** `--name 0xabc…=campaign-lock` (or `0xabc…:type=…`) → profileTransaction's scriptNames. */
285
+ export function parseNames(flags) {
286
+ const names = {};
287
+ for (const flag of flags) {
288
+ const m = /^(0x[0-9a-fA-F]{64})(?::(\w+))?=(.+)$/.exec(flag);
289
+ if (!m || (m[2] && !HASH_TYPES.includes(m[2]))) {
290
+ throw new Error(`--name expects <code-hash>[:<hash-type>]=<label>, got "${flag}"`);
291
+ }
292
+ for (const t of m[2] ? [m[2]] : HASH_TYPES)
293
+ names[`${m[1].toLowerCase()}:${t}`] = m[3];
294
+ }
295
+ return names;
296
+ }
@@ -0,0 +1,90 @@
1
+ import type { CycleReport, GroupResult, ScenarioResult } from "./diff.js";
2
+ import { type RpcOutPoint } from "./mock.js";
3
+ import { type Profile, type ProfileOptions } from "./profile.js";
4
+ export interface BinaryConfig {
5
+ /** The built binary, relative to the config file. */
6
+ path: string;
7
+ outPoint?: RpcOutPoint;
8
+ codeHash?: string;
9
+ /**
10
+ * An unstripped build of the same code, relative to the config file like
11
+ * `path`: run in ckb-debugger's flamegraph mode (`--bin`) to name the
12
+ * functions, in scenarios that ask for `functions`.
13
+ */
14
+ symbols?: string;
15
+ }
16
+ export interface ScenarioConfig {
17
+ name: string;
18
+ tx?: string;
19
+ file?: string;
20
+ mock?: string;
21
+ /**
22
+ * Binaries to substitute, by name. Each must match a cell dep of this
23
+ * scenario. Without it, every binary is offered, and used where it matches.
24
+ */
25
+ binaries?: string[];
26
+ /** CKB-VM version for `hash_type: "type"` scripts; default: the block's, or 2. */
27
+ scriptVersion?: 0 | 1 | 2;
28
+ /** Record the costliest functions of each group whose binary has `symbols`. Default: the config's `functions`. */
29
+ functions?: boolean;
30
+ }
31
+ export interface CyclesConfig {
32
+ network?: "testnet" | "mainnet";
33
+ /** A node for `tx` and `file` scenarios, instead of the public one. */
34
+ rpc?: string;
35
+ /** `<code-hash>[:<hash-type>]` → label, as `--name` takes them. */
36
+ names?: Record<string, string>;
37
+ binaries?: Record<string, BinaryConfig>;
38
+ /** The default of every scenario's `functions`. */
39
+ functions?: boolean;
40
+ scenarios: ScenarioConfig[];
41
+ }
42
+ /** Parses and checks a cycles.json, with a message that says what to fix. */
43
+ export declare function parseCyclesConfig(json: string): CyclesConfig;
44
+ export interface ReportOptions {
45
+ debuggerPath?: string;
46
+ /** Overrides the config's node. */
47
+ rpcUrl?: string;
48
+ /** Per RPC request, in milliseconds. Default 30 s. */
49
+ timeoutMs?: number;
50
+ /**
51
+ * Where binary paths resolve, instead of the config file's directory: a
52
+ * checkout of the base commit, so the base report replays the same scenarios
53
+ * with the binaries built from the base.
54
+ */
55
+ binariesRoot?: string;
56
+ /**
57
+ * Directories every file the config names (mocks, transaction files,
58
+ * binaries, symbols builds) must be inside, symlinks resolved: in CI, the
59
+ * checkouts, so a pull request's cycles.json cannot read the rest of the
60
+ * runner into the report. Default: anywhere.
61
+ */
62
+ roots?: string[];
63
+ /** Called as each scenario finishes, for progress output. */
64
+ onScenario?: (s: ScenarioResult) => void;
65
+ /** Runs ckb-debugger instead of the native binary (see ProfileOptions): for tests. */
66
+ runDebugger?: ProfileOptions["runDebugger"];
67
+ }
68
+ export declare function groupResults(p: Profile): GroupResult[];
69
+ /**
70
+ * Runs every scenario of a cycles.json. A scenario that cannot run is recorded
71
+ * with its error rather than ending the report, so one broken scenario does not
72
+ * hide the others' numbers.
73
+ */
74
+ export declare function runReport(configPath: string, options?: ReportOptions): Promise<CycleReport & {
75
+ errors: string[];
76
+ notices?: string[];
77
+ }>;
78
+ /**
79
+ * `file` with its symlinks resolved, when it is inside one of `roots` (already
80
+ * resolved); an error otherwise. A file that does not exist is checked by its
81
+ * path and returned as given, so reading it fails with the usual ENOENT (a
82
+ * binary absent from the base is a new binary, not an error).
83
+ */
84
+ export declare function confine(file: string, roots: string[] | undefined): Promise<string>;
85
+ /**
86
+ * The report for a terminal: one block per scenario. Every name, warning and
87
+ * error from the config, the build or the debugger goes through termLine (or
88
+ * termLines), so none can start a log line of its own.
89
+ */
90
+ export declare function formatReport(report: CycleReport): string;