bsv-sdk 0.9.0 → 0.10.0

data/lib/bsv/mcp/tools/fetch_utxos.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    module Tools
+      # Fetches unspent transaction outputs (UTXOs) for a BSV address using
+      # the WhatsOnChain API.
+      #
+      # The http_client dependency is injectable for testing — pass a
+      # compatible mock object to +new_woc+.
+      class FetchUtxos < ::MCP::Tool
+        tool_name 'fetch_utxos'
+
+        description <<~DESC.strip
+          Fetch unspent transaction outputs (UTXOs) for a BSV address.
+
+          Queries the WhatsOnChain API and returns the list of UTXOs available
+          to spend from the given address. Requires network access.
+
+          Parameters:
+          - address: a BSV P2PKH address (mainnet starts with '1'; testnet
+            starts with 'm' or 'n')
+          - network: 'mainnet' or 'testnet' — overrides the server default
+
+          Returns an array of UTXO objects, each with:
+          - tx_hash: transaction ID of the UTXO
+          - tx_pos: output index within that transaction
+          - satoshis: value in satoshis
+          - height: block height (0 = unconfirmed)
+
+          Note: addresses are network-specific. A mainnet address on testnet
+          (or vice versa) will return no results or an error.
+        DESC
+
+        input_schema(
+          type: 'object',
+          properties: {
+            address: {
+              type: 'string',
+              description: 'BSV P2PKH address to look up.'
+            },
+            network: {
+              type: 'string',
+              enum: %w[mainnet testnet],
+              description: 'Network to query. Overrides the server default.'
+            }
+          },
+          required: ['address']
+        )
+
+        def self.call(address:, network: nil, server_context: nil)
+          net_sym = Helpers.resolve_network_sym(network, server_context)
+          woc = BSV::Network::WhatsOnChain.new(network: net_sym)
+          utxos = woc.fetch_utxos(address)
+
+          result = {
+            address: address,
+            network: net_sym.to_s,
+            utxos: utxos.map { |u| Helpers.utxo_to_h(u) }
+          }
+
+          ::MCP::Tool::Response.new(
+            [::MCP::Content::Text.new(result.to_json)],
+            structured_content: result
+          )
+        rescue BSV::Network::ChainProviderError => e
+          Helpers.error_response("#{e.message} (HTTP #{e.status_code})")
+        end
+      end
+    end
+  end
+end

data/lib/bsv/mcp/tools/generate_key.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    module Tools
+      # Generates a new random BSV private key and derives the corresponding
+      # public key and address.
+      #
+      # Each invocation produces a cryptographically fresh key — the result is
+      # never reused or persisted by the server. Store the WIF securely; it
+      # cannot be recovered from the address alone.
+      class GenerateKey < ::MCP::Tool
+        tool_name 'generate_key'
+
+        description <<~DESC.strip
+          Generate a new random BSV private key.
+
+          Returns the private key in WIF (Wallet Import Format), the compressed
+          public key as hex, and the corresponding P2PKH address for the
+          configured network.
+
+          IMPORTANT: A new key is generated on every call. The WIF is never
+          stored by the server — save it immediately in secure storage.
+          Losing the WIF means losing access to any funds sent to the address.
+
+          The address format is network-specific: mainnet addresses start with
+          '1', testnet addresses start with 'm' or 'n'.
+        DESC
+
+        input_schema(
+          type: 'object',
+          properties: {
+            network: {
+              type: 'string',
+              enum: %w[mainnet testnet],
+              description: 'Network to generate the key for. Overrides the server default.'
+            }
+          }
+        )
+
+        def self.call(network: nil, server_context: nil)
+          net_sym = Helpers.resolve_network_sym(network, server_context)
+
+          key = BSV::Primitives::PrivateKey.generate
+          pub = key.public_key
+
+          result = {
+            wif: key.to_wif(network: net_sym),
+            public_key_hex: pub.to_hex,
+            address: pub.address(network: net_sym),
+            network: net_sym.to_s
+          }
+
+          ::MCP::Tool::Response.new(
+            [::MCP::Content::Text.new(result.to_json)],
+            structured_content: result
+          )
+        end
+      end
+    end
+  end
+end

data/lib/bsv/mcp/tools/helpers.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    module Tools
+      # Shared helpers used across multiple MCP tools.
+      module Helpers
+        # Resolve a network string to the SDK symbol (:mainnet or :testnet).
+        #
+        # Checks the per-call +network_arg+ first, then falls back to the
+        # server-level config in +server_context+, then defaults to :mainnet.
+        #
+        # @param network_arg [String, nil] per-call override ('mainnet'/'testnet')
+        # @param server_context [Hash, nil] server context with :bsv_network key
+        # @return [Symbol] :mainnet or :testnet
+        def self.resolve_network_sym(network_arg, server_context)
+          net = network_arg
+          net = server_context[:bsv_network] if net.nil? && server_context.is_a?(Hash) && server_context[:bsv_network]
+          net == 'testnet' ? :testnet : :mainnet
+        end
+
+        # Convert a Transaction to a hash suitable for JSON responses.
+        #
+        # @param tx [BSV::Transaction::Transaction]
+        # @return [Hash]
+        def self.transaction_to_h(tx)
+          {
+            txid: tx.txid_hex,
+            version: tx.version,
+            lock_time: tx.lock_time,
+            inputs: tx.inputs.each_with_index.map { |inp, i| input_to_h(inp, i) },
+            outputs: tx.outputs.each_with_index.map { |out, i| output_to_h(out, i) }
+          }
+        end
+
+        # Convert a TransactionInput to a hash.
+        # @api private
+        def self.input_to_h(input, _index)
+          unlock_script = input.unlocking_script
+          {
+            prev_txid: input.prev_tx_id.reverse.unpack1('H*'),
+            vout: input.prev_tx_out_index,
+            script_hex: unlock_script ? unlock_script.to_hex : '',
+            script_asm: unlock_script ? unlock_script.to_asm : '',
+            sequence: input.sequence
+          }
+        end
+
+        # Convert a TransactionOutput to a hash.
+        # @api private
+        def self.output_to_h(output, index)
+          script = output.locking_script
+          {
+            index: index,
+            satoshis: output.satoshis,
+            script_hex: script ? script.to_hex : '',
+            script_asm: script ? script.to_asm : '',
+            script_type: script ? script.type : 'empty'
+          }
+        end
+
+        # Convert a UTXO to a hash.
+        # @api private
+        def self.utxo_to_h(utxo)
+          {
+            tx_hash: utxo.tx_hash,
+            tx_pos: utxo.tx_pos,
+            satoshis: utxo.satoshis,
+            height: utxo.height
+          }
+        end
+
+        # Build a standard MCP error response.
+        #
+        # @param message [String] error description
+        # @return [MCP::Tool::Response]
+        def self.error_response(message)
+          payload = { error: message }
+          ::MCP::Tool::Response.new(
+            [::MCP::Content::Text.new(payload.to_json)],
+            error: true
+          )
+        end
+      end
+    end
+  end
+end

data/lib/bsv/mcp.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    autoload :Config, 'bsv/mcp/config'
+    autoload :Server, 'bsv/mcp/server'
+
+    module Tools
+      autoload :Helpers,         'bsv/mcp/tools/helpers'
+      autoload :GenerateKey,     'bsv/mcp/tools/generate_key'
+      autoload :DecodeTx,        'bsv/mcp/tools/decode_tx'
+      autoload :FetchUtxos,      'bsv/mcp/tools/fetch_utxos'
+      autoload :FetchTx,         'bsv/mcp/tools/fetch_tx'
+      autoload :CheckBalance,    'bsv/mcp/tools/check_balance'
+      autoload :BroadcastP2pkh,  'bsv/mcp/tools/broadcast_p2pkh'
+    end
+  end
+end

data/lib/bsv/network/arc.rb

@@ -15,6 +15,16 @@ module BSV
     # The HTTP client is injectable for testability. It must respond to
     # #request(uri, request) and return an object with #code and #body.
     class ARC
+      # Returns an ARC instance pointed at the GorillaPool public ARC endpoint.
+      #
+      # @param testnet [Boolean] when true, uses the GorillaPool testnet endpoint
+      # @param opts [Hash] forwarded to {#initialize} (e.g. +api_key:+, +callback_url:+)
+      # @return [ARC]
+      def self.default(testnet: false, **opts)
+        url = testnet ? 'https://testnet.arc.gorillapool.io' : 'https://arc.gorillapool.io'
+        new(url, **opts)
+      end
+
       # ARC response statuses that indicate the transaction was NOT accepted.
       # Matches the TypeScript SDK's ARC broadcaster failure set (issue #305,
       # finding F5.13). Prior to this fix, Ruby only recognised REJECTED and
@@ -63,24 +73,62 @@ module BSV
       #   'SEEN_ON_NETWORK', or 'MINED'. When set, ARC holds the
       #   connection open until the transaction reaches the requested
       #   state (or times out). Defaults to nil (no wait).
+      # @param skip_fee_validation [Boolean, nil] when truthy, sends the
+      #   +X-SkipFeeValidation: true+ header, asking ARC to bypass its
+      #   minimum-fee check. Useful for zero-fee data transactions or
+      #   during local testing. Defaults to nil (fee validation applies).
+      # @param skip_script_validation [Boolean, nil] when truthy, sends the
+      #   +X-SkipScriptValidation: true+ header, asking ARC to bypass
+      #   script correctness checks. Defaults to nil (script validation
+      #   applies).
       # @return [BroadcastResponse]
       # @raise [BroadcastError] when ARC returns a non-2xx HTTP status or a
       #   rejected/orphan +txStatus+
-      def broadcast(tx, wait_for: nil)
+      def broadcast(tx, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
         uri = URI("#{@url}/v1/tx")
-        request = Net::HTTP::Post.new(uri)
-        request['Content-Type'] = 'application/json'
-        request['XDeployment-ID'] = @deployment_id
-        request['X-WaitFor'] = wait_for if wait_for
-        request['X-CallbackUrl'] = @callback_url if @callback_url
-        request['X-CallbackToken'] = @callback_token if @callback_token
-        apply_auth_header(request)
+        request = build_post_request(uri, wait_for: wait_for,
+                                          skip_fee_validation: skip_fee_validation,
+                                          skip_script_validation: skip_script_validation)
         request.body = JSON.generate(rawTx: raw_tx_hex(tx))
 
         response = execute(uri, request)
         handle_broadcast_response(response)
       end
 
+      # Submit multiple transactions to ARC in a single batch request.
+      #
+      # Each transaction is encoded as Extended Format (BRC-30) hex where
+      # possible, falling back to plain raw-tx hex per transaction independently.
+      #
+      # Returns a mixed array of {BroadcastResponse} and {BroadcastError} objects
+      # — one element per submitted transaction in the same order. Per-transaction
+      # rejections are returned as {BroadcastError} values rather than raised, so
+      # callers can inspect the full result set even when some transactions fail.
+      # Only HTTP-level errors (non-2xx) raise a {BroadcastError} for the whole
+      # batch.
+      #
+      # @param txs [Array<Transaction>] transactions to broadcast
+      # @param wait_for [String, nil] ARC wait condition (see {#broadcast})
+      # @param skip_fee_validation [Boolean, nil] when truthy, sends
+      #   +X-SkipFeeValidation: true+ for the batch request
+      # @param skip_script_validation [Boolean, nil] when truthy, sends
+      #   +X-SkipScriptValidation: true+ for the batch request
+      # @return [Array<BroadcastResponse, BroadcastError>]
+      # @raise [BroadcastError] when ARC returns a non-2xx HTTP status or a
+      #   malformed (non-array) response body
+      def broadcast_many(txs, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
+        return [] if txs.empty?
+
+        uri = URI("#{@url}/v1/txs")
+        request = build_post_request(uri, wait_for: wait_for,
+                                          skip_fee_validation: skip_fee_validation,
+                                          skip_script_validation: skip_script_validation)
+        request.body = JSON.generate(txs.map { |tx| { rawTx: raw_tx_hex(tx) } })
+
+        response = execute(uri, request)
+        handle_batch_response(response)
+      end
+
       # Query the status of a previously submitted transaction.
       # Returns BroadcastResponse on success, raises BroadcastError on failure.
       def status(txid)
@@ -104,6 +152,19 @@ module BSV
         tx.to_hex
       end
 
+      def build_post_request(uri, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = 'application/json'
+        request['XDeployment-ID'] = @deployment_id
+        request['X-WaitFor'] = wait_for if wait_for
+        request['X-CallbackUrl'] = @callback_url if @callback_url
+        request['X-CallbackToken'] = @callback_token if @callback_token
+        request['X-SkipFeeValidation'] = 'true' if skip_fee_validation
+        request['X-SkipScriptValidation'] = 'true' if skip_script_validation
+        apply_auth_header(request)
+        request
+      end
+
       def apply_auth_header(request)
         request['Authorization'] = "Bearer #{@api_key}" if @api_key
       end
@@ -189,6 +250,44 @@ module BSV
           competing_txs: body['competingTxs']
         )
       end
+
+      def handle_batch_response(response)
+        code = response.code.to_i
+        body = parse_json(response.body)
+
+        unless (200..299).cover?(code)
+          raise BroadcastError.new(
+            body['detail'] || body['title'] || "HTTP #{code}",
+            status_code: code
+          )
+        end
+
+        unless body.is_a?(Array)
+          raise BroadcastError.new(
+            'ARC returned a malformed batch response',
+            status_code: code
+          )
+        end
+
+        body.map { |item| build_response_or_error(item) }
+      end
+
+      def build_response_or_error(body)
+        if rejected_status?(body)
+          BroadcastError.new(
+            body['detail'] || body['title'] || body['txStatus'],
+            status_code: 200,
+            txid: body['txid']
+          )
+        elsif !body['txid']
+          BroadcastError.new(
+            'ARC returned a malformed 2xx response',
+            status_code: 200
+          )
+        else
+          build_response(body)
+        end
+      end
     end
   end
 end

data/lib/bsv/primitives/schnorr.rb

@@ -34,6 +34,28 @@ module BSV
           @s_prime = s_prime
           @z = z
         end
+
+        # Deserialise a proof from its binary representation.
+        #
+        # The format is: R (33 bytes) + S' (33 bytes) + z (remaining bytes).
+        # The z scalar is variable-length to accommodate both the Ruby SDK's
+        # fixed 32-byte encoding and the TS SDK's minimal encoding (which
+        # omits leading zero bytes). See issue #203.
+        #
+        # @param data [String] binary proof data (>= 67 bytes)
+        # @return [Proof]
+        # @raise [ArgumentError] if data is too short
+        def self.from_binary(data)
+          data = data.b
+          raise ArgumentError, "proof too short: #{data.bytesize} bytes (minimum 67)" if data.bytesize < 67
+
+          r = PublicKey.from_bytes(data.byteslice(0, 33))
+          s_prime = PublicKey.from_bytes(data.byteslice(33, 33))
+          z_bytes = data.byteslice(66, data.bytesize - 66)
+          z = OpenSSL::BN.new(z_bytes, 2)
+
+          new(r, s_prime, z)
+        end
       end
 
       module_function

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

@@ -51,6 +51,7 @@ module BSV
       MINIMAL_DATA = :minimal_data
       STACK_MEMORY_EXCEEDED = :stack_memory_exceeded
       UNIMPLEMENTED_OPCODE = :unimplemented_opcode
+      MISSING_TX_CONTEXT = :missing_tx_context
     end
   end
 end

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

@@ -40,9 +40,13 @@ module BSV
       attr_reader :dstack, :astack
 
       # Conditional opcodes must be processed even in non-executing branches
-      # to maintain correct nesting depth.
+      # to maintain correct nesting depth. OP_VERIF and OP_VERNOTIF are included
+      # here because they open conditional blocks (like OP_IF/OP_NOTIF) and must
+      # be dispatched to track nesting depth even when the branch is not executing.
+      # This matches the Go SDK's IsConditional() function.
       CONDITIONAL_OPCODES = [
-        Opcodes::OP_IF, Opcodes::OP_NOTIF, Opcodes::OP_ELSE, Opcodes::OP_ENDIF
+        Opcodes::OP_IF, Opcodes::OP_NOTIF, Opcodes::OP_ELSE, Opcodes::OP_ENDIF,
+        Opcodes::OP_VERIF, Opcodes::OP_VERNOTIF
       ].freeze
 
       # Maximum nesting depth for OP_IF / OP_NOTIF blocks. Prevents interpreter
@@ -179,13 +183,9 @@ module BSV
         when Opcodes::OP_RETURN then op_return
         when Opcodes::OP_RESERVED, Opcodes::OP_RESERVED1, Opcodes::OP_RESERVED2
           op_reserved(opcode)
-        # Chronicle fail-safe: OP_VER, OP_VERIF, OP_VERNOTIF, and the Chronicle
-        # string/shift slots raise UnimplementedOpcode. Full semantics are
-        # deferred to SDK v0.10.
-        when Opcodes::OP_VER, Opcodes::OP_VERIF, Opcodes::OP_VERNOTIF,
-             Opcodes::OP_SUBSTR, Opcodes::OP_LEFT, Opcodes::OP_RIGHT,
-             Opcodes::OP_LSHIFTNUM, Opcodes::OP_RSHIFTNUM
-          op_unimplemented(opcode)
+        when Opcodes::OP_VER then op_ver
+        when Opcodes::OP_VERIF then op_verif
+        when Opcodes::OP_VERNOTIF then op_vernotif
 
         # --- Stack manipulation ---
         when Opcodes::OP_TOALTSTACK then op_toaltstack
@@ -214,6 +214,9 @@ module BSV
         when Opcodes::OP_NUM2BIN then op_num2bin
         when Opcodes::OP_BIN2NUM then op_bin2num
         when Opcodes::OP_SIZE then op_size
+        when Opcodes::OP_SUBSTR then op_substr
+        when Opcodes::OP_LEFT then op_left
+        when Opcodes::OP_RIGHT then op_right
 
         # --- Bitwise ---
         when Opcodes::OP_EQUAL then op_equal
@@ -226,8 +229,8 @@ module BSV
         # --- Arithmetic ---
         when Opcodes::OP_1ADD then op_1add
         when Opcodes::OP_1SUB then op_1sub
-        when Opcodes::OP_2MUL, Opcodes::OP_2DIV
-          op_disabled(opcode)
+        when Opcodes::OP_2MUL then op_2mul
+        when Opcodes::OP_2DIV then op_2div
         when Opcodes::OP_NEGATE then op_negate
         when Opcodes::OP_ABS then op_abs
         when Opcodes::OP_NOT then op_not
@@ -239,6 +242,8 @@ module BSV
         when Opcodes::OP_MOD then op_mod
         when Opcodes::OP_LSHIFT then op_lshift
         when Opcodes::OP_RSHIFT then op_rshift
+        when Opcodes::OP_LSHIFTNUM then op_lshiftnum
+        when Opcodes::OP_RSHIFTNUM then op_rshiftnum
         when Opcodes::OP_BOOLAND then op_booland
         when Opcodes::OP_BOOLOR then op_boolor
         when Opcodes::OP_NUMEQUAL then op_numequal

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

@@ -5,7 +5,7 @@ module BSV
     class Interpreter
       module Operations
         # Arithmetic and comparison operations including restored post-Genesis
-        # opcodes: MUL, DIV, MOD, LSHIFT, RSHIFT.
+        # opcodes: MUL, DIV, MOD, LSHIFT, RSHIFT, and Chronicle opcodes: 2MUL, 2DIV.
         module Arithmetic
           private
 
@@ -190,12 +190,48 @@ module BSV
             @dstack.push_int(ScriptNumber.new(x >= min && x < max ? 1 : 0))
           end
 
-          # OP_2MUL, OP_2DIV: disabled opcodes
-          def op_disabled(opcode)
-            raise ScriptError.new(
-              ScriptErrorCode::DISABLED_OPCODE,
-              "attempt to execute disabled opcode: 0x#{opcode.to_s(16).rjust(2, '0')}"
-            )
+          # OP_2MUL: multiply top of stack by 2 (restored in Chronicle)
+          def op_2mul
+            n = @dstack.pop_int
+            @dstack.push_int(n * ScriptNumber.new(2))
+          end
+
+          # OP_2DIV: integer-divide top of stack by 2, truncating toward zero (restored in Chronicle)
+          def op_2div
+            n = @dstack.pop_int
+            @dstack.push_int(n / ScriptNumber.new(2))
+          end
+
+          # OP_LSHIFTNUM: numeric left shift (Chronicle opcode 0xb6)
+          #
+          # Pops n then value; pushes value.value << n.to_i32.
+          # Raises INVALID_INPUT_LENGTH if the shift amount is negative.
+          def op_lshiftnum
+            n = @dstack.pop_int
+            value = @dstack.pop_int
+            shift = n.to_i32
+            raise ScriptError.new(ScriptErrorCode::INVALID_INPUT_LENGTH, 'shift amount negative') if shift.negative?
+
+            @dstack.push_int(ScriptNumber.new(value.value << shift))
+          end
+
+          # OP_RSHIFTNUM: numeric arithmetic right shift (Chronicle opcode 0xb7)
+          #
+          # Pops n then value; pushes the arithmetic right shift of value by n bits.
+          # Raises INVALID_INPUT_LENGTH if the shift amount is negative.
+          #
+          # IMPORTANT: Ruby's Integer#>> sign-extends negative numbers (-1 >> 1 == -1).
+          # Bitcoin consensus requires -(abs(value) >> n) for negative values, so that
+          # -1 >> 1 == 0 (not -1) and -16 >> 2 == -4. This matches the Go and TS SDKs.
+          def op_rshiftnum
+            n = @dstack.pop_int
+            value = @dstack.pop_int
+            shift = n.to_i32
+            raise ScriptError.new(ScriptErrorCode::INVALID_INPUT_LENGTH, 'shift amount negative') if shift.negative?
+
+            val = value.value
+            shifted = val.negative? ? -(val.abs >> shift) : (val >> shift)
+            @dstack.push_int(ScriptNumber.new(shifted))
           end
 
           # --- Byte-array shift helpers ---

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

@@ -95,16 +95,91 @@ module BSV
             )
           end
 
-          # Chronicle fail-safe: OP_VER, OP_VERIF, OP_VERNOTIF and the Chronicle
-          # string/shift slots (OP_SUBSTR, OP_LEFT, OP_RIGHT, OP_LSHIFTNUM,
-          # OP_RSHIFTNUM). Full semantics are deferred to SDK v0.10. Any script
-          # that reaches one of these opcodes will fail loudly rather than
-          # silently succeeding.
-          def op_unimplemented(opcode)
-            raise ScriptError.new(
-              ScriptErrorCode::UNIMPLEMENTED_OPCODE,
-              "unimplemented opcode: 0x#{opcode.to_s(16).rjust(2, '0')}"
-            )
+          # OP_VER: push 4-byte little-endian transaction version onto the stack.
+          #
+          # Requires a transaction context (@tx must not be nil). Raises
+          # MISSING_TX_CONTEXT when called from Interpreter.evaluate (no-tx path).
+          #
+          # The version is always encoded as exactly 4 bytes (LE uint32), never as
+          # a ScriptNumber. Version 1 → 01000000, version 2 → 02000000.
+          def op_ver
+            if @tx.nil?
+              raise ScriptError.new(
+                ScriptErrorCode::MISSING_TX_CONTEXT,
+                'OP_VER requires transaction context'
+              )
+            end
+
+            @dstack.push_bytes(tx_version_bytes)
+          end
+
+          # OP_VERIF: version-conditional branch — executes like OP_IF but compares
+          # the top stack item against the 4-byte LE transaction version rather than
+          # interpreting the item as a boolean.
+          #
+          # In an executing branch: pops bytes from the stack. If the bytes are
+          # exactly 4 bytes and match the current transaction version, the true
+          # branch executes; otherwise the false/else branch executes.
+          #
+          # In a non-executing branch: pushes +:false+ to track nesting depth
+          # without touching the data stack.
+          #
+          # If @tx is nil, +tx_version_matches?+ returns false — the else branch
+          # is always taken (not an error, unlike OP_VER).
+          def op_verif
+            if @cond_stack.length >= MAX_CONDITIONAL_DEPTH
+              raise ScriptError.new(
+                ScriptErrorCode::UNBALANCED_CONDITIONAL,
+                "conditional depth exceeded #{MAX_CONDITIONAL_DEPTH}"
+              )
+            end
+
+            if branch_executing?
+              data = @dstack.pop_bytes
+              @cond_stack.push(tx_version_matches?(data) ? :true : :false)
+            else
+              @cond_stack.push(:false)
+            end
+            @else_stack.push(false)
+          end
+
+          # OP_VERNOTIF: inverse version-conditional branch — executes like OP_NOTIF
+          # but compares against the 4-byte LE transaction version.
+          #
+          # In an executing branch: match → false branch (else), no match → true branch.
+          # In a non-executing branch: pushes +:false+ for nesting tracking only.
+          def op_vernotif
+            if @cond_stack.length >= MAX_CONDITIONAL_DEPTH
+              raise ScriptError.new(
+                ScriptErrorCode::UNBALANCED_CONDITIONAL,
+                "conditional depth exceeded #{MAX_CONDITIONAL_DEPTH}"
+              )
+            end
+
+            if branch_executing?
+              data = @dstack.pop_bytes
+              @cond_stack.push(tx_version_matches?(data) ? :false : :true)
+            else
+              @cond_stack.push(:false)
+            end
+            @else_stack.push(false)
+          end
+
+          # Returns the transaction version as a 4-byte little-endian binary
+          # string. Used by OP_VER, OP_VERIF, and OP_VERNOTIF.
+          def tx_version_bytes
+            [@tx.version].pack('V')
+          end
+
+          # Compares raw bytes against the current transaction version.
+          # Returns false if:
+          # - +data+ is not exactly 4 bytes
+          # - @tx is nil (no transaction context)
+          # - the bytes do not match the 4-byte LE encoding of @tx.version
+          def tx_version_matches?(data)
+            return false if @tx.nil? || data.bytesize != 4
+
+            data == tx_version_bytes
           end
         end
       end