@smartledger/bsv 9.7.0 → 9.9.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 +217 -0
- package/README.md +19 -19
- package/bsv-gdaf.min.js +59 -59
- package/bsv-smartcontract.min.js +1 -1
- package/bsv.bundle.js +59 -59
- package/bsv.d.ts +642 -55
- package/bsv.min.js +59 -59
- package/docs/AUDIT_SCOPE.md +40 -14
- package/docs/BRC220_BATCH_LEAF_AMENDMENT.md +16 -6
- package/docs/BRC220_ENCODING_AMENDMENT.md +30 -91
- package/docs/BRC220_PLAN.md +39 -34
- package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
- package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
- package/docs/audit-rfq/cure53.txt +24 -10
- package/docs/audit-rfq/ncc-group.txt +24 -10
- package/docs/audit-rfq/trail-of-bits.txt +24 -10
- 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/docs/preimage.md +151 -87
- package/lib/notaryhash/certificate.js +524 -79
- package/lib/notaryhash/index.js +100 -71
- package/lib/notaryhash/merkle.js +94 -0
- package/lib/notaryhash/script.js +8 -1
- package/lib/notaryhash/suites.js +17 -14
- package/package.json +7 -3
- package/tools/gen-brc220-batch-vector.js +7 -3
- package/version.js +1 -1
|
@@ -15,9 +15,11 @@ seeking a quote for an independent security review of its cryptographic core.
|
|
|
15
15
|
|
|
16
16
|
Scope, and we would like these priced separately:
|
|
17
17
|
|
|
18
|
-
Tier 1 —
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
Tier 1 — 11,962 lines. Sighash construction and signing; ECDSA, nonce
|
|
19
|
+
derivation and signature encoding; the consensus-flag and era surface of the
|
|
20
|
+
script interpreter; BRC-220 signing; the covenant verification harness; RFC
|
|
21
|
+
8785 canonicalization; and the covenant-facing entrypoints of the smart
|
|
22
|
+
contract module.
|
|
21
23
|
|
|
22
24
|
Tier 2 — 1,607 lines. BIP-39 mnemonics, ECIES, and the Base58Check/varint
|
|
23
25
|
decoding surface.
|
|
@@ -25,18 +27,30 @@ Scope, and we would like these priced separately:
|
|
|
25
27
|
JavaScript (CommonJS), Node >= 20.19. The code is public.
|
|
26
28
|
|
|
27
29
|
Explicitly out of scope: elliptic-curve and hash primitives, which are supplied
|
|
28
|
-
by the Noble libraries and already audited;
|
|
29
|
-
|
|
30
|
-
|
|
30
|
+
by the Noble libraries and already audited; opcode EXECUTION in the script
|
|
31
|
+
interpreter, which passes 1,483 of 1,483 of the reference node's own consensus
|
|
32
|
+
vectors with zero false accepts and zero false rejects; and the remaining
|
|
33
|
+
26,077-line application layer (credentials, tokens, ordinals), which we would
|
|
34
|
+
treat as a separate engagement.
|
|
35
|
+
|
|
36
|
+
Note the shape of that first exclusion, because it is what we want priced. The
|
|
37
|
+
node's vectors each state their own flags, so they say nothing about which flags
|
|
38
|
+
or which consensus era a caller ends up with by DEFAULT. Every consensus defect
|
|
39
|
+
we have found has been in that selection rather than in the execution — the
|
|
40
|
+
corpus passed 1,483/1,483 before each fix and after it.
|
|
31
41
|
|
|
32
42
|
Context that should shorten discovery: the core is inherited from bitcore and
|
|
33
43
|
has been fixed reactively but never independently reviewed. We can provide a
|
|
34
44
|
test-backed threat model, a 452-case behavioural conformance corpus that a
|
|
35
45
|
second independent implementation agrees with, and a documented history of the
|
|
36
|
-
defects we have found ourselves.
|
|
37
|
-
|
|
38
|
-
The failure mode we most want examined is
|
|
39
|
-
|
|
46
|
+
ten defects we have found and fixed ourselves, with the module each was in.
|
|
47
|
+
|
|
48
|
+
The failure mode we most want examined is an exported security claim, its
|
|
49
|
+
default, and the test asserting it being wrong together, because all three were
|
|
50
|
+
written from the same assumption. Every one of our ten findings has had that
|
|
51
|
+
shape, and a file-by-file review would have found none of them. We would like
|
|
52
|
+
the statement of work to require checking claims against an independent oracle
|
|
53
|
+
or specification rather than against this repository's own tests.
|
|
40
54
|
|
|
41
55
|
Could you indicate availability, an approximate cost range, and what you would
|
|
42
56
|
need from us to firm that up?
|
|
@@ -15,9 +15,11 @@ seeking a quote for an independent security review of its cryptographic core.
|
|
|
15
15
|
|
|
16
16
|
Scope, and we would like these priced separately:
|
|
17
17
|
|
|
18
|
-
Tier 1 —
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
Tier 1 — 11,962 lines. Sighash construction and signing; ECDSA, nonce
|
|
19
|
+
derivation and signature encoding; the consensus-flag and era surface of the
|
|
20
|
+
script interpreter; BRC-220 signing; the covenant verification harness; RFC
|
|
21
|
+
8785 canonicalization; and the covenant-facing entrypoints of the smart
|
|
22
|
+
contract module.
|
|
21
23
|
|
|
22
24
|
Tier 2 — 1,607 lines. BIP-39 mnemonics, ECIES, and the Base58Check/varint
|
|
23
25
|
decoding surface.
|
|
@@ -25,18 +27,30 @@ Scope, and we would like these priced separately:
|
|
|
25
27
|
JavaScript (CommonJS), Node >= 20.19. The code is public.
|
|
26
28
|
|
|
27
29
|
Explicitly out of scope: elliptic-curve and hash primitives, which are supplied
|
|
28
|
-
by the Noble libraries and already audited;
|
|
29
|
-
|
|
30
|
-
|
|
30
|
+
by the Noble libraries and already audited; opcode EXECUTION in the script
|
|
31
|
+
interpreter, which passes 1,483 of 1,483 of the reference node's own consensus
|
|
32
|
+
vectors with zero false accepts and zero false rejects; and the remaining
|
|
33
|
+
26,077-line application layer (credentials, tokens, ordinals), which we would
|
|
34
|
+
treat as a separate engagement.
|
|
35
|
+
|
|
36
|
+
Note the shape of that first exclusion, because it is what we want priced. The
|
|
37
|
+
node's vectors each state their own flags, so they say nothing about which flags
|
|
38
|
+
or which consensus era a caller ends up with by DEFAULT. Every consensus defect
|
|
39
|
+
we have found has been in that selection rather than in the execution — the
|
|
40
|
+
corpus passed 1,483/1,483 before each fix and after it.
|
|
31
41
|
|
|
32
42
|
Context that should shorten discovery: the core is inherited from bitcore and
|
|
33
43
|
has been fixed reactively but never independently reviewed. We can provide a
|
|
34
44
|
test-backed threat model, a 452-case behavioural conformance corpus that a
|
|
35
45
|
second independent implementation agrees with, and a documented history of the
|
|
36
|
-
defects we have found ourselves.
|
|
37
|
-
|
|
38
|
-
The failure mode we most want examined is
|
|
39
|
-
|
|
46
|
+
ten defects we have found and fixed ourselves, with the module each was in.
|
|
47
|
+
|
|
48
|
+
The failure mode we most want examined is an exported security claim, its
|
|
49
|
+
default, and the test asserting it being wrong together, because all three were
|
|
50
|
+
written from the same assumption. Every one of our ten findings has had that
|
|
51
|
+
shape, and a file-by-file review would have found none of them. We would like
|
|
52
|
+
the statement of work to require checking claims against an independent oracle
|
|
53
|
+
or specification rather than against this repository's own tests.
|
|
40
54
|
|
|
41
55
|
Could you indicate availability, an approximate cost range, and what you would
|
|
42
56
|
need from us to firm that up?
|
|
@@ -48,7 +48,7 @@ const tx: Transaction = new Transaction();
|
|
|
48
48
|
#### **Core Library Only (937KB)**
|
|
49
49
|
For basic Bitcoin SV operations:
|
|
50
50
|
```html
|
|
51
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
51
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js"></script>
|
|
52
52
|
<script>
|
|
53
53
|
const privateKey = new bsv.PrivateKey();
|
|
54
54
|
const address = privateKey.toAddress();
|
|
@@ -58,7 +58,7 @@ For basic Bitcoin SV operations:
|
|
|
58
58
|
#### **Complete Bundle (937KB)**
|
|
59
59
|
Everything in one file:
|
|
60
60
|
```html
|
|
61
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
61
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.bundle.js"></script>
|
|
62
62
|
<script>
|
|
63
63
|
// All features available immediately
|
|
64
64
|
const shares = bsv.splitSecret('secret', 5, 3);
|
|
@@ -71,9 +71,9 @@ Everything in one file:
|
|
|
71
71
|
|
|
72
72
|
#### **Smart Contract Development (~2.7MB total — each bundle is self-contained and re-embeds core BSV)**
|
|
73
73
|
```html
|
|
74
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
75
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
76
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
74
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js"></script>
|
|
75
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-covenant.min.js"></script>
|
|
76
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-smartcontract.min.js"></script>
|
|
77
77
|
<script>
|
|
78
78
|
const covenant = bsv.SmartContract.createCovenantBuilder()
|
|
79
79
|
.extractField('amount').push(50000).greaterThanOrEqual().build();
|
|
@@ -82,9 +82,9 @@ Everything in one file:
|
|
|
82
82
|
|
|
83
83
|
#### **Legal & Identity Development (~3.2MB total — each bundle is self-contained and re-embeds core BSV)**
|
|
84
84
|
```html
|
|
85
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
86
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
87
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
85
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js"></script>
|
|
86
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-ltp.min.js"></script>
|
|
87
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-gdaf.min.js"></script>
|
|
88
88
|
<script>
|
|
89
89
|
// Legal Token Protocol
|
|
90
90
|
const propertyToken = bsv.createPropertyToken({
|
|
@@ -98,9 +98,9 @@ Everything in one file:
|
|
|
98
98
|
|
|
99
99
|
#### **Security & Cryptography (~1.4MB total — each bundle is self-contained and re-embeds core BSV)**
|
|
100
100
|
```html
|
|
101
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
102
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
103
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
101
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js"></script>
|
|
102
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-security.min.js"></script>
|
|
103
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-shamir.min.js"></script>
|
|
104
104
|
<script>
|
|
105
105
|
// Threshold Cryptography
|
|
106
106
|
const shares = bsv.splitSecret('my_secret_key', 5, 3);
|
|
@@ -114,18 +114,18 @@ Everything in one file:
|
|
|
114
114
|
|
|
115
115
|
| Module | Size | Purpose | CDN Link |
|
|
116
116
|
|--------|------|---------|----------|
|
|
117
|
-
| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.
|
|
118
|
-
| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.
|
|
119
|
-
| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.
|
|
120
|
-
| **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@9.
|
|
121
|
-
| **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@9.
|
|
122
|
-
| **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@9.
|
|
123
|
-
| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@9.
|
|
124
|
-
| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@9.
|
|
125
|
-
| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@9.
|
|
126
|
-
| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.
|
|
127
|
-
| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.
|
|
128
|
-
| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@9.
|
|
117
|
+
| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js` |
|
|
118
|
+
| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.9.0/bsv.bundle.js` |
|
|
119
|
+
| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.9.0/bsv-smartcontract.min.js` |
|
|
120
|
+
| **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@9.9.0/bsv-ltp.min.js` |
|
|
121
|
+
| **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@9.9.0/bsv-gdaf.min.js` |
|
|
122
|
+
| **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@9.9.0/bsv-shamir.min.js` |
|
|
123
|
+
| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@9.9.0/bsv-security.min.js` |
|
|
124
|
+
| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@9.9.0/bsv-mnemonic.min.js` |
|
|
125
|
+
| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@9.9.0/bsv-ecies.min.js` |
|
|
126
|
+
| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.9.0/bsv-covenant.min.js` |
|
|
127
|
+
| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.9.0/bsv-script-helper.min.js` |
|
|
128
|
+
| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@9.9.0/bsv-message.min.js` |
|
|
129
129
|
|
|
130
130
|
## ⚙️ **Development Environment Setup**
|
|
131
131
|
|
|
@@ -14,10 +14,10 @@ npm install @smartledger/bsv
|
|
|
14
14
|
### Browser CDN (Instant)
|
|
15
15
|
```html
|
|
16
16
|
<!-- Core library (937KB) -->
|
|
17
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
17
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js"></script>
|
|
18
18
|
|
|
19
19
|
<!-- Everything included (937KB) -->
|
|
20
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
20
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.bundle.js"></script>
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
## 💰 **Your First Transaction (60 seconds)**
|
|
@@ -127,19 +127,19 @@ SmartLedger-BSV offers 12 different loading options - use only what you need:
|
|
|
127
127
|
|
|
128
128
|
```html
|
|
129
129
|
<!-- Core BSV only (937KB) -->
|
|
130
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
130
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js"></script>
|
|
131
131
|
|
|
132
132
|
<!-- Smart contracts (937KB) -->
|
|
133
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
133
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-smartcontract.min.js"></script>
|
|
134
134
|
|
|
135
135
|
<!-- Legal tokens (1.16MB) -->
|
|
136
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
136
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-ltp.min.js"></script>
|
|
137
137
|
|
|
138
138
|
<!-- Digital identity (1.16MB) -->
|
|
139
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
139
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-gdaf.min.js"></script>
|
|
140
140
|
|
|
141
141
|
<!-- Everything (937KB) -->
|
|
142
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
142
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.bundle.js"></script>
|
|
143
143
|
```
|
|
144
144
|
|
|
145
145
|
## ⚡ **Key Advantages**
|
|
@@ -159,17 +159,17 @@ const recovered = bsv.reconstructSecret([shares[0], shares[2], shares[4]]);
|
|
|
159
159
|
### **New Modular Options**
|
|
160
160
|
```html
|
|
161
161
|
<!-- Core compatibility (same size as bsv@1.5.6) -->
|
|
162
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
162
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js"></script>
|
|
163
163
|
|
|
164
164
|
<!-- Add smart contracts when ready -->
|
|
165
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
165
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-smartcontract.min.js"></script>
|
|
166
166
|
|
|
167
167
|
<!-- Add advanced features as needed -->
|
|
168
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
169
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
168
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-ltp.min.js"></script>
|
|
169
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv-gdaf.min.js"></script>
|
|
170
170
|
|
|
171
171
|
<!-- Everything in one file -->
|
|
172
|
-
<script src="https://unpkg.com/@smartledger/bsv@9.
|
|
172
|
+
<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.bundle.js"></script>
|
|
173
173
|
```
|
|
174
174
|
|
|
175
175
|
## 🔍 **Testing Your Migration**
|
package/docs/preimage.md
CHANGED
|
@@ -1,126 +1,190 @@
|
|
|
1
|
-
|
|
1
|
+
# The BIP-143 sighash preimage
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The preimage is the byte string that is double-SHA256'd and then signed. Its layout is
|
|
4
|
+
what makes covenants possible on BSV: a script that can prove it was handed *this*
|
|
5
|
+
transaction's preimage can read the transaction's own fields out of it, which is why
|
|
6
|
+
BSV needs no `OP_TXLOCKTIME` or `OP_INPUTVALUE` opcode.
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
Every offset and every script fragment on this page is asserted in
|
|
9
|
+
`test/covenant/preimage_doc.js` against a preimage this library actually produces. If
|
|
10
|
+
you change the layout, that test fails before this page goes stale.
|
|
6
11
|
|
|
7
|
-
|
|
8
|
-
|
|
12
|
+
> **Two digest algorithms, not one.** BIP-143 with `SIGHASH_FORKID` is what this page
|
|
13
|
+
> describes and what almost everything uses. Chronicle restored the **Original
|
|
14
|
+
> Transaction Digest Algorithm**, selected by `SIGHASH_CHRONICLE` (`0x20`), which has a
|
|
15
|
+
> different layout entirely — see `Signature.SIGHASH_CHRONICLE` and
|
|
16
|
+
> `lib/transaction/sighash.js`. Do not assume a signature is BIP-143 without checking
|
|
17
|
+
> its sighash byte.
|
|
9
18
|
|
|
10
19
|
---
|
|
11
20
|
|
|
12
|
-
##
|
|
13
|
-
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
|
|
|
19
|
-
|
|
|
20
|
-
|
|
|
21
|
-
|
|
|
22
|
-
|
|
|
23
|
-
|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
21
|
+
## Field layout
|
|
22
|
+
|
|
23
|
+
| # | Field | Bytes | Encoding |
|
|
24
|
+
| --: | --- | --: | --- |
|
|
25
|
+
| 1 | `nVersion` | 4 | little-endian int32 |
|
|
26
|
+
| 2 | `hashPrevouts` | 32 | HASH256 digest, as the hash function returns it |
|
|
27
|
+
| 3 | `hashSequence` | 32 | HASH256 digest, as the hash function returns it |
|
|
28
|
+
| 4 | `outpoint` | 36 | 32-byte txid in **serialized order** + 4-byte LE index |
|
|
29
|
+
| 5 | `scriptCode` | varint + N | length prefix then the script |
|
|
30
|
+
| 6 | `amount` | 8 | little-endian **uint64** — satoshis in the output being spent |
|
|
31
|
+
| 7 | `nSequence` | 4 | little-endian **uint32** |
|
|
32
|
+
| 8 | `hashOutputs` | 32 | HASH256 digest, as the hash function returns it |
|
|
33
|
+
| 9 | `nLockTime` | 4 | little-endian **uint32** |
|
|
34
|
+
| 10 | `sighashType` | 4 | little-endian uint32 (`0x41` for `ALL｜FORKID`) |
|
|
35
|
+
|
|
36
|
+
**The three 32-byte hashes have no endianness worth naming.** They are the bytes
|
|
37
|
+
`HASH256()` returns, inserted as-is. Calling them "big-endian" invites someone to
|
|
38
|
+
reverse them; the only field in the preimage that is genuinely reversed relative to how
|
|
39
|
+
you normally read it is the **txid inside the outpoint**, which appears here in
|
|
40
|
+
serialized order — the reverse of the string an explorer shows.
|
|
41
|
+
|
|
42
|
+
### Length
|
|
27
43
|
|
|
28
|
-
|
|
44
|
+
```
|
|
45
|
+
4 + 32 + 32 + 36 + 8 + 4 + 32 + 4 + 4 = 156 fixed bytes
|
|
46
|
+
+ varint(len(scriptCode)) + len(scriptCode)
|
|
47
|
+
```
|
|
29
48
|
|
|
30
|
-
|
|
49
|
+
A 25-byte P2PKH `scriptCode` needs a 1-byte length prefix, so the whole preimage is
|
|
50
|
+
**182 bytes** — not ~108, and not 181. There is no "typical" length beyond that,
|
|
51
|
+
because `scriptCode` is whatever locking script is being spent.
|
|
52
|
+
|
|
53
|
+
### Offsets, for a 25-byte scriptCode
|
|
54
|
+
|
|
55
|
+
| Field | From start | From end |
|
|
56
|
+
| --- | --: | --: |
|
|
57
|
+
| `nVersion` | 0 | — |
|
|
58
|
+
| `hashPrevouts` | 4 | — |
|
|
59
|
+
| `hashSequence` | 36 | — |
|
|
60
|
+
| `outpoint` | 68 | — |
|
|
61
|
+
| `scriptCode` (len + data) | 104 | — |
|
|
62
|
+
| `amount` | 130 | **52** |
|
|
63
|
+
| `nSequence` | 138 | **44** |
|
|
64
|
+
| `hashOutputs` | 142 | **40** |
|
|
65
|
+
| `nLockTime` | 174 | **8** |
|
|
66
|
+
| `sighashType` | 178 | **4** |
|
|
67
|
+
|
|
68
|
+
**Use the from-end column in scripts.** Everything before `amount` sits behind a
|
|
69
|
+
variable-length `scriptCode`, so its absolute offset changes with the contract. The
|
|
70
|
+
five tail fields are at fixed distances from the end whatever the script contains,
|
|
71
|
+
which is why every extraction this library ships is written with `OP_RIGHT`.
|
|
31
72
|
|
|
32
|
-
|
|
73
|
+
---
|
|
33
74
|
|
|
34
|
-
|
|
35
|
-
| ----------------------- | ------------- | ------------------------ |
|
|
36
|
-
| nVersion | 4 | `01000000` |
|
|
37
|
-
| hashPrevouts | 32 | `e3...4a` |
|
|
38
|
-
| hashSequence | 32 | `00...00` |
|
|
39
|
-
| outpoint | 36 | `00..00 00000000` |
|
|
40
|
-
| scriptCode (len + data) | 25 | `1976a914...88ac` |
|
|
41
|
-
| amount | 8 | `1027000000000000` |
|
|
42
|
-
| nSequence | 4 | `ffffffff` |
|
|
43
|
-
| hashOutputs | 32 | `d2...1e` |
|
|
44
|
-
| nLockTime | 4 | `e8030000` *(= 1000 LE)* |
|
|
45
|
-
| sighashType | 4 | `41000000` *(= 0x41)* |
|
|
75
|
+
## When the hashes are zero
|
|
46
76
|
|
|
47
|
-
|
|
77
|
+
`hashPrevouts`, `hashSequence` and `hashOutputs` are not always populated. Measured:
|
|
48
78
|
|
|
49
|
-
|
|
79
|
+
| Sighash type | `hashPrevouts` | `hashSequence` | `hashOutputs` |
|
|
80
|
+
| --- | --- | --- | --- |
|
|
81
|
+
| `ALL｜FORKID` (`0x41`) | set | set | set |
|
|
82
|
+
| `NONE｜FORKID` (`0x42`) | set | **zero** | **zero** |
|
|
83
|
+
| `SINGLE｜FORKID` (`0x43`) | set | **zero** | set (the one matching output) |
|
|
84
|
+
| `ALL｜ANYONECANPAY｜FORKID` (`0xc1`) | **zero** | **zero** | set |
|
|
85
|
+
| `SINGLE｜ANYONECANPAY｜FORKID` (`0xc3`) | **zero** | **zero** | set |
|
|
50
86
|
|
|
51
|
-
|
|
52
|
-
|
|
87
|
+
A covenant that reads `hashOutputs` is only meaningful if it *also* pins the sighash
|
|
88
|
+
type — otherwise a spender signs with `NONE` and the field it is checking is 32 zero
|
|
89
|
+
bytes. `PushTx.assertSighashType()` exists for that.
|
|
53
90
|
|
|
54
91
|
---
|
|
55
92
|
|
|
56
|
-
##
|
|
93
|
+
## Reading fields in Script
|
|
57
94
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
95
|
+
`OP_RIGHT n` keeps the last `n` bytes; `OP_LEFT n` keeps the first `n`. Together they
|
|
96
|
+
take a window at a fixed distance from the end. These are the fragments this library
|
|
97
|
+
ships:
|
|
61
98
|
|
|
62
|
-
|
|
99
|
+
| Field | Script |
|
|
100
|
+
| --- | --- |
|
|
101
|
+
| `sighashType` | `OP_DUP 4 OP_RIGHT` |
|
|
102
|
+
| `nLockTime` | `OP_DUP 8 OP_RIGHT 4 OP_LEFT` |
|
|
103
|
+
| `hashOutputs` | `OP_DUP 40 OP_RIGHT 32 OP_LEFT` |
|
|
104
|
+
| `nSequence` | `OP_DUP 44 OP_RIGHT 4 OP_LEFT` |
|
|
105
|
+
| `amount` | `OP_DUP 52 OP_RIGHT 8 OP_LEFT` |
|
|
106
|
+
| `nVersion` | `OP_DUP 4 OP_LEFT` |
|
|
107
|
+
|
|
108
|
+
`OP_DUP` first, because these consume the preimage and you usually want it back.
|
|
109
|
+
|
|
110
|
+
### `OP_BIN2NUM` will silently corrupt three of these
|
|
63
111
|
|
|
64
|
-
|
|
112
|
+
`amount`, `nSequence` and `nLockTime` are **unsigned**. `OP_BIN2NUM` produces a
|
|
113
|
+
**signed** script number. Feeding a raw field straight into it is wrong, and wrong in
|
|
114
|
+
the direction that fails quietly:
|
|
65
115
|
|
|
66
116
|
```
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
[0064-007e] script length + scriptPubKey (varies)
|
|
73
|
-
[007f-0086] amount (8 LE)
|
|
74
|
-
[0087-008a] nSequence (4 LE)
|
|
75
|
-
[008b-00aa] hashOutputs (32)
|
|
76
|
-
[00ab-00ae] nLockTime (4 LE)
|
|
77
|
-
[00af-00b2] sighashType (4 LE)
|
|
117
|
+
nLockTime e8030000 -> 1000 correct
|
|
118
|
+
ffffff7f -> 2147483647 correct — last value before the sign bit
|
|
119
|
+
00000080 -> 0 WRONG, should be 2147483648 (19 Jan 2038)
|
|
120
|
+
01000080 -> -1 WRONG, should be 2147483649
|
|
121
|
+
ffffffff -> -2147483647 WRONG, should be 4294967295 (year 2106)
|
|
78
122
|
```
|
|
79
123
|
|
|
80
|
-
|
|
124
|
+
A `nLockTime >= deadline` check written this way stops working on **19 January 2038**,
|
|
125
|
+
and a `<=` check starts passing when it should not. The same applies to `amount` above
|
|
126
|
+
2³¹ satoshis (21.47 BSV) and to `nSequence` above `0x7fffffff` — which includes
|
|
127
|
+
`0xffffffff`, the most common value there is.
|
|
81
128
|
|
|
82
|
-
|
|
129
|
+
**Sign-pad with a zero byte first:**
|
|
83
130
|
|
|
84
|
-
|
|
131
|
+
```
|
|
132
|
+
OP_DUP 8 OP_RIGHT 4 OP_LEFT <00> OP_CAT OP_BIN2NUM
|
|
133
|
+
```
|
|
85
134
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
135
|
+
```
|
|
136
|
+
nLockTime 00000080 -> 2147483648 correct
|
|
137
|
+
ffffffff -> 4294967295 correct
|
|
138
|
+
e8030000 -> 1000 correct — OP_BIN2NUM re-minimises the pad
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
That five-byte push is only legal because `OP_BIN2NUM` honours the era's script-number
|
|
142
|
+
width — 4 bytes before Genesis, 750,000 after, 32,000,000 after Chronicle. Verify with
|
|
143
|
+
`Interpreter.mainnetFlags()` or no flags at all; a hand-assembled flag word with no era
|
|
144
|
+
bit applies the 4-byte pre-Genesis cap and rejects the padded value.
|
|
92
145
|
|
|
93
146
|
---
|
|
94
147
|
|
|
95
|
-
##
|
|
148
|
+
## Hashing the preimage does not authenticate it
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
<preimage> OP_HASH256
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
gives you `HASH256(preimage)` and **nothing else**. It does not establish that the
|
|
155
|
+
bytes on the stack are this transaction's preimage. A spender can hand you any
|
|
156
|
+
well-formed 182 bytes, satisfy every field check you wrote, and spend the output on a
|
|
157
|
+
transaction that does something entirely different.
|
|
96
158
|
|
|
97
|
-
The
|
|
98
|
-
|
|
159
|
+
The binding has to come from a signature check. `OP_PUSH_TX` — `lib/covenant/pushtx.js`
|
|
160
|
+
— gets it by constructing a signature *from the preimage hash itself* and verifying it
|
|
161
|
+
with `OP_CHECKSIG` against the generator point:
|
|
99
162
|
|
|
100
163
|
```
|
|
101
|
-
|
|
164
|
+
OP_HASH256 z = HASH256(preimage)
|
|
165
|
+
<reverse to LE> e
|
|
166
|
+
<Gx> OP_ADD <n> OP_MOD s = (e + Gx) mod n
|
|
167
|
+
<assemble DER: r = Gx, s> a signature that is valid for P = G
|
|
168
|
+
only if e is this input's sighash
|
|
169
|
+
<02||Gx> OP_CHECKSIG the node checks it against the REAL sighash
|
|
102
170
|
```
|
|
103
171
|
|
|
104
|
-
|
|
172
|
+
`OP_CHECKSIG` computes the sighash itself, from the transaction being validated. The
|
|
173
|
+
signature only verifies if the `e` derived from the supplied preimage equals it. That
|
|
174
|
+
is the whole trick, and it is the step that makes every field check downstream mean
|
|
175
|
+
something.
|
|
105
176
|
|
|
106
|
-
|
|
107
|
-
|
|
177
|
+
Use `PushTx.pushTxCore()` or `SmartContract.policy()` rather than assembling this by
|
|
178
|
+
hand.
|
|
108
179
|
|
|
109
180
|
---
|
|
110
181
|
|
|
111
|
-
##
|
|
112
|
-
|
|
113
|
-
| Field | Bytes | Endian | Covenant Extraction Example |
|
|
114
|
-
| ------------ | -------- | ------ | ------------------------------------------------------- |
|
|
115
|
-
| nVersion | 4 | LE | `4 OP_SPLIT OP_DROP OP_BIN2NUM` |
|
|
116
|
-
| hashPrevouts | 32 | — | `36 OP_SPLIT ...` |
|
|
117
|
-
| hashSequence | 32 | — | next 32 |
|
|
118
|
-
| outpoint | 36 | mixed | — |
|
|
119
|
-
| scriptCode | variable | — | rarely enforced directly |
|
|
120
|
-
| amount | 8 | LE | `40 OP_SPLIT OP_NIP 8 OP_SPLIT OP_DROP OP_BIN2NUM` |
|
|
121
|
-
| nSequence | 4 | LE | `12 OP_SPLIT OP_NIP 4 OP_SPLIT OP_DROP OP_BIN2NUM` |
|
|
122
|
-
| hashOutputs | 32 | — | — |
|
|
123
|
-
| nLockTime | 4 | LE | `<len-8> OP_SPLIT OP_NIP 4 OP_SPLIT OP_DROP OP_BIN2NUM` |
|
|
124
|
-
| sighashType | 4 | LE | `<len-4> OP_SPLIT OP_NIP OP_BIN2NUM` |
|
|
182
|
+
## `scriptCode` is not "the scriptPubKey"
|
|
125
183
|
|
|
126
|
-
|
|
184
|
+
It is the script the signature commits to. For a plain P2PKH spend that happens to be
|
|
185
|
+
the 25-byte locking script, but nothing in the format requires it: it is
|
|
186
|
+
length-prefixed and variable, `OP_CODESEPARATOR` changes where it starts, and for the
|
|
187
|
+
covenants this library builds it is hundreds of bytes.
|
|
188
|
+
|
|
189
|
+
Any parser that assumes 25 bytes, or that reads fields at absolute offsets past the
|
|
190
|
+
`scriptCode`, breaks on the first real contract. Read from the end.
|