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