bsv-sdk 0.1.0

data/lib/bsv/primitives/public_key.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # A secp256k1 public key for address derivation and signature verification.
+    #
+    # Public keys are points on the secp256k1 curve. They can be serialised
+    # in compressed (33-byte) or uncompressed (65-byte) form, converted to
+    # Bitcoin addresses, and used to verify ECDSA signatures.
+    #
+    # @example Derive address from a public key
+    #   pub = private_key.public_key
+    #   pub.address #=> "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
+    class PublicKey
+      # Address version byte for mainnet P2PKH addresses.
+      MAINNET_PUBKEY_HASH = "\x00".b
+
+      # Address version byte for testnet P2PKH addresses.
+      TESTNET_PUBKEY_HASH = "\x6f".b
+
+      # @return [OpenSSL::PKey::EC::Point] the underlying curve point
+      attr_reader :point
+
+      # @param point [OpenSSL::PKey::EC::Point] a point on the secp256k1 curve
+      # @raise [ArgumentError] if point is not an EC point or is at infinity
+      def initialize(point)
+        raise ArgumentError, 'point must be an EC point' unless point.is_a?(OpenSSL::PKey::EC::Point)
+        raise ArgumentError, 'point is at infinity' if point.infinity?
+
+        @point = point
+      end
+
+      # Create a public key from raw bytes (compressed or uncompressed).
+      #
+      # @param bytes [String] 33-byte compressed or 65-byte uncompressed encoding
+      # @return [PublicKey]
+      def self.from_bytes(bytes)
+        point = Curve.point_from_bytes(bytes)
+        new(point)
+      end
+
+      # Create a public key from a hex string.
+      #
+      # @param hex [String] hex-encoded compressed or uncompressed public key
+      # @return [PublicKey]
+      def self.from_hex(hex)
+        from_bytes([hex].pack('H*'))
+      end
+
+      # Derive the public key from a {PrivateKey}.
+      #
+      # @param private_key [PrivateKey] the private key
+      # @return [PublicKey]
+      def self.from_private_key(private_key)
+        private_key.public_key
+      end
+
+      # Return the compressed (33-byte) encoding.
+      #
+      # @return [String] compressed public key bytes
+      def compressed
+        @point.to_octet_string(:compressed)
+      end
+
+      # Return the uncompressed (65-byte) encoding.
+      #
+      # @return [String] uncompressed public key bytes
+      def uncompressed
+        @point.to_octet_string(:uncompressed)
+      end
+
+      # Return the public key as a hex string.
+      #
+      # @param compressed [Boolean] whether to use compressed encoding (default: true)
+      # @return [String] hex-encoded public key
+      def to_hex(compressed: true)
+        if compressed
+          self.compressed.unpack1('H*')
+        else
+          uncompressed.unpack1('H*')
+        end
+      end
+
+      # Compute the Hash160 (RIPEMD-160 of SHA-256) of the compressed public key.
+      #
+      # @return [String] 20-byte public key hash
+      def hash160
+        Digest.hash160(compressed)
+      end
+
+      # Derive a Base58Check-encoded Bitcoin address.
+      #
+      # @param network [Symbol] +:mainnet+ or +:testnet+
+      # @return [String] the P2PKH address
+      def address(network: :mainnet)
+        prefix = network == :mainnet ? MAINNET_PUBKEY_HASH : TESTNET_PUBKEY_HASH
+        Base58.check_encode(prefix + hash160)
+      end
+
+      # Verify an ECDSA signature against a message hash.
+      #
+      # @param hash [String] 32-byte message digest
+      # @param signature [Signature] the signature to verify
+      # @return [Boolean] +true+ if the signature is valid
+      def verify(hash, signature)
+        ECDSA.verify(hash, signature, @point)
+      end
+
+      # @param other [Object] the object to compare
+      # @return [Boolean] +true+ if both keys represent the same curve point
+      def ==(other)
+        other.is_a?(PublicKey) && compressed == other.compressed
+      end
+    end
+  end
+end

data/lib/bsv/primitives/schnorr.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # BRC-94 Schnorr zero-knowledge proof protocol.
+    #
+    # Provides generation and verification of Schnorr proofs for verifiable
+    # revelation of ECDH shared secrets. Given two public keys A and B and
+    # a shared secret S = a*B (where a is A's private key), the prover can
+    # demonstrate knowledge of the discrete log relationship without
+    # revealing the private key.
+    #
+    # @see https://github.com/bitcoin-sv/BRCs/blob/master/peer-to-peer/0094.md BRC-94
+    module Schnorr
+      # A Schnorr zero-knowledge proof consisting of a commitment point,
+      # blinded shared secret, and response scalar.
+      class Proof
+        # @return [PublicKey] the commitment point R
+        attr_reader :r
+
+        # @return [PublicKey] the blinded shared secret S'
+        attr_reader :s_prime
+
+        # @return [OpenSSL::BN] the response scalar z
+        attr_reader :z
+
+        # @param r [PublicKey] commitment point
+        # @param s_prime [PublicKey] blinded shared secret
+        # @param z [OpenSSL::BN] response scalar
+        def initialize(r, s_prime, z)
+          @r = r
+          @s_prime = s_prime
+          @z = z
+        end
+      end
+
+      module_function
+
+      # Generate a Schnorr proof of knowledge of a shared secret.
+      #
+      # Proves that the prover knows the private key +a+ such that
+      # +shared_secret = a * public_key_b+, without revealing +a+.
+      #
+      # @param private_key [PrivateKey] the prover's private key (a)
+      # @param public_key_a [PublicKey] the prover's public key (A = a*G)
+      # @param public_key_b [PublicKey] the counterparty's public key (B)
+      # @param shared_secret [PublicKey] the ECDH shared secret (S = a*B)
+      # @return [Proof] the Schnorr proof
+      def generate_proof(private_key, public_key_a, public_key_b, shared_secret)
+        nonce = PrivateKey.generate
+        r_pub = nonce.public_key
+        s_prime = PublicKey.new(Curve.multiply_point(public_key_b.point, nonce.bn))
+
+        e = compute_challenge(public_key_a, public_key_b, shared_secret, s_prime, r_pub)
+
+        z = (nonce.bn + (e * private_key.bn)) % Curve::N
+
+        Proof.new(r_pub, s_prime, z)
+      end
+
+      # Verify a Schnorr proof of knowledge of a shared secret.
+      #
+      # Checks the two verification equations:
+      # 1. z*G == R + e*A
+      # 2. z*B == S' + e*S
+      #
+      # @param public_key_a [PublicKey] the prover's public key
+      # @param public_key_b [PublicKey] the counterparty's public key
+      # @param shared_secret [PublicKey] the claimed shared secret
+      # @param proof [Proof] the Schnorr proof to verify
+      # @return [Boolean] +true+ if the proof is valid
+      def verify_proof(public_key_a, public_key_b, shared_secret, proof)
+        e = compute_challenge(public_key_a, public_key_b, shared_secret, proof.s_prime, proof.r)
+
+        # Equation 1: z·G == R + e·A
+        z_g = Curve.multiply_generator(proof.z)
+        e_a = Curve.multiply_point(public_key_a.point, e)
+        r_plus_ea = Curve.add_points(proof.r.point, e_a)
+
+        return false unless points_equal?(z_g, r_plus_ea)
+
+        # Equation 2: z·B == S' + e·S
+        z_b = Curve.multiply_point(public_key_b.point, proof.z)
+        e_s = Curve.multiply_point(shared_secret.point, e)
+        sp_plus_es = Curve.add_points(proof.s_prime.point, e_s)
+
+        points_equal?(z_b, sp_plus_es)
+      end
+
+      class << self
+        private
+
+        def compute_challenge(pub_a, pub_b, s, s_prime, r)
+          message = pub_a.compressed + pub_b.compressed +
+                    s.compressed + s_prime.compressed + r.compressed
+          hash = Digest.sha256(message)
+          OpenSSL::BN.new(hash, 2) % Curve::N
+        end
+
+        def points_equal?(p1, p2)
+          p1.to_octet_string(:compressed) == p2.to_octet_string(:compressed)
+        end
+      end
+    end
+  end
+end

data/lib/bsv/primitives/signature.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # An ECDSA signature consisting of (r, s) components.
+    #
+    # Supports DER encoding/decoding with strict BIP-66 validation,
+    # low-S normalisation (BIP-62 rule 5), and hex convenience methods.
+    #
+    # @example Parse a DER-encoded signature
+    #   sig = BSV::Primitives::Signature.from_der(der_bytes)
+    #   sig.low_s? #=> true
+    class Signature
+      # @return [OpenSSL::BN] the r component
+      attr_reader :r
+
+      # @return [OpenSSL::BN] the s component
+      attr_reader :s
+
+      # @param r [OpenSSL::BN, Integer] the r component
+      # @param s [OpenSSL::BN, Integer] the s component
+      def initialize(r, s)
+        @r = r.is_a?(OpenSSL::BN) ? r : OpenSSL::BN.new(r.to_s, 10)
+        @s = s.is_a?(OpenSSL::BN) ? s : OpenSSL::BN.new(s.to_s, 10)
+      end
+
+      # Parse a signature from DER-encoded bytes with strict BIP-66 validation.
+      #
+      # @param der_bytes [String] DER-encoded signature bytes
+      # @return [Signature]
+      # @raise [ArgumentError] if the DER encoding is invalid
+      def self.from_der(der_bytes)
+        der_bytes = der_bytes.b if der_bytes.encoding != Encoding::ASCII_8BIT
+        bytes = der_bytes.bytes
+
+        raise ArgumentError, 'signature too short' if bytes.length < 8
+        raise ArgumentError, 'invalid sequence tag' unless bytes[0] == 0x30
+
+        total_len = bytes[1]
+        raise ArgumentError, 'length mismatch' unless total_len == bytes.length - 2
+
+        # Parse R
+        raise ArgumentError, 'invalid integer tag for R' unless bytes[2] == 0x02
+
+        r_len = bytes[3]
+        raise ArgumentError, 'R length overflows' if 4 + r_len > bytes.length
+        raise ArgumentError, 'R is zero length' if r_len.zero?
+
+        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)
+
+        # Parse S
+        s_offset = 4 + r_len
+        raise ArgumentError, 'invalid integer tag for S' unless bytes[s_offset] == 0x02
+
+        s_len = bytes[s_offset + 1]
+        raise ArgumentError, 'S length overflows' if s_offset + 2 + s_len > bytes.length
+        raise ArgumentError, 'S is zero length' if s_len.zero?
+
+        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, 'trailing bytes' unless s_offset + 2 + s_len == bytes.length
+
+        r = OpenSSL::BN.new(r_bytes.pack('C*'), 2)
+        s = OpenSSL::BN.new(s_bytes.pack('C*'), 2)
+        new(r, s)
+      end
+
+      # Serialise the signature in DER format.
+      #
+      # @return [String] DER-encoded binary string
+      def to_der
+        rb = canonicalise_int(@r)
+        sb = canonicalise_int(@s)
+
+        der = [0x30, rb.length + sb.length + 4,
+               0x02, rb.length, *rb,
+               0x02, sb.length, *sb]
+        der.pack('C*')
+      end
+
+      # Parse a signature from a hex-encoded DER string.
+      #
+      # @param hex [String] hex-encoded DER signature
+      # @return [Signature]
+      def self.from_hex(hex)
+        from_der([hex].pack('H*'))
+      end
+
+      # Serialise the signature as a hex-encoded DER string.
+      #
+      # @return [String] hex-encoded DER signature
+      def to_hex
+        to_der.unpack1('H*')
+      end
+
+      # Check whether the S value is in the lower half of the curve order.
+      #
+      # BIP-62 rule 5 requires S <= N/2 for transaction malleability protection.
+      #
+      # @return [Boolean] +true+ if S is in the lower half
+      def low_s?
+        @s <= Curve::HALF_N
+      end
+
+      # Return a new signature with S normalised to the lower half of the curve order.
+      #
+      # @return [Signature] a new signature with low-S, or +self+ if already low-S
+      def to_low_s
+        return self if low_s?
+
+        self.class.new(@r, Curve::N - @s)
+      end
+
+      # @param other [Object] the object to compare
+      # @return [Boolean] +true+ if both signatures have equal r and s values
+      def ==(other)
+        other.is_a?(Signature) && @r == other.r && @s == other.s
+      end
+
+      private
+
+      def canonicalise_int(bn)
+        bytes = bn.to_s(2).bytes
+        bytes = [0] if bytes.empty?
+        bytes.unshift(0) if bytes[0] & 0x80 != 0
+        bytes
+      end
+    end
+  end
+end

data/lib/bsv/primitives.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BSV
+  # Cryptographic primitives for the BSV blockchain.
+  #
+  # Provides keys, curves, hashing, digital signatures, encryption,
+  # HD key derivation (BIP-32), and mnemonic phrase generation (BIP-39).
+  # All cryptography uses Ruby's stdlib +openssl+ — no external gems.
+  module Primitives
+    autoload :Curve,      'bsv/primitives/curve'
+    autoload :Digest,     'bsv/primitives/digest'
+    autoload :Base58,     'bsv/primitives/base58'
+    autoload :Signature,  'bsv/primitives/signature'
+    autoload :ECDSA,      'bsv/primitives/ecdsa'
+    autoload :ECIES,      'bsv/primitives/ecies'
+    autoload :BSM,        'bsv/primitives/bsm'
+    autoload :Schnorr, 'bsv/primitives/schnorr'
+    autoload :PublicKey, 'bsv/primitives/public_key'
+    autoload :PrivateKey,  'bsv/primitives/private_key'
+    autoload :ExtendedKey, 'bsv/primitives/extended_key'
+    autoload :Mnemonic,    'bsv/primitives/mnemonic'
+  end
+end

data/lib/bsv/script/builder.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module BSV
+  module Script
+    # Fluent builder for constructing scripts incrementally.
+    #
+    # Provides a chainable API for building scripts from opcodes and data
+    # pushes, as an alternative to the template constructors on {Script}.
+    #
+    # @example Build a custom script
+    #   script = BSV::Script::Script.builder
+    #     .push_op(:OP_DUP)
+    #     .push_op(:OP_HASH160)
+    #     .push_data(pubkey_hash)
+    #     .push_op(:OP_EQUALVERIFY)
+    #     .push_op(:OP_CHECKSIG)
+    #     .build
+    class Builder
+      def initialize
+        @chunks = []
+      end
+
+      # Push an opcode onto the script.
+      #
+      # @param opcode [Symbol, Integer] opcode name (e.g. +:OP_DUP+) or byte value
+      # @return [self] for chaining
+      def push_op(opcode)
+        code = opcode.is_a?(Symbol) ? Opcodes.const_get(opcode) : opcode
+        @chunks << Chunk.new(opcode: code)
+        self
+      end
+
+      # Push raw binary data (automatically selects PUSHDATA encoding).
+      #
+      # @param data [String] binary data to push
+      # @return [self] for chaining
+      def push_data(data)
+        bytes = data.b
+        @chunks << Chunk.new(opcode: push_opcode_for(bytes.bytesize), data: bytes)
+        self
+      end
+
+      # Push hex-encoded data.
+      #
+      # @param hex [String] hex-encoded data to push
+      # @return [self] for chaining
+      def push_hex(hex)
+        push_data([hex].pack('H*'))
+      end
+
+      # Finalise and return the constructed {Script}.
+      #
+      # @return [Script] the built script
+      def build
+        Script.from_chunks(@chunks)
+      end
+
+      private
+
+      def push_opcode_for(len)
+        if len <= 0x4b
+          len
+        elsif len <= 0xff
+          Opcodes::OP_PUSHDATA1
+        elsif len <= 0xffff
+          Opcodes::OP_PUSHDATA2
+        else
+          Opcodes::OP_PUSHDATA4
+        end
+      end
+    end
+  end
+end

data/lib/bsv/script/chunk.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module BSV
+  module Script
+    # A single element of a parsed script — either an opcode or a data push.
+    #
+    # Scripts are composed of a sequence of chunks. Each chunk is either
+    # a bare opcode (e.g. +OP_DUP+) or a data push (opcode + data payload).
+    class Chunk
+      # @return [Integer] the opcode byte
+      attr_reader :opcode
+
+      # @return [String, nil] the pushed data bytes, or +nil+ for bare opcodes
+      attr_reader :data
+
+      # @param opcode [Integer] the opcode byte value
+      # @param data [String, nil] data payload for push operations
+      def initialize(opcode:, data: nil)
+        @opcode = opcode
+        @data = data&.b
+      end
+
+      # Whether this chunk carries a data payload.
+      #
+      # @return [Boolean] +true+ if this is a data push chunk
+      def data?
+        !@data.nil?
+      end
+
+      # Serialise this chunk back to raw script bytes.
+      #
+      # @return [String] binary script bytes for this chunk
+      def to_binary
+        if @data
+          push_data_binary(@data)
+        else
+          [@opcode].pack('C')
+        end
+      end
+
+      # Render this chunk as human-readable ASM.
+      #
+      # Data pushes are shown as hex strings; opcodes are shown by name.
+      #
+      # @return [String] ASM representation
+      def to_asm
+        if @data
+          @data.unpack1('H*')
+        else
+          Opcodes.name_for(@opcode) || @opcode.to_s
+        end
+      end
+
+      # @param other [Object] the object to compare
+      # @return [Boolean] +true+ if both chunks have equal opcode and data
+      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/error.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module BSV
+  module Script
+    # Error raised during script execution.
+    #
+    # Carries a machine-readable error code from {ScriptErrorCode} alongside
+    # a human-readable message.
+    class ScriptError < StandardError
+      # @return [Symbol] the error code from {ScriptErrorCode}
+      attr_reader :code
+
+      # @param code [Symbol] error code from {ScriptErrorCode}
+      # @param message [String, nil] human-readable description (auto-generated from code if omitted)
+      def initialize(code, message = nil)
+        @code = code
+        super(message || code.to_s.tr('_', ' '))
+      end
+    end
+
+    # Error codes for script execution failures.
+    #
+    # Each constant corresponds to a specific script validation rule.
+    module ScriptErrorCode
+      EVAL_FALSE = :eval_false
+      EMPTY_STACK = :empty_stack
+      VERIFY_FAILED = :verify_failed
+      EQUALVERIFY_FAILED = :equalverify_failed
+      NUMEQUALVERIFY_FAILED = :numequalverify_failed
+      CHECKSIGVERIFY_FAILED = :checksigverify_failed
+      CHECKMULTISIGVERIFY_FAILED = :checkmultisigverify_failed
+      UNBALANCED_CONDITIONAL = :unbalanced_conditional
+      DISABLED_OPCODE = :disabled_opcode
+      RESERVED_OPCODE = :reserved_opcode
+      INVALID_STACK_OPERATION = :invalid_stack_operation
+      MALFORMED_PUSH = :malformed_push
+      NUMBER_TOO_BIG = :number_too_big
+      DIVIDE_BY_ZERO = :divide_by_zero
+      INVALID_INPUT_LENGTH = :invalid_input_length
+      INVALID_PUBKEY_COUNT = :invalid_pubkey_count
+      INVALID_SIG_COUNT = :invalid_sig_count
+      SIG_NULLFAIL = :sig_nullfail
+      SIG_NULLDUMMY = :sig_nulldummy
+      SIG_DER = :sig_der
+      SIG_HIGH_S = :sig_high_s
+      PUBKEY_TYPE = :pubkey_type
+      INVALID_SIGHASH_TYPE = :invalid_sighash_type
+      EARLY_RETURN = :early_return
+      IMPOSSIBLE_ENCODING = :impossible_encoding
+      INVALID_OPCODE = :invalid_opcode
+      MINIMAL_DATA = :minimal_data
+    end
+  end
+end