bsv-sdk 0.1.0

data/lib/bsv/network/whats_on_chain.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module BSV
+  module Network
+    # WhatsOnChain chain data provider for reading transactions and UTXOs
+    # from the BSV network.
+    #
+    # Any object responding to #fetch_utxos(address) and
+    # #fetch_transaction(txid) can serve as a chain data provider;
+    # this class implements that contract using the WhatsOnChain API.
+    #
+    # The HTTP client is injectable for testability. It must respond to
+    # #request(uri, request) and return an object with #code and #body.
+    class WhatsOnChain
+      BASE_URL = 'https://api.whatsonchain.com'
+
+      def initialize(network: :mainnet, http_client: nil)
+        @network = network == :mainnet ? 'main' : 'test'
+        @http_client = http_client
+      end
+
+      # Fetch unspent transaction outputs for an address.
+      # @param address [String] BSV address
+      # @return [Array<UTXO>]
+      def fetch_utxos(address)
+        response = get("/v1/bsv/#{@network}/address/#{address}/unspent")
+        body = JSON.parse(response.body)
+
+        body.map do |entry|
+          UTXO.new(
+            tx_hash: entry['tx_hash'],
+            tx_pos: entry['tx_pos'],
+            satoshis: entry['value'],
+            height: entry['height']
+          )
+        end
+      end
+
+      # Fetch a raw transaction by its txid and parse it.
+      # @param txid [String] transaction ID (hex)
+      # @return [BSV::Transaction::Transaction]
+      def fetch_transaction(txid)
+        response = get("/v1/bsv/#{@network}/tx/#{txid}/hex")
+        BSV::Transaction::Transaction.from_hex(response.body)
+      end
+
+      private
+
+      def get(path)
+        uri = URI("#{BASE_URL}#{path}")
+        request = Net::HTTP::Get.new(uri)
+        response = execute(uri, request)
+        handle_response(response)
+        response
+      end
+
+      def execute(uri, request)
+        if @http_client
+          @http_client.request(uri, request)
+        else
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+            http.request(request)
+          end
+        end
+      end
+
+      def handle_response(response)
+        code = response.code.to_i
+        return if (200..299).cover?(code)
+
+        raise ChainProviderError.new(
+          response.body || "HTTP #{code}",
+          status_code: code
+        )
+      end
+    end
+  end
+end

data/lib/bsv/network.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module BSV
+  module Network
+    autoload :BroadcastError,     'bsv/network/broadcast_error'
+    autoload :BroadcastResponse,  'bsv/network/broadcast_response'
+    autoload :ChainProviderError, 'bsv/network/chain_provider_error'
+    autoload :UTXO,               'bsv/network/utxo'
+    autoload :ARC,                'bsv/network/arc'
+    autoload :WhatsOnChain,       'bsv/network/whats_on_chain'
+  end
+end

data/lib/bsv/primitives/base58.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module BSV
+  module Primitives
+    # Base58 and Base58Check encoding/decoding.
+    #
+    # Implements the Base58 alphabet used throughout Bitcoin for addresses,
+    # WIF keys, and extended keys. Base58Check adds a 4-byte double-SHA-256
+    # checksum for error detection.
+    #
+    # @example Encode and decode an address payload
+    #   encoded = BSV::Primitives::Base58.check_encode(payload)
+    #   decoded = BSV::Primitives::Base58.check_decode(encoded)
+    module Base58
+      # The Base58 alphabet (no 0, O, I, l to avoid visual ambiguity).
+      ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+      # The base (58).
+      BASE = ALPHABET.length # 58
+
+      # Reverse lookup table mapping ASCII byte values to Base58 digit indices.
+      DECODE_MAP = Array.new(256, -1).tap do |map|
+        ALPHABET.each_char.with_index { |c, i| map[c.ord] = i }
+      end.freeze
+
+      # Raised when a Base58Check checksum does not match.
+      class ChecksumError < StandardError; end
+
+      module_function
+
+      # Encode binary data as a Base58 string.
+      #
+      # Leading zero bytes are preserved as +'1'+ characters.
+      #
+      # @param bytes [String] binary data to encode
+      # @return [String] Base58-encoded string
+      def encode(bytes)
+        return '' if bytes.empty?
+
+        # Count leading zero bytes
+        leading_zeros = 0
+        bytes.each_byte { |b| b.zero? ? leading_zeros += 1 : break }
+
+        # Convert to big integer and repeatedly divide by 58
+        n = bytes.unpack1('H*').to_i(16)
+        result = +''
+        while n.positive?
+          n, remainder = n.divmod(BASE)
+          result << ALPHABET[remainder]
+        end
+
+        # Preserve leading zeros as '1' characters
+        result << (ALPHABET[0] * leading_zeros)
+        result.reverse!
+        result
+      end
+
+      # Decode a Base58 string to binary data.
+      #
+      # Leading +'1'+ characters are decoded as zero bytes.
+      #
+      # @param string [String] Base58-encoded string
+      # @return [String] decoded binary data
+      # @raise [ArgumentError] if the string contains invalid Base58 characters
+      def decode(string)
+        return ''.b if string.empty?
+
+        # Count leading '1' characters (representing zero bytes)
+        leading_ones = 0
+        string.each_char { |c| c == ALPHABET[0] ? leading_ones += 1 : break }
+
+        # Convert from base58 to integer
+        n = 0
+        string.each_char do |c|
+          digit = DECODE_MAP[c.ord]
+          raise ArgumentError, "invalid Base58 character: #{c.inspect}" if digit == -1
+
+          n = (n * BASE) + digit
+        end
+
+        # Convert integer to bytes
+        hex = n.zero? ? '' : n.to_s(16)
+        hex = "0#{hex}" if hex.length.odd?
+        result = [hex].pack('H*')
+
+        # Prepend zero bytes for leading '1' characters
+        (("\x00" * leading_ones) + result).b
+      end
+
+      # Encode binary data with a 4-byte double-SHA-256 checksum appended.
+      #
+      # @param payload [String] binary data to encode
+      # @return [String] Base58Check-encoded string
+      def check_encode(payload)
+        checksum = Digest.sha256d(payload)[0, 4]
+        encode(payload + checksum)
+      end
+
+      # Decode a Base58Check string and verify its checksum.
+      #
+      # @param string [String] Base58Check-encoded string
+      # @return [String] decoded payload (without checksum)
+      # @raise [ChecksumError] if the checksum does not match or input is too short
+      def check_decode(string)
+        data = decode(string)
+        raise ChecksumError, 'input too short for checksum' if data.length < 4
+
+        payload = data[0...-4]
+        checksum = data[-4..]
+        expected = Digest.sha256d(payload)[0, 4]
+        raise ChecksumError, 'checksum mismatch' unless checksum == expected
+
+        payload
+      end
+    end
+  end
+end

data/lib/bsv/primitives/bsm.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module BSV
+  module Primitives
+    # Bitcoin Signed Messages (BSM).
+    #
+    # Signs and verifies messages using the standard Bitcoin message signing
+    # protocol. Messages are prefixed with +"Bitcoin Signed Message:\n"+,
+    # length-prefixed, and double-SHA-256 hashed before signing with
+    # recoverable ECDSA. Signatures are 65-byte compact format, base64-encoded.
+    #
+    # @example Sign and verify a message
+    #   key = BSV::Primitives::PrivateKey.generate
+    #   sig = BSV::Primitives::BSM.sign('hello', key)
+    #   BSV::Primitives::BSM.verify('hello', sig, key.public_key.address) #=> true
+    module BSM
+      # The standard Bitcoin message signing prefix.
+      MAGIC_PREFIX = "Bitcoin Signed Message:\n".b.freeze
+
+      module_function
+
+      # Sign a message with a private key.
+      #
+      # Produces a 65-byte compact recoverable signature encoded as base64.
+      # The flag byte (31-34) indicates compressed P2PKH recovery per BIP-137.
+      #
+      # @param message [String] the message to sign
+      # @param private_key [PrivateKey] the signing key
+      # @return [String] base64-encoded compact signature
+      def sign(message, private_key)
+        hash = magic_hash(message)
+        sig, recovery_id = ECDSA.sign_recoverable(hash, private_key.bn)
+
+        # Flag byte: 31-34 = compressed P2PKH (BIP-137)
+        flag = 31 + recovery_id
+        compact = [flag].pack('C') + bn_to_bytes(sig.r) + bn_to_bytes(sig.s)
+        [compact].pack('m0')
+      end
+
+      # Verify a signed message against a Bitcoin address.
+      #
+      # Recovers the public key from the compact signature and checks
+      # whether the derived address matches the expected address.
+      #
+      # @param message [String] the original message
+      # @param signature [String] base64-encoded compact signature
+      # @param address [String] the expected Bitcoin address
+      # @return [Boolean] +true+ if the signature is valid for the given address
+      # @raise [ArgumentError] if the signature encoding or flag byte is invalid
+      def verify(message, signature, address)
+        compact = decode_compact(signature)
+        flag = compact.getbyte(0)
+        validate_flag!(flag)
+
+        recovery_id = (flag - 27) & 3
+        compressed = flag >= 31
+
+        r_bn = OpenSSL::BN.new(compact[1, 32], 2)
+        s_bn = OpenSSL::BN.new(compact[33, 32], 2)
+        sig = Signature.new(r_bn, s_bn)
+
+        hash = magic_hash(message)
+        pub = ECDSA.recover_public_key(hash, sig, recovery_id)
+
+        derived = if compressed
+                    pub.address
+                  else
+                    h160 = Digest.hash160(pub.uncompressed)
+                    Base58.check_encode(PublicKey::MAINNET_PUBKEY_HASH + h160)
+                  end
+
+        derived == address
+      rescue OpenSSL::PKey::EC::Point::Error
+        false
+      end
+
+      # Compute the double-SHA-256 hash of a Bitcoin-prefixed message.
+      #
+      # @param message [String] the message to hash
+      # @return [String] 32-byte double-SHA-256 digest
+      def magic_hash(message)
+        message = message.encode('UTF-8') if message.encoding != Encoding::UTF_8
+        msg_bytes = message.b
+        buf = encode_varint(MAGIC_PREFIX.bytesize) + MAGIC_PREFIX +
+              encode_varint(msg_bytes.bytesize) + msg_bytes
+        Digest.sha256d(buf)
+      end
+
+      class << self
+        private
+
+        def bn_to_bytes(bn)
+          bytes = bn.to_s(2)
+          bytes = ("\x00".b * (32 - bytes.length)) + bytes if bytes.length < 32
+          bytes
+        end
+
+        def decode_compact(signature)
+          compact = signature.unpack1('m0')
+          unless compact.bytesize == 65
+            raise ArgumentError,
+                  "invalid signature length: #{compact.bytesize} (expected 65)"
+          end
+
+          compact
+        rescue ArgumentError => e
+          raise e if e.message.include?('invalid signature length')
+
+          raise ArgumentError, "invalid base64 encoding: #{e.message}"
+        end
+
+        def validate_flag!(flag)
+          return if flag.between?(27, 34)
+
+          raise ArgumentError,
+                "flag byte #{flag} out of range (expected 27-34)"
+        end
+
+        def encode_varint(len)
+          if len < 0xFD
+            [len].pack('C')
+          elsif len <= 0xFFFF
+            "\xFD".b + [len].pack('v')
+          else
+            "\xFE".b + [len].pack('V')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/primitives/curve.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # Low-level secp256k1 elliptic curve operations.
+    #
+    # Wraps +OpenSSL::PKey::EC+ to provide point arithmetic, scalar
+    # multiplication, and key construction helpers used throughout the SDK.
+    # All constants and methods operate on the secp256k1 curve.
+    module Curve
+      # The secp256k1 curve group.
+      GROUP  = OpenSSL::PKey::EC::Group.new('secp256k1')
+
+      # The curve order (number of points on the curve).
+      N      = GROUP.order
+
+      # The generator point (base point).
+      G      = GROUP.generator
+
+      # Half the curve order, used for low-S normalisation.
+      HALF_N = (N >> 1)
+
+      module_function
+
+      # Multiply the generator point by a scalar.
+      #
+      # @param scalar_bn [OpenSSL::BN] the scalar multiplier
+      # @return [OpenSSL::PKey::EC::Point] the resulting curve point
+      def multiply_generator(scalar_bn)
+        G.mul(scalar_bn)
+      end
+
+      # Multiply an arbitrary curve point by a scalar.
+      #
+      # @param point [OpenSSL::PKey::EC::Point] the point to multiply
+      # @param scalar_bn [OpenSSL::BN] the scalar multiplier
+      # @return [OpenSSL::PKey::EC::Point] the resulting curve point
+      def multiply_point(point, scalar_bn)
+        point.mul(scalar_bn)
+      end
+
+      # Add two curve points together.
+      #
+      # Uses +Point#add+ where available (Ruby 3.0+ / OpenSSL 3), falling
+      # back to multi-scalar multiplication for Ruby 2.7 compatibility.
+      #
+      # @param point_a [OpenSSL::PKey::EC::Point] first point
+      # @param point_b [OpenSSL::PKey::EC::Point] second point
+      # @return [OpenSSL::PKey::EC::Point] the sum of the two points
+      def add_points(point_a, point_b)
+        if point_a.respond_to?(:add)
+          point_a.add(point_b)
+        else
+          # Ruby 2.7 / OpenSSL < 3: use multi-scalar mul
+          # point_a.mul(bns, points) = bns[0]*point_a + bns[1]*points[0] + ...
+          one = OpenSSL::BN.new('1')
+          point_a.mul([one, one], [point_b])
+        end
+      end
+
+      # Extract the x-coordinate from a curve point as a big number.
+      #
+      # @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)
+      end
+
+      # Reconstruct a curve point from its byte representation.
+      #
+      # @param bytes [String] compressed (33 bytes) or uncompressed (65 bytes) point encoding
+      # @return [OpenSSL::PKey::EC::Point] the decoded curve point
+      def point_from_bytes(bytes)
+        OpenSSL::PKey::EC::Point.new(GROUP, OpenSSL::BN.new(bytes, 2))
+      end
+
+      # Build an +OpenSSL::PKey::EC+ key object from raw private key bytes.
+      #
+      # @param private_bytes [String] 32-byte big-endian private key
+      # @return [OpenSSL::PKey::EC] an EC key with both private and public components
+      def ec_key_from_private_bytes(private_bytes)
+        priv_bn = OpenSSL::BN.new(private_bytes, 2)
+        pub_point = multiply_generator(priv_bn)
+
+        asn1 = OpenSSL::ASN1::Sequence.new([
+                                             OpenSSL::ASN1::Integer.new(1),
+                                             OpenSSL::ASN1::OctetString.new(private_bytes),
+                                             OpenSSL::ASN1::ObjectId.new('secp256k1', 0, :EXPLICIT),
+                                             OpenSSL::ASN1::BitString.new(pub_point.to_octet_string(:compressed), 1,
+                                                                          :EXPLICIT)
+                                           ])
+        OpenSSL::PKey::EC.new(asn1.to_der)
+      end
+
+      # Build an +OpenSSL::PKey::EC+ key object from raw public key bytes.
+      #
+      # @param public_bytes [String] compressed (33) or uncompressed (65) public key bytes
+      # @return [OpenSSL::PKey::EC] an EC key with only the public component
+      def ec_key_from_public_bytes(public_bytes)
+        asn1 = OpenSSL::ASN1::Sequence.new([
+                                             OpenSSL::ASN1::Sequence.new([
+                                                                           OpenSSL::ASN1::ObjectId.new('id-ecPublicKey'),
+                                                                           OpenSSL::ASN1::ObjectId.new('secp256k1')
+                                                                         ]),
+                                             OpenSSL::ASN1::BitString.new(public_bytes)
+                                           ])
+        OpenSSL::PKey::EC.new(asn1.to_der)
+      end
+    end
+  end
+end

data/lib/bsv/primitives/digest.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # Cryptographic hash functions and HMAC operations.
+    #
+    # 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.
+    module Digest
+      module_function
+
+      # Compute SHA-1 digest.
+      #
+      # @param data [String] binary data to hash
+      # @return [String] 20-byte digest
+      def sha1(data)
+        OpenSSL::Digest::SHA1.digest(data)
+      end
+
+      # Compute SHA-256 digest.
+      #
+      # @param data [String] binary data to hash
+      # @return [String] 32-byte digest
+      def sha256(data)
+        OpenSSL::Digest::SHA256.digest(data)
+      end
+
+      # Compute double-SHA-256 (SHA-256d) digest.
+      #
+      # Used extensively in Bitcoin for transaction and block hashing.
+      #
+      # @param data [String] binary data to hash
+      # @return [String] 32-byte digest
+      def sha256d(data)
+        sha256(sha256(data))
+      end
+
+      # Compute SHA-512 digest.
+      #
+      # @param data [String] binary data to hash
+      # @return [String] 64-byte digest
+      def sha512(data)
+        OpenSSL::Digest::SHA512.digest(data)
+      end
+
+      # Compute RIPEMD-160 digest.
+      #
+      # @param data [String] binary data to hash
+      # @return [String] 20-byte digest
+      def ripemd160(data)
+        OpenSSL::Digest::RIPEMD160.digest(data)
+      end
+
+      # Compute Hash160: RIPEMD-160(SHA-256(data)).
+      #
+      # Standard Bitcoin hash used for addresses and P2PKH script matching.
+      #
+      # @param data [String] binary data to hash
+      # @return [String] 20-byte digest
+      def hash160(data)
+        ripemd160(sha256(data))
+      end
+
+      # Compute HMAC-SHA-256.
+      #
+      # @param key [String] HMAC key
+      # @param data [String] data to authenticate
+      # @return [String] 32-byte MAC
+      def hmac_sha256(key, data)
+        OpenSSL::HMAC.digest('SHA256', key, data)
+      end
+
+      # Compute HMAC-SHA-512.
+      #
+      # @param key [String] HMAC key
+      # @param data [String] data to authenticate
+      # @return [String] 64-byte MAC
+      def hmac_sha512(key, data)
+        OpenSSL::HMAC.digest('SHA512', key, data)
+      end
+
+      # Derive a key using PBKDF2-HMAC-SHA-512.
+      #
+      # Used by BIP-39 to convert mnemonic phrases into seeds.
+      #
+      # @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
+      def pbkdf2_hmac_sha512(password, salt, iterations: 2048, key_length: 64)
+        OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, key_length, 'sha512')
+      end
+    end
+  end
+end