b017 0.0.0-b → 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.
- package/CHANGELOG.md +280 -1
- package/README.md +120 -25
- package/dist/index.d.ts +15 -7
- package/dist/index.js +14 -5
- package/dist/lib/boltLib.d.ts +29 -3
- package/dist/lib/boltLib.js +60 -12
- package/dist/lib/genesis.d.ts +20 -0
- package/dist/lib/genesis.js +45 -0
- package/dist/lib/multi/multiBoltLib.d.ts +22 -2
- package/dist/lib/multi/multiBoltLib.js +111 -117
- package/dist/lib/scanner/beef.d.ts +11 -0
- package/dist/lib/scanner/beef.js +63 -0
- package/dist/lib/scanner/fingerprints.d.ts +12 -2
- package/dist/lib/scanner/fingerprints.js +44 -11
- package/dist/lib/scanner/verifyEvents.d.ts +84 -6
- package/dist/lib/scanner/verifyEvents.js +519 -44
- package/dist/lib/single/singleAncestor.d.ts +27 -3
- package/dist/lib/single/singleAncestor.js +49 -18
- package/dist/lib/single/singleSpend.d.ts +12 -3
- package/dist/lib/single/singleSpend.js +48 -16
- package/dist/tokens/BOLT.d.ts +6 -5
- package/dist/tokens/GenesisMultiBOLT.d.ts +29 -0
- package/dist/tokens/GenesisMultiBOLT.js +48 -0
- package/dist/tokens/MultiBOLT.d.ts +17 -11
- package/dist/tokens/MultiBOLT.js +79 -68
- package/dist/tokens/templates/AuthBolt.sx.template.d.ts +35 -0
- package/dist/tokens/templates/AuthBolt.sx.template.js +82 -0
- package/dist/tokens/templates/FixedMulti.sx.template.d.ts +13 -0
- package/dist/tokens/templates/FixedMulti.sx.template.js +23 -0
- package/dist/tokens/templates/MinSimple.sx.template.d.ts +10 -1
- package/dist/tokens/templates/MinSimple.sx.template.js +15 -1
- package/dist/tokens/templates/OpenMulti.sx.template.d.ts +13 -0
- package/dist/tokens/templates/OpenMulti.sx.template.js +23 -0
- package/dist/tokens/templates/SerialBolt.sx.template.d.ts +23 -0
- package/dist/tokens/templates/SerialBolt.sx.template.js +61 -0
- package/dist/tokens/templates/SimpleMulti.sx.template.d.ts +11 -5
- package/dist/tokens/templates/SimpleMulti.sx.template.js +30 -21
- package/dist/tokens/templates/pay2Proof.d.ts +2 -1
- package/dist/tokens/templates/pay2Proof.js +1 -1
- package/package.json +8 -3
- package/dist/tokens/templates/MinSimpleBalance.sx.template.d.ts +0 -24
- package/dist/tokens/templates/MinSimpleBalance.sx.template.js +0 -59
- package/dist/tokens/templates/MinSimpleDiscount.sx.template.d.ts +0 -23
- package/dist/tokens/templates/MinSimpleDiscount.sx.template.js +0 -58
package/CHANGELOG.md
CHANGED
|
@@ -6,8 +6,284 @@ 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
|
+
|
|
282
|
+
## [0.0.0-b1] — 2026-06-24
|
|
283
|
+
|
|
284
|
+
### Fixed
|
|
285
|
+
- README title typo: "Bicoin" → "Bitcoin". Docs-only republish (no code changes).
|
|
286
|
+
|
|
11
287
|
## [0.0.0-b] — 2026-06-23
|
|
12
288
|
|
|
13
289
|
First public beta. The library is functional and fully tested; the API may still change
|
|
@@ -29,5 +305,8 @@ before `0.1.0`.
|
|
|
29
305
|
- Build now cleans `dist/` before `tsc` so the published tarball contains no stale artifacts.
|
|
30
306
|
- Added `repository`, `bugs`, `homepage`, and `keywords` metadata.
|
|
31
307
|
|
|
32
|
-
[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
|
|
311
|
+
[0.0.0-b1]: https://github.com/BOLT-Association/b017/releases/tag/v0.0.0-b1
|
|
33
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
|
-
# b017;
|
|
1
|
+
# b017; Bitcoin Original Layer-1 Token Protocol
|
|
2
2
|
|
|
3
3
|
[](https://github.com/BOLT-Association/b017/actions/workflows/ci.yml)
|
|
4
|
-
[](https://github.com/BOLT-Association/b017/actions/workflows/ci.yml)
|
|
5
5
|
[](https://www.npmjs.com/package/b017)
|
|
6
6
|
[](https://www.typescriptlang.org/)
|
|
7
7
|
|
|
8
|
-
> **Status: `0.
|
|
9
|
-
> (
|
|
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
|
-
Standalone TypeScript library for the **
|
|
13
|
-
**SimpleMultiBOLT** (16-byte balance (x2 Bitcoin's base layer limit); mint / transfer / split / merge / melt), a
|
|
14
|
-
|
|
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 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 (
|
|
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
|
-
|
|
75
|
-
|
|
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
|
|
90
|
-
|
|
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
|
|
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
|
|
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
|
|
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/
|
|
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 #
|
|
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
|
|
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 | **
|
|
138
|
-
| Functions | **
|
|
139
|
-
| Lines | **
|
|
140
|
-
| Branches | **
|
|
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
|
-
|
|
143
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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";
|