@smartledger/bsv 8.3.0 → 8.3.1
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 +42 -0
- package/README.md +349 -207
- package/bsv-gdaf.min.js +1 -1
- package/bsv-smartcontract.min.js +1 -1
- package/bsv.bundle.js +2 -2
- package/bsv.min.js +2 -2
- package/docs/BRC220_BATCH_LEAF_AMENDMENT.md +119 -0
- package/docs/BRC220_PLAN.md +9 -0
- package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
- package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
- package/docs/getting-started/INSTALLATION.md +23 -23
- package/docs/getting-started/QUICK_START.md +7 -7
- package/docs/migration/FROM_BSV_1_5_6.md +5 -5
- package/lib/notaryhash/index.js +20 -0
- package/lib/notaryhash/merkle.js +8 -0
- package/lib/notaryhash/suites.js +17 -1
- package/package.json +3 -2
- package/test/notaryhash/batch_leaf.js +140 -0
- package/test/notaryhash/interop.js +112 -0
- package/test/notaryhash/verify.js +5 -2
- package/version.js +1 -1
package/README.md
CHANGED
|
@@ -2,37 +2,44 @@
|
|
|
2
2
|
|
|
3
3
|
**🚀 Complete Bitcoin SV Development Framework with W3C Verifiable Credentials, DID:web, Legal Compliance, and 16 Flexible Loading Options**
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/@smartledger/bsv)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
[](https://bitcoinsv.com/)
|
|
8
8
|
[](#-16-loading-options---choose-your-approach)
|
|
9
9
|
[](#-legally-recognizable-credentials-v34x)
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
>
|
|
22
|
-
>
|
|
23
|
-
>
|
|
11
|
+
A comprehensive Bitcoin SV library whose **defaults describe BSV as the network
|
|
12
|
+
actually runs it**. Since 8.0.0 the script interpreter is measured against the
|
|
13
|
+
reference node's own consensus vectors — 1483/1483, with zero false accepts —
|
|
14
|
+
rather than against the Bitcoin Core vectors inherited from the upstream fork.
|
|
15
|
+
All secp256k1 cryptography runs on the audited, constant-time
|
|
16
|
+
[`@noble`](https://github.com/paulmillr/noble-curves) suite with `elliptic`
|
|
17
|
+
removed, on top of the interpreter-verified covenant stack (OP_PUSH_TX, PELS,
|
|
18
|
+
ownership tokens), a legally-recognizable DID:web + VC-JWT toolkit, and 16
|
|
19
|
+
distribution methods.
|
|
20
|
+
|
|
21
|
+
> **8.3.0 (latest)**: BRC-220 **NotaryHash** — privacy-preserving signed-hash
|
|
22
|
+
> notarization with SPV-verifiable certificates, including RFC 6962 Merkle trees
|
|
23
|
+
> for batch mode. See [NotaryHash](#-notaryhash-brc-220) and the
|
|
24
|
+
> [CHANGELOG](./CHANGELOG.md).
|
|
25
|
+
>
|
|
26
|
+
> **8.0.0 was a breaking release.** `verify()` with no flags now means BSV
|
|
27
|
+
> mainnet rather than "no rules", and two flag constants changed value. Read
|
|
28
|
+
> [Upgrading to v8.0.0](#upgrading-to-v800-breaking-changes) before moving from
|
|
29
|
+
> 7.x or earlier.
|
|
24
30
|
|
|
25
31
|
## **Interpreter-Verified Covenants**
|
|
26
32
|
|
|
27
|
-
The full covenant stack
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
and negative (must-reject) test.
|
|
33
|
+
The full covenant stack lives at `bsv.SmartContract` and verifies end-to-end
|
|
34
|
+
through `Script.Interpreter`. Every locking script has both a positive
|
|
35
|
+
(must-accept) and negative (must-reject) test.
|
|
31
36
|
|
|
32
37
|
```javascript
|
|
33
38
|
const bsv = require('@smartledger/bsv')
|
|
34
39
|
const SC = bsv.SmartContract
|
|
35
|
-
SC.enableGenesis()
|
|
40
|
+
SC.enableGenesis() // OP_PUSH_TX needs the lifted element cap — but note this is
|
|
41
|
+
// process-wide and weakens pre-Genesis validation. See
|
|
42
|
+
// "Consensus defaults" below before calling it in an app.
|
|
36
43
|
|
|
37
44
|
// Self-replicating covenant — every spend recreates the same script (value − fee).
|
|
38
45
|
const lock = SC.perpetualCovenant(500)
|
|
@@ -44,8 +51,9 @@ const token = SC.ownershipToken(500, ownerHash) // ownerHash = SC.Token.ownerId(
|
|
|
44
51
|
// Value covenant — forces spend outputs to match a specific hashOutputs.
|
|
45
52
|
const vlock = SC.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs))
|
|
46
53
|
|
|
47
|
-
// Verify any locking script end-to-end through Script.Interpreter
|
|
48
|
-
|
|
54
|
+
// Verify any locking script end-to-end through Script.Interpreter.
|
|
55
|
+
// Returns { ok, err } — `err` names the interpreter error when ok is false.
|
|
56
|
+
const { ok, err } = SC.verifyScript(unlockScript, lockingScript, { tx, inputIndex, satoshis })
|
|
49
57
|
```
|
|
50
58
|
|
|
51
59
|
**Available primitives under `bsv.SmartContract`:**
|
|
@@ -63,6 +71,94 @@ const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis
|
|
|
63
71
|
> is the intentionally public `a=k=1` construction, and low-S malleability is
|
|
64
72
|
> left unenforced for the in-script signature.
|
|
65
73
|
|
|
74
|
+
## 🔏 NotaryHash (BRC-220)
|
|
75
|
+
|
|
76
|
+
[BRC-220](https://github.com/bitcoin-sv/BRCs/blob/master/apps/0220.md) notarizes a
|
|
77
|
+
document by publishing a signed hash of it. The document itself never leaves your
|
|
78
|
+
hands — what goes on chain is an `OP_FALSE OP_RETURN` record, and what a verifier
|
|
79
|
+
receives is a certificate they can check offline plus an SPV proof they can check
|
|
80
|
+
against block headers obtained independently.
|
|
81
|
+
|
|
82
|
+
Available as `bsv.NotaryHash`, or `require('@smartledger/bsv/lib/notaryhash')`.
|
|
83
|
+
|
|
84
|
+
```javascript
|
|
85
|
+
const bsv = require('@smartledger/bsv')
|
|
86
|
+
const NotaryHash = bsv.NotaryHash
|
|
87
|
+
|
|
88
|
+
// 1. Hash the document. Only the hash is ever published.
|
|
89
|
+
const payloadHash = bsv.crypto.Hash.sha256(Buffer.from(documentBytes))
|
|
90
|
+
|
|
91
|
+
// 2. Sign the payloadHash DIRECTLY — no second hash, no Bitcoin sighash, and no
|
|
92
|
+
// `endian` option. The 32-byte digest is the scalar, big-endian, which is what
|
|
93
|
+
// every other ECDSA implementation does. Passing `endian: 'little'` here is
|
|
94
|
+
// Bitcoin's message-signing convention and produces a signature no conformant
|
|
95
|
+
// BRC-220 verifier will accept.
|
|
96
|
+
const ecdsa = bsv.crypto.ECDSA().set({ hashbuf: payloadHash, privkey: key })
|
|
97
|
+
ecdsa.sign()
|
|
98
|
+
const signatureBuffer = Buffer.concat([ // 64 raw bytes, r || s
|
|
99
|
+
ecdsa.sig.r.toArrayLike(Buffer, 'be', 32),
|
|
100
|
+
ecdsa.sig.s.toArrayLike(Buffer, 'be', 32)
|
|
101
|
+
])
|
|
102
|
+
const publicKeyBuffer = key.toPublicKey().toBuffer()
|
|
103
|
+
|
|
104
|
+
// 3. Build the certificate. `build` computes proofHash over
|
|
105
|
+
// the canonical bytes — the protocol prefix, version and timestamp are inside
|
|
106
|
+
// proofHash but never on chain, so the record alone cannot reconstruct it.
|
|
107
|
+
const certificate = NotaryHash.Certificate.build({
|
|
108
|
+
mode: NotaryHash.MODE.FULL,
|
|
109
|
+
algorithm: 'ECDSA-secp256k1',
|
|
110
|
+
hashAlgorithm: 'SHA-256',
|
|
111
|
+
payloadHash: payloadHash,
|
|
112
|
+
publicKey: publicKeyBuffer,
|
|
113
|
+
signature: signatureBuffer,
|
|
114
|
+
createdAt: new Date().toISOString(),
|
|
115
|
+
anchor: { txid: txid, blockHeight: height }
|
|
116
|
+
})
|
|
117
|
+
|
|
118
|
+
// 4. The output that goes on chain.
|
|
119
|
+
const script = NotaryHash.Script.build({
|
|
120
|
+
mode: NotaryHash.MODE.FULL,
|
|
121
|
+
algorithm: 'ECDSA-secp256k1',
|
|
122
|
+
hashAlgorithm: 'SHA-256',
|
|
123
|
+
payloadHash: payloadHash,
|
|
124
|
+
proofHash: Buffer.from(certificate.proofHash, 'hex'),
|
|
125
|
+
publicKey: publicKeyBuffer,
|
|
126
|
+
signature: signatureBuffer
|
|
127
|
+
})
|
|
128
|
+
|
|
129
|
+
// 5. Checks. Every verify entry point returns a STRICT boolean.
|
|
130
|
+
NotaryHash.Certificate.proofHashMatches(certificate) // proof integrity, offline
|
|
131
|
+
NotaryHash.Script.isNotaryHash(script) // is this a NotaryHash output
|
|
132
|
+
NotaryHash.isValid(certificate, options) // all three spec checks
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
**Three modes**, chosen by how much you can afford on chain:
|
|
136
|
+
|
|
137
|
+
| Mode | On chain | Use when |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| `MODE.FULL` | public key and signature in full | ECDSA, where both are small |
|
|
140
|
+
| `MODE.HYBRID` | `sha256` of each instead | post-quantum signatures, which run to tens of KB |
|
|
141
|
+
| `MODE.BATCH` | a 32-byte Merkle root and a `u32be` leaf count | notarizing many documents in one output |
|
|
142
|
+
|
|
143
|
+
Batch mode uses **RFC 6962** Merkle trees — domain-separated leaves
|
|
144
|
+
(`sha256(0x00‖d)`), internal nodes (`sha256(0x01‖L‖R)`), and a rightmost leaf that
|
|
145
|
+
is *never* duplicated. This is deliberately not the Bitcoin tree in `lib/spv` nor
|
|
146
|
+
the one in `lib/gdaf`; reusing either would produce a root no other BRC-220
|
|
147
|
+
implementation computes. The batch leaf is a certificate's `proofHash` — see
|
|
148
|
+
[`docs/BRC220_BATCH_LEAF_AMENDMENT.md`](./docs/BRC220_BATCH_LEAF_AMENDMENT.md).
|
|
149
|
+
|
|
150
|
+
**Post-quantum signatures are supported but not bundled.** `ECDSA-secp256k1` is
|
|
151
|
+
registered by default; ML-DSA and SLH-DSA are reached by registering a suite, so
|
|
152
|
+
callers who do not need them pay nothing in bundle size or audit surface:
|
|
153
|
+
|
|
154
|
+
```javascript
|
|
155
|
+
NotaryHash.registerSuite('ML-DSA-65', {
|
|
156
|
+
verify: function (payloadHash, signature, publicKey) { /* ... */ }
|
|
157
|
+
})
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
An unregistered `algorithm` fails; it never falls through to a default suite.
|
|
161
|
+
|
|
66
162
|
## 🆕 **Legally-Recognizable Credentials (v3.4.x+)**
|
|
67
163
|
|
|
68
164
|
### **Why This Matters**
|
|
@@ -76,8 +172,8 @@ const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis
|
|
|
76
172
|
### **Quick Start - Issue Your First Verifiable Credential**
|
|
77
173
|
|
|
78
174
|
```bash
|
|
79
|
-
# Install SmartLedger BSV
|
|
80
|
-
npm install @smartledger/bsv
|
|
175
|
+
# Install SmartLedger BSV
|
|
176
|
+
npm install @smartledger/bsv
|
|
81
177
|
|
|
82
178
|
# Initialize DID:web issuer (generates ES256 keys)
|
|
83
179
|
npx smartledger-bsv didweb init --domain example.com --alg ES256
|
|
@@ -186,42 +282,42 @@ console.log('Status:', status) // 'revoked'
|
|
|
186
282
|
### **Core Modules**
|
|
187
283
|
| Module | Size | Use Case | CDN |
|
|
188
284
|
|--------|------|----------|-----|
|
|
189
|
-
| **bsv.min.js** |
|
|
190
|
-
| **bsv.bundle.js** |
|
|
285
|
+
| **bsv.min.js** | 1039KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js` |
|
|
286
|
+
| **bsv.bundle.js** | 1039KB | Everything in one file | `unpkg.com/@smartledger/bsv@8.3.1/bsv.bundle.js` |
|
|
191
287
|
|
|
192
288
|
### **W3C Verifiable Credentials**
|
|
193
289
|
| Module | Size | Use Case | CDN |
|
|
194
290
|
|--------|------|----------|-----|
|
|
195
|
-
| **🟢 bsv-didweb.min.js** |
|
|
196
|
-
| **🟢 bsv-vcjwt.min.js** |
|
|
197
|
-
| **🟢 bsv-statuslist.min.js** |
|
|
198
|
-
| **🟢 bsv-anchor.min.js** |
|
|
291
|
+
| **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-didweb.min.js` |
|
|
292
|
+
| **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-vcjwt.min.js` |
|
|
293
|
+
| **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-statuslist.min.js` |
|
|
294
|
+
| **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-anchor.min.js` |
|
|
199
295
|
|
|
200
296
|
### **Smart Contract & Development**
|
|
201
297
|
| Module | Size | Use Case | CDN |
|
|
202
298
|
|--------|------|----------|-----|
|
|
203
|
-
| **bsv-smartcontract.min.js** |
|
|
204
|
-
| **bsv-covenant.min.js** |
|
|
205
|
-
| **bsv-script-helper.min.js** |
|
|
206
|
-
| **bsv-security.min.js** |
|
|
299
|
+
| **bsv-smartcontract.min.js** | 140KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@8.3.1/bsv-smartcontract.min.js` |
|
|
300
|
+
| **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@8.3.1/bsv-covenant.min.js` |
|
|
301
|
+
| **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@8.3.1/bsv-script-helper.min.js` |
|
|
302
|
+
| **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@8.3.1/bsv-security.min.js` |
|
|
207
303
|
|
|
208
304
|
### **Legal & Compliance**
|
|
209
305
|
| Module | Size | Use Case | CDN |
|
|
210
306
|
|--------|------|----------|-----|
|
|
211
|
-
| **bsv-ltp.min.js** |
|
|
212
|
-
| **bsv-gdaf.min.js** |
|
|
307
|
+
| **bsv-ltp.min.js** | 534KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@8.3.1/bsv-ltp.min.js` |
|
|
308
|
+
| **bsv-gdaf.min.js** | 1039KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@8.3.1/bsv-gdaf.min.js` |
|
|
213
309
|
|
|
214
310
|
### **Advanced Cryptography**
|
|
215
311
|
| Module | Size | Use Case | CDN |
|
|
216
312
|
|--------|------|----------|-----|
|
|
217
|
-
| **bsv-shamir.min.js** |
|
|
313
|
+
| **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@8.3.1/bsv-shamir.min.js` |
|
|
218
314
|
|
|
219
315
|
### **Utilities**
|
|
220
316
|
| Module | Size | Use Case | CDN |
|
|
221
317
|
|--------|------|----------|-----|
|
|
222
|
-
| **bsv-ecies.min.js** |
|
|
223
|
-
| **bsv-message.min.js** |
|
|
224
|
-
| **bsv-mnemonic.min.js** |
|
|
318
|
+
| **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@8.3.1/bsv-ecies.min.js` |
|
|
319
|
+
| **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@8.3.1/bsv-message.min.js` |
|
|
320
|
+
| **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@8.3.1/bsv-mnemonic.min.js` |
|
|
225
321
|
|
|
226
322
|
## ⚡ **2-Minute Quick Start**
|
|
227
323
|
|
|
@@ -232,15 +328,14 @@ Get started with Bitcoin SV development in under 2 minutes:
|
|
|
232
328
|
npm install @smartledger/bsv
|
|
233
329
|
|
|
234
330
|
# Or include in HTML
|
|
235
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
331
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
|
|
236
332
|
```
|
|
237
333
|
|
|
238
|
-
> **🔒
|
|
239
|
-
>
|
|
240
|
-
>
|
|
241
|
-
>
|
|
242
|
-
>
|
|
243
|
-
> DID:web + VC-JWT, StatusList2021, and BSV-anchoring toolkit. See CHANGELOG.
|
|
334
|
+
> **🔒 Upgrading?** 8.0.0 changed what `verify()` means with no flags, and moved
|
|
335
|
+
> two flag constants. Read [Upgrading to v8.0.0](#upgrading-to-v800-breaking-changes)
|
|
336
|
+
> before moving from 7.x or earlier; the older
|
|
337
|
+
> [v5.0.0 notes](#upgrading-to-v500-breaking-changes) still apply if you are coming
|
|
338
|
+
> from 4.x.
|
|
244
339
|
|
|
245
340
|
**Basic Transaction (30 seconds):**
|
|
246
341
|
```javascript
|
|
@@ -263,21 +358,22 @@ console.log('Transaction ID:', tx.id);
|
|
|
263
358
|
|
|
264
359
|
**🆕 Legal Token Development (60 seconds):**
|
|
265
360
|
```javascript
|
|
266
|
-
// Create legal property token
|
|
267
|
-
const
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
});
|
|
361
|
+
// Create a legal property-title token
|
|
362
|
+
const result = bsv.LTP.createRightToken({
|
|
363
|
+
type: bsv.LTP.Right.RightTypes.PROPERTY_TITLE,
|
|
364
|
+
owner: ownerDID,
|
|
365
|
+
jurisdiction: 'us_delaware',
|
|
366
|
+
legalDescription: 'Lot 15, Block 3, Subdivision ABC'
|
|
367
|
+
}, issuerPrivateKey);
|
|
368
|
+
console.log(result.success, result.token.tokenHash);
|
|
273
369
|
|
|
274
370
|
// Generate W3C Verifiable Credential
|
|
275
371
|
const credential = bsv.createEmailCredential(
|
|
276
372
|
issuerDID, subjectDID, 'user@example.com', issuerPrivateKey
|
|
277
373
|
);
|
|
278
374
|
|
|
279
|
-
// Threshold cryptography
|
|
280
|
-
const shares = bsv.
|
|
375
|
+
// Threshold cryptography — split(secret, threshold, shares)
|
|
376
|
+
const shares = bsv.Shamir.split('private_key_backup', 3, 5); // 3 of 5 needed
|
|
281
377
|
```
|
|
282
378
|
|
|
283
379
|
**🆕 Smart Contract Development (90 seconds):**
|
|
@@ -300,11 +396,11 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
|
|
|
300
396
|
```
|
|
301
397
|
|
|
302
398
|
**Next Steps:**
|
|
303
|
-
- 📖 [SmartContract Guide](docs/SMART_CONTRACT_GUIDE.md)
|
|
304
|
-
- ⚖️ [Legal Token Protocol Guide](docs/
|
|
305
|
-
- 🌐 [Digital Identity Guide](docs/
|
|
306
|
-
-
|
|
307
|
-
-
|
|
399
|
+
- 📖 [SmartContract Guide](docs/advanced/SMART_CONTRACT_GUIDE.md)
|
|
400
|
+
- ⚖️ [Legal Token Protocol Guide](docs/advanced/LEGAL_TOKEN_PROTOCOL.md)
|
|
401
|
+
- 🌐 [Digital Identity Guide](docs/technical/GDAF_DEVELOPER_INTERFACE.md)
|
|
402
|
+
- 🔐 [Threshold Cryptography Guide](docs/technical/SHAMIR_INTEGRATION_SUMMARY.md)
|
|
403
|
+
- 🗃️ [UTXO Manager Guide](docs/advanced/UTXO_MANAGER_GUIDE.md)
|
|
308
404
|
- 💡 [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
|
|
309
405
|
|
|
310
406
|
## 🔧 **API Reference**
|
|
@@ -314,37 +410,37 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
|
|
|
314
410
|
| **Core** | `new PrivateKey()` | Generate private key | `const key = new bsv.PrivateKey()` |
|
|
315
411
|
| | `new Transaction()` | Create transaction | `const tx = new bsv.Transaction()` |
|
|
316
412
|
| | `Script.fromASM()` | Parse script | `const script = bsv.Script.fromASM('OP_DUP')` |
|
|
317
|
-
| **Covenant** | `
|
|
318
|
-
| | `
|
|
319
|
-
| | `getPreimage()` | BIP143 preimage | `
|
|
320
|
-
| **Custom Scripts** | `CustomScriptHelper
|
|
321
|
-
| | `createSignature()` | Manual signature | `
|
|
322
|
-
| | `createMultisigScript()` | Multi-signature | `
|
|
413
|
+
| **Covenant** | `SmartContract.perpetualCovenant()` | Self-replicating covenant | `SC.perpetualCovenant(500)` |
|
|
414
|
+
| | `SmartContract.verifyScript()` | Verify a script pair; returns `{ ok, err }` | `SC.verifyScript(unlock, lock, { tx, satoshis })` |
|
|
415
|
+
| | `CustomScriptHelper.getPreimage()` | BIP143 preimage | `bsv.CustomScriptHelper.getPreimage(tx, 0, script, sats)` |
|
|
416
|
+
| **Custom Scripts** | `CustomScriptHelper` | Script utilities — **all methods are static**, do not instantiate | `bsv.CustomScriptHelper.createDataScript(data)` |
|
|
417
|
+
| | `createSignature()` | Manual signature | `bsv.CustomScriptHelper.createSignature(tx, key, 0, script, sats)` |
|
|
418
|
+
| | `createMultisigScript()` | Multi-signature | `bsv.CustomScriptHelper.createMultisigScript(2, [pk1, pk2])` |
|
|
323
419
|
| **Debug Tools** | `SmartContract.examineStack()` | Analyze script | `SmartContract.examineStack(script)` |
|
|
324
420
|
| | `interpretScript()` | Execute script | `SmartContract.interpretScript(script)` |
|
|
325
421
|
| | `getScriptMetrics()` | Performance data | `SmartContract.getScriptMetrics(script)` |
|
|
326
|
-
| **Security (opt-in)** | `SmartVerify.
|
|
327
|
-
| | `EllipticFixed.sign()` | Canonicalized signing wrapper
|
|
422
|
+
| **Security (opt-in)** | `SmartVerify.smartVerify()` | Hardened verify with strict input validation — call explicitly; default `signature.verify()` does NOT route through this | `bsv.SmartVerify.smartVerify(msgHash, sig, pubkey)` |
|
|
423
|
+
| | `EllipticFixed.sign()` | Canonicalized signing wrapper over the `@noble` secp256k1 backend | `bsv.EllipticFixed.sign(hash, privateKey)` |
|
|
328
424
|
|
|
329
425
|
> 💡 **Tip:** All methods include comprehensive error handling and validation. See [documentation links](#documentation) for detailed guides.
|
|
330
426
|
|
|
331
427
|
## 📚 **Quick Start Examples**
|
|
332
428
|
|
|
333
|
-
### 🔧 **Basic Development** (~1.
|
|
429
|
+
### 🔧 **Basic Development** (~1.05MB total)
|
|
334
430
|
```html
|
|
335
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
336
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
431
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
|
|
432
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-script-helper.min.js"></script>
|
|
337
433
|
<script>
|
|
338
434
|
const privateKey = new bsv.PrivateKey();
|
|
339
435
|
const utxos = new bsv.SmartContract.UTXOGenerator().createRealUTXOs(2, 100000);
|
|
340
436
|
</script>
|
|
341
437
|
```
|
|
342
438
|
|
|
343
|
-
### 🔒 **Smart Contract Development** (~
|
|
439
|
+
### 🔒 **Smart Contract Development** (~1.2MB total — each bundle re-embeds core BSV)
|
|
344
440
|
```html
|
|
345
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
346
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
347
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
441
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
|
|
442
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-covenant.min.js"></script>
|
|
443
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-smartcontract.min.js"></script>
|
|
348
444
|
<script>
|
|
349
445
|
const covenant = bsv.SmartContract.createCovenantBuilder()
|
|
350
446
|
.extractField('amount').push(50000).greaterThanOrEqual().verify().build();
|
|
@@ -352,44 +448,45 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
|
|
|
352
448
|
</script>
|
|
353
449
|
```
|
|
354
450
|
|
|
355
|
-
### 🆕 **Legal & Identity Development** (~
|
|
451
|
+
### 🆕 **Legal & Identity Development** (~2.55MB total — each bundle re-embeds core BSV)
|
|
356
452
|
```html
|
|
357
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
358
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
359
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
453
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
|
|
454
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-ltp.min.js"></script>
|
|
455
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-gdaf.min.js"></script>
|
|
360
456
|
<script>
|
|
361
457
|
// Legal Token Protocol
|
|
362
|
-
const
|
|
363
|
-
|
|
364
|
-
|
|
458
|
+
const result = bsv.LTP.createRightToken({
|
|
459
|
+
type: bsv.LTP.Right.RightTypes.PROPERTY_TITLE,
|
|
460
|
+
owner: ownerDID, jurisdiction: 'us_delaware'
|
|
461
|
+
}, key);
|
|
365
462
|
|
|
366
463
|
// Digital Identity
|
|
367
464
|
const credential = bsv.createEmailCredential(issuerDID, subjectDID, 'user@example.com', key);
|
|
368
465
|
</script>
|
|
369
466
|
```
|
|
370
467
|
|
|
371
|
-
### 🆕 **Security & Cryptography** (~1.
|
|
468
|
+
### 🆕 **Security & Cryptography** (~1.22MB total)
|
|
372
469
|
```html
|
|
373
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
374
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
375
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
470
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
|
|
471
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-security.min.js"></script>
|
|
472
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-shamir.min.js"></script>
|
|
376
473
|
<script>
|
|
377
474
|
// Threshold Cryptography
|
|
378
|
-
const shares = bsv.
|
|
475
|
+
const shares = bsv.Shamir.split('my_secret_key', 3, 5); // 5 shares, any 3 recover
|
|
379
476
|
|
|
380
477
|
// Enhanced Security
|
|
381
|
-
const verified = bsvSecurity.SmartVerify.
|
|
478
|
+
const verified = bsvSecurity.SmartVerify.smartVerify(hash, signature, publicKey);
|
|
382
479
|
</script>
|
|
383
480
|
```
|
|
384
481
|
|
|
385
|
-
### 🎯 **Everything Bundle** (~1.
|
|
482
|
+
### 🎯 **Everything Bundle** (~1.02MB)
|
|
386
483
|
```html
|
|
387
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
484
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.bundle.js"></script>
|
|
388
485
|
<script>
|
|
389
486
|
// Everything available immediately
|
|
390
|
-
const shares = bsv.
|
|
391
|
-
const
|
|
392
|
-
const
|
|
487
|
+
const shares = bsv.Shamir.split('secret', 3, 5); // Shamir Secret Sharing
|
|
488
|
+
const did = bsv.createDID(publicKey); // Digital Identity
|
|
489
|
+
const token = bsv.LTP.createRightToken({ /* ... */ }, key); // Legal Tokens
|
|
393
490
|
const covenant = bsv.SmartContract.createCovenantBuilder(); // Smart Contracts
|
|
394
491
|
</script>
|
|
395
492
|
```
|
|
@@ -397,10 +494,10 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
|
|
|
397
494
|
## 🎯 **Key Features**
|
|
398
495
|
|
|
399
496
|
### 🚀 **Unique Capabilities** (Only Bitcoin Library with These Features)
|
|
400
|
-
- ✅ **Legal Token Protocol**: Compliant tokenization of real-world assets → [Legal Guide](docs/
|
|
401
|
-
- ✅ **Digital Identity Framework**: W3C Verifiable Credentials and DIDs → [Identity Guide](docs/
|
|
402
|
-
- ✅ **Threshold Cryptography**: Shamir Secret Sharing for secure key management → [Cryptography Guide](docs/
|
|
403
|
-
- ✅ **Complete Smart Contract Suite**: 23+ production-ready covenant features → [SmartContract Guide](docs/SMART_CONTRACT_GUIDE.md)
|
|
497
|
+
- ✅ **Legal Token Protocol**: Compliant tokenization of real-world assets → [Legal Guide](docs/advanced/LEGAL_TOKEN_PROTOCOL.md)
|
|
498
|
+
- ✅ **Digital Identity Framework**: W3C Verifiable Credentials and DIDs → [Identity Guide](docs/technical/GDAF_DEVELOPER_INTERFACE.md)
|
|
499
|
+
- ✅ **Threshold Cryptography**: Shamir Secret Sharing for secure key management → [Cryptography Guide](docs/technical/SHAMIR_INTEGRATION_SUMMARY.md)
|
|
500
|
+
- ✅ **Complete Smart Contract Suite**: 23+ production-ready covenant features → [SmartContract Guide](docs/advanced/SMART_CONTRACT_GUIDE.md)
|
|
404
501
|
|
|
405
502
|
### 💼 **Core Library Excellence**
|
|
406
503
|
- ✅ **Complete BSV API**: Full Bitcoin SV blockchain operations → [API Reference](#-api-reference)
|
|
@@ -410,14 +507,14 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
|
|
|
410
507
|
- ✅ **Ultra-Low Fees**: 0.01 sats/byte configuration (91% fee reduction)
|
|
411
508
|
|
|
412
509
|
### 🛠️ **Advanced Development Tools**
|
|
413
|
-
- 🔧 **JavaScript-to-Script**: High-level covenant development with 121 opcode mapping → [Covenant Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
|
|
414
|
-
- 🔧 **UTXO Generator**: Create authentic test UTXOs for development → [UTXO Guide](docs/UTXO_MANAGER_GUIDE.md)
|
|
510
|
+
- 🔧 **JavaScript-to-Script**: High-level covenant development with 121 opcode mapping → [Covenant Guide](docs/advanced/ADVANCED_COVENANT_DEVELOPMENT.md)
|
|
511
|
+
- 🔧 **UTXO Generator**: Create authentic test UTXOs for development → [UTXO Guide](docs/advanced/UTXO_MANAGER_GUIDE.md)
|
|
415
512
|
- 🔧 **Preimage Parser**: Complete BIP-143 field extraction and manipulation → [Preimage Tools](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/preimage)
|
|
416
|
-
-
|
|
417
|
-
-
|
|
513
|
+
- 🔧 **Debug Framework**: Script interpreter, stack examiner, and optimizer → [Debug Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
|
|
514
|
+
- 🔧 **PUSHTX Integration**: nChain techniques for advanced covenant patterns → [PUSHTX Insights](docs/pushtx-key-insights.md)
|
|
418
515
|
|
|
419
516
|
### 📦 **Flexible Architecture**
|
|
420
|
-
- 📦 **16 Modular Options**: Load only what you need (
|
|
517
|
+
- 📦 **16 Modular Options**: Load only what you need (32KB to 1039KB) → [Loading Strategy](#-16-loading-options---choose-your-approach)
|
|
421
518
|
- 📦 **Standalone Modules**: Independent legal, identity, and crypto modules → [Standalone Test](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/standalone-modules-test.html)
|
|
422
519
|
- 📦 **Complete Bundle**: Everything in one file for convenience → [Bundle Demo](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/bundle-demo.html)
|
|
423
520
|
- 📦 **CDN Ready**: All modules available via unpkg and jsDelivr
|
|
@@ -429,15 +526,45 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
|
|
|
429
526
|
|
|
430
527
|
### NPM Installation
|
|
431
528
|
```bash
|
|
432
|
-
# Main package
|
|
433
529
|
npm install @smartledger/bsv
|
|
434
|
-
|
|
435
|
-
# Alternative package name (legacy)
|
|
436
|
-
npm install smartledger-bsv
|
|
437
530
|
```
|
|
438
531
|
|
|
439
532
|
> 📖 **Next Steps**: After installation, see [Loading Options](#-16-loading-options---choose-your-approach) to choose your distribution method
|
|
440
533
|
|
|
534
|
+
### Upgrading to v8.0.0 (Breaking Changes)
|
|
535
|
+
|
|
536
|
+
8.0.0 moved the defaults onto BSV as the network actually runs it. Two changes
|
|
537
|
+
need action.
|
|
538
|
+
|
|
539
|
+
**1. `verify()` with no flags now means BSV mainnet, not "no rules".**
|
|
540
|
+
|
|
541
|
+
```javascript
|
|
542
|
+
interp.verify(sig, pubkey, tx, nin) // was: Bitcoin 2015; now: current mainnet
|
|
543
|
+
interp.verify(sig, pubkey, tx, nin, 0) // the old behaviour, stated explicitly
|
|
544
|
+
|
|
545
|
+
// Spending a pre-Chronicle output — state the era of the output being spent,
|
|
546
|
+
// because that is the input the caller knows and the library cannot infer.
|
|
547
|
+
bsv.Script.Interpreter.mainnetFlags({ afterChronicle: false })
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
**2. Two flag constants changed numeric value.** The node assigns `1<<18` and
|
|
551
|
+
`1<<19` to `SCRIPT_GENESIS` and `SCRIPT_UTXO_AFTER_GENESIS`, so ours had to move:
|
|
552
|
+
|
|
553
|
+
```
|
|
554
|
+
SCRIPT_ENABLE_MONOLITH_OPCODES 1<<18 → 1<<11
|
|
555
|
+
SCRIPT_ENABLE_MAGNETIC_OPCODES 1<<19 → 1<<12
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
Code using the **named constants** is unaffected. Code that **persisted or
|
|
559
|
+
hardcoded the numbers** must be updated: `262144` no longer means "Monolith
|
|
560
|
+
opcodes", it now means `SCRIPT_GENESIS`, so a stored value silently selects a
|
|
561
|
+
different era model.
|
|
562
|
+
|
|
563
|
+
Also in 8.0.0: a signature carrying `SIGHASH_CHRONICLE` outside Chronicle is
|
|
564
|
+
rejected rather than reinterpreted, and `MAX_OPS_PER_SCRIPT` is BSV's 500 rather
|
|
565
|
+
than Bitcoin Core's 201. Full details in the
|
|
566
|
+
[CHANGELOG](./CHANGELOG.md#800---2026-08-13).
|
|
567
|
+
|
|
441
568
|
### Upgrading to v5.0.0 (Breaking Changes)
|
|
442
569
|
|
|
443
570
|
v5.0.0 hardens the cryptography. Most apps need **no code changes** — the
|
|
@@ -462,9 +589,9 @@ breaking changes only affect data produced by older versions:
|
|
|
462
589
|
outside `['ES256','ES256K']` (override via `opts.allowedAlgs`) and binds the
|
|
463
590
|
key's curve to the algorithm — defense against alg-substitution attacks.
|
|
464
591
|
- **Browser bundles changed size.** The full bundles ship a real `crypto`
|
|
465
|
-
polyfill so Shamir can source a CSPRNG
|
|
466
|
-
|
|
467
|
-
|
|
592
|
+
polyfill so Shamir can source a CSPRNG. Sizes have moved since; `bsv.min.js` is
|
|
593
|
+
~1039KB at 8.3.0, after the ~20% reduction in 8.0.0. The dedicated
|
|
594
|
+
single-feature module bundles are unaffected.
|
|
468
595
|
|
|
469
596
|
Full details in the [CHANGELOG](./CHANGELOG.md#500---2026-06-13).
|
|
470
597
|
|
|
@@ -482,57 +609,57 @@ const script = bsv.Script.fromASM('OP_1 OP_2 OP_ADD OP_3 OP_EQUAL');
|
|
|
482
609
|
const metrics = bsv.SmartContract.getScriptMetrics(script);
|
|
483
610
|
const stackInfo = bsv.SmartContract.examineStack(script);
|
|
484
611
|
|
|
485
|
-
// Covenant development
|
|
486
|
-
const
|
|
487
|
-
const
|
|
488
|
-
inputs: [...],
|
|
489
|
-
outputs: [...]
|
|
490
|
-
});
|
|
612
|
+
// Covenant development — see bsv.SmartContract for the covenant stack
|
|
613
|
+
const lock = bsv.SmartContract.perpetualCovenant(500);
|
|
614
|
+
const { ok, err } = bsv.SmartContract.verifyScript(unlockScript, lock, { tx, satoshis });
|
|
491
615
|
```
|
|
492
616
|
|
|
493
617
|
### Browser CDN (Choose Your Loading Strategy)
|
|
494
618
|
|
|
495
|
-
#### 1. **Minimal Setup** - Core + Script Helper (~1.
|
|
619
|
+
#### 1. **Minimal Setup** - Core + Script Helper (~1.05MB)
|
|
496
620
|
```html
|
|
497
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
498
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
621
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
|
|
622
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-script-helper.min.js"></script>
|
|
499
623
|
<script>
|
|
500
624
|
const tx = new bsv.Transaction();
|
|
501
625
|
const sig = bsvScriptHelper.createSignature(tx, privateKey, 0, script, satoshis);
|
|
502
626
|
</script>
|
|
503
627
|
```
|
|
504
628
|
|
|
505
|
-
#### 2. **DeFi Development** - Core + Covenants + Debug (~
|
|
629
|
+
#### 2. **DeFi Development** - Core + Covenants + Debug (~1.2MB — each bundle re-embeds core BSV)
|
|
506
630
|
```html
|
|
507
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
508
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
509
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
631
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
|
|
632
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-covenant.min.js"></script>
|
|
633
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-smartcontract.min.js"></script>
|
|
510
634
|
<script>
|
|
511
|
-
const
|
|
512
|
-
const debugInfo = SmartContract.interpretScript(script);
|
|
513
|
-
const optimized = SmartContract.optimizeScript(script);
|
|
635
|
+
const lock = bsv.SmartContract.perpetualCovenant(500);
|
|
636
|
+
const debugInfo = bsv.SmartContract.interpretScript(script);
|
|
637
|
+
const optimized = bsv.SmartContract.optimizeScript(script);
|
|
514
638
|
</script>
|
|
515
639
|
```
|
|
516
640
|
|
|
517
|
-
#### 3. **Security First** - Core + Enhanced Security (~1.
|
|
641
|
+
#### 3. **Security First** - Core + Enhanced Security (~1.05MB)
|
|
518
642
|
```html
|
|
519
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
520
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
643
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
|
|
644
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-security.min.js"></script>
|
|
521
645
|
<script>
|
|
522
|
-
const verified = bsvSecurity.SmartVerify.
|
|
523
|
-
const enhanced = bsvSecurity.EllipticFixed.
|
|
646
|
+
const verified = bsvSecurity.SmartVerify.smartVerify(hash, signature, publicKey);
|
|
647
|
+
const enhanced = bsvSecurity.EllipticFixed.sign(hash, privateKey);
|
|
524
648
|
</script>
|
|
525
649
|
```
|
|
526
650
|
|
|
527
|
-
#### 4. **Everything Bundle** - One File Solution (~1.
|
|
651
|
+
#### 4. **Everything Bundle** - One File Solution (~1.02MB)
|
|
528
652
|
```html
|
|
529
|
-
<script src="https://unpkg.com/@smartledger/bsv@8.3.
|
|
653
|
+
<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.bundle.js"></script>
|
|
530
654
|
<script>
|
|
531
|
-
// Everything available under bsv namespace
|
|
532
|
-
const
|
|
533
|
-
const
|
|
655
|
+
// Everything available under the bsv namespace
|
|
656
|
+
const key = bsv.PrivateKey.fromRandom();
|
|
657
|
+
const lock = bsv.SmartContract.perpetualCovenant(500);
|
|
534
658
|
const message = new bsv.Message('Hello BSV');
|
|
535
|
-
const encrypted = bsv.ECIES
|
|
659
|
+
const encrypted = new bsv.ECIES()
|
|
660
|
+
.privateKey(key)
|
|
661
|
+
.publicKey(recipientPublicKey)
|
|
662
|
+
.encrypt('secret');
|
|
536
663
|
</script>
|
|
537
664
|
```
|
|
538
665
|
|
|
@@ -581,27 +708,30 @@ const utxoManager = {
|
|
|
581
708
|
```javascript
|
|
582
709
|
const bsv = require('@smartledger/bsv');
|
|
583
710
|
|
|
584
|
-
// Create property
|
|
585
|
-
|
|
586
|
-
|
|
711
|
+
// Create a property-rights token. `type` must be one of LTP.Right.RightTypes —
|
|
712
|
+
// an unrecognized type is rejected rather than silently accepted.
|
|
713
|
+
const result = bsv.LTP.createRightToken({
|
|
714
|
+
type: bsv.LTP.Right.RightTypes.PROPERTY_TITLE,
|
|
715
|
+
owner: ownerDID,
|
|
587
716
|
jurisdiction: 'us_delaware',
|
|
588
|
-
legalDescription: 'Lot 15, Block 3, Subdivision ABC'
|
|
589
|
-
|
|
590
|
-
attestations: [titleAttestation, valuationAttestation]
|
|
591
|
-
});
|
|
717
|
+
legalDescription: 'Lot 15, Block 3, Subdivision ABC'
|
|
718
|
+
}, issuerPrivateKey);
|
|
592
719
|
|
|
593
|
-
//
|
|
594
|
-
|
|
720
|
+
console.log(result.success); // true
|
|
721
|
+
console.log(result.token.tokenHash); // hash committed by the token's proof
|
|
722
|
+
|
|
723
|
+
// Obligation tokens
|
|
724
|
+
const obligation = bsv.LTP.Obligation.prepareObligationToken({
|
|
595
725
|
obligationType: 'payment',
|
|
596
726
|
amount: 100000, // satoshis
|
|
597
|
-
dueDate: '
|
|
727
|
+
dueDate: '2026-12-31',
|
|
598
728
|
creditor: creditorDID,
|
|
599
729
|
debtor: debtorDID
|
|
600
730
|
});
|
|
601
731
|
|
|
602
|
-
// Validate
|
|
603
|
-
|
|
604
|
-
|
|
732
|
+
// Validate claim data against a registered schema
|
|
733
|
+
// (schema names come from bsv.LTP.Claim.getSchemaNames())
|
|
734
|
+
const validation = bsv.validateLegalClaim(claimData, schemaType);
|
|
605
735
|
```
|
|
606
736
|
|
|
607
737
|
### 🌐 Global Digital Attestation Framework (GDAF)
|
|
@@ -634,23 +764,20 @@ const gdaf = new bsv.GDAF({
|
|
|
634
764
|
|
|
635
765
|
### 🔐 Shamir Secret Sharing
|
|
636
766
|
```javascript
|
|
637
|
-
// Split secret into threshold shares
|
|
767
|
+
// Split a secret into threshold shares.
|
|
768
|
+
// Signature is split(secret, threshold, shares) — THRESHOLD FIRST.
|
|
638
769
|
const secret = 'my_private_key_backup';
|
|
639
|
-
const shares = bsv.
|
|
770
|
+
const shares = bsv.Shamir.split(secret, 3, 5); // 5 shares, any 3 reconstruct
|
|
640
771
|
|
|
641
772
|
console.log('Generated', shares.length, 'shares');
|
|
642
|
-
shares.forEach((share, i) => {
|
|
643
|
-
console.log(`Share ${i + 1}:`, share);
|
|
644
|
-
});
|
|
645
773
|
|
|
646
|
-
// Reconstruct
|
|
647
|
-
const reconstructed = bsv.
|
|
648
|
-
console.log('Secret recovered:', reconstructed === secret);
|
|
774
|
+
// Reconstruct from any 3 shares
|
|
775
|
+
const reconstructed = bsv.Shamir.combine([shares[0], shares[2], shares[4]]);
|
|
776
|
+
console.log('Secret recovered:', reconstructed === secret); // true
|
|
649
777
|
|
|
650
778
|
// Validate share integrity
|
|
651
779
|
shares.forEach((share, i) => {
|
|
652
|
-
|
|
653
|
-
console.log(`Share ${i + 1} valid:`, isValid);
|
|
780
|
+
console.log(`Share ${i + 1} valid:`, bsv.Shamir.verifyShare(share));
|
|
654
781
|
});
|
|
655
782
|
|
|
656
783
|
// Use cases: Key backup, multi-party security, recovery systems
|
|
@@ -677,7 +804,7 @@ const custom = new CovenantBuilder()
|
|
|
677
804
|
.push(1);
|
|
678
805
|
```
|
|
679
806
|
|
|
680
|
-
### Complete Opcode Mapping (
|
|
807
|
+
### Complete Opcode Mapping (116 Opcodes)
|
|
681
808
|
```javascript
|
|
682
809
|
const SmartContract = require('@smartledger/bsv/lib/smart_contract');
|
|
683
810
|
|
|
@@ -687,7 +814,7 @@ console.log(result.finalStack); // ['01'] - TRUE
|
|
|
687
814
|
|
|
688
815
|
// Get comprehensive opcode information
|
|
689
816
|
const opcodes = SmartContract.getOpcodeMap();
|
|
690
|
-
console.log(Object.keys(opcodes).length); //
|
|
817
|
+
console.log(Object.keys(opcodes).length); // 116 opcodes mapped
|
|
691
818
|
```
|
|
692
819
|
|
|
693
820
|
### BIP143 Preimage Parsing
|
|
@@ -702,7 +829,7 @@ console.log('Amount:', preimage.amountValue); // BigInt accessor
|
|
|
702
829
|
console.log('Valid structure:', preimage.isValid); // Boolean validation
|
|
703
830
|
```
|
|
704
831
|
|
|
705
|
-
### PUSHTX Covenants (nChain WP1605)
|
|
832
|
+
### PUSHTX Covenants (nChain WP1605)
|
|
706
833
|
```javascript
|
|
707
834
|
const bsv = require('@smartledger/bsv')
|
|
708
835
|
const SC = bsv.SmartContract
|
|
@@ -720,7 +847,7 @@ const requiredOutputs = [/* bsv.Transaction.Output objects */]
|
|
|
720
847
|
const valueLock = SC.PushTx.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs))
|
|
721
848
|
```
|
|
722
849
|
|
|
723
|
-
### Perpetually Enforcing Locking Scripts (PELS)
|
|
850
|
+
### Perpetually Enforcing Locking Scripts (PELS)
|
|
724
851
|
```javascript
|
|
725
852
|
// Self-replicating covenant: every spend must recreate the same script
|
|
726
853
|
// (value − fee), reading its own code out of the authenticated preimage's
|
|
@@ -728,7 +855,7 @@ const valueLock = SC.PushTx.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs)
|
|
|
728
855
|
const pels = SC.perpetualCovenant(500) // fee in satoshis deducted each hop
|
|
729
856
|
```
|
|
730
857
|
|
|
731
|
-
### Ownership Tokens (NFT)
|
|
858
|
+
### Ownership Tokens (NFT)
|
|
732
859
|
```javascript
|
|
733
860
|
// Stateful ownership token. Owner is carried as on-chain state (HASH160 of the
|
|
734
861
|
// owner's public key); transfer requires the current owner's ECDSA SIGNATURE over
|
|
@@ -764,36 +891,47 @@ const multi = SC.Token.ownershipTokenMulti(ownerHash)
|
|
|
764
891
|
const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis)
|
|
765
892
|
```
|
|
766
893
|
|
|
767
|
-
###
|
|
894
|
+
### Consensus defaults — BSV mainnet, no flags required (8.0.0+)
|
|
768
895
|
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
arithmetic, and run a few hundred opcodes.
|
|
775
|
-
|
|
776
|
-
Opt into post-Genesis rules with a single call at app startup:
|
|
896
|
+
**Since 8.0.0 you do not opt in to BSV.** `verify()` with no flags means
|
|
897
|
+
current BSV mainnet consensus, and `MAX_OPS_PER_SCRIPT` is BSV's 500 rather
|
|
898
|
+
than Bitcoin Core's 201. Earlier versions defaulted to a 2015-era Bitcoin
|
|
899
|
+
rule set and required an explicit call to reach post-Genesis behaviour; that
|
|
900
|
+
is no longer the case.
|
|
777
901
|
|
|
778
902
|
```javascript
|
|
779
903
|
const bsv = require('@smartledger/bsv');
|
|
904
|
+
const interp = new bsv.Script.Interpreter();
|
|
905
|
+
|
|
906
|
+
// Current BSV mainnet — this is the default.
|
|
907
|
+
const ok = interp.verify(unlockScript, lockScript, tx, 0, undefined, satoshisBN);
|
|
780
908
|
|
|
781
|
-
//
|
|
782
|
-
//
|
|
783
|
-
bsv.Script.Interpreter.
|
|
909
|
+
// Spending a pre-Chronicle output: state the era of the output you are spending,
|
|
910
|
+
// because the library cannot infer it.
|
|
911
|
+
const flags = bsv.Script.Interpreter.mainnetFlags({ afterChronicle: false });
|
|
912
|
+
const ok2 = interp.verify(unlockScript, lockScript, tx, 0, flags, satoshisBN);
|
|
784
913
|
|
|
785
|
-
//
|
|
786
|
-
|
|
914
|
+
// The pre-8.0.0 "no rules" behaviour, if you genuinely want it, is now explicit:
|
|
915
|
+
const ok3 = interp.verify(unlockScript, lockScript, tx, 0, 0, satoshisBN);
|
|
916
|
+
```
|
|
917
|
+
|
|
918
|
+
**Covenants need no special setup.** The element and script-number caps are
|
|
919
|
+
derived from the era flags, not from the `MAX_SCRIPT_ELEMENT_SIZE` static — which
|
|
920
|
+
still reads 520 because it is only the pre-Genesis fallback. An OP_PUSH_TX
|
|
921
|
+
covenant pushing a ~585-byte preimage verifies under the defaults:
|
|
787
922
|
|
|
788
|
-
|
|
923
|
+
```javascript
|
|
789
924
|
const interp = new bsv.Script.Interpreter();
|
|
790
|
-
const ok = interp.verify(unlockScript, lockScript, tx, 0,
|
|
925
|
+
const ok = interp.verify(unlockScript, lockScript, tx, 0, undefined, satoshisBN);
|
|
791
926
|
```
|
|
792
927
|
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
928
|
+
> ⚠️ **`Interpreter.useGenesisLimits()` is legacy and should not be used to enable
|
|
929
|
+
> covenants.** It cannot enable post-Genesis arithmetic — that comes from the era
|
|
930
|
+
> flags — and because it mutates process-wide statics it *weakens* pre-Genesis
|
|
931
|
+
> validation: raising `MAXIMUM_ELEMENT_SIZE` turns 15 of the reference node's 22
|
|
932
|
+
> `SCRIPTNUM_OVERFLOW` vectors into false accepts. If you must call it, capture
|
|
933
|
+
> and restore the caps around it with `Interpreter.getLimits()` /
|
|
934
|
+
> `Interpreter.setLimits()`.
|
|
797
935
|
|
|
798
936
|
## 🛠️ Custom Scripts
|
|
799
937
|
|
|
@@ -834,7 +972,7 @@ const timelockScript = helper.createTimelockScript(
|
|
|
834
972
|
|
|
835
973
|
See the **[16 Loading Options](#-16-loading-options---choose-your-approach)**
|
|
836
974
|
table near the top for the full list of bundles with current sizes and
|
|
837
|
-
canonical `unpkg.com/@smartledger/bsv@8.3.
|
|
975
|
+
canonical `unpkg.com/@smartledger/bsv@8.3.1/...` URLs.
|
|
838
976
|
|
|
839
977
|
## 🔐 Security
|
|
840
978
|
|
|
@@ -842,10 +980,10 @@ canonical `unpkg.com/@smartledger/bsv@8.3.0/...` URLs.
|
|
|
842
980
|
|
|
843
981
|
| Surface | Status | Notes |
|
|
844
982
|
|---------|--------|-------|
|
|
845
|
-
| `elliptic
|
|
983
|
+
| secp256k1 primitives | `@noble/curves` | `elliptic` was removed entirely — it is not a dependency and is not in the bundles. The Noble suite carries a published Cure53 audit. |
|
|
846
984
|
| Default `transaction.verify()` / `signature.verify()` / `Message().verify()` | uses BSV's own `lib/crypto/ecdsa.js` | This path does **not** import elliptic and is **not** routed through `SmartVerify` or `EllipticFixed`. |
|
|
847
985
|
| `bsv.SmartVerify` (opt-in helper) | available | Hardened standalone verify: rejects `r=0`, `s=0`, `r≥n`, `s≥n`; canonicalizes `s` to low half. Built on BSV's own `BN`/`ECDSA`. You must call it explicitly. |
|
|
848
|
-
| `bsv.EllipticFixed` (opt-in helper) | available |
|
|
986
|
+
| `bsv.EllipticFixed` (opt-in helper) | available | An elliptic-*compatible* secp256k1 surface — the name is kept for API compatibility, but it is backed by `@noble/curves`. Adds the same input checks plus low-`s` on sign. |
|
|
849
987
|
| `signature.validate()` / `isCanonical()` / `toCanonical()` | available | Real methods on `bsv.Signature`. |
|
|
850
988
|
| DER canonicalization on TX signing | available | BSV's signature path produces low-`s` DER by default. |
|
|
851
989
|
| BIP143 preimage utilities | available | `lib/smart_contract/preimage.js` and `examples/preimage/`. |
|
|
@@ -864,8 +1002,8 @@ const okDefault = bsv.crypto.ECDSA.verify(msgHashBuffer, signature, publicKey)
|
|
|
864
1002
|
|
|
865
1003
|
### What this library does **not** claim
|
|
866
1004
|
|
|
867
|
-
- It does not silently route every `verify()` call through `SmartVerify`. If you want the strict input validation on every verification, call `SmartVerify` explicitly or wrap `bsv.
|
|
868
|
-
- It
|
|
1005
|
+
- It does not silently route every `verify()` call through `SmartVerify`. If you want the strict input validation on every verification, call `SmartVerify` explicitly or wrap `bsv.crypto.ECDSA.prototype.verify`.
|
|
1006
|
+
- It no longer depends on `elliptic` at all. `lib/crypto/elliptic-fixed.js` keeps the name for API compatibility but is backed by `@noble/curves`; it adds input validation and low-`s` canonicalization on top of that.
|
|
869
1007
|
- It does not turn `bsv.isHardened = true` into an automatic guarantee. That property indicates the hardening helpers ship; whether they're used is up to your code.
|
|
870
1008
|
|
|
871
1009
|
v4.0.0 fixed three critical, exploitable vulnerabilities in the GDAF
|
|
@@ -881,23 +1019,27 @@ and [SECURITY.md](./SECURITY.md) for the supported-versions policy.
|
|
|
881
1019
|
## 📝 Changelog
|
|
882
1020
|
|
|
883
1021
|
The authoritative version history lives in [CHANGELOG.md](./CHANGELOG.md).
|
|
884
|
-
Highlights of the
|
|
885
|
-
|
|
886
|
-
- **[
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
- **[
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
- **[
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
1022
|
+
Highlights of the current line:
|
|
1023
|
+
|
|
1024
|
+
- **[8.3.0](./CHANGELOG.md#830---2026-08-16)** — BRC-220 **NotaryHash**:
|
|
1025
|
+
signed-hash notarization, SPV-verifiable certificates, a pluggable signature
|
|
1026
|
+
suite registry, and RFC 6962 Merkle trees for batch mode.
|
|
1027
|
+
- **[8.2.0](./CHANGELOG.md#820---2026-08-15)** — RFC 8785 (JCS) canonical JSON
|
|
1028
|
+
extracted to `lib/util/jcs.js`, so GDAF signatures verify under other
|
|
1029
|
+
implementations.
|
|
1030
|
+
- **[8.1.0](./CHANGELOG.md#810---2026-08-13)** — `useGenesisLimits()` edge-case
|
|
1031
|
+
fix.
|
|
1032
|
+
- **[8.0.0](./CHANGELOG.md#800---2026-08-13)** — **breaking.** Measured against
|
|
1033
|
+
the reference node's own consensus vectors (1483/1483, from an initial
|
|
1034
|
+
1426/1483 with 21 false accepts). `verify()` with no flags now means BSV
|
|
1035
|
+
mainnet; `SCRIPT_ENABLE_MONOLITH_OPCODES` and `SCRIPT_ENABLE_MAGNETIC_OPCODES`
|
|
1036
|
+
changed numeric value. See [Upgrading](#upgrading-to-v800-breaking-changes).
|
|
1037
|
+
- **[4.0.0](./CHANGELOG.md#400---2026-05-31)** — **security release.** Fixed
|
|
1038
|
+
three exploitable credential-verification flaws in GDAF/VC-JWT and removed a
|
|
1039
|
+
live mainnet WIF that shipped inside prior versions. All ≤ 3.4.5 should be
|
|
1040
|
+
considered untrustworthy.
|
|
1041
|
+
|
|
1042
|
+
Earlier entries are preserved in `CHANGELOG.md`.
|
|
901
1043
|
|
|
902
1044
|
---
|
|
903
1045
|
|
|
@@ -975,6 +1117,6 @@ For security vulnerabilities, follow the disclosure process in
|
|
|
975
1117
|
|
|
976
1118
|
---
|
|
977
1119
|
|
|
978
|
-
**SmartLedger-BSV
|
|
1120
|
+
**SmartLedger-BSV v8.3.1** — *Complete Bitcoin SV Development Framework*
|
|
979
1121
|
|
|
980
1122
|
Built with ❤️ for the Bitcoin SV ecosystem • 16 Loading Options • Interpreter-Verified Covenants
|