@smartledger/bsv 9.2.0 → 9.4.0

package/covenant-entry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Covenant construction.
+ *
+ * The default export is `SmartContract.Covenant`; `reconstructP2pkhScript` is
+ * exported alongside it at runtime.
+ */
+import { SmartContract, Script, PublicKey } from '@smartledger/bsv';
+
+declare const covenant: typeof SmartContract.Covenant & {
+  /**
+   * Rebuild the P2PKH locking script a covenant spends from, for preimage
+   * construction.
+   */
+  reconstructP2pkhScript(publicKey: PublicKey | Buffer | string): Script;
+};
+
+export = covenant;

package/didweb-entry.d.ts

@@ -0,0 +1,7 @@
+/**
+ * did:web issuer keys and DID documents.
+ *
+ * Same surface as `require("@smartledger/bsv").DIDWeb`.
+ */
+import { DIDWeb } from '@smartledger/bsv';
+export = DIDWeb;

package/docs/AUDIT_SCOPE.md

@@ -29,17 +29,23 @@ testing.
 Two tiers, to be **priced separately** so the boundary can be drawn against a number
 rather than before seeing one.
 
-### Tier 1 — core, 12,268 lines across 33 files
+The boundary is drawn by **where defects have actually occurred**, not by how core a
+module sounds. That is a deliberate revision: an earlier version of this document
+scoped Tier 1 as "the cryptographic core" and would have excluded four of the six real
+defects this codebase has produced. See §2.1.
+
+### Tier 1 — 11,247 lines
 
 | Module | Lines | Why it matters |
 | --- | ---: | --- |
-| `lib/script/` | 3,751 | Consensus script interpreter. Divergence from the node means accepting a transaction the network rejects, or the reverse. |
 | `lib/transaction/` | 2,779 | Sighash construction and signing — both BIP-143 and the Original Transaction Digest Algorithm. |
-| `lib/crypto/` | 2,519 | ECDSA, nonce derivation, signature encoding, the script-number type. |
-| `lib/hdprivatekey.js`, `lib/hdpublickey.js` | 1,168 | BIP-32 derivation, including hardened paths. |
+| `lib/script/interpreter.js` | 2,684 | **Scoped to the flag and era surface, not opcode execution.** Consensus-flag selection and defaults, era derivation (Genesis/Chronicle), the limits derived from them, and the semantics of the exported `verify()`. Opcode execution is excluded — see §2.2. |
+| `lib/crypto/` | 2,519 | ECDSA, nonce derivation, signature encoding, the script-number type. **Scope this for an architectural judgement as well as for bugs** — see §2.3. |
+| `lib/notaryhash/` | 1,436 | BRC-220 signing and verification. Publicly reachable and relied on downstream. |
 | `lib/privatekey.js`, `lib/publickey.js` | 843 | Key construction, serialisation, WIF. Recent defects here produced a *different* key without error. |
-| `lib/address.js` | 543 | Address derivation and network binding. |
-| `lib/networks.js`, `lib/opcode.js` | 665 | Network parameters and the opcode table, which BSV upgrades have reassigned. |
+| `lib/smart_contract/` (targeted) | 472 | `locks.js` and the covenant-facing entrypoints in `index.js`: CLTV and HTLC locking semantics, flag plumbing, and any wrapper claiming mainnet-equivalent verification. Not the whole 6,908-line module. |
+| `lib/covenant/` | 409 | The verification harness. Its flag word is what made covenants verify under 2019 rules while claiming to mirror mainnet. |
+| `lib/util/jcs.js` | 105 | RFC 8785 canonicalization, now a public export and the estate's single implementation. |
 
 ### Tier 2 — optional, 1,607 lines
 
@@ -53,24 +59,87 @@ Tier 2 is cryptographic rather than application code, so excluding it is a **bud
 decision, not a risk judgement**. Priced as an add-on it is cheap; discovered later it
 is not.
 
+### 2.1 Why the boundary moved
+
+Six defects have been found in this codebase and fixed. Four of them were in code the
+previous version of this scope **excluded**:
+
+| Defect | Module | Was it in the old scope? |
+| --- | --- | --- |
+| Covenant verification applied pre-Genesis limits while claiming to mirror mainnet | `lib/covenant`, `lib/smart_contract` | no |
+| `timeLockCLTV` and the HTLC timeout enforced nothing on mainnet — Genesis reverted `OP_CLTV` to a NOP, so the funds were spendable immediately | `lib/smart_contract` | no |
+| A BRC-220 suite verified against a byte-reversed digest, rejecting every conformant signature | `lib/notaryhash` | no |
+| The reachable RFC 8785 canonicalizer was non-conformant while a correct one sat private; three downstream packages copied the wrong one | `lib/util/jcs.js`, `lib/ltp` | partly |
+| `ECDSA.verify()` returned the instance, so `if (verify())` was always truthy — a fail-open accepting forged signatures | `lib/crypto` | yes |
+| ECDSA nonce reuse across two signings on one instance, leaking the private key | `lib/crypto` | yes |
+
+The pattern is not "the primitives are weak". It is that **code making claims about
+consensus behaviour was wrong about it**, and the tests agreed because they shared the
+same assumption. Scope has been moved onto that surface.
+
+### 2.2 Why `lib/script` shrinks rather than leaves
+
+`lib/script` has the strongest external evidence in the repository: 1,483/1,483 of the
+reference node's own consensus vectors, zero false accepts and zero false rejects. That
+is evidence about **opcode execution**, and re-auditing it by hand is the least
+productive money in this engagement.
+
+It is not evidence about which flags a caller ends up with. Both consensus defects above
+were flag-selection and era-derivation failures reachable through `interpreter.js`, and
+no vector covers them because every vector states its own flags. So the interpreter stays
+in scope, scoped to that surface, and the remaining 1,175 lines of `lib/script` leave.
+
+### 2.3 A specific instruction for `lib/crypto`
+
+Both in-scope defects — a fail-open `verify()` and nonce reuse across signings — are
+symptoms of a **stateful object wrapper around a stateless primitive library**. The
+curve arithmetic beneath is `@noble/curves`, which is already audited and offers
+stateless signing, RFC 6979 nonces and a strict boolean verify.
+
+So do not only ask whether `lib/crypto` has bugs. Ask whether the wrapper should exist:
+what would it cost to route the signing and verification paths directly at `@noble`, and
+which parts genuinely cannot go? `bn.js`, `Point`, `Signature` and `Shamir` are public
+API (`bsv.crypto.*`) and cannot simply be deleted, so this is a question with a real
+answer rather than a rhetorical one. An answer either way is worth more than a list of
+findings inside code that should not be there.
+
+### 2.4 The requirement that matters most
+
+Whatever the final line count, the statement of work should carry this:
+
+> **Audit exported security claims, defaults, and the tests that assert them as a unit,
+> against an independent oracle or specification — not each in isolation.**
+
+Every defect above shares one shape. The code was wrong, and its tests passed, because
+the tests were written from the same assumption. A file-by-file review finds none of
+them. Checking a claim against something outside this repository finds all of them —
+which is exactly how each was eventually caught.
+
 ## 3. Out of scope, and why
 
 | Component | Status | Reason |
 | --- | --- | --- |
 | `@noble/curves`, `@noble/hashes`, `@noble/ciphers` | Already audited | The primitives come from the Noble libraries, which **Cure53 has audited and published on**. We do not implement curve or hash arithmetic ourselves. State this explicitly to vendors — otherwise they price work we do not need. |
-| `lib/smart_contract/`, `lib/ltp/`, `lib/gdaf/`, `lib/ordinals/`, `lib/block/`, plus 9 further directories and 6 top-level files | Excluded | Application layer, 24,447 lines — 18,600 in the five named modules and 5,847 in the remainder. Written in-house and covered by adversarial tests. Worth a separate engagement; including it here would blur the question in §1. |
+| Opcode execution in `lib/script/` (1,175 lines outside `interpreter.js`) | Excluded, with evidence | 1,483/1,483 of the reference node's own consensus vectors pass, with zero false accepts and zero false rejects. See §2.2 — the flag surface stays in, the execution does not. |
+| `lib/address.js`, `lib/networks.js`, `lib/opcode.js`, `lib/hdprivatekey.js`, `lib/hdpublickey.js` (2,391 lines) | Cut to pay for §2.1 | Formatting, network constants and BIP-32 derivation. No defect has originated here, and `networks.js` in particular defines addressing constants — pubkey hashes, xpub prefixes, ports, DNS seeds — and contains **no consensus-flag logic at all**. |
+| The rest of the application layer — `lib/gdaf/`, `lib/ltp/`, `lib/ordinals/`, `lib/block/`, `lib/didweb/`, `lib/vcjwt/`, `lib/statuslist/`, most of `lib/smart_contract/`, plus assorted top-level files | Excluded | ~26,000 lines. Worth a separate engagement; including it here would blur the question in §1. Note the parts of it with a demonstrated defect history have been pulled *into* Tier 1 rather than left here — see §2.1. |
 
-Totals reconcile against `lib/`, which is 38,322 lines across 130 files:
+Totals reconcile against `lib/`, which is 38,879 lines across 131 files:
 
 ```
-tier 1      12,268
+tier 1      11,247
 tier 2       1,607
-excluded    24,447
+excluded    26,025
             ------
-total       38,322
+total       38,879
 ```
 
-Core + optional = 13,875.
+Measured 2026-08-29 at `a954c27`. These figures drift as the library changes — an
+earlier set was 445 lines light by the time it was read, most of it in
+`lib/script/interpreter.js`, which is priced against. **Re-run §7 immediately before
+sending**, and update the date above with the commit measured.
+
+Core + optional = 12,854.
 
 ## 4. What an auditor gets on day one
 
@@ -124,37 +193,56 @@ any single number.
 ## 6. Enquiry text
 
 ```text
-Subject: Audit enquiry — BSV cryptographic library core (~13k LOC JavaScript)
+Subject: Audit enquiry — BSV library, consensus and signing surface (~13k LOC JavaScript)
 
 Hello,
 
 We maintain @smartledger/bsv, a Bitcoin SV library published on npm. We are
-seeking a quote for an independent security review of its cryptographic core.
+seeking a quote for an independent security review.
 
 Scope, and we would like these priced separately:
 
-  Tier 1 — 12,268 lines, 33 files. Script interpreter, sighash and signing,
-  ECDSA and signature encoding, BIP-32 derivation, key and address
-  construction.
+  Tier 1 — 11,247 lines. Sighash construction and signing; ECDSA, nonce
+  derivation and signature encoding; the consensus-flag and era-derivation
+  surface of the script interpreter; BRC-220 signing and verification;
+  key construction and serialisation; the covenant verification harness and
+  the locking-script semantics built on it; RFC 8785 canonicalization.
 
   Tier 2 — 1,607 lines. BIP-39 mnemonics, ECIES, and the Base58Check/varint
   decoding surface.
 
 JavaScript (CommonJS), Node >= 20.19. The code is public.
 
-Explicitly out of scope: elliptic-curve and hash primitives, which are supplied
-by the Noble libraries and already audited; and our 24,447-line application
-layer (credentials, tokens, ordinals), which we would treat as a separate
-engagement.
+Two things we would ask you to scope deliberately rather than by line count:
+
+  1. Please audit exported security claims, their defaults, and the tests that
+     assert them AS A UNIT, against an independent oracle or specification.
+     Every defect we have found shared one shape: the code was wrong and its
+     tests passed, because both were written from the same assumption. A
+     file-by-file review would have found none of them.
+
+  2. In lib/crypto, we would value a judgement on whether the wrapper should
+     exist at all. Our two worst defects there — a verify() that returned a
+     truthy object instead of a boolean, and nonce reuse across two signings
+     on one instance — are symptoms of a stateful wrapper around a stateless
+     primitive library (@noble/curves) that already offers stateless signing,
+     RFC 6979 nonces and a strict boolean verify. An answer on the cost of
+     removing the wrapper is worth more to us than a list of findings inside it.
+
+Explicitly out of scope: elliptic-curve and hash primitives, supplied by the
+Noble libraries and already audited by Cure53; opcode execution in the script
+interpreter, which passes 1,483/1,483 of the reference node's own consensus
+vectors with zero false accepts; and roughly 26,000 lines of application layer
+(credentials, tokens, ordinals), which we would treat as a separate engagement.
 
 Context that should shorten discovery: the core is inherited from bitcore and
 has been fixed reactively but never independently reviewed. We can provide a
 test-backed threat model, a 452-case behavioural conformance corpus that a
-second independent implementation agrees with, and a documented history of the
-defects we have found ourselves.
+second independent implementation agrees with, the node's own consensus vectors
+run as a gate, and a documented history of the defects we have found ourselves.
 
 The failure mode we most want examined is code that reports a check as passed
-without performing it — several of our own findings have had that shape.
+without performing it — every finding of ours has had that shape.
 
 Could you indicate availability, an approximate cost range, and what you would
 need from us to firm that up?
@@ -170,21 +258,32 @@ SmartLedger Technology
 
 Every figure in this document, including the excluded total, must come out of this
 script. **Derive the excluded count as the complement — never by subtracting tier 1
-alone.** The first draft did exactly that, double-counted tier 2, and published parts
+alone.** An early draft did exactly that, double-counted tier 2, and published parts
 summing to 37,430 against a 38,322 whole; §7 could not catch it because it reproduced
 every figure except the wrong one.
 
+Tier 1 is no longer whole directories. Three entries are partial — the interpreter is
+scoped to its flag surface, `smart_contract` to its locking semantics — so those are
+counted by file and the reason is in §2. A partial scope that is measured as a whole
+directory is how a vendor prices 6,908 lines when you meant 472.
+
 ```sh
 lines () { find "$@" -name '*.js' -exec cat {} + | wc -l; }
 
-TIER1_DIRS="lib/crypto lib/transaction lib/script"
-TIER1_FILES="lib/privatekey.js lib/publickey.js lib/address.js \
-             lib/hdprivatekey.js lib/hdpublickey.js lib/opcode.js lib/networks.js"
+# Whole directories in tier 1
+TIER1_DIRS="lib/crypto lib/transaction lib/notaryhash lib/covenant"
+
+# Individual files — including the PARTIAL entries (§2.2, §2.3)
+TIER1_FILES="lib/privatekey.js lib/publickey.js \
+             lib/script/interpreter.js \
+             lib/smart_contract/locks.js lib/smart_contract/index.js \
+             lib/util/jcs.js"
+
 TIER2_DIRS="lib/encoding lib/mnemonic lib/ecies"
 
 # Per-module breakdown for the scope tables
 for d in $TIER1_DIRS $TIER2_DIRS; do
-  printf '%-18s %3s files %6s lines\n' "$d" \
+  printf '%-20s %3s files %6s lines\n' "$d" \
     "$(find $d -name '*.js' | wc -l)" "$(lines $d)"
 done
 wc -l $TIER1_FILES
@@ -203,5 +302,13 @@ printf 'tier 1    %6s\ntier 2    %6s\nexcluded  %6s\n          ------\ntotal
 [ "$TOTAL" -gt 0 ] || echo "MISMATCH — run this from the repo root"
 [ $(( T1 + T2 + EXCLUDED )) -eq "$TOTAL" ] || echo "MISMATCH — do not send"
 
+# The cut list from §3, so the saving can be stated rather than asserted
+wc -l lib/address.js lib/networks.js lib/opcode.js \
+      lib/hdprivatekey.js lib/hdpublickey.js
+
+# networks.js carries no consensus-flag logic — the claim §3 rests on.
+# Expect 0. A non-zero result means the cut needs re-arguing.
+grep -cE 'SCRIPT_|GENESIS|CHRONICLE|consensus' lib/networks.js
+
 find lib -name '*.js' | wc -l   # file count
 ```

package/docs/MODULE_REFERENCE_COMPLETE.md

@@ -55,19 +55,19 @@ Three advanced modules totaling **~2.7MB** of functionality:
 - **Purpose**: Threshold cryptography for secure secret distribution
 - **Use Cases**: Backup keys, multi-party security, key recovery
 - **Features**: Split secrets into N shares, require M to reconstruct
-- **CDN**: `unpkg.com/@smartledger/bsv@9.2.0/bsv-shamir.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@9.4.0/bsv-shamir.min.js`
 
 #### **🌐 Global Digital Attestation Framework - GDAF (1184KB)**  
 - **Purpose**: W3C Verifiable Credentials and decentralized identity
 - **Use Cases**: Identity verification, attestations, zero-knowledge proofs
 - **Features**: DID creation, credential issuance, selective disclosure
-- **CDN**: `unpkg.com/@smartledger/bsv@9.2.0/bsv-gdaf.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@9.4.0/bsv-gdaf.min.js`
 
 #### **⚖️ Legal Token Protocol - LTP (1184KB)**
 - **Purpose**: Legal compliance framework for tokenized assets
 - **Use Cases**: Property rights, obligations, compliant tokenization  
 - **Features**: Legal primitives, compliance checking, attestation anchoring
-- **CDN**: `unpkg.com/@smartledger/bsv@9.2.0/bsv-ltp.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@9.4.0/bsv-ltp.min.js`
 
 ### **2. Incorrect File Sizes in Documentation**
 
@@ -81,18 +81,18 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 | Module | Size | Use Case | CDN Link |
 |--------|------|----------|----------|
-| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.2.0/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.2.0/bsv.bundle.js` |
-| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@9.2.0/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.2.0/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.2.0/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@9.2.0/bsv-security.min.js` |
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@9.2.0/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@9.2.0/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@9.2.0/bsv-mnemonic.min.js` |
-| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@9.2.0/bsv-shamir.min.js` |
-| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@9.2.0/bsv-gdaf.min.js` |
-| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@9.2.0/bsv-ltp.min.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.4.0/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.4.0/bsv.bundle.js` |
+| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@9.4.0/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.4.0/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.4.0/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@9.4.0/bsv-security.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@9.4.0/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@9.4.0/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@9.4.0/bsv-mnemonic.min.js` |
+| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@9.4.0/bsv-shamir.min.js` |
+| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@9.4.0/bsv-gdaf.min.js` |
+| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@9.4.0/bsv-ltp.min.js` |
 
 ## 🎯 **Updated Usage Examples**
 
@@ -100,22 +100,22 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **1. Basic Development (~963KB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv-script-helper.min.js"></script>
 ```
 
 #### **2. Smart Contract Development (~2.7MB — each bundle re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv-smartcontract.min.js"></script>
 ```
 
 #### **3. 🆕 Legal & Compliance Development (~3.2MB — each bundle re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv-gdaf.min.js"></script>
 <script>
   // Legal Token Protocol
   const legalToken = bsv.createLegalToken({
@@ -132,9 +132,9 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **4. 🆕 Security & Cryptography (~1.4MB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv-shamir.min.js"></script>
 <script>
   // Shamir Secret Sharing
   const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -146,7 +146,7 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **5. Everything Bundle (937KB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv.bundle.js"></script>
 <script>
   // Everything available immediately
   const shares = bsv.splitSecret('secret', 5, 3);

package/docs/ORDINALS_ENVELOPE_FIELDS.md

@@ -0,0 +1,159 @@
+# Envelope fields in `buildInscription` — handoff
+
+**Commit:** `0242542` `feat(ordinals): write envelope fields, and refuse the ones that unbind`
+**Touched:** `lib/ordinals/inscription.js`, `test/ordinals/inscription.js` — nothing else.
+**Suite:** 4768 passing, 0 failing.
+**Date:** 29 August 2026
+
+This landed in your repo from the OrdinalSource side. It is finished and tested,
+but it is **not releasable as-is** — see *What I did not touch*, which is the
+part that needs you.
+
+---
+
+## What it does
+
+`buildInscription` wrote the content type and the body and stopped. Tag 5 —
+`metadata`, the spec's own home for an object's own record — could not be
+written at all, and neither could any other field.
+
+That mattered beyond convenience. The only way to produce one was to assemble
+envelope bytes by hand, which is the most dangerous thing an integrator can do
+on this stack: the bytes are permanent, already paid for, and nothing local
+reports a mistake, because a builder agreeing with its own parser proves only
+that they agree.
+
+```js
+bsv.Ordinals.buildInscription({
+  address: owner,
+  contentType: 'image/jpeg',
+  content: image,
+  fields: { 5: manifest, 21: thumbnail }
+})
+```
+
+Fields are emitted between the content type and the body, in **ascending tag
+order** so the same input always produces the same bytes. Order carries no
+meaning to a parser before the body opens; reproducibility does.
+
+## What it refuses, and why each one is silent otherwise
+
+| Refused | Why it cannot be a warning |
+| --- | --- |
+| **Tag 0** | Opens the body. Everything after it *is* the body, so a field there does not fail — it silently becomes part of the file, and the inscription still looks fine. |
+| **Tag 1** | Is the content type. A second one declares it twice. |
+| **Unrecognized even tag** | The spec requires such an inscription to be "displayed as unbound, that is, without a location". It is indexed nowhere, permanently, and nothing local reports it. |
+| Negative / non-integer tag | Not expressible as a script number. |
+| Empty field value | Inscribes a zero-length field permanently for no reason. |
+
+Build time is the last moment any of these is catchable before the money is
+spent, which is why they throw rather than warn.
+
+## The design decision most worth your review
+
+`allowUnknownEvenFields` exists, and I went back and forth on it.
+
+My first instinct was a hard wall — never emit an unrecognized even tag, no
+exceptions. I changed my mind. The set of named tags grows as the protocol does,
+so a library that can *never* be overridden eventually becomes both wrong and
+unbypassable, and the workaround it forces — hand-assembled envelope bytes — is
+considerably more dangerous than the thing the check prevents.
+
+So it throws by default and can be overridden by a flag long enough that nobody
+passes it by accident. If you disagree, this is the knob to turn; the reasoning
+is in the JSDoc on `assertTagIsSafe` so it can be argued with rather than
+guessed at.
+
+## Byte-level details, since they are easy to get wrong
+
+- Tags **1–16** are emitted as their opcodes; anything larger as a **minimal
+  data push**. `OP_16` is the largest numeric opcode, so tag 21 has no opcode
+  form at all.
+- An indexer reads the resulting **stack element**, so `OP_5` and a one-byte
+  push of `0x05` are the same tag. The distinction still matters, because a data
+  push of a small number is non-minimal and non-minimal pushes are non-standard.
+- Script numbers carry sign in the high bit of the last byte, so a tag ending
+  `>= 0x80` is zero-padded or it reads back **negative**.
+
+## What was verified
+
+Round-tripped through `@smartledger/ordinals` — a **separate** implementation,
+not this library's own parser:
+
+```
+fields written : { 5: manifest, 21: thumbnail }
+keys read back : ["01", "05", "15", ""]     content-type, 5, 21, body
+values         : intact
+warnings       : []          errors: []          valid: true
+```
+
+All five refusals fire with their own messages, and the override builds while
+the independent parser correctly warns about the result.
+
+---
+
+## What I did not touch — this is the part that needs you
+
+**`CHANGELOG.md`, `version.js` and `package.json` all have uncommitted changes
+in the working tree** — the TypeScript-declarations work, `types-test/`,
+`scripts/check-types.js` and the `9.3.0` bump. Staging any of those to write a
+changelog entry would have swept up half-finished work that is not mine.
+
+So the feature is committed with **no changelog entry and no version**, which is
+deliberate and needs closing out. Two options:
+
+1. **Fold into 9.3.0.** It is already a minor bump and is not published yet
+   (npm `latest` is 9.2.0). Cleanest, if the declarations work ships with it.
+2. **Hold for 9.4.0**, if you would rather 9.3.0 stay exactly what you scoped.
+
+Ready to paste under whichever heading you choose:
+
+```markdown
+### Added — `buildInscription` can write envelope fields
+
+`fields` takes tag numbers to values and emits them between the content type and
+the body, in ascending tag order so identical input always produces identical
+bytes. Tag 5 is `metadata`, the spec's own home for an object's own record; it
+previously could not be written at all, so the only way to produce one was to
+assemble envelope bytes by hand.
+
+Three tags are refused at build time because each is silent afterwards. Tag 0
+opens the body, so a field there does not fail — it becomes part of the file.
+Tag 1 is the content type, and a second one declares it twice. An unrecognized
+EVEN tag costs the inscription its location everywhere: the spec requires such
+an inscription to be treated as unbound. Odd tags are ignored by an indexer that
+does not know them, which is why the spec says it is okay to be odd.
+
+`allowUnknownEvenFields` overrides the last of those. It exists because the
+named tag set grows with the protocol, and a library that could never be
+overridden would eventually be wrong AND unbypassable — sending people back to
+hand-assembled bytes, which is worse than what the check prevents.
+
+Tags 1..16 are emitted as opcodes and anything larger as a minimal data push,
+since OP_16 is the largest numeric opcode. Script numbers carry sign in the high
+bit of the last byte, so a tag ending >= 0x80 is zero-padded rather than read
+back negative.
+```
+
+## Related, already shipped
+
+`@smartledger/ordinals@0.1.6` went to npm the same day, fixing a matching blind
+spot on the reading side: its parity check opened with `if (key.length !== 2)
+return null`, so it only ever inspected single-byte tags. Tag 10 warned; tag
+258 — `0x02 0x01`, even and unrecognized — did not, while a conformant indexer
+still unbound the inscription.
+
+Worth knowing here because the two are the same rule from opposite ends: this
+library now refuses to *write* the hazard, and that one now reports it when it
+*reads* one. Parity is settled by the least significant byte, which little-endian
+puts first, so the rule holds at any tag width.
+
+## Not investigated, flagged only
+
+`test/smart_contract/ordinal_transfer.js` and `covenants.js` could not be run
+from an installed copy of the package — they need dev dependencies that are not
+in the published tarball. That is fine for you here in the repo, but it means a
+consumer cannot independently confirm that covenants verify under mainnet flags.
+Given 9.0.0 disclosed that they previously verified under *pre-Genesis* flags
+while the network would have behaved differently, that is a claim worth having
+independently checkable.

package/docs/advanced/UTXO_MANAGER_GUIDE.md

@@ -722,7 +722,7 @@ interface UTXO {
 <html>
 <head>
     <title>UTXO Manager Demo</title>
-    <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@9.2.0/bsv.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@9.4.0/bsv.min.js"></script>
 </head>
 <body>
     <script>

package/docs/audit-rfq/README.md

@@ -0,0 +1,41 @@
+# Audit RFQ — ready to send
+
+Three per-vendor copies of the enquiry in [`../AUDIT_SCOPE.md`](../AUDIT_SCOPE.md) §6.
+
+| File | Vendor | Route |
+| --- | --- | --- |
+| `cure53.txt` | Cure53 | `mail@cure53.de` |
+| `ncc-group.txt` | NCC Group — Cryptography Services | enquiry form |
+| `trail-of-bits.txt` | Trail of Bits | contact form |
+
+**Verify each route on the vendor's own site before sending.** They are recorded here
+as the commonly published ones, not as confirmed current addresses.
+
+## What differs between them
+
+Only the greeting. The scope section — everything from *"We maintain
+@smartledger/bsv"* to the sign-off — is byte-identical in all three, checked by hash:
+
+```
+cure53          78cfa6aba956d1ed
+ncc-group       78cfa6aba956d1ed
+trail-of-bits   78cfa6aba956d1ed
+```
+
+That is the point of `AUDIT_SCOPE.md`: every vendor prices the same thing, so the
+spread in how they scope it back is informative. The one-sentence opener is drawn
+from the vendor rationale in §5 and changes nothing priced — delete it if you would
+rather they all receive identical text.
+
+## Regenerating
+
+These are generated from `AUDIT_SCOPE.md` §6, never hand-written, so the figures
+cannot drift between the scope document and what a vendor receives. If you edit the
+enquiry text, regenerate rather than editing these files.
+
+**Before sending, re-run §7 of `AUDIT_SCOPE.md`.** The figures are measured at a
+commit and go stale: the previous set was 445 lines light after twelve days, most of
+it in `lib/script/interpreter.js`, which is tier 1 and therefore the number a vendor
+quotes against. Current figures were measured 2026-08-28 at `aa551a1`.
+
+Reply address in all three: `support@smartledger.technology`.

package/docs/audit-rfq/cure53.txt

@@ -0,0 +1,49 @@
+To:       Cure53
+Route:    mail@cure53.de  —  verify on cure53.de before sending
+Reply-to: support@smartledger.technology
+
+Subject: Audit enquiry — BSV cryptographic library core (~13k LOC JavaScript)
+
+Hello,
+
+We are approaching you first because you audited the Noble libraries our
+primitives come from, so the layer beneath this code is already familiar to
+you.
+
+We maintain @smartledger/bsv, a Bitcoin SV library published on npm. We are
+seeking a quote for an independent security review of its cryptographic core.
+
+Scope, and we would like these priced separately:
+
+  Tier 1 — 12,391 lines, 33 files. Script interpreter, sighash and signing,
+  ECDSA and signature encoding, BIP-32 derivation, key and address
+  construction.
+
+  Tier 2 — 1,607 lines. BIP-39 mnemonics, ECIES, and the Base58Check/varint
+  decoding surface.
+
+JavaScript (CommonJS), Node >= 20.19. The code is public.
+
+Explicitly out of scope: elliptic-curve and hash primitives, which are supplied
+by the Noble libraries and already audited; and our 24,769-line application
+layer (credentials, tokens, ordinals), which we would treat as a separate
+engagement.
+
+Context that should shorten discovery: the core is inherited from bitcore and
+has been fixed reactively but never independently reviewed. We can provide a
+test-backed threat model, a 452-case behavioural conformance corpus that a
+second independent implementation agrees with, and a documented history of the
+defects we have found ourselves.
+
+The failure mode we most want examined is code that reports a check as passed
+without performing it — several of our own findings have had that shape.
+
+Could you indicate availability, an approximate cost range, and what you would
+need from us to firm that up?
+
+Repository: https://github.com/codenlighten/smartledger-bsv
+Package:    https://www.npmjs.com/package/@smartledger/bsv
+
+Thank you,
+SmartLedger Technology
+support@smartledger.technology