@smartledger/bsv 9.6.0 → 9.8.0

package/docs/preimage.md

@@ -1,126 +1,190 @@
-Excellent — here’s the **definitive, detailed breakdown** of a **Bitcoin (BSV) sighash preimage**, field by field, based on **BIP143** (which all modern BSV libraries, including SmartLedger’s hardened bundle, follow exactly).
+# The BIP-143 sighash preimage
 
----
+The preimage is the byte string that is double-SHA256'd and then signed. Its layout is
+what makes covenants possible on BSV: a script that can prove it was handed *this*
+transaction's preimage can read the transaction's own fields out of it, which is why
+BSV needs no `OP_TXLOCKTIME` or `OP_INPUTVALUE` opcode.
 
-# 🔍 **Bitcoin SV Sighash Preimage Structure (BIP143 / ForkID)**
+Every offset and every script fragment on this page is asserted in
+`test/covenant/preimage_doc.js` against a preimage this library actually produces. If
+you change the layout, that test fails before this page goes stale.
 
-The *preimage* is the exact data that gets double-SHA256 hashed before signing a transaction input with `SIGHASH_FORKID`.
-This deterministic byte layout ensures signatures are reproducible and verifiable.
+> **Two digest algorithms, not one.** BIP-143 with `SIGHASH_FORKID` is what this page
+> describes and what almost everything uses. Chronicle restored the **Original
+> Transaction Digest Algorithm**, selected by `SIGHASH_CHRONICLE` (`0x20`), which has a
+> different layout entirely — see `Signature.SIGHASH_CHRONICLE` and
+> `lib/transaction/sighash.js`. Do not assume a signature is BIP-143 without checking
+> its sighash byte.
 
 ---
 
-## 🧩 **Overview**
-
-| Section                       | Bytes        | Endianness          | Description                                |          |
-| ----------------------------- | ------------ | ------------------- | ------------------------------------------ | -------- |
-| **1. nVersion**               | 4            | Little-Endian (LE)  | Transaction version field                  |          |
-| **2. hashPrevouts**           | 32           |                     | SHA256d of all input outpoints             |          |
-| **3. hashSequence**           | 32           |                     | SHA256d of all input sequences             |          |
-| **4. outpoint (txid + vout)** | 36           | txid: LE, index: LE | The outpoint being signed                  |          |
-| **5. scriptCode length**      | 1–3 (varint) |                     | Compact size of the script being signed    |          |
-| **6. scriptCode**             | variable     |                     | The actual script (usually `scriptPubKey`) |          |
-| **7. amount**                 | 8            | Little-Endian       | Value of the output being spent            |          |
-| **8. nSequence**              | 4            | Little-Endian       | Sequence number of this input              |          |
-| **9. hashOutputs**            | 32           |                     | SHA256d of all outputs                     |          |
-| **10. nLockTime**             | 4            | Little-Endian       | Locktime for entire tx                     |          |
-| **11. sighashType**           | 4            | Little-Endian       | SIGHASH type used (e.g., `0x41` for `ALL   | FORKID`) |
+## Field layout
+
+| # | Field | Bytes | Encoding |
+| --: | --- | --: | --- |
+| 1 | `nVersion` | 4 | little-endian int32 |
+| 2 | `hashPrevouts` | 32 | HASH256 digest, as the hash function returns it |
+| 3 | `hashSequence` | 32 | HASH256 digest, as the hash function returns it |
+| 4 | `outpoint` | 36 | 32-byte txid in **serialized order** + 4-byte LE index |
+| 5 | `scriptCode` | varint + N | length prefix then the script |
+| 6 | `amount` | 8 | little-endian **uint64** — satoshis in the output being spent |
+| 7 | `nSequence` | 4 | little-endian **uint32** |
+| 8 | `hashOutputs` | 32 | HASH256 digest, as the hash function returns it |
+| 9 | `nLockTime` | 4 | little-endian **uint32** |
+| 10 | `sighashType` | 4 | little-endian uint32 (`0x41` for `ALL｜FORKID`) |
+
+**The three 32-byte hashes have no endianness worth naming.** They are the bytes
+`HASH256()` returns, inserted as-is. Calling them "big-endian" invites someone to
+reverse them; the only field in the preimage that is genuinely reversed relative to how
+you normally read it is the **txid inside the outpoint**, which appears here in
+serialized order — the reverse of the string an explorer shows.
+
+### Length
 
----
+```
+4 + 32 + 32 + 36 + 8 + 4 + 32 + 4 + 4  =  156 fixed bytes
+                    + varint(len(scriptCode)) + len(scriptCode)
+```
 
-## 📏 **Typical Length Example**
+A 25-byte P2PKH `scriptCode` needs a 1-byte length prefix, so the whole preimage is
+**182 bytes** — not ~108, and not 181. There is no "typical" length beyond that,
+because `scriptCode` is whatever locking script is being spent.
+
+### Offsets, for a 25-byte scriptCode
+
+| Field | From start | From end |
+| --- | --: | --: |
+| `nVersion` | 0 | — |
+| `hashPrevouts` | 4 | — |
+| `hashSequence` | 36 | — |
+| `outpoint` | 68 | — |
+| `scriptCode` (len + data) | 104 | — |
+| `amount` | 130 | **52** |
+| `nSequence` | 138 | **44** |
+| `hashOutputs` | 142 | **40** |
+| `nLockTime` | 174 | **8** |
+| `sighashType` | 178 | **4** |
+
+**Use the from-end column in scripts.** Everything before `amount` sits behind a
+variable-length `scriptCode`, so its absolute offset changes with the contract. The
+five tail fields are at fixed distances from the end whatever the script contains,
+which is why every extraction this library ships is written with `OP_RIGHT`.
 
-For a *simple single-input, single-output* transaction:
+---
 
-| Section                 | Typical Bytes | Example Hex Segment      |
-| ----------------------- | ------------- | ------------------------ |
-| nVersion                | 4             | `01000000`               |
-| hashPrevouts            | 32            | `e3...4a`                |
-| hashSequence            | 32            | `00...00`                |
-| outpoint                | 36            | `00..00 00000000`        |
-| scriptCode (len + data) | 25            | `1976a914...88ac`        |
-| amount                  | 8             | `1027000000000000`       |
-| nSequence               | 4             | `ffffffff`               |
-| hashOutputs             | 32            | `d2...1e`                |
-| nLockTime               | 4             | `e8030000` *(= 1000 LE)* |
-| sighashType             | 4             | `41000000` *(= 0x41)*    |
+## When the hashes are zero
 
----
+`hashPrevouts`, `hashSequence` and `hashOutputs` are not always populated. Measured:
 
-### 🧮 **Total: ~108 bytes**
+| Sighash type | `hashPrevouts` | `hashSequence` | `hashOutputs` |
+| --- | --- | --- | --- |
+| `ALL｜FORKID` (`0x41`) | set | set | set |
+| `NONE｜FORKID` (`0x42`) | set | **zero** | **zero** |
+| `SINGLE｜FORKID` (`0x43`) | set | **zero** | set (the one matching output) |
+| `ALL｜ANYONECANPAY｜FORKID` (`0xc1`) | **zero** | **zero** | set |
+| `SINGLE｜ANYONECANPAY｜FORKID` (`0xc3`) | **zero** | **zero** | set |
 
-(4 + 32 + 32 + 36 + 25 + 8 + 4 + 32 + 4 + 4 = 181, but since script length and varints can vary,
-the final preimage for a minimal transaction typically is **~108 bytes**.)
+A covenant that reads `hashOutputs` is only meaningful if it *also* pins the sighash
+type — otherwise a spender signs with `NONE` and the field it is checking is 32 zero
+bytes. `PushTx.assertSighashType()` exists for that.
 
 ---
 
-## 🧠 **Endianness Notes**
+## Reading fields in Script
 
-* **nVersion, amount, nSequence, nLockTime, sighashType** are *little-endian* integers.
-* **hashPrevouts, hashSequence, hashOutputs** are *big-endian* SHA256d hashes (32 bytes each).
-* **txid** inside the *outpoint* is *little-endian* (it’s reversed from what’s printed on explorers).
+`OP_RIGHT n` keeps the last `n` bytes; `OP_LEFT n` keeps the first `n`. Together they
+take a window at a fixed distance from the end. These are the fragments this library
+ships:
 
----
+| Field | Script |
+| --- | --- |
+| `sighashType` | `OP_DUP 4 OP_RIGHT` |
+| `nLockTime` | `OP_DUP 8 OP_RIGHT 4 OP_LEFT` |
+| `hashOutputs` | `OP_DUP 40 OP_RIGHT 32 OP_LEFT` |
+| `nSequence` | `OP_DUP 44 OP_RIGHT 4 OP_LEFT` |
+| `amount` | `OP_DUP 52 OP_RIGHT 8 OP_LEFT` |
+| `nVersion` | `OP_DUP 4 OP_LEFT` |
+
+`OP_DUP` first, because these consume the preimage and you usually want it back.
+
+### `OP_BIN2NUM` will silently corrupt three of these
 
-## 🧩 **Visual Layout Example**
+`amount`, `nSequence` and `nLockTime` are **unsigned**. `OP_BIN2NUM` produces a
+**signed** script number. Feeding a raw field straight into it is wrong, and wrong in
+the direction that fails quietly:
 
 ```
-[0000-0003] nVersion (4 LE)
-[0004-0023] hashPrevouts (32)
-[0024-0043] hashSequence (32)
-[0044-005f] outpoint.txid (32 LE)
-[0060-0063] outpoint.vout (4 LE)
-[0064-007e] script length + scriptPubKey (varies)
-[007f-0086] amount (8 LE)
-[0087-008a] nSequence (4 LE)
-[008b-00aa] hashOutputs (32)
-[00ab-00ae] nLockTime (4 LE)
-[00af-00b2] sighashType (4 LE)
+nLockTime   e8030000  ->           1000     correct
+            ffffff7f  ->     2147483647     correct — last value before the sign bit
+            00000080  ->              0     WRONG, should be 2147483648 (19 Jan 2038)
+            01000080  ->             -1     WRONG, should be 2147483649
+            ffffffff  ->    -2147483647     WRONG, should be 4294967295 (year 2106)
 ```
 
----
+A `nLockTime >= deadline` check written this way stops working on **19 January 2038**,
+and a `<=` check starts passing when it should not. The same applies to `amount` above
+2³¹ satoshis (21.47 BSV) and to `nSequence` above `0x7fffffff` — which includes
+`0xffffffff`, the most common value there is.
 
-## ⚙️ **In Script Context (OP_SPLIT / Covenant Use)**
+**Sign-pad with a zero byte first:**
 
-If you push the **raw preimage** onto the stack, you can target sections as follows:
+```
+OP_DUP 8 OP_RIGHT 4 OP_LEFT   <00> OP_CAT   OP_BIN2NUM
+```
 
-| Target           | Extraction Logic                             | Example ASM                                             |
-| ---------------- | -------------------------------------------- | ------------------------------------------------------- |
-| **nVersion**     | First 4 bytes                                | `4 OP_SPLIT OP_DROP OP_BIN2NUM`                         |
-| **nLockTime**    | 8 bytes from end → drop last 4 (sighashType) | `<len-8> OP_SPLIT OP_NIP 4 OP_SPLIT OP_DROP OP_BIN2NUM` |
-| **hashPrevouts** | 32 bytes after first 4                       | `4 OP_SPLIT OP_DROP 32 OP_SPLIT OP_DROP`                |
-| **hashOutputs**  | 8+4+32 from end (44 bytes from tail)         | `<len-44> OP_SPLIT OP_NIP 32 OP_SPLIT OP_DROP`          |
+```
+nLockTime   00000080  ->     2147483648     correct
+            ffffffff  ->     4294967295     correct
+            e8030000  ->           1000     correct — OP_BIN2NUM re-minimises the pad
+```
+
+That five-byte push is only legal because `OP_BIN2NUM` honours the era's script-number
+width — 4 bytes before Genesis, 750,000 after, 32,000,000 after Chronicle. Verify with
+`Interpreter.mainnetFlags()` or no flags at all; a hand-assembled flag word with no era
+bit applies the 4-byte pre-Genesis cap and rejects the padded value.
 
 ---
 
-## 🧾 **Checksum Behavior**
+## Hashing the preimage does not authenticate it
+
+```
+<preimage> OP_HASH256
+```
+
+gives you `HASH256(preimage)` and **nothing else**. It does not establish that the
+bytes on the stack are this transaction's preimage. A spender can hand you any
+well-formed 182 bytes, satisfy every field check you wrote, and spend the output on a
+transaction that does something entirely different.
 
-The `sighashPreimage` is *never hashed directly* into the blockchain.
-Instead:
+The binding has to come from a signature check. `OP_PUSH_TX` — `lib/covenant/pushtx.js`
+— gets it by constructing a signature *from the preimage hash itself* and verifying it
+with `OP_CHECKSIG` against the generator point:
 
 ```
-signature = ECDSA.sign( sha256sha256(preimage), privKey )
+OP_HASH256                     z = HASH256(preimage)
+<reverse to LE>                e
+<Gx> OP_ADD <n> OP_MOD         s = (e + Gx) mod n
+<assemble DER: r = Gx, s>      a signature that is valid for P = G
+                               only if e is this input's sighash
+<02||Gx> OP_CHECKSIG           the node checks it against the REAL sighash
 ```
 
-In your covenant scripts, you typically:
+`OP_CHECKSIG` computes the sighash itself, from the transaction being validated. The
+signature only verifies if the `e` derived from the supplied preimage equals it. That
+is the whole trick, and it is the step that makes every field check downstream mean
+something.
 
-1. Re-hash the preimage (`OP_HASH256`) to verify it matches what was signed.
-2. Then you may dissect it to verify constraints (like `nLockTime`, `nVersion`, etc.).
+Use `PushTx.pushTxCore()` or `SmartContract.policy()` rather than assembling this by
+hand.
 
 ---
 
-## ✅ **Summary Table**
-
-| Field        | Bytes    | Endian | Covenant Extraction Example                             |
-| ------------ | -------- | ------ | ------------------------------------------------------- |
-| nVersion     | 4        | LE     | `4 OP_SPLIT OP_DROP OP_BIN2NUM`                         |
-| hashPrevouts | 32       | —      | `36 OP_SPLIT ...`                                       |
-| hashSequence | 32       | —      | next 32                                                 |
-| outpoint     | 36       | mixed  | —                                                       |
-| scriptCode   | variable | —      | rarely enforced directly                                |
-| amount       | 8        | LE     | `40 OP_SPLIT OP_NIP 8 OP_SPLIT OP_DROP OP_BIN2NUM`      |
-| nSequence    | 4        | LE     | `12 OP_SPLIT OP_NIP 4 OP_SPLIT OP_DROP OP_BIN2NUM`      |
-| hashOutputs  | 32       | —      | —                                                       |
-| nLockTime    | 4        | LE     | `<len-8> OP_SPLIT OP_NIP 4 OP_SPLIT OP_DROP OP_BIN2NUM` |
-| sighashType  | 4        | LE     | `<len-4> OP_SPLIT OP_NIP OP_BIN2NUM`                    |
+## `scriptCode` is not "the scriptPubKey"
 
----
+It is the script the signature commits to. For a plain P2PKH spend that happens to be
+the 25-byte locking script, but nothing in the format requires it: it is
+length-prefixed and variable, `OP_CODESEPARATOR` changes where it starts, and for the
+covenants this library builds it is hundreds of bytes.
+
+Any parser that assumes 25 bytes, or that reads fields at absolute offsets past the
+`scriptCode`, breaks on the first real contract. Read from the end.

package/lib/script/interpreter.js

@@ -293,6 +293,41 @@ Interpreter.MAX_SCRIPT_NUM_LENGTH_AFTER_GENESIS = 750000
 Interpreter.MAX_SCRIPT_NUM_LENGTH_AFTER_CHRONICLE = 32000000
 Interpreter.MAX_PUBKEYS_PER_MULTISIG_AFTER_GENESIS = 4294967295
 
+// Maximum combined size of the main and alt stacks, in ELEMENTS. Pre-Genesis
+// consensus is 1000; post-Genesis BSV removed the element count limit and
+// replaced it with a bound on the memory the two stacks occupy, so that a script
+// is limited by what it actually uses rather than by how it is divided up.
+Interpreter.MAX_STACK_SIZE = 1000
+
+// The post-Genesis memory bound, UNLIMITED by default because post-Genesis
+// CONSENSUS is unbounded by default. The node's 100 MB figure is
+// -maxstackmemoryusagepolicy, a RELAY setting, and applying a relay setting here
+// would make this library refuse scripts the network accepts — the same mistake
+// as carrying the 1000-element cap past Genesis, one release later and in the
+// same function. It is also why MINIMALDATA is not in currentConsensusFlags().
+//
+// A caller validating against relay policy, or hardening against untrusted input,
+// assigns STACK_MEMORY_USAGE_POLICY (or any ceiling) to this:
+//
+//   Interpreter.MAX_STACK_MEMORY_USAGE_AFTER_GENESIS =
+//     Interpreter.STACK_MEMORY_USAGE_POLICY
+//
+// Unbounded means a hostile script can allocate until the process runs out of
+// memory. That is the same trade `useGenesisLimits(max)` documents for element
+// size: consensus does not cap it, so neither do we, and a validator taking
+// scripts from strangers should set a ceiling matched to its workload.
+Interpreter.MAX_STACK_MEMORY_USAGE_AFTER_GENESIS = Interpreter.UNLIMITED
+
+/** The node's -maxstackmemoryusagepolicy default. Relay policy, not consensus. */
+Interpreter.STACK_MEMORY_USAGE_POLICY = 100 * 1024 * 1024
+
+// Charged per element on top of its bytes, because the container holding an
+// element is not free either — a stack of many small elements costs more than
+// their contents. Only consulted when a caller has set a memory ceiling, since
+// the default is unbounded. 32 is deliberately conservative: a bare
+// std::vector<uint8_t> is 24 bytes on the common 64-bit ABIs.
+Interpreter.STACK_ELEMENT_OVERHEAD = 32
+
 Interpreter.LOCKTIME_THRESHOLD = 500000000
 Interpreter.LOCKTIME_THRESHOLD_BN = new BN(Interpreter.LOCKTIME_THRESHOLD)
 
@@ -933,6 +968,66 @@ Interpreter.prototype.maxScriptNumLength = function () {
   return Interpreter.MAXIMUM_ELEMENT_SIZE
 }
 
+/**
+ * How many elements the two stacks may hold between them.
+ *
+ * Genesis removed this cap, the same way it removed the element size, script
+ * size and opcode caps. Leaving it static rejected post-Genesis scripts the
+ * network accepts — measured, a witness of 1,001 pushes:
+ *
+ *   before: SCRIPT_ERR_STACK_SIZE
+ *   node:   accepted
+ *
+ * which is the same shape of bug as the CHECKMULTISIG op count carried over
+ * from the pre-Genesis constant.
+ */
+Interpreter.prototype.maxStackSize = function () {
+  return this.isAfterGenesis() ? Interpreter.UNLIMITED : Interpreter.MAX_STACK_SIZE
+}
+
+/**
+ * What replaced it after Genesis: a bound on the memory the two stacks occupy,
+ * rather than on how many pieces that memory is divided into. Before Genesis
+ * the element cap is the operative one and this is not consulted.
+ *
+ * UNLIMITED in both eras by default, since post-Genesis consensus does not cap
+ * it. Set `MAX_STACK_MEMORY_USAGE_AFTER_GENESIS` to opt into a ceiling.
+ */
+Interpreter.prototype.maxStackMemoryUsage = function () {
+  return this.isAfterGenesis()
+    ? Interpreter.MAX_STACK_MEMORY_USAGE_AFTER_GENESIS
+    : Interpreter.UNLIMITED
+}
+
+/** Bytes held across both stacks, each element charged its container overhead. */
+Interpreter.prototype.stackMemoryUsage = function () {
+  const overhead = Interpreter.STACK_ELEMENT_OVERHEAD
+  let total = (this.stack.length + this.altstack.length) * overhead
+  for (let i = 0; i < this.stack.length; i++) total += this.stack[i].length
+  for (let i = 0; i < this.altstack.length; i++) total += this.altstack[i].length
+  return total
+}
+
+/**
+ * The stack limits, applied where the node applies them: after EVERY opcode.
+ *
+ * Checking once at the end of the script was a false accept in the direction
+ * that costs money — a script that piles up 1,001 elements and drops back to
+ * one before it finishes passed here and is rejected by the network.
+ *
+ * Returns an error string, or null.
+ */
+Interpreter.prototype.checkStackLimits = function () {
+  if (this.stack.length + this.altstack.length > this.maxStackSize()) {
+    return 'SCRIPT_ERR_STACK_SIZE'
+  }
+  const memoryCap = this.maxStackMemoryUsage()
+  if (memoryCap !== Interpreter.UNLIMITED && this.stackMemoryUsage() > memoryCap) {
+    return 'SCRIPT_ERR_STACK_SIZE'
+  }
+  return null
+}
+
 /** Genesis raised this rather than removing it: the node caps at UINT32_MAX. */
 Interpreter.prototype.maxPubKeysPerMultisig = function () {
   return this.isAfterGenesis()
@@ -1041,11 +1136,17 @@ Interpreter.prototype.evaluate = function () {
         // conditional or an invalid opcode beyond this point is not an error.
         return true
       }
+      // Where the node checks it: after each opcode, not once at the end.
+      const limitErr = this.checkStackLimits()
+      if (limitErr) {
+        this.errstr = limitErr
+        return false
+      }
     }
 
-    // Size limits
-    if (this.stack.length + this.altstack.length > 1000) {
-      this.errstr = 'SCRIPT_ERR_STACK_SIZE'
+    const finalErr = this.checkStackLimits()
+    if (finalErr) {
+      this.errstr = finalErr
       return false
     }
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartledger/bsv",
-  "version": "9.6.0",
+  "version": "9.8.0",
   "description": "Bitcoin SV library with an interpreter-verified script engine: OP_PUSH_TX covenants, BIP-143 preimage tooling, and consensus flags that match what miners actually enforce. Also ships DID:web / W3C VC-JWT credentials and the Legal Token Protocol.",
   "author": "SmartLedger Technology <hello@smartledger.technology> (https://smartledger.technology)",
   "homepage": "https://github.com/codenlighten/smartledger-bsv#readme",
@@ -135,13 +135,17 @@
     "test:browser": "echo 'Open tests/standalone-modules-test.html in browser for comprehensive testing'",
     "test:bundle": "echo 'Open tests/bundle-completeness-test.html in browser to verify bundle completeness'",
     "preimage:extract": "node examples/preimage/extract_preimage_bidirectional.js",
-    "prepublishOnly": "npm run build-all && npm run check:readme && npm run check:api && npm run check:types",
+    "prepublishOnly": "npm run build-all && npm run check:readme && npm run check:api && npm run check:types && npm run check:dts",
     "sync-cdn": "node scripts/sync-cdn-urls.js",
     "version": "node scripts/sync-cdn-urls.js && node scripts/sync-version.js && node scripts/gen-esm-wrapper.js && git add README.md docs version.js index.mjs",
     "test:browser:ci": "node tests/browser-smoke-runner.js",
     "api:snapshot": "node scripts/api-surface.js",
     "check:api": "mocha test/api_surface.js --no-config",
-    "check:types": "node scripts/check-types.js"
+    "check:types": "node scripts/check-types.js",
+    "check:dts": "node scripts/check-dts-coverage.js",
+    "check:audit-scope": "node scripts/check-audit-scope.js",
+    "check:audit-scope:fix": "node scripts/check-audit-scope.js --fix",
+    "check:dts:update": "node scripts/check-dts-coverage.js --update"
   },
   "unpkg": "bsv.min.js",
   "jsdelivr": "bsv.min.js",

package/version.js

@@ -1,3 +1,3 @@
 'use strict'
 // GENERATED by scripts/sync-version.js on `npm version` — do not edit.
-module.exports = '9.6.0'
+module.exports = '9.8.0'