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 +568 -312
- package/LICENSE.txt +56 -56
- package/README.md +310 -301
- package/dist/lib/multi/multiBoltLib.d.ts +2 -2
- package/dist/lib/multi/multiBoltLib.js +22 -31
- package/dist/lib/scanner/fingerprints.js +3 -3
- package/dist/lib/scanner/verifyEvents.js +3 -3
- package/dist/tokens/GenesisMultiBOLT.js +1 -1
- package/dist/tokens/MultiBOLT.d.ts +0 -1
- package/dist/tokens/MultiBOLT.js +8 -11
- package/dist/tokens/templates/FixedMulti.sx.template.js +3 -3
- package/dist/tokens/templates/OpenMulti.sx.template.js +3 -3
- package/dist/tokens/templates/SimpleMulti.sx.template.d.ts +1 -1
- package/dist/tokens/templates/SimpleMulti.sx.template.js +9 -10
- package/package.json +64 -63
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
- **`
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
`
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
- **
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
- **
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
- **
|
|
107
|
-
|
|
108
|
-
`
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
-
|
|
117
|
-
`
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
`
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
`
|
|
179
|
-
|
|
180
|
-
`
|
|
181
|
-
token
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
`
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
the
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
`
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
- `
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
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
|