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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hanssen0-Alter-Ego
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,2 +1,141 @@
1
- # ckb-vm-js bootstrap
2
- Placeholder only. This version contains no runtime.
1
+ # ckb-vm-js
2
+
3
+ Offline CKB transaction verification in WebAssembly, with a JavaScript/TypeScript API.
4
+
5
+ This project uses **CKB's own transaction verifiers and CKB-VM**, pinned as Git submodules. It does not substitute a JavaScript VM. The caller supplies the consensus parameters consumed by the pinned transaction-verification paths. Both the ordinary full-transaction API and a selected-script-group API are available.
6
+
7
+ **Early experimental release. Not audited. A successful result is relative to the supplied snapshot, not proof that the network will accept the transaction.** Do not use it as the sole safeguard for funds.
8
+
9
+ ## What `verify` checks
10
+
11
+ For a non-cellbase transaction, using only caller-supplied transaction context:
12
+
13
+ - Canonical RPC decoding, transaction version/size/shape, output-data lengths, supported script hash types and duplicate dependencies.
14
+ - Input resolution, duplicate inputs and dep-group expansion against caller-supplied cells.
15
+ - Cellbase maturity, `since`, occupied capacity, input/output capacity and DAO-aware fees.
16
+ - Every lock/type script group, TYPE_ID rules, syscall behavior, hardfork-selected VM versions, and a shared cycle budget through upstream CKB.
17
+ - The upstream DAO script-size rule, with submission/block-mode activation semantics.
18
+
19
+ `verifyScriptGroup` executes only the requested lock/type group. A successful group result **does not imply that the whole transaction is valid**. Structural decoding and snapshot completeness checks still apply.
20
+
21
+ ## Trust and scope
22
+
23
+ The verifier never contacts a node or indexer. Developers supply transaction bytes as RPC JSON plus the necessary cells, data, headers, block extensions and creation metadata. It recomputes hashes from supplied data and checks internal consistency. It cannot establish that the supplied context is true.
24
+
25
+ Deliberately outside scope:
26
+
27
+ - Whether a cell is live, already spent or on the canonical chain.
28
+ - Proof of work, header/block authenticity, chain selection and inclusion proofs.
29
+ - Transaction proposal inclusion, block-wide byte/cycle limits, conflicts with other block transactions, and cellbase rewards.
30
+ - Mempool policy or future inclusion guarantees.
31
+
32
+ The foundation API has no network selector, chain-state cache, RPC client or automatic mainnet/testnet configuration. The caller supplies the required consensus parameters as well as the data. Network presets and context-maintenance helpers can be built separately on top.
33
+
34
+ `tip_header` means the **actual current chain tip**. By default, verification uses upstream's newly-submitted transaction environment. To check an exact hypothetical block placement, supply `verification: { phase: 'committed', candidate_header, transaction_index }`; the candidate must directly follow the supplied tip. Same-block ancestor cells are supported when their creation metadata identifies this candidate and an earlier transaction index. Explicit `transaction_info: null` represents an unconfirmed non-cellbase cell, not missing metadata. Standalone cellbase transactions and the separate already-proposed pool phase are not supported. See the [complete request contract](crates/verifier/SCHEMA.md).
35
+
36
+ ## Build
37
+
38
+ ```sh
39
+ git clone --recurse-submodules https://github.com/Hanssen0-Alter-Ego/ckb-vm-js.git
40
+ cd ckb-vm-js
41
+ rustup target add wasm32-unknown-unknown
42
+ cargo install wasm-bindgen-cli --version 0.2.105 --locked
43
+ npm ci
44
+ ./scripts/prepare.sh
45
+ # Install clang from your platform's official package manager if absent.
46
+ ./scripts/build-wasm.sh
47
+ npm test
48
+ npm run typecheck
49
+ npm run test:wasm
50
+ node examples/verify.mjs # runs the included valid fixture offline
51
+ ```
52
+
53
+ Rust 1.95.0 is pinned in `rust-toolchain.toml`. `clang` is needed for upstream secp256k1 C code; `CC_wasm32_unknown_unknown=/path/to/clang` overrides it. The generated module targets **wasm32-unknown-unknown**, not WASI, and does not require SharedArrayBuffer or cross-origin isolation.
54
+
55
+ The repository and npm package/import name are `ckb-vm-js`.
56
+
57
+ Build before installing from a checkout or making an npm tarball. No npm registry publication is claimed. `pkg/` contains the generated JS loader, WASM and declarations and is included in the package tarball.
58
+
59
+ ## Publishing
60
+
61
+ To clone, build, test and publish the first package locally, follow the [local first-publish guide](docs/local-first-publish.md), including platform-specific native/WASM tools and the exact-tarball consumer test.
62
+
63
+ [发布工作流与 Trusted Publisher 配置指南](docs/publishing.md) explains the one-time npm bootstrap, exact trust fields, protected environment and release process. Manual runs only build/test/package; publishing a GitHub Release is the only live npm trigger. Adding this workflow does not configure accounts or publish a package.
64
+
65
+ ## Use
66
+
67
+ ```js
68
+ import { createVerifier } from './js/index.js';
69
+
70
+ const verifier = await createVerifier(); // loads the local pkg WASM asset once
71
+ const result = await verifier.verify(request);
72
+ if (!result.ok) console.error(result.error.code, result.error.message);
73
+ else console.log(result.cycles, result.fee, result.groups);
74
+
75
+ const oneGroup = await verifier.verifyScriptGroup(request, {
76
+ group_type: 'lock',
77
+ script_hash: '0x...', // complete 32-byte hash, available in result.groups
78
+ });
79
+ ```
80
+
81
+ For fully offline initialization in Node, pass `wasm: await readFile(...)`. For browsers, use `createWorkerVerifier` to keep CPU-bound verification off the UI thread. The returned Promise does not by itself make direct verification non-blocking. See [JavaScript and Worker usage](docs/javascript.md).
82
+
83
+ The v0.2 foundation interface has 62 synthetic transaction/context fixtures, all passing locally in native and real WASM execution, including comparison with an unmodified-upstream native build. JavaScript/TypeScript and offline installed-tarball checks also pass. Browser execution is checked by the [CI workflow](https://github.com/Hanssen0-Alter-Ego/ckb-vm-js/actions); inspect the check for the exact commit rather than assuming a previous browser pass covers this revision. See the [verification record and limits](docs/verification.md).
84
+
85
+ ## Request
86
+
87
+ All integers are lossless CKB RPC hex strings. The TypeScript declarations describe the full API. Minimal shape:
88
+
89
+ ```js
90
+ const request = {
91
+ transaction: { /* CKB RPC Transaction, including witnesses */ },
92
+ max_cycles: '0x3b9aca00',
93
+ context: {
94
+ tip_header: { /* current chain tip RPC Header */ },
95
+ // verification omitted: defaults to { phase: 'submitted' }
96
+ consensus: {
97
+ tx_version: '0x...', max_block_bytes: '0x...', max_block_cycles: '0x...',
98
+ cellbase_maturity: '0x...', median_time_block_count: '0x...',
99
+ tx_proposal_window: { closest: '0x...', farthest: '0x...' },
100
+ dao_type_hash: '0x...',
101
+ hardforks: {
102
+ rfc0028_epoch: '0x...', rfc0032_epoch: '0x...',
103
+ rfc0049_epoch: '0x...', rfc0044_epoch: '0x...',
104
+ },
105
+ starting_block_limiting_dao_withdrawing_lock: '0x...',
106
+ },
107
+ headers: [ /* creation/header-dep/median-time headers */ ],
108
+ cells: [{
109
+ out_point: { tx_hash: '0x...', index: '0x0' },
110
+ output: { capacity: '0x...', lock: { /* Script */ }, type: null },
111
+ data: '0x...',
112
+ transaction_info: {
113
+ block_hash: '0x...', block_number: '0x...',
114
+ block_epoch: '0x...', index: '0x1',
115
+ },
116
+ }],
117
+ extensions: [{ block_hash: '0x...', data: null }],
118
+ },
119
+ };
120
+ ```
121
+
122
+ The snippet is a shape illustration, not a usable network configuration. Cells must include every input, direct dep, dep-group cell and expanded member. Confirmed origins require their creation headers. `transaction_info.index` is the transaction's index in its creation block, not the cell's output index; zero means cellbase. Its block number and packed epoch must match the supplied creation header. For resolved inputs/dependencies with known origins and declared header deps, each corresponding hash must have an explicit extension entry: bytes when present, `null` when absent. Missing context is an error, never treated as successful verification.
123
+
124
+ Timestamp-based `since` may require the caller-configured median-time ancestor window. Supply the linked header chain, stopping at genesis. Header JSON is the RPC Header body; the block hash is recomputed, not trusted from a separate asserted hash.
125
+
126
+ ### Migration from v0.1
127
+
128
+ The old `context.network` is removed. Supply `context.consensus` explicitly; do not assume a preset is selected implicitly. The old misleading `tip_header` was a candidate header. To retain exact-block semantics, move it to `context.verification.candidate_header`, set `phase: 'committed'`, provide the target `transaction_index`, and put its actual parent in `context.tip_header`. Do not repeat that parent in `headers`. Omitting `verification` intentionally selects **submitted**, not the old committed behavior. JS method names are unchanged.
129
+
130
+ Success returns `{ ok: true, scope: 'transaction' | 'script_group', cycles, fee?, groups, chain_state_verified: false }`. Failure returns `{ ok: false, error: { code, message } }`. Group order is not part of the API. Error messages include upstream details and may change with upstream versions.
131
+
132
+ ## Upstream and reproducibility
133
+
134
+ - [CKB](https://github.com/nervosnetwork/ckb/tree/6abb474c1678e67dae0337abeb8bfd77cfb576e3), commit `6abb474c1678e67dae0337abeb8bfd77cfb576e3` (verification/script crates 1.2.1).
135
+ - [CKB-VM](https://github.com/nervosnetwork/ckb-vm/tree/7199b96d9f24b51c4c5eba358d64cd4d9bcf8150), `v0.24.15`, commit `7199b96d9f24b51c4c5eba358d64cd4d9bcf8150`.
136
+ - The workspace patches `ckb-vm` and `ckb-vm-definitions` to the VM submodule. `Cargo.lock` pins the remaining dependency graph.
137
+ - `scripts/prepare.sh` applies the checked-in, narrowly scoped wasm32 compatibility patches to the exact upstream pins. These retain 64-bit syscall/ELF semantics on a 32-bit host. See `patches/README.md`; do not omit this step. Native builds may select upstream assembly execution; the browser uses the portable interpreter.
138
+
139
+ See [verification notes](docs/verification.md) for actual checks run and remaining test gaps. This is an independent integration, not an official Nervos release. Upstream submodules retain their own licenses.
140
+
141
+ Dependency attribution and unresolved upstream notice gaps are recorded in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Licensing review, like consensus coverage, is not claimed complete for this experimental package.