@smartledger/bsv 4.0.1 → 4.2.1

package/CHANGELOG.md

@@ -5,6 +5,143 @@ All notable changes to SmartLedger-BSV will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.2.1] - 2026-06-07
+
+### Docs
+
+- **Substantial README rewrite for the v4.x line.** The README still
+  headlined v3.4.x (4 minors and a major stale), showed the *old*
+  `lib/covenant-interface` API in the covenant examples instead of the
+  v4.2.0 `bsv.SmartContract.PushTx`/`PELS`/`Token`/`Locks`/`verifyScript`
+  surface, had a wrong CDN-Bundles size table (off by up to 7× on
+  `bsv-mnemonic`), duplicate "Complete Documentation" sections, a
+  "planned 3.5.0" security note that was overtaken by 4.0.0, and a
+  footer stamp claiming "v3.3.4 • 9 Loading Options". Replaced the
+  headline with the v4.2.0 covenant section, rewrote PUSHTX/PELS
+  examples to use the new API, added Ownership Tokens + end-to-end
+  verification snippets, merged the two Documentation sections (7
+  broken file paths fixed, 4 dead links removed), replaced the
+  inaccurate CDN sub-table with a pointer to the canonical
+  loading-options table, updated Security to point at the v4.0.0 GDAF
+  fix, and stamped the footer at v4.2.1.
+
+### Semver
+
+Patch — README only. No source changes; no `lib/`, `bin/`, `bsv.d.ts`,
+or test diffs. Out-of-band republish: `@smartledger/bsv@4.2.0` was
+published from a separate session with the OLD README, then
+unpublished after the rewrite. npm's anti-republish policy refuses to
+reuse the 4.2.0 version number; 4.2.1 is the canonical version with
+the corrected README content. `smartledger-bsv@4.2.0` (unscoped) was
+published with the new README; for parity, the unscoped is also
+republished at 4.2.1.
+
+## [4.2.0] - 2026-06-07
+
+### Added
+
+- **First-class, interpreter-verified covenants under `bsv.SmartContract`.**
+  A complete, tested stack of custom locking scripts that verify end-to-end
+  through `Script.Interpreter` (positive and negative cases), building on the
+  post-Genesis limits from 4.1.0:
+  - **`SmartContract.PushTx`** — a *correct* OP_PUSH_TX (nChain WP1605). The
+    locking script generates an ECDSA signature in-script from the pushed
+    preimage (`a=k=1`, `r=Gx`, `s=(e+Gx) mod n`, pubkey `02||Gx`) and verifies
+    it with `OP_CHECKSIG`, proving the preimage is this very transaction. Uses a
+    fixed-length DER template with an `nLockTime` grind (`PushTx.grind`). Exposes
+    `authenticator()`, `valueCovenant()`, `hashOutputs()`, `extractHashOutputs()`.
+  - **`SmartContract.PELS` / `perpetualCovenant(fee)`** — a Perpetually Enforcing
+    Locking Script: every spend must recreate the same script (value − fee).
+    Reads its own script from the authenticated preimage's `scriptCode`, so there
+    is no self-hash circularity.
+  - **`SmartContract.Token` / `ownershipToken(fee, ownerHash)`** — a stateful
+    ownership token (NFT) carrying its owner as on-chain state; transfer requires
+    the owner's secret and rewrites the state, perpetuating the token code.
+  - **`SmartContract.Locks`** — hash-lock, P2PKH, CLTV time-lock, m-of-n
+    multisig, and HTLC primitives.
+  - **`SmartContract.CovenantHelpers`** + convenience methods
+    `enableGenesis()`, `verifyScript()`, `valueCovenant()` — a consensus-flag
+    `verify()` harness, raw BIP-143 preimage access, signing, and fund/spend
+    scaffolding.
+- New mocha suite `test/smart_contract/covenants.js` (11 specs / 24 assertions),
+  all green; full suite 4178 → 4189 passing.
+
+### Notes
+
+- These covenants require post-Genesis limits: call `SmartContract.enableGenesis()`
+  (a.k.a `Interpreter.useGenesisLimits()`) before verifying. Research-grade and
+  interpreter-verified — review before mainnet value (the OP_PUSH_TX key is the
+  intentionally public `a=k=1`; low-S malleability is left unenforced).
+
+## [4.1.0] - 2026-06-07
+
+### Added
+
+- **`Interpreter.useGenesisLimits([max])` — one-call opt-in for
+  post-Genesis BSV consensus.** The bundled `Script.Interpreter`
+  hardcoded the *pre-Genesis* consensus caps that BSV removed at the
+  Genesis upgrade (February 2020): 520-byte stack elements, 4-byte
+  script numbers, 201 non-push opcodes per script. Those caps make this
+  library's own flagship features impossible to evaluate — OP_PUSH_TX
+  covenants push a ~585-byte preimage element, do 32-byte modular
+  arithmetic (`OP_ADD`/`OP_MOD`), and run a few hundred opcodes.
+
+  ```js
+  // Default: bound the limits to a safe ceiling.
+  // 64 KB covers every covenant pattern seen in production and blocks
+  // memory-exhaustion via oversized pushes from untrusted scripts.
+  bsv.Script.Interpreter.useGenesisLimits(64 * 1024)
+
+  // Or fully unbounded (~2 GB) — only safe for trusted scripts:
+  // bsv.Script.Interpreter.useGenesisLimits()
+  ```
+
+  Defaults are unchanged out of the box (520 / 4 / 201) — existing
+  consumers see zero behavior change unless they opt in. The call
+  mutates static properties on the `Interpreter` constructor and
+  therefore affects every subsequent `new Interpreter()` in the
+  process; treat it as an app-startup setting, not per-request.
+
+- **`Interpreter.MAX_OPS_PER_SCRIPT`** exposed as a named constant
+  (= 201). Replaces the two hardcoded `> 201` checks in `Interpreter.step`.
+
+- **`bsv.d.ts`** now types `Interpreter.MAX_SCRIPT_ELEMENT_SIZE`,
+  `MAXIMUM_ELEMENT_SIZE`, `MAX_OPS_PER_SCRIPT`, and `useGenesisLimits()`.
+
+### Fixed
+
+- **`Interpreter.MAXIMUM_ELEMENT_SIZE` was a dead knob in the numeric
+  opcodes.** The constant was defined as `4` but never threaded into the
+  `BN.fromScriptNumBuffer(buf, fRequireMinimal, size)` calls in
+  `OP_ADD`/`OP_SUB`/`OP_MUL`/`OP_DIV`/`OP_MOD`/`OP_BOOLAND`/`OP_BOOLOR`/
+  `OP_NUMEQUAL`/`OP_NUMEQUALVERIFY`/`OP_NUMNOTEQUAL`/`OP_LESSTHAN`/
+  `OP_GREATERTHAN`/`OP_LESSTHANOREQUAL`/`OP_GREATERTHANOREQUAL`/`OP_MIN`/
+  `OP_MAX` (binary) and `OP_WITHIN` (ternary). The 3rd `size` argument was
+  always omitted, so BN fell back to its own 4-byte default — raising
+  `Interpreter.MAXIMUM_ELEMENT_SIZE` above 4 had no effect. Now threaded
+  through, so the knob actually does what its name implies.
+
+### Tests
+
+- Added `test/script/genesis_limits.js` (6 tests) covering defaults,
+  the lift, rejection of >4-byte arithmetic and >201 opcodes under
+  defaults, and acceptance of both after `useGenesisLimits()`. Full
+  suite: **4178 passing, 0 failing**.
+
+### Docs
+
+- README §"Evaluating covenants locally" — one-paragraph mention of
+  the new API in the covenant/smart-contract section.
+- JSDoc on `useGenesisLimits` calls out the process-wide-mutation
+  semantics and recommends bounded ceilings for untrusted input.
+- CDN/install refs bumped `@4.0.1` → `@4.1.0` across README + 6 docs
+  files.
+
+### Semver
+
+Minor bump — purely additive: a new public method and a fixed-but-was-
+dead constant. No existing API or default behavior changes.
+
 ## [4.0.1] - 2026-05-31
 
 ### Deprecated