ckb-vm-js 0.0.0-bootstrap.0 → 0.2.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/LICENSE +21 -0
- package/README.md +141 -2
- package/THIRD_PARTY_NOTICES.md +2317 -0
- package/crates/verifier/SCHEMA.md +114 -0
- package/docs/javascript.md +187 -0
- package/docs/local-first-publish.md +168 -0
- package/docs/playground.md +90 -0
- package/docs/publishing.md +98 -0
- package/docs/verification.md +92 -0
- package/js/index.d.ts +106 -0
- package/js/index.js +84 -0
- package/js/worker.js +23 -0
- package/package.json +42 -3
- package/pkg/ckb_wasm_verifier.d.ts +44 -0
- package/pkg/ckb_wasm_verifier.js +222 -0
- package/pkg/ckb_wasm_verifier_bg.wasm +0 -0
- package/pkg/ckb_wasm_verifier_bg.wasm.d.ts +13 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Offline verifier request (foundation API)
|
|
2
|
+
|
|
3
|
+
`verify_json(json: &str) -> String` is the native API. WASM exports `verify(json: string): string`. Both return JSON, including on ordinary input/verification errors. No networking or chain-state maintenance is performed.
|
|
4
|
+
|
|
5
|
+
```js
|
|
6
|
+
{
|
|
7
|
+
transaction: { /* CKB RPC Transaction, including witnesses */ },
|
|
8
|
+
context: {
|
|
9
|
+
tip_header: { /* current chain tip RPC Header */ },
|
|
10
|
+
consensus: {
|
|
11
|
+
tx_version: '0x...', max_block_bytes: '0x...', max_block_cycles: '0x...',
|
|
12
|
+
cellbase_maturity: '0x...', median_time_block_count: '0x...',
|
|
13
|
+
tx_proposal_window: { closest: '0x...', farthest: '0x...' },
|
|
14
|
+
dao_type_hash: '0x...',
|
|
15
|
+
hardforks: {
|
|
16
|
+
rfc0028_epoch: '0x...', rfc0032_epoch: '0x...',
|
|
17
|
+
rfc0049_epoch: '0x...', rfc0044_epoch: '0x...',
|
|
18
|
+
},
|
|
19
|
+
starting_block_limiting_dao_withdrawing_lock: '0x...',
|
|
20
|
+
},
|
|
21
|
+
// Optional; omitting it selects submitted mode.
|
|
22
|
+
verification: { phase: 'submitted' },
|
|
23
|
+
headers: [ /* RPC Header objects */ ],
|
|
24
|
+
cells: [{
|
|
25
|
+
out_point: { tx_hash: '0x...32 bytes', index: '0x0' },
|
|
26
|
+
output: { capacity: '0x...', lock: { /* RPC Script */ }, type: null },
|
|
27
|
+
data: '0x...',
|
|
28
|
+
transaction_info: {
|
|
29
|
+
block_hash: '0x...32 bytes', block_number: '0x...',
|
|
30
|
+
block_epoch: '0x...', index: '0x1',
|
|
31
|
+
},
|
|
32
|
+
}],
|
|
33
|
+
extensions: [{ block_hash: '0x...32 bytes', data: null }],
|
|
34
|
+
},
|
|
35
|
+
max_cycles: '0x989680',
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
This is a shape illustration, not runnable JSON or a network preset. Use `ckb-jsonrpc-types` Transaction, Header, OutPoint, CellOutput, and Script shapes. Integer quantities use canonical RPC `0x` strings; byte fields use even-length `0x` strings. Own wrapper objects reject unknown fields. Upstream RPC objects follow upstream serde parsing. Headers are keyed by their recomputed hashes rather than a separately asserted hash. RPC-view `hash` is optional on transactions and headers; when present it must equal the hash recomputed from the object. A mismatch is rejected, and a match does not establish chain authenticity.
|
|
40
|
+
|
|
41
|
+
## Explicit consensus parameters
|
|
42
|
+
|
|
43
|
+
There is no `network` field, bundled-network selection, or remote lookup. The caller must supply the transaction-relevant parameters for its intended chain and rules:
|
|
44
|
+
|
|
45
|
+
| Field | Meaning |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| `tx_version` | Required transaction version, RPC uint32 |
|
|
48
|
+
| `max_block_bytes` | Upstream transaction size-check limit |
|
|
49
|
+
| `max_block_cycles` | Ceiling for the request's `max_cycles` |
|
|
50
|
+
| `cellbase_maturity` | Packed CKB epoch-with-fraction duration |
|
|
51
|
+
| `median_time_block_count` | Positive median-time window length |
|
|
52
|
+
| `tx_proposal_window` | `closest` and `farthest` block distances |
|
|
53
|
+
| `dao_type_hash` | 32-byte DAO type-script code hash |
|
|
54
|
+
| `hardforks.rfc0028_epoch` | Relative timestamp-since start rule activation |
|
|
55
|
+
| `hardforks.rfc0032_epoch` | VM version 1 / syscall-version activation |
|
|
56
|
+
| `hardforks.rfc0049_epoch` | VM version 2 activation |
|
|
57
|
+
| `hardforks.rfc0044_epoch` | Committed-block DAO lock-size rule activation |
|
|
58
|
+
| `starting_block_limiting_dao_withdrawing_lock` | Creation-block threshold used by the DAO lock-size verifier |
|
|
59
|
+
|
|
60
|
+
Except `tx_version` and the hash, these are RPC uint64 hex strings; epoch activation fields are epoch **numbers**, not packed fractions. Byte/cycle limits must be positive; the median count is in `1..=u32::MAX`, maturity must be a well-formed epoch fraction, and `closest <= farthest`. The parameter set covers the audited transaction paths in the pinned upstream, not every full-node consensus setting. TYPE_ID is upstream's protocol constant. PoW, rewards and genesis configuration are not transaction-verifier inputs here. Several historical rules are unconditional in this upstream revision: configurable activation epochs are **not** a promise of arbitrary historical consensus replay.
|
|
61
|
+
|
|
62
|
+
## Verification environment
|
|
63
|
+
|
|
64
|
+
`tip_header` always means the caller's **current existing tip**.
|
|
65
|
+
|
|
66
|
+
- **Submitted (default):** `verification: { phase: 'submitted' }` uses `TxVerifyEnv::new_submit(tip_header)`. Block-number `since` uses the earliest commitment height `tip.number + 1 + closest`. Timestamp median ancestry starts at the tip itself. Maturity and epoch-fraction comparisons use the tip epoch as upstream does; hardfork projections follow upstream's separate rules. This is not equivalent to fabricating a candidate header or promising pool acceptance.
|
|
67
|
+
- **Committed:** `verification: { phase: 'committed', candidate_header: { /* RPC Header */ }, transaction_index: '0x1' }` uses `TxVerifyEnv::new_commit(candidate_header)`. The candidate's parent hash must equal the supplied tip hash and its number must be tip number plus one. The target transaction index is in `1..=u32::MAX` because index zero is cellbase. This mode checks exact proposed placement, not proof the candidate has been mined or accepted. Timestamp median ancestry starts at the candidate parent, i.e. the supplied tip.
|
|
68
|
+
|
|
69
|
+
The upstream pool applies the DAO script-size check unconditionally in submitted mode. Committed mode applies it when the **parent's epoch number** reaches `rfc0044_epoch`; it does not use the candidate's projected activation epoch for this gate.
|
|
70
|
+
|
|
71
|
+
Standalone cellbase transactions are rejected because reward and block-level structure verification is outside this API. The separate upstream already-proposed pool phase is not exposed.
|
|
72
|
+
|
|
73
|
+
## Cells, headers and extensions
|
|
74
|
+
|
|
75
|
+
Include every input, code dependency, dep-group cell and expanded dep-group member. Duplicate cells, headers and extension entries are rejected. Do not repeat `tip_header` or an explicit candidate header in `headers`.
|
|
76
|
+
|
|
77
|
+
`transaction_info` is required but nullable:
|
|
78
|
+
|
|
79
|
+
- An object asserts a known creation block. The block number and packed epoch must agree with its supplied creation header. `index` is the creating transaction's index within that block, **not** the output index; zero means cellbase, and the index must fit uint32. A known creation block cannot be beyond the supplied verification environment. At its latest height, its hash must match the supplied tip or candidate, respectively. In committed mode, a same-block ancestor is allowed when its creation hash is the candidate hash and its transaction index is less than the target `transaction_index`.
|
|
80
|
+
- `null` explicitly asserts an **unconfirmed, non-cellbase** origin. It is not an abbreviation for forgotten creation metadata. Upstream skips cellbase-maturity classification for such origins; supplying null for an actually confirmed/cellbase cell can therefore misrepresent the context. Relative `since` cannot mature without creation metadata, and header/extension syscalls cannot obtain a creation block for it. Final DAO withdrawal also requires the appropriate known origin. Ordinary zero-since spending can be checked against this asserted unconfirmed cell.
|
|
81
|
+
|
|
82
|
+
Include declared header deps, known cell creation headers and sufficient linked ancestors for timestamp-based `since`. Pre-RFC0028 relative timestamp checks can additionally require ancestors starting at the creation header's parent. The configured median window ends early at genesis. Missing required context is an error, not a successful check.
|
|
83
|
+
|
|
84
|
+
Include an explicit extension entry for every declared header dep and each known creation block of resolved inputs/expanded dependencies. `data: null` asserts that no extension exists; omitting `data` or a required entry does not imply absence. A dep-group container needs its cell bytes and known creation metadata, but is not itself an executable expanded dependency unless separately referenced as one.
|
|
85
|
+
|
|
86
|
+
## Results and selected groups
|
|
87
|
+
|
|
88
|
+
Optional top-level `script_group: { group_type: 'lock' | 'type', script_hash: '0x...32 bytes' }` selects only one group. Successful group verification does **not** establish capacity, maturity, since, DAO rules or correctness of other groups. The complete snapshot is still parsed/resolved and noncontextual checks still run.
|
|
89
|
+
|
|
90
|
+
Success:
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{"ok":true,"scope":"transaction","cycles":"0x...","fee":"0x...","groups":[{"group_type":"lock","script_hash":"0x...","input_indices":[0],"output_indices":[]}],"chain_state_verified":false}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Failure:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{"ok":false,"error":{"code":"MissingContext","message":"..."}}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Script-group success uses `scope: "script_group"` and omits `fee`. Group order is not contractual. Error messages are diagnostic and may change with upstream releases.
|
|
103
|
+
|
|
104
|
+
## Scope and trust
|
|
105
|
+
|
|
106
|
+
Full mode runs upstream resolution, noncontextual verification, contextual maturity/since/capacity/scripts/DAO fee validation, and the supplemental DAO script-size rule. Max cycles cannot exceed the supplied consensus ceiling. Scripts use upstream CKB-VM, TYPE_ID and CKB syscalls.
|
|
107
|
+
|
|
108
|
+
Success is conditional on caller-supplied facts **and parameters**. It does not authenticate cell contents against outpoint transaction hashes, prove transaction inclusion, verify PoW, authenticate extensions against commitments, establish canonical ancestry/fork choice, check liveness or double spends elsewhere, prove proposal inclusion, or verify block aggregate limits/rewards. Known same-block index checks do not validate the rest of the candidate block. The caller remains responsible for truth, completeness and consistency of external state beyond the local checks.
|
|
109
|
+
|
|
110
|
+
Use a Web Worker to avoid blocking the browser UI. Enforce application-level JSON/snapshot-size limits; VM cycle limits do not bound parsing or snapshot memory.
|
|
111
|
+
|
|
112
|
+
## Migrating from v0.1
|
|
113
|
+
|
|
114
|
+
Remove `context.network` and supply explicit consensus parameters. The old `tip_header` meant a candidate block: move it to `verification.candidate_header`, set `phase: 'committed'`, add the target `transaction_index`, and put its actual parent into the new `tip_header`. Remove that parent from the separate headers array to avoid duplication. Omitting `verification` now means submitted mode, intentionally not an automatic compatibility alias. JS methods and result shapes remain unchanged.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# JavaScript and TypeScript API
|
|
2
|
+
|
|
3
|
+
Build the Rust/WASM package before importing the default bindings. The generated
|
|
4
|
+
web-target wasm-bindgen files must be under `pkg/`. The package is ESM and includes
|
|
5
|
+
TypeScript declarations. `verify` performs no network requests; all transaction
|
|
6
|
+
inputs, dependencies and contextual data come from the request.
|
|
7
|
+
|
|
8
|
+
## Node: explicit offline initialization
|
|
9
|
+
|
|
10
|
+
```js
|
|
11
|
+
import { readFile } from 'node:fs/promises';
|
|
12
|
+
import { createVerifier } from './js/index.js';
|
|
13
|
+
|
|
14
|
+
const wasm = await readFile('./pkg/ckb_wasm_verifier_bg.wasm');
|
|
15
|
+
const verifier = await createVerifier({ wasm });
|
|
16
|
+
const request = JSON.parse(await readFile('./request.json', 'utf8'));
|
|
17
|
+
const result = await verifier.verify(request);
|
|
18
|
+
if (!result.ok) console.error(result.error.code, result.error.message);
|
|
19
|
+
else console.log(result.scope, result.cycles, result.fee);
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Pass `Uint8Array`, `ArrayBuffer`, or a compiled `WebAssembly.Module` to initialize
|
|
23
|
+
without fetching. Browser initialization without `wasm` loads the packaged WASM
|
|
24
|
+
URL. URL/string inputs may fetch during initialization only. Bundlers can supply
|
|
25
|
+
`loadBindings: () => import('./generated/ckb_wasm_verifier.js')` to select a custom
|
|
26
|
+
binding location.
|
|
27
|
+
|
|
28
|
+
All CKB integer request and response fields use RPC hex strings, never JavaScript
|
|
29
|
+
`number` or `bigint`. Script-group input/output indices are ordinary numbers.
|
|
30
|
+
|
|
31
|
+
## Install a built tarball
|
|
32
|
+
|
|
33
|
+
The GitHub CI artifact contains a ready-to-install `.tgz`. No npm registry
|
|
34
|
+
release is claimed. After downloading and extracting the CI artifact:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
npm install ./ckb-vm-js-0.2.0.tgz
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```js
|
|
41
|
+
import { readFile } from 'node:fs/promises';
|
|
42
|
+
import { createVerifier } from 'ckb-vm-js';
|
|
43
|
+
const wasm = await readFile(new URL(import.meta.resolve(
|
|
44
|
+
'ckb-vm-js/wasm',
|
|
45
|
+
)));
|
|
46
|
+
const verifier = await createVerifier({ wasm });
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Verify a script group
|
|
50
|
+
|
|
51
|
+
```js
|
|
52
|
+
const result = await verifier.verifyScriptGroup(request, {
|
|
53
|
+
group_type: 'lock', // or 'type'
|
|
54
|
+
script_hash: '0x' + 'ab'.repeat(32), // replace with the actual script hash
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The selector is a script hash, not a code hash. This returns `scope: 'script_group'`
|
|
59
|
+
and verifies the selected group's scripts, after shared request/context checks.
|
|
60
|
+
It does not assert that all other groups or all contextual transaction rules pass.
|
|
61
|
+
The input request is not mutated. `verify(request)` can also accept `script_group`.
|
|
62
|
+
|
|
63
|
+
## Browser: keep verification off the UI thread
|
|
64
|
+
|
|
65
|
+
```js
|
|
66
|
+
import { createWorkerVerifier } from './js/index.js';
|
|
67
|
+
|
|
68
|
+
const verifier = await createWorkerVerifier({ wasm: wasmBytes });
|
|
69
|
+
try {
|
|
70
|
+
const result = await verifier.verify(request);
|
|
71
|
+
console.log(result);
|
|
72
|
+
} finally {
|
|
73
|
+
verifier.dispose();
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
A dedicated ES-module Worker runs the same synchronous WASM engine. No
|
|
78
|
+
`SharedArrayBuffer`, pthreads, COOP or COEP headers are needed. The direct API returns
|
|
79
|
+
Promises but still runs CPU work on the calling thread. The Worker API keeps the
|
|
80
|
+
calling thread responsive; it does not make one verification parallel.
|
|
81
|
+
|
|
82
|
+
The default Worker URL is `js/worker.js`. A bundler can supply `workerURL`, or a
|
|
83
|
+
`worker` implementing the browser Worker interface. The client owns and terminates
|
|
84
|
+
caller-supplied Workers too. This helper is for browser Workers; Node users should
|
|
85
|
+
use the direct byte-loading API or write a `worker_threads` adapter.
|
|
86
|
+
|
|
87
|
+
Worker inputs must be structured-cloneable. Pass bytes/module or a URL string,
|
|
88
|
+
not a `Response`, `Request`, binding loader function, or URL object. Bytes are
|
|
89
|
+
cloned, not detached. Calls are correlated by ID; disposing rejects pending and
|
|
90
|
+
future requests. Disposing terminates the Worker, including active WASM work.
|
|
91
|
+
A Worker error also terminates it and rejects pending work. Create a new verifier
|
|
92
|
+
to restart.
|
|
93
|
+
|
|
94
|
+
## Snapshot contract and errors
|
|
95
|
+
|
|
96
|
+
Supply `context.consensus` explicitly. The foundational API has no `network`
|
|
97
|
+
selector, bundled network presets, or network-maintenance wrapper. The caller owns
|
|
98
|
+
consensus configuration and snapshot freshness. Consensus fields are:
|
|
99
|
+
|
|
100
|
+
- `tx_version`, `max_block_bytes`, `max_block_cycles`, `cellbase_maturity`, and
|
|
101
|
+
`median_time_block_count`.
|
|
102
|
+
- `tx_proposal_window: { closest, farthest }` and `dao_type_hash`.
|
|
103
|
+
- `hardforks: { rfc0028_epoch, rfc0032_epoch, rfc0049_epoch, rfc0044_epoch }`.
|
|
104
|
+
- `starting_block_limiting_dao_withdrawing_lock`.
|
|
105
|
+
|
|
106
|
+
Use RPC hex strings for all these values, including activation epochs and limits.
|
|
107
|
+
`dao_type_hash` is a 32-byte hash. A cycle budget must be within the supplied
|
|
108
|
+
`max_block_cycles`. Pass all fields; the verifier does not infer a network.
|
|
109
|
+
|
|
110
|
+
`context.tip_header` is the **actual current chain tip**. Verification defaults to
|
|
111
|
+
submitted mode when `context.verification` is omitted. You can select it explicitly:
|
|
112
|
+
|
|
113
|
+
```js
|
|
114
|
+
const submitted = await verifier.verify({
|
|
115
|
+
...request,
|
|
116
|
+
context: { ...request.context, verification: { phase: 'submitted' } },
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
For checking inclusion in a specific candidate block, supply committed mode:
|
|
121
|
+
|
|
122
|
+
```js
|
|
123
|
+
const committed = await verifier.verify({
|
|
124
|
+
...request,
|
|
125
|
+
context: {
|
|
126
|
+
...request.context,
|
|
127
|
+
verification: {
|
|
128
|
+
phase: 'committed',
|
|
129
|
+
candidate_header: candidateHeader,
|
|
130
|
+
transaction_index: '0x1',
|
|
131
|
+
},
|
|
132
|
+
},
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The candidate must be a direct child of `tip_header`. `transaction_index` must be
|
|
137
|
+
positive: position zero is reserved for cellbase. For known same-block inputs, prefer
|
|
138
|
+
their actual candidate-block origin and earlier transaction index. This lets the
|
|
139
|
+
verifier check ordering within the candidate block.
|
|
140
|
+
The existing `valid.json` fixture uses explicit committed mode; `submitted-valid`
|
|
141
|
+
exercises the omitted/default mode.
|
|
142
|
+
|
|
143
|
+
`context.headers`, `context.extensions`, and every cell's `transaction_info` are
|
|
144
|
+
required, even when an array is empty. `transaction_info` may be an origin object
|
|
145
|
+
with `block_hash`, `block_number`, `block_epoch`, and `index`, or explicit `null`.
|
|
146
|
+
Null is a caller assertion that the cell is non-cellbase with an unknown or
|
|
147
|
+
unconfirmed origin. It is accepted in both submitted and committed modes, but
|
|
148
|
+
does not prove that its producing transaction is valid or establish its position
|
|
149
|
+
within a candidate block. Relative-since checks need a known origin and remain
|
|
150
|
+
immature without one. Do not omit the field. Prefer real origin metadata for
|
|
151
|
+
committed verification, especially for known same-block inputs; the caller remains
|
|
152
|
+
responsible for block-wide validity and ordering that null metadata cannot prove.
|
|
153
|
+
|
|
154
|
+
Supply the creation headers for confirmed resolved cells and any
|
|
155
|
+
header/median-time/DAO dependencies needed by the transaction. Supply an explicit
|
|
156
|
+
extension entry with hex data or `null` for each required creation block and
|
|
157
|
+
header dependency. Omission does not mean “no extension.”
|
|
158
|
+
|
|
159
|
+
A successful result is relative to the caller's snapshot and supplied consensus.
|
|
160
|
+
It has `chain_state_verified: false`: it does not prove cells are live, header
|
|
161
|
+
chain canonicality, chain authenticity, or network acceptance. Cellbase
|
|
162
|
+
transactions are unsupported. Untrusted requests can consume substantial CPU and
|
|
163
|
+
memory; bound request size and use a Worker you can terminate for application-level
|
|
164
|
+
timeouts.
|
|
165
|
+
|
|
166
|
+
Verification rejection returns `{ ok: false, error: { code, message } }`.
|
|
167
|
+
Initialization failures, WASM traps, malformed JS/JSON, and Worker transport
|
|
168
|
+
failures reject the returned Promise. Handle both outcomes.
|
|
169
|
+
|
|
170
|
+
## Tests
|
|
171
|
+
|
|
172
|
+
- `npm test`: mocked JS boundary and Worker protocol unit tests. These do not
|
|
173
|
+
exercise CKB consensus or the WASM engine.
|
|
174
|
+
- `npm run typecheck`: check declarations and exported API usage.
|
|
175
|
+
- `npm run test:wasm`: require real generated WASM, then run every
|
|
176
|
+
`fixtures/*.json` case shaped as `{ "request": ..., "expected": ... }`.
|
|
177
|
+
Every expected top-level response field is compared deeply. Set
|
|
178
|
+
`CKB_WASM_FIXTURE` to run one fixture file instead. Missing real WASM fails the
|
|
179
|
+
suite; an empty fixture directory is reported as a skipped fixture test.
|
|
180
|
+
|
|
181
|
+
- `npm run test:browser`: real dedicated Worker verification, with isolation off,
|
|
182
|
+
SharedArrayBuffer absent, and browser networking disabled after initialization.
|
|
183
|
+
Covers default submitted, unconfirmed input, same-block input, explicit
|
|
184
|
+
committed, selected-lock, and rejecting script fixtures. Requires built WASM
|
|
185
|
+
and a supported Playwright browser runtime.
|
|
186
|
+
- `npm run test:differential`: compare every fixture's actual native CLI and WASM
|
|
187
|
+
output, normalizing script-group order. Requires both built artifacts.
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# 从 clone 到本地首次发布 0.2.0
|
|
2
|
+
|
|
3
|
+
这份说明针对维护者用自己的 npm 账号完成首次公开发布。**只 clone 后运行 `npm install` / `npm pack` 不够**:仓库不提交生成的 `pkg/`,必须先构建 WASM,再测试实际 tarball。任何一步失败都先停止,不要继续 publish。
|
|
4
|
+
|
|
5
|
+
## 平台与工具
|
|
6
|
+
|
|
7
|
+
本次实际验证环境为 **Linux x86_64**,Node 24、Rust 1.95.0、wasm-bindgen 0.2.105、WASI SDK 34 的 clang,以及 Playwright Chromium Headless Shell。普通 CI 使用 Ubuntu 24.04、Node 22 和系统 clang。npm 包运行时声明 Node >=20,不等于所有构建主机均已测试。
|
|
8
|
+
|
|
9
|
+
- Ubuntu/Debian:安装原生 C 编译器、Git、curl、tar、Python 3;例如 `sudo apt-get update && sudo apt-get install -y build-essential pkg-config libssl-dev git curl ca-certificates python3`。下文单独安装的 WASI SDK 提供 WASM clang。
|
|
10
|
+
- macOS:先安装 Xcode Command Line Tools(`xcode-select --install`,如弹出协议由你自己完成),以及 Git、curl、tar、Python 3。原生 Rust 构建用 Xcode 的 C 工具链;WASM 部分用下文按 Intel / Apple Silicon 区分的 WASI SDK。**这些 macOS 命令按官方 SDK 资产写出,本次没有在 macOS 实机验证。**
|
|
11
|
+
- Windows:本次没有验证原生 Windows 构建;建议在 WSL2 Ubuntu 中执行 Linux 路径。
|
|
12
|
+
- 安装 [Node.js 24](https://nodejs.org/en/download) 和 [rustup](https://rustup.rs/),重新打开终端后确认 `node --version`、`npm --version`、`rustup --version` 可用。Rust 的具体版本和组件由仓库 `rust-toolchain.toml` 固定;不要仅安装发行版的旧 cargo。
|
|
13
|
+
- 构建会下载 Git 子模块、Cargo/npm 依赖和浏览器,需要网络及数 GB 可用磁盘空间。普通 Node/npm 包消费者不需要这些编译工具。
|
|
14
|
+
|
|
15
|
+
## 1. 克隆 main
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
git clone --branch main --recurse-submodules \
|
|
19
|
+
https://github.com/Hanssen0-Alter-Ego/ckb-vm-js.git
|
|
20
|
+
cd ckb-vm-js
|
|
21
|
+
git rev-parse HEAD
|
|
22
|
+
git submodule status --recursive
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
将 HEAD 与最终发布交接中报告的 main 完整 SHA 对照;并行开发可能继续推进 main,不要把未经确认的新提交自动当作已验收发布对象。若最初忘了 `--recurse-submodules`,补跑 `git submodule update --init --recursive`。以下原生对照构建要求**全新、尚未执行 prepare.sh 的子模块**;脚本会在后续有意打补丁,之后看到两个 vendor 子模块有修改属于预期,不要把它们作为新 gitlink 提交。
|
|
26
|
+
|
|
27
|
+
## 2. 安装固定工具链和 WASM clang
|
|
28
|
+
|
|
29
|
+
在仓库根目录执行。下面的脚本选择官方 WASI SDK 34 资产,并按发布资产的 SHA256 校验;未列出的主机直接停止。
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
set -eu
|
|
33
|
+
rustup show
|
|
34
|
+
cargo install wasm-bindgen-cli --version 0.2.105 --locked
|
|
35
|
+
wasm-bindgen --version
|
|
36
|
+
npm ci --ignore-scripts
|
|
37
|
+
|
|
38
|
+
case "$(uname -s)/$(uname -m)" in
|
|
39
|
+
Linux/x86_64)
|
|
40
|
+
sdk_host=x86_64-linux
|
|
41
|
+
sdk_sha=b761e3a0721dbae9c09a0059e5fdb2bf917d1b4a8a7b430fb3b5aafb0984b2c4 ;;
|
|
42
|
+
Linux/aarch64|Linux/arm64)
|
|
43
|
+
sdk_host=arm64-linux
|
|
44
|
+
sdk_sha=f7e243dff54d60bcc576e94d6166b69f410f2500ae4a9ceef34315be10e77971 ;;
|
|
45
|
+
Darwin/x86_64)
|
|
46
|
+
sdk_host=x86_64-macos
|
|
47
|
+
sdk_sha=87d27fa8adc68dee59bfbf2e22a6d34ef717c34d6bf1d8af2a56fc929d9ce0eb ;;
|
|
48
|
+
Darwin/arm64)
|
|
49
|
+
sdk_host=arm64-macos
|
|
50
|
+
sdk_sha=9c59398106b417f8f14913380fdf0097a8cc0ff4af9eb3ce0065a859e88d49e9 ;;
|
|
51
|
+
*) echo '此主机未列入本说明;先确认官方 SDK 和构建支持。' >&2; exit 1 ;;
|
|
52
|
+
esac
|
|
53
|
+
mkdir -p .local-tools
|
|
54
|
+
sdk_archive=".local-tools/wasi-sdk-34.0-${sdk_host}.tar.gz"
|
|
55
|
+
curl -fL --retry 3 \
|
|
56
|
+
"https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-34/wasi-sdk-34.0-${sdk_host}.tar.gz" \
|
|
57
|
+
-o "$sdk_archive"
|
|
58
|
+
python3 - "$sdk_archive" "$sdk_sha" <<'PY'
|
|
59
|
+
import hashlib, pathlib, sys
|
|
60
|
+
actual = hashlib.sha256(pathlib.Path(sys.argv[1]).read_bytes()).hexdigest()
|
|
61
|
+
if actual != sys.argv[2]:
|
|
62
|
+
raise SystemExit('WASI SDK SHA256 mismatch; stop')
|
|
63
|
+
print('WASI SDK SHA256 OK')
|
|
64
|
+
PY
|
|
65
|
+
tar -xzf "$sdk_archive" -C .local-tools
|
|
66
|
+
export CC_wasm32_unknown_unknown="$PWD/.local-tools/wasi-sdk-34.0-${sdk_host}/bin/clang"
|
|
67
|
+
"$CC_wasm32_unknown_unknown" --version
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
来源:[WASI SDK 34 官方发布](https://github.com/WebAssembly/wasi-sdk/releases/tag/wasi-sdk-34)。这里只使用它的 clang 来编译上游 C 代码;Rust 目标仍是 **`wasm32-unknown-unknown`,不是 WASI**。也可使用支持 WebAssembly target 的系统 LLVM clang 并设同一环境变量;macOS 的 Apple clang 不应被直接当作已经验证的 WASM clang。若新开终端,需重新设置 `CC_wasm32_unknown_unknown`。
|
|
71
|
+
|
|
72
|
+
## 3. 构建并验证源码
|
|
73
|
+
|
|
74
|
+
先构建未打兼容补丁的原生对照,再准备实际构建:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
set -eu
|
|
78
|
+
cargo build --locked -p ckb-wasm-verifier --bin verify
|
|
79
|
+
cp target/debug/verify target/verify-upstream
|
|
80
|
+
./scripts/prepare.sh
|
|
81
|
+
cargo fmt --all -- --check
|
|
82
|
+
cargo clippy --locked -p ckb-wasm-verifier --all-targets --no-deps -- -D warnings
|
|
83
|
+
cargo test --locked -p ckb-wasm-verifier
|
|
84
|
+
cargo build --locked -p ckb-wasm-verifier --bin verify
|
|
85
|
+
npm test
|
|
86
|
+
npm run typecheck
|
|
87
|
+
./scripts/build-wasm.sh
|
|
88
|
+
npm run test:wasm
|
|
89
|
+
npm run test:differential
|
|
90
|
+
CKB_NATIVE_VERIFY="$PWD/target/verify-upstream" npm run test:differential
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`build-wasm.sh` 再次调用 prepare.sh 是幂等操作。若在已打补丁的 checkout 中重新跑第一行,所得对照就不是未修改上游;需要重新验证该对照时使用新的 clone,不要强制清除自己已有改动。
|
|
94
|
+
|
|
95
|
+
浏览器验证:
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
# Linux(可能由 Playwright 调用 sudo 安装浏览器系统依赖):
|
|
99
|
+
npx playwright install --with-deps chromium --only-shell
|
|
100
|
+
# macOS 用这一行替代上一行:
|
|
101
|
+
# npx playwright install chromium --only-shell
|
|
102
|
+
npm run test:browser
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
这里使用项目锁定的 Playwright 版本及其官方 headless-shell,不必另外设置浏览器可执行路径。浏览器缓存或临时目录空间不足时,可将 `PLAYWRIGHT_BROWSERS_PATH` 和 `TMPDIR` 指向自己有空间的目录;安装及测试应使用相同变量。
|
|
106
|
+
|
|
107
|
+
## 4. 打包一次,验证将要发布的同一文件
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
set -eu
|
|
111
|
+
test -s pkg/ckb_wasm_verifier_bg.wasm
|
|
112
|
+
test -s pkg/ckb_wasm_verifier.js
|
|
113
|
+
test -s pkg/ckb_wasm_verifier.d.ts
|
|
114
|
+
node --input-type=module -e '
|
|
115
|
+
import fs from "node:fs";
|
|
116
|
+
const p = JSON.parse(fs.readFileSync("package.json"));
|
|
117
|
+
if (p.name !== "ckb-vm-js" || p.version !== "0.2.0") throw Error("Unexpected first-release identity");
|
|
118
|
+
'
|
|
119
|
+
npm pack --ignore-scripts
|
|
120
|
+
node scripts/test-package.mjs
|
|
121
|
+
RELEASE_TAG=v0.2.0 node scripts/release.mjs artifact
|
|
122
|
+
cat dist/SHA256SUMS
|
|
123
|
+
tar -tzf dist/ckb-vm-js-0.2.0.tgz
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
`test-package.mjs` 将该 tarball 安装到空 consumer,验证文件清单、Node 实际 WASM、公开类型、浏览器和真实 Worker,覆盖四处 optional hash 的接受及 mismatch 拒绝。首发前应跑完整模式,不能用 `--node-only` 代替。`release.mjs artifact` 只复制文件并记录摘要,不要求创建 tag,也不会发布。
|
|
127
|
+
|
|
128
|
+
你的工具链、平台和这次新增文档可能使本地 tarball 摘要不同于之前提供的下载包;**不要把旧下载包 SHA 当成本地构建的必然值**。保留自己这次验证过的 `dist/` 文件与 SHA256SUMS,后面发布它,不重新 pack。Linux 可以用 `(cd dist && sha256sum -c SHA256SUMS)`;macOS 可用 `(cd dist && shasum -a 256 -c SHA256SUMS)`。
|
|
129
|
+
|
|
130
|
+
## 5. 你在本地执行首次 npm 发布
|
|
131
|
+
|
|
132
|
+
首发使用你自己的 npm 账号。先检查 `0.2.0` 是否已经公开存在;仅明确 HTTP 404 才表示当前公开查询未找到,网络/认证错误不能当作不存在。404 也不保证名称可以由你认领。
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
node --input-type=module -e '
|
|
136
|
+
const r = await fetch("https://registry.npmjs.org/ckb-vm-js/0.2.0", { signal: AbortSignal.timeout(20000) });
|
|
137
|
+
if (r.status !== 404) throw Error(r.ok ? "0.2.0 already exists: stop" : `Registry HTTP ${r.status}: stop`);
|
|
138
|
+
console.log("No public 0.2.0 found; account/name permission still needs verification");
|
|
139
|
+
'
|
|
140
|
+
npm login --registry=https://registry.npmjs.org
|
|
141
|
+
npm whoami --registry=https://registry.npmjs.org
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
确认 whoami 是你希望拥有包的账号,包名仍为 `ckb-vm-js`、版本为 `0.2.0`,完成 npm 要求的 2FA 后,**以下命令会真正公开发布**:
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
npm publish ./dist/ckb-vm-js-0.2.0.tgz \
|
|
148
|
+
--access public --ignore-scripts --registry=https://registry.npmjs.org
|
|
149
|
+
npm view ckb-vm-js@0.2.0 version dist.integrity --registry=https://registry.npmjs.org
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
不要向聊天发送 npm token。遇到名称占用、无权限或版本已存在就停止,不要擅自改包名、覆盖或重复发布。若发布调用超时,先检查 registry 和 npm 页面确认是否已接受该版本;不要盲目重发。本地交互式首发不加 CI 专用的 `--provenance`,不能宣称已有 OIDC provenance。
|
|
153
|
+
|
|
154
|
+
## 6. 后续交给 Trusted Publisher
|
|
155
|
+
|
|
156
|
+
发布准备已集成到 main;最终发布前仍由协调者核对前端收尾、目标提交及 CI。本地首发不要求把 0.2.0 的 Release 再发布一遍。GitHub 管理员创建/检查 **`npm-publish`** environment,配置 required reviewers,并允许版本 tag `v*`。
|
|
157
|
+
|
|
158
|
+
在 npm 包 Settings → Trusted Publisher 中选择 GitHub Actions:
|
|
159
|
+
|
|
160
|
+
| 字段 | 值 |
|
|
161
|
+
| --- | --- |
|
|
162
|
+
| Owner | `Hanssen0-Alter-Ego` |
|
|
163
|
+
| Repository | `ckb-vm-js` |
|
|
164
|
+
| Workflow filename | `publish.yml` |
|
|
165
|
+
| Environment | `npm-publish` |
|
|
166
|
+
| Allowed actions | Allow npm publish |
|
|
167
|
+
|
|
168
|
+
不创建长期 npm token。等下一版准备好时配置 trust,并在首次信任验证窗口内完成成功发布;不要把本地 bootstrap 的 0.2.0 再作为自动发布版本。下一次用新版本(例如 0.2.1),版本文件和 lockfile 一起更新,集成后才按 [发布指南](publishing.md)创建 tag/Release、审批 environment、核查 provenance。这些远端设置和实际 OIDC 发布尚须另行验证。
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Browser playground
|
|
2
|
+
|
|
3
|
+
The `web/` application runs the real `createWorkerVerifier` API. No wallet, RPC
|
|
4
|
+
endpoint, private key or transaction broadcaster is involved. The four bundled
|
|
5
|
+
examples are synthetic fixtures with custom consensus, not network presets.
|
|
6
|
+
|
|
7
|
+
## Build and serve
|
|
8
|
+
|
|
9
|
+
Initialize the pinned submodules and build WASM as described in the repository
|
|
10
|
+
build instructions, then:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm ci
|
|
14
|
+
node scripts/build-site.mjs
|
|
15
|
+
node tests/browser/server.js
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Open `http://127.0.0.1:4178/ckb-vm-js/`. The same `site-dist/` directory is uploaded
|
|
19
|
+
to Pages. JavaScript, Worker, WASM, fixtures, CSS and documentation use relative
|
|
20
|
+
URLs so the project subpath works without rewrite rules or isolation headers.
|
|
21
|
+
The builder refuses to proceed without real generated WASM and bindings.
|
|
22
|
+
|
|
23
|
+
## Interaction
|
|
24
|
+
|
|
25
|
+
The default guided mode needs no JSON. Pick a valid transfer, overspend, low
|
|
26
|
+
cycle-budget or deliberately rejecting toy-lock experiment. Enter the new cell's
|
|
27
|
+
capacity in decimal CKB and select a cycle budget, then click **Run verification**.
|
|
28
|
+
Amounts are converted with BigInt, preserving all eight decimal places. Results
|
|
29
|
+
show plain-language explanations, decimal cycles and CKB fees from the actual
|
|
30
|
+
engine response. Raw requests and responses stay in expandable advanced sections.
|
|
31
|
+
|
|
32
|
+
Guided controls generate only the bundled synthetic fixtures. They are not a
|
|
33
|
+
wallet or general transaction builder. Importing, editing JSON or loading a
|
|
34
|
+
developer fixture explicitly disables the guided fields; selecting an experiment
|
|
35
|
+
resets to guided mode. Invalid guided amounts cannot run or export a stale request.
|
|
36
|
+
|
|
37
|
+
In Advanced mode, choose a sample and click **Load sample**, or edit/import JSON. Import accepts a request object or a fixture containing
|
|
38
|
+
`request`; export saves only the request. Neither operation uploads data. Input
|
|
39
|
+
is kept in page memory and is lost on reload. Editing clears stale output.
|
|
40
|
+
|
|
41
|
+
To check only a script group, use the selected-lock sample or supply
|
|
42
|
+
`script_group: { group_type: "lock" | "type", script_hash: "0x…" }` in the request.
|
|
43
|
+
The hash identifies the complete script, not just its code. Omit `script_group`
|
|
44
|
+
for transaction scope. The advanced mode passes the request to the existing API unchanged;
|
|
45
|
+
it does not inject consensus or infer a network.
|
|
46
|
+
|
|
47
|
+
A successful response is conditional on supplied data. `chain_state_verified`
|
|
48
|
+
is false: no canonical chain or live-cell lookup occurs. A selected group's
|
|
49
|
+
success does not establish full transaction validity. Engine rejection displays
|
|
50
|
+
its actual error code/message. Parsing, transport, initialization and runtime
|
|
51
|
+
failures are reported separately.
|
|
52
|
+
|
|
53
|
+
Each run creates a fresh Worker. Cancel and the 30-second timeout terminate it,
|
|
54
|
+
including stalled initialization. Each imported/edited request is limited to
|
|
55
|
+
2 MiB. A Worker does not provide an independent memory quota, so these controls
|
|
56
|
+
are practical UI limits, not a complete sandbox for hostile workloads.
|
|
57
|
+
|
|
58
|
+
## Verification and publishing
|
|
59
|
+
|
|
60
|
+
`npm run test:browser` builds the site from generated WASM and tests it at the
|
|
61
|
+
project subpath in Chromium. Tests cover successful submitted/committed requests,
|
|
62
|
+
script-group scope, script rejection, malformed JSON, repeated runs, local file
|
|
63
|
+
import/export, cancellation and recovery, mobile overflow and WASM resource URLs.
|
|
64
|
+
The existing Worker test also verifies execution with browser networking disabled.
|
|
65
|
+
|
|
66
|
+
The `Browser playground` Actions workflow rebuilds and tests WASM and the page
|
|
67
|
+
before uploading a Pages artifact, then deploys only `main`. Repository Pages
|
|
68
|
+
must use GitHub Actions as its build source. This workflow is independent of npm
|
|
69
|
+
publication and does not publish a package or change repository access.
|
|
70
|
+
|
|
71
|
+
## Transaction workbench
|
|
72
|
+
|
|
73
|
+
The structured editor and advanced JSON share one request. Edit input/output
|
|
74
|
+
capacity and data, reuse or customize lock/type scripts, choose supplied cells as
|
|
75
|
+
code dependencies, edit witnesses, and select transaction or script-group scope.
|
|
76
|
+
JSON-only extension fields are retained when a structured field changes. Invalid
|
|
77
|
+
JSON remains in the editor; malformed entries are diagnosed rather than repaired.
|
|
78
|
+
|
|
79
|
+
Add/copy input creates a **synthetic unconfirmed cell**, not a live-chain input.
|
|
80
|
+
Input removal/reordering does not guess witness associations or remove context
|
|
81
|
+
cells. Adjust witnesses explicitly. Output operations keep corresponding data
|
|
82
|
+
aligned and refuse mismatched arrays. Capacity arithmetic uses integer shannons;
|
|
83
|
+
the displayed difference is not a validated fee. Dependency selection does not
|
|
84
|
+
infer code hashes, load binaries, or expand dep groups. Preflight hints do not
|
|
85
|
+
replace running the verifier. Arbitrary context remains editable through JSON.
|
|
86
|
+
|
|
87
|
+
The workbench is static frontend code under `web/`, copied only by the site build.
|
|
88
|
+
It adds no core API or npm dependencies and is excluded by the package's explicit
|
|
89
|
+
`files` allowlist. Model regression tests run with `npm test`; UI scenarios are
|
|
90
|
+
included in `npm run test:browser` and require the generated WASM artifacts.
|