@smartledger/bsv 5.4.2 → 5.5.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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).
 
+## [5.5.0] - 2026-06-25
+
+Minor release. Closes a front-running theft flaw in the ownership-token covenant
+and generalizes the covenant core into a pluggable, multi-output state machine.
+
+### Security
+
+- **`SmartContract.Token` ownership is now ECDSA-authorized.** The previous design
+  gated a transfer on revealing `ownerSecret` with `SHA256(ownerSecret) ==
+  ownerHash` — a hash-lock. The secret was exposed in the mempool on the first
+  spend and the spender freely chose the next owner, so a watcher could lift the
+  revealed secret and broadcast a competing spend redirecting the token to
+  themselves. Ownership is now a key: state is `HASH160(ownerPubKey)` and a
+  transfer requires the current owner's signature over the spend
+  (`OP_CHECKSIGVERIFY`), which commits via `SIGHASH_ALL` `hashOutputs` to the
+  exact recreated output — so altering the destination invalidates the proof.
+
+### Added
+
+- **Pluggable ownership — `SmartContract.Authorizers`.** Token ownership is always
+  a 20-byte commitment, so the transfer plumbing is identical across schemes:
+  - `singleKey()` — signature over the spend (the model above).
+  - `multisig(m, n)` — m-of-n group ownership; the key set is committed by hashing
+    the canonical redeem script, revealed at spend, bound to the commitment, and
+    checked with `OP_CHECKMULTISIG`.
+  - `predicate({ commit, emit, unlockArgs })` — escape hatch for custom schemes.
+- **Multi-output (N-output) tokens** — `Token.ownershipTokenMulti` /
+  `unlockTransferMulti` let the recreated token output sit among other outputs
+  (payments, change, data); the spender reveals the surrounding output bytes and
+  the covenant binds them into the committed `hashOutputs`.
+- **`PushTx.grind` configurable nonce** — `{ field: 'nLockTime' | 'sequence' }`,
+  so a covenant pinning `nLockTime` for a CLTV timelock can grind the input
+  sequence instead. `PushTx.assertSighashAll()` guard added to token/PELS scripts.
+
+### Changed (breaking, `SmartContract.Token` only)
+
+- `Token.ownershipToken(fee, owner)` — `owner` is now `HASH160(pubkey)` (use
+  `Token.ownerId(key)`), not `SHA256(secret)`.
+- `Token.unlockTransfer(signer, newOwnerHash, spend, satoshis, lockingScript[, opts])`
+  — now takes the owner key and the spend (it grinds and signs), not a precomputed
+  preimage. The rest of the package's API is unchanged and fully compatible.
+
+### Notes
+
+- Full suite **4267 passing**; `lib/` and `test/` lint clean.
+
 ## [5.4.2] - 2026-06-25
 
 Patch release. Dependency security maintenance — no API or behavior changes.

package/README.md

@@ -37,9 +37,9 @@ SC.enableGenesis()                       // post-Genesis limits (OP_PUSH_TX need
 // Self-replicating covenant — every spend recreates the same script (value − fee).
 const lock = SC.perpetualCovenant(500)
 
-// Stateful ownership token (NFT) — transfer requires the owner's secret,
-// rewrites state, perpetuates the token code.
-const token = SC.ownershipToken(500, ownerHash)
+// Stateful ownership token (NFT) — transfer requires the owner's ECDSA signature
+// over the spend, rewrites state, perpetuates the token code.
+const token = SC.ownershipToken(500, ownerHash) // ownerHash = SC.Token.ownerId(ownerKey)
 
 // Value covenant — forces spend outputs to match a specific hashOutputs.
 const vlock = SC.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs))
@@ -54,7 +54,8 @@ const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis
 |---|---|
 | `PushTx` | nChain WP1605 OP_PUSH_TX — `authenticator()`, `valueCovenant()`, `hashOutputs()`, `extractHashOutputs()`, `grind()` |
 | `PELS` | Perpetually Enforcing Locking Scripts — `perpetualCovenant(fee)` |
-| `Token` | Stateful ownership token (NFT) — `ownershipToken(fee, ownerHash)` |
+| `Token` | Stateful ownership token (NFT) — `ownershipToken(fee, owner[, auth])`, `ownershipTokenMulti(owner[, auth])`, `ownerId(key)`, `unlockTransfer(...)`, `unlockTransferMulti(...)` |
+| `Authorizers` | Pluggable token ownership — `singleKey()`, `multisig(m, n)`, `predicate({...})` |
 | `Locks` | Hash-lock, P2PKH, CLTV time-lock, m-of-n multisig, HTLC |
 | `CovenantHelpers` | Consensus-flag `verify()` harness, raw BIP-143 preimage, signing, fund/spend scaffolding |
 
@@ -729,11 +730,30 @@ const pels = SC.perpetualCovenant(500)   // fee in satoshis deducted each hop
 
 ### Ownership Tokens (NFT) — v4.2.0 API
 ```javascript
-// Stateful ownership token. Owner is carried as on-chain state; transfer
-// requires the current owner's secret and rewrites state, perpetuating
-// the token code across the chain of spends.
-const ownerHash = bsv.crypto.Hash.sha256ripemd160(currentOwnerPubKey.toBuffer())
+// Stateful ownership token. Owner is carried as on-chain state (HASH160 of the
+// owner's public key); transfer requires the current owner's ECDSA SIGNATURE over
+// the spend (OP_CHECKSIG) and rewrites state, perpetuating the token code across
+// the chain of spends. The signature commits to the chosen next owner, so a
+// mempool watcher cannot redirect a pending transfer (no hash-lock front-running).
+const ownerHash = SC.Token.ownerId(currentOwnerKey) // = HASH160(pubkey)
 const token = SC.ownershipToken(500, ownerHash)
+// To spend it forward to `nextOwnerHash`, the current owner signs:
+//   tokenInput.setScript(SC.Token.unlockTransfer(currentOwnerKey, nextOwnerHash, spendTx, sats, token))
+
+// Pluggable ownership — the SAME covenant, owned by an m-of-n group. Ownership is
+// committed as a 20-byte hash either way, so the transfer plumbing is identical.
+const ms = SC.Authorizers.multisig(2, 3)
+const groupToken = SC.Token.ownershipToken(500, ms.commit([pkA, pkB, pkC]), ms)
+// transfer requires any 2 of the 3 keys:
+//   SC.Token.unlockTransfer({ keys: [pkA, pkB, pkC], signWith: [skA, skC] },
+//                           nextOwnerHash, spendTx, sats, groupToken, { auth: ms })
+// Custom schemes: SC.Authorizers.predicate({ commit, emit, unlockArgs }).
+
+// N-output: recreate the token alongside other outputs (payments, change, data).
+// The spender reveals the surrounding output bytes; the covenant binds them all.
+const multi = SC.Token.ownershipTokenMulti(ownerHash)
+//   SC.Token.unlockTransferMulti(currentOwnerKey, nextOwnerHash, spendTx, sats, multi,
+//     { before: serializedOutputsBeforeToken, after: serializedOutputsAfterToken, tokenValue: le8(value) })
 ```
 
 ### End-to-end verification