Merge pull request #391 from sgbett/feat/377-sdk-cross-sdk-alignment-polish

feat: SDK cross-SDK alignment polish (F1.1, F1.2, F1.7, F3.18, F4.6, F4.10/F4.11, F5.11, F6.7, F6.16)

Author: sgbett

.rubocop.yml

@@ -9,6 +9,11 @@ AllCops:
 Style/Documentation:
   Enabled: false
 
+# `be > 0` is idiomatic RSpec for numeric comparisons; `be.positive?` is broken syntax.
+Style/NumericPredicate:
+  Exclude:
+    - 'gem/*/spec/**/*'
+
 Metrics/BlockLength:
   Exclude:
     - 'gem/bsv-wallet/lib/bsv/wallet_interface/wire/**/*'

gem/bsv-sdk/lib/bsv-sdk.rb

@@ -13,4 +13,5 @@ module BSV
   autoload :Identity,    'bsv/identity'
   autoload :Registry,    'bsv/registry'
   autoload :MCP,         'bsv/mcp'
+  autoload :Messages,    'bsv/messages'
 end

gem/bsv-sdk/lib/bsv/messages.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BSV
+  # Namespace providing TS SDK naming parity for messaging primitives.
+  #
+  # Re-exports {BSV::Primitives::SignedMessage} and {BSV::Primitives::EncryptedMessage}
+  # under the +BSV::Messages+ namespace, matching the structure of the TypeScript SDK
+  # (ts-sdk/src/messages/index.ts).
+  #
+  # The canonical implementations remain in +BSV::Primitives+; this module is a
+  # lightweight re-export only.
+  module Messages
+    SignedMessage = BSV::Primitives::SignedMessage
+    EncryptedMessage = BSV::Primitives::EncryptedMessage
+  end
+end

gem/bsv-sdk/lib/bsv/primitives/base58.rb

@@ -61,9 +61,9 @@ def encode(bytes)
       #
       # @param string [String] Base58-encoded string
       # @return [String] decoded binary data
-      # @raise [ArgumentError] if the string contains invalid Base58 characters
+      # @raise [ArgumentError] if the string is empty or contains invalid Base58 characters
       def decode(string)
-        return ''.b if string.empty?
+        raise ArgumentError, 'cannot decode empty string' if string.empty?
 
         # Count leading '1' characters (representing zero bytes)
         leading_ones = 0
@@ -89,19 +89,30 @@ def decode(string)
 
       # Encode binary data with a 4-byte double-SHA-256 checksum appended.
       #
+      # When +prefix+ is given, it is prepended to the payload before checksumming.
+      # The checksum covers the full +prefix + payload+ concatenation.
+      #
       # @param payload [String] binary data to encode
+      # @param prefix [String, nil] optional version prefix to prepend (binary string)
       # @return [String] Base58Check-encoded string
-      def check_encode(payload)
-        checksum = Digest.sha256d(payload)[0, 4]
-        encode(payload + checksum)
+      def check_encode(payload, prefix: nil)
+        full = (prefix || ''.b) + payload
+        checksum = Digest.sha256d(full)[0, 4]
+        encode(full + checksum)
       end
 
       # Decode a Base58Check string and verify its checksum.
       #
+      # When +prefix_length+ is greater than zero, the decoded payload is split
+      # into a prefix and data portion. The returned value is then a Hash with
+      # +:prefix+ and +:data+ keys. When +prefix_length+ is zero (default), the
+      # raw payload is returned unchanged for backwards compatibility.
+      #
       # @param string [String] Base58Check-encoded string
-      # @return [String] decoded payload (without checksum)
+      # @param prefix_length [Integer] number of leading bytes to treat as a prefix (default: 0)
+      # @return [String, Hash] decoded payload, or +{ prefix:, data: }+ when prefix_length > 0
       # @raise [ChecksumError] if the checksum does not match or input is too short
-      def check_decode(string)
+      def check_decode(string, prefix_length: 0)
         data = decode(string)
         raise ChecksumError, 'input too short for checksum' if data.length < 4
 
@@ -110,7 +121,11 @@ def check_decode(string)
         expected = Digest.sha256d(payload)[0, 4]
         raise ChecksumError, 'checksum mismatch' unless checksum == expected
 
-        payload
+        return payload if prefix_length.zero?
+
+        raise ArgumentError, 'prefix_length exceeds payload' if prefix_length > payload.length
+
+        { prefix: payload[0, prefix_length], data: payload[prefix_length..] }
       end
     end
   end

gem/bsv-sdk/lib/bsv/primitives/digest.rb

@@ -38,6 +38,9 @@ def sha256d(data)
         sha256(sha256(data))
       end
 
+      alias hash256 sha256d
+      module_function :hash256
+
       # Compute SHA-512 digest.
       #
       # @param data [String] binary data to hash

gem/bsv-sdk/lib/bsv/primitives/ecies.rb

@@ -33,8 +33,9 @@ class DecryptionError < StandardError; end
       # @param message [String] the plaintext message
       # @param public_key [PublicKey] the recipient's public key
       # @param private_key [PrivateKey, nil] optional ephemeral key (random if omitted)
-      # @return [String] encrypted payload: BIE1 magic + ephemeral pubkey + ciphertext + HMAC
-      def encrypt(message, public_key, private_key: nil)
+      # @param no_key [Boolean] when +true+, omit the ephemeral public key from the payload
+      # @return [String] encrypted payload: BIE1 magic + [ephemeral pubkey] + ciphertext + HMAC
+      def encrypt(message, public_key, private_key: nil, no_key: false)
         message = message.b if message.encoding != Encoding::ASCII_8BIT
 
         ephemeral = private_key || PrivateKey.generate
@@ -48,7 +49,11 @@ def encrypt(message, public_key, private_key: nil)
         cipher.iv = iv
         ciphertext = message.empty? ? cipher.final : cipher.update(message) + cipher.final
 
-        payload = MAGIC + ephemeral_pub.compressed + ciphertext
+        payload = if no_key
+                    MAGIC + ciphertext
+                  else
+                    MAGIC + ephemeral_pub.compressed + ciphertext
+                  end
         mac = Digest.hmac_sha256(key_m, payload)
 
         payload + mac
@@ -58,29 +63,64 @@ def encrypt(message, public_key, private_key: nil)
       #
       # Verifies the HMAC before attempting decryption (encrypt-then-MAC).
       #
+      # The ephemeral public key may be embedded in the payload (compressed or
+      # uncompressed), or absent entirely (when the payload was encrypted with
+      # +no_key: true+). When absent, +sender_public_key+ must be provided.
+      #
+      # If a key is found in the payload and +sender_public_key+ is also given,
+      # the payload key takes precedence (matching TS SDK behaviour).
+      #
       # @param data [String] the encrypted payload (BIE1 format)
       # @param private_key [PrivateKey] the recipient's private key
+      # @param sender_public_key [PublicKey, nil] sender's public key (required when no key in payload)
       # @return [String] the decrypted plaintext
-      # @raise [ArgumentError] if the data is too short or has invalid magic bytes
+      # @raise [ArgumentError] if the data is too short, has invalid magic, or has no key and none provided
       # @raise [DecryptionError] if HMAC verification or AES decryption fails
-      def decrypt(data, private_key)
+      def decrypt(data, private_key, sender_public_key: nil)
         data = data.b if data.encoding != Encoding::ASCII_8BIT
 
-        raise ArgumentError, 'data too short' if data.bytesize < 85
+        # Minimum: magic(4) + ciphertext(16) + HMAC(32) = 52 (no-key case)
+        raise ArgumentError, 'data too short' if data.bytesize < 52
 
         magic = data[0, 4]
         raise ArgumentError, 'invalid magic: expected BIE1' unless magic == MAGIC
 
-        ephemeral_pub_bytes = data[4, 33]
-        mac = data[-32, 32]
-        ciphertext = data[37...-32]
+        # Determine ephemeral key presence and format by inspecting byte at offset 4.
+        # Ambiguity note: a no-key payload whose ciphertext starts with 0x02/0x03/0x04
+        # could be misinterpreted as containing an embedded key. The HMAC check below
+        # will catch this (wrong shared secret → HMAC mismatch), but the resulting
+        # error message will be misleading. This is a TS SDK design inheritance —
+        # the wire format has no explicit key-presence flag.
+        # Guard: only attempt to read a key if sufficient bytes remain beyond HMAC.
+        tag_length = 32
+        offset = 4
+        ephemeral_pub = nil
+
+        remaining_after_offset = data.bytesize - offset - tag_length
+        if remaining_after_offset >= 33
+          first_byte = data.getbyte(offset)
+          if [0x02, 0x03].include?(first_byte)
+            # Compressed key: 33 bytes
+            ephemeral_pub = PublicKey.from_bytes(data[offset, 33])
+            offset += 33
+          elsif first_byte == 0x04 && remaining_after_offset >= 65
+            # Uncompressed key: 65 bytes
+            ephemeral_pub = PublicKey.from_bytes(data[offset, 65])
+            offset += 65
+          end
+        end
+
+        # If no key found in payload, fall back to provided sender_public_key
+        ephemeral_pub ||= sender_public_key
+        raise ArgumentError, 'sender_public_key required when no key in payload' if ephemeral_pub.nil?
 
-        ephemeral_pub = PublicKey.from_bytes(ephemeral_pub_bytes)
+        mac = data[-tag_length, tag_length]
+        ciphertext = data[offset...-tag_length]
 
         iv, key_e, key_m = derive_keys(private_key, ephemeral_pub)
 
         # Verify HMAC before decryption (encrypt-then-MAC)
-        payload = data[0...-32]
+        payload = data[0...-tag_length]
         expected_mac = Digest.hmac_sha256(key_m, payload)
 
         raise DecryptionError, 'HMAC verification failed' unless secure_compare(mac, expected_mac)

gem/bsv-sdk/lib/bsv/script/script.rb

@@ -144,11 +144,19 @@ def self.op_return(*data_items)
 
       # Construct a Pay-to-Public-Key-Hash (P2PKH) locking script.
       #
-      # @param pubkey_hash [String] 20-byte public key hash
+      # Accepts either a raw 20-byte binary hash or a Base58Check address string.
+      # When given an address string, the version prefix is validated: +0x00+
+      # (mainnet) and +0x6f+ (testnet) are accepted; +0x05+ (P2SH) is rejected
+      # with a clear error message.
+      #
+      # @param pubkey_hash_or_address [String] 20-byte binary pubkey hash, or a
+      #   Base58Check address string
       # @return [Script]
-      # @raise [ArgumentError] if pubkey_hash is not 20 bytes
-      def self.p2pkh_lock(pubkey_hash)
-        raise ArgumentError, 'pubkey_hash must be 20 bytes' unless pubkey_hash.bytesize == 20
+      # @raise [ArgumentError] if the argument is not a valid 20-byte hash, if the
+      #   address has an unrecognised prefix, or if a P2SH address is supplied
+      # @raise [BSV::Primitives::Base58::ChecksumError] if the address checksum is invalid
+      def self.p2pkh_lock(pubkey_hash_or_address)
+        pubkey_hash = resolve_pubkey_hash(pubkey_hash_or_address)
 
         buf = [
           Opcodes::OP_DUP,
@@ -159,6 +167,37 @@ def self.p2pkh_lock(pubkey_hash)
         new(buf)
       end
 
+      # @api private
+      # Resolve a pubkey_hash argument that may be a raw binary hash or a
+      # Base58Check address string.
+      def self.resolve_pubkey_hash(arg)
+        # A 20-byte ASCII-8BIT string is treated as a raw binary hash.
+        return arg if arg.encoding == Encoding::ASCII_8BIT && arg.bytesize == 20
+
+        # Otherwise treat as a Base58Check address string.
+        decoded = BSV::Primitives::Base58.check_decode(arg, prefix_length: 1)
+        prefix = decoded[:prefix]
+        data   = decoded[:data]
+
+        p2sh_prefix = "\x05".b
+        mainnet_prefix = "\x00".b
+        testnet_prefix = "\x6f".b # accepted for testnet interop; no mainnet-only restriction
+
+        if prefix == p2sh_prefix
+          raise ArgumentError,
+                'P2SH addresses are not supported on BSV; ' \
+                'use p2pkh_lock with a P2PKH address or 20-byte hash'
+        end
+
+        raise ArgumentError, "unrecognised address prefix: 0x#{prefix.unpack1('H*')}" \
+          unless prefix == mainnet_prefix || prefix == testnet_prefix
+
+        raise ArgumentError, 'decoded hash must be 20 bytes' unless data.bytesize == 20
+
+        data
+      end
+      private_class_method :resolve_pubkey_hash
+
       # Construct a P2PKH unlocking script.
       #
       # @param signature_der [String] DER-encoded signature with sighash byte appended

gem/bsv-sdk/lib/bsv/transaction/merkle_path.rb

@@ -303,10 +303,29 @@ def compute_root_hex(txid_hex = nil)
       # Computes the merkle root from the path and txid, then checks it
       # against the blockchain via the provided chain tracker.
       #
+      # For coinbase transactions (offset 0 in the merkle tree), an additional
+      # maturity check is performed: the coinbase must have at least 100
+      # confirmations before it is considered spendable/valid.
+      #
+      # NOTE: The TS SDK has an inverted coinbase maturity check at MerklePath.ts:378
+      # (`this.blockHeight + 100 < height`), which rejects mature coinbase transactions
+      # and accepts immature ones — the opposite of the intended behaviour. The correct
+      # logic is: reject when `current_height - block_height < 100` (immature).
+      #
       # @param txid_hex [String] hex-encoded transaction ID (display order)
       # @param chain_tracker [ChainTracker] chain tracker to verify the root against
       # @return [Boolean] true if the computed root matches the block at this height
       def verify(txid_hex, chain_tracker)
+        txid_bytes = [txid_hex].pack('H*').reverse
+        txid_leaf = @path[0].find { |l| l.hash == txid_bytes }
+
+        # Offset 0 in a block's merkle tree is always the coinbase transaction —
+        # a Bitcoin protocol invariant. Apply the 100-block maturity check.
+        if txid_leaf&.offset&.zero?
+          current = chain_tracker.current_height
+          return false if current - @block_height < 100
+        end
+
         root_hex = compute_root_hex(txid_hex)
         chain_tracker.valid_root_for_height?(root_hex, @block_height)
       end

gem/bsv-sdk/lib/bsv/transaction/transaction.rb

@@ -801,7 +801,7 @@ def compute_fee_sats(model_or_fee)
         when FeeModel
           model_or_fee.compute_fee(self)
         when Numeric
-          model_or_fee.ceil
+          model_or_fee.ceil # round up — fractional satoshis from callers are not valid; rounding up prevents underpayment
         else
           raise ArgumentError, "expected FeeModel, Numeric, or nil; got #{model_or_fee.class}"
         end

gem/bsv-sdk/lib/bsv/transaction/transaction_input.rb

@@ -15,7 +15,7 @@ class TransactionInput
       attr_reader :prev_tx_out_index
 
       # @return [Integer] sequence number (default: 0xFFFFFFFF)
-      attr_reader :sequence
+      attr_accessor :sequence
 
       # @return [Script::Script, nil] the unlocking script (set after signing)
       attr_accessor :unlocking_script