b017 0.0.0-b1 → 0.1.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.
Files changed (44) hide show
  1. package/CHANGELOG.md +274 -1
  2. package/README.md +118 -23
  3. package/dist/index.d.ts +15 -7
  4. package/dist/index.js +14 -5
  5. package/dist/lib/boltLib.d.ts +29 -3
  6. package/dist/lib/boltLib.js +60 -12
  7. package/dist/lib/genesis.d.ts +20 -0
  8. package/dist/lib/genesis.js +45 -0
  9. package/dist/lib/multi/multiBoltLib.d.ts +22 -2
  10. package/dist/lib/multi/multiBoltLib.js +111 -117
  11. package/dist/lib/scanner/beef.d.ts +11 -0
  12. package/dist/lib/scanner/beef.js +63 -0
  13. package/dist/lib/scanner/fingerprints.d.ts +12 -2
  14. package/dist/lib/scanner/fingerprints.js +44 -11
  15. package/dist/lib/scanner/verifyEvents.d.ts +84 -6
  16. package/dist/lib/scanner/verifyEvents.js +519 -44
  17. package/dist/lib/single/singleAncestor.d.ts +27 -3
  18. package/dist/lib/single/singleAncestor.js +49 -18
  19. package/dist/lib/single/singleSpend.d.ts +12 -3
  20. package/dist/lib/single/singleSpend.js +48 -16
  21. package/dist/tokens/BOLT.d.ts +6 -5
  22. package/dist/tokens/GenesisMultiBOLT.d.ts +29 -0
  23. package/dist/tokens/GenesisMultiBOLT.js +48 -0
  24. package/dist/tokens/MultiBOLT.d.ts +17 -11
  25. package/dist/tokens/MultiBOLT.js +79 -68
  26. package/dist/tokens/templates/AuthBolt.sx.template.d.ts +35 -0
  27. package/dist/tokens/templates/AuthBolt.sx.template.js +82 -0
  28. package/dist/tokens/templates/FixedMulti.sx.template.d.ts +13 -0
  29. package/dist/tokens/templates/FixedMulti.sx.template.js +23 -0
  30. package/dist/tokens/templates/MinSimple.sx.template.d.ts +10 -1
  31. package/dist/tokens/templates/MinSimple.sx.template.js +15 -1
  32. package/dist/tokens/templates/OpenMulti.sx.template.d.ts +13 -0
  33. package/dist/tokens/templates/OpenMulti.sx.template.js +23 -0
  34. package/dist/tokens/templates/SerialBolt.sx.template.d.ts +23 -0
  35. package/dist/tokens/templates/SerialBolt.sx.template.js +61 -0
  36. package/dist/tokens/templates/SimpleMulti.sx.template.d.ts +11 -5
  37. package/dist/tokens/templates/SimpleMulti.sx.template.js +30 -21
  38. package/dist/tokens/templates/pay2Proof.d.ts +2 -1
  39. package/dist/tokens/templates/pay2Proof.js +1 -1
  40. package/package.json +8 -3
  41. package/dist/tokens/templates/MinSimpleBalance.sx.template.d.ts +0 -24
  42. package/dist/tokens/templates/MinSimpleBalance.sx.template.js +0 -59
  43. package/dist/tokens/templates/MinSimpleDiscount.sx.template.d.ts +0 -23
  44. package/dist/tokens/templates/MinSimpleDiscount.sx.template.js +0 -58
package/CHANGELOG.md CHANGED
@@ -6,8 +6,279 @@ All notable changes to **b017** are documented here. The format is based on
6
6
 
7
7
  ## [Unreleased]
8
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
+
9
222
  See [`docs/ROADMAP.md`](docs/ROADMAP.md) for planned work.
10
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
+
11
282
  ## [0.0.0-b1] — 2026-06-24
12
283
 
13
284
  ### Fixed
@@ -34,6 +305,8 @@ before `0.1.0`.
34
305
  - Build now cleans `dist/` before `tsc` so the published tarball contains no stale artifacts.
35
306
  - Added `repository`, `bugs`, `homepage`, and `keywords` metadata.
36
307
 
37
- [Unreleased]: https://github.com/BOLT-Association/b017
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
38
311
  [0.0.0-b1]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b1
39
312
  [0.0.0-b]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b
package/README.md CHANGED
@@ -1,17 +1,19 @@
1
1
  # b017; Bitcoin Original Layer-1 Token Protocol
2
2
 
3
3
  [![CI](https://github.com/BOLT-Association/b017/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/BOLT-Association/b017/actions/workflows/ci.yml)
4
- [![codecov](https://codecov.io/gh/BOLT-Association/b017/branch/main/graph/badge.svg)](https://codecov.io/gh/BOLT-Association/b017)
4
+ [![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/BOLT-Association/b017/badges/coverage.json)](https://github.com/BOLT-Association/b017/actions/workflows/ci.yml)
5
5
  [![npm version](https://img.shields.io/npm/v/b017.svg?logo=npm)](https://www.npmjs.com/package/b017)
6
6
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
7
7
 
8
- > **Status: `0.0.0-b1` (beta).** Considered Live-Network-Testing Ready (Production next). The API is working and fully tested
9
- > (126/126 unit tests, **99% statement / 98% function / 95% branch coverage**) but may still change before `0.1.0`. See
8
+ > **Status: `0.1.0`.** Considered Live-Network-Testing Ready (Production next). The API is working and fully tested
9
+ > (767/767 unit tests, **100% statement / 100% function / 100% branch coverage**) but may still change before `1.0.0`. See
10
10
  > [`docs/ROADMAP.md`](docs/ROADMAP.md) for what's next.
11
11
 
12
12
  Standalone TypeScript library for the **Bitcoin Original Layer-1 Token** protocol on BSV — a fungible & optimised
13
- **SimpleMultiBOLT** (16-byte balance (x2 Bitcoin's base layer limit); mint / transfer / split / merge / melt), a family of
14
- minimal **NFT** templates, and an off-chain **scanner** that recognises and verifies
13
+ **SimpleMultiBOLT** (16-byte balance (x2 Bitcoin's base layer limit); mint / transfer / split / merge / melt), a minimal
14
+ identity **NFT** (`MinSimpleBOLT`, zero-funding), its credential variant `AuthBOLT` (an arbitrary data field `authOrMiscData` of up to 75 bytes),
15
+ the **genesis family** that stores each token's own asset outpoint (`FixedBOLT`: one genesis per asset; `OpenBOLT`: one
16
+ issuer, many mints; `SerialBOLT`: an NFT serial), and an off-chain **scanner** that recognises and verifies
15
17
  **transactional events**. The only runtime dependency is a peer `@bsv/sdk`.
16
18
 
17
19
  Every protocol action is a **transactional event**: a transfer / split / merge is a **commit → settle
@@ -26,12 +28,18 @@ for the argument and the forgery tests that demonstrate it, and
26
28
  [`docs/formal-proof.md`](docs/formal-proof.md) for the rigorous treatment (4 theorems, 7 lemmas,
27
29
  full attack-vector analysis).
28
30
 
31
+ This is **third-party per-token unforgeability**: each unit is internally well-formed and traces
32
+ to an issuer-signed mint. It is *not* a claim about **supply-honesty** (an issuer can mint many
33
+ independent genesis tokens — reserve/cap trust is an issuer matter) or **network-level security**
34
+ (reorg resistance inherits honest-majority hash power). See [`formal-proof.md`](docs/formal-proof.md)
35
+ §1.6 for the exact boundary.
36
+
29
37
  ## Install / build
30
38
 
31
39
  ```
32
40
  npm install
33
41
  npm run build # clean + tsc -> dist/ (JS + .d.ts)
34
- npm test # vitest (126 tests)
42
+ npm test # vitest (767 tests)
35
43
  npm run test:coverage # vitest + v8 coverage -> coverage/ (text + HTML report)
36
44
  ```
37
45
 
@@ -71,11 +79,15 @@ library never touches the network. The signed `Transaction` is available as `tok
71
79
  ```ts
72
80
  import {
73
81
  recognizeType, // (lockingScript, expected?) -> TokenType | null
74
- verifyEvent, // validate ONE event (a mint, a commit→settle pair, or a melt)
75
- verifyEvents, // validate a BATCH of events end to end
82
+ recognizeToken, // (lockingScript, expected?) -> { type, phase? } | null
83
+ verifyEvent, // validate ONE event (a commit→settle pair, or a melt) - same verdict as verifyEvents
84
+ verifyEvents, // validate a BATCH of events end to end (offline)
85
+ verifyAndBroadcast, // verifyEvents + your broadcast of the batch's anchor (settle N-1 / the mint)
76
86
  } from "b017";
77
87
 
78
88
  const type = recognizeType(tx.outputs[0].lockingScript); // "SimpleMultiBOLT" | "MinSimpleBOLT" | ... | null
89
+ // genesis family: also the phase - "mint" (null asset outpoint, any mintData) or "postMint" (empty mintData)
90
+ const { type: t, phase } = recognizeToken(tx.outputs[0].lockingScript) ?? {};
79
91
 
80
92
  // Inspect a batch of transactional events for authenticity. Recognises the type, pins the issuer
81
93
  // across the whole batch, fingerprints every interface, then pairs the events: every commit must
@@ -86,8 +98,23 @@ const r = verifyEvents(txs, { trustedIssuerPubKey });
86
98
 
87
99
  Recognition is strict: a script matches only if **both** the leading data-push layout **and**
88
100
  the sha256 of the static contract code match a registered type, so a tampered contract body or
89
- a non-token script is rejected. An event is well-formed only if its txs pair up — a lone mint or
90
- melt is a valid single-tx event, but an orphan settle or an unsettled commit is rejected.
101
+ a non-token script is rejected. An event is well-formed only if its txs pair up - a melt is a
102
+ valid single-tx event (standing on the settle it spends, its anchor), but an orphan settle or an unsettled commit is
103
+ rejected, by `verifyEvent` as well as `verifyEvents`. A **mint** is accepted only
104
+ with a commit in the same event/batch that spends it; a lone mint returns `{ ok: false, unauthenticated: true }`
105
+ (see "Receiving a token off-chain" below). The scanner also **executes** every input whose source tx is supplied (the
106
+ covenant and the signatures, on the `@bsv/sdk` Spend engine), because structure alone cannot tell a forged commit
107
+ from a real one and off-chain txs have not been validated by a node; a failure returns `ok: false` with
108
+ `script execution failed: tx <id> input <n>: ...`. **Every input's source tx must be supplied** (attached as
109
+ `sourceTransaction`, or another tx in the batch, or inside a BEEF); an input whose source is missing is refused
110
+ (`source tx <id> of tx <id> input <n> was not supplied`). Send the package as **BEEF**: each event tx may be a
111
+ Transaction, raw hex, or Atomic BEEF over BEEF V2 (hex / bytes), whose subject is the tx; `toAtomicBeef(tx)` /
112
+ `fromBeef(bytes)` / `isBeef(x)` are exported. BEEF V1 (BRC-62) and a BEEF that is not self-contained (an unproven tx
113
+ that does not have all its inputs in the BEEF) are refused. The result's `sources` lists the txs the event spends that
114
+ are not part of it, each with `proven` (it carries a BUMP). The scanner checks a BUMP against a block header only
115
+ for an **anchor**, and only when you supply your headers (`isKnownBlockRoot`, or a `chainTracker` to
116
+ `verifyAndBroadcast`). The BUMPs of the other `sources` are **not** checked: verify those with your `ChainTracker`
117
+ (`Beef.verify` / `merklePath.verify`).
91
118
 
92
119
  A commit and its settle are bound **two** independent ways: the **token lineage** (the settle's
93
120
  token `parentOutpoint` references the commit's token output — the binding the scanner asserts), and,
@@ -95,6 +122,54 @@ in general, a **funding chain** (the settle's funding input spends the commit's
95
122
  the pair is chained at the satoshi level too). The funding chain is a construction property — a
96
123
  caller can fund the settle from elsewhere — so the scanner does not require it.
97
124
 
125
+ ### Receiving a token off-chain (SPV): what must travel with it
126
+
127
+ Sending someone a **minted** token over SPV does not prove that the sender holds the issuer key. A mint is
128
+ just an output whose lock names an `issuerPubKey`; anyone can create one naming anybody's key (so
129
+ `verifyEvents` refuses a lone mint as `unauthenticated`). The issuer guard runs when the
130
+ genesis token is first **spent**, so the proof is the first **commit**:
131
+
132
+ - **Ownership of a minted token:** the mint must come with a **commit tx spending it**, signed by the issuer
133
+ key. This holds whether or not the commit is funded (an unfunded commit is SPV-only and never mined, but it
134
+ still executes the covenant, which demands `issuerPubKey == the signer` at genesis). `verifyEvents` runs that
135
+ covenant, so a commit forged by a stranger is refused on execution.
136
+ - **A token carrying `authOrMiscData` (`AuthBOLT`):** the value is created in a commit but authenticated only
137
+ by the **settle**, which rebuilds its grandparent commit and binds the value to that commit's txid. The commit's
138
+ own signature does **not** cover it. So the **signed commit and settle travel together as the data package**;
139
+ a commit alone, or a settle without its commit, does not authenticate the data.
140
+ - A later hop to a new holder repeats the pattern: commit + settle (and the p2pb proof input a back-reaching
141
+ settle spends), unfunded or funded, are what the recipient verifies.
142
+ - **The anchor travels too, and is broadcast.** The anchor is the token tx the package stands on: the settle before
143
+ its first commit (settle N-1), or the mint at genesis. So a package is `[mint, c1, s1]` or `[sN-1, cN, sN]`.
144
+ `verifyEvents` validates the anchor like an event tx (fingerprint, issuer, structure, script execution) and names
145
+ it in `anchors`, but it is offline and its execution reaches the anchor's own inputs only. Use
146
+ `verifyAndBroadcast(txs, broadcastAnchor)`: it runs `verifyEvents`, then your broadcaster sends each anchor and
147
+ reports `accepted`, `already-seen` or `rejected`. The anchor must be a tx the network has seen and will therefore
148
+ mine (or has already mined): that is what shows the history behind it is real. A rejected anchor, a throwing
149
+ broadcaster or an unknown status is `ok: false`. The events standing on the anchor need not be broadcast: they can
150
+ stay off chain, and be funded and broadcast only when the receiver, the sender or both require it.
151
+ - **An unfunded anchor needs an SPV proof.** An anchor with no funding input pays no fee, so the network has no
152
+ reason to mine it and seeing it proves nothing. Such an anchor can still be mined (a friendly miner), so it is
153
+ accepted only once it has been: it must carry a merkle path into a block header you know. Pass your headers as
154
+ `isKnownBlockRoot: (merkleRoot, height) => boolean`, or hand `verifyAndBroadcast` a `chainTracker` (the
155
+ `@bsv/sdk` ChainTracker shape). Without a verified proof the batch is refused (`unfunded anchor <id>: ...`), by
156
+ `verifyEvents`, `verifyEvent` and `verifyAndBroadcast` alike, and nothing is broadcast. Unfunded **events** on a
157
+ funded anchor are unaffected.
158
+ - **A header-proven anchor is taken as mined.** Any anchor (funded or not) whose merkle path proves it into a header
159
+ you know was validated by consensus: the scanner does not re-execute its inputs and does not need its sources. That
160
+ is what lets a mined anchor travel as BEEF, which stops at proven txs. Your header lookup is the trust root here:
161
+ answer `true` only for real block headers. A merkle path with no known header changes nothing (the anchor is
162
+ executed like any other, and its sources must be supplied). Only anchors get this; event txs are always executed.
163
+ - **Value conservation is checked.** An **anchor** whose outputs exceed its inputs is refused (`anchor <id> creates
164
+ value ...`): no node accepts that. An **event** tx that does so is not refused, only reported in
165
+ `offChainOnly: [{ txid, inputSats, outputSats }]`: a commit / settle that is never broadcast (an `AuthBOLT` event
166
+ certifying auth data) is valid off chain, it just cannot be broadcast as built. Pass `requireBroadcastable: true`
167
+ to refuse such a batch instead.
168
+ - **`SimpleMultiBOLT` requires funding and change.** Zero-funding hops are for the NFT types (`MinSimpleBOLT`,
169
+ `AuthBOLT`) only; a MultiBOLT settle never has to rebuild an unfunded commit.
170
+ - **Send it as BEEF** (Atomic BEEF over BEEF V2, `toAtomicBeef(tx)`): each tx travels with the txs it spends, back to
171
+ txs a block has proven (BUMP). The recipient needs every source to execute the scripts, so a bare tx is refused.
172
+
98
173
  ## What's inside
99
174
 
100
175
  The tree is organised by role: `tokens/` (token classes + their contract templates), `lib/` (the
@@ -104,15 +179,21 @@ sub-libraries).
104
179
  | Path | Role |
105
180
  | --- | --- |
106
181
  | `src/tokens/MultiBOLT.ts` | `SimpleMultiBOLT` — the fungible token class (mint/transfer/split/merge/melt). |
182
+ | `src/tokens/GenesisMultiBOLT.ts` | `FixedBOLT` (one genesis per asset) and `OpenBOLT` (many mints, re-rooted merges): the fungible genesis family, every `SimpleMultiBOLT` operation plus `mintData` and the merge rules. |
107
183
  | `src/tokens/BOLT.ts` | `BOLT` — the abstract token base class. |
108
184
  | `src/tokens/templates/SimpleMulti.sx.template.ts` | Runtime lock/unlock/melt assembler for the fungible contract (compiled ASM suffix embedded). |
109
- | `src/tokens/templates/MinSimple*.sx.template.ts` | Single-token (NFT) lock templates: `MinSimple`, `MinSimpleDiscount`, `MinSimpleBalance`. |
185
+ | `src/tokens/templates/MinSimple.sx.template.ts` | Single-token (NFT) lock / unlock / melt template: `MinSimpleBOLT` (identity; a commit or settle may carry no funding input and change is optional, so p2p / SPV hops never need to be mined). |
186
+ | `src/tokens/templates/AuthBolt.sx.template.ts` | `AuthBOLT`: carries an arbitrary data field `authOrMiscData` (<= 75 B, a direct push) created in a commit and authenticated by the next settle. Same lock layout as `MinSimpleBOLT`; told apart by its suffix fingerprint. Lock / unlock / melt. |
187
+ | `src/tokens/templates/FixedMulti.sx.template.ts`, `OpenMulti.sx.template.ts` | The genesis-family fungible templates: SimpleMulti's layout behind two leading pushes (the asset outpoint, `mintData`). |
188
+ | `src/tokens/templates/SerialBolt.sx.template.ts` | `SerialBOLT`: the NFT carrying its own mint outpoint and `mintData`; zero-funding. Lock / unlock / melt. |
189
+ | `src/lib/genesis.ts` | The two leading pushes of the genesis family (`genesisFieldFor`, `mintDataFor`). |
110
190
  | `src/tokens/templates/pay2Proof.ts` | The `pay2Proof` UTXO template (the b017 marker proof output). |
111
191
  | `src/lib/boltLib.ts` | Layout-agnostic primitives (`verifyTx`, `buildOutpoint`, `splitCtx`, …) shared by both streams. |
112
192
  | `src/lib/single/` | Single-token (NFT) engine: `singleSpend` (unlock assembler) + `singleAncestor` (back-reach reconstruction). |
113
- | `src/lib/multi/multiBoltLib.ts` | Fungible-token engine: ancestor reconstruction for `SimpleMultiBOLT`. |
114
- | `src/lib/scanner/fingerprints.ts` | Per-type recognition (`recognizeType`, golden `recognizeP2P`) + the type `REGISTRY`. |
115
- | `src/lib/scanner/verifyEvents.ts` | Off-chain event validator: batch verifier + per-event checker (`verifyEvents`, `verifyEvent`). |
193
+ | `src/lib/multi/multiBoltLib.ts` | Fungible-token engine: ancestor reconstruction per `MultiLayout` (`SimpleMultiBOLT`, `FixedBOLT`, `OpenBOLT`). |
194
+ | `src/lib/scanner/fingerprints.ts` | Per-type recognition (`recognizeType`, `recognizeToken` with the genesis-family phase, golden `recognizeP2P`) + the type `REGISTRY`. |
195
+ | `src/lib/scanner/verifyEvents.ts` | Off-chain event validator: batch verifier, per-event checker, and the anchor broadcast wrapper (`verifyEvents`, `verifyEvent`, `verifyAndBroadcast`). |
196
+ | `src/lib/scanner/beef.ts` | The off-chain data package: Atomic BEEF over BEEF V2 (`toAtomicBeef`, `fromBeef`, `isBeef`). |
116
197
 
117
198
  > Naming note: the `SimpleMultiBOLT` **class** currently lives in `tokens/MultiBOLT.ts`.
118
199
  > Resolving that file/class name mismatch is tracked in the ROADMAP.
@@ -122,25 +203,28 @@ The full public API is the named exports of [`src/index.ts`](src/index.ts).
122
203
  ## Testing & coverage
123
204
 
124
205
  The whole codebase is unit-tested with [Vitest](https://vitest.dev). The `test/` tree mirrors `src/`
125
- by concern (`test/tokens`, `test/templates`, `test/lib`, `test/lib`-level `scanner/`), with shared
206
+ by concern (`test/tokens`, `test/templates`, `test/lib`, `test/scanner`), with shared
126
207
  fixtures in `test/fixtures` and helpers in `test/helpers`.
127
208
 
128
209
  ```
129
- npm test # 126 tests across 18 files
210
+ npm test # 767 tests across 41 files
130
211
  npm run test:coverage # the same suite + a v8 coverage report (text to stdout, HTML in coverage/)
131
212
  ```
132
213
 
133
- Latest run — **every source module is covered**, all above 98% statements:
214
+ Latest run — **every source module is fully covered**: 100% on every metric, enforced by the coverage thresholds. The
215
+ 21 `v8 ignore` markers sit only on defensive TypeScript guards, each stating why it cannot fire:
134
216
 
135
217
  | Metric | Coverage |
136
218
  | --- | --- |
137
- | Statements | **99.1%** (1737/1752) |
138
- | Functions | **98.0%** (96/98) |
139
- | Lines | **99.1%** |
140
- | Branches | **95.1%** (645/678) |
219
+ | Statements | **100.0%** (2305/2305) |
220
+ | Functions | **100.0%** (168/168) |
221
+ | Lines | **100.0%** |
222
+ | Branches | **100.0%** (1153/1153) |
141
223
 
142
- The handful of uncovered branches are fail-safe guards (e.g. a `0xff` >4 GB script-length prefix, or a
143
- type/issuer check an upstream fingerprint already guarantees), annotated `v8 ignore` with the reason inline.
224
+ Fail-safe guards that cannot fire (e.g. a `0xff` >4 GB script-length prefix, or a type/issuer check an
225
+ upstream fingerprint already guarantees) are annotated `v8 ignore` with the reason inline; so are the checks
226
+ behind `@bsv/sdk`'s `Spend.validate()` (it throws rather than returning `false`) and the guards a missing
227
+ unlocking script can never reach (`tx.id()` fails first). Every other branch has a test.
144
228
 
145
229
  What the suite verifies: each contract template is byte-faithful to its sx-compiled artifact and
146
230
  spends under the `@bsv/sdk` Spend engine; the scanner's accept/reject decisions match the on-chain
@@ -193,6 +277,17 @@ needs cheap unbounded settlement, trustless verifiable integrity, and programmab
193
277
  *simultaneously* — and this is the only stack where all three reinforce each other instead of
194
278
  trading off. That is what makes it not just *a* stablecoin platform, but the killer one.
195
279
 
280
+ **What is proven vs. assumed.** To be precise about the integrity layer: what the BOLT covenant
281
+ *proves* (see [`docs/formal-proof.md`](docs/formal-proof.md)) is **third-party per-token
282
+ unforgeability** — authenticity, ownership, per-genesis balance conservation, and state-machine
283
+ integrity — plus local, SPV-friendly verification of all of the above. Two things this layer does
284
+ *not* prove, and that a stablecoin still depends on, are **trust assumptions, not theorems**:
285
+ **issuer supply-honesty** (the protocol stops anyone from forging *a* token, but an issuer can
286
+ mint as many genesis tokens as it likes — matching the float to a reserve is an issuer/governance
287
+ matter) and **honest-majority settlement** (final settlement is only as immutable as the chain's
288
+ hash power). The stack is designed so those two assumptions are the *only* ones left standing —
289
+ but they are assumptions, and §1.6 of the proof says exactly where the proven part ends.
290
+
196
291
  ## License
197
292
 
198
293
  Open BSV License Version 5 — see [`LICENSE.txt`](LICENSE.txt).
package/dist/index.d.ts CHANGED
@@ -1,13 +1,21 @@
1
1
  export { SimpleMultiBOLT } from "./tokens/MultiBOLT.js";
2
2
  export type { VerifierType } from "./tokens/MultiBOLT.js";
3
3
  export { default as SimpleMultiTemplate } from "./tokens/templates/SimpleMulti.sx.template.js";
4
+ export { FixedBOLT, OpenBOLT } from "./tokens/GenesisMultiBOLT.js";
5
+ export { default as FixedMultiTemplate } from "./tokens/templates/FixedMulti.sx.template.js";
6
+ export { default as OpenMultiTemplate } from "./tokens/templates/OpenMulti.sx.template.js";
7
+ export { default as SerialBoltTemplate } from "./tokens/templates/SerialBolt.sx.template.js";
8
+ export { genesisFieldFor, mintDataFor, outpointOf, MINT_DATA_MAX_BYTES } from "./lib/genesis.js";
9
+ export { SIMPLE_MULTI_LAYOUT, FIXED_BOLT_LAYOUT, OPEN_BOLT_LAYOUT } from "./lib/multi/multiBoltLib.js";
10
+ export type { MultiLayout } from "./lib/multi/multiBoltLib.js";
4
11
  export { BOLT } from "./tokens/BOLT.js";
5
- export { verifyTx, buildOutpoint } from "./lib/boltLib.js";
12
+ export { verifyTx, buildOutpoint, p2pkhUnlock, toSigner } from "./lib/boltLib.js";
13
+ export type { Signer, Recipient } from "./lib/boltLib.js";
6
14
  export { default as MinSimpleTemplate } from "./tokens/templates/MinSimple.sx.template.js";
7
- export { default as MinSimpleDiscountTemplate } from "./tokens/templates/MinSimpleDiscount.sx.template.js";
8
- export { default as MinSimpleBalanceTemplate } from "./tokens/templates/MinSimpleBalance.sx.template.js";
15
+ export { default as AuthBoltTemplate, AUTH_DATA_MAX_BYTES } from "./tokens/templates/AuthBolt.sx.template.js";
9
16
  export { default as Pay2ProofTemplate } from "./tokens/templates/pay2Proof.js";
10
- export { REGISTRY, recognizeType, recognizeP2P, issuerPubKeyOf, sha256Hex } from "./lib/scanner/fingerprints.js";
11
- export type { TokenType, TypeSpec } from "./lib/scanner/fingerprints.js";
12
- export { verifyEvents, verifyEvent } from "./lib/scanner/verifyEvents.js";
13
- export type { ScanResult, ScanOpts, EventResult, EventKind } from "./lib/scanner/verifyEvents.js";
17
+ export { REGISTRY, recognizeType, recognizeToken, recognizeP2P, issuerPubKeyOf, sha256Hex } from "./lib/scanner/fingerprints.js";
18
+ export type { TokenType, TypeSpec, TokenPhase } from "./lib/scanner/fingerprints.js";
19
+ export { verifyEvents, verifyEvent, verifyAndBroadcast } from "./lib/scanner/verifyEvents.js";
20
+ export type { ScanResult, ScanOpts, EventResult, EventKind, SourceTx, TxInput, AnchorRef, AnchorStatus, AnchorBroadcastResult, AnchorBroadcaster, HeaderSource, OffChainOnlyTx, } from "./lib/scanner/verifyEvents.js";
21
+ export { toAtomicBeef, fromBeef, isBeef } from "./lib/scanner/beef.js";
package/dist/index.js CHANGED
@@ -2,14 +2,23 @@
2
2
  // Pre-compiled contract (no sx compiler at runtime); only @bsv/sdk.
3
3
  export { SimpleMultiBOLT } from "./tokens/MultiBOLT.js";
4
4
  export { default as SimpleMultiTemplate } from "./tokens/templates/SimpleMulti.sx.template.js";
5
+ // The genesis family: FixedBOLT (one genesis per asset), OpenBOLT (many mints, re-rooted merges), SerialBOLT (NFT serial).
6
+ export { FixedBOLT, OpenBOLT } from "./tokens/GenesisMultiBOLT.js";
7
+ export { default as FixedMultiTemplate } from "./tokens/templates/FixedMulti.sx.template.js";
8
+ export { default as OpenMultiTemplate } from "./tokens/templates/OpenMulti.sx.template.js";
9
+ export { default as SerialBoltTemplate } from "./tokens/templates/SerialBolt.sx.template.js";
10
+ export { genesisFieldFor, mintDataFor, outpointOf, MINT_DATA_MAX_BYTES } from "./lib/genesis.js";
11
+ export { SIMPLE_MULTI_LAYOUT, FIXED_BOLT_LAYOUT, OPEN_BOLT_LAYOUT } from "./lib/multi/multiBoltLib.js";
5
12
  export { BOLT } from "./tokens/BOLT.js";
6
- export { verifyTx, buildOutpoint } from "./lib/boltLib.js";
13
+ export { verifyTx, buildOutpoint, p2pkhUnlock, toSigner } from "./lib/boltLib.js";
7
14
  // Token LOCK templates (mint/build the contract output for each type).
8
15
  export { default as MinSimpleTemplate } from "./tokens/templates/MinSimple.sx.template.js";
9
- export { default as MinSimpleDiscountTemplate } from "./tokens/templates/MinSimpleDiscount.sx.template.js";
10
- export { default as MinSimpleBalanceTemplate } from "./tokens/templates/MinSimpleBalance.sx.template.js";
16
+ export { default as AuthBoltTemplate, AUTH_DATA_MAX_BYTES } from "./tokens/templates/AuthBolt.sx.template.js";
11
17
  export { default as Pay2ProofTemplate } from "./tokens/templates/pay2Proof.js";
12
18
  // Token recognition — the scanner's fingerprint primitive.
13
- export { REGISTRY, recognizeType, recognizeP2P, issuerPubKeyOf, sha256Hex } from "./lib/scanner/fingerprints.js";
19
+ export { REGISTRY, recognizeType, recognizeToken, recognizeP2P, issuerPubKeyOf, sha256Hex } from "./lib/scanner/fingerprints.js";
14
20
  // The shared off-chain BOLT event validator (the scanner): a batch verifier + the per-event checker.
15
- export { verifyEvents, verifyEvent } from "./lib/scanner/verifyEvents.js";
21
+ // verifyAndBroadcast = verifyEvents + the caller's broadcast of the batch's ANCHOR (settle N-1 / the mint).
22
+ export { verifyEvents, verifyEvent, verifyAndBroadcast } from "./lib/scanner/verifyEvents.js";
23
+ // The off-chain data package: Atomic BEEF (BRC-95) over BEEF V2 (BRC-96); V1 is refused.
24
+ export { toAtomicBeef, fromBeef, isBeef } from "./lib/scanner/beef.js";