b017 0.1.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/CHANGELOG.md CHANGED
@@ -1,312 +1,568 @@
1
- # Changelog
2
-
3
- All notable changes to **b017** are documented here. The format is based on
4
- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims to follow
5
- [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
-
7
- ## [Unreleased]
8
-
9
- ## [0.1.0] - 2026-10-11
10
-
11
- ### Changed
12
- - **Coverage is 100% on every metric and the thresholds enforce it** (`vitest.config.ts`: statements, functions,
13
- lines and branches 100; was 99 / 100 / 99 / 98), so a new uncovered branch fails the coverage run. Three
14
- reachable branches gained tests (`coverageEdges`: `p2pkhUnlock` signing from an attached source without a txid,
15
- and refusing a txid with no source; a merge paid to a public-key recipient keeps the builder's signer). 14
16
- defensive guards were marked unreachable with their reason (21 `v8 ignore` markers in all; none covers a covenant
17
- path or a scanner verdict).
18
- - **`verifyTx` is documented as throw-on-failure, and the dead checks behind it are gone.** Every failure already
19
- threw (a failing script: `Spend.validate()` throws rather than returning false), so `valid` was always `true` when
20
- it returned. Its type now says so (`valid: true`; the `{ valid, scriptExecutions }` shape is kept, so callers are
21
- unaffected), and the `if (!valid)` checks in `verifyTx` and the `SimpleMultiBOLT` builder are removed. A builder
22
- failure now reads `<TX TYPE> not valid: <the script error>` (e.g. `MERGE COMMIT TX not valid: ... OP_EQUALVERIFY ...`);
23
- the separate `Mint tx not valid` / `... tx not valid [bsv]` messages, which could never fire, are gone.
24
- `npm run coverage:check` now compares the README's percentages and test counts, not the `(covered/total)`
25
- fractions: V8 counts a few closure branches on some runs only, so the branch total moves by one or two between
26
- identical runs while coverage stays 100%.
27
-
28
- ### Added
29
- - **The genesis family: `FixedBOLT`, `OpenBOLT` and `SerialBOLT`.** Three token types whose lock leads with the
30
- token's own asset outpoint (null on the mint, the mint outpoint from the first spend on) and the issuer's
31
- `mintData` (0..255 bytes on the mint only, `OP_0` on every later output), so a token names its asset in O(1).
32
- - `FixedBOLT` (fungible): one genesis per asset, a fixed supply. Only tokens of one genesis merge; a cross-genesis
33
- or cross-issuer merge is refused by the covenant at the merge commit, and the class refuses it before building.
34
- - `OpenBOLT` (fungible): one issuer, many mints. Tokens of different mints merge, and the merge commit re-roots the
35
- stored outpoint (`lastMergeOrGenesisOutpoint`) to vin0's token outpoint; a cross-issuer merge is refused.
36
- - `SerialBOLT` (NFT): each token carries its own mint outpoint as a serial; zero-funding like `MinSimpleBOLT` (a
37
- commit or settle may carry no funding input, change is optional).
38
- - Classes `FixedBOLT`, `OpenBOLT` (every `SimpleMultiBOLT` operation: mint with `mintData`, transfer, split, merge,
39
- melt); templates `FixedMultiTemplate`, `OpenMultiTemplate`, `SerialBoltTemplate`; `genesisFieldFor`,
40
- `mintDataFor`, `outpointOf`, `MINT_DATA_MAX_BYTES`. The fungible engine takes a `MultiLayout`
41
- (`SIMPLE_MULTI_LAYOUT`, `FIXED_BOLT_LAYOUT`, `OPEN_BOLT_LAYOUT`); `SimpleMultiBOLT` is unchanged.
42
- - Scanner: the three types are registered with two recognition specs each (`mint`: null outpoint + any mintData;
43
- `postMint`: set outpoint + empty mintData), so a non-empty mintData after the mint is not a token.
44
- `recognizeToken` returns the type and its phase (`recognizeType` is unchanged). `verifyEvents` pins the
45
- **asset**, not only the issuer: every token output's outpoint must follow from its parent token (copied, the
46
- mint outpoint at the first spend, or `OpenBOLT`'s re-root), and a `FixedBOLT` merge must not mix genesis
47
- outpoints.
48
- - Fingerprints: `FixedBOLT` `b07ea12b490c759d172016f71d0026c4894ff7d4eadfae75bd845ce72aa5fd81`, `OpenBOLT`
49
- `47a41a00e199904ba84e2e0e4890d3d041782fa3ca283d26014218e4286b72b6`, `SerialBOLT`
50
- `aee7eee8b1254aa765d3f896610d052a2b2da997665e3d9f3d37293ef86d6921`.
51
- - Tests: every ancestor piece and leading push checked byte for byte against chains built by the reference
52
- simulator (`genesisLayouts`, 27), Spend-engine lifecycles, mintData and merge rules (`GenesisMultiBOLT`, 10), the whole
53
- zero-funding suite on `SerialBOLT` plus mintData and melt (`serialBoltZF`, 48), templates (9), scanner (21).
54
-
55
- ### Changed
56
- - **BREAKING for existing tokens: `SimpleMultiBOLT` drops dead covenant code.** The `ancestorHas2TokenOutputs`
57
- branch is removed: it rebuilt a commit carrying a second token, and no such commit can exist (a commit with a
58
- second token output is refused at the commit, by the simulator and by both a Bitcoin SV and a teranode regtest).
59
- With it go its 22 `Vout2*` ancestor args, plus the 6 issuer-key ancestor args nothing has read since the
60
- issuer-counterfeit fix spliced the token's own `issuerPubKey`. Unlock args 198 -> 170 (75 ancestor pieces per
61
- ancestor, was 89; `ARGS2CTX_SMB` 192 -> 164, `SKIP_SMB` 178 -> 150); the locking script is 403 bytes smaller
62
- (static suffix 5103 -> 4700) in every token output, and every settle's unlocking script is smaller too. Every
63
- covenant decision is unchanged: each executed pick reads the same stack item as before, on every lifecycle
64
- fixture. The static bytecode changed, so the fingerprint changed:
65
- `4a7613d176b46f03f1b06df86d7b96a667c31a277e2b4dbc5d5832d1c225fe34` (was
66
- `368c45fdf92164e4e0869c9062be84621ea8ef040e8591399bf6ff3b8c819b11`). Tokens minted with the previous bytecode
67
- keep it (the covenant travels in the token script) and are no longer recognised by `recognizeType`; reissue them.
68
-
69
- ### Added
70
- - **The anchor, and `verifyAndBroadcast`.** The anchor is the token tx a batch stands on: the settle before its
71
- first commit (settle N-1), or the mint when the batch starts at genesis. What travels p2p is `[mint, c1, s1]` or
72
- `[sN-1, cN, sN]`. `verifyEvents` now validates the anchor first, like an event tx (golden fingerprint, issuer,
73
- arrangement, sources, script execution), pulls it into the batch when it was only attached as a source or inside
74
- a BEEF, and names it in `ScanResult.anchors`. An anchor settle is the one settle allowed without its commit in the
75
- batch. `verifyAndBroadcast(txs, broadcastAnchor, opts)` runs `verifyEvents` and then hands every anchor to the
76
- caller's broadcaster; the batch is accepted only if the network accepted or had already seen each one
77
- (`AnchorRef`, `AnchorStatus`, `AnchorBroadcastResult`, `AnchorBroadcaster`). This closes a forged history hidden in
78
- the sources: a stranger-signed `commit1` behind `settle1 -> commit2 -> settle2` used to pass as
79
- `verifyEvents([commit2, settle2])`; `settle1` now fails execution as the anchor. A lone melt now verifies in `verifyEvents` when the settled token
80
- it spends is attached (the type is read off that token, which becomes the anchor), and an attached source that is
81
- not the tx its outpoint names is refused. Offline execution reaches the anchor's own inputs only: a forgery two
82
- events back passes `verifyEvents` and is caught by the anchor broadcast alone (pinned in the tests).
83
- Tests: `anchor` (52), `anchorShapes` (40).
84
- - **An unfunded anchor is refused without an SPV proof to a known block header.** An anchor must be a tx the
85
- network has seen and will therefore mine; an anchor with no funding input pays no fee, so being seen proves
86
- nothing. It is accepted only when it carries a merkle path whose root the caller confirms as a block header:
87
- `ScanOpts.isKnownBlockRoot(merkleRoot, height)`, or a `chainTracker` (`HeaderSource`) given to
88
- `verifyAndBroadcast`. No proof, no headers, an unknown root, a wrong height, a path for another tx, or a
89
- failing lookup all refuse the batch, and nothing is broadcast. The events standing on an anchor may still be
90
- unfunded. Tests: `anchorUnfunded` (42).
91
- - **A header-proven anchor is not re-executed and needs no sources.** An anchor (funded or not) whose merkle path
92
- is confirmed against a known block header was validated by consensus, so its inputs are skipped and their source
93
- txs need not be supplied. A mined anchor can therefore be delivered as BEEF, which stops at proven txs. The
94
- header lookup is the trust root; a merkle path without a known header changes nothing. Event txs are always
95
- executed. With a `chainTracker`, `verifyAndBroadcast` now collects the roots in a first pass, asks the tracker,
96
- and runs the real scan against the answers.
97
- Tests: `anchorProven`, including an unfunded `SimpleMultiBOLT` anchor.
98
- - **Value conservation is checked.** An anchor whose outputs exceed its inputs is refused. An event tx that does
99
- so is reported in `ScanResult.offChainOnly` / `EventResult.offChainOnly` (`OffChainOnlyTx`) and accepted: a
100
- never-broadcast commit / settle is valid off chain. `ScanOpts.requireBroadcastable` refuses such a batch. A
101
- header-proven anchor is not re-checked. Tests: `valueConservation` (23).
102
- - **The scanner no longer throws on a broken `Transaction` object.** An input with no source reference or no
103
- unlocking script, or an output with no locking script, makes the SDK throw when the tx is serialised; that used to
104
- escape `verifyEvents`, `verifyEvent` and `verifyAndBroadcast`. They now return `unverifiable input: ...`.
105
- Tests: `scannerEdges`, `builderEdges` (46).
106
- - **A batch element that is not a transaction is refused, not thrown.** `null`, `undefined`, a number or a plain
107
- object in the array used to surface as `unparseable batch: TypeError ...`; it now returns
108
- `not a transaction: expected a Transaction, raw tx hex, or BEEF hex / bytes`. Tests: `scannerInputs` (12).
109
- - **Coverage tooling (maintainers).** `npm run coverage:gaps` lists every uncovered branch as `file:line`;
110
- `npm run coverage:readme` generates the README test counts and coverage table (`coverage:check` fails if they
111
- are stale); `vitest.config.ts` now has coverage thresholds. `verifyEvents.ts` was refactored with no change in
112
- verdicts (one helper each for the source lookup, the spent txid and error text).
113
- - **`melt(privateKey)` on `MinSimpleTemplate` and `AuthBoltTemplate`** (`SingleUnlockParams.melt`): the owner burns
114
- the token with a null CTX and no token output, funded or unfunded. Script-level only (the `@bsv/sdk` Spend
115
- engine); the b017 melt builder has not been run against a node. Tests: `minSimpleMelt` (40).
116
- - **`verifyEvent` takes its verdict from the same scan as `verifyEvents`.** It used to return
117
- `{ ok: true, kind: "mint" }` for a lone commit, a lone settle or two unrelated settles, ignored
118
- `trustedIssuerPubKey`, had no anchor step, and threw on an input pointing past its source's outputs. It now
119
- refuses all of those, requires exactly one action (its anchor and the mint it authenticates may ride along),
120
- and returns `anchors`. Tests: `verifyEventSingle` (34).
121
- - **`AuthBOLT`: a new identity-NFT type** (`AuthBoltTemplate`, `AUTH_DATA_MAX_BYTES`, `TokenType` `"AuthBOLT"`).
122
- `MinSimpleBOLT` (zero-funding) plus an arbitrary data field `authOrMiscData` of up to 75 bytes: the first unlock
123
- argument, created in a commit and authenticated in the settle, which rebuilds its grandparent commit (whose
124
- scriptSig leads with the value) and binds it to the grandparent txid. The commit's own owner signature does
125
- NOT cover it. Same six-push lock layout as `MinSimpleBOLT`; recognised by its suffix fingerprint
126
- `378932c162a2fb2344ae7357664268608a05efa2fc07be60b6dbf35984dcf669`. `unlock()` refuses a value over 75 bytes
127
- (the lock refuses it too). Node-verified (contract-level broadcast suite) 16/16 on a Bitcoin SV regtest and a
128
- teranode regtest; the b017 library tests run on the `@bsv/sdk` Spend engine.
129
- - **Zero-funding spends in `singleSpendUnlock` / `singleAncestorPieces`.** The funding input and the change
130
- output are detected from the tx (`[token, proof?, funding?]`, `[token, p2pb?, change?]`) instead of assumed
131
- last, and an unfunded or change-less ancestor commit is passed as empty (OP_0) pieces. `SingleLayout`
132
- (`MIN_SIMPLE_LAYOUT`, `AUTH_BOLT_LAYOUT`) parameterises the 37-arg and 39-arg unlock layouts.
133
- - Documented (README, template headers): a minted token received by SPV does not prove the sender holds the
134
- issuer key - the issuer-signed **commit** spending it (funded or not) must accompany it, and a token carrying
135
- `authOrMiscData` must travel with its signed commit **and** settle as the package.
136
- - Tests: `minSimpleZF` (43, the zero-funding matrix + 11 rebuild-mismatch refusals), `minSimpleAttack` (16, the
137
- first MinSimple red-team suite), `authBolt` (53 incl. a 27-cell path-coverage gate), AuthBolt template and
138
- scanner (`nftScan`) tests. `npm run build:nft` regenerates both NFT templates from the compiled contract artifacts.
139
-
140
- ### Security
141
- - **`SimpleMultiBOLT`: the six red-team fixes now ship in the template.** The published `0.0.0-b2`
142
- - **`SimpleMultiBOLT`: the six red-team fixes now ship in the template.** The published `0.0.0-b2`
143
- bytecode carried only the original fabricated-hop anchor; a red-team campaign then found and
144
- closed six further covenant defects - five node-verified on a regtest teranode in both directions
145
- (B1, S1, S2, S3, F3); C5 confirmed in simulation and a 4M-signature measurement (its check is a
146
- basic signature-length bound with no node/simulator divergence) - now compiled in:
147
- B1 (`balanceCommit` unchecked -> split inflation to 2^127-1), S1 (co-spent proof not bound to the
148
- bolt -> a token doubles itself), S2 (rebuilt ancestor's issuer never checked -> counterfeit),
149
- S3 (splitter swaps bolt order -> theft + freeze), F3 (a zero grandparent disabled the anchor ->
150
- a non-issuer settles from nothing, contained to one hop), C5 (a signature-length window bricked
151
- ~1 in 52,000 tokens).
152
-
153
- ### Security
154
- - **The scanner now EXECUTES scripts.** `verifyEvents` / `verifyEvent` used to be purely structural: a forged commit
155
- (a stranger's mint, a commit and settle the stranger signed with their own key, which the covenant's issuer guard
156
- refuses at the commit) passed with `ok: true`. Reproduced, then fixed: every input whose source tx is supplied is run
157
- on the `@bsv/sdk` Spend engine, and a failure returns `ok: false` with `script execution failed: tx <id> input <n>`.
158
- This also closes the redteam2 "misreads" C1-C4 (hand-patched second settle, hidden token input, novel txoType,
159
- inflated balance), which the structure check alone accepted. For mined txs the node already did this; for off-chain
160
- (SPV / zero-funding) packages nothing had.
161
-
162
- ### Changed
163
- - **BREAKING (scanner): every input's source tx must now be supplied.** `verifyEvents` / `verifyEvent` refuse an input
164
- whose source is missing (`source tx <id> of tx <id> input <n> was not supplied`), including funding inputs and the
165
- mint's funding parent; previously external funding was waved through. Supply sources by attaching `sourceTransaction`,
166
- by including the parent in the batch, or by sending BEEF. Results gain `sources: { txid, proven }[]`.
167
- - **Added: BEEF.** Event txs may be given as Atomic BEEF (BRC-95) over BEEF V2 (BRC-96), hex or bytes; new exports
168
- `toAtomicBeef`, `fromBeef`, `isBeef`. BEEF V1 (BRC-62) and a non-self-contained BEEF are refused. BUMPs are not
169
- checked against block headers (use a `ChainTracker`).
170
- - **BREAKING (scanner): a lone mint is no longer a valid event.** `verifyEvents` / `verifyEvent` now refuse a mint
171
- that no commit in the same event/batch spends, returning `{ ok: false, unauthenticated: true, reason: "unauthenticated
172
- mint ..." }` (all token types). A mint only names an `issuerPubKey`; the issuer guard runs when the genesis is first
173
- spent, so a mint alone proves nothing about who holds the key. This verdict is not a signature failure.
174
- A mint with its commit + settle (funded or not) is accepted as before. `ScanResult` / `EventResult` gain
175
- `unauthenticated?: boolean`. Tests: `test/scanner/unauthenticatedMint.test.ts`.
176
- - **BREAKING for existing tokens: `MinSimpleBOLT` is now the zero-funding contract** (the zero-funding build, lock
177
- 1265 -> 1275 bytes) in place of `MSBolt.opt3`. Its static bytecode changed, so its fingerprint changed:
178
- `5dc9c1ddd27e2c91f919531ad82a32c9ce8da772ab87e39af05c2c3361970122` (was
179
- `2892679d85ef021d754036094ecd77e14f0c3934a23a48e09e7da337e50f823d`). `recognizeType` no longer recognises
180
- `MinSimpleBOLT` tokens minted with the old bytecode; they must be REISSUED (the covenant travels in each
181
- token's locking script). The lock layout and the 37-arg unlock layout are unchanged.
182
- - **BREAKING for existing tokens.** The `SimpleMultiBOLT` static bytecode changed, so its fingerprint
183
- changed: `368c45fdf92164e4e0869c9062be84621ea8ef040e8591399bf6ff3b8c819b11` (was
184
- `76cfa45595bfb866010d8f87b9b88d6e27b79a9ab3007119dd00eb0138810c8f`). `recognizeType` no longer
185
- recognises tokens minted with `0.0.0-b2`/`-b1` bytecode - they classify as untrusted and are
186
- invisible to `verifyEvents`, wallet balances and scans. The data-push layout (`LAYOUTS`) is
187
- unchanged, so all TS-side argument construction is identical.
188
- - **Tokens minted with pre-fix bytecode remain exploitable and must be reissued.** The vulnerable
189
- covenant travels in each token's own locking script; upgrading this library does not protect coins
190
- already on chain.
191
-
192
- ### Removed
193
- - **BREAKING: dropped the `MinSimpleDiscountBOLT` and `MinSimpleBalanceBOLT` templates.** The
194
- package now ships three token contracts: `SimpleMultiBOLT` (fungible), `MinSimpleBOLT` (identity
195
- NFT) and `AuthBOLT` (identity NFT + auth data), plus the `pay2Proof` UTXO template. The `MinSimpleDiscountTemplate` and
196
- `MinSimpleBalanceTemplate` exports, their `TokenType` union members, their `LAYOUTS`/`REGISTRY`
197
- entries and their fixtures are gone. `recognizeType` / `verifyEvents` no longer classify those
198
- types; any consumer importing the removed templates or naming those type strings must update.
199
- The kept contracts are unchanged (same bytecode, same fingerprints).
200
- - Coverage for the kept NFT is preserved: `test/lib/minSimpleLifecycle.test.ts` exercises the
201
- `MinSimpleBOLT` mint/commit/settle and a 2-hop ancestor reconstruction through `verifyTx`,
202
- standing in for the removed Discount coupon and ancestor-golden tests.
203
-
204
- ### Fixed
205
- - **`SimpleMultiBOLT`: the second piece of a split could not be transferred or split again.** A settle
206
- co-spends its ancestor commit's proof, and a split commit carries two (vout 1 for piece A, vout 2
207
- for piece B). The builder picked `outputs.length >= 5 ? 2 : 1`, which is always 1 for the 4-output
208
- split commit, so piece B co-spent piece A's proof and its settle failed. The proof vout is now
209
- looked up by the owner's pubKeyHash. Builder-only: the covenant and bytecode are unchanged. Piece B
210
- still has to bring its own funding, because the split settle's change pays piece A.
211
- - **`verifyTx` rejected correctly signed inputs with an nSequence of 0.** It passed
212
- `sequence || 0xffffffff` to the Spend engine, turning a signed non-final sequence into final and
213
- breaking the sighash. It now uses `??`.
214
-
215
- ### Documentation
216
- - README: test and coverage figures refreshed (128 tests across 17 files; 99.5% statements,
217
- 100% functions, 96.3% branches), and the NFT is described as the single `MinSimpleBOLT` identity
218
- token rather than a template family.
219
- - Restored the scanner suite (`test/scanner/verifyEvents.test.ts`) that was deleted with the Discount
220
- and Balance goldens, rebuilt over live `SimpleMultiBOLT` chains.
221
-
222
- See [`docs/ROADMAP.md`](docs/ROADMAP.md) for planned work.
223
-
224
- ## [0.0.0-b2] - 2026-09-05
225
-
226
- ### Security
227
- - **`SimpleMultiBOLT`: fixed a balance-inflation forgery (the "fabricated hop").** A past
228
- recipient of a token could clone a settled token's bytes into an output they funded
229
- themselves, give it any balance they liked, and roll it forward, co-spending the real proof
230
- they legitimately held from the transfer they had received. Every existing check passed:
231
- the commit paid only themselves, the settle rebuilt a genuine grandparent commit and
232
- consumed a real predecessor UTXO that they could sign for. Nothing tied the balance to
233
- anything. **A regtest teranode running GoBDK consensus accepted the whole chain.**
234
-
235
- The settle now reads `balance`, `balanceCommit` and `txoType` off the ancestor it has just
236
- rebuilt, derives the single balance that ancestor authorised (transfer, merge sum, or
237
- either split piece), and requires the balance of the token being spent to equal it. Both
238
- sides of that comparison already existed on chain, so **nothing new is stored**: no new
239
- token field, no new proof field, and no change to the data-push layout.
240
-
241
- There is no gap between the two halves. The rebuild is assembled from fields the spender
242
- supplies, so a forger must choose: give the ancestor's real fields and the reconstruction
243
- hashes correctly but authorises the true balance, not the invented one; or doctor them so
244
- the balance agrees and the reconstruction stops hashing to `grandparentOutpoint`.
245
-
246
- Verified on a real node, not only in simulation: the same rig that accepted the forgery now
247
- rejects the forged settle (`TX_INVALID (31)`), with the honest prefix still accepted and a
248
- byte-tampered control still rejected, reproduced across two independent runs.
249
-
250
- ### Changed
251
- - **BREAKING for existing tokens: `MinSimpleBOLT` is now the zero-funding contract** (the zero-funding build, lock
252
- 1265 -> 1275 bytes) in place of `MSBolt.opt3`. Its static bytecode changed, so its fingerprint changed:
253
- `5dc9c1ddd27e2c91f919531ad82a32c9ce8da772ab87e39af05c2c3361970122` (was
254
- `2892679d85ef021d754036094ecd77e14f0c3934a23a48e09e7da337e50f823d`). `recognizeType` no longer recognises
255
- `MinSimpleBOLT` tokens minted with the old bytecode; they must be REISSUED (the covenant travels in each
256
- token's locking script). The lock layout and the 37-arg unlock layout are unchanged.
257
- - **BREAKING for existing tokens.** The `SimpleMultiBOLT` covenant bytecode changed, so its
258
- static-code fingerprint changed. `recognizeType` will no longer recognise tokens minted
259
- with `0.0.0-b1` bytecode; they classify as untrusted. The API is unchanged, and the
260
- data-push layout is unchanged, so `LAYOUTS` and all TS-side argument construction are
261
- identical to `0.0.0-b1`.
262
-
263
- This is a deliberate clean break, and it has a practical consequence worth stating: an old
264
- token is not merely distrusted, it is **invisible** to anything built on `recognizeType` /
265
- `verifyEvents`, including wallet balances and scans. There is no legacy recogniser and none
266
- is planned. If you hold or index `0.0.0-b1` tokens, identify them before upgrading, because
267
- afterwards this library will not help you find them.
268
- - **Tokens minted with `0.0.0-b1` bytecode remain inflatable and must be reissued.** Upgrading
269
- this library does not protect coins already on chain: the vulnerable covenant travels in the
270
- token's own locking script. Reissue is the only remedy.
271
-
272
- ### Notes
273
- - The NFT templates (`MinSimple`, `MinSimpleDiscount`, `MinSimpleBalance`) are **unaffected**,
274
- and not merely untested: their ancestor rebuild splices in the token's own balance field
275
- rather than accepting the ancestor's as an argument, so the value already sits inside the
276
- pre-image of the hash that must equal `grandparentOutpoint`. An invented balance fails the
277
- hash. They also have no split or merge, so there is no transition to check.
278
- - `test/repro-fabricated-hop.test.ts` deliberately still asserts that the pre-fix chain
279
- verifies. It is the record of what a node accepted, and it recognises its fixture against a
280
- pinned `0.0.0-b1` fingerprint rather than the live registry.
281
-
282
- ## [0.0.0-b1] — 2026-06-24
283
-
284
- ### Fixed
285
- - README title typo: "Bicoin" → "Bitcoin". Docs-only republish (no code changes).
286
-
287
- ## [0.0.0-b] — 2026-06-23
288
-
289
- First public beta. The library is functional and fully tested; the API may still change
290
- before `0.1.0`.
291
-
292
- ### Added
293
- - `SimpleMultiBOLT` fungible token class — mint / transfer / split / merge / melt, each
294
- producing a real, script-valid Bitcoin transaction verified by the `@bsv/sdk` Spend engine.
295
- - NFT token templates: `MinSimple`, `MinSimpleDiscount`, `MinSimpleBalance`, plus the
296
- `pay2Proof` UTXO template.
297
- - Off-chain scanner: `recognizeType` / `REGISTRY` strict fingerprinting, and
298
- `verifyEvent` / `verifyEvents` for validating BOLT transactional events — one event
299
- (mint, commit→settle pair, or melt) or a whole batch (issuer-pinned, every commit
300
- paired with its settle).
301
- - Pre-compiled `.sx` contracts embedded in the templates — **no sx compiler at runtime**.
302
- - `@bsv/sdk` as the single peer dependency (no `@elas_co/ts` runtime dependency).
303
-
304
- ### Packaging
305
- - Build now cleans `dist/` before `tsc` so the published tarball contains no stale artifacts.
306
- - Added `repository`, `bugs`, `homepage`, and `keywords` metadata.
307
-
308
- [Unreleased]: https://github.com/BOLT-Association/b017/compare/v0.1.0...HEAD
309
- [0.1.0]: https://github.com/BOLT-Association/b017/compare/v0.0.0-b2...v0.1.0
310
- [0.0.0-b2]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b2
311
- [0.0.0-b1]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b1
312
- [0.0.0-b]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b
1
+ # Changelog
2
+
3
+ All notable changes to **b017** are documented here. The format is based on
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims to follow
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [Unreleased]
8
+
9
+ ### Changed
10
+ - **npm publishing uses trusted publishing (OIDC) instead of an `NPM_TOKEN` secret.** The token-based publish of
11
+ 0.2.0 was refused by the registry (`E404` on the upload, the answer for a token that cannot publish the package);
12
+ CI's `publish` job now exchanges the run's GitHub identity token for a short-lived publish token, so no secret can
13
+ expire. Setup and reruns are in `scripts/MAINTAINERS.md`, "Releasing".
14
+
15
+ ## [0.2.0] - 2026-11-20
16
+
17
+ ### Added
18
+ - **`lean/scripts/check_generated.py`: the glue's generated files stay reproducible.** It runs, in dependency order,
19
+ the twelve glue generators whose inputs are committed and fails if any output differs from the committed file
20
+ (restoring the files afterwards); CI's `lean-proof` job runs it before the build, beside the vectors' drift check.
21
+ The rules it enforces (never hand-edit a generated file; commit every input a generator reads except a full probe
22
+ output; register a new generator) are in `lean/scripts/README.md`.
23
+ - **`lean/scripts/settle-inputs/` and `extract_settle_inputs.py`: the settle probes' side files, committed.** The
24
+ settle generator read side files that lived only under the git-ignored `lean/.lake/glue-work/`, so the settle
25
+ theorems could not be regenerated on any other machine. The extractor cuts them out of the probes' outputs (the gate
26
+ stack, the outputs fact and now the zero pads, `<probe>.zeros.txt`), and the README gives the exact probe commands.
27
+ - **`docs/issuer-guard.md`: the issuer guard of each family, decoded from the shipped bytecode.** The NFT
28
+ prologue derives `is2ndTx = (grandparent == 0 && txoType != 0)` and requires the issuer under
29
+ `isGenesis || is2ndTx`; the fungible prologue requires the issuer under `isGenesis || grandparent == 0`, the F3
30
+ fix of 2026-09-07, which is a strict superset. The document tells apart the three things that keep being
31
+ conflated (the fabricated hop and its balance anchor; F3 and its zero-grandparent guard; `is2ndTx`, an NFT-only
32
+ design feature that predates both), gives the timeline with commit ids, explains why the NFT family can tolerate
33
+ the settle-typed zero-grandparent orphan at its commit and that F3 was the commit-typed shape both rules refuse,
34
+ and says why `is2ndTx` must **not** be ported (it would close nothing, and the prologue length is the rebuild's
35
+ `signCtx` slice offset).
36
+ - **`test/lib/multiBoltIssuerGuard.test.ts`** pins the issuer guard on the bytes of every contract that carries it.
37
+ Fungible (`SimpleMultiBOLT`, `FixedBOLT`, `OpenBOLT`): a non-issuer's spend of the F3 / `is2ndTx` shape (`21`, no
38
+ grandparent) and of the settle-typed orphan (`20`, no grandparent) that only the fungible rule refuses at its
39
+ commit, each naming the victim issuer and carrying 2^100, is refused at the guard's own `OP_EQUALVERIFY`; the
40
+ honest first settle, and the same bytes under the attacker's own issuer key, are accepted. NFT (`MinSimpleBOLT`,
41
+ `AuthBOLT`, `SerialBOLT`): the `is2ndTx` shape is refused at the guard, the attacker-issuer control is accepted,
42
+ and the resting `00` orphan's lone commit is accepted, pinning the narrower NFT rule. The guard is located from
43
+ its own flag (`OP_BOOLOR`, then `OP_IF`), not by position, since the genesis contracts run an earlier
44
+ `OP_EQUALVERIFY` on `mintData`. No existing test exercised the guard's grandparent branch on any contract but
45
+ MinSimpleBOLT.
46
+ - **`docs/ROADMAP.md`** records, as deferred work, aligning the NFT issuer guard with the fungible rule (drop the
47
+ `txoType` term from `is2ndTx`): an optimisation, not a fix, to be folded into the next NFT bytecode rebuild since
48
+ it changes the fingerprint and needs a reissue.
49
+ - **A machine-checked proof** (`lean/`, Lean 4). Terms: the *model* is Lemmas 1–7 of `docs/formal-proof.md` written
50
+ in Lean as `Accepts`; the *script* is each covenant's compiled bytecode as shipped. Layer 1 proves Theorems 1–4 of
51
+ the model for both families over arbitrary runs, with Assumptions 1–2 as hypotheses and only Lean's three standard
52
+ axioms; a concrete NFT lifecycle is proved a valid run. Layer 2 runs the script inside Lean, with bsv-script-lean
53
+ v1.2.0 under today's BSV rules (post-Chronicle; the old rules are a control only), on the test suite's real
54
+ transactions: the honest lifecycles, every red-team attack and the historical fabricated-hop chain against its
55
+ pre-fix script. Each verdict is registered with the kernel (`native_decide`) and the scanner's fingerprints are
56
+ recomputed. `npm run lean:vectors` regenerates the vectors deterministically; the CI job `lean-proof` builds the
57
+ proof, runs every vector, audits axioms and fails on vector drift. `docs/formal-proof.md` §1.6 states what is
58
+ still trusted.
59
+ - `test/helpers/minSimpleAttacks.ts`: the NFT red-team builders, shared by the suite and the exporter.
60
+ - **`test/lib/indexByte.test.ts`**, with `test/helpers/indexByte.ts`: the index-byte shapes of the `smb_probe_idx_*`
61
+ vectors under the fast suite. The builders (a split settle rebuilt with `pkh1` or `i2` set, a commit or settle with
62
+ `inputIndexN` = 1, a token object on any output) are shared with the Lean vector exporter, which imports them, so
63
+ the two judge the same transactions: four tests, every later operation on a token whose index byte is not its
64
+ position accepted by the Spend engine (no dead tokens).
65
+ - **`docs/ROADMAP.md`** records, as deferred work, dropping the fungible lock's index byte `outputIndexN`, which
66
+ nothing on chain or off reads, at the next fungible bytecode rebuild (new fingerprints and a reissue, so never on
67
+ its own); `inputIndexN` stays as the merge-role flag.
68
+ - **Theorem 1 per hop** (`t1_step`, `t1_genesis_signer`, `lean/BoltProof/Theorems/Authenticity.lean`): every token
69
+ a spend produces is built from the one it spent, same issuer, that token as parent; a genesis moves only under the
70
+ issuer's key. Stated of the script for every valid input by `real_issuer_carried` and `real_genesis_needs_issuer`
71
+ in `Glue/Refine/EndToEnd.lean` (MinSimpleBOLT) and `Glue/SimpleMulti/EndToEnd.lean` (SimpleMultiBOLT).
72
+ - **`lean/BoltProof/Theorems/Chain.lean`, the Layer 1 half of the chaining step**: in a valid run a settled token's
73
+ grandparent is output 0 of an earlier commit step whose outputs are its token, the recipient's proof and, for a
74
+ split, the second recipient's proof (`Run.grandparent_commit`), so the index the script forces (1, or 2 for a
75
+ split) names a proof output of the real grandparent. Reading a real transaction's bytes as that step's `TxDesc`
76
+ is what remains of the composition.
77
+ - **The chaining step, Bridge half** (`lean/BoltProof/Bridge/Glue/Refine/Chain.lean`, `Glue/SimpleMulti/Chain.lean`,
78
+ `Theorems/Chain.lean`): a chain of real MinSimpleBOLT or SimpleMultiBOLT spends, each read by its refinement, with
79
+ the UTXO model's bookkeeping (a well-formed genesis set, each step spending live tokens, each transaction id new),
80
+ is a valid model run (`valid_of_chain`), so Theorems 1, 3, 4 and 5 hold of real tokens: every live token is rooted
81
+ at a genesis of the run and carries the issuer along its lineage, tokens are neither created nor duplicated and
82
+ value is conserved, every type byte is defined, and each real commit's proof admits one settle carrying the
83
+ committed balance (`chain_authenticity`, `chain_count`, `chain_conservation`, `chain_defined_types`,
84
+ `chain_proof_gating`, `chain_fabricated_hop_excluded`). The grandparent's reality (`GpReal`) is read off the run
85
+ (`Run.grandparent_commit_upto`): outright for the NFT script, and for the fungible one under A1, with the
86
+ grandparent token output's balance signs read off the creating commit's own bound check, not assumed.
87
+ - **The second rebuild welded** (`lean/BoltProof/Bridge/Glue/SimpleMulti/RebuiltBParse.lean`, `AnchorB.lean`,
88
+ `GpWeldB.lean`, generated by `lean/scripts/gen_rebuiltB_parse.py` from the first rebuild's files): the bytes a merge
89
+ settle hashes against the other lineage's grandparent txid are parsed as a transaction whose first output is the
90
+ pieces' token, under the widths the run fixes and `HonestPiecesB` of the first piece set, and identified with the
91
+ real other grandparent under no second preimage of its serialisation (`gp_eq_gpTxB`). `GpRealB` is now
92
+ `GpRealF`'s twin (well-formed, the txid, the token at the named index, the proof outputs), the merge-settle
93
+ refinement reads the other grandparent's token type off the bytes (`gpB_token_of_facts`), and the fungible chain
94
+ asserts nothing of a merge settle beyond its spend (`typeB` is gone).
95
+ - **`lean/BoltProof/Bridge/Glue/SimpleMulti/EndToEnd.lean`**: the fungible end-to-end statement. Each proof stage's
96
+ hypotheses are one structure (`RealSpend`, `RealSettleGp`, `RealMergeCommit`, `RealMergeSettle`); Lemma 1,
97
+ Theorems 2, 3 and 4 per step and Theorem 1 per hop are stated of any `SimpleMultiBOLT` spend the script accepts.
98
+ - **Lemma 4 proved over the bytecode** (`lean/BoltProof/Bridge/Gadgets/`): the null-ancestor check's tail
99
+ `OP_SIZE OP_NIP OP_0 OP_EQUALVERIFY` passes exactly when the concatenated ancestor arguments are empty and
100
+ fails with `SCRIPT_ERR_EQUALVERIFY` otherwise, for every input, over bsv-script-lean's own instruction loop and
101
+ with only the three standard axioms; nine per-instruction step lemmas it rests on.
102
+ - **Lemma 6's over-take guard proved over the bytecode** (`Gadgets/BalanceGuards.lean`): the split commit's
103
+ `2d OP_PICK 34 OP_PICK OP_SUB OP_0 OP_GREATERTHANOREQUAL OP_VERIFY` passes exactly when `piece ≤ balance` and
104
+ fails with `SCRIPT_ERR_VERIFY` otherwise, for every input. **Its merge sum guard** `2d OP_PICK 34 OP_PICK OP_ADD
105
+ OP_11 OP_PICK OP_LESSTHANOREQUAL OP_VERIFY` likewise passes exactly when `balance + other ≤ bound`.
106
+ - **Lemma 7 proved over the bytecode** (`Gadgets/Parity.lean`): the fungible covenant's 29-byte parity check
107
+ (`1a OP_PICK OP_2 OP_MOD OP_DUP OP_IF … OP_ENDIF OP_DUP 27 OP_PICK OP_2 OP_MOD OP_SWAP OP_IF OP_0 OP_ELSE OP_1
108
+ OP_ENDIF OP_EQUALVERIFY`) passes exactly when a commit-typed spent token is followed by its own settle type and a
109
+ settle-typed one by a commit type, and fails with `SCRIPT_ERR_EQUALVERIFY` otherwise, for every input; on the six
110
+ defined type bytes this is the Lean model's `Fam.edge .fungible` relation (`parityCheck_edge_iff`). Step lemmas
111
+ for the conditionals (`OP_IF`, `OP_ELSE`, `OP_ENDIF`, skipped instructions) and the arithmetic added.
112
+ - **Lemma 7 for the NFT family proved over the bytecode** (`Gadgets/NftType.lean`): the NFT covenants write the
113
+ produced type rather than check it — the selector `d OP_PICK OP_IF 0100 OP_ELSE 0121 OP_ENDIF OP_CAT` of
114
+ `MinSimpleBOLT`, `AuthBOLT` and `SerialBOLT` appends type `0x00` to a commit-typed token's successor and `0x21` to a settle-typed one's, for every input; on
115
+ the family's type bytes this is the model's `Fam.edge .nft` relation (`nftTypeSel_edge`).
116
+ - **Lemma 6's bounds and settle-side re-checks proved over the bytecode** (`Gadgets/BalanceBounds.lean`): the
117
+ balance bound check (`0 ≤ balance ≤ 2¹²⁷−1`, offsets 610 and 621), the merge settle's sum re-check (offset 781)
118
+ and the split settle's remainder re-check (offset 935) each pass exactly when their arithmetic predicate holds
119
+ and fail with `SCRIPT_ERR_VERIFY` otherwise, for every input; with the commit guards this closes Lemma 6 at the
120
+ fragment level.
121
+ - **Theorem 5, proof gating** (`lean/BoltProof/Theorems/ProofGating.lean`): the §8.1 fabricated-hop exclusion at the
122
+ ledger level — under the UTXO no-double-spend rule a commit's proof output admits at most one settle, and under
123
+ collision resistance a settle's balance is exactly the settle result of the real commit its grandparent names.
124
+ The run model admits only covenant-created tokens, so the attack's own non-covenant transactions are outside it;
125
+ a recipient's off-chain lineage checks (`docs/verification-scaling.md`) are not formalized.
126
+ - **The script proved to enforce the model, per input** (`lean/BoltProof/Bridge/Glue/`, described in
127
+ `lean/README.md`). A symbolic execution of each of the four scripts from the stack the unlocking script leaves,
128
+ built from one inversion lemma per opcode and the `sym_all` driver over the scripts cut into named chunks
129
+ (`lean/vectors/sections.ts` → `Generated/Chunks.lean`). Per script, `*_sound` states what it enforces whenever it
130
+ does not fail, `reaches_*` shows the run reaches every fragment proved in `Gadgets/` with the stack its lemma
131
+ assumes, and `*_refines` (one per NFT script, four stages for `SimpleMultiBOLT`) shows that any spend the network
132
+ accepts is one the model accepts, under assumptions listed once per script: OP_PUSH_TX binds the preimage and
133
+ nothing the spend hashes has a second preimage; the grandparent a token names is the real commit two steps back;
134
+ three model rules the script does not check; and, fungible only, its three extra assumptions (resolved questions in `lean/README.md`). Standard axioms only;
135
+ `Regress.lean` applies each theorem to the real honest spends (`native_decide`). The axiom audit now has Lean
136
+ enumerate Layer 2's declarations, and `AxiomCheck.lean` lists the glue's theorems. The generators of the glue's
137
+ regular files are under `lean/scripts/`.
138
+
139
+ ### Changed
140
+ - **BREAKING for existing tokens and for `lock()` callers: the `outputIndexN` lock field is gone from
141
+ `SimpleMultiBOLT`, `FixedBOLT` and `OpenBOLT`.** The covenant read it at exactly one place, the merge settle's
142
+ bolt-prevout order, and that read always saw `00`: only a merge commit builds the token a merge settle spends,
143
+ and both merge-commit writers emit `00` (measured on every lifecycle fixture with the read deleted, probed and
144
+ forced, and on a regtest teranode). The read is now the constant order, so nothing read the field any more; it
145
+ goes, with its scriptCode slice, its three writers and its three ancestor mirror pieces
146
+ (`Vin1CTXOutputIndexN`, `Vin2CTXOutputIndexN`, `Vout1OutputIndexN`). Every remaining covenant decision is
147
+ unchanged: each executed pick reads the same stack item as before, on every lifecycle fixture.
148
+ - Lock data pushes 11 -> 10 (genesis family 13 -> 12): `parentOutpoint` / `grandparentOutpoint` /
149
+ `issuerPubKey` sit one chunk earlier. Scanner layouts and event field indices follow.
150
+ - Ancestor pieces per ancestor 75 -> 72 (FixedBOLT 77 -> 74, OpenBOLT 80 -> 77): unlock args 170 -> 164
151
+ (`ARGS2CTX_SMB` 164 -> 158, `SKIP_SMB` 150 -> 144); FixedBOLT 174 -> 168, OpenBOLT 180 -> 174.
152
+ - `SimpleMultiTemplate.lock()` loses its `outputIndexN` parameter (it sat before `prevVoutIdx`).
153
+ - Static suffix 4700 -> 4513 bytes (FixedBOLT 5148 -> 4960, OpenBOLT 5210 -> 5021), so every token output and
154
+ every settle's unlocking script is smaller. Measured on the 20 lifecycle fixtures of the three contracts, built
155
+ on both bytecodes: commits and transfer settles about -385 bytes each, mints about -570, split and merge settles
156
+ about -575; whole lifecycles -3.1% to -3.5% (SimpleMultiBOLT split lifecycle 94,067 -> 90,812 bytes, merge
157
+ lifecycle 143,702 -> 138,889; FixedBOLT merge 169,485 -> 164,264; OpenBOLT merge 157,848 -> 152,980).
158
+ - The Lean development (`lean/`) is ported to the new bytecode: the vectors regenerate (`npm run lean:vectors`,
159
+ every verdict re-judged), the glue's offsets and stack positions follow the new suffix (pieces 75 -> 72 per
160
+ ancestor, the settled lock 4946 -> 4757 bytes), the second rebuild has one case, and the settle theorems no
161
+ longer case on `inputIndexN` or `i2` (the settle reads neither); the theorem statements are unchanged.
162
+ `lean/scripts/settle-inputs/` holds the settle probes' side files and the commands that recreate them.
163
+ - Fingerprints: `SimpleMultiBOLT` `4c37d33f26189961f42d129309365bd775c070187216e8f10f33011209cb03a8` (was
164
+ `4a7613d176b46f03f1b06df86d7b96a667c31a277e2b4dbc5d5832d1c225fe34`); `FixedBOLT`
165
+ `2c9e1bf0959d95a55a9c476b6df570bfc5e58f122731013d9b2fddc193164046`; `OpenBOLT`
166
+ `1d69d2185cfac8fd117edf8cbe577791cca24442c7eff54484cb978ec02c64f4`. Tokens minted with the previous bytecode
167
+ keep it and are no longer recognised by `recognizeType`; reissue them.
168
+ - **The model's L2 and L3 clauses admit exactly what the script admits** (`lean/BoltProof/Model/Covenant.lean`,
169
+ `Model/Spend.lean`). A split settle's two tokens may come out in either order (`Spend.OutsOK`), and the anchor
170
+ names the proof a settle co-spends: the balance carried is the settle result at the index one below that proof,
171
+ not at the parent's position, which the script never reads. Safe: the order changes neither recipient nor
172
+ balance, only a proof's recipient can spend it, the script forces the proof to the grandparent's first or, for a
173
+ split, second output (`AnchorOK`), and Theorem 5 lets each proof admit one settle, so each settle result of a
174
+ real commit is claimed at most once. The position-based anchor was wrong in the swapped order. Theorems 1–4 keep
175
+ their statements; Theorem 5's anchor names the proof's index. The script-to-model proofs no longer assume the
176
+ split settle's flags or the anchor argument `i5`: `Residual` loses `splitFlags` and `ResidualGp` loses `i5`;
177
+ `outs_settle_split` proves both orders from the script's flag cases and `AnchorOK.index` reads the anchor's index
178
+ from the script's own check. SimpleMultiBOLT's remaining assumptions are Q4, Q7 and Q8 of `lean/README.md`.
179
+ - **`BalsNonneg` shed from the fungible chain** (`lean/BoltProof/Bridge/Glue/SimpleMulti/ChainBals.lean`,
180
+ `Chain.lean`): the grandparent token output's balance signs are no longer assumed. A real commit's produced
181
+ token carries non-negative balance bytes, from the covenant's own bound check (`commit_out_bals_basic`,
182
+ `commit_out_bals_merge`); the chain identifies the grandparent with its creating commit byte for byte
183
+ (`tx_eq_of_txid`, under no second preimage and each step's txid agreement) and reads the signs off it
184
+ (`chainStep_commit_bals`). The fungible `ChainStep` gains a per-step txid agreement (`hptxid`, the A1-style
185
+ fact the NFT chain's `ChainSpend` already carries); in exchange no byte-level balance fact is assumed. The
186
+ axiom audit now checks 2677 theorems, all on the three standard axioms.
187
+ - **The chain stated for AuthBOLT and SerialBOLT** (`lean/BoltProof/Bridge/Glue/AuthBolt/Chain.lean`,
188
+ `SerialBolt/Chain.lean`): each is MinSimpleBOLT's chain file over its own abstraction, so a chain of real
189
+ AuthBOLT or SerialBOLT spends is a valid model run and Theorems 1, 3, 4 and 5 hold of their real tokens too
190
+ (`valid_of_chain`, `chain_authenticity`, `chain_count`, `chain_defined_types`, `chain_proof_gating`,
191
+ `chain_fabricated_hop_excluded`). Their `GpReal` was already settle-only, so the grandparent's reality is read
192
+ off the run as it is for MinSimpleBOLT, with nothing assumed. The chain now covers all four shipped scripts.
193
+ - **`lean/README.md` is the one document of the Lean development.** It absorbs the glue plan (`lean/GLUE-PLAN.md`:
194
+ the proof style, the per-script structure, the rebuilds, the chain, the assumptions, the findings, the open
195
+ questions and the build notes) and the checklist `lean-proof-todo.md`, both deleted; the prose is compressed, the
196
+ follow-ups are listed once, and the generators' pitfalls are recorded in `lean/scripts/README.md`. The sources,
197
+ the exporter's vector notes and the other documents now point at the README.
198
+ - **The NFT refinements ask `GpReal` of a settle only** (`Residual.gp`): a commit's token can name a settle
199
+ transaction as its grandparent, which has no proof output at index 1, so the unconditional form could not be met
200
+ by the commits of a chain. The theorems are stronger, their proofs unchanged.
201
+
202
+ ### Findings (from the Lean bridge, bsv-script-lean v1.2.0)
203
+ - **A merge's carried balance is checked at the settle, not the commit** (`lean/README.md` Q8; vectors
204
+ `smb_probe_q8_melt_other_*`). A merge commit whose partner input takes the melt branch is accepted whatever balance
205
+ it claims for the partner. The settle with the honest balance passes; the settle claiming 1,000,000 for a token of
206
+ balance 1 is refused (`SCRIPT_ERR_EQUALVERIFY`). An inflated merge commit can exist but never settles; no settled
207
+ token carries value nobody minted. The proofs keep the assumption that the partner presents a preimage, and a
208
+ `0x25` token's `balanceCommit` is unchecked until its settle.
209
+ - **A merge settle's other-lineage index is pinned to a proof output** (Q9; vectors `smb_probe_q9_i4_change_*`,
210
+ controls `smb_probe_q9_i4_proof_*`). A merge settle whose `i4` names the other grandparent's change output instead
211
+ of its proof, and spends that output in the proof input's place with its owner's key, is refused at the covenant
212
+ input (`SCRIPT_ERR_EQUALVERIFY`), whether the other grandparent is a transfer commit or a split commit; the same
213
+ settle with `i4` on the proof passes. The other lineage's proof cannot be left unspent, so proof gating holds on
214
+ both sides of a merge. The pin is read off the bytes by `anchorB_index` (`RefineMergeSettle.lean`): the second
215
+ rebuild's anchor fixes `i4` to 1, or to 2 under the split type piece, as `AnchorOK.index` fixes `i5`. `GpRealB`
216
+ asks a proof output at 1 and, under the split type piece, at 2, instead of one at `i4`, and the second rebuild's
217
+ weld identifies the pieces with the real other grandparent, so the chain asserts nothing of a merge settle beyond
218
+ its spend.
219
+ - **An undefined next type cannot be committed** (Q4; vectors `smb_probe_type_oor_27_commit`,
220
+ `smb_probe_type_oor_29_commit`, with `smb_probe_type27_commit`). The parity check fixes only the next type's
221
+ parity, so off genesis the spender may name any odd byte, and the issuer guard refuses `0x27` only when it fires
222
+ (genesis or no grandparent). But a mid-lineage commit whose spent token has a grandparent (the guard silent) and
223
+ an undefined next type is refused at the covenant's own `OP_EQUALVERIFY`, so the written type is pinned to the six
224
+ even off the guard. This resolves Q4 of `lean/README.md` empirically; the `SmbType a.nty` restriction the
225
+ soundness and refinement theorems carry is the modelling boundary, not a gap, with these probes as the standing
226
+ evidence (a formal derivation would drive a symbolic next type through the output builder, a path-family proof,
227
+ deferred).
228
+ - **A split settle's output order is the spender's** (Q3; vectors `smb_probe_q3_*`). With `pkh1` set, the script
229
+ accepts the settle with its two tokens swapped, each index byte off its position; both stay spendable with the
230
+ committed recipients and balances. Harmless to value; the model admits either order (`Spend.OutsOK`) and the proof covers
231
+ both, so no assumption on the flags remains. Followed through every later operation (`smb_probe_idx_*`, 20 vectors): a token whose index byte
232
+ disagrees with its position, by `pkh1`, `i2` or `inputIndexN`, is transferred, split, merged as either input and
233
+ melted by the honest builder with every input accepted. No spend reads the byte: each spend writes it afresh, the
234
+ rebuild hashes it as supplied, and the anchor's index comes from the proof-vout argument. No token dies of it.
235
+ - **A cross-issuer merge is refused by the other token's covenant** (input 1 of the merge commit,
236
+ `SCRIPT_ERR_EQUALVERIFY`): both covenants pin the output's `issuerPubKey` to their own, as the interface clause
237
+ `l_merge_same_issuer` states.
238
+
239
+ ### Fixed
240
+ - **`scripts/lean-axiom-check.mjs` failed on Windows**: it took the repository root from `URL.pathname`
241
+ (`/C:/...`), which `path.join` turns into `C:\C:\...`; it now uses `fileURLToPath`.
242
+ - **`lean/scripts/gen_smregress.py` no longer reproduced `Regress.lean`**: the guards had been edited by hand after
243
+ the generator last ran (the `GpRealF` proof-output arms, the merge settle's `GpRealB` record), so regenerating
244
+ broke the build. The generator now writes the committed form and is idempotent (it no longer adds a blank line per
245
+ run); `check_generated.py` catches the next such drift.
246
+ - **`gen_settle.py` no longer reads the probes' 90-210 MB outputs**: the zero pads it took from each output's head are a
247
+ side file now (`<probe>.zeros.txt`), so `settle-inputs/` alone regenerates the settle files.
248
+ - **Docs: `formal-proof.md` Lemma 5 still described the pre-F3 fungible guard** ("the only issuer check ...
249
+ fires when the spent token is parentless"). The lemma now states the shipped rule for both families inline,
250
+ with a two-line provenance note in place of stacked corrections; §8.1 gains the F3 row and §9 the new suite; the
251
+ README links the new document and notes that both families demand the issuer at the first settle too.
252
+ - **Docs: `formal-proof.md` §9 and `unforgeability.md` §7 had gone stale.** Both quoted "126 tests across 18
253
+ files", cited suites removed in `ab95827` (`parity.test.ts`, `singleAncestor.test.ts`, `singleCoupon.test.ts`)
254
+ and said the scanner accepts a lone genesis mint, which it has refused as unauthenticated since `110ff77`. The
255
+ rows now cite the suites that carry each property, and the counts point at the README, where
256
+ `npm run coverage:readme` generates them, instead of being copied.
257
+ - Documentation corrected by what the Lean glue found: the NFT prologue's `OP_DUP OP_BIN2NUM OP_0NOTEQUAL` runs
258
+ on the grandparent outpoint (`gp ≠ 0`), not the type (`Gadgets/NftType.lean`, `lean/README.md`); `lean/README.md`'s
259
+ issuer-guard note said the fungible family lacks the second-spend guard, which `docs/issuer-guard.md` and the
260
+ glue's `Enforced.issuer` both show it has; and two rejected vectors fail where the exporter's comments now say
261
+ (`smb_wrong_key_commit#0` at the prologue's issuer guard, `smb_extra_output_settle#0` in the unlocking script's
262
+ own OP_PUSH_TX).
263
+
264
+ ## [0.1.0] - 2026-10-11
265
+
266
+ ### Changed
267
+ - **Coverage is 100% on every metric and the thresholds enforce it** (`vitest.config.ts`: statements, functions,
268
+ lines and branches 100; was 99 / 100 / 99 / 98), so a new uncovered branch fails the coverage run. Three
269
+ reachable branches gained tests (`coverageEdges`: `p2pkhUnlock` signing from an attached source without a txid,
270
+ and refusing a txid with no source; a merge paid to a public-key recipient keeps the builder's signer). 14
271
+ defensive guards were marked unreachable with their reason (21 `v8 ignore` markers in all; none covers a covenant
272
+ path or a scanner verdict).
273
+ - **`verifyTx` is documented as throw-on-failure, and the dead checks behind it are gone.** Every failure already
274
+ threw (a failing script: `Spend.validate()` throws rather than returning false), so `valid` was always `true` when
275
+ it returned. Its type now says so (`valid: true`; the `{ valid, scriptExecutions }` shape is kept, so callers are
276
+ unaffected), and the `if (!valid)` checks in `verifyTx` and the `SimpleMultiBOLT` builder are removed. A builder
277
+ failure now reads `<TX TYPE> not valid: <the script error>` (e.g. `MERGE COMMIT TX not valid: ... OP_EQUALVERIFY ...`);
278
+ the separate `Mint tx not valid` / `... tx not valid [bsv]` messages, which could never fire, are gone.
279
+ `npm run coverage:check` now compares the README's percentages and test counts, not the `(covered/total)`
280
+ fractions: V8 counts a few closure branches on some runs only, so the branch total moves by one or two between
281
+ identical runs while coverage stays 100%.
282
+
283
+ ### Added
284
+ - **The genesis family: `FixedBOLT`, `OpenBOLT` and `SerialBOLT`.** Three token types whose lock leads with the
285
+ token's own asset outpoint (null on the mint, the mint outpoint from the first spend on) and the issuer's
286
+ `mintData` (0..255 bytes on the mint only, `OP_0` on every later output), so a token names its asset in O(1).
287
+ - `FixedBOLT` (fungible): one genesis per asset, a fixed supply. Only tokens of one genesis merge; a cross-genesis
288
+ or cross-issuer merge is refused by the covenant at the merge commit, and the class refuses it before building.
289
+ - `OpenBOLT` (fungible): one issuer, many mints. Tokens of different mints merge, and the merge commit re-roots the
290
+ stored outpoint (`lastMergeOrGenesisOutpoint`) to vin0's token outpoint; a cross-issuer merge is refused.
291
+ - `SerialBOLT` (NFT): each token carries its own mint outpoint as a serial; zero-funding like `MinSimpleBOLT` (a
292
+ commit or settle may carry no funding input, change is optional).
293
+ - Classes `FixedBOLT`, `OpenBOLT` (every `SimpleMultiBOLT` operation: mint with `mintData`, transfer, split, merge,
294
+ melt); templates `FixedMultiTemplate`, `OpenMultiTemplate`, `SerialBoltTemplate`; `genesisFieldFor`,
295
+ `mintDataFor`, `outpointOf`, `MINT_DATA_MAX_BYTES`. The fungible engine takes a `MultiLayout`
296
+ (`SIMPLE_MULTI_LAYOUT`, `FIXED_BOLT_LAYOUT`, `OPEN_BOLT_LAYOUT`); `SimpleMultiBOLT` is unchanged.
297
+ - Scanner: the three types are registered with two recognition specs each (`mint`: null outpoint + any mintData;
298
+ `postMint`: set outpoint + empty mintData), so a non-empty mintData after the mint is not a token.
299
+ `recognizeToken` returns the type and its phase (`recognizeType` is unchanged). `verifyEvents` pins the
300
+ **asset**, not only the issuer: every token output's outpoint must follow from its parent token (copied, the
301
+ mint outpoint at the first spend, or `OpenBOLT`'s re-root), and a `FixedBOLT` merge must not mix genesis
302
+ outpoints.
303
+ - Fingerprints: `FixedBOLT` `b07ea12b490c759d172016f71d0026c4894ff7d4eadfae75bd845ce72aa5fd81`, `OpenBOLT`
304
+ `47a41a00e199904ba84e2e0e4890d3d041782fa3ca283d26014218e4286b72b6`, `SerialBOLT`
305
+ `aee7eee8b1254aa765d3f896610d052a2b2da997665e3d9f3d37293ef86d6921`.
306
+ - Tests: every ancestor piece and leading push checked byte for byte against chains built by the reference
307
+ simulator (`genesisLayouts`, 27), Spend-engine lifecycles, mintData and merge rules (`GenesisMultiBOLT`, 10), the whole
308
+ zero-funding suite on `SerialBOLT` plus mintData and melt (`serialBoltZF`, 48), templates (9), scanner (21).
309
+
310
+ ### Changed
311
+ - **BREAKING for existing tokens: `SimpleMultiBOLT` drops dead covenant code.** The `ancestorHas2TokenOutputs`
312
+ branch is removed: it rebuilt a commit carrying a second token, and no such commit can exist (a commit with a
313
+ second token output is refused at the commit, by the simulator and by both a Bitcoin SV and a teranode regtest).
314
+ With it go its 22 `Vout2*` ancestor args, plus the 6 issuer-key ancestor args nothing has read since the
315
+ issuer-counterfeit fix spliced the token's own `issuerPubKey`. Unlock args 198 -> 170 (75 ancestor pieces per
316
+ ancestor, was 89; `ARGS2CTX_SMB` 192 -> 164, `SKIP_SMB` 178 -> 150); the locking script is 403 bytes smaller
317
+ (static suffix 5103 -> 4700) in every token output, and every settle's unlocking script is smaller too. Every
318
+ covenant decision is unchanged: each executed pick reads the same stack item as before, on every lifecycle
319
+ fixture. The static bytecode changed, so the fingerprint changed:
320
+ `4a7613d176b46f03f1b06df86d7b96a667c31a277e2b4dbc5d5832d1c225fe34` (was
321
+ `368c45fdf92164e4e0869c9062be84621ea8ef040e8591399bf6ff3b8c819b11`). Tokens minted with the previous bytecode
322
+ keep it (the covenant travels in the token script) and are no longer recognised by `recognizeType`; reissue them.
323
+
324
+ ### Added
325
+ - **The anchor, and `verifyAndBroadcast`.** The anchor is the token tx a batch stands on: the settle before its
326
+ first commit (settle N-1), or the mint when the batch starts at genesis. What travels p2p is `[mint, c1, s1]` or
327
+ `[sN-1, cN, sN]`. `verifyEvents` now validates the anchor first, like an event tx (golden fingerprint, issuer,
328
+ arrangement, sources, script execution), pulls it into the batch when it was only attached as a source or inside
329
+ a BEEF, and names it in `ScanResult.anchors`. An anchor settle is the one settle allowed without its commit in the
330
+ batch. `verifyAndBroadcast(txs, broadcastAnchor, opts)` runs `verifyEvents` and then hands every anchor to the
331
+ caller's broadcaster; the batch is accepted only if the network accepted or had already seen each one
332
+ (`AnchorRef`, `AnchorStatus`, `AnchorBroadcastResult`, `AnchorBroadcaster`). This closes a forged history hidden in
333
+ the sources: a stranger-signed `commit1` behind `settle1 -> commit2 -> settle2` used to pass as
334
+ `verifyEvents([commit2, settle2])`; `settle1` now fails execution as the anchor. A lone melt now verifies in `verifyEvents` when the settled token
335
+ it spends is attached (the type is read off that token, which becomes the anchor), and an attached source that is
336
+ not the tx its outpoint names is refused. Offline execution reaches the anchor's own inputs only: a forgery two
337
+ events back passes `verifyEvents` and is caught by the anchor broadcast alone (pinned in the tests).
338
+ Tests: `anchor` (52), `anchorShapes` (40).
339
+ - **An unfunded anchor is refused without an SPV proof to a known block header.** An anchor must be a tx the
340
+ network has seen and will therefore mine; an anchor with no funding input pays no fee, so being seen proves
341
+ nothing. It is accepted only when it carries a merkle path whose root the caller confirms as a block header:
342
+ `ScanOpts.isKnownBlockRoot(merkleRoot, height)`, or a `chainTracker` (`HeaderSource`) given to
343
+ `verifyAndBroadcast`. No proof, no headers, an unknown root, a wrong height, a path for another tx, or a
344
+ failing lookup all refuse the batch, and nothing is broadcast. The events standing on an anchor may still be
345
+ unfunded. Tests: `anchorUnfunded` (42).
346
+ - **A header-proven anchor is not re-executed and needs no sources.** An anchor (funded or not) whose merkle path
347
+ is confirmed against a known block header was validated by consensus, so its inputs are skipped and their source
348
+ txs need not be supplied. A mined anchor can therefore be delivered as BEEF, which stops at proven txs. The
349
+ header lookup is the trust root; a merkle path without a known header changes nothing. Event txs are always
350
+ executed. With a `chainTracker`, `verifyAndBroadcast` now collects the roots in a first pass, asks the tracker,
351
+ and runs the real scan against the answers.
352
+ Tests: `anchorProven`, including an unfunded `SimpleMultiBOLT` anchor.
353
+ - **Value conservation is checked.** An anchor whose outputs exceed its inputs is refused. An event tx that does
354
+ so is reported in `ScanResult.offChainOnly` / `EventResult.offChainOnly` (`OffChainOnlyTx`) and accepted: a
355
+ never-broadcast commit / settle is valid off chain. `ScanOpts.requireBroadcastable` refuses such a batch. A
356
+ header-proven anchor is not re-checked. Tests: `valueConservation` (23).
357
+ - **The scanner no longer throws on a broken `Transaction` object.** An input with no source reference or no
358
+ unlocking script, or an output with no locking script, makes the SDK throw when the tx is serialised; that used to
359
+ escape `verifyEvents`, `verifyEvent` and `verifyAndBroadcast`. They now return `unverifiable input: ...`.
360
+ Tests: `scannerEdges`, `builderEdges` (46).
361
+ - **A batch element that is not a transaction is refused, not thrown.** `null`, `undefined`, a number or a plain
362
+ object in the array used to surface as `unparseable batch: TypeError ...`; it now returns
363
+ `not a transaction: expected a Transaction, raw tx hex, or BEEF hex / bytes`. Tests: `scannerInputs` (12).
364
+ - **Coverage tooling (maintainers).** `npm run coverage:gaps` lists every uncovered branch as `file:line`;
365
+ `npm run coverage:readme` generates the README test counts and coverage table (`coverage:check` fails if they
366
+ are stale); `vitest.config.ts` now has coverage thresholds. `verifyEvents.ts` was refactored with no change in
367
+ verdicts (one helper each for the source lookup, the spent txid and error text).
368
+ - **`melt(privateKey)` on `MinSimpleTemplate` and `AuthBoltTemplate`** (`SingleUnlockParams.melt`): the owner burns
369
+ the token with a null CTX and no token output, funded or unfunded. Script-level only (the `@bsv/sdk` Spend
370
+ engine); the b017 melt builder has not been run against a node. Tests: `minSimpleMelt` (40).
371
+ - **`verifyEvent` takes its verdict from the same scan as `verifyEvents`.** It used to return
372
+ `{ ok: true, kind: "mint" }` for a lone commit, a lone settle or two unrelated settles, ignored
373
+ `trustedIssuerPubKey`, had no anchor step, and threw on an input pointing past its source's outputs. It now
374
+ refuses all of those, requires exactly one action (its anchor and the mint it authenticates may ride along),
375
+ and returns `anchors`. Tests: `verifyEventSingle` (34).
376
+ - **`AuthBOLT`: a new identity-NFT type** (`AuthBoltTemplate`, `AUTH_DATA_MAX_BYTES`, `TokenType` `"AuthBOLT"`).
377
+ `MinSimpleBOLT` (zero-funding) plus an arbitrary data field `authOrMiscData` of up to 75 bytes: the first unlock
378
+ argument, created in a commit and authenticated in the settle, which rebuilds its grandparent commit (whose
379
+ scriptSig leads with the value) and binds it to the grandparent txid. The commit's own owner signature does
380
+ NOT cover it. Same six-push lock layout as `MinSimpleBOLT`; recognised by its suffix fingerprint
381
+ `378932c162a2fb2344ae7357664268608a05efa2fc07be60b6dbf35984dcf669`. `unlock()` refuses a value over 75 bytes
382
+ (the lock refuses it too). Node-verified (contract-level broadcast suite) 16/16 on a Bitcoin SV regtest and a
383
+ teranode regtest; the b017 library tests run on the `@bsv/sdk` Spend engine.
384
+ - **Zero-funding spends in `singleSpendUnlock` / `singleAncestorPieces`.** The funding input and the change
385
+ output are detected from the tx (`[token, proof?, funding?]`, `[token, p2pb?, change?]`) instead of assumed
386
+ last, and an unfunded or change-less ancestor commit is passed as empty (OP_0) pieces. `SingleLayout`
387
+ (`MIN_SIMPLE_LAYOUT`, `AUTH_BOLT_LAYOUT`) parameterises the 37-arg and 39-arg unlock layouts.
388
+ - Documented (README, template headers): a minted token received by SPV does not prove the sender holds the
389
+ issuer key - the issuer-signed **commit** spending it (funded or not) must accompany it, and a token carrying
390
+ `authOrMiscData` must travel with its signed commit **and** settle as the package.
391
+ - Tests: `minSimpleZF` (43, the zero-funding matrix + 11 rebuild-mismatch refusals), `minSimpleAttack` (16, the
392
+ first MinSimple red-team suite), `authBolt` (53 incl. a 27-cell path-coverage gate), AuthBolt template and
393
+ scanner (`nftScan`) tests. `npm run build:nft` regenerates both NFT templates from the compiled contract artifacts.
394
+
395
+ ### Security
396
+ - **`SimpleMultiBOLT`: the six red-team fixes now ship in the template.** The published `0.0.0-b2`
397
+ - **`SimpleMultiBOLT`: the six red-team fixes now ship in the template.** The published `0.0.0-b2`
398
+ bytecode carried only the original fabricated-hop anchor; a red-team campaign then found and
399
+ closed six further covenant defects - five node-verified on a regtest teranode in both directions
400
+ (B1, S1, S2, S3, F3); C5 confirmed in simulation and a 4M-signature measurement (its check is a
401
+ basic signature-length bound with no node/simulator divergence) - now compiled in:
402
+ B1 (`balanceCommit` unchecked -> split inflation to 2^127-1), S1 (co-spent proof not bound to the
403
+ bolt -> a token doubles itself), S2 (rebuilt ancestor's issuer never checked -> counterfeit),
404
+ S3 (splitter swaps bolt order -> theft + freeze), F3 (a zero grandparent disabled the anchor ->
405
+ a non-issuer settles from nothing, contained to one hop), C5 (a signature-length window bricked
406
+ ~1 in 52,000 tokens).
407
+
408
+ ### Security
409
+ - **The scanner now EXECUTES scripts.** `verifyEvents` / `verifyEvent` used to be purely structural: a forged commit
410
+ (a stranger's mint, a commit and settle the stranger signed with their own key, which the covenant's issuer guard
411
+ refuses at the commit) passed with `ok: true`. Reproduced, then fixed: every input whose source tx is supplied is run
412
+ on the `@bsv/sdk` Spend engine, and a failure returns `ok: false` with `script execution failed: tx <id> input <n>`.
413
+ This also closes the redteam2 "misreads" C1-C4 (hand-patched second settle, hidden token input, novel txoType,
414
+ inflated balance), which the structure check alone accepted. For mined txs the node already did this; for off-chain
415
+ (SPV / zero-funding) packages nothing had.
416
+
417
+ ### Changed
418
+ - **BREAKING (scanner): every input's source tx must now be supplied.** `verifyEvents` / `verifyEvent` refuse an input
419
+ whose source is missing (`source tx <id> of tx <id> input <n> was not supplied`), including funding inputs and the
420
+ mint's funding parent; previously external funding was waved through. Supply sources by attaching `sourceTransaction`,
421
+ by including the parent in the batch, or by sending BEEF. Results gain `sources: { txid, proven }[]`.
422
+ - **Added: BEEF.** Event txs may be given as Atomic BEEF (BRC-95) over BEEF V2 (BRC-96), hex or bytes; new exports
423
+ `toAtomicBeef`, `fromBeef`, `isBeef`. BEEF V1 (BRC-62) and a non-self-contained BEEF are refused. BUMPs are not
424
+ checked against block headers (use a `ChainTracker`).
425
+ - **BREAKING (scanner): a lone mint is no longer a valid event.** `verifyEvents` / `verifyEvent` now refuse a mint
426
+ that no commit in the same event/batch spends, returning `{ ok: false, unauthenticated: true, reason: "unauthenticated
427
+ mint ..." }` (all token types). A mint only names an `issuerPubKey`; the issuer guard runs when the genesis is first
428
+ spent, so a mint alone proves nothing about who holds the key. This verdict is not a signature failure.
429
+ A mint with its commit + settle (funded or not) is accepted as before. `ScanResult` / `EventResult` gain
430
+ `unauthenticated?: boolean`. Tests: `test/scanner/unauthenticatedMint.test.ts`.
431
+ - **BREAKING for existing tokens: `MinSimpleBOLT` is now the zero-funding contract** (the zero-funding build, lock
432
+ 1265 -> 1275 bytes) in place of `MSBolt.opt3`. Its static bytecode changed, so its fingerprint changed:
433
+ `5dc9c1ddd27e2c91f919531ad82a32c9ce8da772ab87e39af05c2c3361970122` (was
434
+ `2892679d85ef021d754036094ecd77e14f0c3934a23a48e09e7da337e50f823d`). `recognizeType` no longer recognises
435
+ `MinSimpleBOLT` tokens minted with the old bytecode; they must be REISSUED (the covenant travels in each
436
+ token's locking script). The lock layout and the 37-arg unlock layout are unchanged.
437
+ - **BREAKING for existing tokens.** The `SimpleMultiBOLT` static bytecode changed, so its fingerprint
438
+ changed: `368c45fdf92164e4e0869c9062be84621ea8ef040e8591399bf6ff3b8c819b11` (was
439
+ `76cfa45595bfb866010d8f87b9b88d6e27b79a9ab3007119dd00eb0138810c8f`). `recognizeType` no longer
440
+ recognises tokens minted with `0.0.0-b2`/`-b1` bytecode - they classify as untrusted and are
441
+ invisible to `verifyEvents`, wallet balances and scans. The data-push layout (`LAYOUTS`) is
442
+ unchanged, so all TS-side argument construction is identical.
443
+ - **Tokens minted with pre-fix bytecode remain exploitable and must be reissued.** The vulnerable
444
+ covenant travels in each token's own locking script; upgrading this library does not protect coins
445
+ already on chain.
446
+
447
+ ### Removed
448
+ - **BREAKING: dropped the `MinSimpleDiscountBOLT` and `MinSimpleBalanceBOLT` templates.** The
449
+ package now ships three token contracts: `SimpleMultiBOLT` (fungible), `MinSimpleBOLT` (identity
450
+ NFT) and `AuthBOLT` (identity NFT + auth data), plus the `pay2Proof` UTXO template. The `MinSimpleDiscountTemplate` and
451
+ `MinSimpleBalanceTemplate` exports, their `TokenType` union members, their `LAYOUTS`/`REGISTRY`
452
+ entries and their fixtures are gone. `recognizeType` / `verifyEvents` no longer classify those
453
+ types; any consumer importing the removed templates or naming those type strings must update.
454
+ The kept contracts are unchanged (same bytecode, same fingerprints).
455
+ - Coverage for the kept NFT is preserved: `test/lib/minSimpleLifecycle.test.ts` exercises the
456
+ `MinSimpleBOLT` mint/commit/settle and a 2-hop ancestor reconstruction through `verifyTx`,
457
+ standing in for the removed Discount coupon and ancestor-golden tests.
458
+
459
+ ### Fixed
460
+ - **`SimpleMultiBOLT`: the second piece of a split could not be transferred or split again.** A settle
461
+ co-spends its ancestor commit's proof, and a split commit carries two (vout 1 for piece A, vout 2
462
+ for piece B). The builder picked `outputs.length >= 5 ? 2 : 1`, which is always 1 for the 4-output
463
+ split commit, so piece B co-spent piece A's proof and its settle failed. The proof vout is now
464
+ looked up by the owner's pubKeyHash. Builder-only: the covenant and bytecode are unchanged. Piece B
465
+ still has to bring its own funding, because the split settle's change pays piece A.
466
+ - **`verifyTx` rejected correctly signed inputs with an nSequence of 0.** It passed
467
+ `sequence || 0xffffffff` to the Spend engine, turning a signed non-final sequence into final and
468
+ breaking the sighash. It now uses `??`.
469
+
470
+ ### Documentation
471
+ - README: test and coverage figures refreshed (128 tests across 17 files; 99.5% statements,
472
+ 100% functions, 96.3% branches), and the NFT is described as the single `MinSimpleBOLT` identity
473
+ token rather than a template family.
474
+ - Restored the scanner suite (`test/scanner/verifyEvents.test.ts`) that was deleted with the Discount
475
+ and Balance goldens, rebuilt over live `SimpleMultiBOLT` chains.
476
+
477
+ See [`docs/ROADMAP.md`](docs/ROADMAP.md) for planned work.
478
+
479
+ ## [0.0.0-b2] - 2026-09-05
480
+
481
+ ### Security
482
+ - **`SimpleMultiBOLT`: fixed a balance-inflation forgery (the "fabricated hop").** A past
483
+ recipient of a token could clone a settled token's bytes into an output they funded
484
+ themselves, give it any balance they liked, and roll it forward, co-spending the real proof
485
+ they legitimately held from the transfer they had received. Every existing check passed:
486
+ the commit paid only themselves, the settle rebuilt a genuine grandparent commit and
487
+ consumed a real predecessor UTXO that they could sign for. Nothing tied the balance to
488
+ anything. **A regtest teranode running GoBDK consensus accepted the whole chain.**
489
+
490
+ The settle now reads `balance`, `balanceCommit` and `txoType` off the ancestor it has just
491
+ rebuilt, derives the single balance that ancestor authorised (transfer, merge sum, or
492
+ either split piece), and requires the balance of the token being spent to equal it. Both
493
+ sides of that comparison already existed on chain, so **nothing new is stored**: no new
494
+ token field, no new proof field, and no change to the data-push layout.
495
+
496
+ There is no gap between the two halves. The rebuild is assembled from fields the spender
497
+ supplies, so a forger must choose: give the ancestor's real fields and the reconstruction
498
+ hashes correctly but authorises the true balance, not the invented one; or doctor them so
499
+ the balance agrees and the reconstruction stops hashing to `grandparentOutpoint`.
500
+
501
+ Verified on a real node, not only in simulation: the same rig that accepted the forgery now
502
+ rejects the forged settle (`TX_INVALID (31)`), with the honest prefix still accepted and a
503
+ byte-tampered control still rejected, reproduced across two independent runs.
504
+
505
+ ### Changed
506
+ - **BREAKING for existing tokens: `MinSimpleBOLT` is now the zero-funding contract** (the zero-funding build, lock
507
+ 1265 -> 1275 bytes) in place of `MSBolt.opt3`. Its static bytecode changed, so its fingerprint changed:
508
+ `5dc9c1ddd27e2c91f919531ad82a32c9ce8da772ab87e39af05c2c3361970122` (was
509
+ `2892679d85ef021d754036094ecd77e14f0c3934a23a48e09e7da337e50f823d`). `recognizeType` no longer recognises
510
+ `MinSimpleBOLT` tokens minted with the old bytecode; they must be REISSUED (the covenant travels in each
511
+ token's locking script). The lock layout and the 37-arg unlock layout are unchanged.
512
+ - **BREAKING for existing tokens.** The `SimpleMultiBOLT` covenant bytecode changed, so its
513
+ static-code fingerprint changed. `recognizeType` will no longer recognise tokens minted
514
+ with `0.0.0-b1` bytecode; they classify as untrusted. The API is unchanged, and the
515
+ data-push layout is unchanged, so `LAYOUTS` and all TS-side argument construction are
516
+ identical to `0.0.0-b1`.
517
+
518
+ This is a deliberate clean break, and it has a practical consequence worth stating: an old
519
+ token is not merely distrusted, it is **invisible** to anything built on `recognizeType` /
520
+ `verifyEvents`, including wallet balances and scans. There is no legacy recogniser and none
521
+ is planned. If you hold or index `0.0.0-b1` tokens, identify them before upgrading, because
522
+ afterwards this library will not help you find them.
523
+ - **Tokens minted with `0.0.0-b1` bytecode remain inflatable and must be reissued.** Upgrading
524
+ this library does not protect coins already on chain: the vulnerable covenant travels in the
525
+ token's own locking script. Reissue is the only remedy.
526
+
527
+ ### Notes
528
+ - The NFT templates (`MinSimple`, `MinSimpleDiscount`, `MinSimpleBalance`) are **unaffected**,
529
+ and not merely untested: their ancestor rebuild splices in the token's own balance field
530
+ rather than accepting the ancestor's as an argument, so the value already sits inside the
531
+ pre-image of the hash that must equal `grandparentOutpoint`. An invented balance fails the
532
+ hash. They also have no split or merge, so there is no transition to check.
533
+ - `test/repro-fabricated-hop.test.ts` deliberately still asserts that the pre-fix chain
534
+ verifies. It is the record of what a node accepted, and it recognises its fixture against a
535
+ pinned `0.0.0-b1` fingerprint rather than the live registry.
536
+
537
+ ## [0.0.0-b1] — 2026-06-24
538
+
539
+ ### Fixed
540
+ - README title typo: "Bicoin" → "Bitcoin". Docs-only republish (no code changes).
541
+
542
+ ## [0.0.0-b] — 2026-06-23
543
+
544
+ First public beta. The library is functional and fully tested; the API may still change
545
+ before `0.1.0`.
546
+
547
+ ### Added
548
+ - `SimpleMultiBOLT` fungible token class — mint / transfer / split / merge / melt, each
549
+ producing a real, script-valid Bitcoin transaction verified by the `@bsv/sdk` Spend engine.
550
+ - NFT token templates: `MinSimple`, `MinSimpleDiscount`, `MinSimpleBalance`, plus the
551
+ `pay2Proof` UTXO template.
552
+ - Off-chain scanner: `recognizeType` / `REGISTRY` strict fingerprinting, and
553
+ `verifyEvent` / `verifyEvents` for validating BOLT transactional events — one event
554
+ (mint, commit→settle pair, or melt) or a whole batch (issuer-pinned, every commit
555
+ paired with its settle).
556
+ - Pre-compiled `.sx` contracts embedded in the templates — **no sx compiler at runtime**.
557
+ - `@bsv/sdk` as the single peer dependency (no `@elas_co/ts` runtime dependency).
558
+
559
+ ### Packaging
560
+ - Build now cleans `dist/` before `tsc` so the published tarball contains no stale artifacts.
561
+ - Added `repository`, `bugs`, `homepage`, and `keywords` metadata.
562
+
563
+ [Unreleased]: https://github.com/BOLT-Association/b017/compare/v0.2.0...HEAD
564
+ [0.2.0]: https://github.com/BOLT-Association/b017/compare/v0.1.0...v0.2.0
565
+ [0.1.0]: https://github.com/BOLT-Association/b017/compare/v0.0.0-b2...v0.1.0
566
+ [0.0.0-b2]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b2
567
+ [0.0.0-b1]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b1
568
+ [0.0.0-b]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b