bsv-sdk 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8f24ed29fd0a8beb572b3737c3bbfaba5bf939c5fe20d485306e5e4374587c1
-  data.tar.gz: 53746a1cdad1370718892805b76c763fbe58a73ef057bd65a1eaa4b1b120c7bd
+  metadata.gz: 61435802c338981fb3f6fd8d5881aac9aa83b1cdb261f02dc2a9e2ffa1eb8fa7
+  data.tar.gz: '0159ac16ce996bc45503c6342e0ec763d82285968d9b614c209b4c38fc8f2980'
 SHA512:
-  metadata.gz: 93590d116e66151f51af5167bb405b2d91cd2997f685fad0d684cd07f5231aa1387d57d71852e5464f3f222d1b471534d22ab6633c75d188f9080c1718f834a0
-  data.tar.gz: b26e9a26837af3ce9426311050c0e2fbbdaac9ce4d04a7987c123ef189ec6528e779c69bd7b77605e25df70c1510327a71b7843151f50eb710b2b63a788eeae2
+  metadata.gz: 17c9ee9dee1b8454aff19753196dbbc9a04463bdca7da03c6c0769d23b9603efb9ef9f4d6fd57b4dc426a99077d5780c9bb5e978e10e6675809301fc9fea1178
+  data.tar.gz: 1a1bbbee8c570c28c8c608320e1db986527d1e847e5c2cb1943c2b35ec10f3fd6de983bea3eb0026b4216caecee2771c246a0ba3eebc497f2bce88325a58002c

data/lib/bsv/network/broadcast_response.rb

@@ -3,8 +3,7 @@
 module BSV
   module Network
     class BroadcastResponse
-      attr_reader :txid, :tx_status, :message, :extra_info,
-                  :block_hash, :block_height, :timestamp, :competing_txs
+      attr_reader :txid, :tx_status, :message, :extra_info, :block_hash, :block_height, :timestamp, :competing_txs
 
       def initialize(attrs = {})
         @txid = attrs[:txid]

data/lib/bsv/primitives/bsm.rb

@@ -97,10 +97,7 @@ module BSV
 
         def decode_compact(signature)
           compact = signature.unpack1('m0')
-          unless compact.bytesize == 65
-            raise ArgumentError,
-                  "invalid signature length: #{compact.bytesize} (expected 65)"
-          end
+          raise ArgumentError, "invalid signature length: #{compact.bytesize} (expected 65)" unless compact.bytesize == 65
 
           compact
         rescue ArgumentError => e
@@ -112,8 +109,7 @@ module BSV
         def validate_flag!(flag)
           return if flag.between?(27, 34)
 
-          raise ArgumentError,
-                "flag byte #{flag} out of range (expected 27-34)"
+          raise ArgumentError, "flag byte #{flag} out of range (expected 27-34)"
         end
 
         def encode_varint(len)

data/lib/bsv/primitives/curve.rb

@@ -90,8 +90,7 @@ module BSV
                                              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::ASN1::BitString.new(pub_point.to_octet_string(:compressed), 1, :EXPLICIT)
                                            ])
         OpenSSL::PKey::EC.new(asn1.to_der)
       end

data/lib/bsv/primitives/encrypted_message.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module BSV
+  module Primitives
+    # BRC-78 encrypted messages.
+    #
+    # Provides confidential authenticated messaging using BRC-42 derived keys
+    # and AES-256-GCM symmetric encryption. Both parties derive the same
+    # symmetric key from their respective BRC-42 child keys via ECDH.
+    #
+    # @example Encrypt and decrypt
+    #   ct = EncryptedMessage.encrypt(message, sender_priv, recipient_pub)
+    #   EncryptedMessage.decrypt(ct, recipient_priv) #=> message
+    #
+    # @see https://github.com/bitcoin-sv/BRCs/blob/master/peer-to-peer/0078.md
+    module EncryptedMessage
+      # Protocol version bytes: "BB\x10\x33"
+      VERSION = "\x42\x42\x10\x33".b.freeze
+
+      # Minimum message size: VERSION(4) + sender(33) + recipient(33) + key_id(32) = 102
+      HEADER_SIZE = 102
+
+      module_function
+
+      # Encrypt a message using the BRC-78 protocol.
+      #
+      # @param message [String] the message to encrypt
+      # @param sender [PrivateKey] the sender's private key
+      # @param recipient [PublicKey] the recipient's public key
+      # @return [String] binary encrypted message (header + AES-GCM payload)
+      def encrypt(message, sender, recipient)
+        key_id = SecureRandom.random_bytes(32)
+        invoice = "2-message encryption-#{[key_id].pack('m0')}"
+
+        sym_key = derive_symmetric_key(sender, recipient, invoice)
+        encrypted = sym_key.encrypt(message)
+
+        VERSION +
+          sender.public_key.compressed +
+          recipient.compressed +
+          key_id +
+          encrypted
+      end
+
+      # Decrypt a BRC-78 encrypted message.
+      #
+      # @param data [String] the binary encrypted message (from {.encrypt})
+      # @param recipient [PrivateKey] the recipient's private key
+      # @return [String] the decrypted plaintext (binary)
+      # @raise [ArgumentError] if version is wrong, recipient doesn't match, or message is too short
+      # @raise [OpenSSL::Cipher::CipherError] if decryption fails (tampered or wrong key)
+      def decrypt(data, recipient)
+        data = data.b
+        raise ArgumentError, "encrypted message too short: #{data.bytesize} bytes (minimum #{HEADER_SIZE})" if data.bytesize < HEADER_SIZE
+
+        version = data.byteslice(0, 4)
+        raise ArgumentError, "message version mismatch: expected #{VERSION.unpack1('H*')}, received #{version.unpack1('H*')}" if version != VERSION
+
+        sender_pub = PublicKey.from_bytes(data.byteslice(4, 33))
+        expected_recipient = data.byteslice(37, 33)
+        actual_recipient = recipient.public_key.compressed
+
+        if expected_recipient != actual_recipient
+          raise ArgumentError,
+                "the encrypted message expects a recipient public key of #{expected_recipient.unpack1('H*')}, " \
+                "but the provided key is #{actual_recipient.unpack1('H*')}"
+        end
+
+        key_id = data.byteslice(70, 32)
+        encrypted_payload = data.byteslice(HEADER_SIZE, data.bytesize - HEADER_SIZE)
+
+        invoice = "2-message encryption-#{[key_id].pack('m0')}"
+        sym_key = derive_symmetric_key_for_decrypt(sender_pub, recipient, invoice)
+        sym_key.decrypt(encrypted_payload)
+      end
+
+      class << self
+        private
+
+        # Derive the symmetric key for encryption (sender has private key).
+        def derive_symmetric_key(sender_priv, recipient_pub, invoice)
+          sender_child = sender_priv.derive_child(recipient_pub, invoice)
+          recipient_child = recipient_pub.derive_child(sender_priv, invoice)
+          shared = sender_child.derive_shared_secret(recipient_child)
+          SymmetricKey.new(shared.compressed.byteslice(1, 32))
+        end
+
+        # Derive the symmetric key for decryption (recipient has private key).
+        def derive_symmetric_key_for_decrypt(sender_pub, recipient_priv, invoice)
+          sender_child = sender_pub.derive_child(recipient_priv, invoice)
+          recipient_child = recipient_priv.derive_child(sender_pub, invoice)
+          shared = recipient_child.derive_shared_secret(sender_child)
+          SymmetricKey.new(shared.compressed.byteslice(1, 32))
+        end
+      end
+    end
+  end
+end

data/lib/bsv/primitives/extended_key.rb

@@ -62,8 +62,7 @@ module BSV
       # @param depth [Integer] derivation depth
       # @param parent_fingerprint [String] 4-byte parent fingerprint
       # @param child_number [Integer] child index
-      def initialize(key:, chain_code:, version:, depth: 0, parent_fingerprint: "\x00\x00\x00\x00".b,
-                     child_number: 0)
+      def initialize(key:, chain_code:, version:, depth: 0, parent_fingerprint: "\x00\x00\x00\x00".b, child_number: 0)
         @key = key
         @chain_code = chain_code
         @depth = depth

data/lib/bsv/primitives/key_shares.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module BSV
+  module Primitives
+    # A set of Shamir's Secret Sharing shares derived from a private key.
+    #
+    # Holds the evaluation points (shares), a reconstruction threshold, and an
+    # integrity string for verifying that recombined shares produce the correct
+    # key. Supports serialisation to and from a human-readable backup format.
+    #
+    # Backup format per share: "Base58(x).Base58(y).threshold.integrity"
+    #
+    # This format is compatible with the Go and TypeScript reference SDKs.
+    #
+    # @example Round-trip through backup format
+    #   shares  = key.to_key_shares(2, 5)
+    #   backup  = shares.to_backup_format
+    #   rebuilt = KeyShares.from_backup_format(backup[0..1])
+    #   key     = PrivateKey.from_key_shares(rebuilt)
+    class KeyShares
+      # @return [Array<PointInFiniteField>] the share points
+      attr_reader :points
+
+      # @return [Integer] the minimum number of shares required to reconstruct the key
+      attr_reader :threshold
+
+      # @return [String] first 8 hex characters of the Hash160 of the compressed public key
+      attr_reader :integrity
+
+      # @param points    [Array<PointInFiniteField>] share points
+      # @param threshold [Integer]                   reconstruction threshold
+      # @param integrity [String]                    integrity check string
+      def initialize(points, threshold, integrity)
+        @points    = points
+        @threshold = threshold
+        @integrity = integrity
+      end
+
+      # Deserialise shares from backup format strings.
+      #
+      # Each string must have the form "Base58(x).Base58(y).threshold.integrity".
+      # All shares must agree on threshold and integrity.
+      #
+      # @param shares [Array<String>] backup-format share strings
+      # @return [KeyShares]
+      # @raise [ArgumentError] if any share is malformed or shares are inconsistent
+      def self.from_backup_format(shares)
+        threshold = 0
+        integrity = ''
+        points    = shares.each_with_index.map do |share, idx|
+          parts = share.split('.', -1)
+          raise ArgumentError, "invalid share format in share #{idx}: expected 4 dot-separated parts, got #{share.inspect}" unless parts.length == 4
+
+          x_str, y_str, t_str, i_str = parts
+
+          raise ArgumentError, "threshold not found in share #{idx}" if t_str.empty?
+          raise ArgumentError, "integrity not found in share #{idx}" if i_str.empty?
+
+          t_int = Integer(t_str)
+
+          if idx != 0
+            raise ArgumentError, "threshold mismatch in share #{idx}" unless threshold == t_int
+            raise ArgumentError, "integrity mismatch in share #{idx}" unless integrity == i_str
+          end
+
+          threshold = t_int
+          integrity = i_str
+
+          PointInFiniteField.from_string("#{x_str}.#{y_str}")
+        end
+
+        new(points, threshold, integrity)
+      end
+
+      # Serialise shares to backup format strings.
+      #
+      # @return [Array<String>] one backup string per share point
+      def to_backup_format
+        @points.map { |point| "#{point}.#{@threshold}.#{@integrity}" }
+      end
+    end
+  end
+end

data/lib/bsv/primitives/mnemonic.rb

@@ -42,9 +42,7 @@ module BSV
       # @return [Mnemonic] a new mnemonic with valid checksum
       # @raise [ArgumentError] if strength is not a valid value
       def self.generate(strength: 128)
-        unless VALID_STRENGTHS.include?(strength)
-          raise ArgumentError, "invalid strength: #{strength}. Must be one of #{VALID_STRENGTHS.join(', ')}"
-        end
+        raise ArgumentError, "invalid strength: #{strength}. Must be one of #{VALID_STRENGTHS.join(', ')}" unless VALID_STRENGTHS.include?(strength)
 
         entropy = SecureRandom.random_bytes(strength / 8)
         from_entropy(entropy)

data/lib/bsv/primitives/point_in_finite_field.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # A point (x, y) in a finite field over the secp256k1 field prime P.
+    #
+    # Used as a share in Shamir's Secret Sharing Scheme. Both coordinates are
+    # reduced modulo P on construction so they always lie in [0, P).
+    #
+    # Serialisation uses Base58 for each coordinate, joined by a dot, matching
+    # the format used by the Go and TypeScript reference SDKs.
+    #
+    # @example
+    #   point = PointInFiniteField.new(OpenSSL::BN.new(10), OpenSSL::BN.new(20))
+    #   str   = point.to_s   #=> "C.N"
+    #   back  = PointInFiniteField.from_string(str)
+    class PointInFiniteField
+      # The secp256k1 field prime P.
+      P = OpenSSL::BN.new('FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F', 16).freeze
+
+      # @return [OpenSSL::BN] the x-coordinate, reduced mod P
+      attr_reader :x
+
+      # @return [OpenSSL::BN] the y-coordinate, reduced mod P
+      attr_reader :y
+
+      # @param x [OpenSSL::BN] the x-coordinate
+      # @param y [OpenSSL::BN] the y-coordinate
+      def initialize(x, y)
+        @x = umod(x, P)
+        @y = umod(y, P)
+      end
+
+      # Serialise to Base58(x) + "." + Base58(y).
+      #
+      # @return [String] dot-separated Base58-encoded coordinates
+      def to_s
+        "#{Base58.encode(bn_to_bytes(@x))}.#{Base58.encode(bn_to_bytes(@y))}"
+      end
+
+      # Deserialise from a "Base58(x).Base58(y)" string.
+      #
+      # @param str [String] dot-separated Base58-encoded coordinates
+      # @return [PointInFiniteField]
+      # @raise [ArgumentError] if the string does not contain exactly one dot
+      def self.from_string(str)
+        parts = str.split('.')
+        raise ArgumentError, "invalid point string: expected 'x.y', got #{str.inspect}" unless parts.length == 2
+
+        x = OpenSSL::BN.new(Base58.decode(parts[0]), 2)
+        y = OpenSSL::BN.new(Base58.decode(parts[1]), 2)
+        new(x, y)
+      end
+
+      private
+
+      # Unsigned modulo — always returns a non-negative result in [0, m).
+      def umod(n, m)
+        result = n % m
+        result.negative? ? result + m : result
+      end
+
+      # 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)
+      end
+    end
+  end
+end

data/lib/bsv/primitives/polynomial.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # A polynomial defined by a set of points, evaluated using Lagrange interpolation.
+    #
+    # Used in Shamir's Secret Sharing Scheme to split and reconstruct a secret.
+    # All arithmetic is performed in the finite field GF(P) where P is the
+    # secp256k1 field prime.
+    #
+    # The secret is encoded as the y-value at x=0. Given +threshold+ distinct
+    # points the polynomial can be evaluated at any x by Lagrange interpolation.
+    #
+    # @example Construct shares from a private key
+    #   poly   = Polynomial.from_private_key(key, threshold: 2)
+    #   share1 = poly.value_at(OpenSSL::BN.new('1'))
+    #   share0 = poly.value_at(OpenSSL::BN.new('0'))  # recovers the secret
+    class Polynomial
+      P = PointInFiniteField::P
+
+      # @return [Array<PointInFiniteField>] the defining points of the polynomial
+      attr_reader :points
+
+      # @return [Integer] the minimum number of shares needed to reconstruct the secret
+      attr_reader :threshold
+
+      # @param points    [Array<PointInFiniteField>] defining points
+      # @param threshold [Integer] reconstruction threshold (defaults to points.length)
+      def initialize(points, threshold = nil)
+        @points    = points
+        @threshold = threshold || points.length
+      end
+
+      # Build a polynomial whose y-intercept (secret) is the private key scalar.
+      #
+      # The first point is (0, key_scalar). The remaining +threshold-1+ points
+      # have random coordinates in [0, P), providing the random coefficients of
+      # the underlying polynomial.
+      #
+      # @param key       [PrivateKey] the private key to split
+      # @param threshold [Integer]    the reconstruction threshold (minimum 2)
+      # @return [Polynomial]
+      def self.from_private_key(key, threshold:)
+        secret_y = key.bn
+        points   = [PointInFiniteField.new(OpenSSL::BN.new('0'), secret_y)]
+
+        (threshold - 1).times do
+          random_x = OpenSSL::BN.rand(256) % P
+          random_y = OpenSSL::BN.rand(256) % P
+          points << PointInFiniteField.new(random_x, random_y)
+        end
+
+        new(points, threshold)
+      end
+
+      # Evaluate the polynomial at x using Lagrange interpolation mod P.
+      #
+      # @param x [OpenSSL::BN] the x value at which to evaluate
+      # @return  [OpenSSL::BN] the y value, in [0, P)
+      def value_at(x)
+        y = OpenSSL::BN.new('0')
+
+        threshold.times do |i|
+          term = points[i].y
+          threshold.times do |j|
+            next if i == j
+
+            xi = points[i].x
+            xj = points[j].x
+
+            numerator   = umod(x - xj, P)
+            denominator = umod(xi - xj, P)
+            denom_inv   = denominator.mod_inverse(P)
+
+            fraction = numerator.mod_mul(denom_inv, P)
+            term     = term.mod_mul(fraction, P)
+          end
+          y = y.mod_add(term, P)
+        end
+
+        y
+      end
+
+      private
+
+      # Unsigned modulo — always returns a result in [0, P).
+      def umod(n, m)
+        result = n % m
+        result.negative? ? result + m : result
+      end
+    end
+  end
+end

data/lib/bsv/primitives/private_key.rb

@@ -74,9 +74,7 @@ module BSV
       def self.from_wif(wif_string)
         data = Base58.check_decode(wif_string)
         prefix = data[0]
-        unless [MAINNET_PREFIX, TESTNET_PREFIX].include?(prefix)
-          raise ArgumentError, "unknown WIF network prefix: 0x#{prefix.unpack1('H*')}"
-        end
+        raise ArgumentError, "unknown WIF network prefix: 0x#{prefix.unpack1('H*')}" unless [MAINNET_PREFIX, TESTNET_PREFIX].include?(prefix)
 
         case data.length
         when 33
@@ -168,6 +166,105 @@ module BSV
       def sign(hash)
         ECDSA.sign(hash, @bn)
       end
+
+      # Split this private key into Shamir's Secret Sharing shares.
+      #
+      # Generates +total_shares+ evaluation points on a random polynomial whose
+      # y-intercept encodes this key. Any +threshold+ of them suffice to
+      # reconstruct the key. X-coordinates are derived via HMAC-SHA-512 over a
+      # 64-byte random seed, ensuring uniqueness even under partial RNG failure.
+      #
+      # @param threshold    [Integer] minimum shares needed to reconstruct (>= 2)
+      # @param total_shares [Integer] total shares to generate (>= threshold)
+      # @return [KeyShares]
+      # @raise [ArgumentError] if parameters are out of range
+      def to_key_shares(threshold, total_shares)
+        raise ArgumentError, 'threshold must be an integer'    unless threshold.is_a?(Integer)
+        raise ArgumentError, 'total_shares must be an integer' unless total_shares.is_a?(Integer)
+        raise ArgumentError, 'threshold must be at least 2'    if threshold < 2
+        raise ArgumentError, 'total_shares must be at least 2' if total_shares < 2
+        raise ArgumentError, 'threshold must be <= total_shares' if threshold > total_shares
+
+        poly = Polynomial.from_private_key(self, threshold: threshold)
+
+        seed          = SecureRandom.random_bytes(64)
+        used_x        = {}
+        points        = []
+
+        total_shares.times do |i|
+          x = nil
+          attempts = 0
+          loop do
+            counter_bytes = [i, attempts].pack('N*') + SecureRandom.random_bytes(32)
+            h             = Digest.hmac_sha512(seed, counter_bytes)
+            candidate     = OpenSSL::BN.new(h.unpack1('H*'), 16) % PointInFiniteField::P
+
+            attempts += 1
+            raise ArgumentError, 'failed to generate unique x-coordinate after 5 attempts' if attempts > 5
+
+            next if candidate.zero? || used_x.key?(candidate.to_s)
+
+            x = candidate
+            break
+          end
+
+          used_x[x.to_s] = true
+          y = poly.value_at(x)
+          points << PointInFiniteField.new(x, y)
+        end
+
+        integrity = public_key.hash160[0, 4].unpack1('H*')
+        KeyShares.new(points, threshold, integrity)
+      end
+
+      # Serialise this key as Shamir backup share strings.
+      #
+      # Convenience wrapper around {#to_key_shares} and {KeyShares#to_backup_format}.
+      #
+      # @param threshold    [Integer] minimum shares needed to reconstruct
+      # @param total_shares [Integer] total shares to generate
+      # @return [Array<String>] backup-format share strings
+      def to_backup_shares(threshold, total_shares)
+        to_key_shares(threshold, total_shares).to_backup_format
+      end
+
+      # Reconstruct a private key from a {KeyShares} object.
+      #
+      # Evaluates the Lagrange polynomial at x=0 to recover the secret, then
+      # checks the integrity hash against the reconstructed public key.
+      #
+      # @param key_shares [KeyShares] the shares to combine
+      # @return [PrivateKey] the reconstructed private key
+      # @raise [ArgumentError] if there are too few shares, duplicates, or integrity fails
+      def self.from_key_shares(key_shares)
+        points    = key_shares.points
+        threshold = key_shares.threshold
+        integrity = key_shares.integrity
+
+        raise ArgumentError, 'threshold must be at least 2' if threshold < 2
+        raise ArgumentError, "at least #{threshold} shares are required" if points.length < threshold
+
+        # Guard against duplicate x-coordinates
+        xs = points.first(threshold).map { |p| p.x.to_s }
+        raise ArgumentError, 'duplicate share detected; each share must be unique' if xs.length != xs.uniq.length
+
+        poly    = Polynomial.new(points.first(threshold), threshold)
+        secret  = poly.value_at(OpenSSL::BN.new('0'))
+        key     = new(secret)
+
+        actual_integrity = key.public_key.hash160[0, 4].unpack1('H*')
+        raise ArgumentError, 'integrity hash mismatch — shares may be corrupt or belong to a different key' unless actual_integrity == integrity
+
+        key
+      end
+
+      # Reconstruct a private key from backup-format share strings.
+      #
+      # @param shares [Array<String>] backup-format share strings
+      # @return [PrivateKey]
+      def self.from_backup_shares(shares)
+        from_key_shares(KeyShares.from_backup_format(shares))
+      end
     end
   end
 end

data/lib/bsv/primitives/signed_message.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module BSV
+  module Primitives
+    # BRC-77 signed messages.
+    #
+    # Provides authenticated messaging using BRC-42 derived signing keys.
+    # The sender proves their identity to a specific recipient (or anyone)
+    # without encrypting the message content.
+    #
+    # @example Sign and verify for a specific recipient
+    #   sig = SignedMessage.sign(message, sender_priv, recipient_pub)
+    #   SignedMessage.verify(message, sig, recipient_priv) #=> true
+    #
+    # @example Sign for anyone to verify
+    #   sig = SignedMessage.sign(message, sender_priv)
+    #   SignedMessage.verify(message, sig) #=> true
+    #
+    # @see https://github.com/bitcoin-sv/BRCs/blob/master/peer-to-peer/0077.md
+    module SignedMessage
+      # Protocol version bytes: "BB3\x01"
+      VERSION = "\x42\x42\x33\x01".b.freeze
+
+      module_function
+
+      # Sign a message using the BRC-77 protocol.
+      #
+      # @param message [String] the message to sign
+      # @param signer [PrivateKey] the sender's private key
+      # @param verifier [PublicKey, nil] the recipient's public key (nil for anyone-can-verify)
+      # @return [String] binary signed message (version + keys + key_id + DER signature)
+      def sign(message, signer, verifier = nil)
+        anyone = verifier.nil?
+        verifier = PrivateKey.new(OpenSSL::BN.new(1)).public_key if anyone
+
+        key_id = SecureRandom.random_bytes(32)
+        invoice = "2-message signing-#{[key_id].pack('m0')}"
+
+        signing_key = signer.derive_child(verifier, invoice)
+        hash = Digest.sha256(message.b)
+        signature = signing_key.sign(hash)
+
+        VERSION +
+          signer.public_key.compressed +
+          (anyone ? "\x00".b : verifier.compressed) +
+          key_id +
+          signature.to_der
+      end
+
+      # Verify a BRC-77 signed message.
+      #
+      # @param message [String] the original message
+      # @param sig [String] the binary signature (from {.sign})
+      # @param recipient [PrivateKey, nil] the recipient's private key (nil for anyone-can-verify)
+      # @return [Boolean] true if the signature is valid
+      # @raise [ArgumentError] if the version is wrong, recipient is required but missing, or recipient doesn't match
+      def verify(message, sig, recipient = nil)
+        sig = sig.b
+        raise ArgumentError, "signed message too short: #{sig.bytesize} bytes" if sig.bytesize < 38
+
+        version = sig.byteslice(0, 4)
+        raise ArgumentError, "message version mismatch: expected #{VERSION.unpack1('H*')}, received #{version.unpack1('H*')}" if version != VERSION
+
+        sender_pub = PublicKey.from_bytes(sig.byteslice(4, 33))
+        verifier_first = sig.getbyte(37)
+
+        if verifier_first.zero?
+          # Anyone-can-verify mode
+          recipient = PrivateKey.new(OpenSSL::BN.new(1))
+          key_id_offset = 38
+        else
+          # Specific recipient
+          verifier_pub_bytes = sig.byteslice(37, 33)
+          verifier_pub_hex = verifier_pub_bytes.unpack1('H*')
+
+          if recipient.nil?
+            raise ArgumentError,
+                  "this signature can only be verified with knowledge of a specific private key. The associated public key is: #{verifier_pub_hex}"
+          end
+
+          recipient_pub_hex = recipient.public_key.compressed.unpack1('H*')
+          if verifier_pub_hex != recipient_pub_hex
+            raise ArgumentError,
+                  "the recipient public key is #{recipient_pub_hex} but the signature requires the recipient to have public key #{verifier_pub_hex}"
+          end
+
+          key_id_offset = 70
+        end
+
+        key_id = sig.byteslice(key_id_offset, 32)
+        der_bytes = sig.byteslice(key_id_offset + 32, sig.bytesize - key_id_offset - 32)
+
+        invoice = "2-message signing-#{[key_id].pack('m0')}"
+        signing_pub = sender_pub.derive_child(recipient, invoice)
+
+        signature = Signature.from_der(der_bytes)
+        hash = Digest.sha256(message.b)
+        ECDSA.verify(hash, signature, signing_pub.point)
+      end
+    end
+  end
+end