bsv-sdk 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a0dbc7f524004e1db715058dd17d336e62f99687239ec4c7807512d730e6ef5
-  data.tar.gz: 45b1fc354cbfe718a38e01c0d4896d537600d188bba909f351da1bc17bac66c6
+  metadata.gz: 6152fa9bc473f3ff11eca96fa5a9f1302d88cdbe3d72782c13da1760a5507514
+  data.tar.gz: e3f45fa1d03d36f9943d172fb8db396869f2ad2ff333b8d071af161062e56fc3
 SHA512:
-  metadata.gz: 6e212bf3c077ab32a6d5187c0e3cbd93fd61f26844d40dce31b28c0574a1111db3a081dd0d843be90dc682779ede74ece03f0f7eccc0eec930a372306cdc3ca2
-  data.tar.gz: ec1e1b2e0c7b5ae142b52cb1863000fd262d0c1dc30346c2a7d412af2e1f66cbc3057c864bc9d6229737be59c30eae2eaf6d7fee7c296a9393c6e0f8b636b558
+  metadata.gz: 802d2a0fe86432760fa64b12ac6787b4e8a9c3ce02ea5f66e19eee9e3b61bc050f0712fa8c98f5cfe0ca92550a7b7df7927624f5b120fb5274aac082acb66a0b
+  data.tar.gz: 7ecae6d4a729130f3d14e637b5822cec7bcab141a7e32abcd4d0275b4c81a0c545d64a2272a8684ef8702b85f4a676f6e3545437ccca5f38a1b57108099baf57

data/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to the `bsv-sdk` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.26.0 — 2026-07-08
+
+### Breaking Changes
+- `Transaction::Tx#verify` — the `verified:` kwarg now accepts `nil | Hash{String => Boolean}`
+  (previously `nil | Set<String>`). The Hash is mutated in place, so a caller can both pre-seed
+  the already-verified wtxid set and read back the wtxids walked during verification. A frozen
+  Hash, or a Hash with a truthy `default`/`default_proc`, is rejected at entry (funds risk) (#904).
+
+### Added
+- `Transaction::Tx#verify(verified:)` bidirectional verification cache: pre-seeding short-circuits
+  already-verified ancestor subtrees; post-read exposes the walked wtxid set for a persistent
+  verification cache (#904, #909, #910).
+- Transaction memoisation: per-struct binary, component-hash, and wire-order memos across `Tx`,
+  inputs, and outputs, invalidated on mutation — repeated `to_binary`/`wtxid`/hash computation is
+  now cached (#881).
+- Conformance canonical corpus: a pinned-revision loader plus fetch/sync tooling and cache layout,
+  with the BEEF, BUMP, sighash, SHA-256, ECIES, BRC-42 key-derivation, and script-test specs
+  migrated onto it (#840, #841, #842–#847).
+
+### Fixed
+- Interpreter consensus hardening: correct Chronicle gating of `OP_VER`/`OP_VERIF` (with
+  tx_version), `OP_2MUL`/`OP_2DIV`, and multi-`OP_ELSE` (relaxed mode); enforce the `CLEANSTACK`
+  and `SIGPUSHONLY` verification flags; whitelist verification flags (#837, #850, #851, #852, #853,
+  #854).
+- `Transaction::Tx#verify` — translate the fee-gate `ArgumentError` (missing source data) into a
+  `VerificationError` (`:missing_source`) so every failure mode raises a consistent error type
+  (#904).
+- `Transaction::Tx#verify` — fix a funds-risk bug where a Hash with a truthy default could silently
+  short-circuit verification for unseen wtxids (#904).
+
+### Changed
+- Performance: reuse OpenSSL digest contexts in primitives hashing (thread-safety documented); split
+  `clear_caches` from `invalidate_caches` in the transaction cache lifecycle (#881, #882).
+
 ## 0.25.0 — 2026-06-18
 
 ### Added

data/README.md

@@ -24,7 +24,7 @@ This Ruby SDK is a port of the official BSV Blockchain SDKs, which serve as its
 
 The reference SDKs:
 
-- [TypeScript SDK](https://github.com/bsv-blockchain/ts-sdk)
+- [TypeScript SDK](https://github.com/bsv-blockchain/ts-stack)
 - [Go SDK](https://github.com/bsv-blockchain/go-sdk)
 - [Python SDK](https://github.com/bsv-blockchain/py-sdk)
 
@@ -89,8 +89,10 @@ locking_script = BSV::Script::Script.p2pkh_lock(pubkey_hash)
 tx = BSV::Transaction::Tx.new
 
 # Add an input referencing a previous transaction output
+# wtxid_from_hex converts a display-order hex txid to wire-order binary
+utxo_txid = '5884e5db9de218238671572340b207ee85b628074e7e467096c267266baf77a4'
 input = BSV::Transaction::TransactionInput.new(
-  prev_tx_id: source_txid_bytes,   # 32-byte binary txid of the UTXO
+  prev_wtxid: BSV::Transaction::TransactionInput.wtxid_from_hex(utxo_txid),
   prev_tx_out_index: 0
 )
 input.source_satoshis = 100_000

data/lib/bsv/primitives/digest.rb

@@ -9,33 +9,111 @@ module BSV
     # Thin wrappers around +OpenSSL::Digest+ and +OpenSSL::HMAC+ providing
     # the hash algorithms used throughout the BSV protocol: SHA-1, SHA-256,
     # double-SHA-256, SHA-512, RIPEMD-160, Hash160, HMAC, and PBKDF2.
+    #
+    # @note **Per-fibre cached OpenSSL contexts (via +Thread.current+)**
+    #
+    #   +sha256+, +sha256d+, +sha1+, and +sha512+ each cache one
+    #   +OpenSSL::Digest+ instance per fibre in +Thread.current+ under a
+    #   namespaced key (e.g. +:bsv_sdk_sha256_digest+).  Because MRI has no
+    #   fibres in this SDK's +lib/+ today, "per fibre" and "per thread" are
+    #   the same in practice — but the primitive is fibre-local, so the more
+    #   precise term is used throughout.  On every call the context is reset
+    #   with +OpenSSL::Digest#reset+, which calls +EVP_DigestInit_ex+ against
+    #   the +EVP_MD*+ already stored on the context.  This skips the
+    #   +EVP_get_digestbyname+ namemap lookup that
+    #   +OpenSSL::Digest::SHA256.new+ (or +.digest+) performs on every fresh
+    #   allocation.  The namemap cost is paid exactly once per fibre per
+    #   algorithm.
+    #
+    #   **Fibre-local semantics.**  +Thread.current[:key]+ is *fibre-local*
+    #   in MRI (documented since Ruby 2.0, verified on 3.3 / 3.4 / 4.0) — each
+    #   Fibre gets its own cached context.  This is stronger than the SDK
+    #   currently requires (no Fibres in +lib/+) and is correctly safe if
+    #   Fibres are introduced later.  The HLR body's "GVL makes it safe"
+    #   rationale is subtly wrong; the correct reason is fibre-local scope.
+    #
+    #   **Do not touch the cached instances externally.**  The keys
+    #   +:bsv_sdk_sha256_digest+, +:bsv_sdk_sha1_digest+, and
+    #   +:bsv_sdk_sha512_digest+ are technically reachable via +Thread.current+
+    #   but must never have +update+ called on them outside this module.
+    #   Calling +update+ out-of-band would corrupt the next call's input.
+    #
+    #   **User-visible invariants are unchanged:** return values are always
+    #   +ASCII-8BIT+ binary strings; identical inputs always produce identical
+    #   outputs; successive calls return distinct +String+ objects (output
+    #   buffers are never cached).
+    #
+    #   **Prefix convention.**  +:bsv_sdk_<algo>_digest+ is the SDK-wide
+    #   naming convention for any future +Thread.current+ usage in this
+    #   codebase — the prefix avoids collision with other libraries that may
+    #   also use +Thread.current+.
+    #
+    #   **FIPS.**  SHA-1, SHA-256, and SHA-512 remain FIPS-approved algorithms
+    #   under this pattern; the algorithm fetch happens once at +.new+, not per
+    #   call.
+    #
+    #   **CI matrix.**  Verified on MRI 3.3, 3.4, and 4.0.  JRuby and
+    #   TruffleRuby are not in the CI matrix — per-thread caching is correct on
+    #   true-parallel Rubies (each thread has independent +Thread.current+) but
+    #   unverified here.
+    #
+    #   **Why other SDKs do not do this.**  The TypeScript, Go, and Python SDKs
+    #   allocate fresh digest contexts per call because their OpenSSL bindings
+    #   cache the algorithm handle internally.  MRI's +openssl+ gem bridges
+    #   through +EVP_get_digestbyname+ on every allocation — we are patching
+    #   the Ruby binding overhead, not diverging from BSV protocol semantics.
+    #
+    #   **Out of scope with rationale:**
+    #   - +ripemd160+ — pure-Ruby implementation; no OpenSSL context.
+    #   - +hmac_sha256+ / +hmac_sha512+ — HMAC key changes per call.  A future
+    #     cache *must* key on wrapper-object identity (+object_id+), never on
+    #     key bytes — a key-bytes cache lookup would create a secret-dependent
+    #     side-channel via cache-hit timing.
+    #   - +pbkdf2_hmac_sha512+ — one-shot at BIP-39 seed derivation; not a
+    #     hot path.
     module Digest
       module_function
 
       # Compute SHA-1 digest.
       #
       # @param data [String] binary data to hash
-      # @return [String] 20-byte digest
+      # @return [String] 20-byte digest (ASCII-8BIT)
       def sha1(data)
-        OpenSSL::Digest::SHA1.digest(data)
+        d = Thread.current[:bsv_sdk_sha1_digest] ||= OpenSSL::Digest.new('SHA1')
+        d.reset
+        d.update(data)
+        d.digest
       end
 
       # Compute SHA-256 digest.
       #
       # @param data [String] binary data to hash
-      # @return [String] 32-byte digest
+      # @return [String] 32-byte digest (ASCII-8BIT)
       def sha256(data)
-        OpenSSL::Digest::SHA256.digest(data)
+        d = Thread.current[:bsv_sdk_sha256_digest] ||= OpenSSL::Digest.new('SHA256')
+        d.reset
+        d.update(data)
+        d.digest
       end
 
       # Compute double-SHA-256 (SHA-256d) digest.
       #
       # Used extensively in Bitcoin for transaction and block hashing.
+      # Inlines the two-round chain against the same cached SHA-256 context,
+      # saving one context allocation, one namemap lookup, one intermediate
+      # +String+, and one +module_function+ dispatch per call compared with
+      # the naive +sha256(sha256(data))+ decomposition.
       #
       # @param data [String] binary data to hash
-      # @return [String] 32-byte digest
+      # @return [String] 32-byte digest (ASCII-8BIT)
       def sha256d(data)
-        sha256(sha256(data))
+        d = Thread.current[:bsv_sdk_sha256_digest] ||= OpenSSL::Digest.new('SHA256')
+        d.reset
+        d.update(data)
+        first = d.digest
+        d.reset # defensive: some Ruby versions internally reset after #digest
+        d.update(first)
+        d.digest
       end
 
       alias hash256 sha256d
@@ -44,15 +122,23 @@ module BSV
       # Compute SHA-512 digest.
       #
       # @param data [String] binary data to hash
-      # @return [String] 64-byte digest
+      # @return [String] 64-byte digest (ASCII-8BIT)
       def sha512(data)
-        OpenSSL::Digest::SHA512.digest(data)
+        d = Thread.current[:bsv_sdk_sha512_digest] ||= OpenSSL::Digest.new('SHA512')
+        d.reset
+        d.update(data)
+        d.digest
       end
 
       # Compute RIPEMD-160 digest.
       #
+      # @note Uses the pure-Ruby {BSV::Primitives::Ripemd160} implementation —
+      #   no OpenSSL context is held or cached here.  RIPEMD-160 is not in
+      #   scope for the per-thread caching optimisation (different optimisation
+      #   track; not currently a hot path).
+      #
       # @param data [String] binary data to hash
-      # @return [String] 20-byte digest
+      # @return [String] 20-byte digest (ASCII-8BIT)
       def ripemd160(data)
         Ripemd160.digest(data)
       end
@@ -62,25 +148,32 @@ module BSV
       # Standard Bitcoin hash used for addresses and P2PKH script matching.
       #
       # @param data [String] binary data to hash
-      # @return [String] 20-byte digest
+      # @return [String] 20-byte digest (ASCII-8BIT)
       def hash160(data)
         ripemd160(sha256(data))
       end
 
       # Compute HMAC-SHA-256.
       #
+      # @note HMAC context reuse is deferred — the key changes per call, so a
+      #   future cache must key on wrapper-object identity (+object_id+), never
+      #   on key bytes, to avoid a secret-dependent side-channel via cache-hit
+      #   timing.
+      #
       # @param key [String] HMAC key
       # @param data [String] data to authenticate
-      # @return [String] 32-byte MAC
+      # @return [String] 32-byte MAC (ASCII-8BIT)
       def hmac_sha256(key, data)
         OpenSSL::HMAC.digest('SHA256', key, data)
       end
 
       # Compute HMAC-SHA-512.
       #
+      # @note HMAC context reuse is deferred — see +hmac_sha256+ note.
+      #
       # @param key [String] HMAC key
       # @param data [String] data to authenticate
-      # @return [String] 64-byte MAC
+      # @return [String] 64-byte MAC (ASCII-8BIT)
       def hmac_sha512(key, data)
         OpenSSL::HMAC.digest('SHA512', key, data)
       end
@@ -88,12 +181,13 @@ module BSV
       # Derive a key using PBKDF2-HMAC-SHA-512.
       #
       # Used by BIP-39 to convert mnemonic phrases into seeds.
+      # One-shot at key creation — not a hot path; no context reuse applied.
       #
       # @param password [String] the password (mnemonic phrase)
       # @param salt [String] the salt (+"mnemonic"+ + passphrase)
       # @param iterations [Integer] iteration count (default: 2048 per BIP-39)
       # @param key_length [Integer] desired output length in bytes (default: 64)
-      # @return [String] derived key bytes
+      # @return [String] derived key bytes (ASCII-8BIT)
       def pbkdf2_hmac_sha512(password, salt, iterations: 2048, key_length: 64)
         OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, key_length, 'sha512')
       end

data/lib/bsv/script/interpreter/error.rb

@@ -52,6 +52,8 @@ module BSV
       STACK_MEMORY_EXCEEDED = :stack_memory_exceeded
       UNIMPLEMENTED_OPCODE = :unimplemented_opcode
       MISSING_TX_CONTEXT = :missing_tx_context
+      SIG_PUSHONLY = :sig_pushonly
+      CLEAN_STACK = :clean_stack
     end
   end
 end

data/lib/bsv/script/interpreter/interpreter.rb

@@ -53,18 +53,74 @@ module BSV
       # stack overflow from deeply nested conditionals.
       MAX_CONDITIONAL_DEPTH = 256
 
+      # Opcodes that require Chronicle to execute. With explicit flags but
+      # without UTXO_AFTER_CHRONICLE, executing any of these raises
+      # DISABLED_OPCODE. OP_VER / OP_VERIF / OP_VERNOTIF are included because
+      # pre-Chronicle they're either reserved (OP_VER) or behave as a
+      # conditional-only NOP in non-executing branches — execution itself is
+      # disabled. Mirrors TS Spend.ts (lines ~694-709) and Go IsDisabled.
+      CHRONICLE_ONLY_OPCODES = [
+        Opcodes::OP_2MUL, Opcodes::OP_2DIV,
+        Opcodes::OP_VER, Opcodes::OP_VERIF, Opcodes::OP_VERNOTIF
+      ].freeze
+
+      # The two version-conditional opcodes — extracted to module-level
+      # constants so the interpreter hot path (every conditional dispatch /
+      # every executed chunk) doesn't allocate a fresh Array per call.
+      VER_CONDITIONAL_OPCODES = [Opcodes::OP_VERIF, Opcodes::OP_VERNOTIF].freeze
+
+      # Recognised verification flag names. Catches typos (a misspelled
+      # +SIGPUSHONLLY+ would otherwise silently disable enforcement) and forces
+      # any new flag to be declared here before use. The set is the union of
+      # flags appearing in the canonical conformance corpus and the Bitcoin
+      # Core +script_tests.json+ fixture, plus the witness/taproot family that
+      # downstream callers filter out before reaching the interpreter.
+      KNOWN_FLAGS = Set[
+        'CHECKLOCKTIMEVERIFY', 'CHECKSEQUENCEVERIFY',
+        'CLEANSTACK', 'DERSIG', 'DISCOURAGE_UPGRADABLE_NOPS',
+        'DISCOURAGE_UPGRADABLE_WITNESS_PROGRAM',
+        'GENESIS', 'LOW_S',
+        'MINIMALDATA', 'MINIMALIF',
+        'NULLDUMMY', 'NULLFAIL',
+        'P2SH', 'SIGHASH_FORKID', 'SIGPUSHONLY', 'STRICTENC',
+        'TAPROOT',
+        'UTXO_AFTER_CHRONICLE', 'UTXO_AFTER_GENESIS',
+        'WITNESS'
+      ].freeze
+
       # Evaluate unlock + lock scripts without transaction context.
       #
       # Signature operations will always fail (no sighash available).
       #
+      # @example Relaxed mode (post-Chronicle defaults, no malleability checks)
+      #   Interpreter.evaluate(unlock, lock)                  # flags defaults to nil
+      #
+      # @example Explicit flag set
+      #   Interpreter.evaluate(unlock, lock, flags: %w[UTXO_AFTER_GENESIS CLEANSTACK])
+      #
+      # @example Explicit-but-empty (pre-Genesis, pre-Chronicle, strict)
+      #   Interpreter.evaluate(unlock, lock, flags: [])       # NOT the same as nil
+      #
       # @param unlock_script [Script] the unlocking script
       # @param lock_script [Script] the locking script
+      # @param flags [Array<String>, Set<String>, nil] explicit verification flags
+      #   (e.g. +SIGPUSHONLY+, +CLEANSTACK+, +UTXO_AFTER_CHRONICLE+). +nil+
+      #   selects relaxed (post-Chronicle) mode where malleability checks are
+      #   off; an empty +[]+ array is explicit-but-empty (pre-Genesis,
+      #   pre-Chronicle strict mode). Each flag string must appear in
+      #   {KNOWN_FLAGS} — unknown names raise +ArgumentError+.
+      # @param tx_version [Integer, nil] transaction version made available to
+      #   +OP_VER+/+OP_VERIF+/+OP_VERNOTIF+ when no transaction is supplied
       # @return [Boolean] +true+ if execution succeeds
       # @raise [ScriptError] if script execution fails
-      def self.evaluate(unlock_script, lock_script)
+      # @raise [ArgumentError] if +flags+ contains an unknown name or
+      #   +tx_version+ is not a valid uint32
+      def self.evaluate(unlock_script, lock_script, flags: nil, tx_version: nil)
         new(
           unlock_script: unlock_script,
-          lock_script: lock_script
+          lock_script: lock_script,
+          flags: flags,
+          tx_version: tx_version
         ).execute
       end
 
@@ -75,19 +131,28 @@ module BSV
       # @param unlock_script [Script] the input's unlocking script
       # @param lock_script [Script] the previous output's locking script
       # @param satoshis [Integer] the value of the previous output in satoshis
+      # @param flags [Array<String>, Set<String>, nil] explicit verification flags
+      #   (see {.evaluate}). Production callers (e.g. +Tx#verify_input+) do not
+      #   pass +flags+, so mainnet transaction validation always runs in
+      #   relaxed mode; the parameter exists for conformance-corpus and
+      #   regression-vector runners that need to drive specific flag combinations.
       # @return [Boolean] +true+ if verification succeeds
       # @raise [ScriptError] if script execution fails
-      def self.verify(tx:, input_index:, unlock_script:, lock_script:, satoshis:)
+      # @raise [ArgumentError] if +flags+ contains an unknown name
+      def self.verify(tx:, input_index:, unlock_script:, lock_script:, satoshis:, flags: nil)
         new(
           unlock_script: unlock_script,
           lock_script: lock_script,
           tx: tx,
           input_index: input_index,
-          satoshis: satoshis
+          satoshis: satoshis,
+          flags: flags
         ).execute
       end
 
       def execute
+        enforce_sig_pushonly
+
         scripts = [@unlock_script, @lock_script]
         script_names = %w[unlock_script lock_script]
 
@@ -123,12 +188,15 @@ module BSV
 
       private
 
-      def initialize(unlock_script:, lock_script:, tx: nil, input_index: nil, satoshis: nil)
+      def initialize(unlock_script:, lock_script:, tx: nil, input_index: nil, satoshis: nil,
+                     flags: nil, tx_version: nil)
         @unlock_script = unlock_script
         @lock_script = lock_script
         @tx = tx
         @input_index = input_index
         @satoshis = satoshis
+        @flags = normalise_flags(flags)
+        @tx_version = validate_tx_version(tx_version)
 
         @dstack = Stack.new
         @astack = Stack.new
@@ -141,24 +209,137 @@ module BSV
         @current_chunk_idx = 0
       end
 
+      # Normalises the +flags:+ kwarg into a frozen Set of recognised names.
+      # +nil+ stays +nil+ (relaxed mode); any iterable is coerced to a Set of
+      # strings, dropping +nil+ / empty entries silently (so callers can pass
+      # +flags_csv.split(',')+ without trimming). Unknown flag names raise
+      # +ArgumentError+ — typos in consensus-affecting flag strings would
+      # otherwise silently disable the corresponding rule.
+      def normalise_flags(flags)
+        return nil if flags.nil?
+
+        normalised = Set.new
+        flags.each do |raw|
+          next if raw.nil?
+
+          name = raw.to_s.strip
+          next if name.empty?
+
+          unless KNOWN_FLAGS.include?(name)
+            raise ArgumentError,
+                  "unknown verification flag: #{raw.inspect} (add to KNOWN_FLAGS if intentional)"
+          end
+
+          normalised << name
+        end
+        normalised.freeze
+      end
+
+      # Ensures the +tx_version:+ kwarg is a valid uint32. Returns +nil+ for nil
+      # input. Raises +ArgumentError+ for negative values, values > 2^32-1, or
+      # non-Integer inputs — these would otherwise silently coerce inside
+      # +Array#pack('V')+ (negative wraps to 0xFFFFFFFF, oversized wraps mod
+      # 2^32), masking caller bugs.
+      def validate_tx_version(version)
+        return nil if version.nil?
+        return version if version.is_a?(Integer) && version >= 0 && version <= 0xFFFFFFFF
+
+        raise ArgumentError, "tx_version must be a uint32 (0..0xFFFFFFFF), got #{version.inspect}"
+      end
+
+      # Whether explicit verification flags were supplied.
+      # In their absence the interpreter behaves as if Chronicle is active and
+      # the unlock-script malleability flags are off (matches the TS SDK's
+      # +isRelaxed+ default — see Spend.ts).
+      def explicit_flags?
+        !@flags.nil?
+      end
+
+      def flag?(name)
+        explicit_flags? && @flags.include?(name)
+      end
+
+      # Whether post-Chronicle semantics apply (OP_2MUL/2DIV enabled,
+      # OP_VER/OP_VERIF/OP_VERNOTIF interpret +tx_version+).
+      def chronicle?
+        return flag?('UTXO_AFTER_CHRONICLE') if explicit_flags?
+
+        true
+      end
+
+      # Whether post-Genesis rules apply. With explicit flags this requires one
+      # of the genesis-era flags; without, the interpreter is always post-Genesis.
+      def after_genesis?
+        return flag?('GENESIS') || flag?('UTXO_AFTER_GENESIS') || flag?('UTXO_AFTER_CHRONICLE') if explicit_flags?
+
+        true
+      end
+
+      def enforce_sig_pushonly?
+        return flag?('SIGPUSHONLY') if explicit_flags?
+
+        false
+      end
+
+      def enforce_sig_pushonly
+        return unless enforce_sig_pushonly?
+        return if @unlock_script.push_only?
+
+        raise ScriptError.new(
+          ScriptErrorCode::SIG_PUSHONLY,
+          'unlock script must contain only push-data operations'
+        )
+      end
+
+      def enforce_clean_stack?
+        return flag?('CLEANSTACK') if explicit_flags?
+
+        false
+      end
+
+      def enforce_clean_stack
+        return unless enforce_clean_stack?
+        return if @dstack.length == 1
+
+        raise ScriptError.new(
+          ScriptErrorCode::CLEAN_STACK,
+          "CLEANSTACK requires exactly one stack item at end (found #{@dstack.length})"
+        )
+      end
+
       def execute_opcode(chunk)
         opcode = chunk.opcode
 
+        # Pre-Chronicle, pre-Genesis mode (explicit non-genesis flags) treats
+        # OP_VER / OP_VERIF / OP_VERNOTIF as universally illegal — they raise
+        # even in a non-executing branch. Mirrors TS Spend.ts line ~700.
+        enforce_pre_genesis_ver_gate(opcode)
+
         # After OP_RETURN inside a conditional: only process flow control opcodes
         # and OP_RETURN itself (which may terminate at top level once conditionals
         # are balanced), matching Go SDK's branchExecuting semantics.
         if @after_op_return
-          dispatch_opcode(opcode, chunk) if conditional_opcode?(opcode) || opcode == Opcodes::OP_RETURN
+          if conditional_opcode?(opcode) || opcode == Opcodes::OP_RETURN
+            return if skipped_ver_conditional?(opcode)
+
+            dispatch_opcode(opcode, chunk)
+          end
           return
         end
 
         # In non-executing branch: only dispatch conditional opcodes (for nesting tracking).
         # All other opcodes are skipped.
         unless branch_executing?
-          dispatch_opcode(opcode, chunk) if conditional_opcode?(opcode)
+          if conditional_opcode?(opcode)
+            return if skipped_ver_conditional?(opcode)
+
+            dispatch_opcode(opcode, chunk)
+          end
           return
         end
 
+        enforce_chronicle_gate(opcode)
+
         BSV.logger&.debug do
           name = Opcodes.name_for(opcode) || format('0x%02x', opcode)
           "[Interpreter]   #{name} (stack: #{@dstack.length})"
@@ -166,6 +347,41 @@ module BSV
         dispatch_opcode(opcode, chunk)
       end
 
+      def enforce_chronicle_gate(opcode)
+        return unless CHRONICLE_ONLY_OPCODES.include?(opcode)
+        return if chronicle?
+
+        raise ScriptError.new(
+          ScriptErrorCode::DISABLED_OPCODE,
+          "#{Opcodes.name_for(opcode) || format('0x%02x', opcode)} is disabled outside Chronicle"
+        )
+      end
+
+      # OP_VERIF / OP_VERNOTIF in a non-executing branch are conditional opcodes
+      # post-Chronicle (push to cond_stack, like OP_IF in a non-executing branch),
+      # but a complete NOP pre-Chronicle post-genesis — they neither push nor
+      # consume. This matches TS Spend.ts (line ~710) and Go opcodeVerConditional.
+      def skipped_ver_conditional?(opcode)
+        return false unless VER_CONDITIONAL_OPCODES.include?(opcode)
+
+        !chronicle? && after_genesis?
+      end
+
+      # Pre-Genesis VERIF / VERNOTIF are unconditionally illegal (even in
+      # non-executing branches — they enter the dispatcher as conditional opcodes).
+      # OP_VER pre-Genesis is illegal only when executing; in a non-executing
+      # branch it's skipped silently. Mirrors the Bitcoin Core script test
+      # rule "VER non-functional (ok if not executed); VERIF illegal everywhere".
+      def enforce_pre_genesis_ver_gate(opcode)
+        return unless VER_CONDITIONAL_OPCODES.include?(opcode)
+        return unless explicit_flags? && !after_genesis?
+
+        raise ScriptError.new(
+          ScriptErrorCode::DISABLED_OPCODE,
+          "#{Opcodes.name_for(opcode) || format('0x%02x', opcode)} is illegal pre-Genesis"
+        )
+      end
+
       def dispatch_opcode(opcode, chunk)
         case opcode
         # --- Data push ---
@@ -295,9 +511,12 @@ module BSV
       end
 
       # Verify final stack state: must have at least one truthy element on top.
+      # When the CLEANSTACK flag is set, additionally requires exactly one item.
       def check_final_stack
         raise ScriptError.new(ScriptErrorCode::EMPTY_STACK, 'stack empty at end of script execution') if @dstack.empty?
 
+        enforce_clean_stack
+
         return if @dstack.pop_bool
 
         raise ScriptError.new(ScriptErrorCode::EVAL_FALSE, 'false stack entry at end of script execution')