bsv-sdk 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c8eb40d6b6cfbf03769704b141d681d92229d780abf1efe4d9e32a01db4c90d
-  data.tar.gz: 43950d736297f149ad6fff69d88ebe342111dc1c9259b3fb5b0b78ea90492e47
+  metadata.gz: 392488d3baa5c87f80eda541ca38b55ef0c4c55aa0848acdee995e6f4d1b79b1
+  data.tar.gz: 10bc2f546ec61020eac37158792de00328db64150d1f394375e4287cf32c5ab2
 SHA512:
-  metadata.gz: b0a2a209b899e5f5b4527c91c880fe3c0c3113c155ea5ce34d87496a956656cbe06e78a0b02b03b17da2355c97e91e597352c2fceda438185802f1665fdd4c0a
-  data.tar.gz: ec8d4fef6344e1f121dba4516c80d36f6089133d70ae355d69ac361b62b2aa712fec2e0a84e397db5545efc434e606004bf7ff5d3fddb573cfef5cdd4c46c052
+  metadata.gz: 973064e412dba805c930504c065fac014bfda41ef0306129e7035516b8c4f3f4450b1935667531ef2711a44ef8aad5bddecd146d36f3d35cb6fd2505bbc5be17
+  data.tar.gz: 46f59effd056e78c6a93d3fadcd4858550fc405a97032201e7d8daa2fdbcef60eb13fd87e15597b0250c4a7acebfa1773d76f095ea349baadf56ef27f2a3fb44

data/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.11.0 — 2026-04-12
+
+### Added
+- `Base58Check.check_encode` accepts `prefix:` parameter; `check_decode` accepts `prefix_length:` (F1.1)
+- `Base58.decode("")` raises `ArgumentError` instead of returning empty bytes (F1.2)
+- `Digest.hash256` alias for `sha256d` (F1.7)
+- `Script.p2pkh_lock` accepts Base58Check address strings as well as raw 20-byte hashes (F3.18)
+- `TransactionInput#sequence` and `TransactionOutput#locking_script` now writable via `attr_accessor` (F4.10/F4.11)
+- Coinbase 100-block maturity check in `MerklePath#verify` — intentionally diverges from TS SDK bug (F5.11)
+- ECIES Electrum `no_key:` encrypt and `sender_public_key:` decrypt with uncompressed key detection (F6.7)
+- `BSV::Messages` namespace re-exporting `SignedMessage` and `EncryptedMessage` (F6.16)
+
+### Fixed
+- `PointInFiniteField` zero-coordinate Base58 round-trip (BN(0) now encodes as `"\x00"`)
+- `p2pkh_lock` encoding check uses bytesize only — accepts 20-byte hashes regardless of string encoding
+- `Base58Check.check_decode` raises on `prefix_length` exceeding payload
+- ECIES key-format ambiguity documented (inherited TS SDK design)
+
+### Changed
+- Numeric fee `.ceil` behaviour documented with inline comment (F4.6)
+
 ## 0.10.1 — 2026-04-12
 
 ### Added

data/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

data/lib/bsv/primitives/base58.rb

@@ -61,9 +61,9 @@ module BSV
       #
       # @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 @@ module BSV
 
       # 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 @@ module BSV
         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

data/lib/bsv/primitives/digest.rb

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

data/lib/bsv/primitives/ecies.rb

@@ -33,8 +33,9 @@ module BSV
       # @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 @@ module BSV
         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 @@ module BSV
       #
       # 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)

data/lib/bsv/primitives/point_in_finite_field.rb

@@ -65,7 +65,10 @@ module BSV
       # Convert an OpenSSL::BN to a big-endian binary string, stripping the
       # sign byte that OpenSSL::BN#to_s(2) sometimes prepends.
       def bn_to_bytes(bn)
-        bn.to_s(2)
+        bytes = bn.to_s(2)
+        # BN(0).to_s(2) returns "" — encode as a single zero byte so
+        # Base58 round-trip works (Base58.decode raises on empty strings).
+        bytes.empty? ? "\x00".b : bytes
       end
     end
   end

data/lib/bsv/script/script.rb

@@ -144,11 +144,19 @@ module BSV
 
       # 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,40 @@ module BSV
         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 string is treated as a raw binary hash regardless of
+        # encoding — callers commonly pass `"\x00" * 20` which is UTF-8.
+        # A valid Base58Check address is always longer than 20 characters
+        # (25 raw bytes → ~34 Base58 characters), so this is unambiguous.
+        return arg.b if 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

data/lib/bsv/transaction/merkle_path.rb

@@ -303,10 +303,29 @@ module BSV
       # 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

data/lib/bsv/transaction/transaction.rb

@@ -801,7 +801,7 @@ module BSV
         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

data/lib/bsv/transaction/transaction_input.rb

@@ -15,7 +15,7 @@ module BSV
       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

data/lib/bsv/transaction/transaction_output.rb

@@ -12,7 +12,7 @@ module BSV
       attr_accessor :satoshis
 
       # @return [Script::Script] the locking script (spending conditions)
-      attr_reader :locking_script
+      attr_accessor :locking_script
 
       # @return [Boolean] whether this output receives change
       attr_accessor :change

data/lib/bsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BSV
-  VERSION = '0.10.1'
+  VERSION = '0.11.0'
 end

data/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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-04-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -57,6 +57,7 @@ files:
 - lib/bsv/mcp/tools/fetch_utxos.rb
 - lib/bsv/mcp/tools/generate_key.rb
 - lib/bsv/mcp/tools/helpers.rb
+- lib/bsv/messages.rb
 - lib/bsv/network.rb
 - lib/bsv/network/arc.rb
 - lib/bsv/network/broadcast_error.rb
@@ -164,7 +165,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby SDK for the BSV Blockchain
 test_files: []