@smartledger/bsv 9.6.0 → 9.8.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 +204 -0
- package/README.md +19 -19
- package/bsv-gdaf.min.js +29 -29
- package/bsv-ltp.min.js +17 -17
- package/bsv-smartcontract.min.js +1 -1
- package/bsv.bundle.js +30 -30
- package/bsv.d.ts +301 -54
- package/bsv.min.js +28 -28
- package/docs/AUDIT_SCOPE.md +39 -13
- package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
- package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
- package/docs/audit-rfq/cure53.txt +24 -10
- package/docs/audit-rfq/ncc-group.txt +24 -10
- package/docs/audit-rfq/trail-of-bits.txt +24 -10
- package/docs/getting-started/INSTALLATION.md +23 -23
- package/docs/getting-started/QUICK_START.md +7 -7
- package/docs/migration/FROM_BSV_1_5_6.md +5 -5
- package/docs/preimage.md +151 -87
- package/lib/script/interpreter.js +104 -3
- package/package.json +7 -3
- package/version.js +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,210 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [9.8.0] - 2026-09-08
|
|
11
|
+
|
|
12
|
+
**No runtime change.** `git diff v9.7.0..HEAD -- lib/` is empty. Four bundles do differ,
|
|
13
|
+
which looks like a contradiction and is not: reverting `version.js` alone and rebuilding
|
|
14
|
+
reproduces all four **byte-identical to the v9.7.0 release**, so the embedded version
|
|
15
|
+
string is the only changed input and the shifted minifier identifiers are a
|
|
16
|
+
deterministic consequence of it.
|
|
17
|
+
|
|
18
|
+
This release exists because the two things it corrects both ship in the tarball and
|
|
19
|
+
reach nobody until they are published. `bsv.d.ts` is the package's `types` entry, and
|
|
20
|
+
`docs/` is in `files[]`. On 9.7.0 this is a compile error in three places:
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
const i = new bsv.Script.Interpreter() // TS7009: no construct signature
|
|
24
|
+
const w = i.maxScriptNumLength()
|
|
25
|
+
const f = I.mainnetFlags() | I.SCRIPT_UTXO_AFTER_GENESIS // TS2339: does not exist
|
|
26
|
+
const n = new bsv.crypto.BN(0) // TS2554: expected 0 arguments
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Fixed — `docs/preimage.md` was wrong in ways that cost money
|
|
30
|
+
|
|
31
|
+
The page ships in the npm tarball and is linked from the README, and people build
|
|
32
|
+
covenants from it. It gave the preimage as **~108 bytes** when it is 182 — 156 fixed
|
|
33
|
+
plus a length-prefixed `scriptCode` — and its own arithmetic said 181 because it
|
|
34
|
+
counted a 25-byte script without the varint that precedes it.
|
|
35
|
+
|
|
36
|
+
Every byte offset from the txid onward was wrong. `outpoint.txid` was labelled 32
|
|
37
|
+
bytes over a 28-byte range, and everything after it shifted by three or four:
|
|
38
|
+
`hashOutputs` was given as starting at 139 when it starts at 142.
|
|
39
|
+
|
|
40
|
+
**Four of its seven Script fragments did not work**, run against a real preimage:
|
|
41
|
+
|
|
42
|
+
| fragment | result |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| `hashPrevouts`: `4 OP_SPLIT OP_DROP 32 OP_SPLIT OP_DROP` | `SCRIPT_ERR_INVALID_SPLIT_RANGE` — `OP_DROP` keeps the wrong half |
|
|
45
|
+
| `hashOutputs`: `<len-44>` | reads `nSequence` and the first 28 bytes of the hash |
|
|
46
|
+
| `amount`: `40 OP_SPLIT` | a literal offset landing inside `hashPrevouts` |
|
|
47
|
+
| `nSequence`: `12 OP_SPLIT` | likewise |
|
|
48
|
+
|
|
49
|
+
It showed `hashSequence` as `00…00` for an ordinary `0x41` signature. It is only zero
|
|
50
|
+
under `ANYONECANPAY`, `NONE` or `SINGLE`, and the page now carries the measured table
|
|
51
|
+
for all five combinations — which matters, because a covenant reading `hashOutputs`
|
|
52
|
+
without pinning the sighash type is checking 32 zero bytes.
|
|
53
|
+
|
|
54
|
+
And it recommended `OP_BIN2NUM` on `amount`, `nSequence` and `nLockTime`, which are
|
|
55
|
+
**unsigned**. That is the defect fixed in 9.4.0, recommended as practice:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
nLockTime ffffffff -> -2147483647 should be 4294967295 (year 2106)
|
|
59
|
+
01000080 -> -1 should be 2147483649
|
|
60
|
+
00000080 -> 0 should be 2147483648 (19 Jan 2038)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`nSequence` is `0xffffffff` more often than not, so that one is wrong today rather
|
|
64
|
+
than in 2038.
|
|
65
|
+
|
|
66
|
+
Two things the page said that were not merely inaccurate but backwards:
|
|
67
|
+
|
|
68
|
+
- **"Re-hash the preimage (`OP_HASH256`) to verify it matches what was signed."** It
|
|
69
|
+
does not. `OP_HASH256` yields a hash and nothing else; a spender can supply any 182
|
|
70
|
+
well-formed bytes, satisfy every field check, and spend on a different transaction.
|
|
71
|
+
The binding comes from `OP_CHECKSIG` over a signature constructed from the preimage
|
|
72
|
+
hash — which is what `OP_PUSH_TX` does and what the page now describes.
|
|
73
|
+
- **The 32-byte hashes were called "big-endian"**, inviting someone to reverse them.
|
|
74
|
+
They are the bytes `HASH256()` returns. The only reversed field is the txid inside
|
|
75
|
+
the outpoint.
|
|
76
|
+
|
|
77
|
+
Also: `scriptCode` is not "usually `scriptPubKey`" — it is variable, `OP_CODESEPARATOR`
|
|
78
|
+
moves it, and covenant scripts make it hundreds of bytes, which is why every extraction
|
|
79
|
+
this library ships reads from the END of the preimage rather than by absolute offset.
|
|
80
|
+
The page now says so and gives the from-end offsets: `amount` 52, `nSequence` 44,
|
|
81
|
+
`hashOutputs` 40, `nLockTime` 8, `sighashType` 4.
|
|
82
|
+
|
|
83
|
+
It opens with the Chronicle caveat, since BIP-143 is no longer the only digest
|
|
84
|
+
algorithm on this chain.
|
|
85
|
+
|
|
86
|
+
**`test/covenant/preimage_doc.js` asserts the page** — 24 cases covering every offset,
|
|
87
|
+
every fragment, the zero-hash table, the `OP_BIN2NUM` figures and the authentication
|
|
88
|
+
claim, all against a preimage the library actually produces. Reintroducing the old
|
|
89
|
+
`hashOutputs` offset of 44 fails it.
|
|
90
|
+
|
|
91
|
+
### Fixed — the consensus API was uncallable from TypeScript
|
|
92
|
+
|
|
93
|
+
Everything added across 9.4.0 to 9.7.0 shipped with no declaration. `bsv.d.ts` said
|
|
94
|
+
one thing about the interpreter — a `verify()` returning boolean — so
|
|
95
|
+
`interp.maxScriptNumLength()` was a compile error, the instance had no `errstr` and
|
|
96
|
+
no `stack`, and not one of the era flags existed as a name.
|
|
97
|
+
|
|
98
|
+
`crypto.BN` was worse: `class BN { }`, an empty declaration. `new BN(0)` did not
|
|
99
|
+
compile and every satoshi amount in the public API widened to `{}`, which is what
|
|
100
|
+
made the interpreter unusable rather than merely undocumented.
|
|
101
|
+
|
|
102
|
+
Both are now declared in full: the interpreter's twenty instance members and
|
|
103
|
+
fifty-four statics, and BN's constructor, comparisons, arithmetic and the Bitcoin
|
|
104
|
+
codecs (`fromScriptNumBuffer`, `toScriptNumBuffer`, `fromSM`, `toSM`). bn.js's own
|
|
105
|
+
internals — the `red`/`mont` modular-arithmetic family, the in-place `i*` mutators —
|
|
106
|
+
are deliberately left out: they are inherited, not this library's contract.
|
|
107
|
+
|
|
108
|
+
The declarations are exercised, not just written. `types-test/positive.ts` now
|
|
109
|
+
constructs an interpreter both ways, reads every era method and moves the stack
|
|
110
|
+
ceiling; `negative.ts` gained five cases that must fail, including calling an
|
|
111
|
+
instance method on the constructor and assigning `checkStackLimits()` to a boolean.
|
|
112
|
+
A declaration that quietly degrades to `any` makes those errors vanish.
|
|
113
|
+
|
|
114
|
+
### Added — `npm run check:dts`, a declaration-coverage ratchet
|
|
115
|
+
|
|
116
|
+
`check:types` proves the declarations that exist are correct. Nothing measured the
|
|
117
|
+
surface that was never declared at all, which is how four consecutive releases
|
|
118
|
+
shipped an API no TypeScript consumer could call.
|
|
119
|
+
|
|
120
|
+
`scripts/check-dts-coverage.js` compares `test/fixtures/api-surface.json` against
|
|
121
|
+
`bsv.d.ts` and fails when a name is added to the runtime with no declaration, when a
|
|
122
|
+
name is declared but still sits in the baseline (the ratchet only turns one way), or
|
|
123
|
+
when a namespace listed as COMPLETE develops a gap. `bsv.Script.Interpreter` is the
|
|
124
|
+
first entry in that list, at zero.
|
|
125
|
+
|
|
126
|
+
Coverage is **934 of 1,946 names, 48.0%**. The remaining 1,012 are recorded in
|
|
127
|
+
`test/fixtures/dts-coverage-baseline.json` so the number is visible rather than
|
|
128
|
+
implied — `bsv.Opcode` and its 110 constants are the largest block left.
|
|
129
|
+
|
|
130
|
+
The gate's first act was to reject a claim of mine: I listed `crypto.BN` as complete
|
|
131
|
+
and it named the 69 bn.js internals I had not declared.
|
|
132
|
+
|
|
133
|
+
## [9.7.0] - 2026-09-05
|
|
134
|
+
|
|
135
|
+
### Fixed — the stack limits diverged from the node in both directions
|
|
136
|
+
|
|
137
|
+
The last of the pre-Genesis caps still applied as a literal, and the only one
|
|
138
|
+
left that `useGenesisLimits()` could not reach:
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
// after the whole script had run:
|
|
142
|
+
if (this.stack.length + this.altstack.length > 1000) {
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Two divergences in five lines.
|
|
146
|
+
|
|
147
|
+
**It was checked once, at the end of the script.** The node checks after every
|
|
148
|
+
opcode. A script that piles up 1,001 elements and drops back to one before it
|
|
149
|
+
finishes passed here and is rejected by the network — a false accept, in the
|
|
150
|
+
direction that costs money:
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
pre-Genesis, 1001 pushes then 500 OP_2DROPs
|
|
154
|
+
before: accepted
|
|
155
|
+
node: SCRIPT_ERR_STACK_SIZE
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
No vector in the corpus catches it: every `STACK_SIZE` vector *ends* over the
|
|
159
|
+
cap, which is exactly the case an end-of-script check does see. The regression
|
|
160
|
+
test uses `OP_2DROP` deliberately — it clears two elements per opcode and so
|
|
161
|
+
lands inside the pre-Genesis 500-opcode budget, where 1,001 `OP_DROP`s would
|
|
162
|
+
trip `SCRIPT_ERR_OP_COUNT` and pass the assertion for the wrong reason.
|
|
163
|
+
|
|
164
|
+
**And it was applied after Genesis, which removed it.** Genesis replaced the
|
|
165
|
+
element COUNT with a bound on the memory the two stacks occupy, so that a script
|
|
166
|
+
is limited by what it uses rather than by how it is divided up. Carrying 1000
|
|
167
|
+
unconditionally rejected post-Genesis scripts the network accepts:
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
post-Genesis, 1001 elements before: SCRIPT_ERR_STACK_SIZE after: accepted
|
|
171
|
+
post-Genesis, 5000 elements before: SCRIPT_ERR_STACK_SIZE after: accepted
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The shape that finds it in practice is a 256-step elliptic-curve ladder, which
|
|
175
|
+
needs a witness value per step: over seven hundred elements for one scalar
|
|
176
|
+
multiplication, and two of those in an ECDSA verification.
|
|
177
|
+
|
|
178
|
+
Same shape as 9.4.0, 9.5.0 and 9.6.0 — a limit that was correct when it was
|
|
179
|
+
written, left static while the rest became era-derived. Now:
|
|
180
|
+
|
|
181
|
+
```js
|
|
182
|
+
Interpreter.prototype.maxStackSize() // 1000 before Genesis, UNLIMITED after
|
|
183
|
+
Interpreter.prototype.maxStackMemoryUsage() // UNLIMITED before, 100 MB policy after
|
|
184
|
+
Interpreter.prototype.stackMemoryUsage() // bytes + per-element container overhead
|
|
185
|
+
Interpreter.prototype.checkStackLimits() // called after every opcode
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
`MAX_STACK_MEMORY_USAGE_AFTER_GENESIS` is **`UNLIMITED`**, because post-Genesis
|
|
189
|
+
consensus is unbounded. The node's 100 MB figure is `-maxstackmemoryusagepolicy`,
|
|
190
|
+
a RELAY setting, and defaulting to it would have refused scripts the network
|
|
191
|
+
accepts — the same mistake as carrying the 1000-element cap past Genesis, in the
|
|
192
|
+
same function. It is kept as `STACK_MEMORY_USAGE_POLICY` for anyone who wants it:
|
|
193
|
+
|
|
194
|
+
```js
|
|
195
|
+
Interpreter.MAX_STACK_MEMORY_USAGE_AFTER_GENESIS =
|
|
196
|
+
Interpreter.STACK_MEMORY_USAGE_POLICY
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Unbounded means a hostile script can allocate until the process runs out of
|
|
200
|
+
memory — the same trade `useGenesisLimits(max)` already documents for element
|
|
201
|
+
size. A validator taking scripts from strangers should set a ceiling matched to
|
|
202
|
+
its workload.
|
|
203
|
+
|
|
204
|
+
`STACK_ELEMENT_OVERHEAD` is 32 bytes, charged per element on top of its contents
|
|
205
|
+
because the container is not free either. It is only consulted once a caller has
|
|
206
|
+
set a ceiling, and 32 is deliberately conservative: a bare `std::vector<uint8_t>`
|
|
207
|
+
is 24 bytes on the common 64-bit ABIs.
|
|
208
|
+
|
|
209
|
+
Keeping the default unbounded also keeps the new per-opcode check O(1): with no
|
|
210
|
+
ceiling to test against, the O(n) memory scan is skipped. A post-Genesis script
|
|
211
|
+
holding 900 elements across 40,000 opcodes measures 42.6 ms, against 42.8 ms
|
|
212
|
+
before this change.
|
|
213
|
+
|
|
10
214
|
## [9.6.0] - 2026-09-02
|
|
11
215
|
|
|
12
216
|
### Fixed — a post-Genesis `OP_CHECKMULTISIG` was refused by a cap the era removed
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Bitcoin SV library with an interpreter-verified script engine.
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/@smartledger/bsv)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
[](STABILITY.md)
|
|
8
8
|
|
|
@@ -155,44 +155,44 @@ const bsv = require('@smartledger/bsv') // 128 modules
|
|
|
155
155
|
### **Core Modules**
|
|
156
156
|
| Module | Size | Use Case | CDN |
|
|
157
157
|
|--------|------|----------|-----|
|
|
158
|
-
| **bsv.min.js** |
|
|
159
|
-
| **bsv.bundle.js** |
|
|
158
|
+
| **bsv.min.js** | 1046KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.8.0/bsv.min.js` |
|
|
159
|
+
| **bsv.bundle.js** | 1046KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.8.0/bsv.bundle.js` |
|
|
160
160
|
|
|
161
161
|
### **W3C Verifiable Credentials**
|
|
162
162
|
| Module | Size | Use Case | CDN |
|
|
163
163
|
|--------|------|----------|-----|
|
|
164
|
-
| **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@9.
|
|
165
|
-
| **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@9.
|
|
166
|
-
| **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@9.
|
|
167
|
-
| **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@9.
|
|
164
|
+
| **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@9.8.0/bsv-didweb.min.js` |
|
|
165
|
+
| **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@9.8.0/bsv-vcjwt.min.js` |
|
|
166
|
+
| **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@9.8.0/bsv-statuslist.min.js` |
|
|
167
|
+
| **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@9.8.0/bsv-anchor.min.js` |
|
|
168
168
|
|
|
169
169
|
### **Smart Contract & Development**
|
|
170
170
|
| Module | Size | Use Case | CDN |
|
|
171
171
|
|--------|------|----------|-----|
|
|
172
|
-
| **bsv-smartcontract.min.js** | 141KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.
|
|
173
|
-
| **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.
|
|
174
|
-
| **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.
|
|
175
|
-
| **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@9.
|
|
172
|
+
| **bsv-smartcontract.min.js** | 141KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.8.0/bsv-smartcontract.min.js` |
|
|
173
|
+
| **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.8.0/bsv-covenant.min.js` |
|
|
174
|
+
| **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.8.0/bsv-script-helper.min.js` |
|
|
175
|
+
| **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@9.8.0/bsv-security.min.js` |
|
|
176
176
|
|
|
177
177
|
### **Legal & Compliance**
|
|
178
178
|
| Module | Size | Use Case | CDN |
|
|
179
179
|
|--------|------|----------|-----|
|
|
180
|
-
| **bsv-ltp.min.js** |
|
|
181
|
-
| **bsv-gdaf.min.js** |
|
|
180
|
+
| **bsv-ltp.min.js** | 540KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@9.8.0/bsv-ltp.min.js` |
|
|
181
|
+
| **bsv-gdaf.min.js** | 1046KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@9.8.0/bsv-gdaf.min.js` |
|
|
182
182
|
|
|
183
183
|
### **Advanced Cryptography**
|
|
184
184
|
| Module | Size | Use Case | CDN |
|
|
185
185
|
|--------|------|----------|-----|
|
|
186
|
-
| **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@9.
|
|
186
|
+
| **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@9.8.0/bsv-shamir.min.js` |
|
|
187
187
|
|
|
188
188
|
### **Utilities**
|
|
189
189
|
| Module | Size | Use Case | CDN |
|
|
190
190
|
|--------|------|----------|-----|
|
|
191
|
-
| **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@9.
|
|
192
|
-
| **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@9.
|
|
193
|
-
| **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@9.
|
|
191
|
+
| **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@9.8.0/bsv-ecies.min.js` |
|
|
192
|
+
| **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@9.8.0/bsv-message.min.js` |
|
|
193
|
+
| **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@9.8.0/bsv-mnemonic.min.js` |
|
|
194
194
|
```html
|
|
195
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
195
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.8.0/bsv.min.js"></script>
|
|
196
196
|
<script>
|
|
197
197
|
const key = bsv.PrivateKey.fromRandom()
|
|
198
198
|
</script>
|
|
@@ -240,4 +240,4 @@ MIT
|
|
|
240
240
|
|
|
241
241
|
---
|
|
242
242
|
|
|
243
|
-
**SmartLedger-BSV v9.
|
|
243
|
+
**SmartLedger-BSV v9.8.0**
|