bsv-sdk 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed81ad480647a52136c32f6bd786fd8a0a590aa6d2805fb02151b583c6b8664b
-  data.tar.gz: c6eba8e1020913d59958d68b028b66ef7035d494f3c5d34dbd98c401ab30ec35
+  metadata.gz: d8f24ed29fd0a8beb572b3737c3bbfaba5bf939c5fe20d485306e5e4374587c1
+  data.tar.gz: 53746a1cdad1370718892805b76c763fbe58a73ef057bd65a1eaa4b1b120c7bd
 SHA512:
-  metadata.gz: aa4673f314ac7dddcb94d04d8e9c6db75a2c635c298e46d9412ee65babb491fd514f1bc37e94996206a41ad7d35ff1c2f57554913201be67e532700793b187da
-  data.tar.gz: ca38730828db7c78299a8eee34a682c5781f8cdae44186d7762b12030158f0f696d78204819f832e8f2bb8f913298100f9c55fb7a6f1f89cce4453c759d5e2c1
+  metadata.gz: 93590d116e66151f51af5167bb405b2d91cd2997f685fad0d684cd07f5231aa1387d57d71852e5464f3f222d1b471534d22ab6633c75d188f9080c1718f834a0
+  data.tar.gz: b26e9a26837af3ce9426311050c0e2fbbdaac9ce4d04a7987c123ef189ec6528e779c69bd7b77605e25df70c1510327a71b7843151f50eb710b2b63a788eeae2

data/CHANGELOG.md

@@ -5,6 +5,71 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-03-07
+
+### Fixed
+
+- Truncated OP_PUSHDATA1/2/4 scripts now raise `ArgumentError` instead of crashing with `TypeError`
+- `Transaction#to_beef` uses `merge_bump` to correctly handle multiple ancestors at the same block height
+- `PrivateKey#derive_child` uses `BN.mod_add` instead of Integer roundtrip for modular addition
+- Fixed txid byte-order documentation (display order, not internal order)
+
+### Testing
+
+- FORKID enforcement spec verifying interpreter rejects signatures without SIGHASH_FORKID
+- ExtendedKey fingerprint chain integrity across 3-generation derivation
+- Mnemonic entropy round-trip across all 5 valid entropy lengths
+- BEEF spec for multiple ancestors at the same block height
+
+## [0.2.0] - 2026-03-07
+
+### Added
+
+#### Primitives
+
+- ECDH shared secret derivation (`PrivateKey#derive_shared_secret`, `PublicKey#derive_shared_secret`)
+- BRC-42 key derivation (`PrivateKey#derive_child`, `PublicKey#derive_child`) with official spec test vectors
+
+#### Transaction
+
+- Chain tracker interface (`ChainTracker` base class) with WhatsOnChain implementation
+- Fee model interface (`FeeModel` base class) with `SatoshisPerKilobyte` implementation
+- `Transaction#fee` with change output distribution across multiple change outputs
+- `Transaction#verify` for full SPV verification (merkle path, script execution, recursive ancestry)
+- `TransactionOutput#change` flag for identifying change outputs
+- `MerklePath#verify` for SPV chain tracker integration
+- BEEF completion: `Beef#merge`, `Beef#valid?`, lookup methods (`find_bump`, `find_transaction_for_signing`)
+- `Transaction#to_beef` / `Transaction.from_beef` convenience methods
+- Extended Format (EF) transaction serialisation (`to_ef`, `to_ef_hex`, `from_ef`, `from_ef_hex`)
+- `VerificationError` with typed error codes for SPV verification failures
+
+### Changed
+
+- ECIES refactored to use `PrivateKey#derive_shared_secret` internally (no API change)
+- `Transaction#estimated_size` made public for fee model access
+
+### Fixed
+
+- Nil `source_satoshis` now raises instead of silently coercing to zero in fee distribution and verification
+- Script chunk round-trips preserve original push encoding
+- `OP_RETURN` inside conditionals correctly checked for conditional balance
+- Point x-coordinate extraction preserves leading zeros via octet string
+- `Integer#nobits?` replaced with Ruby 2.7-compatible bitwise check
+- Defensive parsing with descriptive errors for truncated binary input
+
+### Testing
+
+- BRC-42 conformance specs with 9 official specification test vectors
+- ECDH conformance specs (commutativity, cross-method, pinned known-key vector)
+- SPV verification conformance specs (merkle path, script execution, ancestry)
+- Fee model conformance specs (formula validation, default rate, change distribution)
+- Chain tracker conformance specs
+- BEEF cross-SDK conformance vectors
+- Schnorr (BRC-94) cross-SDK interoperability vectors
+- 6 exact-match RFC 6979 vectors from Trezor/CoreBitcoin
+- VarInt boundary tests at size-prefix transitions
+- Script vectors converted to tracked known-failures system
+
 ## [0.1.0] - 2026-02-14
 
 Initial release of the BSV Ruby SDK.

data/lib/bsv/primitives/curve.rb

@@ -65,9 +65,9 @@ module BSV
       # @param point [OpenSSL::PKey::EC::Point] the curve point
       # @return [OpenSSL::BN] the x-coordinate
       def point_x(point)
-        x_hex = point.to_bn(:uncompressed).to_s(16)
-        # Uncompressed format: 04 || X (64 hex) || Y (64 hex)
-        OpenSSL::BN.new(x_hex[2, 64], 16)
+        # Uncompressed octet string: 0x04 || X (32 bytes) || Y (32 bytes)
+        # Slicing raw bytes avoids BN#to_s(16) stripping leading zeros.
+        OpenSSL::BN.new(point.to_octet_string(:uncompressed)[1, 32], 2)
       end
 
       # Reconstruct a curve point from its byte representation.

data/lib/bsv/primitives/ecies.rb

@@ -39,7 +39,7 @@ module BSV
         ephemeral = private_key || PrivateKey.generate
         ephemeral_pub = ephemeral.public_key
 
-        iv, key_e, key_m = derive_keys(public_key.point, ephemeral.bn)
+        iv, key_e, key_m = derive_keys(ephemeral, public_key)
 
         cipher = OpenSSL::Cipher.new('aes-128-cbc')
         cipher.encrypt
@@ -76,7 +76,7 @@ module BSV
 
         ephemeral_pub = PublicKey.from_bytes(ephemeral_pub_bytes)
 
-        iv, key_e, key_m = derive_keys(ephemeral_pub.point, private_key.bn)
+        iv, key_e, key_m = derive_keys(private_key, ephemeral_pub)
 
         # Verify HMAC before decryption (encrypt-then-MAC)
         payload = data[0...-32]
@@ -111,9 +111,9 @@ module BSV
           end
         end
 
-        def derive_keys(point, scalar_bn)
-          shared_point = Curve.multiply_point(point, scalar_bn)
-          ecdh_key = shared_point.to_octet_string(:compressed)
+        def derive_keys(private_key, public_key)
+          shared = private_key.derive_shared_secret(public_key)
+          ecdh_key = shared.compressed
           derived = Digest.sha512(ecdh_key)
 
           iv    = derived[0, 16]

data/lib/bsv/primitives/private_key.rb

@@ -127,6 +127,40 @@ module BSV
         @public_key ||= PublicKey.new(Curve.multiply_generator(@bn))
       end
 
+      # Derive an ECDH shared secret with another party's public key.
+      #
+      # Computes the shared point by multiplying the given public key by
+      # this private key's scalar. The result is commutative:
+      #   alice_priv.derive_shared_secret(bob_pub) ==
+      #     bob_priv.derive_shared_secret(alice_pub)
+      #
+      # This is the foundational primitive for BRC-42 key derivation,
+      # BRC-77/78 messaging, and ECIES encryption.
+      #
+      # @param public_key [PublicKey] the other party's public key
+      # @return [PublicKey] the shared secret as a public key (curve point)
+      def derive_shared_secret(public_key)
+        shared_point = Curve.multiply_point(public_key.point, @bn)
+        PublicKey.new(shared_point)
+      end
+
+      # Derive a child private key using BRC-42 key derivation.
+      #
+      # Computes HMAC-SHA256(key: ECDH_shared_secret, msg: invoice_number)
+      # and adds it to this private key's scalar mod n. The corresponding
+      # public key can be derived without the private key using
+      # {PublicKey#derive_child}.
+      #
+      # @param public_key [PublicKey] the counterparty's public key
+      # @param invoice_number [String] the invoice number (UTF-8)
+      # @return [PrivateKey] the derived child private key
+      def derive_child(public_key, invoice_number)
+        shared = derive_shared_secret(public_key)
+        hmac = Digest.hmac_sha256(shared.compressed, invoice_number.encode('UTF-8'))
+        hmac_bn = OpenSSL::BN.new(hmac.unpack1('H*'), 16)
+        PrivateKey.new(@bn.mod_add(hmac_bn, Curve::N))
+      end
+
       # Sign a 32-byte hash using deterministic ECDSA (RFC 6979).
       #
       # @param hash [String] 32-byte message digest to sign

data/lib/bsv/primitives/public_key.rb

@@ -99,6 +99,42 @@ module BSV
         Base58.check_encode(prefix + hash160)
       end
 
+      # Derive an ECDH shared secret with another party's private key.
+      #
+      # Computes the shared point by multiplying this public key by the
+      # given private key's scalar. The result is commutative:
+      #   alice_pub.derive_shared_secret(bob_priv) ==
+      #     bob_pub.derive_shared_secret(alice_priv)
+      #
+      # This is the foundational primitive for BRC-42 key derivation,
+      # BRC-77/78 messaging, and ECIES encryption.
+      #
+      # @param private_key [PrivateKey] the other party's private key
+      # @return [PublicKey] the shared secret as a public key (curve point)
+      def derive_shared_secret(private_key)
+        shared_point = Curve.multiply_point(@point, private_key.bn)
+        PublicKey.new(shared_point)
+      end
+
+      # Derive a child public key using BRC-42 key derivation.
+      #
+      # Computes HMAC-SHA256(key: ECDH_shared_secret, msg: invoice_number)
+      # and adds the corresponding curve point to this public key. The result
+      # matches the public key of {PrivateKey#derive_child} with the same
+      # inputs, enabling public-key-only derivation.
+      #
+      # @param private_key [PrivateKey] the counterparty's private key
+      # @param invoice_number [String] the invoice number (UTF-8)
+      # @return [PublicKey] the derived child public key
+      def derive_child(private_key, invoice_number)
+        shared = derive_shared_secret(private_key)
+        hmac = Digest.hmac_sha256(shared.compressed, invoice_number.encode('UTF-8'))
+        hmac_bn = OpenSSL::BN.new(hmac.unpack1('H*'), 16)
+        hmac_point = Curve.multiply_generator(hmac_bn)
+        child_point = Curve.add_points(@point, hmac_point)
+        PublicKey.new(child_point)
+      end
+
       # Verify an ECDSA signature against a message hash.
       #
       # @param hash [String] 32-byte message digest

data/lib/bsv/primitives/signature.rb

@@ -50,7 +50,7 @@ module BSV
 
         r_bytes = bytes[4, r_len]
         raise ArgumentError, 'R has negative flag' if r_bytes[0] & 0x80 != 0
-        raise ArgumentError, 'R has excessive padding' if r_len > 1 && r_bytes[0].zero? && r_bytes[1].nobits?(0x80)
+        raise ArgumentError, 'R has excessive padding' if r_len > 1 && r_bytes[0].zero? && (r_bytes[1] & 0x80).zero? # rubocop:disable Style/BitwisePredicate
 
         # Parse S
         s_offset = 4 + r_len
@@ -62,7 +62,7 @@ module BSV
 
         s_bytes = bytes[s_offset + 2, s_len]
         raise ArgumentError, 'S has negative flag' if s_bytes[0] & 0x80 != 0
-        raise ArgumentError, 'S has excessive padding' if s_len > 1 && s_bytes[0].zero? && s_bytes[1].nobits?(0x80)
+        raise ArgumentError, 'S has excessive padding' if s_len > 1 && s_bytes[0].zero? && (s_bytes[1] & 0x80).zero? # rubocop:disable Style/BitwisePredicate
 
         raise ArgumentError, 'trailing bytes' unless s_offset + 2 + s_len == bytes.length
 

data/lib/bsv/script/chunk.rb

@@ -29,12 +29,24 @@ module BSV
 
       # Serialise this chunk back to raw script bytes.
       #
+      # Preserves the original push encoding (including non-minimal pushes)
+      # so that round-tripping through parse/serialise does not alter the
+      # script bytes. This is critical for sighash computation.
+      #
       # @return [String] binary script bytes for this chunk
       def to_binary
-        if @data
-          push_data_binary(@data)
+        return [@opcode].pack('C') unless @data
+
+        case @opcode
+        when Opcodes::OP_PUSHDATA1
+          [Opcodes::OP_PUSHDATA1, @data.bytesize].pack('CC') + @data
+        when Opcodes::OP_PUSHDATA2
+          [Opcodes::OP_PUSHDATA2].pack('C') + [@data.bytesize].pack('v') + @data
+        when Opcodes::OP_PUSHDATA4
+          [Opcodes::OP_PUSHDATA4].pack('C') + [@data.bytesize].pack('V') + @data
         else
-          [@opcode].pack('C')
+          # Direct push: opcode IS the length (0x01..0x4b)
+          [@opcode].pack('C') + @data
         end
       end
 
@@ -56,22 +68,6 @@ module BSV
       def ==(other)
         other.is_a?(Chunk) && @opcode == other.opcode && @data == other.data
       end
-
-      private
-
-      def push_data_binary(data)
-        len = data.bytesize
-
-        if len <= 0x4b
-          [len].pack('C') + data
-        elsif len <= 0xff
-          [Opcodes::OP_PUSHDATA1, len].pack('CC') + data
-        elsif len <= 0xffff
-          [Opcodes::OP_PUSHDATA2, len].pack('Cv') + data
-        else
-          [Opcodes::OP_PUSHDATA4, len].pack('CV') + data
-        end
-      end
     end
   end
 end

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

@@ -28,7 +28,7 @@ module BSV
     #     unlock_script: input.script, lock_script: prev_output.script,
     #     satoshis: prev_output.satoshis
     #   )
-    class Interpreter # rubocop:disable Metrics/ClassLength
+    class Interpreter
       include Operations::DataPush
       include Operations::StackOps
       include Operations::FlowControl
@@ -80,7 +80,7 @@ module BSV
         ).execute
       end
 
-      def execute # rubocop:disable Naming/PredicateMethod
+      def execute
         scripts = [@unlock_script, @lock_script]
 
         scripts.each_with_index do |script, script_idx|
@@ -106,6 +106,7 @@ module BSV
           # Reset state for next script
           @last_code_sep = 0
           @early_return = false
+          @after_op_return = false
         end
 
         check_final_stack
@@ -127,6 +128,7 @@ module BSV
         @else_stack = []
         @last_code_sep = 0
         @early_return = false
+        @after_op_return = false
         @current_script = nil
         @current_chunk_idx = 0
       end
@@ -134,6 +136,14 @@ module BSV
       def execute_opcode(chunk)
         opcode = chunk.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
+          return
+        end
+
         # In non-executing branch: only dispatch conditional opcodes (for nesting tracking).
         # All other opcodes are skipped.
         unless branch_executing?
@@ -261,7 +271,7 @@ module BSV
       # Is the current conditional branch executing?
       # Checks ALL entries — a :false anywhere means we're not executing.
       def branch_executing?
-        @cond_stack.none? { |v| v == :false } # rubocop:disable Lint/BooleanSymbol
+        @cond_stack.none? { |v| v == :false }
       end
 
       def conditional_opcode?(opcode)

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

@@ -6,7 +6,7 @@ module BSV
       module Operations
         # Arithmetic and comparison operations including restored post-Genesis
         # opcodes: MUL, DIV, MOD, LSHIFT, RSHIFT.
-        module Arithmetic # rubocop:disable Metrics/ModuleLength
+        module Arithmetic
           private
 
           # OP_1ADD: increment top by 1

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

@@ -5,7 +5,7 @@ module BSV
     class Interpreter
       module Operations
         # Cryptographic operations: hash functions, CHECKSIG, and CHECKMULTISIG.
-        module Crypto # rubocop:disable Metrics/ModuleLength
+        module Crypto
           private
 
           # --- Hash operations ---

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

@@ -11,9 +11,9 @@ module BSV
           # OP_IF: conditional execution
           def op_if
             if branch_executing?
-              @cond_stack.push(@dstack.pop_bool ? :true : :false) # rubocop:disable Lint/BooleanSymbol
+              @cond_stack.push(@dstack.pop_bool ? :true : :false)
             else
-              @cond_stack.push(:false) # rubocop:disable Lint/BooleanSymbol
+              @cond_stack.push(:false)
             end
             @else_stack.push(false)
           end
@@ -21,9 +21,9 @@ module BSV
           # OP_NOTIF: inverse conditional execution
           def op_notif
             if branch_executing?
-              @cond_stack.push(@dstack.pop_bool ? :false : :true) # rubocop:disable Lint/BooleanSymbol
+              @cond_stack.push(@dstack.pop_bool ? :false : :true)
             else
-              @cond_stack.push(:false) # rubocop:disable Lint/BooleanSymbol
+              @cond_stack.push(:false)
             end
             @else_stack.push(false)
           end
@@ -38,8 +38,8 @@ module BSV
             raise ScriptError.new(ScriptErrorCode::UNBALANCED_CONDITIONAL, 'duplicate OP_ELSE') if @else_stack.pop
 
             case @cond_stack.last
-            when :true  then @cond_stack[-1] = :false # rubocop:disable Lint/BooleanSymbol
-            when :false then @cond_stack[-1] = :true  # rubocop:disable Lint/BooleanSymbol
+            when :true  then @cond_stack[-1] = :false
+            when :false then @cond_stack[-1] = :true
             end
 
             @else_stack.push(true)
@@ -62,9 +62,16 @@ module BSV
             raise ScriptError.new(ScriptErrorCode::VERIFY_FAILED, 'OP_VERIFY failed')
           end
 
-          # OP_RETURN: after-genesis early termination (success)
+          # OP_RETURN: after-genesis early termination.
+          # At top level (outside conditionals): immediate success.
+          # Inside a conditional: remaining opcodes are skipped but conditional
+          # balance is still checked at script end.
           def op_return
-            @early_return = true
+            if @cond_stack.empty?
+              @early_return = true
+            else
+              @after_op_return = true
+            end
           end
 
           # OP_NOP and OP_NOP1..OP_NOP10 (including CLTV/CSV treated as NOP)

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

@@ -11,7 +11,7 @@ module BSV
     # the MSB of the last byte, and the magnitude is stored little-endian.
     # This class handles encoding/decoding, minimal encoding validation,
     # and arithmetic operations as required by the script interpreter.
-    class ScriptNumber # rubocop:disable Metrics/ClassLength
+    class ScriptNumber
       include Comparable
 
       # Maximum byte length for script numbers (post-Genesis: 750 KB).

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

@@ -11,7 +11,7 @@ module BSV
     # Implements Forth-like stack manipulation operations (dup, drop, swap,
     # rot, over, pick, roll, tuck) parameterised by count for the multi-element
     # opcodes (OP_2DUP, OP_2SWAP, etc.).
-    class Stack # rubocop:disable Metrics/ClassLength
+    class Stack
       def initialize
         @items = []
       end
@@ -168,7 +168,7 @@ module BSV
       # --- Boolean conversion ---
 
       # Bitcoin consensus boolean: false if empty, all-zero, or negative zero (0x80 last byte).
-      def self.cast_bool(bytes) # rubocop:disable Naming/PredicateMethod
+      def self.cast_bool(bytes)
         return false if bytes.nil? || bytes.empty?
 
         bytes.each_byte.with_index do |byte, i|

data/lib/bsv/script/script.rb

@@ -391,22 +391,26 @@ module BSV
           pos += 1
 
           if opcode.positive? && opcode <= 0x4b
+            raise ArgumentError, "truncated script: need #{opcode} data bytes at offset #{pos}" if pos + opcode > raw.bytesize
             data = raw.byteslice(pos, opcode)
             pos += opcode
             result << Chunk.new(opcode: opcode, data: data)
           elsif opcode == Opcodes::OP_PUSHDATA1
+            raise ArgumentError, "truncated script: OP_PUSHDATA1 missing length byte at offset #{pos}" if pos >= raw.bytesize
             len = raw.getbyte(pos)
             pos += 1
             data = raw.byteslice(pos, len)
             pos += len
             result << Chunk.new(opcode: opcode, data: data)
           elsif opcode == Opcodes::OP_PUSHDATA2
+            raise ArgumentError, "truncated script: OP_PUSHDATA2 needs 2 length bytes at offset #{pos}" if pos + 2 > raw.bytesize
             len = raw.byteslice(pos, 2).unpack1('v')
             pos += 2
             data = raw.byteslice(pos, len)
             pos += len
             result << Chunk.new(opcode: opcode, data: data)
           elsif opcode == Opcodes::OP_PUSHDATA4
+            raise ArgumentError, "truncated script: OP_PUSHDATA4 needs 4 length bytes at offset #{pos}" if pos + 4 > raw.bytesize
             len = raw.byteslice(pos, 4).unpack1('V')
             pos += 4
             data = raw.byteslice(pos, len)